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.

We look first at built-in functions for loading scripts, and then at a few utilities.

26.1 Creating Scripts

Here is an example of a tiny script. It is supposed to show a number of definitions and then a computation. The lines of J look like this:

       plus =: +
       k    =: 2 plus 3
       k plus 1   

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. We can create this script with a filename of say example.ijs using the built-in verb 1!:2, like this:

   (0 : 0) (1!:2) < 'c:\example.ijs'
plus =: +
k    =: 2 plus 3
k plus 1   
)

26.2 Loading Scripts

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

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

We see on the screen a transcript, or execution log, showing 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

Now we look at some variations on this basic theme.

26.3 With or Without a Transcript

To suppress the transcript we can load with 0!:0

   0!:0 <'c:\example.ijs'

We see nothing on the screen. The value computed in the script for k plus 1 is discarded. As well as 0!:0 and 0!:1 there are more variations of 0!:n - see the Dictionary.

26.4 Local Assignments in Scripts

Here is an example of a script.

   (0 : 0) (1!:2) < 'c:\exa.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.

w can, in effect, be made local to the execution of the script on two conditions. The first is that we 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) < 'c:\exb.ijs'
w   =. 1 + 1
foo =: + & w  
)

The second condition is that we load the script inside an explicit function, so there is something for w to be local to. (Outside any explicit definition that is, "at the top level", =. is the same as =:)

All that is needed is the merest wrapper of explicit definition around 0!:0 or 0!:1. A suitable "localizing loader" verb might be:

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

If we now load this script

   LL < 'c:\exb.ijs'

and then look at the results:

foo	w
+&2	error

we see that foo is as expected, but 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.

26.5 Local Verbs in Scripts

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

   (0 : 0) (1!:2) < 'c:\exc.ijs'
sum  =. +/
mean =: sum % # 
)
   
   LL < 'c:\exc.ijs'

We see that this will not work, because mean needs sum and sum, being local, is no longer available.

   mean
sum % #

The remedy is to "fix" the definition of mean, with the adverb f. (as we did in Chapter 12). Our revised script becomes

   (0 : 0) (1!:2) < 'c:\exd.ijs'
sum =. +/
mean =: (sum % #)  f.
)

Now mean is independent of sum

   LL < 'c:\exd.ijs'
   mean
+/ % #
   

26.6 Loading Into Locales

We looked at locales in Chapter 24. When we load a script with 0!:0 or LL the locale that becomes populated with definitions from the script is the current locale.

By default, the current locale is base. In general, we may wish to load a script into a specified locale, say locale foo. Evidently we can do this by switching to locale foo loading and switching back to the base locale.

    18!:4 'foo'
    0!:0  <'c:\example.ijs' 
    18!:4 'base'
   

A neater way is as follows. We define a loading verb, LLL say, which is just like LL above but this time we install it in locale z.

   LLL_z_ =: 3 : '0!:0 y.'
   

Now we can load a script into a specified locale, foo say, with:

   LLL_foo_  <'c:\example.ijs'
   
   

26.7 Library Scripts

The J system comes supplied with a useful library of script files containing predefined utility functions. Library script files are organized in a set of directories. The topmost of these library directories is identified by the expression (1!:42 '') which yields a pathname as a string:

   1!:42 ''
c:\j\
   

Within this topmost library directory, a typical library script-file might be, for example, system\main\dates.ijs. This contains functions for handling calendar dates, and can of course loaded with 0!:0 (although we will see below there is a better way.)

   0!:0 < (1!:42 ''), 'system\main\dates.ijs'

We can inspect one of the utility functions just loaded:

   weekday
7: | 3: + todayno
   

26.8 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 a standard system-supplied profile is used. In this case a session begins with the automatic execution of:

     0!:0 < (1!:42 ''),'system\extras\config\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.8.1 load and loadd

Among these useful predefined verbs is load. Its effect is the same as 0!:0, that is, to load a script without displaying a transcript.

   load 'c:\example.ijs'

Notice that the argument filename above can be a plain string, not boxed. A companion verb is loadd, which, like 0!:1 loads a script displaying a transcript.

load and loadd have several advantages over 0!:0 and 0!:1. The first advantage of load is that for a library script the full pathname is not needed: a simple name is enough. Instead of

   load (1!:42 ''), 'system\main\dates.ijs'

it is enough to say

   load 'dates'

