Module jamal.tools

Class InputHandler


  • public class InputHandler
    extends java.lang.Object
    Utility class with some simple static methods that fetch characters from an input buffer.
    • Constructor Summary

      Constructors 
      Constructor Description
      InputHandler()  
    • Method Summary

      All Methods Static Methods Concrete Methods 
      Modifier and Type Method Description
      static boolean contains​(int i)  
      static java.lang.String convertGlobal​(java.lang.String id)
      Convert a global macro name.
      static void copy​(Input input, Input output, java.lang.String s)
      Copy the string from the start of the input to the end of the output.
      static java.lang.String fetchId​(Input input)
      Fetch an id from the start of the input.
      static boolean firstCharIs​(java.lang.CharSequence s, char c)  
      static java.lang.String[] getParameters​(Input input, java.lang.String id)
      Get the parameter list that is at the start of the input.
      static java.lang.String[] getParts​(Input input)
      Parse the input and split it up into a String array.
      static boolean isGlobalMacro​(java.lang.String id)  
      static void skip​(Input input, int numberOfCharacters)
      Delete the start of the input
      static void skip​(Input input, java.lang.String s)
      Delete the start of the input
      static void skipWhiteSpaces​(Input input)
      Delete the white space characters from the start of the input
      static void skipWhiteSpaces2EOL​(Input input)
      Delete the white space characters from the start of the input but only until after the first EOL
      static boolean validId1stChar​(char c)  
      static boolean validIdChar​(char c)  
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Constructor Detail

      • InputHandler

        public InputHandler()
    • Method Detail

      • firstCharIs

        public static boolean firstCharIs​(java.lang.CharSequence s,
                                          char c)
        Parameters:
        s - a character sequence of which the first character is checked
        c - the character we are looking for
        Returns:
        returns true if the first character of 's' is 'c'
      • skip

        public static void skip​(Input input,
                                int numberOfCharacters)
        Delete the start of the input
        Parameters:
        input - from which the first characters are deleted
        numberOfCharacters - the number of characters to be deleted from the start of input
      • skip

        public static void skip​(Input input,
                                java.lang.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 java.lang.String fetchId​(Input input)
        Fetch an id from the start of the input.

        An identifier is a string that starts with a character accepted by validId1stChar(char) and contain only characters that are accepted 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​(java.lang.String id)
      • convertGlobal

        public static java.lang.String convertGlobal​(java.lang.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.
      • validId1stChar

        public static boolean validId1stChar​(char c)
        Parameters:
        c - the character to check
        Returns:
        true if the character can be used as the first character of a macro identifier. Currently these are $, _ (underscore), : (colon) and any alphabetic character.
      • validIdChar

        public static boolean validIdChar​(char c)
        Parameters:
        c - the character to check
        Returns:
        true if the character can be used in a macro identifier. These are the same characters that can be used as first characters (see validId1stChar(char)) and also digits.
      • skipWhiteSpaces

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

        public static void skipWhiteSpaces2EOL​(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.
      • copy

        public static void copy​(Input input,
                                Input output,
                                java.lang.String s)
        Copy the string from the start of the input to the end of the output.
        Parameters:
        input - from which the string will be removed
        output - to which the string will be appended
        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.
      • getParameters

        public static java.lang.String[] getParameters​(Input input,
                                                       java.lang.String id)
                                                throws 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:
        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.
      • getParts

        public static java.lang.String[] getParts​(Input input)
                                           throws 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
         

        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.

         macroName `regex` separator a separator b separator .... separator x
         
        Parameters:
        input - to be split up
        Returns:
        the list of the strings created from the input
        Throws:
        BadSyntaxAt - if the separator character is letter or digit