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
213 Returns 1 if the named database exists, or C<undef> if it doesn't.
215 =item tag_list(tag, offset, direction)
217 Returns a list of hashrefs describing blerg posts related to the given tag.
218 C<tag> includes the leading '@' or '#'. Each item has two keys, C<author> and
221 =item hash_tag_list(name, offset, direction)
223 Convenience for C<tag_list> so that you don't have to prepend '#' to the name.
225 =item ref_tag_list(name, offset, direction)
227 Convenience for C<tag_list> so that you don't have to prepend '@' to the name.
229 =item subscription_add(from, to)
231 Adds a subscription from C<from> to C<to>.
233 =item subscription_remove(from, to)
235 The opposite of subscription_add.
237 =item valid_tag_name(name)
239 Validates that C<name> is a valid tag name.
241 =item valid_name(name)
243 Validates that C<name> is a valid username.
253 Opens the named database, creating it if it doesn't exist.
255 =item open_existing(name)
257 Opens the named database. If it doesn't exist, returns C<undef>.
269 Returns the number of records in the database.
273 Stores a new record containing C<data>. Returns the record number of the new
278 Fetches a record from the database.
280 =item timestamp(record)
282 Returns a unix epoch timestamp for when the record was created.
290 =item set_subscription_mark()
292 Mark all items on the subscription list as read.
294 =item get_subscription_mark()
296 Return the subscription list mark.
298 =item subscription_list()
300 Return a list of hashrefs describing posts in your subscription feed. Each
301 hashref has a C<author> and C<record> key.
305 =head2 REFS, MUTE, CLEANUP
311 Convenience for listing references to the database. Equivalent to
312 C<tag_list('@' . $obj-E<gt>{name})>.
316 When v = 1, mute the user, otherwise, unmute. If v is absent, return the mute status.
326 See the Blërg! website at http://blerg.cc. More detailed docs about the
327 database internals are available in the source repo under www/doc, or at
332 Chip Black, E<lt>bytex64@bytex64.netE<gt>
334 =head1 COPYRIGHT AND LICENSE
336 Copyright (C) 2013 by Chip Black
338 This library is free software; you can redistribute it and/or modify
339 it under the same terms as Perl itself, either Perl version 5.16.1 or,
340 at your option, any later version of Perl 5 you may have available.