org.vishia.util

Class OutTextPreparer

java.lang.Object

org.vishia.util.OutTextPreparer

public class OutTextPreparer
extends java.lang.Object

This class helps to prepare output texts with data. It is a more powerful text preparer in comparison to PrintStream.printf(String, Object...) or String.format(String, Object...). The first ones are only for number and date formatting. This class allows access to all Java data as placeholder values inclusively conditions and loops.

• It may be seen as small solution in comparison to JZtxtcmd only for text preparation of one or a few lines.
• In opposite to https://www.eclipse.org/xtend/ resolution for ''' TEXTs ''': The rule to build the text is given outside the programming language, for example in a text file able to control by a user. It is resolved on runtime, not on compile time. Hence it is able to use to control several texts by user.
• It may be seen as a better 'printf'. 'printf' is a text interpreter, in C too, but with lesser capability.

An instance of this class is used as formatter for an output text. The pattern to format can be given as String for the constructor or also as text file using readTemplateCreatePreparer(InputStream, String, Class, Map, String) in the following forms (example, text file via readTemplate...():

 
 <:otx: otxExample : data: placeholder >
 Output plain text with <&placeholder.value>
 <:if:data.cond>conditional output<:else>other variant<.if>
 <:for:var:data.container>element = <&var><.for>
 <:call:subtext:arg=data.var>
 <:exec:operation:data>
 <.otx>
 

To execute this script you should call (see createArgumentDataObj() and exec(Appendable, DataTextPreparer):

StringBuilder sb = new StringBuilder(500);    // for the output text
try {
  OutTextPreparer.DataTextPreparer args = mainOtx.createArgumentDataObj();
  args.setArgument("data", myData);           // The data class for access.
  args.setArgument("placeholder", "any test text");
  args.setExecObj(myExecObj)                  // for <:exec...>
  mainOtx.exec(sb, args);                     // execute the outText script 
} catch(Exception exc) {                      // unexpected exceptions can be occurred, catch it!
  CharSequence sExc = org.vishia.util.ExcUtil.exceptionInfo("unexpected", exc, 0, 10);
  System.err.println(sExc);
}    
 

Arguments
The arguments are simple identifier in the 3th argument of the constructor or in the given argument list in an textual script (see readTemplateCreatePreparer(InputStream, String, Class, Map, String)). or also possible on start of the script as <:args:var, var2>
Its values are set in the instance which should be gotten via createArgumentDataObj(). One of the importants is:

• The translated script of an OutTextPreparer after construction is given and persistent. It is never changed via exec(Appendable, DataTextPreparer). That means also, it can be used concurrently in several threads.
• The OutTextPreparer.DataTextPreparer which are created by call of createArgumentDataObj() should be used in an execution thread, the data should be set due to the after called exec(Appendable, DataTextPreparer). If executions of the same text pattern are executed in several threads, you can have only one reused instance of the OutTextPreparer but several instances of OutTextPreparer.DataTextPreparer, each for one execution thread. You can reuse this instance with exec(Appendable, DataTextPreparer) invocations one after another in the same thread.

The instance of the OutTextPreparer.DataTextPreparer must be matching to the OutputTextPreparer because internally only integer numbers are used for access.
To assign data to the named arguments use the OutTextPreparer.DataTextPreparer.setArgument(int, Object). That are your user data which can be accessed via <&arg1....> in your pattern. Compare it with the arguments of a printf, but with the difference that the possibilities to use the arguments are some more powerful, not only for numbers and date. But possibilities for number formatting are not given yet (maybe interesting, in future). For number formatting just call your java operations.

General to text and placeholder
All plain text is output as given. Only a few character sequences determine a placeholder with a processing functionality for data preparation and output. This sequences are only:

• <& start of a data access till ... >
• <: start for controlling statements till ... > but with:
• <. end of controling statements till ... >

To output exact this character sequences (for example to produce another OutTextPreparer script) you should use the capapbility <:SPECIAL TEXT> for example <:<&> to output a <& itself. See next list.

• <: > skips over all white spaces till the next placeholder
• <: > second time after a <: > stops skipping withspaces but outputs a space.
• <:?nl> skips till the next line (skips over the newline character in the script) (since 2023-05)
• <:? > skips over all white spaces till the next placeholder (since 2023-05)
• <:s> outputs a space (since 2023-05, alternatively usable to a second <: > )
• <:n> outputs a newline as 0x0a
• <:r> outputs a newline as 0x0d
• <:t> outputs a tabulator as 0x09
• <:x1234> outputs the UTF16 character with the given hexa code, here 1234
• <:CHARS> CHARS may be any special character sequences, they will be output as given, for example:
• <:<&var>> produces the text <&var> for generate a OutTextPreparer-Script itself.
• <:<&>var> produces the same <&var>, other writing style.
• <:<&><&var>> produces the text <&CONTENT> whereby CONTENT is the content of var. The truth is: <:<&> procuces the <&. Then <&var> generates the content of the variable, then a simple > follows in the text.

Generally, the plain text outside the placeholder syntax is read without skipping white spaces, hence this special features helps to structure this parts also with white spaces and line breaks. The syntax inside <&...> and <:...> is white space compliant.
Sometimes the script should be written in several lines, but only one line should be output. for example data from a container should be output, one per line. For that you can write (example) (since 2023-05):

 This is a title line
 <:for:element:container><:?nl>
     <&element.data> written with an indentation
 <.for><: >
 

In this script the line for data output should start with a new line, but the necessary first newline is already given after the title line. The newline after the <:for...> line should not be outputted. But in the script the output line should be written as extra line. For that the <:?nl> skips over the next newline in the script. Before 2023.05 the syntax was a little bit more complicated, that runs furthermore:

 This is a title line
 <:for:element:container><: >
 <: >    <&element.data> written with an indentation
 <.for><: >
 

Placeholder values and expression evaluation via reflection
A simple value is immediately gotten from the argument as set via OutTextPreparer.DataTextPreparer.setArgument(int, Object). or also as constant argument given in the 'execClass' or 'idxConstData' given on construction. This is a fast access, only to an container TreeMap or via indexed array access to the arguments.

If the <&data.element> is a more complex access expression then the capability of DataAccess is used. This accesses the elements via reflection. It means the given Class.getDeclaredFields(), Class.getDeclaredMethods() etc. are used to get the data, accessed via Field etc. The access is completely controlled in the DataAccess class. For usage it is simple.

The <&data.operation(arg) + otherdata> can be also a complex expression for numeric calculation, String concatenation and boolean evaluation. This expression is executed in CalculatorExpr with an interpreted approach. It means the calculation needs a longer time then executed in the Java-VM per bytecode/JIT machine code. But you can also prepare complex expressions by Java programming and call this expressions or operations. For that the 'execClass' class can be used which may contain prepared operations for your own. Hence you can decide writing simple expressions or also more complex as script or just as Java operations.

Control statements
It is interesting and important to produce an output conditional depending from data, and also from some container classes.

• <if:condition>conditional Text<elsif:condition>other Text<:else>else-Text<.if> The condition is an expression built with the CalculatorExpr.setExpr(StringPartScan, Map, Class, boolean)
  for example also a type check is possible: <:if:obj ?instanceof classXyz> whereas the classXyz can be given in the static reflection class as static variable as public static Class classXyz = MyClassXyz.class;
• <for:variable:container>text for any element <&variable.element> in loop <:if:variable_next>, <.if><.for>
  ##The next variable is also present, here to test whether a separator character should be output.

Call operations <:call:otxSubScript:arg=value:arg2=value,...>
The call operation invokes another script to output. The script is present with its own instance of OutTextPreparer, either manually programmed by the constructor or as part of the whole script see readTemplateCreatePreparer(InputStream, String, Class, Map, String).
The name of the 'otxScript' should be either found in the 'idxConstData' on construction or call of readTemplate...

 <:otx: otxSubScript : arg1: arg2>
 Any script pattern<.end>
 

or it should be found as static instance of a programmed OutTextPreparer in the 'execClass' given on construction:

 
  static final OutTextPreparer otxListColors = new OutTextPreparer("otxListColors"
  , null            //no static data on construction
  , "colors, text"  //arguments need and used
  , "<&text>: <:for:color:colors><&color><:if:color_next>, <.if><.for>");  //The pattern.
 

The association of arguments to the subscript argument variables is done on call from given values.

Execute operations in one given class
The 'execClass' as second argument of the constructor or the 3th argument of readTemplateCreatePreparer(InputStream, String, Class, Map, String) gives the possibility to have some static operations to call immediately maybe related to the script. The operations should be static because there are given in the script persistent without data. But they can have data arguments of course. That is powerful because you can use specific parts programmed in Java in your script.
Call that operations with <:exec:operation:arg1:arg...>.
It is similar to a data access written as <&path.to.StaticClass.operation(arg1,arg...) but it is faster parsed and executed due to the immediately given 'execClass'.

<:exec:operation:arg>:
The :arg is optional. The operation will be searched in the given reflection class (ctor argument). The operation is stored as Method for usage, so this operation is fast. The optional argument is used from given arguments of call, it should be match to the operations argument type. If the operation is not found, an exception with a detailed error message is thrown on ctor. If the operations argument is not proper, an exception is thrown on exec(Appendable, DataTextPreparer).

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
(package private) static class	OutTextPreparer.Argument
(package private) static class	OutTextPreparer.CallCmd
(package private) static class	OutTextPreparer.Cmd
(package private) static class	OutTextPreparer.CmdString
static class	OutTextPreparer.DataTextPreparer Instances of this class holds the data for one OutTextPreparer instance but maybe for all invocations.
(package private) static class	OutTextPreparer.DebugCmd
(package private) static class	OutTextPreparer.ECmd
(package private) static class	OutTextPreparer.ExecCmd
(package private) static class	OutTextPreparer.ForCmd
(package private) static class	OutTextPreparer.IfCmd
(package private) static class	OutTextPreparer.SetCmd

Field Summary

Fields

Modifier and Type	Field and Description
private java.util.List<OutTextPreparer.Cmd>	cmds
(package private) int	ctCall
private java.lang.Class<?>	execClass This is only stored as info, not used in this class.
protected java.util.Map<java.lang.String,java.lang.Object>	idxConstData Container with some const data given before parsing the scripts, also used to store parsed scripts which can be used to call on <:call:script:args>
private java.util.List<java.lang.String>	listArgs Via script given arguments for the outText.
private java.util.Map<java.lang.String,DataAccess.IntegerIx>	nameVariables All argument variables and internal variables sorted.
java.lang.String	pattern The source of the generation script, argument of parse(Class, String) only for debug.
java.lang.String	sIdent Name of the generation script used for debug and comparison with data.
static java.lang.String	version Version, history and license.

Constructor Summary

Constructors

Constructor and Description
OutTextPreparer(java.lang.String ident, java.lang.Class<?> execClass, java.util.List<java.lang.String> variables, java.lang.String pattern) Instantiates for a given pattern.
OutTextPreparer(java.lang.String ident, java.lang.Class<?> execClass, java.lang.String pattern) Instantiates for a given pattern.
OutTextPreparer(java.lang.String ident, java.lang.Class<?> execClass, java.lang.String variables, java.lang.String pattern) Constructs the text generation control data for the specific pattern.
OutTextPreparer(java.lang.String ident, java.lang.Class<?> execClass, java.lang.String variables, java.lang.String pattern, java.util.Map<java.lang.String,java.lang.Object> idxConstData) Constructs the text generation control data for the specific pattern and given sub pattern.

Method Summary

Modifier and Type	Method and Description
private OutTextPreparer.Cmd	addCmd(java.lang.String src, int from, int to, OutTextPreparer.ECmd ecmd, java.lang.String sDatapath, java.lang.Class<?> data) Explore the sDatapath and adds the proper Cmd
private void	addCmdSimpleVar(java.lang.String src, int from, int to, OutTextPreparer.ECmd eCmd, java.lang.String sName, java.lang.Class<?> execClass) Called if a simple <&name> is detected.
private OutTextPreparer.Cmd	addCmdSp(java.lang.String src, int from, int to, OutTextPreparer.ECmd ecmd, StringPartScan sDatapath, java.lang.Class<?> data) Explore the sDatapath and adds the proper Cmd
private void	addError(java.lang.String sError)
OutTextPreparer.DataTextPreparer	createArgumentDataObj() Returns an proper instance for argument data for a exec(Appendable, DataTextPreparer) run.
(package private) void	debug()
void	exec(java.lang.Appendable wr, OutTextPreparer.DataTextPreparer args) Executes preparation of a pattern with given data.
private void	execCall(java.lang.Appendable wr, OutTextPreparer.CallCmd cmd, OutTextPreparer.DataTextPreparer args, OutTextPreparer callVar) Executes a call
private void	execFor(java.lang.Appendable wr, OutTextPreparer.ForCmd cmd, int ixCmd, java.lang.Object container, OutTextPreparer.DataTextPreparer args) Executes a for loop
private int	execIf(java.lang.Appendable wr, OutTextPreparer.IfCmd ifcmd, int ixCmd, java.lang.Object data, OutTextPreparer.DataTextPreparer args) Executes a if branch
private void	execSub(java.lang.Appendable wr, OutTextPreparer.DataTextPreparer args, int ixStart, int ixEndExcl) Executes preparation for a range of cmd for internal control structures
OutTextPreparer.DataTextPreparer	getArgumentData(java.lang.Object execInstance) Creates the argument data and presets the given execInstance to OutTextPreparer.DataTextPreparer.setExecObj(Object)
private void	parse(java.lang.Class<?> execClass, java.lang.String pattern) Parse the pattern.
private void	parseArgs(StringPartScan sp)
private void	parseCall(java.lang.String src, int pos0, int pos1, StringPartScan sp, java.lang.Class<?> reflData)
private void	parseExec(java.lang.String src, int pos0, int pos1, StringPartScan sp, java.lang.Class<?> reflData)
private void	parseIf(java.lang.String pattern, int pos0, int pos1, OutTextPreparer.ECmd ecmd, StringPartScan sp, java.lang.Class<?> reflData)
private void	parseVariables(java.lang.String variables)
static java.util.Map<java.lang.String,java.lang.String>	readTemplate(java.io.InputStream inp, java.lang.String lineStart) Deprecated. use readTemplateCreatePreparer(InputStream, String, Class, Map, String) for all.
static java.util.Map<java.lang.String,OutTextPreparer>	readTemplateCreatePreparer(java.io.InputStream inp, java.lang.Class<?> execClass) You can use this variant instead readTemplateCreatePreparer(InputStream, String, Class, Map, String) if you have not specific const Data for parsing the script.
static OutTextPreparer	readTemplateCreatePreparer(java.io.InputStream inp, java.lang.String lineStart, java.lang.Class<?> execClass, java.util.Map<java.lang.String,java.lang.Object> idxConstData, java.lang.String sMainScript) Reads a given template which may contain the pattern for some associated OutTextPreparer also for call operations and instantiates all OutTextPreparer to execute the script.
private static void	readTemplateCreatePreparerPriv(java.io.InputStream inp, java.lang.String lineStart, java.lang.Class<?> execClass, java.util.Map<java.lang.String,java.lang.Object> idxConstData, java.util.Map<java.lang.String,OutTextPreparer> idxScript) internal implementation, see readTemplateCreatePreparer(InputStream, Class)
static java.util.List<java.lang.String>	readTemplateList(java.io.InputStream inp, java.lang.String lineStart) Reads a given template which may contain the pattern for some associated OutTextPreparer also for call operations
private void	setVariables(java.util.List<java.lang.String> listArgs)
java.lang.String	toString()
static void	writeOtx(java.io.File fout, java.lang.Object data, java.io.InputStream inTpl, java.lang.Class<?> execClass, java.lang.String sMain) Standard operation to write an output text from given data with a given template.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

version

public static final java.lang.String version

Version, history and license.

• 2023-08 up to now history to the operations
• 2023-06-18: frame of operation now <:otx:args>...<.otx>. The <.end> is no more supported, change it to <.otx> Usage of "=== name ( args) " is deprecated but yet still possible.
• 2023-06-18: bugfix on nested <:if>...<.if>
• 2023-05-16: the evaluation of a simple variable is now more simple organized in addCmdSimpleVar(String, int, int, ECmd, String, Class). This allows now also using the 'idxConstValues' for const texts.
• 2023-05-16: capability of <:x1234> any UTF16 char, not tested yet, should run
• 2023-05-16: some documentation and renaming: 'execClass' instead 'reflData', execClass instead 'clazzPattern'
• 2023-05-15: new Features <:? > as better syntax for skip spaces, <:?nl> skip after newline.
• 2023-05-12: new readTemplateCreatePreparer(InputStream, String, Class, Map, String) now works completely with a String file given script.
• 2022-04-17: new readTemplate(InputStream, String) to support texts from file. Used firstly for org.vishia.java2Vhdl.Java2Vhdl This is 2023-05-12 deprecated because readTemplateCreatePreparer(InputStream, String, Class, Map, String) does all and replaces it.
• 2022-02-11: little bit improved error message, hint to error position
• 2019-11-13: ## Comment in a line
• 2019-10-20: <: > capability
• 2019-08-26: StringPartScan instead String for CalculatorExpr.Operand#Operand(StringPartScan, Map, Class, boolean) yet not complete.
• 2019-08-26: <:args:....>
• 2019-05-08: Creation

Copyright/Copyleft: For this source the LGPL Lesser General Public License, published by the Free Software Foundation is valid. It means:

1. You can use this source without any restriction for any desired purpose.
2. You can redistribute copies of this source to everybody.
3. Every user of this source, also the user of redistribute copies with or without payment, must accept this license for further using.
4. But the LPGL is not appropriate for a whole software product, if this source is only a part of them. It means, the user must publish this part of source, but don't need to publish the whole source of the own product.
5. You can study and modify (improve) this source for own using or for redistribution, but you have to license the modified sources likewise under this LGPL Lesser General Public License. You mustn't delete this Copyright/Copyleft inscription in this source file.

If you are intent to use this sources without publishing its usage, you can get a second license subscribing a special contract with the author.

See Also:

Constant Field Values

nameVariables

private java.util.Map<java.lang.String,DataAccess.IntegerIx> nameVariables

All argument variables and internal variables sorted.

idxConstData

protected final java.util.Map<java.lang.String,java.lang.Object> idxConstData

Container with some const data given before parsing the scripts, also used to store parsed scripts which can be used to call on <:call:script:args>

pattern

public final java.lang.String pattern

The source of the generation script, argument of parse(Class, String) only for debug.

execClass

private final java.lang.Class<?> execClass

This is only stored as info, not used in this class. It is the argument execClass from the user, which is immediately evaluated in the parse(Class, String) operations while construction.

listArgs

private java.util.List<java.lang.String> listArgs

Via script given arguments for the outText. It does not contain the internal created variables.

ctCall

int ctCall

cmds

private java.util.List<OutTextPreparer.Cmd> cmds

sIdent

public final java.lang.String sIdent

Name of the generation script used for debug and comparison with data.

Constructor Detail

OutTextPreparer

public OutTextPreparer(java.lang.String ident,
                       java.lang.Class<?> execClass,
                       java.lang.String pattern)

Instantiates for a given pattern. See OutTextPreparer(String, Class, String, String) The variables are gotten from the pattern. For this case the order of variable depends on the order in the pattern. It is essential for access to data via index or via name. ...TODO see where

OutTextPreparer

public OutTextPreparer(java.lang.String ident,
                       java.lang.Class<?> execClass,
                       java.lang.String variables,
                       java.lang.String pattern)

Constructs the text generation control data for the specific pattern.

Parameters:

ident - Any identification not used for the generated text.

execClass - If the access via reflection should be done, null possible

variables - One variable or list of identifier separated with comma, whiteSpaces possible.

pattern - The pattern in string given form. This pattern will be parsed and divided in parts for a fast text generation.

Throws:

never - because the instantiation is possible especially for static variables. On faulty pattern the prepared cmd for output contains the error message.

OutTextPreparer

public OutTextPreparer(java.lang.String ident,
                       java.lang.Class<?> execClass,
                       java.lang.String variables,
                       java.lang.String pattern,
                       java.util.Map<java.lang.String,java.lang.Object> idxConstData)

Constructs the text generation control data for the specific pattern and given sub pattern. This is the preferred ctor for all capabilities. see also readTemplateCreatePreparer(InputStream, String, Class, Map, String) A constructor is called as: (example):

 static OutTextPreparer otxMyText = new OutTextPreparer (
   "otxMyText"                   // The name of the OutText usable for call
   , UserClass.class             // A class which's static operations and data can be used 
   , "arg1, arg2",               // Name of arguments, see text below
    "A simple text with newline: \n"  // The output text pattern
  + "<&arg1>: a variable value"
  + "<&arg1.operation(arg2)>: Invocation of any operation in arguments resulting in an text"  
  + "<:call:otxSubText:arg1>: call of any sub text maybe with args"
  + "<:exec:operation:arg1> : call of any static operation in the given reflection class maybe with args"
  ;

Parameters:

ident - Any identification not used for the generated text.

execClass - If the access via reflection should be done, null possible

variables - One variable or list of identifier separated with comma, whiteSpaces possible.

pattern - The pattern in string given form. This pattern will be parsed and divided in parts for a fast text generation.

idxConstData - Container for call able scripts, maybe contain all scripts, also for more const data

Throws:

never - because the instantiation is possible especially for static variables. On faulty pattern the prepared cmd for output contains the error message.

OutTextPreparer

public OutTextPreparer(java.lang.String ident,
                       java.lang.Class<?> execClass,
                       java.util.List<java.lang.String> variables,
                       java.lang.String pattern)

Instantiates for a given pattern. See OutTextPreparer(String, Class, String, String)

Parameters:

variables - Identifier given as list, parsing is not necessary. Able to use if the variable idents are anyway given in a list.

Method Detail

readTemplate

@Deprecated
public static java.util.Map<java.lang.String,java.lang.String> readTemplate(java.io.InputStream inp,
                                                                                         java.lang.String lineStart)
                                                                                  throws java.io.IOException

Deprecated. use readTemplateCreatePreparer(InputStream, String, Class, Map, String) for all.

Reads a given template which may contain the pattern for several separated OutTextPreparer. See also readTemplateList(InputStream, String)
The file can contain different patterns in segments:

 === patternName
 content <&withVariables>
 more lines
 
 === nextPatternName
   etc.
 

With this template Strings several OutTextPreparer can be created due to the schema (Example for Java2Vhdl)

    InputStream inTpl = Java2Vhdl.class.getResourceAsStream("VhdlTemplate.txt");  //pathInJar with slash: from root.
    Map tplTexts = OutTextPreparer.readTemplate(inTpl, "===");
    inTpl.close();
    this.vhdlHead = new OutTextPreparer("vhdlHead", null, "fpgaName", tplTexts.get("vhdlHead"));
    this.vhdlAfterPort = new OutTextPreparer("vhdlAfterPort", null, "fpgaName", tplTexts.get("vhdlAfterPort"));
    this.vhdlConst = new OutTextPreparer("vhdlConst", null, "name, type, value", tplTexts.get("vhdlConst"));
    this.vhdlCmpnDef = new OutTextPreparer("vhdlCmpnDef", null, "name, vars", tplTexts.get("vhdlCmpnDef"));
    this.vhdlCmpnCall = new OutTextPreparer("vhdlCmpnCall", null, "name, typeVhdl, preAssignments, vars", tplTexts.get("vhdlCmpnCall"));
    

Parameters:

inp - The open input to read, can also a resource in jar, then use Class.getResourceAsStream(String) to open

lineStart - String which marks a new pattern segment, for the exmaple it should be "=== "

Returns:

Map contains patternName and pattern String, without empty trailing lines.

Throws:

java.io.IOException

readTemplateList

public static java.util.List<java.lang.String> readTemplateList(java.io.InputStream inp,
                                                                java.lang.String lineStart)
                                                         throws java.io.IOException

Reads a given template which may contain the pattern for some associated OutTextPreparer also for call operations

Throws:

java.io.IOException

Since:

2023-05. See also #readTemplateCreatePreparer(InputStream, String, Class)
The file can contain different patterns in segments:

 <:otx: patternName : variable : var2 >  ##comment
 content with <&ariables>       ##comment
 more lines<.otx>
 
 free text between pattern
 
 <:otx: nextPatternName ...
   etc.
 

readTemplateCreatePreparer

public static OutTextPreparer readTemplateCreatePreparer(java.io.InputStream inp,
                                                         java.lang.String lineStart,
                                                         java.lang.Class<?> execClass,
                                                         java.util.Map<java.lang.String,java.lang.Object> idxConstData,
                                                         java.lang.String sMainScript)
                                                  throws java.io.IOException,
                                                         java.text.ParseException

Reads a given template which may contain the pattern for some associated OutTextPreparer also for call operations and instantiates all OutTextPreparer to execute the script.

Parameters:

inp - An opened input stream, which can be for example also part of a zip file content or gotten via Class.getResourceAsStream(String) from a jar file, or also of course via FileReader.FileReader(java.io.File) or via InputStreamReader.InputStreamReader(InputStream, String) to read a file with specific encoding.

lineStart - The pattern which marks the start of a output text. It was "===" in examples, now deprecated.

execClass - a given class which's content is accessed as persistent data.

idxConstData - An index to access const persistent data, and also to store all created OutTextPreparer instances. This is important for <:call:otx...>

sMainScript - name of the main script to return, or null.

Returns:

null or the requested main script. Note: All scripts can be found in idxConstData.

Throws:

java.io.IOException - on file error

java.text.ParseException - on parsing error of the script.

Since:

2023-05.
The file can contain different patterns in segments:

 <:otx: patternName : variable : variable2 >  ##comment
 content with <&variables>      ##comment
 more lines<.otx>
 
 free text between pattern
 
 <:otx: nextPatternName :args>
 <:call:patternName:variables = args> --- more text
 <.otx>
   etc.
 

readTemplateCreatePreparerPriv

private static void readTemplateCreatePreparerPriv(java.io.InputStream inp,
                                                   java.lang.String lineStart,
                                                   java.lang.Class<?> execClass,
                                                   java.util.Map<java.lang.String,java.lang.Object> idxConstData,
                                                   java.util.Map<java.lang.String,OutTextPreparer> idxScript)
                                            throws java.io.IOException,
                                                   java.text.ParseException

internal implementation, see readTemplateCreatePreparer(InputStream, Class)

Parameters:

inp -

lineStart -

execClass -

idxConstData -

idxScript -

Throws:

java.io.IOException

java.text.ParseException

Since:

2023-08 separated from readTemplateCreatePreparerPriv(InputStream, String, Class, Map, Map) which has only returned the main script.

readTemplateCreatePreparer

public static java.util.Map<java.lang.String,OutTextPreparer> readTemplateCreatePreparer(java.io.InputStream inp,
                                                                                         java.lang.Class<?> execClass)
                                                                                  throws java.io.IOException,
                                                                                         java.text.ParseException

You can use this variant instead readTemplateCreatePreparer(InputStream, String, Class, Map, String) if you have not specific const Data for parsing the script.

Parameters:

inp - An opened input stream, which can be for example also part of a zip file content or gotten via Class.getResourceAsStream(String) from a jar file, or also of course via FileReader.FileReader(java.io.File) or via InputStreamReader.InputStreamReader(InputStream, String) to read a file with specific encoding.

execClass - a given class which's content is accessed as persistent data.

Returns:

Map which contains all script operations. access to the desired script via get(name).

Throws:

java.io.IOException

java.text.ParseException

Since:

2023-08 as common usable operation for some OutText templates in one file. The constData processed in readTemplateCreatePreparer(InputStream, String, Class, Map, String) are usual not necessary for that approach, because it was the older concept to define some const data in the Map, and the Map is completed with the found scripts. Here now it is simpler, the operation returns the new Map filled with the content of the read script.

writeOtx

public static void writeOtx(java.io.File fout,
                            java.lang.Object data,
                            java.io.InputStream inTpl,
                            java.lang.Class<?> execClass,
                            java.lang.String sMain)
                     throws java.io.IOException

Standard operation to write an output text from given data with a given template.

Parameters:

fout - The file to write

data - Data for the output with the script, only one is possible.

inTpl - opened input stream which offers the otx-template to read. This inTpl is closed here after read.

execClass - a given class which's content is accessed as persistent data.

sMain - Name of the start or main template in the read script.

Throws:

java.io.IOException

Since:

2023-08, but it is limited for only one data. Hence it may be used only as template.

parseVariables

private void parseVariables(java.lang.String variables)

setVariables

private void setVariables(java.util.List<java.lang.String> listArgs)

parse

private void parse(java.lang.Class<?> execClass,
                   java.lang.String pattern)

Parse the pattern. This routine will be called only from the constructor.

Parameters:

ident - data instance to get data in the construction phase via reflection. It is used for identifier in the pattern which is not found in the variables (parameter 'variables' of ctor). It can be null.

Throws:

java.text.ParseException

parseArgs

private void parseArgs(StringPartScan sp)

parseIf

private void parseIf(java.lang.String pattern,
                     int pos0,
                     int pos1,
                     OutTextPreparer.ECmd ecmd,
                     StringPartScan sp,
                     java.lang.Class<?> reflData)

parseExec

private void parseExec(java.lang.String src,
                       int pos0,
                       int pos1,
                       StringPartScan sp,
                       java.lang.Class<?> reflData)

parseCall

private void parseCall(java.lang.String src,
                       int pos0,
                       int pos1,
                       StringPartScan sp,
                       java.lang.Class<?> reflData)

addError

private void addError(java.lang.String sError)

addCmdSimpleVar

private void addCmdSimpleVar(java.lang.String src,
                             int from,
                             int to,
                             OutTextPreparer.ECmd eCmd,
                             java.lang.String sName,
                             java.lang.Class<?> execClass)

Called if a simple <&name> is detected. It is searched firstly in idxConstData, then in nameVariables and at least in the execClass via Datapath access. If not found then is output on runtime. It adds the plain text if necessary and the data access as Cmd#Cmd(ECmd, int, DataAccess, Object, String) to the list of commands.

Parameters:

src - The text before to output the plain text before

from - range in src

to - to > from, then output the plain text

eCmd - The OutTextPreparer.ECmd for the Cmd

sName - name of the argument or variable or field.

execClass - to search in a data field.

addCmd

private OutTextPreparer.Cmd addCmd(java.lang.String src,
                                   int from,
                                   int to,
                                   OutTextPreparer.ECmd ecmd,
                                   java.lang.String sDatapath,
                                   java.lang.Class<?> data)

Explore the sDatapath and adds the proper Cmd

Parameters:

src - The pattern to get text contents

from - start position for text content

to - end position for text content, if <= from then no text content is stored (both = 0)

ecmd - The cmd kind

sDatapath - null or a textual data path. It will be split to CalculatorExpr.Operand.ixValue and CalculatorExpr.Operand.dataAccess

Returns:

the created Cmd for further parameters.

addCmdSp

private OutTextPreparer.Cmd addCmdSp(java.lang.String src,
                                     int from,
                                     int to,
                                     OutTextPreparer.ECmd ecmd,
                                     StringPartScan sDatapath,
                                     java.lang.Class<?> data)

Explore the sDatapath and adds the proper Cmd

Parameters:

src - The pattern to get text contents

from - start position for text content

to - end position for text content, if <= from then no text content is stored (both = 0)

ecmd - The cmd kind

sDatapath - null or a textual data path. It will be split to CalculatorExpr.Operand.ixValue and CalculatorExpr.Operand.dataAccess

Returns:

the created Cmd for further parameters.

createArgumentDataObj

public OutTextPreparer.DataTextPreparer createArgumentDataObj()

Returns an proper instance for argument data for a exec(Appendable, DataTextPreparer) run. The arguments should be filled using OutTextPreparer.DataTextPreparer.setArgument(String, Object) by name or OutTextPreparer.DataTextPreparer.setArgument(int, Object) by index if the order of arguments are known. The argument instance can be reused in the same thread by filling arguments newly for subsequently usage. If the exec(Appendable, DataTextPreparer) is concurrently executed (multiple threads, multicore processing), then any thread should have its own data.

Returns:

the argument instance.

getArgumentData

public OutTextPreparer.DataTextPreparer getArgumentData(java.lang.Object execInstance)

Creates the argument data and presets the given execInstance to OutTextPreparer.DataTextPreparer.setExecObj(Object)

Parameters:

execInstance - It should be an instance of the given reflection class on ctor.

Returns:

Data

exec

public void exec(java.lang.Appendable wr,
                 OutTextPreparer.DataTextPreparer args)
          throws java.io.IOException

Executes preparation of a pattern with given data. Note: The instance data of this are not changed. The instance can be used in several threads or multicore processing.

Parameters:

wr - The output channel

args - for preparation. The value instance should be gotten with createArgumentDataObj() proper to the instance of this, because the order of arguments should be match. It is internally tested.

Throws:

java.lang.Exception

java.io.IOException

execSub

private void execSub(java.lang.Appendable wr,
                     OutTextPreparer.DataTextPreparer args,
                     int ixStart,
                     int ixEndExcl)
              throws java.io.IOException

Executes preparation for a range of cmd for internal control structures

Parameters:

wr - The output channel

args - for preparation.

ixStart - from this cmd in cmds

Throws:

java.io.IOException

execIf

private int execIf(java.lang.Appendable wr,
                   OutTextPreparer.IfCmd ifcmd,
                   int ixCmd,
                   java.lang.Object data,
                   OutTextPreparer.DataTextPreparer args)
            throws java.io.IOException

Executes a if branch

Parameters:

wr - the output channel

cmd - The ForCmd

ixCmd - the index of the cmd in cmds

container - The container argument

args - actual args of the calling level

Throws:

java.lang.Exception

java.io.IOException

execFor

private void execFor(java.lang.Appendable wr,
                     OutTextPreparer.ForCmd cmd,
                     int ixCmd,
                     java.lang.Object container,
                     OutTextPreparer.DataTextPreparer args)
              throws java.io.IOException

Executes a for loop

Parameters:

wr - the output channel

cmd - The ForCmd

ixCmd - the index of the cmd in cmds

container - The container argument

args - actual args of the calling level

Throws:

java.lang.Exception

java.io.IOException

execCall

private void execCall(java.lang.Appendable wr,
                      OutTextPreparer.CallCmd cmd,
                      OutTextPreparer.DataTextPreparer args,
                      OutTextPreparer callVar)
               throws java.io.IOException

Executes a call

Parameters:

wr - the output channel

cmd - The CallCmd

args - actual args of the calling level

callVar - The OutTextPreparer which is called here.

Throws:

java.lang.Exception

java.io.IOException

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

debug

void debug()