Back to main page

Burlesque - Tutorial

Welcome to the Burlesque cookbook! If you haven't already read Getting Started! then you should do that now!

Understanding Burlesque

Understanding the syntax

The syntax of Burlesque is very easy. The following example shows the basic syntax for values. (From left to right: Int, Double, Character, String, Block)

123 3.14159 'A "ABC" {1 2 3 4 5}

An identifier (you can call it command if you like) is everything else with a length of only two characters. Also keep in mind that spaces are optional.

ps ++

Understanding the stack

Burlesque uses a stack "behind the scene". A stack is a data structure much like a pile (or stack) of books. You can put (push) a book on the pile and you can take away (pop) a book from the top. Every value is automatically pushed in the corresponding order.

1 2 3

This code results in a stack of

3 -- top
2
1 -- bottom
There are commands which support manipulating the stack directly. These are ^^ for duplicating the element on the top, \/ for swapping the two top most elemnts and vv for removing an element from the top.
1 2 3 ^^
Results in a stack of
3 -- top
3
2
1 -- bottom
1 2 3 vv
Results in a stack of
2 -- top
1 -- bottom
and ...
1 2 3 \/
Results in a stack of
2 -- top
3
1 -- bottom

Understanding Blocks

A Block is a list of values. It is also possible for a Block to contain other Blocks as well. Keep in mind that a Burlesque program is just a list of values: It's a Block. A command is actually also just a value (but specially treated by the interpreter). Therefore, a Block can contain commands too.

Understanding Commands

A command that takes two values (takes two arguments) usually pops those, does its thing, and pushes the result back. So doing 1 1 2 .+ .+ results in the following stacks [1],[1,1],[1,1,2],[1,3] and results finally in [4]. What a command actually does depends on which arguments you feed it. .+ on two integers performs an addition but if you feed it other stuff it'll do other stuff!

Arithmetic

Basic arithmetic

You can use Burlesque to do arithmetic for you! It supports addition .+, subtraction .-, multiplication .* division ./ and more. Keep in mind that arithmetic is only defined if applied to two values of the same type. Let's calculate (((1 + 2) * 3) -1) / 2!

1 2 .+ 3 .* 1 .- 2 ./
First we push 1 and 2, add them together, push 3, multiply the previous result with 3, push 1, subtract 1 from the previous result, push 2, divide the previous result by 2. Pretty easy, isn't it?

More arithmetic

Burlesque supports numbers with decimal places too, of course. We call them Doubles.

3.14159 2.0 .*
Calculates 3.14159 * 2.0. Keep in mind that you can't multiply an Int with a Double. Using this and the 'power' command ** we can now calculate the third root of 125.
125.0 1.0 3.0 ./ **
It might surprise you that the result is not 5.0 but 4.99999999~. Sadly, Doubles do not have infinite precision so working with Doubles is always limited to a certain precision with errors. We can workaround that by rounding the number to 6 decimal places using the round command r_.
125.0 1.0 3.0 ./ ** 6 r_

Strings

Strings constist of characters... think of it as 'text'. You can add strings (concatenate) using .+.

"Hello, " "World!" .+
"Hello, World!". You can also do the exact opposite. It's not hard to guess which command you can use for this: It's .-.
 "Hello, World!" "World!" .-
Note: Most commands working on Strings as a list of characters also work with Blocks and vice versa.

Blocks

Basic Block Stuff

As previously mentioned a Block is a list of values (and a Block is therefore also Burlesque code). We can create a Block with some numbers in it add calculate the sum ++ of all numbers in it.

{1 2 3 4} ++
Let's have a look at some Block manipulation commands.
Reverse a Block:
{1 2 3 4} <-
Last element of a Block:
{1 2 3 4} [~
First element of a Block:
{1 2 3 4} -]
All except last element of a Block:
{1 2 3 4} ~]
All except first element of a Block:
{1 2 3 4} [-

Codeblocks

You can treat Blocks as code, but code in a Block does not get automatically evaluated. Luckily there is a command eval e! which does that. Note the difference:

{3 4 .+}
The above code results in the following stack:
 {3 4 .+}
If you eval the code inside the Block:
{3 4 .+} e!
The result will be 7. If you eval it without the .+ the stack looks like:
4 -- top
3 -- bottom

Control flow

If

If you only want to evaluate something based on a condition you can use the Iff if or IfElse ie. Burlesque considers every Integer except 0 to be true. Commonly 1 is used for true and 0 for false. Let's try something like 'if 9 > 6 then multiply by 2'. There are commands for comparision like x > y .>, x < y .< and x = y ==.

9 ^^ 6 .> {2 .*} \/ if
Please note the stack manipulation commands. They are necessary to keep the elements in the right order on the stack. Now let's do 'if 4 > 6 then multiply by 2 else multiply by 3'.
4 ^^ 6 .> {2 .*} \/ {3 .*} \/ ie

While

Burlesque also lets you code loops. A while w! loop is repeated as long as a condition holds true. Let's write something like 'i = 0; while i > 10 { i++; push i }'. That is, we produce the numbers 0 to 10 with 10 at the top of the stack after the loop ends.

0 {^^ \/ 1 .+} {10 .<} w!
A command like .< pops two values, compares them and pushes the result. Therefore you'd expect to loose data while evaluating the while condition. Luckily, that is not the case. Evaluating the while condition does not affect the global stack. It is a continuation!

Continuation

A continuation means, that evaluating something does not affect the global stack. Continuations take a snapshot of the current stack. An example makes this pretty clear.

5 5 ==
Leaves a 1 on the stack and destroyed the two 5. Now:
5 5 {==} c!
Results in a stack of
1
5
5

MapReduce

Map

When it comes to blocks, the map m[ command is very useful. It calls a Block for every element in a Block collecting each result in a new Block.

{1 2 3} {+.} m[
This increments every Integer in the Block.

Reduce

Reduce r[ is a little bit more complicated. But don't worry. Let's say you have a List {1 2 3} and want to do 1*2*3. Or a list {1 2 3} and want to do 1+2+3. That's were reduce can help you! The following example calculates 1*2*3:

{1 2 3} {.*} r[
Using this and the range command r@ we can calculate factorial (of 4 in this case):
1 4 r@ {.*} r[

Concatenative?

You can think of every Burlesque program as a chain of functions which take a Stack as input and return a new stack. You can think of any value as a function too. (The function 3 takes the stack as input and returns a new stack by pushing 3 to it). You can write every Burlesque program in a style of 'data commands'. That means, all the data is at the front and all commands follow it. There is no data between commands. The program 1 2 .+ 3 .* 1 .- 2 ./ can also be written as 2 1 3 2 1 .+ .* \/ .- \/ ./ although usually this style is much more unreadable and more complicated than necessary.

Where to go from here?

Now you're ready to read the language reference.