Parameters and Results

While each message (for more information see Messages) is identified by a single word—the message name—it can also include additional information in the form of parameters. Parameters are values that are passed to commands or functions. The command put "Hello, World!" sends the string “Hello, World!” as a single parameter along with the "put" message. To send more than one parameter, just list them with commas in between:

doSomethingImportant 31,"green", style

The example above passes 3 parameters to the doSomethingImportant command: the number 31, the text green, and the variable style.

Important: Command parameters should not be enclosed in parentheses (unless the intent is to pass a list as a single parameter).

To include parameters with a function call message, list them inside the parentheses after the function name:

put roundToNearest(salary/12, 0.01) into monthlyPayTothePenny

Two commas in a row imply an empty parameter, and a final comma at the end of a list is ignored, so the following passes 3 parameters ("silverBar", "", and 16):

get verifyQuantity("silverBar",,16,)

When passing a variable as a parameter, only its value is passed, so the local variable’s contents cannot be changed, unless it is passed by reference, as described in References to Containers.

Instead of passing individual parameters, you can pass all of the values contained in a list by specifying as parameters. This will pass the values individually, rather than passing the list as a single entity:

updateAllItems thingsToBeUpdated as parameters

As a convenience, when passing a single property list as a parameter, it is not necessary to enclose the property list in parentheses. This gives the effect of passing parameters by name:

addToInventory item:"candles", quantity:6,color:"Blue"

set article to fetchClipping(author:"Lewis", title:"Lost")

The parameters are actually passed as a single property list when one of these forms is used.

Named and unnamed parameters can be combined in a single call, provided that the named parameters come last. The named parameters are sent as a property list which is passed as the last parameter:

addAtPosition 23, item:"paper", quantity:500, color:"White"

A list of values can be passed as individual parameters, by specifying as parameters after the list:

calculateVariance bigListOfNumbers as parameters

This can be especially useful for passing along the list of parameters received by the current handler:

return otherFunction(parameterList() as parameters)

A handler can declare and use the parameters it receives, and supply results, as described below.

Parameters Passed as Containers (by Reference)

Sometimes it is useful for a handler to be able to change one or more of the values in the calling script. In SenseTalk, this can only be done if the calling script allows it, by passing one or more parameters "by reference" or as "containers" (see the description of References to Containers for more details). To illustrate, here is a very simple command handler that swaps two values:

on swapValues a,b

put a into temp

put b into a

put temp into b

end swapValues

If called in the usual way, this command would have no effect in the calling script:

swapValues x,y -- This command leaves x and y unchanged

If the calling script explicitly passes its parameters as containers, though, their values can be changed:

swapValues container x, container y -- This swaps the values in x and y

Returning Results

A function handler will return a value to the calling script, which is used as the value of the function call expression. If a function handler does not explicitly return a value, its return value will simply be empty. Usually, though, the reason to have a function is to provide a value, so function handlers most often end with a return statement. A return statement must include one parameter—the value to be returned (which might be an expression). If needed, multiple values can be returned as a list, as shown here:

return (min(source), max(source), average(source))

Commands and Functions for Working with Parameters and Results

params declaration

Behavior: Declares some named incoming parameters for the initial handler of a script. The params declaration must be the first statement in the script. It assigns names to the incoming parameters. The parameters can still also be accessed using the param, paramcount, and params functions as described below.

Syntax:

params paramName1 {, paramName2 ...}

Example:

params width,height

param function

Behavior: Returns the value of one of the parameters passed to the current handler, specified by its ordinal position in the parameter list. A handler can receive any number of incoming parameters, regardless of the number of named parameters that it declared. The param function can be used to retrieve their values.

Syntax:

the param of numExpr

param( numExpr )

Examples:

get the param of 1-- gets the first parameter

put param(0)-- shows the handler name

paramCount function

Behavior: Returns the number of parameters passed to the current handler.

Syntax:

the paramCount

paramCount()

Example:

repeat with n=1 to the paramCount

put "Parameter " & n & " is " & param(n)

end repeat

params function

Behavior: Returns a text string consisting of the handler name followed by the values of all of the parameters passed to the current handler. Parameter values other than lists and property lists are each enclosed in quotes.

Syntax:

the params

params()

Example:

put the params -- might show: test "John Doe","27",("JD","Bud")

parameterList function

Behavior: Returns a list containing all of the parameters that were passed to the current handler. Sometimes this might be a more convenient way of working with the parameters that were passed in than using the paramCount and param functions.

Syntax:

the parameterList

parameterList()

Example:

repeat with each item of the parameterList

add it to total

end repeat

return func(the parameterList as parameters)

-- pass our params to func

return command

Behavior: Returns the result of a function when used in a function handler, or sets the result if used in a message handler.

Syntax:

return {expression}

Examples

return pi*diameter

result function

Behavior: Returns the result (if any) set by the previous command. Most commands which operate on files, for example, will set the result to empty if they succeed, or to a message indicating what went wrong if they fail.

Syntax:

the result

result()

Example:

if the result is not empty then throw "Error", the result

Tech Talk

At the beginning of each statement the result is set to the result produced by the previous statement. To determine the result of an operation, therefore, you must call this function as part of the very next statement executed.

When a return statement is executed as part of a handler that was called as a command (rather than as a function), the return value sets the result in the script which called it.

The following commands will set the result to something other than empty under some conditions: answer, ask, convert, copy, create, delete, move, open, post, read, rename, replace, seek, shell. It can also be set when accessing a file or URL. In testing the result to determine whether the previous command succeeded, it is usually best to check whether the result is empty, rather than looking for specific words in the result, since the exact wording of an error message might change in a future release.

If the throwExceptionResults global property is set to true, any time a command sets the result to an exception object (which happens on most error conditions), that exception will be thrown rather than becoming available through this function as described above.

Whenever a non-empty result is set, it is inserted into the resultHistory global property. This makes it possible for a script to retrieve a result value from an earlier statement. Care must be used, however, to match a result to a particular statement, as empty values are not included. A limited number of results are retained, as specified by the resultHistoryLimit global property. When this limit is reached, older results are discarded.

If the value returned is an exception object (a property list with an objectType of “exception”) the caller throws the exception if the throwExceptionResults global property is set to True.

 

This topic was last updated on December 06, 2019, at 11:57:44 AM.

Eggplant icon Eggplantsoftware.com | Documentation Home | User Forums | Support | Copyright © 2020 Eggplant