To achieve this effect, load and loadd use a predefined catalog of all the library scripts, set up in the course of executing the standard profile. The catalog is a noun - a boxed table - named PUBLIC_j_ . There are many scripts; the first 7 are shown by:

     7 {.  PUBLIC_j_
+--------+---------------------------------------+-+
|colib   |c:\j\system\main\colib.ijs             |z|
+--------+---------------------------------------+-+
|color16 |c:\j\system\packages\color\color16.ijs |z|
+--------+---------------------------------------+-+
|colortab|c:\j\system\packages\color\colortab.ijs|z|
+--------+---------------------------------------+-+
|compare |c:\j\system\main\compare.ijs           |z|
+--------+---------------------------------------+-+
|convert |c:\j\system\main\convert.ijs           |z|
+--------+---------------------------------------+-+
|dates   |c:\j\system\main\dates.ijs             |z|
+--------+---------------------------------------+-+
|dd      |c:\j\system\main\dd.ijs                |z|
+--------+---------------------------------------+-+
   

Each row has a simple name, the associated full path-name for the script, and finally a locale, usually z or j, into which the script will be loaded. PUBLIC_j_ is itself set up from a file system\extras\config\scripts.ijs. This file can be edited by the user. Thus the second advantage of load is that a script can be automatically steered into an appropriate locale on loading.

The third 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. To avoid repeated loading of the second script we can require it rather than load it, that is load it only if not already loaded.

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

   (0 : 0) (1!:2) < 'c:\first.ijs'
    require 'c:\second.ijs'
    a =: a + 1
)

Here the variable a is a counter: every time first.ijs is loaded, a will be incremented. Similarly for a second script:

   (0 : 0) (1!:2) < 'c:\second.ijs'
    b  =: b + 1
)

We set the counters a and b to zero, load the first script and inspect the counters:

(a =: 0),(b =: 0)	load 'c:\first.ijs'	a,b
0 0		1 1

Evidently each script has executed once. If we now load the first again, we see that it has executed again, but the second has not:

load 'c:\first.ijs'	a,b
	2 1

The effect is achieved by automatically tracking what has been loaded with load or loadd in a table called LOADED_j_.

   LOADED_j_
+--------------------------+-+
|c:\book\tools\mnemonic.ijs| |
+--------------------------+-+
|c:\j\system\main\files.ijs|z|
+--------------------------+-+
|c:\example.ijs            | |
+--------------------------+-+
|c:\j\system\main\dates.ijs|z|
+--------------------------+-+
|c:\first.ijs              | |
+--------------------------+-+
|c:\second.ijs             | |
+--------------------------+-+

The fourth advantage of load is that it respects local assignments (because at the heart of load is 0!: 0).

The fifth advantage of load is that an optional left argument can specify a locale into which to load the script. For example:

   'mylocale' load 'c:\example.ijs'
   
   plus_mylocale_
+
   

26.8.2 More on 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.

   ,. 4 !: 3 ''
+-------------------------------------+
|c:\book\tools\pr1406.ijs             |
+-------------------------------------+
|c:\j\system\extras\util\boot.ijs     |
+-------------------------------------+
|c:\j\system\main\stdlib.ijs          |
+-------------------------------------+
|c:\j\system\main\winlib.ijs          |
+-------------------------------------+
|c:\j\system\main\colib.ijs           |
+-------------------------------------+
|c:\j\system\main\loadlib.ijs         |
+-------------------------------------+
|c:\j\system\main\jadelib.ijs         |
+-------------------------------------+
|c:\j\system\extras\config\scripts.ijs|
+-------------------------------------+
|c:\j\system\extras\config\winpos.ijs |
+-------------------------------------+
|c:\j\system\extras\util\configur.ijs |
+-------------------------------------+
|c:\j\system\extras\config\config.ijs |
+-------------------------------------+
|c:\book\tools\pr2406.ijs             |
+-------------------------------------+
|c:\book\tools\mnemonic.ijs           |
+-------------------------------------+
|c:\j\system\main\files.ijs           |
+-------------------------------------+
|c:\book\work\current.ijs             |
+-------------------------------------+
|c:\example.ijs                       |
+-------------------------------------+
|c:\exb.ijs                           |
+-------------------------------------+
|c:\exc.ijs                           |
+-------------------------------------+
|c:\exd.ijs                           |
+-------------------------------------+
|c:\j\system\main\dates.ijs           |
+-------------------------------------+
|c:\first.ijs                         |
+-------------------------------------+
|c:\second.ijs                        |
+-------------------------------------+

We see some scripts loaded by the standard profile, and others particular to this session. 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

i =: 4!:4 < 'plus'	i { 4!:3 ''
15	+--------------+ |c:\example.ijs| +--------------+

26.8.3 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.
• Use load, loadd or require for loading scripts.

This is the end of Chapter 26.