Have a consistent scheme for choosing names

[yeesian]

A rough organization into a few themes:

getcount() = n()

Examples:

    - getgcpcount -> ngcp
    - datasetgetlayercount -> nlayer
    - getrastercount -> nraster
    - getdrivercount -> ndriver
    - getpointcount -> npoint 
    - getgeometrycount -> ngeometry
    - getfieldcount -> nfield 
    - getgeomfieldcount -> ngeomfield
    - getfeaturecount -> nfeature
    - getfieldcount -> nfield
    - getoverviewcount -> noverview

Remove typenames

(rely on multi-dispatch instead) Examples:

    - datasetcopywholeraster -> copywholeraster
    - deletedataset -> delete
    - renamedataset -> rename
    - copydatasetfiles -> copyfiles
    - getrasterunittype -> getunittype
    - setrasterunittype -> setunittype
    - getrasteroffset -> getoffset
    - setrasteroffset -> setoffset 
    - getrasterscale -> getscale
    - setrasterscale -> setscale
    - getrasterdatatype -> getdatatype
    - getrasteraccess -> getaccess
    - getrasterband -> fetchband (new syntax)
    - getbandnumber -> getindex (new syntax)
    - getbanddataset -> getdataset
    - getrasternodatavalue -> getnodatavalue
    - setrasternodatavalue -> setnodatavalue
    - getrastersampleoverview -> getsampleoverview
    - getrastercolorinterpretation -> getcolorinterp (name shortening)
    - setrastercolorinterpretation -> setcolorinterp (name shortening)
    - getrastercolortable -> getcolortable
    - setrastercolortable -> setcolortable/clearcolortable (new syntax)
    - rasterbandcopywholeraster -> copywholeraster
    - getdatasetdriver -> getdriver
    - destroydriver -> destroy
    - registerdriver -> register
    - deregisterdriver -> deregister 
    - getdrivercreationoptionlist -> options (name shortening)
    - getdrivershortname -> getshortname
    - getdriverlongname -> getlongname
    - datasetrasterio -> rasterio
    - destroygeometry -> destroy
    - datasetdeletelayer -> deletelayer
    - datasetcreatelayer -> createlayer
    - datasetcopylayer -> copylayer
    - datasetexecutesql -> executesql
    - datasetreleaseresultset -> releaseresultset
    - creategeomfield -> createfield
    - addgeomfielddefn -> add
    - deletegeomfielddefn -> delete

Remove "ref"

(no pointers); Examples

    - getprojectionref -> getproj (name shortening)
    - getgeomfielddefnref -> fetchgeomfielddefn (new syntax)
    - getgeomfieldref -> fetchgeomfield (new syntax)
    - getgeometryref(geom, i) -> fetchgeom (new syntax)
    - getgeometryref(feature) -> getgeom (name shortening)
    - getfielddefnref(feature, i) -> getfielddefn
    - getdefnref -> getfeaturedefn
    - getnameref -> getname

Format

(Export/Import, From/To); Examples:

    - createfromwkb -> fromWKB
    - createfromwkt -> fromWKT
    - createfromgml -> fromGML
    - creategeometryfromjson -> fromJSON
    - importfromwkb -> fromWKB
    - exporttowkb -> toWKB
    - exporttoisowkb -> toISOWKB
    - exporttogml -> toGML
    - exporttokml -> toKML
    - exporttojson -> toJSON

New Syntax

    - [new] fetch/update
    - getrasterband -> fetchband
    - datasetgetlayer/datasetgetlayerbyname -> fetchlayer
    - openshared/openex -> read/update
    - close(createcopy(...)) -> write(...)
    - value -> pointalongline
    - setspatialfilterex -> setspatialfilter/clearspatialfilter
    - getbandnumber -> getindex
    - setrastercolortable -> setcolortable/clearcolortable
    - getfieldasinteger -> asint, etc
    - setfieldinteger -> setfield, etc
    - getnextfeature -> fetchnext
    - getrasterxsize, getrasterysize -> width, height
    - getrasterbandxsize, getrasterbandysize -> width, height
    - assignspatialreference -> setspatialref
    - removegeometry -> removegeom /removeallgeoms

Name dropping/shortening

Examples:

    - coordinate -> coord
    - dimension -> dim
    - spatialreference -> spatialref
    - geometry -> geom
    - interpretation -> interp
    - buildpolygon -> polygon
    - nativemedia -> media
    - fillunsetwithdefault -> fillunset
    - drivercreationoptionlist -> options
    - projection -> proj

