GitHub/pbot
3
0
Fork 0
mirror of https://github.com/pragma-/pbot.git synced 2024-11-26 05:49:27 +01:00
Code Issues Projects Releases Wiki Activity

doc/Factoids.md: update TOC and add code factoid languages

Browse Source
This commit is contained in:
Pragmatic Software 2020-01-08 20:30:52 -08:00
parent ac0c9505f1
commit ebf6ccb6fa
1 changed files with 126 additions and 85 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

125
doc/Factoids.md
View File

@ -8,7 +8,16 @@ Factoids
* [/me](#me) * [/me](#me)
* [/call](#call) * [/call](#call)
* [/msg](#msg) * [/msg](#msg)
* [/code](#code)
* [Supported languages](#supported-languages)
* [Special variables](#special-variables) * [Special variables](#special-variables)
* [testargs example](#testargs-example)
* [Setting a usage message](#setting-a-usage-message)
* [poll/vote example](#pollvote-example)
* [SpongeBob Mock meme example](#spongebob-mock-meme-example)
* [Using command-piping](#using-command-piping)
* [Improving SpongeBob Mock meme](#improving-spongebob-mock-meme)
* [Special variables](#special-variables-1)
* [$nick](#nick) * [$nick](#nick)
* [$args](#args) * [$args](#args)
* [$arg[n]](#argn) * [$arg[n]](#argn)
@ -52,7 +61,7 @@ Factoids
* [top20](#top20) * [top20](#top20)
<!-- md-toc-end --> <!-- md-toc-end -->
### Channel namespaces ## Channel namespaces
Factoids added in one channel may be called/triggered in another channel or in private message, providing that the other channel doesn't already have a factoid of the same name (in which case that channel's factoid will be triggered). Factoids added in one channel may be called/triggered in another channel or in private message, providing that the other channel doesn't already have a factoid of the same name (in which case that channel's factoid will be triggered).
Factoids may be added to a special channel named `global`. Factoids that are set in this channel will be accessible to any channels. Factoids that are set in a specific channel will override factoids of the same name that are set in the `global` channel or other channels. Factoids may be added to a special channel named `global`. Factoids that are set in this channel will be accessible to any channels. Factoids that are set in a specific channel will override factoids of the same name that are set in the `global` channel or other channels.
@ -63,8 +72,8 @@ Now imagine `##c++` also has a `malloc` factoid. If you invoke it in `##c++` the
However, if there is no `malloc` factoid in the `global` channel but there is one in `##c` and `##c++`, and you attempt to invoke it in any other channel then PBot will display a disambiguation message listing which channels it belongs to and instructing you to use the [`fact`](#fact) command to call the desired factoid. However, if there is no `malloc` factoid in the `global` channel but there is one in `##c` and `##c++`, and you attempt to invoke it in any other channel then PBot will display a disambiguation message listing which channels it belongs to and instructing you to use the [`fact`](#fact) command to call the desired factoid.
### Special commands ## Special commands
#### /say ### /say
If a factoid begins with `/say` then PBot will not use the `<factoid> is <description>` format when displaying the factoid. Instead, it will simply say only the `<description>`. If a factoid begins with `/say` then PBot will not use the `<factoid> is <description>` format when displaying the factoid. Instead, it will simply say only the `<description>`.
<pragma-> !factadd global hi /say Well, hello there, $nick. <pragma-> !factadd global hi /say Well, hello there, $nick.
@ -72,7 +81,7 @@ If a factoid begins with `/say ` then PBot will not use the `<factoid> is <descr
<prec> PBot, hi <prec> PBot, hi
<PBot> Well, hello there, prec. <PBot> Well, hello there, prec.
#### /me ### /me
If a factoid begins with `/me` then PBot will `CTCP ACTION` the factoid. If a factoid begins with `/me` then PBot will `CTCP ACTION` the factoid.
<pragma-> !factadd global bounce /me bounces around. <pragma-> !factadd global bounce /me bounces around.
@ -80,7 +89,7 @@ If a factoid begins with `/me ` then PBot will `CTCP ACTION` the factoid.
<pragma-> !bounce <pragma-> !bounce
* PBot bounces around. * PBot bounces around.
#### /call ### /call
If a factoid begins with `/call` then PBot will call an existing command. This is what [`factalias`](#factalias) does internally. If a factoid begins with `/call` then PBot will call an existing command. This is what [`factalias`](#factalias) does internally.
<pragma-> !factadd global boing /call bounce <pragma-> !factadd global boing /call bounce
@ -88,7 +97,7 @@ If a factoid begins with `/call ` then PBot will call an existing command. This
<pragma-> !boing <pragma-> !boing
* PBot bounces around. * PBot bounces around.
#### /msg ### /msg
If a factoid begins with `/msg <nick>` then PBot will privately message the factoid text to `<nick>`. Only admins can use this command. If a factoid begins with `/msg <nick>` then PBot will privately message the factoid text to `<nick>`. Only admins can use this command.
### /code ### /code
@ -108,11 +117,43 @@ The `<language>` parameter selects a programming/scripting language or interpret
#### Supported languages #### Supported languages
As of this writing, these are the languages and interpreters that PBot supports. It is easy to add additional As of this writing, these are the languages and interpreters that PBot supports. It is easy to add additional
languages or interpreters. For example, [take a look at these language/interpreter files.](../modules/compiler_vm/languages) languages or interpreters.
Name | Description
--- | ---
[bash](../modules/compiler_vm/languages/bash.pm) | Bourne-again Shell scripting language
[bc](../modules/compiler_vm/languages/bc.pm) | An arbitrary precision calculator language
[bf](../modules/compiler_vm/languages/bf.pm) | BrainFuck esoteric language
[c11](../modules/compiler_vm/languages/c11.pm) | C programming language using GCC -std=c11
[c89](../modules/compiler_vm/languages/c89.pm) | C programming language using GCC -std=c89
[c99](../modules/compiler_vm/languages/c99.pm) | C programming language using GCC -std=c99
[clang11](../modules/compiler_vm/languages/clang11.pm) | C programming language using Clang -std=c11
[clang89](../modules/compiler_vm/languages/clang89.pm) | C programming language using Clang -std=c89
[clang99](../modules/compiler_vm/languages/clang99.pm) | C programming language using Clang -std=c99
[clang](../modules/compiler_vm/languages/clang.pm) | Alias for `clang11`
[clangpp](../modules/compiler_vm/languages/clangpp.pm) | C++ programming language using Clang
[clisp](../modules/compiler_vm/languages/clisp.pm) | Common Lisp dialect of the Lisp programming language
[cpp](../modules/compiler_vm/languages/cpp.pm) | C++ using GCC
[freebasic](../modules/compiler_vm/languages/freebasic.pm) | FreeBasic BASIC compiler/interpreter
[go](../modules/compiler_vm/languages/go.pm) | Golang programming language
[haskell](../modules/compiler_vm/languages/haskell.pm) | Haskell programming language
[java](../modules/compiler_vm/languages/java.pm) | Java programming language
[javascript](../modules/compiler_vm/languages/javascript.pm) | JavaScript programming language
[ksh](../modules/compiler_vm/languages/ksh.pm) | Korn shell scripting language
[lua](../modules/compiler_vm/languages/lua.pm) | LUA scripting language
[perl](../modules/compiler_vm/languages/perl.pm) | Perl programming language
[python3](../modules/compiler_vm/languages/python3.pm) | Python3 programming language
[python](../modules/compiler_vm/languages/python.pm) | Python programming language
[qbasic](../modules/compiler_vm/languages/qbasic.pm) | QuickBasic option using FreeBasic
[ruby](../modules/compiler_vm/languages/ruby.pm) | Ruby programming language
[scheme](../modules/compiler_vm/languages/scheme.pm) | Scheme dialect of the Lisp programming language
[sh](../modules/compiler_vm/languages/sh.pm) | Bourne Shell scripting language
[tcl](../modules/compiler_vm/languages/tcl.pm) | TCL scripting language
[zsh](../modules/compiler_vm/languages/zsh.pm) | Z Shell scripting language
#### Special variables #### Special variables
All the variables listed in [Special Variables](#special-variables) are expanded within Code Factoids before All the variables listed in [Special Variables](#special-variables-1) are expanded within Code Factoids before
the code is executed or interpreted. the code is executed or interpreted.
[List variables](#list-variables) are also expanded beforehand as well. You can prevent this by using [`factset`](#factset) [List variables](#list-variables) are also expanded beforehand as well. You can prevent this by using [`factset`](#factset)
@ -231,34 +272,34 @@ to strip the timestamp and the name, leaving only the message. `smr` stands for
<pragma-> !smr derpy3 girls <pragma-> !smr derpy3 girls
<PBot> gIrLs ArE dUmB! <PBot> gIrLs ArE dUmB!
### Special variables ## Special variables
You can use the following variables in a factoid or as an argument to one. You can use the following variables in a factoid or as an argument to one.
#### $nick ### $nick
`$nick` expands to the nick of the caller. `$nick` expands to the nick of the caller.
#### $args ### $args
`$args` expands to any text following the keyword. If there is no text then it expands to the nick of the caller. `$args` expands to any text following the keyword. If there is no text then it expands to the nick of the caller.
#### $arg[n] ### $arg[n]
`$arg[n]` expands to the nth argument. Indexing begins from 0 (the first argument is `$arg[0]`). You may use a negative number to count from the end; e.g., `$arg[-2]` means the 2nd argument from the end. Multiple words can be double-quoted to constitute one argument. If the argument does not exist, the variable and the leading space before it will be silently removed. `$arg[n]` expands to the nth argument. Indexing begins from 0 (the first argument is `$arg[0]`). You may use a negative number to count from the end; e.g., `$arg[-2]` means the 2nd argument from the end. Multiple words can be double-quoted to constitute one argument. If the argument does not exist, the variable and the leading space before it will be silently removed.
#### $arg[n:m] ### $arg[n:m]
`$arg[n:m]` expands to a slice of arguments between `n` and `m`. Indexing begins from 0 (the first argument is `$arg[0]`). Not specifying the `m` value means the rest of the arguments; e.g., `$arg[2:]` means the remaining arguments after the first two. Multiple words can be double-quoted to constitute one argument. If the argument does not exist, the variable and the leading space before it will be silently removed. `$arg[n:m]` expands to a slice of arguments between `n` and `m`. Indexing begins from 0 (the first argument is `$arg[0]`). Not specifying the `m` value means the rest of the arguments; e.g., `$arg[2:]` means the remaining arguments after the first two. Multiple words can be double-quoted to constitute one argument. If the argument does not exist, the variable and the leading space before it will be silently removed.
#### $arglen ### $arglen
`$arglen` expands to the number of arguments provided to a factoid. `$arglen` expands to the number of arguments provided to a factoid.
#### $channel ### $channel
`$channel` expands to the name of the channel in which the factoid is used. `$channel` expands to the name of the channel in which the factoid is used.
#### $randomnick ### $randomnick
`$randomnick` expands to a random nick from the channel in which the factoid is used. Filtered to nicks who have spoken in channel in the last two hours. `$randomnick` expands to a random nick from the channel in which the factoid is used. Filtered to nicks who have spoken in channel in the last two hours.
#### $0 ### $0
`$0` expands to the original keyword used to invoke a factoid. See also [Overriding $0](#Overriding_$0). `$0` expands to the original keyword used to invoke a factoid.
### List variables ## List variables
You may create a factoid containing a list of quoted values. When this factoid is used as a `$variable` by using the `$` character, a random value You may create a factoid containing a list of quoted values. When this factoid is used as a `$variable` by using the `$` character, a random value
will be selected from the list. will be selected from the list.
@ -292,7 +333,7 @@ Another example, creating the RTFM trigger:
<pragma-> !rtfm mauke <pragma-> !rtfm mauke
* PBot thwacks mauke with a big red manual. * PBot thwacks mauke with a big red manual.
#### modifiers ### modifiers
Factoid `$variables` can accept trailing modifier keywords prefixed with a colon. These can be chained together to combine their effects. Factoid `$variables` can accept trailing modifier keywords prefixed with a colon. These can be chained together to combine their effects.
<pragma-> !echo $colors:uc <pragma-> !echo $colors:uc
@ -308,7 +349,7 @@ Modifier | Description
`:title` | Lowercases the expansion and then uppercases the initial letter of each word `:title` | Lowercases the expansion and then uppercases the initial letter of each word
`:<channel>` | Looks for variable in `<channel>` first; use `global` to refer to the global channel `:<channel>` | Looks for variable in `<channel>` first; use `global` to refer to the global channel
### action_with_args ## action_with_args
You can use the [`factset`](#factset) command to set a special [factoid meta-data](#factoid-metadata-list) key named `action_with_args` to trigger an alternate message if an argument has been supplied. You can use the [`factset`](#factset) command to set a special [factoid meta-data](#factoid-metadata-list) key named `action_with_args` to trigger an alternate message if an argument has been supplied.
@ -321,13 +362,13 @@ You can use the [`factset`](#factset) command to set a special [factoid meta-dat
<pragma-> !snack orbitz <pragma-> !snack orbitz
* PBot gives orbitz a cookie. * PBot gives orbitz a cookie.
### add_nick ## add_nick
You can use the [`factset`](#factset) command to set a special [factoid meta-data](#factoid-metadata-list) key named `add_nick` to prepend the nick of the caller to the output. This is mostly useful for modules. You can use the [`factset`](#factset) command to set a special [factoid meta-data](#factoid-metadata-list) key named `add_nick` to prepend the nick of the caller to the output. This is mostly useful for modules.
Adding a factoid Adding a factoid
---------------- ----------------
### factadd ## factadd
Usage: `factadd [channel] <keyword> <description>` Usage: `factadd [channel] <keyword> <description>`
To add a factoid to the global channel, use `global` as the channel. To add a factoid to the global channel, use `global` as the channel.
@ -343,15 +384,15 @@ To view or trigger a factoid, one merely issues its keyword as a command.
Viewing/triggering another channel's factoid Viewing/triggering another channel's factoid
-------------------------------------------- --------------------------------------------
### fact ## fact
To view or trigger a factoid belonging to a specific channel, use the `fact` command. To view or trigger a factoid belonging to a specific channel, use the `fact` command.
Usage: `fact <channel> <keyword> [arguments]` Usage: `fact <channel> <keyword> [arguments]`
Deleting a factoid Deleting a factoid
------------------ ------------------
### factrem ## factrem
### forget ## forget
To remove a factoid, use the `factrem` or `forget` command. To remove a factoid, use the `factrem` or `forget` command.
@ -359,7 +400,7 @@ Usage: `factrem [channel] <keyword>` `forget [channel] <keyword>`
Aliasing a factoid Aliasing a factoid
------------------ ------------------
### factalias ## factalias
To create an factoid that acts as an alias for a command, use the `factalias` command or set the factoid's `action` meta-data to `/call <command>`. To create an factoid that acts as an alias for a command, use the `factalias` command or set the factoid's `action` meta-data to `/call <command>`.
Usage: `factalias [channel] <keyword> <command>` Usage: `factalias [channel] <keyword> <command>`
@ -384,7 +425,7 @@ Usage: `factalias [channel] <keyword> <command>`
Moving/renaming a factoid Moving/renaming a factoid
------------------------- -------------------------
### factmove ## factmove
To rename a factoid or move a factoid to a different channel, use the `factmove` command: To rename a factoid or move a factoid to a different channel, use the `factmove` command:
Usage: `factmove <source channel> <source factoid> <target channel/factoid> [target factoid]` Usage: `factmove <source channel> <source factoid> <target channel/factoid> [target factoid]`
@ -393,7 +434,7 @@ If three arguments are given, the factoid is renamed in the source channel. If
Changing a factoid Changing a factoid
------------------ ------------------
### factchange ## factchange
To change a factoid, use the `factchange` command: To change a factoid, use the `factchange` command:
Usage: `factchange [channel] <keyword> s/<pattern>/<change to>/[gi]` Usage: `factchange [channel] <keyword> s/<pattern>/<change to>/[gi]`
@ -409,30 +450,30 @@ Note that the final argument is a Perl-style substitution regex. See `man perlr
For instance, it is possible to append to a factoid by using: `factchange channel factoid s/$/text to append/`. Likewise, you can prepend to a factoid by using: `factchange channel factoid s/^/text to prepend/`. For instance, it is possible to append to a factoid by using: `factchange channel factoid s/$/text to append/`. Likewise, you can prepend to a factoid by using: `factchange channel factoid s/^/text to prepend/`.
### factundo ## factundo
To revert to an older revision, use the `factundo` command. You can repeatedly undo a factoid until there are no more undos remaining. To revert to an older revision, use the `factundo` command. You can repeatedly undo a factoid until there are no more undos remaining.
Usage: `factundo [channel] <keyword>` Usage: `factundo [channel] <keyword>`
### factredo ## factredo
To revert to a newer revision, use the `factredo` command. You can repeatedly redo a factoid until there are no more redos available. To revert to a newer revision, use the `factredo` command. You can repeatedly redo a factoid until there are no more redos available.
Usage: `factredo [channel] <keyword>` Usage: `factredo [channel] <keyword>`
### factset ## factset
To view or set [factoid meta-data](#factoid-metadata-list), such as owner, rate-limit, etc, use the [`factset`](#factset) command. To view or set [factoid meta-data](#factoid-metadata-list), such as owner, rate-limit, etc, use the [`factset`](#factset) command.
Usage: `factset [channel] <factoid> [<key> [value]]` Usage: `factset [channel] <factoid> [<key> [value]]`
Omit `<key>` and `<value>` to list all the keys and values for a factoid. Specify `<key>`, but omit `<value>` to see the value for a specific key. Omit `<key>` and `<value>` to list all the keys and values for a factoid. Specify `<key>`, but omit `<value>` to see the value for a specific key.
### factunset ## factunset
To unset [factoid meta-data](#factoid-metadata-list), use the `factunset` command. To unset [factoid meta-data](#factoid-metadata-list), use the `factunset` command.
Usage: `factunset [channel] <factoid> <key>` Usage: `factunset [channel] <factoid> <key>`
#### Factoid Metadata List ## Factoid Metadata List
This is a list of recognized factoid meta-data fields. An admin level of `0` signifies that anybody can set the field. This is a list of recognized factoid meta-data fields. An admin level of `0` signifies that anybody can set the field.
Name | Admin level | Description Name | Admin level | Description
@ -460,7 +501,7 @@ Name | Admin level | Description
Finding a factoid Finding a factoid
----------------- -----------------
### factfind ## factfind
To search the database for a factoid, use the 'factfind` command. You may optionally specify whether to narrow by channel and/or include factoid owner and/or last referenced by in the search. To search the database for a factoid, use the 'factfind` command. You may optionally specify whether to narrow by channel and/or include factoid owner and/or last referenced by in the search.
If there is only one match for the query, it will display that factoid and its text, otherwise it will list all matching keywords. If there is only one match for the query, it will display that factoid and its text, otherwise it will list all matching keywords.
@ -474,7 +515,7 @@ If you specify the `-regex` flag, the `text` argument will be treated as a regex
Information about a factoid Information about a factoid
--------------------------- ---------------------------
### factinfo ## factinfo
To get information about a factoid, such as who submitted it and when, use the `factinfo` command. To get information about a factoid, such as who submitted it and when, use the `factinfo` command.
Usage: `factinfo [channel] <keyword>` Usage: `factinfo [channel] <keyword>`
@ -482,7 +523,7 @@ Usage: `factinfo [channel] <keyword>`
<pragma-> !factinfo ##c NULL <pragma-> !factinfo ##c NULL
<PBot> NULL: Factoid submitted by Major-Willard for all channels on Sat Jan 1 16:17:42 2005 [5 years and 178 days ago], referenced 39 times (last by pragma- on Sun Jun 27 04:40:32 2010 [5 seconds ago]) <PBot> NULL: Factoid submitted by Major-Willard for all channels on Sat Jan 1 16:17:42 2005 [5 years and 178 days ago], referenced 39 times (last by pragma- on Sun Jun 27 04:40:32 2010 [5 seconds ago])
### factshow ## factshow
To see the factoid `action` meta-data, use the `factshow` command. To see the factoid `action` meta-data, use the `factshow` command.
Usage: `factshow [channel] <keyword>` Usage: `factshow [channel] <keyword>`
@ -490,14 +531,14 @@ Usage: `factshow [channel] <keyword>`
<pragma-> !factshow hi <pragma-> !factshow hi
<PBot> hi: /say $greetings, $nick. <PBot> hi: /say $greetings, $nick.
### factset ## factset
To view [factoid meta-data](#factoid-metadata-list), such as owner, rate-limit, etc, use the `factset` command. To view [factoid meta-data](#factoid-metadata-list), such as owner, rate-limit, etc, use the `factset` command.
Usage: `factset [channel] <factoid> [<key> [value]]` Usage: `factset [channel] <factoid> [<key> [value]]`
Omit `<key>` and `<value>` to list all the keys and values for a factoid. Specify `<key>`, but omit `<value>` to see the value for a specific key. Omit `<key>` and `<value>` to list all the keys and values for a factoid. Specify `<key>`, but omit `<value>` to see the value for a specific key.
### factlog ## factlog
To see a factoid's changelog history, use the `factlog` command. To see a factoid's changelog history, use the `factlog` command.
Usage: `factlog [-h] [-t] [channel] <factoid>` Usage: `factlog [-h] [-t] [channel] <factoid>`
@ -519,7 +560,7 @@ Usage: `factlog [-h] [-t] [channel] <factoid>`
<pragma-> !factlog hi <pragma-> !factlog hi
<PBot> [3m ago] pragma- created: /say Hi! [5m ago] pragma- deleted [8m ago] pragma- changed to /say Hello there, $nick! [10m ago] pragma- created: /say Hello there! <PBot> [3m ago] pragma- created: /say Hi! [5m ago] pragma- deleted [8m ago] pragma- changed to /say Hello there, $nick! [10m ago] pragma- created: /say Hello there!
### count ## count
To see how many factoids and what percentage of the database `<nick>` has submitted, use the `count` command. To see how many factoids and what percentage of the database `<nick>` has submitted, use the `count` command.
Usage: `count <nick>` Usage: `count <nick>`
@ -533,13 +574,13 @@ Usage: `count <nick>`
<pragma-> !count pragma <pragma-> !count pragma
<PBot> pragma has submitted 27 factoids out of 233 (11%) <PBot> pragma has submitted 27 factoids out of 233 (11%)
### histogram ## histogram
To see a histogram of the top factoid submitters, use the `histogram` command. To see a histogram of the top factoid submitters, use the `histogram` command.
<pragma-> !histogram <pragma-> !histogram
<PBot> 268 factoids, top 10 submitters: twkm: 74 (27%) Major-Willard: 64 (23%) pragma-: 40 (14%) prec: 39 (14%) defrost: 14 (5%) PoppaVic: 10 (3%) infobahn: 7 (2%) orbitz: 3 (1%) mauke: 3 (1%) Tom^: 2 (1%) <PBot> 268 factoids, top 10 submitters: twkm: 74 (27%) Major-Willard: 64 (23%) pragma-: 40 (14%) prec: 39 (14%) defrost: 14 (5%) PoppaVic: 10 (3%) infobahn: 7 (2%) orbitz: 3 (1%) mauke: 3 (1%) Tom^: 2 (1%)
### top20 ## top20
To see the top 20 most popular factoids, use the `top20` command. It can also show you the 50 most recent factoids that were added to a channel. To see the top 20 most popular factoids, use the `top20` command. It can also show you the 50 most recent factoids that were added to a channel.
Usage: `top20 <channel> [<nick> or 'recent']` Usage: `top20 <channel> [<nick> or 'recent']`