The lisp-gflags Reference Manual

Table of Contents

Next: , Previous: , Up: (dir)   [Contents][Index]

The lisp-gflags Reference Manual

This is the lisp-gflags Reference Manual, version 1.6, generated automatically by Declt version 2.3 "Robert April" on Wed Mar 14 04:08:44 2018 GMT+0.


Next: , Previous: , Up: Top   [Contents][Index]

1 Introduction


Lisp GFlags is a Common Lisp implementation of gflags, Google's command line
flag parsing library.  The library implements functionality similar to that of
Google's C++ and Python gflags libraries, which live here:

    http://code.google.com/p/google-gflags/
    http://code.google.com/p/python-gflags/

The code allows you to define command line flags using the DEFINE-FLAG macro.
For instance, the following form defines a boolean flag called *DEBUG-FLAG*
that is set based on the presence of "--debug" in the application's command
line.

    (define-flag *debug-flag*
      :default-value nil
      :selector "debug"
      :type boolean
      :help "Turn on debugging mode?"
      :documentation "Is debugging mode turned on?")

If the command line contains "--debug" or "--debug=true", then *DEBUG-FLAG* is
set to T.  Otherwise, it defaults to NIL.

The function PARSE-COMMAND-LINE is used to parse the command line and initialize
flags.  It returns the original command line with all recognized flags removed.

The file flag_test.lisp contains many examples.


Next: , Previous: , Up: Top   [Contents][Index]

2 Systems

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


Previous: , Up: Systems   [Contents][Index]

2.1 com.google.flag

Author

Robert Brown

License

New BSD license. See the copyright messages in individual files.

Description

Unix command line flag parsing.

Long Description

An implementation of Google’s gflags command line flag parsing library.

Version

1.6

Dependency

com.google.base

Source

com.google.flag.asd (file)

Components

Next: , Previous: , Up: Top   [Contents][Index]

3 Files

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


Previous: , Up: Files   [Contents][Index]

3.1 Lisp


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.1 com.google.flag.asd

Location

com.google.flag.asd

Systems

com.google.flag (system)


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.2 com.google.flag/package.lisp

Parent

com.google.flag (system)

Location

package.lisp

Packages

com.google.flag


Previous: , Up: Lisp files   [Contents][Index]

3.1.3 com.google.flag/flag.lisp

Dependency

package.lisp (file)

Parent

com.google.flag (system)

Location

flag.lisp

Exported Definitions
Internal Definitions

Next: , Previous: , Up: Top   [Contents][Index]

4 Packages

Packages are listed by definition order.


Previous: , Up: Packages   [Contents][Index]

4.1 com.google.flag

Command line flag parsing.

Source

package.lisp (file)

Use List
Exported Definitions
Internal Definitions

Next: , Previous: , Up: Top   [Contents][Index]

5 Definitions

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


Next: , Previous: , Up: Definitions   [Contents][Index]

5.1 Exported definitions


Next: , Previous: , Up: Exported definitions   [Contents][Index]

5.1.1 Macros

Macro: define-flag FLAG-VARIABLE &key DEFAULT-VALUE SELECTOR TYPE HELP PARSER DOCUMENTATION

Defines a global FLAG-VARIABLE of type TYPE, holding value DEFAULT-VALUE, that can be set via the Unix command line to "value" with argument "–SELECTOR=value" or arguments "–SELECTOR value". As a special case, flags of type "boolean" can additionally be set to true with "–SELECTOR" and to false with "–noSELECTOR".

Optionally, associates a HELP string with the flag and a DOCUMENTATION string with FLAG-VARIABLE.

Values for flags defined to be of boolean, string, keyword, integer, or floating point type are parsed by built-in parsers. For flags of other types supply PARSER, a function designator for a function that converts a string into a value of type TYPE. The parser must return two values, the parsed flag value and a boolean indicating whether the parse was successful.

Examples:

(define-flag *debug-mode*
:default-value nil
:selector "debug"
:type boolean
:help "Turn on debugging mode?"
:documentation "Is debugging mode turned on?")

(define-flag *ip-address*
:default-value (make-instance ’ip-address ...)
:selector "ip_address"
:type (satisfies ip-address-p)
:parser ip-address-parser
:help "An internet protocol address.")

Package

com.google.flag

Source

flag.lisp (file)


Previous: , Up: Exported definitions   [Contents][Index]

5.1.2 Functions

Function: command-line ()

Returns the Unix command line as a list of strings.

Package

com.google.flag

Source

flag.lisp (file)

Function: parse-command-line ARGUMENTS

Parses ARGUMENTS, a list of command line argument strings. If a registered flag is found in ARGUMENTS, sets the flag’s value. Returns a copy of ARGUMENTS, but with all recognized flag arguments removed.

