Add diskfile functions that do not use extended filename parser (#9)

* Add diskfile

* Test nonempty in write functions

* use vectors in create image

* skip test for create image with tuples

* Update src/CFITSIO.jl

Co-authored-by: Mosè Giordano <[email protected]>

* specific error message, add @ref

* change Exception to CFITSIOError in test

* redirect output

* test creation using size tuple

* remove test for hdu in write

Co-authored-by: Mosè Giordano <[email protected]>

Project.toml

@@ -1,7 +1,7 @@
 name = "CFITSIO"
 uuid = "3b1b4be9-1499-4b22-8d78-7db3344d1961"
 authors = ["Miles Lucas <[email protected]> and contributors"]
-version = "1.2.0"
+version = "1.3.0"
 
 [deps]
 CFITSIO_jll = "b3e40c51-02ae-5482-8a39-3ace5868dcf4"

src/CFITSIO.jl

@@ -10,6 +10,7 @@ export FITSFile,
     fits_copy_image_section,
     fits_create_ascii_tbl,
     fits_create_binary_tbl,
+    fits_create_diskfile,
     fits_create_file,
     fits_create_img,
     fits_delete_file,
@@ -41,6 +42,7 @@ export FITSFile,
     fits_movrel_hdu,
     fits_movnam_hdu,
     fits_open_data,
+    fits_open_diskfile,
     fits_open_file,
     fits_open_image,
     fits_open_table,
@@ -240,7 +242,11 @@ onest(::Type{T}, n) where {T} = ntuple(_ -> one(T), n)
 """
     fits_create_file(filename::AbstractString)
 
-Create and open a new empty output `FITSFile`.
+Create and open a new empty output `FITSFile`. This methods uses the
+[extended file name syntax](https://heasarc.gsfc.nasa.gov/docs/software/fitsio/c/c_user/node83.html)
+to create the file.
+
+See also [`fits_create_diskfile`](@ref) which does not use the extended filename parser.
 """
 function fits_create_file(filename::AbstractString)
     ptr = Ref{Ptr{Cvoid}}()
@@ -257,6 +263,27 @@ function fits_create_file(filename::AbstractString)
     FITSFile(ptr[])
 end
 
+"""
+    fits_create_diskfile(filename::AbstractString)
+
+Create and open a new empty output `FITSFile`. Unlike [`fits_create_file`](@ref), this function does
+not use an extended filename parser and treats the string as is as the filename.
+"""
+function fits_create_diskfile(filename::AbstractString)
+    ptr = Ref{Ptr{Cvoid}}()
+    status = Ref{Cint}(0)
+    ccall(
+        (:ffdkinit, libcfitsio),
+        Cint,
+        (Ref{Ptr{Cvoid}}, Ptr{UInt8}, Ref{Cint}),
+        ptr,
+        filename,
+        status,
+    )
+    fits_assert_ok(status[], filename)
+    FITSFile(ptr[])
+end
+
 """
     fits_clobber_file(filename::AbstractString)
 
@@ -284,9 +311,26 @@ Open an existing data file.
 ## Modes:
 * 0 : Read only (equivalently denoted by `CFITSIO.R`)
 * 1 : Read-write (equivalently denoted by `CFITSIO.RW`)
+
+This function uses the extended filename syntax to open the file. See also [`fits_open_diskfile`](@ref)
+that does not use the extended filename parser and uses `filename` as is as the name of the file.
 """
 fits_open_file
 
+"""
+    fits_open_diskfile(filename::String, [mode = 0])
+
+Open an existing data file.
+
+## Modes:
+* 0 : Read only (equivalently denoted by `CFITSIO.R`)
+* 1 : Read-write (equivalently denoted by `CFITSIO.RW`)
+
+This function does not use the extended filename parser, and uses `filename` as is as the name
+of the file that is to be opened. See also [`fits_open_file`](@ref) which uses the extended filename syntax.
+"""
+fits_open_diskfile
+
 """
     fits_open_image(filename::String, [mode = 0])
 
@@ -316,6 +360,7 @@ for (a, b) in (
     (:fits_open_file, "ffopen"),
     (:fits_open_image, "ffiopn"),
     (:fits_open_table, "fftopn"),
+    (:fits_open_diskfile, "ffdkopn"),
     )
 
     @eval begin
@@ -1062,7 +1107,7 @@ end
 Create a new primary array or IMAGE extension with the element type and size of `A`,
 that is capable of storing the entire array `A`.
 """
-fits_create_img(f::FITSFile, a::AbstractArray) = fits_create_img(f, eltype(a), [size(a)...])
+fits_create_img(f::FITSFile, a::AbstractArray) = fits_create_img(f, eltype(a), size(a))
 
 """
     fits_write_pix(f::FITSFile, fpixel::Union{Vector{<:Integer}, Tuple{Vararg{Integer}}}, nelements::Integer, data::StridedArray)
@@ -1082,6 +1127,7 @@ function fits_write_pix(
     )
 
     fits_assert_open(f)
+
     status = Ref{Cint}(0)
     ccall(
         (:ffppxll, libcfitsio),
@@ -1171,6 +1217,7 @@ function fits_write_pixnull(
     )
 
     fits_assert_open(f)
+
     status = Ref{Cint}(0)
     ccall(
         (:ffppxnll, libcfitsio),

test/runtests.jl

@@ -505,13 +505,9 @@ end
     @testset "empty file" begin
         tempfitsfile() do f
             a = zeros(2,2)
-            @test_throws Exception fits_read_pix(f, a)
-            @test_throws Exception fits_read_pix(f, a, 1)
-            @test_throws Exception fits_read_pixnull(f, a, similar(a, UInt8))
-
-            # write some data to avoid errors on closing
-            fits_create_img(f, eltype(a), [size(a)...])
-            fits_write_pix(f, a)
+            @test_throws ErrorException fits_read_pix(f, a)
+            @test_throws ErrorException fits_read_pix(f, a, 1)
+            @test_throws ErrorException fits_read_pixnull(f, a, similar(a, UInt8))
         end
     end
 
@@ -612,4 +608,77 @@ end
         end
     end
 
+
+    @testset "extended filename parser" begin
+        filename = tempname()
+        a = [1 3; 2 4]
+        b = similar(a)
+        try
+            # for filenames that don't contain extended format specifications,
+            # the diskfile functions are equivalent to the file ones
+            for createfn in [fits_create_file, fits_create_diskfile]
+                f = createfn(filename)
+                fits_create_img(f, a)
+                fits_write_pix(f, a)
+                close(f)
+                # Extended format: flipping the image
+                f = fits_open_file(filename*"[*,-*]")
+                fits_read_pix(f, b)
+                @test a[:, [2,1]] == b
+                close(f)
+                f = fits_open_file(filename*"[-*,*]")
+                fits_read_pix(f, b)
+                @test a[[2,1], :] == b
+                close(f)
+                # without extended format
+                f = fits_open_diskfile(filename)
+                fits_read_pix(f, b)
+                @test a == b
+                close(f)
+                rm(filename)
+            end
+        finally
+            rm(filename, force = true)
+        end
+
+        # the diskfile functions may include [] in the filenames
+        filename2 = filename * "[abc].fits"
+        @test_throws CFITSIO.CFITSIOError fits_create_file(filename2)
+        try
+            f = fits_create_diskfile(filename2)
+            fits_create_img(f, a)
+            fits_write_pix(f, a)
+            fits_read_pix(f, b)
+            @test a == b
+            close(f)
+            f = fits_open_diskfile(filename2)
+            fits_read_pix(f, b)
+            @test a == b
+            close(f)
+            @test_throws CFITSIO.CFITSIOError fits_open_file(filename2)
+        finally
+            rm(filename2, force = true)
+        end
+    end
+
+    @testset "stdout/stdin streams" begin
+        # We redirect the output streams to a temp file to avoid cluttering the output
+        # At present this doesn't work completely, as there is some output from fits_create_img
+        # that is not captured
+        mktemp() do _, io
+            redirect_stdout(io) do
+                for fname in ["-", "stdout.gz"]
+                    f = fits_create_file(fname);
+                    for a in Any[[1 2; 3 4], Float64[1 2; 3 4]]
+                        b = similar(a)
+                        fits_create_img(f, a)
+                        fits_write_pix(f, a)
+                        fits_read_pix(f, b)
+                        @test a == b
+                    end
+                    close(f)
+                end
+            end
+        end
+    end
 end