yeesian · visr · Dec 27, 2019 · Jan 23, 2019 · Jan 23, 2019 · Jan 23, 2019
diff --git a/.travis.yml b/.travis.yml
@@ -5,18 +5,21 @@ os:
   - osx
 julia:
   - 1.0
+  - 1
   - nightly
-# matrix:
-#   allow_failures:
-#   - julia: nightly
-#   fast_finish: true
+matrix:
+  allow_failures:
+    - julia: nightly
 notifications:
   email: false
-# uncomment the following lines to override the default test script
-# script:
-#  - if [[ -a .git/shallow ]]; then git fetch --unshallow; fi
-#  - julia -e 'using Pkg; Pkg.clone(pwd()); Pkg.build("ArchGDAL"); Pkg.test("ArchGDAL"; coverage=true)'
-after_success:
-- julia -e 'using Pkg; Pkg.add(["Documenter", "Coverage"])'
-- julia -e 'using ArchGDAL; cd(dirname(dirname(pathof(ArchGDAL)))); include(joinpath("docs", "make.jl"))'
-- julia -e 'using ArchGDAL, Coverage; cd(dirname(dirname(pathof(ArchGDAL)))); Coveralls.submit(process_folder())'
+coveralls: true
+jobs:
+  include:
+    - stage: "Documentation"
+      julia: 1
+      os: linux
+      script:
+        - julia --project=docs/ -e 'using Pkg; Pkg.develop(PackageSpec(path=pwd()));
+                                               Pkg.instantiate()'
+        - julia --project=docs/ docs/make.jl
+      after_success: skip
diff --git a/LICENSE.md b/LICENSE.md
@@ -1,6 +1,6 @@
 The ArchGDAL.jl package is licensed under the MIT "Expat" License:
 
