ptolemy.cg.kernel.generic

Class GenericCodeGenerator

java.lang.Object

ptolemy.kernel.util.NamedObj

ptolemy.kernel.util.Attribute

ptolemy.cg.kernel.generic.GenericCodeGenerator

All Implemented Interfaces:

java.lang.Cloneable, Changeable, Debuggable, DebugListener, Decorator, Derivable, ModelErrorHandler, MoMLExportable, Moveable, Nameable

Direct Known Subclasses:

HTMLCodeGenerator, ProgramCodeGenerator, SyntacticCodeGenerator

public abstract class GenericCodeGenerator
extends Attribute
implements Decorator

Base class for code generator.

Derived classes usually override generateCode(StringBuffer).

Since:

Ptolemy II 10.0

Version:

$Id: GenericCodeGenerator.java 70402 2014-10-23 00:52:20Z cxh $

Author:

Edward A. Lee, Gang Zhou, Ye Zhou, Contributors: Christopher Brooks, Bert Rodiers

Accepted Rating:

Yellow (eal)

Proposed Rating:

Yellow (eal)

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
(package private) class	GenericCodeGenerator.GeneratorPackageListParser Parse the generatorPackageList parameter.

Nested classes/interfaces inherited from class ptolemy.kernel.util.NamedObj

NamedObj.ContainedObjectsIterator

Field Summary

Fields

Modifier and Type	Field and Description
protected java.lang.String	_codeFileName The name of the file that was written.
protected static java.lang.String	_eol End of line character.
protected ExecuteCommands	_executeCommands Execute commands to run the generated code.
protected boolean	_generateInSubdirectory The value of the generateInSubdirectory parameter.
protected CompositeEntity	_model The model we for which we are generating code.
protected java.lang.String	_sanitizedModelName The sanitized model name.
FileParameter	codeDirectory The directory in which to put the generated code.
Parameter	generateInSubdirectory If true, then generate code in a subdirectory of codeDirectory.
StringParameter	generatorPackage The name of the package in which to look for adapter class code generators.
StringParameter	generatorPackageList The name of the package(s) in which to look for adapter classes.
static java.lang.String	INDENT1 Indent string for indent level 1.
static java.lang.String	INDENT2 Indent string for indent level 2.
static java.lang.String	INDENT3 Indent string for indent level 3.
Parameter	overwriteFiles If true, overwrite preexisting files.

Fields inherited from class ptolemy.kernel.util.NamedObj

_changeListeners, _changeLock, _changeRequests, _debugging, _debugListeners, _deferChangeRequests, _elementName, _isPersistent, _verbose, _workspace, ATTRIBUTES, CLASSNAME, COMPLETE, CONTENTS, DEEP, FULLNAME, LINKS

Constructor Summary

Constructors

Constructor and Description
GenericCodeGenerator(NamedObj container, java.lang.String name) Create a new instance of the code generator.
GenericCodeGenerator(NamedObj container, java.lang.String name, java.lang.String outputFileExtension) Create a new instance of the code generator.

Method Summary

