The com.google.flag Reference Manual

This is the com.google.flag Reference Manual, version 1.7, generated automatically by Declt version 4.0 beta 2 "William Riker" on Mon Feb 26 16:55:08 2024 GMT+0.

Table of Contents


1 Introduction


2 Systems

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


2.1 com.google.flag

Unix command line flag parsing.

Author

Robert Brown <>

License

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

Long Description

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

Version

1.7

Dependency

com.google.base (system).

Source

com.google.flag.asd.

Child Components

3 Files

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


3.1 Lisp


3.1.1 com.google.flag/com.google.flag.asd

Source

com.google.flag.asd.

Parent Component

com.google.flag (system).

ASDF Systems

com.google.flag.


3.1.2 com.google.flag/package.lisp

Source

com.google.flag.asd.

Parent Component

com.google.flag (system).

Packages

com.google.flag.


3.1.3 com.google.flag/flag.lisp

Dependency

package.lisp (file).

Source

com.google.flag.asd.

Parent Component

com.google.flag (system).

Public Interface
Internals

4 Packages

Packages are listed by definition order.


4.1 com.google.flag

Command line flag parsing.

Source

package.lisp.

Use List
  • com.google.base.
  • common-lisp.
Public Interface
Internals

5 Definitions

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


5.1 Public Interface


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.


5.1.2 Ordinary functions

Function: command-line ()

Returns the Unix command line as a list of strings.

Package

com.google.flag.

Source

flag.lisp.

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.


5.2 Internals


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.


5.2.2 Ordinary functions

Function: boolean-flag-p (flag)

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

Package

com.google.flag.

Source

flag.lisp.

Function: find-flag (selector)

Searches for the registered flag corresponding to the SELECTOR string.

Package

com.google.flag.

Source

flag.lisp.

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.

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.

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.

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.

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.

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.

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.

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.

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.

Function: register-flag (flag selector)

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

Package

com.google.flag.

Source

flag.lisp.

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.

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.


5.2.3 Generic functions

Generic Reader: flag-variable (object)
Package

com.google.flag.

Methods
Reader Method: flag-variable ((flag flag))

Variable holding this flag’s value.

Source

flag.lisp.

Target Slot

flag-variable.

Generic Reader: help (object)
Package

com.google.flag.

Methods
Reader Method: help ((flag flag))

Help message describing this flag.

Source

flag.lisp.

Target Slot

help.

Generic Reader: parser (object)
Package

com.google.flag.

Methods
Reader 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.

Target Slot

parser.

Generic Reader: type-specifier (object)
Package

com.google.flag.

Methods
Reader Method: type-specifier ((flag flag))

Type of the flag’s value.

Source

flag.lisp.

Target Slot

type-specifier.


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.

Direct methods
Direct slots
Slot: flag-variable

Variable holding this flag’s value.

Type

symbol

Initargs

:flag-variable

Readers

flag-variable.

Writers

This slot is read-only.

Slot: help

Help message describing this flag.

Type

string

Initargs

:help

Readers

help.

Writers

This slot is read-only.

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.

Writers

This slot is read-only.

Slot: type-specifier

Type of the flag’s value.

Type

(or symbol cons)

Initargs

:type-specifier

Readers

type-specifier.

Writers

This slot is read-only.


Appendix A Indexes


A.1 Concepts


A.2 Functions

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

B
boolean-flag-p: Private ordinary functions

C
command-line: Public ordinary functions

D
define-flag: Public macros

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

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

H
help: Private generic functions
help: Private generic functions

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

P
parse-boolean: Private ordinary functions
parse-command-line: Public ordinary functions
parse-double-float: Private ordinary functions
parse-float: Private ordinary functions
parse-int: Private ordinary functions
parse-keyword: Private ordinary functions
parse-single-float: Private ordinary functions
parse-string: Private ordinary functions
parse-symbol: Private ordinary functions
parser: Private generic functions
parser: Private generic functions

R
register-flag: Private ordinary functions

T
type-specifier: Private generic functions
type-specifier: Private generic functions

V
valid-float-characters-p: Private ordinary functions
validate-flag: Private ordinary functions