.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16)
.\"
.\" 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 "MP3::Tag::ParseData 3pm"
.TH MP3::Tag::ParseData 3pm "2009-12-30" "perl v5.14.2" "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"
MP3::Tag::ParseData \- Module for parsing arbitrary data associated with music files.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 3
\&   # parses the file name according to one of the patterns:
\&   $mp3\->config(\*(Aqparse_data\*(Aq, [\*(Aqi\*(Aq, \*(Aq%f\*(Aq, \*(Aq%t \- %n \- %a.%e\*(Aq, \*(Aq%t \- %y.%e\*(Aq]);
\&   $title = $mp3\->title;
.Ve
.PP
see MP3::Tag
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
MP3::Tag::ParseData is designed to be called from the MP3::Tag module.
.PP
Each option of configuration item \f(CW\*(C`parse_data\*(C'\fR should be of the form
\&\f(CW\*(C`[$flag, $string, $pattern1, ...]\*(C'\fR.  For each of the option, patterns of
the option are matched agains the \f(CW$string\fR of the option, until one of them
succeeds.  The information obtained from later options takes precedence over
the information obtained from earlier ones.
.PP
The meaning of the patterns is the same as for \fIparse()\fR or \fIparse_rex()\fR methods
of \f(CW\*(C`MP3::Tag\*(C'\fR.  Since the default for \f(CW\*(C`parse_data\*(C'\fR is empty, by default this
handler has no effect.
.PP
\&\f(CW$flag\fR is split into 1\-character\-long flags (unknown flags are ignored):
.ie n .IP """i""" 4
.el .IP "\f(CWi\fR" 4
.IX Item "i"
the string-to-parse is interpolated first;
.ie n .IP """f""" 4
.el .IP "\f(CWf\fR" 4
.IX Item "f"
the string-to-parse is interpreted as the name of the file to read;
.ie n .IP """F""" 4
.el .IP "\f(CWF\fR" 4
.IX Item "F"
added to \f(CW\*(C`f\*(C'\fR, makes it non-fatal if the file does not exist;
.ie n .IP """B""" 4
.el .IP "\f(CWB\fR" 4
.IX Item "B"
the file should be read in \f(CW\*(C`binary\*(C'\fR mode;
.ie n .IP """n""" 4
.el .IP "\f(CWn\fR" 4
.IX Item "n"
the string-to-parse is interpreted as collection of lines, one per track;
.ie n .IP """l""" 4
.el .IP "\f(CWl\fR" 4
.IX Item "l"
the string-to-parse is interpreted as collection of lines, and the first
matched is chosen;
.ie n .IP """I""" 4
.el .IP "\f(CWI\fR" 4
.IX Item "I"
the resulting string is interpolated before parsing.
.ie n .IP """b""" 4
.el .IP "\f(CWb\fR" 4
.IX Item "b"
Do not strip the leading and trailing blanks.  (With output to file,
the output is performed in binary mode too.)
.ie n .IP """R""" 4
.el .IP "\f(CWR\fR" 4
.IX Item "R"
the patterns are considered as regular expressions.
.ie n .IP """m""" 4
.el .IP "\f(CWm\fR" 4
.IX Item "m"
one of the patterns must match.
.ie n .IP """o"", ""O"", ""D""" 4
.el .IP "\f(CWo\fR, \f(CWO\fR, \f(CWD\fR" 4
.IX Item "o, O, D"
With \f(CW\*(C`o\*(C'\fR or \f(CW\*(C`O\*(C'\fR interpret the pattern as a name of file to output
parse-data to.  With \f(CW\*(C`O\*(C'\fR the name of output file is interpolated.
When \f(CW\*(C`D\*(C'\fR is present, intermediate directories are created.
.ie n .IP """z""" 4
.el .IP "\f(CWz\fR" 4
.IX Item "z"
Do not ignore a field even if the result is a 0\-length string.
.PP
Unless \f(CW\*(C`b\*(C'\fR option is given, the resulting values have starting and
trailing whitespace trimmed.  (Actually, \fIsplit()\fRing into lines is done
using the configuration item \f(CW\*(C`parse_split\*(C'\fR; it defaults to \f(CW"\en"\fR.)
.PP
If the configuration item \f(CW\*(C`parse_data\*(C'\fR has multiple options, the \f(CW$strings\fR
which are interpolated will use information set by preceding options;
similarly, any interolated option may use information obtained by other
handlers \- even if these handers are later in the pecking order than
\&\f(CW\*(C`MP3::Tag::ParseData\*(C'\fR (which by default is the first handler).  For
example, with
.PP
.Vb 1
\&  [\*(Aqi\*(Aq, \*(Aq%t\*(Aq => \*(Aq%t (%y)\*(Aq], [\*(Aqi\*(Aq, \*(Aq%t\*(Aq => \*(Aq%t \- %c\*(Aq]
.Ve
.PP
and a local \s-1CDDB\s0 file which identifies title to \f(CW\*(AqMerry old \- another
interpretation (1905)\*(Aq\fR, the first field will interpolate \f(CW\*(Aq%t\*(Aq\fR into this
title, then will split it into the year and the rest.  The second field will
split the rest into a title-proper and comment.
.PP
Note that one can use fields of the form
.PP
.Vb 1
\&  [\*(Aqmz\*(Aq, \*(AqThis is a forced title\*(Aq => \*(Aq%t\*(Aq]
.Ve
.PP
to force particular values for parts of the \s-1MP3\s0 tag.
.PP
The usual methods \f(CW\*(C`artist\*(C'\fR, \f(CW\*(C`title\*(C'\fR, \f(CW\*(C`album\*(C'\fR, \f(CW\*(C`comment\*(C'\fR, \f(CW\*(C`year\*(C'\fR, \f(CW\*(C`track\*(C'\fR,
\&\f(CW\*(C`year\*(C'\fR can be used to access the results of the parse.
.PP
It is possible to set individual id3v2 frames; use %{\s-1TIT1\s0} or
some such.  Setting to an empty string deletes the frame if config
parameter \f(CW\*(C`id3v2_frame_empty_ok\*(C'\fR is false (the default value).
Setting ID3v2 frames uses the same translation rules as
\&\fIselect_id3v2_frame_by_descr()\fR.
.SS "\s-1SEE\s0 \s-1ALSO\s0"
.IX Subsection "SEE ALSO"
The flags \f(CW\*(C`i f F B l m I b\*(C'\fR are identical to flags of the method
\&\fIinterpolate_with_flags()\fR of MP3::Tag (see \*(L"interpolate_with_flags\*(R" in MP3::Tag).
Essentially, the other flags (\f(CW\*(C`R m o O D z\*(C'\fR) are applied to the result of
calling the latter method.