#d2d 2.0 text using  mtdocpage  : webpage 

// ================================================================================
#title   #src!option! --- Standardized Command Line Parsing and GUI Editing
#htmlTitle bandm metatools "option"  --- Standardized Command Line Parsing
#lang en
// ================================================================================

#tableOfContents

// ================================================================================
#h1 #title Purpose and Way of Operation
// ================================================================================
#p
Purpose of the #src!option!  package is the parametrization of applications,
--- by command line parameters and/or by a graphical user interface (GUI).
#p
Historically, there have been several attempts for standardization in both areas, 
but no one has definitely prevailed.
The #src!option! package is our approach to automate both by source code generation.

#p
The #src!option!  compiler is realized by the class
#link ../api/eu/bandm/tools/option/Compiler.html #text <mt>.option.Compiler#/.
The required run-time code is in 
#link ../api/eu/bandm/tools/option/runtime/package-summary.html
#text <mt>.option.runtime#/.
#p
The compiler takes a specification (including documentation) of all options 
of an application, encoded in XML, and generates
#ldots 
#list
#i code for command line parsing,
#i code for the user help funtion "#src!usage()!" in different languages,
#i a "swing"-based graphic user interface for configuring these options,
#i integration into user documentation html texts
#i TO COME: an html- and ecma-script based gui.
#/list

#p
The central aim of this package is to treat different operating systems,
different ways for starting an application, different styles of use,
different languages, 
and differently socialized users #emph!transparently! and combinable.
#nl
On a first glance, one might assume the task to be rather trivial, but it is not.


// ================================================================================
#h1 #title Data Model and Description  Format
// ================================================================================

// ================================================================================
#h2 #title Historic Predecessors and Paradigms
#label txt_hist

#p
Historically there exist several standardizations for parametrization
of an application by #emph!comand line arguments!:

#list
#i
The old X-11  way, using long names with only one dash as a prefix,
like "#src!-option...!".
#nl
This style has recently been re-activated by #src!java/bin/...!.
No-one knows what good for ?!

#i
IEEE "posix #src!getopt()!",   
as implemented in nearly every programming language as a standard library.
It is documented in
the IEEE posix standard #link 0/www.opengroup.org/onlinepubs/9699919799/ #/link,
therein  esp. 
#link 0/www.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap12.html
#loc tag_12_01 #text Utility Argument Syntax #/link
and 
#link 0/www.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap12.html
#loc tag_12_02 #text Utility Syntax Guidelines #/link.
#nl
Since the posix specification is full of "shoulds and coulds", 
we daresay the implementations
do differ in many details, without having looked at all of them.

#i
The GNU extension "#src!getopt_long()!" allowing long option names with
#emph!two(2)!  minus signs as a lead-in. like "#src!--option...!"

#/list 
#p
See also the valuable discussions at
// https://web.archive.org/web/20090503075914/https://stackoverflow.com/questions/367309/which-command-line-commands-style-do-you-prefer (2014)
#link 0/stackoverflow.com/questions/367309/which-command-line-commands-style-do-you-prefe#/link
(2014),  

// 0/web.archive.org/web/20090503075914/http://catb.org/~esr/writings/taoup/html/ch10s05.html
#link http://catb.org/~esr/writings/taoup/html/ch10s05.html

#/link  and
// https://web.archive.org/web/20090503075914/http://www.gnu.org/prep/standards/html_node/Command_002dLine-Interfaces.html
#link www.gnu.org/prep/standards/html_node/Command_002dLine-Interfaces.html#/link

#p
Our approach basically follows #src!getopt_long(),!but goes beyond  w.r.t. 
typing and type checking of the options' parameters.


// ================================================================================
#h2 #title General Data Model
#label txt_generaldatamodel
#p
The terminology in this area has grown historically, and many words are 
heavily overloaded.
We use in the following:
#list
#i "Parametrization" for the total configuration information for one certain
instantiation of an application.
#i "Option" for the different syntactical parts of such a parametrization,
as identified by a name (long and/or short). On a command line, these options
can be permuted and are recognized by the lead-in  minus sign character.
#i "Argument" for the concrete 
data related to a certain option in a certain parametrization.
In case of the commmand line interface, this can be e.g. a list of integers following 
an option name.
#/list

#p
The main issue with our data model is that it is more abstract than 
merely the command-line oriented. It shall serve for different
representations, text as well as gui, which makes the
task non-trivial. From this, the most important consequences  in the following 
model are #ldots
#list
#i 
the choice between presence and absence of a certain option exists by the most
trivial means in every  command-line version (simply leave it out!)
but must be realized explicitly in a gui version.
#i
a sequential order of the options' value definitions exists 
naturally with a using a command-line input, but is hard to express 
in a gui version.
#/list

#p
The resulting underlying data model can be more easily described following
the command-line version:

#list
#i 
any application instantiation is determined by 
   #list 
   #i the identity of the application,
   #i and a concrete parametrization
   #/list
#i 
the concrete parametrization has to follow the parametrization specification for this
application.
#i
the parametrization specification defines a collection of #emph!options!,
together with the types of their #emph!arguments!.
// FIXME #ii  --> knallt in "liftAllDirectors()"
//#p
#i
each option has for identification purpose
   #list 
   #i a short name only, made up from one(1) character,
   #i or a long name only, 
made up from at least two(2) characters, the first of which  
      must be a letter, followed by letters or digits,
   #i or both of them.
   #/list
