conditionally disable the extended filename parser (#174)

* support for extended filename parser

* improve docstrings

* generalize signature of FITS(::Function, ..)

* Remove unused keyword arguments

Project.toml

@@ -10,7 +10,7 @@ Tables = "bd369af6-aec1-5ad0-b16a-f7cc5008161c"
 
 [compat]
 Aqua = "0.5"
-CFITSIO = "1.2"
+CFITSIO = "1.3"
 Reexport = "0.2, 1.0"
 Tables = "1"
 julia = "1.3"

src/FITSIO.jl

@@ -41,7 +41,9 @@ import Base: iterate, lastindex
 import CFITSIO: FITSFile,
                 FITSMemoryHandle,
                 fits_open_file,
+                fits_open_diskfile,
                 fits_create_file,
+                fits_create_diskfile,
                 fits_assert_open,
                 fits_file_mode,
                 fits_create_img,
@@ -136,7 +138,7 @@ end
 # as deleting extensions. This could be done by, e.g., setting ext=-1
 # in the HDU object.
 """
-    FITS(filename::String, mode::String="r")
+    FITS(filename::String[, mode::String = "r"]; extendedparser = true)
 
 Open or create a FITS file. `mode` can be one of `"r"` (read-only),
 `"r+"` (read-write) or `"w"` (write). In "write" mode, any existing
@@ -157,6 +159,11 @@ supports the following operations:
       ...
   end
   ```
+
+The keyword argument `extendedparser` may be used to enable or disable the
+[extended filename parser](https://heasarc.gsfc.nasa.gov/docs/software/fitsio/c/c_user/node83.html).
+If disabled, `filename` is treated exactly as the name of the file and is not tokenized into
+parameters.
 """
 mutable struct FITS
     fitsfile::FITSFile
@@ -168,11 +175,14 @@ mutable struct FITS
     memhandle::FITSMemoryHandle
     hidden::Any
 
-    function FITS(filename::AbstractString, mode::AbstractString="r")
-        f = (mode == "r"                      ? fits_open_file(filename, 0)    :
-             mode == "r+" && isfile(filename) ? fits_open_file(filename, 1)    :
-             mode == "r+"                     ? fits_create_file(filename)     :
-             mode == "w"                      ? fits_create_file("!"*filename) :
+    function FITS(filename::AbstractString, mode::AbstractString="r"; extendedparser = true)
+        openfn = extendedparser ? fits_open_file : fits_open_diskfile
+        createfn = extendedparser ? fits_create_file : fits_create_diskfile
+        f = (mode == "r"                      ? openfn(filename, 0)    :
+             mode == "r+" && isfile(filename) ? openfn(filename, 1)    :
+             mode == "r+"                     ? createfn(filename)     :
+             mode == "w"                      ?
+                (rm(filename, force = true); createfn(filename)) :
              error("invalid open mode: $mode"))
 
         new(f, filename, mode, Dict{Int, HDU}(), FITSMemoryHandle(), nothing)
@@ -186,13 +196,13 @@ mutable struct FITS
 end
 
 """
-    FITS(f::Function, args...)
+    FITS(f::Function, args...; kwargs...)
 
-Apply the function `f` to the result of `FITS(args...)` and close the
+Apply the function `f` to the result of `FITS(args...; kwargs...)` and close the
 resulting file descriptor upon completion.
 """
-function FITS(f::Function, args...)
-    io = FITS(args...)
+function FITS(f::Function, args...; kwargs...)
+    io = FITS(args...; kwargs...)
     try
         f(io)
     finally

src/image.jl

@@ -69,29 +69,34 @@ Return the element type of the image in `hdu`.
 eltype(::ImageHDU{T}) where T = T
 
 """
-    fitsread(filename::AbstractString, hduindex = 1, arrayindices...)
+    fitsread(filename::AbstractString[, hduindex = 1[, arrayindices...]]; extendedparser = true)
 
 Convenience function to read in an image corresponding to the HDU at index `hduindex` contained in
 the FITS file named `filename`.
 If `arrayindices` are provided, only a slice of the image corresponding to the indices is read in.
 
-Functionally `fitsread(filename, hduindex, arrayindices...)` is equivalent to
+Functionally `fitsread(filename, hduindex, arrayindices...; extendedparser)` is equivalent to
 
 ```julia
-FITS(filename, "r") do f
+FITS(filename, "r"; extendedparser = extendedparser) do f
     read(f[hduindex], arrayindices...)
 end
 ```
 
+The keyword argument `extendedparser` may be used to enable or disable the
+[extended filename parser](https://heasarc.gsfc.nasa.gov/docs/software/fitsio/c/c_user/node83.html).
+If disabled, `filename` is treated exactly as the name of the file and is not tokenized into
+parameters.
+
 !!! note
     Julia follows a column-major array indexing convention, so the indices provided must account for this.
     In particular this means that FITS files created externally following a row-major convention (eg. using astropy)
     will have the sequence of axes flipped when read in using FITSIO.
 
 See also: [`read`](@ref)
 """
-function fitsread(filename::AbstractString, hduindex = 1, arrayindices...)
-    FITS(filename, "r") do f
+function fitsread(filename::AbstractString, hduindex = 1, arrayindices...; extendedparser = true)
+    FITS(filename, "r"; extendedparser = extendedparser) do f
         read(f[hduindex], arrayindices...)
     end
 end
@@ -276,25 +281,30 @@ read!(hdu::ImageHDU, array::StridedArray{<:Real}, I::Union{AbstractRange{<:Integ
 read!(hdu::ImageHDU, array::StridedArray{<:Real}, I::Integer...) = read_internal!(hdu, array, I...)[1]
 
 """
-    fitswrite(filename::AbstractString, data; kwargs...)
+    fitswrite(filename::AbstractString, data; extendedparser = true, kwargs...)
 
 Convenience function to write the image array `data` to a file named `filename`.
 
-Functionally `fitswrite(filename, data; kwargs...)` is equivalent to
+Functionally `fitswrite(filename, data; extendedparser, kwargs...)` is equivalent to
 
 ```julia
-FITS(filename, "w") do f
+FITS(filename, "w"; extendedparser = extendedparser) do f
     write(f, data; kwargs...)
 end
 ```
 
+The keyword argument `extendedparser` may be used to enable or disable the
+[extended filename parser](https://heasarc.gsfc.nasa.gov/docs/software/fitsio/c/c_user/node83.html).
+If disabled, `filename` is treated exactly as the name of the file and is not tokenized into
+parameters.
+
 !!! warn "Warning"
     Existing files with the same name will be overwritten.
 
 See also: [`write`](@ref)
 """
-function fitswrite(filename::AbstractString, data; kwargs...)
-    FITS(filename, "w") do f
+function fitswrite(filename::AbstractString, data; extendedparser = true, kwargs...)
+    FITS(filename, "w", extendedparser = extendedparser) do f
         write(f, data; kwargs...)
     end
 end

test/runtests.jl

@@ -30,6 +30,14 @@ end
         @test_throws Exception write(f, ones(2))
         d = f[1]
         @test_throws Exception write(d, ones(2))
+
+        fname2 = fname*"[12].fits"
+        FITS(fname2, "w", extendedparser = false) do f
+            write(f, [1,2])
+            @test read(f[1]) == [1,2]
+        end
+        FITSIO.fitswrite(fname2, [1:4;], extendedparser = false)
+        @test FITSIO.fitsread(fname2, extendedparser = false) == [1:4;]
     end
 end