Lens script files are just standard Tcl script files. It is customary to give a Tcl script file the extension ".tcl". It is more or less customary to end Lens script files used primarily for build networks with the extension ".in". If the Lens script file doesn't create a network, I would use the ".tcl" extension. If you use extensions other than these, you may want to change the default file filter used by the file browser for script files by editing the .lensrc file.
A script is run using the source command. The behavior of this command in Lens is slightly different than that of the standard Tcl command. In Lens, the current directory will be changed to the directory containing the script file while the script is being executed and then changed back at the end. This makes it possible to use relative references to files accessed within the script. For example, a network building script might contain the command:
loadExamples foo.ex
Assuming that foo.ex is located in the same directory as the script, this will only work properly if the current directory becomes that directory while the script is executing.
Using return
within the top level of a script will cause the script to end. However,
if return is called within a procedure invoked during the script, only
that procedure will end. Using return -code return,
rather than just return will cause the current script to
exit, even if it is executed within a procedure. This will not cause
parent scripts to exit, however. To do that as well, use return
-code error or just error.
Arguments cannot be passed to a script as in other languages. If you would like to run a script with arguments, you might instead define a procedure inside the script and put your code inside the body of the procedure. You could then source the script to define the procedure and then call the procedure with its arguments.
You can avoid sourcing the script containing the procedure by using the
index command to create a
.tclIndex file. The .tclIndex file is a
record of all the procedures defined in all the script files in the
directory. If a procedure is executed that has not been defined and the
procedure is
listed in a .tclIndex somewhere in your auto_path, its file will be
sourced and then the procedure executed.
In order for a procedure to be registered by index, it must be defined in a file whose name ends with ".tcl" or ".in". If you write a new procedure, you must run index again before it will be accessible. If you change a procedure after it has been loaded in the interpreter, you must re-source its file by hand to get the new version.
Rather than creating a new script file for each procedure you may want
to just create a single ".tcl" file in your project directory that
contains definitions of all the procedures you will use. Then you will
have less clutter and the file need only be read once so procedures will
execute more quickly. You may also want to add a directory to your auto_path containing scripts
that define procedures you use on several projects.