GitHub
/
pbot
mirror of https://github.com/pragma-/pbot.git
3
0
Fork 0
Code Issues Projects Releases Wiki Activity

doc/Factoids.md: fix TOC; minor edits

This commit is contained in:
Pragmatic Software 2020-01-08 21:08:45 -08:00
parent 43057a6a9e
commit 88f1f6dadd
1 changed files with 57 additions and 67 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

124
doc/Factoids.md
View File

@ -1,5 +1,4 @@
Factoids # Factoids
========
<!-- md-toc-begin --> <!-- md-toc-begin -->
* [Channel namespaces](#channel-namespaces) * [Channel namespaces](#channel-namespaces)
@ -31,34 +30,35 @@ Factoids
* [action_with_args](#action_with_args) * [action_with_args](#action_with_args)
* [add_nick](#add_nick) * [add_nick](#add_nick)
* [Adding a factoid](#adding-a-factoid) * [Adding a factoid](#adding-a-factoid)
* [factadd](#factadd) * [factadd](#factadd)
* [Viewing/triggering a factoid](#viewingtriggering-a-factoid) * [Viewing/triggering a factoid](#viewingtriggering-a-factoid)
* [Viewing/triggering another channel's factoid](#viewingtriggering-another-channels-factoid) * [Viewing/triggering another channel's factoid](#viewingtriggering-another-channels-factoid)
* [fact](#fact) * [fact](#fact)
* [Deleting a factoid](#deleting-a-factoid) * [Deleting a factoid](#deleting-a-factoid)
* [factrem](#factrem) * [factrem](#factrem)
* [forget](#forget) * [forget](#forget)
* [Aliasing a factoid](#aliasing-a-factoid) * [Aliasing a factoid](#aliasing-a-factoid)
* [factalias](#factalias) * [factalias](#factalias)
* [Moving/renaming a factoid](#movingrenaming-a-factoid) * [Moving/renaming a factoid](#movingrenaming-a-factoid)
* [factmove](#factmove) * [factmove](#factmove)
* [Changing a factoid](#changing-a-factoid) * [Changing a factoid](#changing-a-factoid)
* [factchange](#factchange) * [factchange](#factchange)
* [factundo](#factundo) * [factundo](#factundo)
* [factredo](#factredo) * [factredo](#factredo)
* [factset](#factset) * [Factoid Metadata](#factoid-metadata)
* [factunset](#factunset) * [factset](#factset)
* [Factoid Metadata List](#factoid-metadata-list) * [factunset](#factunset)
* [Factoid Metadata List](#factoid-metadata-list)
* [Finding a factoid](#finding-a-factoid) * [Finding a factoid](#finding-a-factoid)
* [factfind](#factfind) * [factfind](#factfind)
* [Information about a factoid](#information-about-a-factoid) * [Information about a factoid](#information-about-a-factoid)
* [factinfo](#factinfo) * [factinfo](#factinfo)
* [factshow](#factshow) * [factshow](#factshow)
* [factset](#factset-1) * [factset](#factset-1)
* [factlog](#factlog) * [factlog](#factlog)
* [count](#count) * [count](#count)
* [histogram](#histogram) * [histogram](#histogram)
* [top20](#top20) * [top20](#top20)
<!-- md-toc-end --> <!-- md-toc-end -->
## Channel namespaces ## Channel namespaces
@ -157,7 +157,7 @@ All the variables listed in [Special Variables](#special-variables-1) are expand
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)
to set the `interpolate` [factoid meta-data](#factoid-metadata-list) to `0`. Alternatively, you can prevent `$variables` in to set the `interpolate` [factoid meta-data](#factoid-metadata) to `0`. Alternatively, you can prevent `$variables` in
the code from expanding by prefixing their name with an underscore, i.e. `$_variable`. the code from expanding by prefixing their name with an underscore, i.e. `$_variable`.
#### testargs example #### testargs example
@ -175,7 +175,7 @@ the C programming language because why not?
#### Setting a usage message #### Setting a usage message
Suppose you want command to display a usage message if there are no arguments provided. You can use Suppose you want command to display a usage message if there are no arguments provided. You can use
the [`factset`](#factset) command to set the `usage` [factoid meta-data](#factoid-metadata-list). the [`factset`](#factset) command to set the `usage` [factoid meta-data](#factoid-metadata).
<pragma-> !testargs <pragma-> !testargs
<PBot> args: <PBot> args:
@ -350,8 +350,7 @@ Modifier | Description
`:<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) 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.
<pragma-> !factadd global snack is /me eats a cookie. <pragma-> !factadd global snack is /me eats a cookie.
<PBot> snack added to the global channel <PBot> snack added to the global channel
@ -363,44 +362,38 @@ You can use the [`factset`](#factset) command to set a special [factoid meta-dat
* 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) 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
### factadd
Adding a factoid
----------------
## 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.
<pragma-> !factadd ##c c /say C rocks! <pragma-> !factadd ##c c /say C rocks!
Viewing/triggering a factoid ## Viewing/triggering a factoid
----------------------------
To view or trigger a factoid, one merely issues its keyword as a command. To view or trigger a factoid, one merely issues its keyword as a command.
<pragma-> PBot, c? <pragma-> PBot, c?
<PBot> C rocks! <PBot> C rocks!
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.
Usage: `factrem [channel] <keyword>` `forget [channel] <keyword>` 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>`
@ -423,18 +416,16 @@ Usage: `factalias [channel] <keyword> <command>`
<pragma-> !rafb runtime <pragma-> !rafb runtime
* PBot points accusingly at runtime, "Where is your book?!" * PBot points accusingly at runtime, "Where is your book?!"
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]`
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. 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 ## 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]`
@ -450,30 +441,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 ## Factoid Metadata
### 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
@ -497,11 +488,11 @@ Name | Admin level | Description
`persist-key` | 20 | the storage key for allowing code-factoids to persist variables `persist-key` | 20 | the storage key for allowing code-factoids to persist variables
`action_with_args` | 0 | Alternate action to perform if an argument has been supplied when invoking the factoid. `action_with_args` | 0 | Alternate action to perform if an argument has been supplied when invoking the factoid.
`interpolate` | 0 | When set to a false value, `$variables` will not be expanded. `interpolate` | 0 | When set to a false value, `$variables` will not be expanded.
`usage` | 0 | Prints a usage message when no arguments are provided.
`use_output_queue` | 0 | When set to a true value, the output will be delayed by a random number of seconds to simulate reading/typing. `use_output_queue` | 0 | When set to a true value, the output will be delayed by a random number of seconds to simulate reading/typing.
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.
@ -513,9 +504,8 @@ If you specify the `-regex` flag, the `text` argument will be treated as a regex
<pragma-> !factfind cast <pragma-> !factfind cast
<PBot> 3 factoids match: [##c] NULL casting dontcastmalloc <PBot> 3 factoids match: [##c] NULL casting dontcastmalloc
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>`
@ -523,7 +513,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>`
@ -531,14 +521,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>`
@ -560,7 +550,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>`
@ -574,13 +564,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']`