Lua programming with DRAKON Editor

Home | Download

This is a short tutorial of using Lua together with DRAKON for building real programs. Please note that the minimum supported Lua version is 5.2.

Download the source code for the tutorial: hello_lua.drn.

A more advanced tutorial can be found in examples/Lua folder in the DRAKON Editor .zip file.

The basics
Flow control
- Flow control with If
- Control flow with Select
Loops
Commenting out diagrams

Hello, world

Create a new file with DRAKON Editor.
Select Lua as the programming language. In the main menu, go to File / File properties... and select Lua in the Language combobox:
Create a new diagram called Hello:
Add your own code. In the main menu, go to File / File description... and add the following text:

=== footer ===
Hello()
Generate the source code. In the main menu, go to DRAKON / Generate code or just press Ctrl-B (Command-B on Mac).

DRAKON Editor will create a new .lua file and put it next to the .drn file. The Lua code will be something like this:

function Hello()
    print("Hello, world!") 
end

Hello()

Formal parameters

The formal parameters of the function are placed in the special Parameters icon, to the right from the Begin icon.

How to create a Parameters icon:

Add a new Action icon and put it next to the right side of the Begin icon.
Connect the Begin icon with the new Action icon with a horizontal line.
Add parameters, one parameter per line.

DRAKON Editor will generate the following code for the diagram:

function DoubleHello(firstGreeting, secondGreeting)
    print(firstGreeting)
    print(secondGreeting) 
end

Note the item comments in the generated code. They tell which icon on the diagram the next piece of code is generated from.

To jump to the specific icon if you know its number, press Ctrl-I and enter the number. This is really convenient for debugging.

Adding your own code to the generated source file

Sometimes it is necessary to add some hand-written code to the generated file. DRAKON Editor allows you to do that using the so called sections in the file description.

To edit the file description, go to File / File description...

The header section is added at the beginning of the generated file:

=== header ===
print("this code is put at the top")
print("there can be several lines")

The footer section is added at the end of the generated file:

=== footer ===
print("this code is put at the bottom")
print("this is the last line")

We were using the footer section in the Hello example above to actually run the function we created.

The section content is all text below the section header until the next section of end of file.

The text in the file description that goes before any sections is ignored.

Flow control with If

The If icon produces the if statement:

The If icon in the diagram above produces this code:

if length <= maxLength then
    print("The text is short enough.")
    print("I can print it:")
    print(text)
else
    print("The text is too long.")
end

Important! The left and the right branches of an If icon are not equal in DRAKON.

Rule: the further to the right, the worse.

It means that the happy path should go straight down. If we have an If icon and one of the outcomes is worse than the other, the worst one must go to the right.

It is possible to swap YES and NO exits of an if icon. Right-click on the if icon and choose Swap YES and NO.

Control flow with Select

Imagine you need to make a choice out of several options based on some value. In other words, there is a question that has several answers.

In Lua, you would write something like this:

function NumberToString(number)
    if number == 0 then
        print("zero")
    elseif number == 1 then
        print("one")
    elseif number == 2 then
        print("two")
    else
        print("a lot")
    end    
end

In DRAKON, you can use the Select and Case icons like this:

Loops with Arrow

When an Arrow is added to an If or Select, a loop is created.

Do-Check loop:
Check-Do loop:
Do-Check-Do (hybrid) loop:

Foreach loop

function PrintStrings(strings)
    for i, item in pairs(strings) do
        print(item)
    end
end

The DRAKON equivalent for the Lua code above is:

Note that the keyword foreach is used instead of the standard for Lua keyword. Another syntax difference is a semicolon instead of the in keyword. This foreach syntax is standard between all languages that DRAKON Editor supports.