MP3::Archive::Config(3)

NAME
MP3::Archive::Config - Configuration handling for MP3::Archive

SYNOPSIS
    my $conf=MP3::Archive::Config->new([\%newopts]);
    my $opts=$conf->parseconfig($conf->readconfigfile($file);
    $conf->setopts($opts);
    my $value=$conf->get("conf_var_name");

DESCRIPTION
MP3::Archive::Config handles the configuration for MP3::Archive. By default, it uses /etc/mp3archiverc and ~/.mp3archiverc (or $ENV{MP3ARCHIVERC} if defined) for configuration (as well as reasonable defaults), but it can optionally use application-specific config files as well as or instead of the defaults.

The config file format is a fragment of perl which sets the configuration variables.

The user configuration file is automatically created the first time new is called. See "new" in METHODS for details.

CONFIGURATION FILES
What files are consulted depends on the options passed to new. See "new" in METHODS for more details. The order is as follows:

1 Internal defaults are set.
2 Unless $apprconly is set in new(), the default config files are loaded:
    2.1 /etc/mp3archiverc is loaded.
    2.2 If $ENV{MP3ARCHIVERC} is defined and exists, it is loaded.
    2.3 Else, ~/.mp3archiverc is loaded.
3 If $sysrc is set in new() it is loaded.
4 If $rcenv is set in new(), and $ENV{$rcenv} is defined and exists, it is loaded.
5 Else, if $rcfile is set in new() it is loaded.

If you use mp3lint(1), and want to share the configuration, then either create .mp3archiverc as a symbolic link to .mp3lintrc, with:

~$ ln -sf ~/.mp3lintrc ~/.mp3archiverc

or change .mp3archiverc so it just says:

require "$ENV{HOME}/.mp3lintrc";

which will effectively include .mp3lintrc into .mp3archiverc. For this to work, the last line of .mp3lintrc should be "1;", or at least evaluate to true

FORMATS
Formats are used to specify valid filenames and to specify where the artistname, albumname, etc are located.

Formats are regular expressions (see perlretut(1) and perlre(1)), but with ARTIST, ALBUM, TRACK, TRKNUM and EXT as placeholders for the artist, album, track name (song title), track number and extension respectively.

There are two types of formats.

Variables beginning with $formats_ are lists of permissible formats for parsing a filename, each of which are regular expressions (see perlretut(1) and perlre(1) for details). The formats are references to arrays, which essentially means you can have as many as you want, separated by commas, and they must start and end with [ and ] respectively. The individual formats should be quoted with single quotes (').

Variables beginning with $format_ are single formats that are ordinary strings, not regular expressions, and are used when creating filenames. They don't have [ and ] round them, but still should be quoted with single quotes ('), and there should be only one of them, not a list.

  Examples
These are from the default setup.

"$formats_album=['TRKNUM - ARTIST - ALBUM - TRACK\.EXT',
              'ARTIST - ALBUM - TRKNUM - TRACK\.EXT'];"

This defines two acceptable formats for album tracks. The first one would match eg:

01 - Talk Talk - Spirit Of Eden - The Rainbow.mp3

and the second one would match eg:

DJ Shadow - Endtroducing - 07 - Stem-Long Stem.mp3

"$formats_track=['ARTIST - TRACK\.EXT'];"

This defines one acceptable format for non-album tracks. This would match eg:

Radiohead - Paranoid Android (Live at the 10 Spot).ogg

"$format_write_album='TRKNUM - ARTIST - ALBUM - TRACK.EXT';"

This can be though of as the reverse of $formats_album. It defines the format to be used when creating a file, so in this example, given TRKNUM "02", ARTIST "Dead Can Dance", ALBUM "Aion", TRACK "Saltarello", and EXT "wav", it would produce the filename:

 02 - Dead Can Dance - Aion - Saltarello.wav

CONFIGURATION VARIABLES

$formats_album
    This specifies acceptable formats for album tracks.

    Default:

    "$formats_album= ['TRKNUM - ARTIST - ALBUM - TRACK\.EXT', 'ARTIST - ALBUM - TRKNUM - TRACK\.EXT'];"

    See above for details.

$formats_track
    This specifies acceptable formats for non-album tracks.

    Default:

    "$formats_track=['ARTIST - TRACK\.EXT'];"

    See above for details.

$formats_album_dir
    This specifies how to extract info from the directory of an album track.

    Default:

    "$formats_album_dir= ['ARTIST - ALBUM$','ARTIST\/ALBUM$'];"

    This would match

    /Spiritualised - Lazer Guided Melodies/

    or

    /Spiritualised/Pure Phase/

    both at the end of the pathname.

$formats_track_dir
    This specifies how to extract info from the directory of a non-album track.

    Default:

    "$formats_track_dir= ['ARTIST$'];"

    This specifies the last portion of the pathname is the artist.

$formats_album_m3u, $formats_track_m3u
    Specifies the format of m3u playlist filenames for album and non-album tracks.

    Default:

    "$formats_album_m3u= ['ARTIST - ALBUM\.EXT'];"

    "$formats_track_m3u = ['ARTIST\.EXT'];"