Package

com.google.flag

Source

flag.lisp (file)


Previous: , Up: Definitions   [Contents][Index]

5.2 Internal definitions


Next: , Previous: , Up: Internal definitions   [Contents][Index]

5.2.1 Special variables

Special Variable: *registered-flags*

Association list mapping flag selector strings to FLAG instances.

Package

com.google.flag

Source

flag.lisp (file)


Next: , Previous: , Up: Internal definitions   [Contents][Index]

5.2.2 Functions

Function: boolean-flag-p FLAG

Returns true if FLAG is a boolean flag; otherwise, returns false.

Package

com.google.flag

Source

flag.lisp (file)

Function: find-flag SELECTOR

Searches for the registered flag corresponding to the SELECTOR string.

Package

com.google.flag

Source

flag.lisp (file)

Function: flag-parser TYPE-SPECIFIER

Maps a Lisp TYPE-SPECIFIER form, into a designator for a function that can parse the string representation of a TYPE-SPECIFIER value. Returns NIL when there is no predefined parser for TYPE-SPECIFIER.

Package

com.google.flag

Source

flag.lisp (file)

Function: parse-boolean STRING

Parses a STRING representing a boolean value. Returns two values, the boolean and a second boolean indicating whether the parse was successful.

Package

com.google.flag

Source

flag.lisp (file)

Function: parse-double-float STRING

Parses STRING, which represents a double precision floating point value. Returns two values, the double-float number and a boolean indicating whether the parse was successful.

Package

com.google.flag

Source

flag.lisp (file)

Function: parse-float STRING EXPECTED-TYPE

Parses STRING, which represents a floating point value of EXPECTED-TYPE. Returns two values, the floating point number and a boolean indicating whether the parse was successful.

Package

com.google.flag

Source

flag.lisp (file)

Function: parse-int STRING

Parses STRING, a decimal or hexadecimal representation of an integer. Returns two values, the integer and a boolean indicating whether the parse was successful. STRING is parsed as hexadecimal if it starts with "0x".

Package

com.google.flag

Source

flag.lisp (file)

Function: parse-keyword STRING

Returns a symbol in the keyword package with the same name as STRING and T to indicate that parsing STRING was successful.

Package

com.google.flag

Source

flag.lisp (file)

Function: parse-single-float STRING

Parses STRING, which represents a single precision floating point value. Returns two values, the single-float number and a boolean indicating whether the parse was successful.

Package

com.google.flag

Source

flag.lisp (file)

Function: parse-string STRING

Returns two values, STRING and T, to indicate that the parse was (trivially) successful.

Package

com.google.flag

Source

flag.lisp (file)

Function: parse-symbol STRING

If STRING, converted to upper case, represents a package-qualified symbol, returns two values, the symbol and T. Otherwise, returns NIL and NIL.

Package

com.google.flag

Source

flag.lisp (file)

Function: register-flag FLAG SELECTOR

Stores FLAG in a database of registered flags, indexing it by SELECTOR.

Package

com.google.flag

Source

flag.lisp (file)

Function: valid-float-characters-p STRING FLOAT-TYPE

Returns true if every character of STRING is one that may be produced when printing a FLOAT-TYPE floating point number. Otherwise, returns false.

Package

com.google.flag

Source

flag.lisp (file)

Function: validate-flag FLAG SELECTOR

Validates whether a FLAG associated with SELECTOR can be registered without causing any flag parsing problems.

Package

com.google.flag

Source

flag.lisp (file)


Next: , Previous: , Up: Internal definitions   [Contents][Index]

5.2.3 Generic functions

Generic Function: flag-variable OBJECT
Package

com.google.flag

Methods
Method: flag-variable (FLAG flag)

Variable holding this flag’s value.

Source

flag.lisp (file)

Generic Function: help OBJECT
Package

com.google.flag

Methods
Method: help (FLAG flag)

Help message describing this flag.

Source

flag.lisp (file)

Generic Function: parser OBJECT
Package

com.google.flag

Methods
Method: parser (FLAG flag)

Function designator that names a parser function for the flag. The flag parser takes a string as argument and must return two values, the parsed flag value and a boolean indicating whether the parse was successful.

Source

flag.lisp (file)

Generic Function: type-specifier OBJECT
Package

com.google.flag

Methods
Method: type-specifier (FLAG flag)

Type of the flag’s value.

Source

flag.lisp (file)


Previous: , Up: Internal definitions   [Contents][Index]

5.2.4 Classes

Class: flag ()

A global flag that can be initialized by parsing a command line argument.

Package

com.google.flag

Source

flag.lisp (file)

Direct superclasses

standard-object (class)

Direct methods
Direct slots
Slot: flag-variable

Variable holding this flag’s value.

