Extract elements from recreation string of a control

//=========================================================================================================
// recExtract
// -----------
//       'recExtract' is a service function for extracting simple keyword pairs from the 
//       S_Recreation string returned by 'controlInfo'.  This saves extracting using 'execute'
//       directly where the S_Recreation string may overflow the command line buffer of 'execute'.
//       It is not able to extract multiline elements such as 'userdata[(name)]' but this has its
//       own Igor function (getUserdata). 
//
//       ARGUMENTS:
//        - win:       window of the calling control
//        - ctrl:      name of the calling control
//        - iStr:      keyword to be extracted.
//        - trim:      if present, the character[s] in 'trim' will be removed from the beginning
//                        and end of the result string, if they are present.  Useful for trimming
//                        the " character when assigning to a string variable.  If there are two
//                        characters, e.g. "{}", the first will be trimmed from the start of the
//                        string and the second from the end.  Further characters are ignored.
//        - [listSep]: Optional. If present the default list separator of ',' is changed to this,
//                        allowing grouped parameters like {var,var,var} to be matched: see below.
//
//       RETURNS:   The value of the string requested (or numerical value as a string)
//
//       SOURCES:   Patrick Groenestein 2006, WaveMetrics Igor 5 Help.
//
//--------------------------------+------------------------------------------------------------------------
static FUNCTION/S recExtract(win,ctrl,iStr,trim[,listSep])
    string                        ctrl,win,iStr,trim,listSep;
    
    variable                       i,n,pos;
    string                         rStr="",rec,sep,add="";
    
    sep = "\r";
    if(paramIsDefault(listSep))
        listSep = ",";              
                              // allows a kludge: if the parameter is of the form key=(value,value,value)
                              // like a colour definition or key={value,value} then the string won't match,
                              // as the list separator will get only the first element of the sublist.
                              // By redefining the list separator to the closing container ')' or '}' for 
                              // example, the correct element is extracted, and can still be cleaned up
                              // with the 'trim' parameter.
                              //
    else
        add = listSep;
    endif;
 
    controlInfo/W=$win $ctrl;
    for(i=0,n=itemsInList(S_Recreation,sep) ; i<n ; i+=1)
        rec = stringFromList(i,S_Recreation,sep);
        if(strlen(rec))
            pos = strsearch(rec,iStr,0,2);
            if(pos>=0)
                rStr += stringByKey(iStr,rec[pos,min(strlen(rec)-1,pos+1000)],"=",listSep,0);
                break;
            endif;
        endif;
    endfor;
    
    n = strlen(trim);
    if(n)
        if(stringMatch(rStr[0],trim[0]))
            rStr[0,0] = "";
        endif;
        rStr = removeEnding(rStr,selectstring(n>1,trim[0],trim[1]));
    endif;
    
    return(rStr);
END