10.7. Running Larch Scripts, and Modules¶
Once you’ve done any significant amount of work with Larch, you’ll want to save what you’ve done to a file of Larch code or a script and run it over again, perhaps changing some input. You may even want to write some function that can be re-used – this is highly recommended, and it reduces the amount of text to maintain and find bugs in.
Once you have a Larch script, there are two ways to use it with Larch. First, you can just run it as a script. Alternatively, you can import it into Larch. The distinction can be subtle, and has to with where the variables “live” within your larch session. We’ll discuss both possibilities and their differences here.
10.7.1. Running a larch script with run()
¶
If you have a Larch script, you can run it with the built-in run()
function:
# file myscript.lar
print('hello from myscript.lar!')
name = 'Fred'
phi = (sqrt(5)+1)/2
for i in range(5):
print(i, sqrt(i))
#endfor
# end of file myscript.lar
To run this, you simply type:
larch> run('myscript.lar')
hello from myscript.lar!
0 0.0
1 1.0
2 1.41421356237
3 1.73205080757
4 2.0
Again, the script can contain any Larch code, including procedure
definitions. After running the script, any variables assigned in the
script will exist in your larch session. For example, running the above
script, there will be variables name
, phi
, and i
(and i
will hold the value 4), and you can access these:
larch> print(i, name, phi)
4 Fred 1.61803398875
These variables are held in the “top-level namespace”, _main
, about which
we’ll see more below.
10.7.2. Importing a Larch Script as a Module¶
The alternative method for using the script above is to import it,
using the import
statement:
larch> import myscript
0 0.0
1 1.0
2 1.41421356237
3 1.73205080757
4 2.0
Notice a few differences: First, the ‘.lar’ suffix was removed. Second,
the name is not in quotes. The content of the file is still run, and the
print
function still prints output. But now the variables name
,
phi
, and i
are held in a group named myscript
. Compared to the
run()
function above, this provides better organization, as the
variable names are not in the top-level group, but in their own group,
named after the name of the module.
The import
statement is more versatile than the run()
function,
and has three important differences. First, the import
statement looks
for files with extensions of .lar
or .py
, so that you can import
either larch scripts or any python module with the import statement
.
This is a subtle but highly important point: any python module can be
imported directly into Larch.
Second, you can control what is actually imported, and where it goes. For
the above example with import myscript
, a group called myscript
was
created, with variables name
, phi
, and i
. If you want the
group called something else, or you want to not import everything, but only
selected elements (perhaps only one procedure or piece of data), you can
use variations on the standard Python import
statement like:
import myscript as mx
from myscript import name, phi
from myscript import name as my_name
The first of these will create a group mx
with elements name
,
phi
, and i
. The second will copy the values of name
and
phi
into the top group, and the last will copy the value of name
to
the variable my_name
in the top group.
The third important feature of import
is that it will search for
modules outside of the current working directory. For this, there is a
search path used to find larch modules. The search path is held in the
system variable _sys.path
, and can thus be set during a larch session.
By default, this starts with the current working directory (‘.’), and is
then followed by the user’s Larch module directory, which will typically
$HOME/.larch/modules
on Unix or Mac OSX or $USER\larch\modules
on
Windows. If a file with the .lar
extension is not found in one of
these three places, the standard Python rules for importing modules will be
used.