/usr/share/doc/atheme/perl/Atheme.pod is in atheme-services 7.2.9-1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 | =head1 NAME
Atheme -- Perl script interface for Atheme IRC Services.
=head1 SYNOPSIS
use Atheme;
%Info = (
name => 'perl_example.pl',
depends => [ 'chanserv/main' ],
);
$Services{chanserv}->bind_command(
name => "HELLO",
desc => "Says hello",
help_path => "chanserv/hello",
handler => \&cs_hello
);
sub cs_hello {
my ($source, @parv) = @_;
$source->success("Hello, " . $source->user->nick);
my $user = $Users{$source->user->nick};
$source->success("You are " . $user->nick . "!" . $user->user . "@" . $user->host);
$source->success("You are logged in as ". $user->account->name . " and your email address is " . $user->account->email);
}
=head1 DESCRIPTION
Since version 7, Atheme IRC Services can use Perl scripts, as well as C modules,
for extensibility. Since the Perl API is less easy to deduce from header files
than the C one, it is described herein.
=head1 SCRIPT REQUIREMENTS
All Atheme perl scripts must define a C<%Info> hash, with the following
contents:
=head2 name
Required. This is the canonical name which will be used to refer to this script
once it is loaded, both for unloading and for dependencies (see below).
=head2 depends
Optional. If specified, this must be an array reference, containing the
canonical names of all modules and scripts which this script requires.
=head1 EXPORTS
Most of the state available to the Perl interface is exported via a set of
read-only tied hashes. They are:
=head2 %Services
The services currently loaded in this Atheme instance, keyed by internal
name. Values are L<Atheme::Service> references.
=head2 %Users
The users currently connected to the network, keyed by nickname B<or> UID.
Values are L<Atheme::User> references.
=head2 %Accounts
Accounts currently registered, keyed by account name. Values are
L<Atheme::Account> references.
=head2 %Channels
Channels currently in existence on the network, keyed by name. Values are
L<Atheme::Channel> references.
=head2 %ChannelRegistrations
Channels currently registered, keyed by name. Values are
L<Atheme::ChannelRegistration> references.
=head2 %Hooks
Hook types supported by Perl, keyed by hook name. See L<Atheme::Hooks> for
details of how to use this.
=head1 COMMAND HANDLERS
Perl scripts can install command handlers via the C<bind_command> method in
L<Atheme::Service>. See the documentation there for details.
=head1 HOOKS
See L<Atheme::Hooks> for details on writing and installing hook functions.
=head1 CAVEATS
Ownership semantics of Atheme objects are clear: the Perl script owns nothing.
Perl's reference counting also does not apply to objects owned by the Atheme C
code, for obvious reasons. This leads to the most important non-obvious rule of
writing Atheme Perl scripts: B<do not store references to Atheme objects>. As
soon as your handler function returns control to Atheme, all Perl references to
Atheme objects are invalidated. If you need to persistently store such things,
then store the object's name and use this to look up the actual object on each
invocation of your handler.
=head1 SEE ALSO
Network object types: L<Atheme::Service>, L<Atheme::User>, L<Atheme::Server>,
L<Atheme::Channel>, L<Atheme::ChanUser>.
Atheme object types: L<Atheme::Account>, L<Atheme::NickRegistration>,
L<Atheme::ChannelRegistration>, L<Atheme::ChanAcs>.
Command handlers: L<Atheme::Sourceinfo>.
Hook system: L<Atheme::Hooks>.
|