.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Message::Passing::DSL 3pm"
.TH Message::Passing::DSL 3pm "2012-09-07" "perl v5.18.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Message::Passing::DSL \- An easy way to make chains of Message::Passing components.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 6
\&    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 \*(AqMessage::Passing::Role::Script\*(Aq;
\&
\&    option socket_bind => (
\&        is => \*(Aqro\*(Aq,
\&        isa => Str,
\&        default => sub { \*(Aqtcp://*:5558\*(Aq },
\&    );
\&
\&    sub build_chain {
\&        my $self = shift;
\&        message_chain {
\&            output console => (
\&                class => \*(AqSTDOUT\*(Aq,
\&            );
\&            input zmq => (
\&                class => \*(AqZeroMQ\*(Aq,
\&                output_to => \*(Aqconsole\*(Aq,
\&                socket_bind => $self\->socket_bind,
\&            );
\&        };
\&    }
\&
\&    _\|_PACKAGE_\|_\->start unless caller;
\&    1;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module provides a simple to use helper system for writing
scripts which implement a Message::Passing server, like
the built in message-pass script.
.PP
Rather than having to pass instances of an output to each input in the
\&\f(CW\*(C`output_to\*(C'\fR attribute, and full class names, you can use short names
for component classes, and strings for the \f(CW\*(C`output_to\*(C'\fR attribute,
the \s-1DSL\s0 resolves these and deals with instance construction for you.
.PP
See example in the \s-1SYNOPSIS,\s0 and details for the exported sugar
functions below.
.SS "\s-1FUNCTIONS\s0"
.IX Subsection "FUNCTIONS"
\fImessage_chain\fR
.IX Subsection "message_chain"
.PP
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)).
.PP
Maintains a registry / factory for the log classes, which is used to
allow the resolving of symbolic names in the output_to key to function.
.PP
\fIoutput\fR
.IX Subsection "output"
.PP
Constructs a named output within a chain.
.PP
.Vb 4
\&    message_chain {
\&        output foo => ( class => \*(AqSTDOUT\*(Aq );
\&        ....
\&    };
.Ve
.PP
Class names will be assumed to prefixed with 'Message::Passing::Output::',
unless you prefix the class with + e.g. \f(CW\*(C`+My::Own::Output::Class\*(C'\fR
.PP
\fIencoder\fR
.IX Subsection "encoder"
.PP
Constructs a named encoder within a chain.
.PP
.Vb 4
\&    message_chain {
\&        encoder fooenc => ( output_to => \*(Aqout\*(Aq, class => \*(AqJSON\*(Aq );
\&        ....
\&    };
.Ve
.PP
Class names will be assumed to prefixed with 'Message::Passing::Filter::Encoder::',
unless you prefix the class with + e.g. \f(CW\*(C`+My::Own::Encoder::Class\*(C'\fR
.PP
\fIfilter\fR
.IX Subsection "filter"
.PP
Constructs a named filter (which can act as both an output and an input)
within a chain.
.PP
.Vb 5
\&    message_chain {
\&        ...
\&        filter bar => ( output_to => \*(Aqfooenc\*(Aq, class => \*(AqNull\*(Aq );
\&        ...
\&    };
.Ve
.PP
Class names will be assumed to prefixed with 'Message::Passing::Filter::',
unless you prefix the class with + e.g. \f(CW\*(C`+My::Own::Filter::Class\*(C'\fR
.PP
\fIdecoder\fR
.IX Subsection "decoder"
.PP
Constructs a named decoder within a chain.
.PP
.Vb 4
\&    message_chain {
\&        decoder zmq_decode => ( output_to => \*(Aqfilter\*(Aq, class => \*(AqJSON\*(Aq );
\&        ....
\&    };
.Ve
.PP
Class names will be assumed to prefixed with 'Message::Passing::Filter::Decoder::',
unless you prefix the class with + e.g. \f(CW\*(C`+My::Own::Encoder::Class\*(C'\fR
.PP
\fIinput\fR
.IX Subsection "input"
.PP
The last thing in a chain \- produces data which gets consumed.
.PP
.Vb 5
\&    message_chain {
\&        ...
\&        input zmq => ( output_to => \*(Aqzmq_decode\*(Aq, class => \*(AqZeroMQ\*(Aq, bind => \*(Aq...\*(Aq );
\&        ....
\&    }
.Ve
.PP
Class names will be assumed to prefixed with 'Message::Passing::Output::',
unless you prefix the class with + e.g. \f(CW\*(C`+My::Own::Output::Class\*(C'\fR
.PP
\fIerror_log\fR
.IX Subsection "error_log"
.PP
Setup the error logging output. Takes the same arguments as an \f(CW\*(C`input xxx => ()\*(C'\fR block, except without a name.
.PP
\fIrun_message_server\fR
.IX Subsection "run_message_server"
.PP
This enters the event loop and causes log events to be consumed and
processed.
.PP
Can be passed a message_chain to run, although this is entirely optional
(as all chains which are still in scope will run when the event
loop is entered).
.SH "SPONSORSHIP"
.IX Header "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 \s-1API \-\s0
<http://www.surevoip.co.uk/support/wiki/api_documentation>
.SH "AUTHOR, COPYRIGHT AND LICENSE"
.IX Header "AUTHOR, COPYRIGHT AND LICENSE"
See Message::Passing.