Command
	function

Purpose
	Creates a function, which is a block of commands, optionally returning a single constant.

Aliases
	function, func, fun, end

Syntax
	A function is declared as follows.

	function [<options>] <type> <name>
	  [<command>]
	  [<command>]
	  [<command>]
	  ...
	  return [<return_value>]
	  ...
	end

	A function is called (invoked) as follows.
	<name>	(	[<var_name> ( <var_value> )]
			[<var_name> ( <var_value> )]
			...
		)

Options
	-g	Global. If this option is specified, the function being declared is available
		not only locally (within the current script file and in other scripts it calls),
		but is also available throughout (globally). Wihout this option, the function
		is available only locally.

		Global function must not already be declared anywhere else. Global function can
		not be declared again (overloaded) anywhere else.

Arguments
	<type>	The type of value the function returns. See var for available types. In addition to
		the available data types, function type can be declared as none, which indicates
		that the function does not return any value.
		
	<name>	Name of the function. This name is used when invoking the function.

	<return_value>	A value of type <type>. This can be specified using a constant, variable, expression,
		function call to another function, inline command, or a combination of these,
		all resulting in a value of type <type>.
	
	When invoking a function, the parameters to the function are passed as <var_name> and <var_value>.

	<var_name>	Name of a variable. If this name is preceeded by $, the variable is assumed
		to be declared already outside the function. If the name is not preceeded
		by $, the variable is assumed to be declared inside the function.

	<var_value>	Value of the variable <var_name>. This can be a constant, variable (must have $ sign),
		expression, inline command, another function or a combination of these.

Stream Input	
	Ignored.

Stream Output
	None.

Stream Error
	Any errors from the function, return and end commands are produced here.

Description
	function...end is a programming construct that allows to
	separate a certain functionality into a separate part of the code.

	Variables can be declared within a function. These variables remain local
	to the function and are not available outside. Variable overloading is
	permitted - variables with the same name as global variables can be
	declared within a function. If these overloaded variables are used within
	the function, their local type and value are used, instead of their global
	type and value.

	If, in the flow of execution of a function, the end command is encountered
	before encountering a return command, the default value of <type> will be returned.
		
Restrictions
	Redirection is not allowed on function, return and end commands.
	If redirection is specified, it will be ignored.
	However, commands within the function can have their
	individual redirections.

	A function can not call itself recursively. Similarly,
	two functions can not call each other mutually.

	Functions must be declared outside of any programming construct, such as if, else,
	while, for, do. However, the commands within the function themselves can contain
	these programming constructs.

	A function can use only variables local to the function, or global variables.

Valid Examples
	function int square
	  # This function calculates the square of the number
	  # passed as variable $num.
	  var int num
	  var int sqr
	  set $sqr = $num*$num
	  return $sqr
	  end

	The above function calculates the square of an int number.

	var int i
	set $i=1
	while ($i<=10)
	do
	  echo square(num($i))
	  set $i=$i+1
	  done

	The above will print squares of numbers 1 thru 10.

Invalid Examples
	var int i
	...
	if ($i<10)
	    function int square
	    ...
	    end

	Will produce an error. Functions must be declared outside
	of the if construct. But they can be called inside the if
	or any other constructs.


	Consider that a script file script.txt has the following code in it.

	var int output

	function int square
	  var int input
	  set $output = $input * $input
	  return $output
	  end

	When the script file script.txt is executed, it will produce error that variable $output is
	neither local to the function, nor global. If variable $output were declared with the
	-g (global) option, it could be used within the function.

See Also
var
return
script
if
while
systemvar