The cl-getopt Reference Manual

Table of Contents

The cl-getopt Reference Manual

This is the cl-getopt Reference Manual, generated automatically by Declt version 3.0 "Montgomery Scott" on Sun May 15 03:49:39 2022 GMT+0.

1 Introduction

cl-getopt is a Common Lisp CFFI wrapper to the libc utility
"getopt_long".

See example.lisp for an example SBCL script using this library.  To
run the example, follow the instructions at the top of the script to
install it and then run

./example.lisp

with whatever options you want to see.  Note that for old systems
/usr/bin/env won't support the "-S" option which makes it difficult to
pass arguments to sbcl as a script.  In this case you are probably
already familiar with how to run Lisp scripts in some other way, but
if you're not then the general rule is to create an ordinary shell
script and call SBCL with whatever arguments you like rather than
exploiting the hash-bang script syntax.

There is an "install" target in the Makefile if you want to place the
cl-getopt SBCL core file somewhere it will be useful for other
scripts, e.g. genpass (https://www.github.com/ghollisjr/genpass).

cl-getopt is in the public domain.

2 Systems

The main system appears first, followed by any subsystem dependency.

2.1 cl-getopt

Author

Gary Hollis

License

Public Domain

Description

CFFI wrapper to the libc getopt_long function

Defsystem Dependency

cffi-grovel

Dependency

cffi

Source

cl-getopt.asd (file)

Components

• package.lisp (file)
• grovel.lisp (file)
• cl-getopt.lisp (file)

3 Files

Files are sorted by type and then listed depth-first from the systems components trees.

3.1 Lisp

3.1.1 cl-getopt.asd

Location

cl-getopt.asd

Systems

cl-getopt (system)

3.1.2 cl-getopt/package.lisp

Parent

cl-getopt (system)

Location

package.lisp

Packages

cl-getopt

3.1.3 cl-getopt/grovel.lisp

Dependency

package.lisp (file)

Parent

cl-getopt (system)

Location

grovel.lisp

3.1.4 cl-getopt/cl-getopt.lisp

Dependency

grovel.lisp (file)

Parent

cl-getopt (system)

Location

cl-getopt.lisp

Exported Definitions

• getopt (function)
• option-descriptions (function)

Internal Definitions

• ->optionstr (function)
• ->shortchar (function)
• c-getopt-long (function)
• option (class)
• option-shortarg (function)
• options->shortargs (function)
• short-char (function)
• with-foreign-args (macro)
• with-foreign-longopts (macro)
• with-foreign-shortopts (macro)

4 Packages

Packages are listed by definition order.

4.1 cl-getopt

Source

package.lisp (file)

Use List

• cffi
• common-lisp

Exported Definitions

• getopt (function)
• option-descriptions (function)

Internal Definitions

• %var-accessor-+optarg+ (function)
• (setf %var-accessor-+optarg+) (function)
• %var-accessor-+opterr+ (function)
• (setf %var-accessor-+opterr+) (function)
• %var-accessor-+optind+ (function)
• (setf %var-accessor-+optind+) (function)
• %var-accessor-+optopt+ (function)
• (setf %var-accessor-+optopt+) (function)
• +no-argument+ (constant)
• +optarg+ (symbol macro)
• +opterr+ (symbol macro)
• +optind+ (symbol macro)
• +optional-argument+ (constant)
• +optopt+ (symbol macro)
• +required-argument+ (constant)
• ->optionstr (function)
• ->shortchar (function)
• c-getopt-long (function)
• option (class)
• option-shortarg (function)
• options->shortargs (function)
• short-char (function)
• with-foreign-args (macro)
• with-foreign-longopts (macro)
• with-foreign-shortopts (macro)

5 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.

5.1 Exported definitions

5.1.1 Functions

Function: getopt ARGS OPTIONS &key COMMAND-ARG-PRESENT-P

Returns the values

* option-values
* remaining-arguments

given the list of input arguments and options specification.
option-values is hash-table of the short or long argument name
string (short if present) and the list of all supplied values of that
option in the order they were given. remaining-arguments is a list of
the remaining arguments after processing the options.

Note that if no argument is supplied to an option, whether because the
argspec is :none or :optional, there will still be a list of NIL
elements for each time the option was supplied without an argument.
When the argspec is :required, some kind of value must be in the
argument list for each time that option was supplied.

options should be a list of plists, each plist of the form (&key long
short argspec description) where

* long is a symbol, string or character naming the long argument name.
* short is a symbol, string or character naming the short argument name.
* argspec is one of the values :none, :required, :optional.
* description is a string to be used in an automatically generated argument description message.

command-arg-present-p should be T whenever the argument list includes
the command as the first element, and NIL when it’s not included. For
general scripting use it should be present, but this option is
included to allow easier use of getopt for parsing argument lists
without the command being present.

Package

cl-getopt

Source

cl-getopt.lisp (file)

Function: option-descriptions OPTIONS &key COLUMN-WIDTH COLUMN-MINSPACE

Generates a description string for the list of options supplied.

column-width controls the width in characters of each option column. column-minspace controls the minimum space to pad between columns.

Package

cl-getopt

Source

cl-getopt.lisp (file)

5.2 Internal definitions

5.2.1 Constants

Constant: +no-argument+

Package

cl-getopt

Source

/home/quickref/.cache/common-lisp/sbcl-1.5.8-linux-x64/home/quickref/quicklisp/dists/quicklisp/software/cl-getopt-20211209-git/grovel.processed-grovel-file

Constant: +optional-argument+

Package

cl-getopt

Source

/home/quickref/.cache/common-lisp/sbcl-1.5.8-linux-x64/home/quickref/quicklisp/dists/quicklisp/software/cl-getopt-20211209-git/grovel.processed-grovel-file

Constant: +required-argument+

Package

cl-getopt

Source

/home/quickref/.cache/common-lisp/sbcl-1.5.8-linux-x64/home/quickref/quicklisp/dists/quicklisp/software/cl-getopt-20211209-git/grovel.processed-grovel-file

5.2.2 Symbol macros

Symbol Macro: +optarg+

Package

cl-getopt

Source

/home/quickref/.cache/common-lisp/sbcl-1.5.8-linux-x64/home/quickref/quicklisp/dists/quicklisp/software/cl-getopt-20211209-git/grovel.processed-grovel-file

Expansion

(cl-getopt::%var-accessor-+optarg+)

Symbol Macro: +opterr+

Package

cl-getopt

Source

/home/quickref/.cache/common-lisp/sbcl-1.5.8-linux-x64/home/quickref/quicklisp/dists/quicklisp/software/cl-getopt-20211209-git/grovel.processed-grovel-file

Expansion

(cl-getopt::%var-accessor-+opterr+)

Symbol Macro: +optind+

Package

cl-getopt

Source

/home/quickref/.cache/common-lisp/sbcl-1.5.8-linux-x64/home/quickref/quicklisp/dists/quicklisp/software/cl-getopt-20211209-git/grovel.processed-grovel-file

Expansion

(cl-getopt::%var-accessor-+optind+)

Symbol Macro: +optopt+

Package

cl-getopt

Source

/home/quickref/.cache/common-lisp/sbcl-1.5.8-linux-x64/home/quickref/quicklisp/dists/quicklisp/software/cl-getopt-20211209-git/grovel.processed-grovel-file

Expansion

(cl-getopt::%var-accessor-+optopt+)

5.2.3 Macros

Macro: with-foreign-args (ARGC ARGV) ARGS &body BODY

Converts a Lisp list of strings denoting the arguments supplied to a command into two values:

* argc: number of argument strings
* argv: array of argument strings

These are bound to the symbols supplied in the (argc argv) list.

Package

cl-getopt

Source

cl-getopt.lisp (file)

Macro: with-foreign-longopts (FOREIGN-ARRAY LONG-ONLY-LIST) OPTIONS &body BODY

Package

cl-getopt

Source

cl-getopt.lisp (file)

Macro: with-foreign-shortopts SHORTOPTS-BINDING OPTIONS &body BODY

Package

cl-getopt

Source

cl-getopt.lisp (file)

5.2.4 Functions

Function: %var-accessor-+optarg+ ()

Function: (setf %var-accessor-+optarg+) VALUE

Package

cl-getopt

Source

/home/quickref/.cache/common-lisp/sbcl-1.5.8-linux-x64/home/quickref/quicklisp/dists/quicklisp/software/cl-getopt-20211209-git/grovel.processed-grovel-file

Function: %var-accessor-+opterr+ ()

Function: (setf %var-accessor-+opterr+) VALUE

Package

cl-getopt

Source

/home/quickref/.cache/common-lisp/sbcl-1.5.8-linux-x64/home/quickref/quicklisp/dists/quicklisp/software/cl-getopt-20211209-git/grovel.processed-grovel-file

Function: %var-accessor-+optind+ ()

Function: (setf %var-accessor-+optind+) VALUE

Package

cl-getopt

Source

/home/quickref/.cache/common-lisp/sbcl-1.5.8-linux-x64/home/quickref/quicklisp/dists/quicklisp/software/cl-getopt-20211209-git/grovel.processed-grovel-file

Function: %var-accessor-+optopt+ ()

Function: (setf %var-accessor-+optopt+) VALUE

Package

cl-getopt

Source

/home/quickref/.cache/common-lisp/sbcl-1.5.8-linux-x64/home/quickref/quicklisp/dists/quicklisp/software/cl-getopt-20211209-git/grovel.processed-grovel-file

Function: ->optionstr X

Package

cl-getopt

Source

cl-getopt.lisp (file)

Function: ->shortchar X

Package

cl-getopt

Source

cl-getopt.lisp (file)

Function: c-getopt-long ARGC ARGV SHORTOPTS LONGOPTS INDEX

Package

cl-getopt

Source

cl-getopt.lisp (file)

Function: option-shortarg OPTION

Package

cl-getopt

Source

cl-getopt.lisp (file)

Function: options->shortargs OPTIONS

Package

cl-getopt

Source

cl-getopt.lisp (file)

Function: short-char X

Package

cl-getopt

Source

cl-getopt.lisp (file)

5.2.5 Classes

Class: option ()

Package

cl-getopt

Source

cl-getopt.lisp (file)

Direct superclasses

• translatable-foreign-type (class)
• foreign-struct-type (class)

Appendix A Indexes

A.1 Concepts

A.2 Functions

A.3 Variables

A.4 Data types