Synopsis:
Meta-HTML allows the use of array variables as well as single element variables. In fact, all string variables in Meta-HTML can be treated as array variables -- there is no special command for creating such variables.
Commands:
More Information:
Array variable values are referenced by placing the array index directly after the variable name, enclosed in square brackets ([ and ]). Thus, a reference to the 3rd element of the array FOO looks like:
foo[3]
When an array reference is made without any containing index, the reference refers to the entire array. So, to get the value of the entire array stored in FOO, you would write:
<get-var foo[]>
In order to ease the writing of array references which rely on a variable index, a variable name seen as an array reference index is automatically looked up as if you had written <get-var VAR>
. Finally, multiple values may be given in a set-var
command by separating those values with newline characters. The following sequence of commands illustrates the typical use of array variables.
<set-var array[] =
"value-zero
value-one
value-two
value-three">
<set-var i=0>
<while <get-var array[i]>>
The value of array[<get-var i>] is `<get-var array[i]>'.<br>
<increment i>
</while>
produces:
The value of array[0] is `value-zero'.
The value of array[1] is `value-one'.
The value of array[2] is `value-two'.
The value of array[3] is `value-three'.
Function Documentation
<array-add-unique ITEM ARRAYVAR [CASELESS=TRUE]>
|
Simple
|
Adds ITEM as the last array element of the contents
of ARRAYVAR if, and only if, ITEM is not already
a member of that array.
The comparison is a direct string-wise compare. If CASELESS is non-empty, then a caseless string compare is done.
See also array-append
.
<array-append ITEM ARRAYVAR>
|
Simple
|
Adds ITEM as the last array element of the contents
of ARRAYVAR. This is especially useful in conjunction with foreach
as a collector:
<foreach name allnames>
<if <satifies-criteria <get-var name>>
<array-append <get-var name> useful-names>>
</foreach>
See also array-add-unique
.
<array-concat RECEIVER [CONTRIBUTOR...]>
|
Simple
|
Appends the contents of each CONTRIBUTOR array to the
end of RECEIVER.
Both RECEIVER and each are variable names whose values are treated as arrays.
For a single CONTRIBUTOR, array-concat
could have been defined as:
<defsubst array-concat>
<foreach item %1>
<array-append <get-var item> %0>
</foreach>
</defsubst>
<array-member ITEM ARRAYVAR [CASELESS=TRUE]>
|
Simple
|
Looks up (and returns) the index of ITEM in the contents of the array referenced by ARRAYVAR.
If ITEM is not found, then array-member
returns the empty string.
If CASELESS is non-empty, then the comparison is done without regard to character case. Otherwise, character case is significant in the location of the item.
<set-var array[] =
<prog
this
another
multi word
thing>>
<array-member "multi word" array>
produces:
2
<array-shift AMOUNT ARRAYVAR>
|
Simple
|
Shift the elements of ARRAYVAR the indicated amount.
If AMOUNT is negative, the elements are shifted down (i.e. towards zero), with the lowest number elements being lost.
If AMOUNT is positive, the elements are shifted up, with no loss at all -- instead empty elements are used to fill the created space.
Given the array:
<set-var array[] =
<prog
0
1
2>>
then after executing <array-shift 2 array>
, the array looks like:
""
""
"0"
"1"
"2"
and, a subsequent execution of <array-shift -3 array>
leaves ARRAY:
"1"
"2"
<array-size ARRAYVAR>
|
Simple
|
Returns the number of elements in the array referenced by the variable ARRAYVAR.
Examples:
<set-var array[]="this">
<array-size array>
produces:
1
and,
<array-shift 4 array>
<array-size array>
produces:
5
<foreach ELEMENTVAR ARRAYVAR [START=X] [END=X] [STEP=X]> body </foreach>
|
Complex
|
Perform BODY with ELEMENTVAR bound to successive
memebers of ARRAYVAR, starting with the element at START (default 0), and ending at END (default
<array-size ARRAYVAR>
), advancing by STEP (default 1).
The foreach
command is the basic array looping device in Meta-HTML. It is guaranteed to iterate over each element that you specify, whether that element is the empty string or not.
Starting with the simple array:
<set-var array[]="0\n1\n2\n3\n4\n5\n6\n7\n8\n9">
we can print out the odd numbers of this array by using values for both START and STEP:
<foreach x array start=1 step=2> <get-var x>, </foreach>
produces:
1, 3, 5, 7, 9,
or, we can produce a "countdown" with a negative value for STEP:
<foreach x array step=-1> <get-var x>, </foreach> BOOM!
produces:
9, 8, 7, 6, 5, 4, 3, 2, 1, 0, BOOM!
<sort ARRAYVAR [SORT-FUN] [CASELESS=TRUE] [SORTORDER=REVERSE] [NUMERIC=TRUE]>
|
Simple
|
Sort the contents of the array ARRAYVAR.
The elements are sorted in place -- this function has no return value.
If CASELESS=TRUE is given, then the comparison of the elements of the array is done without regards to case.
If SORTORDER=REVERSE is given, then the results are returned in descending order, instead of ascending order. The default is to order the elements in ascending order.
If NUMERIC=TRUE is given, then the elements of ARRAYVAR are treated as numeric entities, whether they are or not. The default is to treat the elements as character strings, which can have unexpected results when sorting numeric quantities ("11" is less then "2" when sorting alphabetically!)
Finally, you may supply a sorting function, whose name is passed as SORT-FUN. This function will be called on each element just before comparison, and the results of that function will be used for the comparison instead of the element itself. This allows you to create a collating sort, or to sort on complex weighting features, or anything else that you can conceive of.
Examples:
Given the array:
<set-var array[0] = 1
array[1] = 2
array[3] = 3
array[4] = 4
array[5] = 20>
then,
<sort array>
<foreach x array> <get-var x> </foreach>
produces:
1 2 2 20 3 4 6 7 8 9
while
<sort array numeric=true>
<foreach x array> <get-var x> </foreach>
produces:
1 2 2 3 4 6 7 8 9 20
Sorting strings:
<set-var array[]="a\nb\nc\nd\ne\nf\nA\nB\nC\nD\nE\nF">
<sort array sortorder=descending>
<foreach x array> <get-var x> </foreach>
produces:
f e d c b a F E D C B A
Without regards to case:
<sort array caseless=true>
<foreach x array> <get-var x> </foreach>
produces:
a A b B c C d D e E f F
Finally, here is an example which sorts a list
of words based upon the percentage of vowels
present in each word, using a sort function
which calculates that value for each string:
<defun vowel-percentage string>
<set-var x =
<subst-in-string <downcase <get-var string>> "([^aeiou])" "">>
<percent <string-length <get-var x>>
<string-length <get-var string>>>
</defun>
.blank
<set-var words[]=
<prog
Brian
Fox
sorts
elegant
strings
beautifully>>
.blank
<sort words vowel-percentage numeric=true sortorder=descending>
.blank
<foreach word words>
<get-var word> (<vowel-percentage <get-var word>>)<br>
</foreach>
produces:
beautifully (45.45)
elegant (42.92)
Brian (40.00)
Fox (33.33)
sorts (20.00)
strings (14.29)
Edit Section
Function Index
Variable Index

The
META-HTML
Reference Manual V1.4
Copyright © 1995, 1996,
Brian J. Fox,
1996, 1997 Universal Access Inc.
Found a bug? Send mail to
bug-manual@metahtml.com