Update documentation about native functions.

doc/page/05-advanced.rst

@@ -198,7 +198,7 @@ Native .NET functions
 
 If you need new features or improved performance, you can assign your own .NET methods to template variables so they're available as Cottle functions. That's actually what Cottle does when you use :meth:`Context.CreateBuiltin` method: a set of Cottle methods is added to your context, and you can have a look at the source code to see how these methods work.
 
-To pass a function in a context, use one of the methods from :type:`Function` class, then pass it to :meth:`Value.FromFunction` method to wrap it into a value you can add to a context:
+To pass a function in a context, use one of the creation methods from :type:`Function` class, then pass it to :meth:`Value.FromFunction` method to wrap it into a value you can add to a context:
 
 .. code-block:: plain
     :caption: Cottle template
@@ -237,19 +237,19 @@ To pass a function in a context, use one of the methods from :type:`Function` cl
 Static class :type:`Function` supports multiple methods to create Cottle functions. Each method expects a .NET callback that contains the code to be executed when the method is invoked, and some of them also ask for the accepted number of parameters for the function being defined. Methods from :type:`Function` are defined across a combination of 2 criteria:
 
 * Whether they're having side effects or not:
-    * Methods :meth:`Function.CreatePure`, :meth:`Function.CreatePure1` and :meth:`Function.CreatePure2` must be pure functions having no side effect and not relying on anything but their arguments. This assumption is used by Cottle to perform optimizations in your templates. For this reason their callbacks don't receive a ``TextWriter`` argument as pure methods are not allowed to write anything to output.
-    * Methods :meth:`Function.Create`, :meth:`Function.Create1` and :meth:`Function.Create2` are allowed to perform side effects but will be excluded from most optimizations. Their callbacks receive a ``TextWriter`` argument so they can write any text contents to it.
+    * Methods ``Function.CreateNative*`` (e.g. :meth:`Function.CreateNativeExact`) are allowed to perform side effects but will be excluded from most optimizations. Their callbacks receive a :type:`IRuntime` instance to access runtime information such as global variables, and a :type:`System.IO.TextWriter` instance so they can write any text contents to it.
+    * Methods ``Function.CreatePure*`` (e.g. :meth:`Function.CreatePureVariadic`) must be pure functions having no side effect and not relying on anything but their arguments. This assumption is used by Cottle to perform optimizations in your templates.
 * How many arguments they accept:
-    * Methods :meth:`Function.Create` and :meth:`Function.CreatePure` with no integer argument accept any number of arguments, it is the responsibility of provided callback to validate this number.
-    * Methods :meth:`Function.Create` and :meth:`Function.CreatePure` with a ``count`` integer accept exactly this number of arguments or return an undefined value otherwise.
-    * Methods :meth:`Function.Create` and :meth:`Function.CreatePure` with two ``min`` and ``max`` integers accept a number of arguments contained between these two values or return an undefined value otherwise.
-    * Methods :meth:`Function.CreateN` and :meth:`Function.CreatePureN` only accept exactly ``N`` arguments or return an undefined value otherwise.
+    * Methods ``Function.Create*Exact`` (e.g. :meth:`Function.CreateNativeExact`) expect a fixed number of arguments when invoked or return an undefined value otherwise.
+    * Methods ``Function.Create*MinMax`` (e.g. :meth:`Function.CreatePureMinMax`) accept between ``min`` and ``max`` arguments or return an undefined value otherwise.
+    * Methods ``Function.Create*N`` (e.g. :meth:`Function.CreateNativeN`) only accept exactly ``N`` arguments or return an undefined value otherwise.
+    * Methods ``Function.Create*Variadic`` (e.g. :meth:`Function.CreatePureVariadic`) accept any number of arguments, it is the responsibility of provided callback to validate this number.
 
-The callback you'll pass to :type:`Function` takes multiple arguments:
+Here are the arguments received by the callback you'll pass to these methods:
 
-* First argument is always an internal state that must be forwarded to any nested function call ;
+* First argument is either a :type:`IRuntime` instance (for non-pure functions) or an opaque state (for pure ones) that must be forwarded to any nested function call ;
 * Next arguments are either a list of values (for functions accepting variable number of arguments) or separate scalar values (for functions accepting a fixed number of arguments) received as arguments when invoking the function ;
-* Last argument, for non-pure functions only, is a ``TextWriter`` instance open to current document output.
+* Last argument, for non-pure functions only, is a :type:`System.IO.TextWriter` instance open to current document output.
 
 
 

doc/page/06-api.rst

@@ -242,43 +242,43 @@ Function declaration
 
     Methods from this static class must be used to create instances of :type:`IFunction`.
 
-    .. method:: IFunction Create(System.Func<System.Object,System.Collections.Generic.IReadOnlyList<Value>,System.IO.TextWriter,Value> callback, int min, int max)
+    .. method:: IFunction CreateNativeExact(System.Func<IRuntime,System.Collections.Generic.IReadOnlyList<Value>,System.IO.TextWriter,Value> callback, int count)
 
