slight interface changes and begin working on docs

docs/src/tables.md

@@ -1,5 +1,12 @@
 # CasaCore.Tables
 
+``` @meta
+CurrentModule = CasaCore.Tables
+DocTestSetup = quote
+    using CasaCore.Tables
+end
+```
+
 Load this module by running
 
 ``` julia
@@ -10,6 +17,21 @@ The `Tables` module is used to interact with CasaCore tables. This is a common d
 astronomy. For example CASA measurement sets and CASA calibration tables are simply CasaCore tables
 with a standard set of columns, keywords, and subtables.
 
+## Tables
+
+```@docs
+Table
+Tables.create
+Tables.open
+Tables.close
+Tables.delete
+```
+
+
+
+
+
+
 Opening a table is simple:
 
 ``` julia

src/tables/tables.jl

@@ -15,13 +15,15 @@
 
 @noinline table_exists_error() = err("Table already exists.")
 @noinline table_does_not_exist_error() = err("Table does not exist.")
+@noinline table_readonly_error() = err("Table is read-only.")
+@noinline table_closed_error() = err("Table is closed.")
 
 struct CasaCoreTable end
 
 @enum TableStatus closed=0 readonly=1 readwrite=5
 
 """
-    struct Table
+    mutable struct Table
 
 This type is used to interact with CasaCore tables (including measurement sets).
 
@@ -31,21 +33,73 @@ This type is used to interact with CasaCore tables (including measurement sets).
 - `status` - the current status of the table
 - `ptr` - the pointer to the table object
 
-**Constructors:**
-
 **Usage:**
 
-**See also:**
+```jldoctest
+julia> table = Tables.create("/tmp/my-table.ms")
+Table: /tmp/my-table.ms (read/write)
+
+julia> Tables.add_rows!(table, 3)
+3
+
+julia> table["DATA"] = Complex64[1+2im, 3+4im, 5+6im]
+3-element Array{Complex{Float32},1}:
+ 1.0+2.0im
+ 3.0+4.0im
+ 5.0+6.0im
+
+julia> Tables.close(table)
+closed::CasaCore.Tables.TableStatus = 0
+
+julia> table = Tables.open("/tmp/my-table.ms")
+Table: /tmp/my-table.ms (read-only)
+
+julia> table["DATA"]
+3-element Array{Complex{Float32},1}:
+ 1.0+2.0im
+ 3.0+4.0im
+ 5.0+6.0im
+
+julia> Tables.delete(table)
+```
+
+**See also:** [`Tables.create`](@ref), [`Tables.open`](@ref), [`Tables.close`](@ref),
+[`Tables.delete`](@ref)
 """
-struct Table
+mutable struct Table
     path   :: String
-    status :: Ref{TableStatus}
+    status :: TableStatus
     ptr    :: Ptr{CasaCoreTable}
+    function Table(path, status, ptr)
+        table = new(path, status, ptr)
+        finalizer(table, close)
+        table
+    end
 end
 
 enum2type[TpTable] = Table
 Base.unsafe_convert(::Type{Ptr{CasaCoreTable}}, table::Table) = table.ptr
 
+"""
+    create(path)
+
+Create a CasaCore table at the given path.
+
+**Arguments:**
+
+- `path` - the path where the table will be created
+
+**Usage:**
+
+```jldoctest
+julia> table = Tables.create("/tmp/my-table.ms")
+Table: /tmp/my-table.ms (read/write)
+
+julia> Tables.delete(table)
+```
+
+**See also:** [`Tables.open`](@ref), [`Tables.close`](@ref), [`Tables.delete`](@ref)
+"""
 function create(path)
     path = table_fix_path(path)
     if isfile(path) || isdir(path)
@@ -56,6 +110,38 @@ function create(path)
     Table(path, readwrite, ptr)
 end
 
+"""
+    open(path; write=false)
+
+Open the CasaCore table at the given path.
+
+**Arguments:**
+
+- `path` - the path to the table that will be opened
+
+**Keyword Arguments:**
+
+- `write` - if `false` (the default) the table will be opened read-only
+
+**Usage:**
+
+```jldoctest
+julia> table = Tables.create("/tmp/my-table.ms")
+Table: /tmp/my-table.ms (read/write)
+
+julia> table′ = Tables.open("/tmp/my-table.ms")
+Table: /tmp/my-table.ms (read-only)
+
+julia> table″ = Tables.open("/tmp/my-table.ms", write=true)
+Table: /tmp/my-table.ms (read/write)
+
+julia> Tables.close(table′)
+       Tables.close(table″)
+       Tables.delete(table)
+```
+
+**See also:** [`Tables.create`](@ref), [`Tables.close`](@ref), [`Tables.delete`](@ref)
+"""
 function open(path; write=false)
     path = table_fix_path(path)
     if !isdir(path)
@@ -67,14 +153,79 @@ function open(path; write=false)
     Table(path, mode, ptr)
 end
 
