org.vishia.util

Class OutTextPreparer

java.lang.Object

org.vishia.util.OutTextPreparer

public class OutTextPreparer
extends java.lang.Object

This class helps to prepare an output text with data.

• 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. On construction a pattern is given:

 static OutTextPreparer otxMyText = new OutTextPreparer("otxMyText", UserClass.class, "arg1, arg2",
    "A simple text with newline: \n"
  + "<&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 operation in the given reflection class maybe with args"
  + "");
 

Instead a given pattern in Java code it is possible to read the pattern from a file.

More specials

• <:args:var, var2> written on start of the script defines variable for the script.
• <:CHARS>: CHARS may be special chars, they will be outputted like given, for example
• <:<&var>> produces the text <&var> for generate a OutTextPreparer-Script itself.
• <:<&><&var>> produces the text <&CONTENT> whereby CONTENT is the content of var.
• Note that <:if etc. cannot be used for common texts, it is used as control statement:
• <if:condition>conditional Text<elsif:condition>other Text<else>else-Text<.if>
• <for:variable:container>text for any element <&variable> in loop <.for>
• <: > skips over whitespaces till next text, does not output the whitespaces, able to use for example to write a simple sequence in more as one line for better readability of the script.
• <: > <: > A second <: > after skipped whitespaces produces one space because it is not recognized as 'skip again' but as special character, here a space.
• ## Comment till end of line it is important for texts from a textual file.

 <:args:var, var2><: >
 <: >anyText after one space as indention
   <tag attrib="<&var>" >any xml output</tag> 
    <:<&var>>
 

It is proper for XML output generation. The last constructs a text containing "<&var>", it is to produce a OutTextPreparer pattern with OutTextPreparer itself. A "<: >" or "<:+>" skips over whiteSpaces, especially line feed, but immediately following "<: >" inserts one space.
Arguments of ctor : see also OutTextPreparer(String, Class, String, String):

• First arg: only a text for error reports
• Second: The reflection class where <:exec:operation> is searched
• 3.: All argument names
• last: The pattern to format the output.

Data for execution: A proper instance to store the argument data should be gotten via createArgumentDataObj(). It is possible to build this instance on construction in the ctor of the users organization class. Then this instance is reused (save calculation time for allocation and garbage), possible in single thread usage.

   public MyWriterClass() { 
     dataMyText =   otxMyText.getArgumentData(this);

If multithreading should be used (speed up generation time) to built output texts with the same instance of this, it is possible. This class is readonly and can be used without any restriction in multithreading, after it is contsructed. Any thread need its own instance of the OutTextPreparer.DataTextPreparer instance to work independent.

Call of preparation for output of a text:

    try {
      wr = new BufferedWriter(new FileWriter(toFile));
      dataMyText.setArgument("arg1", arg1Value);
      dataMyText.setArgument("arg2", arg2Value);
      otxMyText.exec(wr, dataMyText);
    } 
    catch(IOException exc) {....
 

The argument value are set. It is possible to use OutTextPreparer.DataTextPreparer.setArgument(int, Object) too if the order of arguments is known and definitely. It is faster because the position of the argument should not be searched (uses binary search, fast too). The it is executed. The output text is written in the given Appendable, it may be a StringBuilder too.

<: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
java.lang.Class<?>	clazzPattern
private java.util.List<OutTextPreparer.Cmd>	cmds
(package private) int	ctCall
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<?> reflData, java.util.List<java.lang.String> variables, java.lang.String pattern) Instantiates for a given pattern.
OutTextPreparer(java.lang.String ident, java.lang.Class<?> reflData, java.lang.String pattern) Instantiates for a given pattern.
OutTextPreparer(java.lang.String ident, java.lang.Class<?> reflData, java.lang.String variables, java.lang.String pattern) Constructs the text generation control data for the specific 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 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<?> reflData, 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) Reads a given template which may contain the pattern for several OutTextPreparer.
private void	setVariables(java.util.List<java.lang.String> listArgs)
java.lang.String	toString()

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.

• 2022-04-17: new readTemplate(InputStream, String) to support texts from file. Used firstly for org.vishia.java2Vhdl.Java2Vhdl
• 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.

pattern

public final java.lang.String pattern

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

clazzPattern

public final java.lang.Class<?> clazzPattern

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<?> reflData,
                       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<?> reflData,
                       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.

reflData - 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<?> reflData,
                       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

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

Reads a given template which may contain the pattern for several OutTextPreparer. The file can contain different patterns in segments:

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

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

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<?> reflData,
                   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)

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()