NAME

Blerg::Database - Perl extension for reading Blërg! databases

SYNOPSIS

  use Blerg::Database;

  my $blerg = Blerg::Database->open_existing('foo');
  my $record = $blerg->post('This is some data!');
  $blerg->fetch($record);

DESCRIPTION

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!.

MODULE FUNCTIONS

GENERAL

exists(name)

Returns 1 if the named database exists, or undef if it doesn't.

tag_list(tag, offset, direction)

Returns a list of hashrefs describing blerg posts related to the given tag. tag includes the leading '@' or '#'. Each item has two keys, author and record.

hash_tag_list(name, offset, direction)

Convenience for tag_list so that you don't have to prepend '#' to the name.

ref_tag_list(name, offset, direction)

Convenience for tag_list so that you don't have to prepend '@' to the name.

subscription_add(from, to)

Adds a subscription from from to to.

subscription_remove(from, to)

The opposite of subscription_add.

valid_tag_name(name)

Validates that name is a valid tag name.

valid_name(name)

Validates that name is a valid username.

configuration()

Returns a hashref containing runtime configuration information. Contains these fields:

base_path: The base path to the Blërg database
data_path: The path under base_path for account data
hash_tags_path: The path under base_path for hashtag data
ref_tags_path: The path under base_path for mention data

AUTHENTICATION

auth_set_password(username, password): Sets the password for the given username. Returns 1 on success, 0 otherwise.
auth_check_password(username, password): Checks the password for the given username. Returns 1 on successful authentication, 0 on failed authentication or error.
auth_login(username, password): Authenticates and logs the user in. Returns the authentication token if successful, or undef on failure or error.
auth_logout(username, token): 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..
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.
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.

CONSTRUCTOR

open(name): Opens the named database, creating it if it doesn't exist.
open_existing(name): Opens the named database. If it doesn't exist, returns undef.

CLASS METHODS

RECORDS

record_count(): Returns the number of records in the database.
store(data): Stores a new record containing data. Returns the record number of the new record.
fetch(record): Fetches a record from the database.
timestamp(record): Returns a unix epoch timestamp for when the record was created.

SUBSCRIPTIONS

set_subscription_mark(): Mark all items on the subscription list as read.
get_subscription_mark(): Return the subscription list mark.
subscription_list(): Return a list of hashrefs describing posts in your subscription feed. Each hashref has a author and record key.

REFS, MUTE, CLEANUP

refs(): Convenience for listing references to the database. Equivalent to tag_list('@' . $obj->{name}).
mute(v): When v = 1, mute the user, otherwise, unmute. If v is absent, return the mute status.
close(): Closes the database.

AUTHOR

Chip Black, <bytex64@bytex64.net>

COPYRIGHT AND LICENSE

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.