X-Git-Url: http://git.bytex64.net/?a=blobdiff_plain;f=lib%2Fperl%2FBlerg-Database%2Flib%2FBlerg%2FDatabase.pm;h=8d3789ab811f89a0de5dce24393394f8bef24a7c;hb=d67dd1bf5a247e20141b9907f5a452da73624235;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..8d3789a 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,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,16 +122,27 @@ 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 { my ($obj, $v) = @_; $obj->_ensure_pointer; if (defined $v) { - return Blerg::Database::_set_mute($obj->{ptr}, $v); + return Blerg::Database::_set_status($obj->{ptr}, $obj->BLERGSTATUS_MUTED, $v); + } else { + return Blerg::Database::_get_status($obj->{ptr}, $obj->BLERGSTATUS_MUTED); + } +} + +sub mention { + my ($obj, $v) = @_; + $obj->_ensure_pointer; + if (defined $v) { + return Blerg::Database::_set_status($obj->{ptr}, $obj->BLERGSTATUS_MENTIONED, $v); } else { - return Blerg::Database::_get_mute($obj->{ptr}); + return Blerg::Database::_get_status($obj->{ptr}, $obj->BLERGSTATUS_MENTIONED); } } @@ -166,60 +184,214 @@ sub ref_tag_list { 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 + +=head2 GENERAL + +=over + +=item exists(name) + +Returns 1 if the named database exists, or C if it doesn't. + +=item tag_list(tag, offset, direction) + +Returns a list of hashrefs describing blerg posts related to the given tag. +C includes the leading '@' or '#'. Each item has two keys, C and +C. + +=item hash_tag_list(name, offset, direction) + +Convenience for C so that you don't have to prepend '#' to the name. + +=item ref_tag_list(name, offset, direction) -Blah blah blah. +Convenience for C so that you don't have to prepend '@' to the name. -=head2 EXPORT +=item subscription_add(from, to) -None by default. +Adds a subscription from C to C. +=item subscription_remove(from, to) -=head1 HISTORY +The opposite of subscription_add. -=over 8 +=item valid_tag_name(name) -=item 1.7 +Validates that C is a valid tag name. -Original version; created by h2xs 1.23 with options +=item valid_name(name) - -C - -b - 5.8.0 - -n - Blerg::Database - -v - 1.7 +Validates that C is a valid username. + +=item configuration() + +Returns a hashref containing runtime configuration information. Contains these fields: + +=over + +=item base_path + +The base path to the Blërg database + +=item data_path + +The path under base_path for account data + +=item hash_tags_path + +The path under base_path for hashtag data + +=item ref_tags_path + +The path under base_path for mention data =back +=back +=head2 AUTHENTICATION -=head1 SEE ALSO +=over + +=item auth_set_password(username, password) + +Sets the password for the given username. Returns 1 on success, 0 otherwise. + +=item auth_check_password(username, password) + +Checks the password for the given username. Returns 1 on successful +authentication, 0 on failed authentication or error. + +=item auth_login(username, password) -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. +Authenticates and logs the user in. Returns the authentication token if +successful, or undef on failure or error. -If you have a mailing list set up for your module, mention it here. +=item auth_logout(username, token) -If you have a web site set up for your module, mention it here. +Logs the given user out if the token represents a valid session. Returns 1 on +success, or 0 on failure. Failure can happen if the token is no longer valid +(meaning the user has been automatically logged out), so the return status is +probably best ignored.. + +=item auth_check_token(username, token) + +Checks that the token represents a valid session for the given username. +Returns 1 if the session is valid, 0 otherwise. Also resets the expiration +time of the session. + +=item auth_get_counter(username) + +Gets an opaque "counter" value for the auth information of the given username. +This counter is changed every time the authentication information is changed, +making it useful for protecting password changes against replay attacks. +Returns a 32-bit integer on success, or undef on failure. + +=back + +=head1 CONSTRUCTOR + +=over + +=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. + +=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. 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 + +=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 and C key. + +=back + +=head2 REFS, MUTE, CLEANUP + +=over + +=item refs() + +Convenience for listing references to the database. Equivalent to +C{name})>. + +=item mute(v) + +When v = 1, mute the user, otherwise, unmute. If v is absent, return the mute status. + +=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 +405,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