Using metadata in texts

Metadata can be used in header/footer texts and comments. The general format of a metadata value in a text is %{name}, where name is the name of the metadata item.

It is also possible to conditionally substitute texts depending on the value of metadata items.

%{name|true-text|false-text}
%{name|true-text}

If metadata item name, the controling item, has a value, the true-text is substituted. If metadata item name has no value, the false-text is substituted. Both alternatives may be left out.

It is possible to test for specific values using the = (equality) operator:

%{name=value|true-text|false-text}

For even more power, true-text and false-text may contain other metadata subtitutions. The special %{} can be used to substitute the value of the controling item.

For example, if metadata item album has the value “Yes”, %{album|Album: %{}} expands to “Album: Yes”. If album did not have a value, the expansion would be empty.

All metadata items can have multiple values. To get multiple values, just issue multiple directives. For example:

{album: Cover Stories}
{album: Greatest Hits}

Now album has two values. When substituted, the values are concatenated using the configuration setting metadata.separator. To access the individual values, use album.1 for the first value, album.2 for the second value, and so on. Negative numbers count from the end, e.g. album.-1 will give the last value.

Metadata values passed on the command line (--meta) are always inserted first.

If necessary, the special meaning of the characters \, {, }, and | can be escaped by preceding it a \. Note that in the configuration files the strings are JSON strings and each \ must be doubled: "\\{" is an escaped {. "\\\\" is an escaped backslash.

Standard meta data

The ChordPro reference implementation provides additional meta data:

  • songindex: The index (serial number) of the song in the songbook.

  • page: The starting page number of the song.

  • pages: The number of pages of the song.

  • today: The current date in the format defined in the config file. See Dates and Times.

  • tuning: The tuning of the instrument. Usually "E2 A2 D3 G3 B3 E4".

  • instrument.type: The name of the instrument as set by instrument configs. Usually "guitar".

  • instrument: Short for instrument.type.

  • instrument.description: Set by instrument configs. Usually "Guitar, 6 strings, standard tuning".

  • user.name: The (login) name of the user running ChordPro. Initial value is derived from the environment.

  • user: Short for user.name.

  • user.fullname: The full name of the user running ChordPro. Initial value is derived from the environment, if possible.

The value of "instrument" and "user" can be used for directive selection