.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" 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 >0, 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
.\" ========================================================================
.\"
.IX Title "Tirex::Message 3pm"
.TH Tirex::Message 3pm "2021-10-07" "perl v5.32.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"
Tirex::Message \- A message
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
my \f(CW$msg\fR = Tirex::Message\->new( ... );
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Messages are used to exchange requests and replies between different components
of the Tirex system.
.PP
\&\*(L"On the wire\*(R" they consist of several lines (separated by an optional carriage
return and a newline). Each line has the form \*(L"key=value\*(R". No spaces are
allowed before or after the key or equals sign.
.SH "METHODS"
.IX Header "METHODS"
.ie n .SS "Tirex::Message\->new( type => '...', field1key => ""field2value"", ... )"
.el .SS "Tirex::Message\->new( type => '...', field1key => ``field2value'', ... )"
.IX Subsection "Tirex::Message->new( type => '...', field1key => field2value, ... )"
Create new message. You always need a type for the message, all other
fields are optional.
.PP
Will croak if there is no type given.
.ie n .SS "Tirex::Message\->new_from_string(""type=foo\enbar=baz\en"");"
.el .SS "Tirex::Message\->new_from_string(``type=foo\enbar=baz\en'');"
.IX Subsection "Tirex::Message->new_from_string(type=foonbar=bazn);"
Create message object from string.
.SS "Tirex::Message\->new_from_socket($socket)"
.IX Subsection "Tirex::Message->new_from_socket($socket)"
Read a datagram from given socket and create new message from it.
.ie n .SS "$msg\->reply([RESULT[, \s-1ERRMSG\s0]])"
.el .SS "\f(CW$msg\fP\->reply([RESULT[, \s-1ERRMSG\s0]])"
.IX Subsection "$msg->reply([RESULT[, ERRMSG]])"
Create new message with reply to old one. If \s-1RESULT\s0 is not given
it defaults to 'ok'. If \s-1ERRMSG\s0 is given, it is attached to the
message.
.PP
You can't send a reply to a reply, so if the original message
contains a 'result' field, this method croaks.
.ie n .SS "$msg\->\fBserialize()\fP"
.el .SS "\f(CW$msg\fP\->\fBserialize()\fP"
.IX Subsection "$msg->serialize()"
Serialize this message into a string with lines of the format
key=value.
.PP
If a value is undefined the field is not added.
.ie n .SS "$msg\->\fBto_s()\fP"
.el .SS "\f(CW$msg\fP\->\fBto_s()\fP"
.IX Subsection "$msg->to_s()"
Return string version of this message, for instance for debugging.
Format is key=value separated by spaces.
.PP
If a value is undefined the field is not added.
.ie n .SS "$msg\->send($socket, $dest)"
.el .SS "\f(CW$msg\fP\->send($socket, \f(CW$dest\fP)"
.IX Subsection "$msg->send($socket, $dest)"
Send message through \f(CW$socket\fR to \f(CW$dest\fR.
.ie n .SS "$msg\->\fBto_metatile()\fP"
.el .SS "\f(CW$msg\fP\->\fBto_metatile()\fP"
.IX Subsection "$msg->to_metatile()"
Create metatile from message.
.PP
Croaks when the message can't be made into a valid metatile.
.ie n .SS "$msg\->\fBok()\fP"
.el .SS "\f(CW$msg\fP\->\fBok()\fP"
.IX Subsection "$msg->ok()"
Is this message a positive reply (contains 'result=ok')?
.ie n .SS "$msg\->\fBunknown_message_type()\fP"
.el .SS "\f(CW$msg\fP\->\fBunknown_message_type()\fP"
.IX Subsection "$msg->unknown_message_type()"
Is this an error message for an unknown message type (contains
\&'result=error_unknown_command')?