1 files changed, 74 insertions, 2 deletions

diff --git a/comparse.scm b/comparse.scm
index 5a007b6..5dc1a50 100644
--- a/comparse.scm
+++ b/comparse.scm
@@ -1,5 +1,5 @@
 ;;; "comparse.scm" Break command line into arguments.
-;Copyright (C) 1995, 1997 Aubrey Jaffer
+;Copyright (C) 1995, 1997, 2003 Aubrey Jaffer
 ;
 ;Permission to copy this software, to modify it, to redistribute it,
 ;to distribute modified versions, and to use it for any purpose is
@@ -8,7 +8,7 @@
 ;1.  Any copy made of this software must include this copyright notice
 ;in full.
 ;
-;2.  I have made no warrantee or representation that the operation of
+;2.  I have made no warranty or representation that the operation of
 ;this software will be error-free, and I am under no obligation to
 ;provide any services, by way of maintenance, update, or otherwise.
 ;
@@ -24,6 +24,10 @@
 ;;; reading files of options -- therefore READ-OPTIONS-FILE.
 
 (require 'string-port)
+
+;;@code{(require 'read-command)}
+;;@ftindex read-command
+
 (define (read-command-from-port port nl-term?)
   (define argv '())
   (define obj "")
@@ -86,6 +90,64 @@
     (cond ((and (null? argv) (eof-object? c)) c)
 	  (else (reverse argv)))))
 
+;;@args port
+;;@args
+;;@code{read-command} converts a @dfn{command line} into a list of strings
+;;@cindex command line
+;;suitable for parsing by @code{getopt}.  The syntax of command lines
+;;supported resembles that of popular @dfn{shell}s.  @code{read-command}
+;;updates @var{port} to point to the first character past the command
+;;delimiter.
+;;
+;;If an end of file is encountered in the input before any characters are
+;;found that can begin an object or comment, then an end of file object is
+;;returned.
+;;
+;;The @var{port} argument may be omitted, in which case it defaults to the
+;;value returned by @code{current-input-port}.
+;;
+;;The fields into which the command line is split are delimited by
+;;whitespace as defined by @code{char-whitespace?}.  The end of a command
+;;is delimited by end-of-file or unescaped semicolon (@key{;}) or
+;;@key{newline}.  Any character can be literally included in a field by
+;;escaping it with a backslach (@key{\}).
+;;
+;;The initial character and types of fields recognized are:
+;;@table @asis
+;;@item @samp{\}
+;;The next character has is taken literally and not interpreted as a field
+;;delimiter.  If @key{\} is the last character before a @key{newline},
+;;that @key{newline} is just ignored.  Processing continues from the
+;;characters after the @key{newline} as though the backslash and
+;;@key{newline} were not there.
+;;@item @samp{"}
+;;The characters up to the next unescaped @key{"} are taken literally,
+;;according to [R4RS] rules for literal strings (@pxref{Strings, , ,r4rs,
+;;Revised(4) Scheme}).
+;;@item @samp{(}, @samp{%'}
+;;One scheme expression is @code{read} starting with this character.  The
+;;@code{read} expression is evaluated, converted to a string
+;;(using @code{display}), and replaces the expression in the returned
+;;field.
+;;@item @samp{;}
+;;Semicolon delimits a command.  Using semicolons more than one command
+;;can appear on a line.  Escaped semicolons and semicolons inside strings
+;;do not delimit commands.
+;;@end table
+;;
+;;@noindent
+;;The comment field differs from the previous fields in that it must be
+;;the first character of a command or appear after whitespace in order to
+;;be recognized.  @key{#} can be part of fields if these conditions are
+;;not met.  For instance, @code{ab#c} is just the field ab#c.
+;;
+;;@table @samp
+;;@item #
+;;Introduces a comment.  The comment continues to the end of the line on
+;;which the semicolon appears.  Comments are treated as whitespace by
+;;@code{read-dommand-line} and backslashes before @key{newline}s in
+;;comments are also ignored.
+;;@end table
 (define (read-command . port)
   (read-command-from-port (cond ((null? port) (current-input-port))
 				((= 1 (length port)) (car port))
@@ -94,6 +156,16 @@
 					     "Wrong Number of ARGs:" port)))
 			  #t))
 
+;;@body
+;;@code{read-options-file} converts an @dfn{options file} into a list of
+;;@cindex options file
+;;strings suitable for parsing by @code{getopt}.  The syntax of options
+;;files is the same as the syntax for command
+;;lines, except that @key{newline}s do not terminate reading (only @key{;}
+;;or end of file).
+;;
+;;If an end of file is encountered before any characters are found that
+;;can begin an object or comment, then an end of file object is returned.
 (define (read-options-file filename)
   (call-with-input-file filename
     (lambda (port) (read-command-from-port port #f))))