Model (BandM metatools API doc)

java.lang.Object
- eu.bandm.tools.option.runtime.Model

Direct Known Subclasses:: InsertOverprintOptions, ToolOptions

public abstract class Model
extends Object

The common base class of all models generated by the the option compiler, as implemented in Compiler.
It contains

the basic parsing methods, which are called by the generated code,
and some auxiliary methods callable by the user after successful parsing.

The fundamental control flow is a "ping-pong" between generated code and runtime library:

  parse(String[], msgr)
    V
    parse(String, msgr) // blanks are escaped !
      |
      V                   /
     main parsing loop   <=========================================   \
      |                   \   (recover after error!)                  \
      V                                                               \
     -------------------------------------- GENERATED CODE            |
    |   parseName           /parseAbbrev/parsePositionals             |
    |      V                          |                               |
    |      parse_              |                               |
    |         |   |   |               |                               |
     ---------------------------------|---------------------          |
              |   |   V               |                               |
              |   V   parseEnum       |                               |
              V   parseInt            |                               |
              parseInit   |           |                               |
                          V           V                               |
                          T_ERROR     ERROR_UNKNOWN_NAME              /
                              \         \                            /
                               \_________\_________>THROW exception /

Please not that the lexer process = the tokenization (implemented by getOptToken() and getNextArgToken()) is driven by the top-level parsing process: A long-name option key and an argument token are all characters up to the next whitespace (or end of input), but a short-name option token is only the next character.

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`protected class`	`Model.ExcDuplicate` Thrown if option appears more than once.
`protected class`	`Model.ExcFinish` Thrown if "skip to next option" error recovery reaches end of input.
`protected class`	`Model.ExcNoData` Thrown if argument is needed, but end of line reached.
`protected class`	`Model.ExcNoData_allowed` Thrown if end of line reached when new positional option could start.
`protected class`	`Model.ExcUnknownOpt` Thrown if option name / abbrev is unknown.
`protected class`	`Model.ExcWrongType` Thrown if argument is of wrong type.
`class`	`Model.Pre20220613`
`class`	`Model.SeemsToWorkForLinuxAndSomeWindowsVersions20220613`

Field Summary

Fields
Modifier and Type	Field and Description
`protected boolean`	`boolresult` Result of trying the boolean parser.
`protected int`	`curArg` Number of the argument currently being parsed.
`protected int`	`curArgGroup` Number of the repeting group which is under parsing, or `-1` in case the fixed part is currently being parsed.
`protected String`	`curOption` Human readable identification of the option currently being parsed.
`CatalogByString`	`descriptions` Filled in by generated code.
`protected static Rational`	`dummyRat`
`boolean`	`hasNonMetaOptions` Reflects whether there are any payload-options in the parsed command line.
`protected int`	`inputlength` Length of `inputstring`.
`protected String`	`inputstring` Input concatentated into one single string, only input data for the parsing process.
`protected Matcher`	`matcher` Re-used matcher for the input, once loaded with string data, then re-linked to different patterns.
`protected Messages`	`messages`
`protected @Opt String`	`nextAbbrev` Written to by `updateOptTokens()`
`protected @Opt String`	`nextArgToken` Argument token, written be `lookForArgToken()`, when such a token could be parsed, and read by type-specific scanners `parseInt()`, etc., and cleared again.
`protected @Opt String`	`nextName` Written to by `updateOptTokens()`
`protected boolean`	`optTokenValid` Whether an opt token has been consumed and stored to `nextName` or to `nextAbbrev`.
`protected Pattern`	`p_argRAUS` Pattern for arguments, ie sections without blanks, or only with BACKSLASH-ESCAPED blanks.
`protected static Pattern`	`p_hideblanks` Pattern to recognize blank characters, for escaping them prior to parsing.
`protected static Pattern`	`p_option` Pattern for option keywords (long and short).
`protected Pattern`	`p_rest`
`protected SimpleMessage.Generator<Location<String>>`	`parseErrorGenerator`
`protected boolean`	`positionalPhase` Set by runtime code for correct end-of-cmdline handling.
`protected boolean`	`positionalsExplicit` Set by generated code, whenever a positional option has already been set explicitly.
`protected boolean`	`positionalsFound` Set by generated code, whenever a positional option is set implicitly.
`protected StringBuilder`	`protocol` Text which reflects the parsing and interpretation process, for debugging only.
`protected eu.bandm.tools.option.runtime.Model.ShellAdapter`	`shellAdapter` can be changed by subclassing.

