Ryu(3)

πŸ“¦ version 4.001, in alpine 3.24

πŸ’– NAME

Bestie, this is Ryu β€” your little toolkit of asynchronous stream building blocks ✨ (that's the manual page for Ryu(3), and yes, it's giving "glue module with main character energy").

✨ SYNOPSIS

Okay so here's the whole vibe in one script, no cap:

#!/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";

Look at that chain. It ate. πŸ’…

🌸 DESCRIPTION

So this module hands you data flow processing for asynchronous coding purposes. Conceptually it's a bit like ReactiveX (that's https://reactivex.io) β€” and wherever it could, it tries to give you a similar API. But bestie, listen: it is not a directly-compatible implementation, okay? Similar vibe, not a clone. 🫢

Want the real tea? Start with Ryu::Source. That's where all the genuinely useful parts live.

Why would I be using this?

Eventually some documentation pages might appear… but atm they're unlikely to exist 😭. Still, here's the dream:

  • 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

And ngl, 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 β€” go, fly, we support you πŸ¦‹.

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. That is not yet implemented πŸ™ˆ β€” but it may be added in a future version. So like… someday?

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 at https://github.com/team-at-cpan/Ryu/issues or provide patches! We literally love patches πŸ’–

Components

Sources

A source emits items. See Ryu::Source. If in doubt, this is likely to be the class that you wanted β€” like, that's the one, periodt. ✨

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 you're fine bestie).

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. And 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'
 )
);

Same thing, just shorter. Slay. πŸ’…

πŸ¦‹ Why the name?

Genuinely iconic reasons, honestly:

  • $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

Quick heads up before you scroll: 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 β€” the whole friend group:

  • 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 Reactive API at http://reactivex.io
  • 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:

πŸŽ€ AUTHOR

Tom Molesworth <TEAM@cpan.org> with contributions from β€” shoutout to the whole squad 🫢:

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

πŸ’– And that's the whole page bestie β€” brought to you by perl v5.42.2, dated 2026-02-15, filed under Ryu(3). Go build some streams, you absolute icon. 🌈✨
πŸ“¦ where this page comes from