Title

Author

Status

This SRFI is currently in final status. Here is an explanation of each status that a SRFI can hold. To provide input on this SRFI, please send email to srfi-37@nospamsrfi.schemers.org. To subscribe to the list, follow these instructions. You can access previous messages via the mailing list archive.

• Draft: 2002-09-23--2002-12-23
• Final: 2003-01-13
• Post-finalization note added on 2020-11-30: POSIX, the GNU extensions, and this SRFI are not formally specified and conflicting implementations do exist. For portability, you probably need to avoid optional short arguments and required long option arguments, but we have no proof of that statement. The SRFI author, Anthony Carrico, declares the reference implementation to be in the public domain. You may import the source code into your program to avoid portability issues. [ed. note: See the related email discussion.]

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 to 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

• parsing short-options and long-options in any order and possibly repeated,
• option-arguments (possibly required or forbidden),
• operands (non-option argument strings),
• and recognizing option processing termination.

• Each short-option name is a single character.
• One or more short-options are accepted in a single argument string when grouped behind one - delimiter character. Examples: -a -bcd
• A short-option-argument is accepted in a separate argument string immediately following a short-option. Examples: -a foo -bcd bar
• Also (for historical reasons) a short-option-argument is accepted immediately following the last short-option in a single argument string. Examples: -afoo -bcdbar
• Each long-option name is one or more characters.
• One long-option is accepted in a single argument string when preceded by two - delimiter characters. Example: --help
• In a single argument string, a long-option followed by one = delimiter character followed by a long-option-argument is accepted. Example: --speed=fast
• The first -- argument string is accepted as a delimiter indicating the end of options. It is not treated as an option or an operand. Any argument strings following this delimiter are treated as operands, even if they begin with the - character.
• All other argument strings are treated as operands. This includes argument strings consisting of a single - character.
• Operands may be intermingled with options in any order.

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.

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.