-
Notifications
You must be signed in to change notification settings - Fork 0
/
perl.html
210 lines (133 loc) · 13.4 KB
/
perl.html
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
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
<?xml version="1.0" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title></title>
<meta http-equiv="content-type" content="text/html; charset=utf-8" />
<link rev="made" href="mailto:_mdnsresponder@b1017.apple.com" />
</head>
<body style="background-color: white">
<ul id="index">
<li><a href="#NAME">NAME</a></li>
<li><a href="#SYNOPSIS">SYNOPSIS</a></li>
<li><a href="#DESCRIPTION">DESCRIPTION</a></li>
<li><a href="#METHODS">METHODS</a>
<ul>
<li><a href="#connect-socket">connect($socket)</a></li>
<li><a href="#socket">socket()</a></li>
<li><a href="#networks">networks()</a></li>
<li><a href="#channels-network">channels($network)</a></li>
<li><a href="#message-network-channel-message">message($network, $channel, $message)</a></li>
<li><a href="#action-network-channel-message">action($network, $channel, $message)</a></li>
<li><a href="#sendNames-network-channel">sendNames($network, $channel)</a></li>
<li><a href="#sendWhois-network-nick">sendWhois($network, $nick)</a></li>
<li><a href="#join-network-channel">join($network, $channel)</a></li>
<li><a href="#part-network-channel">part($network, $channel)</a></li>
<li><a href="#getNick-network">getNick($network)</a></li>
<li><a href="#doHandshake-name-version-configName">doHandshake($name, $version, [$configName])</a></li>
<li><a href="#getConfig-group-name">getConfig($group, $name)</a></li>
<li><a href="#getProperty-name-network-receiver-sender">getProperty($name, [$network, [$receiver, [$sender]]])</a></li>
<li><a href="#setProperty-name-value-network-receiver-sender">setProperty($name, $value, [$network, [$receiver, [$sender]]])</a></li>
<li><a href="#unsetProperty-name-network-receiver-sender">unsetProperty($name, [$network, [$receiver, [$sender]]])</a></li>
<li><a href="#getPropertyKeys-name-network-receiver-sender">getPropertyKeys($name, [$network, [$receiver, [$sender]]])</a></li>
<li><a href="#subscribe-event-event-event-...-coderef">subscribe($event, [$event, [$event, ..., [$coderef]]])</a></li>
<li><a href="#subscribe_command-command-filter-coderef">subscribe_command($command, [$filter], [$coderef])</a></li>
<li><a href="#unsubscribe-event-event-event">unsubscribe($event, [$event, [$event, ...]])</a></li>
<li><a href="#handleEvent-timeout">handleEvent($timeout)</a></li>
<li><a href="#handleEvents">handleEvents()</a></li>
</ul>
</li>
<li><a href="#AUTHOR">AUTHOR</a></li>
<li><a href="#COPYRIGHT-AND-LICENSE">COPYRIGHT AND LICENSE</a></li>
</ul>
<h1 id="NAME">NAME</h1>
<p>DaZeus - Perl interface to the DaZeus 2 Socket API</p>
<h1 id="SYNOPSIS">SYNOPSIS</h1>
<pre><code> use DaZeus;
my $dazeus = DaZeus->connect("unix:/tmp/dazeus.sock");
# or:
my $dazeus = DaZeus->connect("tcp:localhost:1234");
# Get connection status
my $networks = $dazeus->networks();
foreach (@$networks) {
my $channels = $dazeus->channels($n);
print "$_:\n";
foreach (@$channels) {
print " $_\n";
}
}
$dazeus->subscribe("JOINED", sub { warn "JOINED event received!" });
$dazeus->subscribe(qw/PRIVMSG NOTICE/);
while(my $event = $dazeus->handleEvent()) {
next if($event->{'event'} eq "JOINED");
my ($network, $sender, $channel, $message)
= @{$event->{'params'}};
print "[$network $channel] <$sender> $message\n";
my $destination = $channel eq "msg" ? $sender : $channel;
$dazeus->message($network, $destination, $message);
}</code></pre>
<h1 id="DESCRIPTION">DESCRIPTION</h1>
<p>This module provides a Perl interface to the DaZeus 2 Socket API, so a Perl application can act as a DaZeus 2 plugin. The module supports receiving events and sending messages. See also the "examples" directory that comes with the Perl bindings.</p>
<h1 id="METHODS">METHODS</h1>
<h2 id="connect-socket"><code>connect($socket)</code></h2>
<p>Creates a DaZeus object connected to the given socket. Returns the object if the initial connection succeeded; otherwise, calls die(). If, after this initial connection, the connection fails, for example because the bot is restarted, the module will re-connect.</p>
<p>The given socket name must either start with "tcp:" or "unix:"; in the case of a UNIX socket it must contain a path to the UNIX socket, in the case of TCP it may end in a port number. IPv6 addresses must have a port number attached, so it can be distinguished from the rest of the address; in "tcp:2001:db8::1:1234" 1234 is the port number.</p>
<p>If you give an object through $socket, the module will attempt to use it directly as the target socket.</p>
<h2 id="socket"><code>socket()</code></h2>
<p>Returns the internal UNIX or TCP socket used for communication. This call is useful if you want to watch multiple sockets, for example, using the select() call. Every time the socket can be read, you can call the handleEvents() method to process any incoming events. Do not call read() or write() on this socket, or other calls that change internal socket state.</p>
<p>If the given DaZeus object was not connected, a new connection is opened and a valid socket will still be returned.</p>
<h2 id="networks"><code>networks()</code></h2>
<p>Returns a list of active networks on this DaZeus instance, or calls die() if communication failed.</p>
<h2 id="channels-network"><code>channels($network)</code></h2>
<p>Returns a list of joined channels on the given network, or calls die() if communication failed.</p>
<h2 id="message-network-channel-message"><code>message($network, $channel, $message)</code></h2>
<p>Sends given message to given channel on given network, or calls die() if communication failed.</p>
<h2 id="action-network-channel-message"><code>action($network, $channel, $message)</code></h2>
<p>Like message(), but sends the message as a CTCP ACTION (as if "/me" was used).</p>
<h2 id="sendNames-network-channel"><code>sendNames($network, $channel)</code></h2>
<p>Requests a NAMES command being sent for the given channel on the given network. After this, a NAMES event will be produced using the normal event system described below, if the IRC server behaves correctly. Calls die() if communication failed.</p>
<h2 id="sendWhois-network-nick"><code>sendWhois($network, $nick)</code></h2>
<p>Requests a WHOIS command being sent for the given nick on the given network. After this, a WHOIS event will be produced using the normal event system described below, if the IRC server behaves correctly. Calls die() if communication failed.</p>
<h2 id="join-network-channel"><code>join($network, $channel)</code></h2>
<p>Requests a JOIN command being sent for the given channel on the given network. After this, a JOIN event will be produced using the normal event system described below, if the IRC server behaves correctly and the channel was not already joined. Calls die() if communication failed.</p>
<h2 id="part-network-channel"><code>part($network, $channel)</code></h2>
<p>Requests a PART command being sent for the given channel on the given network. After this, a PART event will be produced using the normal event system described below, if the IRC server behaves correctly and the channel was joined. Calls die() if communication failed.</p>
<h2 id="getNick-network"><code>getNick($network)</code></h2>
<p>Requests the current nickname on given network, and returns it. Calls die() if communication failed.</p>
<h2 id="doHandshake-name-version-configName"><code>doHandshake($name, $version, [$configName])</code></h2>
<p>Does the optional DaZeus handshake, required for getting configuration later. If the configuration name is not given, $name is used for it.</p>
<h2 id="getConfig-group-name"><code>getConfig($group, $name)</code></h2>
<p>Retrieves the given variable from the configuration file and returns its value. Calls die() if communication failed. $group can be "core" or "plugin"; "plugin" can only be used if you did a succesful handshake earlier.</p>
<h2 id="getProperty-name-network-receiver-sender"><code>getProperty($name, [$network, [$receiver, [$sender]]])</code></h2>
<p>Retrieves the given variable from the persistent database and returns its value. Optionally, context can be given for this property request, so properties stored earlier using a specific scope can be correctly matched against this request, and the most specific match will be returned. Calls die() if communication failed.</p>
<h2 id="setProperty-name-value-network-receiver-sender"><code>setProperty($name, $value, [$network, [$receiver, [$sender]]])</code></h2>
<p>Stores the given variable to the persistent database. Optionally, context can be given for this property, so multiple properties with the same name and possibly overlapping context can be stored and later returned. This is useful in situations where you want different settings per network, but also overriding settings per channel. Calls die() if communication failed.</p>
<h2 id="unsetProperty-name-network-receiver-sender"><code>unsetProperty($name, [$network, [$receiver, [$sender]]])</code></h2>
<p>Unsets the given variable with given context from the persistent database. If no variable was found with the exact given context, no variables are removed. Calls die() if communication failed.</p>
<h2 id="getPropertyKeys-name-network-receiver-sender"><code>getPropertyKeys($name, [$network, [$receiver, [$sender]]])</code></h2>
<p>Retrieves all keys in a given namespace. I.e. if example.foo and example.bar were stored earlier, and getPropertyKeys("example") is called, "foo" and "bar" will be returned from this method. Calls die() if communication failed.</p>
<h2 id="subscribe-event-event-event-...-coderef"><code>subscribe($event, [$event, [$event, ..., [$coderef]]])</code></h2>
<p>Subscribes to the given events. If the last parameter is a code reference, it will be called automatically every time one of the given events hits, with the DaZeus object as the first parameter, and the received event as the second.</p>
<h2 id="subscribe_command-command-filter-coderef"><code>subscribe_command($command, [$filter], [$coderef])</code></h2>
<p>Subscribe to the given command. Filter is an optional hashref which looks like one of:</p>
<pre><code> {network => 'name'}
{network => 'name', sender => 'ircnick'}
{network => 'name', receiver => 'ircnick'}</code></pre>
<p>Multiple subscriptions to the same command with a different filter is possible, but the last given coderef will be called for all of them.</p>
<h2 id="unsubscribe-event-event-event"><code>unsubscribe($event, [$event, [$event, ...]])</code></h2>
<p>Unsubscribe from the given events. They will no longer be received, until subscribe() is called again.</p>
<h2 id="handleEvent-timeout"><code>handleEvent($timeout)</code></h2>
<p>Returns all events that can be returned as soon as possible, but no longer than the given $timeout. If $timeout is zero, do not block. If timeout is undefined, wait forever until the first event arrives.</p>
<p>"As soon as possible" means that if there are cached events already read from the socket earlier, the socket will not be touched. Otherwise, if events are available for reading, they will be immediately read. Only if no events were cached, none were available for reading, and $timeout is not zero will this function block to retrieve events. (See also handleEvents().)</p>
<p>This method only returns a single event, in order of receiving. For every returned event, the event handler (if given to subscribe()), is called.</p>
<h2 id="handleEvents"><code>handleEvents()</code></h2>
<p>Handle and return as much events as possible without blocking. Also calls the event handler for every returned event.</p>
<h1 id="AUTHOR">AUTHOR</h1>
<p>Sjors Gielen, <dazeus@sjorsgielen.nl></p>
<h1 id="COPYRIGHT-AND-LICENSE">COPYRIGHT AND LICENSE</h1>
<p>Copyright (C) 2012 by Sjors Gielen All rights reserved.</p>
<p>Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:</p>
<p>1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. 2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.</p>
<p>THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.</p>
</body>
</html>