zaphar/ucg
1
0
Fork 0
mirror of https://github.com/zaphar/ucg.git synced 2025-07-25 18:49:50 -04:00
Code Issues Packages Projects Releases Wiki Activity

MAINT: Grammar, Spelling, and minor content fixes.

Browse Source
This commit is contained in:
Jeremy Wall 2018-11-18 14:23:35 -06:00
parent 4875a0d75d
commit 11f86ea8f8
6 changed files with 110 additions and 93 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

34
docsite/site/content/getting-started/_index.md
View File

@ -73,26 +73,28 @@ Ucg will generate the yaml file with the same name as the file containing the ou
The ucg command line The ucg command line
----------- -----------
Ucg has builtin help on the command line. You can Ucg has builtin help on the command line.
$> ucg help ```
ucg 0.2.2 $> ucg help
Jeremy Wall <jeremy@marzhillstudios.com> ucg 0.2.2
Universal Configuration Grammar compiler. Jeremy Wall <jeremy@marzhillstudios.com>
Universal Configuration Grammar compiler.
USAGE: USAGE:
ucg [SUBCOMMAND] ucg [SUBCOMMAND]
FLAGS: FLAGS:
-h, --help Prints help information -h, --help Prints help information
-V, --version Prints version information -V, --version Prints version information
SUBCOMMANDS: SUBCOMMANDS:
build Build a list of ucg files. build Build a list of ucg files.
converters list the available converters converters list the available converters
help Prints this message or the help of the given subcommand(s) help Prints this message or the help of the given subcommand(s)
inspect Inspect a specific symbol in a ucg file. inspect Inspect a specific symbol in a ucg file.
test Check a list of ucg files for errors and run test assertions. test Check a list of ucg files for errors and run test assertions.
```
* build will build a list of files or directories of files. * 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. * inspect will allow you to print out the contents of a specific named binding in a ucg file.

8
docsite/site/content/how-to/script.md
View File