+function open(table::Table; write=false)
+    if !isopen(table)
+        path = table_fix_path(table.path)
+        if !isdir(path)
+            table_does_not_exist_error()
+        end
+        mode = write ? readwrite : readonly
+        ptr = ccall((:new_table_open, libcasacorewrapper), Ptr{CasaCoreTable},
+                    (Ptr{Cchar}, Cint), path, mode)
+        Table(path, mode, ptr)
+    end
+    table
+end
+
+"""
+    close(table)
+
+Close the given CasaCore table.
+
+**Arguments:**
+
+- `table` - the table to be closed
+
+**Usage:**
+
+```jldoctest
+julia> table = Tables.create("/tmp/my-table.ms")
+Table: /tmp/my-table.ms (read/write)
+
+julia> Tables.close(table)
+closed::CasaCore.Tables.TableStatus = 0
+
+julia> Tables.delete(table)
+```
+
+**See also:** [`Tables.create`](@ref), [`Tables.open`](@ref), [`Tables.delete`](@ref)
+"""
 function close(table::Table)
-    if table.status[] != closed
+    if isopen(table)
         ccall((:delete_table, libcasacorewrapper), Void,
               (Ptr{CasaCoreTable},), table)
-        table.status[] = closed
+        table.status = closed
     end
 end
 
+"""
+    delete(table)
+
+Close and delete the given CasaCore table.
+
+**Arguments:**
+
+- `table` - the table to be deleted
+
+**Usage:**
+
+```jldoctest
+julia> table = Tables.create("/tmp/my-table.ms")
+Table: /tmp/my-table.ms (read/write)
+
+julia> Tables.delete(table)
+```
+
+**See also:** [`Tables.create`](@ref), [`Tables.open`](@ref), [`Tables.create`](@ref)
+"""
+function delete(table::Table)
+    close(table)
+    rm(table.path, recursive=true, force=true)
+end
+
+isopen(table::Table) = table.status != closed
+iswritable(table::Table) = table.status == readwrite
+
 function table_fix_path(path)
     # Remove the "Table: " prefix, if it exists
     if startswith(path, "Table: ")
@@ -87,11 +238,11 @@ function table_fix_path(path)
 end
 
 function Base.show(io::IO, table::Table)
-    if table.status[] == closed
+    if table.status == closed
         str = " (closed)"
-    elseif table.status[] == readonly
-        str = " (read only)"
-    elseif table.status[] == readwrite
+    elseif table.status == readonly
+        str = " (read-only)"
+    elseif table.status == readwrite
         str = " (read/write)"
     else
         str = ""

test/tables.jl

@@ -34,7 +34,7 @@
         table = Tables.open(path)
         @test table.path == path
         @test table.status[] === Tables.readonly
-        @test repr(table) == "Table: "*path*" (read only)"
+        @test repr(table) == "Table: "*path*" (read-only)"
         Tables.close(table)
 
         table = Tables.open(path, write=true)
@@ -49,10 +49,10 @@
         table = Tables.open("Table: "*path)
         @test table.path == path
         @test table.status[] === Tables.readonly
-        @test repr(table) == "Table: "*path*" (read only)"
-        Tables.close(table)
+        @test repr(table) == "Table: "*path*" (read-only)"
 
-        rm(path, force=true, recursive=true)
+        Tables.delete(table)
+        @test !isdir(table.path) && !isfile(table.path)
 
         # Issue #58
         # This will create a temporary table in the user's home directory so only run this test if
@@ -101,8 +101,7 @@
         Tables.remove_rows!(table, 1:Tables.num_rows(table))
         @test Tables.num_rows(table) == 0
 
-        Tables.close(table)
-        rm(path, force=true, recursive=true)
+        Tables.delete(table)
     end
 
     @testset "basic columns" begin
@@ -152,8 +151,7 @@
             Tables.remove_column!(table, "test")
         end
 
-        Tables.close(table)
-        rm(path, force=true, recursive=true)
+        Tables.delete(table)
     end
 
     @testset "basic cells" begin
@@ -199,8 +197,7 @@
             Tables.remove_column!(table, "test")
         end
 
-        Tables.close(table)
-        rm(path, force=true, recursive=true)
+        Tables.delete(table)
     end
 
     @testset "basic keywords" begin
@@ -239,8 +236,7 @@
             end
         end
 
-        Tables.close(table)
-        rm(path, force=true, recursive=true)
+        Tables.delete(table)
     end
 
     @testset "column keywords" begin
@@ -283,8 +279,7 @@
             end
         end
 
-        Tables.close(table)
-        rm(path, force=true, recursive=true)
+        Tables.delete(table)
     end
 
     @testset "old tests" begin
@@ -432,7 +427,7 @@
         @test_throws CasaCoreTablesError table′["FABRICATED_DATA"]
         Tables.close(table′)
 
-        rm(path, force=true, recursive=true)
+        Tables.delete(table)
     end
 end