pbot/doc/README.md

# PBot Documentation

## Table of Contents

<!-- md-toc-begin -->
* [QuickStart](QuickStart.md#quickstart)
  * [Installation](QuickStart.md#installation)
    * [Installing Perl](QuickStart.md#installing-perl)
    * [Installing PBot](QuickStart.md#installing-pbot)
      * [git (recommended)](QuickStart.md#git-recommended)
      * [Download zip archive](QuickStart.md#download-zip-archive)
  * [Initial Setup](QuickStart.md#initial-setup)
    * [Installing CPAN modules](QuickStart.md#installing-cpan-modules)
      * [Installing cpanminus](QuickStart.md#installing-cpanminus)
      * [Installing and using local::lib](QuickStart.md#installing-and-using-locallib)
      * [Using cpanminus](QuickStart.md#using-cpanminus)
      * [re::engine::RE2](QuickStart.md#reenginere2)
    * [Clone data-directory](QuickStart.md#clone-data-directory)
    * [Configuration](QuickStart.md#configuration)
      * [Recommended settings for IRC Networks](QuickStart.md#recommended-settings-for-irc-networks)
  * [Starting PBot](QuickStart.md#starting-pbot)
    * [Usage](QuickStart.md#usage)
      * [rlwrap](QuickStart.md#rlwrap)
      * [Overriding directories](QuickStart.md#overriding-directories)
      * [Overriding registry](QuickStart.md#overriding-registry)
    * [First-time start-up](QuickStart.md#first-time-start-up)
      * [Using default settings](QuickStart.md#using-default-settings)
      * [Using custom settings](QuickStart.md#using-custom-settings)
    * [Regular start-up](QuickStart.md#regular-start-up)
  * [Additional configuration](QuickStart.md#additional-configuration)
    * [Creating your bot owner admin account](QuickStart.md#creating-your-bot-owner-admin-account)
    * [Adding other users and admins](QuickStart.md#adding-other-users-and-admins)
    * [Adding channels](QuickStart.md#adding-channels)
  * [Further Reading](QuickStart.md#further-reading)
    * [Commands](QuickStart.md#commands)
    * [Factoids](QuickStart.md#factoids)
    * [Plugins](QuickStart.md#plugins)
    * [Applets](QuickStart.md#applets)
<!-- md-toc-end -->
<!-- md-toc-begin -->
* [Plugins](Plugins.md#plugins)
  * [About](Plugins.md#about)
  * [Plang](Plugins/Plang.md)
  * [Quotegrabs](Plugins/Quotegrabs.md)
<!-- md-toc-end -->
<!-- md-toc-begin -->
* [Commands](Commands.md#commands)
  * [Command interpreter](Commands.md#command-interpreter)
    * [Command invocation](Commands.md#command-invocation)
    * [Addressing output to users](Commands.md#addressing-output-to-users)
    * [Inline invocation](Commands.md#inline-invocation)
    * [Chaining](Commands.md#chaining)
    * [Piping](Commands.md#piping)
    * [Substitution](Commands.md#substitution)
    * [Variables](Commands.md#variables)
    * [Selectors](Commands.md#selectors)
    * [Background processing](Commands.md#background-processing)
  * [Types of commands](Commands.md#types-of-commands)
    * [Built-in commands](Commands.md#built-in-commands)
      * [Listing all built-in commands](Commands.md#listing-all-built-in-commands)
      * [Creating new built-in commands](Commands.md#creating-new-built-in-commands)
      * [Plugins](Commands.md#plugins)
      * [Functions](Commands.md#functions)
    * [Factoids](Commands.md#factoids)
      * [Code Factoids](Commands.md#code-factoids)
      * [Applets](Commands.md#applets)
  * [Commands documented here](Commands.md#commands-documented-here)
    * [version](Commands.md#version)
    * [help](Commands.md#help)
    * [uptime](Commands.md#uptime)
    * [my](Commands.md#my)
    * [date](Commands.md#date)
    * [weather](Commands.md#weather)
  * [Commands documented elsewhere](Commands.md#commands-documented-elsewhere)
    * [Administrative](Commands.md#administrative)
      * [Logging in and out of PBot](Commands.md#logging-in-and-out-of-pbot)
      * [User-management](Commands.md#user-management)
      * [Channel-management](Commands.md#channel-management)
      * [Applet-management](Commands.md#applet-management)
      * [Plugin-management](Commands.md#plugin-management)
      * [Command metadata](Commands.md#command-metadata)
      * [Event-queue management](Commands.md#event-queue-management)
      * [Process-management](Commands.md#process-management)
      * [Registry](Commands.md#registry)
      * [Message-history/user-tracking](Commands.md#message-historyuser-tracking)
      * [Miscellaneous admin commands](Commands.md#miscellaneous-admin-commands)
    * [Factoid commands](Commands.md#factoid-commands)
      * [Adding/removing factoids](Commands.md#addingremoving-factoids)
      * [Displaying factoids](Commands.md#displaying-factoids)
      * [Editing factoids](Commands.md#editing-factoids)
      * [Factoid metadata](Commands.md#factoid-metadata)
      * [Information about factoids](Commands.md#information-about-factoids)
<!-- md-toc-end -->
<!-- md-toc-begin -->
* [Administrative](Admin.md#administrative)
  * [Logging in and out](Admin.md#logging-in-and-out)
    * [login](Admin.md#login)
    * [logout](Admin.md#logout)
  * [User-management](Admin.md#user-management)
    * [useradd](Admin.md#useradd)
    * [userdel](Admin.md#userdel)
    * [userset](Admin.md#userset)
    * [userunset](Admin.md#userunset)
      * [User metadata list](Admin.md#user-metadata-list)
    * [Listing users](Admin.md#listing-users)
  * [User capabilities](Admin.md#user-capabilities)
    * [Introduction](Admin.md#introduction)
    * [cap](Admin.md#cap)
      * [Listing capabilities](Admin.md#listing-capabilities)
      * [Grouping capabilities](Admin.md#grouping-capabilities)
      * [Giving capabilities to users](Admin.md#giving-capabilities-to-users)
      * [Checking user capabilities](Admin.md#checking-user-capabilities)
      * [Listing users who have a capability](Admin.md#listing-users-who-have-a-capability)
      * [User capabilities list](Admin.md#user-capabilities-list)
  * [Channel management](Admin.md#channel-management)
    * [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)
      * [Channel metadata list](Admin.md#channel-metadata-list)
    * [ignore](Admin.md#ignore)
    * [unignore](Admin.md#unignore)
    * [blacklist](Admin.md#blacklist)
    * [nicklist](Admin.md#nicklist)
    * [banlist](Admin.md#banlist)
    * [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)
    * [checkban](Admin.md#checkban)
    * [checkmute](Admin.md#checkmute)
    * [invite](Admin.md#invite)
    * [kick](Admin.md#kick)
  * [Applet-management](Admin.md#applet-management)
    * [load](Admin.md#load)
    * [unload](Admin.md#unload)
    * [Listing applets](Admin.md#listing-applets)
  * [Plugin-management](Admin.md#plugin-management)
    * [plug](Admin.md#plug)
    * [unplug](Admin.md#unplug)
    * [replug](Admin.md#replug)
    * [pluglist](Admin.md#pluglist)
  * [Command metadata](Admin.md#command-metadata)
    * [cmdset](Admin.md#cmdset)
    * [cmdunset](Admin.md#cmdunset)
    * [Command metadata list](Admin.md#command-metadata-list)
  * [Event-queue management](Admin.md#event-queue-management)
    * [eventqueue](Admin.md#eventqueue)
  * [Process-management](Admin.md#process-management)
    * [ps](Admin.md#ps)
    * [kill](Admin.md#kill)
  * [Message-history/user-tracking](Admin.md#message-historyuser-tracking)
    * [recall](Admin.md#recall)
    * [id](Admin.md#id)
    * [aka](Admin.md#aka)
    * [akalink](Admin.md#akalink)
    * [akaunlink](Admin.md#akaunlink)
    * [akadelete](Admin.md#akadelete)
  * [Miscellaneous](Admin.md#miscellaneous)
    * [export](Admin.md#export)
    * [refresh](Admin.md#refresh)
    * [reload](Admin.md#reload)
    * [sl](Admin.md#sl)
    * [die](Admin.md#die)
<!-- md-toc-end -->
<!-- md-toc-begin -->
* [Factoids](Factoids.md#factoids)
  * [About](Factoids.md#about)
  * [Special commands](Factoids.md#special-commands)
    * [/say](Factoids.md#say)
    * [/me](Factoids.md#me)
    * [/call](Factoids.md#call)
    * [/msg](Factoids.md#msg)
    * [/code](Factoids.md#code)
      * [Supported languages](Factoids.md#supported-languages)
      * [Special variables](Factoids.md#special-variables)
      * [testargs example](Factoids.md#testargs-example)
      * [Setting a usage message](Factoids.md#setting-a-usage-message)
      * [poll/vote example](Factoids.md#pollvote-example)
      * [SpongeBob Mock meme example](Factoids.md#spongebob-mock-meme-example)
      * [Using command-piping](Factoids.md#using-command-piping)
      * [Improving SpongeBob Mock meme](Factoids.md#improving-spongebob-mock-meme)
      * [Formatting and editing lengthy Code Factoids](Factoids.md#formatting-and-editing-lengthy-code-factoids)
  * [Special variables](Factoids.md#special-variables-1)
    * [$args](Factoids.md#args)
    * [$arg[n]](Factoids.md#argn)
    * [$arg[n:m]](Factoids.md#argnm)
    * [$arglen](Factoids.md#arglen)
    * [$channel](Factoids.md#channel)
    * [$nick](Factoids.md#nick)
    * [$randomnick](Factoids.md#randomnick)
    * [$0](Factoids.md#0)
  * [List variables](Factoids.md#list-variables)
    * [Expansion modifiers](Factoids.md#expansion-modifiers)
  * [action_with_args](Factoids.md#action_with_args)
  * [add_nick](Factoids.md#add_nick)
  * [Channel namespaces](Factoids.md#channel-namespaces)
  * [Adding/removing factoids](Factoids.md#addingremoving-factoids)
    * [factadd](Factoids.md#factadd)
    * [factrem](Factoids.md#factrem)
    * [forget](Factoids.md#forget)
    * [factalias](Factoids.md#factalias)
  * [Displaying factoids](Factoids.md#displaying-factoids)
    * [fact](Factoids.md#fact)
    * [factshow](Factoids.md#factshow)
  * [Editing factoids](Factoids.md#editing-factoids)
    * [factchange](Factoids.md#factchange)
    * [factmove](Factoids.md#factmove)
    * [factundo](Factoids.md#factundo)
    * [factredo](Factoids.md#factredo)
  * [Factoid metadata](Factoids.md#factoid-metadata)
    * [factset](Factoids.md#factset)
    * [factunset](Factoids.md#factunset)
    * [Factoid metadata List](Factoids.md#factoid-metadata-list)
  * [Information about factoids](Factoids.md#information-about-factoids)
    * [factfind](Factoids.md#factfind)
    * [factinfo](Factoids.md#factinfo)
    * [factlog](Factoids.md#factlog)
    * [factset](Factoids.md#factset-1)
    * [count](Factoids.md#count)
    * [histogram](Factoids.md#histogram)
    * [top20](Factoids.md#top20)
<!-- md-toc-end -->
<!-- md-toc-begin -->
* [Registry](Registry.md#registry)
  * [About](Registry.md#about)
    * [Types of values](Registry.md#types-of-values)
    * [Creating array values](Registry.md#creating-array-values)
    * [Overriding Registry values per-channel](Registry.md#overriding-registry-values-per-channel)
  * [Overriding Registry values via command-line](Registry.md#overriding-registry-values-via-command-line)
  * [Registry commands](Registry.md#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)
  * [Editing Registry file](Registry.md#editing-registry-file)
  * [Metadata list](Registry.md#metadata-list)
  * [List of known Registry items](Registry.md#list-of-known-registry-items)
    * [Channel-specific Registry items](Registry.md#channel-specific-registry-items)
<!-- md-toc-end -->
<!-- md-toc-begin -->
* [Applets](Applets.md#applets)
  * [About](Applets.md#about)
  * [Creating applets](Applets.md#creating-applets)
  * [Documentation for built-in applets](Applets.md#documentation-for-built-in-applets)
    * [cc](Applets.md#cc)
      * [Usage](Applets.md#usage)
      * [Supported Languages](Applets.md#supported-languages)
      * [Default Language](Applets.md#default-language)
      * [Disallowed system calls](Applets.md#disallowed-system-calls)
      * [Program termination with no output](Applets.md#program-termination-with-no-output)
      * [Abnormal program termination](Applets.md#abnormal-program-termination)
      * [C and C++ Functionality](Applets.md#c-and-c-functionality)
      * [Using the preprocessor](Applets.md#using-the-preprocessor)
      * [main() Function Unnecessary](Applets.md#main-function-unnecessary)
      * [Embedding Newlines](Applets.md#embedding-newlines)
      * [Printing in binary/base2](Applets.md#printing-in-binarybase2)
      * [Using the GDB debugger](Applets.md#using-the-gdb-debugger)
      * [Interactive Editing](Applets.md#interactive-editing)
      * [Some Examples](Applets.md#some-examples)
    * [english](Applets.md#english)
    * [expand](Applets.md#expand)
    * [prec](Applets.md#prec)
    * [paren](Applets.md#paren)
    * [faq](Applets.md#faq)
    * [cfact](Applets.md#cfact)
    * [cjeopardy](Applets.md#cjeopardy)
      * [hint](Applets.md#hint)
      * [what](Applets.md#what)
      * [w](Applets.md#w)
      * [filter](Applets.md#filter)
      * [score](Applets.md#score)
      * [rank](Applets.md#rank)
      * [reset](Applets.md#reset)
      * [qstats](Applets.md#qstats)
      * [qshow](Applets.md#qshow)
    * [c99std](Applets.md#c99std)
    * [c11std](Applets.md#c11std)
    * [man](Applets.md#man)
    * [google](Applets.md#google)
    * [define](Applets.md#define)
    * [dict](Applets.md#dict)
    * [foldoc](Applets.md#foldoc)
    * [vera](Applets.md#vera)
    * [udict](Applets.md#udict)
    * [wdict](Applets.md#wdict)
    * [acronym](Applets.md#acronym)
    * [math](Applets.md#math)
    * [calc](Applets.md#calc)
    * [qalc](Applets.md#qalc)
    * [compliment](Applets.md#compliment)
    * [insult](Applets.md#insult)
    * [excuse](Applets.md#excuse)
    * [horoscope](Applets.md#horoscope)
    * [quote](Applets.md#quote)
<!-- md-toc-end -->
<!-- md-toc-begin -->
* [Anti-Abuse](AntiAbuse.md#anti-abuse)
  * [Flood control](AntiAbuse.md#flood-control)
    * [Message flood](AntiAbuse.md#message-flood)
    * [Join flood](AntiAbuse.md#join-flood)
    * [Enter key abuse](AntiAbuse.md#enter-key-abuse)
    * [Nick flood](AntiAbuse.md#nick-flood)
  * [Anti-away/Nick-control](AntiAbuse.md#anti-awaynick-control)
  * [Anti-auto-rejoin control](AntiAbuse.md#anti-auto-rejoin-control)
  * [Opping/Deopping](AntiAbuse.md#oppingdeopping)
<!-- md-toc-end -->
<!-- md-toc-begin -->
* [Virtual Machine](VirtualMachine.md#virtual-machine)
  * [Initial virtual machine set-up](VirtualMachine.md#initial-virtual-machine-set-up)
    * [Prerequisites](VirtualMachine.md#prerequisites)
      * [CPU Virtualization Technology](VirtualMachine.md#cpu-virtualization-technology)
      * [KVM](VirtualMachine.md#kvm)
      * [libvirt and QEMU](VirtualMachine.md#libvirt-and-qemu)
      * [Make a pbot-vm user or directory](VirtualMachine.md#make-a-pbot-vm-user-or-directory)
      * [Add libvirt group to your user](VirtualMachine.md#add-libvirt-group-to-your-user)
      * [Download Linux ISO](VirtualMachine.md#download-linux-iso)
    * [Create a new virtual machine](VirtualMachine.md#create-a-new-virtual-machine)
      * [Install Linux in the virtual machine](VirtualMachine.md#install-linux-in-the-virtual-machine)
      * [Set up serial ports](VirtualMachine.md#set-up-serial-ports)
      * [Set up virtio-vsock](VirtualMachine.md#set-up-virtio-vsock)
      * [Reboot virtual machine](VirtualMachine.md#reboot-virtual-machine)
      * [Install software](VirtualMachine.md#install-software)
      * [Install Perl](VirtualMachine.md#install-perl)
      * [Install PBot VM Guest](VirtualMachine.md#install-pbot-vm-guest)
      * [Start PBot VM Guest](VirtualMachine.md#start-pbot-vm-guest)
      * [Test PBot VM Guest](VirtualMachine.md#test-pbot-vm-guest)
      * [Save initial state](VirtualMachine.md#save-initial-state)
    * [Initial virtual machine set-up complete](VirtualMachine.md#initial-virtual-machine-set-up-complete)
  * [Start PBot VM Host](VirtualMachine.md#start-pbot-vm-host)
    * [Test PBot](VirtualMachine.md#test-pbot)
<!-- md-toc-end -->
<!-- md-toc-begin -->
* [Frequently Asked Questions](FAQ.md#frequently-asked-questions)
  * [When I type `!version` it say "new version available"?](FAQ.md#when-i-type-version-it-say-new-version-available)
  * [How do I change the bot trigger?](FAQ.md#how-do-i-change-the-bot-trigger)
  * [How do I whitelist a user?](FAQ.md#how-do-i-whitelist-a-user)
  * [How do I change how the bot outputs multi-line messages?](FAQ.md#how-do-i-change-how-the-bot-outputs-multi-line-messages)
  * [I made a command. It's supposed to output formatting with spaces and tabs?](FAQ.md#i-made-a-command-its-supposed-to-output-formatting-with-spaces-and-tabs)
  * [How do I change my password?](FAQ.md#how-do-i-change-my-password)
  * [How do I make PBot remember my `date` timezone?](FAQ.md#how-do-i-make-pbot-remember-my-date-timezone)
  * [How do I make PBot remember my `weather` location?](FAQ.md#how-do-i-make-pbot-remember-my-weather-location)
<!-- md-toc-end -->