r6200@rob-kinyons-computer-2 (orig r9980): rkinyon | 2007-09-22 21:02:54 -0400
rkinyon [Sun, 23 Sep 2007 02:00:47 +0000 (02:00 +0000)]
 Updates to POD and added a test for POD compliance
 r6201@rob-kinyons-computer-2 (orig r9981):  rkinyon | 2007-09-22 21:56:53 -0400
 Added POD coverage test

MANIFEST
lib/DBM/Deep.pod
lib/DBM/Deep/Cookbook.pod
t/98_pod.t [new file with mode: 0644]
t/99_pod_coverage.t [new file with mode: 0644]

index 95ba4b1..ad92bcd 100644 (file)
--- a/MANIFEST
+++ b/MANIFEST
@@ -57,6 +57,8 @@ t/41_transaction_multilevel.t
 t/42_transaction_indexsector.t
 t/43_transaction_maximum.t
 t/44_upgrade_db.t
+t/98_pod.t
+t/99_pod_coverage.t
 t/common.pm
 t/etc/db-0-983
 t/etc/db-0-99_04
index 57a6151..622130c 100644 (file)
@@ -695,84 +695,34 @@ remove a filter, set the function reference to C<undef>:
 
   $db->set_filter( "filter_store_value", undef );
 
-=head2 Real-time Encryption Example
+=head2 Examples
 
-Here is a working example that uses the I<Crypt::Blowfish> module to
-do real-time encryption / decryption of keys & values with DBM::Deep Filters.
-Please visit L<http://search.cpan.org/search?module=Crypt::Blowfish> for more
-on I<Crypt::Blowfish>. You'll also need the I<Crypt::CBC> module.
+Please read L<DBM::Deep::Manual/> for examples of filters.
 
-  use DBM::Deep;
-  use Crypt::Blowfish;
-  use Crypt::CBC;
-
-  my $cipher = Crypt::CBC->new({
-      'key'             => 'my secret key',
-      'cipher'          => 'Blowfish',
-      'iv'              => '$KJh#(}q',
-      'regenerate_key'  => 0,
-      'padding'         => 'space',
-      'prepend_iv'      => 0
-  });
+=head2 set_filter()
 
-  my $db = DBM::Deep->new(
-      file => "foo-encrypt.db",
-      filter_store_key => \&my_encrypt,
-      filter_store_value => \&my_encrypt,
-      filter_fetch_key => \&my_decrypt,
-      filter_fetch_value => \&my_decrypt,
-  );
-
-  $db->{key1} = "value1";
-  $db->{key2} = "value2";
-  print "key1: " . $db->{key1} . "\n";
-  print "key2: " . $db->{key2} . "\n";
+This method takes two paramters - the filter type and the filter subreference.
+The four types are:
 
-  undef $db;
-  exit;
+=over 4
 
-  sub my_encrypt {
-      return $cipher->encrypt( $_[0] );
-  }
-  sub my_decrypt {
-      return $cipher->decrypt( $_[0] );
-  }
+=item * filter_store_key
 
-=head2 Real-time Compression Example
+This subreference is called when a key is stored in a hash.
 
-Here is a working example that uses the I<Compress::Zlib> module to do real-time
-compression / decompression of keys & values with DBM::Deep Filters.
-Please visit L<http://search.cpan.org/search?module=Compress::Zlib> for
-more on I<Compress::Zlib>.
+=item * filter_store_value
 
-  use DBM::Deep;
-  use Compress::Zlib;
+This subreference is called when a value is stored.
 
-  my $db = DBM::Deep->new(
-      file => "foo-compress.db",
-      filter_store_key => \&my_compress,
-      filter_store_value => \&my_compress,
-      filter_fetch_key => \&my_decompress,
-      filter_fetch_value => \&my_decompress,
-  );
+=item * filter_fetch_key
 
-  $db->{key1} = "value1";
-  $db->{key2} = "value2";
-  print "key1: " . $db->{key1} . "\n";
-  print "key2: " . $db->{key2} . "\n";
+This subreference is called when a key is retrieved fram a hash.
 
-  undef $db;
-  exit;
+=item * filter_fetch_value
 
-  sub my_compress {
-      return Compress::Zlib::memGzip( $_[0] ) ;
-  }
-  sub my_decompress {
-      return Compress::Zlib::memGunzip( $_[0] ) ;
-  }
+This subreference is called when a key is retrieved.
 
-B<Note:> Filtering of keys only applies to hashes. Array "keys" are
-actually numerical index numbers, and are not filtered.
+=back
 
 =head1 ERROR HANDLING
 
