libgis: add G_mapset_path()

        remove subroutines used only by gis library from gis.h
        add gis_local_proto.h
        improve dox documentation for location.c and mapset.c


git-svn-id: https://svn.osgeo.org/grass/grass/trunk@53595 15284696-431f-4ddb-bdfa-cd5b030d7da7

include/defs/gis.h

@@ -372,7 +372,6 @@ int G_llres_scan(const char *, double *);
 /* location.c */
 const char *G_location(void);
 char *G_location_path(void);
-char *G__location_path(void);
 
 /* ls.c */
 void G_set_ls_filter(int (*)(const char *, void *), void *);
@@ -411,7 +410,7 @@ char *G_toucase(char *);
 
 /* mapset.c */
 const char *G_mapset(void);
-const char *G__mapset(void);
+char *G_mapset_path(void);
 
 /* mapset_msc.c */
 int G__make_mapset_element(const char *);

lib/gis/file_name.c

@@ -16,6 +16,8 @@
 #include <string.h>
 #include <grass/gis.h>
 
+#include "gis_local_proto.h"
+
 /*!
   \brief Builds full path names to GIS data files
 

lib/gis/gis_local_proto.h

@@ -0,0 +1,14 @@
+#ifndef __GIS_LOCAL_PROTO_H__
+#define __GIS_LOCAL_PROTO_H__
+
+/* subroutines used only by GIS Library */
+/* TODO: move other G__*() subroutines here */
+
+/* location.c */
+char *G__location_path(void);
+
+/* mapset.c */
+const char *G__mapset(void);
+char *G__mapset_path(void);
+
+#endif

lib/gis/location.c

@@ -1,14 +1,12 @@
 /*!
-  \file gis/location.c
+  \file lib/gis/location.c
   
   \brief GIS library - environment routines (location)
   
-  (C) 2001-2008 by the GRASS Development Team
+  (C) 2001-2008, 2012 by the GRASS Development Team
   
-  This program is free software under the 
-  GNU General Public License (>=v2). 
-  Read the file COPYING that comes with GRASS
-  for details.
+  This program is free software under the GNU General Public License
+  (>=v2).  Read the file COPYING that comes with GRASS for details.
   
   \author Original author CERL
 */
@@ -20,34 +18,39 @@
 #include <grass/gis.h>
 #include <grass/glocale.h>
 
+#include "gis_local_proto.h"
 
 /*!
- * \brief Get current location name
- *
- * Returns the name of the current database location. This routine
- * should be used by modules that need to display the current location
- * to the user. See Locations for an explanation of locations.
- *
- *  \return char* tolocation name
- */
-
+  \brief Get current location name
+  
+  Returns the name of the current database location. This routine
+  should be used by modules that need to display the current location
+  to the user. See Locations for an explanation of locations.
+  
+  \return location name
+*/
 const char *G_location(void)
 {
     return G_getenv("LOCATION_NAME");
 }
 
 /*!
- * \brief Get current location directory
- *
- * Returns the full UNIX path name of the current database
- * location. For example, if the user is working in location
- * <i>spearfish</i> in the <i>/home/user/grassdata</i> database
- * directory, this routine will return a string which looks like
- * <i>/home/user/grassdata/spearfish</i>.
- *
- *  \return char * 
- */
+  \brief Get current location UNIX-like path
+ 
+  Allocated buffer should be freed by G_free(). See
+  G__location_path().
 
