Module jamal.tools
Package javax0.jamal.tools

Class InputHandler

java.lang.Object
javax0.jamal.tools.InputHandler
public class InputHandler
extends Object
Utility class with some simple static methods that fetch characters from an input buffer.

  • Method Summary

    Modifier and Type Method Description
    static boolean contains​(int i)  
    static String convertGlobal​(String id)
    Convert a global macro name.
    static void eatEscapedNL​(javax0.jamal.api.Input input)
    Delete the white space characters from the start of the input up to and including the next new-line character, but only if there is a new-line character following zero or more non-new-line white space characters and the very first character IS a back-slash \.
    static String[] ensure​(String[] parameters, javax0.jamal.api.Position ref)
    Checks that no parameter name contains another parameter name.
    static String fetch2EOL​(javax0.jamal.api.Input input)
    Delete the characters from the start of the input until after the first EOL and return the deleted start as a String.
    static String fetchId​(javax0.jamal.api.Input input)
    Fetch an id from the start of the input.
    static boolean firstCharIs​(CharSequence s, char... chars)
    Checks that the first character of the input is one of the characters listed.
    static String[] getParameters​(javax0.jamal.api.Input input, String id)
    Get the parameter list that is at the start of the input.
    static String[] getParts​(javax0.jamal.api.Input input)
    Parse the input and split it up into a String array.
    static String[] getParts​(javax0.jamal.api.Input input, int limit)
    Same as getParts(Input) but we want at most limit number of parts.
    static boolean isGlobalMacro​(String id)
    Checks that the identifier is global or not.
    static void move​(javax0.jamal.api.Input input, int numberOfCharacters, StringBuilder sb)
    Deprecated.
    Use the method move(Input, int, Input) method instead.
    static void move​(javax0.jamal.api.Input input, int numberOfCharacters, javax0.jamal.api.Input output)
    Same as skip(Input, int) but it also appends the deleted characters to the output.
    static void move​(javax0.jamal.api.Input input, String s, javax0.jamal.api.Input output)
    Copy the string from the start of the input to the end of the output.
    static void moveWhiteSpaces​(javax0.jamal.api.Input input, StringBuilder sb)
    Same as skipWhiteSpaces(Input) but it also appends the deleted spaces to the string builder.
    static void moveWhiteSpaces​(javax0.jamal.api.Input input, javax0.jamal.api.Input output)
    Same as skipWhiteSpaces(Input) but it also appends the deleted spaces to the output.
    static void rtrim​(javax0.jamal.api.Input input)
    Delete the white space character from the end of the input.
    static void skip​(javax0.jamal.api.Input input, int numberOfCharacters)
    Delete the start of the input.
    static void skip​(javax0.jamal.api.Input input, String s)
    Delete the start of the input.
    static void skip2EOL​(javax0.jamal.api.Input input)
    Delete the characters from the start of the input until after the first EOL
    static void skipWhiteSpaces​(javax0.jamal.api.Input input)
    Delete the white space characters from the start of the input
    static void skipWhiteSpaces2EOL​(javax0.jamal.api.Input input)
    Delete the white space characters from the start of the input but only until after the first EOL
    static void skipWhiteSpacesNoNL​(javax0.jamal.api.Input input)
    Delete the white space characters from the start of the input but do not delete \n characters.
    static int startsWith​(CharSequence s, String... strings)  
    static void trim​(javax0.jamal.api.Input input)
    Delete the white space character from the start and from the end of the input.

    Methods inherited from class java.lang.Object

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

  • Method Details

    • firstCharIs

      public static boolean firstCharIs​(CharSequence s, char... chars)
      Checks that the first character of the input is one of the characters listed.
      Parameters:
      s - a character sequence of which the first character is checked
      chars - the characters we are looking for
      Returns:
      true if the first character of s is one of the chars. Returns false if the character sequence is empty or the first character is none of the chars.

    • startsWith

      public static int startsWith​(CharSequence s, String... strings)
      Parameters:
      s - a character sequence of which the start is checked
      strings - the possible strings to check that the sequence starts with
      Returns:
      the index of the string that the sequence starts with or -1 if the sequence does not start with any of the strings

    • skip

      public static void skip​(javax0.jamal.api.Input input, int numberOfCharacters)
      Delete the start of the input. It is an error trying to delete more character than the number of characters there are in the input.
      Parameters:
      input - from which the first characters are deleted
      numberOfCharacters - the number of characters to be deleted from the start of input

    • move

      @Deprecated public static void move​(javax0.jamal.api.Input input, int numberOfCharacters, StringBuilder sb)
      Deprecated.
      Use the method move(Input, int, Input) method instead. The interface `Input` extends CharSequence and can give access to an underlying StringBuilder. Instead of creating a StringBuilder, invoke Input.makeInput() and use that instead of the StringBuilder.

      The reason to deprecate this method is to avoid use when the characters are first moved to a StringBuilder and then a new Input is created from the StringBuilder. This approach may loose the position information that later implementations of move(Input, int, Input) may also copy.

      Same as skip(Input, int) but it also appends the deleted characters to the string builder.
      Parameters:
      input - from which the first characters are deleted
      numberOfCharacters - the number of characters to be deleted from the start of input
      sb - where the characters will be appended

    • move

      public static void move​(javax0.jamal.api.Input input, int numberOfCharacters, javax0.jamal.api.Input output)
      Same as skip(Input, int) but it also appends the deleted characters to the output.
      Parameters:
      input - from which the first characters are deleted
      numberOfCharacters - the number of characters to be deleted from the start of input
      output - where the characters will be appended

    • move

      public static void move​(javax0.jamal.api.Input input, String s, javax0.jamal.api.Input output)
      Copy the string from the start of the input to the end of the output.

      Note that this is a convenience method for move(Input, int, Input). There is no check that the input really starts with the characters contained by s.

      Parameters:
      input - from which the string will be removed
      s - the string. There is no check that the input really starts with the string. The string is skip(Input, String)-ped in the input and is appended to the output.
      output - to which the string will be appended

    • skip

      public static void skip​(javax0.jamal.api.Input input, String s)
      Delete the start of the input.
      Parameters:
      input - from which the first characters are deleted
      s - is a string that is supposed to be on the start of the input and this string is going to be deleted from the start of the input. The actual implementation does not check that the string is really there at the start of the input, it just skips so many characters as many the string has.

    • contains

      public static boolean contains​(int i)
      Parameters:
      i - the result of String.indexOf(int)
      Returns:
      true the value is a valid character code and not a signal that the string does not contain the character we are looking for.

    • fetchId

      public static String fetchId​(javax0.jamal.api.Input input)
      Fetch an id from the start of the input.

      An identifier is a string that starts with a character accepted by Macro.validId1stChar(char) and contain only characters that are accepted Macro.validIdChar(char)

      or

      a string that starts with some special character, which usually can not be part of an identifier and does not contain space. This way you can have macros like 

      

        {@define =hatto (x)=belxanto}{#define {=hatto /1}(x) =tttxttt}{bel1anto/_}
      which is an experimental feature and is deliberately not documented except here.
      Parameters:
      input - that contains the identifier at the start. The identifier will be removed at the end of the method.
      Returns:
      the identifier string that was found and removed from the start of the input.

    • isGlobalMacro

      public static boolean isGlobalMacro​(String id)
      Checks that the identifier is global or not. The check simply looks for embedded ':' character in the identifier.
      Parameters:
      id - the identifier to check
      Returns:
      true if the identifier is a global identifier.

    • convertGlobal

      public static String convertGlobal​(String id)
      Convert a global macro name.

      Macro names that contain the ':' character are global macros and automatically are defined on the top level. This provides a way to macro package developers to use name spacing, although Jamal does not handle name spaces, the names can be treated as 'namespace:localName' or even name space notations can be nested.

      A global macro without name space starts with a ':' character when defined but this character is removed by this conversion so later the macro can be referred to with the name without the : character.

      Parameters:
      id - the identifier of the macro.
      Returns:
      the converted identifier.

    • skipWhiteSpaces

      public static void skipWhiteSpaces​(javax0.jamal.api.Input input)
      Delete the white space characters from the start of the input
      Parameters:
      input - from which the spaces should be deleted.

    • skipWhiteSpacesNoNL

      public static void skipWhiteSpacesNoNL​(javax0.jamal.api.Input input)
      Delete the white space characters from the start of the input but do not delete \n characters. If it sees a \n character then stop with the deletion.
      Parameters:
      input - from which the spaces (but no \n)should be deleted.

    • skipWhiteSpaces2EOL

      public static void skipWhiteSpaces2EOL​(javax0.jamal.api.Input input)
      Delete the white space characters from the start of the input but only until after the first EOL
      Parameters:
      input - from which the spaces should be deleted.

    • moveWhiteSpaces

      public static void moveWhiteSpaces​(javax0.jamal.api.Input input, StringBuilder sb)
      Same as skipWhiteSpaces(Input) but it also appends the deleted spaces to the string builder.
      Parameters:
      input - from which the spaces should be deleted.
      sb - where the spaces will be appended

    • moveWhiteSpaces

      public static void moveWhiteSpaces​(javax0.jamal.api.Input input, javax0.jamal.api.Input output)
      Same as skipWhiteSpaces(Input) but it also appends the deleted spaces to the output.
      Parameters:
      input - from which the spaces should be deleted.
      output - where the spaces will be appended

    • trim

      public static void trim​(javax0.jamal.api.Input input)
      Delete the white space character from the start and from the end of the input.
      Parameters:
      input - from which the spaces should be deleted.

    • rtrim

      public static void rtrim​(javax0.jamal.api.Input input)
      Delete the white space character from the end of the input.
      Parameters:
      input - from which the spaces should be deleted.

    • eatEscapedNL

      public static void eatEscapedNL​(javax0.jamal.api.Input input)
      Delete the white space characters from the start of the input up to and including the next new-line character, but only if there is a new-line character following zero or more non-new-line white space characters and the very first character IS a back-slash \.

      This method is used when the option nl is in effect that says that any new line character that follows a macro closing string should be consumed and not put into the output. This helps writing better looking output easier and not caring too much about the new lines.

      If there are some spaces immediately before the new-line they will also be deleted, because they cannot easily be recognized by the person editing the file and we want to avoid mysterious errors.

      Parameters:
      input - from which the spaces and the new-line should be deleted.

    • skip2EOL

      public static void skip2EOL​(javax0.jamal.api.Input input)
      Delete the characters from the start of the input until after the first EOL
      Parameters:
      input - from which the spaces should be deleted.

    • fetch2EOL

      public static String fetch2EOL​(javax0.jamal.api.Input input)
      Delete the characters from the start of the input until after the first EOL and return the deleted start as a String. The returned string does not contain the closing new line, but the closing new line is removed from the input.
      Parameters:
      input - from which the spaces should be deleted.
      Returns:
      the string from the original start of the input to the end of line, not including the end of line

    • getParameters

      public static String[] getParameters​(javax0.jamal.api.Input input, String id) throws javax0.jamal.api.BadSyntaxAt
      Get the parameter list that is at the start of the input. The parameter list has to start with a ( character and should be closed with a ) character. The parameters are separated by , characters, and starting and ending spaces from the parameters are removed. 
               ( a,b, c ,d)

      There is no restriction on what characters the parameter names can contain other than those implied by the parsing algorithm: you cannot use ) and , characters in a parameter and you cannot have space at the start and at the end of the parameter. It is recommended not to abuse this possibility.

      Parameters:
      input - that contains the parameter list
      id - the id of the macro that has this parameter list. This parameter is only used for error reporting.
      Returns:
      the array containing the parameter, or an empty (zero length) array if there are no parameters (when the first character is not ( opening paren)
      Throws:
      javax0.jamal.api.BadSyntaxAt - when the input starts with a ( character, therefore it is supposed to have parameters but the parameter list if any is not closed with a ) character.

    • ensure

      public static String[] ensure​(String[] parameters, javax0.jamal.api.Position ref) throws javax0.jamal.api.BadSyntaxAt
      Checks that no parameter name contains another parameter name. If there is any parameter name that contains another parameter name then BadSyntax is thrown.

      This restriction ensures that the parameter replacement with the actual values is definite and there are no readability issues.

      Parameters:
      parameters - the parameters to check
      ref - the position in the input
      Returns:
      the parameters themselves
      Throws:
      javax0.jamal.api.BadSyntaxAt - is any of the parameter names contain another parameter name.

    • getParts

      public static String[] getParts​(javax0.jamal.api.Input input) throws javax0.jamal.api.BadSyntaxAt
      Parse the input and split it up into a String array. It can be used in many macros to provide a consistent syntax and structure when the macro processing needs a list of strings.

      The possible syntax variations are: 

       macroName / a / b / c / ... /x
 macroName   a   b   c   ...  x
 macroName `regex` separator a separator b separator .... separator x

      where the separator character is the first non-whitespace character after the macro name, and it is not the back-tick (`) character. If the first non-whitespace character after the name of the macro id is a backtick then the parsing expects to be a regular expression till the next backtick. After the regular expression and after the closing backtick the rest of the input is spit up and the separator is the regular expression.

      Backtick was selected during the design of the syntax to enclose the regular expression because this character is very rare in Java regular expression. In case you need one inside the regular expression then you have to simply double it and the parsing will single it back.

      If the first character after the white spaces is a digit or alpha character then the input will be split along the spaces.

      Parameters:
      input - to be split up
      Returns:
      the list of the strings created from the input
      Throws:
      javax0.jamal.api.BadSyntaxAt - if the separator character is letter or digit

    • getParts

      public static String[] getParts​(javax0.jamal.api.Input input, int limit)
      Same as getParts(Input) but we want at most limit number of parts.
      Parameters:
      input - the input from which we want to get the parts
      limit - the maximum number of parts we need
      Returns:
      the parts of the input in an array