diff --git a/doc/Admin.md b/doc/Admin.md index 1be894da..53e5a2a4 100644 --- a/doc/Admin.md +++ b/doc/Admin.md @@ -4,7 +4,7 @@ * [Logging in and out](#logging-in-and-out) * [login](#login) * [logout](#logout) -* [User management commands](#user-management-commands) +* [User-management commands](#user-management-commands) * [useradd](#useradd) * [userdel](#userdel) * [userset](#userset) @@ -43,11 +43,11 @@ * [unban/unmute](#unbanunmute) * [invite](#invite) * [kick](#kick) -* [Module management commands](#module-management-commands) +* [Module-management commands](#module-management-commands) * [load](#load) * [unload](#unload) * [Listing modules](#listing-modules) -* [Plugin management commands](#plugin-management-commands) +* [Plugin-management commands](#plugin-management-commands) * [plug](#plug) * [unplug](#unplug) * [replug](#replug) @@ -56,12 +56,14 @@ * [cmdset](#cmdset) * [cmdunset](#cmdunset) * [Command metadata list](#command-metadata-list) -* [Event queue management](#event-queue-management) +* [Event-queue management](#event-queue-management) * [eventqueue](#eventqueue) -* [Process management commands](#process-management-commands) +* [Process-management commands](#process-management-commands) * [ps](#ps) * [kill](#kill) -* [Message history commands](#message-history-commands) +* [Message-history/user-tracking commands](#message-historyuser-tracking-commands) + * [recall](#recall) + * [id](#id) * [aka](#aka) * [akalink](#akalink) * [akaunlink](#akaunlink) @@ -91,7 +93,7 @@ Logs out of PBot. Usage: `logout` -## User management commands +## User-management commands ### useradd Adds a new user to PBot. @@ -478,7 +480,7 @@ Removes a user from the channel. `` can be a comma-separated list of multi Usage from channel: `kick [reason]` From private message: `kick [reason]` -## Module management commands +## Module-management commands Note that modules are "reloaded" each time they are executed. There is no need to `refresh` after editing a module. ### load @@ -503,7 +505,7 @@ it is included here for completeness. Usage: `list modules` -## Plugin management commands +## Plugin-management commands ### plug Loads a plugin into PBot. @@ -552,7 +554,7 @@ Name | Description `background-process` | When set to a true value then this command will be executed as a background process. Use this for commands that can potentially take a long time to complete. `process-timeout` | The timeout, in seconds, before the process is automatically killed. If not set then the `processmanager.default_timeout` [registry](Registry.md) value will be used. -## Event queue management +## Event-queue management ### eventqueue PBot uses an event queue to schedule future tasks or commands. The `eventqueue` command can be used to list or remove upcoming events. It can also be used to schedule a command. @@ -581,7 +583,7 @@ Or to remove all `command` events in `#channel`: eventqueue remove command #channel * -## Process management commands +## Process-management commands ### ps Lists all currently running background processes. @@ -607,13 +609,67 @@ Option | Description If neither options `-a` or `-t` are provided then the `pids...` option is required. -## Message history commands +## Message-history/user-tracking commands Message history has an advanced user tracking algorithm in order to ensure that messages are being stored in the right message history accounts. The following commands query and manipulate the message history account links. Note that "message history account" and "PBot user account" are distinct accounts. +### recall +The `recall` command queries the message history and displays matching results. + +Usage: `recall [nick [history [channel]]] [-c ] [-t ] [-b ] [-a ] [-x ] [-n ] [-r raw mode] [+ ...]` + +You can chain multiple recalls together with the `+` operator. + +Option | Description +--- | --- +`-c ` | Filter to messages only in `` +`-t ` | Filter to messages containing `` +`-b ` | Show `` (integral) count messages appearing immediately before matching messages +`-a ` | Show `` (integral) count messages appearing immediately after matching messages +`-x ` | Filter messages to only those spoken by `` +`-n ` | Limit results to `` (integral); implies `-x` +`-r` | Show only the message without any nickname or timestamp prefixes + +Examples: + + hello + hi there + hey + PBot: recall garp + [20s ago] hi there + PBot: recall garp -b1 -a1 + [35s ago] hello [20s ago] hi there [10s ago] hey + PBot: recall -t hey + [10s ago] hey + +### id +The `id` command lists various user-tracking and user-account metadata about a user hostmask. + +Usage: `id [nickname | hostmask | message account id]` + +If no argument is provided, your own id information will be shown. The `hostmask` form accepts wildcards. +The `message account id` form is an integer. + +Examples: + + id + pragma- (pragma-!~chaos@user/pragmatic-chaos): user id: 2; user account: pragma- (logged in); NickServ: pragma- + + id pragma- + pragma- (pragma-!~chaos@user/pragmatic-chaos): user id: 2; user account: pragma- (logged in); NickServ: pragma- + + id 2 + pragma- (pragma-!~chaos@user/pragmatic-chaos): user id: 2; user account: pragma- (logged in); NickServ: pragma- + + id *!*@*/pragmatic-chaos + pragma- (pragma-!~chaos@user/pragmatic-chaos): user id: 2; user account: pragma- (logged in); NickServ: pragma- + + id *!*@user/* + Multiple accounts found: PBot!pbot3@user/pbot (1), pragma-!~chaos@user/pragmatic-chaos (2), ... + ### aka The `aka` command lists all known aliases for a given message history account. @@ -623,7 +679,7 @@ Option | Description --- | --- `-h` | show hostmasks `-i` | show ids -`-l` | show last seen +`-l` | show last seen timestamps `-n` | show nickserv accounts `-g` | show gecos `-r` | show relationships @@ -654,7 +710,7 @@ Usage: `akalink [type]` The optional `type` argument can be `0` (weak) or `1` (strong). Defaults to `1`. -Use the `id` command to look up message history account ids for a given hostmask. +Use the [`id`](#id) command to look up message history account ids for a given hostmask. ### akaunlink The `akaunlink` command manually unlinks two message history accounts from each other. diff --git a/doc/Commands.md b/doc/Commands.md index a6c532f3..ef6290dd 100644 --- a/doc/Commands.md +++ b/doc/Commands.md @@ -84,11 +84,12 @@ * [regsetmeta](Registry.md#regsetmeta) * [regunsetmeta](Registry.md#regunsetmeta) * [Message history](#message-history) - * [recall](Commands.md#recall) + * [recall](Admin.md#recall) * [aka](Admin.md#aka) * [akalink](Admin.md#akalink) * [akaunlink](Admin.md#akaunlink) * [akadelete](Admin.md#akadelete) + * [id](Admin.md#id) * [Miscellaneous admin commands](#miscellaneous-admin-commands) * [export](Admin.md#export) * [refresh](Admin.md#refresh) @@ -574,11 +575,12 @@ to have the command remember your location. ##### [regunsetmeta](Registry.md#regunsetmeta) #### Message history -##### [recall](Commands.md#recall) +##### [recall](Admin.md#recall) ##### [aka](Admin.md#aka) ##### [akalink](Admin.md#akalink) ##### [akaunlink](Admin.md#akaunlink) ##### [akadelete](Admin.md#akadelete) +##### [id](Admin.md#id) #### Miscellaneous admin commands ##### [export](Admin.md#export) diff --git a/doc/Functions.md b/doc/Functions.md index c1e6c413..c193f8a2 100644 --- a/doc/Functions.md +++ b/doc/Functions.md @@ -21,6 +21,7 @@ Name | Description --- | --- `uri_escape` | Percent-encodes unsafe URI characters. `sed` | Performs sed-like regex substitution. +`grep` | Searches a string, using a regex, and prints the matching whole-word (e.g. `echo pizza hamburger hotdog \| {grep burger}` outputs `hamburger`). `pluralize` | Intelligently makes a word or phrase plural. `unquote` | Removes surrounding quotation marks. `title` | Title-cases text. That is, lowercases the text then uppercases the first letter of each word. @@ -28,4 +29,5 @@ Name | Description `uc` | Uppercases all characters. `lc` | Lowercases all characters. -Additional Functions can be loaded via PBot Plugins. +Additional Functions can be loaded via PBot Plugins. For examples, see [Plugin/FuncBuiltins.pm](../lib/PBot/Plugin/FuncBuiltins.pm) and +[Plugin/FuncGrep.pm](../lib/PBot/Plugin/FuncGrep.pm). diff --git a/doc/README.md b/doc/README.md index 2ca888df..c0739a40 100644 --- a/doc/README.md +++ b/doc/README.md @@ -95,7 +95,7 @@ * [Logging in and out](Admin.md#logging-in-and-out) * [login](Admin.md#login) * [logout](Admin.md#logout) - * [User management commands](Admin.md#user-management-commands) + * [User-management commands](Admin.md#user-management-commands) * [useradd](Admin.md#useradd) * [userdel](Admin.md#userdel) * [userset](Admin.md#userset) @@ -132,11 +132,11 @@ * [unban/unmute](Admin.md#unbanunmute) * [invite](Admin.md#invite) * [kick](Admin.md#kick) - * [Module management commands](Admin.md#module-management-commands) + * [Module-management commands](Admin.md#module-management-commands) * [load](Admin.md#load) * [unload](Admin.md#unload) * [Listing modules](Admin.md#listing-modules) - * [Plugin management commands](Admin.md#plugin-management-commands) + * [Plugin-management commands](Admin.md#plugin-management-commands) * [plug](Admin.md#plug) * [unplug](Admin.md#unplug) * [replug](Admin.md#replug) @@ -145,12 +145,14 @@ * [cmdset](Admin.md#cmdset) * [cmdunset](Admin.md#cmdunset) * [Command metadata list](Admin.md#command-metadata-list) - * [Event queue management](Admin.md#event-queue-management) + * [Event-queue management](Admin.md#event-queue-management) * [eventqueue](Admin.md#eventqueue) - * [Process management commands](Admin.md#process-management-commands) + * [Process-management commands](Admin.md#process-management-commands) * [ps](Admin.md#ps) * [kill](Admin.md#kill) - * [Message history commands](Admin.md#message-history-commands) + * [Message-history/user-tracking commands](Admin.md#message-historyuser-tracking-commands) + * [recall](Admin.md#recall) + * [id](Admin.md#id) * [aka](Admin.md#aka) * [akalink](Admin.md#akalink) * [akaunlink](Admin.md#akaunlink)