Added supports() and rewrote the tests so that Engine::DBI doesn't run the transactio...

[dbsrgits/DBM-Deep.git] / lib / DBM / Deep.pod

diff --git a/lib/DBM/Deep.pod b/lib/DBM/Deep.pod
index 7252f7c..6d0a263 100644 (file)
--- a/lib/DBM/Deep.pod
+++ b/lib/DBM/Deep.pod
@@ -156,14 +156,14 @@ one of these two constants:
 
 =over 4
 
-=item * C<DBM::Deep-E<gt>TYPE_HASH>
+=item * C<<DBM::Deep->TYPE_HASH>>
 
-=item * C<DBM::Deep-E<gt>TYPE_ARRAY>.
+=item * C<<DBM::Deep->TYPE_ARRAY>>
 
 =back
 
 This only takes effect when beginning a new file. This is an optional
-parameter, and defaults to C<DBM::Deep-E<gt>TYPE_HASH>.
+parameter, and defaults to C<<DBM::Deep->TYPE_HASH>>.
 
 =item * locking
 
@@ -309,7 +309,7 @@ assign a temporary variable to C<$db->{foo}>, then pass that to each().
 As with hashes, you can treat any DBM::Deep object like a normal Perl array
 reference. This includes inserting, removing and manipulating elements,
 and the C<push()>, C<pop()>, C<shift()>, C<unshift()> and C<splice()> functions.
-The object must have first been created using type C<DBM::Deep-E<gt>TYPE_ARRAY>,
+The object must have first been created using type C<<DBM::Deep->TYPE_ARRAY>>,
 or simply be a nested array reference inside a hash. Example:
 
   my $db = DBM::Deep->new(
@@ -321,9 +321,9 @@ or simply be a nested array reference inside a hash. Example:
   push @$db, "bar", "baz";
   unshift @$db, "bah";
 
-  my $last_elem = pop @$db; # baz
-  my $first_elem = shift @$db; # bah
-  my $second_elem = $db->[1]; # bar
+  my $last_elem   = pop @$db;   # baz
+  my $first_elem  = shift @$db; # bah
+  my $second_elem = $db->[1];   # bar
 
   my $num_elements = scalar @$db;
 
@@ -385,7 +385,7 @@ value.
 
   $db->clear(); # hashes or arrays
 
-=item * lock_exclusive() / lock_shared() / lock() / unlock()
+=item * lock() / unlock() / lock_exclusive() / lock_shared()
 
 q.v. L</LOCKING> for more info.
 
@@ -412,6 +412,17 @@ This copy is in RAM, not on disk like the DB is.
 
 These are the transactional functions. L</TRANSACTIONS> for more information.
 
+=item * supports( $option )
+
+This returns a boolean depending on if this instance of DBM::Dep supports
+that feature. C<$option> can be one of:
+
+=over 4
+
+=item * transactions
+
+=back
+
 =back
 
 =head2 Hashes
@@ -555,12 +566,12 @@ NFS> below for more.
 =head2 Explicit Locking
 
 You can explicitly lock a database, so it remains locked for multiple
-actions. This is done by calling the C<lock()> method, and passing an
-optional lock mode argument (defaults to exclusive mode). This is particularly
-useful for things like counters, where the current value needs to be fetched,
-then incremented, then stored again.
+actions. This is done by calling the C<lock_exclusive()> method (for when you
+want to write) or the C<lock_shared()> method (for when you want to read).
+This is particularly useful for things like counters, where the current value
+needs to be fetched, then incremented, then stored again.
 
-  $db->lock();
+  $db->lock_exclusive();
   my $counter = $db->get("counter");
   $counter++;
   $db->put("counter", $counter);
@@ -568,13 +579,10 @@ then incremented, then stored again.
 
   # or...
 
-  $db->lock();
+  $db->lock_exclusive();
   $db->{counter}++;
   $db->unlock();
 
-If you want a shared lock, you will need to call C<lock_shared()>. C<lock()> is
-an alias to C<lock_exclusive()>.
-
 =head2 Win32/Cygwin
 
 Due to Win32 actually enforcing the read-only status of a shared lock, all
@@ -731,7 +739,7 @@ DBM::Deep by default uses 32-bit file offset tags, but these can be changed
 by specifying the 'pack_size' parameter when constructing the file.
 
   DBM::Deep->new(
-      filename  => $filename,
+      file      => $filename,
       pack_size => 'large',
   );
 
@@ -739,7 +747,7 @@ This tells DBM::Deep to pack all file offsets with 8-byte (64-bit) quad words
 instead of 32-bit longs. After setting these values your DB files have a
 theoretical maximum size of 16 XB (exabytes).
 
-You can also use C<pack_size =E<gt> 'small'> in order to use 16-bit file
+You can also use C<<pack_size => 'small'>> in order to use 16-bit file
 offsets.
 
 B<Note:> Changing these values will B<NOT> work for existing database files.
@@ -949,7 +957,7 @@ the reference. Again, this would generally be considered a feature.
 
 =head2 External references and transactions
 
-If you do C<my $x = $db-E<gt>{foo};>, then start a transaction, $x will be
+If you do C<<my $x = $db->{foo};>>, then start a transaction, $x will be
 referencing the database from outside the transaction. A fix for this (and other
 issues with how external references into the database) is being looked into. This
 is the skipped set of tests in t/39_singletons.t and a related issue is the focus
@@ -1048,7 +1056,7 @@ Check out the DBM::Deep Google Group at L<http://groups.google.com/group/DBM-Dee
 or send email to L<DBM-Deep@googlegroups.com>. You can also visit #dbm-deep on
 irc.perl.org
 
-The source code repository is at L<http://svn.perl.org/modules/DBM-Deep>
+The source code repository is at L<http://github.com/robkinyon/dbm-deep>
 
 =head1 MAINTAINERS