Modifier and Type	Method and Description
protected void	_copyCFilesTosrc(java.lang.String path, java.lang.String directoryToCopy, java.lang.String[] codeFileNames) Copy files into the directory of the project.
protected void	_copyCFileTosrc(java.lang.String path, java.lang.String directoryToCopy, java.lang.String codeFileName) Copy a C (or h) file into the directory /src of the project.
protected int	_executeCommands() Execute the compile and run commands in the codeDirectory directory.
protected int	_generateCode(java.lang.StringBuffer code) Generate code and append it to the given string buffer.
protected CodeGeneratorAdapter	_getAdapter(java.lang.Object object) Get the code generator adapter associated with the given object.
protected java.lang.Class<?>	_getAdapterClassFilter() Return the filter class to find adapters.
protected CodeGeneratorAdapter	_getAutoGeneratedAdapter(GenericCodeGenerator codeGenerator, java.lang.Object object) Attempt to automatically generate an adapter.
protected java.lang.String	_getOutputFilename() Return the name of the output file.
protected CodeGeneratorAdapter	_instantiateAdapter(java.lang.Object component, java.lang.Class<?> componentClass, java.lang.String adapterClassName) Instantiate the given code generator adapter.
protected boolean	_isTopLevel() Test if the containing actor is in the top level.
protected long	_printTimeAndMemory(long startTime, java.lang.String message) Print the elapsed time since the specified startTime if the elapsed time is greater than 10 seconds.
protected void	_reset() Reset the code generator.
protected void	_resetAll() Reset the code generator, including setting the model to null.
protected java.lang.String	_writeCode(java.lang.StringBuffer code) Write the code to a directory named by the codeDirectory parameter, with a file name that is a sanitized version of the model name, and an extension that is the last package of the generatorPackage.
protected java.lang.String	_writeCodeFileName(java.lang.StringBuffer code, java.lang.String codeFileName, boolean overwriteFile, boolean dontShowDialog) Write the code to a directory named by the codeDirectory parameter, with a file name that is a sanitized version of the model name, and an extension that is the last package of the generatorPackage.
void	attributeChanged(Attribute attribute) If the attribute is the codeDirectory parameter, then set the base directory of the codeDirectory parameter.
java.lang.Object	clone(Workspace workspace) Clone the object into the specified workspace.
java.lang.String	comment(java.lang.String comment) Return a formatted comment containing the specified string.
DecoratorAttributes	createDecoratorAttributes(NamedObj target) Return the decorated attributes for the target NamedObj.
java.util.List<NamedObj>	decoratedObjects() Return a list of the entities deeply contained by the container of this resource scheduler.
int	generateCode() Generate code and write it to the file specified by the codeDirectory parameter.
static int	generateCode(java.lang.String[] args) Generate code for a model.
int	generateCode(java.lang.StringBuffer code) Generate code.
java.lang.String	generateCopyright() Return the copyright for this code.
java.lang.Object	getAdapter(java.lang.Object component) Get the code generator adapter associated with the given component.
java.lang.String	getCodeFileName() Return the name of the code file that was written, if any.
NamedObj	getComponent() Return the associated component, which is always the container.
ExecuteCommands	getExecuteCommands() Get the command executor, which can be either non-graphical or graphical.
java.lang.String	getMethodExceptionString() Return the exception signature (for Java).
java.lang.String	getMethodVisibilityString() Return the visibility signature for run() and execute() (for Java).
boolean	isGlobalDecorator() Return false to indicate that this decorator should not decorate objects across opaque hierarchy boundaries.
static void	main(java.lang.String[] args) Generate code for a model.
void	setCodeGenerator(GenericCodeGenerator codeGenerator) This method is used to set the code generator for a adapter class.
void	setContainer(NamedObj container) Override the base class to first set the container, then establish a connection with any decorated objects it finds in scope in the new container.
void	setExecuteCommands(ExecuteCommands executeCommands) Set the command executor, which can be either non-graphical or graphical.
java.lang.String[][]	updateCommandOptions() Return an updated array of command line options.

Methods inherited from class ptolemy.kernel.util.Attribute

_checkContainer, _getContainedObject, _propagateExistence, getContainer, moveDown, moveToFirst, moveToIndex, moveToLast, moveUp, setName, updateContent

Methods inherited from class ptolemy.kernel.util.NamedObj

_addAttribute, _adjustOverride, _attachText, _cloneFixAttributeFields, _containedDecorators, _copyChangeRequestList, _debug, _debug, _debug, _debug, _debug, _description, _executeChangeRequests, _exportMoMLContents, _getIndentPrefix, _isMoMLSuppressed, _markContentsDerived, _notifyHierarchyListenersAfterChange, _notifyHierarchyListenersBeforeChange, _propagateValue, _removeAttribute, _splitName, _stripNumericSuffix, _validateSettables, addChangeListener, addDebugListener, addHierarchyListener, attributeDeleted, attributeList, attributeList, attributeTypeChanged, clone, containedObjectsIterator, decorators, deepContains, depthInHierarchy, description, description, event, executeChangeRequests, exportMoML, exportMoML, exportMoML, exportMoML, exportMoML, exportMoMLPlain, getAttribute, getAttribute, getAttributes, getChangeListeners, getClassName, getDecoratorAttribute, getDecoratorAttributes, getDerivedLevel, getDerivedList, getDisplayName, getElementName, getFullName, getModelErrorHandler, getName, getName, getPrototypeList, getSource, handleModelError, isDeferringChangeRequests, isOverridden, isPersistent, lazyContainedObjectsIterator, message, notifyOfNameChange, propagateExistence, propagateValue, propagateValues, removeAttribute, removeChangeListener, removeDebugListener, removeHierarchyListener, requestChange, setClassName, setDeferringChangeRequests, setDerivedLevel, setDisplayName, setModelErrorHandler, setPersistent, setSource, sortContainedObjects, toplevel, toString, uniqueName, validateSettables, workspace

