Expand the examples section of the README.

This commit is contained in:
Jeremy Wall 2017-07-29 13:20:57 -05:00
parent c00306337b
commit 42b5b8f656

View File

@ -1,6 +1,6 @@
# Universal Configuration Generator. - A working title.
# Universal Configuration Grammar - Working Title.
This is an experiment in configuration management. The approach is not
This is an experiment in configuration management. The approach is **not**
to create a "parsable" config file format. We have plenty of
those. Instead we try to specify a grammar for describing
configuration values that can then target various configuration
@ -10,12 +10,13 @@ In theory this could support anything from command line flags to json
to yaml or toml or even xml.
The goal is to allow a global shared configuration repository that can
be version controlled, enforce some typesafety, and output
be version controlled, enforce _some_ typesafety, and output
configuration for any application regardless of that applications
preferred format.
## Examples
### Bindings and Tuples.
Let statements introduce a new name in a ucg file. Most configurations
will be a tuple like below. Tuples are delimited by braces and have a list
of named fields in them.
@ -26,6 +27,10 @@ of named fields in them.
database = "place-holder",
};
Tuple fields have no ordering guarantees.
### Copying and modifying Tuples.
You can use a previously defined tuple as the basis for a new tuple. Doing
this will make a copy of the source tuple and allow you to add new fields
or override an already existing field.
@ -35,6 +40,8 @@ or override an already existing field.
timeout = 30,
};
### Limited Types safety
Types are inferred for tuple fields. We enforce type consistency when
overriding a field in a base tuple. The port field below expects a
number not a string so you will get a TypeFail error.
@ -43,3 +50,34 @@ number not a string so you will get a TypeFail error.
let bad_mysql_conn = mysql_conn_base{
port = "3307",
}
### Conditional Values
The grammar has limited support for conditionals using the select expression.
let my_sql_app_conn = mysql_conn_base{
port = select prod, 33007 {
prod = 3307,
qa = 3308,
}
};
The first argument to the select call is the key you wish to select. The second
argument is a default value to use if the key doesn't exist. The third is a set
of fields to choose from.
### Macros
We also support a limited macro facility with the macro expression.
let conn_string_macro = macro (host, port) {
conn_str = "mysql://" + host + ":" + port,
}
let web_conn = conn_string_macro ("proddb", "3307");
let conn_string = web_conn.conn_str;
Macro's always output a tuple whose fields are evaluated at the location they
are called from. You can acccess the generated fields from the resulting tuple
like usual.