1 package Blerg::Database;
11 our @ISA = qw(Exporter);
13 # Items to export into callers namespace by default. Note: do not export
14 # names by default without a very good reason. Use EXPORT_OK instead.
15 # Do not simply export all your public functions/methods/constants.
17 # This allows declaration use Blerg::Database ':all';
18 # If you do not need this, moving things directly into @EXPORT or @EXPORT_OK
20 our %EXPORT_TAGS = ( 'all' => [ qw(
24 our @EXPORT_OK = ( @{ $EXPORT_TAGS{'all'} } );
30 our $VERSION = '1.9.0';
33 # This AUTOLOAD is used to 'autoload' constants from the constant()
38 ($constname = $AUTOLOAD) =~ s/.*:://;
39 croak "&Blerg::Database::constant not defined" if $constname eq 'constant';
40 my ($error, $val) = constant($constname);
41 if ($error) { croak $error; }
44 # Fixed between 5.005_53 and 5.005_61
45 #XXX if ($] >= 5.00561) {
46 #XXX *$AUTOLOAD = sub () { $val };
49 *$AUTOLOAD = sub { $val };
56 XSLoader::load('Blerg::Database', $VERSION);
58 # Preloaded methods go here.
60 if (!Blerg::Database::init()) {
61 die "Could not initialize C library";
65 my ($class, $name) = @_;
66 my $ptr = Blerg::Database::_open($name);
71 return bless $obj, $class;
75 my ($class, $name) = @_;
77 if (Blerg::Database::exists($name)) {
78 return Blerg::Database->open($name);
85 if (!defined $obj->{ptr}) {
86 croak "Attempted to use closed Blerg::Database";
92 if (!(defined $obj && defined $obj->{ptr})) {
93 # Welp, nothing to do here!
96 Blerg::Database::_close($obj->{ptr});
107 $obj->_ensure_pointer;
108 return Blerg::Database::_get_record_count($obj->{ptr});
111 sub set_subscription_mark {
113 $obj->_ensure_pointer;
114 return Blerg::Database::_set_subscription_mark($obj->{ptr});
117 sub get_subscription_mark {
119 $obj->_ensure_pointer;
120 return Blerg::Database::_get_subscription_mark($obj->{ptr});
123 sub subscription_list {
125 $obj->_ensure_pointer;
126 return Blerg::Database::_subscription_list($obj->{name}, 0, -1);
131 $obj->_ensure_pointer;
133 return Blerg::Database::_set_status($obj->{ptr}, $obj->BLERGSTATUS_MUTED, $v);
135 return Blerg::Database::_get_status($obj->{ptr}, $obj->BLERGSTATUS_MUTED);
141 $obj->_ensure_pointer;
143 return Blerg::Database::_set_status($obj->{ptr}, $obj->BLERGSTATUS_MENTIONED, $v);
145 return Blerg::Database::_get_status($obj->{ptr}, $obj->BLERGSTATUS_MENTIONED);
151 return Blerg::Database::tag_list('@' . $obj->{name}, 50, -1);
155 my ($obj, $data) = @_;
156 $obj->_ensure_pointer;
157 return Blerg::Database::_store($obj->{ptr}, $data);
161 my ($obj, $record) = @_;
162 $obj->_ensure_pointer;
163 return Blerg::Database::_fetch($obj->{ptr}, $record);
167 my ($obj, $record) = @_;
168 $obj->_ensure_pointer;
169 return Blerg::Database::_get_timestamp($obj->{ptr}, $record);
172 # Convenience shortcuts
174 my ($name, $str_offset, $direction) = @_;
175 return Blerg::Database::tag_list("#$name", $str_offset, $direction);
179 my ($name, $str_offset, $direction) = @_;
180 return Blerg::Database::tag_list("@$name", $str_offset, $direction);
183 # Autoload methods go after =cut, and are processed by the autosplit program.
192 Blerg::Database - Perl extension for reading Blërg! databases
198 my $blerg = Blerg::Database->open_existing('foo');
199 my $record = $blerg->post('This is some data!');
200 $blerg->fetch($record);
204 Blerg::Database is a utility library wrapping the core Blërg! database. It
205 provides nicer OO wrappers around the core C library that powers Blërg!.
207 =head1 MODULE FUNCTIONS
215 Returns 1 if the named database exists, or C<undef> if it doesn't.
217 =item tag_list(tag, offset, direction)
219 Returns a list of hashrefs describing blerg posts related to the given tag.
220 C<tag> includes the leading '@' or '#'. Each item has two keys, C<author> and
223 =item hash_tag_list(name, offset, direction)
225 Convenience for C<tag_list> so that you don't have to prepend '#' to the name.
227 =item ref_tag_list(name, offset, direction)
229 Convenience for C<tag_list> so that you don't have to prepend '@' to the name.
231 =item subscription_add(from, to)
233 Adds a subscription from C<from> to C<to>.
235 =item subscription_remove(from, to)
237 The opposite of subscription_add.
239 =item valid_tag_name(name)
241 Validates that C<name> is a valid tag name.
243 =item valid_name(name)
245 Validates that C<name> is a valid username.
247 =item configuration()
249 Returns a hashref containing runtime configuration information. Contains these fields:
255 The base path to the Blërg database
259 The path under base_path for account data
263 The path under base_path for hashtag data
267 The path under base_path for mention data
273 =head2 AUTHENTICATION
277 =item auth_set_password(username, password)
279 Sets the password for the given username. Returns 1 on success, 0 otherwise.
281 =item auth_check_password(username, password)
283 Checks the password for the given username. Returns 1 on successful
284 authentication, 0 on failed authentication or error.
286 =item auth_login(username, password)
288 Authenticates and logs the user in. Returns the authentication token if
289 successful, or undef on failure or error.
291 =item auth_logout(username, token)
293 Logs the given user out if the token represents a valid session. Returns 1 on
294 success, or 0 on failure. Failure can happen if the token is no longer valid
295 (meaning the user has been automatically logged out), so the return status is
296 probably best ignored..
298 =item auth_check_token(username, token)
300 Checks that the token represents a valid session for the given username.
301 Returns 1 if the session is valid, 0 otherwise. Also resets the expiration
304 =item auth_get_counter(username)
306 Gets an opaque "counter" value for the auth information of the given username.
307 This counter is changed every time the authentication information is changed,
308 making it useful for protecting password changes against replay attacks.
309 Returns a 32-bit integer on success, or undef on failure.
319 Opens the named database, creating it if it doesn't exist.
321 =item open_existing(name)
323 Opens the named database. If it doesn't exist, returns C<undef>.
335 Returns the number of records in the database.
339 Stores a new record containing C<data>. Returns the record number of the new
344 Fetches a record from the database.
346 =item timestamp(record)
348 Returns a unix epoch timestamp for when the record was created.
356 =item set_subscription_mark()
358 Mark all items on the subscription list as read.
360 =item get_subscription_mark()
362 Return the subscription list mark.
364 =item subscription_list()
366 Return a list of hashrefs describing posts in your subscription feed. Each
367 hashref has a C<author> and C<record> key.
371 =head2 REFS, MUTE, CLEANUP
377 Convenience for listing references to the database. Equivalent to
378 C<tag_list('@' . $obj-E<gt>{name})>.
382 When v = 1, mute the user, otherwise, unmute. If v is absent, return the mute status.
392 See the Blërg! website at http://blerg.cc. More detailed docs about the
393 database internals are available in the source repo under www/doc, or at
398 Chip Black, E<lt>bytex64@bytex64.netE<gt>
400 =head1 COPYRIGHT AND LICENSE
402 Copyright (C) 2013 by Chip Black
404 This library is free software; you can redistribute it and/or modify
405 it under the same terms as Perl itself, either Perl version 5.16.1 or,
406 at your option, any later version of Perl 5 you may have available.