Title

args-fold: a program argument processor

Author

Anthony Carrico

Status

This SRFI is currently in ``final'' status. To see an explanation of each status that a SRFI can hold, see here. You can access previous messages via the archive of the mailing list.

Abstract

Many operating systems make the set of argument strings used to invoke a program available (often following the program name string in an array called argv). Most programs need to parse and process these argument strings in one way or another. This SRFI describes a set of procedures that support processing program arguments according to POSIX and GNU C Library Reference Manual guidelines.

Rationale

Program arguments are the primary interface to many programs, so processing arguments is a common programming task. There are many common (often conflicting) ways take care of this task, so a custom processor is often necessary; however, many programmers (and their users) would welcome a convenient interface supporting common guidelines.

POSIX provides several guidelines for the specification of program options, option-arguments, and operands. It also notes historical exceptions to these guidelines. The GNU C Library Reference Manual describes long option extensions to the POSIX guidelines.

This SRFI supports creating programs following the guidelines mentioned above by

It parses argument strings according to the following rules:

Preliminary versions of this interface are already available for some Scheme implementations: here for Chicken, and here for Scsh.

Specification

Args-fold is an iterator similar to SRFI 1's fold procedure ("the fundamental list iterator"). As it parses options and operands, it calls their corresponding operand and option processors. Unlike mapping, folding passes state, called seeds, from one processor to the next.

For example, a program may need a list of operands and a table of options. To build these, args-fold could be seeded with an empty operand list, and an empty option table. The operand processor could add the operands to the operand list, and the option processors could add the options to the option table. Along the way, some option processors might even take immediate action for options like --version or --help. This kind of heterogeneous processing is appropriate for program arguments, and folding allows a functional implementation if desired.

procedure prototype: (option-processor OPTION NAME ARG SEEDS ...)

Prototype for an option-processor. It should return the next seeds as values. OPTION will be the option. NAME will be one of the OPTION's option-names as encountered by args-fold. ARG will be a string, or #f if args-fold didn't encounter an option-argument.

procedure prototype: (operand-processor OPERAND SEEDS ...)

Prototype for an operand-processor. It should return the next seeds as values. OPERAND will be a string.

procedure: (option NAMES REQUIRED-ARG? OPTIONAL-ARG? OPTION-PROC)

Return an option. NAMES is a list of short (character) and long (string) option names. REQUIRED-ARG? specifies if this options requires an option-argument (boolean). OPTIONAL-ARG? specifies if this option can accept an option-argument (boolean). OPTION-PROC is a procedure (following the option-processor prototype) used to process this option.

procedure: (option-names OPTION)
procedure: (option-required-arg? OPTION)
procedure: (option-optional-arg? OPTION)
procedure: (option-processor OPTION)

Return the contents of corresponding fields of OPTION.

procedure: (args-fold ARGS OPTIONS UNRECOGNIZED-OPTION-PROC OPERAND-PROC SEEDS ...)

Parse argument strings left-to-right, calling the appropriate processors in-order (for the parsed known options, unknown options, and operands), passing the seed values from one processor to the next and returning the final seeds values as results. ARGS is a list of strings. OPTIONS is a list of options. UNRECOGNIZED-OPTION-PROC is a procedure (following the option-processor prototype) for unrecognized options. NOTE: args-fold will create temporary options as necessary for the UNRECOGNIZED-OPTION-PROC. OPERAND-PROC is a procedure (following the operand-processor prototype) for operands.

Source for the reference implementation.

Copyright

Copyright (C) Anthony Carrico (2002). All Rights Reserved.

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.


Editor: David Rush