2020-01-21 08:07:08 +01:00
# Commands
<!-- md - toc - begin -->
2020-01-22 02:37:13 +01:00
* [Command interpreter ](#command-interpreter )
* [Piping ](#piping )
* [Substitution ](#substitution )
* [Chaining ](#chaining )
* [Variables ](#variables )
* [Inline invocation ](#inline-invocation )
2020-02-15 08:35:34 +01:00
* [Background processing ](#background-processing )
2020-01-22 02:37:13 +01:00
* [Types of commands ](#types-of-commands )
* [Built-in commands ](#built-in-commands )
* [Creating new built-in commands ](#creating-new-built-in-commands )
* [Plugins ](#plugins )
2020-02-16 21:22:05 +01:00
* [Functions ](#functions )
2020-01-22 02:37:13 +01:00
* [Factoids ](#factoids )
* [Code Factoids ](#code-factoids )
* [Modules ](#modules )
2020-01-22 23:57:48 +01:00
* [Commands documented here ](#commands-documented-here )
2020-01-22 02:37:13 +01:00
* [version ](#version )
* [help ](#help )
2020-01-22 23:57:48 +01:00
* [uptime ](#uptime )
2020-01-27 05:15:00 +01:00
* [my ](#my )
* [date ](#date )
* [weather ](#weather )
2020-01-22 23:57:48 +01:00
* [Commands documented elsewhere ](#commands-documented-elsewhere )
2020-01-22 02:37:13 +01:00
* [Administrative commands ](#administrative-commands )
* [Logging in and out of PBot ](#logging-in-and-out-of-pbot )
* [login ](Admin.md#login )
* [logout ](Admin.md#logout )
2020-01-27 05:15:00 +01:00
* [User management commands ](#user-management-commands )
* [useradd ](Admin.md#useradd )
* [userdel ](Admin.md#userdel )
* [userset ](Admin.md#userset )
* [userunset ](Admin.md#userunset )
2020-02-10 09:19:07 +01:00
* [users ](Admin.md#listing-users )
2020-01-22 02:37:13 +01:00
* [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 )
2020-01-22 03:24:16 +01:00
* [Command metadata ](#command-metadata )
2020-01-22 02:37:13 +01:00
* [cmdset ](Admin.md#cmdset )
* [cmdunset ](Admin.md#cmdunset )
2020-02-15 08:35:34 +01:00
* [Process management ](#process-management )
* [ps ](Admin.md#ps )
* [kill ](Admin.md#kill )
2020-01-22 02:37:13 +01:00
* [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 )
2020-01-22 03:24:16 +01:00
* [Adding/removing factoids ](#addingremoving-factoids )
2020-01-22 02:37:13 +01:00
* [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 )
2020-01-22 03:24:16 +01:00
* [Factoid metadata ](#factoid-metadata )
2020-01-22 02:37:13 +01:00
* [factset ](Factoids.md#factset )
* [factunset ](Factoids.md#factunset )
* [Information about factoids ](#information-about-factoids )
* [factfind ](Factoids.md#factfind )
* [factinfo ](Factoids.md#factinfo )
2020-01-22 03:24:16 +01:00
* [factlog ](Factoids.md#factlog )
2020-01-22 02:37:13 +01:00
* [count ](Factoids.md#count )
* [histogram ](Factoids.md#histogram )
* [top20 ](Factoids.md#top20 )
2020-01-21 08:07:08 +01:00
<!-- md - toc - end -->
2020-01-21 20:35:57 +01:00
## Command interpreter
PBot has a powerful command interpreter with useful functionality.
2020-01-21 08:07:08 +01:00
2020-01-21 20:35:57 +01:00
### Piping
2020-01-21 08:07:08 +01:00
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
2020-01-21 20:35:57 +01:00
### Substitution
2020-01-21 08:07:08 +01:00
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.
< pragma- > !echo This is & {echo a demonstration} of command substitution
< PBot > This is a demonstration of command substitution
For example, suppose you want to make a Google Image Search command. The naive
way would be to simply do:
< pragma- > !factadd img /call echo https://google.com/search?tbm=isch& q=$args
Unfortuately this would not support queries containing spaces or certain symbols. But
never fear! We can use command substitution and the `uri_escape` function from the
`func` command.
Note that you must escape the command substitution to insert it literally into the
factoid otherwise it will be expanded first.
< pragma- > !factadd img /call echo https://google.com/search?tbm=isch& q=\&{func uri_escape $args}
< pragma- > !img spaces & stuff
< PBot > https://google.com/search?tbm=isch& q=spaces%20%26%20stuff
2020-01-21 20:35:57 +01:00
### Chaining
2020-01-21 08:07:08 +01:00
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
2020-01-21 20:35:57 +01:00
### Variables
2020-01-21 08:07:08 +01:00
You can use factoids as variables and interpolate them within commands.
< pragma- > !factadd greeting "Hello, world"
< pragma- > !echo greeting is $greeting
< PBot > greeting is Hello, world
PBot variable interpolation supports [expansion modifiers ](doc/Factoids.md#expansion-modifiers ), which can be chained to
combine their effects.
< pragma- > !echo $greeting:uc
< PBot > HELLO, WORLD
2020-01-21 20:35:57 +01:00
### Inline invocation
2020-01-21 08:07:08 +01:00
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.
< pragma- > newuser13: Check the !{version} and the !{help} documentation.
< PBot > newuser13: PBot version 2696 2020-01-04
< PBot > newuser13: To learn all about me, see https://github.com/pragma-/pbot/tree/master/doc
2020-02-15 08:35:34 +01:00
### Background processing
Any command can be flagged to be executed as a background process. For example, suppose you
make a Plugin that has a command that may potentially take a long time to complete, which could
cause PBot to be non-responsive...
2020-02-15 08:36:47 +01:00
Not a problem! You can use the [`cmdset` ](Admin.md#cmdset ) command to set the `background-process` [command metadata ](Admin.md#command-metadata-list )
2020-02-15 08:35:34 +01:00
and the command will now run as a background process, allowing PBot to carry on with its duties.
2020-02-15 08:36:47 +01:00
The familiar [`ps` ](Admin.md#ps ) and [`kill` ](Admin.md#kill ) commands can be used to list and kill the background processes.
2020-02-15 08:35:34 +01:00
2020-02-15 08:36:47 +01:00
You can also [`cmdset` ](Admin.md#cmdset ) the `process-timeout` [command metadata ](Admin.md#command-metadata-list ) to set the timeout, in seconds, before the command is automatically killed. Otherwise the `processmanager.default_timeout` [registry value ](Registry.md ) will be used.
2020-02-15 08:35:34 +01:00
2020-01-21 08:07:08 +01:00
## Types of commands
2020-01-21 20:35:57 +01:00
There are several ways of adding new commands to PBot. We'll go over them here.
2020-01-21 08:07:08 +01:00
### Built-in commands
2020-01-21 20:35:57 +01:00
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
2020-01-22 06:29:27 +01:00
of the PBot instance can add new commands by editing PBot's source code
2020-01-21 20:49:45 +01:00
or by acquiring and loading Plugins.
2020-01-21 20:35:57 +01:00
2020-01-22 06:29:27 +01:00
* only bot owner can create new built-in commands
2020-01-22 02:37:13 +01:00
* built-in commands have access to PBot internal API functions and data structures
2020-01-21 08:07:08 +01:00
#### Plugins
2020-01-21 20:35:57 +01:00
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.
2020-01-21 21:50:41 +01:00
2020-01-22 02:37:13 +01:00
* only bot owner can install and load PBot Plugins
* PBot Plugins have access to PBot internal API functions and data structures
2020-01-21 20:35:57 +01:00
2020-02-16 21:22:05 +01:00
#### Functions
Functions are commands that accept input, manipulate it and then output the result. They are extremely
useful with [piping ](#piping ) or [command substituting ](#substitution ).
2020-02-16 21:26:17 +01:00
For example, the `uri_escape` function demonstrated in the [Substitution ](#substitution ) section earlier
2020-02-16 21:22:05 +01:00
makes text safe for use in a URL. We also saw the `sed` and `uc` functions demonstrated in [Piping ](#piping ).
Functions can be loaded via PBot Plugins.
* only bot owner can load new Functions
* Functions have access to PBot internal API functions and data structures
2020-02-16 21:27:23 +01:00
For more information, see the [Functions documentation. ](Functions.md )
2020-01-21 08:07:08 +01:00
### Factoids
2020-01-22 02:37:13 +01:00
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
using the [powerful interpreter features ](#command-interpreter ) and by using the even more powerful
[`/code` Factoid command ](Factoids.md#code ).
* anybody can create Factoids
2020-01-27 23:00:08 +01:00
* Factoids do not have access to PBot internal API functions and data structures (unless the [`eval` ](Admin.md#eval ) command is used)
2020-01-21 20:35:57 +01:00
2020-01-22 02:37:13 +01:00
For more information, see the [Factoids documentations. ](Factoids.md )
2020-01-21 20:35:57 +01:00
2020-01-21 08:07:08 +01:00
#### Code Factoids
2020-01-21 20:49:45 +01:00
Code Factoids are Factoids whose text begins with the `/code` command.
These Factoids will execute their text using the scripting or programming
2020-01-22 02:37:13 +01:00
language specified by the argument following the `/code` command.
* anybody can create Code Factoids
2020-01-27 23:00:08 +01:00
* Code Factoids do not have access to PBot internal API functions and data structures (unless the [`eval` ](Admin.md#eval ) command is used)
2020-01-21 20:35:57 +01:00
2020-01-22 02:37:13 +01:00
For more information, see the [Code Factoid documentation. ](Factoids.md#code )
2020-01-21 20:35:57 +01:00
2020-01-21 08:07:08 +01:00
#### Modules
2020-01-21 20:35:57 +01:00
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.
2020-01-22 02:37:13 +01:00
* only bot owner can install new command-line modules
* Modules do not have access to PBot internal API functions and data structures
For more information, see the [Modules documentation. ](Modules.md )
2020-01-21 20:35:57 +01:00
2020-01-22 23:57:48 +01:00
## Commands documented here
These are the commands documented in this file. For commands documented in
other files see the [PBot documentation ](../doc ).
There is also a list of of commands and links to their documentation in the
[Commands documented elsewhere ](#commands-documented-elsewhere ) section in this file.
2020-01-21 20:35:57 +01:00
2020-01-22 02:37:13 +01:00
### 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.
< pragma- > !version
< 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]`
2020-01-22 23:57:48 +01:00
### uptime
The `uptime` command displays the date and time your instance of PBot was started
and how long it has been running.
< pragma- > !uptime
< PBot > Tue Jan 14 01:55:40 2020 [8 days and 13 hours]
2020-01-27 05:15:00 +01:00
### my
2020-01-27 23:00:08 +01:00
The `my` command allows non-admin users to view and manipulate their user account
metadata.
Usage: `my [<key> [value]]`
If `key` is omitted, the command will list all metadata keys and values for your
user account.
2020-01-27 23:09:34 +01:00
< pragma- > my timezone los angeles
< PBot > [global] *!* @unaffiliated/pragmatic -chaos: timezone set to los angeles
<!-- -->
< pragma- > my
< PBot > Usage: my [< key > [value]]; [global] *!* @unaffiliated/pragmatic -chaos keys:
2020-02-04 11:28:26 +01:00
autologin => 1; botowner => 1; location => PST, loggedin => 1; name => pragma;
2020-01-27 23:09:34 +01:00
password => < private > ; timezone => los angeles
2020-01-27 23:00:08 +01:00
See also [user metadata list ](Admin.md#user-metadata-list ).
2020-01-27 05:15:00 +01:00
### date
2020-01-27 23:00:08 +01:00
The `date` command displays the date and time. Note that it uses the Linux
timezone files to find timezones.
2020-01-29 21:43:35 +01:00
Usage: `date [-u <user account>] [timezone]`
2020-01-27 05:15:00 +01:00
2020-01-27 23:00:08 +01:00
If `timezone` is omitted, the command will show the UTC date and time unless you
have the `timezone` user metadata set on your user account in which case the command
will use that timezone instead.
2020-01-29 21:43:35 +01:00
If the `-u <user account>` option is specified, the command will use the `timezone`
user metadata set for `<user account>` .
2020-01-27 23:00:08 +01:00
You may use the [`my` ](#my ) command to set the user metadata `timezone`
to have the command remember your timezone.
2020-01-27 23:09:34 +01:00
< pragma- > !date los angeles
2020-01-27 23:13:11 +01:00
< PBot > It's Mon 27 Jan 2020 16:20:00 PM PST in Los Angeles.
2020-01-27 23:09:34 +01:00
2020-01-27 05:15:00 +01:00
### weather
2020-01-27 23:00:08 +01:00
The `weather` command displays the weather conditions and temperature for a location.
2020-01-29 21:43:35 +01:00
Usage: `weather [-u <user account>] [location]`
2020-01-27 23:00:08 +01:00
If `location` is omitted, the command will use the `location` user metadata set on your
user account.
2020-01-29 21:43:35 +01:00
If the `-u <user account>` option is specified, the command will use the `location`
user metadata set for `<user account>` .
2020-01-27 23:00:08 +01:00
You may use the [`my` ](#my ) command to set the user metadata `location`
to have the command remember your location.
2020-01-27 05:15:00 +01:00
2020-01-27 23:09:34 +01:00
< pragma- > !weather los angeles
< PBot > Weather for Los Angeles, CA: Currently: Mostly Sunny: 71F/21C;
Forecast: High: 72F/22C Low: 53F/11C Warmer with sunshine
2020-01-22 23:57:48 +01:00
## Commands documented elsewhere
2020-01-21 08:07:08 +01:00
### Administrative commands
2020-01-21 20:35:57 +01:00
#### Logging in and out of PBot
2020-01-21 21:43:07 +01:00
##### [login](Admin.md#login)
##### [logout](Admin.md#logout)
2020-01-21 20:49:45 +01:00
2020-01-27 05:15:00 +01:00
#### User management commands
##### [useradd](Admin.md#useradd)
##### [userdel](Admin.md#userdel)
##### [userset](Admin.md#userset)
##### [userunset](Admin.md#userunset)
2020-02-10 09:19:07 +01:00
##### [users](Admin.md#listing-users)
2020-01-21 20:49:45 +01:00
2020-01-21 20:35:57 +01:00
#### Channel management commands
2020-01-21 21:43:07 +01:00
##### [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)
2020-01-22 02:37:13 +01:00
##### [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)
2020-01-21 20:49:45 +01:00
2020-01-21 20:35:57 +01:00
#### Module management commands
2020-01-21 21:43:07 +01:00
##### [load](Admin.md#load)
##### [unload](Admin.md#unload)
##### [list modules](Admin.md#listing-modules)
2020-01-21 20:49:45 +01:00
2020-01-21 20:35:57 +01:00
#### Plugin management commands
2020-01-21 21:43:07 +01:00
##### [plug](Admin.md#plug)
##### [unplug](Admin.md#unplug)
2020-01-21 22:10:40 +01:00
##### [replug](Admin.md#replug)
2020-01-21 21:43:07 +01:00
##### [pluglist](Admin.md#pluglist)
2020-01-21 20:35:57 +01:00
2020-01-22 03:24:16 +01:00
#### Command metadata
2020-01-21 21:43:07 +01:00
##### [cmdset](Admin.md#cmdset)
##### [cmdunset](Admin.md#cmdunset)
2020-01-21 20:35:57 +01:00
2020-02-15 08:35:34 +01:00
#### Process management
##### [ps](Admin.md#ps)
##### [kill](Admin.md#kill)
2020-01-21 20:35:57 +01:00
2020-02-15 08:35:34 +01:00
#### Registry commands
2020-01-21 21:10:29 +01:00
##### [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)
2020-01-21 20:35:57 +01:00
2020-01-21 20:49:45 +01:00
#### Miscellaneous admin commands
2020-01-21 21:10:29 +01:00
##### [export](Admin.md#export)
##### [refresh](Admin.md#refresh])
##### [reload](Admin.md#reload])
##### [sl](Admin.md#sl)
##### [die](Admin.md#die)
2020-01-21 20:35:57 +01:00
2020-01-21 20:49:45 +01:00
### Factoid commands
2020-01-22 03:24:16 +01:00
#### Adding/removing factoids
2020-01-21 21:10:29 +01:00
##### [factadd](Factoids.md#factadd)
2020-01-21 21:43:07 +01:00
##### [factrem](Factoids.md#factrem)
2020-01-21 21:45:07 +01:00
##### [factalias](Factoids.md#factalias)
2020-01-21 21:10:29 +01:00
#### Displaying factoids
##### [fact](Factoids.md#fact)
##### [factshow](Factoids.md#factshow)
#### Editing factoids
2020-01-21 21:45:07 +01:00
##### [factchange](Factoids.md#factchange)
##### [factmove](Factoids.md#factmove)
##### [factundo](Factoids.md#factundo)
##### [factredo](Factoids.md#factredo)
2020-01-22 03:24:16 +01:00
#### Factoid metadata
2020-01-21 21:45:07 +01:00
##### [factset](Factoids.md#factset)
##### [factunset](Factoids.md#factunset)
2020-01-21 21:10:29 +01:00
#### Information about factoids
2020-01-21 21:45:07 +01:00
##### [factfind](Factoids.md#factfind)
##### [factinfo](Factoids.md#factinfo)
2020-01-22 03:24:16 +01:00
##### [factlog](Factoids.md#factlog)
2020-01-21 21:45:07 +01:00
##### [count](Factoids.md#count)
##### [histogram](Factoids.md#histogram)
##### [top20](Factoids.md#top20)
