Read list

Purpose: Read/update key/value pair from a linked list.

 read-list <list> \
     key <key> \
     value <value> \
     [ update-value <update value> ] [ update-key <update key> ] \
     [ status <status> ]

read-list retrieves an element from the linked <list>, storing it into <key> string (in "key" clause) and <value> string (in "value" clause). After each read-list, the list's current element remains at the element read; use position-list to move it (for instance to the next one).

If an element could not be retrieved, <status> number (in "status" clause) will be GG_ERR_EXIST and <key> and <value> will be unchanged (this can happen if current list element is beyond the last element, such as for instance if "end" clause is used in position-list statement), otherwise <status> is GG_OKAY.

Initially when the list is created with new-list, read-list starts with the first element in the list. Use position-list to change the default list's current element.

You can update the element's value with "update-value" clause by specifying <update value> string. This update is performed after a <value> has been retrieved, allowing you to obtain the previous value in the same statement.

You can update the element's key with "update-key" clause by specifying <update key> string. This update is performed after a <key> has been retrieved, allowing you to obtain the previous key in the same statement.

Examples

In this example, a linked list is created, and three key/value pairs added. They are then retrieved from the last towards the first element, and then again in the opposite direction:

 new-list mylist

 // Add data to the list
 write-list mylist key "key1" value "value1"
 write-list mylist key "key2" value "value2"
 write-list mylist key "key3" value "value3"

 position-list mylist last
 start-loop
    // Get data from the list starting with the last one, producing value1, value2, value3
    read-list mylist key k value v
    @Obtained key <<p-out k>> with value <<p-out v>>
    position-list mylist previous status s
    // Check if no more data
    if-true s equal GG_ERR_EXIST
        break-loop
    end-if
 end-loop

 // Now the list is positioned at the first element, reading produces value3, value2, value1
 start-loop
    read-list mylist key k value v status s
    if-true s equal GG_ERR_EXIST
        break-loop
    end-if
    @Again obtained key <<p-out k>> with value <<p-out v>>
    position-list mylist next
 end-loop

 purge-list mylist