.\" Automatically generated by Pod::Man 2.1801 (Pod::Simple 3.05)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "arename 1"
.TH arename 1 "2008-12-15" "perl v5.10.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
arename \- automatically rename audio files by tagging information
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
arename [\s-1OPTION\s0(s)] \s-1FILE\s0(s)...
.SH "OPTIONS AND ARGUMENTS"
.IX Header "OPTIONS AND ARGUMENTS"
.IP "\fB\-D\fR" 8
.IX Item "-D"
Enable debugging output. This is likely to be very noisy. You probably want
to use the \fI\-v\fR option (setting: \fIverbose\fR) in addition to this.
.IP "\fB\-d\fR" 8
.IX Item "-d"
Go into dryrun mode. This means, that no action will be taken. \fBarename\fR
will print what it would do, if called without \fI\-d\fR.
.IP "\fB\-f\fR" 8
.IX Item "-f"
Overwrite files if needed.
.IP "\fB\-h\fR" 8
.IX Item "-h"
Display a short help text.
.IP "\fB\-H\fR" 8
.IX Item "-H"
Do not make use of hooks of any sort (neither global nor local ones).
.IP "\fB\-L\fR" 8
.IX Item "-L"
List the current configuration in the actual configuration format.
.IP "\fB\-l\fR" 8
.IX Item "-l"
Read a local config file (./.arename.local). Overwrites the \fBuselocalrc\fR
configuration setting.
.IP "\fB\-M\fR" 8
.IX Item "-M"
Prints the version of the arename script and the version of the Perl module,
that contains most of the code. These versions should be the same. If not,
that would indicate a possibly broken installation.
.IP "\fB\-N\fR" 8
.IX Item "-N"
Do \fInot\fR use configuration profiles (see below).
Overwrites the \fBuseprofiles\fR setting.
.IP "\fB\-q\fR" 8
.IX Item "-q"
Make the output way more quiet, when processing files.
.Sp
This option conflicts with the verbose option.
.IP "\fB\-Q\fR" 8
.IX Item "-Q"
Be even more quiet (this option will suppress, if a file is skipped.
Except for files, that are skipped because they would overwrite something).
.Sp
This option implies '\-q'.
.IP "\fB\-S\fR" 8
.IX Item "-S"
Print a list of profile names defined in the active configuration.
(This is primarily used by the zsh completion for the \fI\-P\fR option.)
.IP "\fB\-s\fR" 8
.IX Item "-s"
Read filenames from stdin after processing files given on the command line.
It reads one file name per line, which means that file names containing
newlines are not supported.
.IP "\fB\-V\fR" 8
.IX Item "-V"
Display version information.
.IP "\fB\-v\fR" 8
.IX Item "-v"
Enable verbose output.
.IP "\fB\-c\fR <file>" 8
.IX Item "-c <file>"
Read \fIfile\fR instead of ~/.arenamerc.
.IP "\fB\-C\fR <file>" 8
.IX Item "-C <file>"
Read \fIfile\fR \fBafter\fR ~/.arenamerc and \fBbefore\fR ./.arename.local.
.IP "\fB\-P\fR <profile(s),...>" 8
.IX Item "-P <profile(s),...>"
Define a list of one or more profiles to use forcibly, no matter if they
would be activated normally or not.
.IP "\fB\-p\fR <prefix>" 8
.IX Item "-p <prefix>"
Define a prefix for destination files.
.IP "\fB\-T\fR <template>" 8
.IX Item "-T <template>"
Define a template, that will be used for files that contain a compilation
tag.
.IP "\fB\-t\fR <template>" 8
.IX Item "-t <template>"
Define a generic template (for all files that do \fInot\fR contain a
compilation tag).
.IP "\fI\s-1FILE\s0(s)...\fR" 8
.IX Item "FILE(s)..."
Input files, that are subject for renaming.
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBarename\fR is a tool that is able to rename audio files by looking at
a file's tagging information. It uses this information to assemble a
consistent destination file name. The user can define the format of the
destination filename by the use of template strings.
.PP
Templates can be defined in the \*(L"Configuration files\*(R", by the
\&\fItemplate\fR and \fIcomp_template\fR settings (See \*(L"\s-1SETTINGS\s0\*(R" below).
.PP
By default, \fBarename\fR will refuse to overwrite destination files,
if the file in question already exists. You can force overwriting by
supplying the \fB\-f\fR option.
.PP
In order to see what would happen instead of actually modifying files, you
can use the \fB\-d\fR option. This way you can avoid problems, that would
occur if the situation (e.g. the information in the files or your
configuration) is not exactly as you expected it.
.SS "Supported file formats"
.IX Subsection "Supported file formats"
\&\fBarename\fR currently supports three widely used audio formats, namely
\&\s-1MPEG\s0 Layer3, ogg vorbis and flac (Free Lossless Audio Codec). The format,
that \fBarename\fR will assume for each input file is determined by the file's
filename-extension (\fI.mp3\fR vs. \fI.ogg\fR vs. \fI.flac\fR).
The extension check is case-insensitive.
.PP
\&\fI.mp3\fR files may contain different types of tags, namely id3v1 and id3v2.
Id3v1 is a very limited format. Therefore \fBarename\fR will use the id3v2 tag
when it finds it. Which means you should make sure that the id3v2 tag has
all the information you need, if you use files with both id3v1 and id3v2
tags.
.SS "Inputting a *lot* of files"
.IX Subsection "Inputting a *lot* of files"
\&\fBarename\fR can be used to keep the file names of whole audio archives in
sync. However, that means that you will have to tell the script the
location of many files, thousands maybe.
.PP
In order to do that you will face the problem, that on most UNIX-like
systems, the length of the argument list for external programs is limited
(recent Linux versions, as an exception, do not have that limitation
anymore).
.PP
So, even if your shell can do recursive globbing like ksh or zsh, this will
most likely get you into trouble (for more than just a few files):
.PP
.Vb 1
\&  % arename \-d **/*.mp3
.Ve
.PP
There are several ways to overcome that limitation, of course.
.PP
The first solution is to use \fBfind\fR in connection with \fBarename\fR's \fI\-s\fR
option:
.PP
.Vb 1
\&  % find . \-name "*.mp3" \-print | arename \-d \-s
.Ve
.PP
This will break for file names that contain newlines, because \fI\-s\fR will
read one file name per line from the standard input stream.
.PP
Another way of using \fBfind\fR to deal with this problem is to use find's
\&\fI\-exec\fR option:
.PP
.Vb 1
\&  % find . \-name "*.mp3" \-exec arename \-d \*(Aq{}\*(Aq \*(Aq+\*(Aq
.Ve
.PP
This will work for every possible file name. No matter if it has spaces
or newlines in it. The \fI+\fR at the end of the call causes find to call
the external program (\fBarename\fR in this case) with as many arguments as
possible, without exceeding the limit. This requires a POSIXly correct
find. \s-1GNU\s0 find for instance, did not support the \fI+\fR way for a long time.
If you are stuck with an old version, you can exchange the \fI+\fR with a
\&\fI;\fR (note, that a semicolon \fBmust\fR be quoted in any case), or use \s-1GNU\s0's
xargs tool instead.
.PP
A last solution for zsh users would be zargs (which requires
\&'autoload zargs' in your zsh configuration):
.PP
.Vb 1
\&  % zargs \-\- **/*.mp3 \-\- arename \-d
.Ve
.SH "GENERAL USAGE"
.IX Header "GENERAL USAGE"
When you are first confronted with \fBarename\fR and you try to get started
with the documentation you might argue, that a 1000+ lines manual, that
is not filled with too many examples is hardly starter-friendly.
.PP
Therefore, this section was introduced to give you the bare minimum of
information in order to use the program without going through too much
fuzz.
.PP
If you are really afraid of documentation, you could of course just read
the output of the \fI\-h\fR option and see which options to provide in order
to get what you want. Then again, you will soon be pissed by the weird
default values \fBarename\fR uses.
.PP
You will probably want other templates. After all, the ability to have
these expanded strings is one of the points to use \fBarename\fR in the first
place. They are described in the \s-1TEMPLATE\s0 section; and reading that
section is the minimum effort you will want to go through.
.PP
After that, you can open the file \fI~/.arenamerc\fR in your favourite
text editor and resemble the following text (and presumably change the
few values in there to your liking):
.PP
.Vb 3
\&  # as soon as you get pissed by too much output, while arename is
\&  # running, uncomment the following line:
\&  #quiet
\&
\&  # now you certainly want your own templates, so define them here
\&  # one for your normal files
\&  template &artist \- &album \- &tracknumber. &tracktitle
\&
\&  # and another one for files that orignate from compilations
\&  comp_template va \- &album \- &tracknumber. &artist \- &tracktitle
.Ve
.PP
If you want more automation or more customization, you will not get
around reading the manual below. If you need to solve special
problems, the \*(L"\s-1HOOKS\s0\*(R" part even further below is for you.
.SH "FILES"
.IX Header "FILES"
\&\fBarename\fR's behaviour can be altered by a number of files it reads when
starting up.
.PP
Normal configuration tasks are done in (how convenient)
\&\*(L"Configuration files\*(R", described below.
.PP
If you need more control, or want to solve special problems you are having,
you can do so by supplying Perl code in \*(L"Hook definition files\*(R".
.PP
\&\fBarename\fR can be configured to read configuration files as well as hook
definition files from the current working directory. This feature is
disabled by default, because they can be a security issue on multiuser
systems.
.PP
There are no such things as system wide configuration files in \fBarename\fR.
.PP
For all setup files \fBarename\fR tries to find (except for the local ones)
three different locations are tried. If the directory \fI~/etc/arename/\fR
exists, \fBall\fR files are expected to be in there. If that directory does
not exist, \fI~/.arename/\fR is tried instead. If that one could not be found,
either, \fBarename\fR will try to find the file it is looking for directly in
the user's home directory.
.PP
The first setup directory we find always wins. \fBarename\fR does not consider
more than one setup directory.
.PP
If, for example, \fI~/etc/arename/\fR exists and we are looking for the normal
configuration file (see below), but
\&\fI~/etc/arename/rc\fR could not be found, we do \fBnot\fR try to find it in
\&\fI~/.arename/\fR or the user's home directory.
.SS "Configuration files"
.IX Subsection "Configuration files"
\&\fBarename\fR uses up to three configuration files. As for most programs,
the script will try to read a configuration file, that is located in the
user's \fIhome directory\fR. In addition to that, it will try to load \fIlocal\fR
configuration files, if it finds appropriately named files in the
\&\fIcurrent directory\fR (and the \fIuselocalrc\fR feature is enabled):
.IP "\fB~/etc/arename/rc\fR" 8
.IX Item "~/etc/arename/rc"
.PD 0
.IP "\fB~/.arename/rc\fR" 8
.IX Item "~/.arename/rc"
.IP "\fB~/.arenamerc\fR" 8
.IX Item "~/.arenamerc"
.PD
per-user normal configuration file.
.IP "\fB./.arename.local\fR" 8
.IX Item "./.arename.local"
per-directory local configuration file (only read if \fIuselocalrc\fR is set
or the \fI\-l\fR option is given on the command line).
.PP
The per-user normal configuration file can be substituted by another file,
if specified via the \fI\-c\fR option.
.PP
Last but not least, you can specify an intermediate configuration file,
that is read in between the normal and the per-directory file, via the
\&\fI\-C\fR option.
.PP
\fIFile format\fR
.IX Subsection "File format"
.PP
The format of the aforementioned files is pretty simple.
It is parsed line by line. Empty lines, lines only containing whitespace
and lines, whose first non whitespace character is a hash character (\fI#\fR)
are ignored.
.PP
There are two different types of settings: boolean and scalar settings.
.PP
Booleans can be set like this:
.PP
.Vb 1
\&  <setting> [true|false]
.Ve
.PP
If the value is omitted, \fItrue\fR is assumed. \fItrue\fR and \fIfalse\fR are
recognized case insensitively, and a value of \fI1\fR is synonymous to \fItrue\fR,
as is \fI0\fR to \fIfalse\fR.
.PP
Scalar settings are done very in a very similar way:
.PP
.Vb 1
\&  <setting> <value>
.Ve
.PP
If the value is omitted, string values will be set to an empty string and
numeric values will be set to zero.
.PP
In both cases, setting and value are separated by one or more whitespace
characters. The value will be the rest of the line (all of it, including
trailing whitespace).
.PP
If the value part starts with a backslash, that backslash is left out of the
value. That makes it possible to define templates with leading whitespace.
.PP
If a line contains only a string within square brackets, that string is the
start of a section. Section names are matches for starts of file names.
That means, the settings following such a section definition will only
applied for input file names that start with the same string as the section
name. Where file name means the string, handed over to \fBarename\fR. The string
\&\fI~/\fR at the beginning of a section name is expanded to the user's home
directory.
.PP
You may start as many sections as you would like.
.PP
A section named \fI/foo/bar/\fR supersedes a section named \fI/foo/\fR for a file
named \fI/foo/bar/baz.ogg\fR. So, the longest match wins.
.PP
Another possible configuration file entry is a user variable, which is
defined via the \fBset\fR command. These settings are very different from the
normal settings. Therefore, they are defined in a different way. That way
is described in the \*(L"User defined variables\*(R" subsection below.
.PP
Last but not least, you may define so called
profiles, see below.
.PP
\fIConfiguration profiles\fR
.IX Subsection "Configuration profiles"
.PP
Profiles are a very flexible and context sensitive way of using multiple
configuration files at once. With profiles, local configuration files (and
local hook definition files) can be substituted in a secure way; even on
multi-user systems.
.PP
Reading local files (configs and hook-files) is still supported for backwards
compatibility (see \fIuselocalrc\fR and \fIuselocalhooks\fR options).
However, you are strongly encouraged to use profiles whenever you can.
.PP
As normal configuration files and global hook-files, profile-related files are
searched in one of the setup directories described above. They are using the
following naming conventions:
.IP "\fB~/etc/arename/profile.PROFILENAME\fR" 8
.IX Item "~/etc/arename/profile.PROFILENAME"
.PD 0
.IP "\fB~/.arename/profile.PROFILENAME\fR" 8
.IX Item "~/.arename/profile.PROFILENAME"
.IP "\fB~/.arename.PROFILENAME\fR" 8
.IX Item "~/.arename.PROFILENAME"
.PD
Profile related configuration files; read if \fI\s-1PROFILENAME\s0\fR is active.
.Sp
They are read after a intermediate config file defined by \fI\-C\fR and
a local config file (if enabled).
.IP "\fB~/etc/arename/profile.PROFILENAME.hooks\fR" 8
.IX Item "~/etc/arename/profile.PROFILENAME.hooks"
.PD 0
.IP "\fB~/.arename/profile.PROFILENAME.hooks\fR" 8
.IX Item "~/.arename/profile.PROFILENAME.hooks"
.IP "\fB~/.arename.PROFILENAME.hooks\fR" 8
.IX Item "~/.arename.PROFILENAME.hooks"
.PD
Profile related \*(L"Hook definition files\*(R" (see below for details); read if
\&\fI\s-1PROFILENAME\s0\fR is active.
.Sp
These files are read, between global and local hook-definition files.
.PP
In order to define profiles, you need to use the \fIprofile\fR keyword:
.PP
.Vb 1
\&  profile <name> <pattern>
.Ve
.PP
Where \fIname\fR is a string, that is used in the place of \fB\s-1PROFILENAME\s0\fR
in the file location lists above. This name may contain of the following
character range: \fBa\-zA\-Z0\-9_\-\fR
.PP
\&\fIpattern\fR is part of a Perl regex pattern (see \fIperlreref\fR and \fIperlretut\fR
manpages). The pattern will be anchored at the beginning and is open at
the end, somewhat like this pseudocode:
.PP
.Vb 1
\&  if ($working_directory =~ m/^PATTERN/) { use_this_profile(); }
.Ve
.PP
Example:
.PP
.Vb 1
\&  profile music /mnt/audio/music/
.Ve
.PP
Will cause the profile \fImusic\fR to be active when the working directory is
\&\fI/mnt/audio/music/\fR or below. So, do not be afraid. You can use profiles
without understanding regular expressions.
.PP
Like many other values in \fBarename\fR's configuration, a leading backslash of
a pattern will be ignored to allow patterns, that start in white spaces.
Furthermore, if a pattern starts in \fI~/\fR, that string is replaced by the
user's home directory.
.PP
You may add as many patterns to a profile name, as you want:
.PP
.Vb 2
\&  profile music /mnt/audio/music/
\&  profile music /mnt/extern/audio/music/
.Ve
.PP
The above activates the \fImusic\fR profile in \fI/mnt/audio/music/\fR and
\&\fI/mnt/extern/audio/music/\fR, for example.
.PP
More than one profile can be activated at the same time. If that is true,
the according configuration files are read in lexical order.
.PP
\fISections versus Profiles\fR
.IX Subsection "Sections versus Profiles"
.PP
Since \fBarename\fR provides two context sensitive configuration facilities,
you might ask yourself when to use which, when you are confronted with both
for the first time.
.PP
First of all, \fIprofiles\fR are more powerful. They may even introduce new
hooks for \fBarename\fR to use. But that is not the conceptual difference
between the two.
.PP
\&\fIsections\fR are sets of configuration settings, that are considered for
\&\fBeach and every\fR input file and they are \fBonly\fR enabled for input files,
whose name matches the section name.
.PP
\&\fIprofiles\fR on the other hand are sets of configuration and hook-definition
files, whose inclusion in the current \fBarename\fR run is decided at the
\&\fBbeginning\fR of the program's execution (not for every input file) \- namely,
if the name of the current working directory matches one of the profile's
patterns.
.PP
That means, that if you need to introduce slight configuration changes based
on an \fBinput file's name\fR you want to use a \fIsection\fR.
.PP
If you need to make broader configuration changes, considering the name of
the \fBcurrent working directory\fR, \fIprofiles\fR are the way to go.
.PP
Of course, profile configuration files may introduce new sections, too.
.SS "Configuration file example"
.IX Subsection "Configuration file example"
.Vb 2
\&  # switch on verbosity
\&  verbose
\&
\&  # canonicalize file names before working with them
\&  canonicalize
\&
\&  # the author is crazy! use a sane template by default. :\-)
\&  template &artist \- &album (&year) \- &tracknumber. &tracktitle
\&
\&  # activate the \*(Aqmusic\*(Aq profile below /mnt/audio/music/.
\&  profile music /mnt/audio/music/
\&
\&  # force files from /foo/bar/ to stay below that directory
\&  [/foo/bar/]
\&  prefix /foo/bar
.Ve
.SS "Hook definition files"
.IX Subsection "Hook definition files"
.IP "\fB~/etc/arename/hooks\fR" 4
.IX Item "~/etc/arename/hooks"
.PD 0
.IP "\fB~/.arename/hooks\fR" 4
.IX Item "~/.arename/hooks"
.IP "\fB~/.arename.hooks\fR" 4
.IX Item "~/.arename.hooks"
.PD
Defines global hooks, that are in effect in every directory if the \fIusehooks\fR
option is set to \fBtrue\fR.
.IP "\fB./.arename.hooks.local\fR" 4
.IX Item "./.arename.hooks.local"
This allows you to define special hooks, that will only be applied for processes
that run in the directory the local file is found (and if the \fIuselocalhooks\fR
option is set to \fBtrue\fR).
.PP
For details about hooks in \fBarename\fR, see \*(L"\s-1HOOKS\s0\*(R" below.
.SH "SETTINGS"
.IX Header "SETTINGS"
The following settings are supported in all configuration files.
.PP
Not all of them are usable in \fIsections\fR. The ones you can use in
sections are: All \fIdefault_*\fR options, \fIforce\fR, \fIprefix\fR, \fIsepreplace\fR,
\&\fItnpad\fR, \fIcomp_template\fR and \fItemplate\fR.
.IP "\fBcanonicalize\fR" 8
.IX Item "canonicalize"
If set, a given file name will be transformed to its cleaned up absolute
path. You may want to set this, if you are using sections in the
configuration. If you do not use sections, all this will give you is a
performance penalty. (default value: \fIfalse\fR)
.IP "\fBcheckprofilerc\fR" 8
.IX Item "checkprofilerc"
If set, \fBarename\fR will check if there is a configuration file for a
profile as soon as it reads a profile definition in the setup and \fBonly\fR
consider the profile if it found the according config file. Profiles
without config file will cause a warning if this is set, which may cause the
\&\fIdryrun\fR option to be set if the \fIwarningsautodryrun\fR option is set.
.Sp
If unset, profiles without config file will not cause warnings. You will
see messages about missing configuration files, if a profile without config
file is active. (default: \fItrue\fR)
.IP "\fBcomp_template\fR" 8
.IX Item "comp_template"
Defines a template to use with files that provide a compilation tag
(for 'various artist' CDs, for example). This setting can still be
overwritten by the \fB\-T\fR command line option. (default value:
\&\fIva/&album/&tracknumber \- &artist \- &tracktitle\fR)
.IP "\fBdebug\fR" 8
.IX Item "debug"
Enable debugging by default. This is probably only useful, if you want
debugging to be enabled as soon as possible, when you are trying to chase
bugs. Do not set this for normal execution. (default value: \fIfalse\fR)
.IP "\fBdefault_*\fR" 8
.IX Item "default_*"
default_artist, default_album, default_compilation, default_genre,
default_tracknumber, default_tracktitle, default_year
.Sp
Defines a default value, for the given tag in files, that lack this
information. (default value: \fIundefined\fR)
.IP "\fBhookerrfatal\fR" 8
.IX Item "hookerrfatal"
If this is set to false, arename will continue execution even if
reading, parsing or compiling a hooks file failed. (default value:
\&\fIfalse\fR)
.IP "\fBprefix\fR" 8
.IX Item "prefix"
Defines a prefix for destination files. Setting this to '/foo/bar' results
in destination files named '/foo/bar/Expanded Template.ogg'
.Sp
This setting can still be overwritten by the \fB\-p\fR command line option.
(default value: \fI.\fR)
.IP "\fBquiet\fR" 8
.IX Item "quiet"
Switches on quietness. This makes the output a lot more compact. (default
value: \fIoff\fR)
.IP "\fBquiet_skip\fR" 8
.IX Item "quiet_skip"
Be quiet about skips. Even if \fIquiet\fR is set, \fBarename\fR will
report files it does not process, because renaming would not change their
names. With this option, these skipped files will not be reported. This
implicitly sets 'quiet'. (default value: \fIoff\fR)
.IP "\fBsepreplace\fR" 8
.IX Item "sepreplace"
Tagging information strings may contain slashes, which is a pretty bad
idea on most file systems. Therefore, you can define a string, that replaces
slashes with the value of this setting. (default value: \fI_\fR)
.IP "\fBtemplate\fR" 8
.IX Item "template"
Defines a template to use with files that do not provide a compilation tag
(or where the compilation tag and the artist tag are exactly the same).
This setting can be overwritten by the \fB\-T\fR command line option.
(default value: \fI&artist[1]/&artist/&album/&tracknumber \- &tracktitle\fR)
.IP "\fBtnpad\fR" 8
.IX Item "tnpad"
This defines the width, to which the track number field is padded with zeros
on the left. Setting this to zero disables padding. (default value: \fI2\fR)
.IP "\fBusehooks\fR" 8
.IX Item "usehooks"
If set to true, use hooks defined in \fB~/.arename.hooks\fR.
(default value: \fItrue\fR)
.IP "\fBuselocalhooks\fR" 8
.IX Item "uselocalhooks"
If set to true, use hooks defined in \fB./.arename.hooks.local\fR.
(default value: \fIfalse\fR)
.IP "\fBuselocalrc\fR" 8
.IX Item "uselocalrc"
If set to true, read a local configuration file (\fB./.arename.local\fR),
if it exists. (default value: \fIfalse\fR)
.IP "\fBuseprofiles\fR" 8
.IX Item "useprofiles"
If set to true, configuration profiles will be used. If false, they are not.
(default value: \fItrue\fR)
.IP "\fBverbose\fR" 8
.IX Item "verbose"
Switches on verbosity by default. This makes \fBarename\fR's output really
noisy. This is probably only useful for debugging or if you are really
interested in what is going on. (default value: \fIfalse\fR)
.IP "\fBwarningsautodryrun\fR" 8
.IX Item "warningsautodryrun"
Switches on the \fIdryrun\fR option (if not enabled already), as soon as the
configuration file parser encounters a non-fatal warnings. This option was
introduced to avoid destructive behaviour due to incorrect lines in any
of the configuration files. (default value: \fItrue\fR)
.SS "User defined variables"
.IX Subsection "User defined variables"
You can use the \fBset\fR command in arenamerc files. This way the user can
define his own variables. The namespace is seperate from \fBarename\fR's
normal settings. (That means, you cannot, for example,  overwrite the
internal \fItemplate\fR variable with this command.)
.PP
The synax is quite simple (and \fBdifferent\fR to normal settings on purpose!):
.PP
\&\fBset\fR \fIvarname\fR = \fIvalue\fR
.PP
There may be an arbitrary amount of whitespace around the equal sign
(including no whitespace at all). If you want to have a value that
starts in a whitespace character, you may start the value with a
backslash character (just like with the normal settings, a leading
backslash is always ignored).
.PP
User defined variables are useful to make hooks configurable (see
\&\*(L"\s-1HOOKS\s0\*(R" below).
.SH "TEMPLATE FORMAT"
.IX Header "TEMPLATE FORMAT"
\&\fBarename\fR's templates are quite simple, yet powerful.
.PP
At simplest, a template is just a fixed character string. However, that would
not be exactly useful. So, the script is able to expand certain expressions
with information gathered from the file's tagging information.
.PP
The expressions can have two slightly different forms:
.IP "\fB&\fR\fIidentifier\fR" 8
.IX Item "&identifier"
The simple form.
.IP "\fB&\fR\fIidentifier\fR\fB[\fR\fIlength\fR\fB]\fR" 8
.IX Item "&identifier[length]"
The \*(L"complex\*(R" form. The \fIlength\fR argument in square brackets defines the
maximum length, to which the expression should be expanded.
.Sp
That means, if the Artist of a file reveals to be '\fIFrank Zappa\fR', then
using '\fB&artist[1]\fR' will expand to '\fIF\fR'.
.SS "Available expression identifiers"
.IX Subsection "Available expression identifiers"
The data, that is expanded is derived from tagging information in
the audio files. For \fI.ogg\fR and \fI.flac\fR files, the tag checking
\&\fBarename\fR does is case insensitive and the first matching tag
will be used.
.IP "\fBalbum\fR" 8
.IX Item "album"
Guess.
.IP "\fBartist\fR" 8
.IX Item "artist"
Guess again.
.IP "\fBcompilation\fR" 8
.IX Item "compilation"
For \fI.ogg\fR and \fI.flac\fR this is filled with information found in the
\&'albumartist' tag. For \fI.mp3\fR this is filled with information from the
id3v2 \s-1TPE2\s0 frame. If the mp3 file only provides a id3v1 tag, this is not
supported.
.IP "\fBgenre\fR" 8
.IX Item "genre"
The genre or content type of the audio file.
.IP "\fBtracknumber\fR" 8
.IX Item "tracknumber"
The number of the position of the track on the disc. Obviously. However, this
can be in the form of '12' or '12/23'. In the second form, only the part left
of the slash is used. The tracknumber is a little special, as you can define
to what width it should be padded with zeros on the left (see \fItnpad\fR setting
in \*(L"\s-1SETTINGS\s0\*(R").
.IP "\fBtracktitle\fR" 8
.IX Item "tracktitle"
Well...
.IP "\fByear\fR" 8
.IX Item "year"
Year (id3v1), \s-1TYER\s0 (id3v2) or \s-1DATE\s0 tag (.ogg/.flac).
.SH "EXIT STATUS"
.IX Header "EXIT STATUS"
\&\fBarename\fR returns zero if everything went fine; non-zero on fatal
problems. This may change in future versions.
.SH "HOOKS"
.IX Header "HOOKS"
Before we start, a word of warning: Hooks can solve a lot of problems.
That amount of flexibility comes at its price. All data passed to
hook functions are \fBreferences\fR to the \fBactual data\fR in the script
(except for the namespace argument, which is a copy). If you write
hooks carelessly, arename will get back at you! \s-1HOOKS\s0 \s-1ARE\s0 A \s-1BIG\s0
\&\s-1HAMMER\s0, \s-1THAT\s0 \s-1CAN\s0 \s-1CRUSH\s0 \s-1PROBLEMS\s0 \s-1AS\s0 \s-1WELL\s0 \s-1AS\s0 \s-1LIMBS\s0!
.PP
\&\fIYou have been warned!\fR
.SS "Discussion"
.IX Subsection "Discussion"
The reason for implementing hooks was to have a simple way of post
processing tags, filenames etc. without having to invent own magic in
the configuration files, when Perl has regular expressions on steriods
anyway. Hooks can do more then pure pre and post processing, because
they are called in numerous places and give broad access to the script's
data structures. Still, post processing is probably the most useful
feature they implement.
.PP
Hooks are just Perl subroutines, which are defined in one of two files
(see \*(L"\s-1FILES\s0\*(R"). They are run at certain events during the
execution of arename. The contents of the argument list for each hook
depends on what hook is called (see the \*(L"List of hook events\*(R" below).
However, the first argument (argument zero aka. \f(CW$_\fR[0]) to all hooks is
the hook namespace, the subroutine is called in.
.PP
The global hooks file is read before the local one, which means, that
this local file may overwrite and extend the definitions from the global
file, as much as Perl permits. This also means, that hooks from the
local file are run \fIafter\fR the ones from the global file (unless you
are using your own method of registering hooks; but if you do so, you
know what you are doing anyway).
.PP
Subroutines must be registered to arename, to be known as hooks.
Once registered, a subroutine can be removed from the known hooks,
if requested (see \*(L"Utility subroutines\*(R" below).
.PP
The keys in various data hashes passed to the hooks can be one of
the following: \fIalbum\fR, \fIartist\fR, \fIcompilation\fR, \fIgenre\fR,
\&\fItracknumber\fR, \fItracktitle\fR, \fIyear\fR.
.SS "Utility subroutines"
.IX Subsection "Utility subroutines"
\fIRegistration subroutines\fR
.IX Subsection "Registration subroutines"
.PP
There are two subroutines, that are used to tell arename about
subroutines, you defined that shall become hooks.
.IP "\fBregister_hook\fR(\fIevent\fR, \fIcoderef\fR)" 4
.IX Item "register_hook(event, coderef)"
Registers a \fIcode reference\fR (read: your subroutine) for the given
\&\fIevent\fR. Example: register_hook('startup', \e&custom_banner);
.IP "\fBremove_hook\fR(\fIevent\fR, \fIcoderef\fR)" 4
.IX Item "remove_hook(event, coderef)"
Removes \fBall\fR entries of the \fIcode reference\fR for the given
\&\fIevent\fR. Example: remove_hook('startup', \e&custom_banner);
.Sp
If the coderef was added more than once, all entries are removed.
.PP
\fIFile access and manipulation\fR
.IX Subsection "File access and manipulation"
.PP
The currently processed file name can be accessed via two subroutines:
.IP "\fBget_file\fR()" 4
.IX Item "get_file()"
Returns the current file name as a string. This way, you can get the
name of the currently processed file in every hook.
.IP "\fBset_file\fR(\fIfile name string\fR)" 4
.IX Item "set_file(file name string)"
This gives you the opportunity of manipulating the current file name.
Be careful using this, because if you break the file name, \fBarename\fR
cannot work properly.
.PP
With these, you could even change the file name of the processed file,
while \fBarename\fR works on it (which you really should only do, if you
know what you are doing).
.PP
\fIUser-defined-variable subroutines\fR
.IX Subsection "User-defined-variable subroutines"
.PP
Hooks can also use the data from user defined variables, via their Perl
interface:
.IP "\fBuser_get\fR(\fIsetting\fR)" 4
.IX Item "user_get(setting)"
Returns the current value of \fIsetting\fR. This is always a scalar value.
.IP "\fBuser_set\fR(\fIsetting\fR, \fIvalue\fR)" 4
.IX Item "user_set(setting, value)"
Change the value of \fIsetting\fR to \fIvalue\fR.
.PP
Here is an example for user defined settings:
.PP
.Vb 5
\&  # Assume, the user set the myvar\-variable to "bar" in his
\&  # configuration file
\&  my $foo = user_get(\*(Aqmyvar\*(Aq);    # $foo is now "bar"
\&  user_set(\*(Aqfoo\*(Aq, "bar, baz");
\&  my $foo = user_get(\*(Aqmyvar\*(Aq);    # $foo is now "bar, baz"
.Ve
.PP
\fI\s-1API\s0 for accessing to arename's internal configuration\fR
.IX Subsection "API for accessing to arename's internal configuration"
.PP
You can also access the configuration data of \fBarename\fR itself:
.IP "\fBget_opt\fR(\fIsetting\fR)" 4
.IX Item "get_opt(setting)"
Returns the current value of \fIsetting\fR. This is always a scalar value.
.IP "\fBset_opt\fR(\fIsetting\fR, \fIvalue\fR)" 4
.IX Item "set_opt(setting, value)"
Change the value of \fIsetting\fR to \fIvalue\fR.
.PP
A list of settings \fBarename\fR will use: canonicalize, dryrun, force,
hookerrfatal, oprefix, prefix, quiet, quiet_skip, readstdin, shutup,
sepreplace, tnpad, usehooks, uselocalhooks, uselocalrc, verbose,
comp_template and template.
.PP
If you want to actually change these settings, you should have a profound
knowledge of \fBarename\fR's internals. Be careful.
.PP
\fI\s-1API\s0 for default_* settings\fR
.IX Subsection "API for default_* settings"
.PP
If you need to access the current values of the \fIdefault_*\fR settings:
.IP "\fBget_defaults\fR(\fItagname\fR)" 4
.IX Item "get_defaults(tagname)"
Returns the value of default_\fItagname\fR.
.IP "\fBget_default_keys\fR()" 4
.IX Item "get_default_keys()"
Returns a lexically sorted array of tag names of currently set \fIdefault_*\fR
values.
.IP "\fBset_default\fR(\fItagname\fR, \fIvalue\fR)" 4
.IX Item "set_default(tagname, value)"
Sets the value of default_\fItagname\fR to \fIvalue\fR.
.PP
\fIOutput subroutines\fR
.IX Subsection "Output subroutines"
.PP
For output, you can use the following functions, the rest of \fBarename\fR
uses as well:
.IP "\fBoprint\fR(\fIargs\fR, ...)" 4
.IX Item "oprint(args, ...)"
Print to the standard output stream. This can be called the same way as
Perl's usual \fIprint\fR subroutine.
.IP "\fBowarn\fR(\fIargs\fR, ...)" 4
.IX Item "owarn(args, ...)"
Print to the standard error stream.
.PP
\fIMiscellaneous subroutines\fR
.IX Subsection "Miscellaneous subroutines"
.PP
And finally, a few miscellaneous functions ARename.pm provides, that
might be of interest.
.IP "\fBchoose_template\fR(\fIdata hash reference\fR)" 4
.IX Item "choose_template(data hash reference)"
Return the appropriate template (\fInormal\fR versus \fIcompiliation\fR template)
by the data in the referenced data hash.
.IP "\fBexpand_template\fR(\fItemplate string\fR, \fIdata hash reference\fR)" 4
.IX Item "expand_template(template string, data hash reference)"
Return the expanded version of \fItemplate string\fR. The information, that
is used to do the expansion is taken from the referenced data hash.
.Sp
Keep in mind that this function calls hooks itself. Avoid endless loops!
See \*(L"Hooks when expanding the template\*(R" for details.
.IP "\fBensure_dir\fR(\fIdirectory\fR)" 4
.IX Item "ensure_dir(directory)"
Makes sure \fIdirectory\fR exists. Think: mkdir \-p \fIdirectory\fR
.IP "\fBfile_eq\fR(\fIfile0\fR, \fIfile1\fR)" 4
.IX Item "file_eq(file0, file1)"
Checks if the name \fIfile0\fR and the name \fIfile1\fR point to the same file.
Returns \fI0\fR, if one of the file names does not exist or if the files do
not point to the same file, \fI1\fR otherwise.
.Sp
Dies if it cannot stat one of the given files.
.IP "\fBtag_supported\fR(\fItagname\fR)" 4
.IX Item "tag_supported(tagname)"
Returns \fI1\fR if the tag \fItagname\fR is supported by arename, \fI0\fR otherwise.
.IP "\fBxrename\fR(\fIsrc\fR, \fIdest\fR)" 4
.IX Item "xrename(src, dest)"
Renames \fIsrc\fR to \fIdest\fR. Works across file systems, too. Dies
if something fails.
.SS "List of hook events"
.IX Subsection "List of hook events"
This is a complete list of hooks events with descriptions.
.PP
The first argument (argument number \*(L"zero\*(R") for every hook is the
name space they are called in. To find out the name of the currently
processed file, use the \fIget_file\fR() subroutine described above.
.PP
\fIHooks in the main loop\fR
.IX Subsection "Hooks in the main loop"
.PP
These hooks are called at the highest level of the script.
.IP "\fBcanonicalize\fR" 4
.IX Item "canonicalize"
This is called in the middle of the file name canonicalization process
(but \fBonly\fR it is enabled via the \fIcanonicalize\fR setting).
.Sp
Get the current file name via \fI\fIget_file()\fI\fR. The canonicalized file name
is handed to you via the hook's arguments. The value from this argument
will be assigned to the processed filename after the execution of this
hook.
.Sp
\&\fIArguments\fR: \fB1:\fR canonicalized file name
.IP "\fBnext_file_early\fR" 4
.IX Item "next_file_early"
Called at the start of the main loop \fIbefore\fR any file checks and
canonicalizations (if enabled) are done.
.Sp
\&\fIArguments\fR:
.IP "\fBnext_file_late\fR" 4
.IX Item "next_file_late"
Called in the main loop \fIafter\fR the file checks and canonicalizations
are done.
.Sp
By file checks, checks for read-access and for symlinks are meant. \fIarename\fR
will refuse to process symlinks and files it cannot read.
.Sp
\&\fIArguments\fR:
.IP "\fBfile_done\fR" 4
.IX Item "file_done"
Called in the main loop \fIafter\fR the file has been processed (unless
\&\fBfiletype_unknown\fR was triggered, see below).
.Sp
\&\fIArguments\fR:
.IP "\fBfiletype_unknown\fR" 4
.IX Item "filetype_unknown"
Called in the main loop \fIafter\fR the file was tried to be processed but
the file type (the extension, specifically) was unknown.
.Sp
\&\fIArguments\fR:
.PP
\fIHooks in the renaming procedure\fR
.IX Subsection "Hooks in the renaming procedure"
.PP
When all data has been gathered, \fBarename\fR will go on to actually
rename the files to their new destination name (which will be generated
in the process, see \*(L"Hooks when expanding the template\*(R" below).
.IP "\fBpre_apply_defaults\fR" 4
.IX Item "pre_apply_defaults"
This is the first action to be taken in the renaming process. It is
called even before the default values are applied.
.Sp
\&\fIArguments\fR: \fB1:\fR data hash, \fB2:\fR file extension
.IP "\fBpre_template\fR" 4
.IX Item "pre_template"
Called \fIbefore\fR template expansions have been done.
.Sp
\&\fIArguments\fR: \fB1:\fR data hash, \fB2:\fR file extension
.IP "\fBpost_template\fR" 4
.IX Item "post_template"
Called \fIafter\fR the template has been expanded and the new file name
has been completely generated (including the destination directory
prefix).
.Sp
\&\fIArguments\fR: \fB1:\fR data hash, \fB2:\fR file extension
\&\fB3:\fR the generated new filename (including directory prefix and file
extension)
.IP "\fBpost_ensure_dir\fR" 4
.IX Item "post_ensure_dir"
The destnation directory for the new file name may contain sub directories,
which currently do not exist. This hook is called \fIafter\fR it is ensured,
every directory portion exists.
.Sp
\&\fIArguments\fR: \fB1:\fR data hash, \fB2:\fR file extension
\&\fB3:\fR the generated new filename (including directory prefix and file
extension)
.IP "\fBpost_rename\fR" 4
.IX Item "post_rename"
This is the final hook in the actual renaming process. The file has been
renamed at this point.
.Sp
\&\fIArguments\fR: \fB1:\fR data hash, \fB2:\fR file extension
\&\fB3:\fR the generated new filename (including directory prefix and file
extension)
.PP
\fIHooks when expanding the template\fR
.IX Subsection "Hooks when expanding the template"
.PP
These hooks are called when the template string is filled with the data
from tags in the audio files. All file type specific actions will have
been taken care of already. That makes these hooks probably most useful
for post processing tags, the template and file names.
.IP "\fBpre_expand_template\fR" 4
.IX Item "pre_expand_template"
Called before any expansions are done.
.Sp
\&\fIArguments\fR: \fB1:\fR the template string, \fB2:\fR the data hash
.IP "\fBexpand_template_next_tag\fR" 4
.IX Item "expand_template_next_tag"
This hook is triggered when the next identifier in the template string
is processed. At this point it is already verified, that there is an
according tag in the data hash to fill in the identifier's space.
.Sp
\&\fIArguments\fR: \fB1:\fR the template string, \fB2:\fR the tag's name
\&\fB3:\fR the value of the length modifier in the template (zero, if
unspecified) \fB4:\fR the data hash
.IP "\fBexpand_template_postprocess_tag\fR" 4
.IX Item "expand_template_postprocess_tag"
This hooks is triggered after all internal processing of the replacement
token is done (directory seperators are replaced; tracknumbers are padded
up).
.Sp
\&\fIArguments\fR: \fB1:\fR the template string, \fB2:\fR the text token, that will
replace the identifier in the template, \fB3:\fR the tag's name \fB4:\fR the
value of the length modifier, \fB5:\fR the data hash
.IP "\fBpost_expand_template\fR" 4
.IX Item "post_expand_template"
Called after all expansions have been done, right before the the resulting
string is returned.
.Sp
\&\fIArguments\fR: \fB1:\fR the template string (fully expanded), \fB2:\fR the data
hash
.PP
\fIHooks when gathering information\fR
.IX Subsection "Hooks when gathering information"
.PP
These hooks are triggered while the tag information is extracted from
the audio files arename is processing. Due to the differing nature
of the the involved backends, these are slightly different from file type
to file type.
.PP
Specifically, the tag for .ogg and .flac files are read one after another
(the tags in these files are pretty much the same, hence they are processed
exactly the same), whereas tags in .mp3 files are read all at the same
time.
.IP "\fBpre_process_flac\fR" 4
.IX Item "pre_process_flac"
\&\fI.flac only!\fR
.Sp
Called \fIbefore\fR a flac file is processed.
.Sp
\&\fIArguments\fR:
.IP "\fBpost_process_flac\fR" 4
.IX Item "post_process_flac"
\&\fI.flac only!\fR
.Sp
Called \fIafter\fR a flac file is processed.
.Sp
\&\fIArguments\fR:
.IP "\fBpre_process_ogg\fR" 4
.IX Item "pre_process_ogg"
\&\fI.ogg only!\fR
.Sp
Called \fIbefore\fR an ogg file is processed.
.Sp
\&\fIArguments\fR:
.IP "\fBpost_process_ogg\fR" 4
.IX Item "post_process_ogg"
\&\fI.ogg only!\fR
.Sp
Called \fIafter\fR an ogg file is processed.
.Sp
\&\fIArguments\fR:
.IP "\fBpre_handle_vorbistag\fR" 4
.IX Item "pre_handle_vorbistag"
\&\fI.ogg and .flac only!\fR
.Sp
Triggered \fIbefore\fR any processing of a certain tag. It is not ensured
that the tag is even among the supported tags at this point.
.Sp
\&\fIArguments\fR: \fB1:\fR tag name, \fB2:\fR tag value, \fB3:\fR data hash
.IP "\fBpost_handle_vorbistag\fR" 4
.IX Item "post_handle_vorbistag"
\&\fI.ogg and .flac only!\fR
.Sp
Triggered \fIafter\fR a certain tag was processed.
.Sp
This hook is only reached if the currently processed tag is in fact among
the tags supported by \fBarename\fR.
.Sp
\&\fIArguments\fR: \fB1:\fR tag name, \fB2:\fR tag value, \fB3:\fR the internal name for
the tag (also used as the key in the data hash), \fB4:\fR data hash
.IP "\fBpre_process_mp3\fR" 4
.IX Item "pre_process_mp3"
\&\fI.mp3 only!\fR
.Sp
Called \fIbefore\fR an mp3 file is processed.
.Sp
\&\fIArguments\fR:
.IP "\fBpost_process_mp3\fR" 4
.IX Item "post_process_mp3"
\&\fI.mp3 only!\fR
.Sp
Called \fIafter\fR an mp3 file is processed.
.Sp
\&\fIArguments\fR:
.IP "\fBpre_handle_mp3tag\fR" 4
.IX Item "pre_handle_mp3tag"
\&\fI.mp3 only!\fR
.Sp
Called \fIbefore\fR data from the mp3 object is copied to the data hash.
.Sp
\&\fIArguments\fR: \fB1:\fR the mp3 object, \fB2:\fR data hash
.IP "\fBpost_handle_mp3tag\fR" 4
.IX Item "post_handle_mp3tag"
\&\fI.mp3 only!\fR
.Sp
Called \fIafter\fR data from the mp3 object has been copied to the data hash.
.Sp
\&\fIArguments\fR: \fB1:\fR the mp3 object, \fB2:\fR data hash
.PP
\fIMiscellaneous hooks\fR
.IX Subsection "Miscellaneous hooks"
.IP "\fBapply_defaults\fR" 4
.IX Item "apply_defaults"
This is triggered before values from the default_* settings are applied
to missing values in the audio file. This hook is \fIonly\fR run if a
default value for a tag will be used!
.Sp
\&\fIArguments\fR: \fB1:\fR data hash, \fB2:\fR current key
.IP "\fBpre_method\fR" 4
.IX Item "pre_method"
This hook is called after a method for a file type is choosen but
\&\fIbefore\fR the method was executed.
.Sp
\&\fIArguments\fR: \fB1:\fR method name
.IP "\fBpost_method\fR" 4
.IX Item "post_method"
Called after a method for a file type was executed.
.Sp
\&\fIArguments\fR: \fB1:\fR method name
.IP "\fBstartup\fR" 4
.IX Item "startup"
Called directly after all the module initialisation is done, at the very
start of the script. Configuration files will have been read, as well as
hook files (obviously) and command line options will have been handled at
this point already.
.Sp
This hook may be useful for postprocessing the configuration as well as
for debugging.
.Sp
\&\fIArguments\fR: \fB1:\fR program name, \fB2:\fR its version, \fB3:\fR configuration
hash, \fB4:\fR hash of extensions, that point the the according method for
the file type \fB5:\fR array of supported tags, \fB6:\fR the program's argument
list
.IP "\fBnormal_quit\fR" 4
.IX Item "normal_quit"
Called at the end of the script. This is reached if nothing fatal happened.
.Sp
\&\fIArguments\fR: \fB1:\fR the program's argument list
.SS "Example"
.IX Subsection "Example"
This is a very simple example for a hook file, that prints a custom
banner and replaces all whitespace in the expanded template with
underscores:
.PP
.Vb 4
\&  sub my_banner {
\&      oprint "Hello World.\en";
\&  }
\&  register_hook(\*(Aqstartup\*(Aq, \e&my_banner);
\&
\&  sub replace_spaces_by_underscore {
\&      my ($templateref, $datref) = @_;
\&      $$templateref =~ s/\es+/_/g;
\&  }
\&  register_hook(\*(Aqpost_expand_template\*(Aq,
\&      \e&replace_spaces_by_underscore);
.Ve
.PP
Further examples can be found in the \fBarename.hook\fR file of the
distribution.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Ogg::Vorbis::Header, Audio::FLAC::Header and MP3::Tag.
.SH "AUTHOR"
.IX Header "AUTHOR"
Frank Terbeck <ft@bewatermyfriend.org>,
.PP
Please report bugs.
.SH "LICENCE"
.IX Header "LICENCE"
.Vb 2
\& Copyright 2007, 2008
\& Frank Terbeck <ft@bewatermyfriend.org>, All rights reserved.
\&
\& Redistribution and use in source and binary forms, with or without
\& modification, are permitted provided that the following conditions
\& are met:
\&
\&   1. Redistributions of source code must retain the above
\&      copyright notice, this list of conditions and the following
\&      disclaimer.
\&   2. Redistributions in binary form must reproduce the above
\&      copyright notice, this list of conditions and the following
\&      disclaimer in the documentation and/or other materials
\&      provided with the distribution.
\&
\&  THIS SOFTWARE IS PROVIDED "AS IS" AND ANY EXPRESS OR IMPLIED
\&  WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
\&  OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
\&  DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS OF THE
\&  PROJECT BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
\&  EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
\&  PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
\&  PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY
\&  OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
\&  (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
\&  OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
.Ve