From 4998e9494e14446e1c8e13242b5782d2d1551495 Mon Sep 17 00:00:00 2001 From: Pragmatic Software Date: Thu, 23 Jul 2020 12:10:33 -0700 Subject: [PATCH] Update documentation: start adding Plugins; add Plang --- README.md | 8 +++ doc/Plugins.md | 20 ++++++++ doc/Plugins/Plang.md | 90 +++++++++++++++++++++++++++++++++ doc/{ => Plugins}/Quotegrabs.md | 0 4 files changed, 118 insertions(+) create mode 100644 doc/Plugins.md create mode 100644 doc/Plugins/Plang.md rename doc/{ => Plugins}/Quotegrabs.md (100%) diff --git a/README.md b/README.md index e23b809e..5298587c 100644 --- a/README.md +++ b/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). diff --git a/doc/Plugins.md b/doc/Plugins.md new file mode 100644 index 00000000..41c93f03 --- /dev/null +++ b/doc/Plugins.md @@ -0,0 +1,20 @@ +# Plugins + + +* [About](#about) + * [PBot Plugins](#pbot-plugins) + + +## 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/) diff --git a/doc/Plugins/Plang.md b/doc/Plugins/Plang.md new file mode 100644 index 00000000..6d31d12d --- /dev/null +++ b/doc/Plugins/Plang.md @@ -0,0 +1,90 @@ +# Plang + + +* [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) + + +## 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 ` + +#### `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: + + !plang userget('pragma-') + { channels: "global", hostmasks: "*!*\@unaffiliated/pragmatic-chaos", botowner: 1 } + + !plang userget('pragma-')['botowner'] + 1 + diff --git a/doc/Quotegrabs.md b/doc/Plugins/Quotegrabs.md similarity index 100% rename from doc/Quotegrabs.md rename to doc/Plugins/Quotegrabs.md