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!

Quick revision

Actions are things like scríobh and coladh. Actions take arguments and use them to perform some action.

You call an action by using brackets ( ) and placing the arguments inside the brackets.

e.g: scríobh("Dia duit"), ciorcal@stáitse(100, 100, 100), léigh()

Some actions also have results that can be used like any other value

e.g: aois := ceist("Cén aois thú")

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?

Explanation

When Setanta reads an action call like say_hello, it jumps to where you defined the action and executes the code you wrote. So when you call say_hello(), it jumps to the code in the say_hello action, which was scríobh("Hey") and runs it, causing “Hey” to be written on the console.

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) {
    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) {
    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.

More than one argument

You can expand the list of arguments to take as many arguments as you like by separating the names of the variables with commas (,).

e.g. gníomh i_need_3_args(arg_1, arg_2, arg_3) {}

Challenge

Create an action called rand_circs that takes 3 arguments n, radius and colour, that draws n random circles with radius radius and colour colour on the stage.

Click here to see a solution

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.

Simple example

Here’s an action called return_1 that just returns 1 as it’s result, and doesn’t do anything else.

gníomh return_1() {
    toradh 1
}

Look what happens when we call scríobh(return_1())

“1” is written on the console, this is because 1 was the result of the call to return_1().

Important note

It’s important to note that when a toradh statement is reached, the execution of the action is stopped, and the result is returned immediately.

If we add scríobh("Setanta is fun") after the toradh statement in our return_1 action, we can see that it will not be called:

As you can see, "Setanta is fun" is not written on the console. This is because the scríobh call was never reached.

Challenge

Try and create an action called max_3 that takes in 3 arguments, a, b and c and returns the biggest of the 3.

For example the result of max_3(10, 20, 30) should be 30.

Click here to see a full answer.