SEL Inbuilt Function Reference
Index:
- &return – returning information from functions
- &permvar – keeping track of information
- &killvar – tidying up
- &addtolist – building lists
- &removefromlist – removing information from lists
- &countinlist – counting information in lists
- &splice – manipulating lists
- &random – Generating random numbers
- &my – Scoping your variables
- &print – Output data
- &is_numeric – check variable data type
- &defined – check if variable has a value
- &round – rounding off a number to nearest whole number
- &floor – rounding down a number
- &ceil – rounding up a number
&return
Parameters:
- list of value(s) to return from function
Example:
&return 5+7,’hello’;
Description:
Ends the processing of a function and returns the values in the list following the &return statement to the statement that called its function.
&permvar
Parameters:
- list of valid variable names
Example:
&permvar $items, $roses, $health;
Description:
Makes the given list of variable names permanent – meaning that the variables will be remembered between pages of your adventure.
&killvar
Parameters:
- list of existing valid variable names
Example:
&killvar $items, $roses, $health;
Description:
Makes the given list of variable names non-permanent if they were previously. After this statement is executed the values and variables will be forgotten by the system.
&addtolist
Parameters:
- Variable/listname
- List of values to store in the list
Example:
&addtolist $items, ‘Dagger’, ‘Crucifix’, $list_of_items_in_backpack;
Description:
Puts the list of values into the variable name passed as parameter 1 – which must be a valid variable name, not a constant. If the variable name of the list is not yet a list it will be converted automatically, or created if it does not yet exist. The list of values to put into the list may be constant values (e.g. ‘sword’, or a number), variables (e.g. $roses, $myname), or even variables that are lists themselves (e.g. $inventory, $friends_names), or any combination of such.
&removefromlist
Parameters:
- Listname
- Number to remove or ‘ALL’
- List of values to be removed from the list
Example:
&removefromlist $items, 3, ‘Garlic’, ‘Crucifix’;
&removefromlist $items, ‘ALL’, ‘Provisions’;
Description:
Will remove each item in the list given as parameters 3 onward from the list given as parameter 1 as many times as determined by the quantity given as parameter 2. So in our first example the list $items will have the value ‘Garlic’ removed 3 times, and the value ‘Crucifix’ also removed 3 times. In our second example, all values of ‘Provisions’ will be removed from the $items list.
*NOTE* at this time any non-numeric value passed as parameter 2 will count as ‘All’
*NOTE 2* This function will recurse into sub-lists and remove elements from those as well. This may change in the future however, as it does not strike as good programming.
&countinlist
Parameters:
- Listname
- Value we want counted (optional)
Example:
&countinlist $items,’Garlic’;
Description:
Counts the number of times the value of parameter 2 is present in the list given as parameter 1, so in our example if $list held the following values: ‘Crucifix, Garlic, Holy Water, Garlic’, then the function would return 2. If the second parameter is omitted and the function is called on just a list name, returns the number of all elements in that list, e.g. if $items held ‘Crucifix, Garlic, Holy Water, Garlic’, and we called ‘&countinlist $items’, it would return the number 4. &countinlist does NOT recurse into sub-lists.
&splice
Parameters:
- Variable/listname
- Offset
- Length
- Replacement list
Example:
&splice $list,3,2,’hello’,'goodbye’,$sublist;
Description:
Removes the number of elements, denoted by Length, in a list starting at the location denoted by Offset, and replaces them with all the elements in the Replacement list. The original list grows or shrinks as required to accomodate the replacement list. In the example $list[2] and $list[3] would be removed and replaced by ‘hello’, ‘goodbye’, and all the elements in $sublist. $list would grow to accomodate as necessary (note that this means whatever was in $list[4] and subsequent indexes would ‘move up’ appropriately).
Length set to 0 means that the Replacement list will be inserted. Leaving out a replacement list means that elements denoted by Offset and Length will be deleted.
&random
Parameters:
- Lower Limit
- Higher Limit
Example:
&random 7,12;
Description:
Returns a whole random number in the range determined by Lower and Higher Limit parameters
&my
Parameters:
- List of variables to be scoped locally
Example:
&my $temporary_value1, $temporary_value2;
Description:
Provides a local scope for the variables listed, more specifically a private scope. This means that variables are visible only to the function it is declared in. A local variable $temp declared in &myfunction cannot be accessed in &myotherfunction – although &myotherfunction may also have a local variable called $temp that exists completely independantly of the one in $myfunction. Local variables exist for only as long as it takes to execute the scope of the function it is declared in – the values are lost once the function exits.
The initial value for the Local variable will be either undefined, or, if a temporary variable exists with that name, it will be initialised with that value – however as this sits uncomfortably in my mind as not good programming practice, this may well change to all local variables declared through &my being initialised to Undefined.
The &my function returns an integer corresponding to the number of variables succesfully declared Local
Also please not that unlike most languages a statement such as:
&my $temp=3;
- will NOT have the result you expect. If $temp already exists as a Permanent or Temporary variable, it will assign the value of 3 to the permanent/temporary variable, then create a localised $temp. If $temp does not already exist, a temporary variable called $temp will be created, assigned the value of 3, then a local copy will be created.
It is not yet decided whether to allow making Local variables permanent through the &permvar function, as this would encourage bad coding and increase likelihood of scripting errors.
Parameters:
- Lists of items to output
Example:
&print 123,”456″,7+8; displays 12345615
Description:
Displays the list of items given. The list may be simple numbers, strings, variables, or expressions. At this time there is no seperator between items in the list – consideration is being given as to whether to make a space a default seperator. Unlike Perl, a variable inside a literal string, i.e. &print “Skill=$skill”;, will not be interpolated – yet. I plan to add this facility later. In the meantime use the concatenation operator to achieve the same effect, i.e. &print “Skill=”.$skill;
&is_numeric
Parameters:
- Variable to be examined
Example:
&is_numeric $x;
Description:
Returns 1 if the contents of the variable is a number (either positive, negative, whole integer or floating point), 0 if the variable is undefined or contains non-numeric data.
&defined
Parameters:
- Variable to be tested
Example:
&defined $x;
Description:
Returns 1 if the variable has had any value assigned to it, or if it has been assigned the undefined value (possible by assigning $x=$y where $y is undefined) (am I sure about this??? check again sometime). Returns 0 if the variable has yet to be assigned a value.
&round
Parameters:
- Variable to be rounded
$value=&round $value;
Rounds off a numeric value/variable to the nearest whole number, e.g. 5.3 returns 5 and 5.8 returns 6.
&floor
Parameters:
- Variable to be ‘floored’
$value=&floor $value;
Description:
Rounds down a numeric value/variable to the nearest whole number, e.g. 5.3 returns 5 and 6.7 returns 6.
&ceil
Parameters:
- Variable to be ‘ceilinged’
$value=&round $value
Description:
Rounds up a numeric value/variable to the nearest whole number, e.g. 5.3 returns 6 and 6.8 returns 7.