NAME

       "Protocol::IRC::Message" - encapsulates a single IRC message

SYNOPSIS

        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\n",
           $hello->command, $hello->arg( -1 );

DESCRIPTION

       An object in this class represents a single IRC 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.

       This class also understands IRCv3 message tags.

CONSTRUCTOR

   new_from_line
          $message = Protocol::IRC::Message->new_from_line( $line )

       Returns a new "Protocol::IRC::Message" object, constructed by parsing the given IRC line.
       Most typically used to create a new object to represent a message received from the
       server.

   new
          $message = Protocol::IRC::Message->new( $command, $prefix, @args )

       Returns a new "Protocol::IRC::Message" object, intialised from the given components. Most
       typically used to create a new object to send to the server using "stream_to_line". The
       message will contain no IRCv3 tags.

   new_from_named_args
          $message = Protocol::IRC::Message->new_from_named_args( $command, %args )

       Returns a new "Protocol::IRC::Message" object, initialised from the given named arguments.
       The argument names must match those required by the given command.

   new_with_tags
          $mesage = Protocol::IRC::Message->new_with_tags( $command, \%tags, $prefix, @args )

       Returns a new "Protocol::IRC::Message" object, as with "new" but also containing the given
       IRCv3 tags.

METHODS

   STRING
          $str = $message->STRING

          $str = "$message"

       Returns a string representing the message, suitable for use in a debugging message or
       similar. Note: This is not the same as the IRC wire form, to send to the IRC server; for
       that see "stream_to_line".

   command
          $command = $message->command

       Returns the command name or numeric stored in the message object.

   command_name
          $name = $message->command_name

       For named commands, returns the command name directly. For server numeric replies, returns
       the name of the numeric.

   tags
          $tags = $message->tags

       Returns a HASH 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.

   prefix
          $prefix = $message->prefix

       Returns the line prefix stored in the object, or the empty string if one was not supplied.

   prefix_split
          ( $nick, $ident, $host ) = $message->prefix_split

       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 "undef".

   arg
          $arg = $message->arg( $index )

       Returns the argument at the given index. Uses normal perl array indexing, so negative
       indices work as expected.

   args
          @args = $message->args

       Returns a list containing all the message arguments.

   stream_to_line
          $line = $message->stream_to_line

       Returns a string suitable for sending the message to the IRC server.

   arg_names
          $names = $message->arg_names

       Returns a HASH reference giving details on how to parse named arguments for the command
       given in this message.

       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.

       Normally this method is only called internally by the "named_args" method, but is
       documented here for the benefit of completeness, and in case extension modules wish to
       define parsing of new message types.

       Each value should be one of the following:

       •   String literal "pn"

           The value is a string, the nickname given in the message prefix

       •   NUMBER..NUMBER

           The value is an ARRAY 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.

       •   NUMBER

           The value is the argument at that numeric index. May be negative to count backwards
           from the end.

       •   NUMBER@

           The value is the argument at that numeric index as for "NUMBER", except that the
           result will be split on spaces and stored in an ARRAY ref.

   arg_names (class method)
          $names = Protocol::IRC::Message->arg_names( $command )

       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.

   named_args
          $args = $message->named_args

       Parses arguments in the message according to the specification given by the "arg_names"
       method. Returns a hash of parsed arguments.

       TODO: More complete documentation on the exact arg names/values per message type.

   gate_disposition
          $disp = $message->gate_disposition

       Returns the "gating disposition" 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 "undef", 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.

       -GATE
           Adds more information to the response for that gate, but doesn't yet complete it.

       +GATE
           Completes the gate with a successful result.

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

       !GATE
           Completes the gate with a failure result.

AUTHOR

       Paul Evans <leonerd@leonerd.org.uk>