;------------------------------------------------------------
;------------------------------------------------------------
;------------------------------------------------------------
;+
; NAME: isafile
;
; PURPOSE: same as find.pro except that as long as the file is 'NOT FOUND',
;          isafile calls dialog_pickfile, to ask the user to select a file.
;
; CATEGORY: io
;
; CALLING SEQUENCE:filename = isafile([filein])
; 
; INPUTS:optional:a proposed name. If neither filein
;        input parameter of filename keyword are defined,
;        the ask the user to choose a file.
;
; KEYWORD PARAMETERS:
;
;     FILENAME: a proposed filename.
;
;     IODIRECTORY: a directory where we look for the file. this
;           keyword is taken into account only if the dirmame
;           of filein or filename is '.'
;
;     /NEW:to specify that filename is a new file and that
;        we should check only its path
;
;     ONLYPRO:force to look only at file ending with .pro
;
;     ONLYNC:force to look only at file ending with .nc
;
;     RECURSIVE: performs recursive searching of directory hierarchies.
;        In a recursive search, find looks recursively for any and all 
;        subdirectories in the file hierarchy rooted at the IODIRECTORY
;        argument. 
;
;     all find, file_search and dialog_pickfile keywords (like title)
;
; OUTPUTS:the filename with its path
;
; COMMON BLOCKS:none
;
; SIDE EFFECTS:
;
; RESTRICTIONS:
;
; EXAMPLE:
;
;  IDL> print, isafile('/Users/sebastie/SAXO_RD/Commons/cm_4mesh.pro')
;  /Users/sebastie/SAXO_RD/Commons/cm_4mesh.pro
;  IDL> print, isafile('cm_4mesh.pro', iodir = '/Users/sebastie/SAXO_RD/Commons')
;  /Users/sebastie/SAXO_RD/Commons/cm_4mesh.pro
;  IDL> print, isafile('cm_4mesh.pro', iodir = !path)
;  /Users/sebastie/SAXO_RD/Commons/cm_4mesh.pro
;  IDL> print, isafile('cm_4mesh.pro', iodir = '/Users/sebastie/SAXO_RD', /recursive)
;  /Users/sebastie/SAXO_RD/Commons/cm_4mesh.pro
;  IDL> print, isafile('cm_4mesh.pro', iodir = getenv('HOME'), /recursive)
;  /Users/sebastie/SAXO_RD/Commons/cm_4mesh.pro
;  IDL> print, isafile('fake_file.pro')
;
; MODIFICATION HISTORY:Sebastien Masson (smasson@lodyc.jussieu.fr)
;                      11/2/2000
; June 2005: Sebastien Masson: cleaning, use for file_* functions
;-
;------------------------------------------------------------
;------------------------------------------------------------
;------------------------------------------------------------
FUNCTION isafile, filein, FILENAME = filename, IODIRECTORY = iodirectory $
                  , NEW = new, RECURSIVE = RECURSIVE, ONLYPRO = onlypro $
                  , ONLYNC = onlync, _extra = ex
;------------------------------------------------------------
  CASE 1 OF
    (size(filein, /type))[0] EQ 7:fileout = filein
    keyword_set(filename):fileout = filename
    ELSE:fileout = 'file that is not existing'
  ENDCASE
  if size(fileout, /type) NE 7 THEN return, -1
;
  CASE 1 OF
    keyword_set(onlypro): filter = '*.pro'
    keyword_set(onlync): filter = '*.nc'
    else: filter = '*'
  ENDCASE
;
  basename = file_basename(fileout)
  dirname = file_dirname(fileout)
; should we redefine dirname?
  if keyword_set(iodirectory) AND dirname EQ '.' then dirname = iodirectory
;
  if keyword_set(new) then return, dirname + path_sep() + basename
;
  fileout = find(basename, iodirectory = dirname $
                 , recursive = recursive, /unique, /firstfound, ONLYPRO = onlypro $
                 , ONLYNC = onlync, _extra = ex)
  WHILE fileout[0] EQ 'NOT FOUND' DO BEGIN
    fileout = dialog_pickfile(path = dirname[0], filter = filter, _extra = ex)
    if fileout EQ '' THEN RETURN, report('check/find file canceled')
; check again everything...
    basename = file_basename(fileout)
    dirname = file_dirname(fileout)
; check if the name of the dirname is ok
    dirname = isadirectory(dirname, title = 'choose a directory for the file ' $
                           + basename)
; if we cancel the check
    IF size(dirname, /type) NE 7 THEN return, report('check/find file canceled')
    fileout = find(basename, iodirectory = dirname $
                   , recursive = recursive, /unique, /firstfound, ONLYPRO = onlypro $
                   , ONLYNC = onlync, _extra = ex)
  ENDWHILE
;
  RETURN, fileout
END