excelExporter.excelParser.dataModel

## Class Info

- java.lang.Object
- - excelExporter.excelParser.dataModel.Info

-     public class Info
      extends java.lang.Object

  The data structure holding general information for code generation. The basic design principle is the use of public members because such members can be directly accessed from the output templates. Boolean decisions are either expressed as explicit public Boolean members or by references to nested member objects, which are null if an optional member is not used or applicable: StringTemplate can query public Boolean members or check for null references.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static java.lang.String` | `application` The name of the code generating application.
    `java.util.Map<java.lang.String,java.lang.Object>` | `calc` This is a Java Map object, which can hold custom number objects.
    `excelExporter.excelParser.dataModel.ST4CmdInterpreter<java.lang.Integer,java.lang.Object>` | `debug` This is a pseudo field of the StringTemplate V4 data model.
    `static java.lang.String` | `envVarHOME` The value of the environment variable HOME.
    `static java.lang.String` | `envVarOS` The value of the environment variable OS.
    `static java.lang.String` | `envVarTMP` The value of the environment variable TMP.
    `static java.lang.String` | `envVarUSERNAME` The value of the environment variable USERNAME.
    `excelExporter.excelParser.dataModel.ST4CmdInterpreter<java.lang.Integer,java.lang.Object>` | `error` This is a pseudo field of the StringTemplate V4 data model.
    `excelExporter.excelParser.dataModel.ST4CmdInterpreter<java.lang.Integer,java.lang.Object>` | `info` This is a pseudo field of the StringTemplate V4 data model.
    `static java.util.Map<java.lang.String,java.lang.Boolean>` | `isVersionDataModel` The version designation versionDataModel for the data model, which is essential for relating templates to permitted, compatible tool revisions, is testable through this data element.
    `java.util.LinkedHashMap<java.lang.String,java.lang.Object>` | `optionMap` A map of user specified options or template attributes.
    `FileExt` | `output` The generated output file as an extended Java File object.
    `java.lang.String` | `templateArgNameCluster` The StringTemplate V4 template, which is used to render the information has an argument, that contains all network related information.
    `java.lang.String` | `templateArgNameInfo` The StringTemplate V4 template, which is used to render the information has an argument, that contains general purpose information (e.g.
    `FileExt` | `templateFile` The StringTemplate V4 group template file as an extended Java File object.
    `java.lang.String` | `templateName` The name of the StringTemplate V4 template used to render the information.
    `java.lang.Integer` | `templateWrapCol` Information rendering can optionally apply line wrapping.
    `java.lang.String` | `time` Time of code generation.
    `static java.lang.String` | `version` The first parts of the version of the tool, which relate to the functional state of the application.
    `static int` | `versionBuild` Forth part of version designation of the application.
    `static int` | `versionDataModel` The version of the data model supported by the code generator.
    `static int` | `versionFix` Third part of version designation of the application.
    `static int` | `versionMajor` Major part of version designation of the application.
    `static int` | `versionMinor` Minor part of version designation of the application.
    `excelExporter.excelParser.dataModel.ST4CmdInterpreter<java.lang.Integer,java.lang.Object>` | `warn` This is a pseudo field of the StringTemplate V4 data model.
    `java.lang.String` | `year` Year of date (as applicable for copyright notices).

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `Info(excelExporter.excelParser.ErrorCounter errCnt)` Create the Info object.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `int` | `getNoCalcNumbers()` The number of user stored numbers in the scratch pad `calc`.
    `int` | `getNoOptions()` The number of user options in `optionMap`.
    `java.lang.Object` | `interpret(java.lang.Integer logLevel, java.lang.String message)` This method implements the command listener, which is used to emit a message to the application log under control of the currently expanded StringTemplate V4 template.
    `static void` | `setApplicationInfo(java.lang.String appName, int[] versionAry, int verDataModel)` Set the information about this application.
    `void` | `setOutputInfo(java.lang.String fileName)` Fill the information concerning the generated output file.
    `void` | `setTemplateInfo(java.lang.String tFileName, java.lang.String tName, java.lang.String tArgCluster, java.lang.String tArgInfo, int tWrapCol)` Fill the object with information about the template in use.
    `void` | `setUserOptions(java.util.LinkedHashMap<java.lang.String,java.lang.Object> map)` Copy a map with user attributes by reference into the Info object.
    `java.lang.String` | `toString()` Get the string representation of the Info object; it's composed from some of some of its general fields.

    - ### Methods inherited from class java.lang.Object

      `equals, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- - ### Field Detail

    - #### application

          public static java.lang.String application

      The name of the code generating application.

    - #### version

          public static java.lang.String version

      The first parts of the version of the tool, which relate to the functional state of the application.

    - #### versionMajor

          public static int versionMajor

      Major part of version designation of the application. This part relates to major releases.

    - #### versionMinor

          public static int versionMinor

      Minor part of version designation of the application. This part relates to functional changes; a change of the data model will always cause an increment of this part.

    - #### versionFix

          public static int versionFix

      Third part of version designation of the application. This part relates to fixes or insignificant functional changes.

    - #### versionBuild

          public static int versionBuild

      Forth part of version designation of the application. This part is updated with every change of the any of the files of the application - regardless whether it is a functional change, a documentation change or a change of the samples.

    - #### versionDataModel

          public static int versionDataModel

      The version of the data model supported by the code generator. This version is synchronized with the major parts of the tool version when but only when the data model is changed. Any change of the data model will lead to a change of at least one of the tool's two major version parts. A template should make a check of the data model version and create an error message if the data model version it is designed for differs from the one passed into the template by the tool.

      To make conditional code for error generation easier this version designation is an integer number. The number is composed as M*1000+m if M.m.f used to be the version designation of the tool when the data model was changed the last time.

      Please refer to isVersionDataModel for testing the data model version from a template.

    - #### isVersionDataModel

          public static java.util.Map<java.lang.String,java.lang.Boolean> isVersionDataModel

      The version designation versionDataModel for the data model, which is essential for relating templates to permitted, compatible tool revisions, is testable through this data element. It is a map with a single key, value pair. The value is Boolean true, the key is the String "v"+versionDataModel, e.g. v2012 for data model revision 2.12.

      A template can use an expressing like

                    <if(!isVersionDataModel.v2012)>#error Wrong tool revision, need data model 2.12<endif>

      to validate that it is running on a revision of the code generator tool, which supports the data model the template was designed for. (Any none matching key evaluates to a Boolean false.)

    - #### time

          public final java.lang.String time

      Time of code generation.

    - #### year

          public final java.lang.String year

      Year of date (as applicable for copyright notices).

    - #### templateFile

          public FileExt templateFile

      The StringTemplate V4 group template file as an extended Java File object. This object extends the Java class File by adding some information about parts of the file name (like its extension). Please refer to class FileExt.

      The information from the Java class File is partly accessible: All methods starting with get or is can be used by placing the method name without the syllable get/is into the template, e.g. would yield the return value of File.getName().

      Please refer to the online help of Java class File for details.

    - #### templateName

          public java.lang.String templateName

      The name of the StringTemplate V4 template used to render the information.

    - #### templateArgNameCluster

          public java.lang.String templateArgNameCluster

      The StringTemplate V4 template, which is used to render the information has an argument, that contains all network related information. This is the name of this argument.

    - #### templateArgNameInfo

          public java.lang.String templateArgNameInfo

      The StringTemplate V4 template, which is used to render the information has an argument, that contains general purpose information (e.g. data, time, file names). This is the name of this argument.

      The object passed in into the template under this argument name is an instance of this class codeGenerator.dataModelListener.Info.

    - #### templateWrapCol

          public java.lang.Integer templateWrapCol

      Information rendering can optionally apply line wrapping. If so then templateWrapCol is an Integer with the wrap column. Normally it is null and no wrapping takes place.

    - #### output

          public FileExt output

      The generated output file as an extended Java File object. This object extends the Java class File by adding some information about parts of the file name (like its extension). Please refer to class FileExt.

      The information from the Java class File is partly accessible: All methods starting with get or is can be used by placing the method name without the syllable get/is into the template, e.g. would yield the return value of File.getName().

      Please refer to the online help of Java class File for details.

    - #### envVarUSERNAME

          public static final java.lang.String envVarUSERNAME

      The value of the environment variable USERNAME.

    - #### envVarHOME

          public static final java.lang.String envVarHOME

      The value of the environment variable HOME.

    - #### envVarTMP

          public static final java.lang.String envVarTMP

      The value of the environment variable TMP.

    - #### envVarOS

          public static final java.lang.String envVarOS

      The value of the environment variable OS.

    - #### calc

          public java.util.Map<java.lang.String,java.lang.Object> calc

      This is a Java Map object, which can hold custom number objects. The normal operation of a number is to start at 0 and to count up each time it is referenced. These counters can be used to generate null based linear indexes in the generated code. However, special operations permit to use more general arithmetic and binary operations on the numbers. Furthermore, they can be compared against boundary values.

      Please note, unlike the other fields of `Info` does `calc` not bring any information into the template expansion process. It's an empty scratch pad for some simple arithmetics on numeric value (which need to come from other elements of the data model). The main use case it the support of linear counters (numeric enumerations) in the generated code and the possibility to have conditional code on numeric data elements like integer message attributes.

      All numbers are 64 Bit integers, all operations are 64 Bit integer operations.

      The reading of a number is got by simply querying it by name in the map. All of the more complex operations are submitted by using pseudo map element names, which encode number name, operation and operand at the same time. Reading the number and doing the comparisons are the only operations, which affect the template expansion: They return a numeric or Boolean object to engine and template. All other operations only have their side-effect on the addressed number in the map but return null to the template engine - no text will be generated from those.

      The pseudo element names have the pattern `<numberName>[_<operation>[_<operand>]]`. The operand either is a literal number or the name of an other number, which must already exist in the map.

      Literal numbers are either signed decimal numbers, which may have the suffix n or positive hexadecimal numbers with prefix 0x or one of the Boolean constants true and false. The suffix n means a negation of the decimal number literal. Examples are 12, -123, 123n or 0xffff.

      The negation suffix n has been added as an alternative to the common dash for sake of simple template writing. Using this syntax pattern enables using the simpler StringTemplate V4 map access operator `map.key`, where `map` and `key` need to be identifiers. This holds for literals. If the operand is a signed integer attribute from the data model one will anyway have to use the more complex access operator `map.(<sub-template>)` and here the usual rendering of negative values with the preceding dash would be applied. (Examples below.)

      The default for the optional operand depends on the operation. Most typical use cases are supported like linear counters and comparison with null.

      The destination number of the operation should already exist in the map. If it doesn't it is created by side effect. The initial value depends on the operation. This is only possible for a few operations like set, sadd, ssub and smul and referencing a number for read. Except for set, linear or logarithmic counters are assumed.

      The operations are set, get, add, sub, mul, div, sadd, ssub, smul, and, or, xor, not, sr, asr, sl, isGE, isLE, isG, isL, isE and isNE.

      set is the assignment. Only the value is assigned; if the operand is another number than its possible sticky operation (see below) is not inherited.

      get means reading a number. It is a unary operator and must not have an operand. The difference to normal reading by just stating the number's name is that a sticky post operation is not executed after reading. This is particular useful for debugging of the template code; values can be printed without altering the behavior of the code generation.

      add, sub, mul, div are the basic numeric operations.

      sadd, ssub, smul do the same as add, sub, mul but they are sticky, meaning that the operation is repeated every time after reading the number. This stickiness is how the counters are implemented. The sticky operation is cleared by applying any of the non sticky operations with the exception of set. Keeping the sticky operation for operation set further supports the use of counters as main purpose of the scratch pad: A counter can be adjusted to a new value but keeps counting as before.

      and, or, xor, not, sr, asr, sl are the binary operations, the latter three mean shifting. Note that not is a unary operator and must not have an operand.

      isGE, isLE, isG, isL, isE, isNE are the comparisons >=, <=, >, <, ==, !=, respectively. They yield a Boolean result, which is returned to the template engine and which can be used in a StringTemplate V4 conditional expression. Please note, the Boolean result is not assigned to the destination number; all of these operations do not alter the map contents, they just affect the code generation.

      The default operand of all comparisons is null. You can check if number x is negative by a simple `<info.calc.x_isL>`.

      Examples:

      `<info.calc.x>`: Read number x, i.e. return the numeric value to the template and expand it there into text. Create it as linear null based counter, if this should be the first reference to x. (x gets the initial value 0 and the sticky operation +1.)

      `<info.calc.x_mul_23n>`: Multiply x with -23.

      `<info.calc.y_set_0xff>`: Create y and set it to 255. No sticky operation is defined for y.

      `<info.calc.y_ssub_x>`: Assign the difference y-x to y. Next reading of y will yield this value but subtract the same value again as internal post operation; subtracting x's value is the sticky operation. Note, due to the post-processing y's internal value always differs from the one got from reading y. Note, the sticky operation subtracts x's value as it was at the evaluation time of this command, not x's current value meanwhile.

      `<info.calc.({noFrames_set_<cluster.noFrames>})>`: A typical way to get "real" numeric information into the initially empty scratch pad is the use of the StringTemplate V4 map operator `.()`, which builds the key to the wanted value by template expansion prior to querying the map.

      `<if(info.calc.noFrames_isG_0)>uint16 noFrames = <info.calc.noFrames>;<else><info.error.("No frames are defined!")><endif>`: Use of comparison operation to generate conditional output from a template.

      Since Boolean results are not stored back into the map just like that can Boolean expressions be computed only with the work around of using conditional template code. If we express the Boolean true as -1 and false as 0 then the available binary operators behave like Boolean operators; this is the meaning of the Boolean literals true and false:

      `<if(info.calc.x_isL_0)><info.calc.xBad_set_false><else><info.calc.xBad_set_true><endif><\\>`

      `<if(info.calc.x_isG_100)><info.calc.xTooLarge_set_true><else><info.calc.xTooLarge_set_false><endif><\\>`

      `<info.calc.xBad_or_xTooLarge><\\>`

      `<if(info.calc.xBad_isNE)>#error x (<info.calc.x>) is out of range [0; 100]<endif>`

    - #### optionMap

          public java.util.LinkedHashMap<java.lang.String,java.lang.Object> optionMap

      A map of user specified options or template attributes. User options are template attributes, which are simply passed through from the application's command line to the StringTemplate V4 template and can there be used to control the code generation. The use case are optional constructs in the generated code, which are controlled from the command line.

      User options/attributes can be given in the context of an in- or output file. This map holds all options given in the context of the currently generated output file. (Refer to `ExcelWorkbook.optionMap` for the input related options.)

      The name of an option or template attribute is the key into the map and the attribute's value is the value of the map entry. The value object's Java type is one out of String, Boolean, Integer or Double, depending on which fits best to the original command line argument; a command line argument cmdLineArg with value `true` would obviously be passed as Boolean into the template and would permit conditional code by using a construct like: `<if(info.optionMap.cmdLineArg)>Command line argument is TRUE!<endif>`

      A sorted map is used for the implementation. The map retains the order of appearance of options on the command line. A map iteration in the StringTemplate V4 template will yield this order. Example:

      `<info.optionMap:{name|<name>=<info.optionMap.(name)><\n>}>`

    - #### error

          public final excelExporter.excelParser.dataModel.ST4CmdInterpreter<java.lang.Integer,java.lang.Object> error

      This is a pseudo field of the StringTemplate V4 data model. If it is used from a template then it expands to nothing. It operates only by side-effect on its argument: The argument is treated as error message during code generation. It is printed to the code generator's application log and the code generation fails. It should be used if the conditional template code detects some unwanted state, like an empty list of frames for example:

      `<if(!bus.frameAry)><info.error.("There are no frames defined!")><endif>`

    - #### warn

          public final excelExporter.excelParser.dataModel.ST4CmdInterpreter<java.lang.Integer,java.lang.Object> warn

      This is a pseudo field of the StringTemplate V4 data model. If it is used from a template then it expands to nothing. It operates only by side-effect on its argument: The argument is treated as a warning during code generation. It is printed to the code generator's application log but the code generation continues. It should be used if the conditional template code detects some unwanted state, which can be tolerated. The example reports if there's only a single frame defined:

      `<if(!rest(bus.frameAry))><info.warn.("There's only one frame defined!")><endif>`

    - #### info

          public final excelExporter.excelParser.dataModel.ST4CmdInterpreter<java.lang.Integer,java.lang.Object> info

      This is a pseudo field of the StringTemplate V4 data model. If it is used from a template then it expands to nothing. It operates only by side-effect on its argument: The argument is treated as a informative output during code generation. It is printed to the code generator's application log and the code generation continues. It can be used to report some status information:

      `<info.info.(["There are ", length(bus.frameAry), " frames defined"])>`

    - #### debug

          public final excelExporter.excelParser.dataModel.ST4CmdInterpreter<java.lang.Integer,java.lang.Object> debug

      This is a pseudo field of the StringTemplate V4 data model. If it is used from a template then it expands to nothing. It operates only by side-effect on its argument: The argument is treated as a informative output during code generation. It is printed to the code generator's application log and the code generation continues. It can be used to report verbose progress information:

      `<bus.frameAry:{f|<info.debug.({Process frame <f.name>})>}>`

  - ### Constructor Detail

    - #### Info

          public Info(excelExporter.excelParser.ErrorCounter errCnt)

      Create the Info object.
      Parameters:
        `errCnt` - Template emitted and caused errors are counted in this object.

  - ### Method Detail

    - #### getNoCalcNumbers

          public int getNoCalcNumbers()

      The number of user stored numbers in the scratch pad `calc`. From a StringTemplate V4 template this member is accessed as `<info.noCalcNumbers>`.

    - #### getNoOptions

          public int getNoOptions()

      The number of user options in `optionMap`. From a StringTemplate V4 template this member is accessed as `<info.noOptions>`.

    - #### toString

          public java.lang.String toString()

      Get the string representation of the Info object; it's composed from some of some of its general fields.
      Overrides:
        `toString` in class `java.lang.Object`
      Returns:
        The string value

    - #### setApplicationInfo

          public static void setApplicationInfo(java.lang.String appName,
                                                int[] versionAry,
                                                int verDataModel)

      Set the information about this application.
      Parameters:
        `appName` - The application name.
        `versionAry` - The four parts of the version designation of the application
        `verDataModel` - The version of the data model for the templates.

    - #### setTemplateInfo

          public void setTemplateInfo(java.lang.String tFileName,
                                      java.lang.String tName,
                                      java.lang.String tArgCluster,
                                      java.lang.String tArgInfo,
                                      int tWrapCol)

      Fill the object with information about the template in use.
      Parameters:
        `tFileName` - The name of the template file.
        `tName` - The name of the template.
        `tArgCluster` - The name of the template argument with network information.
        `tArgInfo` - The name of the template argument with general information.
        `tWrapCol` - The wrap column or a value <= 0 if no wrapping takes place.

    - #### setOutputInfo

          public void setOutputInfo(java.lang.String fileName)

      Fill the information concerning the generated output file.
      Parameters:
        `fileName` - The name of the generated output file.

    - #### setUserOptions

          public void setUserOptions(java.util.LinkedHashMap<java.lang.String,java.lang.Object> map)

      Copy a map with user attributes by reference into the Info object.
      Parameters:
        `map` - The map with pairs of attribute names (key) and attribute values.

    - #### interpret

          public java.lang.Object interpret(java.lang.Integer logLevel,
                                            java.lang.String message)

      This method implements the command listener, which is used to emit a message to the application log under control of the currently expanded StringTemplate V4 template.
      Parameters:
        `logLevel` - The listener is connected to different command interpreters. The interpreters relate to the different logging severity levels and this information is passed in as context. The context is the integer value of the static Log4j Level objects, e.g. `Level`.
        `message` - The command string, which is interpreted as message to be logged.
      Returns:
        The function will always return null: The template engine must not generate any ouput because of the log command.