add blerg_init to blerg.a consumers

[blerg.git] / lib / perl / Blerg-Database / lib / Blerg / Database.pm

diff --git a/lib/perl/Blerg-Database/lib/Blerg/Database.pm b/lib/perl/Blerg-Database/lib/Blerg/Database.pm
index b05c7f9..0101a9d 100644 (file)
--- 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);
@@ -170,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.
 
-Blah blah blah.
+=item tag_list(tag, offset, direction)
 
-=head2 EXPORT
+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>.
 
-None by default.
+=item hash_tag_list(name, offset, direction)
 
+Convenience for C<tag_list> so that you don't have to prepend '#' to the name.
 
-=head1 HISTORY
+=item ref_tag_list(name, offset, direction)
 
-=over 8
+Convenience for C<tag_list> so that you don't have to prepend '@' to the name.
 
-=item 1.7
+=item subscription_add(from, to)
 
-Original version; created by h2xs 1.23 with options
+Adds a subscription from C<from> to C<to>.
 
-  -C
-       -b
-       5.8.0
-       -n
-       Blerg::Database
-       -v
-       1.7
+=item subscription_remove(from, to)
+
+The opposite of subscription_add.
+
+=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)
 
-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.
+Fetches a record from the database.
 
-If you have a mailing list set up for your module, mention it here.
+=item timestamp(record)
 
-If you have a web site set up for your module, mention it here.
+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
 
@@ -237,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