Add documentation for Blerg::Database
);
-our $VERSION = '1.7';
+our $VERSION = '1.8.1';
sub AUTOLOAD {
# This AUTOLOAD is used to 'autoload' constants from the constant()
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>.
-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.
-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 timestamp(record)
-If you have a mailing list set up for your module, mention it here.
+Returns a unix epoch timestamp for when the record was created.
-If you have a web site set up for your module, mention it here.
+=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
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