3: Invoking Gri

3.1: Invoking Gri in a nutshell

gri myscript

where the file `myscript.gri' holds a script (list of Gri commands), and Gri will create a PostScript file called `myscript.ps' with the output.

Some folks like to give the `.gri' suffix explicitly, so they would invoke Gri as

gri myscript.gri

instead.

If you'd rather not have `myscript.ps' as the PostScript output file name (let's say you prefer `graph1.ps') you'd do

gri -output graph1.ps myscript.gri

Few readers will need to know more than this. But, for the rest, the table in the next section gives full details on all the optional arguments that Gri can handle.

3.2: Using Gri to draw things

gri [OPTIONS] [CmdFile [optional_arguments]]

where the square brackets indicate that the enclosed items are optional. The `OPTIONS' item may consist of one or more of the following (explained below):

[-batch] [-b] [-chatty N] [-c N] [-debug] [-d] [-directory_default] [-directory pathname] [-help] [-h] [-no_bounding_box] [-no_cmd_in_ps] [-no_startup_message] [-output PS_file_name|SVG_file_name] [-private] [-no_private] [-publication] [-p] [-superuser N] [-trace] [-t] [-yes] [-y] [-version] [-v] [-warn_offpage] [-no_warn_offpage]

Here, the optional `optional_arguments' are a mechanism to customize the action of the given Gri script from the commandline. After Gri processes standard arguments (e.g. `-t' for tracing), it puts the remaining commandline arguments into a list. This behavior is borrowed from C and othe languages, so Gri borrows the name of the list as well: it's called the "arg" list, and its elements are available with the RPN operators named `argc' (see Solitary Operators) and `argv' (see Unary Operators).

For a note on usage within the Emacs gri-mode, see see Filename arguments when running gri.

Details of command-line options

• `-batch' or `-b' Stops Gri from printing out prompts and hints.

• `-chatty N' or `-c N' Make Gri print out various informative messages. The numerical value gives a level of chattiness. A value of 1, the default if the `-chatty' code is not supplied, tells Gri to keep you informed of some important things, like the success in gridding data for contouring. Higher values make Gri tell you more:

  Information printed at various chatty levels:

  • 0 The bare minimum is printed. Thus invoking Gri as `gri -c 0'... will make it as quiet as can be.

  • 1 or higher (the default) The full filenames of the commandfiles are displayed at startup time.

    `convert columns to grid' prints percentage of grid filled, as well as a suite of diagnostics, if you've let it calculate the region of influence automatically. It also prints a warning of the time it expects to take, before starting the calculation.

    `convert grid to image' prints characteristics of image created, including amount of image clipped.

    `read grid data' reports number of data values it could not read (since they were nonnumeric).

    `draw symbol' reports number of data points not drawn because they were missing or outside clip region (if one exists).

  • 2 or higher `draw contour' prints value of contour being drawn.

    `open "...|"' prints the command to be passed to the operating system as well as the name of the temporary file being created; also notifies user when the temporary file is destroyed.

    `show image' reports histograms in intensity bands of 8 units, instead of the default 16 units.

  • 3 or higher `show image' reports histograms in intensity bands of 4 units, instead of the default 16 units.

• `-debug' or `-d' Sets the built-in variable flag `..debug..' that you can use to isolate blocks of code.

• `-directory_default' Reports directory where `gri.cmd' is expected to be found, either in the default location or the one specified by `-directory' commandline option.

• `-directory pathname' Specifies the directory where Gri looks for the startup file `gri.cmd'. (This file teaches Gri the standard commands; Gri will report an error and die if it cannot find this file.) If this switch is not provided -- and it is normally not -- then Gri looks for `gri.cmd' in a standard system directory (sometimes, but not always, `/usr/local/share/gri/2.12.26') which was specified during the compilation of the Gri program itself. For more on how Gri looks for `gri.cmd', see the subsection below.

• `-no_bounding_box' Make the so-called ``bounding box'' in the PostScript file be the full page. The bounding box is used by some PostScript previewers to clip the image to just the drawn parts of the page, and is used by the `epsfbox' macro in `latex' to automatically determine the geometry of the graph for inclusion in text. Normally the bounding box is calculated automatically, to enclose all the items drawn on the page. But the box may also be set with the `set bounding box' command (see Set Bounding Box).

• `-no_cmd_in_ps' Prevent Gri from inserting the lines of the commandfile into the PostScript file as comments. (These comments can be used by the `-creator' commandline option (see above), but they take up a little bit of space and users might sometimes want to get rid of them.)

• `-no_warn_offpage' Do not warn if items are offpage. (Contrast this with `-warn_offpage'.)