Methods inherited from class java.lang.Object

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

Methods inherited from interface ptolemy.kernel.util.Nameable

description, getContainer, getDisplayName, getFullName, getName, getName, setName

Field Detail

codeDirectory

public FileParameter codeDirectory

The directory in which to put the generated code. This is a file parameter that must specify a directory. The default is "$HOME/cg/".

generateInSubdirectory

public Parameter generateInSubdirectory

If true, then generate code in a subdirectory of codeDirectory. The default value is false, indicating that code should be generated in the directory named by codeDirectory. If the value is true, then code is generated in a subdirectory of the directory named by the codeDirectory parameter. This is useful for languages such as Java, which means that the code will be generated in a package named by the sanitized version of the model name. The default value is a Boolean with the value "false".

generatorPackage

public StringParameter generatorPackage

The name of the package in which to look for adapter class code generators. The default value of this parameter is the empty string. Derived classes may set this parameter to values like ptolemy.cg.kernel.generic.program.procedural.c. ptolemy.cg.kernel.generic.html, or ptolemy.cg.kernel.generic.program.procedural.java.

generatorPackageList

public StringParameter generatorPackageList

The name of the package(s) in which to look for adapter classes. The string can either be just one package, such as "generic.program.procedural.java" or a list of semicolon ';' , colon ':', space ' ' or asterix '*' separated list of Java packages, such as generic.program.procedural.java.target1:generic.program.procedural.java.target2. The adapter is first searched in the first package. Adapters are looked up by class name, where the class name consists of "ptolemy.cg.adapter" + the package name from this list + "adapters.". Thus, if generatorPackageList is set to generic.program.procedural.java, then the ptolemy.cg.adapter.generic.program.procedural.java.adapters. package will be searched.

overwriteFiles

public Parameter overwriteFiles

If true, overwrite preexisting files. The default value is a parameter with the value true.

INDENT1

public static final java.lang.String INDENT1

Indent string for indent level 1.

See Also:

StringUtilities.getIndentPrefix(int)

INDENT2

public static final java.lang.String INDENT2

Indent string for indent level 2.

See Also:

StringUtilities.getIndentPrefix(int)

INDENT3

public static final java.lang.String INDENT3

Indent string for indent level 3.

See Also:

StringUtilities.getIndentPrefix(int)

_eol

protected static final java.lang.String _eol

End of line character. Under Unix: "\n", under Windows: "\n\r". We use a end of line character so that the files we generate have the proper end of line character for use by other native tools.

_executeCommands

protected ExecuteCommands _executeCommands

Execute commands to run the generated code.

_generateInSubdirectory

protected boolean _generateInSubdirectory

The value of the generateInSubdirectory parameter.

_model

protected CompositeEntity _model

The model we for which we are generating code.

_sanitizedModelName

protected java.lang.String _sanitizedModelName

The sanitized model name.

_codeFileName

protected java.lang.String _codeFileName

The name of the file that was written. If no file was written, then the value is null.

Constructor Detail

GenericCodeGenerator

public GenericCodeGenerator(NamedObj container,
                            java.lang.String name)
                     throws IllegalActionException,
                            NameDuplicationException

Create a new instance of the code generator. The file extension is set to the last package of the generatePackage parameter.

Parameters:

container - The container.

name - The name of the code generator.

Throws:

IllegalActionException - If the super class throws the exception or error occurs when setting the file path.

NameDuplicationException - If the super class throws the exception or an error occurs when setting the file path.

GenericCodeGenerator

public GenericCodeGenerator(NamedObj container,
                            java.lang.String name,
                            java.lang.String outputFileExtension)
                     throws IllegalActionException,
                            NameDuplicationException

Create a new instance of the code generator.

Parameters:

container - The container.

name - The name of the code generator.

