File Coverage

blib/lib/Ryu.pm

Criterion	Covered	Total	%
statement	18	24	75.0
branch			n/a
condition			n/a
subroutine	7	9	77.7
pod	3	3	100.0
total	28	36	77.7

package Ryu;
# ABSTRACT: stream and data flow handling for async code
use strict;
use warnings;

# Older versions cannot complete the test suite successfully
use 5.018;

our $VERSION = '4.001';
our $AUTHORITY = 'cpan:TEAM'; # AUTHORITY

=encoding utf8

=head1 NAME

Ryu - asynchronous stream building blocks

=head1 SYNOPSIS

 #!/usr/bin/env perl
 use strict;
 use warnings;
 use Ryu qw($ryu);
 my ($lines) =
 	$ryu->from(\*STDIN)
 		->by_line
 		->filter(qr/\h/)
 		->count
 		->get;
 print "Had $lines line(s) containing whitespace\n";

=head1 DESCRIPTION

Provides data flow processing for asynchronous coding purposes. It's a bit like L in
concept. Where possible, it tries to provide a similar API. It is not a directly-compatible implementation, however.

For more information, start with L. That's where most of the
useful parts are.

=head2 Why would I be using this?

Eventually some documentation pages might appear, but at the moment they're unlikely to exist.

=over 4

=item * Network protocol implementations - if you're bored of stringing together C, C, C
and C, try L or L.

=item * Extract, Transform, Load workflows (ETL) - need to pull data from somewhere, mangle it into shape, push it to
a database? that'd be L

=item * Reactive event handling - L

=back

As an expert software developer with a keen eye for useful code, you may already be bored of this documentation
and on the verge of reaching for alternatives. The L section may speed you on your way.

=head2 Compatibility

Since L follows the ReactiveX conventions quite closely, we'd expect to have
the ability to connect L observables to a L, and provide an
adapter from a L to act as an L-style observable. This is not yet
implemented, but may be added in a future version.

Most of the other modules in L are either not used widely enough or not a good
semantic fit for a compatibility layer - but if you're interested in this,
L or provide patches!

=head2 Components

=head3 Sources

A source emits items. See L. If in doubt, this is likely to be the class
that you wanted.

Items can be any scalar value - some examples:

=over 4

=item * a single byte

=item * a character

=item * a byte string

=item * a character string

=item * an object instance

=item * an arrayref or hashref

=back

=head3 Sinks

A sink receives items. It's the counterpart to a source. See L.

=head3 Streams

A stream is a thing with a source. See L, which is likely to be something that does not yet
have much documentation - in practice, the L implementation covers most use-cases.

=head2 So what does this module do?

Nothing. It's just a top-level loader for pulling in all the other components.
You wanted L instead, or possibly L. The other half of a
L is a L.

=head2 Some notes that might not relate to anything

With a single parameter, L and L will use the given
instance as a L or L respectively.

Multiple parameters are a shortcut for instantiating the given source
or sink:

 my $stream = Ryu::Stream->from(
  file => 'somefile.bin'
 );

is equivalent to

 my $stream = Ryu::Stream->from(
  Ryu::Source->new(
   file => 'somefile.bin'
  )
 );

=head1 Why the name?

=over 4

=item * C< $ryu > lines up with typical 4-character indentation settings.

=item * there's Rx for other languages, and this is based on the same ideas

=item * 流 was too hard for me to type

=back

=cut

use Exporter qw(import export_to_level);

use Ryu::Source;
use Ryu::Sink;

our $ryu = __PACKAGE__->new;

our @EXPORT_OK = qw($ryu);

our $FUTURE_FACTORY = sub {
    Future->new->set_label($_[1])
};

=head1 METHODS

Note that you're more likely to find useful methods in the following classes:

=over 4

=item * L

=item * L

=item * L

=back

=cut

=head2 new

Instantiates a L object, allowing L, L and other methods.

=cut

sub new { bless { @_[1..$#_] }, $_[0] }

=head2 from

Helper method which returns a L from a list of items.

=cut

sub from {
    my $self = shift;
    my $src = Ryu::Source->new;
    $src->from(@_)
}

=head2 just

Helper method which returns a single-item L.

=cut

sub just {
    my $self = shift;
    my $src = Ryu::Source->new;
    $src->from(shift);
}

1;

__END__