@ -11,7 +11,7 @@ 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.
``` ```
let image_conf = { let container_conf = {
port = 8888, port = 8888,
hostMount = "~/iJulia/notebooks", hostMount = "~/iJulia/notebooks",
mountPoint = "/var/iJulia/notebooks", mountPoint = "/var/iJulia/notebooks",
@ -26,8 +26,8 @@ let map_to_container = macro (host, container) => {
result = "@:@" % (host, container) result = "@:@" % (host, container)
}; };
let publish = map_to_container(docker_conf.port, docker_conf.port); let publish = map_to_container(container_conf.port, container_conf.port);
let volumes = map_to_container(docker_conf.hostMount, docker_conf.mountPoint); let volumes = map_to_container(container_conf.hostMount, container_conf.mountPoint);
``` ```
Now we set up our docker run flags. Now we set up our docker run flags.
@ -48,7 +48,7 @@ Finally we are ready to define our jupyter specific flags.
``` ```
let jupyter_flags = { let jupyter_flags = {
notebook-dir = docker_conf.mountPoint notebook-dir = container_conf.mountPoint
}; };
``` ```

8
docsite/site/content/reference/converters.md
View File

@ -35,7 +35,7 @@ rules for each type.
* Nested tuples concatenate the field names to create the field. * Nested tuples concatenate the field names to create the field.
* Nested Lists generate a new `--field listitem` pair for each item in the list. * Nested Lists generate a new `--field listitem` pair for each item in the list.
* For fields that are just one character in length use a single `-`. Use double * For fields that are just one character in length use a single `-`. Use double
dashes for fields of longer than one character. dashes `--` for fields that are longer than one character.
### Example ### Example
@ -69,7 +69,7 @@ translation rules.
* Booleans, Integers, Floats, and Strings are output as is. * Booleans, Integers, Floats, and Strings are output as is.
* Lists are not output. * Lists are not output.
* Tuples are output as a `FIELD=value` for each field with strings surrounded by double * Tuples are output as a `FIELD=value` for each field with strings surrounded by single
quotes. quotes.
* Nested Tuples are not output. * Nested Tuples are not output.
@ -117,7 +117,7 @@ let common_flags = {
let script = { let script = {
env = { env = {
apikey = "foo-key-and-stuff", API_KEY = "foo-key-and-stuff",
}, },
command = "my-app", command = "my-app",
args = [ args = [
@ -136,7 +136,7 @@ The script tuple above will generate the following bash script:
# Turn on unofficial Bash-Strict-Mode # Turn on unofficial Bash-Strict-Mode
set -euo pipefail set -euo pipefail
VERBOSE_LOG="true" API_KEY="foo-key-and-stuff"
exec my-app --log-level debug --maxMem 2048M serve --port 8080 exec my-app --log-level debug --maxMem 2048M serve --port 8080
``` ```

110
docsite/site/content/reference/expressions.md
View File

@ -4,24 +4,27 @@ weight = 3
sort_by = "weight" sort_by = "weight"
in_search_index = true in_search_index = true
+++ +++
Ucg expressions can reference a bound name, do math, concatenate lists or strings, Ucg expressions can reference a bound name, do math, concatenate lists or
copy and modify a struct, or format a string. 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 for either Many ucg expressions or statements use a symbol. A symbol might be used as
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. 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.
Selectors Selectors
------ ------
A UCG selector references a bound value by name. They can descend into tuples or lists A UCG selector references a bound value by name. They can descend into tuples
or refer to symbols in imported files. They are symbol followed optionally by a list or lists or refer to symbols in imported files. They start with a symbol followed
of other symbols or numbers separated by a `.` to reference subfields or indexes in a list. optionally by a list of other symbols or numbers separated by `.` characters to
reference subfields or indexes in a list.
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 You can reference a field in a tuple by putting the field name after a dot.
a `.`. Lists are always 0 indexed. You can index into a list by referencing the index
after a `.`.
``` ```
let tuple = { let tuple = {
@ -40,10 +43,11 @@ tuple.list.0;
### The environment Selector ### The environment Selector
There is a special selector in ucg for obtaining a value from the environment. The There is a special selector in ucg for obtaining a value from the environment.
`env` selector references the environment variables in environment at the time of The `env` selector references the environment variables in environment at the
the build. You reference environment variables just like it was a tuple. Attempting time of the build. You reference an environment variable just like it was in a
to reference a variable that doesn't exist will be a compile error. tuple. Attempting to reference a variable that doesn't exist will be a compile
error.
``` ```
let env_name = env.DEPLOY_ENV; let env_name = env.DEPLOY_ENV;
@ -52,7 +56,7 @@ let env_name = env.DEPLOY_ENV;
Binary Operators Binary Operators
---------- ----------
UCG has a numver of binary infix operators. Some work only on numeric values and others UCG has a number of binary infix operators. Some work only on numeric values and others
work on more than one type. work on more than one type.
### Numeric Operators ### Numeric Operators
@ -78,11 +82,11 @@ version both sides must be the same type, either string or list.
### Comparison Operators ### Comparison Operators
UCG supports the comparison operators `==`, `!=`, `>=`, `<=`, `<`, and `>`. The all UCG supports the comparison operators `==`, `!=`, `>=`, `<=`, `<`, and `>`.
expect both sides to be of the same type. They all expect both sides to be of the same type.
The `>`, `<`, `>=`, and `>=` operators are only supported on numeric types (i.e. int, The `>`, `<`, `>=`, and `>=` operators are only supported on numeric types
and float). (i.e. int, and float).
``` ```
1 > 2; // result is false 1 > 2; // result is false
@ -91,8 +95,8 @@ and float).
(1+2) == 3; (1+2) == 3;
``` ```
The equality operators `==` and `!=` are supported for all types and will perform deep The equality operators `==` and `!=` are supported for all types and will
equal comparisons on complex types. perform deep equal comparisons on complex types.
``` ```
let tpl1 = { let tpl1 = {
@ -112,27 +116,28 @@ let tpl2 = {
tpl1 == tpl3; // returns false tpl1 == tpl3; // returns false
``` ```
Because tuples are an ordered set both tuples in a comparison must have their fields in Because tuples are an ordered set both tuples in a comparison must have their
the same order to compare as equal. fields in the same order to compare as equal.
#### Operator Precedence #### Operator Precedence
UCG binary operators follow the typical operator precedence for math. `*` and `/` are UCG binary operators follow the typical operator precedence for math. `*` and
higher precendence than `+` and `-` which are higher precedence than any of the `/` are higher precendence than `+` and `-` which are higher precedence than
comparison operators. any of the comparison operators.
Copy Expressions Copy Expressions
---------------- ----------------
UCG expressions have a special copy expression for tuples. These faciliate a form of UCG expressions have a special copy expression for tuples. These faciliate a
data reuse as well as a way to get a modified version of a tuple. Copy expressions form of data reuse as well as a way to get a modified version of a tuple. Copy
start with a selector referencing a tuple followed by braces `{}` with `name = value` expressions start with a selector referencing a tuple followed by braces `{}`
pairs separated by commas. Trailing commas are allowed. with `name = value` pairs separated by commas. Trailing commas are allowed.
Copied expressions can change base fields in the copied tuple or add new fields. If Copied expressions can change base fields in the copied tuple or add new
you are changing the value of a base field in the copy then the new value must be of fields. If you are changing the value of a base field in the copy then the new
the same type as the base field's value. This allows you to define a base "type" of value must be of the same type as the base field's value. This allows you to
sorts and ensure that any modified fields stay the same. define a base "type" of sorts and ensure that any modified fields stay the
same.
``` ```
let base = { let base = {
@ -156,8 +161,9 @@ let bad = base{
``` ```
There is a special selector that can be used in a copy expression to refer to the base There is a special selector that can be used in a copy expression to refer to
tuple in a copy called `self`. `self` can only be used in the body of the copy. the base tuple in a copy called `self`. `self` can only be used in the body of
the copy.
``` ```
let nestedtpl = { let nestedtpl = {
@ -182,11 +188,11 @@ let copiedtpl = nestedtpl{
Format Expressions Format Expressions
---------- ----------
UCG has a format expression that has a limited form of string templating. A format UCG has a format expression that has a limited form of string templating. A
expression starts with a string followed by the `%` operator and a list of arguments format expression starts with a string followed by the `%` operator and a list
in parentheses separated by commas. Trailing commas are allowed. The format string of arguments in parentheses separated by commas. Trailing commas are allowed.
should have `@` in each location where a value should be placed. Any primitive value The format string should have `@` characters in each location where a value
can be used as an argument. should be placed. Any primitive value can be used as an argument.
``` ```
"https://@:@/" % (host, port) "https://@:@/" % (host, port)
@ -195,11 +201,11 @@ can be used as an argument.
Conditionals Conditionals
---------- ----------
UCG supports a limited conditional expression called a select. A select expression UCG supports a limited conditional expression called a select. A select
starts with the `select` keyword and is followed by a an expression resolving to a expression starts with the `select` keyword and is followed by a an expression
string naming the field to select, an expression resolving to the default value, and resolving to a string naming the field to select, an expression resolving to
finally a tuple literal to select the field from. If the field selected is not in the the default value, and finally a tuple literal to select the field from. If the
tuple then the default value will be used. field selected is not in the tuple then the default value will be used.
``` ```
let want = "baz"; let want = "baz";
@ -220,13 +226,13 @@ select "quack", "quux", {
Macros Macros
----- -----
Macros look like functions but they are resolved at compile time and configurations Macros look like functions but they are resolved at compile time and
don't execute so they never appear in output. Macros do not close over their configurations don't execute so they never appear in output. Macros do not
environment so they can only reference values defined in their arguments. They can't close over their environment so they can only reference values defined in their
refer to bindings or other macros defined elsewhere. They are useful for constructing arguments. They can't refer to bindings or other macros defined elsewhere. They
tuples of a certain shape or otherwise promoting data reuse. You define a macro with are useful for constructing tuples of a certain shape or otherwise promoting
the `macro` keyword followed by the arguments in parentheses, a `=>`, and then a tuple data reuse. You define a macro with the `macro` keyword followed by the
literal. arguments in parentheses, a `=>`, and then a tuple literal.
``` ```
let mymacro = macro (arg1, arg2) => { let mymacro = macro (arg1, arg2) => {

30
docsite/site/content/reference/statements.md
View File

@ -18,8 +18,7 @@ followed by a semicolon.
``` ```
Despite the fact that these are valid the results are thrown away and can essentially Despite the fact that these are valid the results are thrown away and can essentially
be considered a noop. If we ever create a repl for ucg statements they may prove more be considered a noop.
useful.
Named Value Statements Named Value Statements
-------- --------
@ -27,7 +26,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
statnements 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.
@ -38,7 +37,7 @@ 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 files 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.
@ -50,7 +49,8 @@ let mysqlconf = dbconfigs.mysql;
Output Statements Output Statements
----------- -----------
Some statements in ucg exist to generate an output. Either a compiled configuration or the results of test assertions. Some statements in ucg exist to generate an output. Either a compiled
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 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.
``` ```
@ -74,15 +74,20 @@ assert |
|; |;
``` ```
When _test.ucg files are run in a test run then ucg will output a log of all the assertions to stdout. Giving you a simple test harness for your ucg configs. Assert statements are only evaluated when running the `ucg test` command. That
command evaluates all of the `*_test.ucg` files. When `*_test.ucg` files are
run in a test run then ucg will output a log of all the assertions to stdout as
well as a PASS or FAIL for each file. This gives you a simple test harness for
your ucg configs.
### Out Statements ### Out Statements
The Out statement defines the output for a UCG file. It identifies the output 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 converter type and an expression that will be output. The output converter type
expected to be one of the registered converters (e.g. json, exec) and the artifact is expected to be one of the registered converters unquoted (e.g. json, exec)
file will take the same name as the ucg file with the extension replaced by the and the value to convert. The generated artificact will take the same name as
defined extension for that converter. 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: For a file named api_config.ucg with the following contents:
@ -96,4 +101,7 @@ 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.
Next: <a href="/reference/converters">Converters</a> Next: <a href="/reference/converters">Converters</a>

5
docsite/site/content/reference/types.md
View File

@ -29,7 +29,7 @@ An Integer is any 64 bit integer number.
### Float ### Float
A Float is any 64 bit floating point numer. You indicate a number is a Float by A Float is any 64 bit floating point number. You indicate a number is a Float by
including a decimal point. Any number with a decimal point is a float. including a decimal point. Any number with a decimal point is a float.
``` ```
@ -40,10 +40,11 @@ including a decimal point. Any number with a decimal point is a float.
### String ### String
Strings are any double quoted text. Strings are any double quoted text. You can use the `\` to esacpe characters in the text.
``` ```
"This is a string"; "This is a string";
"This is an escaped \"string\"";
``` ```
### NULL or the Empty type ### NULL or the Empty type