Merge branch 'master' of https://github.com/JuliaInterop/MATLAB.jl

Author: musm

README.md

@@ -86,7 +86,7 @@ x = mxarray(["a", 1, 2.3])  # converts a Julia array to a MATLAB cell array
 x = mxarray(Dict("a"=>1, "b"=>"string", "c"=>[1,2,3])) # converts a Julia dictionary to a MATLAB struct
 ```
 
-The function ``mxarray`` can also converts a compound type to a Julia struct:
+The function ``mxarray`` can also convert a compound type to a Julia struct:
 ```julia
 type S
 	x::Float64
@@ -196,19 +196,19 @@ Both ``read_matfile`` and ``write_matfile`` will close the MAT file handle befor
 **Examples:**
 
 ```julia
-immutable S
-	x::Float64
-	y::Bool
-	z::Vector{Float64}
+struct S
+    x::Float64
+    y::Bool
+    z::Vector{Float64}
 end
 
 write_matfile("test.mat"; 
-	a = Int32[1 2 3; 4 5 6], 
-	b = [1.2, 3.4, 5.6, 7.8], 
-	c = [[0.0, 1.0], [1.0, 2.0], [1.0, 2.0, 3.0]], 
-	d = Dict("name"=>"MATLAB", "score"=>100.0), 
-	s = "abcde",
-	ss = [S(1.0, true, [1., 2.]), S(2.0, false, [3., 4.])] )
+    a = Int32[1 2 3; 4 5 6], 
+    b = [1.2, 3.4, 5.6, 7.8], 
+    c = [[0.0, 1.0], [1.0, 2.0], [1.0, 2.0, 3.0]], 
+    d = Dict("name"=>"MATLAB", "score"=>100.0), 
+    s = "abcde",
+    ss = [S(1.0, true, [1., 2.]), S(2.0, false, [3., 4.])] )
 ```
 
 This example will create a MAT file called ``test.mat``, which contains six MATLAB variables:
@@ -228,9 +228,11 @@ This example will create a MAT file called ``test.mat``, which contains six MATL
 To evaluate expressions in MATLAB, one may open a MATLAB engine session and communicate with it. There are three ways to call MATLAB from Julia:
 
 - The `mat""` custom string literal allows you to write MATLAB syntax inside Julia and use Julia variables directly from MATLAB via interpolation
