Invoking

1: Introduction
2: Invoking Gre
3: Gre Grammar
4: Commands
5: Cookbook
6: Hints
7: History
8: Plans
9: Concept Index

2: Running `gre'

About this chapter. This chapter tells the details of running `gre'. If you read the end of the last chapter, you already know enough about running `gre' to skip ahead to the next chapter for now, planning to return here to read the gory details if/when you need them.

2.1: Command-line options

`Gre' usage is of the form: 
   gre OPTIONS ARGS

where `ARGS' often consists of just one argument, the name of a command file containing `gre' commands to be executed.

2.1.1: Command file

Although it is normal (and recommended) to provide a command-file name, it is actually optional. If no command-file is given, `gre' reads standard input for the commands to be done. Thus, one might do 
   cat cmd.gre | gre

instead of 
   gre cmd.gre

If a PostScript file is created (i.e. if any drawing commands are done), it will be named something like `gre-00.ps', or `gre-01.ps', etc (see below). One might also type `gre' at the unix prompt, and type commands in interactively. This makes very little sense, however, since the commands won't be parsed until end-of-file (control-D) is typed, so you could type for minutes, get an error, and lose the work.

Usually the command file name ends in the suffix `.gre'. Thus one might invoke `gre' as 
   gre foo.gre

to run the commands in the file `foo.gre'. However, since the suffix is the expected one, in this case you may also run `gre' by the command 
   gre foo

and the default suffix will be assumed.

Most applications involve drawing something, and the result is a PostScript file. The name of this file is normally derived from the command-file name by switching the suffix to `.ps', e.g. the example above creates a PostScript file called `foo.ps', although the use of the `-p' command-line argument permits the use of any file-name (see below). If no command-file is given, then standard-input is used and the PostScript output is saved in a file called `gre-00.ps', or, if that file exists, `gre-01.ps', etc.

2.1.2: Extra arguments

Any extra `ARGS' provided in addition to the command-file name are stored into the built-in vector `$ARGV'. Thus, invoking `gre' as 

   gre foo.gre hi there
defines `$ARGV[0]' as the string `hi' and `$ARGV[1]' as the string `there'. This is often useful in `gre' programs designed to work on a series of datafiles; for more information see Vector System Variables.

2.1.3: Options

Each option has both a long form (double-dash) and a short form (single-dash). The `OPTIONS' are as follows.

`-h'
`--help'

Print a help message, mainly listing these commandline arguments.

`-p psname'
`--postscript psname'
Name the PostScript output file.

`-d D'
`--debug D'
Turn on various types of debugging:

`1' -> print information about commands as they are parsed

`2' -> print info when values are assigned to variables

`4' -> print info when the OS is used, e.g. to create temporary files

`8' -> while parsing, print any comments that start with `##'

`128' -> used by developer only; meaning changes without warning

`256' -> output 'yacc' info during parsing; only the `gre' developer will find this useful

The value of `D' may be the sum of some of the above, or the `-d' flag may be repeated, to yield several of the listed behaviors.

`-O opt'
`--Optimize opt'

Set optimization level, `opt', as defined in the following list.

`0' -> no optimization (the default)

`-t'
`--trace'
Turn on tracing during scanning (not during execution!).

`-w'
`--warnings'
Turn on warnings.

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

`-e cmd'
`--execute cmd'

Add indicated command(s) to a list of things to be done instead of processing a command file. Because the operating system will be reading this information, `cmd' is normally enclosed in quote marks. If your command requires quote-marks, you will need to escape them, e.g. the following will print a greeting before doing anything else. 

gre -e "print \"HELLO\\n\";"

`-o OPTION'
`--option OPTION'

Specify an OPTION chosen from this list:

`no_startup' -- do not use the system `gre.cmd' startup file (only the developer should use this flag)

`no_grerc' -- do not use `~/.grerc' user-startup file

`-L dir'
`--Library dir'

