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_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.
182 Blerg::Database - Perl extension for reading Blërg! databases
188 my $blerg = Blerg::Database->open_existing('foo');
189 my $record = $blerg->post('This is some data!');
190 $blerg->fetch($record);
194 Blerg::Database is a utility library wrapping the core Blërg! database. It
195 provides nicer OO wrappers around the core C library that powers Blërg!.
197 =head1 MODULE FUNCTIONS
203 Returns 1 if the named database exists, or C<undef> if it doesn't.
205 =item tag_list(tag, offset, direction)
207 Returns a list of hashrefs describing blerg posts related to the given tag.
208 C<tag> includes the leading '@' or '#'. Each item has two keys, C<author> and
211 =item hash_tag_list(name, offset, direction)
213 Convenience for C<tag_list> so that you don't have to prepend '#' to the name.
215 =item ref_tag_list(name, offset, direction)
217 Convenience for C<tag_list> so that you don't have to prepend '@' to the name.
219 =item subscription_add(from, to)
221 Adds a subscription from C<from> to C<to>.
223 =item subscription_remove(from, to)
225 The opposite of subscription_add.
227 =item valid_tag_name(name)
229 Validates that C<name> is a valid tag name.
231 =item valid_name(name)
233 Validates that C<name> is a valid username.
243 Opens the named database, creating it if it doesn't exist.
245 =item open_existing(name)
247 Opens the named database. If it doesn't exist, returns C<undef>.
259 Returns the number of records in the database.
263 Stores a new record containing C<data>. Returns the record number of the new
268 Fetches a record from the database.
270 =item timestamp(record)
272 Returns a unix epoch timestamp for when the record was created.
280 =item set_subscription_mark()
282 Mark all items on the subscription list as read.
284 =item get_subscription_mark()
286 Return the subscription list mark.
288 =item subscription_list()
290 Return a list of hashrefs describing posts in your subscription feed. Each
291 hashref has a C<author> and C<record> key.
295 =head2 REFS, MUTE, CLEANUP
301 Convenience for listing references to the database. Equivalent to
302 C<tag_list('@' . $obj-E<gt>{name})>.
306 When v = 1, mute the user, otherwise, unmute.
316 See the Blërg! website at http://blerg.cc. More detailed docs about the
317 database internals are available in the source repo under www/doc, or at
322 Chip Black, E<lt>bytex64@bytex64.netE<gt>
324 =head1 COPYRIGHT AND LICENSE
326 Copyright (C) 2013 by Chip Black
328 This library is free software; you can redistribute it and/or modify
329 it under the same terms as Perl itself, either Perl version 5.16.1 or,
330 at your option, any later version of Perl 5 you may have available.