NAME

IRC::Toolkit::Modes - IRC mode parsing utilities

SYNOPSIS

  use IRC::Toolkit::Modes;
  my $mode_string = '+o-o avenj Joah';
  my $array = mode_to_array( $mode_string );
  my $hash  = mode_to_hash( $mode_string );

DESCRIPTION

Utility functions for parsing IRC mode strings.

Also see IRC::Mode::Set for an object-oriented approach to modes.

mode_to_array

  my $array = mode_to_array(
    ## Mode change string with or without params, e.g. '+kl-t'
    $mode_string,

    ## Modes that always have a param:
    param_always => ARRAY,

    ## Modes that only have a param when set:
    param_set    => ARRAY,

    ## Respective params for modes specified above
    ## (or can be specified as part of mode string)
    params       => ARRAY,
  );

Given a mode string and some options, return an ARRAY of ARRAYs containing parsed mode changes.

The structure looks like:

  [
    [ FLAG, MODE, MAYBE_PARAM ],
    [ . . . ],
  ]

For example:

  mode_to_array( '+kl-t',
    params => [ 'key', 10 ],
    param_always => [ split //, 'bkov' ],
    param_set    => [ 'l' ],
  );

  ## Result:
  [
    [ '+', 'k', 'key' ],
    [ '+', 'l', 10 ],
    [ '-', 't' ],
  ],

If the mode string contains (space-delimited) parameters, they are given precedence ahead of the optional 'params' ARRAY.

Instead of manually specifying param_always and param_set, you can pass in the chanmodes object provided by IRC::Toolkit::ISupport:

  my $isupport = parse_isupport(@isupport_lines);
  my $array = mode_to_array( '+kl-t',
    params => [ 'key', 10 ],
    isupport_chanmodes => $isupport->chanmodes,
  );

isupport_chanmodes will override param_always / param_set -- if that's not acceptable, you can select individual sets:

  my $array = mode_to_array( '+klX-t',
    params => [ 'key', 10, 'foo' ],
    param_always => $isupport->chanmodes->always,
    param_set    => [ 'lX' ],

array_to_mode

Takes an ARRAY such as that produced by "mode_to_array" and returns an IRC mode string.

mode_to_hash

Takes the same parameters as "mode_to_array" -- this is just a way to inflate the ARRAY to a hash.

Given a mode string and some options, return a HASH with the keys add and del.

add and del are HASHes mapping mode characters to either a simple boolean true value or an ARRAY whose only element is the mode's parameters, e.g.:

  mode_to_hash( '+kl-t',
    params => [ 'key', 10 ],
    param_always => [ split //, 'bkov' ],
    param_set    => [ 'l' ],
  );

  ## Result:
  {
    add => {
      'l' => [ 10 ],
      'k' => [ 'key' ],
    },

    del => {
      't' => 1,
    },
  }

This is a 'lossy' approach that won't deal well with multiple conflicting mode changes in a single line; "mode_to_array" should generally be preferred.

AUTHOR

Jon Portnoy <avenj@cobaltirc.org>