Name: function

Type: control structure

Syntax: function <functionName> [<parametersList>] <statementList> end <functionName>

Summary:

Defines a custom function <handler>.

Introduced: 1.0

OS: mac, windows, linux, ios, android

Platforms: desktop, server, mobile

Example:

function myFunction

return "test"

end myFunction

Parameters:

functionName (string):

A string up to 65,535 characters in length.

parametersList:

The parametersList consists of one or more parameter names, separated by

commas.

statementList:

The statementList consists of one or more LiveCode statements.

The result:

>*Note:* As the <result> is a global property, if you do not explicitly

> <return(control structure)> a value, then <the result> will not

> change, but reflect the last engine command, engine function or

> command or function handler that did return a value.

Description:

Use the <function> <control structure> to implement a custom function.

Form:The first line of a <function> <handler> consists of the word

"function" followed by the function's name. If the function has any

<parameter|parameters>, their names come after the function name,

separated by commas.

The last line of a <function> <handler> consists of the word "end"

followed by the function's name.

The purpose of a function is to compute a value and return it to the

handler that called the function. The function's value is returned by a

return <control structure> within the <function> <handler>.

A function handler can contain any set of LiveCode statements. Most

functions contain a return <statement>, which <return(glossary)|returns>

the value to the <caller|calling handler>. This example of a custom

function uses two <parameter|parameters> and <return(glossary)|returns>

a <string> :

function reversedName firstName,lastName

-- firstName and lastName are parameters

put lastName,firstName into constructedName

return constructedName

end reversedName

You create a custom function by writing a function handler for it. When

you use the function in a script, the function call is passed through

the message path. When it reaches the object whose script contains the

<function> <handler>, the <statement|statements> in the <handler> are

<execute|executed>.

A custom function is called by name, just like a built-in function, as

part of an expression. For example, this handler calls the custom

function above:

on mouseUp

ask "What is your first name?"

put it into firstParam

ask "What is your last name?"

put it into secondParam

put reversedName(firstParam,secondParam) into field "Name"

end mouseUp

A function can call itself. The following example calls itself to

compute the factorial of an integer:

function factorial theNumber

if theNumber = 1 then return 1

else return theNumber * factorial(theNumber -1)

end factorial

>*Note:* To declare a function that is local to the script it is

> contained in, prefix the declaration with <private>. For more

> information about this see the dictionary entry for the <private

> keyword>.

References: exit (control structure), return (control structure),

param (function), functionNames (function), result (function),

paramCount (function), the result (function), return (glossary),

handler (glossary), execute (glossary), statement (glossary),

control structure (glossary), parameter (glossary), caller (glossary),

private keyword (keyword), end (keyword), $ (keyword), private (keyword),

string (keyword)