Section Intro: Arrays

THE META-HTML LANGUAGE REFERENCE MANUAL

Variables

[TOC]

Packages

Section Intro: Arrays

Arrays

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:

array-add-unique
array-append
array-concat
array-delete-index
array-intersection

array-member
array-reverse
array-section
array-shift
array-size

array-union
comma-separated
foreach
sort
sort::correlated-sort

More Information:

Array variable values are referenced by placing the array index directly after the variable name, enclosed in square brackets ([ and ]). Array references use a zero-base index, so that the first accessible element in the array is at index 0 and a reference to the 4th accessible 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-once 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-once array[i]>>
      The value of array[<get-var-once i>] is `<get-var-once array[i]>'.<br>
      <increment i>
    </while>

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'.

<array-add-unique ITEM ARRAYVAR &key [CASELESS=TRUE] [TELLME=TRUE] Simple

Add 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.

If the keyword argument TELLME is supplied with a non-null value, then this function returns the word "true" if the item was added, or the empty string if not.

See also array-add-unique.

<array-concat RECEIVER &rest contributors...> Simple

Appends the contents of each CONTRIBUTOR array to the end of RECEIVER.

Both RECEIVER and each CONTRIBUTOR are variable names whose values are treated as arrays.

For a single CONTRIBUTOR, array-concat could have been defined as:

<defsubst array-concat dest-name source-name>
  <foreach item <get-var-once source-name>>
     <array-append <get-var-once item> <get-var-once dest-name>>
  </foreach>
</defsubst>

<array-delete-index INDEX ARRAYVAR Simple

Delete the element of ARRAYVAR indicated by INDEX. The remainder of the array after INDEX is shifted back by one, so that the array ends up with one less element than it had before.

<array-intersection ARRAY1 ARRAY2 Simple

Return the intersection of the two arrays represented by the variables ARRAY1 and ARRAY2. For example:

 <set-var a1[0]=0 a1[1]=1 a1[2]=2 a2[0]=2 a2[1]=3 a2[2]=4>
 <array-intersection a1 a2>

<array-member ITEM ARRAYVAR &key [CASELESS=TRUE] [COMPARE=FUNC] Simple

Look up (and return) 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.

If a function name is passed, as in COMPARE=FUNC, it should be the name of a function which receives two required arguments -- the item that is to be looked for, and an element of the array that this item is to be compared against, and an optional keyword argument of "caseless". If the function returns a non-empty string, then this item is considered a match.

By default, string comparison is done on the elements.

<set-var array[] =
  <prog
     this
     another
     multi word
     thing>>
<array-member "multi word" array>

<array-reverse ARRAYVAR Simple

Directly modify the values of ARRAYVAR making the first element be the last, and the last be the first.

<set-var array[]="0
1
2
3">
<array-reverse array>
<get-var-once array[]>

<array-section ARRAYVAR &optional [BEG] [END] Simple

Return the section of the array in ARRAYVAR which starts at index offset BEG and continues until index offset END.

BEG defaults to zero (i.e., the beginning of the array), and END defaults to the size of the array (see also array-size).

If BEG is greater than END, the elements of the array are returned in reverse order, starting from the ENDth element.

<array-shift AMOUNT ARRAYVAR &key [START] 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.

If the keyword argument START is present, it indicates the zero-based offset from which to start shifting.

Given the array:

<set-var array[] =
   <prog
       0
       1
       2>>

then after executing <array-shift 2 array>, the array looks like:

   ""
   ""
   "0"
   "1"
   "2"

<array-shift -3 array>

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>

and,

<array-shift 4 array>
<array-size array>

<array-union ARRAY1 ARRAY2 Simple

Return the union of the two arrays represented by the variables ARRAY1 and ARRAY2. For example:

 <set-var a1[0]=0 a1[1]=1 a1[2]=2 a2[0]=2 a2[1]=3 a2[2]=4>
 <array-union a1 a2>

<comma-separated ARRAYVAR Simple

Produce a human readable string of the elements in the array variable ARRAYVAR separated by commas where appropriate, and with the word "and" after the penultimate item.

<foreach ELEMENTVAR ARRAYVAR &key [START=X] [END=X] [STEP=X] [ITER=VAR] [NO-COPY=TRUE] 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.

If NO-COPY=TRUE is specified, the array is not copied before iteration, so that changes that you make to the array take place immediately, during the execution of the surrounding <foreach>.

Starting with the simple array:

<set-var example::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 example::array start=1 step=2> <get-var-once x>, </foreach>

1,  3,  5,  7,  9,

or, we can produce a "countdown" with a negative value for STEP:

<foreach x example::array step=-1> <get-var-once x>, </foreach> BOOM!

9,  8,  7,  6,  5,  4,  3,  2,  1,  0,  BOOM!

<sort ARRAYVAR &optional [SORT-FUN] &key [CASELESS=TRUE] [SORTORDER=[ASCENDING|DESCENDING]] [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>

1 2 20 3 4 while 1 2 3 4 20

Sorting strings: f e d c b a F E D C B A

Without regards to case: 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-once string>> "([^aeiou])" "">>
  <percent <string-length <get-var-once x>>
           <string-length <get-var-once string>>>
</defun>

<set-var words[]=
  <prog
    Brian
    Fox
    sorts
    elegant
    strings
    beautifully>>

<sort words vowel-percentage numeric=true sortorder=descending>

<foreach word words>
  <get-var-once word> (<vowel-percentage <get-var-once word>>)<br>
</foreach>

beautifully (45.45)
  elegant (42.86)
  Brian (40.00)
  Fox (33.33)
  sorts (20.00)
  strings (14.29)

<sort::correlated-sort KEYARRAY &key [CASELESS] [SORTORDER] [NUMERIC] &rest correlated-arrays[]> Simple

Sort the CORRELATED-ARRAYS based on the results of sorting KEYARRAY. Also see sort.

Edit Section
Function Index
Variable Index