Name directory where startup file `gre.cmd' is to be found, over-riding the system default of `/usr/share/gre-0.2.2'. NOTE: Multiple `--Library' commands are allowed, the last one being used and previous ones ignored.

`--which_library'
Reports which directory stores the library files, as set by the `--Library' command or be default, and then exits. This is normally used only by the gre-mode.el Emacs mode.
Commandline aliases: Following an invention of the linux community, `gre' allows user-derived aliasing of commandline options. Aliases may be stored in the user's `$HOME/.popt' file, or in a system file (by default, `/etc/popt' on linux machines -- presently unavailable on other machines). See linux documentation for more on the technique. For example, the following entry in a `$HOME/.popt' file might be used to set up large fonts and thick lines, for use in generating graphs for projected overhead transparencies: 

   alias gre --overhead -e "set font size 24;" -e "set line width 3;"

With this, one need only to invoke `gre' as 

   gre --overhead slide1.gre

to get the desired effect.

2.2: System startup file `gre.cmd'

The `gre' grammar is defined ``on the fly'' in a system startup file named `gre.cmd'. This file is used by `gre' at startup time, and it should not be edited by users. It is normally located in directory named `/usr/share/gre-0.2.2'.

One may specify an alternate location of the `gre.cmd' file with the `-L' commandline option see Commandline options. If this is specified, then the indicated directory is searched instead of the default directory.

`gre' will die immediately if it cannot locate the `gre.cmd' file.

2.3: User startup file `~/.grerc'

Once the builtin grammar has been processed, `gre' looks for any additional enhancements the user may have created in his/her personalized startup file, named `~/.grerc'.

Any commands you put in a file called `~/.grerc' will be parsed before `gre' parses your command file. (This behaviour may be turned off with the command-line argument `-o no_grerc' (Commandline options.) Therefore `~/.grerc' is the place to put code that you use often: it is your personal library of extensions to `gre'. Here is an example, from the author's `~/.grerc' file, which draws a pretty blue underlay in the graph area, then draws vertical and horizontal white lines at the labelled tic marks of the axes, laying out a grid. This is nice for creating slides for projection in seminars. 

   #* Draw color underlay for graph, with white grid lines
   #* @param $style =0 for light blue underlay
   cmd draw axes_underlay ($;) {  # $style
       if ($_[0] == 0) {
           draw axes none;
           set color rgb 0.5 0.7 1;
           draw box filled $_xleft $_ybottom $_xright $_ytop;
           set color white;        
           set line width $_linewidth_axis / 1.25;
           for ($x = $_xleft; $x <= $_xright; $x += $_xinc) {
               draw line from $x $_ybottom to $x $_ytop;
           }
           for ($y = $_ybottom; $y >= $_ytop; $y += $_yinc) {
               draw line from $_xleft $y to $_xright $y;
           }
           set color black;
       } else {
           die "`draw axes underlay' style=$_[0] not allowed.";
       }
   }

Sample use: 
   # ... define the axes (perhaps by auto-scaling from data)
   draw axes_underlay 0;
   draw axes;
   draw curve;

Caution. The use of a startup file by `gre' is a bit of a missed blessing, as it is in other programs. Compatibility problems can arise when you change how commands work in your `~/.grerc' file without changing all files that use these commands. For example, suppose you've written a great new command `draw whizbang' and put it in your `~/.grerc' file. If it's really useful, you'll probably refer to it in dozens of your `gre' programs. But then, one day, you may decide to change `draw whizbang' in some way that makes sense for the work you're doing at the moment. Unless you go back and change all the `gre' programs that were set up to use the old version of `draw whizbang', you'll find that the changes have broken old code. This sort of compatibility error is not unique to `gre'; it occurs with startup files of many programs. The problem is that very few users keep track of dependencies from program to program. For this reason, you should use caution when working with `~/.grerc'.

For many purposes you'll find it better to work with numbered libraries that you maintain and use with the `use' command see Use.

(c) 1997-2000 Dan E. Kelley, email Dan.Kelley@Dal.Ca