Changeset 2 in mp3-find for trunk/lib/MP3/Find


Ignore:
Timestamp:
01/30/06 01:03:14 (19 years ago)
Author:
peter
Message:
  • MP3::Find::Base stores options passed to new
  • massive doc updates to MP3::Find::Base
File:
1 edited

Legend:

Unmodified
Added
Removed

  • trunk/lib/MP3/Find/Base.pm

    r1 r2  
    2121    my $invocant = shift; 
    2222    my $class = ref $invocant || $invocant; 
    23     my $self = {}; 
     23    my %options = @_; 
     24    my $self = \%options; 
    2425    bless $self, $class; 
    2526} 
    … …  
    4041        (); 
    4142     
    42      
    4343    foreach (keys %QUERY) { 
    4444        # so we don't have spurious warnings when trying to match against undef 
    4545        delete $QUERY{$_} unless defined $QUERY{$_}; 
    46         # package everything unioformly, so subclasses don't need to unpack 
     46        # package everything uniformly, so subclasses don't need to unpack it 
    4747        $QUERY{$_} = [ $QUERY{$_} ] unless ref $QUERY{$_} eq 'ARRAY'; 
    4848    } 
    … …  
    9090=head1 NAME 
    9191 
    92 MP3::Find - Search and sort MP3 files based on their ID3 tags 
     92MP3::Find::Base - Base class for MP3::Find finders 
    9393 
    9494=head1 SYNOPSIS 
    9595 
    96     use MP3Find; 
    97      
    98     print "$_\n" foreach find_mp3s( 
    99         dir => '/home/peter/cds', 
    100         query => { 
    101             artist => 'ilyaimy', 
    102             title => 'deep in the am', 
    103         }, 
    104         ignore_case => 1, 
    105         match_words => 1, 
    106         sort => [qw(year album tracknum)], 
    107         printf => '%2n. %a - %t (%b: %y)', 
    108     ); 
     96    package MyFinder; 
     97    use base 'MP3::Find::Base'; 
     98     
     99    sub search { 
     100        my $self = shift; 
     101        my ($query, $dirs, $sort, $options) = @_; 
     102         
     103        # do something to find and sort the mp3s... 
     104        my @results = do_something(...); 
     105         
     106        return @results; 
     107    } 
     108     
     109    package main; 
     110    my $finder = MyFinder->new; 
     111     
     112    # see MP3::Find for details about %options 
     113    print "$_\n" foreach $finder->find_mp3s(\%options);         
    109114 
    110115=head1 DESCRIPTION 
    111116 
    112 This module allows you to search for MP3 files by their ID3 tags. 
    113 You can ask for the results to be sorted by one or more of those 
    114 tags, and return either the list of filenames (the deault), a 
    115 C<printf>-style formatted string for each file using its ID3 tags, 
    116 or the actual Perl data structure representing the results. 
    117  
    118 =head1 REQUIRES 
    119  
    120 L<File::Find>, L<MP3::Info>, L<Scalar::Util> 
    121  
    122 L<DBI> and L<DBD::SQLite> are needed if you want to have a 
    123 database backend. 
    124  
    125 =head1 EXPORTS 
     117This is the base class for the classes that actually do the 
     118searching and sorting for L<MP3::Find>. 
     119 
     120=head1 METHODS 
     121 
     122=head2 new 
     123 
     124Really simple constructor. If you pass it a hash of options, it 
     125will hang on to them for you. 
     126 
     127=head2 search 
     128 
     129This is the one you should override in your subclass. If you 
     130don't, the base class C<search> method will croak. 
     131 
     132The C<search> method is called by the C<find_mp3s> method with 
     133the following arguments: the finder object, a hashref of query 
     134parameters, an arrayref of directories to search, and a hashref 
     135of miscellaneous options. 
     136 
     137The search method should return a list of hashrefs representing 
     138the results of the search. Each hashref should have the following 
     139keys (all except C<FILENAME> are derived from the keys returned 
     140by the C<get_mp3tag> and C<get_mp3Info> functions from L<MP3::Info>): 
     141 
     142    FILENAME 
     143     
     144    TITLE 
     145    ARTIST 
     146    ALBUM 
     147    YEAR 
     148    COMMENT 
     149    GENRE 
     150    TRACKNUM 
     151     
     152    VERSION         -- MPEG audio version (1, 2, 2.5) 
     153    LAYER           -- MPEG layer description (1, 2, 3) 
     154    STEREO          -- boolean for audio is in stereo 
     155     
     156    VBR             -- boolean for variable bitrate 
     157    BITRATE         -- bitrate in kbps (average for VBR files) 
     158    FREQUENCY       -- frequency in kHz 
     159    SIZE            -- bytes in audio stream 
     160    OFFSET          -- bytes offset that stream begins 
     161     
     162    SECS            -- total seconds 
     163    MM              -- minutes 
     164    SS              -- leftover seconds 
     165    MS              -- leftover milliseconds 
     166    TIME            -- time in MM:SS 
     167     
     168    COPYRIGHT       -- boolean for audio is copyrighted 
     169    PADDING         -- boolean for MP3 frames are padded 
     170    MODE            -- channel mode (0 = stereo, 1 = joint stereo, 
     171                    -- 2 = dual channel, 3 = single channel) 
     172    FRAMES          -- approximate number of frames 
     173    FRAME_LENGTH    -- approximate length of a frame 
     174    VBR_SCALE       -- VBR scale from VBR header 
     175 
    126176 
    127177=head2 find_mp3s 
    128178 
    129     my @results = find_mp3s(%options); 
    130  
    131 Takes the following options: 
    132  
    133 =over 
    134  
    135 =item C<dir> 
    136  
    137 Where to start the search. This can either be a single string or 
    138 an arrayref. Defaults to your home directory. 
    139  
    140 =item C<query> 
    141  
    142 Hashref of search parameters. Recognized fields are anything that 
    143 L<MP3::Info> knows about. Field names can be given in either upper 
    144 or lower case; C<find_mp3s> will convert them into upper case for  
    145 you. Value may either be strings, which are converted into regular 
    146 exporessions, or may be C<qr[...]> regular expressions already. 
    147  
    148 =item C<ignore_case> 
    149  
    150 Ignore case when matching search strings to the ID3 tag values. 
    151  
    152 =item C<exact_match> 
    153  
    154 Adds an implicit C<^> and C<$> around each query string. 
    155  
    156 =item C<sort> 
    157  
    158 What field or fields to sort the results by. Can either be a single 
    159 scalar field name to sort by, or an arrayref of field names. Again, 
    160 acceptable field names are anything that L<MP3::Info> knows about. 
    161  
    162 =item C<printf> 
    163  
    164 By default, C<find_mp3s> just returns the list of filenames. The  
    165 C<printf> option allows you to provide a formatting string to apply 
    166 to the data for each file. The style is roughly similar to Perl's 
    167 C<printf> format strings. The following formatting codes are  
    168 recognized: 
    169  
    170     %a - artist 
    171     %t - title 
    172     %b - album 
    173     %n - track number 
    174     %y - year 
    175     %g - genre 
    176     %% - literal '%' 
    177  
    178 Numeric modifers may be used in the same manner as with C<%s> in 
    179 Perl's C<printf>. 
    180  
    181 =item C<no_format> 
    182  
    183 Causes C<find_mp3s> to return an array of hashrefs instead of an array 
    184 of (formatted) strings. Each hashref consists of the key-value pairs 
    185 from C<MP3::Info::get_mp3_tag> and C<MP3::Info::get_mp3_info>, plus 
    186 the key C<FILENAME> (with the obvious value ;-) 
    187  
    188     @results = ( 
    189         { 
    190             FILENAME => ..., 
    191             TITLE    => ..., 
    192             ARTIST   => ..., 
    193             ... 
    194             SECS     => ..., 
    195             BITRATE  => ..., 
    196             ... 
    197         }, 
    198         ... 
    199     ); 
    200  
    201 =back 
     179The method that should be called by the program doing the searching. 
     180 
     181See L<MP3::Find> for an explanation of the options that can be passed 
     182to C<find_mp3s>. 
    202183 
    203184=head1 TODO 
    204185 
    205 More of a structured query would be nice; currently everything 
    206 is and-ed together, and it would be nice to be able to put query 
    207 keys together with a mixture of and and or. 
    208  
    209 Searching a big directory is slo-o-ow! Investigate some sort of  
    210 caching of results? 
    211  
    212 The current sorting function is also probably quite inefficient. 
     186More format codes? Possibly look into using L<String::Format> 
    213187 
    214188=head1 SEE ALSO 
     189 
     190L<MP3::Find>, L<MP3::Find::Filesystem>, L<MP3::Find::DB> 
    215191 
    216192See L<MP3::Info> for more information about the fields you can 
    217193search and sort on. 
    218194 
    219 L<File::Find::Rule::MP3Info> is another way to search for MP3 
    220 files based on their ID3 tags. 
    221  
    222195=head1 AUTHOR 
    223196 
Note: See TracChangeset for help on using the changeset viewer.