Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
POE::Component::IRC::SUser(Contributed Perl DocumPOE::Component::IRC::State(3)

NAME
       POE::Component::IRC::State - A fully event-driven IRC client module
       with nickname and channel tracking

SYNOPSIS
	# A simple Rot13 'encryption' bot

	use strict;
	use warnings;
	use POE	qw(Component::IRC::State);

	my $nickname = 'Flibble' . $$;
	my $ircname = 'Flibble the Sailor Bot';
	my $ircserver =	'irc.blahblahblah.irc';
	my $port = 6667;

	my @channels = ( '#Blah', '#Foo', '#Bar' );

	# We create a new PoCo-IRC object and component.
	my $irc	= POE::Component::IRC::State->spawn(
	    nick => $nickname,
	    server => $ircserver,
	    port => $port,
	    ircname => $ircname,
	) or die "Oh noooo! $!";

	POE::Session->create(
	    package_states => [
		main =>	[ qw(_default _start irc_001 irc_public) ],
	    ],
	    heap => { irc => $irc },
	);

	$poe_kernel->run();

	sub _start {
	    my ($kernel, $heap)	= @_[KERNEL, HEAP];

	    # We get the session ID of the component from the object
	    # and register and connect to the specified	server.
	    my $irc_session = $heap->{irc}->session_id();
	    $kernel->post( $irc_session	=> register => 'all' );
	    $kernel->post( $irc_session	=> connect => {	} );
	    return;
	}

	sub irc_001 {
	    my ($kernel, $sender) = @_[KERNEL, SENDER];

	    # Get the component's object at any	time by	accessing the heap of
	    # the SENDER
	    my $poco_object = $sender->get_heap();
	    print "Connected to	", $poco_object->server_name(),	"\n";

	    # In any irc_* events SENDER will be the PoCo-IRC session
	    $kernel->post( $sender => join => $_ ) for @channels;
	    return;
	}

	sub irc_public {
	    my ($kernel	,$sender, $who,	$where,	$what) = @_[KERNEL, SENDER, ARG0 .. ARG2];
	    my $nick = ( split /!/, $who )[0];
	    my $channel	= $where->[0];
	    my $poco_object = $sender->get_heap();

	    if ( my ($rot13) = $what =~	/^rot13	(.+)/ )	{
		# Only operators can issue a rot13 command to us.
		return if !$poco_object->is_channel_operator( $channel,	$nick );

		$rot13 =~ tr[a-zA-Z][n-za-mN-ZA-M];
		$kernel->post( $sender => privmsg => $channel => "$nick: $rot13" );
	    }
	    return;
	}

	# We registered	for all	events,	this will produce some debug info.
	sub _default {
	    my ($event,	$args) = @_[ARG0 .. $#_];
	    my @output = ( "$event: " );

	    for	my $arg	( @$args ) {
		if (ref	$arg  eq 'ARRAY') {
		    push( @output, '[' . join(', ', @$arg ) . ']' );
		}
		else {
		    push ( @output, "'$arg'" );
		}
	    }
	    print join ' ', @output, "\n";
	    return 0;
	}

DESCRIPTION
       POE::Component::IRC::State is a sub-class of POE::Component::IRC	which
       tracks IRC state	entities such as nicks and channels. See the
       documentation for POE::Component::IRC for general usage.	 This document
       covers the extra	methods	that POE::Component::IRC::State	provides.

       The component tracks channels and nicks,	so that	it always has a
       current snapshot	of what	channels it is on and who else is on those
       channels. The returned object provides methods to query the collected
       state.

CONSTRUCTORS
       POE::Component::IRC::State's constructors, and its "connect" event, all
       take the	same arguments as POE::Component::IRC does, as well as two
       additional ones:

       'AwayPoll', the interval	(in seconds) in	which to poll (i.e. "WHO
       #channel") the away status of channel members. Defaults to 0
       (disabled). If enabled, you will	receive	"irc_away_sync_*" /
       "irc_user_away" / "irc_user_back" events, and will be able to use the
       "is_away" method	for users other	than yourself. This can	cause a	lot of
       increase	in traffic, especially if you are on big channels, so if you
       do use this, you	probably don't want to set it too low. For reference,
       X-Chat uses 300 seconds (5 minutes).

       'WhoJoiners', a boolean indicating whether the component	should send a
       "WHO nick" for every person which joins a channel. Defaults to on (the
       "WHO" is	sent). If you turn this	off, "is_operator" will	not work and
       "nick_info" will	only return the	keys 'Nick', 'User', 'Host' and
       'Userhost'.

METHODS
       All of the POE::Component::IRC methods are supported, plus the
       following:

   "ban_mask"
       Expects a channel and a ban mask, as passed to MODE +b-b. Returns a
       list of nicks on	that channel that match	the specified ban mask or an
       empty list if the channel doesn't exist in the state or there are no
       matches.

   "channel_ban_list"
       Expects a channel as a parameter. Returns a hashref containing the
       banlist if the channel is in the	state, a false value if	not. The
       hashref keys are	the entries on the list, each with the keys 'SetBy'
       and 'SetAt'. These keys will hold the nick!hostmask of the user who set
       the entry (or just the nick if it's all the ircd	gives us), and the
       time at which it	was set	respectively.

   "channel_creation_time"
       Expects a channel as parameter. Returns channel creation	time or	a
       false value.

   "channel_except_list"
       Expects a channel as a parameter. Returns a hashref containing the ban
       exception list if the channel is	in the state, a	false value if not.
       The hashref keys	are the	entries	on the list, each with the keys
       'SetBy' and 'SetAt'. These keys will hold the nick!hostmask of the user
       who set the entry (or just the nick if it's all the ircd	gives us), and
       the time	at which it was	set respectively.

   "channel_invex_list"
       Expects a channel as a parameter. Returns a hashref containing the
       invite exception	list if	the channel is in the state, a false value if
       not. The	hashref	keys are the entries on	the list, each with the	keys
       'SetBy' and 'SetAt'. These keys will hold the nick!hostmask of the user
       who set the entry (or just the nick if it's all the ircd	gives us), and
       the time	at which it was	set respectively.

   "channel_key"
       Expects a channel as parameter. Returns the channel key or a false
       value.

   "channel_limit"
       Expects a channel as parameter. Returns the channel limit or a false
       value.

   "channel_list"
       Expects a channel as parameter. Returns a list of all nicks on the
       specified channel. If the component happens to not be on	that channel
       an empty	list will be returned.

   "channel_modes"
       Expects a channel as parameter. Returns a hash ref keyed	on channel
       mode, with the mode argument (if	any) as	the value. Returns a false
       value instead if	the channel is not in the state.

   "channels"
       Takes no	parameters. Returns a hashref, keyed on	channel	name and
       whether the bot is operator, halfop or has voice	on that	channel.

	for my $channel	( keys %{ $irc->channels() } ) {
	    $irc->yield( 'privmsg' => $channel => 'm00!' );
	}

   "channel_topic"
       Expects a channel as a parameter. Returns a hashref containing topic
       information if the channel is in	the state, a false value if not. The
       hashref contains	the following keys: 'Value', 'SetBy', 'SetAt'. These
       keys will hold the topic	itself,	the nick!hostmask of the user who set
       it (or just the nick if it's all	the ircd gives us), and	the time at
       which it	was set	respectively.

       If the component	happens	to not be on the channel, nothing will be
       returned.

   "channel_url"
       Expects a channel as a parameter. Returns the channel's URL. If the
       channel has no URL or the component is not on the channel, nothing will
       be returned.

   "has_channel_voice"
       Expects a channel and a nickname	as parameters. Returns a true value if
       the nick	has voice on the specified channel. Returns false if the nick
       does not	have voice on the channel or if	the nick/channel does not
       exist in	the state.

   "is_away"
       Expects a nick as parameter. Returns a true value if the	specified nick
       is away.	 Returns a false value if the nick is not away or not in the
       state. This will	only work for your IRC user unless you specified a
       value for 'AwayPoll' in "spawn".

   "is_channel_admin"
       Expects a channel and a nickname	as parameters. Returns a true value if
       the nick	is an admin on the specified channel. Returns false if the
       nick is not an admin on the channel or if the nick/channel does not
       exist in	the state.

   "is_channel_halfop"
       Expects a channel and a nickname	as parameters. Returns a true value if
       the nick	is a half-operator on the specified channel. Returns false if
       the nick	is not a half-operator on the channel or if the	nick/channel
       does not	exist in the state.

   "is_channel_member"
       Expects a channel and a nickname	as parameters. Returns a true value if
       the nick	is on the specified channel. Returns false if the nick is not
       on the channel or if the	nick/channel does not exist in the state.

   "is_channel_mode_set"
       Expects a channel and a single mode flag	"[A-Za-z]". Returns a true
       value if	that mode is set on the	channel.

   "is_channel_operator"
       Expects a channel and a nickname	as parameters. Returns a true value if
       the nick	is an operator on the specified	channel. Returns false if the
       nick is not an operator on the channel or if the	nick/channel does not
       exist in	the state.

   "is_channel_owner"
       Expects a channel and a nickname	as parameters. Returns a true value if
       the nick	is an owner on the specified channel. Returns false if the
       nick is not an owner on the channel or if the nick/channel does not
       exist in	the state.

   "is_channel_synced"
       Expects a channel as a parameter. Returns true if the channel has been
       synced.	Returns	false if it has	not been synced	or if the channel is
       not in the state.

   "is_operator"
       Expects a nick as parameter. Returns a true value if the	specified nick
       is an IRC operator. Returns a false value if the	nick is	not an IRC
       operator	or is not in the state.

   "is_user_mode_set"
       Expects single user mode	flag "[A-Za-z]". Returns a true	value if that
       user mode is set.

   "nick_channel_modes"
       Expects a channel and a nickname	as parameters. Returns the modes of
       the specified nick on the specified channel (ie.	qaohv).	If the nick is
       not on the channel in the state,	a false	value will be returned.

   "nick_channels"
       Expects a nickname. Returns a list of the channels that that nickname
       and the component are on. An empty list will be returned	if the
       nickname	does not exist in the state.

   "nick_info"
       Expects a nickname. Returns a hashref containing	similar	information to
       that returned by	WHOIS. Returns a false value if	the nickname doesn't
       exist in	the state. The hashref contains	the following keys:

       'Nick', 'User', 'Host', 'Userhost', 'Hops', 'Real', 'Server' and, if
       applicable, 'IRCop'.

   "nick_long_form"
       Expects a nickname. Returns the long form of that nickname, ie.
       "nick!user@host"	or a false value if the	nick is	not in the state.

   "nicks"
       Takes no	parameters. Returns a list of all the nicks, including itself,
       that it knows about. If the component happens to	be on no channels then
       an empty	list is	returned.

   "umode"
       Takes no	parameters. Returns the	current	user mode set for the bot.

OUTPUT EVENTS
   Augmented events
       New parameters are added	to the following POE::Component::IRC events.

       "irc_quit"

       See also	"irc_quit" in POE::Component::IRC.

       Additional parameter "ARG2" contains an arrayref	of channel names that
       are common to the quitting client and the component.

       "irc_nick"

       See also	"irc_nick" in POE::Component::IRC.

       Additional parameter "ARG2" contains an arrayref	of channel names that
       are common to the nick hanging client and the component.

       "irc_kick"

       See also	"irc_kick" in POE::Component::IRC.

       Additional parameter "ARG4" contains the	full nick!user@host of the
       kicked individual.

       "irc_topic"

       See also	"irc_kick" in POE::Component::IRC.

       Additional parameter "ARG3" contains the	old topic hashref, like	the
       one returned by "channel_topic".

       "irc_disconnected"

       "irc_error"

       "irc_socketerr"

       These three all have two	additional parameters. "ARG1" is a hash	of
       information about your IRC user (see "nick_info"), while	"ARG2" is a
       hash of the channels you	were on	(see "channels").

   New events
       As well as all the usual	POE::Component::IRC "irc_*" events, there are
       the following events you	can register for:

       "irc_away_sync_start"

       Sent whenever the component starts to synchronise the away statuses of
       channel members.	"ARG0" is the channel name. You	will only receive this
       event if	you specified a	value for 'AwayPoll' in	"spawn".

       "irc_away_sync_end"

       Sent whenever the component has completed synchronising the away
       statuses	of channel members. "ARG0" is the channel name.	You will only
       receive this event if you specified a value for 'AwayPoll' in "spawn".

       "irc_chan_mode"

       This is almost identical	to "irc_mode", except that it's	sent once for
       each individual mode with it's respective argument if it	has one	(ie.
       the banmask if it's +b or -b). However, this event is only sent for
       channel modes.

       "irc_chan_sync"

       Sent whenever the component has completed synchronising a channel that
       it has joined. "ARG0" is	the channel name and "ARG1" is the time	in
       seconds that the	channel	took to	synchronise.

       "irc_chan_sync_invex"

       Sent whenever the component has completed synchronising a channel's
       INVEX (invite list). Usually triggered by the component being opped on
       a channel.  "ARG0" is the channel name.

       "irc_chan_sync_excepts"

       Sent whenever the component has completed synchronising a channel's
       EXCEPTS (ban exemption list). Usually triggered by the component	being
       opped on	a channel. "ARG0" is the channel.

       "irc_nick_sync"

       Sent whenever the component has completed synchronising a user who has
       joined a	channel	the component is on. "ARG0" is the user's nickname and
       "ARG1" the channel they have joined.

       "irc_user_away"

       Sent when an IRC	user sets his/her status to away. "ARG0" is the
       nickname, "ARG1"	is an arrayref of channel names	that are common	to the
       nickname	and the	component. You will only receive this event if you
       specified a value for 'AwayPoll'	in "spawn".

       Note: This above	is only	for users other	than yourself. To know when
       you change your own away	status,	register for the "irc_305" and
       "irc_306" events.

       "irc_user_back"

       Sent when an IRC	user unsets his/her away status. "ARG0"	is the
       nickname, "ARG1"	is an arrayref of channel names	that are common	to the
       nickname	and the	component. You will only receive this event if you
       specified a value for 'AwayPoll'	in "spawn".

       Note: This above	is only	for users other	than yourself. To know when
       you change your own away	status,	register for the "irc_305" and
       "irc_306" events.

       "irc_user_mode"

       This is almost identical	to "irc_mode", except it is sent for each
       individual umode	that is	being set.

CAVEATS
       The component gathers information by registering	for "irc_quit",
       "irc_nick", "irc_join", "irc_part", "irc_mode", "irc_kick" and various
       numeric replies.	 When the component is asked to	join a channel,	when
       it joins	it will	issue 'WHO #channel', 'MODE #channel', and 'MODE
       #channel	b'. These will solicit between them the	numerics, "irc_352",
       "irc_324" and "irc_329",	respectively.  When someone joins a channel
       the bot is on, it issues	a 'WHO nick'. You may want to ignore these.

       Currently, whenever the component sees a	topic or channel list change,
       it will use "time" for the SetAt	value and the full address of the user
       who set it for the SetBy	value. When an ircd gives us its record	of
       such changes, it	will use its own time (obviously) and may only give us
       the nickname of the user, rather	than their full	address. Thus, if our
       "time" and the ircd's time do not match,	or the ircd uses the nickname
       only, ugly inconsistencies can develop.	This leaves the	'SetAt'	and
       'SetBy' values inaccurate at best, and you should use them with this in
       mind (for now, at least).

AUTHOR
       Chris Williams <chris@bingosnet.co.uk>

       With contributions from Lyndon Miller.

LICENCE
       This module may be used,	modified, and distributed under	the same terms
       as Perl itself. Please see the license that came	with your Perl
       distribution for	details.

SEE ALSO
       POE::Component::IRC

       POE::Component::IRC::Qnet::State

perl v5.24.1			  2014-06-28	 POE::Component::IRC::State(3)

NAME | SYNOPSIS | DESCRIPTION | CONSTRUCTORS | METHODS | OUTPUT EVENTS | CAVEATS | AUTHOR | LICENCE | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=POE::Component::IRC::State&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help