outputFileExtension - The extension of the output file. (for example c in case of C and java in case of Java)

Throws:

IllegalActionException - If the super class throws the exception or error occurs when setting the file path.

NameDuplicationException - If the super class throws the exception or an error occurs when setting the file path.

Method Detail

attributeChanged

public void attributeChanged(Attribute attribute)
                      throws IllegalActionException

If the attribute is the codeDirectory parameter, then set the base directory of the codeDirectory parameter.

Overrides:

attributeChanged in class NamedObj

Parameters:

attribute - The attribute that changed.

Throws:

IllegalActionException - If the change is not acceptable to this container.

clone

public java.lang.Object clone(Workspace workspace)
                       throws java.lang.CloneNotSupportedException

Clone the object into the specified workspace.

Overrides:

clone in class Attribute

Parameters:

workspace - The workspace for the new object.

Returns:

A new NamedObj.

Throws:

java.lang.CloneNotSupportedException - If any of the attributes cannot be cloned.

See Also:

NamedObj.exportMoML(Writer, int, String), NamedObj.setDeferringChangeRequests(boolean)

comment

public java.lang.String comment(java.lang.String comment)

Return a formatted comment containing the specified string. In this base class, the empty string is returned.

Parameters:

comment - The string to put in the comment.

Returns:

A formatted comment.

createDecoratorAttributes

public DecoratorAttributes createDecoratorAttributes(NamedObj target)

Return the decorated attributes for the target NamedObj.

Specified by:

createDecoratorAttributes in interface Decorator

Parameters:

target - The NamedObj that will be decorated.

Returns:

A list of decorated attributes for the target NamedObj, or null if there is no adapter for this object.

decoratedObjects

public java.util.List<NamedObj> decoratedObjects()

Return a list of the entities deeply contained by the container of this resource scheduler.

Specified by:

decoratedObjects in interface Decorator

Returns:

A list of the objects decorated by this decorator.

generateCode

public int generateCode()
                 throws KernelException

Generate code and write it to the file specified by the codeDirectory parameter.

Returns:

The return value of the last subprocess that was executed. or -1 if no commands were executed.

Throws:

KernelException - If the target file cannot be overwritten or write-to-file throw any exception.

generateCode

public int generateCode(java.lang.StringBuffer code)
                 throws KernelException

Generate code. This is the main entry point.

Parameters:

code - The code buffer into which to generate the code.

Returns:

The return value of the last subprocess that was executed. or -1 if no commands were executed.

Throws:

KernelException - If a type conflict occurs or the model is running.

generateCode

public static int generateCode(java.lang.String[] args)
                        throws java.lang.Exception

Generate code for a model.

Parameters:

args - An array of Strings, each element names a MoML file containing a model.

Returns:

The return value of the last subprocess that was run to compile or run the model. Return -1 if called with no arguments. Return -2 if no CodeGenerator was created.

Throws:

java.lang.Exception - If any error occurs.

generateCopyright

public java.lang.String generateCopyright()

Return the copyright for this code. In this base class, the empty string is returned. In derived classes, the standard Ptolemy copyright is returned within a comment.

Returns:

The copyright.

getAdapter

public final java.lang.Object getAdapter(java.lang.Object component)
                                  throws IllegalActionException

Get the code generator adapter associated with the given component.

Parameters:

component - The given component.

Returns:

The code generator adapter.

Throws:

IllegalActionException - If the adapter class cannot be found.

getCodeFileName

public final java.lang.String getCodeFileName()

Return the name of the code file that was written, if any. If no file was written, then return null.

Returns:

The name of the file that was written.

getComponent

public NamedObj getComponent()

Return the associated component, which is always the container.

Returns:

The adapter to generate code.

getExecuteCommands

public final ExecuteCommands getExecuteCommands()

Get the command executor, which can be either non-graphical or graphical. The initial default is non-graphical, which means that stderr and stdout from subcommands is written to the console.

Returns:

executeCommands The subprocess command executor.

See Also:

setExecuteCommands(ExecuteCommands)

getMethodVisibilityString

public java.lang.String getMethodVisibilityString()

Return the visibility signature for run() and execute() (for Java).

Returns:

The visibility signature, empty string for C.

getMethodExceptionString

public java.lang.String getMethodExceptionString()

Return the exception signature (for Java).

