diff --git a/.travis.yml b/.travis.yml index 1a940bdf..34cdbc4d 100644 --- a/.travis.yml +++ b/.travis.yml @@ -3,7 +3,6 @@ os: - linux - osx julia: - - 0.3 - 0.4 - nightly notifications: diff --git a/REQUIRE b/REQUIRE index 60439979..105f73d4 100644 --- a/REQUIRE +++ b/REQUIRE @@ -1,4 +1,2 @@ -julia 0.3 +julia 0.4 Compat 0.7.19 -# The rest are needed only on julia 0.3 -Docile diff --git a/src/FileIO.jl b/src/FileIO.jl index 74d4f457..9da8c05f 100644 --- a/src/FileIO.jl +++ b/src/FileIO.jl @@ -4,16 +4,6 @@ module FileIO using Compat import Compat.String -if VERSION < v"0.4.0-dev" - using Docile - immutable Pair{A,B} - first::A - second::B - end - Base.first(p::Pair) = p.first - Base.last(p::Pair) = p.second -end - export DataFormat, File, Formatted, @@ -44,7 +34,7 @@ include("error_handling.jl") include("loadsave.jl") include("registry.jl") -@doc """ +""" `FileIO` API (brief summary, see individual functions for more detail): - `format"PNG"`: specifies a particular defined format @@ -66,6 +56,7 @@ include("registry.jl") - `add_format(fmt, magic, extension)`: register a new format - `add_loader(fmt, :Package)`: indicate that `Package` supports loading files of type `fmt` - `add_saver(fmt, :Package)`: indicate that `Package` supports saving files of type `fmt` -""" -> FileIO +""" +FileIO end diff --git a/src/error_handling.jl b/src/error_handling.jl index fc87915c..17bab590 100644 --- a/src/error_handling.jl +++ b/src/error_handling.jl @@ -1,8 +1,8 @@ -@doc """ +""" `LoaderError` should be thrown when loader library code fails, and other libraries should be given the chance to recover from the error. Reports the library name and an error message: LoaderError("ImageMagick", "Foo not available") -""" -> +""" immutable LoaderError <: Exception library::Compat.UTF8String msg::Compat.UTF8String @@ -10,11 +10,11 @@ end Base.showerror(io::IO, e::LoaderError) = println(io, e.library, " load error: ", msg, "\n Will try next loader.") -@doc """ +""" `WriterError` should be thrown when writer library code fails, and other libraries should be given the chance to recover from the error. Reports the library name and an error message: WriterError("ImageMagick", "Foo not available") -""" -> +""" immutable WriterError <: Exception library::Compat.UTF8String msg::Compat.UTF8String @@ -24,27 +24,27 @@ Base.showerror(io::IO, e::WriterError) = println( msg, "\n Will try next writer." ) -@doc """ +""" `NotInstalledError` should be thrown when a library is currently not installed. -""" -> +""" immutable NotInstalledError <: Exception library::Symbol message::Compat.UTF8String end Base.showerror(io::IO, e::NotInstalledError) = println(io, e.library, " is not installed.") -@doc """ +""" `UnknownFormat` gets thrown when FileIO can't recognize the format of a file. -""" -> +""" immutable UnknownFormat{T <: Formatted} <: Exception format::T end Base.showerror(io::IO, e::UnknownFormat) = println(io, e.format, " couldn't be recognized by FileIO.") -@doc """ +""" Handles error as soon as they get thrown while doing IO -""" -> +""" function handle_current_error(e, library, islast::Bool) bt = catch_backtrace() bts = sprint(io->Base.show_backtrace(io, bt)) @@ -53,9 +53,9 @@ function handle_current_error(e, library, islast::Bool) end handle_current_error(e::NotInstalledError) = warn(string("lib ", e.library, " not installed, trying next library")) -@doc """ +""" Handles a list of thrown errors after no IO library was found working -""" -> +""" function handle_error(exceptions::Vector) for exception in exceptions continue_ = handle_error(exception...) @@ -77,12 +77,10 @@ function handle_error(e::NotInstalledError, q) return false # don't continue elseif input == "n" info(string("Not installing ", e.library)) - return true # User does not install, continue going through errors. + return true # User does not install, continue going through errors. else println("$input is not a valid choice. Try typing y or n") end end - true # User does not install, continue going through errors. + true # User does not install, continue going through errors. end - - diff --git a/src/loadsave.jl b/src/loadsave.jl index e9bbca96..139e5699 100644 --- a/src/loadsave.jl +++ b/src/loadsave.jl @@ -28,27 +28,29 @@ for (applicable_, add_, dict_) in ( end -@doc "`add_loader(fmt, :Package)` triggers `using Package` before loading format `fmt`" -> add_loader -@doc "`add_saver(fmt, :Package)` triggers `using Package` before saving format `fmt`" -> add_saver +"`add_loader(fmt, :Package)` triggers `using Package` before loading format `fmt`" +add_loader +"`add_saver(fmt, :Package)` triggers `using Package` before saving format `fmt`" +add_saver -@doc """ +""" - `load(filename)` loads the contents of a formatted file, trying to infer the format from `filename` and/or magic bytes in the file. - `load(strm)` loads from an `IOStream` or similar object. In this case, the magic bytes are essential. - `load(File(format"PNG",filename))` specifies the format directly, and bypasses inference. - `load(f; options...)` passes keyword arguments on to the loader. -""" -> +""" load(s::@compat(Union{AbstractString,IO}), args...; options...) = load(query(s), args...; options...) -@doc """ +""" - `save(filename, data...)` saves the contents of a formatted file, trying to infer the format from `filename`. - `save(Stream(format"PNG",io), data...)` specifies the format directly, and bypasses inference. - `save(f, data...; options...)` passes keyword arguments on to the saver. -""" -> +""" save(s::@compat(Union{AbstractString,IO}), data...; options...) = save(query(s), data...; options...) diff --git a/src/query.jl b/src/query.jl index bbeaf451..c7056065 100644 --- a/src/query.jl +++ b/src/query.jl @@ -30,13 +30,13 @@ function add_loadsave(format, predicates) end end -@doc """ +""" `DataFormat{sym}()` indicates a known binary or text format of kind `sym`, where `sym` is always a symbol. For example, a .csv file might have `DataFormat{:CSV}()`. An easy way to write `DataFormat{:CSV}` is `format"CSV"`. -""" -> +""" immutable DataFormat{sym} end macro format_str(s) @@ -45,8 +45,8 @@ end const unknown_df = DataFormat{:UNKNOWN} -@doc """ -`unknown(f)` returns true if the format of `f` is unknown.""" -> +""" +`unknown(f)` returns true if the format of `f` is unknown.""" unknown(::Type{format"UNKNOWN"}) = true unknown{sym}(::Type{DataFormat{sym}}) = false @@ -64,7 +64,7 @@ function add_format(fmt, magic, extension, load_save_libraries...) fmt end -@doc """ +""" `add_format(fmt, magic, extention)` registers a new `DataFormat`. For example: @@ -73,7 +73,7 @@ For example: add_format(format"NRRD", "NRRD", [".nrrd",".nhdr"]) Note that extensions, magic numbers, and format-identifiers are case-sensitive. -""" -> +""" function add_format{sym}(fmt::Type{DataFormat{sym}}, magic::@compat(Union{Tuple,AbstractVector,String}), extension) haskey(sym2info, sym) && error("format ", fmt, " is already registered") m = canonicalize_magic(magic) @@ -113,9 +113,9 @@ function add_format{sym}(fmt::Type{DataFormat{sym}}, magic, extension) fmt end -@doc """ +""" `del_format(fmt::DataFormat)` deletes `fmt` from the format registry. -""" -> +""" function del_format{sym}(fmt::Type{DataFormat{sym}}) magic, extension = sym2info[sym] del_magic(magic, sym) @@ -148,9 +148,9 @@ function del_magic{N}(magic::NTuple{N, UInt8}, sym) nothing end -@doc """ +""" `info(fmt)` returns the magic bytes/extension information for -`DataFormat` `fmt`.""" -> +`DataFormat` `fmt`.""" Base.info{sym}(::Type{DataFormat{sym}}) = sym2info[sym] @@ -209,32 +209,32 @@ end abstract Formatted{F<:DataFormat} # A specific file or stream -@doc """ +""" `File(fmt, filename)` indicates that `filename` is a file of known DataFormat `fmt`. For example, `File{fmtpng}(filename)` would indicate a PNG -file.""" -> +file.""" immutable File{F<:DataFormat} <: Formatted{F} filename::Compat.UTF8String end File{sym}(fmt::Type{DataFormat{sym}}, filename) = File{fmt}(filename) -@doc """ +""" `filename(file)` returns the filename associated with `File` `file`. -""" -> +""" filename(f::File) = f.filename -@doc """ +""" `file_extension(file)` returns the file extension associated with `File` `file`. -""" -> +""" file_extension(f::File) = splitext(filename(f))[2] -@doc """ +""" `Stream(fmt, io, [filename])` indicates that the stream `io` is written in known `Format`. For example, `Stream{PNG}(io)` would indicate PNG format. If known, the optional `filename` argument can -be used to improve error messages, etc.""" -> +be used to improve error messages, etc.""" immutable Stream{F<:DataFormat,IOtype<:IO} <: Formatted{F} io::IOtype filename::Nullable{Compat.UTF8String} @@ -245,17 +245,17 @@ Stream{F<:DataFormat}(::Type{F}, io::IO, filename::AbstractString) = Stream{F,ty Stream{F<:DataFormat}(::Type{F}, io::IO, filename) = Stream{F,typeof(io)}(io,filename) Stream{F}(file::File{F}, io::IO) = Stream{F,typeof(io)}(io,filename(file)) -@doc "`stream(s)` returns the stream associated with `Stream` `s`" -> +"`stream(s)` returns the stream associated with `Stream` `s`" stream(s::Stream) = s.io -@doc """ +""" `filename(stream)` returns a nullable-string of the filename -associated with `Stream` `stream`.""" -> +associated with `Stream` `stream`.""" filename(s::Stream) = s.filename -@doc """ +""" `file_extension(file)` returns a nullable-string for the file extension associated with `Stream` `stream`. -""" -> +""" function file_extension(f::Stream) isnull(filename(f)) && return filename(f) splitext(get(filename(f)))[2] @@ -301,13 +301,13 @@ Base.readbytes(s::Stream, nb) = read(stream(s), nb) Base.isreadonly(s::Stream) = isreadonly(stream(s)) Base.isopen(s::Stream) = isopen(stream(s)) -@doc "`magic(fmt)` returns the magic bytes of format `fmt`" -> +"`magic(fmt)` returns the magic bytes of format `fmt`" magic{F<:DataFormat}(fmt::Type{F}) = UInt8[info(fmt)[1]...] -@doc """ +""" `skipmagic(s)` sets the position of `Stream` `s` to be just after the magic bytes. For a plain IO object, you can use `skipmagic(io, fmt)`. -""" -> +""" skipmagic{F}(s::Stream{F}) = (skipmagic(stream(s), F); s) function skipmagic{sym}(io, fmt::Type{DataFormat{sym}}) magic, _ = sym2info[sym] @@ -345,9 +345,9 @@ end unknown{F}(::File{F}) = unknown(F) unknown{F}(::Stream{F}) = unknown(F) -@doc """ +""" `query(filename)` returns a `File` object with information about the -format inferred from the file's extension and/or magic bytes.""" -> +format inferred from the file's extension and/or magic bytes.""" function query(filename::AbstractString) _, ext = splitext(filename) if haskey(ext2sym, ext) @@ -381,9 +381,9 @@ hasfunction(v::Vector) = any(hasfunction, v) hasfunction(s::Any) = true #has function hasfunction(s::Tuple) = false #has magic -@doc """ +""" `query(io, [filename])` returns a `Stream` object with information about the -format inferred from the magic bytes.""" -> +format inferred from the magic bytes.""" query(io::IO, filename) = query(io, Nullable(Compat.UTF8String(filename))) function query(io::IO, filename::Nullable{Compat.UTF8String}=Nullable{Compat.UTF8String}())