2020-07-23 21:10:33 +02:00
# 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 )
2020-09-30 04:49:01 +02:00
* [Examples ](#examples )
* [Basic examples ](#basic-examples )
* [Karma example ](#karma-example )
2020-07-23 21:10:33 +02:00
<!-- md - toc - end -->
## About
2020-07-23 21:53:38 +02:00
The Plang plugin provides a scripting interface to PBot. It has access to PBot
2020-07-23 21:10:33 +02:00
internal APIs and state.
2020-07-23 21:37:34 +02:00
## The Plang Language
2020-07-23 21:10:33 +02:00
The scripting language is [Plang ](https://github.com/pragma-/Plang ). It was
2020-09-21 08:12:43 +02:00
written specifically for PBot, but aims to be powerful enough to be used as a general-purpose
2020-07-23 21:10:33 +02:00
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-07-23 21:10:33 +02:00
2020-09-22 23:05:25 +02:00
## PBot commands
### plang
2020-07-23 21:10:33 +02:00
Use the `plang` command to run a Plang script.
Usage: `plang <code>`
2020-09-22 23:05:25 +02:00
### plangrepl
2020-07-23 21:10:33 +02:00
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-07-23 21:10:33 +02:00
2020-07-23 21:37:34 +02:00
### factget
2020-07-23 21:10:33 +02:00
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`
2020-07-23 21:10:33 +02:00
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:10:33 +02:00
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-07-23 21:10:33 +02:00
2020-09-22 23:05:25 +02:00
Signature: `factset(channel: String, keyword: String, text: String, meta: String = "action") -> String`
2020-07-23 21:10:33 +02:00
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"` .
2020-07-23 21:10:33 +02:00
The `factset` function returns a `String` containing the value of `text` .
2020-07-23 21:37:34 +02:00
### factappend
2020-07-23 21:10:33 +02:00
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`
2020-07-23 21:10:33 +02:00
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
2020-07-23 21:10:33 +02:00
Use the `userget` function to retrieve user metadata.
2020-09-25 04:34:43 +02:00
Signature: `userget(name: String) -> Map | Null`
2020-09-22 23:05:25 +02:00
2020-07-23 21:10:33 +02:00
The `userget` function takes one parameter: `name` .
The `userget` function returns a `Map` containing all the metadata of the user, or
2020-09-21 08:12:43 +02:00
`null` if there is no user matching `name` .
2020-07-23 21:10:33 +02:00
2020-09-25 22:52:22 +02:00
See the [Plang Map documentation ](https://github.com/pragma-/Plang#maps ) for a refresher on using Plang maps.
2020-07-23 21:10:33 +02:00
2020-09-22 23:05:25 +02:00
## Examples
### Basic examples
2020-07-23 21:10:33 +02:00
< pragma- > !plang userget('pragma-')
2020-07-25 18:31:24 +02:00
< PBot > { channels: "global", hostmasks: "*!*@unaffiliated/pragmatic-chaos", botowner: 1 }
2020-07-23 21:10:33 +02:00
2020-09-22 23:05:25 +02:00
< pragma- > !plang userget('pragma-').botowner
2020-07-23 21:10:33 +02:00
< 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.
2020-09-30 04:49:01 +02:00
< pragma- > !factadd ++ /call plang var karma = Integer(factget('#karma-data', '$arg[0]')); karma += 1; factset('#karma-data', '$arg[0]', String(karma));
< PBot > ++ added to global channel.
Similarly, we add the `--` command.
< pragma- > !factadd -- /call plang var karma = Integer(factget('#karma-data', '$arg[0]')); karma -= 1; factset('#karma-data', '$arg[0]', String(karma));
< PBot > -- added to global channel.
2020-09-30 04:59:44 +02:00
Finally, we add the `karma` command.
2020-09-30 04:49:01 +02:00
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}')
2020-09-30 04:49:01 +02:00
< 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
2020-09-30 04:49:01 +02:00
< pragma- > !karma "this and that"
< PBot > Karma for "this and that": 1