3
0
mirror of https://github.com/pragma-/pbot.git synced 2024-11-25 13:29:29 +01:00

doc: update TOCs and misc improvements

This commit is contained in:
Pragmatic Software 2020-01-21 18:24:16 -08:00
parent ca0051fb68
commit 52be2c6de8
8 changed files with 295 additions and 324 deletions

View File

@ -58,7 +58,7 @@
* [unplug](Admin.md#unplug)
* [replug](Admin.md#replug)
* [pluglist](Admin.md#pluglist)
* [Command metadata commands](#command-metadata-commands)
* [Command metadata](#command-metadata)
* [cmdset](Admin.md#cmdset)
* [cmdunset](Admin.md#cmdunset)
* [Registry commands](#registry-commands)
@ -76,7 +76,7 @@
* [sl](Admin.md#sl)
* [die](Admin.md#die)
* [Factoid commands](#factoid-commands)
* [Adding/remove factoids](#addingremove-factoids)
* [Adding/removing factoids](#addingremoving-factoids)
* [factadd](Factoids.md#factadd)
* [factrem](Factoids.md#factrem)
* [factalias](Factoids.md#factalias)
@ -88,12 +88,13 @@
* [factmove](Factoids.md#factmove)
* [factundo](Factoids.md#factundo)
* [factredo](Factoids.md#factredo)
* [Factoid metadata](#factoid-metadata)
* [factset](Factoids.md#factset)
* [factunset](Factoids.md#factunset)
* [Information about factoids](#information-about-factoids)
* [factlog](Factoids.md#factlog)
* [factfind](Factoids.md#factfind)
* [factinfo](Factoids.md#factinfo)
* [factlog](Factoids.md#factlog)
* [count](Factoids.md#count)
* [histogram](Factoids.md#histogram)
* [top20](Factoids.md#top20)
@ -101,18 +102,15 @@
<!-- md-toc-end -->
## Command interpreter
PBot has a powerful command interpreter with useful functionality.
### Piping
You can pipe output from one command as input into another command, indefinitely.
<pragma-> !echo hello world | {sed s/world/everybody/} | {uc}
<PBot> HELLO EVERYBODY
### Substitution
You can insert the output from another command at any point within a command. This
substitutes the command with its output at the point where the command was used.
@ -137,14 +135,12 @@ factoid otherwise it will be expanded first.
<PBot> https://google.com/search?tbm=isch&q=spaces%20%26%20stuff
### Chaining
You can execute multiple commands sequentially as one command.
<pragma-> !echo Test! ;;; me smiles. ;;; version
<PBot> Test! * PBot smiles. PBot version 2696 2020-01-04
### Variables
You can use factoids as variables and interpolate them within commands.
<pragma-> !factadd greeting "Hello, world"
@ -159,7 +155,6 @@ combine their effects.
<PBot> HELLO, WORLD
### Inline invocation
You can invoke up to three commands inlined within a message. If the message
is addressed to a nick, the output will also be addressed to them.
@ -168,17 +163,14 @@ is addressed to a nick, the output will also be addressed to them.
<PBot> newuser13: To learn all about me, see https://github.com/pragma-/pbot/tree/master/doc
## Types of commands
There are several ways of adding new commands to PBot. We'll go over them here.
### Built-in commands
Built-in commands are commands that are internal and native to PBot. They are
executed within PBot's API and context. They have access to PBot internal
subroutine and data structures.
#### Creating new built-in commands
Built-in commands are created via the `register()` function of the `Commands`
module. Such commands are registered throughout PBot's source code. The owner
of the PBot instance can locally add new commands by editing PBot's source code
@ -188,7 +180,6 @@ or by acquiring and loading Plugins.
* built-in commands have access to PBot internal API functions and data structures
#### Plugins
Additional built-in commands can be created by loading PBot Plugins. Plugins are
stand-alone self-contained units of code that can be loaded by the PBot owner.
@ -196,7 +187,6 @@ stand-alone self-contained units of code that can be loaded by the PBot owner.
* PBot Plugins have access to PBot internal API functions and data structures
### Factoids
Factoids are another type of command. Factoids are simple text commands which
anybody can create. In their most basic form, they simply display their text
when invoked. However, significantly more complex Factoids can be created by
@ -209,7 +199,6 @@ using the [powerful interpreter features](#command-interpreter) and by using the
For more information, see the [Factoids documentations.](Factoids.md)
#### Code Factoids
Code Factoids are Factoids whose text begins with the `/code` command.
These Factoids will execute their text using the scripting or programming
language specified by the argument following the `/code` command.
@ -220,7 +209,6 @@ language specified by the argument following the `/code` command.
For more information, see the [Code Factoid documentation.](Factoids.md#code)
#### Modules
Modules are simple stand-alone external command-line scripts and programs. Just
about any application that can be run in your command-line shell can be loaded as
a PBot module.
@ -231,12 +219,10 @@ a PBot module.
For more information, see the [Modules documentation.](Modules.md)
## List of commands
Here is the list of all of PBot's built-in commands and some of the more useful
Factoids, Plugins and Modules.
### version
The `version` command displays the currently installed PBot revision and
revision date. It will also check to see if there is a new version available.
@ -244,20 +230,16 @@ revision date. It will also check to see if there is a new version available.
<PBot> PBot version 2845 2020-01-19; new version available: 2850 2020-01-20!
### help
The `help` command displays useful information about built-in commands and Factoids.
Usage: `help [keyword] [channel]`
### Administrative commands
#### Logging in and out of PBot
##### [login](Admin.md#login)
##### [logout](Admin.md#logout)
#### Admin management commands
##### [adminadd](Admin.md#adminadd)
##### [adminrem](Admin.md#adminrem)
##### [adminset](Admin.md#adminset)
@ -265,7 +247,6 @@ Usage: `help [keyword] [channel]`
##### [list admins](Admin.md#listing-admins)
#### Channel management commands
##### [join](Admin.md#join)
##### [part](Admin.md#part)
##### [chanadd](Admin.md#chanadd)
@ -300,8 +281,7 @@ Usage: `help [keyword] [channel]`
##### [replug](Admin.md#replug)
##### [pluglist](Admin.md#pluglist)
#### Command metadata commands
#### Command metadata
##### [cmdset](Admin.md#cmdset)
##### [cmdunset](Admin.md#cmdunset)
@ -316,7 +296,6 @@ Usage: `help [keyword] [channel]`
##### [regunsetmeta](Registry.md#regunsetmeta)
#### Miscellaneous admin commands
##### [export](Admin.md#export)
##### [refresh](Admin.md#refresh])
##### [reload](Admin.md#reload])
@ -324,8 +303,7 @@ Usage: `help [keyword] [channel]`
##### [die](Admin.md#die)
### Factoid commands
#### Adding/remove factoids
#### Adding/removing factoids
##### [factadd](Factoids.md#factadd)
##### [factrem](Factoids.md#factrem)
##### [factalias](Factoids.md#factalias)
@ -339,13 +317,15 @@ Usage: `help [keyword] [channel]`
##### [factmove](Factoids.md#factmove)
##### [factundo](Factoids.md#factundo)
##### [factredo](Factoids.md#factredo)
#### Factoid metadata
##### [factset](Factoids.md#factset)
##### [factunset](Factoids.md#factunset)
#### Information about factoids
##### [factlog](Factoids.md#factlog)
##### [factfind](Factoids.md#factfind)
##### [factinfo](Factoids.md#factinfo)
##### [factlog](Factoids.md#factlog)
##### [count](Factoids.md#count)
##### [histogram](Factoids.md#histogram)
##### [top20](Factoids.md#top20)

View File

@ -31,33 +31,28 @@
* [Expansion modifiers](#expansion-modifiers)
* [action_with_args](#action_with_args)
* [add_nick](#add_nick)
* [Adding a factoid](#adding-a-factoid)
* [Adding/removing factoids](#addingremoving-factoids)
* [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)
* [Displaying factoids](#displaying-factoids)
* [fact](#fact)
* [factshow](#factshow)
* [Editing factoids](#editing-factoids)
* [factchange](#factchange)
* [factmove](#factmove)
* [factundo](#factundo)
* [factredo](#factredo)
* [Factoid Metadata](#factoid-metadata)
* [factset](#factset)
* [factunset](#factunset)
* [Factoid Metadata List](#factoid-metadata-list)
* [Finding a factoid](#finding-a-factoid)
* [Information about factoids](#information-about-factoids)
* [factfind](#factfind)
* [Information about a factoid](#information-about-a-factoid)
* [factinfo](#factinfo)
* [factshow](#factshow)
* [factset](#factset-1)
* [factlog](#factlog)
* [factset](#factset-1)
* [count](#count)
* [histogram](#histogram)
* [top20](#top20)
@ -175,7 +170,7 @@ All the variables listed in [Special Variables](#special-variables-1) are expand
the code is executed or interpreted.
[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) to `0`. Alternatively, you can prevent `$variables` in
to set the `interpolate` [factoid metadata](#factoid-metadata) to `0`. Alternatively, you can prevent `$variables` in
the code from expanding by prefixing their name with an underscore, i.e. `$_variable`.
#### testargs example
@ -195,7 +190,7 @@ the C programming language because why not?
#### Setting a usage message
Suppose you want the 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).
the [`factset`](#factset) command to set the `usage` [factoid metadata](#factoid-metadata).
<pragma-> !testargs
<PBot> args:
@ -412,7 +407,7 @@ Modifier | Description
`:<channel>` | Looks for variable in `<channel>` first; use `global` to refer to the global channel
## 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 metadata](#factoid-metadata) 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
@ -427,9 +422,9 @@ You can use the [`factset`](#factset) command to set a special [factoid meta-dat
* PBot gives orbitz a cookie.
## 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 metadata](#factoid-metadata) key named `add_nick` to prepend the nick of the caller to the output. This is mostly useful for modules.
## Adding a factoid
## Adding/removing factoids
### factadd
Usage: `factadd [-f] [channel] <keyword> (<description> | -url <Web paste site>)`
@ -446,19 +441,6 @@ will retain all formatting, including line-breaks and indentation.
<pragma-> !factadd newfactoid -url http://ix.io/XXXX
<PBot> newfactoid added to global channel.
## 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]`
## Deleting a factoid
### factrem
### forget
@ -466,45 +448,61 @@ 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` 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` metadata to `/call <command>`.
Usage: `factalias [channel] <keyword> <command>`
<pragma-> !factadd ##c offtopic is /say In this channel, $args is off-topic.
<pragma-> !factadd offtopic /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-> !factadd C++ /call 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-> !factadd book /me points accusingly at $args, "Where is your book?"
<pragma-> !book newbie
* PBot points accusingly at newbie, "Where is your book?!"
* PBot points accusingly at newbie, "Where is your book?"
<pragma-> !factadd ##c rafb /call book
<PBot> rafb added to ##c
<pragma-> !factalias rafb book
<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
### factmove
To rename a factoid or move a factoid to a different channel, use the `factmove` command:
## Displaying factoids
To view or trigger a factoid, one merely issues its keyword as a command.
Usage: `factmove <source channel> <source factoid> <target channel/factoid> [target factoid]`
<pragma-> PBot, c?
<PBot> C rocks!
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.
<pragma-> !snack
* PBot eats a cookie.
## Changing a factoid
### fact
To view or trigger a factoid belonging to a specific channel, use the `fact` command.
Usage: `fact <channel> <keyword> [arguments]`
### factshow
To see a factoid's literal value without invoking the factoid, use the `factshow` command.
Usage: `factshow [-p] [channel] <keyword>`
<pragma-> !factshow hi
<PBot> hi: /say $greetings, $nick.
You can use the `-p` option to have PBot paste the factoid description to a Web-based
text paste site. PBot will output a link to the paste instead. This is useful if the
factoid was added with [`factadd`](#factadd)'s `-url` option and contains formatting
such as line-breaks and indentation.
## Editing factoids
### factchange
To change a factoid, use the `factchange` command:
@ -523,6 +521,13 @@ 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/`.
### 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.
### factundo
To revert to an older revision, use the `factundo` command. You can repeatedly undo a factoid until there are no more undos remaining.
@ -535,19 +540,19 @@ Usage: `factredo [channel] <keyword>`
## 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 metadata](#factoid-metadata-list), such as owner, rate-limit, etc, use the [`factset`](#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.
### factunset
To unset [factoid meta-data](#factoid-metadata-list), use the `factunset` command.
To unset [factoid metadata](#factoid-metadata-list), use the `factunset` command.
Usage: `factunset [channel] <factoid> <key>`
### 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 metadata fields. An admin level of `0` signifies that anybody can set the field.
Name | Admin level | Description
--- | --- | ---
@ -573,7 +578,7 @@ Name | Admin level | Description
`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.
## Finding a factoid
## Information about factoids
### 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.
@ -586,7 +591,6 @@ 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.
@ -595,26 +599,6 @@ 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 description, use the `factshow` command.
Usage: `factshow [-p] [channel] <keyword>`
<pragma-> !factshow hi
<PBot> hi: /say $greetings, $nick.
You can use the `-p` option to have PBot paste the factoid description to a Web-based
text paste site. PBot will output a link to the paste instead. This is useful if the
factoid was added with the `-url` option and contains formatting such as line-breaks
and indentation.
### factset
To view [factoid meta-data](#factoid-metadata-list), 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.
@ -640,6 +624,13 @@ Usage: `factlog [-h] [-t] [channel] <factoid>`
<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!
### factset
To view [factoid metadata](#factoid-metadata-list), 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.
### count
To see how many factoids and what percentage of the database `<nick>` has submitted, use the `count` command.