$format_default
    How to treat tracks that are not in $paths_album or $paths_track. This can be album, track, or anything else, which means don't test the files at all (eg skip).

    Default:

    $format_default="skip";

$format_delimiter_album, $format_delimiter_track
    These specify the delimiters for album and non-album tracks. This allows extra checks, eg to make sure there are the right number of fields (eg, if the delimiter is `-' and you have a track named Stem - Long Stem, so the file is called

    07 - DJ Shadow - Entroducing - Stem - Long Stem.mp3

    then the extra dash will cause you problems, but specifying a delimiter will allow mp3lint to determine there are too many fields.

    Default:

    "$format_delimiter_album= ' - ';"

    "$format_delimiter_track= ' - ';"

$paths_album, $paths_track
    These are used to determine from its pathname whether a file should be treated as part of an album. They are regular expressions, so the same warnings about quoting apply as to formats. This also means that they are substring matches, so the defaults below match any pathname that contains a component called albums or tracks. Although there is only one path each in the default, they can be lists of multiple paths (or portions of paths) to match.

    Default:

    "$paths_album=['album'];"

    "$paths_track=['track'];"

    This means that any pathname containing /albums or /tracks will be treated accordingly (eg /music/groovy-albums/).

$archive_root
    $archive_root is currently only used to define the $path_write_* variables (below), but its use may be expanded in the future.

    Default:

    "$archive_root="$ENV{HOME}/music";"

    On any sane unix system, $ENV{HOME} expands to your home directory.

$path_write_album, $path_write_track
    $path_write_album and $path_write_track are used to determine the canonical pathname for files, for tools like movemusic(1).

    The defaults are defined relative to $archive_root (see above).

    Defaults:

    "$path_write_album="$archive_root/cut/albums/";" "$path_write_track="$archive_root/tracks/";"

$format_write_album, $format_write_track, $format_write_album_m3u, $format_write_track_m3u, $format_write_album_dir, $format_write_track_dir,
    These variables are analogous to the $formats_* variables above, but they are used for constructing filenames rather than parsing them to extract information. They are not regular expressions, they are ordinary strings, and there is only one of each rather than a list (array). The same magic variables ("TRKNUM", "ARTIST", "ALBUM", "TRACK") are used and are replaced with the actual data.

    Defaults:

    "$format_write_album='TRKNUM - ARTIST - ALBUM - TRACK.EXT';"

    "$format_write_track='ARTIST - TRACK.EXT';"

    "$format_write_album_m3u='ARTIST - ALBUM.EXT';"

    "$format_write_track_m3u='ARTIST.EXT';"

    "$format_write_album_dir="/ARTIST/ALBUM/";"

    "$format_write_track_dir="/ARTIST/";"

METHODS

  new([$optshashref]);
Creates an instance of MP3::Archive::Config

Takes an optional reference to a hash of options:

defaults
    A scalar containing perl code for additional default options.

rcfile
    An additional application-specific and user-specific config file.

rcenv
    The name of an environment variable, which, if defined and exists, is used instead of "rcfile".

sysrc
    An additional system-wide (ie in /etc or /usr/local/etc) application-specific config file.

apprconly
    If non-zero, skips /etc/mp3archiverc and $HOME/.mp3archiverc, and just uses the application-specific config files defined above.

If it doesn't exist, the user config file is created, containing the defaults. This file is either $ENV{$rcenv}, $rcfile, or "~/.mp3archiverc", depending what is defined.

  setopts($optshashref)
Sets options. Takes a hashref of options to set. Preserves any options not mentioned.

  get($item)
Returns the value of the configuration variable $item, or undef if it is not defined.

  readconfigfile($file)
Reads in $file and returns it as one long string. Returns undef on failure.

Can be called as a static method (eg "$conf=MP3::Archive::Config::readconfigfile($file)").

  parseconfig($code)
Parses the perl code in $code and returns a reference to a hash containing the variables defined therein.

If there is a problem with the perl in $code, it sets $self->{parseerror} to the error message, and returns undef.

parseconfig works by eval-ing the perl code within the context of a package with an empty symbol table, then reading the contents of that symbol table.

  writeconfigfile($file,$config)
Writes the config data $config to $file.

$config is expected to be a string of perl code.

Can be called as a static method (eg "MP3::Archive::Config::writeconfigfile($file,$config)").

ENVIRONMENT

$MP3ARCHIVERC
    If set, uses this instead of $HOME/.mp3archiverc

$HOME
    Used to find .mp3archiverc

BUGS
None known. Please report any found to ianb@nessie.mcc.ac.uk

I am especially interested in how well the code for filename formats works for other people's filenames.

SEE ALSO
MP3::Archive(3), MP3::Archive::Format(3), mp3lint(1), mp3-archive-tools(1)

AUTHOR
Ian Beckwith <ianb@nessie.mcc.ac.uk>