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 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.

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 Mojo::Rx follows the ReactiveX conventions quite closely, we'd expect to have the ability to connect Mojo::Rx observable to a Ryu::Source, and provide an adapter from a Ryu::Source to act as a Mojo::Rx-style observable. This is not yet implemented, but planned for 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.

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:

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:

Other references

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

AUTHOR

Tom Molesworth <TEAM@cpan.org> with contributions from Mohammad S Anwar, Michael Mueller, Zak Elep, Mohanad Zarzour and Nael Alolwani.

LICENSE

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