Your own commands

Naming a job

So far every example has been a list of lines that run once, top to bottom. As soon as a program does the same job twice, you want to give the job a name and write its lines once. In xTalk a named job is a handler, and the simplest kind is a command.

A command handler starts with on and its name, and ends with end and the same name. To run it, write its name as a line of its own, just like put or add:

on countDown
   repeat with i = 3 down to 1
      put i
   end repeat
   put "Lift off!"
end countDown

countDown
countDown

3
2
1
Lift off!
3
2
1
Lift off!

Writing the handler does nothing by itself; it only teaches xTalk a new word. The lines run each time something calls it, here twice.

Handing it values: parameters

A command becomes far more useful when you can tell it what to work on. List names after the handler's name, separated by commas: these are its parameters. When you call it, put the values after the command's name in the same order, and each parameter holds one of them while the handler runs.

on greet pName, pGreeting
   if pGreeting is empty then put "Hello" into pGreeting
   put pGreeting & "," && pName & "!"
end greet

greet "Ada"
greet "Grace", "Good morning"

Hello, Ada!
Good morning, Grace!

A parameter you leave out is simply empty, so a handler can give it a sensible value of its own, as greet does. Many xTalk programmers start parameter names with p, so that you can tell at a glance which values came in from outside.

Any number of values

A handler can also take as many values as you care to give it. the paramCount says how many came, and param(n) gives the n-th one, whether or not it has a name.

on showAll
   repeat with i = 1 to the paramCount
      put i & ":" && param(i)
   end repeat
end showAll

showAll "red", "green", "blue"

1: red
2: green
3: blue

Getting an answer back

A command can report back with return. The value does not appear where you called it; it goes into the result, which you read on the very next line, before anything else changes it. The usual habit is to return empty when all went well and a message when something did not:

command checkAge pAge
   if pAge < 0 then return "An age cannot be negative"
   return empty
end checkAge

checkAge -3
put the result
checkAge 30
put the result is empty

An age cannot be negative
true

Here the handler starts with command rather than on. The two mean the same thing; some people use command for handlers they call themselves and keep on for messages like mouseUp that xTalk sends.

Stopping early

return also ends the handler at once. When there is nothing to report, exit followed by the handler's name does the same:

on describe pNumber
   if pNumber > 100 then
      put pNumber && "is too big to describe"
      exit describe
   end if
   put pNumber && "has" && the number of chars of pNumber && "digits"
end describe

describe 42
describe 5000

42 has 2 digits
5000 is too big to describe

Parameters are copies

A parameter holds a copy of the value you passed. Changing it inside the handler does not change the variable you called it with:

on double pN
   multiply pN by 2
   put "inside:" && pN
end double

put 5 into tN
double tN
put "outside:" && tN

inside: 10
outside: 5

That is almost always what you want: a handler cannot spoil your variables by accident. When you really do want a handler to change one, put @ before the parameter's name. The parameter then is the caller's variable, not a copy:

on addTax @pPrice
   multiply pPrice by 1.2
end addTax

put 10 into tCost
addTax tCost
put tCost

12

A name xTalk does not know

If you call a command that has no handler anywhere, perhaps because of a typing slip, xTalk stops and says so:

greet "Ada"

The playground tells you it does not know a command called greet: the handler is missing from the code you ran.

on drawLine pChar, pCount
   if pCount is empty then put 10 into pCount
   put empty into tLine
   repeat pCount times
      put pChar after tLine
   end repeat
   put tLine
end drawLine

drawLine "*", 5
drawLine "="

*****
==========