;+
; NAME:
;  lexecute
; PURPOSE: (one line)
;  execute a potentially long string
; DESCRIPTION:
;  execute a string that is too long for the intrinsic execute
; CATEGORY:
;  util
; CALLING SEQUENCE:
;  lexecute, str, newsav, oldsav=oldsav, <keyword=keyword>
; INPUTS:
;  str - the (potentially long) string or array of strings to execute
; OPTIONAL INPUT PARAMETERS:
;  none
; KEYWORD INPUT PARAMETERS:
;  oldsav - a save file, if lexecute needs to get passed inputs
; KEYWORD OUTPUT PARAMETERS:
;  none
; OUTPUTS:
;  newsav - a save file, if lexecute needs to pass outputs
; COMMON BLOCKS:
;  None
; SIDE EFFECTS:
;  writes the file <tmp>/<newsave>
; RESTRICTIONS:
;  If you must use the following characters within strings,
;  make sure the strlen of str is < 160:
;  &,()[]+-*/^ 
;
;  The method of passing by reference doesn't seem to work.
; 
; PROCEDURE:
; USAGE
;  There are several ways to use this function
;  
;  If no variables have to be passed, then simply call
;  lexecute,str
;
;  If just a few variables have to be passed
;  (eg str uses in1 and in2, assigns out1 and out2), then use keywords
;  lexecute,str,in1=in1,in2=in2, out1=out1, out2=out2
;
;  If many variable have to be passed, 
;  or you don't know ahead of time what variables are used in str,
;  then use save files
;  oldsav=tmpfile('','sav') ; get a temporary sav filename
;  save,/all,fil=oldsav     ; save variables
;  lexecute,str,newsav,lexecute_oldsav=oldsav ; run, saving calcs in newsav
;  restore,newsav           ; restore newsav
;  file_delete,newsav       ; cleanup
; MODIFICATION HISTORY:
;  2005 Dec 30 Leslie Young, SwRI
;  2006 Jan  2 LAY, restored value of !quiet before executing proc
;  2007 Mar 09 LAY.  IDL_NOCACHE doesn't seem to be enough?
;      added call to idl_cache,/clear
;-

pro lexecute, str, newsav, lexecute_oldsav=oldsav, lexecute_keepproc=keepproc,$
              _ref_extra=extra

    ; get the filenames
    fnpro = tmppro('lexecute')
    fdecomp, fnpro, disk, dir, proc ;get the procedure name

    ; open the file and write preliminaries
    openw,lun, fnpro, /get_lun, width=max(strlen(str))+1L
    if keyword_set(extra) then begin
        printf, lun, 'pro ' + proc + ', $'
        nkey = n_elements(extra)
        for i=0, nkey-2 do begin
            printf, lun, extra[i] + '=' + extra[i] + ', $'
        endfor
        printf, lun, extra[nkey-1] + '=' + extra[nkey-1]
    endif else begin
        printf, lun, 'pro ' + proc
    endelse
    printf, lun, ''

    ; Restore oldsav to define existing parameters
    if keyword_set(oldsav) then begin
        printf, lun, 'restore, ' + "'"+oldsav+"'"
    end

    ; write the strings
    maxbuf = 160
    eol = string([38B, 10B, 13B])    ; split the string at &, CR, or LF
    eotok = ',[]()=+-*/^'
    nstr = n_elements(str)
    for i=0,nstr-1 do begin
        s = strtrim(str[i],2)
        if strlen(s) le maxbuf then begin
            printf, lun, s
        endif else begin
            ; string too long, break it up at line ends
            str2 = strsplit(s, eol, /extract)
            nstr2 = n_elements(str2)
            for j=0,nstr2-1 do begin
                s2 = strtrim(str2[j],2)
                if strlen(s2) le maxbuf then begin
                    printf, lun, s2
                endif else begin
                    ; string too long, break it up at token ends
                    pos = strsplit(s2,eotok,len=len)
                    ntok = n_elements(pos)
                    for k = 0, ntok-2 do begin
                        s3 = strtrim(strmid(s2,pos[k], len[k]+1),2)
                        printf, lun, s3 + '$'
                    endfor
                    k = ntok-1
                    s3 = strtrim(strmid(s2,pos[k], len[k]+1),2)
                    printf, lun, s3
                endelse
            endfor 
        endelse
    endfor

    if n_params() gt 1 then begin
        newsav = tmpfile('lexecute','sav')
        printf, lun, 'save, /comm, /variables, file = ' + "'" + newsav + "'"
    end
    
    ; write the ending parts and close the file
    printf, lun, ''
    printf, lun, 'end'
    close,lun
    free_lun, lun

    ; execute the file
    quiet = !quiet
    !quiet = 1
    path_cache,/clear
    resolve_routine, proc
    !quiet = quiet
    if keyword_set(extra) then begin
        r = execute(proc + ', _extra=extra')
    endif else begin
        r = execute(proc)
    endelse

    if not keyword_set(keepproc) then file_delete, fnpro

end