Like many people, I enjoy taking something and experimenting with it before going and reading the instructions! With this in mind, I have written a brief tutorial that you can use to start exploring Hecl on your own.

To launch the interactive Hecl shell:

java -jar ./jars/j2se/Hecl.jar

This will give you a prompt: hecl> where you can type in commands.

Of course, we would be out of place not to begin with the famous "Hello, World". Behold:

puts "Hello, World"

Hecl is based on the notion of commands, which take any number of arguments. The puts command takes one argument, a string, and prints it out.

Like all programming languages, Hecl provides variables that may be used to store information. Here, we set a variable, rating, and then print it out in the midst of a string. This is called "interpolation", and is a convenient way of creating new strings.

set rating 10
puts "Hecl, from 1 to 10: $rating"

Something else we notice in the above examples is that we use double quotes "" to group a series of things. In Hecl, commands and their arguments are separated by spaces. Since puts only takes one argument, a string, we use the quotes to group several words together in order to pass them as one string to the command. Many languages require quotes to delineate a string, but in Hecl that is not necessary if the string has no spaces in it. For instance, puts helloworld is legitimate.

Something else visible in the above command is that Hecl commands occur one per line, and that no line ending is necessary, as in languages like C where lines end in a semicolon. In Hecl, the semicolon is optional, and can be used to put more than one command on a line:

puts "hello" ; puts "world" 

Another way of grouping multiple words in Hecl is with braces: {}. Hecl does not automatically perform any substitution on the variables or commands grouped within braces, as it does with quotes.

puts {The $dollar $signs $are printed	    literally$$ - no substitution}

Aside from the dollar sign, which returns a reference to the value of a variable, it is also possible to utilize the results of one command as the input of a second command. For example:

set rating 10
puts "Rating:"
puts [set rating]

In this case, we pass the results of the set command to the puts command. In reality, set rating is just a long way of writing $rating but it's a good example.

Like everything else in Hecl, we perform math operations as commands:

puts "2 + 2 = [+ 2 2]"

In the example, the + takes two arguments, adds them together and return the result, which is then printed out by the puts command.

In order to choose between one or more

set temp 10
if { < $temp 0 } {
    puts "It's freezing"
} else {
    puts "Not freezing"
}

"while" loop command:

set i 0
while { < $i 10 } {
    puts "i is now $i"
    incr $i
}

Lists:

set foo [list a b c]
set bar {a b c}
lappend $foo d
lappend $bar d
set foo
# Returns 'a b c d'
set bar
# Returns 'a b c d'

Hash tables:

set foo [hash {a b c d}]
puts [hget $foo a]
# prints 'b'
puts [hget $foo c]
# prints 'd'
hset $foo c 2
puts [hget $foo c]
# prints '2'
puts $foo
# prints 'a b c 2' (although not necessarily in that order)

"foreach" loop command:

set lst {a b c d e f}
foreach {m n} $lst {
    puts  "It is possible to grab two variables at a time: $m $n"
}

foreach {x} $lst {
    puts  "Or one at a time: $x"
}

Create new commands with the "proc" command. In this example we create a command that prints out a numbered list. In Hecl, commands created within procs normally are only visible within that proc, and are cleaned up when the procedure exits. For exceptions to this rule, see the global and upeval commands.

set list {red blue green}
proc printvals {vals} {
    set num 1
    foreach v $vals {
	puts "$num - $v"
	incr $num
    }
}

printvals $list

Hecl is very flexible - in this example, we create a "do...while" loop command that works as if it were a native loop construct.

proc do {code while condition} {
    upeval $code
    while { upeval $condition } {
	upeval $code
    }
}

set x 100
set foo ""
do {
    append $foo $x
    incr $x
} while { < $x 10 }
set foo
# Returns 100 - because the loop is run once and only once.