chiark / gitweb /
documentation for twit command from naath
[irc.git] / servus.html
1 <?xml version="1.0" encoding="UTF-8"?>
2 <!DOCTYPE html 
3      PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
4      "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
5 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
6
7 <head>
8 <title>Servus Documentation</title>
9 <style type="text/css">
10 body {background: white; color: black; text-align: left}
11 h1 {text-align: center; font-weight: bold; font-size: xx-large}
12 h2 {font-weight: bold; font-size: x-large}
13 h3, h4, h5, h6 {font-weight: bold; font-size: large}
14 li {list-style-type: circle}
15 hr {clear: both}
16 span.code {font-family: courier, monospace}
17 </style>
18 </head>
19
20 <body>
21 <h1>Servus Documentation</h1> 
22
23 <h2>Introduction</h2>
24 <p>Servus is one of the IRC bots on <span
25 class="code">#chiark</span>. This page documents the available
26 commands. You can get a copy of the source code by running <span
27 class="code">git-clone <a
28 href="http://www.chiark.greenend.org.uk/~matthewv/irc/.git">http://www.chiark.greenend.org.uk/~matthewv/irc/.git</a></span></p>
29
30 <h2>Invocation</h2>
31 <p>Servus may be invoked in-channel using either <span
32 class="code">!command</span> or <span
33 class="code">~command</span>. Alternatively, you may pass commands by
34 <span class="code">/msg</span>.
35 </p>
36
37 <h2>Commands</h2>
38
39 <ul>
40 <li><a href="#define">define</a></li>
41 <li><a href="#die">die</a></li>
42 <li><a href="#do">do</a></li>
43 <li><a href="#fish">fish</a></li>
44 <li><a href="#flirt">flirt</a></li>
45 <li><a href="#google">google</a></li>
46 <li><a href="#help">help</a></li>
47 <li><a href="#info">info</a></li>
48 <li><a href="#karma">karma</a></li>
49 <li><a href="#karmadel">karmadel</a></li>
50 <li><a href="#karmalist">karmalist</a></li>
51 <li><a href="#list">list</a></li>
52 <li><a href="#quiet">quiet</a></li>
53 <li><a href="#quit">quit</a></li>
54 <li><a href="#reload">reload</a></li>
55 <li><a href="#rot13">rot13</a></li>
56 <li><a href="#say">say</a></li>
57 <li><a href="#slash">slash</a></li>
58 <li><a href="#trout">trout</a></li>
59 <li><a href="#twit">twit</a></li>
60 <li><a href="#units">units</a></li>
61 <li><a href="#url">url</a></li>
62 </ul>
63
64 <hr />
65
66 <h3><a name="define">define</a></h3>
67 <p>This command returns (either on-channel or by <span
68 class="code">/msg</span>) a definition of the argument(s) of the
69 "define" command. This is done by using a "define:" query on
70 google, so the results may be a little unusual at times...</p>
71
72 <h3><a name="die">die</a></h3>
73 <p>This command must be invoked by <span class="code">/msg</span> only,
74 and is only effective if invoked by the bot's owner. The bot
75 exits.</p>
76
77 <h3><a name="do">do</a></h3>
78 <p>This command must be invoked by <span class="code">/msg</span>, and
79 is only effective if invoked by the bot's owner. The syntax is:<br />
80 <span class="code">/msg Servus do thing</span><br />...which results
81 in output to the channel of the form:<br />
82 <span class="code">* Servus/#chiark thing</span></p>
83
84 <h3><a name="fish">fish</a></h3>
85 <p>This command must be invoked by <span class="code">/msg</span>, and
86 is only effective if invoked by the bot's owner. It
87 returns some details about the internal state of the "fishpond" (a
88 simple rate-limiting feature for restricting the over-use of <span
89 class="code">trout</span>, <span class="code">flirt</span>, and <span
90 class="code">slash</span>).</p>
91
92 <h3><a name="flirt">flirt</a></h3>
93 <p>The syntax is:<br /> <span
94 class="code">flirt target</span><br /> Servus picks a flirt at random
95 from the flirts list (<span
96 class="code">/home/matthew/programming/irc/bot/flirts</span> on rapun),
97 and substitutes "target" for "%s" in the flirt line. If this command
98 is invoked by <span class="code">/msg</span>, there is a 10% chance
99 of Servus stating who invoked it by adding "(but nick is their secret
100 admirer)" to the end of the flirt. Further suggestions for flirts
101 should be submitted by email; a list of current flirts may be found
102 online at <a
103 href="flirts">http://www.chiark.greenend.org.uk/~matthewv/irc/flirts</a>.</p>
104
105 <h3><a name="google">google</a></h3>
106 <p>This command returns (either on-channel or by <span
107 class="code">/msg</span>) the "I'm feeling lucky" result of google
108 searching for the argument(s) of the "google" command.</p>
109
110 <h3><a name="help">help</a></h3>
111 <p>This command returns (either on-channel or by <span
112 class="code">/msg</span>) the location of this help file.</p>
113
114 <h3><a name="info">info</a></h3>
115 <p>This command returns (either on-channel or by <span
116 class="code">/msg</span>) information about the software version
117 running, which channel the bot is on, the bot's owner, and how many
118 items have karma recorded about them</p>
119
120 <h3><a name="karma">karma</a></h3>
121 <p>The syntax is:<br />
122 <span class="code">karma target</span><br />
123 It returns (either on-channel or by <span class="code">/msg</span>)
124 the current karma value for <span class="code">target</span> or "<span
125 class="code">target has no karma set.</span>" as appropriate. Items
126 gain or lose karma as the result of commands of the form:<br />
127 <span class="code">target++</span><br />or<br />
128 <span class="code">target--</span><br />
129 Note that if issued in-channel, the initial <span
130 class="code">!</span> or <span class="code">~</span> should not be
131 included. Karma targets must be one word only.</p>
132
133 <h3><a name="karmadel">karmadel</a></h3>
134 <p>The syntax is:<br /> <span
135 class="code">karmadel target</span><br /> <span
136 class="code">target</span>'s karma entry is deleted. An error message
137 is produced if <span class="code">target</span> has no karma set.</p>
138
139 <h3><a name="karmalist">karmalist</a></h3>
140 <p><span style="font-weight: bold">Do not use this
141 command</span>. Servus has too long a list of karma items, so
142 attempting to use this command will DoS the bot (it gets temporarily
143 removed from channel for excess flooding).</p>
144
145 <h3><a name="list">list</a></h3>
146 <p>This command returns (either on-channel or by <span
147 class="code">/msg</span>) a list of the commands Servus
148 understands</p> 
149
150 <h3><a name="quiet">quiet</a></h3>
151 <p>This command prevents the use of <span
152 class="code">trout</span>, <span class="code">flirt</span>, and <span
153 class="code">slash</span> for a short period of time (and will tell
154 anyone who attempts to do so that you have invoked this command).</p> 
155
156 <h3><a name="quit">quit</a></h3>
157 <p>This command is identical to <a href="#die">die</a>.</p>
158
159 <h3><a name="reload">reload</a></h3>
160 <p>This command may only be invoked by <span class="code">/msg</span>,
161 and only by the bot's owner. It causes Servus to re-load its <span
162 class="code">trout</span>, <span class="code">flirt</span>, and <span
163 class="code">slash</span> files, and to re-stock its fishpond.</p>
164
165 <h3><a name="rot13">rot13</a></h3>
166 <p>The syntax is:<br />
167 <span class="code">rot13 some text</span><br />
168 It returns by <span class="code">/msg</span>
169 the argument rot13d (so "<span class="code">fbzr grkg</span>" in this
170 case).</p>
171
172 <h3><a name="say">say</a></h3>
173 <p>This command must be invoked by <span class="code">/msg</span>, and
174 is only effective if invoked by the bot's owner. The syntax is:<br />
175 <span class="code">/msg Servus say thing</span><br />...which results
176 in output to the channel of the form:<br />
177 <span class="code">&lt;Servus&gt; thing</span></p>
178
179 <h3><a name="slash">slash</a></h3>
180 <p>The syntax is:<br /> <span
181 class="code">slash target1 / target2 </span><br /> Servus picks a slash at random
182 from the slashes list (<span
183 class="code">/home/matthew/programming/irc/bot/slashes</span> on rapun),
184 and substitutes "target1" for the first "%s" and "target2" for the
185 second "%s" in the slash line. If this command
186 is invoked by <span class="code">/msg</span>, there is a 10% chance
187 of Servus stating who invoked it by adding "(while nick watches)" to
188 the end of the slash. Further suggestions for slashes should be
189 submitted by email; a list of current slashes may be found online at <a
190 href="slashes">http://www.chiark.greenend.org.uk/~matthewv/irc/slashes</a>.</p>
191
192 <h3><a name="trout">trout</a></h3>
193 <p>The syntax is:<br /> <span
194 class="code">trout target</span><br /> Servus picks a trout at random
195 from the trouts list (<span
196 class="code">/home/matthew/programming/irc/bot/trouts</span> on rapun),
197 and substitutes "target" for "%s" in the trout line. If this command
198 is invoked by <span class="code">/msg</span>, there is a 10% chance
199 of Servus stating who invoked it by adding "(at the instigation of
200 nick)" to the end of the trout. Further suggestions for trouts should
201 be submitted by email; a list of current trouts may be found online at
202 <a href="trouts">http://www.chiark.greenend.org.uk/~matthewv/irc/trouts</a>.</p>
203
204 <h3><a name="twit">twit</a></h3>
205 <p>The syntax is:<br /><span
206 class="code">twit twitter-url</span><br /> Servus returns the content
207 of the tweet and the twitter user who posted it.</p>
208
209 <h3><a name="units">units</a></h3>
210 <p>The syntax is:<br /> <span
211 class="code">units x unit1 as unit2</span><br />or:<br /> <span
212 class="code">units unit1 as unit2</span><br />or:<br /> <span
213 class="code">units x unit1 as ?</span><br />or:<br /> <span
214 class="code">units unit1 as ?</span><br />
215 The first two will give the first value in terms of the second unit;
216 the latter two forms convert the first value into SI units. This
217 command is implemented by calling <span class="code">units(1)</span>.</p>
218
219 <h3><a name="url">url</a></h3>
220 <p>Servus now tracks URLs pasted into <span
221 class="code">#chiark</span>, and will comment if you post a duplicate
222 URL. The <span class="code">url</span> command provides a way for you
223 to check if a URL has been posted before (if not, Servus posts it on
224 your behalf). The syntax is:<br /> 
225 <span class="code">/msg Servus url http://some.url</span><br />
226 Servus will either paste the URL into channel, or <span
227 class="code">/msg</span> you to tell you it was a duplicate. Although
228 you can use this command in-channel (and get a response by <span
229 class="code">/msg </span>), this is discouraged.</p>
230
231 <hr />
232 <address>
233   <a href="mailto:matthewv@chiark.greenend.org.uk">Matthew Vernon</a><br />
234   Coventry, England
235 </address>
236  <p>
237 <a href="http://validator.w3.org/check/referer"><img
238         src="http://www.w3.org/Icons/valid-xhtml10"
239         alt="Valid XHTML 1.0!" height="31" width="88" /></a>
240 <a href="http://jigsaw.w3.org/css-validator/check/referer">
241 <img style="width:88px;height:31px"
242        src="http://jigsaw.w3.org/css-validator/images/vcss" 
243        alt="Valid CSS!" />
244 </a>
245 </p>
246 </body>
247 </html>
248