option.dtd-- Visualization of ../absy/option.dtd

<!-- file description --><!-- This is an html rendering of the DTD file 
         option.dtd
     This Xhtml file is DYNAMIC, using Java-script.
     The semantically relevant contents of the initial state 
     of this file DOES DIFFER from the input. 
       (pis omitted)
     This file has been created by the command line
          <JAVA> eu.bandm.tools.dtm.Tool --PIs offOn --source  \
             ../absy/option.dtd --result  \
             ../absy/doc-files/option.dtd-rendered.html
     For info about this program see http://bandm.eu/metatools .
-->
<!-- collapse/expand --><!-- Click the opening symbols (angle brackets etc.) for collapsing/expanding.
     Click references for the definitions.
     Click element/attlist name position for the counterpart/next attlist. 
     Wait on a reference or on such a name for a tooltip.
     To control ALL declarations of one kind use these links:
     expand  all PIs  comments  PEs  
     collaps all PIs  comments  PEs  
-->
<!-- entity usage graph --><!-- =========================================================

 ========================================================= --->
<!-- element containment graph --><!-- =========================================================

 ========================================================= --->
<!--  --><!-- XML 1.1 DTD  SYSTEM = "../option/absy/option.dtd" -->

<!-- ?tdom --><?tdom doc - Source format for the Option compiler, for command line parsing, GUI input, 
 generation of documentation, etc.
 <br/> See also the 
<a href="http://bandm.eu/metatools/docs/usage/option.html">option compiler user documentation</a>.
 <br/>
?>

<!--  --><!-- 
This relative link could be used, if we were sure, that the generated documentation
 (Java API Doc and dtd rendering) will only be viewed in the context of the meta-tools 
 user documentation file trees:
<a href="{@docRoot}/../usage/option.html">mt option compiler user documentation</a>. 
-->


<!-- ?tdom --><?tdom default private?>
<!-- ?tdom --><?tdom xmlns="http://bandm.eu/doctypes/option" ?>

<!-- %int --><!ENTITY % int 'NMTOKEN'>

<!-- %sorting --><!ENTITY % sorting '( 0AaB | 0ABa | AaB0 | ABa0 | AaB | ABa )'>
<!--  --><!-- 
    sort styles containing "0" = sort by short names,
       followed by those without short names
    position of "0"-character indicates position of numeric keys.
    sort styles not containing "0" = sort by long keys,
       followed by those without long names, finally numbers-only
    AaB means not respecting case
    ABa means respecting case
-->

<!-- ?tdom --><?tdom public optionlist?>
<!-- ?tdom --><?tdom doc optionlist Sequence of a collection of command line options, to
be compiled into GUI mask, online help method, parsing method, etc. 
(In several contexts, the sequential order is significant.) ?>
<!-- ?tdom --><?tdom doc optionlist@fragmentedLists Whether reperated option arguments may be continued
following some other option(s). ?>
<!-- ?tdom --><?tdom doc optionlist@setterFunctions Whether setter methods will be synthesized
for editing the value of an option instance ?>
<!ELEMENT optionlist  (printout_title?, (enumeration | option | comment)*) >
<!ATTLIST optionlist  defaultSorting %sorting; "AaB0"
                      fragmentedLists (yes|no) 'yes' 
                      setterFunctions (yes|no) 'no' 
                      hexadecimalIntegers (yes|no) 'yes'
>


<!ELEMENT printout_title (text)+>
<!-- ?tdom --><?tdom doc printout_title The text to be printed as a header line in the "usage()" function.
Can be specified for several languages. ?>

