Custom Functions and "by name"

Eggplant Functional
, ,
1

Hi

If I consume the EPF API I can make a call as follows:

set loc to imagelocation(text:textSearch, searchrectangle:searchRect)

If i make my own custom function, in order to pass parameters in the same explicit normat i have to append “by name” to the call liek this:

TestFunction(param1:"test1", param2:"Test2" **by name**)

Without the “by name” term, the calls fail.

How can I construct a function that will allow explicit parameters by default, rather than ordinal position?

many thanks

2

When “by name” isn’t specified, SenseTalk will just pass all of the values as a single property list. So you can just write your handler to expect one parameter (a property list) and access the individual properties of the value that is passed in. Something like this:

to handle TestFunction options
    put options.param1 into param1
    put options.param2 into param2

Or, if you prefer to make it more concise:

to handle TestFunction options
    put options.[param1,param2] into [param1, param2]
3

Thanks for the reply - does this mean though the ordering is index-sensitive?

When we call the API functions using the “:” notation, do your handlers just look for key:name pairs and populate their internal variables by hand?

In the interests of readability and maintainability (in the absence of mouse-over code-insight and easily consumable global variables) I am trying to encourage people to be explicit with the function consumption so that anyone new coming into the project knows what a value is supposed to be doing in the target function. Having to supply “by name” on the end of every call feels cumbersome when compared to consuming the EPF API.

4

When you make a call like imageLocation(text:textSearch, searchRectangle:searchRect) SenseTalk creates a property list with text and searchRectangle properties and passes that as a single parameter to the function. This is true for your own functions as well as built-in functions.

Yes. Since the built-in handler for a function like imageLocation gets passed a single parameter which is a property list in this case, our code extracts the property values in essentially the same way I suggested earlier for your own handlers.

Understood. When we added the “by name” functionality recently, we considered making it automatic (without requiring the words “by name”) but that would have potentially broken existing scripts so we couldn’t do that. There may be a way for us to fix that in the future without breaking anything, but there is no definite plan for that. So for now you’ll have to take the approach of pulling the individual properties out of the property list rather than having them assigned to your variables automatically.

5

Hi Doug

Thanks for taking the time to give that reply - really helps with how i need to construct stuff moving forwards (and possibly retrospectively :slight_smile: ).

Am also hopeful for a way round the “by name” thing… Is this something that could be handled as an application option that is off by default to maintain backwards compatibility? New users can opt to switch it on without fear as there will be no existing stuff to break and makes scripts neater to work with.

best regards

paul