mirror of https://github.com/pragma-/pbot.git
403 lines
17 KiB
Markdown
403 lines
17 KiB
Markdown
![]() |
Factoids
|
||
|
========
|
||
|
|
||
|
|
||
|
<!-- md-toc-begin -->
|
||
|
* [Factoids](#factoids)
|
||
|
* [Channel namespaces](#channel-namespaces)
|
||
|
* [Special commands](#special-commands)
|
||
|
* [/say](#say)
|
||
|
* [/me](#me)
|
||
|
* [/call](#call)
|
||
|
* [/msg](#msg)
|
||
|
* [Special variables](#special-variables)
|
||
|
* [$nick](#nick)
|
||
|
* [$args](#args)
|
||
|
* [$arg[n]](#argn)
|
||
|
* [$arg[n:m]](#argnm)
|
||
|
* [$arglen](#arglen)
|
||
|
* [$channel](#channel)
|
||
|
* [$randomnick](#randomnick)
|
||
|
* [$0](#0)
|
||
|
* [adlib list variables](#adlib-list-variables)
|
||
|
* [modifiers](#modifiers)
|
||
|
* [action_with_args](#action_with_args)
|
||
|
* [add_nick](#add_nick)
|
||
|
* [Viewing/triggering a factoid](#viewingtriggering-a-factoid)
|
||
|
* [Viewing/triggering another channel's factoid](#viewingtriggering-another-channels-factoid)
|
||
|
* [fact](#fact)
|
||
|
* [Adding a factoid](#adding-a-factoid)
|
||
|
* [factadd](#factadd)
|
||
|
* [Deleting a factoid](#deleting-a-factoid)
|
||
|
* [factrem](#factrem)
|
||
|
* [forget](#forget)
|
||
|
* [Aliasing a factoid](#aliasing-a-factoid)
|
||
|
* [factalias](#factalias)
|
||
|
* [Moving/renaming a factoid](#movingrenaming-a-factoid)
|
||
|
* [factmove](#factmove)
|
||
|
* [Changing a factoid](#changing-a-factoid)
|
||
|
* [factchange](#factchange)
|
||
|
* [factundo](#factundo)
|
||
|
* [factredo](#factredo)
|
||
|
* [factset](#factset)
|
||
|
* [Factoid Metadata List](#factoid-metadata-list)
|
||
|
* [factunset](#factunset)
|
||
|
* [Finding a factoid](#finding-a-factoid)
|
||
|
* [factfind](#factfind)
|
||
|
* [Information about a factoid](#information-about-a-factoid)
|
||
|
* [factinfo](#factinfo)
|
||
|
* [factshow](#factshow)
|
||
|
* [factset](#factset-1)
|
||
|
* [factlog](#factlog)
|
||
|
* [count](#count)
|
||
|
* [histogram](#histogram)
|
||
|
* [top20](#top20)
|
||
|
<!-- md-toc-end -->
|
||
|
|
||
|
|
||
|
### 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 may also be added to a special channel named `global` or `.*`. Factoids that are set in this channel will be accessible to any channel, including private messages. However, 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.
|
||
|
|
||
|
For example, a factoid named `malloc` set in `##c` will be called instead of `malloc` set in `global`, if the factoid were triggered in `##c`; otherwise, the latter 'malloc' will be triggered if the factoid were triggered in another channel.
|
||
|
|
||
|
Similiarily, if there were no `malloc` factoid in the `global` namespace, but only in `##c` and you attempted to use this factoid in a channel other than `##c`, that channel will invoke `##c`'s version of `malloc`, providing that channel doesn't have its own `malloc` factoid.
|
||
|
|
||
|
Likewise, if there is a `malloc` factoid set in `##c++` and the factoid is triggered in the `##c++` channel, then this version of `malloc` will be called instead of the `##c` or the `global` factoid.
|
||
|
|
||
|
However, if you are in a channel that doesn't have a `malloc` factoid and there is no `malloc` factoid in the global channel, and you attempt to call `malloc` then the bot will display a message notifying you that `malloc` is ambiguous and which channels it belongs to so that you may use the [fact](#fact) command to call the correct factoid.
|
||
|
|
||
|
### Special commands
|
||
|
#### /say
|
||
|
If a factoid begins with `/say ` then PBot will not use the `<factoid> is <description>` format when displaying the factoid.
|
||
|
|
||
|
<pragma-> factadd global hi /say Well, hello there, $nick.
|
||
|
<PBot> 'hi' added to the global channel
|
||
|
<prec> PBot, hi
|
||
|
<PBot> Well, hello there, prec.
|
||
|
|
||
|
#### /me
|
||
|
If a factoid begins with `/me ` then PBot will ACTION the factoid.
|
||
|
|
||
|
<pragma-> factadd global bounce /me bounces around.
|
||
|
<PBot> 'bounce' added to the global channel
|
||
|
<pragma-> bounce
|
||
|
* PBot bounces around.
|
||
|
|
||
|
#### /call
|
||
|
If a factoid begins with `/call ` then PBot will call an existing command.
|
||
|
|
||
|
<pragma-> factadd global boing /call bounce
|
||
|
<PBot> 'boing' added to the global channel
|
||
|
<pragma-> boing
|
||
|
* PBot bounces around.
|
||
|
|
||
|
#### /msg
|
||
|
If a factoid begins with `msg <nick> ` then PBot will /MSG the factoid text to <nick>
|
||
|
|
||
|
### Special variables
|
||
|
You can use the following variables in a factoid or as an argument to one.
|
||
|
|
||
|
#### $nick
|
||
|
`$nick` expands to the nick of the caller.
|
||
|
|
||
|
#### $args
|
||
|
`$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]` 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]` 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` expands to the number of arguments provided to a factoid.
|
||
|
|
||
|
#### $channel
|
||
|
`$channel` expands to the name of the channel in which the factoid is used.
|
||
|
|
||
|
#### $randomnick
|
||
|
`$randomnick` expands to a random nick from the channel in which the factoid is used.
|
||
|
|
||
|
#### $0
|
||
|
`$0` expands to the original keyword used to invoke a factoid. See also [Overriding $0](#Overriding_$0).
|
||
|
|
||
|
### adlib list variables
|
||
|
You may create a list of adlib words by using the normal factoid creation method. Multiple words can be surrounded with quotes to constitute one element.
|
||
|
|
||
|
<pragma-> factadd global colors is red green blue "bright yellow" pink "dark purple" orange
|
||
|
<PBot> colors added to the global channel
|
||
|
|
||
|
Then you can instruct PBot to pick a random word from this list to use in another factoid by inserting the list as a variable.
|
||
|
|
||
|
<pragma-> factadd global sky is /say The sky is $colors.
|
||
|
<PBot> sky added to the global channel
|
||
|
<pragma-> sky
|
||
|
<PBot> The sky is dark purple.
|
||
|
<pragma-> sky
|
||
|
<PBot> The sky is green.
|
||
|
|
||
|
A practical example, creating the RTFM trigger:
|
||
|
|
||
|
<pragma-> factadd global sizes is big large tiny small huge gigantic teeny
|
||
|
<PBot> 'sizes' added to the global channel
|
||
|
<pragma-> factadd global attacks is whaps thwacks bashes smacks punts whacks
|
||
|
<PBot> 'attacks' added to the global channel
|
||
|
<pragma-> factadd global rtfm is /me $attacks $args with a $sizes $colors manual.
|
||
|
<PBot> 'rtfm' added to the global channel
|
||
|
<pragma-> rtfm mauke
|
||
|
* PBot thwacks mauke with a big red manual.
|
||
|
|
||
|
#### modifiers
|
||
|
Adlib list variables can accept trailing modifier keywords prefixed with a colon. These can be chained together to combine their effects.
|
||
|
|
||
|
* `:uc` - uppercases the expansion
|
||
|
* `:lc` - lowercases the expansion
|
||
|
* `:ucfirst` - uppercases the first letter in the expansion
|
||
|
* `: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
|
||
|
|
||
|
|
||
|
<pragma-> echo $colors:uc
|
||
|
<PBot> RED
|
||
|
<pragma-> echo $colors:ucfirst
|
||
|
<PBot> Blue
|
||
|
|
||
|
### action_with_args
|
||
|
|
||
|
You can use the [factset](#factset) command to set a special factoid meta-data key named `action_with_args` to trigger an alternate message if an argument has been supplied.
|
||
|
|
||
|
<pragma-> factadd global snack is /me eats a cookie.
|
||
|
<PBot> 'snack' added to the global channel
|
||
|
<pragma-> factset global snack action_with_args /me gives $args a cookie.
|
||
|
<PBot> [Factoids] (global) snack: 'action_with_args' set to '/me gives $args a cookie.'
|
||
|
<pragma-> snack
|
||
|
* PBot eats a cookie.
|
||
|
<pragma-> snack orbitz
|
||
|
* PBot gives orbitz a cookie.
|
||
|
|
||
|
### add_nick
|
||
|
|
||
|
You can use the [factset](#factset) command to set a special factoid meta-data key named `add_nick` to prepend the nick of the caller to the output. This is mostly useful for modules.
|
||
|
|
||
|
Viewing/triggering a factoid
|
||
|
----------------------------
|
||
|
To view or trigger a factoid, one merely issues its keyword as a command.
|
||
|
|
||
|
<pragma-> PBot, c?
|
||
|
<PBot> C rocks!
|
||
|
|
||
|
Viewing/triggering another channel's factoid
|
||
|
--------------------------------------------
|
||
|
### fact
|
||
|
To view or trigger a factoid belonging to a specific channel, use the `fact` command.
|
||
|
|
||
|
Usage: `fact <channel> <keyword> [arguments]`
|
||
|
|
||
|
Adding a factoid
|
||
|
----------------
|
||
|
### factadd
|
||
|
Usage: `factadd [channel] <keyword> <description>`
|
||
|
|
||
|
To add a factoid to the global channel, use `global` or `.*` as the channel. `.*` is regex-speak for "everything".
|
||
|
|
||
|
<pragma-> factadd ##c c /say C rocks!
|
||
|
|
||
|
Deleting a factoid
|
||
|
------------------
|
||
|
### factrem
|
||
|
### forget
|
||
|
|
||
|
To remove a factoid, use the `factrem` or `forget` command.
|
||
|
|
||
|
Usage: `factrem <channel> <keyword>` `forget <channel> <keyword>`
|
||
|
|
||
|
Aliasing a factoid
|
||
|
------------------
|
||
|
### factalias
|
||
|
To create an factoid that acts as an alias for a command, use the `factalias` command or set the factoid's `action` to `/call <command>`.
|
||
|
|
||
|
Usage: `factalias <channel> <new keyword> <command>`
|
||
|
|
||
|
<pragma-> factadd ##c offtopic is /say In this channel, $args is off-topic.
|
||
|
<pragma-> offtopic C++
|
||
|
<PBot> In this channel, C++ is off-topic.
|
||
|
<pragma-> factalias ##c C++ offtopic C++
|
||
|
<pragma-> C++
|
||
|
<PBot> In this channel, C++ is off-topic.
|
||
|
|
||
|
<!-- -->
|
||
|
|
||
|
<pragma-> factadd ##c book is /me points accusingly at $args, "Where is your book?!"
|
||
|
<PBot> 'book' added to ##c
|
||
|
<pragma-> book newbie
|
||
|
* PBot points accusingly at newbie, "Where is your book?!"
|
||
|
<pragma-> factadd ##c rafb /call book
|
||
|
<PBot> 'rafb' added to ##c
|
||
|
<pragma-> rafb runtime
|
||
|
* PBot points accusingly at runtime, "Where is your book?!"
|
||
|
|
||
|
Moving/renaming a factoid
|
||
|
-------------------------
|
||
|
### factmove
|
||
|
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]`
|
||
|
|
||
|
If three arguments are given, the factoid is renamed in the source channel. If four arguments are given, the factoid is moved to the target channel with the target name.
|
||
|
|
||
|
Changing a factoid
|
||
|
------------------
|
||
|
### factchange
|
||
|
To change a factoid, use the `factchange` command:
|
||
|
|
||
|
Usage: `factchange <channel> <keyword> s/<pattern>/<change to>/[gi]`
|
||
|
|
||
|
<pragma-> c
|
||
|
<PBot> C rocks!
|
||
|
<pragma-> factchange ##c c s/rocks/rules/
|
||
|
<PBot> c changed.
|
||
|
<pragma-> c
|
||
|
<PBot> C rules!
|
||
|
|
||
|
Note that the final argument is a Perl-style substitution regex. See `man perlre` on your system.
|
||
|
|
||
|
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/`
|
||
|
|
||
|
Alternatively, you may append to a factoid by using `is also`:
|
||
|
|
||
|
<pragma-> PBot, c is also See FAQ at http://www.eskimo.com/~scs/C-faq/top.html
|
||
|
<PBot> Changed: c is /say C rules! ; See FAQ at http://www.eskimo.com/~scs/C-faq/top.html
|
||
|
|
||
|
### factundo
|
||
|
To revert to an older revision, use the `factundo` command. You can repeatedly factundo a factoid until it has no more remaining undos.
|
||
|
|
||
|
Usage: `factundo [channel] <keyword>`
|
||
|
|
||
|
### factredo
|
||
|
To revert to a newer revision, use the `factredo` command. You can repeatedly factredo a factoid until it has no more remaining redos.
|
||
|
|
||
|
Usage: `factredo [channel] <keyword>`
|
||
|
|
||
|
### factset
|
||
|
To view or set factoid meta-data, such as owner, rate-limit, etc, use the `factset` command. See also: [factoid metadata list](#Factoid_Metadata_List).
|
||
|
|
||
|
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.
|
||
|
|
||
|
#### Factoid Metadata List
|
||
|
This is a list of recognized factoid meta-data fields. The number in parentheses next to the field is the minimum admin level necessary to modify it; if there is no such number then anybody may modify it.
|
||
|
|
||
|
* `created_on` (90): The timestamp of when the factoid was created.
|
||
|
* `enabled` (10): Whether the factoid can be invoked or not.
|
||
|
* `last_referenced_in` (90): The channel or private-message in which the factoid was last used.
|
||
|
* `last_referenced_on` (90): The timestamp of when the factoid was last used.
|
||
|
* `modulelauncher_subpattern` (90): A substitution expression used to modify the arguments into a command-line.
|
||
|
* `owner` (90): The creator of the factoid.
|
||
|
* `rate_limit` (10): How often the factoid may be invoked, in seconds. Zero for unlimited.
|
||
|
* `ref_count` (90): How many times the factoid has been invoked.
|
||
|
* `ref_user` (90): The hostmask of the last person to invoke the factoid.
|
||
|
* `type` (90): The type of the factoid. "text" for regular factoid; "module" for module.
|
||
|
* `edited_by` (90): The hostmask of the person to last edit the factoid.
|
||
|
* `edited_on` (90): The timestamp of when the factoid was last edited.
|
||
|
* `locked` (10): If enabled, prevents the factoid from being changed or removed.
|
||
|
* `add_nick` (10): Prepends the nick of the person invoking the factoid to the output of the factoid.
|
||
|
* `nooverride` (10): Prevents the creation of a factoid with an identical name in a different channel.
|
||
|
* `effective-level` (20): the effective admin level at which this factoid executes (i.e., for /kick, etc)
|
||
|
* `persist-key` (20): the storage key for allowing code-factoids to persist variables
|
||
|
* `action_with_args`: Alternate action to perform if an argument has been supplied when invoking the factoid.
|
||
|
* `noembed`: Factoid will not be triggered if embedded within a sentence.
|
||
|
* `interpolate`: when set to a false value, $variables will not be expanded.
|
||
|
* `use_output_queue`: when set to a true value, the output will be delayed by a random number of seconds to simulate reading/typing.
|
||
|
|
||
|
### factunset
|
||
|
|
||
|
To unset factoid meta-data, use the `factunset` command.
|
||
|
|
||
|
Usage: `factunset <channel> <factoid> <key>`
|
||
|
|
||
|
Finding a factoid
|
||
|
-----------------
|
||
|
### 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.
|
||
|
|
||
|
If there is only one match for the query, it will display that factoid and its text, otherwise it will list all matching keywords.
|
||
|
|
||
|
Usage: `factfind [-channel channel] [-owner nick] [-by nick] [-regex] [text]`
|
||
|
|
||
|
If you specify the `-regex` flag, the `text` argument will be treated as a regex.
|
||
|
|
||
|
<pragma-> factfind cast
|
||
|
<PBot> 3 factoids match: [##c] NULL casting dontcastmalloc
|
||
|
|
||
|
Information about a factoid
|
||
|
---------------------------
|
||
|
### factinfo
|
||
|
To get information about a factoid, such as who submitted it and when, use the `factinfo` command.
|
||
|
|
||
|
Usage: `factinfo [channel] <keyword>`
|
||
|
|
||
|
<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])
|
||
|
|
||
|
### factshow
|
||
|
To see the factoid `action` literal, use the `factshow` command.
|
||
|
|
||
|
Usage: `factshow [channel] <keyword>`
|
||
|
|
||
|
<pragma-> factshow ##c hi
|
||
|
<PBot> hi: /say $greetings, $nick.
|
||
|
|
||
|
### factset
|
||
|
To view factoid meta-data, such as owner, rate-limit, etc, use the `factset` command.
|
||
|
|
||
|
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.
|
||
|
|
||
|
### factlog
|
||
|
To see a factoid's changelog history, use the `factlog` command.
|
||
|
|
||
|
Usage: `factlog [-h] [-t] [channel] <factoid>`
|
||
|
|
||
|
`-h` shows full hostmasks instead of just the nick. `-t` shows the actual timestamp instead of relative.
|
||
|
|
||
|
<pragma-> factadd hi /say Hello there!
|
||
|
<PBot> hi added to global channel.
|
||
|
<pragma-> factchange hi s/!$/, $nick!/
|
||
|
<PBot> Changed: hi is /say Hello there, $nick!
|
||
|
<pragma-> forget hi
|
||
|
<PBot> hi removed from the global channel.
|
||
|
<pragma-> factadd hi /say 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!
|
||
|
|
||
|
### count
|
||
|
To see how many factoids and what percentage of the database `<nick>` has submitted, use the `count` command.
|
||
|
|
||
|
Usage: `count <nick>`
|
||
|
|
||
|
<pragma-> count prec
|
||
|
<PBot> prec has submitted 28 factoids out of 233 (12%)
|
||
|
<pragma-> count twkm
|
||
|
<PBot> twkm has submitted 74 factoids out of 233 (31%)
|
||
|
<pragma-> count pragma
|
||
|
<PBot> pragma has submitted 27 factoids out of 233 (11%)
|
||
|
|
||
|
### histogram
|
||
|
To see a histogram of the top factoid submitters, use the `histogram` command.
|
||
|
|
||
|
<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%)
|
||
|
|
||
|
### top20
|
||
|
To see the top 20 most popular factoids, use the 'top20' command.
|
||
|
|