Package eu.bandm.tools.option

Class Compiler

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:

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

  • Field Details

    • NAME_PROGRAM

      public static final String NAME_PROGRAM
      Used only as argument to Formats.generationComment(String,String,int,boolean,String[]). Therefore an html encoding is sensible.
      See Also:

    • VERSION_PROGRAM

      public static final String VERSION_PROGRAM
      See Also:

    • formatCache

      protected Map<String,Format> formatCache

    • LINGUA_FRANCA

      public 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:

    • BASECLASS_MODEL

      final Class BASECLASS_MODEL

    • BASECLASS_GUI

      final Class BASECLASS_GUI

    • NAME_OF_DESCRIPTION_CATALOG_CLASS

      public final String NAME_OF_DESCRIPTION_CATALOG_CLASS
      Must correspond to eu.bandm.tools.option.runtime
      See Also:

    • NAME_OF_DESCRIPTION_CATALOG_FIELD

      public final String NAME_OF_DESCRIPTION_CATALOG_FIELD
      Must correspond to eu.bandm.tools.option.runtime
      See Also:

    • NAME_OF_MODEL_ACCESS_FUNCTION

      public final String NAME_OF_MODEL_ACCESS_FUNCTION
      Must correspond to eu.bandm.tools.option.runtime
      See Also:

    • 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:

    • ENUM_ITEMS_INLINE_SEPARATOR

      public static final String ENUM_ITEMS_INLINE_SEPARATOR
      See Also:

    • msgr

      protected MessageReceiver<SimpleMessage<XMLDocumentIdentifier>> msgr

    • 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.

    • 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

    • bothTags

      protected Map<String,String> bothTags
      Maps option qualifiers to user readable option indication.'

    • 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

    • default_usage_header

      final String default_usage_header
      Default string printed at the top of the usage() output, if no language-specific value is specified in Element_printout_title.
      See Also:

    • required

      final List<String> required
      List of all options declared @required='yes'

    • 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:

    • LINEWIDTH

      protected static final int LINEWIDTH
      Format of the generated java source files.
      See Also:

  • Constructor Details

    • Compiler

      public Compiler()

  • Method Details

    • compile

      public void compile(Element_optionlist data0, String packagename0, String classname_model, @Opt @Opt String classname_gui, String destdir, Format genComment, String inputfilename, MessageReceiver<SimpleMessage<XMLDocumentIdentifier>> 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.

    • checkStar

      static boolean checkStar(Element_rep el)
      Whether the repeting group is of "star" kind, not of "plus" kind.

    • 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 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="bandmUser"> 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 xml source to Java sources. Additionally the xml source is copied into the "doc-files" subdirectory of that directory to where the package code is written (roughly spoken = "concat(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