-> Copyright (c) 2016: yeesian.
+> Copyright (c) 2019: Yeesian Ng, Maarten Pronk, Martijn Visser, and contributors
 >
 > Permission is hereby granted, free of charge, to any person obtaining
 > a copy of this software and associated documentation files (the

diff --git a/Project.toml b/Project.toml
@@ -1,6 +1,9 @@
 name = "ArchGDAL"
 uuid = "c9ce4bd3-c3d5-55b8-8973-c0e20141b8c3"
-version = "0.2.2"
+keywords = ["GDAL", "IO"]
+license = "MIT"
+desc = "A high level API for GDAL - Geospatial Data Abstraction Library"
+version = "0.3.0"
 
 [deps]
 DataStreams = "9a8bc11e-79be-5b39-94d7-1ccc349a1a85"
@@ -10,9 +13,9 @@ GeoInterface = "cf35fbd7-0cd7-5166-be24-54bfbe79505f"
 
 [compat]
 DataStreams = "0.4.2"
-GDAL = "0.2"
+GDAL = "1.0.2"
 GeoInterface = "0.4"
-julia = "0.7, 1.0"
+julia = "1"
 
 [extras]
 BinaryProvider = "b99e7846-7c00-51b0-8f62-c81ae34c0232"

diff --git a/README.md b/README.md
@@ -12,9 +12,7 @@ This package aims to be a complete solution for working with GDAL in Julia, simi
 ## Principles (The Arch Way)
 (adapted from: https://wiki.archlinux.org/index.php/Arch_Linux#Principles)
 
-- **simplicity**: without unnecessary additions or modifications.
-    (i) Preserves GDAL Data Model, and makes available GDAL/OGR methods without trying to mask them from the user.
-    (ii) minimal dependencies
+- **simplicity**: ArchGDAL tries to avoid unnecessary additions or modifications. It preserves the GDAL Data Model and requires minimal dependencies.
 - **modernity**: ArchGDAL strives to maintain the latest stable release versions of GDAL as long as systemic package breakage can be reasonably avoided.
 - **pragmatism**: The principles here are only useful guidelines. Ultimately, design decisions are made on a case-by-case basis through developer consensus. Evidence-based technical analysis and debate are what matter, not politics or popular opinion.
 - **user-centrality**: Whereas other libraries attempt to be more user-friendly, ArchGDAL shall be user-centric. It is intended to fill the needs of those contributing to it, rather than trying to appeal to as many users as possible.

diff --git a/appveyor.yml b/appveyor.yml
@@ -1,17 +1,16 @@
 environment:
   matrix:
   - julia_version: 1.0
+  - julia_version: 1
   - julia_version: nightly
 
 platform:
   - x86 # 32-bit
   - x64 # 64-bit
 
-# # Uncomment the following lines to allow failures on nightly julia
-# # (tests will run but not make your overall status red)
-# matrix:
-#   allow_failures:
-#   - julia_version: nightly
+matrix:
+  allow_failures:
+  - julia_version: nightly
 
 branches:
   only:

diff --git a/docs/Project.toml b/docs/Project.toml
@@ -0,0 +1,6 @@
+[deps]
+ArchGDAL = "c9ce4bd3-c3d5-55b8-8973-c0e20141b8c3"
+Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+
+[compat]
+Documenter = "0.23"
diff --git a/docs/make.jl b/docs/make.jl
@@ -2,7 +2,7 @@ using Documenter, ArchGDAL
 
 makedocs(
     modules = [ArchGDAL],
-    format = :html,
+    format = Documenter.HTML(),
     sitename = "ArchGDAL.jl",
     pages = [
         "index.md",
@@ -11,8 +11,8 @@ makedocs(
         "Raster Data" => "rasters.md",
         "Geometric Operations" => "geometries.md",
         "Spatial Projections" => "projections.md",
-        "Memory Management" => "memory.md",
-        "Working with Spatialite" => "spatialite.md"
+        "Interactive versus Scoped Objects" => "memory.md"
+        # "Working with Spatialite" => "spatialite.md"
         # "Naming Conventions" => "conventions.md", # table between GDAL, GDAL.jl, and ArchGDAL.jl
     ]
 
@@ -23,5 +23,4 @@ deploydocs(
     make = nothing,
     target = "build",
     repo = "github.com/yeesian/ArchGDAL.jl.git",
-    julia = "1.0"
 )
diff --git a/docs/src/considerations.md b/docs/src/considerations.md
@@ -1,11 +1,5 @@
 # Design Considerations
 
-## Data Serialization
-
-As modern [builds](https://trac.osgeo.org/gdal/wiki/BuildHints) of GDAL (e.g. by [Homebrew](https://github.com/OSGeo/homebrew-osgeo4mac) and [Conda-Forge](https://github.com/conda-forge/gdal-feedstock)) comes pre-compiled with support for PROJ.4 and GEOS, one of the goals of `ArchGDAL.jl` is for it to enjoy the full spectrum of GIS functionality, while avoiding the price of data serialization in [duck-typing proposals](https://gist.github.com/sgillies/2217756).
-
-In the long term, this decouples (i) the development and maintenance of a high-level interface for GDAL from (ii) the development and maintenance of other projects relying on customized builds of GDAL. `ArchGDAL.jl` and [`GDAL.jl`](https://github.com/visr/GDAL.jl) are only concerned with (i), and will only be developed and tagged in accordance with [release changes](https://trac.osgeo.org/gdal/wiki/NewsAndStatus) in GDAL's C API.
-
 ## Code Defensiveness
 
 Although GDAL provides a unified data model for different data formats, there are still significant differences between their implementations such that each driver is effectively its own application. This has the following implications:
@@ -14,7 +8,7 @@ Although GDAL provides a unified data model for different data formats, there ar
 - Not all capabilities are available for all drivers.
 - Performance characteristics may vary significantly depending on the driver.
 
-`ArchGDAL.jl` provides mechanisms similar to those of mapbox/rasterio for setting GDAL's configuration options, and does not maintain its own list of *sanctioned* options for each driver. Although [ongoing work is underway](https://github.com/yeesian/GDALUtils.jl/issues/1) to make this an easier experience for the user, it remains the responsibility of the user to check that a particular configuration exists and works for their choice of driver.
+`ArchGDAL.jl` provides mechanisms for setting GDAL's configuration options, and does not maintain its own list of sanctioned options for each driver. Although work is underway to make this an easier experience for the user, it remains the responsibility of the user to check that a particular configuration exists and works for their choice of drivers.
 
 Here's a collection of references for developers who are interested:
 - https://trac.osgeo.org/gdal/wiki/ConfigOptions

diff --git a/docs/src/datasets.md b/docs/src/datasets.md
@@ -1,140 +1,113 @@
-# GDAL Datasets
+# Data Model
+
+## GDAL Datasets
 
 The following code demonstrates the general workflow for reading in a dataset:
 
 ```julia
-ArchGDAL.registerdrivers() do
-    ArchGDAL.read(filename) do dataset
-        # work with dataset
-    end
+ArchGDAL.read(filename) do dataset
+    # work with dataset
 end
 ```
 
-We defer the discussions on `ArchGDAL.registerdrivers()` and `ArchGDAL.read(filename)` to the sections on [Driver Management](@ref) and [Working with Files](@ref) respectively.
-
-!!! note
-
-    In this case, a handle to the dataset is obtained, and no further data was requested. It is only when we run `print(dataset)` that calls will be made through GDAL's C API to obtain information about `dataset` for display.
+We defer the discussion on `ArchGDAL.read(filename)` to the section on [Working with Files](@ref).
 
 ## Vector Datasets
-```@setup vector_example
-import ArchGDAL
-filepath = download("https://github.com/raw/yeesian/ArchGDALDatasets/307f8f0e584a39a050c042849004e6a2bd674f99/data/point.geojson", "point.geojson")
-```
-In this section, we work with the [`data/point.geojson`](https://github.com/yeesian/ArchGDALDatasets/blob/307f8f0e584a39a050c042849004e6a2bd674f99/data/point.geojson) dataset via
-```@example vector_example
-ArchGDAL.registerdrivers() do
-    ArchGDAL.read(filepath) do dataset
-        print(dataset)
-    end
-end
+In this section, we work with the [`data/point.geojson`](https://github.com/yeesian/ArchGDALDatasets/blob/307f8f0e584a39a050c042849004e6a2bd674f99/data/point.geojson) dataset:
+```julia
+julia> dataset = ArchGDAL.read("data/point.geojson")
+GDAL Dataset (Driver: GeoJSON/GeoJSON)
+File(s):
+  data/point.geojson
+
+Number of feature layers: 1
+  Layer 0: point (wkbPoint)
 ```
 
 The display indicates
 * the **type** of the object (`GDAL Dataset`)
 * the **driver** used to open it (shortname/longname: `GeoJSON/GeoJSON`)
-* the **files** that it corresponds to (`point.geojson`)
-* the **number of layers** in the dataset, and their brief summary.
+* the **files** that it corresponds to (`data/point.geojson`)
+* the **number of layers** in the dataset (`1`), and a brief summary of each.
 
 You can also programmatically retrieve them using
-* `typeof(dataset)`: the **type** of the object
-* `ArchGDAL.filelist(dataset)`: the **files** that it corresponds to
-* `ArchGDAL.nlayer(dataset)`: the **number of layers** in the dataset
-* `drv = ArchGDAL.getdriver(dataset)`: the **driver** used to open it
-* `ArchGDAL.shortname(drv)`: the short name of a driver
-* `ArchGDAL.longname(drv)`: the long name of a driver
-* `layer = ArchGDAL.getlayer(dataset, i)`: the `i`-th layer in `dataset`.
-* `ArchGDAL.getgeomtype(layer)`: the geometry type for `layer` (i.e. `wkbPoint`)
-* `ArchGDAL.getname(layer)`: the name of `layer` (i.e. `OGRGeoJSON`)
-* `ArchGDAL.nfeature(layer)`: the number of features in `layer` (i.e. `4`)
-
-For more on working with features and vector data, see the Section on `Feature Data`.
+* `typeof(dataset)`: the **type** of the object (`GDAL Dataset`)
+* `ArchGDAL.filelist(dataset)`: the **files** that it corresponds to (`["data/point.geojson"]`)
+* `ArchGDAL.nlayer(dataset)`: the **number of layers** in the dataset (`1`)
+* `driver = ArchGDAL.getdriver(dataset)`: the **driver** used to open it
+* `ArchGDAL.shortname(driver)`: the **short name** of a driver (`"GeoJSON"`)
+* `ArchGDAL.longname(driver)`: the **long name** of a driver (`"GeoJSON"`)
+* `layer = ArchGDAL.getlayer(dataset, i)`: the `i`-th layer in the dataset.
+* `ArchGDAL.getgeomtype(layer)`: the **geometry type** for `layer` (i.e. `wkbPoint`)
+* `ArchGDAL.getname(layer)`: the **name** of `layer` (i.e. `point`)
+* `ArchGDAL.nfeature(layer)`: the **number of features** in the `layer` (i.e. `4`)
+
+For more on working with features and vector data, see the Section on [Feature Data](@ref).
 
 ## Raster Datasets
-```@setup raster_example
-import ArchGDAL
-filepath = download("https://github.com/yeesian/ArchGDALDatasets/blob/307f8f0e584a39a050c042849004e6a2bd674f99/gdalworkshop/world.tif?raw=true", "world.tif")
-```
 In this section, we work with the [`gdalworkshop/world.tif`](https://github.com/yeesian/ArchGDALDatasets/blob/307f8f0e584a39a050c042849004e6a2bd674f99/gdalworkshop/world.tif) dataset:
-```@example raster_example
-ArchGDAL.registerdrivers() do
-    ArchGDAL.read(filepath) do dataset
-        print(dataset)
-    end
-end
+```julia
+julia> dataset = AG.read("gdalworkshop/world.tif")
+GDAL Dataset (Driver: GTiff/GeoTIFF)
+File(s):
+  gdalworkshop/world.tif
+
+Dataset (width x height): 2048 x 1024 (pixels)
+Number of raster bands: 3
+  [GA_ReadOnly] Band 1 (Red): 2048 x 1024 (UInt8)
+  [GA_ReadOnly] Band 2 (Green): 2048 x 1024 (UInt8)
+  [GA_ReadOnly] Band 3 (Blue): 2048 x 1024 (UInt8)
 ```
 
 The display indicates
 * the **type** of the object (`GDAL Dataset`)
 * the **driver** used to open it (shortname/longname: `GTiff/GeoTIFF`)
-* the **files** that it corresponds to (`world.tif`)
-* the **number of raster bands** in the dataset, and their brief summary.
+* the **files** that it corresponds to (`gdalworkshop/world.tif`)
+* the **number of raster bands** in the dataset (`3`), and a brief summary of each.
 
 You can also programmatically retrieve them using
-* `typeof(dataset)`: the type of the object
-* `ArchGDAL.filelist(dataset)`: the files that it corresponds to
-* `ArchGDAL.nraster(dataset)`: the number of rasters
+* `typeof(dataset)`: the **type** of the object (`GDAL Dataset`)
+* `ArchGDAL.filelist(dataset)`: the **files** that it corresponds to (`["gdalworkshop/world.tif"]`)
+* `ArchGDAL.nraster(dataset)`: the **number of rasters** (`3`)
 * `ArchGDAL.width(dataset)` the width (`2048` pixels)
 * `ArchGDAL.height(dataset)` the height (`1024` pixels)
-* `drv = ArchGDAL.getdriver(dataset)`: the driver used to open it
-* `ArchGDAL.shortname(drv)`: the short name of a driver
-* `ArchGDAL.longname(drv)`: the long name of a driver
+* `driver = ArchGDAL.getdriver(dataset)`: the **driver** used to open it
+* `ArchGDAL.shortname(driver)`: the **short name** of a driver (`"GTiff"`)
+* `ArchGDAL.longname(driver)`: the **long name** of a driver (`"GeoTIFF"`)
 * `band = ArchGDAL.getband(dataset, i)`: the `i`-th raster band
-* `i = ArchGDAL.getnumber(band)`: the index of `band`.
-* `ArchGDAL.getaccess(band)`: the access flag (i.e. `GA_ReadOnly`)
-* `ArchGDAL.getname(ArchGDAL.getcolorinterp(rasterband))`: the color channel (e.g. `Red`)
-* `ArchGDAL.width(band)` the width (`2048` pixels) of the band
-* `ArchGDAL.height(band)` the height (`1024` pixels) of the band
-* `ArchGDAL.getdatatype(band)`: the pixel type (i.e. `UInt8`)
-
-For more on working with raster data, see the Section on `Raster Data`.
-
-## Driver Management
-Before opening a GDAL supported datastore it is necessary to register drivers. Normally this is accomplished with the `GDAL.allregister()` function which registers all known drivers. However, the user will then need to remember to de-register the drivers using `GDAL.destroydrivermanager()` when they're done.
+* `i = ArchGDAL.indexof(band)`: the **index** of the raster band.
+* `ArchGDAL.accessflag(band)`: the **access flag** (i.e. `GA_ReadOnly`)
+* `ArchGDAL.getname(ArchGDAL.getcolorinterp(band))`: the **color channel** (e.g. `Red`)
+* `ArchGDAL.width(band)` the **width** of the raster band (`2048` pixels)
+* `ArchGDAL.height(band)` the **height** of the raster band (`1024` pixels)
+* `ArchGDAL.pixeltype(band)`: the **pixel type** of the raster band (i.e. `UInt8`)
 
-In ArchGDAL, we provide a `registerdrivers()` block, such that
-
-```julia
-ArchGDAL.registerdrivers() do
-    # your code here
-end
-```
-is equivalent to
-
-```julia
-GDAL.allregister()
-# your code here
-GDAL.destroydrivermanager()
-```
+For more on working with raster data, see the Section on [Raster Data](@ref).
 
 ## Working with Files
 We provide the following methods for working with files:
 
-* `ArchGDAL.createcopy()`: create a copy of a raster dataset. This is often used with a virtual source dataset allowing configuration of band types, and other information without actually duplicating raster data.
-* `ArchGDAL.create()`: creates a new dataset Note: many sequential write-once formats (such as JPEG and PNG) don't implement the `Create()` method but do implement the `CreateCopy()` method. If the driver doesn't implement `CreateCopy()`, but does implement `Create()` then the default `CreateCopy()` mechanism built on calling `Create()` will be used.
-* `ArchGDAL.read()`: opens a dataset in read-only mode. The returned dataset should only be accessed by one thread at a time. To use it from different threads, you must add all necessary code (mutexes, etc.) to avoid concurrent use of the object. (Some drivers, such as GeoTIFF, maintain internal state variables that are updated each time a new block is read, preventing concurrent use.)
+* `ArchGDAL.copy()`: creates a copy of a dataset. This is often used with a virtual source dataset allowing configuration of band types, and other information without actually duplicating raster data.
+* `ArchGDAL.create()`: creates a new dataset.
+* `ArchGDAL.read()`: opens a dataset in read-only mode.
 * `ArchGDAL.update()`: opens a dataset with the possibility of updating it. If you open a dataset object with update access, it is not recommended to open a new dataset on the same underlying file.
 
-For each one of them, we will call `ArchGDAL.destroy` at the end of the `do`-block which will dispatch to the corresponding GDAL method. For example,
+In GDAL, datasets are closed by calling `GDAL.close()`. This will result in proper cleanup, and flushing of any pending writes. Forgetting to call `GDAL.close()` on a dataset opened in update mode in a popular format like `GTiff` will likely result in being unable to open it afterwards.
 
+In ArchGDAL, the closing of datasets is handled by the API and not by the user. ArchGDAL provides two methods for working with datasets.
+
+The first is to use a do-block:
 ```julia
-ArchGDAL.read(filename) do dataset
+ArchGDAL.<copy/create/read/update>(...) do dataset
     # work with dataset
 end
 ```
-
-will correspond to
-
+The second is to call the method directly:
 ```julia
-dataset = ArchGDAL.unsafe_read(filename)
+dataset = ArchGDAL.<copy/create/read/update>(...)
 # work with dataset
-ArchGDAL.destroy(dataset) # the equivalent of GDAL.close(dataset.ptr)
 ```
 
-!!! note
-
-    In GDAL, datasets are closed by calling `GDAL.close()`. This will result in proper cleanup, and flushing of any pending writes. Forgetting to call `GDAL.close()` on a dataset opened in update mode in a popular format like `GTiff` will likely result in being unable to open it afterwards.
-
 !!! note
 
     This pattern of using `do`-blocks to manage context plays a big way into the way we handle memory in this package. For details, see the section on Memory Management.