Plugins

You can easily extends python-droit using plugins. They define custom input and output sub-rules. If you don't know what a rule or sub-rule is I recommend to read the Introduction to Droit v1.1 first.

What's the job of a plugin?

Sub-rules are evaluated by plugins. [Some standard plugins] are always included in the python-droit plugin folder. As you can write your own plugins or download plugins other people made you are able to [extend the sub-rules]. The name of the folder a plugin is located in specifies the name of the input sub-rule respectively the name of the output plugin.

Where are plugins located?

Usually plugins are located within the droit/plugins/input or droit/plugins/output folder. The folder structure looks like this:

plugins
----- input
----- ----- inp
----- ----- ----- main.py
----- ----- ----- info.json
----- ----- srtx
----- ----- ----- main.py
----- ----- ----- info.json
----- ----- simt
----- ----- ----- main.py
----- ----- ----- info.json
----- ----- text
----- ----- ----- main.py
----- ----- ----- req.py
----- ----- ----- info.json
----- output
----- ----- text
----- ----- ----- main.py
----- ----- var
----- ----- ----- main.py
----- ----- eval.rand
----- ----- ----- main.py

You can load plugins from any folder by using the db.loadPlugins(location='path/to/plugins/folder/').

Any folder containing plugins must be called plugins and contain the sub-folders input and output. Each plugin has it's own folder which defines the plugins name. Each plugin folder has to contain a file called main.py.

Input plugins have to include an info.json file which defines some behavior. Example:

{"name":"INP","description":"Stores a word or multiple words into a variable","attributes":{"var":true}}

The parameter attributes contains all possible attributes the sub-rule supports. The value true tells python-droit that the attribute has to exist. If it is optional you would use false.

If you want to read the code of some example plugins just have a look at the standard plugins that come with python-droit.

Writing an input plugin

Let's have a look at the SRTX input plugin. The SRTX sub-rule checks whether one of the given values is equal to the user-input.

# main.py - plugins.input - SRTX plugin for python-droit

def block(userinput, iN, block, db):
	passRule = False
	variables = []
	rankMod = 2

	inputRules = db.rules[iN].input

	if(len(inputRules) == 1 and inputRules[0].tag == block):
		if(userinput.simpleInput in inputRules[0].children):
			passRule = True
	
	return passRule, variables, rankMod, db

When running an input sub-rule the function block() from main.py at plugins/input/nameofsubrule will be called. The function block always takes four parameter:

• userinput (a DroitUserinput object)
• ruleIndex (index of currently active rule in db.rules)
• block (the name of this block)
• db (a droit.Database object)

How does this plugin work?
At first there is an if-statement which checks whether there is only one input sub-rule in the current rule and whether this sub-rule is SRTX. In the second if-statement it checks whether the raw user-input is included in the values of the sub-rule. If so the variable passRule is set to True.

passRule is a boolean variable and the first one of the tuple of three variables to be returned by the block() function. When it is set to True it tells Droit that the condition of this sub-rules is met. If the sub-rule is used more than one time in a rule the function block() has to check whether the condition of every sub-rule of it's type is met. To do so you can use a loop scanning each item of inputRules.

variables is a list of variables that were read in by the sub-rule. The INP sub-rule e.g. uses it. In this example an empty list is returned.

rankMod specifies how relevant the plugin is. Usually it is set to zero. The higher rankMod is the more likely a rule is to be used for output.

Writing an output plugin

Output plugins work different due to the fact that their task is different. There are two types of output-plugins. While input plugins check whether the user-input meets some conditions the output plugins produce some kind of output. This can be anything from returning some text to sending an email. We will now have a look at the rand plugin. It makes it possible to return one of several strings chosen randomly.

# main.py - plugins.output - eval.rand plugin for python-droit
import random

def text(data, db):
    rint = random.randint(0, len(data) - 1)
    return data[rint], db

Here is an example of how to use this plugin:

SRTX!whats you name->EVAL!rand.text("my name is droit","i'm droit")

Output plugins can contain multiple functions. Any function from main.py can be called using the EVAL sub-rule: EVAL!plugin.function(param1,param2,...)
Any function that can be called like this has the parameters data and db and returns a string.
data is a list containing all given parameters. Parameters are either a variable or a string.
db is a droit.Database object.
The string which is returned will be appended to the output string returned by formatOut().