function

Typecontrol structure
DictionaryLCS
LibraryLiveCode Script
Syntax
[private] function <functionName> [<parametersList>] 
   <statementList> 
end <functionName>
Summary

Defines a custom function handler.

Introduced1.0
OSmac, windows, linux, ios, android, web
Platformsdesktop, server, mobile
Parameters
NameTypeDescription
functionName

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 final statement is typically a return statement, which sends the value derived in the function handler back to the statement that calls the function.

Example
function myFunction
   return "test"
end myFunction
function cubeIt pNum
   return pNum * pNum * pNum
end cubeIt
Values
NameTypeDescription
The result

By default the result is set to the value returned by the function. See entry for the return control structure for more details. *Note:* As the result function is global in scope, if you do not explicitly return 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.

RelatedKeyword: $, end, private, string
Function: functionNames, param, paramCount, result
Glossary: call, caller, control structure, execute, expression, handler, message path, parameter, return, statement
Control Structure: exit, return
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 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 returns the value to the calling handler. This example of a custom function uses two parameters and 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 call the function in a handler, the function call is passed through the message path. When it reaches the object whose script contains the function handler, the statements in the handler are 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.