);
-our $VERSION = '1.7';
+our $VERSION = '1.9.0';
sub AUTOLOAD {
# This AUTOLOAD is used to 'autoload' constants from the constant()
# 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);
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};
}
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);
}
}
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<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.
+
+=item ref_tag_list(name, offset, direction)
-Blah blah blah.
+Convenience for C<tag_list> 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<from> to C<to>.
+=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<name> 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<name> 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<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
+
+=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-E<gt>{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
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
projects / blerg.git / blobdiff