Quick Setup

This section is a short description of setting up commands and parameters for Litr. The configuration format is TOML. The file name is either litr.toml or .litr.toml.

Commands

Short form

[commands]
install = "some install script"

Long form

A description is used on calling litr --help.

[commands.install]
script = "some install script"
description = "A nice description here"
# Multiline example that will shop up running `litr install --help`
example = """
...
"""

Child commands

Child commands are executed in order of definition. The first command to execute is the parent command. To narrow down execution a dir property can be specific (string or array of strings) to run commands only on certain directories. Commands are executed for every folder.

[commands.install]
script = "jest"

[commands.install.cpp]
script = "some install script"
dir = [ "src/cpp1", "src/cpp2" ]

[commands.install.java]
script = "some install script"
dir = "src/java"
output = "silent"

Given some example execution, the first will run all three commands in order, meaning install > cpp > java, as defined in the configuration file:

litr install

The command will only execute the one child command:

litr install cpp

And this will execute two child commands, order as defined in the command (java > cpp), without executing the parent command:

litr install java,cpp

Parameters

Parameters are for passing values to a command. Here are some rules for parameters:

• Parameters are global, meaning they can be used in any command, there is no restriction.
• Parameters are unique, so every name can only appear once.
• If a parameter is used inside a command, it will appear inside the help description for that command.
• A parameter without a default will always be required for commands where its is used in.

Short form

The short form defines a name and a description for the help text.

[params]
target = "Define a build target, nice description"

Long form

[params.target]
default = "debug"
description = "Define a build target, nice description"
shortcut = "t"
type = "string"

Note: The option type is not finalised (#8).

Parameter functions

Note: Parameter functions are a work in progress and may change in the future.

There are a couple of functions that can be used to edit parameter values before executing a command. The following functions are defined:

• pascal_case - Transform the value to PascalCase
• camel_case - Transform the value to camelCase
• snake_case - Transform the value to snake_case
• kebab_case - Transform the value to kebab-case

Restricted parameters

The following parameter names and shortcuts are restricted and will throw an error message:

• help, h - This parameter and the shortcut is restricted for the built-in help text generation.

Example

To drive this by example, this repository itself is taken to show how Litr can be utilised.

# litr.toml
[commands]
install = "git clone --recurse-submodules -j8 git@github.com:krieselreihe/litr.git"
update = "git pull && git submodule update --init"
build = [
  # Not sure about this `pascal_case` function here, yet.
  "cmake -GNinja -DDEBUG=1 -DCMAKE_BUILD_TYPE=${pascal_case(target)} --build build/${target}",
  "ninja -C build/${target}"
]
run = "./build/${target}/litr/client/Client"

[params.target]
shortcut = "t"
description = "Define the build target"
type = ["debug", "release"]
default = "debug"

Usage:

# Set the target, build and then run the application
litr --target=release build, run