#%TITLE% STLIST.MAC
#
#%NAME%
#  STLIST.MAC - Macros for list handling
#
#%OVERVIEW%
#  This macro file provides a set of functions to handle lists of elements
#  with optional parameters.%BR%
#  A list is data structure stored in an associative array that is composed 
#  of a number of elements. Each element is a string that occupies a certain 
#  position in the list, numeric elements are not allowed.
#  An element can be referenced by it name (string) or by its position in 
#  the list (number).%BR%
#  Each element in the list can have an arbitrary number of parameters 
#  associated to it.
#  Each parameter has a name (a string) and a value (a number or a string).%BR%
#  This macro set provides functions to initialise the list and add elements 
#  and parameters to it. It also provides functions to retrieve information
#  from the list.%BR%
#  %BR%
#  When retrieving information it may be convenient to use shortcuts to 
#  access directily the content of the list instead of going through the 
#  macro functions. In this case there is no error checking but performance 
#  is considerably increased.%BR%
#  if LIST[] is the associative array that holds the list, the following 
#  expressions can be used:
#%UL%
#%LI% (LIST[0])  evaluates to the number of elements in the list.
#%LI% (elem in LIST)  is true if the string elem is a valid element.
#%LI% (LIST[n])  returns the element in position n (>0).
#%LI% (LIST[elem][par]) returns the value of the parameter par of element elem.
#%XUL%
#
#%ATTENTION%
# This macro set overrides some macros previously included in %B%stlocal.mac%B%.
#%EXAMPLE%
#%DL%
#%DT%list_add(mylist, \"el1\")
#%DD% Adds the element "el1" to the list stored in the associative array
#     mylist.
#%DT%list_addpar(mylist, \"el1\", \"par1\", 34)
#%DD% Adds the parameter "par1" to the element "el1" with a value of 34.
#%DT%list_list(mylist)
#%DD% Prints on the screen the current content of the list mylist.
#%DD%
#%XDL%
#
#%END%


#%UU% <list>
#%MDESC%
#  This macro checks if <list> is an associative array and if not
#  initialises it to be ready to contain a list. It does nothing if
#  <list> was already initialised.
#
def list_test 'if (!(whatis("$1") & 0x01000000)) {$1[0]=0}'

#%UU% <list>
#%MDESC%
#  This macro clears and iniatilises <list> to contain a list. The information
#  contained (if any) is lost.
#
def list_init '{
   local i
   if (whatis("$1") & 0x01000000) {
      for (i in $1) 
         delete $1[i]
   }
   $1[0]=0
}'

#%UU% (<list>)
#%MDESC%
#  This function returns the number of elements contained in the list
#  specified as parameter. <list> must be an associative array (old-style
#  array), if not the function returns -1.
#
def list_n(list) '{
   local wl
   wl = whatis("list")
   if (wl) {
      if (wl & 0x01000000){
         return(list[0]+0)
      }else
         return (-1)
   } else
      return(0)
}'

#%UU% (<list>, <item>)
#%MDESC%
#  This function checks if <item> is contained in <list> and returns its
#  current position. If <item> is not in the list the function returns
#  zero.%BR% 
#  <list> must be an associative array (old-style array), if not the
#  function returns -1.%BR%
#  <item> is either a string or a number. If a number is used it refers to
#  the position of the element in the list.
#
def list_check(list, item) '{
   local i

   if (list_n(list) < 0)
      return(-1)

   if (item + 0 == item) {
      i = (item < 0) ? 0 : int(item)
   } else {
      i = (item in list)? list[item] : 0
   }
   if (i <= list[0])
      return(i)
   else
      return(0)
}'

#%UU% (<list>, <item>)
#%MDESC%
#  This function adds a new element to the list. The element is specified
#  by the string <item>. If such element already exists it is moved to the
#  end of the list but no new elements are appended.%BR%
#  The function returns the position in the list of the element recently 
#  added. This value is always the size of the list.%BR%
#  <item> cannot be a numeric value.%BR%
#  If <item> is a number, the element is not added and the function
#  returns 0. If <list> is not a valid list the function returns -1.
#
def list_add(list, item) '{
   local N

   if (item == (item+0))
      return(0)

   if (item in list) {
      for (N = list[item]; N < list[0]; N++) {
         list[N] = list[N+1]
         list[list[N+1]] = N
      }
      list[list[0]] = item
      list[item] = list[0]
   } else {
      list[++list[0]] = item
      list[item] = list[0]
   }
   return(list[0])
}'

#%UU% (<list>, <string> [,<separator>])
#%MDESC%
#  This function adds new elements to <list> in the same way than
#  %B%list_add%B% but several elements can be appended in the same function
#  call. The element specifiers are
#  obtained by spliting <string> by means of the %B%spec%B% function split(). 
#  If no <separator> is specified space characters are used as delimiters.%BR%
#  The function returns the number of elements added to the list. If an error
#  happens -1 is returned and <list> is not modified. 
def list_splitadd(list, str, sep) '{
   local i larr[] llist[] n

   if (list_n(list) < 0)
      return(-1)

   if (whatis("sep") & 0x08000000)
      n = split(str, larr)
   else
      n = split(str, larr, sep)

   for (i = 0; i < n; i++) if (list_add(llist, larr[i]) <= 0) return(-1)
   for (i = 0; i < n; i++) list_add(list, larr[i])
   return(llist[0])
}'

