3
0
mirror of https://github.com/pragma-/pbot.git synced 2024-12-23 19:22:40 +01:00
pbot/doc/Plugins/Plang.md

159 lines
5.7 KiB
Markdown
Raw Normal View History

# Plang
<!-- md-toc-begin -->
* [About](#about)
2020-07-23 21:37:34 +02:00
* [The Plang Language](#the-plang-language)
2020-09-22 23:05:25 +02:00
* [PBot commands](#pbot-commands)
* [plang](#plang-1)
* [plangrepl](#plangrepl)
2020-07-23 21:37:34 +02:00
* [PBot built-in Plang functions](#pbot-built-in-plang-functions)
* [factget](#factget)
* [factset](#factset)
* [factappend](#factappend)
* [userget](#userget)
* [Examples](#examples)
* [Basic examples](#basic-examples)
* [Karma example](#karma-example)
<!-- md-toc-end -->
## About
The Plang plugin provides a scripting interface to PBot. It has access to PBot
internal APIs and state.
2020-07-23 21:37:34 +02:00
## The Plang Language
The scripting language is [Plang](https://github.com/pragma-/Plang). It was
written specifically for PBot, but aims to be 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
2020-07-23 21:18:53 +02:00
language, see the [Plang documentation](https://github.com/pragma-/Plang/blob/master/README.md).
2020-09-22 23:05:25 +02:00
## PBot commands
### plang
Use the `plang` command to run a Plang script.
Usage: `plang <code>`
2020-09-22 23:05:25 +02:00
### 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.
2020-07-23 21:37:34 +02:00
## PBot built-in Plang functions
[Plang](https://github.com/pragma-/Plang) lets you add custom built-in functions.
Several have been added for PBot; they are described here.
2020-10-02 02:44:01 +02:00
Function | Signature / Description
--- | ---
2020-10-02 02:40:44 +02:00
[factget](#factget) | `factget(channel: String, keyword: String, meta: String = "action") -> String \| Null`<br>Retrieve metadata from factoids
[factset](#factset) | `factset(channel: String, keyword: String, text: String, meta: String = "action") -> String`<br>Sets metadata on factoids
[factappend](#factappend) | `factappend(channel: String, keyword: String, text: String) -> String`<br>Appends to the `action` metadata on factoids
[userget](#userget) | `userget(name: String) -> Map \| Null`<br>Retrieve metadata from users
2020-07-23 21:37:34 +02:00
### factget
Use the `factget` function to retrieve metadata from factoids.
2020-09-22 23:05:25 +02:00
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"`.
2020-09-22 23:05:25 +02:00
The `factget` function returns a `String` containing the value of the factoid metadata or
`null` if the factoid does not exist.
2020-07-23 21:37:34 +02:00
### factset
2020-09-22 23:05:25 +02:00
Use the `factset` function to set metadata values for factoids. The factoid
will be created if it does not exist.
2020-09-22 23:05:25 +02:00
Signature: `factset(channel: String, keyword: String, text: String, meta: String = "action") -> String`
2020-09-22 23:05:25 +02:00
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`.
2020-07-23 21:37:34 +02:00
### factappend
Use the `factappend` function to append text to the `action` metadata for factoids.
2020-09-22 23:05:25 +02:00
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.
2020-07-23 21:37:34 +02:00
### userget
Use the `userget` function to retrieve user metadata.
Signature: `userget(name: String) -> Map | Null`
2020-09-22 23:05:25 +02:00
The `userget` function takes one parameter: `name`.
The `userget` function returns a `Map` containing all the metadata of the user, or
`null` if there is no user matching `name`.
See the [Plang Map documentation](https://github.com/pragma-/Plang#maps) for a refresher on using Plang maps.
2020-09-22 23:05:25 +02:00
## Examples
### Basic examples
<pragma-> !plang userget('pragma-')
<PBot> { channels: "global", hostmasks: "*!*@unaffiliated/pragmatic-chaos", botowner: 1 }
2020-09-22 23:05:25 +02:00
<pragma-> !plang userget('pragma-').botowner
<PBot> 1
2020-07-27 07:54:01 +02:00
2020-09-22 23:05:25 +02:00
<pragma-> !plang if userget('pragma-').botowner then print('Greetings master!') else print('Hello mortal.')
2020-07-27 07:54:01 +02:00
<PBot> Greetings master!
2020-09-22 23:05:25 +02:00
### Karma example
2020-09-30 05:02:47 +02:00
Here is a quick-and-dirty way to make a simple Karma system. This is a demonstration of what is
currently possible with Plang. This will not be its final form. Support for classes will be added
soon.
2020-09-22 23:05:25 +02:00
2020-09-30 04:59:44 +02:00
We'll use the `factget()` and `factset()` functions to get and store Karma values to an
2020-09-30 05:19:30 +02:00
unique unused channel. Let's call it `#karma-data`. To get the first command argument,
2020-09-30 04:59:44 +02:00
we'll use PBot's special factoid variable `$arg[0]`.
First we add the `++` command.
<pragma-> !factadd ++ /call plang var karma = Integer(factget('#karma-data', '$arg[0]')); factset('#karma-data', '$arg[0]', String(karma + 1));
<PBot> ++ added to global channel.
Similarly, we add the `--` command.
<pragma-> !factadd -- /call plang var karma = Integer(factget('#karma-data', '$arg[0]')); factset('#karma-data', '$arg[0]', String(karma - 1));
<PBot> -- added to global channel.
2020-09-30 04:59:44 +02:00
Finally, we add the `karma` command.
2020-09-30 05:19:30 +02:00
<pragma-> !factadd karma /call plang var k = factget('#karma-data', '$arg[0]'); if k == null then print('No karma for $arg[0] yet.') else print($'Karma for $arg[0]: {k}')
<PBot> karma added to global channel.
A short demonstration:
<pragma-> !karma nf
<PBot> No karma for nf yet.
<pragma-> !-- nf
<PBot> -1
<pragma-> !-- nf
<PBot> -2
<pragma-> !++ nf
<PBot> -1
<pragma-> !karma nf
<PBot> Karma for nf: -1
You can use double quotes to group multiple words as one argument (but not single quotes due to how `$arg[0]` is inserted
into single-quoted strings in the Plang snippets).
<pragma-> !++ "this and that"
2020-09-22 23:05:25 +02:00
<PBot> 1
<pragma-> !karma "this and that"
<PBot> Karma for "this and that": 1