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,)

Number of Parameters

In SenseTalk, when a command or function is called, it will invoke a custom handler or built-in command or function with that name, regardless of the number of parameters that were passed or expected. If the number of parameters that are passed don't match what is expected by the called handler, it may deal with the difference in various ways: an exception may be thrown; excess values may be ignored; or default values may be assumed for parameters that were not supplied. It is up to the called handler to take what it receives and respond appropriately at runtime. For more information, see Receiving Passed Parameters.

Passing a List as Parameters

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 in the list individually, rather than passing the list as a single entity:

put [candles, 6, blue] into thingsToBeUpdated

updateAllItems thingsToBeUpdated as parameters -- This passes three parameters: the variable candles, the number 6, and the variable blue.

If you do this without "as parameters", the entire list will be passed as one parameter.

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

return otherFunction(parameterList() as parameters)

Property Lists as Parameters

As a convenience, when the last or only parameter is a property list, the curly braces can be omitted. When one of these forms is used, all of the individual properties are passed together as a single property list.

Examples:

Both of these examples do the same thing. The only difference is that one leaves off the curly braces for the property list passed as the second parameter.

addAtPosition 23, {item:"paper", quantity:500, color:"White"} -- The first parameter passed is 23, and the second parameter is the property list.

addAtPosition 23, item:"paper", quantity:500, color:"White" -- The first parameter passed is 23, and the second parameter is the property list.

Examples:

addToInventory item:"candles", quantity:6,color:"Blue"-- Passes a property list to the called handler as a single parameter.

set article to fetchClipping(author:"Lewis", title:"Lost")-- Passes a property list to the called function as a single parameter.

Named and Unnamed Parameters

Passing property lists as parameters can give the effect of passing 'named' parameters, with the 'name' being the key associated with each property in the list. Named and unnamed (non-property list) parameters can be combined in a single call, provided that the named parameters come last. The named parameters are sent as a single property list.

Example:

The following example starts with a simple text string, and then runs two calls that modify that text string in different ways, demonstrating how the specialReplace handler is able to work with the parameters as they are passed, whether that be a number of parameters or a single property list.

The first call passes four parameters. The first three of these parameters are single values, and the fourth is a property list containing the caseSensitive and matchCase keys and their corresponding values. Because the caseSensitive property passes "No" (meaning it is not case sensitive), the output is: 'The red fox said "YUM!" when it ate the red Bunny icecream.'

The second call passes a single property list to the specialReplace handler. Because this call passes "Yes" for the caseSensitive property, the output is: 'The red fox said "YUM!" when it ate the Blue Bunny icecream.'

You can copy and paste the below example into an Eggplant Functional script and run it to try it out yourself.

set text to {{

The blue fox said "YUM!" when it ate the Blue Bunny icecream.

}}

 

//Call 1 (passes 4 parameters):

put textChange(text, "blue", "red", caseSensitive: No, matchCase: Yes) -- Prints the output returned by the textChange handler when passed four parameters, including a property list, in this case 'The red fox said "YUM!" when it ate the red Bunny icecream.'

 

//Call 2 (passes one property list as a parameter):

put textChange(old: "blue", new: "red", source: text, caseSensitive: Yes) -- Prints the output returned by the textChange handler when passed this single property list, in this case 'The red fox said "YUM!" when it ate the Blue Bunny icecream.'

 

to textChange options

 

//Determine what kind of parameters were passed:

if options is a property list then

// Everything was passed as 'named' parameters, and can be accessed using their property keys:

put options.source into someText

put options.old into oldWord

put options.new into newWord

else

// Since the first parameter wasn't a property list, assume the parameters were sent sequentially so they can be accessed by position:

put param(1) into someText

put param(2) into oldWord

put param(3) into newWord

end if

 

//Replace the text:

if options.caseSensitive then

replace oldWord with newWord in someText case sensitive

else

replace oldWord with newWord in someText

end if

 

return someText -- This returns the modified text string to the initial call, which prints the modified text (either Call 1 or Call 2).

 

end textChange

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}

Example:

return pi*diameter

Related:

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.

Related:

 

This topic was last updated on July 02, 2020, at 02:51:53 PM.

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