Read Me

shnflac-verify contains two scripts both of which
need perl to run.  They are designed to help make
the verification of shn/flac music filesets easier
and faster in bulk.  These scripts run from the 
command line, so on Windows that means dos. See
the "USAGE" sections for how to run each script
from the command line.  Please see the "DEPENDENCIES" 
sections below for each script since they rely on 
tools you'll need to specify by editing the script.

Installing perl 5.8+:

On Windows: ActiveState Perl is the most common way
to go.  You can download perl here:
http://www.activestate.com/Products/activeperl/index.mhtml

On Mac OS X: perl should already be installed.  Open a
terminal and type: perl -v to see what version you have.

On Linux/Cygwin:  use your package managers to install
perl 5.10+.

==================================================
shnflac-verify.pl
==================================================
This script is designed to test FLAC and SHN files 
for conformance to checksums as well as internal 
integrity checks.  The script takes a path (absolute 
or relative) as an input.  By default, the script 
will traverse the input path looking for directories 
that start with the "gdYY*", where YY is meant to 
be a year designator (gdYY and gdYYYY directories 
will both work). 

SHN FILES:
---------------------------------------------
SHN files are have md5sums calculated and verified 
against any .md5 files in the directories.  
shntool md5s are also verified against any .st5
files in the directory.  Composite shntool 
fingerprints are verified against any .cfp files
in the directory.  The scope of the md5 and st5 
checksum files are checked as well to make sure 
that there aren't SHN files in the directory not 
covered by the checksum files.

FLAC FILES:
----------------------------------------------
FLAC files have md5sums checked (like SHN) files.  
They also have their FLAC fingerprints checked 
against any fingerprints stored in .ffp files,
and shntool md5 checksums stored in .st5 files.
Composite shntool fingerprints are verified 
against any .cfp files in the directory.    
The scope of all md5, ffp, and st5 files is checked
to make sure that there aren't FLAC files in the
directory not covered by the checksum files.  
Lastly, FLAC files are tested for internal 
integrity using flac's --test flag.  

OPTIONS:
---------------------------------------------
Option flags are taken prior to the path in 
command line usage.  Current options include:

  --single, -s: use this flag if you're looking 
  to verify just a single flac/shn fileset.  
  When this flag is set, the path inputed is not 
  traversed recursively.

  --no-test, -not:  use this flag if you wish to 
  skip the internal flac file integrity tests.
  
  --case, -cs: by default, coverage checking
  is not case sensitive.  Use this option for case
  sensitive coverage tests.

  --no-md5, -nom:  use this flag to skip md5 checks.  
  Note, no checks on SHN files will be made.

  --no-ffp, -nof:  use this flag to skip ffp verification.
  
  --no-st5:  use this flag to skip st5 verification.
  
  --no-cfp:  use this flag to skip cfp verification.

  --pattern=regex, -p:  use this flag to override 
  the default directory pattern matching.  Uses 
  standard regular expressions.  See example below. 
  
DEPENDENCIES:
--------------------------------------------
This script relies on and serves as a wrapper for
several command line tools including md5sum, shntool,
metaflac and flac.  These tools are available under Windows 
and Unix-like systems.  Unix folks will likely know 
how to find these.  On Windows you'll need to download:
 md5sum.exe: http://etree.org/md5com.html

 flac.exe and metaflac.exe: http://flac.sourceforge.net/download.html

 shntool.exe: http://www.etree.org/shnutils/shntool/
 
Once downloaded, set the location of these files in 
the paths section of this script.

USAGE:
---------------------------------------------
Example - traverse a directory tree looking checking 
any filesets that exist under the path (relative or absolute):
  perl shnflac-verify.pl path/to/yourdir/
  
Example - find directories starting with paf followed 
by a two digit year:
  perl shnflac-verify.pl --pattern=^paf\\\\d\\\\d
  
Example - test a single seed, skipping ffp verifications 
and flac integrity checks:
  perl shnflac-verify.pl --single --no-ffp --no-test path/to/gdYYseed/
  
CREDITS:
Originally written by Dr. Unclear, distributed 
under the GPL license.

==================================================
etree-verify.pl
==================================================
This script is designed to traverse a directory
containing shn or flac filesets and downloads
checksum and info text files from db.etree.org 
for any fileset with a discernable shnid.  
Why? It is recommended before any file set is seeded that 
you verify the file set against checksums from 
db.etree.org to make absolutely sure you're not 
seeding a file set with errors.  This script aims 
to facilitate that checking process.

By default, the script will traverse the input path 
looking for directories that start with the "gdYY*", 
where YY is meant to be a year designator (gdYY and 
gdYYYY directories will both work).  You can
override the default with the --pattern= option 
(see below).

This script should run on Windows, Mac OS X, Linux,
Cygwin, or just about any OS with perl installed.

OPTIONS:
---------------------------------------------
Option flags are taken prior to the path in 
command line usage.  Current options include:

  --single, -s: use this flag if you're looking 
  to verify just a single flac/shn fileset.  
  When this flag is set, the path inputed is not 
  traversed recursively.

  --wav, -w: by default, this script will skip
  wav md5s.  If you include this option, wav md5s
  will not be skipped.
  
  --delete, -d: by default, your existing text and
  checksum files are preserved.  Adding this flag
  deletes your existing text and checksum files before
  extracting the new ones from db.etree.org.  Note,
  any text file with "shntool" in the name is 
  preserved, even with this option.

  --pattern=regex, -p:  use this flag to override 
  the default directory pattern matching.  Uses 
  standard regular expressions.  See example below. 
  
DEPENDENCIES:
--------------------------------------------
This script relies on info-zip's "unzip" tool. You
may already have this tool on your computer, so 
open a command prompt/terminal and type "unzip"
to see if you do.

If not, this tool can be downloaded from:
http://www.info-zip.org/

On Windows 32-bit platforms, you can download 
and extract:
ftp://tug.ctan.org/tex-archive/tools/zip/info-zip/WIN32/unz552xN.exe
See the website for other platforms.

Once downloaded and extracted, find the "unzip" program
itself.  On Win 32 this is "unzip.exe".  Then
edit this script and modify the location of unzip to 
match the location on your computer. 

USAGE:
---------------------------------------------
Example - traverse a directory tree updating
checksums from db.etree.org that exist under the path:
  perl etree-verify.pl (/)path/to/yourdir/
  
Example - find directories starting with paf followed 
by a two digit year:
  perl etree-verify.pl --pattern=^paf\\\\d\\\\d
  
Example - test a single seed, and include wav 
md5s, delete existing checksums and info texts:
  perl etree-verify.pl --single --wav --delete path/to/gdYYseed/
  
CREDITS:
Originally written by Dr. Unclear, distributed 
under the GPL license.