Package ptolemy.cg.kernel.generic.program

Class TemplateParser

  • Direct Known Subclasses:
    ProceduralTemplateParser
    public class TemplateParser
extends java.lang.Object
    A class that allows to parse macros of templates in a code generator perspective.
    Since:
    Ptolemy II 10.0
    Version:
    $Id$
    Author:
    Bert Rodiers, William Lucas
    Pt.AcceptedRating:
    Red (wlc)
    Pt.ProposedRating:
    Red (wlc)

    • Constructor Summary

      Constructors 
      Constructor Description
      TemplateParser()
      Construct the TemplateParser associated with the given component and the given adapter.

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      protected static int _findClosedParen​(java.lang.String string, int pos)
      Find the paired close parenthesis given a string and an index which is the position of an open parenthesis.
      protected ProgramCodeGenerator _getCodeGenerator()
      Get the code generator associated with this adapter class.
      protected java.lang.String _replaceMacro​(java.lang.String macro, java.lang.String parameter)
      Return the replacement string of the given macro.
      void addFunctionUsed​(java.lang.String functionName)
      Add a function to the Set of function used thus far.
      void addNewTypesUsed​(java.lang.String typeName)
      Add a type to the set of codegen types.
      static java.lang.String escapeName​(java.lang.String name)
      Escape a port or actor name for use in the macro language.
      static java.lang.String escapePortName​(java.lang.String name)
      Escape a port name for use in the macro language.
      java.lang.String generateBlockCode​(java.lang.String blockName, java.util.List<java.lang.String> args)
      Given a block name, generate code for that block.
      java.lang.String generateTypeConvertMethod​(java.lang.String expression, java.lang.String castType, java.lang.String refType)
      Generate expression that evaluates to a result of equivalent value with the cast type.
      java.lang.String generateTypeConvertStatement​(ProgramCodeGeneratorAdapter.Channel source, ProgramCodeGeneratorAdapter.Channel sink, int offset, java.lang.String alternativeSourceRef)
      Generate the type conversion statement for the particular offset of the two given channels.
      CodeStream getCodeStream()
      Return the code stream.
      java.lang.String getFunctionInvocation​(java.lang.String functionString, boolean isStatic)
      Return the translated token instance function invocation string.
      java.util.Set<java.lang.String> getHeaderFiles()
      Get the files needed by the code generated from this adapter class.
      java.lang.String getNewInvocation​(java.lang.String constructorString)
      Return the translated new constructor invocation string.
      java.lang.String getParameterValue​(java.lang.String name, NamedObj container)
      Return the value or an expression in the target language for the specified parameter of the associated actor.
      ParseTreeCodeGenerator getParseTreeCodeGenerator()
      Return the parse tree to use with expressions.
      TypedIOPort getPort​(java.lang.String refName)
      Get the port that has the given name.
      java.lang.String getSize​(java.lang.String name)
      Get the size of a parameter.
      static int indexOf​(java.lang.String ch, java.lang.String string, int fromIndex)
      Return the index of a specific character in the string starting from the given index.
      void init​(java.lang.Object component, ProgramCodeGeneratorAdapter adapter)
      Init the TemplateParser with the associated given component and the given adapter.
      static java.util.List<java.lang.String> parseList​(java.lang.String parameters)
      Parse the list of comma separated parameters.
      java.lang.String processCode​(java.lang.String code)
      Process the specified code, replacing macros with their values.
      void setCodeGenerator​(ProgramCodeGenerator codeGenerator)
      Set the associated code generator.
      static java.lang.String unescapeName​(java.lang.String name)
      Unescape a port or actor name so that the return value may be used to find the port in the model.
      static java.lang.String unescapePortName​(java.lang.String name)
      Unescape a port name so that the return value may be used to find the port in the model.

      • Methods inherited from class java.lang.Object

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

    • Constructor Detail

      • TemplateParser

        public TemplateParser()
        Construct the TemplateParser associated with the given component and the given adapter.

    • Method Detail

      • addFunctionUsed

        public void addFunctionUsed​(java.lang.String functionName)
        Add a function to the Set of function used thus far.
        Parameters:
        functionName - A string naming the function.

      • addNewTypesUsed

        public void addNewTypesUsed​(java.lang.String typeName)
        Add a type to the set of codegen types.
        Parameters:
        typeName - A string naming the type.

      • escapeName

        public static java.lang.String escapeName​(java.lang.String name)
        Escape a port or actor name for use in the macro language. The issue is that port or actor names can have certain characters in them that cause problems with macro expansion. Removing these characters is not sufficient as the code generator sometimes needs to refer to the corresponding port or actor. The solution is to replace the characters with a string that we can then use to reverse the escape process in unescapeName(String).
        Parameters:
        name - The port or actorname, which may contain "$", "-" and/or "*".
        Returns:
        A sanitized string suitable for use with the macro language.
        See Also:
        CodeGeneratorAdapter.generateName(NamedObj), unescapePortName(String)

      • escapePortName

        public static java.lang.String escapePortName​(java.lang.String name)
        Escape a port name for use in the macro language. The issue is that port names can have certain characters in them that cause problems with macro expansion. Removing these characters is not sufficient as the code generator sometimes needs to refer to the corresponding port. The solution is to replace the characters with a string that we can then use to reverse the escape process in unescapePortName(String).
        Parameters:
        name - The port name, which may contain "$", "-" and/or "*".
        Returns:
        A sanitized string suitable for use with the macro language.
        See Also:
        CodeGeneratorAdapter.generateName(NamedObj), unescapePortName(String)

      • generateTypeConvertMethod

        public java.lang.String generateTypeConvertMethod​(java.lang.String expression,
                                                  java.lang.String castType,
                                                  java.lang.String refType)
                                           throws IllegalActionException
        Generate expression that evaluates to a result of equivalent value with the cast type.
        Parameters:
        expression - The given variable expression.
        castType - The given cast type.
        refType - The given type of the variable.
        Returns:
        The variable expression that evaluates to a result of equivalent value with the cast type.
        Throws:
        IllegalActionException - If thrown while processing code.

      • generateTypeConvertStatement

        public java.lang.String generateTypeConvertStatement​(ProgramCodeGeneratorAdapter.Channel source,
                                                     ProgramCodeGeneratorAdapter.Channel sink,
                                                     int offset,
                                                     java.lang.String alternativeSourceRef)
                                              throws IllegalActionException
        Generate the type conversion statement for the particular offset of the two given channels. This assumes that the offset is the same for both channel. Advancing the offset of one has to advance the offset of the other.

        If alternativeSourceRef is not null, then we use this instead of the source itself. Thus we generate the type conversion statement with alternativeSourceRef on the right side of the equal sign, and a reference to the sink on the left side.

        Parameters:
        source - The given source channel.
        sink - The given sink channel.
        offset - The given offset._generateTypeConvertStatement
        alternativeSourceRef - The alternative source reference for the port. If alternativeSourceRef is null, then the adapter for the port of the source channel is used.
        Returns:
        The type convert statement for assigning the converted source variable to the sink variable with the given offset.
        Throws:
        IllegalActionException - If there is a problem getting the adapters for the ports or if the conversion cannot be handled.

      • getCodeStream

        public final CodeStream getCodeStream()
        Return the code stream.
        Returns:
        The code stream.

      • getHeaderFiles

        public java.util.Set<java.lang.String> getHeaderFiles()
                                               throws IllegalActionException
        Get the files needed by the code generated from this adapter class. This base class returns an empty set.
        Returns:
        A set of strings that are header files needed by the code generated from this adapter class.
        Throws:
        IllegalActionException - Not Thrown in this base class.

      • getParameterValue

        public final java.lang.String getParameterValue​(java.lang.String name,
                                                NamedObj container)
                                         throws IllegalActionException
        Return the value or an expression in the target language for the specified parameter of the associated actor. If the parameter is specified by an expression, then the expression will be parsed. If any parameter referenced in that expression is specified by another expression, the parsing continues recursively until either a parameter is directly specified by a constant or a parameter can be directly modified during execution in which case a reference to the parameter is generated.
        Parameters:
        name - The name of the parameter.
        container - The container to search upwards from.
        Returns:
        The value or expression as a string.
        Throws:
        IllegalActionException - If the parameter does not exist or does not have a value.

      • getParseTreeCodeGenerator

        public ParseTreeCodeGenerator getParseTreeCodeGenerator()
        Return the parse tree to use with expressions.
        Returns:
        the parse tree to use with expressions.

      • indexOf

        public static int indexOf​(java.lang.String ch,
                          java.lang.String string,
                          int fromIndex)
        Return the index of a specific character in the string starting from the given index. It find the first occurrence of the character that is not embedded inside parentheses "()".
        Parameters:
        ch - The character to search for.
        string - The given string to search from.
        fromIndex - The index to start the search.
        Returns:
        The first occurrence of the character in the string that is not embedded in parentheses.

      • parseList

        public static java.util.List<java.lang.String> parseList​(java.lang.String parameters)
        Parse the list of comma separated parameters.
        Parameters:
        parameters - A comma separate list of parameters.
        Returns:
        A list of parameters.

      • init

        public void init​(java.lang.Object component,
                 ProgramCodeGeneratorAdapter adapter)
        Init the TemplateParser with the associated given component and the given adapter.

        Calling this method sets the code generator to that of the adapter. Note that calling setCodeGenerator(ProgramCodeGenerator) also sets the code generator.

        Parameters:
        component - The associated component.
        adapter - The associated adapter.

      • processCode

        public final java.lang.String processCode​(java.lang.String code)
                                   throws IllegalActionException
        Process the specified code, replacing macros with their values. Macros have the possible forms:

        $xxx(), where are processed by _replaceMacro(String, String)

        ${foo}, which means get the value of the parameter "foo"

        $nation, which is ignored.

        Parameters:
        code - The code to process.
        Returns:
        The processed code.
        Throws:
        IllegalActionException - If illegal macro names are found.

      • generateBlockCode

        public java.lang.String generateBlockCode​(java.lang.String blockName,
                                          java.util.List<java.lang.String> args)
                                   throws IllegalActionException
        Given a block name, generate code for that block. This method is called by actors adapters that have simple blocks that do not take parameters or have widths.
        Parameters:
        blockName - The name of the block.
        args - The arguments for the block.
        Returns:
        The code for the given block.
        Throws:
        IllegalActionException - If illegal macro names are found, or if there is a problem parsing the code block from the adapter .c file.

      • getFunctionInvocation

        public java.lang.String getFunctionInvocation​(java.lang.String functionString,
                                              boolean isStatic)
                                       throws IllegalActionException
        Return the translated token instance function invocation string.
        Parameters:
        functionString - The string within the $tokenFunc() macro.
        isStatic - True if the method is static.
        Returns:
        The translated type function invocation string.
        Throws:
        IllegalActionException - The given function string is not well-formed.

      • getNewInvocation

        public java.lang.String getNewInvocation​(java.lang.String constructorString)
                                  throws IllegalActionException
        Return the translated new constructor invocation string. Keep the types referenced in the info table of this adapter. The kernel will retrieve this information to determine the total number of referenced types in the model.
        Parameters:
        constructorString - The string within the $new() macro.
        Returns:
        The translated new constructor invocation string.
        Throws:
        IllegalActionException - The given constructor string is not well-formed.

      • getPort

        public final TypedIOPort getPort​(java.lang.String refName)
        Get the port that has the given name.
        Parameters:
        refName - The given of the port, usually a simple string like "input". The refName is also processed using unescapePortName(String) so that we handle port names that have "$", "*" and "-".
        Returns:
        The port that has the given name.

      • getSize

        public java.lang.String getSize​(java.lang.String name)
                         throws IllegalActionException
        Get the size of a parameter. The size of a parameter is the length of its array if the parameter's type is array, and 1 otherwise.
        Parameters:
        name - The name of the parameter.
        Returns:
        The expression that represents the size of a parameter or port.
        Throws:
        IllegalActionException - If no port or parameter of the given name is found.

      • unescapeName

        public static java.lang.String unescapeName​(java.lang.String name)
        Unescape a port or actor name so that the return value may be used to find the port in the model.
        Parameters:
        name - The port or actor name, which may contain "$", "-" and/or "*".
        Returns:
        A sanitized string suitable for use with the macro language.
        See Also:
        escapePortName(String)

      • unescapePortName

        public static java.lang.String unescapePortName​(java.lang.String name)
        Unescape a port name so that the return value may be used to find the port in the model.
        Parameters:
        name - The port name, which may contain "$", "-" and/or "*".
        Returns:
        A sanitized string suitable for use with the macro language.
        See Also:
        escapePortName(String)

      • _replaceMacro

        protected java.lang.String _replaceMacro​(java.lang.String macro,
                                         java.lang.String parameter)
                                  throws IllegalActionException
        Return the replacement string of the given macro. Subclass of GenericCodeGenerator may overriding this method to extend or support a different set of macros.
        Parameters:
        macro - The given macro.
        parameter - The given parameter to the macro.
        Returns:
        The replacement string of the given macro.
        Throws:
        IllegalActionException - Thrown if the given macro or parameter is not valid.

      • _findClosedParen

        protected static int _findClosedParen​(java.lang.String string,
                                      int pos)
                               throws IllegalActionException
        Find the paired close parenthesis given a string and an index which is the position of an open parenthesis. Return -1 if no paired close parenthesis is found.
        Parameters:
        string - The given string.
        pos - The given index.
        Returns:
        The index which indicates the position of the paired close parenthesis of the string.
        Throws:
        IllegalActionException - If the character at the given position of the string is not an open parenthesis or if the index is less than 0 or past the end of the string.