doc

1 files changed, 93 insertions, 67 deletions

diff --git a/videomv.pl b/videomv.pl
index aa7a9ad..9eb1a5e 100755
--- a/videomv.pl
+++ b/videomv.pl
@@ -38,35 +38,50 @@ my $videodata = "videodb_videodata";
 
 =head1 NAME
 
-videomv.pl - TODO
+videomv.pl - Move your videos to or within your collection.
 
 =head1 SYNOPSIS
 
-B<videomv.pl> [B<--sort>]
-I<path/to/oldfile> [I<.../>{I<MOVIES>,I<DIRECTORS/director/>}I</>[I<newfile>]]
+B<videomv.pl> [B<--db>] [B<-q>]
+I<path/to/oldfile> [{I<MOVIES>,I<DIRECTORS/director/>}I</>[I<newfile>]]
+
+=head1 DESCRIPTION
+
+Your collection is assumed to have the following structure: two
+folders, here I<DIRECTORS> and I<MOVIES> that have the same parent.
+I<DIRECTORS> contains one subdirectory for each director, and each movie
+lies (B<as a regular file>) in the subdirectory of its director.
+The I<MOVIES> folders contains symlinks, one for each movie, that target
+to I<../DIRECTORS/director_of_the_movie/movie>.
+The behavior of B<videomv.pl> is NOT specified if your collection does
+not verify these conventions!
 
-video
   |- ...
   |- DIRECTORS
-  |    |- director1/
+  |    |- director1
+  |    |-   |- movie11
+  |    |    `- movie12
   |    |- director2/
   |    `- ...