The short name character may not be a whitespace or a minus sign.
The long name may contain minus signs, but not at first position.
#i
both names must be unique among all options of a certain application.
#i
each option is assigned a sequence of data types for its arguments.
#i
in a concrete parametrization, the option is represented in the command line text 
   #list 
   #i either by one(1) single "minus-sign" character "-" = 0x2D, followed
      (directly, without intervening whitespace) by the options's short name, 
   #i or by two(1) of these "minus-sign" characters, followed
      (directly, without intervening whitespace) by the options's long name.
   #/list
(This corresponds to the "#src!getopt_long(...)!" function in GNU.)
#i
Both representations are followed by a sequence of the representations of the 
option's arguments, which may be more than one, according to the
option's specification. An #emph!empty! list of arguments is only
possible as an exception, see #ref txt_single_boolean_argument.
#i
The representations of the single arguments are separated by whitespace.
#i
Each option can appear (conceptually/semantically) 
#emph!at most once! in each concrete parametrization.
This is in contrast to the other models mentioned in #ref txt_hist,
but is compensated by the possibility to give multiple #emph!arguments! instead.
(But see #ref txt_fragmented  for continuing the list of a "repeting group" 
by a second appearance of the option name.)
#i
The sequential order of options as they appear on a command line 
is never significant.
#nl
(This is a severe difference to many other command line systems, but is unavoidable, since
in a gui there is no corresponding notion of sequential order. At least not a 
natural one !-)
#/list

// ================================================================================
#h3 #title Data Types for Arguments
#label txt_datatypes

#commentchar\
#p
The data type assigned to each option can be defined by the
following grammar:
#source
    simpletypes = int | float | rat | string | bool | enum | enumset | specialtypes
    specialtypes = uri // more to come: | file | action | ...

    type = simpletypes*, rep?
    rep = RepKind, simpletypes+ 
    RepKind = star | plus 
#/source
#commentchar/
#p
The sequence of arguments of a certain option  must comply to the sequence of types
as specified.
#p
The types and corresponding arguments contained in the "#src!rep!" construct
are called "repeting group" in the following. This group may
be repeated arbitrarily often. It needs to appear at least once
in the "#src!plus!" case, and can have the length zero in the "#src!star!" case.

/* ====
#p
The data type "char" is #xemph!deprecated!: It is complicated enough to get
the intended value for a #src!string! type argument without too much harm 
through the command-line/shell/system-exec-call pipeline.
This is nearly impossible for many special characters (backslash, single quote, etc.).
So taking a character from the input string #emph!verbatim! as the representation 
of an argument of character type is not a good idea, -- better encode it as
integer value, which may be even input in hexadecimal format. FIXME MEHR
== */

