NAME

       MP3::Tag::ParseData - Module for parsing arbitrary data associated with music files.

SYNOPSIS

          # parses the file name according to one of the patterns:
          $mp3->config('parse_data', ['i', '%f', '%t - %n - %a.%e', '%t - %y.%e']);
          $title = $mp3->title;

       see MP3::Tag

DESCRIPTION

       MP3::Tag::ParseData is designed to be called from the MP3::Tag module.

       Each option of configuration item "parse_data" should be of the form "[$flag, $string,
       $pattern1, ...]".  For each of the option, patterns of the option are matched agains the
       $string of the option, until one of them succeeds.  The information obtained from later
       options takes precedence over the information obtained from earlier ones.

       The meaning of the patterns is the same as for parse() or parse_rex() methods of
       "MP3::Tag".  Since the default for "parse_data" is empty, by default this handler has no
       effect.

       $flag is split into 1-character-long flags (unknown flags are ignored):

       "i" the string-to-parse is interpolated first;

       "f" the string-to-parse is interpreted as the name of the file to read;

       "F" added to "f", makes it non-fatal if the file does not exist;

       "B" the file should be read in "binary" mode;

       "n" the string-to-parse is interpreted as collection of lines, one per track;

       "l" the string-to-parse is interpreted as collection of lines, and the first matched is
           chosen;

       "I" the resulting string is interpolated before parsing.

       "b" Do not strip the leading and trailing blanks.  (With output to file, the output is
           performed in binary mode too.)

       "R" the patterns are considered as regular expressions.

       "m" one of the patterns must match.

       "o", "O", "D"
           With "o" or "O" interpret the pattern as a name of file to output parse-data to.  With
           "O" the name of output file is interpolated.  When "D" is present, intermediate
           directories are created.

       "z" Do not ignore a field even if the result is a 0-length string.

       Unless "b" option is given, the resulting values have starting and trailing whitespace
       trimmed.  (Actually, split()ing into lines is done using the configuration item
       "parse_split"; it defaults to "\n".)

       If the configuration item "parse_data" has multiple options, the $strings 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 "MP3::Tag::ParseData" (which by default is the first handler).  For
       example, with

         ['i', '%t' => '%t (%y)'], ['i', '%t' => '%t - %c']

       and a local CDDB file which identifies title to 'Merry old - another interpretation
       (1905)', the first field will interpolate '%t' 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.

       Note that one can use fields of the form

         ['mz', 'This is a forced title' => '%t']

       to force particular values for parts of the MP3 tag.

       The usual methods "artist", "title", "album", "comment", "year", "track", "year" can be
       used to access the results of the parse.

       It is possible to set individual id3v2 frames; use %{TIT1} or some such.  Setting to an
       empty string deletes the frame if config parameter "id3v2_frame_empty_ok" is false (the
       default value).  Setting ID3v2 frames uses the same translation rules as
       select_id3v2_frame_by_descr().

   SEE ALSO
       The flags "i f F B l m I b" are identical to flags of the method interpolate_with_flags()
       of MP3::Tag (see "interpolate_with_flags" in MP3::Tag).  Essentially, the other flags ("R
       m o O D z") are applied to the result of calling the latter method.