ptolemy.cg.kernel.generic.program

Class TemplateParser

java.lang.Object

ptolemy.cg.kernel.generic.program.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)

Field Summary

Fields

Modifier and Type	Field and Description
protected ProgramCodeGenerator	_codeGenerator The ProgramCodeGenerator, set by calling init(Object, ProgramCodeGeneratorAdapter) or setCodeGenerator(ProgramCodeGenerator).
protected java.lang.Object	_component The component, set by calling init(Object, ProgramCodeGeneratorAdapter).
protected ParseTreeCodeGenerator	_parseTreeCodeGenerator The parse tree to use with expressions.

Constructor Summary

Constructors

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

Method Summary

Modifier and Type	Method and 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.
(package private) CodeStream	_getActualCodeStream() Return the actual CodeStream for this Adapter.
(package private) static CodeStream	_getActualCodeStream(java.lang.Object component, GenericCodeGenerator codeGenerator) Return the actual CodeStream associated with the given Actor and GenericCodeGenerator.
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

Field Detail

_codeGenerator

protected ProgramCodeGenerator _codeGenerator

The ProgramCodeGenerator, set by calling init(Object, ProgramCodeGeneratorAdapter) or setCodeGenerator(ProgramCodeGenerator).

_component

protected java.lang.Object _component

The component, set by calling init(Object, ProgramCodeGeneratorAdapter).

_parseTreeCodeGenerator

protected ParseTreeCodeGenerator _parseTreeCodeGenerator

The parse tree to use with expressions.

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.

setCodeGenerator

public final void setCodeGenerator(ProgramCodeGenerator codeGenerator)

Set the associated code generator. Note that calling init(Object, ProgramCodeGeneratorAdapter) also sets the code generator.

Parameters:

codeGenerator - The code generator associated with this class.

See Also:

_getCodeGenerator()

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)

_getCodeGenerator

protected ProgramCodeGenerator _getCodeGenerator()

Get the code generator associated with this adapter class.

Returns:

The code generator associated with this adapter class.

See Also:

setCodeGenerator(ProgramCodeGenerator)

_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.

_getActualCodeStream

static CodeStream _getActualCodeStream(java.lang.Object component,
                                       GenericCodeGenerator codeGenerator)
                                throws IllegalActionException

Return the actual CodeStream associated with the given Actor and GenericCodeGenerator. Generally, this will come from the Actor's template file, but EmbeddedCActors get their code from the embeddedCCode parameter.

Parameters:

component - The actor whose code to return.

codeGenerator - The actor's GenericCodeGenerator.

Returns:

The actor's actual CodeStream.

Throws:

IllegalActionException - If thrown when getting the actor's adapter.

_getActualCodeStream

CodeStream _getActualCodeStream()
                         throws IllegalActionException

Return the actual CodeStream for this Adapter.

Returns:

The actual CodeStream.

Throws:

IllegalActionException - If thrown by a called method.