ryrc

DESCRIPTION

The various command line tools that come with Rayon (called the rytools) get their configuration, in order, from the following sources:

  1. The system-wide configuration file /etc/ryrc.
  2. The user configuration file ~/.ryrc.
  3. A per-invocation configuration file, passed in via the --config-file option.
  4. A file specified by the --config-file options.
  5. Options passed in on the command line.

If an option is defined twice, the last defined value will be used, unless the source specifies that previous configuration should be ignored. (See IGNORING CONFIGURATION.)

CONFIGURATION FILE FORMAT

The configuration file uses ”.ini file”-style syntax documented in Python’s ConfigParser documentation.

Options to apply to all tools should go in the [ALL] section of the configuration file. Options for a specific tool should go in a section named for the tool. (E.g., options for ryscatterplot go in the section [ryscatterplot].) This allows a single file to contain configuration for many rytools commands.

Configuration option names and values are identical to the names and values of command-line options or the tool. Flags (options passed on the command line without values) may be enabled in a configuration file by supplying any value except false or 0. (For consistency, users may wish to use the values true or 1.)

IGNORING CONFIGURATION

If the user passes the --ignore-config option on the command-line or includes ignore_config in a configuration file, previous configuration information will be ignored.

EXAMPLES

Invoke ryscatterplot with some options:

ryscatterplot \
   --title="the title" \
   --width=800 \
   --height=200 \
   --marker-size=5 \
   --x-scale-dont-zero \
   --input-path="indata.txt" \
   --output-path="test.png"

The same options may be placed in the configuration file one-off.cfg, with the following format:

[ryscatterplot]
title="the title"
width=800
height=200
marker_size=5
x-scale-dont-zero=true
input_path=indata.txt
output_path=test.png

ryscatterplot may then be invoked with just a reference to the configuration file:

ryscatterplot --config-file=one-off.cfg

If the file is renamed to ~/.ryrc, the --config-file option is unnecessary:

ryscatterplot

However, options may still be overridden on the command line. This example uses otherindata.txt for input:

ryscatterplot --input-path=otherindata.txt

To use the width and height values in multiple tools, put them in the [ALL] section of the configuration file. If this is ~/ryrc:

[ALL]
width=800
height=200

[ryscatterplot]
title="the title"
marker_size=5
input_path=indata.txt
output_path=test.png

...other commands such as rytimeseries will use the --width and --height options specified in the configuration file, unless they are overridden on the command-line:

# output will be 800 x 200
rytimeseries --input-path=foo.txt --output=test2.png

Among other things, the system-wide value for --marker-size is 10 in this /etc/ryrc file:

[ryscatterplot]
marker_size=10
# ...other configuration...

This (and all other customization in /etc/ryrc) can be changed to the command defaults per-user by putting --ignore-config in the ~/.ryrc file:

[ryscatterplot]
ignore_config=1
# marker_size set back to default

Alternately, --ignore-config could be passed in on the command line to ensure that no unexpected configuration values are set:

ryscatterplot --ignore-config ...

To disable the behavior of --x-scale-dont-zero, omit it from the configuration file, or alternately, change the value to false or 0. (This can be used to temporarily disable features, or make it clear that the feature is meant to be disabled.):

[ryscatterplot]
title="the title"
width=800
height=200
marker_size=5
x-scale-dont-zero=false
input_path=indata.txt
output_path=test.png