Command Line Parsing

Tomo supports automatic command line argument parsing for programs. Here’s a simple example:

# greet.tm
func main(name:Text, be_excited|E:Bool=no)
    if be_excited
        say("Hello $name!!!")
    else
        say("Hi $name.")

This program will automatically support command line argument parsing for the arguments to main():

$ tomo -e greet.tm
Compiled executable: greet

$ ./greet
greet: Required argument 'name' was not provided!
Usage: greet [--help] <name> [--be-excited|-E|--no-be-exited]

$ ./greet --help
Usage: greet [--help] <name> [--be-excited|-E|--no-be-excited]

$ ./greet "Zaphod"
Hi Zaphod. 

$ ./greet "Zaphod" --be-excited
Hello Zaphod!!!

$ ./greet "Zaphod" -E
Hello Zaphod!!!

$ ./greet --no-be-excited --name="Zaphod"
Hi Zaphod.

$ ./greet --not-a-real-argument "Bob"
greet: Unrecognized argument: --not-a-real-argument
Usage: greet [--help] <name> [--be-excited|-E|--no-be-excited]

Underscores in argument names are converted to dashes when parsing command line arguments.

Running Programs Directly

If you want to run a program directly (instead of compiling to an executable with tomo -e), you can run the program with tomo program.tm -- [program arguments...]. The -- is required to separate the arguments passed to the Tomo compiler from those being passed to your program. For example, tomo greet.tm -- --help will pass the argument --help to your program, whereas tomo greet.tm --help will pass --help to tomo.

Positional vs Default Arguments

Any arguments with a default value must be specified with a --flag=value or --flag value. Arguments without a default value can be specified either by explicit --flag or positionally. If an argument does not have a default value it is required and the program will report a usage error if it is missing.

Supported Argument Types

Tomo automatically supports several argument types out of the box, but if there is a type that isn’t supported, you can always fall back to accepting a Text argument and parsing it yourself.

Text

Text arguments are the simplest: the input arguments are taken verbatim.

Bool

For a boolean argument, foo, the argument can be passed in several ways:

Integers and Numbers

Integer and number values can be passed and parsed automatically. Any failures to parse will cause a usage error. Integers support decimal (123), hexadecimal (0xFF), and octal values (0o644). Nums support regular (123 or 1.23) or scientific notation (1e99).

For fixed-size integers (Int64, Int32, Int16, Int8), arguments that exceed the representable range for those values are considered usage errors.

Structs

For structs, values can be passed using positional arguments for each struct field.

# foo.tm
struct Pair(x,y:Int)

func main(pair:Pair)
    >> pair


$ tomo foo.tm -- --pair 1 2
Pair(x=1, y=2)

Tomo does not currently support omitting fields with default values or passing individual struct fields by named flag.

Enums

For enums, values can be passed using the enum’s tag name and each of its fields positionally (the same as for structs). Parsing is case-sensitive:

# foo.tm
enum Foo(Nothing, AnInteger(i:Int), TwoThings(i:Int, text:Text))
func main(foo:Foo)
    >> foo

$ tomo foo.tm -- Nothing
Nothing

$ tomo foo.tm -- AnInteger 123
AnInteger(123)

$ tomo foo.tm -- TwoThings 123 hello
TwoThings(i=123, text="hello")

Like structs, enums do not currently support passing fields as flags or omitting fields with default values.

Lists of Text

Currently, Tomo supports accepting arguments that take a list of text. List-of-text arguments can be passed like this:

# many-texts.tm
func main(args:[Text])
    >> args
$ tomo many-texts.tm
>> [] : [Text]

$ tomo many-texts.tm one two three
>> ["one", "two", "three"] : [Text]

$ tomo many-texts.tm --args=one,two,three
>> ["one", "two", "three"] : [Text]

$ tomo many-texts.tm -- one --not-a-flag 'a space'
>> ["one", "--not-a-flag", "a space"] : [Text]

Aliases and Flag Arguments

Each argument may optionally have an alias of the form name|alias. This allows you to specify a long-form argument and a single-letter flag like verbose|v = no. Single letter flags (whether as an alias or as a main flag name) have slightly different command line parsing rules:

When single letter flags coalesce together, the first flags in the cluster must be boolean values, while the last one is allowed to be any type. This lets you specify several flags at once while still providing arguments:

func main(output|o:Path? = none, verbose|v:Bool = no)
    ...
$ tomo -e program.tm && ./program -vo outfile.txt`

Help and Manpages

When your program is generated, it will also come with a --help flag (unless you have one defined) with automatically generated usage information. If you add comments in front of your main function arguments, they will appear in the --help output. Additionally, when your program is compiled, Tomo will also build a Manpage for your program in .build/yourprogram.1, which will get installed if you install your program.

func main(
    # Whether or not to frob your gropnoggles
    frob: Bool = no
)
    pass
$ tomo -e myprogram.tm
$ ./myprogram --help
# Usage: ./myprogram [--help] [--frob|--no-frob]
#
#  --frob|--no-frob Whether or not to frob your gropnoggles (default:no)
#
$ man .build/myprogram.1
MYPROGRAM(1)

NAME
       myprogram - a Tomo program

OPTIONS
       --frob | --no-frob
              Whether or not to frob your gropnoggles

Metadata

You can specify metadata for a program, which is used for CLI messages like --help, as well as manpage documentation. Metadata can be specified as either a text literal (no interpolation) or as a file path literal.

USAGE: "--foo <n>"
HELP: "
    This is some custom help text.
    You can use these flags:

    --foo <n>  The foo parameter
    --help     Show this message
"
MANPAGE_DESCRIPTION: (./description.roff)

Supported metadata: