From 632d3de34ccfdc6438583d38e8a70fdbf02a5154 Mon Sep 17 00:00:00 2001
From: Marius Gavrilescu <marius@ieval.ro>
Date: Sat, 9 Dec 2017 20:07:16 +0200
Subject: [PATCH] Better new + doc

---
 lib/Slob.pm | 70 +++++++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 68 insertions(+), 2 deletions(-)

diff --git a/lib/Slob.pm b/lib/Slob.pm
index 8298bec..4b796cb 100644
--- a/lib/Slob.pm
+++ b/lib/Slob.pm
@@ -12,7 +12,10 @@ use Encode;
 
 sub new {
 	my ($class, $path) = @_;
-	open my $fh, '<', $path or croak "Cannot open \"$path\": $!";
+	my $fh =
+	  ref $path eq 'IO'
+	  ? $path
+	  :  open my $fh, '<', $path or croak "Cannot open \"$path\": $!";
 	my $self = bless {path => $path, fh => $fh}, $class;
 	$self->{header} = $self->read_header;
 	$self
@@ -241,7 +244,70 @@ Slob - Read .slob dictionaries (as used by Aard 2)
 
 =head1 DESCRIPTION
 
-No documentation yet, see SYNOPSIS.
+Slob is a compressed read-only format for storing natural language
+dictionaries. It is used in Aard 2. C<Slob.pm> is a module that reads
+dictionaries in slob format.
+
+The following methods are available:
+
+=over
+
+=item Slob->B<new>(I<$path>)
+=item Slob->B<new>(I<$fh>)
+
+Create a new slob reader reading from the given path or filehandle.
+
+=item $slob->B<ref_count>
+
+The number of refs (keys) in the dictionary.
+
+=item $slob->B<seek_and_read_ref>(I<$index>)
+
+Read the ref (key) at the given index. Returns a hashref with the
+following keys:
+
+=over
+
+=item key
+
+The key
+
+=item bin_index
+
+The storage bin that contains the value for this key
+
+=item item_index
+
+The index in the bin_index storage bin of the value for this key
+
+=item fragment
+
+HTML fragment that, when applied to the HTML value, points to the
+definition of the key.
+
+=back
+
+=item $slob->B<seek_and_read_storage_bin>(I<$index>)
+
+Read the storage bin with the given index. Returns the storage bin,
+which can later be given to B<get_entry_of_storage_bin>.
+
+=item $slob->B<get_entry_of_storage_bin>(I<$bin>, I<$index>)
+
+Given a storage bin (as returned by C<seek_and_read_storage_bin>) and
+item index, returns the value at the index i nthe storage bin.
+
+=item $slob->B<seek_and_read_ref_and_data>($index)
+
+Convenience method that returns the key and value at a given index.
+Returns a hashref like C<seek_and_read_ref> with an extra key,
+I<data>, which is the value of the key.
+
+=back
+
+=head1 SEE ALSO
+
+L<https://github.com/itkach/slob>
 
 =head1 AUTHOR
 
-- 
2.39.2