&| What          | '''autoopts''' |&
&| Where         | https://gitlab.com/dbohdan/autoopts |&
&| Prerequisites | Tcl 8.5-8.6 |&
&| Updated       | 2017-08 |&
&| License       | MIT |&

** Description **

Autoopts is a Tcl module that automates processing of command line arguments. It was inspired by [Perl 6], which does a similar thing [https://perl6advent.wordpress.com/2010/12/02/day-2-interacting-with-the-command-line-with-main-subs/%|%quite elegantly]. In short, this module automatically generates a command line interface for your Tcl program based on the arguments that its main proc takes. It maps the proc's arguments whose names are prefixed with dashes (e.g., `-a` or `--arg`) to named command line arguments (options) and other proc arguments to positional command line arguments. E.g., `proc main {filename -a {--factor 2x}} ...` will result in `usage: yourscript.tcl -a A [--factor 2x] [--] filename`. Proc arguments with default values are mapped to optional command line arguments, named or positional; other arguments are considered mandatory. If some of the mandatory arguments are missing or unrecognized extra command line arguments are given, autoopts will output an informative error message, print an automatically generated usage note, and exit. It will also output a usage message if the user gives the command line argument `-h` or `--help`.

To use autoopts, source it or `package require` it as a [module] and call `::autoopts::go ?description? ?your-main-proc?`

Download: `curl https://gitlab.com/dbohdan/autoopts/raw/master/autoopts.tcl > autoopts-0.3.0.tm`

** Use example **

*** Code ***

======
#! /usr/bin/env tclsh
proc main {{input -} {--indent 4}} {
    set ch [expr {$input eq "-" ? "stdin" : [open $input]}]
    while {[gets $ch line] > 0} {
        puts [string repeat { } ${--indent}]$line
    }
}

source autoopts.tcl
::autoopts::go {indenter pro v1.0.1 -- indents input with spaces}
======

*** Shell transcript ***

======
$ ./autoopts-example.tcl --help
indenter pro v1.0.1 - indents input with spaces
usage: autoopts-example.tcl [--indent 4] [--] [input]

$ ./autoopts-example.tcl --wrong
unknown option: --wrong
usage: autoopts-example.tcl [--indent 4] [--] [input]

$ ./autoopts-example.tcl file1 file2 file3
too many positional arguments
usage: autoopts-example.tcl [--indent 4] [--] [input]

$ ./autoopts-example.tcl --indent
missing value for option --indent
usage: autoopts-example.tcl [--indent 4] [--] [input]

$ ./autoopts-example.tcl ./autoopts-example.tcl --indent 11
           #! /usr/bin/env tclsh
           proc main {{input -} {--indent 4}} {
               set ch [expr {$input eq "-" ? "stdin" : [open $input]}]
               while {[gets $ch line] > 0} {
                   puts [string repeat { } ${--indent}]$line
               }
           }
======


** Code **

See https://gitlab.com/dbohdan/autoopts/blob/master/autoopts.tcl.


** Discussion **

'''[arjen] - 2017-08-15 14:01:13'''

Just a few remarks:
   * Shouldn't invoke use [uplevel] to make sure that the procedure is called in the right namespace and that variables that are referred by name are correctly [upvar]'ed?
   * The test cases should include an example where the procedure lives in a different namespace.
   * It is a common convention to capitalise the names of private procedures. An easy way to see what you may and may not use.

[dbohdan] 2017-08-15: Thanks for the suggestions! I've implemented 1-2 (with an `uplevel 1` in both `::autoopts::go` and `::autoopts::invoke`). As for 3, consider the whole API unstable for now. I do not expect to change it in a major way, especially not `::autoopts::go`, but I can't promise I won't. When it stabilizes, I'll probably separate the public and the private procedures like in https://github.com/dbohdan/jimhttp/blob/master/json.tcl.

<<categories>>Argument Processing | Package