[m-rev.] diff: document some getopt details

[Julien Fischer]

Estimated hours taken: 0.5
Branches: main

Document some details regarding getopt.

library/getopt.m:
library/getopt_io.m:
 	Document that `--' terminates option processing and that the
 	<option>=<arg> is accepted.

 	Reformat some paragraphs to make better use of the available
 	screen space.

Julien.

Index: library/getopt.m
===================================================================
RCS file: /home/mercury/mercury1/repository/mercury/library/getopt.m,v
retrieving revision 1.43
diff -u -r1.43 getopt.m
--- library/getopt.m	23 Nov 2007 07:35:55 -0000	1.43
+++ library/getopt.m	18 Feb 2008 04:50:39 -0000
@@ -10,13 +10,12 @@
  % Authors: fjh, zs.
  % Stability: medium.
  %
-% This module exports the predicate getopt.process_options/4,
-% which can be used to parse command-line options.
+% This module exports the predicate getopt.process_options/4, which can be
+% used to parse command-line options.
  %
-% This version allows both short (single-character) options
-% and GNU-style long options. It also has the GNU extension
-% of recognizing options anywhere in the command-line, not
-% just at the start.
+% This version allows both short (single-character) options and GNU-style long
+% options. It also has the GNU extension of recognizing options anywhere in
+% the command-line, not just at the start.
  %
  % To use this module, you must provide an `option' type which
  % is an enumeration of all your different options.
@@ -54,21 +53,20 @@
  % module, because it requires process_options to take a pair of I/O state
  % arguments.
  %
-% For the "simple" option types, if there are multiple occurrences
-% of the same option on the command-line, then the last (right-most)
-% occurrence will take precedence.  For "accumulating" options,
-% multiple occurrences will be appended together into a list.
-%
-% The "special" option types are handled by a special option handler
-% (see `special_handler' below), which may perform arbitrary
-% modifications to the option_table.  For example, an option which
-% is not yet implemented could be handled by a special handler which
-% produces an error report, or an option which is a synonym for a
-% set of more "primitive" options could be handled by a special
-% handler which sets those "primitive" options.
+% For the "simple" option types, if there are multiple occurrences of the same
+% option on the command-line, then the last (right-most) occurrence will take
+% precedence.  For "accumulating" options, multiple occurrences will be
+% appended together into a list.
+%
+% The "special" option types are handled by a special option handler (see
+% `special_handler' below), which may perform arbitrary modifications to the
+% option_table.  For example, an option which is not yet implemented could be
+% handled by a special handler which produces an error report, or an option
+% which is a synonym for a set of more "primitive" options could be handled by
+% a special handler which sets those "primitive" options.
  %
-% It is an error to use a "special" option for which there is no
-% handler, or for which the handler fails.
+% It is an error to use a "special" option for which there is no handler, or
+% for which the handler fails.
  %
  % Boolean (i.e. bool or bool_special), maybe_int, maybe_string
  % and accumulating options can be negated. Negating an accumulating
@@ -78,6 +76,14 @@
  % Long options can be negated by preceding them with `--no-',
  % e.g. `--no-foo' will negate the `--foo' option.
  %
+% Note that arguments following an option may be separated from the option by
+% either whitespace or an equals, `=', character, e.g. `--foo 3' and `--foo=3'
+% both specify the option `--foo' with the integer argument `3'.
+%
+% If the argument `--' is encountered on the command-line then option
+% processing will immediately terminate, without processing any remaining
+% options.
+%
  %-----------------------------------------------------------------------------%
  %-----------------------------------------------------------------------------%

Index: library/getopt_io.m
===================================================================
RCS file: /home/mercury/mercury1/repository/mercury/library/getopt_io.m,v
retrieving revision 1.12
diff -u -r1.12 getopt_io.m
--- library/getopt_io.m	23 Nov 2007 07:35:56 -0000	1.12
+++ library/getopt_io.m	18 Feb 2008 04:50:39 -0000
@@ -10,13 +10,12 @@
  % Authors: fjh, zs
  % Stability: medium
  %
-% This module exports the predicate getopt_io.process_options/6,
-% which can be used to parse command-line options.
+% This module exports the predicate getopt_io.process_options/6, which can be
+% used to parse command-line options.
  %
-% This version allows both short (single-character) options
-% and GNU-style long options. It also has the GNU extension
-% of recognizing options anywhere in the command-line, not
-% just at the start.
+% This version allows both short (single-character) options and GNU-style long
+% options. It also has the GNU extension of recognizing options anywhere in
+% the command-line, not just at the start.
  %
  % To use this module, you must provide an `option' type which
  % is an enumeration of all your different options.
@@ -51,21 +50,21 @@
  %   - maybe_string_special
  %   - file_special
  %
-% For the "simple" option types, if there are multiple occurrences
-% of the same option on the command-line, then the last (right-most)
-% occurrence will take precedence.  For "accumulating" options,
-% multiple occurrences will be appended together into a list.
-%
-% With the exception of file_special, the "special" option types are
-% handled by a special option handler (see `special_handler' below), which
-% may perform arbitrary modifications to the option_table.  For example,
-% an option which is not yet implemented could be handled by a special handler
-% which produces an error report, or an option which is a synonym for a
-% set of more "primitive" options could be handled by a special
-% handler which sets those "primitive" options.
+% For the "simple" option types, if there are multiple occurrences of the same
+% option on the command-line, then the last (right-most) occurrence will take
+% precedence.  For "accumulating" options, multiple occurrences will be
+% appended together into a list.
  %
-% It is an error to use a "special" option for which there is no
-% handler, or for which the handler fails.
+% With the exception of file_special, the "special" option types are handled
+% by a special option handler (see `special_handler' below), which may perform
+% arbitrary modifications to the option_table.  For example, an option which
+% is not yet implemented could be handled by a special handler which produces
+% an error report, or an option which is a synonym for a set of more
+% "primitive" options could be handled by a special handler which sets those
+% "primitive" options.
+%
+% It is an error to use a "special" option for which there is no handler, or
+% for which the handler fails.
  %
  % Boolean (i.e. bool or bool_special), maybe_int, maybe_string
  % and accumulating options can be negated. Negating an accumulating
@@ -81,6 +80,14 @@
  % contents into a sequence of words separated by white space, and interpreting
  % those words as options in the usual manner.
  %
+% Note that arguments following an option may be separated from the option by
+% either whitespace or an equals, `=', character, e.g. `--foo 3' and `--foo=3'
+% both specify the option `--foo' with the integer argument `3'.
+%
+% If the argument `--' is encountered on the command-line then option
+% processing will immediately terminate, without processing any remaining
+% options.
+%
  %-----------------------------------------------------------------------------%
  %-----------------------------------------------------------------------------%


--------------------------------------------------------------------------
mercury-reviews mailing list
Post messages to:       mercury-reviews at csse.unimelb.edu.au
Administrative Queries: owner-mercury-reviews at csse.unimelb.edu.au
Subscriptions:          mercury-reviews-request at csse.unimelb.edu.au
--------------------------------------------------------------------------