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

FreeBSD Manual Pages

  
 
  

home | help
POE::Component::IRC::PUsernContributedEPeromponent::IRC::Plugin::BotCommand(3)

NAME
       POE::Component::IRC::Plugin::BotCommand - A PoCo-IRC plugin which
       handles commands	issued to your bot

SYNOPSIS
	use POE;
	use POE::Component::Client::DNS;
	use POE::Component::IRC;
	use POE::Component::IRC::Plugin::BotCommand;

	my @channels = ('#channel1', '#channel2');
	my $dns	= POE::Component::Client::DNS->spawn();
	my $irc	= POE::Component::IRC->spawn(
	    nick   => 'YourBot',
	    server => 'some.irc.server',
	);

	POE::Session->create(
	    package_states => [
		main =>	[ qw(_start irc_001 irc_botcmd_slap irc_botcmd_lookup dns_response) ],
	    ],
	);

	$poe_kernel->run();

	sub _start {
	    $irc->plugin_add('BotCommand', POE::Component::IRC::Plugin::BotCommand->new(
		Commands => {
		    slap   => 'Takes one argument: a nickname to slap.',
		    lookup => 'Takes two arguments: a record type (optional), and a host.',
		}
	    ));
	    $irc->yield(register => qw(001 botcmd_slap botcmd_lookup));
	    $irc->yield(connect	=> { });
	}

	# join some channels
	sub irc_001 {
	    $irc->yield(join =>	$_) for	@channels;
	    return;
	}

	# the good old slap
	sub irc_botcmd_slap {
	    my $nick = (split /!/, $_[ARG0])[0];
	    my ($where,	$arg) =	@_[ARG1, ARG2];
	    $irc->yield(ctcp =>	$where,	"ACTION	slaps $arg");
	    return;
	}

	# non-blocking dns lookup
	sub irc_botcmd_lookup {
	    my $nick = (split /!/, $_[ARG0])[0];
	    my ($where,	$arg) =	@_[ARG1, ARG2];
	    my ($type, $host) =	$arg =~	/^(?:(\w+) )?(\S+)/;

	    my $res = $dns->resolve(
		event => 'dns_response',
		host =>	$host,
		type =>	$type,
		context	=> {
		    where => $where,
		    nick  => $nick,
		},
	    );
	    $poe_kernel->yield(dns_response => $res) if	$res;
	    return;
	}

	sub dns_response {
	    my $res = $_[ARG0];
	    my @answers	= map {	$_->rdatastr } $res->{response}->answer() if $res->{response};

	    $irc->yield(
		'notice',
		$res->{context}->{where},
		$res->{context}->{nick}	. (@answers
		    ? ": @answers"
		    : ': no answers for	"' . $res->{host} . '"')
	    );

	    return;
	}

DESCRIPTION
       POE::Component::IRC::Plugin::BotCommand is a POE::Component::IRC
       plugin. It provides you with a standard interface to define bot
       commands	and lets you know when they are	issued.	Commands are accepted
       as channel or private messages.

       The plugin will respond to the 'help' command by	default, listing
       available commands and information on how to use	them. However, if you
       add a help command yourself, that one will be used instead.

