From 11f86ea8f8c4abd994cb53c321687b50dc690df0 Mon Sep 17 00:00:00 2001 From: Jeremy Wall Date: Sun, 18 Nov 2018 14:23:35 -0600 Subject: [PATCH] MAINT: Grammar, Spelling, and minor content fixes. --- .../site/content/getting-started/_index.md | 40 ++++--- docsite/site/content/how-to/script.md | 8 +- docsite/site/content/reference/converters.md | 8 +- docsite/site/content/reference/expressions.md | 110 +++++++++--------- docsite/site/content/reference/statements.md | 32 +++-- docsite/site/content/reference/types.md | 5 +- 6 files changed, 110 insertions(+), 93 deletions(-) diff --git a/docsite/site/content/getting-started/_index.md b/docsite/site/content/getting-started/_index.md index 9f95ade..90fea63 100644 --- a/docsite/site/content/getting-started/_index.md +++ b/docsite/site/content/getting-started/_index.md @@ -73,26 +73,28 @@ Ucg will generate the yaml file with the same name as the file containing the ou 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 - Jeremy Wall - Universal Configuration Grammar compiler. - - USAGE: - ucg [SUBCOMMAND] - - FLAGS: - -h, --help Prints help information - -V, --version Prints version information - - SUBCOMMANDS: - build Build a list of ucg files. - converters list the available converters - help Prints this message or the help of the given subcommand(s) - inspect Inspect a specific symbol in a ucg file. - test Check a list of ucg files for errors and run test assertions. +``` +$> ucg help +ucg 0.2.2 +Jeremy Wall +Universal Configuration Grammar compiler. + +USAGE: + ucg [SUBCOMMAND] + +FLAGS: + -h, --help Prints help information + -V, --version Prints version information + +SUBCOMMANDS: + build Build a list of ucg files. + converters list the available converters + help Prints this message or the help of the given subcommand(s) + inspect Inspect a specific symbol in a ucg file. + 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. diff --git a/docsite/site/content/how-to/script.md b/docsite/site/content/how-to/script.md index 99a8f2e..cd372f2 100644 --- a/docsite/site/content/how-to/script.md +++ b/docsite/site/content/how-to/script.md @@ -11,7 +11,7 @@ a script to launch the container. First lets define some docker configuration values that we'll use later. ``` -let image_conf = { +let container_conf = { port = 8888, hostMount = "~/iJulia/notebooks", mountPoint = "/var/iJulia/notebooks", @@ -26,8 +26,8 @@ let map_to_container = macro (host, container) => { result = "@:@" % (host, container) }; -let publish = map_to_container(docker_conf.port, docker_conf.port); -let volumes = map_to_container(docker_conf.hostMount, docker_conf.mountPoint); +let publish = map_to_container(container_conf.port, container_conf.port); +let volumes = map_to_container(container_conf.hostMount, container_conf.mountPoint); ``` 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 = { - notebook-dir = docker_conf.mountPoint + notebook-dir = container_conf.mountPoint }; ``` diff --git a/docsite/site/content/reference/converters.md b/docsite/site/content/reference/converters.md index 5ac05bc..cd51a8b 100644 --- a/docsite/site/content/reference/converters.md +++ b/docsite/site/content/reference/converters.md @@ -35,7 +35,7 @@ rules for each type. * Nested tuples concatenate the field names to create the field. * 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 - dashes for fields of longer than one character. + dashes `--` for fields that are longer than one character. ### Example @@ -69,7 +69,7 @@ translation rules. * Booleans, Integers, Floats, and Strings are output as is. * 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. * Nested Tuples are not output. @@ -117,7 +117,7 @@ let common_flags = { let script = { env = { - apikey = "foo-key-and-stuff", + API_KEY = "foo-key-and-stuff", }, command = "my-app", args = [ @@ -136,7 +136,7 @@ The script tuple above will generate the following bash script: # Turn on unofficial Bash-Strict-Mode set -euo pipefail -VERBOSE_LOG="true" +API_KEY="foo-key-and-stuff" exec my-app --log-level debug --maxMem 2048M serve --port 8080 ``` diff --git a/docsite/site/content/reference/expressions.md b/docsite/site/content/reference/expressions.md index 09687a7..473e673 100644 --- a/docsite/site/content/reference/expressions.md +++ b/docsite/site/content/reference/expressions.md @@ -4,24 +4,27 @@ weight = 3 sort_by = "weight" in_search_index = true +++ -Ucg expressions can reference a bound name, do math, concatenate lists or strings, -copy and modify a struct, or format a string. +Ucg expressions can reference a bound name, do math, concatenate lists or +strings, copy and modify a struct, or format a string. Symbols ------- -Many ucg expressions or statements use a symbol. A symbol might be used for either -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. +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. Selectors ------ -A UCG selector references a bound value by name. They can descend into tuples or lists -or refer to symbols in imported files. They are symbol followed optionally by a list -of other symbols or numbers separated by a `.` to reference subfields or indexes in a list. +A UCG selector references a bound value by name. They can descend into tuples +or lists or refer to symbols in imported files. They start with a symbol followed +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 -a `.`. +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 a `.`. ``` let tuple = { @@ -40,10 +43,11 @@ tuple.list.0; ### The environment Selector -There is a special selector in ucg for obtaining a value from the environment. The -`env` selector references the environment variables in environment at the time of -the build. You reference environment variables just like it was a tuple. Attempting -to reference a variable that doesn't exist will be a compile error. +There is a special selector in ucg for obtaining a value from the environment. +The `env` selector references the environment variables in environment at the +time of the build. You reference an environment variable just like it was in a +tuple. Attempting to reference a variable that doesn't exist will be a compile +error. ``` let env_name = env.DEPLOY_ENV; @@ -52,7 +56,7 @@ let env_name = env.DEPLOY_ENV; 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. ### Numeric Operators @@ -78,11 +82,11 @@ version both sides must be the same type, either string or list. ### Comparison Operators -UCG supports the comparison operators `==`, `!=`, `>=`, `<=`, `<`, and `>`. The all -expect both sides to be of the same type. +UCG supports the comparison operators `==`, `!=`, `>=`, `<=`, `<`, and `>`. +They all expect both sides to be of the same type. -The `>`, `<`, `>=`, and `>=` operators are only supported on numeric types (i.e. int, -and float). +The `>`, `<`, `>=`, and `>=` operators are only supported on numeric types +(i.e. int, and float). ``` 1 > 2; // result is false @@ -91,8 +95,8 @@ and float). (1+2) == 3; ``` -The equality operators `==` and `!=` are supported for all types and will perform deep -equal comparisons on complex types. +The equality operators `==` and `!=` are supported for all types and will +perform deep equal comparisons on complex types. ``` let tpl1 = { @@ -112,27 +116,28 @@ let tpl2 = { tpl1 == tpl3; // returns false ``` -Because tuples are an ordered set both tuples in a comparison must have their fields in -the same order to compare as equal. +Because tuples are an ordered set both tuples in a comparison must have their +fields in the same order to compare as equal. #### Operator Precedence -UCG binary operators follow the typical operator precedence for math. `*` and `/` are -higher precendence than `+` and `-` which are higher precedence than any of the -comparison operators. +UCG binary operators follow the typical operator precedence for math. `*` and +`/` are higher precendence than `+` and `-` which are higher precedence than +any of the comparison operators. Copy Expressions ---------------- -UCG expressions have a special copy expression for tuples. These faciliate a form of -data reuse as well as a way to get a modified version of a tuple. Copy expressions -start with a selector referencing a tuple followed by braces `{}` with `name = value` -pairs separated by commas. Trailing commas are allowed. +UCG expressions have a special copy expression for tuples. These faciliate a +form of data reuse as well as a way to get a modified version of a tuple. Copy +expressions start with a selector referencing a tuple followed by braces `{}` +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 -you are changing the value of a base field in the copy then the new value must be of -the same type as the base field's value. This allows you to define a base "type" of -sorts and ensure that any modified fields stay the same. +Copied expressions can change base fields in the copied tuple or add new +fields. If you are changing the value of a base field in the copy then the new +value must be of the same type as the base field's value. This allows you to +define a base "type" of sorts and ensure that any modified fields stay the +same. ``` 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 -tuple in a copy called `self`. `self` can only be used in the body of the copy. +There is a special selector that can be used in a copy expression to refer to +the base tuple in a copy called `self`. `self` can only be used in the body of +the copy. ``` let nestedtpl = { @@ -182,11 +188,11 @@ let copiedtpl = nestedtpl{ Format Expressions ---------- -UCG has a format expression that has a limited form of string templating. A format -expression starts with a string followed by the `%` operator and a list of arguments -in parentheses separated by commas. Trailing commas are allowed. The format string -should have `@` in each location where a value should be placed. Any primitive value -can be used as an argument. +UCG has a format expression that has a limited form of string templating. A +format expression starts with a string followed by the `%` operator and a list +of arguments in parentheses separated by commas. Trailing commas are allowed. +The format string should have `@` characters in each location where a value +should be placed. Any primitive value can be used as an argument. ``` "https://@:@/" % (host, port) @@ -195,11 +201,11 @@ can be used as an argument. Conditionals ---------- -UCG supports a limited conditional expression called a select. A select expression -starts with the `select` keyword and is followed by a an expression resolving to a -string naming the field to select, an expression resolving to the default value, and -finally a tuple literal to select the field from. If the field selected is not in the -tuple then the default value will be used. +UCG supports a limited conditional expression called a select. A select +expression starts with the `select` keyword and is followed by a an expression +resolving to a string naming the field to select, an expression resolving to +the default value, and finally a tuple literal to select the field from. If the +field selected is not in the tuple then the default value will be used. ``` let want = "baz"; @@ -220,13 +226,13 @@ select "quack", "quux", { Macros ----- -Macros look like functions but they are resolved at compile time and configurations -don't execute so they never appear in output. Macros do not close over their -environment so they can only reference values defined in their arguments. They can't -refer to bindings or other macros defined elsewhere. They are useful for constructing -tuples of a certain shape or otherwise promoting data reuse. You define a macro with -the `macro` keyword followed by the arguments in parentheses, a `=>`, and then a tuple -literal. +Macros look like functions but they are resolved at compile time and +configurations don't execute so they never appear in output. Macros do not +close over their environment so they can only reference values defined in their +arguments. They can't refer to bindings or other macros defined elsewhere. They +are useful for constructing tuples of a certain shape or otherwise promoting +data reuse. You define a macro with the `macro` keyword followed by the +arguments in parentheses, a `=>`, and then a tuple literal. ``` let mymacro = macro (arg1, arg2) => { diff --git a/docsite/site/content/reference/statements.md b/docsite/site/content/reference/statements.md index fb3be3e..6dfa2bb 100644 --- a/docsite/site/content/reference/statements.md +++ b/docsite/site/content/reference/statements.md @@ -18,8 +18,7 @@ followed by a semicolon. ``` 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 -useful. +be considered a noop. Named Value Statements -------- @@ -27,7 +26,7 @@ Named Value Statements ### Let statements 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 modified. @@ -38,7 +37,7 @@ let name = "foo"; ### Import Statement 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, the keyword `as`, and a name for the imported values. @@ -50,7 +49,8 @@ let mysqlconf = dbconfigs.mysql; 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 @@ -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 in the block +of ucg statements delimited by `|` characters. The final statement in the block 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 -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 (e.g. json, exec) and the artifact -file will take the same name as the ucg file with the extension replaced by the -defined extension for that converter. +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 +converter. 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 +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: Converters \ No newline at end of file diff --git a/docsite/site/content/reference/types.md b/docsite/site/content/reference/types.md index 676a315..feaf2ee 100644 --- a/docsite/site/content/reference/types.md +++ b/docsite/site/content/reference/types.md @@ -29,7 +29,7 @@ An Integer is any 64 bit integer number. ### 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. ``` @@ -40,10 +40,11 @@ including a decimal point. Any number with a decimal point is a float. ### 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 an escaped \"string\""; ``` ### NULL or the Empty type