1=============== 2Commands Manual 3=============== 4 5.. contents:: 6 :local: 7 :depth: 3 8 :backlinks: none 9 10.. _commands-playground: 11 12Playground 13========== 14 15User can run commands in two ways, the one way is typing them into the input 16entry of chat buffer. 17 18The another way is writing the commands to the ``server.auto-run`` and 19``chat.auto-run`` configuration items. For more details, please refer to 20:doc:`config`. 21 22.. _commands-syntax: 23 24Syntax 25====== 26 27A command is a line of string that has the following format, different elements 28are separated by whitespace:: 29 30 /<name|alias> [subcommand] [<option> [value]]... [argument]... 31 32User should use ``name`` to invoke a command. 33The command's ``name`` starts with a slash ``/`` and doesn't contain any 34whitespace, such as: ``/join``. 35Some commands have ``alias`` that can be used instead of ``name``, 36for example, user can use ``/j`` instead of ``/join``. 37 38.. note:: 39 40 When you want to send a message starts with a slash, please prepend 41 another slash to the message. 42 For example, you want to send "/this is a slash prefixed message", you need 43 to type "//this is a slash prefixed message". 44 45A ``subcommand`` is a instruction behind the command name, it is optional. 46 47An ``option``, as its name, is optional too, starts with a hyphen ``-`` and may 48has a ``value``. 49 50``option`` is often used as the switch of a flag or a way to change some 51default values. For example, The command ``/connect -tls -port 6697``, 52option ``-tls`` is just a flag that tells srain use secure connections with TLS. 53And ``-port`` requires a ``value``, if ``-port`` is not specified, program will 54use the default value ``6667``. Check :ref:`commands-connect` for more details. 55 56If a ``value`` starts with a hyphen ``-`` or contains whitespaces, it should be 57enclosed by single quotation mark ``'``. 58 59.. note:: 60 61 All ``option`` should appear behind ``subcommand`` (If any), and before 62 ``argument``. 63 64An ``argument`` is similar to ``value``, but commonly it doesn't have a default 65value so it can not be omitted (actually it depends on the implement of the 66command). If the first ``argument`` starts with a hyphen ``-``, it should be 67enclosed by single quotation mark ``'``. If an ``argument`` contains whitespaces, 68it should be quoted too. Specially, the last argument can contain whitespace 69without quoted. 70 71If you want to use a single quotation mark in a quoted text, use backslash ``\`` 72to escape it. For backslash itself, use double backslash ``\\``. 73 74Available Commands 75================== 76 77/reload 78------- 79 80Usage:: 81 82 /reload 83 84Reload user configuration. 85 86.. _commands-server: 87 88/server 89------- 90 91Usage:: 92 93 /server [connect|disconnect|list] <name> 94 95Predefined IRC server management. 96 97Sub commands: 98 99* ``connect``: connect to specified predefined server 100* ``disconnect``: disconnect from specified predefined server 101* ``list``: list all predefined servers 102 103Arguments: 104 105* ``name``: unique name of server 106 107.. _commands-connect: 108 109/connect 110-------- 111 112Usage:: 113 114 /connect [-port <port>] [-pwd <password>] [-tls] [-tls-noverify] 115 [-user <username>] [-real <realname>] <host> <nick> 116 117Create a IRC server and connect to it immediately. 118 119Options: 120 121* ``-port``: server port, default ``6667`` 122* ``-pwd``: connection password, default empty 123* ``-tls``: use secure connections with TLS 124* ``-tls-noverify``: use TLS connection without certificate verification 125* ``-user``: specify username, default same as nickname 126* ``-real``: specify realname, default same as nickname 127 128Arguments: 129 130* ``host``: server host 131* ``nick``: specify nickname 132 133Example:: 134 135 /connect -real 'I am srainbot' -tls -port 6697 chat.freenode.org srainbot 136 /connect 127.0.0.1 srainbot 137 138/ignore & /unignore 139------------------- 140 141Usage:: 142 143 /ignore [-cur] <nick> 144 /unignore [-cur] <nick> 145 146Ignore/unignore somebody's message. 147 148Options: 149 150* ``-cur``: only ignore in current chat 151 152/query & /unquery 153----------------- 154Usage:: 155 156 /query|q <nick> 157 /unquery [nick] 158 159Start/stop private chat with somebody. For ``/unquery`` , If no ``nick`` is 160specified, it stops the current private chat. 161 162.. _commands-join: 163 164/join 165----- 166 167Usage:: 168 169 /join|j <channel>[,<channel>]... [<passwd>[,<passwd>]]... 170 171Join specified channel(s), channels are separated by commas ``,``. 172 173Example:: 174 175 /join #archinux-cn,#gzlug,#linuxba 176 /join #channel1,#channe2 passwd1 177 178/part 179----- 180 181Usage:: 182 183 /part|leave [<channel>[,<channel>]]... [<reason>] 184 185Leave specified channel(s) with optional reason, channels are separated by 186commas ``,``. If no ``channel`` is specified, it leaves the current channel. 187 188Example:: 189 190 /part #archinux-cn Zzz... 191 /part #archlinux-cn,#tuna 192 /part 193 194/quit 195----- 196 197Usage:: 198 199 /quit [reason] 200 201Quit current server with optional reason. 202 203/topic 204------ 205 206Usage:: 207 208 /topic [-rm|<topic>] 209 210Set the current channel's topic. If no ``topic`` specified, it just displays 211the current channel's topic. 212 213* ``-rm``: remove current channel's topic 214 215Example:: 216 217 # Just view the topic 218 /topic 219 # Set the topic to "Welcome to Srain!" 220 /topic Welcome to Srain! 221 # Clear the topic 222 /topic -rm 223 224/msg 225---- 226 227Usage:: 228 229 /msg|m <target> <message> 230 231Send message to a target, the target can be channel or somebody's nick. If you 232want to send a message to channel, you should :ref:`commands-join` it first. 233 234/me 235--- 236 237Usage:: 238 239 /me <message> 240 241Send an action message to the current target. 242 243 244/nick 245----- 246 247Usage:: 248 249 /nick <new_nick> 250 251Change your nickname. 252 253/whois 254------ 255 256Usage:: 257 258 /whois <nick> 259 260Get somebody's information on the server. 261 262/invite 263------- 264 265Usage:: 266 267 /invite <nick> [channel] 268 269Invite somebody to join a channel. If no ``channel`` is specified, it falls 270back to current channel. 271 272/kick 273----- 274 275Usage:: 276 277 /kick <nick> [channel] [reason] 278 279Kick somebody from a channel, with optional reason. If no ``channel`` is 280specified, it falls back to current channel. 281 282/mode 283----- 284 285Usage:: 286 287 /mode <target> <mode> 288 289Change ``target`` 's mode. 290 291.. _commands-ctcp: 292 293/ctcp 294----- 295 296Usage:: 297 298 /ctcp <target> <command> [message] 299 300Send a CTCP request to ``target``. The commonly used commands are: 301CLIENTINFO, FINGER, PING, SOURCE, TIME, VERSION, USERINFO. For the detail of 302each command, please refer to https://modern.ircdocs.horse/ctcp.html . 303 304If you send a CTCP PING request without ``message``, you will get the latency 305between the ``target``. 306 307.. note:: 308 309 DCC is not yet supported. 310 311.. _commands-pattern: 312 313/pattern 314-------- 315 316Usage:: 317 318 /pattern add <name> <pattern> 319 /pattern rm <name> 320 /pattern list 321 322Regular expression pattern management. 323The added pattern can be used elsewhere in the application, such as 324:ref:`commands-filter` and :ref:`commands-render`. 325 326Sub commands: 327 328* ``add``: add a pattern with given name 329* ``rm``: remove a pattern with given name 330* ``list``: list all availables patterns 331 332Arguments: 333 334* ``name``: unique name of pattern 335* ``pattern``: a valid `Perl-compatible Regular Expression`_ 336 337.. _Perl-compatible Regular Expression: https://developer.gnome.org/glib/stable/glib-regex-syntax.html 338 339.. _commands-filter: 340 341/filter & /unfilter 342------------------- 343 344Usage:: 345 346 /filter [-cur] <pattern> 347 /unfilter [-cur] <pattern> 348 349Filter message whose content matches specified pattern. 350 351Options: 352 353* ``-cur``: only ignore in current chat 354 355Arguments: 356 357* ``pattern``: name of regular expression pattern which is managed by 358 :ref:`commands-pattern` 359 360Example: 361 362This filter message that content is "Why GTK and not Qt?":: 363 364 /pattern add troll ^Why GTK and not Qt\?$ 365 /filter troll 366 367To cancel the filter of these kind of message, use:: 368 369 /unfilter troll 370 371.. note:: 372 373 Pattern **NO NEED** to consider the case where the mIRC color code is 374 included in the message. 375 376.. _commands-render: 377 378/render & /unrender 379------------------- 380 381Usage:: 382 383 /render [-cur] <nick> <pattern> 384 /unrender [-cur] <nick> <pattern> 385 386Render message of specific user via specific pattern. 387 388The given pattern should contains specific `Named Subpatterns`_ used for 389capturing message fragment from original message content and become part of 390rendered message. 391 392.. _Named Subpatterns: https://developer.gnome.org/glib/stable/glib-regex-syntax.html#id-1.5.25.13 393 394There are list of available named subpatterns: 395 396* ``(?<sender>)``: match name of sender, once this subpatterns is matched, 397 the original sender will be displayed as message remark 398* ``(?<content>)``: match content of rendered message 399* ``(?<time>)``: match time of rendered message 400 401Arguments: 402 403* ``nick``: nickname of user 404* ``pattern``: name of regular expression pattern which is managed by 405 :ref:`commands-pattern` 406 407Options: 408 409* ``-cur``: only effects the user under current chat 410 411Example: 412 413We assume that there is a IRC bot named "xmppbot". 414It forwards message between XMPP and IRC. 415On IRC side, the forwarded message looks like "<xmppbot> [xmpp_user] xmpp_message", 416you can render it to a more easy-to-read format via the following commands:: 417 418 /pattern add xmpp \[(?<sender>[^:]+?)\] (?<content>.*) 419 /render xmppbot xmpp 420 421The forwarded meessage will look like "<xmpp_user> xmpp_message", and the 422original message sender "xmppbot" will be displayed as message remark. 423Please refer to :ref:`faq-relay-message-transform` see its effect. 424 425.. note:: 426 427 Pattern **SHOULD** consider the case where the mIRC color code is 428 included in the message. 429 430Obsoleted Commands 431================== 432 433.. _commands-rignore: 434 435/rignore & /unrignore 436--------------------- 437 438This command has been dropped since :ref:`version-1.0.0rc5`, 439please use :ref:`commands-filter` instead. 440 441.. _commands-relay: 442 443/relay & /unrelay 444----------------- 445 446This command has been dropped since :ref:`version-1.0.0rc5`, 447please use :ref:`commands-render` instead. 448