• `-output PS_file_name' Specify the PostScript filename. If this is not specified, the PostScript filename is derived from the name of the commandfile (e.g. `mygraph.gri' produces `mygraph.ps'), or, for interactive use, it will have a name like `gri-00.ps', or `gri-01.ps' if the former file exists, etc.

• `-output SVG_file_name' Specify the SVG filename. This is a pre-feature, as of version 2.12.x, meaning that SVG output is not working properly yet. If you specify an SVG file name, you will see a long list of warnings. These are debugging messages, and are not specific to your actual Gri script. For example, you will see warnings about centring strings, even if you are not centering any strings. This manual does not contain a list of working features (or broken features) for SVG output; the idea is that a discussion of such things be done using the bug-reporting system of the Gri website see Reporting Bugs. In addition to bugs, the author is interested in users' opinions on the scheme of the SVG, especially the hieararchy of groupings of graphical elements. It is because such things are being altered that this is designated a pre-feature.

• `-no_startup_message' Stops Gri from printing the startup message.

• `-private' Prevents inserting any information about the user into the PostScript file (see `-no_private', next). As of version 2.12.10, this privacy option is assumed by default.

• `-no_private' Instructs Gri to include comments in the PostScript file that identify the user, state the commandline arguments used in invoking Gri, and that list all the commands that were executed. This information can be recovered by calling Gri on the PostScript file, with the `-creator' commandline argument. Until version 2.12.10, the default was to include this information, but a change was made out of privacy concerns.

• `-publication' or `-p' Sets the built-in variable `..publication..' to 1. You may use this to distinguish between working plots and publication plots, as in this example:

  if !..publication.. draw time stamp draw title "working version of plot" end if

• `-superuser' (This option is included here only for completeness. It should only be used by developers (who will alter the code to print debugging information if `-superuser' is set in addition to `-debug'). An optional value can be inserted (e.g. `-superuser 2') to set the debugging level (retrievable by the function superuser()) to indicated integer value. Specifying the `-superuser' command-line option sets the built-in variable `..superuser..' to 1 or the specified value.)

  For flag meanings, see `superuser' command (see Superuser). Using the question-mark symbol `?' instead of a flag number makes Gri print out the list of flags.

• `-trace' or `-t' Makes Gri print out command lines as they are executed; this has the same effect as the `set trace' command.

• `-version' or `-v' Display version information and exit successfully.

• `-warn_offpage' Causes warnings to be issued for all items drawn far off a 8.5x11 inch page. This is the default. (Contrast with `-no_warn_offpage'.)

• `-yes' or `-y' Bypasses all `query' commands, making Gri act as though the user typed a carriage-return (thus giving the default) for each `query'.

• `-help' or `-h' Prints explanation of options.

• `CommandFile' If a command file `CommandFile' is specified, then commands will be read from that file instead of the keyboard. If the `chatty' level is 1 or larger, Gri prints the names of the commandfiles at startup time. It is conventional but not necessary that the filename ends in `.gri'. If the filename does end in `.gri', you may delete this suffix; Gri will assume it as implied.

Executable scripts. If you don't need to supply commandline options, you can put the following line as the first line in your Gri program

#!/usr/bin/gri

(or point to wherever Gri is located on your machine), and `chmod +x' the file. Then you can run Gri simply by naming the file. There is no particular advantage in this, except for saving the typing of a few characters, but some folks like this.

How Gri locates the `gri.cmd' file. In a normal installation, Gri finds the `gri.cmd' file all by itself. However, developers and some others may wish to control where Gri looks for this file. The rules below specify how Gri looks for `gri.cmd'.

Case 1

If `-directory' was given on the commandline used to invoke Gri (e.g. `gri -directory /some/place mycommand_file.gri'), then Gri will use the `gri.cmd' in the named directory. An error will result if `gri.cmd' is not found there.

Case 2

If `-directory' was not given on the commandline, then Gri looks for `gri.cmd' in a location that was specified during compilation. If `gri.cmd' is found there, then it is used. If it is not found, then Gri checks to see if an environment variable named `GRI_DIRECTORY_LIBRARY' is defined. If so, then Gri takes this to be the name of a directory that contains the `gri.cmd' file. If `gri.cmd' is not found there, an error results.

3.3: Extracting commandfile from a PostScript file

gri -creator PostScriptFile

See also `-no_cmd_in_ps'.

The `-creator' flag makes gri examine the indicate PostScript file, and produce a facsimile of the command file (or interactively-typed commands) that created this PostScript file. (This only works if the Gri command that created the PostScript file used the `-no_private' commandline argument.)