DOCS: A raft of fixes and updates to the documentation site.

.gitignore

@@ -5,3 +5,6 @@ target
 docsite/site/generated
 docsite/site/public
 rerast_rules/
+integration.log
+stdlibtest.log
+unittest.log

docsite/site/content/getting-started/_index.md

@@ -28,7 +28,7 @@ from github and use cargo to build.
 git clone https://github.com/zaphar/ucg
 cd ucg
 # optionally checkout the current version
-git checkout v0.2.3
+git checkout v0.5.1
 # use cargo to build and install
 cargo install --path .
 ```
@@ -91,16 +91,12 @@ SUBCOMMANDS:
     build         Build a list of ucg files.
     converters    list the available converters
     env           Describe the environment variables ucg uses.
+    eval          Evaluate an expression with an optional ucg file as context.
     help          Prints this message or the help of the given subcommand(s)
-    inspect       Inspect a specific symbol in a ucg file.
+    importers     list the available importers for includes
     test          Check a list of ucg files for errors and run test assertions.
 ```
 
-* build will build a list of files or directories of files.
-* inspect will allow you to print out the contents of a specific named binding in a ucg file.
-* test compiles and runs any test assertions in the provided files or directories of files.
-* converters will list the available conversion formats that this ucg tool supports.
-
 You can get more information about the options for each command by running `ucg help $command`
 
 Next: <a href="/reference">Reference</a>

docsite/site/content/reference/_index.md

@@ -34,6 +34,7 @@ Some words are reserved in UCG and can not be used as a named binding.
 * env
 * map
 * filter
+* reduce
 * NULL
 * out
 

docsite/site/content/reference/expressions.md

@@ -459,8 +459,10 @@ Include expressions
 -------------------
 
 UCG can include the contents of other files as an expression. Currently we only
-support strings but we plan to support yaml, and json and possibly base64 encoding
+support strings and base64 encoding but we plan to support yaml, and json in
-in the future. include expressions start with the `include` keyword a type (currently only `str`), and a path. Relative paths are calculated relative to the including file.
+the future. include expressions start with the `include` keyword a type
+(currently only `str`), and a path. Relative paths are calculated relative to
+the including file.
 
 ```
 let script = include str "./script.sh";
@@ -500,15 +502,18 @@ let ifresult = select true, NULL, {
 Modules
 -------
 
-UCG has another form of reusable execution that is a little more robust than functions
+UCG has another form of reusable execution that is a little more robust than
-are. Modules allow you to parameterize a set of statements and build the statements
+functions are. Modules allow you to parameterize a set of statements and build
-later. Modules are an expression. They can be bound to a value and then reused later.
+the statements later. Modules are an expression. They can be bound to a value
-Modules do not close over their environment by they can import other UCG files into
+and then reused later. Modules do not close over their environment but they can
-the module using import statements.
+import other UCG files into the module using import statements including the
+file they are located themselves. This works since the statements in a module
+until you attempt to call the module with a copy expression.
 
-Module expressions start with the module keyword followed by a tuple representing their
+Module expressions start with the module keyword followed by a tuple
-parameters with any associated default values. The body of the module is separated from
+representing their parameters with any associated default values. The body of
-the parameter tuple by the `=>` symbol and is delimited by `{` and `}` respectively.
+the module is separated from the parameter tuple by the `=>` symbol and is
+delimited by `{` and `}` respectively.
 
 The body of the module can contain any valid UCG statement.
 
@@ -528,9 +533,9 @@ let top_mod = module {
 };
 ```
 
-You instantiate a module via the copy expression. The resulting module instance can
+You instantiate a module via the copy expression. The resulting module instance
-reference the bindings in the module similarly to selecting a tuple field or a binding
+can reference the bindings in the module similarly to selecting a tuple field
-from an imported file.
+or a binding from an imported file.
 
 ```
 let embedded_default_params = top_mod{};
@@ -540,12 +545,20 @@ let embedded_with_params = embedded_mod{deep_value = "Some"};
 embedded_with_params.embedded.value == "Some";
 ```
 
+### Recursive Modules
+
+One consequence of a module being able to import the same file they are located in
+is that modules can be called recursively. They are the only expression that is
+capable of recursion in UCG. Recursion can be done by importing the module's file
+inside the module's definition and using it as normal.
+
 Fail Expression
 ---------------
 
 UCG has a way to declaratively trigger a build failure using the `fail` expression.
 
-Fail expression start with the `fail` keyword and are followed with either a string or a format expression with the build failure message.
+Fail expressions start with the `fail` keyword and are followed an expression
+that must resolve to a string with the build failure message.
 
 ```
 fail "Oh No This was not what we wanted!";

docsite/site/content/reference/statements.md

@@ -43,7 +43,7 @@ configuration or the results of test assertions.
 
 The assert statement defines an expression that must evaluate to tuple with an
 ok field that is either true or false and a desc field that is a string. Assert
-statements are noops except during a validation compile. They give you a way to
+statements are noops except when executing `ucg test`. They give you a way to
 assert certains properties about your data and can be used as a form of unit
 testing for your configurations. It starts with the `assert` keyword followed
 by a valid ucg expression.
@@ -74,7 +74,7 @@ your ucg configs.
 The Out statement defines the output for a UCG file. It identifies the output
 converter type and an expression that will be output. The output converter type
 is expected to be one of the registered converters unquoted (e.g. json, exec)
-and the value to convert. The generated artificact will take the same name as
+and the value to convert. The generated artifact will take the same name as
 the UCG file with the extension replaced by the defined extension for that
 converter.