Changeset 3 in mp3-find for trunk/lib

Timestamp:

01/30/06 02:05:25 (19 years ago)

Author:

peter

Message:

• updated MANIFEST to include all lib/* and Makefile.PL to include bin/mp3find
• doc updates to *.pm and mp3find

Location:

trunk/lib/MP3

Files:

• Find.pm (modified) (5 diffs)
• Find/DB.pm (modified) (1 diff)
• Find/Filesystem.pm (modified) (1 diff)

trunk/lib/MP3/Find.pm

@@ -37 +37 @@
 =head1 SYNOPSIS
 
-    use MP3Find;
+    # select with backend you want
+    use MP3::Find qw(Filesystem);
     
     print "$_\n" foreach find_mp3s(
@@ -59 +60 @@
 or the actual Perl data structure representing the results.
 
+There are currently two backends to this module: L<MP3::Find::Filesystem>
+and L<MP3::Find::DB>. You choose which one you want by passing its
+name as the argument to you C<use> statement; B<MP3::Find> will look for
+a B<MP3::Find::$BACKEND> module. If no backend name is given, it will
+default to using L<MP3::Find::Filesystem>.
+
+B<Note:> I'm still working out some kinks in the DB backend, so it
+is currently not as stable as the Filesystem backend.
+
 =head1 REQUIRES
 
-L<File::Find>, L<MP3::Info>, L<Scalar::Util>
+L<File::Find>, L<MP3::Info>, and L<Scalar::Util> are needed for
+the filesystem backend (L<MP3::Find::Filesystem>).
 
-L<DBI> and L<DBD::SQLite> are needed if you want to have a
-database backend.
+L<DBI>, L<DBD::SQLite>, and L<SQL::Abstract> are needed for the
+database backend (L<MP3::Find::DB>).
 
 =head1 EXPORTS
@@ -95 +106 @@
 =item C<exact_match>
 
-Adds an implicit C<^> and C<$> around each query string.
+Adds an implicit C<^> and C<$> around each query string. Does nothing
+if the query is already a regular expression.
 
 =item C<sort>
@@ -101 +113 @@
 What field or fields to sort the results by. Can either be a single
 scalar field name to sort by, or an arrayref of field names. Again,
-acceptable field names are anything that L<MP3::Info> knows about.
+acceptable field names are anything that L<MP3::Info> knows about;
+field names will be converted to upper case as with the C<query>
+option.
 
 =item C<printf>
@@ -144 +158 @@
 =back
 
+=head1 BUGS
+
+There are probably some in there; let me know if you find any (patches
+welcome).
+
 =head1 TODO
 
-More of a structured query would be nice; currently everything
-is and-ed together, and it would be nice to be able to put query
-keys together with a mixture of and and or.
+Better tests, using some actual sample mp3 files.
 
-Searching a big directory is slo-o-ow! Investigate some sort of 
-caching of results?
-
-The current sorting function is also probably quite inefficient.
+Other backends (a caching filesystem backend, perhaps?)
 
 =head1 SEE ALSO
+
+L<MP3::Find::Filesystem>, L<MP3::Find::DB>
+
+L<mp3find> is the command line frontend to this module (it
+currently only uses the filesystem backend).
 
 See L<MP3::Info> for more information about the fields you can

trunk/lib/MP3/Find/DB.pm

@@ -47 +47 @@
 # module return
 1;
+
+=head1 NAME
+
+MP3::Find::DB - SQLite database backend to MP3::Find
+
+=head1 SYNOPSIS
+
+    use MP3::Find::DB;
+    my $finder = MP3::Find::DB->new;
+    
+    my @mp3s = $finder->find_mp3s(
+        dir => '/home/peter/music',
+        query => {
+            artist => 'ilyaimy',
+            album  => 'myxomatosis',
+        },
+        ignore_case => 1,
+    );
+
+=head1 REQUIRES
+
+L<DBI>, L<DBD::SQLite>, L<SQL::Abstract>
+
+=head1 DESCRIPTION
+
+This is the SQLite database backend for L<MP3::Find>.
+
+B<Note:> I'm still working out some kinks in here, so this backend
+is currently not as stable as the Filesystem backend.
+
+=head2 Special Options
+
+=over
+
+=item C<db_file>
+
+The name of the SQLite database file to use. Defaults to F<~/mp3.db>.
+
+The database should have at least one table named C<mp3> with the
+following schema:
+
+    CREATE TABLE mp3 (
+        mtime         INTEGER,
+        FILENAME      TEXT, 
+        TITLE         TEXT, 
+        ARTIST        TEXT, 
+        ALBUM         TEXT,
+        YEAR          INTEGER, 
+        COMMENT       TEXT, 
+        GENRE         TEXT, 
+        TRACKNUM      INTEGER, 
+        VERSION       NUMERIC,
+        LAYER         INTEGER, 
+        STEREO        TEXT,
+        VBR           TEXT,
+        BITRATE       INTEGER, 
+        FREQUENCY     INTEGER, 
+        SIZE          INTEGER, 
+        OFFSET        INTEGER, 
+        SECS          INTEGER, 
+        MM            INTEGER,
+        SS            INTEGER,
+        MS            INTEGER, 
+        TIME          TEXT,
+        COPYRIGHT     TEXT, 
+        PADDING       INTEGER, 
+        MODE          INTEGER,
+        FRAMES        INTEGER, 
+        FRAME_LENGTH  INTEGER, 
+        VBR_SCALE     INTEGER
+    );
+
+=back
+
+=head1 TODO
+
+Move the database/table creation code from F<mp3db> into this
+module.
+
+Database maintanence routines (e.g. clear out old entries)
+
+=head1 SEE ALSO
+
+L<MP3::Find>, L<MP3::Find::DB>
+
+=head1 AUTHOR
+
+Peter Eichman <peichman@cpan.org>
+
+=head1 COPYRIGHT AND LICENSE
+
+Copyright (c) 2006 by Peter Eichman. All rights reserved.
+
+This program is free software; you can redistribute it and/or
+modify it under the same terms as Perl itself.
+
+=cut

trunk/lib/MP3/Find/Filesystem.pm

@@ -73 +73 @@
 # module return
 1;
+
+=head1 NAME
+
+MP3::Find::Filesystem - File::Find-based backend to MP3::Find
+
+=head1 SYNOPSIS
+
+    use MP3::Find::Filesystem;
+    my $finder = MP3::Find::Filesystem->new;
+    
+    my @mp3s = $finder->find_mp3s(
+        dir => '/home/peter/music',
+        query => {
+            artist => 'ilyaimy',
+            album  => 'myxomatosis',
+        },
+        ignore_case => 1,
+    );
+
+=head1 REQUIRES
+
+L<File::Find>, L<MP3::Info>, L<Scalar::Util>
+
+=head1 DESCRIPTION
+
+This module implements the C<search> method from L<MP3::Find::Base>
+using a L<File::Find> based search of the local filesystem.
+
+=head2 Special Options
+
+There are no special options for B<MP3::Find::Filesystem>. See
+L<MP3::Find> for the description of the general options.
+
+=head1 SEE ALSO
+
+L<MP3::Find>, L<MP3::Find::DB>
+
+=head1 AUTHOR
+
+Peter Eichman <peichman@cpan.org>
+
+=head1 COPYRIGHT AND LICENSE
+
+Copyright (c) 2006 by Peter Eichman. All rights reserved.
+
+This program is free software; you can redistribute it and/or
+modify it under the same terms as Perl itself.
+
+=cut