Messag...ng::DSL(3pm)

💖 Message::Passing::DSL — the manual, but make it cute 💖

okay bestie, so you know the page Messag...ng::DSL(3pm) from the User Contributed Perl Documentation? That's this one. Yes the name got truncated by the formatter, no we are not going to let that ruin our day. It's Message::Passing::DSL and it is genuinely a little gem. 💎

---

✨ NAME ✨

Message::Passing::DSL — an easy way to make chains of Message::Passing components.

Like, an easy way. That's the whole point. That's the assignment and it ate. 🫶

---

🌸 SYNOPSIS 🌸

package mylogcollectorscript;
use Moo;
use MooX::Options;
use Message::Passing::DSL;
use MooX::Types::MooseLike::Base qw/ Str /;
use namespace::clean -except => [qw( meta _options_data _options_config )];

with 'Message::Passing::Role::Script';

option socket_bind => (
    is => 'ro',
    isa => Str,
    default => sub { 'tcp://*:5558' },
);

sub build_chain {
    my $self = shift;
    message_chain {
        output console => (
            class => 'STDOUT',
        );
        input zmq => (
            class => 'ZeroMQ',
            output_to => 'console',
            socket_bind => $self->socket_bind,
        );
    };
}

__PACKAGE__->start unless caller;
1;

look at that. clean. no notes. 💅

---

🦋 DESCRIPTION 🦋

So this module is a simple-to-use helper system for writing scripts that implement a Message::Passing server — same energy as the built-in message-pass script. It's giving "we made the boilerplate disappear" and honestly? iconic.

Here's the tea: normally you'd have to pass actual instances of an output to each input in the output_to attribute, and you'd have to write out full class names like a menace. With this DSL you can:

• use short names for component classes, and
• use strings for the output_to attribute.

The DSL resolves all of that and deals with instance construction for you. no cap. 🧚

Check the example up in the SYNOPSIS, and the details for the exported sugar functions are right below. ⬇️

🎀 FUNCTIONS 🎀

message_chain

Constructs a message chain (i.e. a series of Message::Passing objects feeding into each other), warns about any unused parts of the chain, and returns an array ref to the heads of the chain (i.e. the input class(es)).

It also maintains a registry / factory for the log classes, which is what makes the resolving of symbolic names in the output_to key actually function. so that's the magic trick. ✨

output

Constructs a named output within a chain.

message_chain {
    output foo => ( class => 'STDOUT' );
    ....
};

Class names will be assumed to be prefixed with 'Message::Passing::Output::', unless you prefix the class with +, e.g. "+My::Own::Output::Class".

encoder

Constructs a named encoder within a chain.

message_chain {
    encoder fooenc => ( output_to => 'out', class => 'JSON' );
    ....
};

Class names will be assumed to be prefixed with 'Message::Passing::Filter::Encoder::', unless you prefix the class with +, e.g. "+My::Own::Encoder::Class".

filter

Constructs a named filter within a chain — and a filter is the multitasker of the group because it can act as both an output and an input. main character energy, fr.

message_chain {
    ...
    filter bar => ( output_to => 'fooenc', class => 'Null' );
    ...
};

Class names will be assumed to be prefixed with 'Message::Passing::Filter::', unless you prefix the class with +, e.g. "+My::Own::Filter::Class".

decoder

Constructs a named decoder within a chain.

message_chain {
    decoder zmq_decode => ( output_to => 'filter', class => 'JSON' );
    ....
};

Class names will be assumed to be prefixed with 'Message::Passing::Filter::Decoder::', unless you prefix the class with +, e.g. "+My::Own::Encoder::Class".

input

The last thing in a chain — it produces data which gets consumed.

message_chain {
    ...
    input zmq => ( output_to => 'zmq_decode', class => 'ZeroMQ', bind => '...' );
    ....
}

Class names will be assumed to be prefixed with 'Message::Passing::Output::', unless you prefix the class with +, e.g. "+My::Own::Output::Class".

error_log

Sets up the error logging output. Takes the same arguments as an "input xxx => ()" block, except without a name. (No name, no problem. 🙈)

run_message_server

This enters the event loop and causes log events to be consumed and processed.

You can pass it a message_chain to run, although this is entirely optional — because all chains which are still in scope will run when the event loop is entered. lowkey convenient. 🌈

---

👑 SPONSORSHIP 👑

This module exists due to the wonderful people at Suretec Systems Ltd. <http://www.suretecsystems.com/> who sponsored its development for its VoIP division called SureVoIP <http://www.surevoip.co.uk/> for use with the SureVoIP API — <http://www.surevoip.co.uk/support/wiki/api_documentation>.

shoutout to the sponsors, they really said "we fund open source" and that's beautiful. 🫶✨

---

💜 AUTHOR, COPYRIGHT AND LICENSE 💜

See Message::Passing. (short and sweet, we love a cross-reference.)

---

okay that's the whole page, you're welcome, go build a chain and slay 💖 this was Messag...ng::DSL(3pm) from perl v5.32.1, dated 2021-11-09, and yes I'm mentioning the version and date because the footer said so and I never skip details. mwah. 💅🎀