Compiler (BandM metatools API doc)

java.lang.Object
- eu.bandm.tools.option.Compiler

```
public class Compiler
extends Object
```
Compile java source for different front-ends for editing, saving, decoding etc. program options, from an abstract option and type description.

The abstract description is given as an XML document. Its document type and semantics are discussed in the user documentation.
The compiled code is executed on the basis of the run-time system in package eu.bandm.tools.option.runtime
Each run generates code for one class derivend from Model and one optional from Gui. Both will be in the same package, so that "protected" fields and methods are mutally accessible.
The process of parsing is a complicated ping-pong between runtime class and generated code and documented with Model.
In BandM meta-tools one currently finds examples for all important special cases:

fragmentedLists xslt/base/Options.xml : sourceRoots, etc.
option w/o argument ("switch") tdom_withOptions : patterns, noCompress, etc.

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`protected class`	`Compiler.Phase` Base class for compiler phases.
`protected class`	`Compiler.Phase_enum` Zeroth phase, collect and generate code for enumerations.
`protected class`	`Compiler.Phase_gui` Compile code for the gui class.
`protected class`	`Compiler.Phase_parser` Create a parsing method for each option, and two "switch" methods calling these, one for short and one for long names.
`protected class`	`Compiler.Phase_pre_enum` Minus-first phase, make crossref in which arguments an enum occurs.
`protected class`	`Compiler.Phase_usage` Common superclass for `Compiler.Phase_usage_enumerations` and `Compiler.Phase_usage_options`.
`protected class`	`Compiler.Phase_usage_enumerations` Deliver the documentation text table for all enumeration types.
`protected class`	`Compiler.Phase_usage_options` Make one default `usage()` function and many specials for each language appearing at least once in the collection of descriptions.
`protected class`	`Compiler.Phase1` First and main code generation phase. Creates code for (1) checks uniqueness and correctness of names and abbrevs. (2) collects documentation into `desrcibes_argument_types`. (3) makes value fields and getter methods for all option arguments (4) generates code for enabling conditions. (currently only simple "equal()" have been tested.

Field Summary

Fields
Modifier and Type	Field and Description
`protected GeneratedAnnotation`	`annotationDeprecated_has`
`protected GeneratedAnnotation`	`annotationOverride`
`static EnvironmentClass`	`CL_ArrayList` Evident
`static EnvironmentClass`	`CL_boolean` Evident
`static EnvironmentClass`	`CL_char` Evident
`static EnvironmentClass`	`CL_Component` Evident
`static EnvironmentClass`	`CL_double` Evident
`static EnvironmentClass`	`CL_EnumSet` Evident
`static EnvironmentClass`	`CL_Function` Evident
`static EnvironmentClass`	`CL_int` Evident
`static EnvironmentClass`	`CL_LinkedList` Evident
`static EnvironmentClass`	`CL_List` Evident
`static EnvironmentClass`	`CL_rational` Evident
`static EnvironmentClass`	`CL_String` Evident
`protected Map<Element_comment,String>`	`comment_name` All comments (=separator lines) are collected in a first visit and used in subsequent GUI generation.
`protected CatalogByString`	`descriptions` Inter-phase information transfer: all collected multi-lingual description texts.
`Map<Element_option,String>`	`desrcibes_argument_types` Human readable documentation text describing the option.
`Map<Element_option,String>`	`element_conditionUsage`
`static String`	`ENUM_ITEMS_INLINE_SEPARATOR`
`static int`	`ENUM_ITEMS_INLINE_THRESHOLD`
`Map<String,GeneratedClass>`	`enumClasses`
`Map<String,List<Element_enumitem>>`	`enums` All defined enumeration types.
`protected Multimap<String,String>`	`enums2options`
`Set<String>`	`enumsWithDocText`
`Set<String>`	`enumsWithItemDocText`
`Map<String,String>`	`enumValuesList`
`protected Set<String>`	`evalforinactive`
`protected Map<String,Format>`	`formatCache`
`protected boolean`	`fragmentedLists` Whether lists may come in more than one portions.
`protected Format`	`generationComment` Copy of argument needed only for Phase_enum.
`protected GeneratedClass`	`guiclass` Inter-phase information transfer: the currently defined gui class.
`protected boolean`	`hasRationals` Whether the code for Rationals must be imported.
`protected boolean`	`hexIntegers` Whether integer input may be given in hexdecimal by `0x123`.
`protected static int`	`LINEWIDTH` Format of the generated java source files.
`protected static String`	`LINGUA_FRANCA` Language selection for generating source comments and for the unparamterized `usage()` method.
`protected Set<String>`	`maybeinactive`
`protected GeneratedMethod`	`meth_checkActive`
`protected GeneratedMethod`	`meth_displayActive`
`protected GeneratedClass`	`modelclass` Inter-phase information transfer: the currently defined model class.
`protected SimpleMessage.Generator<XMLDocumentIdentifier>`	`msg` Message Generator for all error and warning messages during compilation.
`protected MessageReceiver<Message>`	`msgr`
`String`	`NAME_OF_DESCRIPTION_CATALOG_CLASS` Must correspond to `eu.bandm.tools.option.runtime`
`String`	`NAME_OF_DESCRIPTION_CATALOG_FIELD` Must correspond to `eu.bandm.tools.option.runtime`
`String`	`NAME_OF_MODEL_ACCESS_FUNCTION` Must correspond to `eu.bandm.tools.option.runtime`
`static String`	`NAME_PROGRAM` Used only as argument to `CommentFormats.generationComment(String,String,int,boolean,String[])`.
`protected String`	`noDoc` Text used if even the language fallback mechanism fails to find a description.
`protected Set<String>`	`nonEmptyGroups` Lists with "plus" operator (not "star"), finally checked for non-emptyness
`protected Map<Element_option,GeneratedClass>`	`option2tailClass` The class generated to represent the repeting group of arguments.
`protected boolean`	`overall_has_repeting` Whether there is at least one repeting group, requiring import of metaools ops.
`protected Map<Integer,Element_option>`	`positionals` All options which are positional, sorted by their index (short name).
`static Set<String>`	`RESERVED_TYPE_NAMES` Must not appear as names of user-defined enumerations.
`static String`	`VERSION_PROGRAM`

Constructor Summary

Constructors
Constructor and Description

Compiler()

Constructors
Constructor and Description
`Compiler()`

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`protected void`	`add_comment_for_sourcetext(@Opt Element_desc desc, GeneratedAnnotationTarget target)` Add the description in the `LINGUA_FRANCA`, if any, to the generated java object "target", by calling {@link add_comment_for_sourcetext(String,Element_desc, GeneratedAnnotationTarget).
`protected void`	`add_comment_for_sourcetext(@Opt String prefix, @Opt Element_desc desc, GeneratedAnnotationTarget target)` Adds formatted user-level (=payload) comment to a generated method or field.
`protected boolean`	`argnumberRedundant(Element_option el)` For recognizing an option with at most one argument.
`void`	`compile(Element_optionlist data0, String packagename0, String classname_model, @Opt String classname_gui, String destdir, Format genComment, String inputfilename, MessageReceiver<Message> msgr)` Create source text for a model, and for a gui, if required.
`protected Format`	`expression(String code)`
`protected String`	`find_printout_title(Element_optionlist olist, String lang)` Looks in the header of the option list for the title text of the usage() output.
`protected Format`	`format_dquoted(String s)` Generate a literal format containing a string in double quotes.
`protected boolean`	`listByAbbrev(String enumname)` Decides between different presentation formats in usage().
`static void`	`main(String[] args)` Execute compilation of the dtd to Java sources.
`protected void`	`make_usage(Element_optionlist olist)` Call `Visitor.visit(Element_optionlist)` for all languages appearing at least once in the collection of descriptions.
`protected String`	`name2tag(String r)` Prepend the correct number of lead-in minus signs to long name or abbrev name.
`protected void`	`parsePositional()` Generate the parsing method for the positional options/arguments.
`protected Format`	`statement(String code)`
`protected Format`	`statements(String code)`
`protected boolean`	`typeNotEmpty(Element_option el)` For recognizing totally empty type (no types nor rep group).
`protected static void`	`usage()` Print the usage information of this tool to stderr.

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

- Field Detail
  - NAME_PROGRAM
```
public static final String NAME_PROGRAM
```
    Used only as argument to CommentFormats.generationComment(String,String,int,boolean,String[]). Therefore an html encoding is sensible.
    
    See Also:
    
    Constant Field Values
  - VERSION_PROGRAM
```
public static final String VERSION_PROGRAM
```
    See Also:
    
    Constant Field Values
  - formatCache
```
protected Map<String,Format> formatCache
```
  - LINGUA_FRANCA
```
protected static final String LINGUA_FRANCA
```
    Language selection for generating source comments and for the unparamterized usage() method. Since the lingua franca of the computer area is English, these documentation texts are taken for program documentation = API documentation (NOT user documentation like "usage()" and error messages). It will also be used as the fall-back for usage() if some doc text in the required language does not exist. If even a text in LINGUA_FRANCA does not exist, a language will be chosen by random.
    
    See Also:
    
    Constant Field Values
  - NAME_OF_DESCRIPTION_CATALOG_CLASS
```
public final String NAME_OF_DESCRIPTION_CATALOG_CLASS
```
    Must correspond to eu.bandm.tools.option.runtime
    
    See Also:
    
    Constant Field Values
  - NAME_OF_DESCRIPTION_CATALOG_FIELD
```
public final String NAME_OF_DESCRIPTION_CATALOG_FIELD
```
    Must correspond to eu.bandm.tools.option.runtime
    
    See Also:
    
    Constant Field Values
  - NAME_OF_MODEL_ACCESS_FUNCTION
```
public final String NAME_OF_MODEL_ACCESS_FUNCTION
```
    Must correspond to eu.bandm.tools.option.runtime
    
    See Also:
    
    Constant Field Values
  - RESERVED_TYPE_NAMES
```
public static final Set<String> RESERVED_TYPE_NAMES
```
    Must not appear as names of user-defined enumerations. (This exclusion is for readability of documentation only.)
  - ENUM_ITEMS_INLINE_THRESHOLD
```
public static final int ENUM_ITEMS_INLINE_THRESHOLD
```
    See Also:
    
    Constant Field Values
  - ENUM_ITEMS_INLINE_SEPARATOR
```
public static final String ENUM_ITEMS_INLINE_SEPARATOR
```
    See Also:
    
    Constant Field Values
  - msgr
```
protected MessageReceiver<Message> msgr
```
  - msg
```
protected SimpleMessage.Generator<XMLDocumentIdentifier> msg
```
    Message Generator for all error and warning messages during compilation.
  - generationComment
```
protected Format generationComment
```
    Copy of argument needed only for Phase_enum.
  - modelclass
```
protected GeneratedClass modelclass
```
    Inter-phase information transfer: the currently defined model class.
  - guiclass
```
protected GeneratedClass guiclass
```
    Inter-phase information transfer: the currently defined gui class.
  - descriptions
```
protected CatalogByString descriptions
```
    Inter-phase information transfer: all collected multi-lingual description texts. Filled by Compiler.Phase1 for Element_option and in Compiler.Phase_enum for Element_enum and Element_enumitem.
  - annotationOverride
```
protected GeneratedAnnotation annotationOverride
```
  - annotationDeprecated_has
```
protected GeneratedAnnotation annotationDeprecated_has
```
  - maybeinactive
```
protected Set<String> maybeinactive
```
  - evalforinactive
```
protected Set<String> evalforinactive
```
  - meth_checkActive
```
protected GeneratedMethod meth_checkActive
```
  - meth_displayActive
```
protected GeneratedMethod meth_displayActive
```
  - option2tailClass
```
protected Map<Element_option,GeneratedClass> option2tailClass
```
    The class generated to represent the repeting group of arguments.
  - desrcibes_argument_types
```
public Map<Element_option,String> desrcibes_argument_types
```
    Human readable documentation text describing the option. One string contains the long and the short name, if present, followed bs the option's arguments' type signature. Is filled by Phase1 and read when making usage(..), etc.
  - element_conditionUsage
```
public Map<Element_option,String> element_conditionUsage
```
  - enums2options
```
protected Multimap<String,String> enums2options
```
  - enums
```
public Map<String,List<Element_enumitem>> enums
```
    All defined enumeration types.
  - enumClasses
```
public Map<String,GeneratedClass> enumClasses
```
  - enumsWithDocText
```
public Set<String> enumsWithDocText
```
  - enumsWithItemDocText
```
public Set<String> enumsWithItemDocText
```
  - enumValuesList
```
public Map<String,String> enumValuesList
```
  - comment_name
```
protected Map<Element_comment,String> comment_name
```
    All comments (=separator lines) are collected in a first visit and used in subsequent GUI generation.
  - positionals
```
protected Map<Integer,Element_option> positionals
```
    All options which are positional, sorted by their index (short name).
  - overall_has_repeting
```
protected boolean overall_has_repeting
```
    Whether there is at least one repeting group, requiring import of metaools ops.
  - fragmentedLists
```
protected boolean fragmentedLists
```
    Whether lists may come in more than one portions.
  - hexIntegers
```
protected boolean hexIntegers
```
    Whether integer input may be given in hexdecimal by 0x123.
  - hasRationals
```
protected boolean hasRationals
```
    Whether the code for Rationals must be imported.
  - nonEmptyGroups
```
protected Set<String> nonEmptyGroups
```
    Lists with "plus" operator (not "star"), finally checked for non-emptyness
  - CL_boolean
```
public static final EnvironmentClass CL_boolean
```
    Evident
  - CL_int
```
public static final EnvironmentClass CL_int
```
    Evident
  - CL_double
```
public static final EnvironmentClass CL_double
```
    Evident
  - CL_rational
```
public static final EnvironmentClass CL_rational
```
    Evident
  - CL_char
```
public static final EnvironmentClass CL_char
```
    Evident
  - CL_String
```
public static final EnvironmentClass CL_String
```
    Evident
  - CL_List
```
public static final EnvironmentClass CL_List
```
    Evident
  - CL_LinkedList
```
public static final EnvironmentClass CL_LinkedList
```
    Evident
  - CL_EnumSet
```
public static final EnvironmentClass CL_EnumSet
```
    Evident
  - CL_Function
```
public static final EnvironmentClass CL_Function
```
    Evident
  - CL_ArrayList
```
public static final EnvironmentClass CL_ArrayList
```
    Evident
  - CL_Component
```
public static final EnvironmentClass CL_Component
```
    Evident
  - noDoc
```
protected final String noDoc
```
    Text used if even the language fallback mechanism fails to find a description. Is included in usage() and (marked as bold) in generated api doc. (Can only happen if no text is included at all, ie. the option list contains only un-documented enumeration definitions.)
    
    See Also:
    
    Constant Field Values
  - LINEWIDTH
```
protected static final int LINEWIDTH
```
    Format of the generated java source files.
    
    See Also:
    
    Constant Field Values
- Constructor Detail
  - Compiler
```
public Compiler()
```
- Method Detail
  - compile
```
public void compile(Element_optionlist data0,
                    String packagename0,
                    String classname_model,
                    @Opt
                    @Opt String classname_gui,
                    String destdir,
                    Format genComment,
                    String inputfilename,
                    MessageReceiver<Message> msgr)
```
    Create source text for a model, and for a gui, if required.
    
    Parameters:
    
    data0 - the top-level element of the option specification file
    
    packagename0 - where to to generate the source
    
    classname_model - the name of the generated class
    
    classname_gui - the name of the generated gui class.
    May be ==null to suppress code generation.
    
    destdir - where the java source hierarchy starts
    
    msgr - for error messages and warnings
  - expression
```
protected Format expression(String code)
```
  - statement
```
protected Format statement(String code)
```
  - statements
```
protected Format statements(String code)
```
  - format_dquoted
```
protected Format format_dquoted(String s)
```
    Generate a literal format containing a string in double quotes. Can only be applied to keys, enum values etc. which definitely do not contain special characters.
  - typeNotEmpty
```
protected boolean typeNotEmpty(Element_option el)
```
    For recognizing totally empty type (no types nor rep group).
  - argnumberRedundant
```
protected boolean argnumberRedundant(Element_option el)
```
    For recognizing an option with at most one argument. Can LATER be used to shorten the usage-documentation of conditions.
  - name2tag
```
protected String name2tag(String r)
```
    Prepend the correct number of lead-in minus signs to long name or abbrev name.
  - listByAbbrev
```
protected boolean listByAbbrev(String enumname)
```
    Decides between different presentation formats in usage().
  - find_printout_title
```
protected String find_printout_title(Element_optionlist olist,
                                     String lang)
```
    Looks in the header of the option list for the title text of the usage() output.
  - add_comment_for_sourcetext
```
protected void add_comment_for_sourcetext(@Opt
                                          @Opt Element_desc desc,
                                          GeneratedAnnotationTarget target)
```
    Add the description in the LINGUA_FRANCA, if any, to the generated java object "target", by calling {@link add_comment_for_sourcetext(String,Element_desc, GeneratedAnnotationTarget).
  - add_comment_for_sourcetext
```
protected void add_comment_for_sourcetext(@Opt
                                          @Opt String prefix,
                                          @Opt
                                          @Opt Element_desc desc,
                                          GeneratedAnnotationTarget target)
```
    Adds formatted user-level (=payload) comment to a generated method or field. Only the LINGUA_FRANCA (currently English) is output, since all other text generated by the tool javadoc is in this language. The text is wrapped in a <span class="bandUser"> xhtml tag for css style formatting.
    
    Parameters:
    
    prefix - prepended to the found text, also contained in the wrapping tag.
  - make_usage
```
protected void make_usage(Element_optionlist olist)
```
    Call Visitor.visit(Element_optionlist) for all languages appearing at least once in the collection of descriptions.
  - parsePositional
```
protected void parsePositional()
```
    Generate the parsing method for the positional options/arguments.
  - usage
```
protected static void usage()
```
    Print the usage information of this tool to stderr.
  - main
```
public static void main(String[] args)
                 throws SAXException
```
    Execute compilation of the dtd to Java sources. Additionally the dtd is copied into the "doc-files" subdirectory of that directory to where the package code is written (roughly: args[4]+args[1]).
```
  args[0] = inputfile
  args[1] = packagename 
  args[2] = classname of the generated model class
  args[3] = classname oc the generated gui class (when = empty string "", then no 
                                                  no gui will be generated)
  args[4] = outputroot
  
```
    Throws:
    
    SAXException

fragmentedLists	xslt/base/Options.xml : sourceRoots, etc.
option w/o argument ("switch")	tdom_withOptions : patterns, noCompress, etc.

Class Compiler

Nested Class Summary

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

NAME_PROGRAM

VERSION_PROGRAM

formatCache

LINGUA_FRANCA

NAME_OF_DESCRIPTION_CATALOG_CLASS

NAME_OF_DESCRIPTION_CATALOG_FIELD

NAME_OF_MODEL_ACCESS_FUNCTION

RESERVED_TYPE_NAMES

ENUM_ITEMS_INLINE_THRESHOLD

ENUM_ITEMS_INLINE_SEPARATOR

msgr

msg

generationComment

modelclass

guiclass

descriptions

annotationOverride

annotationDeprecated_has

maybeinactive

evalforinactive

meth_checkActive

meth_displayActive

option2tailClass

desrcibes_argument_types

element_conditionUsage

enums2options

enums

enumClasses

enumsWithDocText

enumsWithItemDocText

enumValuesList

comment_name

positionals

overall_has_repeting

fragmentedLists

hexIntegers

hasRationals

nonEmptyGroups

CL_boolean

CL_int

CL_double

CL_rational

CL_char

CL_String

CL_List

CL_LinkedList

CL_EnumSet

CL_Function

CL_ArrayList

CL_Component

noDoc

LINEWIDTH

Constructor Detail

Compiler

Method Detail

compile

expression

statement

statements

format_dquoted

typeNotEmpty

argnumberRedundant

name2tag

listByAbbrev

find_printout_title

add_comment_for_sourcetext

add_comment_for_sourcetext

make_usage

parsePositional

usage

main