esrf

Beamline Instrument Software Support
SPEC Macro documentation: [ Macro Index | BCU Home ]

STLIST.MAC
See other macros in category: All
Description:
    STLIST.MAC - Macros for list handling
Documentation:
    OVERVIEW
    This macro file provides a set of functions to handle lists of elements with optional parameters.
    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).
    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).
    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.

    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.
    if LIST[] is the associative array that holds the list, the following expressions can be used:
    • (LIST[0]) evaluates to the number of elements in the list.
    • (elem in LIST) is true if the string elem is a valid element.
    • (LIST[n]) returns the element in position n (>0).
    • (LIST[elem][par]) returns the value of the parameter par of element elem.


    ATTENTION
    This macro set overrides some macros previously included in stlocal.mac.

    EXAMPLE
    list_add(mylist, \"el1\")
    Adds the element "el1" to the list stored in the associative array mylist.
    list_add(mylist, \"el1\", \"par1\")
    Adds the parameter "par1" to the item "el1".
    list_setpar(mylist, \"el1\", \"par1\", 5312)
    Sets the parameter "par1" of the item "el1" to 5312.
    list_list(mylist)
    Prints on the screen the current content of the list mylist.


    DEPENDENCIES
    No dependencies

Macros:
    list_test
    Usage: list_test <list>
    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.

    list_init
    Usage: list_init <list>
    This macro clears and iniatilises <list> to contain a list. The information contained (if any) is lost.

    list_n
    Usage: list_n (<list>)
    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.

    list_check
    Usage: list_check (<list>, <item>)
    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.
    <list> must be an associative array (old-style array), if not the function returns -1.
    <item> is either a string or a number. If a number is used it refers to the position of the element in the list.

    list_add
    Usage: list_add (<list>, <item>)
    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.
    The function returns the position in the list of the element recently added. This value is always the size of the list.
    <item> cannot be a numeric value.
    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.

    list_splitadd
    Usage: list_splitadd (<list>, <string> [,<separator>])
    This function adds new elements to <list> in the same way than list_add but several elements can be appended in the same function call. The element specifiers are obtained by spliting <string> by means of the spec function split(). If no <separator> is specified space characters are used as delimiters.
    The function returns the number of elements added to the list. If an error happens -1 is returned and <list> is not modified.

    list_setpar
    Usage: list_setpar (<list>, <item>, <param>, <value>)
    This function sets the value of a parameter for a particular element in a list.
    <list> and <item> must follow the rules explained for the function
    list_check()
    . <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.
    If no error is found, the function returns 1, otherwise it returns -1.

    list_getparlist
    Usage: list_getparlist (<list>, <item>, <param_list>)
    This function creates an auxiliary list that contains all the parameters associated to a given element in a list.
    <list> and <item> must follow the rules explained for the function
    list_check()
    . 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>.
    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.

    list_getpar
    Usage: list_getpar (<list>, <item>, <param>)
    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
    list_setpar()
    . If an error is found the function returns -1.

    list_removepar
    Usage: list_removepar (<list>, <item> [, <param>])
    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.

    list_remove
    Usage: list_remove (<list>, <item>)
    This function deletes a particular element in a list and returns its position in the list before deletion.
    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.


    list_item
    Usage: list_item (<list>, <item>)
    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).


    list_list
    Usage: list_list (<list>)
    This function prints on the screen all the elements in a list along with the associated parameters. It is intended for debugging purposes.
    It returns the number of eleemnts in the list or -1 if an error happens.

Internal Macros:
Filename: stlist.mac
Author: P. Fajardo, (Original 3/96 in stlocal.mac).
$Revision: 1.1 $ / $Date: 2008/11/17 12:39:27 $
Last mod.: 17/11/2008 13:37 by guilloud