# Configuration: Overview
The way the output is formatted and some behavioural aspects of the reference implementation are configurable via configuration files.
ChordPro understands two variants (formats) of configuration files: PRP and JSON. If both variants of the same config are available, the PRP variant takes precedence.
PRP files have
filenames with extension .prp
and are based on the Java properties
files, but with structure
and many more extensions. They require much less typing and are much
less prone to errors than JSON.
JSON files have filenames with extension
.json
and can be created and modified using
any convenient text editor. There are also several JSON editors
available, often in the form of web services. For schema-based
editors, the schema can be downloaded here.
As an example, compare the variants of the following identical definitions:
// JSON
"diagrams" : {
"auto" : false,
"show" : "all",
"sorted" : false,
},
"tuning" : [ "E2", "A2", "D3", "G3", "B3", "E4" ],
# Properties
diagrams.auto = false
diagrams.show = all
diagrams.sorted = false
tuning = [ E2 A2 D3 G3 B3 E4 ]
# Properties, structured
diagrams {
auto = false
show = all
sorted = false
}
tuning = [ E2 A2 D3 G3 B3 E4 ]
All forms of config definitions will be used in the documentation.
# Standard configuration files
ChordPro tries to read several configuration files and combines their contents to form the actual configuration. ChordPro always starts with the built-in default configuration. Then all configuration files are processed in order, and their contents are merged into the existing configuration. So all settings accumulate. Configuration files do not need to be complete (i.e., contain all settings), it is often sufficient to only include the settings that must be changed. See for example the preset configurations modern1 and nashville, that only contains a few changes.
In the examples below the symbol ~
denotes the user’s home directory. Windows users may need to change the forward slashes to backward slashes.
-
On systems that support it, a system-wide configuration file is read. On Linux systems, this is
/etc/chordpro.json
. -
A user specific configuration file is read from either:
$XDG_CONFIG_HOME/chordpro/chordpro.json
or:
~/.config/chordpro/chordpro.json
~/.chordpro/chordpro.json
Note that if you have a~/.config
directory ChordPro expects the configs to be there and the latter alternative will be ignored. -
A project specific configuration file is read from the current directory, either:
chordpro.json
.chordpro.json
Instead of a project specific configuration file you can specify arbitrary configuration files.
- In the GUI, select
Preferences...
from theEdit
menu.
Using the configuration dropdown list, chooseCustom
.
Click...
for a file dialog to choose the desired configuration file. - On the command line, pass the name of the configuration file with
--config
, for example--config=myconfig.json
.
- In the GUI, select
-
A song specific configuration file is read if it exists. The name of the configuration file is the same as the song file name, with the extension replaced by
prp
orjson
(in that order).Note that the scope of the song specific configuration file is the song only. Every song will start with an initial config that results from steps 1 through 3, and then its song specific configuration file if it exists.
Important A song specific configuration file may not contain an
"include"
or"tuning"
item.
# How config files are combined
The config files are processed in order, and their contents are merged. In general, a config setting from a later file replaces the value from previous files. There are a few exceptions: instrument definitions, hashes and arrays.
# Merging instrument definitions
Instrument definitions, in particular the settings "tuning"
, "notes"
and "chords"
, are handled differently. These are processed immediately after parsing a configuration file and then the setting is removed from the configuration.
For example, assume "chords_italian.json"
defines a number of chords using italian (latin) note names and "chords_german.json"
defines some chords using german note names. Then the following sequence of configuration files will work as expected:
notes:latin (built-in, enable latin note names)
chords_italian.json (defines chords with latin note names)
notes:german (built-in, enable german note names)
chords_german.json (defines chords with german note names)
# Merging hash valued items
Hashes are merged by key. For example, assume:
{ "settings" : { "titles" : "center", "columns" : 1 } }
when merged with:
{ "settings" : { "columns" : 2 } }
the result will be:
{ "settings" : { "titles" : "center", "columns" : 2 } }
# Merging array values items
Arrays are either overwritten or appended/prepended. This is
controlled by the first element of the new array. If this first
element is the string "append"
then the new contents are appended, if it
is "prepend"
then the new contents are prepended. Otherwise the new
contents replace the existing contents.
For example:
{ "keys" : [ "title", "subtitle" ] }
when merged with:
{ "keys" : [ "composer" ] }
will result in:
{ "keys" : [ "composer" ] }
If, however, this was merged with:
{ "keys" : [ "append", "composer" ] }
the result would have been:
{ "keys" : [ "title", "subtitle", "composer" ] }
Likewise, use "prepend"
to prepend items.