[GRASS-dev] grass7: passing fullyqualified names to G_ fns

[Glynn Clements]

Martin Landa wrote:

> there are couple of functions which allow passing fully qualified map
> name even they have mapset argument available.
> 
> E.g.
> 
> G__open() where you can pass name as fully qualified, then 'mapset'
> argument is ignored.

If you pass a fully-qualfied name, it fails if the mapset part of the
name doesn't match the mapset argument. It should probably accept ""
as the mapset to skip this check, as for G_find_*.

Most functions which reference an existing map (or other element)
accept both a name and a mapset.

If the mapset is non-empty, unqualified names use that mapset while
qualified names must have an @mapset part which matches it.

If the mapset is the empty string (""), qualified names use their
@mapset part while unqualified names use the mapset search path (the
default is the current mapset followed by PERMANENT).

Functions which create a new map or other element only work with the
current mapset and don't accept a mapset argument. Unqualified names
refer to the current mapset, while qualified names must have the
current mapset as their @mapset part.

> Maybe this behaviour could be changed in GRASS 7,
> either to require not-fully qualified names or just to omit 'mapset'
> argument and expect that name is fully qualified? First choice seems
> to be more reasonable.

I really want to eliminate mapsets altogether from the higher-level
functions. Modules should be able to pass opt->answer directly to most
GRASS functions without needing to call G_find_* or know anything
about mapsets.

> Currently functions G_find_cell / G_find_cell2 return mapset name or
> NULL. Maybe we could eliminate G_find_*2 function by adding a new
> argument.
> 
> G_find_cell(fname, mapset, name)
> 
> where name is char * to not-fully qualified name (allocated by G_store())
> 
> or just
> 
> G_find_cell(fname, mapset, NULL) (as G_find_cell2)

Ideally, modules shouldn't need to use the G_find_* functions. In most
cases, use of G_find_* has been unnecessary since the libgis functions
were modified to accept fully qualified names, rather than requiring
the caller to "de-qualify" the name beforehand.

It should normally be sufficient to just use e.g.:

	G_open_cell_old(input->answer, "")

rather than e.g.:

	mapset = G_find_cell2(input->answer, "");
	G_open_cell_old(input->answer, mapset);

[error checking elided.]

If all of the unnecessary G_find_* calls are eliminated, most of the
mapset arguments will eventually become "", at which point the
parameter can be eliminated altogether. If you need to force a
specific mapset, you can construct a qualified name with
G_fully_qualified_name().

But first, we should track down and replace any residual uses of
G_find_cell() (which overwrites the name argument with the unqualified
version). If you really need to de-qualify a name (e.g. because you're
using it as a base for generting map names[1]), use an explicit call
to G__name_is_fully_qualified().

-- 
Glynn Clements <glynn at gclements.plus.com>