Chapter 26: Script Files

A file containing text in the form of lines of J is called a script-file,
or just a script.
By convention a script has a filename
terminating with .ijs .
The process of executing the lines of J in a script-file
is called "loading" a script.

We write our own scripts for our
particular programming projects.
In addition, the J system comes supplied
with a library of predefined scripts of
general utility.

The plan for this chapter is to look at

built-in verbs for loading scripts

the load verb and its advantages,
including convenient loading of library scripts

the "profile" script automatically loaded at the beginning of a J session

26.1 Creating Scripts

Suppose we have an existing directory where
we intend to store our own scripts.
It is useful to begin by identifying this directory.
For example, with Linux we could say:

scriptdir =: '/home/username/jscripts/'

(Notice that last character). With Windows we could say:

scriptdir =: 'c:\jscripts\'

Scripts are usually created using a text editor,
but here it is convenient
to use J to create small examples of scripts
as we need them.
Here is an example of creating a tiny script,
with a filename of say example.ijs, using
the built-in verb 1!:2 thus:

26.2 Loading Scripts

There is a built-in verb 0!:1 to load a script.
The argument is a filename as a boxed string.

0!:1 < scriptdir,'example.ijs'
plus =: +
k =: 2 plus 3
k plus 1
6

We see on the screen a display of the lines of the script as they were executed,
together with the result-values of any computations.
The definitions of plus and k are now available:

plus

k

+

5

The verb 0!:1, as we saw, loads a script with a display.
We can choose whether or not to display, and
whether to stop or to continue loading after an error. There are four similar verbs:

0!:0

no display

stopping on error

0!:1

with display

stopping on error

0!:10

no display

continuing on error

0!:11

with display

continuing on error

For example:

0!:0 < scriptdir,'example.ijs'

We see nothing on the screen. The value computed in the script for k plus 1
is discarded.

26.3 The load Verb

There is a verb load which is predefined, that is, automatically available
in the standard J setup.
It can be used just like 0!:0 to load a script

load < scriptdir,'example.ijs'

The script is loaded without a display and stopping on error. There is a companion
verb loadd which loads with a display, stopping on error.

loadd < scriptdir, 'example.ijs'
plus =: +
k =: 2 plus 3
k plus 1
6

load and loadd have several advantages compared with 0!:n .
The first of these is that the filename need not be boxed.

loadd scriptdir, 'example.ijs'
plus =: +
k =: 2 plus 3
k plus 1
6

26.4 Library Scripts

The second advantage of load is that it is convenient for loading "library"
scripts. The J system comes supplied with a useful library
of script files containing predefined utility functions and documentation.
Library script files are organized in a set of
directories under the J installation directory.

There is a catalog of library scripts, stored in a variable,
a table called PUBLIC_j_ .
The following shows a few "catalog entries" in rows 15-17 of PUBLIC_j_

We see for each library script a "short name"
(for example, 'dir')
and a filename for the script, in a special form where ~
means the directory in which J is installed. The ~
form can be translated into a full filename with the library verb
jpath.

jpath '~system\main\dir.ijs'
e:\j\j601obeta\system\main\dir.ijs

The load verb can load a library script given the short
name or a full filename.

load 'dir'
load jpath '~system\main\dir.ijs'

26.5 Local Definitions in Scripts

Now we look at the treatment of local variables in scripts.
Here is an example of a script.

(0 : 0) (1!:2) < scriptdir, 'ex1.ijs'
w =: 1 + 1
foo =: + & w
)

Suppose that variable w has the sole purpose
of helping to define verb foo and otherwise w is of
no interest. It would be better
to make w a local variable.

Firstly, we need to assign to w with =.
in the same way that we assign to local variables in explicit
functions. Our revised script becomes:

(0 : 0) (1!:2) < scriptdir, 'ex2.ijs'
w =. 1 + 1
foo =: + & w
)

Secondly, we need something for w to be local to, that is, an explicit
function, because outside any explicit function
(that is, "at the top level") =. is the same as =:
All that would be needed is the merest wrapper of explicit definition
around 0!:n, such as:

LL =: 3 : '0!:0 y'

If we now load our script

LL < scriptdir, 'ex2.ijs'

and then look at the results:

foo

w

+&2

error

we see that foo is as expected,
and, as intended, there is no value for w.
Therefore w was local to the execution of the script,
or strictly speaking,
local to the execution of LL.

An advantage of the load verb is that it provides the explicit function
needed to make w local.

erase 'foo';'w'
1 1
load scriptdir, 'ex2.ijs'

foo

w

+&2

error

26.5.1 Local Verbs in Scripts

In the previous example,
the local variable w was a noun.
With a local verb,
there is a further consideration.
Here is an example of a script which tries to use
a local verb (sum) to assist the
definition of a global verb (mean).

so we conclude that self-steering scripts should be loaded with load and
not with 0!:n.

We return to base.

18 !: 4 < 'base'

26.7 Repeated Loading, and How to Avoid It

Another advantage of load is this.
Suppose one script depends on (definitions in)
a second script. If the first
includes a line
such as load 'second' then
the second is automatically loaded
when the first is loaded.

If we load the first script again
(say, after correcting an error)
then the second will be loaded again. This may
be unnecessary or undesirable.
The predefined verb require is like load
but does not load a script if it is already loaded.

Here is a demonstration. Suppose we have
these two lines for the first script:

26.8 Load Status

We saw above that the J system maintains a record of
which scripts have been loaded with the load verb.
There is
another separate system which keeps track of ALL scripts
loaded, whether with load or with 0!:0. The built-in verb
4!:3 with a null argument gives a report
as a boxed list of filenames. Here are the last few entries
in this report.

Recall that we defined plus
in the script example.ijs which we loaded above.
The built-in verb 4!:4 keeps track
of which name was loaded from which script.
The argument is a name (plus for example)
and the result is an index into the list of scripts
generated by 4!:3. We see that plus was indeed
defined by loading the script example.ijs

26.9 The Profile

A J session begins with the
automatic behind-the-scenes loading of a
script file called the "profile".
The contents of the profile can be whatever we choose -
whatever function definitions or other things we find
convenient to have on hand as our regular setup at the beginning of
a session. Commonly a profile itself loads
a further selection of library scripts and our own scripts.

The profile to be used is specified in the operating-system command-line
initiating the J session.
If no profile is specified in the command-line,
then by default a standard system-supplied profile is used.

This default, or standard, profile can be identified by 1 !: 45 :

1 !: 45 ''
e:\j\j601obeta\profile.ijs

Loading this standard profile
will load a further standard selection of library scripts,
to give a set of commonly useful predefined verbs.
The user can customize the standard profile to load
further scripts.

26.9.1 Summary

The recommendation is :

Use the standard profile, or the standard profile
with additional customizing. This ensures that
a session begins having loaded the standard library scripts.