;+
;
; @file_comments
; Read a text file into a string array.
;
; @param filein {in}{required}
; text file name.
;
; @keyword ERROR
; =err error flag: 0=ok, 1=file not opened,
; 2=no lines in file.
;
; @keyword QUIET
; means give no error message.
;
; @keyword LINES
; =n 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
; 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 find)
; when using /find keyword. Use SPAWN, '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