Package ptolemy.cg.kernel.generic.program

Class CodeStream

  • public class CodeStream
extends java.lang.Object
    FIXME: Get rid of C-specific comments, and put C-specific code in a subclass. Read and process code blocks from the adapter .c file. Adapter .c files contain c code blocks for the associated java adapter actor. A proper code block should have the following grammar: 
         _BLOCKSTART CodeBlockName [(Parameter1, Parameter2), ...] _HEADEREND
         CodeBlockBody
     _BLOCKEND
    Parameterized code blocks can contain parameters which the user can specify. Parameter substitution syntax is straight-forward string pattern substitution, so the user is responsible for declaring unique parameter names. For example, a code block is declared to be the following: FIXME: $ref()'s should be replaced with $get() and $put(). 
         /*** initBlock ($arg) ***/
         if ($get(input) != $arg) {
             $put(output, $arg);
         }
     /**/
    If the user invoke the appendCodeBlock() method with a single argument, which is the integer 3, 
         LinkedList args = new LinkedList();
     args.add(Integer.toString(3));
     appendCodeBlock("initBlock", args);
    then after parameter substitution, the code block would become: FIXME: $ref()'s should be replaced with $get() and $put(). 
         if ($get(input) != 3) {
         $put(output, 3);
     }
    Parameter substitution takes place before macro substitution processed by the codegen kernel. CodeStream supports overriding superclass code blocks. It also supports overloading code blocks with different number of parameters.
    Since:
    Ptolemy II 10.0
    Version:
    $Id$
    Author:
    Man-Kit Leung
    Pt.AcceptedRating:
    Yellow (mankit)
    Pt.ProposedRating:
    Yellow (mankit)

    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class Description
      static class  CodeStream.Signature
      Inner class for representing a code block signature.

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void append​(java.lang.String codeBlock)
      Append the contents of the given String to this code stream.
      void appendCodeBlock​(java.lang.String blockName)
      Append the code block specified the given block name.
      void appendCodeBlock​(java.lang.String blockName, boolean mayNotExist)
      Append the code block specified the given block name.
      void appendCodeBlock​(java.lang.String blockName, boolean mayNotExist, int indentLevel)
      Append the code block specified the given block name.
      void appendCodeBlock​(java.lang.String blockName, java.util.List<java.lang.String> arguments)
      Append the specific code block with an array of arguments and substitute each argument with the parameters of the code block in the order listed in the given arguments array list.
      void appendCodeBlock​(java.lang.String blockName, java.util.List<java.lang.String> arguments, boolean mayNotExist)
      Append the specific code block with an array of arguments and substitute each argument with the parameters of the code block in the order listed in the given arguments array list.
      void appendCodeBlock​(java.lang.String blockName, java.util.List<java.lang.String> arguments, boolean mayNotExist, int indentLevel)
      Append the specific code block with an array of arguments and substitute each argument with the parameters of the code block in the order listed in the given arguments array list.
      void appendCodeBlock​(java.lang.String blockName, java.util.List<java.lang.String> arguments, int indentLevel)
      Append the specific code block with an array of arguments and substitute each argument with the parameters of the code block in the order listed in the given arguments array list.
      void appendCodeBlocks​(java.lang.String nameExpression)
      Append multiple code blocks whose names match the given regular expression.
      void clear()
      Clear the contents of this code stream.
      java.lang.String description()
      Return a String that contains all the code block names and bodies from the associated adapter .[target] file.
      java.util.List<java.lang.String> getAllCodeBlockNames()
      Return a list of code block names contained by this CodeStream.
      java.util.Set<CodeStream.Signature> getAllCodeBlockSignatures()
      Return a set of code block signatures contained by this CodeStream.
      java.lang.String getCodeBlock​(java.lang.String name)
      Given a code block name, return the corresponding code block.
      java.lang.String getCodeBlock​(java.lang.String blockName, java.util.List<java.lang.String> arguments)
      Return a codeBlock with a given name and substitute in the given arguments.
      java.lang.String getCodeBlock​(java.lang.String blockName, java.util.List<java.lang.String> arguments, boolean mayNotExist)
      Return a codeBlock with a given name and substitute in the given arguments.
      java.lang.String getCodeBlockTemplate​(java.lang.Object signature)
      Given a code block signature, return the corresponding code block template.
      static java.lang.String indent​(int indentLevel, java.lang.String inputString)
      Indent the string to the specified indent level.
      static java.lang.String indent​(java.lang.String inputString)
      Indent the string to the default indent level.
      void insert​(int offset, java.lang.String code)
      Insert the contents of the given String to this code stream at the given position.
      boolean isEmpty()
      return a boolean indicating if this stream is empty.
      static void main​(java.lang.String[] args)
      Simple stand alone test method.
      void parse​(java.lang.String filePath)
      Parse additional code blocks from the file specified by the given file path.
      void parse​(java.lang.String filePath, boolean mayNotExist)
      Parse additional code blocks from the file specified by the given file path.
      void reset()
      Reset this CodeStream object so that its code table will be re-constructed when needed.
      static void selfTest()
      Perform a self test.
      void setCodeBlocks​(java.lang.String codeBlocks)
      Set the code blocks which will be parsed instead of .c file.
      static void setIndentLevel​(int indentLevel)
      Set the indent level.
      java.lang.String toString()
      Return the string representation of the code stream.

      • Methods inherited from class java.lang.Object

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

    • Field Detail

      • _codeGenerator

        protected ProgramCodeGenerator _codeGenerator
        The code generator associated with this code stream.

    • Constructor Detail

      • CodeStream

        public CodeStream​(ProgramCodeGeneratorAdapter adapter)
        Construct a new code stream associated with the given java actor adapter. Each actor should have its own codestream during code generation.
        Parameters:
        adapter - The actor adapter associated with this code stream, which is currently ignored.

      • CodeStream

        public CodeStream​(java.util.List<java.lang.String> templateArguments,
                  ProgramCodeGeneratorAdapter adapter)
        Construct a new code stream associated with the given java actor adapter. Each actor should have its own codestream during code generation.
        Parameters:
        templateArguments - Template arguments to be substituted in the code. Template arguments begin with "<" and end with ">".
        adapter - The actor adapter associated with this code stream, which is currently ignored.

      • CodeStream

        public CodeStream​(java.lang.String path,
                  ProgramCodeGenerator generator)
        Construct a new code stream, given a specified file path of the adapter .[target] file as a URL suitable for FileUtilities.openForReading(String, URI, ClassLoader), for example "file:./test/testCodeBlock.c".
        Parameters:
        path - The given file path.
        generator - The generator associated with this CodeStream.

    • Method Detail

      • append

        public void append​(java.lang.String codeBlock)
        Append the contents of the given String to this code stream.
        Parameters:
        codeBlock - The given string.

      • appendCodeBlock

        public void appendCodeBlock​(java.lang.String blockName)
                     throws IllegalActionException
        Append the code block specified the given block name. This method invokes appendCodeBlock(String, LinkedList) with no arguments by passing an empty array list of arguments. The requested code block is required to exist.
        Parameters:
        blockName - The given code block name.
        Throws:
        IllegalActionException - If appendCodeBlock(String, List, boolean) throws the exception.
        See Also:
        appendCodeBlock(String, List, boolean)

      • appendCodeBlock

        public void appendCodeBlock​(java.lang.String blockName,
                            boolean mayNotExist)
                     throws IllegalActionException
        Append the code block specified the given block name. This method invokes appendCodeBlock(String, LinkedList) with no arguments by passing an empty array list of arguments. The requested code block is required to exist.
        Parameters:
        blockName - The given code block name.
        mayNotExist - Indicate if it is okay not to find the code block. if the code block has parameters.
        Throws:
        IllegalActionException - If appendCodeBlock(String, List, boolean) throws the exception.
        See Also:
        appendCodeBlock(String, List, boolean)

      • appendCodeBlock

        public void appendCodeBlock​(java.lang.String blockName,
                            boolean mayNotExist,
                            int indentLevel)
                     throws IllegalActionException
        Append the code block specified the given block name. This method invokes appendCodeBlock(String, LinkedList) with no arguments by passing an empty array list of arguments. The requested code block is required to exist.
        Parameters:
        blockName - The given code block name.
        mayNotExist - Indicate if it is okay not to find the code block. if the code block has parameters.
        indentLevel - The level of indention.
        Throws:
        IllegalActionException - If appendCodeBlock(String, List, boolean) throws the exception.
        See Also:
        appendCodeBlock(String, List, boolean)

      • appendCodeBlock

        public void appendCodeBlock​(java.lang.String blockName,
                            java.util.List<java.lang.String> arguments)
                     throws IllegalActionException
        Append the specific code block with an array of arguments and substitute each argument with the parameters of the code block in the order listed in the given arguments array list. The requested code block is required to exist.
        Parameters:
        blockName - The name of the code block.
        arguments - The user-specified arguments for the code block, if the code block has parameters.
        Throws:
        IllegalActionException - If appendCodeBlock(String, List, boolean) throws the exception.
        See Also:
        appendCodeBlock(String, List, boolean)

      • appendCodeBlock

        public void appendCodeBlock​(java.lang.String blockName,
                            java.util.List<java.lang.String> arguments,
                            int indentLevel)
                     throws IllegalActionException
        Append the specific code block with an array of arguments and substitute each argument with the parameters of the code block in the order listed in the given arguments array list. The requested code block is required to exist.
        Parameters:
        blockName - The name of the code block.
        arguments - The user-specified arguments for the code block, if the code block has parameters.
        indentLevel - The level of indention.
        Throws:
        IllegalActionException - If appendCodeBlock(String, List, boolean) throws the exception.
        See Also:
        appendCodeBlock(String, List, boolean)

      • appendCodeBlock

        public void appendCodeBlock​(java.lang.String blockName,
                            java.util.List<java.lang.String> arguments,
                            boolean mayNotExist)
                     throws IllegalActionException
        Append the specific code block with an array of arguments and substitute each argument with the parameters of the code block in the order listed in the given arguments array list. The initial default level of indention is 0. To change the the level of indentation, call setIndentLevel(int).
        Parameters:
        blockName - The name of the code block.
        arguments - The user-specified arguments for the code block,
        mayNotExist - Indicate if it is okay not to find the code block. if the code block has parameters.
        Throws:
        IllegalActionException - If _constructCodeTable() throws the exception, or if the requested code block is required but cannot be found, or if the numbers of arguments and parameters do not match.

      • appendCodeBlock

        public void appendCodeBlock​(java.lang.String blockName,
                            java.util.List<java.lang.String> arguments,
                            boolean mayNotExist,
                            int indentLevel)
                     throws IllegalActionException
        Append the specific code block with an array of arguments and substitute each argument with the parameters of the code block in the order listed in the given arguments array list.
        Parameters:
        blockName - The name of the code block.
        arguments - The user-specified arguments for the code block,
        mayNotExist - Indicate if it is okay not to find the code block. if the code block has parameters.
        indentLevel - The level of indention.
        Throws:
        IllegalActionException - If _constructCodeTable() throws the exception, or if the requested code block is required but cannot be found, or if the numbers of arguments and parameters do not match.

      • getCodeBlock

        public java.lang.String getCodeBlock​(java.lang.String blockName,
                                     java.util.List<java.lang.String> arguments)
                              throws IllegalActionException
        Return a codeBlock with a given name and substitute in the given arguments. The codeBlock must exist or an exception is thrown.
        Parameters:
        blockName - The given name that identifies the code block.
        arguments - The list of arguments to substitute in the code block.
        Returns:
        The content contained by the code block with the given name.
        Throws:
        IllegalActionException - Thrown if getCodeBlock(String, List, boolean) throws it.

      • getCodeBlock

        public java.lang.String getCodeBlock​(java.lang.String blockName,
                                     java.util.List<java.lang.String> arguments,
                                     boolean mayNotExist)
                              throws IllegalActionException
        Return a codeBlock with a given name and substitute in the given arguments.
        Parameters:
        blockName - The given name that identifies the code block.
        arguments - The list of arguments to substitute in the code block.
        mayNotExist - False to require the codeblock to exist.
        Returns:
        The content contained by the code block with the given name.
        Throws:
        IllegalActionException - Thrown if a problem occurs in constructing the code block table, or the given code block name is required to exist but does not.

      • appendCodeBlocks

        public void appendCodeBlocks​(java.lang.String nameExpression)
                      throws IllegalActionException
        Append multiple code blocks whose names match the given regular expression.
        Parameters:
        nameExpression - The given regular expression for the block names.
        Throws:
        IllegalActionException - If _constructCodeTable() throws the exception, or if the requested code block is required but cannot be found, or if the numbers of arguments and parameters do not match.

      • clear

        public void clear()
        Clear the contents of this code stream.

      • description

        public java.lang.String description()
                             throws IllegalActionException
        Return a String that contains all the code block names and bodies from the associated adapter .[target] file.
        Returns:
        The content from parsing the adapter .[target] file.
        Throws:
        IllegalActionException - If an error occurs during parsing.

      • getAllCodeBlockNames

        public java.util.List<java.lang.String> getAllCodeBlockNames()
        Return a list of code block names contained by this CodeStream.
        Returns:
        The list of code block names contained by this CodeStream.

      • getAllCodeBlockSignatures

        public java.util.Set<CodeStream.Signature> getAllCodeBlockSignatures()
                                                              throws IllegalActionException
        Return a set of code block signatures contained by this CodeStream.
        Returns:
        The set of code block signatures contained by this CodeStream.
        Throws:
        IllegalActionException - If there is a problem when parsing the code adapter .[target] file.

      • getCodeBlock

        public java.lang.String getCodeBlock​(java.lang.String name)
                              throws IllegalActionException
        Given a code block name, return the corresponding code block.
        Parameters:
        name - The name of the code block.
        Returns:
        The code block with the name.
        Throws:
        IllegalActionException - If a code block by that name cannot be found.

      • getCodeBlockTemplate

        public java.lang.String getCodeBlockTemplate​(java.lang.Object signature)
                                      throws IllegalActionException
        Given a code block signature, return the corresponding code block template.
        Parameters:
        signature - The signature of the code block.
        Returns:
        The code block template that matches the signature, or the empty string if a code block with that signature cannot be found.
        Throws:
        IllegalActionException - If thrown while getting a code block template with the name of the signature.

      • indent

        public static java.lang.String indent​(java.lang.String inputString)
        Indent the string to the default indent level.
        Parameters:
        inputString - The string to be indented.
        Returns:
        The indented string.

      • indent

        public static java.lang.String indent​(int indentLevel,
                                      java.lang.String inputString)
        Indent the string to the specified indent level.
        Parameters:
        indentLevel - The level of indention.
        inputString - The string to be indented
        Returns:
        The indented string.

      • insert

        public void insert​(int offset,
                   java.lang.String code)
        Insert the contents of the given String to this code stream at the given position.
        Parameters:
        offset - The given position.
        code - The given string.

      • isEmpty

        public boolean isEmpty()
        return a boolean indicating if this stream is empty.
        Returns:
        true if this stream is empty.

      • main

        public static void main​(java.lang.String[] args)
                 throws java.io.IOException,
                        IllegalActionException
        Simple stand alone test method. Parse a adapter .[target] file, and print all the code blocks.
        Parameters:
        args - Command-line arguments, the first of which names a .[target] file as a URL , for example file:./test/testCodeBlock.c.
        Throws:
        java.io.IOException - If an error occurs when reading user inputs.
        IllegalActionException - If an error occurs during parsing the adapter .[target] file.

      • parse

        public void parse​(java.lang.String filePath)
           throws IllegalActionException
        Parse additional code blocks from the file specified by the given file path. This assumes the given filePath points to an existing file. This is equivalent to calling parse(filePath, false). See parse(String, boolean).
        Parameters:
        filePath - The given file path.
        Throws:
        IllegalActionException - Thrown if an error occurs when parsing the code blocks in the file.

      • parse

        public void parse​(java.lang.String filePath,
                  boolean mayNotExist)
           throws IllegalActionException
        Parse additional code blocks from the file specified by the given file path. The new code blocks will be put alongside and have higher precedence than the code blocks already contained by this CodeStream. Also, the specified file path may not be required to point to an existing file; otherwise, an exception is thrown.
        Parameters:
        filePath - The given file path.
        mayNotExist - Whether to allow invalid filePath input. True if the given filePath may not exist (no exception thrown for invalid file path); false, otherwise.
        Throws:
        IllegalActionException - Thrown if an error occurs when parsing the code blocks in the file.

      • reset

        public void reset()
        Reset this CodeStream object so that its code table will be re-constructed when needed.

      • setCodeBlocks

        public void setCodeBlocks​(java.lang.String codeBlocks)
        Set the code blocks which will be parsed instead of .c file.
        Parameters:
        codeBlocks - The code blocks to be parsed.

      • selfTest

        public static void selfTest()
        Perform a self test.

      • setIndentLevel

        public static void setIndentLevel​(int indentLevel)
        Set the indent level.
        Parameters:
        indentLevel - The indent level, where 0 means no indentation, 1 means indent one level (probably 4 spaces).

      • toString

        public java.lang.String toString()
        Return the string representation of the code stream.
        Overrides:
        toString in class java.lang.Object
        Returns:
        The string representation of this code stream.