getopt-utils

Documentation

Provides some helpers for the getopt-long library, whose documentation must be consulted for the Command-line option grammar referenced below.

Module getopt-utils

Usage

(import getopt-utils)

Argument Conventions

GRAMMER: a (list-of (pair symbol list)), an extended getopt-long grammer
OVERRIDES: reporting option overrides, a (list-of (pair symbol . *))
ARGUMENTS: result of (command-line-arguments), a (list-of string)
PARAMS: ((list-of (pair symbol list))) ; processed options (see opt-pase).
KEY?: symbol ; name of option to reference

Reporting option overrides

command: the command-name, default (program-name) parameter
port: the error-port, default (current-error-port) parameter
long-option-value-cset: a SRFI-14 character-set that specifies all valid characters in an option value, default getop-long default-long-option-value-cset constant value
long-option-value-quoting: a boolean specifying whether arguments are quoted "...", default getop-long (long-option-value-quoting) parameter
message: the usage template message, default (usage-message) parameter
width: the output line width, default getop-long (width) parameter
separator: the output line width, default getop-long (separator) parameter
indent: the output line width, default getop-long (indent) parameter

extend-opt-grammar

(extend-opt-grammar HELP? OPTION ...)syntax

(extend-opt-grammar SOURCE OPTION ...)syntax

HELP?: boolean ; include help flag
SOURCE: (or (list-of OPTION) OPTION) ; appends SOURCE OPTION ...
OPTION: see {[getopt-long]} Command-line option grammar

