[[tags: egg]]

== easy-args

[[toc:]]

=== Description

Handle command-line arguments as parameter objects.

'''Note:''' This egg is no longer supported. Please refer to
[[/eggref/4/srfi-37|srfi-37]], [[/eggref/4/args|args]] or
[[/eggref/4/getopt-long|getopt-long]] for command-line argument handling
libraries.

=== Requirements

[[/eggref/4/srfi-37|srfi-37]]

=== API

==== define-arguments

<syntax>(define-arguments (name [value [guard]]) ...)</syntax>

{{define-arguments}} defines parameter objects for the given command line
option names and sets them according to the program's
{{command-line-arguments}} parameter.

For each specified argument, {{name}} should be an identifier or list of
identifiers. The first of these will be bound to the newly-created parameter
object. {{value}}, if given, must be a boolean, string, number or symbol, and
will be the default value of the parameter object. If no {{value}} is given,
{{#f}} is used. If a procedure {{guard}} is given, it is used as the parameter
object's conversion procedure.

Each {{name}}, when prefixed by one dash (in the case of a single-character
identifier) or two (for all others), will be used as a command-line flag to set
the corresponding parameter object's value. If {{name}} contains asterisks,
they are stripped from the flag.

{{define-arguments}} reads and modifies Chicken's {{command-line-arguments}}
parameter, setting matched parameter objects to the specified values and
removing their options from the list. Unmatched arguments are accumulated into
an alist accessible by the {{unmatched-arguments}} procedure. Upon completion,
{{command-line-arguments}} will contain any non-option arguments to the
program. The return value is unspecified.

==== invalid-argument-handler

<parameter>invalid-argument-handler</parameter>

{{invalid-argument-handler}} is called when {{define-arguments}} encounters an
invalid command-line value. It is a procedure of three arguments: an error
message (string), option name (string or character) and value (a string or
{{#t}}). By default, this procedure simply prints an error message and exits
the program.

==== unmatched-arguments

<procedure>(unmatched-arguments)</procedure>

Returns an alist of the command-line arguments unmatched by
{{define-arguments}}. If called before {{define-arguments}}, it will return an
empty list.

=== Examples

<enscript highlight="scheme">
(use easy-args extras)

(define-arguments
  (all-caps)
  (prompt "Your name? ")
  ((exclamations e) 1))

(display (prompt))

(let ((message (string-join `("Hello," ,(read-line)))))
  (if (all-caps)
    (display (string-upcase message))
    (display message)))

(print (make-string (exclamations) #\!))

(if (not (null? (unmatched-arguments)))
  (print (unmatched-arguments)))
</enscript>

With the file above as {{greeter.scm}}:

  $ csc greeter.scm
  
  $ ./greeter
  Your name? [Henrietta]
  Hello, Henrietta!
  
  $ ./greeter --all-caps
  Your name? [Henrietta]
  HELLO, HENRIETTA!
  
  $ ./greeter --prompt 'Name: ' -e3
  Name: [Henrietta]
  Hello, Henrietta!!!
  
  $ ./greeter -w --unmatched=args
  Your name? Henrietta
  Hello, Henrietta!
  ((w . #t) (unmatched . args))

=== History

* 0.6 Deprecated
* 0.5 Use srfi-37, getopt-style flags
* 0.4 Allow symbols
* 0.1 Initial release

=== Author

[[Evan Hanson]]

=== License

Public Domain