#%UU% (<list>, <item>, <param>, <value>)
#%MDESC%
#  This function sets the value of a parameter for a particular element in
#  a list.%BR%
#  <list> and <item> must follow the rules explained for the
#  function %BR%list_check()%BR%.
#  <param> is a string that specifies the parameter, if a number is used it is
#  internally converted to string. <value> can be a number or a string. %BR%
#  If no error is found, the function returns 1, otherwise it returns -1.
#
def list_setpar(list, item, param, value) '{
   local N parlist

   if ((N = list_check(list, item)) > 0) {
      item = list[N]
      parid = item "\034" param
      list[parid] = value
      return(1)
   } else
      return(-1)
}'

#%UU% (<list>, <item>, <param_list>)
#%MDESC%
#  This function creates an auxiliary list that contains all the parameters
#  associated to a given element in a list.%BR%
#  <list> and <item> must follow the rules explained for the
#  function %BR%list_check()%BR%.
#  The auxiliary list is created in <param_list> that must be also an 
#  associative array as <list>. When the function returns, the elements of 
#  <param_list> are the identifiers of all the parameters associated to the
#  element <item> in <list>. Each element of <param_list> has a single
#  parameter called `value' that is set to the actual value of the
#  corresponding parameter in <list>.%BR%
#  The function returns the total number of parameters associated to <item>,
#  i.e. the total number of elements in <param_list>, or -1 if an error
#  happens.
#
def list_getparlist(list, item, parlist) '{
   local N npar i len parid

   if ((N = list_check(list, item)) <= 0)
      return(-1)

   list_init parlist

   parid = list[N] "\034"
   len = length(parid)
   for (i in list) {
      if (length(i) >= len && substr(i, 1, len) == parid) {
         N = list_add(parlist, substr(i, len+1))
         list_setpar(parlist, N, "value", list[i])
      }
   }
   return(parlist[0])
}'

#%UU% (<list>, <item>, <param>)
#%MDESC%
#  This function returns the value of a particular parameter associated to
#  an element of a list. 
#  <list>, <item> and <param> must follow the rules explained for the
#  function %BR%list_setpar()%BR%.
#  If an error is found the function returns -1.
#
def list_getpar(list, item, param) '{
   local par
   
   if ((N = list_check(list, item)) <= 0)
      return(-1)

   par = list[N] "\034" param
   return((par in list)? list[par] : -1)
}'

#%UU% (<list>, <item> [, <param>])
#%MDESC%
#  This function removes a parameter associated to an element of a list.
#  If <param> is not especified, all the parameters associated with the
#  element <item> are removed.
# 
def list_removepar(list, item, param) '{
   local parid len i

   parid =  item "\034"
   len = length(parid)
   if (whatis("param") & 0x08000000) {
      for (i in list)
         if (length(i) >= len && substr(i, 1, len) == parid)
            delete list[i]
   } else {
      parid = parid param
      if (parid in list)
         delete list[parid]
      else
         return(-1)
   }
   return(0)
}'

#%UU% (<list>, <item>)
#%MDESC%
#  This function deletes a particular element in a list and returns its
#  position in the list before deletion.%BR%
#  If <item> is not in the list the function returns zero.
#  <list> must be an associative array (old-style array), if not the
#  function returns -1.%BR%
#
def list_remove(list, item) '{
   local N i len

   list_removepar(list, item)
   if ((N = list_check(list, item)) > 0){
      item = list[N]
      for (i=N; i<list[0]; i++) {
         list[i] = list[i+1]
         list[list[i+1]] = i
      }
      delete list[i]
      delete list[item]
      list[0] = list[0] - 1
   }
   return(N)
}'

#%UU% (<list>, <item>)
#%MDESC%
#  This function returns -1 if the element <item> is not included in <list>
#  or if an error happens. If <item> is a valid element the function returns
#  the element identifier (that may be different from <item> if a number is
#  used).%BR%
#
def list_item(list, item) '{
   local N
   if ((N = list_check(list, item)) > 0)
      return(list[N])
   else
      return(-1)
}'

#%UU% (<list>)
#%MDESC%
#  This function prints on the screen all the elements in a list along with
#  the associated parameters. It is intended for debugging purposes.%BR%
#  It returns the number of eleemnts in the list or -1 if an error happens.
#
def list_list(list) '{
   local N i j parlist[]

   if ((N = list_n(list)) < 0){
      return(-1)
   }
   if (N == 0) 
      print "List is empty"
   else {
      printf("List contains %d element%s:\n", N, N>1?"s":"")
      parlist[0]=0
      for (i=1; i<=N; i++) {
         printf("%3d - %10s  ", i, list[i])
         if (npar = list_getparlist(list, list[i], parlist) <= 0)
            print "No parameters"
         else {
            for (j = 1; j <= parlist[0]; j++)
               printf("%s:<%s> ", parlist[j], list_getpar(parlist, j, "value"))
            print
         }
      }
   }
   return(N)
}'
#%MACROS%
#%DEPENDENCIES%
#  No dependencies
#%AUTHOR% P. Fajardo, (Original 3/96 in stlocal.mac). %BR%
#  $Revision: 1.0 $ / $Date: 2002/01/29 09:14:39 $
#%TOC%