Getting Started



    You can install UCG using Rust's Cargo package manager.

    cargo install ucg


    You can also install from source yourself. First ensure that you have the latest version of Rust installed. You can find install instructions for Rust here. Then you can get the source from github and use cargo to build.

    # Get the source code from github
    git clone
    cd ucg
    # optionally checkout the current version
    git checkout v0.5.1
    # use cargo to build and install
    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 extension.

    let hostname = "";
    let mysql_host = "localhost";
    let mysql_port = 3306;
    let config = {
        // This uses a format string to put the hostname into
        // the baseUrl.
        baseUrl = "http://@" % (hostname),
        db = {
            host = mysql_host,
            port = myssql_port,
    // Generate a yaml file from that config.
    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.

    To generate a yaml file from the above run the UCG build command.

    ucg build sample.ucg
    cat sample.yaml

    UCG will generate the yaml file with the same name as the file containing the out statement.

    The UCG repl

    UCG has a built in repl where you can explore the language interactively. It supports the full set of UCG expressions and statements. As well as some repl directives that are not part of the UCG language proper.

    ucg repl
    Welcome to the UCG repl. Ctrl-D to exit
    Type '#help' for help.
    1> let foo = "bar";
    1> out json {foo="bar"};
            foo = "bar",

    The UCG command line

    UCG has builtin help on the command line.

    $> ucg help
    Universal Configuration Grammar compiler.
        ucg [FLAGS] [SUBCOMMAND]
        -h, --help         Prints help information
            --no-strict    Turn off strict checking.
        -V, --version      Prints version information
        build         Build a list of ucg files.
        converters    list the available converters
        env           Describe the environment variables ucg uses.
        eval          Evaluate an expression with an optional ucg file as context.
        help          Prints this message or the help of the given subcommand(s)
        importers     list the available importers for includes
        test          Check a list of ucg files for errors and run test assertions.

    You can get more information about the options for each command by running ucg help $command

    Next: Reference