Changeset 25490 in project


Ignore:
Timestamp:
11/11/11 02:43:15 (9 years ago)
Author:
evhan
Message:

update docs

File:
1 edited

Legend:

Unmodified
Added
Removed

  • wiki/eggref/4/easy-args

    r25152 r25490  
    99Handle command-line arguments as parameter objects.
    1010
    11 === Author
     11=== Requirements
    1212
    13 Evan Hanson
     13[[/eggref/4/srfi-37|srfi-37]]
    1414
    1515=== Documentation
    … …  
    1818parameter objects.
    1919
    20 It is intended to be easy to use for small binaries and one-off
    21 scripts. For more complete option handling and usage message utilities,
    22 see [[/eggref/4/args|args]], [[/eggref/4/getopt-long|getopt-long]],
    23 [[/eggref/4/srfi-37|srfi-37]], or [[/eggref/4/usage|usage]].
     20It is defined over [[/eggref/4/srfi-37|srfi-37]] and is intended to be easy to
     21use for small binaries and one-off scripts. For more flexible option handling
     22and usage message utilities, use srfi-37 itself or see [[/eggref/4/args|args]],
     23[[/eggref/4/getopt-long|getopt-long]], or [[/eggref/4/usage|usage]].
    2424
    2525==== define-arguments
    … …  
    2727<syntax>(define-arguments (name [value [guard]]) ...)</syntax>
    2828
    29 {{define-arguments}} creates parameter objects for the given command
    30 line option names and sets them according to the application's
     29{{define-arguments}} defines parameter objects for the given command line
     30option names and sets them according to the program's
    3131{{command-line-arguments}} parameter.
    3232
    33 For each specified argument, {{name}} should be an identifier and will
    34 be bound to the newly-created parameter object. {{value}}, if given,
    35 must be a boolean, string, number or symbol and will be the default value
    36 of the parameter object. If no {{value}} is given, {{#f}} is used. If
    37 a procedure {{guard}} is given, it is used as the parameter object's
    38 conversion procedure.
     33For each specified argument, {{name}} should be an identifier or list of
     34identifiers. The first of these will be bound to the newly-created parameter
     35object. {{value}}, if given, must be a boolean, string, number or symbol, and
     36will be the default value of the parameter object. If no {{value}} is given,
     37{{#f}} is used. If a procedure {{guard}} is given, it is used as the parameter
     38object's conversion procedure.
    3939
    40 This form reads Chicken's {{command-line-arguments}} parameter internally,
    41 setting any matching parameter objects to the specified values and
    42 removing handled arguments from the list. Matched boolean arguments
    43 are set to {{#t}}; other arguments are set to the value following the
    44 matched argument's flag.
     40Each {{name}}, when prefixed by one dash (in the case of a single-character
     41identifier) or two (for all others), will be used as a command-line flag to set
     42the corresponding parameter object's value. If {{name}} contains asterisks,
     43they are stripped from the flag.
    4544
    46 {{name}}, when prefixed by a single dash ("-"), is used as the argument's
    47 command-line flag. If {{name}} contains asterisks ("*"), they are stripped
    48 from the flag.
     45{{define-arguments}} reads and modifies Chicken's {{command-line-arguments}}
     46parameter, setting matched parameter objects to the specified values and
     47removing their options from the list. Unmatched arguments are accumulated into
     48an alist accessible by the {{unmatched-arguments}} procedure. Upon completion,
     49{{command-line-arguments}} will contain any non-option arguments to the
     50program. The return value is unspecified.
    4951
    50 {{define-arguments}} renames the original {{command-line-arguments}}
    51 object to {{command-line-arguments*}}. Its return value is undefined.
     52==== invalid-argument-handler
     53
     54<parameter>invalid-argument-handler</parameter>
     55
     56{{invalid-argument-handler}} is called when {{define-arguments}} encounters an
     57invalid command-line value. It is a procedure of three arguments: an error
     58message (string), option name (string or character) and value (a string or
     59{{#t}}). By default, this procedure simply prints an error message and exits
     60the program.
     61
     62==== unmatched-arguments
     63
     64<procedure>(unmatched-arguments)</procedure>
     65
     66Returns an alist of the command-line arguments unmatched by
     67{{define-arguments}}. If called before {{define-arguments}}, it will return an
     68empty list.
    5269
    5370=== Examples
    … …  
    5976  (all-caps)
    6077  (prompt "Your name? ")
    61   (exclamations 1))
     78  ((exclamations e) 1))
    6279
    6380(display (prompt))
    … …  
    6986
    7087(print (make-string (exclamations) #\!))
     88
     89(if (not (null? (unmatched-arguments)))
     90  (print (unmatched-arguments)))
    7191</enscript>
    7292
    … …  
    7999  Hello, Henrietta!
    80100 
    81   $ ./greeter -all-caps
     101  $ ./greeter --all-caps
    82102  Your name? [Henrietta]
    83103  HELLO, HENRIETTA!
    84104 
    85   $ ./greeter -prompt "Name: " -exclamations 3
     105  $ ./greeter --prompt 'Name: ' -e3
    86106  Name: [Henrietta]
    87107  Hello, Henrietta!!!
     108 
     109  $ ./greeter -w --unmatched=args
     110  Your name? Henrietta
     111  Hello, Henrietta!
     112  ((w . #t) (unmatched . args))
    88113
    89114=== History
    90115
    91 * 0.4 Allow symbols, stash original c-l-a
    92 * 0.3 Fix scoping for newer chickens
    93 * 0.2 Rewrite as single form
     116* 0.5 Use srfi-37, getopt-style flags
     117* 0.4 Allow symbols
    94118* 0.1 Initial release
     119
     120=== Author
     121
     122[[Evan Hanson]]
    95123
    96124=== License
    97125
    98   Copyright (c) 2011, Evan Hanson All rights reserved.
    99  
    100   Redistribution and use in source and binary forms, with or without
    101   modification, are permitted provided that the following conditions
    102   are met:
    103  
    104   * Redistributions of source code must retain the above copyright
    105   notice, this list of conditions and the following disclaimer.  *
    106   Redistributions in binary form must reproduce the above copyright
    107   notice, this list of conditions and the following disclaimer in the
    108   documentation and/or other materials provided with the distribution.
    109   * Neither the name of the author nor the names of its contributors
    110   may be used to endorse or promote products derived from this software
    111   without specific prior written permission.
    112  
    113   THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER AND CONTRIBUTORS
    114   "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
    115   LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
    116   A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
    117   HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
    118   SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
    119   LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
    120   DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
    121   THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
    122   (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
    123   OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
     126Copyright (c) 2011 Evan Hanson, 3-Clause BSD.
Note: See TracChangeset for help on using the changeset viewer.