getopt-utils

Utilities for the getopt-long egg.

  1. getopt-utils
  2. Documentation
    1. Module getopt-utils
      1. Usage
      2. Argument Conventions
      3. Reporting option overrides
      4. extend-opt-grammar
      5. opt-docstring
      6. opt-parse
      7. opt-set!
      8. opt-ref
      9. opt-rest
      10. usage-message
      11. opt-usage
      12. opt-usage-error
      13. opt-exn-error
      14. opt-error
  3. Examples
  4. Notes
  5. Requirements
  6. Author
  7. Repository
  8. Version history
  9. License

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

[syntax] (extend-opt-grammar HELP? OPTION ...)
[syntax] (extend-opt-grammar SOURCE OPTION ...)
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

[procedure] (opt-docstring MESSAGE [VALUE]) -> string

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

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

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!

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

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

[syntax] (opt-ref KEY PARAMS)) -> *

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

opt-rest

[procedure] (opt-rest PARAMS) -> list

Any remaining, unprocessed, options.

usage-message

[parameter] (usage-message [MESSAGE]) -> string

The usage template message.

opt-usage

[procedure] (opt-usage GRAMMER [OVERRIDES])

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

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

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

[procedure] (opt-exn-error EXN GRAMMER [OVERRIDES])

Prints an error message for EXN with opt-error.

EXN
condition ; error condition

opt-error

[procedure] (opt-error MESSAGE ARGUMENTS GRAMMER [OVERRIDES])

Prints an error MESSAGE to the error-port for the ARGUMENTS and GRAMMER, with any reporting OVERRIDES.

Examples

(import (chicken file))
(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 +opt-grammar+ (extend-opt-grammar #t
  ((replace-all a) "replace all geocodes")
  ((db-fil f) ,(opt-docstring "database pathname" +db-pathname+)
    (value
      (optional DB-PATHNAME)
      (predicate ,file-exists?) ) )
  ((service s) ,(opt-docstring "geocode service" +geocode-service-name+)
    (value
      (optional SERVICE-NAME) ) )
  ((db-view v) ,(opt-docstring "database view" +db-view+)
    (value
      (optional DB-VIEW-NAME) ) )
  ((app-dir d) ,(opt-docstring "Ti project directory" +app-dir+)
    (value
      (optional APP-DIRECTORY)
      (predicate ,directory-exists?) ) ) ))

(define +opt-overides+ '((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) )

(define (appmain params)
  (processs-options params)
  #;(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+)
  #;(logout-empty)
  ;
  (void "... app code ...") )

;;

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

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

Notes

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

Requirements

srfi-1 getopt-long

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.1.0
Extended name syntax (long s).
1.0.1
.
1.0.0
Hello

License

Copyright (C) 2022-2023 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.