@@ -810,7 +760,7 @@ parameters are per-file, meaning you can access 32-bit and 64-bit files, as
 you choose.
 
 B<Note:> We have not personally tested files larger than 4 GB -- all my
-systems have only a 32-bit Perl. However, I have received user reports that
+systems have only a 32-bit Perl. However, we have received user reports that
 this does indeed work.
 
 =head1 LOW-LEVEL ACCESS
@@ -833,55 +783,11 @@ such as enabling/disabling locking. You can also store your own temporary user
 data in this structure (be wary of name collision), which is then accessible from
 any child hash or array.
 
-=head1 CUSTOM DIGEST ALGORITHM
-
-DBM::Deep by default uses the I<Message Digest 5> (MD5) algorithm for hashing
-keys. However you can override this, and use another algorithm (such as SHA-256)
-or even write your own. But please note that DBM::Deep currently expects zero
-collisions, so your algorithm has to be I<perfect>, so to speak. Collision
-detection may be introduced in a later version.
-
-You can specify a custom digest algorithm by passing it into the parameter
-list for new(), passing a reference to a subroutine as the 'digest' parameter,
-and the length of the algorithm's hashes (in bytes) as the 'hash_size'
-parameter. Here is a working example that uses a 256-bit hash from the
-I<Digest::SHA256> module. Please see
-L<http://search.cpan.org/search?module=Digest::SHA256> for more information.
-
-  use DBM::Deep;
-  use Digest::SHA256;
-
-  my $context = Digest::SHA256::new(256);
-
-  my $db = DBM::Deep->new(
-      filename => "foo-sha.db",
-      digest => \&my_digest,
-      hash_size => 32,
-  );
-
-  $db->{key1} = "value1";
-  $db->{key2} = "value2";
-  print "key1: " . $db->{key1} . "\n";
-  print "key2: " . $db->{key2} . "\n";
-
-  undef $db;
-  exit;
-
-  sub my_digest {
-      return substr( $context->hash($_[0]), 0, 32 );
-  }
-
-B<Note:> Your returned digest strings must be B<EXACTLY> the number
-of bytes you specify in the hash_size parameter (in this case 32).
-
-B<Note:> If you do choose to use a custom digest algorithm, you must set it
-every time you access this file. Otherwise, the default (MD5) will be used.
-
 =head1 CIRCULAR REFERENCES
 
-B<NOTE>: DBM::Deep 0.99_03 has turned off circular references pending
+B<NOTE>: DBM::Deep 1.0000 has turned off circular references pending
 evaluation of some edge cases. I hope to be able to re-enable circular
-references in a future version after 1.00. This means that circular references
+references in a future version after 1.0000. This means that circular references
 are B<NO LONGER> available.
 
 DBM::Deep has B<experimental> support for circular references. Meaning you
@@ -904,7 +810,7 @@ a future release.
 
 =head1 TRANSACTIONS
 
-New in 0.99_01 is ACID transactions. Every DBM::Deep object is completely
+New in 1.0000 is ACID transactions. Every DBM::Deep object is completely
 transaction-ready - it is not an option you have to turn on. You do have to
 specify how many transactions may run simultaneously (q.v. L</num_txns>).
 
index 61b8163..b82ad8a 100644 (file)
@@ -26,4 +26,128 @@ In 5.6, you will have to do the following:
 In a future version, you will be able to specify C<utf8 =E<gt> 1> and
 L<DBM::Deep/> will do these things for you.
 
