X-Git-Url: http://git.bytex64.net/?a=blobdiff_plain;f=lib%2Fperl%2FBlerg-Database%2Flib%2FBlerg%2FDatabase.pm;h=0101a9df8e0a4a6f12ec48c481c8a4f65d11870f;hb=e6dca775a923fa76d62b3ea420fd8b7bae3c420b;hp=823dc6aa66cbc8bbedc3b25bdbc8f3204b8c8286;hpb=ac2c65c84fed370fb4dc21e40dce5b407e230821;p=blerg.git

diff --git a/lib/perl/Blerg-Database/lib/Blerg/Database.pm b/lib/perl/Blerg-Database/lib/Blerg/Database.pm
index 823dc6a..0101a9d 100644
--- a/lib/perl/Blerg-Database/lib/Blerg/Database.pm
+++ b/lib/perl/Blerg-Database/lib/Blerg/Database.pm
@@ -27,7 +27,7 @@ our @EXPORT = qw(
 	
 );
 
-our $VERSION = '1.7';
+our $VERSION = '1.8.1';
 
 sub AUTOLOAD {
     # This AUTOLOAD is used to 'autoload' constants from the constant()
@@ -57,6 +57,10 @@ XSLoader::load('Blerg::Database', $VERSION);
 
 # Preloaded methods go here.
 
+if (!Blerg::Database::init()) {
+    die "Could not initialize C library";
+}
+
 sub open {
     my ($class, $name) = @_;
     my $ptr = Blerg::Database::_open($name);
@@ -85,7 +89,10 @@ sub _ensure_pointer {
 
 sub close {
     my ($obj) = @_;
-    $obj->_ensure_pointer;
+    if (!(defined $obj && defined $obj->{ptr})) {
+        # Welp, nothing to do here!
+        return;
+    }
     Blerg::Database::_close($obj->{ptr});
     delete $obj->{ptr};
 }
@@ -115,7 +122,8 @@ sub get_subscription_mark {
 
 sub subscription_list {
     my ($obj) = @_;
-    return Blerg::Database::subscription_list($obj->{name});
+    $obj->_ensure_pointer;
+    return Blerg::Database::_subscription_list($obj->{name}, 0, 1);
 }
 
 sub mute {
@@ -166,60 +174,147 @@ sub ref_tag_list {
 
 1;
 __END__
-# Below is stub documentation for your module. You'd better edit it!
 
+=encoding utf8
 =head1 NAME
 
-Blerg::Database - Perl extension for blah blah blah
+Blerg::Database - Perl extension for reading Blërg! databases
 
 =head1 SYNOPSIS
 
   use Blerg::Database;
-  blah blah blah
+
+  my $blerg = Blerg::Database->open_existing('foo');
+  my $record = $blerg->post('This is some data!');
+  $blerg->fetch($record);
 
 =head1 DESCRIPTION
 
-Stub documentation for Blerg::Database, created by h2xs. It looks like the
-author of the extension was negligent enough to leave the stub
-unedited.
+Blerg::Database is a utility library wrapping the core Blërg! database.  It
+provides nicer OO wrappers around the core C library that powers Blërg!.
+
+=head1 MODULE FUNCTIONS
+
+=over
+
+=item exists(name)
+
+Returns 1 if the named database exists, or C<undef> if it doesn't.
+
+=item tag_list(tag, offset, direction)
+
+Returns a list of hashrefs describing blerg posts related to the given tag.
+C<tag> includes the leading '@' or '#'.  Each item has two keys, C<author> and
+C<record>.
+
+=item hash_tag_list(name, offset, direction)
+
+Convenience for C<tag_list> so that you don't have to prepend '#' to the name.
 
-Blah blah blah.
+=item ref_tag_list(name, offset, direction)
 
-=head2 EXPORT
+Convenience for C<tag_list> so that you don't have to prepend '@' to the name.
 
-None by default.
+=item subscription_add(from, to)
 
+Adds a subscription from C<from> to C<to>.
 
-=head1 HISTORY
+=item subscription_remove(from, to)
 
-=over 8
+The opposite of subscription_add.
 
-=item 1.7
+=item valid_tag_name(name)
 
-Original version; created by h2xs 1.23 with options
+Validates that C<name> is a valid tag name.
 
-  -C
-	-b
-	5.8.0
-	-n
-	Blerg::Database
-	-v
-	1.7
+=item valid_name(name)
+
+Validates that C<name> is a valid username.
 
 =back
 
+=head1 CONSTRUCTOR
 
+=over
 
-=head1 SEE ALSO
+=item open(name)
+
+Opens the named database, creating it if it doesn't exist.
+
+=item open_existing(name)
+
+Opens the named database.  If it doesn't exist, returns C<undef>.
+
+=back
+
+=head1 CLASS METHODS
+
+=head2 RECORDS
+
+=over
+
+=item record_count()
+
+Returns the number of records in the database.
+
+=item store(data)
+
+Stores a new record containing C<data>.  Returns the record number of the new
+record.
 
-Mention other useful documentation such as the documentation of
-related modules or operating system documentation (such as man pages
-in UNIX), or any relevant external documentation such as RFCs or
-standards.
+=item fetch(record)
 
-If you have a mailing list set up for your module, mention it here.
+Fetches a record from the database.
 
-If you have a web site set up for your module, mention it here.
+=item timestamp(record)
+
+Returns a unix epoch timestamp for when the record was created.
+
+=back
+
+=head2 SUBSCRIPTIONS
+
+=over
+
+=item set_subscription_mark()
+
+Mark all items on the subscription list as read.
+
+=item get_subscription_mark()
+
+Return the subscription list mark.
+
+=item subscription_list()
+
+Return a list of hashrefs describing posts in your subscription feed.  Each
+hashref has a C<author> and C<record> key.
+
+=back
+
+=head2 REFS, MUTE, CLEANUP
+
+=over
+
+=item refs()
+
+Convenience for listing references to the database.  Equivalent to
+C<tag_list('@' . $obj->{name})>.
+
+=item mute(v)
+
+When v = 1, mute the user, otherwise, unmute.
+
+=item close()
+
+Closes the database.
+
+=back
+
+=head1 SEE ALSO
+
+See the Blërg! website at http://blerg.cc.  More detailed docs about the
+database internals are available in the source repo under www/doc, or at
+http://blerg.cc/doc/
 
 =head1 AUTHOR
 
@@ -233,5 +328,4 @@ This library is free software; you can redistribute it and/or modify
 it under the same terms as Perl itself, either Perl version 5.16.1 or,
 at your option, any later version of Perl 5 you may have available.
 
-
 =cut