view release on metacpan or  search on metacpan

lib/Agent/TCLI/Package/XMPP.pm  view on Meta::CPAN

package Agent::TCLI::Package::XMPP;
#
# $Id: XMPP.pm 59 2007-04-30 11:24:24Z hacker $
#
=pod

=head1 NAME

Agent::TCLI::Package::XMPP - A package of commands to access the XMPP transport

=head1 SYNOPSIS

	# Within a TCLI Agent script

	use Agent::TCLI::Transport::XMPP;
	use Agent::TCLI::Package::XMPP;

	my @packages = (
		Agent::TCLI::Package::XMPP->new(),
	);

	Agent::TCLI::Transport::XMPP->new(
	    'control_options'	=> {
		    'packages' 		=> \@packages,
	     },
	);


=head1 DESCRIPTION

This package provides commands for the control of the XMPP Transport from
within a TLCI Agent. One would typically want to have this command package
loaded when using the XMPP Transport, but it is not required.

This is still poorly documented. I apologize for the inconvenience.

=head1 INTERFACE

=cut

use warnings;
use strict;

use POE;
use Agent::TCLI::Command;
use Agent::TCLI::Parameter;
use Agent::TCLI::User;
use Getopt::Lucid qw(:all);

use Object::InsideOut qw(Agent::TCLI::Package::Base);

our $VERSION = '0.030.'.sprintf "%04d", (qw($Id: XMPP.pm 59 2007-04-30 11:24:24Z hacker $))[2];

=head2 ATTRIBUTES

The following attributes are accessible through standard <attribute>
methods unless otherwise noted.

These attrbiutes are generally internal and are probably only useful to
someone trying to enhance the functionality of this Package module.

=cut

=head2 METHODS

Most of these methods are for internal use within the TCLI system and may
be of interest only to developers trying to enhance TCLI.

=over

=item new ( hash of attributes )

Usually the only attributes that are useful on creation are the
verbose and do_verbose attrbiutes that are inherited from Agent::TCLI::Base.

=cut

sub _preinit :Preinit {
	my ($self,$args) = @_;

	$args->{'name'} = 'tcli_xmpp';

  	$args->{'session'} = POE::Session->create(
      object_states => [
          $self => [qw(
          	_start
          	_stop
          	_shutdown
          	_default

			change
			establish_context
			peer
			show
			shutdown
			)],
      ],
  	);

  	$args->{'opt_args'} = [qw( group_mode group_prefix verbose )];

}

sub _init :Init {
	my $self = shift;

	$self->Verbose("init: loading parameters and commands" );

	$self->LoadYaml(<<'...');
---
Agent::TCLI::Parameter:
  name: peers
  help: list the peers
  manual: >
    This debugging parameter can be used to list the peers currently
    loaded in a transport.
  type: Switch
---
Agent::TCLI::Parameter:
  name: controls
  help: list the controls
  manual: >
    This debugging parameter can be used to list the controls currently
    loaded in a transport.
  type: Switch
---
Agent::TCLI::Parameter:
  name: xmpp_verbose
  aliases: verbose|v
  constraints:
    - UINT
  help: an integer for verbosity
  manual: >
    This debugging parameter can be used to adjust the verbose setting
    for the XMPP transport.
  type: Counter
---
Agent::TCLI::Parameter:
  name: group_mode
  constraints:
    - ASCII
  help: sets how the control processes group chats
  manual: |
    The group_mode tells the control how to determine if a group chat
    message is directed at itself. The possible settings are:
        all - treat everything from others as a command
        log - ignore everything from others, only use chatroom for logging
        named - only accept commands prefixed by the name followed by a colon
        prefixed - only accept commands prefixed by the group_prefix,
          by default a colon
  type: Param
---
Agent::TCLI::Parameter:
  name: group_prefix
  constraints:
    - ASCII
  help: sets the prefix used in group chats
  manual: >
    The group_prefix sets the prefix used by the group_mode prefixed option.
    By default, it is a colon.
  type: Param
---
Agent::TCLI::Parameter:
  name: id
  constraints:
    - ASCII
  help: the user id
  manual: >
    ID of user in a form acceptable to the protocol.
    XMPP/Jabber IDs MUST not include resource information.
  type: Param
---
Agent::TCLI::Parameter:
  name: auth
  constraints:
    - ASCII
  help: Authorization level of user.
  manual: |
    Authorization level of user. MUST be one of these values:
      reader - has read access
      writer - has write access
      master - has root access
      logger - receives copies of all messages, can't do anything

    Note that commands must choose from the above to determine if a user can
    do anything. Not very robust, but hey, it's not even 1.0 yet.

    Every user should be defined with an B<auth>, but currently this is not
    being checked anywhere.
  type: Param
---
Agent::TCLI::Parameter:
  name: protocol
  constraints:
    - ASCII
  help: Protocol that user is allowed access on.
  manual: >
    Protocol that user is allowed access on. Currently only xmpp and
    xmpp-groupchat are supported by Transport::XMPP. If the protocol
    is xmpp-groupchat, the Transport will automatically join the
    conference room when the user is added.
  type: Param
---
Agent::TCLI::Parameter:
  name: password
  constraints:
    - ASCII
  help: A password for the user.
  manual: >
    A password for the user. For a private XMPP chatroom,
    this is used to log on. It is not used anywhere else currently.
  type: Param
---
Agent::TCLI::Command:
  call_style: session
  command: tcli_xmpp
  contexts:
    ROOT:
      - jabber
      - xmpp
  handler: establish_context
  help: 'manipulate the jabber/xmpp transport'
  manual: >
    This command allows one to control various aspects of the XMPP
    transport.
  name: xmpp
  topic: admin
  usage: xmpp change group_mode prefixed
---
Agent::TCLI::Command:
  name: change
  call_style: session
  command: tcli_xmpp
  contexts:
    jabber: change
    xmpp: change
  handler: change
  help: 'change the jabber/xmpp transport parameters'
  manual: >
    This command allows one to change one of several different parameters
    that control the operation of the XMPP transport.
  parameters:
    group_mode:
    group_prefix:
    xmpp_verbose:
  topic: admin
  usage: xmpp change group_mode prefixed
---
Agent::TCLI::Command:
  name: show
  call_style: session
  command: tcli_xmpp
  contexts:
    jabber: show
    xmpp: show
  handler: show
  help: 'show the jabber/xmpp transport settings'
  manual: >
    This command will show the current setting for parameters
    that control the operation of the XMPP transport. One can use all
    to see all the parameters.
  parameters:
    group_mode:
    group_prefix:
    xmpp_verbose:
    controls:
    peers:
  topic: admin
  usage: xmpp show group_mode
---
Agent::TCLI::Command: