getopt-utils

Utilities for the getopt-long egg.

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

opt-docstring

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

RO

(or (required KIND) (optional KIND) KIND) ; requirement

TP} : {{(or (string -> boolean) ((string -> *) (string -> boolean))) ; transform-predicate

opt-body

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

Use utf8 read to transform the string STR.

string->/?

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

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!

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

Returns the value of the processed option KEY, in the PARAMS. The KEY is evaluated so a literal must be quoted.

opt-rest

Any remaining, unprocessed, options.

usage-message

The usage template message.

opt-usage

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

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

Prints an error message for EXN with opt-error.

EXN

condition ; error condition

opt-error

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 getopt-utils)

(define-constant *db-pathname-def* "development.sqlite3")

(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)
  ;
  (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.

Requirements

srfi-1 getopt-long

test test-utils

Author

Kon Lovett

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.3.0

C6 release.

License

Copyright (C) 2022-2024 Kon Lovett. 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 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.