PRO write_table, data, filename, width=width, double=double, header=header, $
                                 _EXTRA=EXTRA_KEYWORDS

; ----------------------------------------------------------
;+
; NAME:
;       WRITE_TABLE
;
; PURPOSE:
;       Write a data array to an ASCII table file.
;
; AUTHOR:
;       Simon Vaughan (U.Leicester)
;
; CALLING SEQUENCE:
;       WRITE_TABLE, data, filename='file.dat'
;
; INPUTS:
;       data    - (array) 1 or 2 dimensional data array
;       file    - (string) file name
;
; OPTIONAL INPUTS:
;       width   - (integer) width of lines in characters
;       double  - (logical) whether to use double prec. format
;       header  - (string) optional file header info
;
; OUTPUTS:
;       ASCII file
;
; DETAILS:
;       The 1d or 2d 'data' array is written to an ASCII file.
;       If 1-dimensional it is written as a column vectors,
;       otherwise the array is written 'as is'.
;       If there are many columns the width parameter may
;       need to be increased to fit the columns on one line.
;       Note, data are simple type - ie: all floating point,
;       all integers, etc... no mixing is allowed (yet).
;
;       Using the DOUBLE keyowrd will force all columns to
;       be printed in double precision format.
;
;       If more specific formats are needed, they may be
;       passed using the _EXTRA keyword (with DOUBLE not set).
;
; EXAMPLE CALL:
;  IDL> write_table,double(x),'temp.txt',/double
;
; HISTORY:
;       01/02/2007 -  v1.0  - first working version
;       27/04/2007 -  v1.1  - added EXTRA and DOUBLE options
;       05/04/2012 -  v1.2  - added HEADER keyword
;
;-
; ----------------------------------------------------------

; watch out for errors
  on_error,2

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

  if (n_elements(data) eq 0) then begin
      print,'** No data in WRITE_TABLE.'
      return
  endif

; supply default filename if none supplied
  if (n_elements(filename) eq 0) then filename='idl.out'

; supply default width if none supplied
  if (n_elements(width) eq 0) then width=150

; ----------------------------------------------------------
; Prepare for writing data array

; determine dimensions of data array
  s = size(data)
  d = s[0]

  if (d eq 2) then begin
      m=s[1]                    ; columns if 2d
      n=s[2]                    ; rows 
      type=s[3]                 ; variable type
  endif else begin
      m=1
      n=s[1]                    ; rows if 1d
      type=s[2]                 ; variable type
  endelse

  if (d gt 2) then begin
      print,'** Data array has >2 dimensions in WRITE_TABLE.'
      return
  endif

; ----------------------------------------------------------
; Open ASCII file, write data, then close file

  openw,lun,filename,/get_lun,width=width

  if KEYWORD_SET(header) then begin
      printf, lun, header
  endif

  if keyword_set(double) then begin

      if (d eq 2) then begin
          printf, lun, data, format='('+strtrim(m,2)+'(d30.15))',_extra=extra_keywords
      endif
      if (d eq 1) then begin
          printf, lun, transpose(data), format='(d)', _extra=extra_keywords
      endif

  endif else begin

      if (d eq 2) then begin
          printf, lun, data, _extra=extra_keywords
      endif
      if (d eq 1) then begin
          printf, lun, transpose(data), _extra=extra_keywords
      endif

  endelse

  free_lun,lun

; ----------------------------------------------------------
; Return to user

END