Package eu.bandm.tools.expander

Class ParameterExpander

java.lang.Object
eu.bandm.tools.expander.ParameterExpander
public class ParameterExpander extends Object
Processor for parameter substitution in character streams. Every recognized parameter reference in the input stream is expanded to a specified value in the output stream.

Parameter References

Parameters references are of the form ESC+'{'+ name+'}', where ESC is a configurable nonempty constant prefix string, and name is a valid Java identifier starting with a lower-case letter. Compounds may be structured by internal capitalization (camel case). The default prefix is "$". Examples: ${param}, ${anotherParam}.

If a parameter reference is recognized, and a value has been specified (via substitution or the command line), then the reference is removed from the character stream, and replaced by the value. References to unknown parameters and syntactic fragments that do not constitute a well-formed reference are left untouched.

Java identifiers that start with an upper case letter are reserved for intrinsic operations. The names of these are otherwise case-insensitive; for interoperability a form that uses only upper case is recommended.

Java identifiers that do not start with a letter are reserved for future use.

Command Line Intrinsics

When this class is run as a command line application, the following intrinsic parameters expand to pre-defined values:

NOW
ISO-8601 representation of the time when processing has started.
INPUTS
A space-separated list of all input file arguments.
SUBST
A space-separated list of name=value pairs of the defined parameters.
There is a more complex command line tool in ParameterExpander_main which takes multiple substitution from a text file input and can process multiple input files to multiple outputs in one single run.

Conditional Sections

Arbitrary sections of input text may be included from or excluded in the output, depending on whether a parameter has a specified non-empty value.

IF name
Marks the beginning of a section that is only included if parameter name has a specified value that is not the empty string. The section extends until a matching ELSE or ENDIF reference, or until the end of input.
ELSE
Ends the current conditional section and starts a section that is only included in the opposite case, that is if the named parameter has no specified value or is set to the empty string. If there is no current conditional section, then an excluded section is started.
ENDIF
Ends the current conditional section. Enclosing conditional sections remain in effect. If there is no current conditional section, then nothing happens.

Conditional sections may be nested. Text is included if and only if there is no enclosing section that is being excluded.

Command Line Syntax

FIXME DOKU WEITERMACHEN ?? SONAR-BT

  • Field Details

  • Constructor Details

    • ParameterExpander

      public ParameterExpander(String escape, Consumer<String> receiveWarnings)
      Only constructor, sets the escape string to be applied when running this instance.

  • Method Details

    • userParameter

      @Opt public static @Opt ParameterExpander.Parameter userParameter(String name)
      Constructs a new parameter object if the given name is a valid user parameter name. This includes non-emptiness, lower case start, only valid Java id characters, etc. see class documentation.
      Returns:
      null if not a valid user parameter name

    • systemParameter

      @Opt protected static @Opt ParameterExpander.Parameter systemParameter(String name)
      Constructs a new parameter object if the given name is a valid system (= predefined) parameter name. This includes non-emptiness, upper case start, only valid Java id characters, etc. see class documentation.
      Returns:
      null if not a valid user parameter name

    • substitution

      public Map<ParameterExpander.Parameter,String> substitution()
      Return the map from parameter instances to their substitution text. The delivered refernce is directly to the mutable map, applied when running.

    • process

      public void process(Reader in, Writer out) throws IOException
      evident
      Throws:
      IOException

    • main

      public static void main(String[] args) throws IOException
      Run an instance of this class as a command line tool.

      Every command line argument that contains the character '=' is assumed to be a parameter specifier of the form name+'='+value.

      Command line arguments that do not contain the character '=' are assumed to be names of input files. All named files are processed in order, and the output is concatenated. If there is no named input file, then input is read from System.in. Output is always written to System.out.

      The behavior can be configured via system properties:
      eu.bandm.tools.util.ParameterExpander.encoding
      The name of the encoding to use for input and output stream (default: "UTF-8").
      eu.bandm.tools.util.ParameterExpander.escape
      The nonempty escape prefix (default: "$").
      Throws:
      IOException

    • setPredefinedParameters

      public void setPredefinedParameters(Collection<String> inputs)
      Stores to substitution the values of the predfined system parameters for this run.

    • parseArgument

      public static void parseArgument(String arg, List<String> inputs, Consumer<String> receiveWarnings, Map<ParameterExpander.Parameter,String> substitution)
      Analyses one command line argument and puts it to the given substituion map or the list of inputs, depending on an appearing '='.

    • getSubstValue

      public String getSubstValue()
      Build a string representation of all map entries in substitution.

    • getNowValue

      public static String getNowValue()
      Return the current date in ISO format.

    • getInputsValue

      public static String getInputsValue(Collection<String> inputs)
      Build a string representation of file names in the given collection.

    • unfoldRecursiveSubstitutions

      public void unfoldRecursiveSubstitutions()
      Apply the substitution as defined by this ParameterExpander to the replacement text assigend to all parameters. The number of repeated substitution runs is limited, and cyclic dependencies will thus not hang the execution, but will not be resolved. This is signalled by a warning text printed to System.err.