keylist(3Tcl)

NAME
     Tcl_GetKeyedListKeys, Tcl_GetKeyedListField, Tcl_SetKeyedListField,
     Tcl_DeleteKeyedListField - Keyed list management routines.

SYNOPSIS
     #include <tclExtend.h>

     int
     Tcl_GetKeyedListKeys (Tcl_Interp  *interp,
                           const char  *subFieldName,
                           const char  *keyedList,
                           int         *keyesArgcPtr,
                           char      ***keyesArgvPtr);

     int
     Tcl_GetKeyedListField (Tcl_Interp  *interp,
                            const char  *fieldName,
                            const char  *keyedList,
                            char       **fieldValuePtr);

     char *
     Tcl_SetKeyedListField (Tcl_Interp  *interp,
                            const char  *fieldName,
                            const char  *fieldvalue,
                            const char  *keyedList);

     char *
     Tcl_DeleteKeyedListField (Tcl_Interp  *interp,
                               const char  *fieldName,
                               const char  *keyedList);

DESCRIPTION
     These routines perform operations on keyed lists.  See the Extended Tcl
     man page for a description of keyed lists.

   Tcl_GetKeyedListKeys
     Retrieve a list of keyes from a keyed list.  The list is walked rather
     than converted to a argv for increased performance.

     Parameters:
       o interp - Error message will be return in result if there is an error.
       o subFieldName - If "" or NULL, then the keys are retreved for the top
       level of the list.  If specified, it is name of the field who's
       subfield keys are to be retrieve.
       o keyedList - The list to search for the field.
       o keyesArgcPtr - The number of keys in the keyed list is returned here.
       o keyesArgvPtr - An argv containing the key names.  It is dynamically
       allocated, containing both the array and the strings. A single call to
       ckfree will release it.

     Returns:
       TCL_OK if a list of keys is returned, TCL_BREAK if the field was not
       found, or TCL_ERROR if an error occured.

   Tcl_GetKeyedListField
     Retrieve a field value from a keyed list.  The list is walked rather than
     converted to a argv for increased performance.  This if the name contains
     sub-fields, this function recursive.

     Parameters:
       o interp - Error message will be return in result if there is an error.
       o fieldName - The name of the field to extract.  Will recusively
       process sub-field names seperated by `.'.
       o keyedList - The list to search for the field.
       o fieldValuePtr - If the field is found, a pointer to a dynamicly
       allocated string containing the value is returned here.  If NULL is
       specified, then only the presence of the field is validated, the value
       is not returned.

     Returns:
       TCL_OK if the field was found,  TCL_BREAK if the field was not found or
       TCL_ERROR if an error occured.

   Tcl_SetKeyedListField
     Set a field value in keyed list.

     Parameters:
       o interp - Error message will be return in result if there is an error.
       o fieldName - The name of the field to extract.  Will recusively
       process sub-field names seperated by `.'.
       o fieldValue - The value to set for the field.
       o keyedList - The keyed list to set a field value in, may be an NULL or
       an empty list to create a new keyed list.

     Returns:
       A pointer to a dynamically allocated string, or NULL if an error
       occured.

   Tcl_DeleteKeyedListField
     Delete a field value in keyed list.

     Parameters:
       o interp - Error message will be return in result if there is an error.
       o fieldName - The name of the field to extract.  Will recusively
       process sub-field names seperated by `.'.
       o fieldValue - The value to set for the field.
       o keyedList - The keyed list to delete the field from.

     Returns:
       A pointer to a dynamically allocated string containing the new list, or
       NULL if an error occured.