diff --git a/.gitignore b/.gitignore index 058252d..4454e6d 100644 --- a/.gitignore +++ b/.gitignore @@ -5,3 +5,6 @@ target docsite/site/generated docsite/site/public rerast_rules/ +integration.log +stdlibtest.log +unittest.log diff --git a/docsite/site/content/getting-started/_index.md b/docsite/site/content/getting-started/_index.md index 11ff0f1..215e26d 100644 --- a/docsite/site/content/getting-started/_index.md +++ b/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: Reference \ No newline at end of file diff --git a/docsite/site/content/reference/_index.md b/docsite/site/content/reference/_index.md index 7e948be..c2cc31e 100644 --- a/docsite/site/content/reference/_index.md +++ b/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 diff --git a/docsite/site/content/reference/expressions.md b/docsite/site/content/reference/expressions.md index 7ee49da..81a4089 100644 --- a/docsite/site/content/reference/expressions.md +++ b/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 -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. +support strings and base64 encoding but we plan to support yaml, and json 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. ``` 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 -are. Modules allow you to parameterize a set of statements and build the statements -later. Modules are an expression. They can be bound to a value and then reused later. -Modules do not close over their environment by they can import other UCG files into -the module using import statements. +UCG has another form of reusable execution that is a little more robust than +functions are. Modules allow you to parameterize a set of statements and build +the statements later. Modules are an expression. They can be bound to a value +and then reused later. Modules do not close over their environment but they can +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 -parameters with any associated default values. The body of the module is separated from -the parameter tuple by the `=>` symbol and is delimited by `{` and `}` respectively. +Module expressions start with the module keyword followed by a tuple +representing their parameters with any associated default values. The body of +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 -reference the bindings in the module similarly to selecting a tuple field or a binding -from an imported file. +You instantiate a module via the copy expression. The resulting module instance +can reference the bindings in the module similarly to selecting a tuple field +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!"; diff --git a/docsite/site/content/reference/statements.md b/docsite/site/content/reference/statements.md index d413b91..e67f085 100644 --- a/docsite/site/content/reference/statements.md +++ b/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.