-        Create a non-pure function accepting between ``min`` and ``max`` arguments (included).
+        Create a non-pure function accepting exactly ``count`` arguments.
 
-    .. method:: IFunction Create(System.Func<System.Object,System.Collections.Generic.IReadOnlyList<Value>,System.IO.TextWriter,Value> callback, int count)
+    .. method:: IFunction CreateNativeMinMax(System.Func<IRuntime,System.Collections.Generic.IReadOnlyList<Value>,System.IO.TextWriter,Value> callback, int min, int max)
 
-        Create a non-pure function accepting exactly ``count`` arguments.
+        Create a non-pure function accepting between ``min`` and ``max`` arguments (included).
 
-    .. method:: IFunction Create(System.Func<System.Object,System.Collections.Generic.IReadOnlyList<Value>,System.IO.TextWriter,Value> callback)
+    .. method:: IFunction CreateNativeVariadic(System.Func<IRuntime,System.Collections.Generic.IReadOnlyList<Value>,System.IO.TextWriter,Value> callback)
 
         Create a non-pure function accepting any number of arguments.
 
-    .. method:: IFunction Create0(System.Func<System.Object,System.IO.TextWriter,Value> callback)
+    .. method:: IFunction CreateNative0(System.Func<IRuntime,System.IO.TextWriter,Value> callback)
 
         Create a non-pure function accepting zero argument.
 
-    .. method:: IFunction Create1(System.Func<System.Object,Value,System.IO.TextWriter,Value> callback)
+    .. method:: IFunction CreateNative1(System.Func<IRuntime,Value,System.IO.TextWriter,Value> callback)
 
         Create a non-pure function accepting one argument.
 
-    .. method:: IFunction Create2(System.Func<System.Object,Value,Value,System.IO.TextWriter,Value> callback)
+    .. method:: IFunction CreateNative2(System.Func<IRuntime,Value,Value,System.IO.TextWriter,Value> callback)
 
         Create a non-pure function accepting two arguments.
 
-    .. method:: IFunction Create3(System.Func<System.Object,Value,Value,Value,System.IO.TextWriter,Value> callback)
+    .. method:: IFunction CreateNative3(System.Func<IRuntime,Value,Value,Value,System.IO.TextWriter,Value> callback)
 
         Create a non-pure function accepting three arguments.
 
-    .. method:: IFunction CreatePure(System.Func<System.Object,System.Collections.Generic.IReadOnlyList<Value>,Value> callback, int min, int max)
+    .. method:: IFunction CreatePureExact(System.Func<System.Object,System.Collections.Generic.IReadOnlyList<Value>,Value> callback, int count)
 
-        Create a pure function accepting between ``min`` and ``max`` arguments (included).
+        Create a pure function accepting exactly ``count`` arguments.
 
-    .. method:: IFunction CreatePure(System.Func<System.Object,System.Collections.Generic.IReadOnlyList<Value>,Value> callback, int count)
+    .. method:: IFunction CreatePureMinMax(System.Func<System.Object,System.Collections.Generic.IReadOnlyList<Value>,Value> callback, int min, int max)
 
-        Create a pure function accepting exactly ``count`` arguments.
+        Create a pure function accepting between ``min`` and ``max`` arguments (included).
 
-    .. method:: IFunction CreatePure(System.Func<System.Object,System.Collections.Generic.IReadOnlyList<Value>,Value> callback)
+    .. method:: IFunction CreatePureVariadic(System.Func<System.Object,System.Collections.Generic.IReadOnlyList<Value>,Value> callback)
 
         Create a pure function accepting any number of arguments.
 
@@ -299,6 +299,16 @@ Function declaration
         Create a pure function accepting three arguments.
 
 
+.. namespace:: Cottle
+.. class:: IRuntime
+
+    Access to runtime execution data.
+
+    .. property:: IMap Globals { get; }
+
+        Global variables defined in template being rendered currently.
+
+
 
 Value declaration
 =================

doc/page/07-version.rst

@@ -23,6 +23,14 @@ The main difference between this approach and SemVer is the distinction made bet
 Migration guide
 ===============
 
+From 2.0.\* to 2.1.\*
+---------------------
+
+* Non-pure functions should be created with ``Function.CreateNative*`` instead of ``Function.Create*``, and the first argument of the callback they receive is now :type:`IRuntime`.
+* Overloads of method ``Function.Create`` are replaced by methods with unique name: :meth:`Function.CreateNativeExact`, :meth:`Function.CreateNativeMinMax` & :meth:`Function.CreateNativeVariadic`.
+* Overloads of method ``Function.CreatePure`` are replaced by methods with unique name: :meth:`Function.CreatePureExact`, :meth:`Function.CreatePureMinMax` & :meth:`Function.CreatePureVariadic`.
+
+
 From 1.6.\* to 2.0.\*
 ---------------------