Package eu.bandm.tools.expander

Class ParameterExpander

java.lang.Object
eu.bandm.tools.expander.ParameterExpander
@PropertyDependency({"eu.bandm.tools.util.ParameterExpander.encoding","eu.bandm.tools.util.ParameterExpander.escape"}) @ResourceDependency("project-info.properties") 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 (programmatically or on the command line), then the reference is removed from the character stream, and replaced by the value. This process is recursive; the value may contain more parameter references to be replaced. Termination is enforced by stopping the unfolding after a reasonable number of iterations. 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.

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 the invocation of ELSE is left unreplaced.
ENDIF
Ends the current conditional section. Enclosing conditional sections remain in effect. If there is no current conditional section, then the invocation of ENDIF is left unreplaced.

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

Command Line

This class defines a main method and can be run as a command line application. See the documentation of main(java.lang.String[]) for the syntax.

The command line interface of this class is rudimentary, and designed for use in situations where dependencies on more sophisticated tools must be avoided.

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.
EXPANDER
A qualified name that identifies this tool.
VERSION
The version of this tool.

  • Field Details

  • Constructor Details

    • ParameterExpander

      public ParameterExpander(Consumer<String> receiveWarnings)
      Create a new tool instance with the default escape prefix.
      Parameters:
      receiveWarnings - where warnings are sent to

    • ParameterExpander

      public ParameterExpander(String escape, Consumer<String> receiveWarnings)
      Create a new tool instance with a given escape prefix.
      Parameters:
      escape - the escape prefix
      receiveWarnings - where warnings are sent to
      Throws:
      IllegalArgumentException - if the escape prefix is the empty string

  • 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.

      The given name is validated, see the syntax description; in particular, user parameter names must start with a lower-case letter. If it is not valid, null is returned.

      Parameters:
      name - the parameter name
      Returns:
      a new parameter object if valid; null otherwise

    • systemParameter

      @Opt protected static @Opt ParameterExpander.Parameter systemParameter(String name)
      Constructs a new parameter object, if the given name is a valid user parameter name.

      The given name is validated, see the syntax description; in particular, system parameter names must start with an upper-case letter. If it is not valid, null is returned.

      Parameters:
      name - the parameter name
      Returns:
      a new parameter object if valid; null otherwise

    • substitution

      public Map<ParameterExpander.Parameter,String> substitution()
      Access the substitution map.

      The returned map should not be modified concurrently while character streams are being processed.

      Returns:
      the mutable substitution map
      See Also:

    • process

      public void process(Reader in, Writer out) throws IOException
      Processes a character stream with this tool instance.

      Several character streams can be processed with the same tool instance, both sequentially and concurrently. The tool-wide settings (escape prefix, substitution map, warning output channel) apply uniformly to all processing jobs.

      Parameters:
      in - the character input stream
      out - the character output stream
      Throws:
      IOException - if something goes wrong

    • main

      @Deprecated(since="1.0", forRemoval=false) public static void main(String[] args) throws IOException
      Deprecated.
      Use more sophisticated front-end tools if available.
      Runs 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: "$").
      Parameters:
      args - the command line arguments
      Throws:
      IOException - if something goes wrong

    • setPredefinedParameters

      public void setPredefinedParameters(Collection<String> inputs)
      Stores the values of the predefined system parameters for this tool instance.

      The value of parameter NOW is computed implicitly from the current system time.

      The value of parameterSUBST does not reflexively include the system parameters being set.

      Parameters:
      inputs - the list of input files
      See Also:

    • parseArgument

      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()
      Builds a string representation of all substitution map entries.
      Returns:
      a space-separated list of parameter name–value pairs

    • getNowValue

      public static String getNowValue()
      Builds a string representation of the current date and time.
      Returns:
      the current date and time in ISO-8601 format

    • getInputsValue

      public static String getInputsValue(Collection<String> inputs)
      Builds a string representation of the given file names.
      Parameters:
      inputs - the list of file names
      Returns:
      a space-separated list of the given file names

    • getVersionValue

      public static String getVersionValue()
      Builds a version string that identifies this tool.

      The result is suitable for the version parameter of a Generated annotation in source code generated by this tool.

      Returns:
      the version of this tool
      See Also:

    • getExpanderValue

      public static String getExpanderValue()
      Builds a qualified name that identifies this tool.

      The result is suitable for the generator parameter of a Generated annotation in source code generated by this tool.

      Returns:
      the qualified name of this tool
      See Also:

    • unfoldRecursiveSubstitutions

      public void unfoldRecursiveSubstitutions()
      Apply the currently defined substitutions recursively to all of the contained values.

      The number of repeated substitution runs is limited, and cyclic dependencies will thus not hang the execution, but will not be resolved. A warning is issued in that case.

      If this operation completes normally without a warning, it is idempotent. It only needs to be called again if new the substitution map changes.