Switch to re-entrant methods (#46)

* switch to re-entrant methods

we switch from GEOSconnection (with a `status::Symbol`) to GEOScontext
(with a `ptr::GEOSContextHandle_t`), since the former is deprecated for
the latter. This change only applies to everything after GEOS v3.5.0.

There will be a global-level `_context` object that is passed to every
method to maintain the same behavior for now. We might want to also
provide methods that allows users to pass in their own context, and
fallback on the global _context object otherwise.

* expose `context::GEOScontext` as an optional argument to all methods

* switch to WK*Reader and WK*Writer style methods

- introduced `WKTReader`, `WKBReader`, `WKTWriter` and `WKBWriter` types
- we should be promoting the Julian (wrapper) geometry types through
`readgeom` and `writegeom`, rather than encouraging the C-pointers in
`_readgeom` and `_writegeom`
- the corresponding changes are `parseWKT` -> `readgeom`, `geomFromWKT`
-> `_readgeom`, and `geomToWKT` -> `_writegeom`
- moved the `GEOMTYPE` dict into `src/geos_operations.jl` since
`src/geos_functions.jl` is meant more for a direct 1-1 mapping with the
corresponding C functions

* bugfix

* remove module readers and writers in favor of ones local to methods

* update docs

* add deprecated functions

for a smoother transition

* GEOScontext -> GEOSContext

* test readgeom instead of _readgeom

* bugfix

Author: yeesian

README.md

@@ -9,42 +9,37 @@ LibGEOS is a LGPL-licensed package for manipulation and analysis of planar geome
 Among other things, it allows you to parse [Well-known Text (WKT)](https://en.wikipedia.org/wiki/Well-known_text)
 
 ```julia
-p1 = parseWKT("POLYGON((0 0,1 0,1 1,0 0))")
-p2 = parseWKT("POLYGON((0 0,1 0,1 1,0 1,0 0))")
-p3 = parseWKT("POLYGON((2 0,3 0,3 1,2 1,2 0))")
+p1 = readgeom("POLYGON((0 0,1 0,1 1,0 0))")
+p2 = readgeom("POLYGON((0 0,1 0,1 1,0 1,0 0))")
+p3 = readgeom("POLYGON((2 0,3 0,3 1,2 1,2 0))")
 ```
 ![Example 1](examples/example1.png)
 
 Add a buffer around them
 ```julia
-g1 = buffer(p1,0.5)
-g2 = buffer(p2,0.5)
-g3 = buffer(p3,0.5)
+g1 = buffer(p1, 0.5)
+g2 = buffer(p2, 0.5)
+g3 = buffer(p3, 0.5)
 ```
 ![Example 2](examples/example2.png)
 
 and take the union of different geometries
 ```julia
-polygon = union(buffer(p1,0.5),buffer(p3,0.5))
+polygon = LibGEOS.union(g1, g3)
 ```
 ![Example 3](examples/example3.png)
 
 GEOS functionality is extensive, so coverage is incomplete, but the basic functionality for working with geospatial data is already available. I'm learning as I go along, so documentation is lacking, but if you're interested, you can have a look at the examples in the `examples/` folder, or the tests in `test/test_geo_interface.jl` and `test/test_geos_operations.jl`.
 
-Installation (on Linux and OS X)
+Installation
 ------------
-1. First, install a copy of GEOS, and point the `LD_LIBRARY_PATH` (Linux) or `DYLD_LIBRARY_PATH` (OS X) variable to the GEOS library by adding, e.g.,
-  ```bash
-  export DYLD_LIBRARY_PATH="/usr/local/Cellar/geos/3.4.2/lib:$DYLD_LIBRARY_PATH"
-  ```
-to your start-up file (e.g. ``.bash_profile``).
-
-2. At the Julia prompt, run 
+1. At the Julia prompt, run 
   ```julia
   julia> Pkg.add("LibGEOS")
   ```
+  This will install both the Julia package and GEOS shared libraries together. To just reinstall the GEOS shared libraries, run `Pkg.build("LibGEOS")`.
 
-3. Test that `LibGEOS` works by runnning
+2. Test that `LibGEOS` works by runnning
   ```julia
   julia> Pkg.test("LibGEOS")
   ```

examples/example1.png

@@ -13,7 +13,7 @@ module LibGEOS
     import Base: contains
 
     export  Point, MultiPoint, LineString, MultiLineString, LinearRing, Polygon, MultiPolygon, GeometryCollection,
-            parseWKT, geomFromWKT, geomToWKT,
+            parseWKT, geomFromWKT, geomToWKT, readgeom, writegeom,
             project, projectNormalized, interpolate, interpolateNormalized,
             buffer, envelope, intersection, convexhull, difference, symmetricDifference,
             boundary, union, unaryUnion, pointOnSurface, centroid, node,
@@ -40,35 +40,85 @@ module LibGEOS
         end
     end
 
-    mutable struct GEOSconnection
-        status::Symbol
+    mutable struct GEOSContext
+        ptr::GEOSContextHandle_t
 
-        function GEOSconnection()
-            connection = new(:Initialized)
-            initializeGEOS(
-                C_NULL,
+        function GEOSContext()
+            context = new(GEOS_init_r())
+            GEOSContext_setNoticeHandler_r(context.ptr, C_NULL)
+            GEOSContext_setErrorHandler_r(context.ptr,
                 cfunction(geosjl_errorhandler,Ptr{Void},(Ptr{UInt8},Ptr{Void}))
             )
-            finalizer(connection, finalizeGEOS)
-            connection
+            finalizer(context, context -> (GEOS_finish_r(context.ptr); context.ptr = C_NULL))
+            context
         end
     end
 
-    initializeGEOS(notice_f, error_f) = initGEOS(notice_f, error_f)
-    function finalizeGEOS(connection::GEOSconnection)
-        connection.status = :Finished
-        finishGEOS()
+    mutable struct WKTReader
+        ptr::Ptr{GEOSWKTReader}
+
+        function WKTReader(context::GEOSContext)
+            reader = new(GEOSWKTReader_create_r(context.ptr))
+            finalizer(reader, function(reader)
+                GEOSWKTReader_destroy_r(context.ptr, reader.ptr)
+                reader.ptr = C_NULL
+            end)
+            reader
+        end
+    end
+
+    mutable struct WKTWriter
+        ptr::Ptr{GEOSWKTWriter}
+
+        function WKTWriter(context::GEOSContext; trim::Bool=true, outputdim::Int=3, roundingprecision::Int=-1)
+            writer = new(GEOSWKTWriter_create_r(context.ptr))
+            finalizer(writer, function(writer)
+                GEOSWKTWriter_destroy_r(context.ptr, writer.ptr)
+                GEOSWKTWriter_setTrim_r(context.ptr, writer.ptr, UInt8(trim))
+                GEOSWKTWriter_setOutputDimension_r(context.ptr, writer.ptr, outputdim)
+                GEOSWKTWriter_setRoundingPrecision_r(context.ptr, writer.ptr, roundingprecision)
+                writer.ptr = C_NULL
+            end)
+            writer
+        end
+    end
+
+    mutable struct WKBReader
+        ptr::Ptr{GEOSWKBReader}
+
+        function WKBReader(context::GEOSContext)
+            reader = new(GEOSWKBReader_create_r(context.ptr))
+            finalizer(reader, function(reader)
+                GEOSWKBReader_destroy_r(context.ptr, reader.ptr)
+                reader.ptr = C_NULL
+            end)
+            reader
+        end
+    end
+
+    mutable struct WKBWriter
+        ptr::Ptr{GEOSWKBWriter}
+
+        function WKBWriter(context::GEOSContext)
+            writer = new(GEOSWKBWriter_create_r(context.ptr))
+            finalizer(writer, function(writer)
+                GEOSWKBWriter_destroy_r(context.ptr, writer.ptr)
+                writer.ptr = C_NULL
+            end)
+            writer
+        end
     end
 
     function __init__()
         # Always check your dependencies from `deps.jl`
         check_deps()
 
-        global const _connection = GEOSconnection()
+        global const _context = GEOSContext()
     end
 
     include("geos_functions.jl")
     include("geos_types.jl")
     include("geos_operations.jl")
     include("geo_interface.jl")
+    include("deprecated.jl")
 end

examples/example2.png

@@ -0,0 +1,3 @@
+@Base.deprecate parseWKT(geom::String) readgeom(geom)
+@Base.deprecate geomFromWKT(geom::String) _readgeom(geom)
+@Base.deprecate geomToWKT(geom::Ptr{GEOSGeometry}) writegeom(geom)

examples/example3.png

@@ -54,6 +54,14 @@ function finishGEOS_r(handle::GEOSContextHandle_t)
     ccall((:finishGEOS_r,libgeos),Void,(GEOSContextHandle_t,),handle)
 end
 
+function GEOS_init_r()
+    ccall((:GEOS_init_r,libgeos),GEOSContextHandle_t,())
+end
+
+function GEOS_finish_r(handle::GEOSContextHandle_t)
+    ccall((:GEOS_finish_r,libgeos),Void,(GEOSContextHandle_t,),handle)
+end
+
 function GEOSContext_setNoticeHandler_r(extHandle::GEOSContextHandle_t,nf::GEOSMessageHandler)
     ccall((:GEOSContext_setNoticeHandler_r,libgeos),GEOSMessageHandler,(GEOSContextHandle_t,GEOSMessageHandler),extHandle,nf)
 end