DOCS: Normalize naming of UCG for consistency.

This commit is contained in:
Jeremy Wall 2019-01-05 09:56:07 -06:00
parent 6c0da11ff7
commit 922955ad0a
7 changed files with 31 additions and 31 deletions

View File

@ -10,7 +10,7 @@ Installing
### Cargo ### Cargo
You can install ucg using Rust's Cargo package manager. You can install UCG using Rust's Cargo package manager.
```sh ```sh
cargo install ucg cargo install ucg
@ -36,7 +36,7 @@ cargo install --path .
A simple configuration A simple configuration
---------------------- ----------------------
To create a configuration and build it in ucg you must first create a ucg file. Copy the below contents into a file called `sample.ucg`. All ucg files must end in the ucg To create a configuration and build it in UCG you must first create a UCG file. Copy the below contents into a file called `sample.ucg`. All UCG files must end in the UCG
extension. extension.
``` ```
@ -59,21 +59,21 @@ out yaml config;
``` ```
The above binds 3 values to names and then creates a config tuple using those values. The above binds 3 values to names and then creates a config tuple using those values.
We'll look in more detail at ucg's syntax later. We'll look in more detail at UCG's syntax later.
To generate a yaml file from the above run the ucg build command. To generate a yaml file from the above run the UCG build command.
```sh ```sh
ucg build sample.ucg ucg build sample.ucg
cat sample.yaml cat sample.yaml
``` ```
Ucg will generate the yaml file with the same name as the file containing the out statement. UCG will generate the yaml file with the same name as the file containing the out statement.
The ucg command line The UCG command line
----------- -----------
Ucg has builtin help on the command line. UCG has builtin help on the command line.
``` ```
$> ucg help $> ucg help

View File

@ -7,6 +7,6 @@ in_search_index = true
A collection of useful HowTo Guides A collection of useful HowTo Guides
---------- ----------
Some example use cases for ucg. Some example use cases for UCG.
* <a href="script">Creating a launch script for a docker container.</a> * <a href="script">Creating a launch script for a docker container.</a>

View File

@ -4,8 +4,8 @@ weight = 1
sort_by = "weight" sort_by = "weight"
in_search_index = true in_search_index = true
+++ +++
Let's say we wanted to use ucg generate a launch script for a local jupyter datascience Let's say we wanted to use UCG generate a launch script for a local jupyter datascience
notebook container. This HowTo walks you through creating a ucg file that can generate notebook container. This HowTo walks you through creating a UCG file that can generate
a script to launch the container. a script to launch the container.
First lets define some docker configuration values that we'll use later. First lets define some docker configuration values that we'll use later.

View File

@ -14,7 +14,7 @@ a name. A valid UCG file is composed of a series of statements. Statements can b
an expression, introduce named bindings, or create different outputs. All statements an expression, introduce named bindings, or create different outputs. All statements
must be terminiated by a semicolon. must be terminiated by a semicolon.
Some words are reserved in ucg and can not be used as a named binding. Some words are reserved in UCG and can not be used as a named binding.
* self * self

View File

@ -64,7 +64,7 @@ Generates the following flags in a file with the `.txt` extension.
Environment Variables Environment Variables
-------- --------
ucg is also able to generate environment variables from ucg values following a few UCG is also able to generate environment variables from UCG values following a few
translation rules. translation rules.
* Booleans, Integers, Floats, and Strings are output as is. * Booleans, Integers, Floats, and Strings are output as is.
@ -94,7 +94,7 @@ VERBOSE=true
Exec Script Exec Script
----- -----
ucg has an exec converter that will generate a launch script in bash for applications UCG has an exec converter that will generate a launch script in bash for applications
that are configured via command line flags or environment variables. The exec converter that are configured via command line flags or environment variables. The exec converter
uses a tuple with some required and optional fields to generate the script with. uses a tuple with some required and optional fields to generate the script with.

View File

