Hamster-Scripts: Functions (self-defined)

Creating a function

sub <identifier>( <variable-list> )

sub <identifier>

Starts a user-defined function named <identifier>, which has to start with a letter ("A"..."Z", "a"..."z"). Further characters may also contain digits ("0"..."9") or underscores ("_").

If the function has parameters, they have to be noted as a comma-separated list of variables within parenthesis:

	TestSub( 1, "two", 3 )
	quit

	sub TestSub( $a, $b, $c )
	   print( "TestSub called with " + $a + ", " + $b + " and " + $c )
	endsub

Each function has a return-value which can be set by "return", which additionally exits the function immediately:

	print( TestSub( 1, "two", 3 ) )
	quit

	sub TestSub( $a, $b, $c )
	   return( "TestSub called with " + $a + ", " + $b + " and " + $c )
	endsub

If no return-value is given, it is always set to 0 by a final "endsub", which is just an equivalent to "return( 0 )".

Please note, that the "endsub" in the example above is not really needed, as the function was already left by the previous "return". It's just there to make the script more "readable" and it's a good idea to a) always note it at the very end of a function and b) only there.

Parameters by value / by reference

By default, all parameters of a function are "called by value", which means, that their values are copied to their counterparts given in the parameter-list of the "sub". The values of the variables used for calling the "sub" are left unchanged:

	var( $a )
	$a = 1
	TestSub( $a )
	print( $a )  # -> 1 (unchanged by TestSub)

	quit

	sub TestSub( $x )
	   $x = 42
	endsub

If a variable in the parameter-list of a function is preceded with a "*", this value is "called by reference", which means, that the function directly uses the variable the function was called with. So if the function changes the value of the parameter variable, the value of the calling variable is changed as well:

	var( $a )
	$a = 1
	TestSub( $a )
	print( $a )  # -> 42 (changed by TestSub)

	quit

	sub TestSub( *$x )
	   $x = 42
	endsub

Optional parameters

By default, all parameters are mandatory, i. e. you have to provide the same number of parameters when calling the "sub" as declared in the "sub" line. By appending a question mark to a variable in the "sub" line, you declare this variable to be "optional", i. e. it might or might not be given when calling the function:

print( TestSub( 1, 2 ) )   # all parameters given
print( TestSub( 1 ) )      # second parameter omitted

quit

sub TestSub( $mandatory, $optional? )

   if( !IsVarSet( $optional ) )
      $optional = 42 # not given so use default value
   endif

   return( $mandatory + $optional )

endsub

If an optional parameter is not given when calling the function, the parameter variable in the function will be created but has no valid value assigned yet. You can check for such a "missing" value with function "IsVarSet" like in the example above.

A very special case is an optional "by reference" parameter. As there is no reference for a missing value, the parameter variable is not created at all in this case. You can check for such a "missing reference parameter" with function "IsVar" and create it yourself if required:

sub TestSub2( *$optRef? )

   if( !IsVar( $optRef ) )
      varset( $optRef, 0 )
   endif

   # ...

endif

If both mandatory and optional variables are used in a "sub" line, the mandatory ones have to be given in front of any optional ones.

Scope of variables

All variables declared within a function are local to this function. When the function is left again, they are deleted.

Global variables (i.e. declared outside of any function) are accessible within the function, unless a variable with the same name is created in it:

	var( $a )

	$a = 1
	print( $a )  # -> 1

	TestSub
	print( $a )  # -> 42

	quit

	sub TestSub

	   print( $a ) # -> 1
	   $a = 42
	   print( $a ) # -> 42

	   var( $a )   # global $a is from now on "out of scope"
	   $a = 666
	   print( $a ) # -> 666

	endsub

[www.elbiah.de Hamster Playground Documentation]