Add user-friendly wrapper functions

florisvdh commented 3 months ago

The addition of user-friendly wrappers was discussed last GRASS GIS Community Meeting (2023) - see discussion https://github.com/rsbivand/rgrass/discussions/78:

TO DO: make an issue with proposed new function names, usage (new arguments with defaults), and an indication of 'becoming internal'. So also including old function names that are kept (internally).

The referred discussion contains more details. We're planning to contribute to some of the discussed rgrass topics at the upcoming Meeting, which starts this week.

Here follow some very rough ideas to give this a start and get some first feedback already. This definitely needs more thought and experimentation while implementing, e.g. through vignettes and examples. That also includes the arguments of below functions. I don't want to push anything, it's all open to change.

Note that the underlying functions of the wrappers would be the current unchanged functions.

They wouldn't be internalized once all new exported functions are in place, but only after a much longer period.
Functions not covered below would not be covered by exported wrapper functions or aliases and eventually be internalized, such as the functions to set & get package specific options, but this also needs more thought (now assuming they're for internal use only, but this needs more investigation at least for me).

Proposition: eventually use grass_ as prefix for all exported functions. (in qgisprocess package the qgis_ prefix is used)

Main functions (names are the wrappers)

grass_init() grass_vect() (to read vector layer; name inspired by terra) grass_rast() (to read raster; name inspired by terra) grass_write() grass_help() grass_exec()

(grass_write() could detect whether it needs write_VECT() or write_RAST() as backend based on the inputted R object, and check whether the appropriate (and no inappropriate) arguments are present. If such integration proves too difficult or user-unfriendly, we can still split into e.g. grass_write_vect and grass_write_rast() but a short name might be appealing)

Export; consider `grass_` function names for wrappers/aliases

gmeta() getLocationProj() gmeta2grd() vect2neigh() vInfo() vColumns() vDataCount()

Advanced helpers (consider exporting too, in that case: consider `grass_` function names for wrappers/aliases)

get.GIS_LOCK() set.GIS_LOCK(pid) unset.GIS_LOCK() unlink_.gislock() remove_GISRC()

@rsbivand obviously you're best placed to assess the sensibility of this first attempt, and improve upon it.

rsbivand commented 3 months ago

Please take the lead. Personally, I do not grasp why function names matter, as they are only tokens, and any user should be able to learn the tokens needed for their workflows. However, since you are closer to what users expect, that's fine.

When may someone replace me as maintainer? I would really have appreciated help with #88 which remains open - could anyone with Ubuntu 22 LTS check whether the 8.3.2 binary isn't broken?

ecodiv commented 3 months ago

I would really have appreciated help with #88 which remains open - could anyone with Ubuntu 22 LTS check whether the 8.3.2 binary isn't broken?

It doesn't seem so, I have no problem, and also florisvdh reports to have no issues.

rsbivand / rgrass