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

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.