Tcl programming with DRAKON Editor

Hello, world

1. Create a new file with DRAKON Editor.

2. Select Tcl as the programming language. In the main menu, go to File / File properties... and choose "Tcl".

3. Create a new diagram called Hello:

   

4. Add your own code. In the main menu, go to File / File description... and add the following text:

   === footer ===
   Hello

5. 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 .tcl file and put it next to the .drn file. The Tcl code will be something like this:

proc Hello { } {
        #item 16
    puts "Hello, world!"
    return {}
}

Hello

Formal parameters

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

How to create a Parameters icon:

1. Add a new Action icon and put it next to the right side of the Begin icon.

2. Connect the Begin icon with the new Action icon with a horizontal line.

3. Add parameters, one parameter per line.

   

DRAKON Editor will generate the following code for the diagram:

proc DoubleHello { firstGreeting secondGreeting } {
        #item 22
    puts $firstGreeting
    #item 23
    puts $secondGreeting
    return {}
}

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 ===
puts "this code is put at the top"
puts "there can be several lines"

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

=== footer ===
puts "this code is put at the bottom"
puts "this is the last line"

We were using the footer section in the Hello example above to actually run the procedure 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:

#item 30
if {$length <= $maxLength} {
    #item 31
    puts "The text is short enough."
    puts "I can print it:"
    puts $text
    return {}
} else {
    #item 34
    puts "The text is too long."
    return {}
}

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 Tcl, you would write something like this:

if {$number == 0} {
    puts "zero"
} elseif {$number == 1} {
    puts "one"
} elseif {$number == 2} {
    puts "two"
} else {
    puts "a lot"
}

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.

1. Do-Check loop:

   

2. Check-Do loop:

   

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

   

Foreach loop

proc PrintStrings { strings } {
    foreach item $strings {
        puts $item
    }
}

The DRAKON equivalent for the Tcl code above is:

Note that the keyword foreach and the loop variable are followed by a semicolon (;) which is unusual for Tcl.

C-style loop

With DRAKON, it is possible to write C-style for constructs:

Which is a syntactically sugared version of the below picture:

Commenting out diagrams

It is possible to exclude the whole diagram from code generation.

If the first line of the formal parameters list is
#comment
then no code is generated for this diagram.

Its correctness, however, will still be checked against the DRAKON rules.