Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
MP3::Archive::Config(3User Contributed Perl DocumentatiMP3::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=['TRKNUMA -A ARTISTA -A ALBUMA -A TRACK\.EXT',
			'ARTISTA -A ALBUMA -A TRKNUMA -A TRACK\.EXT'];"

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

       01_A -_A Talk_A Talk_A -_A Spirit_A Of_A Eden_A -_A The_A Rainbow.mp3

       and the second one would	match eg:

       DJ_A Shadow_A -_A Endtroducing_A -_A 07_A -_A Stem-Long_A Stem.mp3

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

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

       Radiohead_A -_A Paranoid_A Android_A	(Live_A at_A the_A	10_A Spot).ogg

       "$format_write_album='TRKNUMA -A	ARTISTA	-A ALBUMA -A 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= ['TRKNUMA -A ARTISTA -A ALBUMA -A TRACK\.EXT',
	   'ARTISTA -A ALBUMA -A TRKNUMA -A TRACK\.EXT'];"

	   See above for details.

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

	   Default:

	   "$formats_track=['ARTISTA -A	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=	['ARTISTA -A ALBUM$','ARTIST\/ALBUM$'];"

	   This	would match

	   /Spiritualised^A -^A Lazer^A Guided^A Melodies/

	   or

	   /Spiritualised/Pure^A	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=	['ARTISTA -A 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_A -_A Long_A Stem,	so the file is called

	   07_A -_A DJ_A Shadow_A -_A Entroducing_A -_A Stem_A -_A Long_A	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= 'A	-A ';"

	   "$format_delimiter_track= 'A	-A ';"

       $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='TRKNUMA -A ARTISTA -A ALBUMA -A TRACK.EXT';"

	   "$format_write_track='ARTISTA -A TRACK.EXT';"

	   "$format_write_album_m3u='ARTISTA -A	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>

perl v5.32.0			  2003-12-06	       MP3::Archive::Config(3)

NAME | SYNOPSIS | DESCRIPTION | CONFIGURATION FILES | FORMATS | CONFIGURATION VARIABLES | METHODS | ENVIRONMENT | BUGS | SEE ALSO | AUTHOR

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=MP3::Archive::Config&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help