.\" 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
.\"
.\" 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 "Protocol::IRC::Message 3pm"
.TH Protocol::IRC::Message 3pm "2021-01-08" "perl v5.32.0" "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"
"Protocol::IRC::Message" \- encapsulates a single IRC message
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& use Protocol::IRC::Message;
\&
\& my $hello = Protocol::IRC::Message\->new(
\&    "PRIVMSG",
\&    undef,
\&    "World",
\&    "Hello, world!"
\& );
\&
\& printf "The command is %s and the final argument is %s\en",
\&    $hello\->command, $hello\->arg( \-1 );
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
An object in this class represents a single \s-1IRC\s0 message, either received from
or to be sent to the server. These objects are immutable once constructed, but
provide a variety of methods to access the contained information.
.PP
This class also understands IRCv3 message tags.
.SH "CONSTRUCTOR"
.IX Header "CONSTRUCTOR"
.SS "new_from_line"
.IX Subsection "new_from_line"
.Vb 1
\&   $message = Protocol::IRC::Message\->new_from_line( $line )
.Ve
.PP
Returns a new \f(CW\*(C`Protocol::IRC::Message\*(C'\fR object, constructed by parsing the
given \s-1IRC\s0 line. Most typically used to create a new object to represent a
message received from the server.
.SS "new"
.IX Subsection "new"
.Vb 1
\&   $message = Protocol::IRC::Message\->new( $command, $prefix, @args )
.Ve
.PP
Returns a new \f(CW\*(C`Protocol::IRC::Message\*(C'\fR object, intialised from the given
components. Most typically used to create a new object to send to the server
using \f(CW\*(C`stream_to_line\*(C'\fR. The message will contain no IRCv3 tags.
.SS "new_from_named_args"
.IX Subsection "new_from_named_args"
.Vb 1
\&   $message = Protocol::IRC::Message\->new_from_named_args( $command, %args )
.Ve
.PP
Returns a new \f(CW\*(C`Protocol::IRC::Message\*(C'\fR object, initialised from the given
named argmuents. The argument names must match those required by the given
command.
.SS "new_with_tags"
.IX Subsection "new_with_tags"
.Vb 1
\&   $mesage = Protocol::IRC::Message\->new_with_tags( $command, \e%tags, $prefix, @args )
.Ve
.PP
Returns a new \f(CW\*(C`Protocol::IRC::Message\*(C'\fR object, as with \f(CW\*(C`new\*(C'\fR but also
containing the given IRCv3 tags.
.SH "METHODS"
.IX Header "METHODS"
.SS "\s-1STRING\s0"
.IX Subsection "STRING"
.Vb 1
\&   $str = $message\->STRING
\&
\&   $str = "$message"
.Ve
.PP
Returns a string representing the message, suitable for use in a debugging
message or similar. \fINote\fR: This is not the same as the \s-1IRC\s0 wire form, to
send to the \s-1IRC\s0 server; for that see \f(CW\*(C`stream_to_line\*(C'\fR.
.SS "command"
.IX Subsection "command"
.Vb 1
\&   $command = $message\->command
.Ve
.PP
Returns the command name or numeric stored in the message object.
.SS "command_name"
.IX Subsection "command_name"
.Vb 1
\&   $name = $message\->command_name
.Ve
.PP
For named commands, returns the command name directly. For server numeric
replies, returns the name of the numeric.
.SS "tags"
.IX Subsection "tags"
.Vb 1
\&   $tags = $message\->tags
.Ve
.PP
Returns a \s-1HASH\s0 reference containing IRCv3 message tags. This is a reference to
the hash stored directly by the object itself, so the caller should be careful
not to modify it.
.SS "prefix"
.IX Subsection "prefix"
.Vb 1
\&   $prefix = $message\->prefix
.Ve
.PP
Returns the line prefix stored in the object, or the empty string if one was
not supplied.
.SS "prefix_split"
.IX Subsection "prefix_split"
.Vb 1
\&   ( $nick, $ident, $host ) = $message\->prefix_split
.Ve
.PP
Splits the prefix into its nick, ident and host components. If the prefix
contains only a hostname (such as the server name), the first two components
will be returned as \f(CW\*(C`undef\*(C'\fR.
.SS "arg"
.IX Subsection "arg"
.Vb 1
\&   $arg = $message\->arg( $index )
.Ve
.PP
Returns the argument at the given index. Uses normal perl array indexing, so
negative indices work as expected.
.SS "args"
.IX Subsection "args"
.Vb 1
\&   @args = $message\->args
.Ve
.PP
Returns a list containing all the message arguments.
.SS "stream_to_line"
.IX Subsection "stream_to_line"
.Vb 1
\&   $line = $message\->stream_to_line
.Ve
.PP
Returns a string suitable for sending the message to the \s-1IRC\s0 server.
.SS "arg_names"
.IX Subsection "arg_names"
.Vb 1
\&   $names = $message\->arg_names
.Ve
.PP
Returns a \s-1HASH\s0 reference giving details on how to parse named arguments for
the command given in this message.
.PP
This will be a hash whose keys give the names of the arguments, and the values
of these keys indicate how that argument is derived from the simple positional
arguments.
.PP
Normally this method is only called internally by the \f(CW\*(C`named_args\*(C'\fR method,
but is documented here for the benefit of completeness, and in case extension
modules wish to define parsing of new message types.
.PP
Each value should be one of the following:
.IP "\(bu" 4
String literal \f(CW\*(C`pn\*(C'\fR
.Sp
The value is a string, the nickname given in the message prefix
.IP "\(bu" 4
\&\s-1NUMBER..NUMBER\s0
.Sp
The value is an \s-1ARRAY\s0 ref, containing a list of all the numbered arguments
between the (inclusive) given limits. Either or both limits may be negative;
they will count backwards from the end.
.IP "\(bu" 4
\&\s-1NUMBER\s0
.Sp
The value is the argument at that numeric index. May be negative to count
backwards from the end.
.IP "\(bu" 4
NUMBER@
.Sp
The value is the argument at that numeric index as for \f(CW\*(C`NUMBER\*(C'\fR, except that
the result will be split on spaces and stored in an \s-1ARRAY\s0 ref.
.SS "arg_names (class method)"
.IX Subsection "arg_names (class method)"
.Vb 1
\&   $names = Protocol::IRC::Message\->arg_names( $command )
.Ve
.PP
This method may also be invoked as a class method by passing in the command
name or numeric. This allows inspection of what arguments would be required
or returned before a message object itself is constructed.
.SS "named_args"
.IX Subsection "named_args"
.Vb 1
\&   $args = $message\->named_args
.Ve
.PP
Parses arguments in the message according to the specification given by the
\&\f(CW\*(C`arg_names\*(C'\fR method. Returns a hash of parsed arguments.
.PP
\&\s-1TODO:\s0 More complete documentation on the exact arg names/values per message
type.
.SS "gate_disposition"
.IX Subsection "gate_disposition"
.Vb 1
\&   $disp = $message\->gate_disposition
.Ve
.PP
Returns the \*(L"gating disposition\*(R" of the message. This defines how a reply
message from the server combines with other messages in response of a command
sent by the client. The disposition is either \f(CW\*(C`undef\*(C'\fR, or a string consisting
of a type symbol and a gate name. If defined, the symbol defines what effect
it has on the gate name.
.IP "\-GATE" 4
.IX Item "-GATE"
Adds more information to the response for that gate, but doesn't yet complete
it.
.IP "+GATE" 4
.IX Item "+GATE"
Completes the gate with a successful result.
.IP "*GATE" 4
.IX Item "*GATE"
Completes the gate with a successful result, but only if the nick in the
message prefix relates to the connection it is received on.
.IP "!GATE" 4
.IX Item "!GATE"
Completes the gate with a failure result.
.SH "AUTHOR"
.IX Header "AUTHOR"
Paul Evans <leonerd@leonerd.org.uk>