Returns:

The exception signature, empty string for C.

isGlobalDecorator

public boolean isGlobalDecorator()

Return false to indicate that this decorator should not decorate objects across opaque hierarchy boundaries.

Specified by:

isGlobalDecorator in interface Decorator

Returns:

True if decorator is global.

main

public static void main(java.lang.String[] args)
                 throws java.lang.Exception

Generate code for a model.

For example:

  java -classpath $PTII ptolemy.cg.kernel.generic.GenericCodeGenerator $PTII/ptolemy/cg/adapter/generic/program/procedural/c/adapters/ptolemy/actor/lib/test/auto/Ramp.xml
  

or

  $PTII/bin/ptinvoke ptolemy.cg.kernel.generic.GenericCodeGenerator $PTII/ptolemy/cg/adapter/generic/program/procedural/c/adapters/ptolemy/actor/lib/test/auto/Ramp.xml
  

The HandSimDroid work in $PTII/ptserver uses dependency injection to determine which implementation actors such as Const and Display to use. This method reads the ptolemy/actor/ActorModule.properties file.

Parameters:

args - An array of Strings, each element names a MoML file containing a model.

Throws:

java.lang.Exception - If any error occurs.

setCodeGenerator

public void setCodeGenerator(GenericCodeGenerator codeGenerator)

This method is used to set the code generator for a adapter class. Since this is not a adapter class for a component, this method does nothing.

Parameters:

codeGenerator - The given code generator.

setContainer

public void setContainer(NamedObj container)
                  throws IllegalActionException,
                         NameDuplicationException

Override the base class to first set the container, then establish a connection with any decorated objects it finds in scope in the new container.

Overrides:

setContainer in class Attribute

Parameters:

container - The given container.

Throws:

IllegalActionException - If the given container is not null and not an instance of CompositeEntity.

NameDuplicationException - If there already exists a container with the same name.

See Also:

Attribute.getContainer()

setExecuteCommands

public void setExecuteCommands(ExecuteCommands executeCommands)

Set the command executor, which can be either non-graphical or graphical. The initial default is non-graphical, which means that stderr and stdout from subcommands is written to the console.

Parameters:

executeCommands - The subprocess command executor.

See Also:

getExecuteCommands()

updateCommandOptions

public java.lang.String[][] updateCommandOptions()

Return an updated array of command line options.

Returns:

An array of updated command line options.

_copyCFileTosrc

protected void _copyCFileTosrc(java.lang.String path,
                               java.lang.String directoryToCopy,
                               java.lang.String codeFileName)
                        throws IllegalActionException

Copy a C (or h) file into the directory /src of the project. This is useful to copy the files pre-written in C.

Parameters:

path - The path to the source to be copied. A relative path has $PTII prepended to it.

directoryToCopy - The destination directory, typically an absolute path determined by the value of the codeDirectory parameter.

codeFileName - the name of the file to copy.

Throws:

IllegalActionException - If thrown while copying a file.

_copyCFilesTosrc

protected void _copyCFilesTosrc(java.lang.String path,
                                java.lang.String directoryToCopy,
                                java.lang.String[] codeFileNames)
                         throws IllegalActionException

Copy files into the directory of the project. This is useful to copy the files pre-written in C.

Parameters:

path - The path to the source to be copied. A relative path has $PTII prepended to it.

directoryToCopy - The destination directory, typically an absolute path determined by the value of the codeDirectory parameter.

codeFileNames - the name of the file to copy.

Throws:

IllegalActionException - If thrown while copying a file.

_executeCommands

protected int _executeCommands()
                        throws IllegalActionException

Execute the compile and run commands in the codeDirectory directory. In this base class, 0 is returned by default.

Returns:

The result of the execution.

Throws:

IllegalActionException - Not thrown in this base class.

_generateCode

protected int _generateCode(java.lang.StringBuffer code)
                     throws KernelException

Generate code and append it to the given string buffer.

Write the code to the directory specified by the codeDirectory parameter. The file name is a sanitized version of the model name with a suffix that is based on last package name of the generatorPackage parameter. Thus if the codeDirectory is $HOME, the name of the model is Foo and the generatorPackage is ptolemy.codegen.c, then the file that is written will be $HOME/Foo.c