-  `- MOVIES/
+  `- MOVIES
+       |- movie11 -> ../DIRECTORS/director1/movie1
+       |- movie12 -> ../DIRECTORS/director1/movie2
+       `- ...
 
 
-=head1 DESCRIPTION
 
-Depending on whether I<path/to/> is I<.../MOVIES/>,
-I<.../DIRECTORS/director/>, or something
-else, one has one of the six behaviors below. For the sake of
-readability the paths are absolute here, but relative paths are fine as
-well.
+Depending on whether I<path/to/> is I<MOVIES/>,
+I<DIRECTORS/*/>, or something
+else, you will get one of the six behaviors below. For the sake of
+readability the paths are relative to the root of your video collection
+here, but hopefully other origins or
+paths that contain symlinks are fine as well.
 
 =over 4
 
-=item B<videomv.pl> [B<--sort>] I<.../MOVIES/oldfile> I<.../MOVIES/newfile>
+=item B<videomv.pl> [B<--db>] I<MOVIES/oldfile> I<MOVIES/newfile>
 
-I<oldfile> is supposed to be an existing symlink in I<.../MOVIES/>,
+I<oldfile> is expected to be an existing symlink in I<MOVIES/>,
 which targets to I<../DIRECTORS/director/oldfile>. If
 I<oldfile>=I<newfile>, an error will be raised. Otherwise, the following
 actions will be performed:
@@ -74,24 +89,24 @@ actions will be performed:
 =over 4
 
 
-=item * The old target will be renamed to I<../DIRECTORS/director/newfile>,
+=item * The old target will be renamed to I<DIRECTORS/director/newfile>,
 
 =item * the old symlink will be deleted,
 
-=item * a new symlink I<.../MOVIES/newfile> -> I<../DIRECTORS/director/newfile>
+=item * a new symlink I<MOVIES/newfile> -> I<../DIRECTORS/director/newfile>
 will be created, and
 
 =item * the filename in the database will be updated.
 
 =back
 
-If the B<--sort> flag is set, the new I<director> will be find on the
-database instead of from the old target. 
+If the B<--db> flag is set, the new I<director> will be found on the
+database instead of by parsing the path of the old target. 
 
 
-=item B<videomv.pl> I<.../MOVIES/oldfile> I<.../DIRECTOR/newdirector/>[I<newfile>]
+=item B<videomv.pl> I<MOVIES/oldfile> I<DIRECTORS/newdirector/>[I<newfile>]
 
-I<oldfile> is supposed to be an existing symlink in I<.../MOVIES/>,
+I<oldfile> is expected to be an existing symlink in I<MOVIES/>,
 which targets to I<../DIRECTORS/olddirector/oldfile>. If
 I<olddirector/oldfile>=I<newdirector/newfile>
 (or if I<olddirector>=I<newdirector> and I<newfile> was not given),
@@ -100,46 +115,49 @@ Otherwise, the following actions will be performed:
 
 =over 4
 
-=item * The old target will be moved to I<../DIRECTORS/newdirector/newfile>,
-(or to I<../DIRECTORS/newdirector/oldfile> if I<newfile> was not given),
+=item * The old target will be moved to I<DIRECTORS/newdirector/newfile>,
+(or to I<DIRECTORS/newdirector/oldfile> if I<newfile> was not given),
 
 =item * the old symlink will be deleted,
 
-=item * a new symlink I<.../MOVIES/newfile> -> I<../DIRECTORS/newdirector/newfile>
+=item * a new symlink I<MOVIES/newfile> -> I<../DIRECTORS/newdirector/newfile>
 (or -> I<../DIRECTORS/newdirector/oldfile> if I<newfile> was not given)
 will be created, and
 
-=item * the filename in the database will be updated if I<oldfile><>I<newfile>.
+=item * the filename in the database will be updated unless I<oldfile>=I<newfile>.
 
 =back
 
 
-=item B<videomv.pl> [B<--sort>] I<.../DIRECTORS/director/oldfile> I<.../MOVIES/newfile>
+=item B<videomv.pl> [B<--db>] I<DIRECTORS/director/oldfile> I<MOVIES/newfile>
 
-A symlink I<.../MOVIES/oldfile> -> I<../DIRECTORS/director/oldfile> is
-supposed to exist.
+A symlink I<MOVIES/oldfile> -> I<../DIRECTORS/director/oldfile> is
+expected to exist.
 If I<oldfile>=I<newfile>, an error will be raised. Otherwise, the following
 actions will be performed:
 
 =over 4
 
-=item * The old target I<../DIRECTORS/director/oldfile> will be renamed to
-I<../DIRECTORS/director/newfile>,
+=item * The old target I<DIRECTORS/director/oldfile> will be renamed to
+I<DIRECTORS/director/newfile>,
 
 =item * the old symlink will be deleted,
 
-=item * a new symlink I<.../MOVIES/newfile> -> I<../DIRECTORS/director/newfile>
+=item * a new symlink I<MOVIES/newfile> -> I<../DIRECTORS/director/newfile>
 will be created, and
 
 =item * the filename in the database will be updated.
 
 =back
 
+If the B<--db> flag is set, the new I<director> will be found on the
+database instead of by parsing the path of the old target. 
 
-=item B<videomv.pl> I<.../DIRECTORS/olddirector/oldfile> I<.../DIRECTOR/newdirector/>[I<newfile>]
 
-A symlink I<.../MOVIES/oldfile> -> I<../DIRECTORS/olddirector/oldfile> is
-supposed to exist.  
+=item B<videomv.pl> I<DIRECTORS/olddirector/oldfile> I<DIRECTOR/newdirector/>[I<newfile>]
+
+A symlink I<MOVIES/oldfile> -> I<../DIRECTORS/olddirector/oldfile> is
+expected to exist.  
 If I<olddirector/oldfile>=I<newdirector/newfile>
 (or if I<olddirector>=I<newdirector> and I<newfile> was not given),
 an error will be raised.
@@ -152,56 +170,55 @@ I<../DIRECTORS/newdirector/newfile>,
 
 =item * the old symlink will be deleted,
 
-=item * a new symlink I<.../MOVIES/newfile> -> I<../DIRECTORS/newdirector/newfile>
+=item * a new symlink I<MOVIES/newfile> -> I<../DIRECTORS/newdirector/newfile>
 will be created, and
 
-=item * the filename in the database will be updated if I<oldfile><>I<newfile>.
+=item * the filename in the database will be updated unless I<oldfile>=I<newfile>.
 
 =back
 
 
-=item B<videomv.pl> B<--sort> I<path/to/oldfile> [I<.../MOVIES/newfile>]
+=item B<videomv.pl> B<--db> I<path/to/oldfile> [I<MOVIES>[I</newfile>]]
 
-Where I<path/to/> is neither of I<.../MOVIES/> nor I<.../DIRECTORS/*/>,
+Where I<path/to/> is neither of I<MOVIES/> nor I<DIRECTORS/*/>,
 and I<oldfile> is a regular file.
-The director will looked for in the database, and and error will be
-raised if no entry is found.
-Otherwise, the following actions will be performed:
+The I<director> will found in the database, and and error will be
+raised if no entry is (or multiple entries are) found.
+In case of success, the following actions will be performed:
 
 =over 4
 
-=item * The old file will be moved to I<../DIRECTORS/director/newfile>
-(or to I<../DIRECTORS/director/oldfile> if the second argument was not
-given),
+=item * I<oldfile> will be moved to I<DIRECTORS/director/newfile>
+(or to I<DIRECTORS/director/oldfile> if I<newfile> was not given),
 
-=item * a symlink I<.../MOVIES/newfile> -> I<../DIRECTORS/director/newfile>
-(or I<.../MOVIES/oldfile> -> I<../DIRECTORS/director/oldfile> if the second
-argument was not given) will be created, and
+=item * a symlink I<MOVIES/newfile> -> I<../DIRECTORS/director/newfile>
+(or I<MOVIES/oldfile> -> I<../DIRECTORS/director/oldfile> if I<newfile>
+was not given) will be created, and
 
-=item * the filename in the database will be updated if I<oldfile><>I<newfile>.
+=item * the filename in the database will be updated unless I<oldfile>=I<newfile>.
 
 =back
 
-Note that the B<--sort> has to be set for this to work; if not, an error
+Note that the B<--db> flag has to be set for this to work; if not, an error
 will be raised.
 
 
-=item B<videomv.pl> I<path/to/oldfile> I<.../DIRECTOR/director/>[I<newfile>]
+=item B<videomv.pl> I<path/to/oldfile> I<DIRECTOR/director/>[I<newfile>]
 
-Where I<path/to/> is neither of I<.../MOVIES/> nor I<.../DIRECTORS/*/>,
+Where I<path/to/> is neither of I<MOVIES/> nor I<DIRECTORS/*/>,
 and I<oldfile> is a regular file.
 The following actions will be performed:
 
 =over 4
 
-=item * The old file will be moved to I<../DIRECTORS/director/newfile>
-(or to I<../DIRECTORS/director/oldfile> if I<newfile> was not given),
+=item * I<oldfile> will be moved to I<DIRECTORS/director/newfile>
+(or to I<DIRECTORS/director/oldfile> if I<newfile> was not given),
 
-=item * a symlink I<.../MOVIES/newfile> -> I<../DIRECTORS/director/newfile>
-(or I<.../MOVIES/oldfile> -> I<../DIRECTORS/director/oldfile> if the second
+=item * a symlink I<MOVIES/newfile> -> I<../DIRECTORS/director/newfile>
+(or I<MOVIES/oldfile> -> I<../DIRECTORS/director/oldfile> if the second
 argument was not given) will be created,
 
-=item * the filename in the database will be updated if I<oldfile><>I<newfile>.
+=item * the filename in the database will be updated unless I<oldfile>=I<newfile>.
 
 
 =back
@@ -213,23 +230,26 @@ argument was not given) will be created,
 
 =over 8
 
-=item B<--sort>
+=item B<--db>
 
-TODO
+If the second argument is in I<MOVIES/*/> and this flag is set, B<videomv.pl> 
+will search the I<director> in the data base. An error will be raied if
+no entry is (or multiple entries are) found. Look above for details.
 
-=item B<--fail>
+=item B<-q>, B<--quiet>
 
-TODO
+By default, B<videomv.pl> prints each action it performs, with their
+return status. This flag supresses this behavior.
 
 =back
 
 =head1 EXIT STATUS
 
-TODO
+The exit status is 0 if all the actions went through, and 1 otherwise.
 
 =head1 REQUIREMENTS
 
-TODO
+The imported modules are available on CPAN. See the source for details.
 
 =head1 AUTHOR
 
@@ -239,10 +259,15 @@ Copyright 2011 Guilhem Moulin. See the source for copying conditions.
 
 ################################################################################
 
-my $sort;
+
+#TODO: overwrite existing files?
+#TODO: revert in case of error
+#TODO: explore depth>1 in DIRECTORS/
+
+my $db_flag;
 
 # Get options
-GetOptions( "sort"    => \$sort,
+GetOptions( "db"      => \$db_flag,
             "q|quiet" => sub { open LOG, '>', '/dev/null'
                                or die "Cannot open `/dev/null': $!" },
             "man"     => sub { pod2usage(-exitstatus => 0, -verbose => 2) }