<!ELEMENT text (#PCDATA)>

<!ATTLIST text  lang  NMTOKEN #REQUIRED>
<!-- ?tdom --><?tdom doc text One translation into one particular language. 
(Its role and meaning depend on the enclosing context element.) ?>

<!ELEMENT desc (text)+>
<!-- ?tdom --><?tdom doc desc One description, in several languages. 
(Its role and meaning depend on the enclosing context element.) ?>



<!--  --><!-- =========================================================================== -->

<!ELEMENT enumeration (desc?, (enumitem)+) >
<!ATTLIST enumeration name NMTOKEN #REQUIRED>
<!-- ?tdom --><?tdom doc enumeration An enumeration type which can be used for several parameters of
 several options ?>
<!-- ?tdom --><?tdom doc enumeration@name  Used to refer to this enumeration when defining the type
 of option parameters ?>


<!ELEMENT enumitem (desc)? >
<!ATTLIST enumitem value      CDATA #REQUIRED
                   compilable NMTOKEN #IMPLIED
>
<!-- ?tdom --><?tdom doc enumitem One position in an enumeration type (represented by the enclosing
 context element). ?>
<!-- ?tdom --><?tdom doc enumitem@value  Text as which this item appears to the user, on the command line, in
 a GUI, etc. 
 It maybe not a valid Java identifier. In this case {@code @compilable} must be given. ?>
<!-- ?tdom --><?tdom doc enumitem@compilable  Text as which this item is realized in the generated code.
 It must be a valid Java identifier, and must be present if {@code @value} is not. ?>


<!--  --><!-- =========================================================================== -->

<!ELEMENT comment (text)+>
<!ATTLIST comment name  NMTOKEN #IMPLIED>
<!-- ?tdom --><?tdom doc comment Multi-Lingual text which separates groups of options and appears in 
 a GUI screen mask, etc.  Mostly used for further explanations and directives to the user. ?>
<!-- ?tdom --><?tdom doc comment@name  mangled into a variable name which gives access to the
 corresponding graphic sub-object  in the generated GUI class. ?>

<!--  --><!-- =========================================================================== -->

<!ELEMENT option (noGui?, isMeta?, desc, type, condition?) >  

<!ELEMENT noGui EMPTY>
<!ELEMENT isMeta EMPTY>

<!ATTLIST option name     NMTOKEN #IMPLIED
                 abbrev   NMTOKEN #IMPLIED 
                 required (yes|no) "no"   >
<!-- ?tdom --><?tdom doc option Definition of one particular option as it appears on a command line,
 in the GUI, etc. At least one of {@code @name} or {@code @abbrev} must be given! ?>
<!-- ?tdom --><?tdom doc option@name  the long name, entered in the commandline with two minus signs,
 like "{@code --help}". Must have more than one character. ?>
<!-- ?tdom --><?tdom doc option@abbrev   the short name, entered in the commandline with one minus sign,
 like "{@code -h}". Must have exactly one character. ?>
<!-- ?tdom --><?tdom doc option@required Says whether this option must be present on the command line. 
 Is used to synthesize  checking code. ?>

<!-- %simpletypes --><!ENTITY %  simpletypes '(int | float | rat | bool | string | uri | enum | enumset)'>
<!ELEMENT simpletypes (%simpletypes;)>

<!ELEMENT type ( (%simpletypes;)*, rep?   )>
<!-- ?tdom --><?tdom doc type Sequence of the types of all arguments of a particular option . ?>


<!ELEMENT int EMPTY>
<!ATTLIST int default    NMTOKEN #IMPLIED>
<!-- ?tdom --><?tdom doc int Describes one integer argument in an option's list of argument types. 
 Please note that negative ints cannot be entered at the beginnig of a repetition group
 due to parsing ambiguity. ?>
<!-- ?tdom --><?tdom doc int@default Default value in case the option is missing completely.
Must be verbatim valid Java source text. ?>

<!ELEMENT float EMPTY>
<!ATTLIST float default    NMTOKEN #IMPLIED>
<!-- ?tdom --><?tdom doc float Describes one floating point argument in an option's list of argument types.
(Floats can be translated to Java "float" or "double", controlled by an operation parameter. ?>
<!-- ?tdom --><?tdom doc float@default Default value in case the option is missing completely.
Must be verbatim valid Java source text. ?>

<!ELEMENT rat EMPTY>
<!ATTLIST rat default    CDATA #IMPLIED>
<!-- ?tdom --><?tdom doc rat Describes one rational number argument in an option's list of argument types. ?>
<!-- ?tdom --><?tdom doc float@default Default value in case the option is missing completely.
Must be verbatim valid Java source text, eg. a call to "rat.valueOf(..)" . ?>

<!ELEMENT bool EMPTY>
<!ATTLIST bool default    NMTOKEN #IMPLIED>
<!-- ?tdom --><?tdom doc bool Describes one boolean argument in an option's list of argument types. ?>
<!-- ?tdom --><?tdom doc bool@default Default value in case the option is missing completely.
Must be verbatim valid Java source text. ?>

<!ELEMENT string EMPTY>
<!ATTLIST string default    CDATA #IMPLIED>
<!-- ?tdom --><?tdom doc string Describes one string value argument in an option's list of argument types. ?>
<!-- ?tdom --><?tdom doc string@default Default value in case the option is missing completely.
Can be any string (without framing double quotes) which will be processed into a 
valid String constant. ?>


<!ELEMENT uri ((dirOnly | notDir)?, writable?) >
<!ATTLIST uri default    CDATA    #IMPLIED>
<!-- ?tdom --><?tdom doc uri Describes one uri value argument in an option's list of argument types. 
Is mostly used for file system positions / files.?>
<!-- ?tdom --><?tdom doc uri@default Default value in case the option is missing completely.
Must be verbatim valid Java source text. ?>

<!ELEMENT dirOnly EMPTY>
<!-- ?tdom --><?tdom doc dirOnly Only directories are valid values. ?>
<!ELEMENT notDir EMPTY>
<!-- ?tdom --><?tdom doc dirOnly Only normal files = not directories are valid values. ?>
<!ELEMENT writable EMPTY>
<!-- ?tdom --><?tdom doc writable The file or directory must be writable. ?>


<!ELEMENT rep ( (%simpletypes;)+, defaults?) >
<!ATTLIST rep kind     (plus|star) #REQUIRED>
<!-- ?tdom --><?tdom doc rep Describes a sequence of value types in an option's list of argument types which 
 can appear more than once. ?>
<!-- ?tdom --><?tdom doc rep@kind Whether the empty sequence is a valid input ("star", not "plus") ?>


<!ELEMENT defaults (v)+>
<!ELEMENT v (#PCDATA)>
<!-- ?tdom --><?tdom doc defaults gives the sequence of default values for a repetition group, is the
 option is completely omitted. The number of contained elements must be an integral
 multiple of the length of the containing repetion group. ?>
<!-- ?tdom --><?tdom doc v One single default value. Must be verbatim valid Java source text,
except for Strings, where it must be the unquoted String contents.
This includes wrapping a String constant in double quotes, but allows expressions. ?>

<!ELEMENT enum  EMPTY>
<!ATTLIST enum name NMTOKEN    #REQUIRED
               default NMTOKEN  #IMPLIED>
<!-- ?tdom --><?tdom doc enum  Refers to an Enumeration as the type of the value of an option's argument. ?>
<!-- ?tdom --><?tdom doc enum@name The name of the enum, for referring. ?>
<!-- ?tdom --><?tdom doc enum@default The enumeration item which shall be used as 
 default value, if the option is missing completely. The text must be the Java identifier,
 i.e. the  compilable version, not the command line version. ?>

<!ELEMENT enumset  EMPTY>
<!ATTLIST enumset name    NMTOKEN    #REQUIRED
                  default NMTOKENS   #IMPLIED>
<!-- ?tdom --><?tdom doc enumset  Refers to an Enumeration as the base type for a set type for 
 the value of an option's argument. ?>
<!-- ?tdom --><?tdom doc enumset@name The name of the enum, for referring. ?>
<!-- ?tdom --><?tdom doc enumset@default The enumeration items which make the set value be used as 
 default value, if the option is missing completely. The text must be a sequence of 
 Java identifiers, i.e. the  compilable versions, not the command line versions. ?>


<!--  --><!-- =========================================================================== -->

<!-- %primecondition --><!ENTITY % primecondition '(testequal| testgreater|optarg)'>
<!-- %conditions --><!ENTITY % conditions '((%primecondition;) | and | or | not)'>

<!ELEMENT condition (%conditions;) >
<!ELEMENT and       (%conditions;)+ >
<!ELEMENT or        (%conditions;)+ >
<!ELEMENT not       (%conditions;) >
<!-- ?tdom --><?tdom doc condition Enabling condition which "un-greys" the input fields of an option,
 if fulfilled. ?>
<!-- ?tdom --><?tdom doc and Conjuntive combination of two conditions for enabling an option. ?>
<!-- ?tdom --><?tdom doc or Disjuntive combination of two conditions for enabling an option. ?>
<!-- ?tdom --><?tdom doc not Negation of a condition for enabling an option. ?>

<!-- %testvalues --><!ENTITY % testvalues '(constant | optarg)'>

<!ELEMENT testequal (%testvalues;,%testvalues;)>
<!-- ?tdom --><?tdom doc testequal Enabling condition whether both arguments have the same numric value. ?>

<!ELEMENT testgreater (%testvalues;,%testvalues;)>
<!-- ?tdom --><?tdom doc testequal Enabling condition whether first argument is strictly larger 
 than the second. ?>

<!ELEMENT constant EMPTY>
<!ATTLIST constant value CDATA  #REQUIRED>
<!-- ?tdom --><?tdom doc constant Constant to test against some current option argument value,
for forming an enabling condition. Must be verbatim compilable Java source text. ?>

<!ELEMENT optarg EMPTY>
<!ATTLIST optarg option NMTOKEN #REQUIRED
                 number NMTOKEN "0"
                >
<!-- ?tdom --><?tdom doc optarg Reference to some option's current argument value, to test it in an
enabling  condition. ?>
<!-- ?tdom --><?tdom doc optarg@option The option from which the current argument value is taken. 
It is identified either by its long name or its short abbrev value. ?>
<!-- ?tdom --><?tdom doc optarg@number The argument of the option by its (zero-based) position index.
The value of this argument is taken for comparison. 
 (The argument values of a repetition group are currently not adressable; neither is its length.) ?>

<!--  --><!-- eof -->