16 KiB
Commands
- Command interpreter
- Types of commands
- Commands documented here
- Commands documented elsewhere
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 EVERYBODYSubstitution
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 substitutionFor 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=$argsUnfortuately 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%20stuffChaining
You can execute multiple commands sequentially as one command.
<pragma-> !echo Test! ;;; me smiles. ;;; version
<PBot> Test! * PBot smiles. PBot version 2696 2020-01-04Variables
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, worldPBot variable interpolation supports expansion modifiers, which can be chained to combine their effects.
<pragma-> !echo $greeting:uc
<PBot> HELLO, WORLDInline 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.
<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/docBackground 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…
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.
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 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
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.
- only bot owner can install and load PBot Plugins
- PBot Plugins have access to PBot internal API functions and data structures
Functions
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
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
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.
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.
- 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.
Commands documented here
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 in this file.
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]
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]my
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.
<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 angelesSee also user metadata list.
date
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.weather
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