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.
-
Value
-
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.
-
DocumentResult
-
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.
-
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.
-
String
-
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.
-
IDocument
-
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.
-
String
-
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
.
-
IContext
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.
-
Boolean
-
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.
-
IFunction
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
.
- From numbers, return
-
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
.
- From booleans, return
-
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.
- From booleans, return 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.
-
Value
-
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.
-
Value
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.
-
ISpyRecord
-
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.
-
ISpyRecord