- Command interpreter
- Types of commands
- Commands documented here
- Commands documented elsewhere
PBot has a powerful command interpreter with useful functionality.
There are a number of ways to invoke commands with PBot.
The documentation and syntax of PBot's commands largely follow Unix/POSIX conventions:
Square brackets [optional] indicate that the enclosed element (parameter, value, or information) is optional.
You can choose one or more items or no items. Do not type the square brackets themselves in the command line.
Angle brackets <required> indicate that the enclosed element (parameter, value, or information) is mandatory.
You are required to replace the text within the angle brackets with the appropriate information.
Do not type the angle brackets themselves in the command line.
A parenthesized set of elements delimited by a vertical bar (x|y|z) indicates mutually exclusive choices. You
must pick one and only one. Do not type the parentheses in the command line.
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-
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
<PBot> mike: It's Sun 31 May 2020 06:03:08 PM PDT in Los Angeles.
You can use inline invocation, as well -- see the next section.
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.
The syntax for inline invocation is:
[nickname:] [text] <bot trigger>{ <command> } [text]
[nickname:] may optionally be prefixed to the message to address the command output to them.
[text] is optional message text that is ignored.
<bot trigger> is the bot's command trigger; which defaults to the exclamation mark (!).
<command> is the command to invoke.
Example:
<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
You can execute multiple commands sequentially as one command.
The syntax for chaining is:
<command> ;;; <command> [...]
Example:
<pragma-> !echo Test! ;;; me smiles. ;;; version
<PBot> Test! * PBot smiles. PBot version 2696 2020-01-04
You can pipe output from one command as input into another command, indefinitely.
The syntax for piping is:
<command> | { <command> } [...]
Example:
<pragma-> !echo hello world | {sed s/world/everybody/} | {uc}
<PBot> HELLO EVERYBODY
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.
The syntax for substitution is:
<command &{ <command> } >
Example:
<pragma-> !echo This is &{echo a demonstration} of command substitution
<PBot> This is a demonstration of command substitution
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. To fix this,
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
Both Piping and Substitutions can be nested.
For example:
<pragma-> !echo $randomnick's IQ is &{roll 1d50+70}
<PBot> mnrmnaugh's IQ is rolled 1d50+70 for 85.
<pragma-> !echo $randomnick's IQ is &{roll 1d50+70 | {sed s/rolled.*for //}}
<PBot> ntwk's IQ is 110.
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, which can be chained to combine their effects.
<pragma-> !echo $greeting:uc
<PBot> HELLO, WORLD
You can select a random item from a selection list and interpolate the value within commands.
The syntax for Selectors is:
%(<list of selections>)[:modifiers]
<list of selections> is a list of items or $variables separated by a vertical bar.
[:modifiers] is an optional list of modifiers, each prefixed with a colon. See expansion-modifiers.
Examples:
<pragma-> !echo This is a %(neat|cool|awesome) bot.
<PBot> This is a cool bot.
<pragma-> !echo IRC is %(fun|weird|confusing|amazing):pick_unique(2):enumerate
<PBot> IRC is weird and fun
You can use Selectors to create a command that picks randomly from a list of commands!
Example:
<pragma-> !factadd lart /call %(kick|slap|insult) $args
<PBot> lart added
<pragma-> !lart someuser
<PBot> someuser: If I ever need a brain transplant, I'd choose yours because I'd want a brain that had never been used.
<pragma-> !lart someuser
* PBot slaps someuser with a large rabid turkey.
To allow an unprivileged (not bot owner, admin, etc) user to use the kick command within the lart command, you must
set the cap-override Factoid metadata:
<pragma-> !factset lart cap-override can-kick 1
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...
Not a problem! You can use the cmdset command to set the background-process command metadata
and the command will now run as a background process, allowing PBot to carry on with its duties.
The familiar ps and kill commands can be used to list and kill the background processes.
You can also cmdset the process-timeout command metadata to set the timeout, in seconds, before the command is automatically killed. Otherwise the processmanager.default_timeout registry value will be used.
There are several ways of adding new commands to PBot. We'll go over them here.
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.
To list all built-in commands, use the list commands command.
Commands prefixed with a + require the user to have the respective can-<command>
user-capability in order to invoke it.
<pragma-> list commands
<PBot> Registered commands: +actiontrigger aka +akadelete +akalink +akaunlink +antispam +ban +ban-exempt banlist battleship +blacklist cap +chanadd +chanlist ... etc
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 add new commands by editing PBot's source code
or by acquiring and loading Plugins.
- only bot owner can create new built-in commands
- built-in commands have access to PBot internal API functions and data structures
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.
- only bot owner can install and load PBot Plugins
- PBot Plugins have access to PBot internal API functions and data structures
Functions are commands that accept input, manipulate it and then output the result. They are extremely useful with piping or command substituting.
For example, the uri_escape function demonstrated in the Substitution section earlier
makes text safe for use in a URL. We also saw the sed and uc functions demonstrated in 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
For more information, see the Functions documentation.
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 and by using the even more powerful
/code Factoid command.
- anybody can create Factoids
- Factoids do not have access to PBot internal API functions and data structures (unless the
evalcommand is used)
For more information, see the Factoids documentations.
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.
- anybody can create Code Factoids
- Code Factoids do not have access to PBot internal API functions and data structures (unless the
evalcommand is used)
For more information, see the Code Factoid documentation.
Applets 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 applet.
- only bot owner can install new command-line applets
- Applets do not have access to PBot internal API functions and data structures
For more information, see the Applets documentation.
To list all of the currently loaded applets, use the list applets command.
<pragma-> list applets
<PBot> Loaded applets: ago bashfaq bashpf c11std c2english c99std cdecl cfact cfaq ... etc.
These are the commands documented in this file. For commands documented in other files see the PBot documentation.
There is also a list of of commands and links to their documentation in the Commands documented elsewhere section of this file.
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!
The help command displays useful information about built-in commands and Factoids.
Usage: help [keyword] [channel]
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]
The my command allows non-admin users to view and manipulate their user account
metadata. If there is no user account, one will be created with an appropriate
hostmask.
Usage: my [<key> [value]]
If key is omitted, the command will list all metadata keys and values for your
user account.
<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:
autologin => 1; botowner => 1; location => PST, loggedin => 1; name => pragma;
password => <private>; timezone => los angeles
See also user metadata list.
The date command displays the date and time. Note that it uses the Linux
timezone files to find timezones.
Usage: date [-u <user account>] [timezone]
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.
If the -u <user account> option is specified, the command will use the timezone
user metadata set for <user account>.
You may use the my command to set the user metadata timezone
to have the command remember your timezone.
<pragma-> !date los angeles
<PBot> It's Mon 27 Jan 2020 16:20:00 PM PST in Los Angeles.
The weather command displays the weather conditions and temperature for a location.
Usage: weather [-u <user account>] [location]
If location is omitted, the command will use the location user metadata set on your
user account.
If the -u <user account> option is specified, the command will use the location
user metadata set for <user account>.
You may use the my command to set the user metadata location
to have the command remember your location.
<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