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.
61 my ($class, $name) = @_;
62 my $ptr = Blerg::Database::_open($name);
67 return bless $obj, $class;
71 my ($class, $name) = @_;
73 if (Blerg::Database::exists($name)) {
74 return Blerg::Database->open($name);
81 if (!defined $obj->{ptr}) {
82 croak "Attempted to use closed Blerg::Database";
88 if (!(defined $obj && defined $obj->{ptr})) {
89 # Welp, nothing to do here!
92 Blerg::Database::_close($obj->{ptr});
103 $obj->_ensure_pointer;
104 return Blerg::Database::_get_record_count($obj->{ptr});
107 sub set_subscription_mark {
109 $obj->_ensure_pointer;
110 return Blerg::Database::_set_subscription_mark($obj->{ptr});
113 sub get_subscription_mark {
115 $obj->_ensure_pointer;
116 return Blerg::Database::_get_subscription_mark($obj->{ptr});
119 sub subscription_list {
121 $obj->_ensure_pointer;
122 return Blerg::Database::_subscription_list($obj->{name}, 0, 1);
127 $obj->_ensure_pointer;
129 return Blerg::Database::_set_mute($obj->{ptr}, $v);
131 return Blerg::Database::_get_mute($obj->{ptr});
137 return Blerg::Database::tag_list('@' . $obj->{name}, 50, -1);
141 my ($obj, $data) = @_;
142 $obj->_ensure_pointer;
143 return Blerg::Database::_store($obj->{ptr}, $data);
147 my ($obj, $record) = @_;
148 $obj->_ensure_pointer;
149 return Blerg::Database::_fetch($obj->{ptr}, $record);
153 my ($obj, $record) = @_;
154 $obj->_ensure_pointer;
155 return Blerg::Database::_get_timestamp($obj->{ptr}, $record);
158 # Convenience shortcuts
160 my ($name, $str_offset, $direction) = @_;
161 return Blerg::Database::tag_list("#$name", $str_offset, $direction);
165 my ($name, $str_offset, $direction) = @_;
166 return Blerg::Database::tag_list("@$name", $str_offset, $direction);
169 # Autoload methods go after =cut, and are processed by the autosplit program.
177 Blerg::Database - Perl extension for reading Blërg! databases
183 my $blerg = Blerg::Database->open_existing('foo');
184 my $record = $blerg->post('This is some data!');
185 $blerg->fetch($record);
189 Blerg::Database is a utility library wrapping the core Blërg! database. It
190 provides nicer OO wrappers around the core C library that powers Blërg!.
192 =head1 MODULE FUNCTIONS
198 Returns 1 if the named database exists, or C<undef> if it doesn't.
200 =item tag_list(tag, offset, direction)
202 Returns a list of hashrefs describing blerg posts related to the given tag.
203 C<tag> includes the leading '@' or '#'. Each item has two keys, C<author> and
206 =item hash_tag_list(name, offset, direction)
208 Convenience for C<tag_list> so that you don't have to prepend '#' to the name.
210 =item ref_tag_list(name, offset, direction)
212 Convenience for C<tag_list> so that you don't have to prepend '@' to the name.
214 =item subscription_add(from, to)
216 Adds a subscription from C<from> to C<to>.
218 =item subscription_remove(from, to)
220 The opposite of subscription_add.
222 =item valid_tag_name(name)
224 Validates that C<name> is a valid tag name.
226 =item valid_name(name)
228 Validates that C<name> is a valid username.
238 Opens the named database, creating it if it doesn't exist.
240 =item open_existing(name)
242 Opens the named database. If it doesn't exist, returns C<undef>.
254 Returns the number of records in the database.
258 Stores a new record containing C<data>. Returns the record number of the new
263 Fetches a record from the database.
265 =item timestamp(record)
267 Returns a unix epoch timestamp for when the record was created.
275 =item set_subscription_mark()
277 Mark all items on the subscription list as read.
279 =item get_subscription_mark()
281 Return the subscription list mark.
283 =item subscription_list()
285 Return a list of hashrefs describing posts in your subscription feed. Each
286 hashref has a C<author> and C<record> key.
290 =head2 REFS, MUTE, CLEANUP
296 Convenience for listing references to the database. Equivalent to
297 C<tag_list('@' . $obj->{name})>.
301 When v = 1, mute the user, otherwise, unmute.
311 See the Blërg! website at http://blerg.cc. More detailed docs about the
312 database internals are available in the source repo under www/doc, or at
317 Chip Black, E<lt>bytex64@bytex64.netE<gt>
319 =head1 COPYRIGHT AND LICENSE
321 Copyright (C) 2013 by Chip Black
323 This library is free software; you can redistribute it and/or modify
324 it under the same terms as Perl itself, either Perl version 5.16.1 or,
325 at your option, any later version of Perl 5 you may have available.