// ================================================================================
#h3 #title Positional Options
#label txt_positional_options
#p
Concerning the command line parsing, there are some further rules for
modeling the historic behaviour:
#nl
The posix standard and other publications describe the syntax of a certain
application instantiation  
(e.g.
#link 0/www.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap12.html
#loc tag_12_01 #top#text here #/link) frequently by examples like

#source
utility_name[-a][-b][-c option_argument]
    [-d|-e][-f[option_argument]][operand...]
#/source
#p
Therein "#src!utility_name!" corresponds to our notion of "application",
and "#src!option_argument!" is nearly the same as with us.
#nl
Now "#src!operand!" are all these tokens on the commandline following the
last option, if any,  which (1) are not not arguments to the preceding (last) option,
and (2) are not options themselves.
#nl
For us (2) it means, that their text does not start with
a minus-sign character.
(In posix they could also be explicitly declared not to be options 
by the special separator "#src!--!" which ends the option list. This case we do ignore.)

#p
These "operands" are parameters to the application, but are not options
in the sense defined so far.
But of course we want to treat all command line components in a unified way, and
we have to map them to some gui. 
Therefore we define some further rules:
#list
#i
An option can be idenfied by a short name which is one(1) single 
#emph!numeric ASCII digit!, i.e. taken from "#src!0!, #src!1!, #ldots, #src!9!".
In this case it represents a "#emph!positional option!" (This corresponds
to "operand" in the posix nomenclature from above).
#i
When after parsing all explicitly mentioned options there is still
character data in the contents of the command line, then this
data is considered to be represent arguments for positional options.
#i
All those positional options which have not yet appeared in the command-line
(by explicitly using there long or short name) are mapped
to this rest input data in ascending order of their short names.
#i
As long as there is any text left to be parsed as an option argument, 
the next positional option is recognized implicitly.
#i
From the last point it follows that a positional option 
#emph!may not have the empty type! for its arguments, #ldots
#i
and that none but the last positional option may have a repetiting pattern type
for its arguments. (Any non-last positional option with repeting type would
swallow all the rest of the command line, because there is no further
"minus-sign" to stop it! See #ref txt_parsingprocess below.)
#/list
#p
A standard way to support this historic way of parametrizing is to
give those positional parameters "speaking" long names, as in
#source 
   -m / --mode      : what to do with the files
   -C / --classpath : where the libraries are searched for 
   -0 / --inputfile
   -1 / --outputfile
   -2 / --logfile 
#/source

// ================================================================================
#h2 #title Input Data Format
#p
All option specifications must be contained in one single XML document.
This must be declared as 
#commentchar \
#source
<!DOCTYPE optionlist PUBLIC "+//IDN bandm.eu//DTD option//EN"  "">
#/source
#commentchar /

#p
The syntax of the input is defined by the dtd, see here
#link ../api/eu/bandm/tools/option/absy/doc-files/option.dtd-rendered.html
#text a linked rendering.#/text
// PRE20221011 file contained in the #link file_option_dtd.html
// #text APPENDIX: option dtd file#/link

#p#kind src 
The original of this dtd can be found at 
#link 3/eu/bandm/tools/option/absy/option.dtd 
#text <mt>/option/absy/option.dtd #/link

#p
The toplevel definition is 

#source
<!ELEMENT optionlist (enumeration|option|comment)+ >
#/source

// ================================================================================
#h3 #title Multilingual Text for Documentation
#p
A text element type is employed ubiquituously  for multi-lingual documentation:
#suppressVerbatimCommandCharWarning 2
#source
<!ELEMENT text (#PCDATA)>
<!ATTLIST text  lang  NMTOKEN #REQUIRED>
#/source

#p#kind missing 
The "#src!lang!" attribute means the same as "#src!xml:lang!", and should be
replaced by this (as soon as all our tools support name spaces !-)

#p
The #src!lang!  attribute should be used following the same rules as
common practice with #src!xml:lang!, i.e. following 
RFC 4646 / RFC 4647 / "[IETF BCP 47], Tags for the Identification of Languages".
#p
(( Currently, we refer to ISO 639-2, as  listed e.g. in #cite isolanguage,
instead, because the URL for IETF BCP 47 as referred to at the end of 
#cite xml is BROKEN  !!))
#p
The set of supported languages may be chosen arbitrarily (including the
empty set), but it should be the same in all lists of #src!text! elements.


// ================================================================================
#h3  #title Enumeration Types
#p
Enumeration types which shall serve as data type for option
arguments must be declared according to #ldots 

#suppressVerbatimCommandCharWarning 2
#source
<!ELEMENT enumeration (desc?, enumitem)+) >
<!ATTLIST enumeration name NMTOKEN #IMPLIED>


<!ELEMENT enumitem (desc)? >
<!ATTLIST enumitem value      CDATA #REQUIRED
                   compilable NMTOKEN #IMPLIED
>
#/source

#p
Multilingual documentation text may be added to enumeration types as a whole,
and/or to every item separately. (As mentioned above, the support of the 
different languages should be consistent over all objects carrying doc texts.)
#p
The front-end appearance of an enumeration item (on the command line or 
shown in a GUI may be  an arbitrary string, containing
arbitrary character data, like "#src!<->!" or "#src!0abc!").
#nl
In cases they do not make up a valid Java identifier, the attribute 
#src!compilable! must be given, which is used in the generated #src!enum{..}! code instead.

#p#kind missing 
Currently only enumeration types may be declared.
We intend to add "type" declarations for general data type reusage.

// ================================================================================
#h3 #title Grouping Documentation Comments

#p
#src!comment!  elements can be interspered into the sequence of option declarations.
Currently, they only lead to additional text labels in the generated GUI.

#suppressVerbatimCommandCharWarning 1
#source
<!ELEMENT comment (text)+>
<!ATTLIST comment name  NMTOKEN #IMPLIED>
#/source

#p
(The "name" attribute shall be used later
to switch on/off a whole group of options in the GUI.)

#p#kind missing 
NOT YET OK ! (kills gui !-) // FIXME


// ================================================================================
#h3 #title Option Declarations
#p
In the following definitions it holds that #ldots
#list
#i
#src!desc!  is a multi-lingual description. It should cover the
meaning and the correct usage of the option. As mentioned above,
all text lists should support the same set of languages.
#i
The short name of an option (cf. above #ref txt_generaldatamodel)
is given by the attribute #src!abbrev!, the long name by the attribute #src!name!.
At least one of them must be specified.
#i
If #src!type! is omitted, the type of the option's arguments is the empty type,
e.g. there are no arguments.
#i
#src!condition! describes logic conditions on other options and their
arguments which must be
fulfilled to #emph!enable! this option, cf. #ref txt_enablingconditions below.
#/list

#suppressVerbatimCommandCharWarning 2
#source
<!ELEMENT option (noGui?, isMeta?, desc, type?, condition?) >
<!ATTLIST option name     NMTOKEN #IMPLIED
                 abbrev   NMTOKEN #IMPLIED
                 required (yes|no) "no"   >
<!ELEMENT desc (text)+>
#/source

// ================================================================================
#h3 #title Special Categories of Options
#p
Currently three special categories can be assigned to an option, as in
#source
    <option name='lang' required="yes">
    <noGui />
    <isMeta />
    <desc><text lang="de"> ....
#/source

#p
The category #src!noGui! prevents this option from appearing in the generated gui.
#nl
The category #src!meta! marks this option as adressing the outer execution conditions 
in which the "payload task" of the application will be performed, but does not
contribute to the definition of this task, to "what really to do".
#nl
The category #src!required! indicates that a command line input which does not
specify this option is invalid.
#p
#src!meta! and #src!noGui! appear together in many cases.
Typical examples are
#table
#tr#td language #td the user language in which gui and command line error messages
                    will be presented
#tr#td geometry #td initial window size of GUI etc.
#tr#td debug    #td level of verbosity / of debug facilities presented by the GUI

#tr#td version  #td trigger the Posix "version" behaviour, as described by
   #link 0/www.gnu.org/prep/standards/html_node/002d_002d_version.html
#tr#td gui      #td start interactive GUI inspite of complete payload options given in the
                 command line
#tr#td help     #td trigger the Posix "help" behaviour, as described by
   #link 0/www.gnu.org/prep/standards/html_node/002d_002d_help.html

#tr#td clearParsistent #td clear from the machine's the persistency cache all
memorized data related to this application.
#/table

FIXME LINK
#nl
(For instance, #link 1/DocumentedDistribution2#/link has an own, dedicated way of presenting
the value of the #src!language! option in the GUI, namely as drop-down in the
ubiquituous menu line, supporting flags, and #src!clearPersistent! as a 
function in the help menu. Therefore these options (and others) do appear in the GUI,
but automated generation is suppressed by #src!noGui!.)
#p
All non-meta arguments refer to the definition of the payload task.
A boolean flag in the model reflects the fact that such options are present.


// ================================================================================
#h3 #title Types
#p
Basically each option can have arbitrarily many arguments.
The prefix of the argument sequence has to follow a first sequence of
types, the rest of the arguments can follow  a repeated pattern of types.
By this means argument lists of varying length can be specified.
#nl
Currently "optional" arguments are #emph!not! supported, therefore after every
option name for each declared argument type an external value representation must follow
in the command line input text.
(Thereis only one exception, see below #ref txt_single_boolean_argument#/ref).

#suppressVerbatimCommandCharWarning 1
#source
<!ENTITY %  simpletypes '(int | float | rat | bool | string | uri 
                          | enum | enumset | action)'>
<!ELEMENT simpletypes (%simpletypes;)>

<!ELEMENT type ( (%simpletypes;)*, rep?   )>
<!ELEMENT rep ((%simpletypes;)+, defaults?) >
<!ATTLIST rep kind     (plus|star) #REQUIRED>
#/source

#p
Only the #src!enum! and #src!enumset! type identifiers have a required attribute, namely the name
of the enumeration declaration it refers to.
#p
All option arguments are parsed into a variable with the intuitively
corresponding Java type. For #src!rat! the #mt  library type 
#link 4/util/Rational.html#text Rational#/link  is used.


#suppressVerbatimCommandCharWarning 9
#source
<!ELEMENT int EMPTY>
<!ATTLIST int default      NMTOKEN #IMPLIED>
<!ELEMENT float EMPTY>
<!ATTLIST float default    NMTOKEN #IMPLIED>
<!ELEMENT rat EMPTY>
<!ATTLIST rat default    NMTOKEN #IMPLIED>
<!ELEMENT bool EMPTY>
<!ATTLIST bool default     NMTOKEN #IMPLIED>
<!ELEMENT string EMPTY>
<!ATTLIST string default   NMTOKEN #IMPLIED>

<!ELEMENT enum  EMPTY>
<!ATTLIST enum name        NMTOKEN #REQUIRED
               default     NMTOKEN #IMPLIED>
<!ELEMENT enumset  EMPTY>
<!ATTLIST enumset name    NMTOKEN  #REQUIRED
                  default NMTOKENS #IMPLIED>

<!ELEMENT uri EMPTY>
<!ATTLIST uri default      NMTOKEN #IMPLIED>
<!ELEMENT action EMPTY>
<!ATTLIST action name      NMTOKEN #IMPLIED>
#/source

// ================================================================================
#h3 #title Default Values
#label txt_defaultvalues
#p
Each single argument #emph!may optionally! be given a #emph!default value!. 
This value will be used as initial value for the corresponding fields of the model
class (#ref txt_modelclass_api#/ref).
#p
Please note that the default value must #ital!verbatim! be 
a #emph!valid Java expression! for initializing a field of this type. 
(Only String values are given as the string's contents, ie. like typed
on the command line.)
The check for correctness is
left to the subsequent application of the Java compiler.
Regrettably, this may show technical details to the user when displaying the
option definitions by #src!usage()!.
(For an argument of rational type the default value must be something 
like #src!Rational.valueOf(1,4)!, -- the compiler imports this class into the
visible name space if necessary.)
#p
With #src!rep! elements the situation is more complicated: 
First method: the elements which represent the single
simple types of the repeated type pattern can each be given their own
default, as described above.
They define the default values for any newly created instance of the
Java class, which is generated to represent this repetion group.
One or zero repetition groups (with these values) are created implicitly.
depending on "star" or "plus" flavour.
#p
Second method: the #src!rep! element itself may be given a #src!default! element,
consisting of a sequence of #src!v! elements, which initialize one of the
repeated primitive arguments each.
The text values must correspond to the repeated types and must be an integral
multiple of the repeated sequence.
#p
For example, the following default declaration leads to three instantions of the argument
pattern:
#source
<option name="vle">
   <desc><text lang="en">variable length default example</text></desc>
   <type>
     <int default="0"/>
     <rep>
       <int/>
       <string/>
       <defaults>
         <v>1</v>   <v>"c"</v>
         <v>1+1</v> <v>"d"</v>
         <v>3</v>   <v>"\n"</v>
       </defaults>
     </rep>
   </type>
</option>
#/source
#p
Again, type and syntax errrors are left to the Java compiler.
(Here also String types must be verbatim valid Java source, including the double quotes.)

// --------------------------------------------------------------------------------
#h3 #title Special Empty Type
#label txt_single_boolean_argument
#p
An option with no argument at all carries as only semantics its presence or
absence on a command-line input.
Historically, they are often called "switches" or "flags".
#nl
But there is no natural equivalent to "presence" when using a GUI.
Therefore we decided above, that the mere presence or absence of
an option with additional parameters 
#emph!should better not! carry any semantics. Instead, the
parameters should be given a default value which indicates their
"absence" in the application's logic.
#p
Since nevertheless parameter-less "switches" are often indispensable, 
we define a dedicated default value for boolean arguments
named "presence", and implicitly give every "empty type" #ldots
#source  
  <option abbrev="x"><desc><text lang="en">a simple switch</text></desc>
    <type/>
  </option>
#/source  
#p
#ldots the meaning of something like   #ldots
#source  
  <option abbrev=="x"><desc><text lang="en">a simple switch</text></desc>
    <type><bool default="presence"/></type>
  </option>
#/source  
#p
The value "presence" is virtual and cannot be used explicitly by the user.
On later parsing it will result to a default value of "true" if the 
option is present, and of "false" if not (thereby definining also the actual value
to "false"!). This is the only case of an #emph!optional argument! !
#nl
So these all are valid command lines:
#commentchar\
#source  
  applic                    // leads to x = false
  applic -x                 // leads to x = true
  applic -x false           // leads to x = false
  applic -x true            // leads to x = true
#/source  
#commentchar/

#p
The explict argument may turn out useful when a command line is constructed
programmatically.
Its price is, that the #emph!compactification of one-character flags! as known by Posix
cannot be supported:

#source  
  -abc 
#/source  
#p
#ldots  could be interpreted as three switch keys "a", "b", "c", but
#source  
  -stu
#/source  
#p
#ldots
would be the explicit value "true" for the switch key "s", followed by a parsing 
error ("superfluous argument input 'u'").


// ================================================================================
#h3 #title Enabling Conditions
#label txt_enablingconditions
#p
Some options do only make sense in certain modes of operation, as defined
by other options.
For convenience, this can be indicated by a GUI e.g. by disactivating the
input widgets for a currently not applicable option.
#p
In our model, each option can be assigned an 
"enabling condition", according to the following grammar:
#source
  Condition ::= PrimeCondition | CompoundCondition
  CompoundCondition ::= not Condition | and (Condition)+ | or (Condition)+
  PrimeCondition ::= Optarg | testEqual TestValue TestValue | testGreater TestValue TestValue 
  TestValue ::= constant String | Optarg
  OptArg ::= option Ident (Number)?
#/source
#p
(This is a mere symobolical representation; for the real grammar see 
#link ../api/eu/bandm/tools/option/absy/doc-files/option.dtd-rendered.html
#text the DTD#/text.)
// PRE20221011 #link file_option_dtd.html #text the DTD#link).

#p
So (1) it can be tested whether a certain argument of a certain option is equal to
or greater than a constant value or some other argument, and (2) these 
tests can be combined by standard logical operators.
#p
Please note that there should be #emph!no cyclic dependencies!, because then
the current, straight-forward implementation of the GUI could run into
a dead lock.


// ================================================================================
#h2 #title Survey on Features and Design Decisions Compared to Predecessors
#p
The following list tries to summaries the design decisions of #mt  options, which
partly differ, partly follow the above-mentioned preceding approaches 
(see #ref txt_hist).

#list
#i Long names must be completely written out; a unique prefix does #emph!not! suffice.
#i Long names may contain the minus character "-".
#i Several names of "switches" (with no arguments) #emph!cannot! be aggregated into one input
token.
#i Each option can have a sequence of more than one argument, the #emph!type! of which
must be fixed. A trainling subsequence can be repeated.
#i Options as such may only appear once, but more than once to prolongate such a repetition list.
#i The sequential order of options on the command line does #emph!not! have
any significance.
#i The presence or absence of an option on the command line should #emph!not! have
any significance, iff the option has arguments.
#i Options without arguments (standing just for their presence or absence)
can be specified with an optional explicit boolean type.
#i "Operands" are called "positional parameters" and can alteratively be
specified by their names or by an abbreviation, which is a decimal digit.
#i Relevance of options can be defined dependent on the values of some arguments of 
other options. In the GUI, this is reflected by active/inactive input fields.

#/list

// ================================================================================
#h1 #title Operation of the Tool and the Generated Code
// ================================================================================

// ================================================================================
#h2 #title Compiler for Model and Gui Code
#p
The #src!option!  compiler is realized by the 
class
#link ../api/eu/bandm/tools/option/Compiler.html #text <mt>.option.Compiler#/.
#nl
Its run-time code is in 
#link ../api/eu/bandm/tools/option/runtime/package-summary.html
#text <mt>.option.runtime#/.
#p
The compiler is called like
#source
 $(JAVA) eu.bandm.tools.option.Compiler <inputFile> \
            <packageName><modelClassName><guiClassName> \
            <rootOfJavaSources>
#/source
#p
The input file is an XML file, as described above. The compiler generates
one or two(2) Java source files: the model class source is generated
anyhow, with the given name, in a package with the given name. The source
is written to the file system, relative to the given root, descending the
directory levels which correspond to the package name.
#p
The gui class is only generated if the gui class name is #emph!not the empty string!.
#p
In the following examples, let "#src!MyOpts!" be the name of the model class, and
"#src!MyGui!" be the name of the GUI class.


// ================================================================================
#h2 #title Generated Model Code 
#label txt_modelclass_api
#p
The generated model class  #src!MyOpts! will offer the following API:

#list
#i 
#src!public MyOpts()!
#nl
This constructor creates a new model instance. The field values which
correspond to the options' arguments (see next list point) are initialized
by the #emph!default values!, as specified in the XML file (#ref txt_defaultvalues#/ref).
#i 
#src!parse(String[], MessageReceiver<SimpleMessage>)!
#nl
This method takes an array of strings (normally exactly that
what has been passed to #src!public static main(...)! as its method
argument!)
and performs the parsing process. Therein, the arguments for recognized
options will overwrite the intial default values. For all options not
appearing in the input, the default values will survive.
#nl
#bold Please note#/bold  that the values of the arguments after parsing should be
the only point where the presence or absence of an option is
reflected. The default values should be selected accordingly.
#nl
The message receiver
is needed for different kinds of warnings and errors. 
By counting critical errors the programmer can decide whether parsing failed:
#commentchar\
#source
  public static main (final String[] args){
    final MessageReceiver<Message> m0 = new MessagePrinter<Message>();
    final MessageCounter<Message>  m1 = new MessageCounter<Message>();
    final MessageTee<Message> m3 = new MessageTee<Message>(m0,m1);
    final MyOpts myOpts = new MyOpts();
    myOpts.parse(args, m3);
    if(m1.getCriticalCount()>0)
      System.exit(99);
    // ---- e.t.c.---
  }
#/source
#commentchar/
#p
#list
#i 
Let "#src!grmmpf!" be the long name of a certain option. 
#nl
Let the type of its arguments  be specified as a sequence of 
three types, with a trailing repeting group: 
#nl
  "int float string (REP * rat bool)".
#nl
Then the API will offer the following functions by which, after successful parsing
(or after turning the knobs of the gui, see below) the current argument values for
this option can be obtained:

#commentchar\
#source
public class MyOpt extends <mt>/options/runtime/Model {
   ...
public class MyOpt extends <mt>/options/runtime/Model {
   ...
   public int      get_grmmpf_0(); 
   public double   get_grmmpf_1(); 
   public string   get_grmmpf_2(); 
   public int      repcount_grmmpf();
   // repeting group starts counting arguments from zero again:
   public Rational get_grmmpf_0(int); 
   public boolean  get_grmmpf_1(int);

   // additionally indicating whether the option "grmmpf" did appear at all:
   // DEPRECATED, this SHOULD NOT be used!
   public boolean  has_grmmpf ;
#/source
#commentchar/
#p
In case a certain option does not have a long name, the short name
is taken for constructing these identifiers.

// ================================================================================
#h3 #title Setter Functions
#p
Whenever the generated option model class shall be used for representing 
configuration data / taks specifiations in a more advanced mode, e.g. programatically controlled,
the declaration
#source
   <optionlist setterFunction="yes"  >...
#/source
#p
will cause the compile to additionally generate setter functions which allow 
to change the options parameter values.
#p
#xemph Currently not yet supported!



// ================================================================================
#h2 #title Command Line Parsing
#label txt_parsingprocess
#p
The parsing of the options and their parameters may seem trivial,
but is not. This because different OSs are involved. The 

#link 0/www.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap12.html
#loc tag_12_01 #text ieee posix specification "Utility Argument Syntax"#/link  
(esp. point 2.b, to make it more confusing!) uses the notion of
"argument string" for the portioning already done be some "shell" program,
before the #src!getopt()!-code starts working.
This is the portioning reflected by the array structure of
"#src!static main(final String[] args)!" in case of Java.
#p
This also has to be considered here, as well as the different 
shell processors and system services which #emph!lead to! the appearance
of this "array of strings" or "argument strings".
#p
We took a brute-force approach, what is always a good thing to do
when things get toooo historically determined.
So we found the following rules, which might appear somehow rude, but do
ensure portability:
#p
#list
#i
All "argument strings" are concatenated into on long string, separated
by whitespace.
#nl
All withespace appearing in the #emph!inner data! of such an argument string
is temporarily masked and is not recognized as "whitespace" in the following
algorithm!
#i
Every option on the command line 
begins with one or two "minus-sign" characters, followed
by its short name or its long name, resp., and some whitespace.
#i
A long name must appear completely, in contrast to other
approaches, unambiguousness of some prefix is #emph!not sufficient!. 
This is a difference to most Posix interpretations 
and done to simplify future addition of new options.
#i
The following text is separated into tokens, as defined by the appearance
of (unmasked) #emph!whitespace!
#i
Each token is parsed as an argument for the current option. The parsing
is determined by the type declared for this argument.
#i
Whenever a token #emph!cannot! be parsed as a denotation for the expected type,
an error is generated.
In this case the parsing process skips all tokens not starting with
a minus-sign character, and tries to continue with the parsing of 
the next option.
#nl
(Mostly this is only done to inform the user about subsequent, further syntax errors.
The result of the parsing so far must in most cases be discarded, anyhow.)
#i
When the start of the repeting pattern of the current option's argument
types is reached, and the next token does not start with a minus-sign, then
a sequence of further arguments according to the repeting pattern
is recognized and parsed, as described.
#i
If the first token to read #emph!does start! with a minus-sign, it is
assumed to be the start of the next option.
#i
If the repeting group is of "plus" flavour, it must be entered at least once.
Otherwise an error is generated, and parsing is continued with the
next option, as described above.
#i
From this simple rule for detecting options, i.e. the end of the repeting
arguments, it follows that #emph!negative numbers! cannot stand at the
beginning of a repeting group of arguments (only of the very first in
a "plus"-flavour repeting group!)
#i
When, contrarily, the arguments of an option are completely parsed, and
there is no repeting group, and the next input token does #emph!not start!
with a minus-sign character, then the explicit options are considered to
be complete, and the positional options start parsing.
#i
The parsing process continues as described, but the 
positional option with the lowest digit as its short name which has not
yet appeared in the command line (by explit mentioning or implicitly, because
this process will continue looping until all input is consumed!) is
substituted, i.e. assumed to be recognized just before.
#nl
The parsing process continues as described above, with the difference that
from now on minus-sign characters will no more
be significant, i.e. no more explicit option names will be recognized.
#nl
When the input to some options is found in the positional way, but other
positional options are given by explicit keys ("mixed input"), a warning is issued.
#i
When all input is consumed, the parsing process terminates.
#i
When (a) the arguments of the last option are completely parsed, 
(b) no un-parsed input ("garbage") is left over on the input line, and
(c) all options marked as "required" have been defined, then the parsing process 
was successful.
#i
The caller must check the message receiver if any error messages have been emitted
during parsing. If so, the parsing result should be discarded.
#/list

#p
This description show clearly, that the "positional options" do make the
parsing process much more complicated. They are only supported
for historic reasons, and should be abandoned when the calls for
applications are generated e.g. by make scripts. The difference is small, like
#source
    d2d --path $(HOME)/lib/documents $(PWD) --mode text2xml  source.d2d tmp.xml
... vs ...
    d2d --path $(HOME)/lib/documents $(PWD) --mode text2xml  -0 source.d2d -1 tmp.xml
#/source

// ================================================================================
#h3 #title String Arguments containing Whitespace
#p
The parsing algorithm recognizes only the "gaps" between the 
"argument strings" as separating whitespace, i.e. the gaps between
the string objects which make up the #src!string[]! passed as an argument to 
#src!static void main(String[])!. All whitespace contained in one such string
is masked and treated as character data. Therefore it will end up in the
value of an option argument whenever it can be parsed as such, 
e.g. whenever the type of this argument is "string" (or "character" or
"URI", which special cases can be ignored in the context of this discussion).
#p
The string array which arrives at the start of #src!main()! is 
constructed by the co-operative efforts of some shell program and
a call to the system service "#src!exec!", or sim.
Therefore it depends on #emph!their correct handling!, whether some
whitespace can enter the value of an options argument. Consequently, this
is out of scope w.r.t. the #src!option! module! Puhhhh!!!
#p
E.g. normally any input in "double quotes", like
#source
   $(JAVA) eu.bandm.Application  --title "this is a headline with whitespace"
#/source
#p
will stimulate #src!bash! or any other shell-like program, to pass
the contents (sic!) of these quotes as one single argument string to the
system call named "#src!exec!", or sim. Therefore it will arrive as
#emph!one(1) single token! at the #src!option! parser.
But the concrete details of these rules may be very complicated and os-specific.

// ================================================================================
#h3 #title Representing Boolean values
#p
As Boolean values are recognized (not regarding case):
#source
   t true 1 +   --> true
   f false 0 -  --> false
#/source

// ================================================================================
#h3 #title Multiple File Names, e.g. for "class path"
#p
It is an old habit of UNIX programs to concatenate file names using
a colon "#src!:!" in the value of arguments which represent more than
one position in the file system.
#p
We recommend using multiple arguments instead. This is os-independent, because
some shells will try to resolve the colon as a separator for "drive letters".
#source
 For
   $(JAVA) eu.bandm.Application --libraries a.b:c.d:e.f 
 better 
   $(JAVA) eu.bandm.Application --libraries a.b c.d e.f 
#/source

// ================================================================================
#h3 #title Argument values starting with a "minus-sign" Character
#p
Please note that the fact whether a token starts with a minus-sign character
is evaluated only whenever a new option #emph!may! start. As long
as the type specification of the arguments of the current option still
requires character data, a minus-sign never is interpreted as a new
option keyword lead-in.
#p
As soon as a parsing error occurs, input is skipped upto the next
minus-sign character, and a new option name is assumed to follow.
This does of course #emph!not! happen after the parsing of 
the positional option is entered!

// ================================================================================
#h3 #title Fragmented Lists 
#label txt_fragmented
#p
When constructing command lines automatically, parts of an option's repeting group
may come from different sources. In this case it may by helpful to allow
multiple occurences of an option, the arguments being concatenated. This is
activated by the declaration
#source
   <optionlist fragmentedLists="yes"  >...
#/source
#p
This will allow:
#source
   declaration:
     <option foo><type><int/><string/><rep kind="plus"><int/><bool/></rep></type> </option>

   command line
     --foo   3 "stringvalue"  3 true    --otheroption ... --foo 7 false 
#/source
#p
This fragmentation is only allowed at group borders. 
Each group must be defined completely in one particular appearance of the option.
Esp. the prefix of arguments before the first group must be given with the
first appearance as a whole.
#nl
(Fragmentation does never apply to values of type "EnumSet" etc. Inspite of being
a collection in themselves, these are treated as one single value which must be
specified in once.)


// ================================================================================
#h2 #title Help Function "#src!usage()!"
#p
As usual with unix programs, the compiler generates help functions
which list the options, the types of their arguments and the description texts
in various languages. Assuming the source file contains descriptions
for the languages #src!en!, #src!de! and #src!sv!.
Then the following functions will exist:

#commentchar\
#source
public class MyOpt extends <mt>/options/runtime/Model {
   ...
   public void usage_en (PrintStream p){...}
   public void usage_de (PrintStream p){...}
   public void usage_sv (PrintStream p){...}
   public void usage (String lang, PrintStream p){...}
   public void usage (PrintStream p){...}
    // defaults to a language chosen by random, only supplied for
    // historic reasons!
}
#/source
#commentchar/

// ================================================================================
#h2 #title Unparsing 
#p
The function
#source
public class MyOpt extends <mt>/options/runtime/Model {
   ...
   public String serialize (){...}
}
#/source
#p
delivers a textual representation of the state of the model which 
can be used for persistent storage and which will reconstruct this state
when submitted to command line parsing.
#p
It most cases it is also wise to insert it into the produced output, together with
the name of the programm, its version, the date, etc.,
as supported by 
#link ../api/eu/bandm/tools/format/java/CommentFormats.html 
#text <mt>.format.java.CommentFormats#/.

// ================================================================================
#h2 #title Usage of the GUI
#p
The generated GUI class is simply a specialization of 
#link 5/javax/swing/JPanel.html #text a swing JPanel#/link.
It contains on the left side (in a "grid bag layout") the short and long
names of the options, and on the right side a sequence of input widgets,
corresponding to the option's argument types.
#p
When pointing to the names, a tool tip will appear with the description of
the option in the current language.
#p
Before the GUI can be operated, i.e. edited by the user, it must
be initialized by the values taken from some well-defined model.
#nl
A command line parsing process may precede a graphic editing phase,
but thanks to the default parameters, this is not required.
#nl
Vice versa, after editing is complete, the values have to be transfered back
to a model instance, to be retrievable as described above.
#nl
For this the gui class offers the following methods:
#source
public class MyGui extends <mt>/options/runtime/Gui {
  ...
  public static MyGui makeInstance(MyOpts model)
  public void model2view(MyOpts model)
  public void view2model(MyOpts model)
  ...
}
#/source
#p
The JPanel can be integrated into arbitrary swing containers and
programming contexts. 
#p
FIXME see for example DocumentedDistribution2
#p
FIXME error handling of the Gui
#p
FIXME non-gui parameters / OBEN: meta-parameters
#list
#i --geometry  (initial window size)
#/list


#p
For convenience, it offers (currently just one) default method which 
runs a dialog, detects input errors and adds some "meta-"buttons to the
option panel.
There are more than one call patterns to this method, supplying
different default arguments. The user language must always be given explicitly.
#nl
The result indicates whether the user ended the dialog with the "ok" or
the "cancel" button.

#source
public class MyGui extends <mt>/options/runtime/Gui {
  ...
  public boolean editGraphically(String userlanguage)
  public boolean editGraphically(String userlanguage, int width, int height)
  public boolean editGraphically(String userlanguage, int width, int height,
                                 boolean languageSwitchable)
  ...
}
#/source

#p
The example from above can thus be continued 

#commentchar\
#source
     final MyGui myGui = MyGui.makeInstance(myOpts);
     final boolean userPressedOk 
       =  myGui.editGraphically("en", 400, 500);
     if (!userPressedOk){
       System.err.println("Leaving program due to user's cancellation.");
       System.exit(99);
     }
     final MyOpts editedOpts = new MyOpts();
     myGui.view2model(editedOpts);
     // perform task according to the settings in "editedOpts"
     // of course, the "old" model could be re-used to store 
     // the new parametrization, by performing
     //        myGui.view2model(myOpts);

#/source
#commentchar/

// ================================================================================
#h2 #title Automated Integration of Options' Descriptions into HTML Based Manuals
#label txt_docu_generation
#p
The d2d/xml/xhtml-based documentation system, as employed in the doc
of #mt itself, can integrate a user-readable form of the
options specification as a table into the html text.
This is part of the "#src!d2d_gp!" application architecture,
and described in more detail with the module
#link d2d.html#loc txt_d2d_gp_technicalDoc#text technicalDoc.commandLineDoc#/link.
#p
The d2d-frontend representation works like 

#suppressVerbatimCommandCharWarning 2
#source
#cmdline_option_documentation ../../src/eu/bandm/tools/umod/umodOptions.xml 
    #lang en 
#/source
#p
This corresponds to the xml element 
#source
      <cmdline_option_documentation>
        <url>../../src/eu/bandm/tools/umod/umodOptions.xml</url>
        <lang>en</lang>
      </cmdline_option_documentation>
#/source
#p
The rendering process as defined by "#src!docpage_xml2xhtml.xsl!"  
will create a nice table with names, descriptions, type patterns and
default values.
#p#kind src 
The code is contained in 
#link 3/eu/bandm/tools/doctypes/d2d_gp/docpage_xml2xhtml.xsl
#/link
#p
The result can be seen e.g. in #link umod.html  #loc txtcommandlineoptions
#text the #src!umod! documentation#/link.

#p
The sequential order of the print-out can be defined indenpendently of the 
source text by 
#source
<optionlist defaultSorting="0AaB"> ....

with 

<!ENTITY % sorting '( 0AaB | 0ABa | AaB0 | ABa0 | AaB | ABa )'>
#/source

#p
The meaning of these "sort strategies" is:
#nl
#src!AaB! -> treat lower case and upper case equivalently 
#nl
#src!ABa! -> first upper case, then lower case (like the old-fashioned ASCII table !-)
#nl
Sort strategy contains "#src!0!" -> sort according to abbreviations(=one character names);
afterwards all those which do not have an abbreviation. The position of the "#src!0!" is
the position of the numeric abbreviations = positional parameters. 
#nl
Sort strategy does not contain "#src!0!" -> sort according to long names.
Afterwards all those which do not have a long name.


#eof