;; $Revision: 1.3 $ $Date: 2005/07/13 19:07:50 $

(use eggdoc)
(include "eggdoc-zb.scm")

(define examples `( (pre #<<EOF
(use args)

(define opts
 (list (args:make-option (c cookie)    #:none     "give me cookie"
         (print "cookie was tasty"))
       (args:make-option (d)           (optional: "LEVEL")  "debug level [default: 1]")
       (args:make-option (e elephant)  #:required "flatten the argument"
         (print "elephant: arg is " arg))
       (args:make-option (f file)      (required: "NAME")   "parse file NAME")
       (args:make-option (v V version) #:none     "Display version"
         (print "args-example $Revision: 1.3 $")
         (exit))
       (args:make-option (abc)         #:none     "Recite the alphabet")
       (args:make-option (h help)      #:none     "Display this text"
         (usage))))

(define (usage)
 (with-output-to-port (current-error-port)
   (lambda ()
     (print "Usage: " (car (argv)) " [options...] [files...]")
     (newline)
     (print (args:usage opts))
     (print "Report bugs to zbigniewsz at gmail.")))
 (exit 1))

(receive (options operands)
    (args:parse (command-line-arguments) opts)
  (print "-e -> " (alist-ref 'elephant options))) ;; 'e or 'elephant both work

;; If command line is --cookie -e test -e hello:
;;  cookie was tasty
;;  elephant: arg is test
;;  elephant: arg is hello
;;  -e -> hello

;; If command line is --cookie -e test --foo:
#|
cookie was tasty
elephant: arg is test
./args-example: unrecognized option: foo
Usage: ./args-example [options...] [files...]

 -c, --cookie             give me cookie
 -d [LEVEL]               debug level [default: 1]
 -e, --elephant=ARG       flatten the argument
 -f, --file=NAME          parse file NAME
 -v, -V, --version        Display version
     --abc                Recite the alphabet
 -h, --help               Display this text

Report bugs to zbigniewsz at gmail.
|#

EOF
)
    (p "Additional examples can be found in " (a (@ (href "args-examples.scm"))
                                                 "args-examples.scm") ".")))


(define doc
  `((eggdoc:begin
    (name "args")
    (description "Command-line argument handling facilities, layered on SRFI 37 (args-fold).")
    (author (a (@ (href ,zbigniew-homepage))
               "Zbigniew"))
    (history ; (version "1.1" (b "Fix typo"))
             (version "1.0" "Initial release"))
    (requires "srfi-37 [args-fold]"
              "srfi-13 [string-lib]"
              "srfi-1 [list-lib]")
    (usage)
    (download "args.egg")  ;; download may also be a pair, in which case it's inserted verbatim

    (documentation
     (p "This extension provides a wrapper around SRFI 37 (args-fold).  The main goal is to let the user parse command-line arguments without having to write a lot of similar support code every time.")

     (p "By default, options and operands (non-options) are collected into two lists and returned by the parser, and unrecognized options complain and display help.  Therefore, it is very possible not to write any option-procs, operand-procs, or unrecognized-procs as required by SRFI 37.  However, the capability to customize is there should you need it.")

     (p "Additionally, the help text for your options can be generated for you, so your options and usage information don't get out of sync.")

;;; CREATING OPTIONS
     
     (subsection "Creating options"
                ;; I'd like multiple signatures sometimes -- should they be a plain list,
                ;; an element followed by a list, one element per signature, attributes (@), or what?
       (group            
        (macro "(args:make-option (OPTION-NAME ...) ARG-DATA [BODY])"
          (p "Make an args:option record, suitable for passing to args:parse.")

          (p "OPTION-NAME ... is a sequence of short or long option names. "
             "They must be literal symbols; single-character symbols become "
             "short options, and longer symbols become long options. So "
             (tt "(args:make-option (c cookie) ...)") " specifies a short "
             "option -c and long option --cookie.  Under the hood, (c cookie) "
             "becomes '(#\\c \"cookie\"), as expected by SRFI 37's OPTION.")

          (p "ARG-DATA is either a pair (ARG-TYPE ARG-NAME) or a plain keyword ARG-TYPE.
ARG-TYPE is a keyword that specifies whether the option takes an argument:")

          (symbol-table (describe "#:required" "Argument is required")
                        (describe "#:optional" "Argument is optional")
                        (describe "#:none"     "No argument (actually, any other value than #:required or #:optional is interpreted as #:none)"))

          (p "ARG-NAME, if provided, is a string specifying the name of the argument.
This name is used in the help text produced by args:usage.")

          (p "BODY is an optional sequence of statements executed when this option is encountered.
Behind the scenes, BODY is wrapped in code which adds the current option and its
argument to the final options alist.  So, simply leave BODY blank and options
will be collected for you.  BODY is an option-processor as defined in SRFI 37,
and has access to the variables OPT (the current #<option>), NAME (the option name)
and ARG (argument value or #f)."))))

;;; PARSING THE COMMAND LINE
     
     (subsection "Parsing the command line"
      (group           
       (procedure "(args:parse ARGS OPTIONS-LIST [OPTIONALS])"
                  (p "Parse ARGS, a list of command-line arguments given as strings,
and return two values: an alist of option names (symbols) and their values,
and a list of operands (non-option arguments).")

                  (p "Operands are returned in order, but options
are returned in reverse order.  Duplicate options are retained in
the options alist, so this lets ASSQ find the " (i "last") "
occurrence of any duplicate option on the command line.  A (name
. value) pair is added for each alias of every option found, so
any alias is a valid lookup key.")

                  (p "OPTIONS-LIST is a list of accepted options, each created by
args:make-option.")

                  (p "OPTIONALS is an optional sequence of keywords and values:")
;;; XXX: width should be 15em, not 10em
                  (symbol-table
                   (describe "#:operand-proc PROC" "calls PROC for each operand, with
                                   arguments OPERAND OPTIONS OPERANDS")
                   (describe "#:unrecognized-proc PROC" "calls PROC for each unrecognized
                                   option, with arguments OPTION NAME ARG OPTIONS OPERANDS"))

                  (p "The default operand-proc is a no-op, and the default unrecognized-proc
issues an error message and calls the help option's processor.
See the args-fold documentation for usage information and an explanation
of the procedure arguments; OPTIONS and OPERANDS are seed values."))

       (parameter "args:help-options"
                  (p "List of option names (strings or single characters, as in SRFI 37)
to be considered 'help' options, in order of preference.  args:parse
uses this to select a help option from the option list it is passed.
This is currently used only for unrecognized options, for which the
help option is automatically invoked.")
                  (p "By default, --help, -h and -? are considered help options."))))

     
     (subsection "Usage information"
       (p "Well-behaved programs display help or usage text when invoked with an option such as --help.  args:usage will generate a formatted list of options in the GNU style, from a list of args:options.  Around this you might place a descriptive header and footer.")
        (group (procedure "(args:usage OPTION-LIST)"
                          (p "Generate a formatted list of options from OPTION-LIST,
and return a string suitable for embedding into help text.
The single string consists of multiple lines, with a newline
at the end of each line.  Thus, a typical use would be " (tt "(print (args:usage opts)).")))
               (parameter "args:width"
                          (p "We don't auto-format the left column (the option keys) based on the length of the longest option, but you can override it manually.  Example:")
                          (p (tt "(parameterize ((args:width 40)) (args:usage opts))")))))
        
        (subsection "Operands and unrecognized options (advanced)"
           (p "These are suitable for use with #:operand-proc or #:unrecognized-proc in args:parse.  Most users will probably not customize these procedures themselves, but a couple useful prefabricated ones are provided.")
           (group (procedure "args:ignore-unrecognized-options"
                             (p "Silently ignore unrecognized options, and omit from the options alist."))

                  (procedure "args:accept-unrecognized-options"
                             (p "Silently add unrecognized options to the options alist."))

                  (macro     "(args:make-operand-proc [BODY])"
                    (p "Return a procedure suitable for using as an operand procedure
in args:parse.  Provides the arguments OPERAND, OPTIONS, and OPERANDS
to the BODY; where OPERAND is the current operand (as in args-fold)
and OPTIONS and OPERANDS are SEEDS (as in args-fold) and should not be modified.
Also wraps BODY in code that adds the operand to the final operand list (seed).")))))

             
    (section "Bugs"
             (p "The name " (tt "args:make-option") " is verbose."))
;;; Note examples now wraps in a div with id=examples, not
;;; pre#examples.  You must specify pre manually, because we may not
;;; want entire section encased in pre.... maybe undo that
;;; and better to use section "examples" if you don't want the entire
;;; thing encased in pre?
    
    (examples ,examples)
;;; Note: license sets id=license.  Perhaps sections should do this automatically.
    
    (license ,licenses:zbigniew-bsd))))

#|                  
(with-output-to-file "~/scheme/html/eggdoc-sxslt/args.html"
  (lambda ()
    (eggdoc->html doc)))
|#

(eggdoc->html doc)