# 7.1 Configuration files

Configuration files for Pyxplot have the filename `.pyxplotrc`, and may be placed either in a user’s home directory, in which case they globally affect all of that user’s Pyxplot sessions, or in particular directories, in which case they only affect Pyxplot sessions which are instantiated with that particular directory as the current working directory. When configuration files are present in both locations, both are read; settings found in the `.pyxplotrc` file in the current working directory take precedence over those found in the user’s home directory. Configuration files are read only once, upon startup, and subsequent changes to the configuration files do not affect copies of Pyxplot which are already running.

Changes to settings made in configuration files affect not only the values that these settings have upon startup; they also changes the values to which the `unset` command returns settings. Thus, whilst the command

    unset multiplot

ordinarily turns off multiplot mode, it may turn it on if a configuration file contains the line

    multiPlot=on

When colored terminal output is enabled, the color-coding of the `show` command also reflects the current default configuration: settings which match their default values are shown in green1 whilst those settings which have been changed from their default values are shown in amber2.

Configuration files should take the form of a series of sections, each headed by a section heading enclosed in square brackets. Each section heading should be followed by a series of settings, which often take the form of

    setting_name = value

In most cases, neither the setting name nor the value are case sensitive.

The following sections are used, although they do not all need to be present in any given file, and they may appear in any order:

- `colors` – contains a single setting `palette`, which should be set to a comma-separated list of colors which should make up the palette used to plot datasets. The first will be called color 1 in Pyxplot, the second color 2, etc. A list of recognised color names is given in Section 7.4.

- `filters` – can be used to define input filters which should be used for certain file types (see Section 5.1).

- `functions` – contains user-defined function definitions which become predefined in Pyxplot’s mathematical environment, for example

      sinc(x) = sin(x)/(x)

- `latex` – contains a single setting `preamble`, which is prefixed to the beginning of all latex text items, before the `\begin{document}` statement. It can be used to define custom latex macros or to include packages using the `\includepackage{}` command. The preamble can be also changed using the `set preamble` command.

- `script` – can contain a list of `set` commands, using the same syntax which would be used to enter them at a Pyxplot command prompt. This section provides an alternative and more general way of controlling the settings which can be changed in the `settings` section. Note that this section may only contain instances of the `set` command; other Pyxplot commands may not be used. The `set` command’s `item` modifier may not be used.

- `settings` – contains settings similar to those which can be set with the `set` command. A complete list is given in Section 7.3.2 below.

- `styling` – contains settings which control various detailed aspects of the graphical output which Pyxplot produces. These settings cannot be accessed by any other means.

- `terminal` – contains settings for altering the behaviour and appearance of Pyxplot’s interactive terminal. These cannot be changed with the `set` command, and can only be controlled via configuration files. A complete list of the available settings is given in Section 7.3.4.

- `units` – can be used to define new physical units for use in Pyxplot’s mathematical environment.

- `variables` – contains variable definitions, in the format

      variable = value

  Any variables defined in this section will be pre-defined in Pyxplot’s mathematical environment upon startup.

Footnotes

1. This color can be changed using the `color_rep` setting in a configuration file.
2. This color can be changed using the `color_wrn` setting in a configuration file.