;+
;
; @file_comments
; same as <pro>find</pro> except that as long as the file is 'NOT FOUND',
; <pro>isafile</pro> calls 
; <proidl>dialog_pickfile</proidl>, to ask the user to select a file.
;
; @categories
; io
;
; @param FILEIN {in}{optional}
; a proposed name. If neither filein input parameter of filename keyword are
; defined, we ask the user to choose a file.
;
; @keyword FILENAME
; a proposed filename.
;
; @keyword IODIRECTORY
; a directory where we look for the file. this
; keyword is taken into account only if the dirname
; of filein or filename is '.'
;
; @keyword NEW
; to specify that filename is a new file and that we should check only its
; path
;
; @keyword ONLYPRO
; force to look only at file ending with .pro
;
; @keyword ONLYNC
; force to look only at file ending with .nc
;
; @keyword RECURSIVE
; performs recursive searching of directory hierarchies.
; In a recursive search, <pro>find</pro> looks recursively for any and all
; subdirectories in the file hierarchy rooted at the IODIRECTORY argument.
;
; @keyword _EXTRA
; Used to pass keywords to <pro>find</pro>,
; <proidl>file_search</proidl> and
; <proidl>dialog_pickfile</proidl>
;
; @returns
; the filename with its path
;
; @examples
; 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')
;
; @history
; Sebastien Masson (smasson\@lodyc.jussieu.fr)
;                      11/2/2000
; June 2005: Sebastien Masson: cleaning, use for file_* functions
;
; @version
; $Id$
;
;-
;
FUNCTION isafile, filein, FILENAME = filename, IODIRECTORY = iodirectory $
                  , NEW = new, RECURSIVE = RECURSIVE, ONLYPRO = onlypro $
                  , ONLYNC = onlync, _EXTRA = ex
;
  compile_opt idl2, strictarrsubs
;
  CASE 1 OF
    (size(filein, /type))[0] EQ 7:fileout = filein
    keyword_set(filename):fileout = filename[0]
    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 fileout NE dirname+'/'+basename AND dirname EQ '.' AND NOT keyword_set(iodirectory) then 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