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 vs Droit Database Script

Droit Database Script is easier to write. Droit Database Script files are only about half the file size of Droit XML files. However XML is a standardized file format whereas Droit Database Script was created only for the use with Droit. Extending Droit XML is also a lot easier while adding parameters to Droit Database Script rules is very hard. The parsing algorithm has to be edited each time while XML has the opportunity of inserting parameters into a tag.

Which one should I learn?
Both. They are working quite similar and if you have worked with markup languages it will be easy for you to switch from Droit Database Script to Droit XML.

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

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!
TEXT!i:INP*verb!like,love:TEXT!you:NOTX!dont,not->TEXT!I :VAR!inp.verb: you too!

Droit XML

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>

You will now understand the disadvantages of Droit XML: it is harder to read and write. But there are also some advantages. 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".