ptolemy.cg.kernel.generic.program

Class CodeStream

java.lang.Object

ptolemy.cg.kernel.generic.program.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: CodeStream.java 70402 2014-10-23 00:52:20Z cxh $

Author:

Man-Kit Leung

Accepted Rating:

Yellow (mankit)

Proposed Rating:

Yellow (mankit)

Nested Class Summary

Nested Classes

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

Field Summary

Fields

Modifier and Type	Field and Description
protected ProgramCodeGenerator	_codeGenerator The code generator associated with this code stream.

Constructor Summary

Constructors

Constructor and Description
CodeStream(java.util.List<java.lang.String> templateArguments, ProgramCodeGeneratorAdapter adapter) Construct a new code stream associated with the given java actor adapter.
CodeStream(ProgramCodeGeneratorAdapter adapter) Construct a new code stream associated with the given java actor adapter.
CodeStream(java.lang.String path, ProgramCodeGenerator generator) Construct a new code stream, given a specified file path of the adapter .

Method Summary

Modifier and Type	Method and 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 .
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.