NAME

IRC::Mode::Set - A set of parsed IRC mode changes

SYNOPSIS

  ## Construct a new set of changes from a mode string:
  my $from_string = IRC::Mode::Set->new(
    mode_string => '+o-o+v avenj Joah Gilded',

    ## Optionally specify modes that take parameters (always or when set)
    ## defaults, should vaguely match ISUPPORT CHANMODES parameters:
    param_always => 'bkohv',
    param_on_set => 'l',
  );

  my $mode_array = $from_string->mode_array;
  ## $mode_array looks like:
  ## [
  ##   [ '+', 'o', 'avenj' ],
  ##   [ '-', 'o', 'Joah'  ],
  ##   [ '+', 'v', 'Gilded' ],
  ## ]

  ## Iterate over each mode change:
  while (my $change = $from_string->next) {
    ## $change is set to each individual array as seen above, in turn
  }

  ## Reset ->next() iterator to top:
  $from_string->reset;

  ## Like above loop, but get IRC::Mode::Single objects:
  while (my $this_mode = $from_string->next(as_object => 1) ) {
    ## $this_mode is an IRC::Mode::Single
  }

  ## Construct a new set of changes from an ARRAY
  ## (such as produced by IRC::Toolkit::Modes):
  my $from_array = IRC::Mode::Set->new(
    mode_array => $mode_array,
  );

  ## Get an IRC-appropriate string back out:
  my $str_from_array = $from_array->mode_string;

  ## Split a Set into multiple Sets with a max of $count items each
  ## (defaults to 4 changes per set if none specified)
  my @sets = $from_array->split_mode_set( 3 );
  
  ## Create a new Set containing matching items from this Set:
  my $modes_match = $from_array->clone_from_mode('v');
  my $args_match  = $from_array->clone_from_params('Joah');

DESCRIPTION

These objects provide a simple parser interface to IRC mode changes.

An understanding of the CHANMODES= directive in ISUPPORT will help immensely -- see http://www.irc.org/tech_docs/005.html

new

  my $set = IRC::Mode::Set->new(
    mode_string => '+o-o avenj Joah',
  );

  ## Or with IRC::Toolkit::Modes ->
  my $mode_array = mode_to_array($string);
  my $set = IRC::Mode::Set->new(
    mode_array  => $mode_array,
  );

Create a new IRC::Mode::Set from either a string or an ARRAY produced by IRC::Toolkit::Modes.

param_always can be specified (as a string or an ARRAY of modes) to indicate modes that are expected to always take a parameter. Defaults to 'bkohv'

param_on_set can be specified (as a string or an ARRAY of modes) to indicate modes that are expected to take a parameter only when set. Defaults to 'l'

See IRC::Toolkit::ISupport for an easy way to retrieve these values from a parsed ISUPPORT (005) numeric.

clone

Clone the instanced Mode::Set.

clone_from_mode

Takes a single mode character.

Returns a new Mode::Set composed of only modes in the existing set containing the specified mode character.

clone_from_params

Takes a pattern or regexp object.

Returns a new Mode::Set composed of only modes in the existing set with parameters matching the pattern.

mode_array

Returns the array-of-arrays containing each change in the Set.

This is a data structure in the form of:

  [
    [ $mode_flag, $mode_char, $param ],
    ...
  ]

Also see "mode_to_array" in IRC::Toolkit::Modes

modes_as_objects

Returns a list of IRC::Mode::Single objects constructed from our current "mode_array".

mode_string

Returns the string representing the mode change.

as_string

as_string is an alias for mode_string to retain compatibility with IRC::Mode::Single.

params

Retrieve only the parameters to the mode change (as an ARRAY)

next

Iterates the array-of-arrays composing the Set.

Returns the next ARRAY in the set (or empty list if none left).

If as_object => 1 is specified, an IRC::Mode::Single object is returned.

Reset to top by calling "reset".

reset

Resets the "next" iterator.

split_mode_set

Given an integer parameter $x, splits a Set into smaller Sets containing at most $x single mode changes.

Defaults to 4, which is a common ISUPPORT MODES= setting.

AUTHOR

Jon Portnoy <avenj@cobaltirc.org>