ucg/docsite/site/content/reference/converters.md

+++ title = "UCG Converters" weight = 5 sort_by = "weight" in_search_index = true +++ UCG has several formats it can convert a value into. Each one has various limits and restrictions on the values that can be converted to that format.

JSON and YAML

All UCG values can be converted into JSON or YAML. Integers and Floats are turned into Their equivalent number types. Tuples are turned into dicts. Lists are turned into arrays. Strings are turned into strings.

The NULL or empty type is turned into null in JSON or YAML.

TOML

TOML is very similar to the JSON and YAML formats. TOML has no notion of null though so NULL types result in a compile error when converting to TOML.

Command Line Flags

UCG is able to generate command line flags from ucg values following some translation rules for each type.

• Empty values are not emitted.
• Boolean values are translated to "true" and "false" repsectively.
• Integers and Floats are rendered as numbers.
• Tuples are rendered as --field value pairs for each 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.
  • For fields that are just one character in length use a single -. Use double dashes for fields of longer than one character.

Example

let flags = {
    port = 8080,
    listen = "0.0.0.0",
    verbose = NULL,
    dir = [
        "some/dir",
        "some/other/dir",
    ],
    log = {
        debug = true,
        format = "json",
    },
}

Generates the following flags in a file with the .txt extension.

-port 8080 --listen '0.0.0.0' --verbose --dir 'some/dir' --dir 'some/other/dir' --log.debug true --log.format 'json'

Environment Variables

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.
• Lists are not output.
• Tuples are output as a FIELD=value for each field with strings surrounded by double quotes.
  • Nested Tuples are not output.

let vars = {
    USER = "me",
    HOSTNAME = "localhost",
    TWO = 2,
    VERBOSE = true,
};

Generates the following in a file with a .env extension.

USER='me'
HOSTNAME='localhost'
TWO=2
VERBOSE=true

Exec Script

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.

The command field is the path to the application the script will be launching. It is expected to be a string. There must only be one command field in the tuple.

The args field is a list of command line arguments. The elements of the list can be strings or tuples. There must only be one args field in the tuple.

The env field is a tuple representing the environment variables that will be set for the application. there must only be one env field in the tuple.

Example

let common_flags = {
    log-level = "debug",
    maxMem = "2048M",
};

let script = {
    env = {
        apikey = "foo-key-and-stuff",
    },
    command = "my-app",
    args = [
        common_flags,
        "serve", "--port", "8080",
    ],
};

out exec script;

The script tuple above will generate the following bash script:

#!/usr/bin/env bash
# Turn on unofficial Bash-Strict-Mode
set -euo pipefail

VERBOSE_LOG="true"

exec my-app --log-level debug --maxMem 2048M serve --port 8080

The items in the args should be either strings or tuples. The tuples are turned into flags using the builtin flag converter.