optimism

Command line option handling.

  1. optimism
  2. Description
  3. Usage
    1. API
  4. Author
  5. Repository
  6. License

Description

This extension provides a way to collect command line options into an association list according to a simple S-expressive grammar.

Usage

One procedure is provided, parse-command-line, which takes as arguments an options grammar and an optional list of command line option strings and returns an association list. If no list of options is given, the program's command line arguments are used.

(import (optimism))

(parse-command-line
 '("-a" "-b" "one" "-c" "two" "three" "-d" "four" "5" "six")
 `((-a)
   (-b . foo)
   (-c bar baz)
   (-d ,string->symbol ,string->number)))

; => ((-a)
;     (-b . "one")
;     (-c "two" "three")
;     (-d four 5)
;     (-- "six"))

As a special case, an item in the grammar whose first element is a list will be split into separate entries. This allows the following shorthand syntax for aliases, where multiple options should have the same form:

(parse-command-line
 '(((-f --foo) . bar)))

; The above is equivalent to:
;
;     (parse-command-line
;      '((-f    . bar)
;        (--foo . bar)))

Parsers for getopt(3) and getopt_long(3)-style command lines are provided by the getopt and getopt-long sublibraries, respectively.

(import (optimism getopt))

(parse-command-line               ; => ((-a)
 '("-abcone" "-d" "two")          ;     (-b)
 '((-a)                           ;     (-c . "one")
   (-b)                           ;     (-d . "two")
   (-c . one)                     ;     (--))
   (-d . two)))

(import (optimism getopt-long))

(parse-command-line               ; => ((-a . "one")
 '("-aone" "--foo" "--bar=two")   ;     (--foo)
 '((-a . one)                     ;     (--bar . "two")
   (--foo)                        ;     (--))
   (--bar . two)))

API

[procedure] (parse-command-line grammar)
[procedure] (parse-command-line arguments grammar)
[procedure] (parse-command-line matcher arguments grammar)

parse-command-line parses a program's command line arguments into an association list according to an S-expressive options grammar.

It takes one required and two optional arguments: an option matching procedure, an S-expressive options grammar, and a list of command line argument strings. If matcher is not given a basic string comparison is used, while arguments defaults to the value of (cdr (command-line)).

grammar is a finite list of pairs whose cars are symbols and whose cdrs are pairs or atoms. All other cars in the grammar must be atoms; grammars may not be nested.

The given arguments are matched as symbols against the cars of the options grammar. When a match is found, an association from the matched symbol to the arguments immediately following the matched item in the arguments list is added, following the form of the matched pair.

(parse-command-line               ; => ((foo . "bar")
 '("foo" "bar")                   ;     (--))
 '((foo . bar)))

(parse-command-line               ; => ((foo)
 '("foo" "bar" "baz" "qux")       ;     (bar "baz" "qux")
 '((foo)                          ;     (--))
   (bar baz qux)))

Unmatched arguments are added to the resulting association list under the key --. Similarly, any arguments following a "--" in the arguments list are treated as unmatched.

(parse-command-line               ; => ((foo . "bar")
 '("foo" "bar" "baz")             ;     (-- "baz"))
 '((foo . bar)))

(parse-command-line               ; => ((foo . "bar")
 '("foo" "bar" "--" "baz" "qux")  ;     (-- "baz" "qux"))
 '((foo . bar)
   (baz . qux)))

In a matched options form, procedures are replaced by the result of invoking that procedure on the corresponding item in the arguments list. All other objects are replaced by the corresponding argument string directly.

(parse-command-line               ; => ((foo ("bar") 42 qux)
 '("foo" "bar" "42" "qux")        ;     (--))
 `((foo ,list
        ,string->number
        ,string->symbol)))

Author

Evan Hanson

Repository

https://git.foldling.org/optimism/

License

Public Domain