Constructor Summary

Constructors
Constructor and Description

Model()

Constructors
Constructor and Description
`Model()`

Method Summary

All Methods Static Methods Instance Methods Abstract Methods Concrete Methods Deprecated Methods
Modifier and Type	Method and Description
`protected abstract void`	`_finalCheck()` Callback, overridden by compiled code.
`protected abstract String`	`_getMissingParams()` Is overridden in the generated code and concatenates the "longest names" of all otions marked as required, but not present in the parsed input.
`protected void`	`ARG_ERROR(String msg)` Generate error message related to the current option, the argument number, and (possibly) the repetition group number.
`protected boolean`	`canReenterRepetitionGroup()` Returns only true if the next consumable input is not an option key (i.e.
`protected abstract void`	`checkActive()` The generated code will evaluate all conditions to activate/deactive options in the GUI.
`static String`	`descriptionKeyForCommentField(String name)` Generated MuLi-Catalog key to store a (multilingual) comment field.
`static String`	`descriptionKeyForEnum(Class<?> cl)` Generated MuLi-Catalog key to store the description of an enum type.
`static String`	`descriptionKeyForEnum(MetaClass cl)` Generated MuLi-Catalog key to store the description of an enum type.
`static String`	`descriptionKeyForEnumItem(Class<?> cl, Object item)` Generated MuLi-Catalog key to store the description of an enum item value.
`protected void`	`ERROR_plus()` Generate the error message that the repeting group of "plus" type is empty.
`protected void`	`ERROR_UNKNOWN_ABBREV()` Called from compiled code and the end of the switch between short optipn names.
`protected void`	`ERROR_UNKNOWN_NAME()` Called from compiled code and the end of the switch between long optipn names.
`protected void`	`ERROR(String s)` Only source of error messages.
`protected void`	`ERROR(String s, Object rest)`
`String`	`getInputString()` Get parsing input, maybe constructred from a String-array.
`String`	`getMissingParams()` Get String of missing parameters, is empty if none are missing.
`protected void`	`getNextArgToken()` Decodes next argument token to consume, if this has not yet been done.
`protected void`	`getOptToken()` Test whether next input is an option key token.
`String`	`getParsingProtocol()`
`protected void`	`lookForArgToken()` Decode argument token, advance input, set nextArgToken for further processing.
`abstract Model`	`makeDefaultInstance()` Overriden by the generated code to make a constructor call of the actual Model (sub-)class.
`void`	`parse(String[] args, MessageReceiver<SimpleMessage<?>> mr)` The main entry for setting all values according to some command line input, as reaching `public void main(String[])` from some `exec` system call.
`protected abstract void`	`parseAbbrev(String s)` Callback, overridden by compiled code, which realizes a switch over all one character option names.
`protected boolean`	`parseBool_optional()` Called by compiled code for "switch-type", argument-less options.
`protected boolean`	`parseBool_X()` Aux function, return whether the next token is a representation of a boolean value, and put the result into `boolresult`.
`protected boolean`	`parseBool()` Called by compiled code for required boolean arguments.
`protected char`	`parseChar()` Deprecated. To take a character value from the input text verbatim as an option arguments' value is not a good idea, because one never knows what the accidentally employed shell will do to special characters. Instead use an integer value (possibly with hexadecimal input format).
`protected <E extends Enum<E>> E`	`parseEnum(Class<E> enumclass)` Called by compiled code.
`protected <E extends Enum<E>> EnumSet<E>`	`parseEnumSet(Class<E> enumclass)` Called by compiled code. FIXME: only the "compilable" enumItem is parsed, not a possibly "uncomilable" @value.
`protected double`	`parseFloat()` Get the next argument token, parse it into a double value, invalidate the argument token and return the value.
`protected void`	`parseInit(String opt, boolean hasIt)` Called from compiled code when starting the parsing of the arguments for a recognized/accepted option key.
`protected int`	`parseInt_16or10()`
`protected int`	`parseInt()` Get the next argument token, parse it into an integer value, invalidate the argument token and return the value.
`protected abstract void`	`parseName(String s)` Callback, overridden by compiled code, which realizes a switch over all long option names.
`void`	`parseOneString(String s, MessageReceiver mr)` Central entry point in case the command line data is already packed into one single String, with escaped blanks.
`protected String`	`parseOneUri()` Called by compiled code.
`protected abstract void`	`parsePositionals()` Callback, overridden by compiled code, which calls one after the other the positional parameters.
`protected Rational`	`parseRational()` Get the next argument token, parse it into a rational value, invalidate the argument token and return the value.
`protected String`	`parseString()` Called by compiled code.
`protected void`	`putprot_option(String s)` Append the name of the option and set parentheses.
`protected void`	`putprot(String s)`
`abstract String`	`serialize()` Called to generate a String representation of the model's state.
`protected static String`	`serialize(boolean value)` Called by compiled code.
`protected static String`	`serialize(char value)` Called by compiled code.
`protected static String`	`serialize(double value)` Called by compiled code.
`protected static <E extends Enum<E>> String`	`serialize(E value)` Called by compiled code.
`protected static <E extends Enum<E>> String`	`serialize(EnumSet<E> value)` Called by compiled code.
`protected static String`	`serialize(int value)` Called by compiled code.
`protected static String`	`serialize(Rational rat)` Called by compiled code.
`protected String`	`serialize(String value)` Called by compiled code.
`protected void`	`skipToOption()` Skip input to next option token, if not already done.
`protected void`	`T_ERROR(String msg)` Generate error message on wrong argument type and throw the corresponding exception.
`protected void`	`updateOptTokens()` Decide whether long or short name, and store it to `nextName` or `nextAbbrev`.
`abstract void`	`usage()` The generated code will print the documentation text of all options, in the default language.
`abstract void`	`usage(String language)` The generated code will print the documentation text of all options, in the given language.
`protected void`	`WARNING(String s)` Only source of warning messages.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - shellAdapter
```
protected eu.bandm.tools.option.runtime.Model.ShellAdapter shellAdapter
```
    can be changed by subclassing.
  - messages
```
protected Messages messages
```
  - parseErrorGenerator
```
protected SimpleMessage.Generator<Location<String>> parseErrorGenerator
```
  - protocol
```
protected transient StringBuilder protocol
```
    Text which reflects the parsing and interpretation process, for debugging only. Can be retrieved after successful and erroneous parsing by getParsingProtocol(). The entering the parsing of an option with name "xxx" is indicated by "xxx(" and the recognized argument types follow, like "int", "string", etc.
  - descriptions
```
public CatalogByString descriptions
```
    Filled in by generated code. Needed by the GUI for dynamic tool-tip translation.
  - hasNonMetaOptions
```
public boolean hasNonMetaOptions
```
    Reflects whether there are any payload-options in the parsed command line.
  - inputstring
```
protected String inputstring
```
    Input concatentated into one single string, only input data for the parsing process.
  - inputlength
```
protected transient int inputlength
```
    Length of inputstring. For conveniece, because it is frequently used in Matcher set-ups.
  - curOption
```
protected transient String curOption
```
    Human readable identification of the option currently being parsed. Used for error message generation.
  - curArg
```
protected transient int curArg
```
    Number of the argument currently being parsed. This is relative to begin of the option's type list, or to the beginnig of the repeting group.
  - curArgGroup
```
protected transient int curArgGroup
```
    Number of the repeting group which is under parsing, or -1 in case the fixed part is currently being parsed.
  - p_option
```
protected static final Pattern p_option
```
    Pattern for option keywords (long and short). A short option key is one single minus, followed by one arbitrary (not-minus) character. A long option key are two minus characters followed by arbitrary many non-blank characters. The compiler level guarantees that long option names have more than one character. The short option names which are decimal digits denote positional parameters.
  - p_rest
```
protected final Pattern p_rest
```
  - p_argRAUS
```
protected Pattern p_argRAUS
```
    Pattern for arguments, ie sections without blanks, or only with BACKSLASH-ESCAPED blanks.
  - matcher
```
protected transient Matcher matcher
```
    Re-used matcher for the input, once loaded with string data, then re-linked to different patterns.
  - nextArgToken
```
@Opt
protected transient @Opt String nextArgToken
```
    Argument token, written be lookForArgToken(), when such a token could be parsed, and read by type-specific scanners parseInt(), etc., and cleared again.
  - optTokenValid
```
protected transient boolean optTokenValid
```
    Whether an opt token has been consumed and stored to nextName or to nextAbbrev. Invalidated after its decoding and in parseInit(String, boolean). For conveniece only. It always holds "(nextName!=null||nextAbbrev!=null) = optTokenValid" and "!(nextName!=null&&nextAbbrev!=null)".
  - nextName
```
@Opt
protected transient @Opt String nextName
```
    Written to by updateOptTokens()
  - nextAbbrev
```
@Opt
protected transient @Opt String nextAbbrev
```
    Written to by updateOptTokens()
  - positionalsExplicit
```
protected boolean positionalsExplicit
```
    Set by generated code, whenever a positional option has already been set explicitly.
  - positionalsFound
```
protected boolean positionalsFound
```
    Set by generated code, whenever a positional option is set implicitly.
  - positionalPhase
```
protected boolean positionalPhase
```
    Set by runtime code for correct end-of-cmdline handling.
  - p_hideblanks
```
protected static final Pattern p_hideblanks
```
    Pattern to recognize blank characters, for escaping them prior to parsing.
  - dummyRat
```
protected static final Rational dummyRat
```
  - boolresult
```
protected boolean boolresult
```
    Result of trying the boolean parser. Needed, because the return result indicates the fact whether a boolean designation has been parsed.
- Constructor Detail
  - Model
```
public Model()
```
- Method Detail
  - usage
```
public abstract void usage()
```
    The generated code will print the documentation text of all options, in the default language. For each option print its names, its argument type structure and the description in the selected language.
  - usage
```
public abstract void usage(String language)
```
    The generated code will print the documentation text of all options, in the given language. For each option print its names, its argument type structure and the description in the selected language.
  - checkActive
```
protected abstract void checkActive()
```
    The generated code will evaluate all conditions to activate/deactive options in the GUI.
  - ERROR
```
protected void ERROR(String s)
```
    Only source of error messages.
  - ERROR
```
protected void ERROR(String s,
                     Object rest)
```
  - WARNING
```
protected void WARNING(String s)
```
    Only source of warning messages.
  - putprot
```
protected void putprot(String s)
```
  - putprot_option
```
protected void putprot_option(String s)
```
    Append the name of the option and set parentheses.
  - getParsingProtocol
```
public String getParsingProtocol()
```
    Returns:
    
    The parsing protocol, for debugging.
  - descriptionKeyForEnum
```
public static String descriptionKeyForEnum(MetaClass cl)
```
    Generated MuLi-Catalog key to store the description of an enum type.
  - descriptionKeyForEnum
```
public static String descriptionKeyForEnum(Class<?> cl)
```
    Generated MuLi-Catalog key to store the description of an enum type.
  - descriptionKeyForEnumItem
```
public static String descriptionKeyForEnumItem(Class<?> cl,
                                               Object item)
```
    Generated MuLi-Catalog key to store the description of an enum item value.
  - descriptionKeyForCommentField
```
public static String descriptionKeyForCommentField(String name)
```
    Generated MuLi-Catalog key to store a (multilingual) comment field.
  - makeDefaultInstance
```
public abstract Model makeDefaultInstance()
```
    Overriden by the generated code to make a constructor call of the actual Model (sub-)class.
  - _finalCheck
```
protected abstract void _finalCheck()
```
    Callback, overridden by compiled code.
  - parseAbbrev
```
protected abstract void parseAbbrev(String s)
```
    Callback, overridden by compiled code, which realizes a switch over all one character option names. The generated code calls the argument parsers and stores the resulting values to the model's fields.
    
    Parameters:
    
    s - the one-character option name, as parsed by this code.
  - parseName
```
protected abstract void parseName(String s)
```
    Callback, overridden by compiled code, which realizes a switch over all long option names. The generated code calls the argument parsers and stores the resulting values to the model's fields.
    
    Parameters:
    
    s - the multi-character option name, as parsed by this code.
  - parsePositionals
```
protected abstract void parsePositionals()
```
    Callback, overridden by compiled code, which calls one after the other the positional parameters. Each of them corresponds to an implicit option (with short names "-0", "-1", "-2", ...). These can also be defined explicitly, e.g. be given a long name, etc. Anyhow, they can be set explicitly by their short name. If one single positional option is given explicitly, the implicit parsing of the others is suppressed and this code will not be called.
  - ARG_ERROR
```
protected void ARG_ERROR(String msg)
```
    Generate error message related to the current option, the argument number, and (possibly) the repetition group number. FIXME MULI MSG !?!?!?
  - ERROR_plus
```
protected void ERROR_plus()
```
    Generate the error message that the repeting group of "plus" type is empty.
  - T_ERROR
```
protected void T_ERROR(String msg)
```
    Generate error message on wrong argument type and throw the corresponding exception. The next higher level will try to resume parsing with the next option.
    
    Throws:
    
    Model.ExcWrongType
  - updateOptTokens
```
protected void updateOptTokens()
```
    Decide whether long or short name, and store it to nextName or nextAbbrev. Advance the input (as realized by matcher and set optTokenValid flag. Is only called (by getOptToken() or skipToOption()) when match is known to succeed,
  - getOptToken
```
protected void getOptToken()
```
    Test whether next input is an option key token. If so, then parse it and fill nextName or nextAbbrev, if this has not been done already. Result is reflected in optTokenValid, which is cleared in parseInit(String, boolean). Called only by main parsing loop, and by look-ahead for "cannot re-enter rep group" criterion.
  - skipToOption
```
protected void skipToOption()
```
    Skip input to next option token, if not already done. Only called for error recovery, at end of main parsing loop.
    
    Throws:
    
    Model.ExcFinish - if no option token can be found.
  - lookForArgToken
```
protected void lookForArgToken()
```
    Decode argument token, advance input, set nextArgToken for further processing. Called only by getNextArgToken(), and as look-ahead by canReenterRepetitionGroup(). The resulting variable nextArgToken is re-set after successful decoding in "parse()"
  - canReenterRepetitionGroup
```
protected boolean canReenterRepetitionGroup()
```
    Returns only true if the next consumable input is not an option key (i.e. starting with "-"), AND there is more character data. Because of the first condition, repeting argument groups can unfortunately not start with a negative number.
  - getNextArgToken
```
protected void getNextArgToken()
```
    Decodes next argument token to consume, if this has not yet been done. Is only called when the upper level knows that there must be an argument value. Therefore here error messages can be generated and exceptions thrown. This pre-condition is further important, because the pattern matching an argument is a superset of that of option keys, see e.g. "-1".)
  - parseOneString
```
public void parseOneString(String s,
                           MessageReceiver mr)
```
    Central entry point in case the command line data is already packed into one single String, with escaped blanks.
  - parse
```
public void parse(String[] args,
                  MessageReceiver<SimpleMessage<?>> mr)
```
    The main entry for setting all values according to some command line input, as reaching public void main(String[]) from some exec system call.
  - getInputString
```
public String getInputString()
```
    Get parsing input, maybe constructred from a String-array.
  - getMissingParams
```
public String getMissingParams()
```
    Get String of missing parameters, is empty if none are missing. Must be called after parsing.
  - _getMissingParams
```
protected abstract String _getMissingParams()
```
    Is overridden in the generated code and concatenates the "longest names" of all otions marked as required, but not present in the parsed input. Length==0 iff none is missing. Cf "sourcedtd required='yes'" in tools/tdom_withOptions/Options.xml
  - parseInit
```
protected void parseInit(String opt,
                         boolean hasIt)
```
    Called from compiled code when starting the parsing of the arguments for a recognized/accepted option key. Reset all flags and counters and stores the name for error message and protocol generation.
    FIXME broken lists not yet supported.
    
    Parameters:
    
    opt - Name of option (both names, for error messages only)
    
    hasIt - if this option has already occured in this parsing process
  - ERROR_UNKNOWN_NAME
```
protected void ERROR_UNKNOWN_NAME()
```
    Called from compiled code and the end of the switch between long optipn names.
  - ERROR_UNKNOWN_ABBREV
```
protected void ERROR_UNKNOWN_ABBREV()
```
    Called from compiled code and the end of the switch between short optipn names.
  - parseInt
```
protected int parseInt()
```
    Get the next argument token, parse it into an integer value, invalidate the argument token and return the value. Called from compiled code.
  - parseInt_16or10
```
protected int parseInt_16or10()
```
  - parseFloat
```
protected double parseFloat()
```
    Get the next argument token, parse it into a double value, invalidate the argument token and return the value. Called from compiled code.
  - parseRational
```
protected Rational parseRational()
```
    Get the next argument token, parse it into a rational value, invalidate the argument token and return the value. Called from compiled code.
  - parseBool_X
```
protected boolean parseBool_X()
```
    Aux function, return whether the next token is a representation of a boolean value, and put the result into boolresult.
    
    Returns:
    
    whether an argument string for a boolean value has been consumed.
  - parseBool_optional
```
protected boolean parseBool_optional()
```
    Called by compiled code for "switch-type", argument-less options.
  - parseBool
```
protected boolean parseBool()
```
    Called by compiled code for required boolean arguments.
  - parseString
```
protected String parseString()
```
    Called by compiled code.
  - parseOneUri
```
protected String parseOneUri()
```
    Called by compiled code.
  - parseChar
```
@Deprecated
protected char parseChar()
```
    Deprecated. To take a character value from the input text *verbatim* as an option arguments' value is not a good idea, because one never knows what the accidentally employed shell will do to special characters. Instead use an integer value (possibly with hexadecimal input format).
    
    Called by compiled code.
  - parseEnum
```
protected <E extends Enum<E>> E parseEnum(Class<E> enumclass)
```
    Called by compiled code.
  - parseEnumSet
```
protected <E extends Enum<E>> EnumSet<E> parseEnumSet(Class<E> enumclass)
```
    Called by compiled code.
    FIXME: only the "compilable" enumItem is parsed, not a possibly "uncomilable" @value.
  - serialize
```
public abstract String serialize()
```
    Called to generate a String representation of the model's state. Code is overridden by the compiled code.
  - serialize
```
protected static String serialize(int value)
```
    Called by compiled code. Always PREpend a blank to the added string constant.
  - serialize
```
protected static String serialize(double value)
```
    Called by compiled code.
  - serialize
```
protected static String serialize(Rational rat)
```
    Called by compiled code.
  - serialize
```
protected static String serialize(char value)
```
    Called by compiled code.
  - serialize
```
protected String serialize(String value)
```
    Called by compiled code. The field shellAdapter is considered.
  - serialize
```
protected static String serialize(boolean value)
```
    Called by compiled code.
  - serialize
```
protected static <E extends Enum<E>> String serialize(E value)
```
    Called by compiled code.
  - serialize
```
protected static <E extends Enum<E>> String serialize(EnumSet<E> value)
```
    Called by compiled code.

Class Model

Nested Class Summary

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

shellAdapter

messages

parseErrorGenerator

protocol

descriptions

hasNonMetaOptions

inputstring

inputlength

curOption

curArg

curArgGroup

p_option

p_rest

p_argRAUS

matcher

nextArgToken

optTokenValid

nextName

nextAbbrev

positionalsExplicit

positionalsFound

positionalPhase

p_hideblanks

dummyRat

boolresult

Constructor Detail

Model

Method Detail

usage

usage

checkActive

ERROR

ERROR

WARNING

putprot

putprot_option

getParsingProtocol

descriptionKeyForEnum

descriptionKeyForEnum

descriptionKeyForEnumItem

descriptionKeyForCommentField

makeDefaultInstance

_finalCheck

parseAbbrev

parseName

parsePositionals

ARG_ERROR

ERROR_plus

T_ERROR

updateOptTokens

getOptToken

skipToOption

lookForArgToken

canReenterRepetitionGroup

getNextArgToken

parseOneString

parse

getInputString

getMissingParams

_getMissingParams

parseInit

ERROR_UNKNOWN_NAME

ERROR_UNKNOWN_ABBREV

parseInt

parseInt_16or10

parseFloat

parseRational

parseBool_X

parseBool_optional

parseBool

parseString

parseOneUri

parseChar