Model (BandM metatools API doc)

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

Direct Known Subclasses:: BatchOptions, CallXsltOptions, InsertOverprintOptions, JarLinkerOptions, JWhichOptions, Options, Options, Options, Options, 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 /

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 parameter could start.
`protected class`	`Model.ExcUnknownOpt` Thrown if option name / abbrev is unknown.
`protected class`	`Model.ExcWrongType` Thrown if argument is of wrong type.

Field Summary

Fields
Modifier and Type	Field and Description
`protected boolean`	`boolresult` Result of trying the boolean parser.
`protected String`	`curOption` Human readable identification of the option currently being parsed.
`protected int`	`curParam` Number of the argument (relative to begin of option's types, or to repeting group!) currently being parsed.
`protected int`	`curParamGroup` Number of the repeting group which is under parsing, or `-1` in case the fixed part is currently being parsed.
`CatalogByString`	`descriptions` Filled in by generated code.
`protected int`	`inputlength`
`protected String`	`inputstring` Input concatentated into one single string, only input data for the parsing process.
`protected Matcher`	`m_escapedBlanks`
`protected Matcher`	`matcher` Re-used matcher for the input, once loaded with string data, then linked to different patterns!
`protected String`	`nextAbbrev` Written to by `updateOptTokens()`
`protected String`	`nextName` Written to by `updateOptTokens()`
`protected String`	`nextPToken` Argument token, written be `lookForPToken()` and read by type-specific scanners `parseInt()`, etc.
`protected boolean`	`optTokenValid` Whether an opt token has been consumed and stored to `nextName` or to `nextAbbrev`.
`protected static Pattern`	`p_escapedBlanks`
`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 static Pattern`	`p_param` Pattern for parameters, ie sections without blanks, or only with BACKSLASH-ESCAPED blanks.
`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 explitly.
`protected boolean`	`positionalsFound` Set by generated code, whenever a positional option is set implicitly.
`protected StringBuilder`	`protocol` Debugging only !?!?

Constructor Summary

Constructors
Constructor and Description

Model()

Constructors
Constructor and Description
`Model()`

Method Summary

All Methods Static Methods Instance Methods Abstract Methods Concrete Methods
Modifier and Type	Method and Description
`protected abstract void`	`_finalCheck()` Callback, overridden by compiled code.
`protected abstract String`	`_getMissingParams()`
`protected boolean`	`canReenterRepetitionGroup()` Returns only true if there is NO option lead in, AND more character data.
`static String`	`descriptionKeyForCommentField(String name)`
`static String`	`descriptionKeyForEnum(Class<?> cl)`
`static String`	`descriptionKeyForEnum(GeneratedClass cl)`
`static String`	`descriptionKeyForEnumItem(Class<?> cl, Object item)`
`protected void`	`ERROR_plus()`
`protected void`	`ERROR_UNKNOWN_ABBREV()` Called from compiled code.
`protected void`	`ERROR_UNKNOWN_NAME()` Called from compiled code.
`protected void`	`ERROR(String s)` Only source of error messages.
`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`	`getNextPToken()` Decodes next argument token.
`protected void`	`getOptToken()` Decode next option name token, if not already done.
`String`	`getParsingProtocol()` DEBUG only
`protected void`	`lookForPToken()` Decode argument token, advance input, set nextPtoken for further processing.
`abstract Model`	`makeEmptyInstance()`
`protected void`	`P_ERROR(String msg)` Generate error message related to the current option and (possibly) repetition group number.
`void`	`parse(String[] args, MessageReceiver 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.
`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()` Called by compiled code.
`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()` Called from compiled code.
`protected void`	`parseInit(String opt, boolean hasIt)` Called from compiled code when starting each option.
`protected int`	`parseInt()` Called from compiled code.
`protected abstract void`	`parseName(String s)` Callback, overridden by compiled code.
`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.
`protected String`	`parseString()` Called by compiled code.
`protected void`	`putprot_option(String s)`
`protected void`	`putprot(String s)`
`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(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 exception.
`protected String`	`unescapeBlanks(String s)`
`protected void`	`updateOptTokens()` Decide whether long or short name, and store it to `nextName` or `nextAbbrev`.
`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
  - parseErrorGenerator
```
protected SimpleMessage.Generator<Location<String>> parseErrorGenerator
```
  - protocol
```
protected transient StringBuilder protocol
```
    Debugging only !?!?
  - descriptions
```
public CatalogByString descriptions
```
    Filled in by generated code. Needed by the GUI for dynamic tool-tip translation.
  - inputstring
```
protected String inputstring
```
    Input concatentated into one single string, only input data for the parsing process.
  - inputlength
```
protected transient int inputlength
```
  - curOption
```
protected transient String curOption
```
    Human readable identification of the option currently being parsed.
  - curParam
```
protected transient int curParam
```
    Number of the argument (relative to begin of option's types, or to repeting group!) currently being parsed.
  - curParamGroup
```
protected transient int curParamGroup
```
    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)
  - p_param
```
protected static final Pattern p_param
```
    Pattern for parameters, 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 linked to different patterns!
  - nextPToken
```
protected transient String nextPToken
```
    Argument token, written be lookForPToken() and read by type-specific scanners parseInt(), etc.
  - 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).
  - nextName
```
protected transient String nextName
```
    Written to by updateOptTokens()
  - nextAbbrev
```
protected transient String nextAbbrev
```
    Written to by updateOptTokens()
  - positionalsExplicit
```
protected boolean positionalsExplicit
```
    Set by generated code, whenever a positional option has already been set explitly.
  - 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.
  - 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.
  - p_escapedBlanks
```
protected static final Pattern p_escapedBlanks
```
  - m_escapedBlanks
```
protected final Matcher m_escapedBlanks
```
- Constructor Detail
  - Model
```
public Model()
```
- Method Detail
  - ERROR
```
protected void ERROR(String s)
```
    Only source of error messages.
  - 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)
```
  - descriptionKeyForEnum
```
public static String descriptionKeyForEnum(GeneratedClass cl)
```
  - descriptionKeyForEnum
```
public static String descriptionKeyForEnum(Class<?> cl)
```
  - descriptionKeyForEnumItem
```
public static String descriptionKeyForEnumItem(Class<?> cl,
                                               Object item)
```
  - descriptionKeyForCommentField
```
public static String descriptionKeyForCommentField(String name)
```
  - makeEmptyInstance
```
public abstract Model makeEmptyInstance()
```
  - _finalCheck
```
protected abstract void _finalCheck()
```
    Callback, overridden by compiled code.
  - parseAbbrev
```
protected abstract void parseAbbrev(String s)
```
    Callback, overridden by compiled code.
  - parseName
```
protected abstract void parseName(String s)
```
    Callback, overridden by compiled code.
  - parsePositionals
```
protected abstract void parsePositionals()
```
    Callback, overridden by compiled code.
  - P_ERROR
```
protected void P_ERROR(String msg)
```
    Generate error message related to the current option and (possibly) repetition group number.
  - ERROR_plus
```
protected void ERROR_plus()
```
  - T_ERROR
```
protected void T_ERROR(String msg)
```
    Generate error message on wrong argument type and THROW exception.
  - updateOptTokens
```
protected void updateOptTokens()
```
    Decide whether long or short name, and store it to nextName or nextAbbrev. Skip input and set optTokenValid flag. IS ONLY CALLED when match is known to succeed!
  - getOptToken
```
protected void getOptToken()
```
    Decode next option name token, if not already done. Called only by main parsing loop, and by look-ahead for "cannot re-enter rep group" criterion. NB flag is re-set in parseInit(String, boolean).
  - 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.
  - lookForPToken
```
protected void lookForPToken()
```
    Decode argument token, advance input, set nextPtoken for further processing. Called only by getNextPToken(), and as look-ahead for "can re-enter rep group" criterion. NB result-var is re-set after successul decoding in "parse()"
  - canReenterRepetitionGroup
```
protected boolean canReenterRepetitionGroup()
```
    Returns only true if there is NO option lead in, AND more character data.
  - getNextPToken
```
protected void getNextPToken()
```
    Decodes next argument token.
  - 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 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.
  - getParsingProtocol
```
public String getParsingProtocol()
```
    DEBUG only
  - 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()
```
  - parseInit
```
protected void parseInit(String opt,
                         boolean hasIt)
```
    Called from compiled code when starting each option. FIXME broken lists not yet supported.
  - ERROR_UNKNOWN_NAME
```
protected void ERROR_UNKNOWN_NAME()
```
    Called from compiled code.
  - ERROR_UNKNOWN_ABBREV
```
protected void ERROR_UNKNOWN_ABBREV()
```
    Called from compiled code.
  - parseInt
```
protected int parseInt()
```
    Called from compiled code.
  - parseFloat
```
protected double parseFloat()
```
    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.
  - 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.
  - unescapeBlanks
```
protected String unescapeBlanks(String s)
```
  - parseString
```
protected String parseString()
```
    Called by compiled code.
  - parseOneUri
```
protected String parseOneUri()
```
    Called by compiled code.
  - parseChar
```
protected char parseChar()
```
    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
```
protected static String serialize(int value)
```
    Called by compiled code.
  - serialize
```
protected static String serialize(double value)
```
    Called by compiled code.
  - serialize
```
protected static String serialize(char value)
```
    Called by compiled code.
  - serialize
```
protected static String serialize(String value)
```
    Called by compiled code.
  - 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

parseErrorGenerator

protocol

descriptions

inputstring

inputlength

curOption

curParam

curParamGroup

p_option

p_param

matcher

nextPToken

optTokenValid

nextName

nextAbbrev

positionalsExplicit

positionalsFound

positionalPhase

p_hideblanks

boolresult

p_escapedBlanks

m_escapedBlanks

Constructor Detail

Model

Method Detail

ERROR

WARNING

putprot

putprot_option

descriptionKeyForEnum

descriptionKeyForEnum

descriptionKeyForEnumItem

descriptionKeyForCommentField

makeEmptyInstance

_finalCheck

parseAbbrev

parseName

parsePositionals

P_ERROR

ERROR_plus

T_ERROR

updateOptTokens

getOptToken

skipToOption

lookForPToken

canReenterRepetitionGroup

getNextPToken

parseOneString

parse

getParsingProtocol

getInputString

getMissingParams

_getMissingParams

parseInit

ERROR_UNKNOWN_NAME

ERROR_UNKNOWN_ABBREV

parseInt

parseFloat

parseBool_X

parseBool_optional

parseBool

unescapeBlanks

parseString

parseOneUri

parseChar

parseEnum

parseEnumSet

serialize

serialize

serialize

serialize

serialize

serialize