From da586de223826ed841fcf24cd7dfa26d5b1594e3 Mon Sep 17 00:00:00 2001 From: Pragmatic Software Date: Wed, 8 Jan 2020 04:26:08 -0800 Subject: [PATCH] doc/Factoids.md: many improvements --- doc/Factoids.md | 339 ++++++++++++++++++++++++------------------------ 1 file changed, 172 insertions(+), 167 deletions(-) diff --git a/doc/Factoids.md b/doc/Factoids.md index 9a58a180..304b562d 100644 --- a/doc/Factoids.md +++ b/doc/Factoids.md @@ -1,84 +1,79 @@ Factoids ======== - -* [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) + * [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) +* [Adding a factoid](#adding-a-factoid) + * [factadd](#factadd) +* [Viewing/triggering a factoid](#viewingtriggering-a-factoid) +* [Viewing/triggering another channel's factoid](#viewingtriggering-another-channels-factoid) + * [fact](#fact) +* [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) + * [factunset](#factunset) + * [Factoid Metadata List](#factoid-metadata-list) +* [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) - ### 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. +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. -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. +For example, if there were factoid named `malloc` set in `##c` and in `global`, and you invoke it in `##c` then the `##c` version would be used. If the factoid were triggered in any other channel, then the `global` version would be invoked. -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. +Now imagine `##c++` also has a `malloc` factoid. If you invoke it in `##c++` then its version of the factoid would be used instead of `##c`'s or `global`'s versions. If you invoke it in a channel that is not `##c++` or `##c` then the `global` version would be used. -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. +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 #### /say -If a factoid begins with `/say ` then PBot will not use the ` is ` format when displaying the factoid. +If a factoid begins with `/say ` then PBot will not use the ` is ` format when displaying the factoid. Instead, it will simply say only the ``. - factadd global hi /say Well, hello there, $nick. - 'hi' added to the global channel + !factadd global hi /say Well, hello there, $nick. + hi added to the global channel PBot, hi Well, hello there, prec. #### /me -If a factoid begins with `/me ` then PBot will ACTION the factoid. +If a factoid begins with `/me ` then PBot will `CTCP ACTION` the factoid. factadd global bounce /me bounces around. 'bounce' added to the global channel @@ -86,7 +81,7 @@ If a factoid begins with `/me ` then PBot will ACTION the factoid. * PBot bounces around. #### /call -If a factoid begins with `/call ` then PBot will call an existing command. +If a factoid begins with `/call ` then PBot will call an existing command. This is what [`factalias`](#factalias) does internally. factadd global boing /call bounce 'boing' added to the global channel @@ -94,7 +89,7 @@ If a factoid begins with `/call ` then PBot will call an existing command. * PBot bounces around. #### /msg -If a factoid begins with `msg ` then PBot will /MSG the factoid text to +If a factoid begins with `msg ` then PBot will `/MSG` the factoid text to ``. Only admins can use this command. ### Special variables You can use the following variables in a factoid or as an argument to one. @@ -118,7 +113,7 @@ You can use the following variables in a factoid or as an argument to one. `$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. +`$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` expands to the original keyword used to invoke a factoid. See also [Overriding $0](#Overriding_$0). @@ -126,60 +121,70 @@ You can use the following variables in a factoid or as an argument to one. ### 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. - factadd global colors is red green blue "bright yellow" pink "dark purple" orange + !factadd global colors is red green blue "bright yellow" pink "dark purple" orange 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. - factadd global sky is /say The sky is $colors. + !factadd global sky is /say The sky is $colors. sky added to the global channel - sky + !sky The sky is dark purple. - sky + !sky The sky is green. A practical example, creating the RTFM trigger: - factadd global sizes is big large tiny small huge gigantic teeny - 'sizes' added to the global channel - factadd global attacks is whaps thwacks bashes smacks punts whacks - 'attacks' added to the global channel - factadd global rtfm is /me $attacks $args with a $sizes $colors manual. - 'rtfm' added to the global channel - rtfm mauke + !factadd global sizes is big large tiny small huge gigantic teeny + sizes added to the global channel + !factadd global attacks is whaps thwacks bashes smacks punts whacks + attacks added to the global channel + !factadd global rtfm is /me $attacks $args with a $sizes $colors manual. + rtfm added to the global channel + !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 -* `:` - looks for variable in `` first; use `global` to refer to the global channel +Modifier | Description +--- | --- +`: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 +`:` | Looks for variable in `` first; use `global` to refer to the global channel - - echo $colors:uc + !echo $colors:uc RED - echo $colors:ucfirst + !echo $colors:ucfirst 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. +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. - factadd global snack is /me eats a cookie. - 'snack' added to the global channel - factset global snack action_with_args /me gives $args a cookie. + !factadd global snack is /me eats a cookie. + snack added to the global channel + !factset global snack action_with_args /me gives $args a cookie. [Factoids] (global) snack: 'action_with_args' set to '/me gives $args a cookie.' - snack + !snack * PBot eats a cookie. - snack orbitz + !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. +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 +Usage: `factadd [channel] ` + +To add a factoid to the global channel, use `global` as the channel. + + !factadd ##c c /say C rocks! Viewing/triggering a factoid ---------------------------- @@ -195,15 +200,6 @@ To view or trigger a factoid belonging to a specific channel, use the `fact` com Usage: `fact [arguments]` -Adding a factoid ----------------- -### factadd -Usage: `factadd [channel] ` - -To add a factoid to the global channel, use `global` or `.*` as the channel. `.*` is regex-speak for "everything". - - factadd ##c c /say C rocks! - Deleting a factoid ------------------ ### factrem @@ -211,7 +207,7 @@ Deleting a factoid To remove a factoid, use the `factrem` or `forget` command. -Usage: `factrem ` `forget ` +Usage: `factrem [channel] ` `forget [channel] ` Aliasing a factoid ------------------ @@ -220,22 +216,22 @@ To create an factoid that acts as an alias for a command, use the `factalias` co Usage: `factalias ` - factadd ##c offtopic is /say In this channel, $args is off-topic. - offtopic C++ + !factadd ##c offtopic is /say In this channel, $args is off-topic. + !offtopic C++ In this channel, C++ is off-topic. - factalias ##c C++ offtopic C++ - C++ + !factalias ##c C++ offtopic C++ + !C++ In this channel, C++ is off-topic. - factadd ##c book is /me points accusingly at $args, "Where is your book?!" - 'book' added to ##c - book newbie + !factadd ##c book is /me points accusingly at $args, "Where is your book?!" + book added to ##c + !book newbie * PBot points accusingly at newbie, "Where is your book?!" - factadd ##c rafb /call book - 'rafb' added to ##c - rafb runtime + !factadd ##c rafb /call book + rafb added to ##c + !rafb runtime * PBot points accusingly at runtime, "Where is your book?!" Moving/renaming a factoid @@ -254,71 +250,65 @@ To change a factoid, use the `factchange` command: Usage: `factchange s///[gi]` - c + !c C rocks! - factchange ##c c s/rocks/rules/ + !factchange ##c c s/rocks/rules/ c changed. - c + !c 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`: - - PBot, c is also See FAQ at http://www.eskimo.com/~scs/C-faq/top.html - Changed: c is /say C rules! ; See FAQ at http://www.eskimo.com/~scs/C-faq/top.html +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 -To revert to an older revision, use the `factundo` command. You can repeatedly factundo a factoid until it has no more remaining undos. +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] ` ### factredo -To revert to a newer revision, use the `factredo` command. You can repeatedly factredo a factoid until it has no more remaining redos. +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] ` ### 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). +To view or set [factoid meta-data](#factoid-metadata-list), such as owner, rate-limit, etc, use the [`factset`](#factset) command. -Usage: `factset [ [value]]` +Usage: `factset [channel] [ [value]]` Omit `` and `` to list all the keys and values for a factoid. Specify ``, but omit `` 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. +To unset [factoid meta-data](#factoid-metadata-list), use the `factunset` command. -Usage: `factunset ` +Usage: `factunset [channel] ` + +#### 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. + +Name | Admin level | Description +--- | --- | --- +`created_on` | 90 | The timestamp of when the factoid was created. +`enabled` | 10 | Whether the factoid can be invoked or not. If it is disabled, the command will be silently ignored. +`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 for a module factoid. +`owner` | 90 | The creator of the factoid. The creator has the ability to lock the factoid, etc. +`rate_limit` | 10 | The factoid may be invoked only once per this many seconds. `0` for no limit. +`ref_count` | 90 | How many times the factoid has been invoked in its life-time. +`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` | 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. +`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 ----------------- @@ -331,7 +321,7 @@ 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. - factfind cast + !factfind cast 3 factoids match: [##c] NULL casting dontcastmalloc Information about a factoid @@ -341,19 +331,19 @@ To get information about a factoid, such as who submitted it and when, use the ` Usage: `factinfo [channel] ` - factinfo ##c NULL + !factinfo ##c NULL 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. +To see the factoid `action` meta-data, use the `factshow` command. Usage: `factshow [channel] ` - factshow ##c hi + !factshow hi hi: /say $greetings, $nick. ### factset -To view factoid meta-data, 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 [ [value]]` @@ -366,17 +356,17 @@ Usage: `factlog [-h] [-t] [channel] ` `-h` shows full hostmasks instead of just the nick. `-t` shows the actual timestamp instead of relative. - factadd hi /say Hello there! + !factadd hi /say Hello there! hi added to global channel. - factchange hi s/!$/, $nick!/ + !factchange hi s/!$/, $nick!/ Changed: hi is /say Hello there, $nick! - forget hi + !forget hi hi removed from the global channel. - factadd hi /say Hi! + !factadd hi /say Hi! - factlog hi + !factlog hi [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 @@ -384,19 +374,34 @@ To see how many factoids and what percentage of the database `` has submit Usage: `count ` - count prec + !count prec prec has submitted 28 factoids out of 233 (12%) - count twkm + !count twkm twkm has submitted 74 factoids out of 233 (31%) - count pragma + !count pragma pragma has submitted 27 factoids out of 233 (11%) ### histogram To see a histogram of the top factoid submitters, use the `histogram` command. - histogram + !histogram 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. +To see the top 20 most popular factoids, use the `top20` command. It can also show you the 50 most recent factoids to be added to a channel. + +Usage: `top20 [ or 'recent']` + + !top20 ##c + Top 20 referenced factoids for ##c: explain (3459) c11 (2148) book (1070) books (1049) K&R (1000) dontcastmalloc (991) notC (696) standard (655) c99 (506) scanf (501) declare (453) std (434) cstd (344) tias (305) parens (291) int (287) c1x (272) UB (263) H&S (257) binky (236) + + + + !top20 ##c pragma- + 20 factoids last referenced by pragma- (pragma-!~chaos@unaffiliated/pragmatic-chaos): to [1d20h ago] realloc [3d15h ago] deport [4d16h ago] long [4d16h ago] decay [6d17h ago] x [6d16h ago] sizeof [13d18h ago] ENOQUESTION [13d19h ago] main [13d10h ago] cfaq [14d22h ago] heap [14d23h ago] malloc [15d15h ago] _ [16d20h ago] declareuse [17d15h ago] rot13 [17... + + + + !top20 ##c recent + 50 most recent ##c submissions: barometer [9h ago by kurahaupo] glib-pcre [21h ago by aozt] unspecified [1d13h ago by pragma-] rules [1d17h ago by oldlaptop] pjp [2d3h ago by d3738] gnu-errno-name-num [2d21h ago by aozt] cbreak [5d8h ago by jp] test case [5d9h ago by pragma-] googlearn [6d2h ago by glacial] threads [8d10h ago by glacial] cjeopard...