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-value
      7. opt-body
      8. opt-number
      9. opt-string
      10. string-read
      11. string->/?
      12. opt-parse
      13. opt-set!
      14. opt-ref
      15. opt-rest
      16. usage-message
      17. opt-usage
      18. opt-usage-error
      19. opt-exn-error
      20. 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-value

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

opt-body

[syntax] (opt-body MSG [RO [TP]])
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

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

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

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

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

[procedure] (string-read STR) -> *

Use utf8 read to transform the string STR.

string->/?

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

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

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

Requirements

srfi-1 utf8 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.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

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.