BusyBird
view release on metacpan or search on metacpan
lib/BusyBird/Timeline.pm view on Meta::CPAN
$args_ref->{timeline} = $self->name;
local @CARP_NOT = (ref($self->{storage}));
$self->{storage}->$method(%$args_ref);
}
sub get_statuses {
my ($self, %args) = @_;
$self->_get_from_storage("get_statuses", \%args);
}
sub get_unacked_counts {
my ($self, %args) = @_;
$self->_get_from_storage("get_unacked_counts", \%args);
}
sub _write_statuses {
my ($self, $method, $args_ref) = @_;
$args_ref->{timeline} = $self->name;
local @CARP_NOT = (ref($self->{storage}));
my $orig_callback = $args_ref->{callback};
$self->{storage}->$method(%$args_ref, callback => sub {
$self->_update_unacked_counts();
goto $orig_callback if defined($orig_callback);
});
}
sub put_statuses {
my ($self, %args) = @_;
$self->_write_statuses('put_statuses', \%args);
}
sub delete_statuses {
my ($self, %args) = @_;
$self->_write_statuses('delete_statuses', \%args);
}
sub ack_statuses {
my ($self, %args) = @_;
$self->_write_statuses('ack_statuses', \%args);
}
sub add_statuses {
my ($self, %args) = @_;
if(!defined($args{statuses})) {
croak "statuses argument is mandatory";
}
my $ref = ref($args{statuses});
if($ref eq "HASH") {
$args{statuses} = [ $args{statuses} ];
}elsif($ref ne "ARRAY") {
croak "statuses argument must be a status or an array-ref of statuses";
}
my $statuses = dclone($args{statuses});
my $final_callback = $args{callback};
$self->{filter_flow}->execute($statuses, sub {
my $filter_result = shift;
my $cur_time;
foreach my $status (@$filter_result) {
next if !defined($status) || ref($status) ne 'HASH';
if(!defined($status->{id})) {
$status->{id} = sprintf('busybird://%s/%s', $self->name, $self->{id_generator}->create_str);
}
if(!defined($status->{created_at})) {
$cur_time ||= DateTime->now;
$status->{created_at} = BusyBird::DateTime::Format->format_datetime($cur_time);
}
}
$self->_write_statuses('put_statuses', {
mode => 'insert', statuses => $filter_result,
callback => $final_callback
});
});
}
sub add {
my ($self, $statuses, $callback) = @_;
$self->add_statuses(statuses => $statuses, callback => $callback);
}
sub contains {
my ($self, %args) = @_;
$self->_get_from_storage("contains", \%args);
}
sub add_filter {
my ($self, $filter, $is_async) = @_;
if(!$is_async) {
my $sync_filter = $filter;
$filter = sub {
my ($statuses, $done) = @_;
@_ = $sync_filter->($statuses);
goto $done;
};
}
$self->{filter_flow}->add($filter);
}
sub add_filter_async {
my ($self, $filter) = @_;
$self->add_filter($filter, 1);
}
sub set_config {
shift()->{config}->set_config(@_);
}
sub get_config {
shift()->{config}->get_config(@_);
}
sub watch_unacked_counts {
my ($self, %watch_args) = @_;
my $callback = $watch_args{callback};
my $assumed = $watch_args{assumed};
if(!defined($callback) || ref($callback) ne 'CODE') {
croak "watch_unacked_counts: callback must be a code-ref";
}
if(!defined($assumed) || ref($assumed) ne 'HASH') {
croak "watch_unacked_counts: assumed must be a hash-ref";
}
$assumed = +{ %$assumed };
lib/BusyBird/Timeline.pm view on Meta::CPAN
1;
__END__
=pod
=head1 NAME
BusyBird::Timeline - a timeline object in BusyBird
=head1 SYNOPSIS
use BusyBird::Timeline;
use BusyBird::StatusStorage::SQLite;
my $storage = BusyBird::StatusStorage::SQLite->new(
path => ':memory:'
);
my $timeline = BusyBird::Timeline->new(
name => "sample", storage => $storage
);
$timeline->set_config(
time_zone => "+0900"
);
## Add some statuses
$timeline->add_statuses(
statuses => [{text => "foo"}, {text => "bar"}],
callback => sub {
my ($error, $num) = @_;
if($error) {
warn("error: $error");
return;
}
print "Added $num statuses.\n";
}
);
## Ack all statuses
$timeline->ack_statuses(callback => sub {
my ($error, $num) = @_;
if($error) {
warn("error: $error");
return;
}
print "Acked $num statuses.\n";
});
## Change acked statuses into unacked.
$timeline->get_statuses(
ack_state => 'acked', count => 10,
callback => sub {
my ($error, $statuses) = @_;
if($error) {
warn("error: $error");
return;
}
foreach my $s (@$statuses) {
$s->{busybird}{acked_at} = undef;
}
$timeline->put_statuses(
mode => "update", statuses => $statuses,
callback => sub {
my ($error, $num) = @_;
if($error) {
warn("error: $error");
return;
}
print "Updated $num statuses.\n";
}
);
}
);
## Delete all statuses
$timeline->delete_statuses(
ids => undef, callback => sub {
my ($error, $num) = @_;
if($error) {
warn("error: $error");
return;
}
print "Delete $num statuses.\n";
}
);
=head1 DESCRIPTION
L<BusyBird::Timeline> stores and manages a timeline, which is an ordered sequence of statuses.
You can add statuses to a timeline, and get statuses from the timeline.
This module uses L<BusyBird::Log> for logging.
=head2 Filters
You can set status filters to a timeline.
A status filter is a subroutine that is called when new statuses are added to the timeline
via C<add_statuses()> method.
Using status filters, you can modify or even drop the added statuses before they are
actually inserted to the timeline.
Status filters are executed in the same order as they are added.
L<BusyBird> comes with some pre-defined status filters. See L<BusyBird::Filter> for detail.
=head2 Status Storage
A timeline's statuses are actually saved in a L<BusyBird::StatusStorage> object.
When you create a timeline via C<new()> method, you have to specify a L<BusyBird::StatusStorage> object explicitly.
=head2 Callback-Style Methods
Some methods of L<BusyBird::Timeline> are callback-style, that is,
their results are not returned but given to the callback function you specify.
It depends on the underlying L<BusyBird::StatusStorage> object
whether the callback-style methods are synchronous or asynchronous.
L<BusyBird::StatusStorage::SQLite>, for example, is synchronous.
If the status storage is synchronous, the callback is always called before the method returns.
lib/BusyBird/Timeline.pm view on Meta::CPAN
=item C<name> => STRING (mandatory)
Specifies the name of the timeline.
If it includes Unicode characters, it must be a character string (decoded string), not a binary string (encoded string).
=item C<storage> => STATUS_STORAGE (mandatory)
Specifies a L<BusyBird::StatusStorage> object.
Statuses in C<$timeline> is saved to the C<storage>.
=back
=head1 OBJECT METHODS
=head2 $name = $timeline->name()
Returns the C<$timeline>'s name.
=head2 $timeline->add($statuses, [$callback])
=head2 $timeline->add_statuses(%args)
Adds new statuses to the C<$timeline>.
Note that statuses added by C<add_statuses()> method go through the C<$timeline>'s filters.
It is the filtered statuses that are actually inserted to the storage.
In addition to filtering, if statuses added to the C<$timeline> lack C<id> or C<created_at> field,
it automatically generates and sets these fields.
This auto-generation of IDs and timestamps are done after the filtering.
C<add()> method is a short-hand of C<< add_statuses(statuses => $statuses, callback => $callback) >>.
Fields in C<%args> are as follows.
=over
=item C<statuses> => {STATUS, ARRAYREF_OF_STATUSES} (mandatory)
Specifies a status object or an array-ref of status objects to be added.
See L<BusyBird::Manual::Status> about what status objects look like.
=item C<callback> => CODEREF($error, $added_num) (optional, default: C<undef>)
Specifies a subroutine reference that is called when the operation has completed.
In success, C<callback> is called with two arguments (C<$error> and C<$added_num>).
C<$error> is C<undef>, and C<$added_num> is the number of statuses actually added to the C<$timeline>.
In failure, C<$error> is a truthy value describing the error.
=back
=head2 $timeline->ack_statuses(%args)
Acknowledges statuses in the C<$timeline>, that is, changing 'unacked' statuses into 'acked'.
Acked status is a status whose C<< $status->{busybird}{acked_at} >> field evaluates to true.
Otherwise, the status is unacked.
Fields in C<%args> are as follows.
=over
=item C<ids> => {ID, ARRAYREF_OF_IDS} (optional, default: C<undef>)
Specifies the IDs of the statuses to be acked.
If it is a defined scalar, the status with the specified ID is acked.
If it is an array-ref of IDs, the statuses with those IDs are acked.
If both C<max_id> and C<ids> are omitted or set to C<undef>, all unacked statuses are acked.
If both C<max_id> and C<ids> are specified, both statuses older than or equal to C<max_id>
and statuses specifed by C<ids> are acked.
If Status IDs include Unicode characters, they should be character strings (decoded strings), not binary strings (encoded strings).
=item C<max_id> => ID (optional, default: C<undef>)
Specifies the latest ID of the statuses to be acked.
If specified, unacked statuses with IDs older than or equal to the specified C<max_id> are acked.
If there is no unacked status with ID C<max_id>, no status is acked.
If both C<max_id> and C<ids> are omitted or set to C<undef>, all unacked statuses are acked.
If both C<max_id> and C<ids> are specified, both statuses older than or equal to C<max_id>
and statuses specifed by C<ids> are acked.
If the Status ID includes Unicode characters, it should be a character string (decoded string), not a binary string (encoded string).
=item C<callback> => CODEREF($error, $acked_num) (optional, default: C<undef>)
Specifies a subroutine reference that is called when the operation completes.
In success, the C<callback> is called with two arguments (C<$error> and C<$acked_num>).
C<$error> is C<undef>, and C<$acked_num> is the number of acked statuses.
In failure, C<$error> is a truthy value describing the error.
=back
=head2 $timeline->get_statuses(%args)
Fetches statuses from the C<$timeline>.
The fetched statuses are given to the C<callback> function.
Fields in C<%args> are as follows.
=over
=item C<callback> => CODEREF($error, $arrayref_of_statuses) (mandatory)
Specifies a subroutine reference that is called upon completion of
fetching statuses.
lib/BusyBird/Timeline.pm view on Meta::CPAN
Deletes statuses from the C<$timeline>.
Fields in C<%args> are as follows.
=over
=item C<ids> => {C<undef>, ID, ARRAYREF_OF_IDS} (mandatory)
Specifies the IDs (value of C<< $status->{id} >> field) of the
statuses to be deleted.
If it is a defined scalar, the status with the specified ID is
deleted. If it is an array-ref of IDs, the statuses with those IDs
are deleted. If it is explicitly set to C<undef>, all statuses in the C<$timeline> are deleted.
If Status IDs include Unicode characters, they should be character strings (decoded strings), not binary strings (encoded strings).
=item C<callback> => CODEREF($error, $deleted_num) (optional, default: C<undef>)
Specifies a subroutine reference that is called when the operation completes.
In success, the C<callback> is called with two arguments (C<$error> and C<$deleted_num>).
C<$error> is C<undef>, and C<$deleted_num> is the number of deleted statuses.
In failure, C<$error> is a truthy value describing the error.
=back
=head2 $timeline->get_unacked_counts(%args)
Fetches numbers of unacked statuses in the C<$timeline>.
Fields in C<%args> are as follows.
=over
=item C<callback> => CODEREF($error, $unacked_counts) (mandatory)
Specifies a subroutine reference that is called when the operation completes.
In success, the C<callback> is called with two arguments (C<$error> and C<$unacked_counts>).
C<$error> is C<undef>, and C<$unacked_counts> is a hash-ref describing numbers of unacked statuses in each level.
In failure, C<$error> is a truthy value describing the error.
=back
Fields in C<%$unacked_counts> are as follows.
=over
=item LEVEL => COUNT_OF_UNACKED_STATUSES_IN_THE_LEVEL
LEVEL is an integer key that represents the status level.
The value is the number of unacked statuses in the level.
A status's level is the C<< $status->{busybird}{level} >> field.
See L<BusyBird::Manual::Status> for detail.
LEVEL key-value pair is present for each level in which
there are some unacked statuses.
=item C<total> => COUNT_OF_ALL_UNACKED_STATUSES
The key C<"total"> represents the total number of unacked statuses
in the C<$timeline>.
=back
For example, C<$unacked_counts> is structured like:
$unacked_counts = {
total => 3,
0 => 1,
1 => 2,
};
This means there are 3 unacked statuses in total, one of which is in level 0,
and the rest is in level 2.
=head2 $timeline->contains(%args)
Checks if the given statuses (or IDs) are contained in the C<$timeline>.
Fields in C<%args> are as follows.
=over
=item C<query> => {STATUS, ID, ARRAYREF_OF_STATUSES_OR_IDS} (mandatory)
Specifies the statuses or IDs to be checked.
If it is a scalar, that value is treated as a status ID.
If it is a hash-ref, that object is treated as a status object.
If it is an array-ref,
elements in the array-ref are treated as status objects or IDs.
Status objects and IDs can be mixed in a single array-ref.
If some statuses in C<query> don't have their C<id> field, those statuses are always treated as "not contained" in the C<$timeline>.
If Status IDs include Unicode characters, they should be character strings (decoded strings), not binary strings (encoded strings).
=item C<callback> => CODEREF($error, $contained, $not_contained) (mandatory)
Specifies a subroutine reference that is called when the check has completed.
In success, C<callback> is called with three arguments (C<$error>, C<$contained>, C<$not_contained>).
C<$error> is C<undef>.
C<$contained> is an array-ref of given statuses or IDs that are contained in the C<$timeline>.
C<$not_contained> is an array-ref of given statuses or IDs that are NOT contained in the C<$timeline>.
In failure, C<$error> is a truthy value describing the error.
=back
( run in 0.997 second using v1.01-cache-2.11-cpan-99c4e6809bf )