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.
249 =head2 AUTHENTICATION
253 =item auth_set_password(username, password)
255 Sets the password for the given username. Returns 1 on success, 0 otherwise.
257 =item auth_check_password(username, password)
259 Checks the password for the given username. Returns 1 on successful
260 authentication, 0 on failed authentication or error.
262 =item auth_login(username, password)
264 Authenticates and logs the user in. Returns the authentication token if
265 successful, or undef on failure or error.
267 =item auth_logout(username, token)
269 Logs the given user out if the token represents a valid session. Returns 1 on
270 success, or 0 on failure. Failure can happen if the token is no longer valid
271 (meaning the user has been automatically logged out), so the return status is
272 probably best ignored..
274 =item auth_check_token(username, token)
276 Checks that the token represents a valid session for the given username.
277 Returns 1 if the session is valid, 0 otherwise. Also resets the expiration
288 Opens the named database, creating it if it doesn't exist.
290 =item open_existing(name)
292 Opens the named database. If it doesn't exist, returns C<undef>.
304 Returns the number of records in the database.
308 Stores a new record containing C<data>. Returns the record number of the new
313 Fetches a record from the database.
315 =item timestamp(record)
317 Returns a unix epoch timestamp for when the record was created.
325 =item set_subscription_mark()
327 Mark all items on the subscription list as read.
329 =item get_subscription_mark()
331 Return the subscription list mark.
333 =item subscription_list()
335 Return a list of hashrefs describing posts in your subscription feed. Each
336 hashref has a C<author> and C<record> key.
340 =head2 REFS, MUTE, CLEANUP
346 Convenience for listing references to the database. Equivalent to
347 C<tag_list('@' . $obj-E<gt>{name})>.
351 When v = 1, mute the user, otherwise, unmute. If v is absent, return the mute status.
361 See the Blërg! website at http://blerg.cc. More detailed docs about the
362 database internals are available in the source repo under www/doc, or at
367 Chip Black, E<lt>bytex64@bytex64.netE<gt>
369 =head1 COPYRIGHT AND LICENSE
371 Copyright (C) 2013 by Chip Black
373 This library is free software; you can redistribute it and/or modify
374 it under the same terms as Perl itself, either Perl version 5.16.1 or,
375 at your option, any later version of Perl 5 you may have available.