cco

TL;DR: Transforms HCL to json or yaml.

Usage

• cco e[valuate] <file...> to evaluate HCL files
• cco import <file> to convert a json or yaml file to HCL

Evaluation

cco evaluate [[<identifier>=]<file>...] loads each file into a global context. If an identifier is provided, the file is loaded into a variable under that name instead. cco resolves all expressions and prints the global context as json or yaml to stdout.

Alternatively, cco evaluate [-e/--expression <hcl-expression>] [<files...>] can be used to evaluate a single hcl expression.

Output

• stdout: hcl/yaml/json output
• stderr: log messages

Exit Codes

• == 0: success
• != 0: failure
  • 1: general error
  • 2: invalid invocation / help displayed
  • >=3: reserved/unused

Environment Variables

• CCO_LOG: configure logging. see tracing_subscriber's env_filter directive for value format.

Functions

The following functions are available for use in HCL expressions. The subject is always the first argument. If the argument is denoted as ..., then multiple individual arguments or a single list are accepted.

Currently, functions are namespaced by type. Maybe this is not a good idea but it keeps the unnamespaced functions open for future use. Subject to change...

String Functions (str)

• str::empty(string) → bool: Returns true if string is empty
• str::len(string) → number: Returns the length of the string
• str::trim(string) → string: Removes whitespace from both ends
• str::trim_start(string) → string: Removes whitespace from the start
• str::trim_end(string) → string: Removes whitespace from the end
• str::contains(subject, search) → bool: Returns true if subject contains search
• str::starts_with(subject, prefix) → bool: Returns true if subject starts with prefix
• str::ends_with(subject, suffix) → bool: Returns true if subject ends with suffix
• str::to_upper(string) → string: Converts string to uppercase
• str::to_lower(string) → string: Converts string to lowercase
• str::split(string, delimiter) → list: Splits string by delimiter into a list
• str::join(..., separator) → string: Joins strings with separator (accepts list or multiple arguments)
• str::concat(...) → string: Concatenates strings (accepts list or multiple arguments)
• str::replace(string, old, new) → string: Replaces all occurrences of old with new
• str::reverse(string) → string: Reverses the string

Path Functions (path)

• path::basename(path) or path::file_name(path) → string: Returns the file name
• path::file_stem(path) → string: Returns the file name without extension
• path::file_ext(path) → string: Returns the file extension
• path::dirname(path) → string: Returns the parent directory
• path::join(...) → string: Joins path segments (accepts list or multiple arguments)

List Functions (list)

• list::empty(list) → bool: Returns true if list is empty
• list::len(list) → number: Returns the length of the list
• list::all(...) → bool: Returns true if all booleans are true (accepts list or multiple arguments)
• list::any(...) → bool: Returns true if any boolean is true (accepts list or multiple arguments)
• list::first(list) → any: Returns the first element
• list::last(list) → any: Returns the last element
• list::reverse(list) → list: Returns a reversed copy of the list
• list::contains(list, value) → bool: Returns true if list contains value

Map Functions (map)

• map::empty(map) → bool: Returns true if map is empty
• map::len(map) → number: Returns the number of keys in the map
• map::keys(map) → list: Returns a list of all keys
• map::values(map) → list: Returns a list of all values
• map::has_key(map, key) → bool: Returns true if map contains key
• map::merge(...) → map: Merges maps (accepts list or multiple arguments)

Math Functions (math)

• int::abs(number) → int: Returns the absolute value
• int::sum(...) → int: Returns the sum of all values
• int::min(...) → int: Returns the smallest number
• int::max(...) → int: Returns the largest number
• int::clamp(number, min, max) → int: Returns a value between min and max, or min/max when the value is outside of the range

Time functions (time)

• time::minutes(number) → int: Returns the number of seconds in number of hours (60 seconds)
• time::hours(number) → int: Returns the number of seconds in number of hours (60 minutes)
• time::days(number) → int: Returns the number of seconds in number of days (24 hours)
• time::weeks(number) → int: Returns the number of seconds in number of weeks (7 days)

Limitations, known issues and future work

• attribute only splat and full splat expressions are implemented but behave the same
• functions are inconveniently namespaced to keep the unnamespaced function names open for user defined functions
• no support for strip in interpolation (templates)
• cco's custom evaluation may behave different than what's expected from other software