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.
Network protocol implementations - if you're bored of stringing together
substr
,pack
,unpack
andvec
, 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 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. The other half of a Ryu::Source is a Ryu::Sink.
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:
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 - a Perl version of the https://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)
Async::Stream - early release, but seems to be very similar in concept to Ryu::Source
RxPerl - previously known as Mojo::Rx, targets close compatibility with rxjs
Other references
There are various documents, specifications and discussions relating to the concepts we use. Here's a few:
AUTHOR
Tom Molesworth <[email protected]>
with contributions from:
Mohammad S Anwar
Michael Mueller
Zak Elep
Mohanad Zarzour
Nael Alolwani
Amin Marashi
LICENSE
Copyright Tom Molesworth 2011-2024. Licensed under the same terms as Perl itself.