Package ca.cgjennings.util

Class CommandFormatter

  • Direct Known Subclasses:
    DefaultCommandFormatter
    public class CommandFormatter
extends java.lang.Object
    Parses strings that represent a command line into a list of arguments, possibly performing simple variable replacements.
    Since:
    3.0
    Author:
    Chris Jennings

    • Constructor Summary

      Constructors 
      Constructor Description
      CommandFormatter()
      Creates a new command formatter that has no variables defined except the reserved % variable.
      CommandFormatter​(java.lang.String... variableDefinitions)
      Creates a new command formatter, populating the table of variables from an array of strings.
      CommandFormatter​(java.util.Map<java.lang.String,​java.lang.String> variableMap)
      Creates a new command formatter, populating the table of variables from a map.

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      java.lang.String evaluateVariable​(char name)
      Evaluates a variable to return its string expansion in a formatted command.
      java.lang.String[] formatCommand​(java.lang.String template)
      Given a template for a command line that may include variables, returns an array of the tokens that make up the command.
      java.lang.Object getVariable​(char name)
      Returns the value of a variable, or null if the variable is not defined.
      void setVariable​(char name, java.lang.Object value)
      Defines a variable that will replaced when formatting a command.

      • Methods inherited from class java.lang.Object

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

    • Constructor Detail

      • CommandFormatter

        public CommandFormatter()
        Creates a new command formatter that has no variables defined except the reserved % variable.

      • CommandFormatter

        public CommandFormatter​(java.lang.String... variableDefinitions)
        Creates a new command formatter, populating the table of variables from an array of strings. This array must contain an even number of strings, forming a number of pairs. The first string of each pair is a one character variable name, and the second is the value to assign to that name.
        Parameters:
        variableDefinitions - an array of name, value pairs
        Throws:
        java.lang.IllegalArgumentException - if a variable name is missing a value, or if any name is not exactly one character
        java.lang.NullPointerException - if the array or any element in it is null

      • CommandFormatter

        public CommandFormatter​(java.util.Map<java.lang.String,​java.lang.String> variableMap)
        Creates a new command formatter, populating the table of variables from a map.
        Parameters:
        variableMap - a map from variable names to their values
        Throws:
        java.lang.NullPointerException - if any map entry is null
        java.lang.IllegalArgumentException - if any key does not have length 1 or is the % symbol

    • Method Detail

      • setVariable

        public void setVariable​(char name,
                        java.lang.Object value)
        Defines a variable that will replaced when formatting a command. When a percent sign (%) occurs in a command template and is followed by this variable name, it will be replaced by calling value.toString(). Setting a variable name to null will remove the variable, if it has been defined. The variable % is reserved so that the sequence "%%" always produces "%" in the formatted command.
        Parameters:
        name - the variable name
        value - the value for the variable
        Throws:
        java.lang.IllegalArgumentException - if name is the percent sign

      • getVariable

        public java.lang.Object getVariable​(char name)
        Returns the value of a variable, or null if the variable is not defined.
        Parameters:
        name - the variable name
        Returns:
        the object assigned to the variable

      • evaluateVariable

        public java.lang.String evaluateVariable​(char name)
        Evaluates a variable to return its string expansion in a formatted command. This is done by obtaining the variable's assigned value and calling its toString() method.
        Parameters:
        name - the name of the variable to evaluate
        Returns:
        a string representing the value of the variable
        Throws:
        java.lang.IllegalArgumentException - if the variable has no assigned value

      • formatCommand

        public java.lang.String[] formatCommand​(java.lang.String template)
        Given a template for a command line that may include variables, returns an array of the tokens that make up the command. Tokens are separated by whitespace, except that tokens
        Parameters:
        template - the command template to tokenize
        Returns:
        the tokens in the command, with variables replaced
        Throws:
        java.lang.IllegalArgumentException - if a variable is used that has no assigned value (last character of the message is the variable name)