Extends the option grammer w/ ((long s) ...) => ((long s) ... (single-char #\s)).

opt-docstring

opt-docstring MESSAGE #!optional VALUEprocedure: Takes a string MESSAGE and any VALUE, returning a string composed of the MESSAGE with the string form of the VALUE, as a default value.

opt-value

(opt-value RO [TP])syntax

RO: (or (required KIND) (optional KIND) KIND) ; requirement
TP} : {{(or (string -> boolean) ((string -> *) (string -> boolean))) ; transform-predicate

opt-body

(opt-body MSG [RO [TP]])syntax

MSG: (or string (string *)) ; help text, * is default value
RO: (or (required KIND) (optional KIND) KIND) ; requirement
TP} : {{(or (string -> boolean) ((string -> *) (string -> boolean))) ; transform-predicate

opt-number

(opt-number MSG [RO [PRED]])syntax

opt-body element for number values.

MSG: (or string (string *)) ; message, * is default value
RO: (or (required KIND) (optional KIND) KIND) ; requirement
PRED: (string -> boolean) ; predicate

((size s) ,@(opt-number ("sample size" *sample-size*) (required INTEGER)
                        (conjoin integer? positive?)))

opt-string

(opt-string MSG [RO [PRED]])syntax

opt-body element for string values.

MSG: (or string (string *)) ; message, * is default value
RO: (or (required KIND) (optional KIND) KIND) ; requirement
PRED: (string -> boolean) ; predicate

(et ,@(opt-string "entry thingy directory" ET-PATHNAME dirname?))

string-read

string-read STRprocedure: Use utf8 read to transform the string STR.

string->/?

(string->/? TRAN PRED) -> (string -> (or false *))syntax

Returns a procedure returning the transformed & tested value from an input string. Cannot be used when #f is valid for the domain.

TRAN: (string -> 'a) ; transformer
PRED: ('a -> boolean) ; predicate

(string->/? string->number (conjoin integer (cut <= 1 <> 32)))

opt-parse

(opt-parse ARGUMENTS GRAMMER [OVERRIDES] [RAW?]) -> (list-of (pair symbol *))procedure

Have getopt-long parse the ARGUMENTS using the GRAMMER, with any OVERRIDES, and returns an association-list of grammer option names (symbol) to option values.

When RAW? is #t any interpreter script mode processing is not perfomed; any leading "--" is left.

The long-option-value-quoting override is in effect; the corresponding getopt-long parameter is set.

A getopt-long unknown-option-handler is

opt-set!

(opt-set! VARIABLE KEY PARAMS [DEFAULT])syntax

Sets the VARIABLE to the value of the processed option KEY, in the PARAMS, with DEFAULT supplying a value when no such option KEY. The KEY is evaluated so a literal must be quoted.

VARIABLE: symbol ; name of variable to set!
DEFAULT: (or procedure *) ; default is (DEFAULT), when procedure, and DEFAULT otherwise

opt-ref

(opt-ref KEY PARAMS)) -> *syntax: Returns the value of the processed option KEY, in the PARAMS. The KEY is evaluated so a literal must be quoted.

opt-rest

opt-rest PARAMSprocedure: Any remaining, unprocessed, options.

usage-message

usage-message #!optional MESSAGEparameter: The usage template message.

opt-usage

opt-usage GRAMMER #!optional OVERRIDESprocedure

Display getopt-long usage for the GRAMMER, with any reporting OVERRIDES, on the error-port.

The message, width, separator, and indent overrides are in effect; the corresponding getopt-long parameter is set.

opt-usage-error

(opt-usage-error ISSUE GRAMMER [OVERRIDES] [EXIT-CODE])procedure

Prints an error arguments message for ISSUE & the getopt-long usage, using the GRAMMER, with any reporting OVERRIDES, then exits the process with EXIT-CODE.

ISSUE: (or string condition) ; error condition/message
EXIT-CODE: fixnum ; process exit-code, default is EX_USAGE (64).

opt-exn-error

opt-exn-error EXN GRAMMER #!optional OVERRIDESprocedure

Prints an error message for EXN with opt-error.

EXN: condition ; error condition

opt-error

opt-error MESSAGE ARGUMENTS GRAMMER #!optional OVERRIDESprocedure: Prints an error MESSAGE to the error-port for the ARGUMENTS and GRAMMER, with any reporting OVERRIDES.

Examples

Note that the example is incomplete - no app code, no logging library.

(import (chicken file))
;(import ph-log-utils)
(import getopt-utils)

(define-constant DB-PATHNAME-DEF "development.sqlite3")
(define-constant BUSINESS-VIEW-NAME "business_entries")

(define +geocode-service-name+ "google")
(define +db-view+ "entries")
(define +replace-all?+ (the boolean #f))
(define +app-dir+ ".")
(define +db-pathname+ DB-PATHNAME-DEF)
(define +sample-size+)

(define +opt-grammar+ (extend-opt-grammar #t
  ((replace-all a) "replace all geocodes")
  ((db-fil f) ,@(opt-string ("database pathname" +db-pathname+) DB-PATHNAME file-exists?))
  ((service s) ,@(opt-string ("geocode service" +geocode-service-name+) SERVICE-NAME))
  ((db-view v) ,@(opt-string ("database view" +db-view+) DB-VIEW-NAME))
  ((app-dir d) ,@(opt-string ("Ti project directory" +app-dir+) APP-DIRECTORY directory-exists?))
  ((size s) ,@(opt-number "sample size" (required INTEGER) (conjoin integer? positive?)))
))

(define +opt-options+ '((width . 48)))

(define (processs-options params)
  (opt-set! +geocode-service-name+ 'service params)
  (opt-set! +db-view+ 'db-view params)
  (opt-set! +replace-all?+ 'replace-all params)
  (opt-set! +app-dir+ 'app-dir params)
  (opt-set! +db-pathname+ 'db-fil params)
  (opt-set! +sample-size+ 'size params) )

(define (appmain params)
  (processs-options params)
  #| ;no logging
  (current-log-level 'trace)
  (log-info "project dir: ~S" +app-dir+)
  (log-info "project db: ~S" "(app-db-pathname)")
  (log-info "db view: ~S" +db-view+)
  (log-info "service: ~S" +geocode-service-name+)
  (log-info "sample-size: ~A" +sample-size+)
  (logout-empty)
  |#
  ;
  (void "... app code ...") )

;;;

(define (main args)
  (appmain (opt-parse args +opt-grammar+ +opt-options+)) )

(cond-expand
  (chicken-script
    (main (command-line-arguments)) )
  (csi
    (display "(main (\"--example\" ...))") (newline)
    (main '("-h")) )
  (else
    (main (command-line-arguments)) ) )

Notes

 * The {{define-options}} egg takes a ''bundled'' approach.

Repository

This egg is hosted on the CHICKEN Subversion repository:

https://anonymous@code.call-cc.org/svn/chicken-eggs/release/5/getopt-utils

If you want to check out the source code repository of this egg and you are not familiar with Subversion, see this page.

Version history

1.2.0: Add opt-value, opt-body, opt-number, opt-string, string-read, string->/?.
1.1.1: .
1.1.0: Extended name syntax (long s).
1.0.1: .
1.0.0: Hello

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 ASIS, 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.

chickadee » getopt-utils

Identifier search

TOC »