Time for Action

Less talk more action

Throughout this tutorial we’ve used lots of actions to do everything from reading text to drawing shapes.

But, we don’t always have to depend on the actions that come with Setanta, we can make our own!

Gníomh Statements

To make our own action we use the gníomh keyword. “gníomh”, unsurprisingly translates as “action”. We define the name of our action, what arguments it takes and the code to execute when we call the action. We’ll see how to make your action have a result later.

The syntax for a gníomh statement is:

gníomh <action name> ( <list of argument names> ) {
    <action code>
}

Writing a gníomh statement like this creates a new action with the name we supplied. When you call the action with some arguments, the arguments are assigned to variables with the names we gave in the <list of argument names>, then the code between the curly braces { } is executed. (This code is called the body of the action).

Here is a quick example: Let’s make an action called say_hello, say_hello will take no arguments, and write “Hey” on the console.

gníomh say_hello() {
    scríobh("Hey")
}

As you can see we have filled in say_hello as the action name, the list of arguments is empty, and the body of the action is scríobh("Hey").

We call this new action with say_hello(). Let’s try it out!

As you can see, calling say_hello() caused “Hey” to be written on the console! What’s going on here?

Arguments

How do we make actions that take arguments? You do this by picking names for your arguments, and then when the action is called the argument values are attached to variables with those names.

Let’s write an action to draw a blue circle in the middle of the screen, with the radius given as an argument. We’ll call the action mid_circle.

Let’s start with some code to draw a circle in the middle with radius 100, and we’ll see how to change this to be an argument after.

We use fad_x@stáitse and fad_y@stáitse to get the midpoints and use ciorcal@stáitse to draw the circle.

gníomh mid_circle() {
    >-- Change to blue
    dath@stáitse("gorm")

    >-- Get midpoint
    mid_x := fad_x@stáitse / 2
    mid_y := fad_y@stáitse / 2

    >-- Draw the circle
    ciorcal@stáitse(mid_x, mid_y, 100)
}

We call this with mid_circle(), try it out:

Now we want to get rid of that fixed radius of 100, and replace it with an argument. Let’s call the argument radius. We place the name of the argument between the brackets ( ) in the defining line of the action:

gníomh mid_circle(radius) {
    dath@stáitse("gorm")
    mid_x := fad_x@stáitse / 2
    mid_y := fad_y@stáitse / 2
    ciorcal@stáitse(mid_x, mid_y, 100)
}

Inside the action we can now refer to the name radius anywhere we’d like to use the argument. So let’s replace the 100 value with radius.

gníomh mid_circle(radius) {
    dath@stáitse("gorm")
    mid_x := fad_x@stáitse / 2
    mid_y := fad_y@stáitse / 2
    ciorcal@stáitse(mid_x, mid_y, radius)
}

Now we can call mid_circle with one argument and it’ll draw the circle for us, let’s try calling it with 200 (mid_circle(200)).

Now we can use our mid_circle action as many times as we want, and we don’t need to write out all that code again.

But now, what if we want to be able to change the colour of the circle too? All we have to do is add a new argument, let’s call it “colour”, and we can use that argument instead of “gorm” for the colour. To add a new argument we can put it in between the brackets after the existing argument “radius”. We use a comma to separate the two arguments. Here is our new code:

gníomh mid_circle(radius, colour) {
    dath@stáitse(colour)
    mid_x := fad_x@stáitse / 2
    mid_y := fad_y@stáitse / 2
    ciorcal@stáitse(mid_x, mid_y, radius)
}

To call this new action we have to supply two arguments, the radius and the colour. Lets change our previous code to draw a blue, green and red circle.

Results

Now that we’ve seen how to make our own actions, we can see how to make our actions have results.

We will use the keyword “toradh”, meaning “result”

The syntax for a toradh statement is simple. It’s just:

toradh < expression >

To set a value as the result of the action (called “returning” the value), you simply put toradh in front of the value.

For example, “toradh 1”, “toradh ["a", "b", "c"]”.

When the Setanta interpreter reads a toradh statement, it stops executing the action immediately, and returns the given value.

gníomh return_1() {
    toradh 1
}