document FortranFileError

Add documentation for the `FortranFileError` exception.
Move `fthrow` calls to their own line so coverage can find them.
Throw `ArgumentError` for `@fread` syntax errors.

README.md

@@ -2,7 +2,7 @@
 
 A Julia package for reading/writing Fortran unformatted (i.e. binary) files.
 
-[![Documentation](https://img.shields.io/badge/docs-latest-blue.svg)](https://traktofon.github.io/FortranFiles.jl/stable/)
+[![Documentation](https://img.shields.io/badge/docs-latest-blue.svg)](https://traktofon.github.io/FortranFiles.jl/latest/)
 [![Build Status](https://travis-ci.org/traktofon/FortranFiles.jl.svg?branch=master)](https://travis-ci.org/traktofon/FortranFiles.jl)
 [![coveralls Status](https://coveralls.io/repos/traktofon/FortranFiles.jl/badge.svg?branch=master&service=github)](https://coveralls.io/github/traktofon/FortranFiles.jl?branch=master)
 [![codecov.io Status](http://codecov.io/github/traktofon/FortranFiles.jl/coverage.svg?branch=master)](https://codecov.io/gh/traktofon/FortranFiles.jl/branch/master)

docs/make.jl

@@ -10,6 +10,7 @@ makedocs(
       "types.md",
       "read.md",
       "write.md",
+      "exceptions.md",
       "tests.md",
       "Index" => "theindex.md"
    ]

docs/src/exceptions.md

@@ -0,0 +1,15 @@
+# Exceptions
+
+The following exception type is used to signal errors when handling `FortranFile`s.
+
+```@docs
+FortranFilesError
+```
+
+The errors could be:
+
+* using unsupported features, or invalid combinations of features
+* I/O errors related to the Fortran layer, e.g. non-matching record markers.
+  I/O errors on the underlying `IO`, e.g. read/write failure, will show up
+  as one of the Julia built-in exceptions.
+

docs/src/index.md

@@ -30,12 +30,13 @@ Pages = [
    "types.md",
    "read.md",
    "write.md",
+   "exceptions.md",
    "tests.md",
    "theindex.md"
 ]
 ```
 
-This documentation uses julia-0.7 syntax. On julia-0.6, either use `using Compat`
+This documentation uses julia-0.7/1.0 syntax. On julia-0.6, either use `using Compat`
 or make the following adjustments:
 * `ComplexF64` -> `Complex128` and `ComplexF32` -> `Complex64`
 * drop `undef` from Array constructors

docs/src/theindex.md

@@ -10,6 +10,7 @@ Pages = [
    "types.md",
    "read.md",
    "write.md",
+   "exceptions.md",
    "tests.md"
 ]
 ```

src/fixedlengthrecords.jl

@@ -34,14 +34,18 @@ function gotorecord( f::FortranFile{DirectAccess}, recnum::Integer )
 end
 
 function unsafe_read( rec::FixedLengthRecord, p::Ptr{UInt8}, n::UInt )
-   if (n > rec.nleft); fthrow("attempting to read beyond record end"); end
+   if (n > rec.nleft)
+      fthrow("attempting to read beyond record end")
+   end
    unsafe_read( rec.io, p, n )
    rec.nleft -= n
    nothing
 end
 
 function unsafe_write( rec::FixedLengthRecord, p::Ptr{UInt8}, n::UInt )
-   if (n > rec.nleft); fthrow("attempting to write beyond record end"); end
+   if (n > rec.nleft)
+      fthrow("attempting to write beyond record end")
+   end
    nwritten = unsafe_write( rec.io, p, n )
    rec.nleft -= n
    return nwritten

src/macro.jl

@@ -51,20 +51,20 @@ macro fread(fortranFile, args...)
                recnum = esc(arg.args[2])
                haverecnum = true
             else
-               error("unknown keyword argument '$(arg.args[1])'")
+               throw(ArgumentError("unknown keyword argument '$(arg.args[1])'"))
             end
          elseif arg.head == :(::)
             var = esc(arg.args[1])
             typ = esc(arg.args[2])
             push!(specs, (var,typ))
          else
-            error("unsupported specification for read: '$(arg)'")
+            throw(ArgumentError("unsupported specification for read: '$(arg)'"))
          end
       elseif isa(arg, Symbol)
          var = esc(arg)
          push!(specs, var)
       else
-         error("unsupported specification for read: '$(arg)'")
+         throw(ArgumentError("unsupported specification for read: '$(arg)'"))
       end
    end
 

src/withoutsubrecords.jl

@@ -23,27 +23,35 @@ function Record( f::FortranFile{SequentialAccess{WithoutSubrecords{T}},C}, towri
 end
 
 function unsafe_read( rec::RecordWithoutSubrecords, p::Ptr{UInt8}, n::UInt )
-   if (n > rec.nleft); fthrow("attempting to read beyond record end"); end
+   if (n > rec.nleft)
+      fthrow("attempting to read beyond record end")
+   end
    unsafe_read( rec.io, p, n )
    rec.nleft -= n
    nothing
 end
 
 function unsafe_write( rec::RecordWithoutSubrecords, p::Ptr{UInt8}, n::UInt )
-   if (n > rec.nleft); fthrow("attempting to write beyond record end"); end
+   if (n > rec.nleft)
+      fthrow("attempting to write beyond record end")
+   end
    nwritten = unsafe_write( rec.io, p, n )
    rec.nleft -= n
    return nwritten
 end
 
 function close( rec::RecordWithoutSubrecords{T} ) where {T}
    if rec.writable
-      if rec.nleft != 0; fthrow("record has not yet been completely written"); end
+      if rec.nleft != 0
+         fthrow("record has not yet been completely written")
+      end
       write(rec.io, rec.convert.onwrite( convert(T, rec.reclen)) ) # write trailing record marker
    else
       skip(rec.io, rec.nleft)
       reclen = rec.convert.onread( read(rec.io, T) ) # read trailing record marker
-      if reclen != rec.reclen; fthrow("trailing record marker doesn't match"); end
+      if reclen != rec.reclen
+         fthrow("trailing record marker doesn't match")
+      end
    end
    nothing
 end

src/withsubrecords.jl

@@ -50,7 +50,9 @@ end
 
 function advance!( rec::RecordWithSubrecords )
    subreclen, sign = rdmarker(rec) # read trailing record marker
-   if subreclen != rec.subreclen; fthrow("trailing subrecord marker doesn't match"); end
+   if subreclen != rec.subreclen
+      fthrow("trailing subrecord marker doesn't match")
+   end
    if rec.more
       subreclen, more = rdmarker(rec) # read next leading subrecord marker
       rec.subleft = rec.subreclen = subreclen
@@ -61,7 +63,9 @@ end
 
 function unsafe_read( rec::RecordWithSubrecords, p::Ptr{UInt8}, n::UInt )
    while (n>0)
-      if rec.subleft==0; fthrow("attempting to read beyond record end"); end
+      if rec.subleft==0
+         fthrow("attempting to read beyond record end")
+      end
       toread = min(n, rec.subleft)
       unsafe_read(rec.io, p, toread)
       p += toread
@@ -75,7 +79,9 @@ end
 function unsafe_write( rec::RecordWithSubrecords, p::Ptr{UInt8}, n::UInt )
    nwritten = 0
    while (n>0)
-      if rec.totleft==0; fthrow("attempting to write beyond record end"); end
+      if rec.totleft==0
+         fthrow("attempting to write beyond record end")
+      end
       towrite = min(n, rec.subleft)
       nwritten += unsafe_write(rec.io, p, towrite)
       p += towrite

src/write.jl

@@ -88,7 +88,8 @@ _check_fortran_type(::Type{FString{L}}) where L = true
 _check_fortran_type(T::Type) = isbitstype(T)
 
 function sizeof_var( var::T ) where {T}
-   check_fortran_type(var) || fthrow("cannot serialize datatype $T for Fortran")
+   check_fortran_type(var) ||
+      fthrow("cannot serialize datatype $T for Fortran")
    sizeof(var)
 end