METHODS
   "new"
       'Commands', a hash reference, with your commands	as keys, and usage
       information as values. If the usage string contains newlines, the
       plugin will send	one message for	each line.

       If a command's value is a HASH ref like this:

	    $irc->plugin_add('BotCommand', POE::Component::IRC::Plugin::BotCommand->new(
		Commands => {
		    slap   => {
		       info => 'Slap someone',
		       args => [qw(nickname)],
		       nickname	=> 'nickname to	slap'
		    }
		}
	    ));

       The args	array reference	is than	used to	validate number	of arguments
       required	and to name arguments passed to	event handler. Help is than
       generated from "info" and other hash keys which represent arguments
       (they are optional).

       An optional "handler" key can be	specified inside the HASH ref to
       override	the event handler.  The	irc_botcmd_ prefix  is not
       automatically prepended	to the handler name when overriding it.

       An optional "aliases"  key can be specified inside the HASH ref
       containing a array ref with alias names.	 The aliases can be specified
       for help	and to run the command.

       Accepting commands

       'In_channels', a	boolean	value indicating whether to accept commands in
       channels. Default is true.

       'In_private', a boolean value indicating	whether	to accept commands in
       private.	Default	is true.

       'Addressed', requires users to address the bot by name in order to
       issue commands. Default is true.

       'Prefix', a string which	all commands must be prefixed with (except in
       channels	when 'Addressed' is true). Default is '!'. You can set it to
       '' to allow bare	commands.

       'Bare_private', a boolean value indicating whether bare commands
       (without	the prefix) are	allowed	in private messages. Default is	false.

       Authorization

       'Auth_sub', a subroutine	reference which, if provided, will be called
       for every command. The subroutine will be called	in list	context. If
       the first value returned	is true, the command will be processed as
       normal. If the value is false, then no events will be generated,	and an
       error message will possibly be sent back	to the user.

       You can override	the default error message by returning a second	value,
       an array	reference of (zero or more) strings. Each string will be sent
       as a message to the user.

       Your subroutine will be called with the following arguments:

       1. The IRC component object
       2. The nick!user@host of	the user
       3. The place where the command was issued (the nickname of the user if
       it was in private)
       4. The name of the command
       5. The command argument string

       'Ignore_unauthorized', if true, the plugin will ignore unauthorized
       commands, rather	than printing an error message upon receiving them.
       This is only relevant if	'Auth_sub' is also supplied. Default is	false.

       Help Command

       'Help_sub', a subroutine	reference which, if provided, will be called
       upon the	end of the predefined help command. The	subroutine will	be
       called in list context.

       Your subroutine will be called with the following arguments:

       1. The IRC component object
       2. The command.
       3. The resolved command(after alias processing).
       4. The arguments.
       5. The generated	help text as array.

       Miscellaneous

       'Ignore_unknown', if true, the plugin will ignore undefined commands,
       rather than printing a help message upon	receiving them.	Default	is
       false.

       'Method', how you want help messages to be delivered. Valid options are
       'notice'	(the default) and 'privmsg'.

       'Eat', set to true to make the plugin hide "irc_public" events from
       other plugins when they look like commands. Probably only useful	when a
       'Prefix'	is defined. Default is false.

       Returns a plugin	object suitable	for feeding to POE::Component::IRC's
       "plugin_add" method.

   "add"
       Adds a new command. Takes two arguments,	the name of the	command, and a
       string or hash reference	containing its usage information (see "new").
       Returns false if	the command has	already	been defined or	no info	or
       arguments are provided, true otherwise.

   "remove"
       Removes a command. Takes	one argument, the name of the command. Returns
       false if	the command wasn't defined to begin with, true otherwise.

   "list"
       Takes no	arguments. Returns a list of key/value pairs, the keys being
       the command names and the values	being the usage	strings	or hash
       references.

   "resolve_alias"
       Takes one argument, a string to match against command aliases, if no
       matching	command	can be found undef is returned.

OUTPUT EVENTS
   "irc_botcmd_*"
       You will	receive	an event like this for every valid command issued.
       E.g. if 'slap' were a valid command, you	would receive an
       "irc_botcmd_slap" event every time someone issued that command. It
       receives	the following arguments:

       o   "ARG0": the nick!hostmask of	the user who issued the	command.

       o   "ARG1" is the name of the channel in	which the command was issued,
	   or the sender's nickname if this was	a private message.

       o   "ARG2": a string of arguments to the	command, or hash reference
	   with	arguments in case you defined command along with arguments, or
	   undef if there were no arguments

AUTHOR
       Hinrik Arn SigurA<degree>sson, hinrik.sig@gmail.com

perl v5.24.1			  20POE::Component::IRC::Plugin::BotCommand(3)

NAME | SYNOPSIS | DESCRIPTION | METHODS | OUTPUT EVENTS | AUTHOR

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

home | help