Multiple Script Files
In complex 3D modeling projects, it is often beneficial to organize code into multiple script files. This approach promotes code reuse, improves maintainability, and allows for better organization of model components. The trCAD system supports the inclusion of multiple script files, enabling developers to build modular and scalable 3D models.
This section covers the methods available in trCAD for including external scripts into a main script. We will explore the use of the #insert and #import commands, discussing their purposes, benefits, and potential pitfalls.
The #insert Command
The #insert command is a precompiler pragma used to inline another script into the current script. It takes a string argument that specifies the file name of the script to be included.
Example
#insert("anotherscript.sps")
Potential Name Conflicts
When using the #insert command, be cautious of name conflicts. Inlining scripts can lead to variable or function name clashes if the same identifiers are used in both the main script and the included script. To avoid this, ensure that variable and function names are unique across all scripts being combined.
The #import Command
The #import command provides a more robust way to include external scripts by importing them as packages. Unlike inlining, importing scripts as packages helps prevent name conflicts by encapsulating the included script's scope.
The #import command takes the name of a script file as only argument, e.g #import( "myfiles/anotherscript.sps" ). The file is then included as package. This package can be addressed by its identifier that is the file name without directory and postfix (e.g anotherscript). To avoid conficts from importing multiple files with equal names, an additional identifier can be appended to the #import command that is then used as package identifier, like in the following example:
Example
#import("myfiles/anotherscript.sps") mypackage
Benefits of Using #import
Using the #import command offers several advantages over #insert:
- Encapsulation: Scripts are imported as packages, which encapsulates their scope and prevents name conflicts.
- Reusability: Packages can be reused across different projects without modification.
- Clarity: The package identifier provides a clear namespace, making it easier to understand where variables and functions originate.
- Using as parts: Packages can be used as 3D model parts.
Accessing Objects Inside Packages
Objects within a package can be accessed using the package identifier followed by a double colon (::) and the object name:
mypackage::myobject
Only variables and functions declared with the open or public keywords can be accessed from the importing script. Additionally, the document.expose_opar variable, as described in the section about open parameter visibility, can be accessed. The main solid object, which is detailed in the main solid object access section, is also accessible from the importing script.
File "anotherscript.sps":
Example
open int i
{
name = "My Open Parameter"
descr = "This integer is readable from outside."
value = 3
}
public string s = "My public string."
public function f()
{
echo("This is function f()")
}
Main script file:
Example
#import("anotherscript.sps")
echo(anotherscript::i)
echo(anotherscript::s)
anotherscript::f()
Output
3
My public string.
This is function f()
Objects in package that are imported over more than one level can be access by the same mechanism:
File "level2.sps":
Example
public string s = "My public string."
File "level1.sps":
Example
#import( "level2.sps" )
Main script file:
Example
#import ( "level1.sps" )
echo( level1::level2::s )
Repeated Package Import
It is possible to import a single package multiple times to access different instances. Each instance must have a unique identifier.
Example
#import("anotherscript.sps")
#import("anotherscript.sps") s2
anotherscript::f()
s2::f()
An alternative method for creating multiple instances of solids generated by an imported package is described in the section about multiple instances.
Package Execution Control
Lazy Execution
Lazy execution means that a new execution of a package occurs only when open or public values are accessed. This allows for efficient execution by preventing unnecessary recalculations. For instance, setting multiple open parameter values does not trigger an execution each time a value is set. Instead, execution is deferred until the values are actually needed.
The run Command
The run command can be used to explicitly trigger the execution of a package. This is useful when you want to ensure that the package is executed immediately, regardless of whether any open or public values have been accessed.
Example
run mypackage
Resetting a Package
The reset command is used to reset a package to a state where it will be executed freshly whenever a public or open parameter or function is read next. This ensures that any changes to the open parameters or their attributes are correctly applied the next time the package is executed.
Conclusion
Using multiple script files in trCAD allows for better organization, reusability, and maintainability of 3D models. The #import command is generally preferred over #insert due to its encapsulation benefits and reduced risk of name conflicts. By understanding and utilizing these commands, developers can create more modular and scalable 3D models.