This method is the main entry point, derived classes will override this method with code that traverses the model and generates code.

Parameters:

code - The given string buffer.

Returns:

The return value of the last subprocess that was executed. or -1 if no commands were executed.

Throws:

KernelException - If the target file cannot be overwritten or write-to-file throw any exception.

_getAdapter

protected final CodeGeneratorAdapter _getAdapter(java.lang.Object object)
                                          throws IllegalActionException

Get the code generator adapter associated with the given object.

Parameters:

object - The given object.

Returns:

The code generator adapter.

Throws:

IllegalActionException - If the adapter class cannot be found.

_getAdapterClassFilter

protected java.lang.Class<?> _getAdapterClassFilter()

Return the filter class to find adapters. All adapters have to extend this class.

Returns:

The base class for the adapters.

_getAutoGeneratedAdapter

protected CodeGeneratorAdapter _getAutoGeneratedAdapter(GenericCodeGenerator codeGenerator,
                                                        java.lang.Object object)

Attempt to automatically generate an adapter. In this base class, return null, indicating that an adapter cannot be generated. Derived classes could create an adapter

Parameters:

codeGenerator - The code generator with which to associate the adapter.

object - The given object.

Returns:

The code generator adapter or null if no adapter can be automatically generated.

_getOutputFilename

protected java.lang.String _getOutputFilename()
                                       throws IllegalActionException

Return the name of the output file.

Returns:

The output file name.

Throws:

IllegalActionException - If there is problem resolving the string value of the generatorPackage parameter.

_instantiateAdapter

protected CodeGeneratorAdapter _instantiateAdapter(java.lang.Object component,
                                                   java.lang.Class<?> componentClass,
                                                   java.lang.String adapterClassName)
                                            throws IllegalActionException

Instantiate the given code generator adapter.

Parameters:

component - The given component.

componentClass - The class of the component to be instantiated. The constructor for class named by the adapterClassName argument must take an argument of the class componentClass.

adapterClassName - The dot separated name of the adapter.

Returns:

The code generator adapter.

Throws:

IllegalActionException - If the adapter class cannot be found.

_isTopLevel

protected boolean _isTopLevel()
                       throws IllegalActionException

Test if the containing actor is in the top level.

Returns:

true if the containing actor is in the top level.

Throws:

IllegalActionException - If thrown while getting the container.

_printTimeAndMemory

protected long _printTimeAndMemory(long startTime,
                                   java.lang.String message)

Print the elapsed time since the specified startTime if the elapsed time is greater than 10 seconds. Otherwise, do nothing.

Parameters:

startTime - The start time. Usually set to the value of (new Date()).getTime().

message - A prefix to the printed message.

Returns:

The current time.

_reset

protected void _reset()
               throws IllegalActionException

Reset the code generator.

Throws:

IllegalActionException - If the container of the model cannot be set to null.

_resetAll

protected void _resetAll()
                  throws IllegalActionException

Reset the code generator, including setting the model to null.

Throws:

IllegalActionException - If the container of the model cannot be set to null.

_writeCode

protected java.lang.String _writeCode(java.lang.StringBuffer code)
                               throws IllegalActionException

Write the code to a directory named by the codeDirectory parameter, with a file name that is a sanitized version of the model name, and an extension that is the last package of the generatorPackage.

Parameters:

code - The StringBuffer containing the code.

Returns:

The name of the file that was written.

Throws:

IllegalActionException - If there is a problem reading a parameter, if there is a problem creating the codeDirectory directory or if there is a problem writing the code to a file.

_writeCodeFileName

protected java.lang.String _writeCodeFileName(java.lang.StringBuffer code,
                                              java.lang.String codeFileName,
                                              boolean overwriteFile,
                                              boolean dontShowDialog)
                                       throws IllegalActionException

Write the code to a directory named by the codeDirectory parameter, with a file name that is a sanitized version of the model name, and an extension that is the last package of the generatorPackage.

Parameters:

code - The StringBuffer containing the code.

codeFileName - The name of the output file.

overwriteFile - The overwrite flag.

dontShowDialog - When true the confirmation dialog won't be shown.

Returns:

The name of the file that was written.

Throws:

IllegalActionException - If there is a problem reading a parameter, if there is a problem creating the codeDirectory directory or if there is a problem writing the code to a file.