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.8.1';
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_mute($obj->{ptr}, $v);
135 return Blerg::Database::_get_mute($obj->{ptr});
141 return Blerg::Database::tag_list('@' . $obj->{name}, 50, -1);
145 my ($obj, $data) = @_;
146 $obj->_ensure_pointer;
147 return Blerg::Database::_store($obj->{ptr}, $data);
151 my ($obj, $record) = @_;
152 $obj->_ensure_pointer;
153 return Blerg::Database::_fetch($obj->{ptr}, $record);
157 my ($obj, $record) = @_;
158 $obj->_ensure_pointer;
159 return Blerg::Database::_get_timestamp($obj->{ptr}, $record);
162 # Convenience shortcuts
164 my ($name, $str_offset, $direction) = @_;
165 return Blerg::Database::tag_list("#$name", $str_offset, $direction);
169 my ($name, $str_offset, $direction) = @_;
170 return Blerg::Database::tag_list("@$name", $str_offset, $direction);
173 # Autoload methods go after =cut, and are processed by the autosplit program.
181 Blerg::Database - Perl extension for reading Blërg! databases
187 my $blerg = Blerg::Database->open_existing('foo');
188 my $record = $blerg->post('This is some data!');
189 $blerg->fetch($record);
193 Blerg::Database is a utility library wrapping the core Blërg! database. It
194 provides nicer OO wrappers around the core C library that powers Blërg!.
196 =head1 MODULE FUNCTIONS
202 Returns 1 if the named database exists, or C<undef> if it doesn't.
204 =item tag_list(tag, offset, direction)
206 Returns a list of hashrefs describing blerg posts related to the given tag.
207 C<tag> includes the leading '@' or '#'. Each item has two keys, C<author> and
210 =item hash_tag_list(name, offset, direction)
212 Convenience for C<tag_list> so that you don't have to prepend '#' to the name.
214 =item ref_tag_list(name, offset, direction)
216 Convenience for C<tag_list> so that you don't have to prepend '@' to the name.
218 =item subscription_add(from, to)
220 Adds a subscription from C<from> to C<to>.
222 =item subscription_remove(from, to)
224 The opposite of subscription_add.
226 =item valid_tag_name(name)
228 Validates that C<name> is a valid tag name.
230 =item valid_name(name)
232 Validates that C<name> is a valid username.
242 Opens the named database, creating it if it doesn't exist.
244 =item open_existing(name)
246 Opens the named database. If it doesn't exist, returns C<undef>.
258 Returns the number of records in the database.
262 Stores a new record containing C<data>. Returns the record number of the new
267 Fetches a record from the database.
269 =item timestamp(record)
271 Returns a unix epoch timestamp for when the record was created.
279 =item set_subscription_mark()
281 Mark all items on the subscription list as read.
283 =item get_subscription_mark()
285 Return the subscription list mark.
287 =item subscription_list()
289 Return a list of hashrefs describing posts in your subscription feed. Each
290 hashref has a C<author> and C<record> key.
294 =head2 REFS, MUTE, CLEANUP
300 Convenience for listing references to the database. Equivalent to
301 C<tag_list('@' . $obj->{name})>.
305 When v = 1, mute the user, otherwise, unmute.
315 See the Blërg! website at http://blerg.cc. More detailed docs about the
316 database internals are available in the source repo under www/doc, or at
321 Chip Black, E<lt>bytex64@bytex64.netE<gt>
323 =head1 COPYRIGHT AND LICENSE
325 Copyright (C) 2013 by Chip Black
327 This library is free software; you can redistribute it and/or modify
328 it under the same terms as Perl itself, either Perl version 5.16.1 or,
329 at your option, any later version of Perl 5 you may have available.