-=end
+=head2 Real-time Encryption Example
+
+Here is a working example that uses the I<Crypt::Blowfish> module to
+do real-time encryption / decryption of keys & values with DBM::Deep Filters.
+Please visit L<http://search.cpan.org/search?module=Crypt::Blowfish> for more
+on I<Crypt::Blowfish>. You'll also need the I<Crypt::CBC> module.
+
+  use DBM::Deep;
+  use Crypt::Blowfish;
+  use Crypt::CBC;
+
+  my $cipher = Crypt::CBC->new({
+      'key'             => 'my secret key',
+      'cipher'          => 'Blowfish',
+      'iv'              => '$KJh#(}q',
+      'regenerate_key'  => 0,
+      'padding'         => 'space',
+      'prepend_iv'      => 0
+  });
+
+  my $db = DBM::Deep->new(
+      file => "foo-encrypt.db",
+      filter_store_key => \&my_encrypt,
+      filter_store_value => \&my_encrypt,
+      filter_fetch_key => \&my_decrypt,
+      filter_fetch_value => \&my_decrypt,
+  );
+
+  $db->{key1} = "value1";
+  $db->{key2} = "value2";
+  print "key1: " . $db->{key1} . "\n";
+  print "key2: " . $db->{key2} . "\n";
+
+  undef $db;
+  exit;
+
+  sub my_encrypt {
+      return $cipher->encrypt( $_[0] );
+  }
+  sub my_decrypt {
+      return $cipher->decrypt( $_[0] );
+  }
+
+=head2 Real-time Compression Example
+
+Here is a working example that uses the I<Compress::Zlib> module to do real-time
+compression / decompression of keys & values with DBM::Deep Filters.
+Please visit L<http://search.cpan.org/search?module=Compress::Zlib> for
+more on I<Compress::Zlib>.
+
+  use DBM::Deep;
+  use Compress::Zlib;
+
+  my $db = DBM::Deep->new(
+      file => "foo-compress.db",
+      filter_store_key => \&my_compress,
+      filter_store_value => \&my_compress,
+      filter_fetch_key => \&my_decompress,
+      filter_fetch_value => \&my_decompress,
+  );
+
+  $db->{key1} = "value1";
+  $db->{key2} = "value2";
+  print "key1: " . $db->{key1} . "\n";
+  print "key2: " . $db->{key2} . "\n";
+
+  undef $db;
+  exit;
+
+  sub my_compress {
+      return Compress::Zlib::memGzip( $_[0] ) ;
+  }
+  sub my_decompress {
+      return Compress::Zlib::memGunzip( $_[0] ) ;
+  }
+
+B<Note:> Filtering of keys only applies to hashes. Array "keys" are
+actually numerical index numbers, and are not filtered.
+
+=head1 Custom Digest Algorithm
+
+DBM::Deep by default uses the I<Message Digest 5> (MD5) algorithm for hashing
+keys. However you can override this, and use another algorithm (such as SHA-256)
+or even write your own. But please note that DBM::Deep currently expects zero
+collisions, so your algorithm has to be I<perfect>, so to speak. Collision
+detection may be introduced in a later version.
+
+You can specify a custom digest algorithm by passing it into the parameter
+list for new(), passing a reference to a subroutine as the 'digest' parameter,
+and the length of the algorithm's hashes (in bytes) as the 'hash_size'
+parameter. Here is a working example that uses a 256-bit hash from the
+I<Digest::SHA256> module. Please see
+L<http://search.cpan.org/search?module=Digest::SHA256> for more information.
+
+  use DBM::Deep;
+  use Digest::SHA256;
+
+  my $context = Digest::SHA256::new(256);
+
+  my $db = DBM::Deep->new(
+      filename => "foo-sha.db",
+      digest => \&my_digest,
+      hash_size => 32,
+  );
+
+  $db->{key1} = "value1";
+  $db->{key2} = "value2";
+  print "key1: " . $db->{key1} . "\n";
+  print "key2: " . $db->{key2} . "\n";
+
+  undef $db;
+  exit;
+
+  sub my_digest {
+      return substr( $context->hash($_[0]), 0, 32 );
+  }
+
+B<Note:> Your returned digest strings must be B<EXACTLY> the number
+of bytes you specify in the hash_size parameter (in this case 32). Undefined
+behavior will occur otherwise.
+
+B<Note:> If you do choose to use a custom digest algorithm, you must set it
+every time you access this file. Otherwise, the default (MD5) will be used.
+
+=cut
diff --git a/t/98_pod.t b/t/98_pod.t
new file mode 100644 (file)
index 0000000..82b971a
--- /dev/null
@@ -0,0 +1,8 @@
+use strict;
+
+use Test::More;
+
+eval "use Test::Pod 1.14";
+plan skip_all => "Test::Pod 1.14 required for testing POD" if $@;
+
+all_pod_files_ok();
diff --git a/t/99_pod_coverage.t b/t/99_pod_coverage.t
new file mode 100644 (file)
index 0000000..0fd3457
--- /dev/null
@@ -0,0 +1,27 @@
+# Only DBM::Deep has any POD to test. All the other classes are private
+# classes. Hence, they have no POD outside of DBM::Deep::Internals
+
+use strict;
+
+use Test::More tests => 1;
+
+eval "use Test::Pod::Coverage 1.04";
+plan skip_all => "Test::Pod::Coverage 1.04 required for testing POD coverage" if $@;
+
+# I don't know why TYPE_ARRAY isn't being caught and TYPE_HASH is.
+my @private_methods = qw(
+    TYPE_ARRAY
+);
+
+# These are method names that have been commented out, for now
+# max_of total_of
+# begin_page end_page
+
+my $private_regex = do {
+    local $"='|';
+    qr/^(?:@private_methods)$/
+};
+
+pod_coverage_ok( 'DBM::Deep' => {
+    also_private => [ $private_regex ],
+});