<commit_before>
# Commands

<!-- md-toc-begin -->
* [Command interpreter](#command-interpreter)
  * [Command invocation](#command-invocation)
  * [Addressing output to users](#addressing-output-to-users)
  * [Inline invocation](#inline-invocation)
  * [Chaining](#chaining)
  * [Piping](#piping)
  * [Substitution](#substitution)
  * [Variables](#variables)
  * [Background processing](#background-processing)
* [Types of commands](#types-of-commands)
  * [Built-in commands](#built-in-commands)
    * [Creating new built-in commands](#creating-new-built-in-commands)
    * [Plugins](#plugins)
    * [Functions](#functions)
  * [Factoids](#factoids)
    * [Code Factoids](#code-factoids)
    * [Modules](#modules)
* [Commands documented here](#commands-documented-here)
  * [version](#version)
  * [help](#help)
  * [uptime](#uptime)
  * [my](#my)
  * [date](#date)
  * [weather](#weather)
* [Commands documented elsewhere](#commands-documented-elsewhere)
  * [Administrative commands](#administrative-commands)
    * [Logging in and out of PBot](#logging-in-and-out-of-pbot)
      * [login](Admin.md#login)
      * [logout](Admin.md#logout)
    * [User management commands](#user-management-commands)
      * [useradd](Admin.md#useradd)
      * [userdel](Admin.md#userdel)
      * [userset](Admin.md#userset)
      * [userunset](Admin.md#userunset)
      * [users](Admin.md#listing-users)
    * [Channel management commands](#channel-management-commands)
      * [join](Admin.md#join)
      * [part](Admin.md#part)
      * [chanadd](Admin.md#chanadd)
      * [chanrem](Admin.md#chanrem)
      * [chanset](Admin.md#chanset)
      * [chanunset](Admin.md#chanunset)
      * [chanlist](Admin.md#chanlist)
      * [ignore](Admin.md#ignore)
      * [unignore](Admin.md#unignore)
      * [blacklist](Admin.md#blacklist)
      * [op](Admin.md#op)
      * [deop](Admin.md#deop)
      * [voice](Admin.md#voice)
      * [devoice](Admin.md#devoice)
      * [mode](Admin.md#mode)
      * [ban/mute](Admin.md#banmute)
      * [unban/unmute](Admin.md#unbanunmute)
      * [invite](Admin.md#invite)
      * [kick](Admin.md#kick)
    * [Module management commands](#module-management-commands)
      * [load](Admin.md#load)
      * [unload](Admin.md#unload)
      * [list modules](Admin.md#listing-modules)
    * [Plugin management commands](#plugin-management-commands)
      * [plug](Admin.md#plug)
      * [unplug](Admin.md#unplug)
      * [replug](Admin.md#replug)
      * [pluglist](Admin.md#pluglist)
    * [Command metadata](#command-metadata)
      * [cmdset](Admin.md#cmdset)
      * [cmdunset](Admin.md#cmdunset)
    * [Event queue](#event-queue)
      * [eventqueue](Admin.md#eventqueue)
    * [Process management](#process-management)
      * [ps](Admin.md#ps)
      * [kill](Admin.md#kill)
    * [Registry commands](#registry-commands)
      * [regset](Registry.md#regset)
      * [regunset](Registry.md#regunset)
      * [regchange](Registry.md#regchange)
      * [regshow](Registry.md#regshow)
      * [regfind](Registry.md#regfind)
      * [regsetmeta](Registry.md#regsetmeta)
      * [regunsetmeta](Registry.md#regunsetmeta)
    * [Miscellaneous admin commands](#miscellaneous-admin-commands)
      * [export](Admin.md#export)
      * [refresh](Admin.md#refresh])
      * [reload](Admin.md#reload])
      * [sl](Admin.md#sl)
      * [die](Admin.md#die)
  * [Factoid commands](#factoid-commands)
    * [Adding/removing factoids](#addingremoving-factoids)
      * [factadd](Factoids.md#factadd)
      * [factrem](Factoids.md#factrem)
      * [factalias](Factoids.md#factalias)
    * [Displaying factoids](#displaying-factoids)
      * [fact](Factoids.md#fact)
      * [factshow](Factoids.md#factshow)
    * [Editing factoids](#editing-factoids)
      * [factchange](Factoids.md#factchange)
      * [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)
      * [factfind](Factoids.md#factfind)
      * [factinfo](Factoids.md#factinfo)
      * [factlog](Factoids.md#factlog)
      * [count](Factoids.md#count)
      * [histogram](Factoids.md#histogram)
      * [top20](Factoids.md#top20)
<!-- md-toc-end -->

## Command interpreter
PBot has a powerful command interpreter with useful functionality.

### Command invocation
There are a number of ways to invoke commands with PBot.

The syntax of PBot's commands largely follow Unix/POSIX conventions.

A single command's syntax is:

    <keyword> [arguments]

`<keyword>` is one token containing no whitespace, and is required as denoted by the angle brackets.

`[arguments]` is a list of tokens which can be quoted to contain whitespace, and is optional as denoted by the square brackets.

We will refer to this as `<command>` throughout this documentation.

The most straight-forward way to invoke a command is:

    <bot trigger> <command>

`<bot trigger>` is the bot's trigger sequence, defined in the `general.trigger` registry setting
(defined to be the exclamation mark by default).

Example:

    <pragma-> !echo hi
       <PBot> hi

You can also prefix or postfix address PBot by its nickname:

    <bot nick> <command>
    <command> <bot nick>

Examples:

    <pragma-> PBot: hello
       <PBot> Hi there, pragma-

    <pragma-> bye, PBot
       <PBot> Good-bye, pragma-

### Addressing output to users
There are a number of ways to address command output to users.

You can use the `tell` keyword:

    tell <nickname> (about|the) <command>

Examples:

    <pragma-> !tell dave about echo Testing
       <PBot> dave: Testing

    <pragma-> !tell mike the time
       <PBot> mike: It's Sun 31 May 2020 06:03:08 PM PDT in Los Angeles.

You can use the `give` keyword:

    give <nickname> <command>

Examples:

    <pragma-> !give dave echo Testing
       <PBot> dave: Testing

    <pragma-> !give mike time<commit_msg>doc/Commands.md: add another way to address output to users<commit_after>
# Commands

<!-- md-toc-begin -->
* [Command interpreter](#command-interpreter)
  * [Command invocation](#command-invocation)
  * [Addressing output to users](#addressing-output-to-users)
  * [Inline invocation](#inline-invocation)
  * [Chaining](#chaining)
  * [Piping](#piping)
  * [Substitution](#substitution)
  * [Variables](#variables)
  * [Background processing](#background-processing)
* [Types of commands](#types-of-commands)
  * [Built-in commands](#built-in-commands)
    * [Creating new built-in commands](#creating-new-built-in-commands)
    * [Plugins](#plugins)
    * [Functions](#functions)
  * [Factoids](#factoids)
    * [Code Factoids](#code-factoids)
    * [Modules](#modules)
* [Commands documented here](#commands-documented-here)
  * [version](#version)
  * [help](#help)
  * [uptime](#uptime)
  * [my](#my)
  * [date](#date)
  * [weather](#weather)
* [Commands documented elsewhere](#commands-documented-elsewhere)
  * [Administrative commands](#administrative-commands)
    * [Logging in and out of PBot](#logging-in-and-out-of-pbot)
      * [login](Admin.md#login)
      * [logout](Admin.md#logout)
    * [User management commands](#user-management-commands)
      * [useradd](Admin.md#useradd)
      * [userdel](Admin.md#userdel)
      * [userset](Admin.md#userset)
      * [userunset](Admin.md#userunset)
      * [users](Admin.md#listing-users)
    * [Channel management commands](#channel-management-commands)
      * [join](Admin.md#join)
      * [part](Admin.md#part)
      * [chanadd](Admin.md#chanadd)
      * [chanrem](Admin.md#chanrem)
      * [chanset](Admin.md#chanset)
      * [chanunset](Admin.md#chanunset)
      * [chanlist](Admin.md#chanlist)
      * [ignore](Admin.md#ignore)
      * [unignore](Admin.md#unignore)
      * [blacklist](Admin.md#blacklist)
      * [op](Admin.md#op)
      * [deop](Admin.md#deop)
      * [voice](Admin.md#voice)
      * [devoice](Admin.md#devoice)
      * [mode](Admin.md#mode)
      * [ban/mute](Admin.md#banmute)
      * [unban/unmute](Admin.md#unbanunmute)
      * [invite](Admin.md#invite)
      * [kick](Admin.md#kick)
    * [Module management commands](#module-management-commands)
      * [load](Admin.md#load)
      * [unload](Admin.md#unload)
      * [list modules](Admin.md#listing-modules)
    * [Plugin management commands](#plugin-management-commands)
      * [plug](Admin.md#plug)
      * [unplug](Admin.md#unplug)
      * [replug](Admin.md#replug)
      * [pluglist](Admin.md#pluglist)
    * [Command metadata](#command-metadata)
      * [cmdset](Admin.md#cmdset)
      * [cmdunset](Admin.md#cmdunset)
    * [Event queue](#event-queue)
      * [eventqueue](Admin.md#eventqueue)
    * [Process management](#process-management)
      * [ps](Admin.md#ps)
      * [kill](Admin.md#kill)
    * [Registry commands](#registry-commands)
      * [regset](Registry.md#regset)
      * [regunset](Registry.md#regunset)
      * [regchange](Registry.md#regchange)
      * [regshow](Registry.md#regshow)
      * [regfind](Registry.md#regfind)
      * [regsetmeta](Registry.md#regsetmeta)
      * [regunsetmeta](Registry.md#regunsetmeta)
    * [Miscellaneous admin commands](#miscellaneous-admin-commands)
      * [export](Admin.md#export)
      * [refresh](Admin.md#refresh])
      * [reload](Admin.md#reload])
      * [sl](Admin.md#sl)
      * [die](Admin.md#die)
  * [Factoid commands](#factoid-commands)
    * [Adding/removing factoids](#addingremoving-factoids)
      * [factadd](Factoids.md#factadd)
      * [factrem](Factoids.md#factrem)
      * [factalias](Factoids.md#factalias)
    * [Displaying factoids](#displaying-factoids)
      * [fact](Factoids.md#fact)
      * [factshow](Factoids.md#factshow)
    * [Editing factoids](#editing-factoids)
      * [factchange](Factoids.md#factchange)
      * [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)
      * [factfind](Factoids.md#factfind)
      * [factinfo](Factoids.md#factinfo)
      * [factlog](Factoids.md#factlog)
      * [count](Factoids.md#count)
      * [histogram](Factoids.md#histogram)
      * [top20](Factoids.md#top20)
<!-- md-toc-end -->

## Command interpreter
PBot has a powerful command interpreter with useful functionality.

### Command invocation
There are a number of ways to invoke commands with PBot.

The syntax of PBot's commands largely follow Unix/POSIX conventions.

A single command's syntax is:

    <keyword> [arguments]

`<keyword>` is one token containing no whitespace, and is required as denoted by the angle brackets.

`[arguments]` is a list of tokens which can be quoted to contain whitespace, and is optional as denoted by the square brackets.

We will refer to this as `<command>` throughout this documentation.

The most straight-forward way to invoke a command is:

    <bot trigger> <command>

`<bot trigger>` is the bot's trigger sequence, defined in the `general.trigger` registry setting
(defined to be the exclamation mark by default).

Example:

    <pragma-> !echo hi
       <PBot> hi

You can also prefix or postfix address PBot by its nickname:

    <bot nick> <command>
    <command> <bot nick>

Examples:

    <pragma-> PBot: hello
       <PBot> Hi there, pragma-

    <pragma-> bye, PBot
       <PBot> Good-bye, pragma-

### Addressing output to users
There are a number of ways to address command output to users.

You can prefix the `<bot trigger>`-based invocation with the user's nickname:

    <nickname> <bot trigger> <command>

Examples:

    <pragma-> dave: !echo Testing
       <PBot> dave: Testing

    <pragma-> mike: !time
       <PBot> mike: It's Sun 31 May 2020 06:03:08 PM PDT in Los Angeles.

You can use the `tell` keyword:

    tell <nickname> (about|the) <command>

Examples:

    <pragma-> !tell dave about echo Testing
       <PBot> dave: Testing

    <pragma-> !tell mike the time
       <PBot> mike: It's Sun 31 May 2020 06:03:08 PM PDT in Los Angeles.

You can use the `give` keyword:

    give <nickname> <command>

Examples:

    <pragma-> !give dave echo Testing
       <PBot> dave: Testing

    <pragma-> !give mike time
{'fraction_non_alphanumeric': 0.15408830414077004, 'fraction_numerical': 0.0035515376543708128, 'mean_word_length': 3.5939933259176864, 'pattern_counts': {'":': 0, '<': 69, '<?xml version=': 0, '>': 69, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3548614', 'n_tokens_mistral': 4316, 'n_tokens_neox': 4060, 'n_words': 832}