@@ -302,13 +327,13 @@ if (&is_symlink($real_new_path)) {
 
     # The destination is under $symlinks
 
-    if (defined $sort) {
+    if (defined $db_flag) {
         # Find the new director on the database
 
         # Ensure there is exactly one entry in the db
-        die "Error: No entry found in the database while the flag `--sort' was set.\n"
+        die "Error: No entry found in the database while the flag `--db' was set.\n"
             if $nRES == 0;
-        die "Error: Multiples entries found in the database while the flag `--sort' was set.\n"
+        die "Error: Multiples entries found in the database while the flag `--db' was set.\n"
             if $nRES > 1;
 
         $new_director = $RES->{$id}->{director};
@@ -373,7 +398,7 @@ if (&is_symlink($real_new_path)) {
         $old_target = $old_path;
         die "Error: `" .$old_path. "' is expected to be a regular file.\n"
             unless -f $old_path;
-        die "Error: Dunno where to put this file. Try the `--sort' flag.\n"
+        die "Error: Dunno where to put this file. Try the `--db' flag.\n"
             unless defined $new_director;
 
         $new_target = catfile ($directors, $new_director, $new_filename);
@@ -462,6 +487,7 @@ unless ($old_filename eq $new_filename) {
 # Disconnect
 $dbh->disconnect();
 
+return $r;
 
 
 ################################################################################