getopt-utils (historical revision 41705)

You are looking at historical revision 41705 of this page. It may differ significantly from its current revision.

getopt-utils

Geographic Utilities

getopt-utils
Documentation
1. Module getopt-utils
Examples

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: getopt-long Command-line option grammar, a (list-of (pair symbol list))
OVERRIDES: reporting option overrides, a (list-of (pair symbol . *))
ARGUMENTS: result of (command-line-arguments), a (list-of string)

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 GRAMMER

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.

KEY?: symbol ; name of option to reference
PARAMS: ({(list-of (pair symbol list))}) ; processed options (see opt-pase).

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!
KEY?: symbol ; name of option to reference
PARAMS: ({(list-of (pair symbol list))}) ; processed options (see opt-pase).
DEFAULT: (or procedure *) ; default is (DEFAULT), when procedure, and DEFAULT otherwise

opt-rest

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

Any remaining, unprocessed, options.

usage-message

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

The usage template message.

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.

opt-usage-error

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

Invoke getopt-long usage for the ISSUE, using the GRAMMER, with any reporting OVERRIDES.

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

opt-usage

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

Invoke getopt-long usage for the GRAMMER, with any reporting OVERRIDES.

opt-exn-error

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

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

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-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 "replace all geocodes")
  (db-fil ,(opt-docstring "database pathname" +db-pathname+)
    (value
      (optional DB-PATHNAME)
      (predicate ,file-exists?) ) )
  (service ,(opt-docstring "geocode service" +geocode-service-name+)
    (value
      (optional SERVICE-NAME) ) )
  (db-view ,(opt-docstring "database view" +db-view+)
    (value
      (optional DB-VIEW-NAME) ) )
  (app-dir ,(opt-docstring "titanium 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)) ) )
/enscript>


== Requirements

[[srfi-1]]
[[getopt-long]]


== Author

[[/users/kon-lovett|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|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 [[/egg-svn-checkout|this page]].


== Version history

; 0.1.0 : Hello


== License

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