pbot/doc/Plugins/Plang.md

Plang

• About
• The Plang Language
• plang command
• plangrepl command
• PBot built-in Plang functions
  • factget
  • factset
  • factappend
  • userget

About

The 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. 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 language, see the Plang documentation.

plang command

Use the plang command to run a Plang script.

Usage: plang <code>

plangrepl command

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 lets you add custom built-in functions. 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.

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: String, keyword: String, text: String) -> String

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: String, keyword: String, text: String) -> String

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: String) -> Map

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 null if there is no user matching name.

See the Plang Map documentation 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

<pragma-> !plang if userget('pragma-')['botowner'] then print('Greetings master!') else print('Hello mortal.')
   <PBot> Greetings master!