Droit Databases

To build a bot using Droit you will need a database containing rules. Currently there are two types of databases supported:
Droit XML and Droit Database Script

Droit XML was introduced at version 1.0 whereas the Droit Database Script was used in the 0.x version. They will both stay supported and are mostly compatible. python-droit comes with some tools to convert the databases from Droit Database Script to Droit XML as there is parsing as well as dumping functionality.

Droit XML

Droit XML was introduced with Droit v1.0 and will be removed at Droit v1.1. As XML is a standardized format python comes with a fast C parsing algorithm for XML which was faster than the Droit Database Script parsing algorithm. Due to improvements of the Droit Database Script parsing algorithm in version 1.1 parsing Droit Database Script will be much faster which means the profits of Droit XML are gone so far. Droit Database Script is a lot easier to read and write and produces much smaller files.

Droit Databases

Droit XML and Droit Database Script are Droit Databases. They contain a list of "rules". Each rule has input sub-rules and output sub-rules. The input sub-rules determine what user-inputs the rule fits to. If a user-input fits to the input sub-rules the rule will be selected by python-droit. Usually the best fitting rule will be use for the output. Therefore the output sub-rules of this rule will be evaluated.

Example rule:

• rule
  • input sub-rules
    • If the user-input contains "i"
    • If the user-input contains "am"
    • And there is a another word which has to be read in as variable "name"
  • output sub-rules
    • return the text "hi "
    • and append the variable "name"

When the user-input was I am max this rule would generate the output hi max.

Droit Database Script

The example rule above would look like this in Droit Database Script:

TEXT!i:TEXT!am:INP*name!->TEXT!Hi :VAR!inp.name

At first this looks complicated but actually it isn't. There are simple rules you have to follow to write the script.

1. Each line is a new rule.
2. Input and output sub-rules are separated by ->.
3. Sub-rules are separated by a colon.
4. The name of a sub-rule and it's value are separated by an exclamation mark.
5. The name of a sub-rule is written in uppercase letters.
6. Values of sub-rules are written in lowercase letters - bots are not case sensitive.
7. Value of sub-rules are comma-separated.
8. When using as a value of a sub-rule, exclamation marks are represented by &arz; and colons by &dpp;
9. Blocks that declare a variable specified the variable name after an asterisk.
10. Lines without -> are ignored and considered as comments

Input sub-rules

TEXT

One of the words that are given as values must be included in the user-input.
Usage: TEXT!word1,word2,word3

NOTX

None of the words that are given as values may be included in the user-input. This is mainly used to recognize and avoid negations.
Usage: NOTX!no,not

SRTX

One of the sentences given as values must be equal to the user-input. This block cannot be combined with other blocks.
Usage: SRTX!This is an example,another example

INP

Placeholder for words that follow the last TEXT sub-rule. Values are optional - if given, they limit the possible words to be read in.
Usage: INP*varname! or: INP*day!monday,tuesday,wednesday,thursday,friday

SIMT

One of the sentences given as values must be similar by a specific percentage to the user-input. This block cannot be combined with other blocks.
Usage: SIMT*85!how are you,whats up (will e.g accept "hw are you")

Output sub-rules

TEXT

Returns the text given as value. If you want to use exclamation marks or colons, you have to use &arz; and &dpp; instead.
Usage: TEXT!Here goes some text

VAR

Returns the value of a variable. Most of the time you will access variables that were defined with the INP input sub-rule via inp.varname. Other common variables are global.username, global.date and global.time.
Usage: VAR!type.varname

EVAL

Using this sub-rule you can access output plugins. You can pass variables that were defined using the INP input sub-rule.
Usage: EVAL!plugin.function (*varname1,*varname2,...)

More sub-rules

Sub-rules are evaluated by plugins. The rules sub-rules described above 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 use those 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.

Examples

SRTX!how are you->TEXT!I'm fine.
TEXT!I:TEXT!am:INP*name!->TEXT!Hi :VAR!inp.name
TEXT!calulate,calc:INP*term!->VAR!term:TEXT! = :EVAL!math.calc(*inp.term)
TEXT!i:TEXT!like,love:TEXT!you:NOTX!dont,not->TEXT!I like you too&arz;
TEXT!i:INP*verb!like,love:TEXT!you:NOTX!dont,not->TEXT!I :VAR!inp.verb:TEXT! you too&arz;

Droit XML

Please note that Droit XML will be removed in Droit v1.1! Droit XML follows the XML Syntax Rules. The Droit Database Script above would look like this in Droit XML:

<?xml version="1.0" ?>
<droitdb>
  <droitxml>
    <rule>
      <input>
        <SRTX>
          <item>how are you</item>
        </SRTX>
      </input>
      <output>
        <TEXT>
          <item>I'm fine.</item>
        </TEXT>
      </output>
    </rule>
    <rule>
      <input>
        <TEXT>
          <item>i</item>
        </TEXT>
        <TEXT>
          <item>am</item>
        </TEXT>
        <INP var="name">
          <item/>
        </INP>
      </input>
      <output>
        <TEXT>
          <item>Hi </item>
        </TEXT>
        <VAR>
          <item>inp.name</item>
        </VAR>
      </output>
    </rule>
    <rule>
      <input>
        <TEXT>
          <item>calulate</item>
          <item>calc</item>
        </TEXT>
        <INP var="term">
          <item/>
        </INP>
      </input>
      <output>
        <VAR>
          <item>term</item>
        </VAR>
        <TEXT>
          <item> = </item>
        </TEXT>
        <EVAL>
          <item>math.calc(*inp.term)</item>
        </EVAL>
      </output>
    </rule>
    <rule>
      <input>
        <TEXT>
          <item>i</item>
        </TEXT>
        <TEXT>
          <item>like</item>
          <item>love</item>
        </TEXT>
        <TEXT>
          <item>you</item>
        </TEXT>
        <TEXT not="true">
          <item>dont</item>
          <item>not</item>
        </TEXT>
      </input>
      <output>
        <TEXT>
          <item>I like you too</item>
        </TEXT>
      </output>
    </rule>
  </droitxml>
</droitdb>

Here are some differences between Droit XML and Droit Database Script.

Droit XML doesn't have a NOTX sub-rule. Instead you can pass the optional parameter not="true" which makes the TEXT sub-rule act like the NOTX sub-rule.
The name of a variable isn't defined after an asterisk but as the parameter var="varname".