Merge pull request #37 from JuliaIO/teh/writemime

Add support for writemime

Author: SimonDanisch

README.md

@@ -76,10 +76,10 @@ This means MeshIO supports loading and saving of the `off` format.
 You can add multiple loaders and specifiers like this:
 ```jl
 add_format(
-    format"BMP", 
+    format"BMP",
     UInt8[0x42,0x4d],
     ".bmp",
-    [:OSXNativeIO, LOAD, OSX], 
+    [:OSXNativeIO, LOAD, OSX],
     [:ImageMagick]
 )
 ```
@@ -91,6 +91,18 @@ Users are encouraged to contribute these definitions to the
 `registry.jl` file of this package, so that information about file
 formats exists in a centralized location.
 
+Handling MIME outputs is similar, except that one also provides the
+type of the object to be written:
+```jl
+mimewritable(::MIME"image/png", img::AbstractArray) = ndims(img) == 2
+add_mime(MIME("image/png"), AbstractArray, :ImageMagick)
+```
+
+In cases where the type is defined in Base julia, such declarations
+can by included in FileIO's `registry` file.  In contrast, when the
+type is defined in a package, that package should call them. Note that
+`add_mime` should be called from the package's `__init__` function.
+
 ## Implementing loaders/savers
 
 In your package, write code like the following:
@@ -130,6 +142,19 @@ automatically even if the code inside the `do` scope throws an error.)
 Conversely, `load(::Stream)` and `save(::Stream)` should not close the
 input stream.
 
+For MIME output, you would implement a method like this:
+```jl
+function Base.writemime(s::Stream{format"ImageMagick"}, ::MIME"image/png", x)
+    io = stream(s)
+    # Do the stuff needed to create the output
+end
+```
+
+It's perfectly acceptable to also create a `Base.writemime(s::IO,
+::MIME"image/png", x)` method.  Such methods will generally take
+precedence over FileIO's generic fallback `writemime` function, and
+therefore in some cases might improve performance.
+
 ## Help
 
 You can get an API overview by typing `?FileIO` at the REPL prompt.

src/FileIO.jl

@@ -23,6 +23,7 @@ export DataFormat,
        add_format,
        del_format,
        add_loader,
+       add_mime,
        add_saver,
        filename,
        file_extension,
@@ -85,6 +86,21 @@ function save(s::@compat(Union{AbstractString,IO}), data...; options...)
     rethrow(last_exception)
 end
 
+function Base.writemime(io::IO, mime::MIME, x)
+    handlers = applicable_mime(mime)
+    last_exception = ErrorException("No package available to writemime $mime")
+    for (T,pkg) in handlers
+        isa(x, T) || continue
+        try
+            check_mime(pkg)
+            return writemime(Stream(DataFormat{pkg}, io), mime, x)
+        catch e
+            last_exception = e
+        end
+    end
+    rethrow(last_exception)
+end
+
 # Fallbacks
 load{F}(f::Formatted{F}; options...) = error("No load function defined for format ", F, " with filename ", filename(f))
 save{F}(f::Formatted{F}, data...; options...) = error("No save function defined for format ", F, " with filename ", filename(f))

src/loadsave.jl

@@ -1,8 +1,10 @@
 const sym2loader = Dict{Symbol,Vector{Symbol}}()
 const sym2saver  = Dict{Symbol,Vector{Symbol}}()
+const mimedict   = Dict{Symbol,Vector{Any}}()
 
-for (appl,fchk,fadd,dct) in ((:applicable_loaders, :check_loader, :add_loader, :sym2loader),
-                        (:applicable_savers, :check_saver,  :add_saver,  :sym2saver))
+for (appl,fchk,fadd,dct) in (
+        (:applicable_loaders, :check_loader, :add_loader, :sym2loader),
+        (:applicable_savers,  :check_saver,  :add_saver,  :sym2saver))
     @eval begin
         $appl{sym}(::Formatted{DataFormat{sym}}) = get($dct, sym, [:FileIO]) # if no loader is declared, fallback to FileIO
         function $fchk(pkg::Symbol)
@@ -16,5 +18,20 @@ for (appl,fchk,fadd,dct) in ((:applicable_loaders, :check_loader, :add_loader, :
     end
 end
 
-@doc "`add_loader(fmt, :Package)` forces `using Package` before loading format `fmt`" -> add_loader
-@doc "`add_saver(fmt, :Package)` forces `using Package` before saving format `fmt`" -> add_saver
+applicable_mime{sym}(::MIME{sym}) = get(mimedict, sym, [:nothing])
+function check_mime(pkg::Symbol)
+    pkg == :nothing && error("No MIME package available")
+    !isdefined(Main, pkg) && eval(Main, Expr(:import, pkg))
+    return pkg
+end
+
+@doc """
+`add_mime(mime, T, :Package)`  triggers `using Package` before attempting to write object of type `T` in format `mime`.
+""" ->
+function add_mime{sym,T}(::MIME{sym}, ::Type{T}, pkg::Symbol)
+    list = get(mimedict, sym, Any[])
+    mimedict[sym] = push!(list, (T,pkg))
+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

test/runtests.jl

@@ -4,6 +4,7 @@ using FactCheck
 facts("FileIO") do
 	include("query.jl")
 	include("loadsave.jl")
+	include("writemime.jl")
 end
 # make Travis fail when tests fail:
 FactCheck.exitstatus()

test/writemime.jl

@@ -0,0 +1,9 @@
+Base.writemime(s::Stream{format"FileIO"}, ::MIME"test/floatvector", v::Vector{Float32}) = print(stream(s), v)
+context("writemime") do 
+	add_mime(MIME("test/floatvector"), Vector{Float32}, :FileIO)
+	io = IOBuffer()
+	t = rand(Float32, 88)
+	writemime(io, MIME("test/floatvector"), t)
+	@fact takebuf_string(io) --> string(t)
+	close(io)
+end