FUNCTION READ_TABLE, filename, $
    columns=columns, nrows=nrows, nmax=nmax, double=double, text=text, head=head

; ----------------------------------------------------------
;+
; NAME:
;       READ_TABLE
;
; PURPOSE:
;       Read an ASCII table into a data array.
;
; AUTHOR:
;       Simon Vaughan (U.Leicester)
;
; CALLING SEQUENCE:
;       data = READ_TABLE('file.dat')
;
; INPUTS:
;       file - (string) file name 
;
; OPTIONAL INPUTS:  
;       columns - (integer vector) which columns of table to retain 
;       nrows   - (integer) number of lines to read 
;       nmax    - (integer) minimum size of file, default is 100,000
;       double  - (logical) whether to use double or single prec.
;       text    - (logical) whether to load text from file       
;       head    - (integer) number of lines to skip in header
;
; OUTPUTS:
;       2-dimensional data array (floating point values)
;
; DETAILS:
;       Data are assumed to be floating point numbers, by
;       default single precision, seperated by spaces in a
;       rectangular grid (ncols*nrow)
;
; Example calls:
;
; IDL> data = read_table('table.txt')
; IDL> data = read_table('table.txt',columns=[2,3])
; IDL> data = read_table('table.txt',n=100)
;
; HISTORY:
;       Based losely on DDREAD.PRO by Frank Knight (MIT)
;       11/01/2007 -  v1.0  - first working version
;       27/04/2007 -  v1.1  - added TEXT option
;       22/11/2007 -  v1.2  - added HEAD option
;       22/09/2008 -  v1.3  - HEAD now takes integer input
;       16/06/2010 -  v1.4  - fixed handling of text input
;                             using STRSPLIT function.
;
;-
; ----------------------------------------------------------

; options for compilation (recommended by RSI)

  COMPILE_OPT idl2

; watch out for errors
  on_error,2

; ----------------------------------------------------------
; Check the arguments

; is the file name defined?
  if (n_elements(filename) eq 0) then begin
      filename=''
      read,'-- Enter file name (ENTER to list current directory): ',filename
      if (filename eq '') then begin
          list = findfile()
          print, list
          read,'-- Enter file name: ',filename
      endif
  endif

; is there a user-defined maximum file size?
  if (n_elements(nmax) eq 0) then nmax=100000L

; is there a user-defined number of lines to read
  if (n_elements(nrows) eq 0) then nrows=nmax

; sanity check
  if (nrows gt nmax) then nmax = nrows

; are we reading in single (=4) or double precision (=5)?
  type=4
  if (keyword_set(double)) then type=5

; are we reading numbers or text?
  if (keyword_set(text)) then type=7

; ----------------------------------------------------------
; Checks of the file existance and shape

; check the file exists
  if ((findfile(filename))[0] eq '') then begin
      print,'** File not found.'
      return,0
  endif

; find the number of columns in the file by reading first line
; into a string (tmp)
  ncols = 0
  tmp = ''
  openr, lun, filename, /get_lun
  if keyword_set(head) then begin
      for i=0,head-1 do readf, lun, tmp ; skip header
  endif
  readf,lun,tmp
  free_lun, lun

; remove whitespace
  tmp = ' ' + strcompress(strtrim(tmp,2))

; count the spaces (there is one per column)
  for i=0,strlen(tmp)-1 do begin
      ncols = ncols + (strpos(tmp,' ',i) eq i)
  end

; ----------------------------------------------------------
; load the data into an array

; define the data array ready to receive data

  data = make_array(size=[2,ncols,nrows,type,ncols*nrows])

; define a single line (row) array for reading each line
; except for text which is loaded a whole line at a time 

  if NOT KEYWORD_SET(text) then begin
      record = make_array(size=[1,ncols,type,ncols])
  endif else begin
      record = ''
  endelse

; Open the file ready to read

  openr, lun, filename, /get_lun

; skip header line if HEAD keyword is set

  if keyword_set(head) then begin
      for i=0,head-1 do readf, lun, tmp ; skip header
  endif

; Read each line one at a time, until either end-of-file
; or we reach nrows.

  n = 0L
  while (eof(lun) ne 1) do begin
      on_ioerror, IOERR
      error = 1
      readf, lun, record
;      print,record
;      help,record
      error = 0
      if KEYWORD_SET(text) then begin
          data[*,n] = STRSPLIT(record, ' ', /EXTRACT)
      endif else begin
          data[*,n] = record
      endelse
      n = n + 1L
      if (n eq nrows) then break

      IOERR:
      if (error eq 1) then begin
          print, '** Error reading line',n,' in READ_TABLE'
          free_lun,lun
          return,0
      endif

  endwhile

; Did we finish with the file or run out of rows in array?
  if (eof(lun) ne 1 && n ge nmax) then begin
      print,"** Increase nmax in READ_TABLE."
  endif

; Close the file
  free_lun, lun

; ----------------------------------------------------------
; Return the data array to the user

; trim the unused rows
  data = data[*,0:(n-1)]

; if no column selection, return entire array 
  if (n_elements(columns) eq 0) then return, data

; otherwise remove unwanted columns before returning
  indx=where((columns ge ncols-1),count)
  if (count eq 0) then begin
      data = data[columns,*]
  endif else begin
      print,'** Requested columns outside allowed range'
      print,'** Returning all columns from READ_TABLE'
  endelse

  return,data

END
; ----------------------------------------------------------