source: trunk/SRC/ToBeReviewed/STRING/getfile.pro @ 495

;+
;
; @file_comments
; Read a text file into a string array.
;
; @param filein {in}{required}
; text file name.
;
; @keyword ERROR
; error flag: 0=ok, 1=file not opened, 2=no lines in file.
;
; @keyword QUIET
; means give no error message.
;
; @keyword LINES
; Number of lines to read (def=all).
; Much faster if number of lines is known.
; Automatic for IDL 5.6 or later.
;
; @keyword FIND
; search the file in the all !path directories (use <pro>find</pro>)
;
; @keyword HELP
;
; @returns
;
; @history
;  - R. Sterner, 20 Mar, 1990
;  - R. Sterner, 1999 Apr 14 --- Added LINES=n keyword.
;  - R. Sterner, 2003 Aug 29 --- Automatic lines if IDL 5.6+.
;  - R. Sterner, 2003 Sep 02 --- Check if file exists first.
;  - R. Sterner, 2003 Sep 04 --- Fixed error in number of lines in file.
;  - R. Sterner, 2003 Oct 10 --- Fixed error when no lines.
;  - R. Sterner, 2004 Jan 27 --- Fixed to work in IDL as old as vers 4.
;  - S. Masson (smasson\@lodyc.jussieu.fr) 4 Feb 2002
;
;       search the file in the all !path directories (use <pro>find</pro>)
;       when using /find keyword. Use <proidl>SPAWN</proidl>, 'cat...' for
;       unix os.
;
; Copyright (C) 1990, Johns Hopkins University/Applied Physics Laboratory
; This software may be used, copied, or redistributed as long as it is not
; sold and this copyright notice is reproduced on each copy made.  This
; routine is provided as is without any express or implied warranties
; whatsoever.  Other limitations apply as described in the file disclaimer.txt.
;
; @version
; $Id$
;
;-
FUNCTION getfile, filein, ERROR=err $
                , HELP=hlp, QUIET=quiet, LINES=lines, FIND=find
;
  compile_opt idl2, strictarrsubs
;

if (n_params(0) lt 1) or keyword_set(hlp) then begin
ras = report([ $
          ' Read a text file into a string array.', $
' s = getfile(f)', $
'   f = text file name.      in', $
'   s = string array.        out', $
' Keywords:', $
'   ERROR=err  error flag: 0=ok, 1=file not opened,', $
'     2=no lines in file.', $
'   /QUIET means give no error message.', $
'   LINES=n  Number of lines to read (def=all).', $
'     Much faster if number of lines is known.', $
'     Automatic for IDL 5.6 or later.'])
return, -1
endif
;
        if keyword_set(find) then begin
          file = find(filein)
          file = file[0]
          if file EQ 'NOT FOUND' then begin
            print, ' Error in getfile: File '+filein+' not found.'
            return, -1
          endif
        ENDIF ELSE file = filein

        if (!version.release+0. ge 5.5) then begin
          f = call_function('file_search', file, count = c)
        endif else begin
          f = findfile(file,count=c)
        endelse
        if c eq 0 then begin
          err = 1
          return,''
        endif

        if n_elements(line) eq 0 and (!version.release+0. ge 5.6) then begin
          lines = file_lines(file)
          if lines eq 0 then begin
            if not keyword_set(quiet) then print,' No lines in file.'
               err = 2
               return,-1
          endif
          minlines = 0
        endif else minlines=1

        get_lun, lun
        on_ioerror, err
        openr, lun, file

        if n_elements(lines) ne 0 then begin
          s = strarr(lines)
          readf,lun,s
        endif else begin
          s = [' ']
          t = ''
          while not eof(lun) do begin
            readf, lun, t
            s = [s,t]
          endwhile
        endelse

        close, lun
        free_lun, lun
        if n_elements(s) eq minlines then begin
          if not keyword_set(quiet) then print,' No lines in file.'
          err = 2
          return,-1
        endif
        if minlines eq 1 then s=s[1:*]

        err = 0
        return, s

err:    if !err eq -168 then begin
         if not keyword_set(quiet) then print,' Non-standard text file format.'
         free_lun, lun
         return, s
        endif
        if not keyword_set(quiet) then print,$
         ' Error in getfile: File '+file+' not opened.'
        free_lun, lun
        err = 1
        return, -1

        end