@ -10,13 +10,13 @@ strings, copy and modify a struct, or format a string.
Symbols Symbols
------- -------
Many ucg expressions or statements use a symbol. A symbol might be used as Many UCG expressions or statements use a symbol. A symbol might be used as
either a name for a binding or a name for a field. Symbols must start with an either a name for a binding or a name for a field. Symbols must start with an
ascii letter and can contain any ascii letter, number, `_`, or `-` characters. ascii letter and can contain any ascii letter, number, `_`, or `-` characters.
### The environment symbol ### The environment symbol
There is a special symbol in ucg for obtaining a value from the environment. There is a special symbol in UCG for obtaining a value from the environment.
The `env` symbol references the environment variables in environment at the The `env` symbol references the environment variables in environment at the
time of the build. You reference an environment variable just like it was in a time of the build. You reference an environment variable just like it was in a
tuple. By default, attempting to reference a variable that doesn't exist will tuple. By default, attempting to reference a variable that doesn't exist will
@ -37,11 +37,11 @@ work on more than one type.
### Selector operators ### Selector operators
The UCG selector operator `.` selects a field or index from tuples or lists. The UCG selector operator `.` selects a field or index from tuples or lists.
They can descend descend arbitrarily deep into the selector. They can descend arbitrarily deep into data structures.
You can reference a field in a tuple by putting the field name after a dot. You can reference a field in a tuple by putting the field name after a dot. You
Lists are always 0 indexed. You can index into a list by referencing the index can index into a list by referencing the index after the `.`. Lists are always
after the `.`. 0 indexed.
``` ```
let tuple = { let tuple = {
@ -59,7 +59,7 @@ tuple.inner.field;
tuple.list.0; tuple.list.0;
``` ```
Selectors can quote fields in the selector if there are quoted fields with spaces in them. Selectors can quote fields if there are quoted fields with spaces in the tuple.
``` ```
tuple."quoted field"; tuple."quoted field";
@ -67,7 +67,7 @@ tuple."quoted field";
### Numeric Operators ### Numeric Operators
ucg supports the following numeric operators, `+`, `-`, `*`, `/` Each one is type safe UCG supports the following numeric operators, `+`, `-`, `*`, `/` Each one is type safe
and infers the types from the values they operate on. The operators expect both the and infers the types from the values they operate on. The operators expect both the
left and right operands to be of the same type. left and right operands to be of the same type.
@ -294,20 +294,20 @@ Modules
UCG has another form of reusable execution that is a little more composable than macros UCG has another form of reusable execution that is a little more composable than macros
are. Modules allow you to parameterize a set of statements and build the statements 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. 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 Modules do not close over their environment by they can import other UCG files into
the module using import statements. the module using import statements.
Module expressions start with the module keyword followed by a tuple representing their 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 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 parameter tuple by the `=>` symbol and is delimited by `{` and `}` respectively.
The body of the module can contain any valid ucg statement. The body of the module can contain any valid UCG statement.
``` ```
let top_mod = module { let top_mod = module {
deep_value = "None", deep_value = "None",
} => { } => {
import "shared.ucg" as shared_macros; import "shared.UCG" as shared_macros;
let embedded_def = module { let embedded_def = module {
deep_value = "None", deep_value = "None",

View File

@ -25,7 +25,7 @@ Named Value Statements
### Let statements ### Let statements
There are two statements that can introduce a named value for a given ucg file. Let There are two statements that can introduce a named value for a given UCG file. Let
statements and import statements. Any collisions in binding names inside a file are statements and import statements. Any collisions in binding names inside a file are
treated as compile errors. Bindings are immutable and once bound they can't be treated as compile errors. Bindings are immutable and once bound they can't be
modified. modified.
@ -36,9 +36,9 @@ let name = "foo";
### Import Statement ### Import Statement
The import statement imports the contents of another ucg file into the current file The import statement imports the contents of another UCG file into the current file
with a name. The imported file's named values are exposed as a tuple in the referencing with a name. The imported file's named values are exposed as a tuple in the referencing
file. It starts with the `import` keyword and is followed by a quoted path to the ucg file. It starts with the `import` keyword and is followed by a quoted path to the UCG
file, the keyword `as`, and a name for the imported values. file, the keyword `as`, and a name for the imported values.
``` ```
@ -49,7 +49,7 @@ let mysqlconf = dbconfigs.mysql;
Output Statements Output Statements
----------- -----------
Some statements in ucg exist to generate an output. Either a compiled Some statements in UCG exist to generate an output. Either a compiled
configuration or the results of test assertions. configuration or the results of test assertions.
### Assert Statements ### Assert Statements
@ -58,7 +58,7 @@ The assert statement defines an expression that must evaluate to either true or
Assert statements are noops except during a validation compile. They give you a way to Assert statements are noops except during a validation compile. They give you a way to
assert certains properties about your data and can be used as a form of unit testing 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 block for your configurations. It starts with the `assert` keyword followed by a valid block
of ucg statements delimited by `|` characters. The final statement in the block of UCG statements delimited by `|` characters. The final statement in the block
must evaluate to a boolean expression. must evaluate to a boolean expression.
``` ```
@ -86,7 +86,7 @@ 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 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) 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 artificact will take the same name as
the ucg file with the extension replaced by the defined extension for that the UCG file with the extension replaced by the defined extension for that
converter. converter.
For a file named api_config.ucg with the following contents: For a file named api_config.ucg with the following contents:
@ -99,7 +99,7 @@ let myconf = {
out json myconf; out json myconf;
``` ```
ucg will output the myconf tuple as json to a file called api_config.json UCG will output the myconf tuple as json to a file called api_config.json
You can get a list of the available converters as well as the extensions You can get a list of the available converters as well as the extensions
defined for each one by running the `ucg converters` command. defined for each one by running the `ucg converters` command.