[[toc:]] == Description This is the command-line parser from Mowedline, now an independent project. It is a simple imperative-style command-line parser, and the "-a" suffix on its name is there to suggest that this module represents only one of many possible imperative-style command-line frameworks. An "imperative" command-line style is one in which the command-line arguments represent procedures and parameters, to be called in left-to-right order, a kind of DSL, or mini-language. Contrast this style with other command-line styles where the options represent simple flags, and order is not significant. In an imperative-style command-line, the options represent ''actions'' to take in the order given. There are times though, when strict left-to-right order is not desired, and to support these situations, imperative-command-line-a supports ''command groups''. If you want to take certain options out of the overall ordering, you use groups. When the command-line is processed, commands from different command groups are first parsed into separate lists. Then the commands in these lists are called, in the order of their respective command groups in the {{(groups)}} parameter. Command groups are notably used to support "-help" and "-version" options, which may appear anywhere in the command-line (barring positional errors). A command group could also be used to support order-independent flag options that need to run before the imperative "actions". Imperative-command-line-a provides one pre-made command-group, {{special-options}}, which defines the commands "help" and "version". These command line options are automatically available in your program, unless you override them (for which see {{groups}} below). The output of these commands is configured in part by the parameters {{help-heading}} and {{help-minimum-intercolumn-space}}. Each defined command-line option takes a certain number of positional parameters. Your commands are not limited to a single parameter, but variable numbers of parameters are not yet supported. Since the distinction between command and parameter is purely positional, the conventional leading hyphens on option names are purely stylistic and may be omitted. This module has room to grow. The initial set of features are those that meet the requirements of Mowedline, but now that this is a separate project, new uses and needs will undoubtedly arise, and future versions of this egg will be more powerful, flexible, and easier to use. == Authors * John J Foerch == Requirements * [[miscmacros]] == API Any program that uses imperative-command-line-a will define at least one command group. Typically, you will use {{define-command-group}} to do this. <syntax>(define-command-group name command-def ...)</syntax> <syntax>(define-command-group name #:title title command-def ...)</syntax> <syntax>(define-command-group* name command-def ...)</syntax> <syntax>(define-command-group* name #:title title command-def ...)</syntax> {{define-command-group}} is the typical way to define a command group. It defines the symbol {{name}} as a command group constructed according to the rest of the arguments. It adds the new group to {{(groups)}}. The starred form, {{define-command-group*}}, is the same, except that it does not automatically add the new group to {{(groups)}}. When no title is given, {{make-title}} is used to generate one automatically based on {{name}}. The title is used in the -help display. Each command-def looks like {{((name . args) . body)}} or {{((name . args) #:doc doc . body)}}. The {{#:doc}} keyword may be used to store a short docstring for the command, which will be printed in the -help display. <procedure>(make-command-group title commands)</procedure> You will not normally use this procedure directly. It is part of the expansion of {{define-command-group}} and {{define-command-group*}}. <parameter>make-title</parameter> Value is a procedure that converts a symbol to a string, suitable for use in -help titling. The default upcases the string and replaces hyphen with spacen. <procedure>(abort-parse)</procedure> Helper procedure for use in command bodies to stop calling of commands, and inform the calling program that it should exit. This is used by the built-in special commands {{-help}} and {{-version}} to ensure that only one command is called. <procedure>(parse input)</procedure> Parse the list of command-line arguments, input into commands and call them. Returns {{#t}} on successful completion of calling commands, {{#f}} if parsing was aborted. <parameter>groups</parameter> The groups parameter holds the list of command-groups that {{parse}} draws from. By default, it starts with a single group, special-options, which contains the commands -help and -version. The syntax form {{define-command-group}} adds to this list. To remove the provided special-options group, call {{(group '())}} to initialize the list before defining any other command groups. <parameter>help-heading</parameter> The string value of help-heading is printed out by the provided -version command, and as the first line of the provided -help command. Be sure to set this. <parameter>help-minimum-intercolumn-space</parameter> The provided -help command prints command call forms and docstrings in two columns. The help-minimum-intercolumn-space parameter gives the minimum number of spaces by which to separate the two columns, defaulting to 3. === Commands API You will generally not need to use this part of the API, unless you write introspective commands, like your own -help. <procedure>(make-command name args doc body)</procedure> <procedure>(command-name cmd)</procedure> <procedure>(command-args cmd)</procedure> <procedure>(command-doc cmd)</procedure> <procedure>(command-body cmd)</procedure> <procedure>(command-name-string cmd)</procedure> == Examples <enscript highlight=scheme> (use srfi-1 (prefix imperative-command-line-a icla:)) (icla:help-heading "icla-example version 1.0, by Harry S Beethoven") (icla:define-command-group general-options ((foo) doc: "print foo" (print "foo")) ((bar baz) (print baz))) (icla:parse (command-line-arguments)) </enscript> == License BSD == Version History * 0.1 (February 13, 2013) initial release * 0.2 (February 14, 2013) simpler 'parse' call-form * 0.3 (February 18, 2013) 'parse' now calls the commands * 0.4 (February 19, 2013) introducing define-command-group * 0.5.0 (June 16, 2016) signal (exn icla parse) error for parse errors