+  Returns the full UNIX path name of the current database
+  location. For example, if the user is working in location
+  <i>spearfish</i> in the <i>/home/user/grassdata</i> database
+  directory, this routine will return a string which looks like
+  <i>/home/user/grassdata/spearfish</i>.
+  
+  This function also checks if location path is readable by the
+  current user. It calls G_fatal_error() on failure.
+
+  \return buffer with location path
+ */
 char *G_location_path(void)
 {
     char *location;
@@ -55,7 +58,7 @@ char *G_location_path(void)
     location = G__location_path();
     if (access(location, F_OK) != 0) {
 	perror("access");
-	G_fatal_error(_("LOCATION << %s >> not available"), location);
+	G_fatal_error(_("LOCATION <%s> not available"), location);
     }
 
     return location;
@@ -63,9 +66,14 @@ char *G_location_path(void)
 
 
 /*!
- * \brief Get current location path
- *
- *  \return char* to location path
+  \brief Get current location UNIX-like path (internal use only)
+  
+  Allocated buffer should be freed by G_free(). See also
+  G_location_path().
+  
+  \todo Support also Windows-like path (?)
+  
+  \return buffer with location path
  */
 char *G__location_path(void)
 {

lib/gis/mapset.c

@@ -1,34 +1,35 @@
 /*!
-  \file gis/mapset.c
+  \file lib/gis/mapset.c
   
   \brief GIS library - environment routines (mapset)
   
-  (C) 2001-2009 by the GRASS Development Team
+  (C) 2001-2009, 2012 by the GRASS Development Team
   
-  This program is free software under the 
-  GNU General Public License (>=v2). 
-  Read the file COPYING that comes with GRASS
-  for details.
+  This program is free software under the GNU General Public License
+  (>=v2).  Read the file COPYING that comes with GRASS for details.
 
   \author Original author CERL
  */
 
 #include <string.h>
 #include <stdlib.h>
+#include <unistd.h>
 #include <grass/gis.h>
 #include <grass/glocale.h>
 
+#include "gis_local_proto.h"
+
 /*!
- * \brief Get current mapset name
- *
- * Returns the name of the current mapset in the current
- * location. This routine is often used when accessing files in the
- * current mapset. See Mapsets for an explanation of mapsets.
- *
- * G_fatal_error() is called on error.
- *
- * \return pointer mapset name
- */
+  \brief Get current mapset name
+  
+  Returns the name of the current mapset in the current location. This
+  routine is often used when accessing files in the current
+  mapset. See Mapsets for an explanation of mapsets.
+  
+  G_fatal_error() is called on error.
+  
+  \return mapset name
+*/
 const char *G_mapset(void)
 {
     const char *m = G__mapset();
@@ -40,12 +41,68 @@ const char *G_mapset(void)
 }
 
 /*!
- * \brief Get current mapset name
- *
- * \return pointer mapset name
- * \return NULL on error
- */
+  \brief Get current mapset name (internal use only)
+  
+  See G_mapset().
+  
+  \return pointer mapset name
+  \return NULL on error
+*/
 const char *G__mapset(void)
 {
     return G__getenv("MAPSET");
 }
+
+/*!
+  \brief Get current mapset UNIX-like path
+ 
+  Allocated buffer should be freed by G_free(). See
+  G__mapset_path().
+
+  Returns the full UNIX path name of the current mapset. For example,
+  if the user is working in mapset <i>user1</i>, location
+  <i>spearfish</i> in the <i>/home/user/grassdata</i> database
+  directory, this routine will return a string which looks like
+  <i>/home/user/grassdata/spearfish/user1</i>.
+  
+  This function also checks if mapset path is readable by the current
+  user. It calls G_fatal_error() on failure.
+
+  \return buffer with location path
+*/
+char *G_mapset_path(void)
+{
+    char *mapset;
+
+    mapset = G__mapset_path();
+    if (access(mapset, F_OK) != 0) {
+	perror("access");
+	G_fatal_error(_("MAPSET <%s> not available"), mapset);
+    }
+
+    return mapset;
+}
+
+/*!
+  \brief Get current mapset UNIX-like path (internal use only)
+  
+  Allocated buffer should be freed by G_free(). See also
+  G_mapset_path().
+  
+  \todo Support also Windows-like path (?)
+  
+  \return buffer with mapset path
+*/
+char *G__mapset_path(void)
+{
+    const char *mapset = G__mapset();
+    const char *location = G_location();
+    const char *base = G_gisdbase();
+    
+    char *mapset_path = G_malloc(strlen(base) + strlen(location) +
+                                 strlen(mapset) + 3);
+
+    sprintf(mapset_path, "%s/%s/%s", base, location, mapset);
+
+    return mapset_path;
+}