1 # Command Line Parsing
   2 
   3 Tomo supports automatic command line argument parsing for programs.
   4 Here's a simple example:
   5 
   6 ```tomo
   7 # greet.tm
   8 func main(name:Text, be_excited|E:Bool=no)
   9     if be_excited
  10         say("Hello $name!!!")
  11     else
  12         say("Hi $name.")
  13 ```
  14 
  15 This program will automatically support command line argument parsing
  16 for the arguments to `main()`:
  17 
  18 ```bash
  19 $ tomo -e greet.tm
  20 Compiled executable: greet
  21 
  22 $ ./greet
  23 greet: Required argument 'name' was not provided!
  24 Usage: greet [--help] <name> [--be-excited|-E|--no-be-exited]
  25 
  26 $ ./greet --help
  27 Usage: greet [--help] <name> [--be-excited|-E|--no-be-excited]
  28 
  29 $ ./greet "Zaphod"
  30 Hi Zaphod. 
  31 
  32 $ ./greet "Zaphod" --be-excited
  33 Hello Zaphod!!!
  34 
  35 $ ./greet "Zaphod" -E
  36 Hello Zaphod!!!
  37 
  38 $ ./greet --no-be-excited --name="Zaphod"
  39 Hi Zaphod.
  40 
  41 $ ./greet --not-a-real-argument "Bob"
  42 greet: Unrecognized argument: --not-a-real-argument
  43 Usage: greet [--help] <name> [--be-excited|-E|--no-be-excited]
  44 ```
  45 
  46 Underscores in argument names are converted to dashes when parsing command line
  47 arguments.
  48 
  49 ## Running Programs Directly
  50 
  51 If you want to run a program directly (instead of compiling to an executable
  52 with `tomo -e`), you can run the program with `tomo program.tm -- [program
  53 arguments...]`. The `--` is required to separate the arguments passed to the
  54 Tomo compiler from those being passed to your program. For example, `tomo
  55 greet.tm -- --help` will pass the argument `--help` to your program, whereas
  56 `tomo greet.tm --help` will pass `--help` to `tomo`.
  57 
  58 ## Positional vs Default Arguments
  59 
  60 Any arguments with a default value must be specified with a `--flag=value` or
  61 `--flag value`. Arguments without a default value can be specified either by
  62 explicit `--flag` or positionally. If an argument does not have a default value
  63 it is required and the program will report a usage error if it is missing.
  64 
  65 ## Supported Argument Types
  66 
  67 Tomo automatically supports several argument types out of the box, but if there
  68 is a type that isn't supported, you can always fall back to accepting a `Text`
  69 argument and parsing it yourself.
  70 
  71 ### Text
  72 
  73 Text arguments are the simplest: the input arguments are taken verbatim.
  74 
  75 ### Bool
  76 
  77 For a boolean argument, `foo`, the argument can be passed in several ways:
  78 
  79 - `--foo` or `--no-foo` provide the argument as `yes`/`no` respectively
  80 - `--foo=yes`/`--foo=on`/`--foo=true`/`--foo=1` all parse as `yes` (case insensitive)
  81 - `--foo=no`/`--foo=off`/`--foo=false`/`--foo=0` all parse as `no` (case insensitive)
  82 - Any other values will report a usage error
  83 
  84 ### Integers and Numbers
  85 
  86 Integer and number values can be passed and parsed automatically. Any failures
  87 to parse will cause a usage error. Integers support decimal (`123`),
  88 hexadecimal (`0xFF`), and octal values (`0o644`). Nums support regular (`123`
  89 or `1.23`) or scientific notation (`1e99`).
  90 
  91 For fixed-size integers (`Int64`, `Int32`, `Int16`, `Int8`), arguments that
  92 exceed the representable range for those values are considered usage errors.
  93 
  94 ### Structs
  95 
  96 For structs, values can be passed using positional arguments for each struct
  97 field.
  98 
  99 ```
 100 # foo.tm
 101 struct Pair(x,y:Int)
 102 
 103 func main(pair:Pair)
 104     >> pair
 105 
 106 
 107 $ tomo foo.tm -- --pair 1 2
 108 Pair(x=1, y=2)
 109 ```
 110 
 111 Tomo does not currently support omitting fields with default values or passing
 112 individual struct fields by named flag.
 113 
 114 ### Enums
 115 
 116 For enums, values can be passed using the enum's tag name and each of its
 117 fields positionally (the same as for structs). Parsing is case-sensitive:
 118 
 119 ```
 120 # foo.tm
 121 enum Foo(Nothing, AnInteger(i:Int), TwoThings(i:Int, text:Text))
 122 func main(foo:Foo)
 123     >> foo
 124 
 125 $ tomo foo.tm -- Nothing
 126 Nothing
 127 
 128 $ tomo foo.tm -- AnInteger 123
 129 AnInteger(123)
 130 
 131 $ tomo foo.tm -- TwoThings 123 hello
 132 TwoThings(i=123, text="hello")
 133 ```
 134 
 135 Like structs, enums do not currently support passing fields as flags or
 136 omitting fields with default values.
 137 
 138 ### Lists of Text
 139 
 140 Currently, Tomo supports accepting arguments that take a list of text.
 141 List-of-text arguments can be passed like this:
 142 
 143 ```tomo
 144 # many-texts.tm
 145 func main(args:[Text])
 146     >> args
 147 ```
 148 
 149 ```bash
 150 $ tomo many-texts.tm
 151 >> [] : [Text]
 152 
 153 $ tomo many-texts.tm one two three
 154 >> ["one", "two", "three"] : [Text]
 155 
 156 $ tomo many-texts.tm --args=one,two,three
 157 >> ["one", "two", "three"] : [Text]
 158 
 159 $ tomo many-texts.tm -- one --not-a-flag 'a space'
 160 >> ["one", "--not-a-flag", "a space"] : [Text]
 161 ```
 162 
 163 ## Aliases and Flag Arguments
 164 
 165 Each argument may optionally have an alias of the form `name|alias`. This allows
 166 you to specify a long-form argument and a single-letter flag like `verbose|v =
 167 no`. Single letter flags (whether as an alias or as a main flag name) have
 168 slightly different command line parsing rules:
 169 
 170 - Single letter flags use only a single dash: `-v` vs `--verbose`
 171 - Single letter flags can coalesce with other single letter flags: `-abc` is the
 172 same as `-a -b -c`
 173 
 174 When single letter flags coalesce together, the first flags in the cluster must
 175 be boolean values, while the last one is allowed to be any type. This lets you
 176 specify several flags at once while still providing arguments:
 177 
 178 ```tomo
 179 func main(output|o:Path? = none, verbose|v:Bool = no)
 180     ...
 181 ```
 182 ```bash
 183 $ tomo -e program.tm && ./program -vo outfile.txt`
 184 ```
 185 
 186 ## Help and Manpages
 187 
 188 When your program is generated, it will also come with a `--help` flag (unless
 189 you have one defined) with automatically generated usage information. If you
 190 add comments in front of your main function arguments, they will appear in the
 191 `--help` output. Additionally, when your program is compiled, Tomo will also
 192 build a Manpage for your program in `.build/yourprogram.1`, which will get
 193 installed if you install your program.
 194 
 195 ```tomo
 196 func main(
 197     # Whether or not to frob your gropnoggles
 198     frob: Bool = no
 199 )
 200     pass
 201 ```
 202 
 203 ```bash
 204 $ tomo -e myprogram.tm
 205 $ ./myprogram --help
 206 # Usage: ./myprogram [--help] [--frob|--no-frob]
 207 #
 208 #  --frob|--no-frob Whether or not to frob your gropnoggles (default:no)
 209 #
 210 ```
 211 
 212 ```bash
 213 $ man .build/myprogram.1
 214 ```
 215 
 216 ```
 217 MYPROGRAM(1)
 218 
 219 NAME
 220        myprogram - a Tomo program
 221 
 222 OPTIONS
 223        --frob | --no-frob
 224               Whether or not to frob your gropnoggles
 225 ```
 226 
 227 ## Metadata
 228 
 229 You can specify metadata for a program, which is used for CLI messages like
 230 `--help`, as well as manpage documentation. Metadata can be specified as either
 231 a text literal (no interpolation) or as a file path literal.
 232 
 233 ```
 234 USAGE: "--foo <n>"
 235 HELP: "
 236     This is some custom help text.
 237     You can use these flags:
 238 
 239     --foo <n>  The foo parameter
 240     --help     Show this message
 241 "
 242 MANPAGE_DESCRIPTION: (./description.roff)
 243 ```
 244 
 245 Supported metadata:
 246 
 247 - `EXECUTABLE`: the name of the executable to compile. If not provided, the name
 248   will be the name of the Tomo source file without the ".tm" extension.
 249 
 250 - `USAGE`: the short form usage shown in CLI parsing errors and help pages. This
 251   should be a single line without the name of the program, so `USAGE: "--foo"`
 252   would translate to the error message `Usage: myprogram --foo`. If this is not
 253   present, it will be generated automatically.
 254 
 255 - `HELP`: The help message displayed when the `--help` flag is used or when there
 256   is an argument parsing error. This should be a description of the program with
 257   a multi-line documentation of commonly used flags.
 258 
 259 - `MANPAGE`: the full manpage (overrules the options below).
 260 
 261 - `MANPAGE_SYNOPSYS`: the synopsis section of the manpage (inserted literally).
 262 
 263 - `MANPAGE_DESCRIPTION`: the description section of the manpage (inserted literally).