From VFXPedia

Contents 1 Getting Started: Functions 1.1 What are Functions? 1.2 Defining Functions 1.3 Calling Functions 1.4 Arguments 1.5 Return Values 1.6 Calling a Function With An Unknown Number of Arguments 1.7 Tips for Functions (edit)

Getting Started: Functions

What are Functions?

A function is a chunk of code intended to do a task. Functions accept arguments, then manipulate those arguments to produce a result . The advantage to functions is that they help to break a script up into smaller conceptual pieces, and that they are reusable.

Defining Functions

A function must be defined before it can be used. A function is defined using the following constructor syntax, where 'name' is the name used to call the function, 'argX' represents the values passed to the function, and the 'chunk' is the code executed when the function is called.

function name( arg1, arg2, arg3)
   chunk
end

eyeonScript allows functions to be assigned to variables, so the same function could also be defined as

name = function(arg_name_1, arg_name_2, arg_name_3)
   chunk
end

Calling Functions

Once a function has been defined, it can be called later within the script, as show in the example below.

-- declare the greater function
function greater( )
   num_1 = 10
   num_2 = 100
 
   if num_1 > num_2 then
      print( num_1 )
   else
      print( num_2 )
   end
end
 
--now call the greater function
greater( )

If we try to call a function before we declare it, eyeonScript generates an error and halts script execution.

Arguments

The above example isn't very reusable or useful; it compares two fixed values since we assign values to num_1 and num_2 within the function itself. The result from our ‘greater’ function will always be the same. Ideally, we want our function to return the greatest of two completely unknown values. To accomplish this, we need to pass arguments to our function when we call it.

When we pass an argument to a function the value or variable becomes available to the function under the name of the argument. In the case of number or string variables a copy of the variable is made - similar to writing 'local argname = variable'. In the case of tables or objects the values are passed by reference, so modifications made to the table or object will affect the original.

function greater( num_1, num_2 )
   if num_1 > num_2 then
      print( num_1 )
   else
      print( num_2 )
   end
end
 
--now call the greater function
greater(10, 100)

Now the values of num_1 and num_2 are assigned when we call the function, so we could call this function with any two values we want. This makes the function far more re-usable.

Return Values

The greater() function above is fine if all we want to do is print the largest value, but most of the time we will want our function to return a value we can do further processing with the result.

So now we need to make our function return a value that we can assign to a variable when we call the function. This is done by placing the 'return' statement within the function. If we modify our previous example to use the return statement it end up looking like this example :

-- declare the greater function
function greater( num_1, num_2 )
   if num_1 > num_2 then
      return num_1
   else
      return num_2
   end
end
 
--now call the greater function
ret = greater( 10, 100 )
 
print("The biggest number is "..ret)

Note that 'return' must be the last statement in the chunk, if you placed a print(num_1) statement after the return statements in the above example eyeonScript would generate an error.

One of the more interesting capabilities of eyeonScript is the ability to return more than one value from a function by separating the values with a comma, as shown below

-- a function that counts the number of letters 
-- and words in a string
function count_string( val )
   local length = string.len(val)
   local count = 0
 
   string.gsub(val,"(%w+)", function (v) count = count + 1 end)
 
   return length, count
end
 
str = "I have four words"
 
c, w = count_string(str)
 
print("There are ".. w .. " words and " .. c.. " letters in : ")
print("   "..str)

Calling a Function With An Unknown Number of Arguments

The greater function used in our above examples only accepts two arguments. If we tried to determine the greater of three values, we would have to call the function twice, as shown here :

x = 100
y = 15
z = 256.5
 
-- we could get the greater of these three values with
a = greater(x, y)
b = greater(a, z)
 
-- or we could also have used
a = greater( x, greater(y, z) )

However, ideally we would want our function to accept any number of arguments and return the greatest value from them all

function greater(...)
  sofar = 0
 
  for i = 1, table.getn(arg) do
    if sofar < arg[i] then
      sofar = arg[i]
    end
  end
 
  return sofar
end

In the above example we use the ellipsis (...) to indicate that the function will receive an unknown number of arguments. The arguments are provided into a local table called arg, so each argument can be accessed as arg[index]. The total number of numeric arguments in the table can be determined with the table.getn(arg) function.

The ellipses can be combined with other arguments, but the ellipsis must always be the last argument in the function declaration. For example, function(x, y, ...) is valid, where function(x, ..., y) is not valid.

None of the arguments defined for a function are considered to be required. The function will run regardless of whether all arguments for the function are called, or none at all. You must write functions so that they will not crash of fail unexpectedly if the expected arguments are not provided. Our greater example would return 0 if no arguments were provided.

Tips for Functions (edit)

EyeonTips:Script/Reference/Language/Functions