Type

symbol

Initargs

:flag-variable

Readers

flag-variable (generic function)

Slot: help

Help message describing this flag.

Type

string

Initargs

:help

Readers

help (generic function)

Slot: parser

Function designator that names a parser function for the flag. The flag parser takes a string as argument and must return two values, the parsed flag value and a boolean indicating whether the parse was successful.

Type

symbol

Initargs

:parser

Readers

parser (generic function)

Slot: type-specifier

Type of the flag’s value.

Type

(or symbol cons)

Initargs

:type-specifier

Readers

type-specifier (generic function)


Previous: , Up: Top   [Contents][Index]

Appendix A Indexes


Next: , Previous: , Up: Indexes   [Contents][Index]

A.1 Concepts

Jump to:   C   F   L  
Index Entry  Section

C
com.google.flag.asd: The com<dot>google<dot>flag<dot>asd file
com.google.flag/flag.lisp: The com<dot>google<dot>flag/flag<dot>lisp file
com.google.flag/package.lisp: The com<dot>google<dot>flag/package<dot>lisp file

F
File, Lisp, com.google.flag.asd: The com<dot>google<dot>flag<dot>asd file
File, Lisp, com.google.flag/flag.lisp: The com<dot>google<dot>flag/flag<dot>lisp file
File, Lisp, com.google.flag/package.lisp: The com<dot>google<dot>flag/package<dot>lisp file

L
Lisp File, com.google.flag.asd: The com<dot>google<dot>flag<dot>asd file
Lisp File, com.google.flag/flag.lisp: The com<dot>google<dot>flag/flag<dot>lisp file
Lisp File, com.google.flag/package.lisp: The com<dot>google<dot>flag/package<dot>lisp file

Jump to:   C   F   L  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.2 Functions

Jump to:   B   C   D   F   G   H   M   P   R   T   V  
Index Entry  Section

B
boolean-flag-p: Internal functions

C
command-line: Exported functions

D
define-flag: Exported macros

F
find-flag: Internal functions
flag-parser: Internal functions
flag-variable: Internal generic functions
flag-variable: Internal generic functions
Function, boolean-flag-p: Internal functions
Function, command-line: Exported functions
Function, find-flag: Internal functions
Function, flag-parser: Internal functions
Function, parse-boolean: Internal functions
Function, parse-command-line: Exported functions
Function, parse-double-float: Internal functions
Function, parse-float: Internal functions
Function, parse-int: Internal functions
Function, parse-keyword: Internal functions
Function, parse-single-float: Internal functions
Function, parse-string: Internal functions
Function, parse-symbol: Internal functions
Function, register-flag: Internal functions
Function, valid-float-characters-p: Internal functions
Function, validate-flag: Internal functions

G
Generic Function, flag-variable: Internal generic functions
Generic Function, help: Internal generic functions
Generic Function, parser: Internal generic functions
Generic Function, type-specifier: Internal generic functions

H
help: Internal generic functions
help: Internal generic functions

M
Macro, define-flag: Exported macros
Method, flag-variable: Internal generic functions
Method, help: Internal generic functions
Method, parser: Internal generic functions
Method, type-specifier: Internal generic functions

P
parse-boolean: Internal functions
parse-command-line: Exported functions
parse-double-float: Internal functions
parse-float: Internal functions
parse-int: Internal functions
parse-keyword: Internal functions
parse-single-float: Internal functions
parse-string: Internal functions
parse-symbol: Internal functions
parser: Internal generic functions
parser: Internal generic functions

R
register-flag: Internal functions

T
type-specifier: Internal generic functions
type-specifier: Internal generic functions

V
valid-float-characters-p: Internal functions
validate-flag: Internal functions

Jump to:   B   C   D   F   G   H   M   P   R   T   V  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.3 Variables

Jump to:   *  
F   H   P   S   T  
Index Entry  Section

*
*registered-flags*: Internal special variables

F
flag-variable: Internal classes

H
help: Internal classes

P
parser: Internal classes

S
Slot, flag-variable: Internal classes
Slot, help: Internal classes
Slot, parser: Internal classes
Slot, type-specifier: Internal classes
Special Variable, *registered-flags*: Internal special variables

T
type-specifier: Internal classes

Jump to:   *  
F   H   P   S   T  

Previous: , Up: Indexes   [Contents][Index]

A.4 Data types

Jump to:   C   F   P   S  
Index Entry  Section

C
Class, flag: Internal classes
com.google.flag: The com<dot>google<dot>flag system
com.google.flag: The com<dot>google<dot>flag package

F
flag: Internal classes

P
Package, com.google.flag: The com<dot>google<dot>flag package

S
System, com.google.flag: The com<dot>google<dot>flag system

Jump to:   C   F   P   S