# 3.1 Getting started

The simplest way to start Pyxplot is to type `pyxplot` at a shell prompt. This starts an interactive session, and produces a Pyxplot command-line prompt into which commands can be typed. Pyxplot can be exited either by typing `exit`, `quit`, or by pressing CTRL-D. Various switches can be specified on the shell command line to modify Pyxplot’s behaviour; these are listed in Box 3.1. Of particular interest may be the switches `-c` and `-m`, which change between the use of color-highlighted (default) and non-colored text.

Typing commands into interactive terminals is likely to be a sufficient way for a beginner to drive Pyxplot, but as tasks grow more complicated, more commands are needed to set up plots. It is likely to become preferable to store these commands in text files called scripts. Once such a script has been written, it can be executed automatically by passing the filename of the command script to Pyxplot on the shell command line, for example:

    pyxplot foo.ppl

From the shell command line, Pyxplot accepts the following switches which modify its behaviour:

`-h –help` | Display a short help message listing the available command-line switches.
`-v –version` | Display the current version number of Pyxplot.
`-q –quiet` | Turn off the display of the welcome message on startup.
`-V –verbose` | Display the welcome message on startup, as happens by default.
`-c –color` | Use color highlighting1, as is the default behaviour, to display output in green, warning messages in amber, and error messages in red.2 These colors can be changed in the `terminal` section of the configuration file; see Section 9.3.4 for more details.
`-m –monochrome` | Do not use color highlighting.

In this case, Pyxplot executes the commands in the file `foo.ppl` and then exits. By convention, we affix the suffix `.ppl` to the filenames of all Pyxplot command scripts. This is not strictly necessary, but it allows Pyxplot scripts to be easily distinguished from other text files in a filing system. The filenames of several command scripts may be passed to Pyxplot on a single command line, indicating that they should be executed in sequence, as in the example:

    pyxplot foo1.ppl foo2.ppl foo3.ppl

It is also possible to have a single Pyxplot session alternate between running command scripts autonomously and allowing the user to enter commands interactively. There are two ways of doing this. Pyxplot can be passed the magic filename `–` on the command line, as in the example

    pyxplot foo1.ppl -- foo2.ppl

where the `–` represents an interactive session which commences after the execution of `foo1.ppl` and should be terminated by the user in the usual way, using either the `exit` or `quit` commands. After the interactive session is finished, Pyxplot will automatically execute the command script `foo2.ppl`.

From within an interactive session, it is possible to run a command script using the `load` command, as in the example:

`pyxplot> load ’foo.ppl’`

This example would have the same effect as typing the contents of the file `foo.ppl` into the present interactive terminal.

The `save` command may assist in producing Pyxplot command scripts: it stores to a text file a history of the commands which have been typed into the present interactive session.

When Pyxplot is used interactively, its command-line environment is based upon the GNU Readline Library. This means that the up- and down-arrow keys can be used to repeat or modify previously executed commands. Each user’s command history is stored in his homespace in a history file called `.pyxplot_history`; this file is used by Pyxplot to remember command histories between sessions. Pyxplot’s `save` command allows the user to save to a text file a list of the commands which have been typed into the present session, as in the following example:

`save ’output_filename.ppl’`

The related `history` command displays on the terminal a history of all of the commands which have been typed into this and previous interactive sessions. The total history can stretch to several hundred lines long, in which case it can be useful to follow the `history` command by an optional number, whereupon it only displays the last commands, e.g.:

`history 20`

Footnotes

1. This will only function on terminals which support color output.
2. The authors apologise to those members of the population who are red/green color blind, but draw their attention to the following sentence.