instances:

    - getcoordinatedimension -> getcoorddim
    - setcoordinatedimension -> setcoorddim
    - getgeometrytype -> getgeomtype
    - getgeometryname -> getgeomname
    - assignspatialreference -> setspatialref (new syntax)
    - getspatialreference -> getspatialref 
    - addgeometry -> addgeom
    - addgeometrydirectly -> addgeomdirectly
    - removegeometry -> removegeom /removeallgeoms (new syntax)
    - hascurvegeometry -> hascurvegeom
    - getlineargeometry -> getlineargeom
    - getgeometrycolumn -> getgeomcolumn
    - getcolorinterpretationbyname -> getcolorinterp
    - validatecreationoptions -> validate
    - buildpolygonfromedges -> polygonfromedges
    - getnativemediatype -> getmediatype
    - setnativemediatype -> setmediatype
    - fillunsetwithdefault -> fillunset 
    - getdrivercreationoptionlist -> options
    - getprojectionref -> getproj
    - setprojection -> setproj

[yeesian]

Some lingering thoughts:

1. whether to change methods with both getters and setters to julian-like attributes
   • pros: light on the eyes, easy to find (using tab-completion)
   • cons: might be confused for wrapper state/attributes
2. whether to motivate the notion of fetch (overriding get in some cases)
   • get/set: for heterogeneous attributes of individual items
   • fetch/update: for collections of homogeneous items
3. whether to drop get/set from the method name when there is no corresponding set/get

[yeesian]

Thoughts? (See the developments at https://github.com/visr/GDAL.jl for context.)

@visr @meggart @garborg @wkearn @c42f @joa-quim @marciolegal @sboysel @tedsteiner @awbsmith @penntaylor @ljwolf

[visr]

Nice list, good to get some discussion started. In general I quite like the names you propose, but I'm also thinking about some more radical ideas. Do you explicitly want to avoid extending Base functions? Since we have new types for all components I believe we can make good use of them extending Base functions without problems. What about these for example:

• Replace all get___count() / n___() by new methods of Base.length.
• Add methods to Base.getindex instead of fetch
• Add methods to Base.setindex instead of update
• Replacing create___ with type constructors: createlayer() -> Layer()
• Make rasterbands a subtype of AbstractArray?

[yeesian]

What I worry about for Base.getindex and Base.setindex is how it makes it seem as if they are cheap operations, when in fact a lot might be happening under the hood, and I'm not sure it's behavior to be encouraged yet [1].

I think we need a good set of idiomatic (and performant) GDAL usage code before we decide what methods/behavior to encourage.

---

So if you find yourself needing to use the methods for fetch/update a lot, maybe you should be encouraged/prodded to read them into a buffer/array, and then to work with that buffer/array (which will have nice Base.getindex and Base.setindex syntax), rather than working with the thin object wrapper.

It's the same issue with rasterbands being a subtype of AbstractArray. That said, we could/should make it easy to

• manipulate rasters in memory (a la https://github.com/mapbox/rasterio/issues/578), and
• work with virtual dataset/formats

though. I'm going to spend more time digging through other developers' notes and trying different proposals here first.

---

[1]: On the other hand, my arguments above is weak if we're talking about Base.getindex and Base.setindex for "arrays of pointers". (so they all remain as "views", rather than concrete instantiations of in-memory values).

[yeesian]

Replace all getcount() / n() by new methods of Base.length. [...] Replacing create___ with type constructors: createlayer() -> Layer()

I have considered them too. A concern I have is that methods might seem to be "disappearing" from the GDAL API if we make them base-methods/type-constructors.

But you're right, I think that might be more of a documentation issue, rather than an argument in syntax choice.

There's also the possibility of providing both the base-method/type-constructor, as well as the corresponding (simplified) GDAL API methods, in which case we can defer the decision on implementing base-methods/type-constructors to a separate issue.

[ljwolf]

I think the "both" is a reasonable way to go. As a general rule, I don't typically expect basemethods to be extended correctly. Specifically, I have in mind some confusion people have about generic magic methods behavior in Python GIS, where the "len" of a polyline isn't super clear on whether it's the measured length of the arc or the number of points defining its nodes.

Confusions like that, I think, make it necessary to provide the corresponding raw methods, and then (hopefully) transparently add them as methods in a reasonable way to appropriate Base.* functions. As long as a package makes it clear how, say Base.length might dispatch to getpointcount or getarclength, we're in the clear.