API reference
Public API definition
This page contains information about types that are part of Cottle’s public API.
Warning
Types not listed in this page should not be considered as part of the public API, and are not taken into consideration when changing version number (see section Versioning convention).
Warning
You should avoid relying on method behaviors not documented in this page as they could change from one version to another.
Compiled documents
- class IDocument
A document in Cottle is a compiled template, which means a template converted to an optimized in-memory representation.
- Value Render (IContext context, IO.TextWriter writer)
Render document and write output to given IO.TextWriter instance. Return value is the value passed to top-level
return
command if any, or an undefined value otherwise.
- class Document
Methods from this static class must be used to create instances of
DocumentResult
.- DocumentResult CreateDefault (IO.TextReader template, DocumentConfiguration configuration = default)
Create a new default
IDocument
instance suitable for most use cases. Template is read from any non-seekable IO.TextWriter instance.
- DocumentResult CreateDefault (String template, DocumentConfiguration configuration = default)
Create a new default
IDocument
instance similar to previous method. Template is read from given String instance.
- DocumentResult CreateNative (IO.TextReader template, DocumentConfiguration configuration = default)
Create a new native
IDocument
instance for better rendering performance but higher compilation cost. Template is read from any non-seekable IO.TextWriter instance. See section Native documents for details about native documents.
- DocumentResult CreateNative (String template, DocumentConfiguration configuration = default)
Create a new native
IDocument
instance similar to previous method. Template is read from given String instance.
- class DynamicDocument
-
Deprecated class, use
Cottle.Document.CreateNative
to create native documents.
- class SimpleDocument
-
Deprecated class, use
Cottle.Document.CreateDefault
to create documents.
- class DocumentConfiguration
Document configuration options, can be passed as an optional argument when creating a new document.
- String BlockBegin { get; set; }
Delimiter for block begin, see section Delimiters customization for details.
- String BlockContinue { get; set; }
Delimiter for block continue, see section Delimiters customization for details.
- String BlockEnd { get; set; }
Delimiter for block end, see section Delimiters customization for details.
- Nullable<char> Escape { get; set; }
Delimiter for escape, see section Delimiters customization for details. Default escape character is \ when this property is null.
- int? NbCycleMax { get; set; }
When set to a non-null value, a
NbCycleExceededException
exception is thrown if template rendering requires more cycles than allowed, see Render cycle limit for details.
- Boolean NoOptimize { get; set; }
Disable code optimizations after compiling a document, see Optimizer deactivation for details.
- Func<String, String> Trimmer { get; set; }
Function used to trim unwanted character out of plain text when parsing a document, see section Plain text trimming for details.
- class DocumentResult
This structure holds result of a template compilation, which can either be successful and provide compiled
IDocument
instance or failed and provide compilation error details as a list ofDocumentReport
elements:- IDocument Document { get; }
Instance of compiled document, only if compilation was successful (see
DocumentResult.Success
).
- IReadOnlyList<DocumentReport> Reports { get; }
List of anomalies detected during compilation, as a read-only list of
DocumentReport
items.
- IDocument DocumentOrThrow { get; }
Helper to return compiled document when compilation was successful or throw a
Exceptions.ParseException
exception with details about first compilation error otherwise.
- class DocumentReport
Anomaly report on compiled template, with references to related code location.
- String Message { get; }
Human-readable description of the anomaly. This value is meant for being displayed in a user interface but not processed, as its contents is not predictable.
- DocumentSeverity Severity { get; }
Report severity level.
- enum DocumentSeverity
Report severity level.
- Error
Template issue that prevents document from being constructed.
- Warning
Template issue that doesn’t prevent document from being constructed nor rendered, but may impact rendered result or performance and require your attention.
- Notice
Template issue with no visible impact, mostly used for code suggestions or deprecation messages.
Rendering contexts
- class IContext
This interface is used to pass variables to a document when rendering it.
- class Context
Methods from this static class must be used to create instances of
IContext
.- IContext CreateBuiltin (IContext custom)
Create a rendering context by combining a given existing context with all Cottle built-in functions (see section Built-in functions). Variables from the input context always have priority over built-in functions in case of collision.
- IContext CreateBuiltin (IReadOnlyDictionary<Value, Value> symbols)
Create a rendering context by combining variables from given dictionary with all Cottle built-in functions. This method is similar to previous one and only exists as a convenience helper.
- IContext CreateCascade (IContext primary, IContext fallback)
Create a rendering context by combining two existing contexts that will be searched in order when querying a variable. Primary context is searched first, then fallback context is searched second if the result from first one was an undefined value.
- IContext CreateCustom (Func<Value, Value> callback)
Create a rendering context using given callback for resolving variables. Callback must always expected to return a non-null result, possibly an undefined value.
- IContext CreateCustom (IReadOnlyDictionary<Value, Value> symbols)
Create a rendering context from given variables dictionary.
- ISpyContext CreateSpy (IContext source)
Wrap given context inside a spying context to get information about variables referenced in a template, along with their last known value and accessed fields. See section Spying values for details about lazy value resolution.
- (IContext,ISymbolUsage) CreateMonitor (IContext context)
Obsolete alternative to
Context.CreateSpy
.
Function declaration
- class IFunction
Cottle function interface.
- Boolean IsPure { get; }
Indicates whether function is pure or not. Pure functions have no side effects nor rely on them, and may offer better rendering performance as they’re eligible to more compilation optimizations.
- Value Invoke (Object state, IReadOnlyList<Value> arguments, IO.TextWriter output)
Invoke function with given arguments. Variable
state
is an opaque payload that needs to be passed to nested function calls if any,arguments
contains the ordered list of values passed to function, andoutput
is a text writer to document output result.
- class Function
Methods from this static class must be used to create instances of
IFunction
.- IFunction Create (Func<Object, IReadOnlyList<Value>, IO.TextWriter, Value> callback, Int32 min, Int32 max)
Create a non-pure function accepting between
min
andmax
arguments (included).
- IFunction Create (Func<Object, IReadOnlyList<Value>, IO.TextWriter, Value> callback, Int32 count)
Create a non-pure function accepting exactly
count
arguments.
- IFunction Create (Func<Object, IReadOnlyList<Value>, IO.TextWriter, Value> callback)
Create a non-pure function accepting any number of arguments.
- IFunction Create0 (Func<Object, IO.TextWriter, Value> callback)
Create a non-pure function accepting zero argument.
- IFunction Create1 (Func<Object, Value, IO.TextWriter, Value> callback)
Create a non-pure function accepting one argument.
- IFunction Create2 (Func<Object, Value, Value, IO.TextWriter, Value> callback)
Create a non-pure function accepting two arguments.
- IFunction Create3 (Func<Object, Value, Value, Value, IO.TextWriter, Value> callback)
Create a non-pure function accepting three arguments.
- IFunction CreatePure (Func<Object, IReadOnlyList<Value>, Value> callback, Int32 min, Int32 max)
Create a pure function accepting between
min
andmax
arguments (included).
- IFunction CreatePure (Func<Object, IReadOnlyList<Value>, Value> callback, Int32 count)
Create a pure function accepting exactly
count
arguments.
- IFunction CreatePure (Func<Object, IReadOnlyList<Value>, Value> callback)
Create a pure function accepting any number of arguments.
- IFunction CreatePure0 (Func<Object, Value> callback)
Create a pure function accepting zero argument.
- IFunction CreatePure1 (Func<Object, Value, Value> callback)
Create a pure function accepting one argument.
Value declaration
- class Value
Cottle values can hold instances of any of the supported types (see section Value types).
- Value EmptyMap { get; }
Static and read-only empty map value, equal to
Value.FromEnumerable(Array.Empty<Value>()))
.
- Value EmptyString { get; }
Static and read-only empty string value, equal to
Value.FromString(string.Empty)
.
- Value False { get; }
Static and read-only boolean “false” value, equal to
Value.FromBoolean(false)
.
- Value Undefined { get; }
Static and read-only undefined value, equal to
new Value()
ordefault(Value)
.
- Boolean AsBoolean { get; }
Read value as a boolean after converting it if needed. Following conversion is applied depending on base type:
From numbers, return
true
for non-zero values andfalse
otherwise.From strings, return
true
for non-zero length values andfalse
for empty strings.From undefined values, always return
false
.
- IFunction AsFunction { get; }
Read value as a function, only if base type was already a function. No conversion is applied on this property, and return value is undefined if value was not a function.
- Double AsNumber { get; }
Read value as a double precision floating point number after converting it if needed. Following conversion is applied depending on base type:
From booleans, return
0
forfalse
or1
fortrue
.From strings, convert to double number if value can be parsed as one using
double.TryParse()
on invariant culture, or return0
otherwise.From undefined values, always return
0
.
- String AsString { get; }
Read value as a string after converting it if needed. Following conversion is applied depending on base type:
From booleans, return string
"true"
fortrue
and empty string otherwise.From numbers, return result of call to
double.ToString()
method with invariant culture.From undefined values, always return an empty string.
- ValueContent Type { get; }
Get base type of current value instance.
- FromDictionary (IReadOnlyDictionary<Value, Value> dictionary)
Create a map value from given keys and associated value in given
dictionary
, without preserving any ordering. This override assumes input dictionary is immutable and simply keeps a reference on it without duplicating the data structure.
- FromEnumerable (IEnumerable<KeyValuePair<Value, Value>> pairs)
Create a map value from given
elements
, preserving element ordering but also allowing O(1) access to values by key.
- FromEnumerable (IEnumerable<Value> elements)
Create a map value from given
elements
. Numeric keys are generated for each element starting at index0
.
- FromFunction (IFunction function)
Create a function value by wrapping an executable
IFunction
instance. See sections Function declaration and Native .NET functions for details about functions in Cottle.
- FromGenerator (Func<Int32, Value> generator, Int32 count)
Create map value from given generator. Generator function
generator
is used to create elements based on their index, and the map will containcount
values associated to keys0
tocount - 1
. Values are created only when retrieved, so creating a generator value with 10000000 elements won’t have any cost until you actually access these elements from your template.
- FromLazy (Func<Value> resolver)
Create a lazy value from given value resolver. See section Lazy value evaluation for details about lazy value resolution.
- FromReflection<TSource> (TSource source, Reflection.BindingFlags bindingFlags)
Create a reflection-based value to read members from object
source
. Source object fields and properties are resolved using Type.GetFields and Type.GetProperties methods and provided binding flags for resolution. See section Reflection values for details about reflection-based inspection.
- class FunctionValue
-
Deprecated class, use
Value.FromFunction
to create function values.Class constructor.
- class LazyValue
-
Deprecated class, use
Value.FromLazy
to create lazy values.Class constructor.
- class ReflectionValue
-
Deprecated class, use
Value.FromReflection
to create reflection values.- ReflectionValue (Object source, Reflection.BindingFlags binding)
Class constructor with explicit binding flags.
- ReflectionValue (Object source)
Class constructor with default binding flags for resolution (public + private + instance).
- class IMap
Value fields container.
- Value this[, Value key] { get; }
Get field by its key (usually its name), or an undefined value if no field was defined with this name.
Spying context
- class ISpyContext
-
Rendering context able to spy on variables and fields used during document rendering.
- ISpyRecord SpyVariable (Value key)
Spy variable matching given key from underlying context. This method can be called either before or after rendering a document, as returned record is updated on each rendering.
- IReadOnlyDictionary<Value, ISpyRecord> SpyVariables ()
Spy all variables used in rendered document from underlying context and return them as a dictionary indexed by variable key. Note that every variable referenced in a document will have an entry in returned dictionary, even if they were not accessed at rendering.
- class ISpyRecord
Spying information about variable or field value.
- ISpyRecord SpyField (Value key)
Spy field matching given key from current variable or field. This method is similar to
ISpyContext.SpyVariable
but works on variable fields instead of context variables.
- IReadOnlyDictionary<Value, ISpyRecord> SpyFields ()
Spy all fields from current variable or field and return then as a dictionary indexed by field key.