NAME

    Ryu - asynchronous stream building blocks

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";

DESCRIPTION

    Provides data flow processing for asynchronous coding purposes. It's a
    bit like ReactiveX <https://reactivex.io> in concept. Where possible,
    it tries to provide a similar API. It is not a directly-compatible
    implementation, however.

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

 Why would I be using this?

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

      * Network protocol implementations - if you're bored of stringing
      together substr, pack, unpack and vec, try Ryu::Manual::Protocol or
      Ryu::Buffer.

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

      * Reactive event handling - Ryu::Manual::Reactive

    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 "SEE ALSO" section may speed you on your way.

 Compatibility

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

    Most of the other modules in "SEE ALSO" are either not used widely
    enough or not a good semantic fit for a compatibility layer - but if
    you're interested in this, please ask about it
    <https://github.com/team-at-cpan/Ryu/issues> or provide patches!

 Components

  Sources

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

    Items can be any scalar value - some examples:

      * a single byte

      * a character

      * a byte string

      * a character string

      * an object instance

      * an arrayref or hashref

  Sinks

    A sink receives items. It's the counterpart to a source. See Ryu::Sink.

  Streams

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

 So what does this module do?

    Nothing. It's just a top-level loader for pulling in all the other
    components. You wanted Ryu::Source instead, or possibly Ryu::Buffer.

 Some notes that might not relate to anything

    With a single parameter, "from" and "to" will use the given instance as
    a Ryu::Source or Ryu::Sink 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'
      )
     );

Why the name?

      *  $ryu  lines up with typical 4-character indentation settings.

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

      * 流 was too hard for me to type

METHODS

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

      * Ryu::Source

      * Ryu::Sink

      * Ryu::Observable

 new

    Instantiates a Ryu object, allowing "from", "just" and other methods.

 from

    Helper method which returns a Ryu::Source from a list of items.

 just

    Helper method which returns a single-item Ryu::Source.

SEE ALSO

 Other modules

    Some perl modules of relevance:

      * Future - fundamental building block for one-shot tasks

      * Future::Queue - a FIFO queue for Future tasks

      * Future::Buffer - provides equivalent functionality to Ryu::Buffer

      * POE::Filter - venerable and battle-tested, but slightly short on
      features due to the focus on protocols

      * Data::Transform - standalone version of POE::Filter

      * List::Gen - list mangling features

      * HOP::Stream - based on the Higher Order Perl book

      * Flow - quite similar in concept to this module, maybe a bit short
      on documentation, doesn't provide integration with other sources such
      as files or IO::Async::Stream

      * Flux - more like the java8 streams API, sync-based

      * Message::Passing - on initial glance seemed more of a commandline
      tool, sadly based on AnyEvent

      * Rx.pl <https://github.com/eilara/Rx.pl> - a Perl version of the
      http://reactivex.io Reactive API

      * Perlude - combines features of the shell / UNIX streams and
      Haskell, pipeline syntax is "backwards" (same as grep/map chains in
      Perl)

      * IO::Pipeline

      * DS

      * Evo

      * Async::Stream - early release, but seems to be very similar in
      concept to Ryu::Source

      * Data::Monad

      * RxPerl - previously known as Mojo::Rx, targets close compatibility
      with rxjs <https://rxjs-dev.firebaseapp.com/guide/overview>

 Other references

    There are various documents, specifications and discussions relating to
    the concepts we use. Here's a few:

      * http://www.reactivemanifesto.org/

      * Java 8 streams API
      <https://docs.oracle.com/javase/8/docs/api/java/util/stream/package-summary.html>

      * C++ range-v3 <https://github.com/ericniebler/range-v3>

AUTHOR

    Tom Molesworth <TEAM@cpan.org> with contributions from:

      * Mohammad S Anwar

      * Michael Mueller

      * Zak Elep

      * Mohanad Zarzour

      * Nael Alolwani

      * Amin Marashi

LICENSE

    Copyright Tom Molesworth 2011-2021. Licensed under the same terms as
    Perl itself.