mirror of
https://github.com/zaphar/ucg.git
synced 2025-07-22 18:19:54 -04:00
DOCS: Normalize naming of UCG for consistency.
This commit is contained in:
parent
6c0da11ff7
commit
922955ad0a
@ -10,7 +10,7 @@ Installing
|
||||
|
||||
### Cargo
|
||||
|
||||
You can install ucg using Rust's Cargo package manager.
|
||||
You can install UCG using Rust's Cargo package manager.
|
||||
|
||||
```sh
|
||||
cargo install ucg
|
||||
@ -36,7 +36,7 @@ cargo install --path .
|
||||
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.
|
||||
|
||||
```
|
||||
@ -59,21 +59,21 @@ out yaml config;
|
||||
```
|
||||
|
||||
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
|
||||
ucg build sample.ucg
|
||||
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
|
||||
|
@ -7,6 +7,6 @@ in_search_index = true
|
||||
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>
|
@ -4,8 +4,8 @@ weight = 1
|
||||
sort_by = "weight"
|
||||
in_search_index = true
|
||||
+++
|
||||
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
|
||||
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
|
||||
a script to launch the container.
|
||||
|
||||
First lets define some docker configuration values that we'll use later.
|
||||
|
@ -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
|
||||
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
|
||||
|
@ -64,7 +64,7 @@ Generates the following flags in a file with the `.txt` extension.
|
||||
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.
|
||||
|
||||
* Booleans, Integers, Floats, and Strings are output as is.
|
||||
@ -94,7 +94,7 @@ VERBOSE=true
|
||||
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
|
||||
uses a tuple with some required and optional fields to generate the script with.
|
||||
|
||||
|
@ -10,13 +10,13 @@ strings, copy and modify a struct, or format a string.
|
||||
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
|
||||
ascii letter and can contain any ascii letter, number, `_`, or `-` characters.
|
||||
|
||||
### 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
|
||||
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
|
||||
@ -37,11 +37,11 @@ work on more than one type.
|
||||
### Selector operators
|
||||
|
||||
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.
|
||||
Lists are always 0 indexed. You can index into a list by referencing the index
|
||||
after the `.`.
|
||||
You can reference a field in a tuple by putting the field name after a dot. You
|
||||
can index into a list by referencing the index after the `.`. Lists are always
|
||||
0 indexed.
|
||||
|
||||
```
|
||||
let tuple = {
|
||||
@ -59,7 +59,7 @@ tuple.inner.field;
|
||||
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";
|
||||
@ -67,7 +67,7 @@ tuple."quoted field";
|
||||
|
||||
### 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
|
||||
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
|
||||
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
|
||||
Modules do not close over their environment by they can import other UCG files into
|
||||
the module using import statements.
|
||||
|
||||
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.
|
||||
The body of the module can contain any valid UCG statement.
|
||||
|
||||
```
|
||||
let top_mod = module {
|
||||
deep_value = "None",
|
||||
} => {
|
||||
import "shared.ucg" as shared_macros;
|
||||
import "shared.UCG" as shared_macros;
|
||||
|
||||
let embedded_def = module {
|
||||
deep_value = "None",
|
||||
|
@ -25,7 +25,7 @@ Named Value 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
|
||||
treated as compile errors. Bindings are immutable and once bound they can't be
|
||||
modified.
|
||||
@ -36,9 +36,9 @@ let name = "foo";
|
||||
|
||||
### 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
|
||||
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.
|
||||
|
||||
```
|
||||
@ -49,7 +49,7 @@ let mysqlconf = dbconfigs.mysql;
|
||||
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.
|
||||
|
||||
### 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 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
|
||||
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.
|
||||
|
||||
```
|
||||
@ -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
|
||||
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
|
||||
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.
|
||||
|
||||
For a file named api_config.ucg with the following contents:
|
||||
@ -99,7 +99,7 @@ let 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
|
||||
defined for each one by running the `ucg converters` command.
|
||||
|
Loading…
x
Reference in New Issue
Block a user