-- The `@matlab` macro, in combination with `@mput` and `@mget`, translates Julia syntax to MATLAB
+- The `eval_string` evaluate a string containing MATLAB expressions (typically used with the helper macros `@mget` and `@mput`
 - The `mxcall` function calls a given MATLAB function and returns the result
 
+In general, the `mat""` custom string literal is the preferred method to interact with the MATLAB engine.
+
 *Note:* There can be multiple (reasonable) ways to convert a MATLAB variable to Julia array. For example, MATLAB represents a scalar using a 1-by-1 matrix. Here we have two choices in terms of converting such a matrix back to Julia: (1) convert to a scalar number, or (2) convert to a matrix of size 1-by-1.
 
 ##### The `mat""` custom string literal
@@ -253,49 +255,19 @@ mat"""
 
 As with ordinary string literals, you can also interpolate whole Julia expressions, e.g. `mat"$(x[1]) = $(x[2]) + $(binomial(5, 2))"`.
 
-##### The `@matlab` macro
-
-The example above can also be written using the `@matlab` macro in combination with `@mput` and `@mget`.
-
-```julia
-using MATLAB
-
-x = linspace(-10., 10., 500)
-@mput x                  # put x to MATLAB's workspace
-@matlab plot(x, sin(x))  # evaluate a MATLAB function
-
-y = linspace(2., 3., 500)
-@mput y
-@matlab begin
-    u = x + y
-	v = x - y
-end
-@mget u v
-@show u v
-```
-
-###### Caveats of @matlab
-
-Note that some MATLAB expressions are not valid Julia expressions. This package provides some ways to work around this in the ``@matlab`` macro:
+##### `eval_string`
 
-```julia
- # MATLAB uses single-quote for strings, while Julia uses double-quote. 
-@matlab sprintf("%d", 10)   # ==> MATLAB: sprintf('%d', 10)
-
- # MATLAB does not allow [x, y] on the left hand side
-x = linspace(-5.0, 5.0, 100)
-y = x
-@mput x y
-@matlab begin
-    (xx, yy) = meshgrid(x, y)  # ==> MATLAB: [xx, yy] = meshgrid(x, y)
-	mesh(xx, yy, xx.^2 + yy.^2)
-end
+You may also use the `eval_string` function to evaluate MATLAB code as follows		
+ ```julia
+eval_string("a = sum([1,2,3])")
 ```
 
-While we try to cover most MATLAB statements, some valid MATLAB statements remain unsupported by ``@matlab``. For this case, one may always call the ``eval_string`` function, as follows
-
+The `eval_string` function also takes an optional argument that specifies which MATLAB session to evaluate the code in, e.g.
 ```julia
-eval_string("[u, v] = myfun(x, y);")
+julia> s = MSession();
+julia> eval_string(s, "a = sum([1,2,3])")
+a =
+     6
 ```
 
 ##### `mxcall`
@@ -309,7 +281,27 @@ xx, yy = mxcall(:meshgrid, 2, x, y)
 ```
 *Note:* Since MATLAB functions behavior depends on the number of outputs, you have to specify the number of output arguments in ``mxcall`` as the second argument.
 
-``mxcall`` puts the input arguments to the MATLAB workspace (using mangled names), evaluates the function call in MATLAB, and retrievs the variable from the MATLAB session. This function is mainly provided for convenience. However, you should keep in mind that it may incur considerable overhead due to the communication between MATLAB and Julia domain.
+``mxcall`` puts the input arguments to the MATLAB workspace (using mangled names), evaluates the function call in MATLAB, and retrieves the variable from the MATLAB session. This function is mainly provided for convenience. However, you should keep in mind that it may incur considerable overhead due to the communication between MATLAB and Julia domain.
+
+##### `@mget` and `@mput`
+
+The macro `@mget` can be used to extract the value of a MATLAB variable into Julia 
+```julia
+julia> mat"a = 6"
+julia> @mget a
+6.0
+```
+
+The macro `@mput` can be used to translate a Julia variable into MATLAB
+```julia
+julia> x = [1,2,3]
+julia> @mput x
+julia> eval_string("y = sum(x)")
+julia> @mget y
+6.0
+julia> @show y
+a = 63.0
+```
 
 #### Viewing the MATLAB Session (Windows only)
 

REQUIRE

@@ -1,2 +1,2 @@
-julia 0.5
-Compat 0.9.5
+julia 0.6
+Compat 0.33.0

src/MATLAB.jl

@@ -2,7 +2,8 @@ __precompile__()
 
 module MATLAB
 
-using Compat.take!
+using Compat
+using Compat.Sys: islinux, iswindows, isapple
 
 import Base: eltype, close, size, copy, ndims, unsafe_convert
 
@@ -31,14 +32,14 @@ export MSession, MatFile,
        eval_string, get_mvariable, get_variable, put_variable, put_variables,
        variable_names, read_matfile, write_matfile,
        mxcall,
-       @mput, @mget, @matlab, @mat_str
+       @mput, @mget, @mat_str
 
-if is_windows()
+if iswindows()
     export show_msession, hide_msession, get_msession_visiblity
 end
 
 # exceptions
-type MEngineError <: Exception
+struct MEngineError <: Exception
     message::String
 end
 
@@ -156,7 +157,7 @@ function __init__()
     mat_get_dir[]      = matfunc(:matGetDir)
 
 
-    if is_windows()
+    if iswindows()
         # workaround "primary message table for module 77" error
         # creates a dummy Engine session and keeps it open so the libraries used by all other
         # Engine clients are not loaded and unloaded repeatedly
@@ -190,4 +191,10 @@ end
 
 @deprecate mxempty() mxarray(Float64,0,0)
 
+export @matlab
+macro matlab(ex)
+    Base.depwarn("@matlab is deprecated, use custom string literal mat\"\" instead.", :matlab)
+    :( MATLAB.eval_string($(mstatement(ex))) )
+end
+
 end

src/engine.jl

@@ -10,17 +10,28 @@ const default_startcmd = matlab_startcmd() * " -nosplash"
 # 64 K buffer should be sufficient to store the output text in most cases
 const default_output_buffer_size = 64 * 1024
 
-type MSession
+mutable struct MSession
     ptr::Ptr{Void}
     buffer::Vector{UInt8}
     bufptr::Ptr{UInt8}
 
     function MSession(bufsize::Integer = default_output_buffer_size)
         ep = ccall(eng_open[], Ptr{Void}, (Ptr{UInt8},), default_startcmd)
-        ep == C_NULL && throw(MEngineError("failed to open a MATLAB engine session"))
-        # hide the MATLAB command window on Windows
-        is_windows() && ccall(eng_set_visible[], Cint, (Ptr{Void}, Cint), ep, 0)
-
+        if ep == C_NULL
+            Base.warn_once("Confirm MATLAB is installed and discoverable.")
+            if iswindows()
+                Base.warn_once("Ensure `matlab -regserver` has been run in a Command Prompt as Administrator.")
+            elseif islinux()
+                Base.warn_once("Ensure `csh` is installed; this may require running `sudo apt-get install csh`.")
+            end
+            throw(MEngineError("failed to open MATLAB engine session"))
+        end
+        if iswindows()
+            # hide the MATLAB command window on Windows and change to current directory
+            ccall(eng_set_visible[], Cint, (Ptr{Void}, Cint), ep, 0)
+            ccall(eng_eval_string[], Cint, (Ptr{Void}, Ptr{UInt8}),
+                ep, "try cd('$(escape_string(pwd()))'); end")
+        end
         buf = Vector{UInt8}(bufsize)
         if bufsize > 0
             bufptr = pointer(buf)
@@ -54,7 +65,7 @@ end
 function close(session::MSession)
     # close a MATLAB Engine session
     ret = ccall(eng_close[], Cint, (Ptr{Void},), session)
-    ret != 0 && throw(MEngineError("failed to close a MATLAB engine session (err = $ret)"))
+    ret != 0 && throw(MEngineError("failed to close MATLAB engine session (err = $ret)"))
     session.ptr = C_NULL
     return nothing
 end
@@ -90,7 +101,7 @@ function close_default_msession()
     return nothing
 end
 
-if is_windows()
+if iswindows()
     function show_msession(m::MSession = get_default_msession())
         ret = ccall(eng_set_visible[], Cint, (Ptr{Void}, Cint), m, 1)
         ret != 0 && throw(MEngineError("failed to show MATLAB engine session (err = $ret)"))
@@ -137,7 +148,7 @@ eval_string(stmt::String) = eval_string(get_default_msession(), stmt)
 function put_variable(session::MSession, name::Symbol, v::MxArray)
     # put a variable into a MATLAB engine session
     ret = ccall(eng_put_variable[], Cint, (Ptr{Void}, Ptr{UInt8}, Ptr{Void}), session, string(name), v)
-    ret != 0 && throw(MEngineError("failed to put the variable $(name) into a MATLAB session (err = $ret)"))
+    ret != 0 && throw(MEngineError("failed to put variable $(name) into MATLAB session (err = $ret)"))
     return nothing
 end
 
@@ -148,7 +159,7 @@ put_variable(name::Symbol, v) = put_variable(get_default_msession(), name, v)
 
 function get_mvariable(session::MSession, name::Symbol)
     pv = ccall(eng_get_variable[], Ptr{Void}, (Ptr{Void}, Ptr{UInt8}), session, string(name))
-    pv == C_NULL && throw(MEngineError("failed to get the variable $(name) from a MATLAB session"))
+    pv == C_NULL && throw(MEngineError("failed to get variable $(name) from MATLAB session"))
     return MxArray(pv)
 end
 
@@ -215,10 +226,6 @@ macro mget(vs...)
     esc( _mget_multi(vs...) )
 end
 
-macro matlab(ex)
-    :( MATLAB.eval_string($(mstatement(ex))) )
-end
-
 
 ###########################################################
 #

src/matfile.jl

@@ -1,6 +1,6 @@
 # mat file open & close
 
-type MatFile
+mutable struct MatFile
     ptr::Ptr{Void}
     filename::String
 

src/matstr.jl

@@ -2,7 +2,7 @@
 
 # A really basic parser intended only to handle checking whether
 # a variable is on the left or right hand side of an expression
-type DumbParserState
+mutable struct DumbParserState
     paren_depth::Int
     in_string::Bool
 end