Update documentation: start adding Plugins; add Plang

README.md

@@ -17,6 +17,7 @@ PBot is a versatile IRC Bot written in Perl
     * [Selectors](#selectors)
     * [Inline invocation](#inline-invocation)
     * [Background processing](#background-processing)
+  * [Scripting interface](#scripting-interface)
   * [Extensible](#extensible)
   * [Factoids](#factoids)
   * [Code Factoids](#code-factoids)
@@ -186,6 +187,13 @@ The familiar [`ps`](doc/Admin.md#ps) and [`kill`](doc/Admin.md#kill) commands ca
 
 You can also [`cmdset`](doc/Admin.md#cmdset) the `process-timeout` [command metadata](doc/Admin.md#command-metadata-list) to set the timeout, in seconds, before the command is automatically killed. Otherwise the `processmanager.default_timeout` [registry value](doc/Registry.md) will be used.
 
+### Scripting interface
+PBot uses [Plang](https://github.com/pragma-/Plang) as a scripting language. You can use the
+scripting language to construct advanced commands that are capable of interacting with PBot
+internal API functions.
+
+[Learn more.](doc/Plugins/Plang.md)
+
 ### Extensible
 PBot is extensible in multiple ways. Additional commands and functionality can  be added to PBot through
 [Factoids](#factoids), [Plugins](#plugins), [Modules](#modules) and [Functions](#functions).

doc/Plugins.md

@@ -0,0 +1,20 @@
+# Plugins
+
+<!-- md-toc-begin -->
+* [About](#about)
+  * [PBot Plugins](#pbot-plugins)
+<!-- md-toc-end -->
+
+## About
+A Plugin is an independent unit of PBot code that can be loaded and unloaded at will.
+Plugins have full access to PBot internal APIs and state.
+
+### PBot Plugins
+These are the Plugins that come with PBot. Click a Plugin to learn more about it.
+
+Plugin | Description
+--- | ---
+[Plang](Plugins/Plang.md) | Scripting interface to PBot
+[Quotegrabs](Plugins/Quotegrabs.md) | Grabs and stores user messages for posterity.
+
+Note that this list is probably incomplete. For the complete list of Plugins, see [the Plugins directory.](../Plugins/)

doc/Plugins/Plang.md

@@ -0,0 +1,90 @@
+# Plang
+
+<!-- md-toc-begin -->
+* [About](#about)
+  * [The Plang Language](#the-plang-language)
+  * [PBot `plang` and `plangrepl` commands](#pbot-plang-and-plangrepl-commands)
+    * [`plang`](#plang-1)
+    * [`plangrepl`](#plangrepl)
+  * [PBot built-in Plang functions](#pbot-built-in-plang-functions)
+    * [factget](#factget)
+    * [factset](#factset)
+    * [factappend](#factappend)
+    * [userget](#userget)
+<!-- md-toc-end -->
+
+## About
+This Plang plugin provides a scripting interface to PBot. It has access to PBot
+internal APIs and state.
+
+### The Plang Language
+The scripting language is [Plang](https://github.com/pragma-/Plang). It was
+written specifically for PBot, but is powerful enough to be used as a general-purpose
+scripting language embedded into any Perl application.
+
+This document describes PBot's Plang plugin. To learn how to use the Plang scripting
+language, see the [Plang documentation](https://github.com/pragma-/Plang/README.md).
+
+### PBot `plang` and `plangrepl` commands
+#### `plang`
+Use the `plang` command to run a Plang script.
+
+Usage: `plang <code>`
+
+#### `plangrepl`
+The `plangrepl` command is identical to the `plang` command, except the environment
+is preserved in-between commands and the types of values is output along with the value.
+
+### PBot built-in Plang functions
+[Plang](https://github.com/pragma-/Plang) lets you add custom built-in functions. We
+have added several for PBot. They are described here.
+
+#### factget
+    factget(channel, keyword, meta = "action")
+
+Use the `factget` function to retrieve metadata from factoids.
+
+The `factget` function takes three paramaters: `channel`, `keyword` and `meta`. The `meta`
+parameter can be omitted and will default to `"action"`.
+
+The `factget` function returns a `String` containing the value of the factoid metadata key.
+
+#### factset
+    factset(channel, keyword, text)
+
+Use the `factset` function to set the `action` metadata value for factoids.
+
+The `factset` function takes three parameters: `channel`, `keyword` and `text`.
+
+The `factset` function returns a `String` containing the value of `text`.
+
+#### factappend
+    factappend(channel, keyword, text)
+
+Use the `factappend` function to append text to the `action` metadata for factoids.
+
+The `factappend` function takes three parameters: `channel`, `keyword` and `text`.
+
+The `factappend` function returns a `String` containing the value of factoid's `action`
+metadata with `text` appended.
+
+#### userget
+    userget(name)
+
+Use the `userget` function to retrieve user metadata.
+
+The `userget` function takes one parameter: `name`.
+
+The `userget` function returns a `Map` containing all the metadata of the user, or
+`nil` if there is no user matching `name`.
+
+See the [Plang Map documentation](https://github.com/pragma-/Plang#map) for a refresher on using Plang maps.
+
+Examples:
+
+    <pragma-> !plang userget('pragma-')
+       <PBot> { channels: "global", hostmasks: "*!*\@unaffiliated/pragmatic-chaos", botowner: 1 }
+
+    <pragma-> !plang userget('pragma-')['botowner']
+       <PBot> 1
+