X-Git-Url: http://git.bytex64.net/?a=blobdiff_plain;f=lib%2Fperl%2FBlerg-Database%2Flib%2FBlerg%2FDatabase.pm;h=d71340d822105d68b07a73db246c29a46927986c;hb=74799006801178ec48185e2e058772b876920d5d;hp=3da5ad3f898e6001d20b63185725a06b5dcdc9c8;hpb=2016f2b13cfb48bea6d6d0498fe2a4492b491bf2;p=blerg.git

diff --git a/lib/perl/Blerg-Database/lib/Blerg/Database.pm b/lib/perl/Blerg-Database/lib/Blerg/Database.pm
index 3da5ad3..d71340d 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.9.0';
 
 sub AUTOLOAD {
     # This AUTOLOAD is used to 'autoload' constants from the constant()
@@ -57,11 +57,16 @@ 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);
     my $obj = {
-        ptr => $ptr
+        ptr => $ptr,
+        name => $name,
     };
     return bless $obj, $class;
 }
@@ -70,7 +75,7 @@ sub open_existing {
     my ($class, $name) = @_;
 
     if (Blerg::Database::exists($name)) {
-        return Blerg::Database::open($name);
+        return Blerg::Database->open($name);
     }
     return undef;
 }
@@ -84,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};
 }
@@ -94,6 +102,45 @@ DESTROY {
     $obj->close;
 }
 
+sub record_count {
+    my ($obj) = @_;
+    $obj->_ensure_pointer;
+    return Blerg::Database::_get_record_count($obj->{ptr});
+}
+
+sub set_subscription_mark {
+    my ($obj) = @_;
+    $obj->_ensure_pointer;
+    return Blerg::Database::_set_subscription_mark($obj->{ptr});
+}
+
+sub get_subscription_mark {
+    my ($obj) = @_;
+    $obj->_ensure_pointer;
+    return Blerg::Database::_get_subscription_mark($obj->{ptr});
+}
+
+sub subscription_list {
+    my ($obj) = @_;
+    $obj->_ensure_pointer;
+    return Blerg::Database::_subscription_list($obj->{name}, 0, 1);
+}
+
+sub mute {
+    my ($obj, $v) = @_;
+    $obj->_ensure_pointer;
+    if (defined $v) {
+        return Blerg::Database::_set_mute($obj->{ptr}, $v);
+    } else {
+        return Blerg::Database::_get_mute($obj->{ptr});
+    }
+}
+
+sub refs {
+    my ($obj) = @_;
+    return Blerg::Database::tag_list('@' . $obj->{name}, 50, -1);
+}
+
 sub store {
     my ($obj, $data) = @_;
     $obj->_ensure_pointer;
@@ -106,64 +153,169 @@ sub fetch {
     return Blerg::Database::_fetch($obj->{ptr}, $record);
 }
 
+sub timestamp {
+    my ($obj, $record) = @_;
+    $obj->_ensure_pointer;
+    return Blerg::Database::_get_timestamp($obj->{ptr}, $record);
+}
+
+# Convenience shortcuts
+sub hash_tag_list {
+    my ($name, $str_offset, $direction) = @_;
+    return Blerg::Database::tag_list("#$name", $str_offset, $direction);
+}
+
+sub ref_tag_list {
+    my ($name, $str_offset, $direction) = @_;
+    return Blerg::Database::tag_list("@$name", $str_offset, $direction);
+}
+
 # Autoload methods go after =cut, and are processed by the autosplit program.
 
 1;
 __END__
-# Below is stub documentation for your module. You'd better edit it!
 
 =head1 NAME
 
-Blerg::Database - Perl extension for blah blah blah
+=encoding utf8
+
+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>.
 
-Blah blah blah.
+=item hash_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 ref_tag_list(name, offset, direction)
 
+Convenience for C<tag_list> so that you don't have to prepend '@' to the name.
 
-=head1 HISTORY
+=item subscription_add(from, to)
 
-=over 8
+Adds a subscription from C<from> to C<to>.
 
-=item 1.7
+=item subscription_remove(from, to)
 
-Original version; created by h2xs 1.23 with options
+The opposite of subscription_add.
 
-  -C
-	-b
-	5.8.0
-	-n
-	Blerg::Database
-	-v
-	1.7
+=item valid_tag_name(name)
+
+Validates that C<name> is a valid tag name.
+
+=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.
+
+=item fetch(record)
+
+Fetches a record from the database.
+
+=item timestamp(record)
+
+Returns a unix epoch timestamp for when the record was created.
+
+=back
 
-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.
+=head2 SUBSCRIPTIONS
 
-If you have a mailing list set up for your module, mention it here.
+=over
 
-If you have a web site set up for your module, mention it here.
+=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-E<gt>{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
 
@@ -177,5 +329,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