diff --git a/Plang b/Plang index ce9e56be..6a82c3fd 160000 --- a/Plang +++ b/Plang @@ -1 +1 @@ -Subproject commit ce9e56be7f51ec08d77106036fda273a7ec78f93 +Subproject commit 6a82c3fd30bde9a22675cc1b76b30d6cd1fc12b4 diff --git a/doc/Plugins/Plang.md b/doc/Plugins/Plang.md index b95e2150..60704e9f 100644 --- a/doc/Plugins/Plang.md +++ b/doc/Plugins/Plang.md @@ -3,8 +3,9 @@ * [About](#about) * [The Plang Language](#the-plang-language) -* [`plang` command](#plang-command) -* [`plangrepl` command](#plangrepl-command) +* [PBot commands](#pbot-commands) + * [plang](#plang-1) + * [plangrepl](#plangrepl) * [PBot built-in Plang functions](#pbot-built-in-plang-functions) * [factget](#factget) * [factset](#factset) @@ -24,12 +25,13 @@ 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/blob/master/README.md). -## `plang` command +## PBot commands +### plang Use the `plang` command to run a Plang script. Usage: `plang ` -## `plangrepl` command +### 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. @@ -38,39 +40,43 @@ is preserved in-between commands and the types of values is output along with th Several have been added for PBot; they are described here. ### factget - factget(channel: String, keyword: String, meta: String = "action") -> String - Use the `factget` function to retrieve metadata from factoids. +Signature: `factget(channel: String, keyword: String, meta: String = "action") -> String | Null` + 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. +The `factget` function returns a `String` containing the value of the factoid metadata or +`null` if the factoid does not exist. ### factset - factset(channel: String, keyword: String, text: String) -> String +Use the `factset` function to set metadata values for factoids. The factoid +will be created if it does not exist. -Use the `factset` function to set the `action` metadata value for factoids. +Signature: `factset(channel: String, keyword: String, text: String, meta: String = "action") -> String` -The `factset` function takes three parameters: `channel`, `keyword` and `text`. +The `factset` function takes four parameters: `channel`, `keyword`, `text`, +and optionally `meta`. If the `meta` parameter is omitted it will default to +`"action"`. The `factset` function returns a `String` containing the value of `text`. ### factappend - factappend(channel: String, keyword: String, text: String) -> String - Use the `factappend` function to append text to the `action` metadata for factoids. +Signature: `factappend(channel: String, keyword: String, text: String) -> String` + 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: String) -> Map - Use the `userget` function to retrieve user metadata. +Signature: userget(name: String) -> Map | Null + The `userget` function takes one parameter: `name`. The `userget` function returns a `Map` containing all the metadata of the user, or @@ -78,13 +84,22 @@ The `userget` function returns a `Map` containing all the metadata of the user, See the [Plang Map documentation](https://github.com/pragma-/Plang#map) for a refresher on using Plang maps. -Examples: +## Examples +### Basic examples !plang userget('pragma-') { channels: "global", hostmasks: "*!*@unaffiliated/pragmatic-chaos", botowner: 1 } - !plang userget('pragma-')['botowner'] + !plang userget('pragma-').botowner 1 - !plang if userget('pragma-')['botowner'] then print('Greetings master!') else print('Hello mortal.') + !plang if userget('pragma-').botowner then print('Greetings master!') else print('Hello mortal.') Greetings master! + +### Karma example + +This is just a quick-and-dirty placeholder snippet for now. This section will be updated with a proper +and elaborate demonstration of creating proper `karma` commands and triggers. + + !plang var karma = Integer(factget('#karma-data', 'pragma-')); karma += 1; factset('#karma-data', 'pragma-', String(karma)); + 1 diff --git a/doc/QuickStart.md b/doc/QuickStart.md index be40de1c..d98fa791 100644 --- a/doc/QuickStart.md +++ b/doc/QuickStart.md @@ -17,6 +17,7 @@ * [Other networks](#other-networks) * [Starting PBot](#starting-pbot) * [Usage](#usage) + * [rlwrap](#rlwrap) * [Overriding directories](#overriding-directories) * [Overriding registry](#overriding-registry) * [First-time start-up](#first-time-start-up) @@ -179,6 +180,12 @@ or in the `#pbot2` channel on the Freenode network. ### Usage $ pbot [directory overrides...] [registry overrides...] +#### rlwrap +It is recommended to use the `rlwrap` program for command-line history if you use +the PBot STDIN interface. + + $ rlwrap pbot [...] + #### Overriding directories You may override PBot's default directory locations via the command-line. diff --git a/doc/README.md b/doc/README.md index be192b87..453cfe4a 100644 --- a/doc/README.md +++ b/doc/README.md @@ -7,6 +7,7 @@ * [Installation](QuickStart.md#installation) * [Installing Perl](QuickStart.md#installing-perl) * [Installing CPAN modules](QuickStart.md#installing-cpan-modules) + * [re::engine::RE2](QuickStart.md#reenginere2) * [Installing PBot](QuickStart.md#installing-pbot) * [git (recommended)](QuickStart.md#git-recommended) * [Download zip archive](QuickStart.md#download-zip-archive) @@ -16,6 +17,7 @@ * [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)