The Handler Rule

The eponymous handler

What I call "the handler rule" has to do with the relationship between a script and its "eponymous handler."

A script's eponymous handler is the "on" line defining the verb whose name is the same as that of the script object itself -- for example, in workspace.Counter, the line "on Counter ()" introduces the script's eponymous handler, because the script and the handler are both called Counter.

The handler rule comes in two parts:

The Handler Rule, Part 1

A script doesn't have to have an eponymous handler at all just in case the verb it defines takes no parameters.

Well, our verb Counter does take parameters. Back when it didn't, though, we could have foregone the "on" line and the final calling line altogether.

Our script, workspace.Counter, could have looked like this:

for n = 1 to 10
   msg (n)
   clock.waitseconds (1)

This would have worked when we pressed the Run button, and it would have worked when we called workspace.Counter () from another script, such as workspace.CounterCaller.

Now that Counter does take parameters, though, we are required to use the form we are presently using, with an eponymous handler in the script.

We can, however, rewrite workspace.CounterCaller to have no eponymous handler; just make it consist of one single line, like this:

workspace.Counter (10, 7)

Press the Run button. Sure enough, CounterCaller calls Counter, as before, counting down from 10 to 7.

The Handler Rule, Part 2

When you press a script's Run button, the top-level commands in the script execute.

But when, from one script, you call another script that has an eponymous handler, it is the eponymous handler that executes; the top-level commands of the called script are ignored.

Part 2 of the handler rule says that when, in CounterCaller, we call workspace.Counter (), Frontier will jump right into the Counter handler as defined in the "on" line of Counter; the last line of the Counter script, which is at top level (it is outdented as far to the left as it can be), will be ignored.

To confirm this, change the last line of workspace.Counter to this:

Counter (1, 3)

Press the Run button, and Counter counts from 1 to 3. Now go into CounterCaller and press the Run button; Counter counts from 10 down to 7. The last line of workspace.Counter is being ignored.

This way of doing things has great advantages when you want to test a verb you're in the process of creating.

If your script contains an eponymous handler, the script can contain the verb itself (the eponymous handler) plus anything else you care to put into the script.

This "anything else" can be a test, or series of tests, designed to make sure that your verb works correctly.

To see that this is so, let's modify workspace.Counter so that it allows us to test Counter for any parameters we care to supply. Change workspace.Counter so that it looks like this:

on Counter (lowerLimit = 1, upperLimit = 10)
   if lowerLimit < upperLimit
      for n = lowerLimit to upperLimit
         msg (n)
         clock.waitseconds (1)
   else
      for n = lowerLimit downto upperLimit
         msg (n)
         clock.waitseconds (1)
if dialog.getInt("Count from?", @fromWhat)\ 
   and dialog.getInt("Count to?", @toWhat)
   window.about ()
   Counter(fromWhat, toWhat)

Run this by pressing the Run button. You can see that we've created a testing interface, which puts up dialogs to let us enter numbers to count from and to, and then tells Counter to count.

Play with it for a while, pressing the Run button and supplying various numbers. Now go to workspace.CounterCaller and press the Run button. The dialogs never appear; Counter just counts from 10 down to 7, because that's how CounterCaller calls it.

In workspace.Counter, the "if...and" lines we created are at the top level (and the next two lines are indented below them, so they are part of the "if"); hence these are not executed when we call Counter from another script. They are executed only when we press the Run button within workspace.Counter itself.

A testing milieu such as we have just created for Counter is called a stub, and one of the nice features of Frontier is that it makes it easy to write stubs without their getting in the way of the basic functionality of the verb you're developing.

Introducing...

In the stub we've just written, several interesting features of Frontier were introduced. We used a couple of verbs, dialog.getInt and window.about, which represent classes of verb (dialog verbs and window verbs) capable of controlling interface elements of the Frontier environment as a whole.

Indeed, from a script, you can make Frontier do just about anything you could do manually, and more besides. This tutorial won't go into much detail about such verbs; it's not hard to learn more about them later on from the documentation.

We also split a single line into two by ending the first with the backslash character. It would have been equivalent to put the whole "if" expression on a single line, but as lines get long in a script they can get hard to read, so it is convenient to be able to split them in this way.

Also, we used the "@" character. This is explained in the next chapter.