r.mask.status: Always output name of the mask

include/grass/defs/raster.h

@@ -392,6 +392,7 @@ int Rast_option_to_interp_type(const struct Option *);
 
 /* mask_info.c */
 char *Rast_mask_info(void);
+char *Rast_mask_name(void);
 bool Rast_mask_status(char *, char *, bool *, char *, char *);
 int Rast__mask_info(char *, char *);
 bool Rast_mask_is_present(void);

lib/raster/mask_info.c

@@ -49,6 +49,27 @@ char *Rast_mask_info(void)
     return G_store(text);
 }
 
+/**
+ * @brief Retrieves the name of the raster mask to use.
+ *
+ * The returned raster map name is fully qualified, i.e., in the form
+ % "name@mapset".
+ *
+ * The uses the mask name "MASK@<mapset>", where <mapset> is the current
+ * mapset.
+ *
+ * The memory for the returned mask name is dynamically allocated using
+ * G_store(). It is the caller's responsibility to free the memory with
+ * G_free() when it is no longer needed.
+ *
+ * @returns A dynamically allocated string containing the mask name.
+ */
+char *Rast_mask_name(void)
+{
+    // Mask name is always "MASK@<current mapset>".
+    return G_fully_qualified_name("MASK", G_mapset());
+}
+
 /**
  * @brief Get raster mask status information
  *

raster/r.mask.status/main.c

@@ -89,7 +89,7 @@ int report_status(struct Parameters *params)
     }
 
     // Mask raster
-    char *full_mask = G_fully_qualified_name(name, mapset);
+    char *full_mask = Rast_mask_name();
     // Underlying raster if applicable
     char *full_underlying = NULL;
     if (is_mask_reclass)
@@ -99,10 +99,7 @@ int report_status(struct Parameters *params)
         JSON_Value *root_value = json_value_init_object();
         JSON_Object *root_object = json_object(root_value);
         json_object_set_boolean(root_object, "present", present);
-        if (present)
-            json_object_set_string(root_object, "full_name", full_mask);
-        else
-            json_object_set_null(root_object, "full_name");
+        json_object_set_string(root_object, "name", full_mask);
         if (is_mask_reclass)
             json_object_set_string(root_object, "is_reclass_of",
                                    full_underlying);
@@ -121,9 +118,7 @@ int report_status(struct Parameters *params)
             printf("1");
         else
             printf("0");
-        printf("\nfull_name=");
-        if (present)
-            printf("%s", full_mask);
+        printf("\nname=%s", full_mask);
         printf("\nis_reclass_of=");
         if (is_mask_reclass)
             printf("%s", full_underlying);
@@ -135,34 +130,31 @@ int report_status(struct Parameters *params)
             printf("true");
         else
             printf("false");
-        printf("\nfull_name: ");
-        if (present)
-            printf("|-\n  %s", full_mask);
-        else
-            printf("null");
-        // Null values in YAML can be an empty (no) value (rather than null),
-        // so we could use that, but using the explicit null as a reasonable
-        // starting point.
+        printf("\nname: ");
+        printf("|-\n  %s", full_mask);
         printf("\nis_reclass_of: ");
         // Using block scalar with |- to avoid need for escaping.
         // Alternatively, we could check mapset naming limits against YAML
         // escaping needs for different types of strings and do the necessary
         // escaping here.
+        // Null values in YAML can be an empty (no) value (rather than null),
+        // so we could use that, but using the explicit null as a reasonable
+        // starting point.
         if (is_mask_reclass)
             printf("|-\n  %s", full_underlying);
         else
             printf("null");
         printf("\n");
     }
     else {
-        if (present)
-            printf(_("Mask is active"));
-        else
-            printf(_("Mask is not present"));
         if (present) {
-            printf("\n");
+            printf(_("Mask is active"));
             printf(_("Mask name: %s"), full_mask);
         }
+        else {
+            printf(_("Mask is not present"));
+            printf(_("If activated, mask name will be: %s"), full_mask);
+        }
         if (is_mask_reclass) {
             printf("\n");
             printf(_("Mask is a raster reclassified from: %s"),

raster/r.mask.status/r.mask.status.html

@@ -1,11 +1,21 @@
 <h2>DESCRIPTION</h2>
 
 The <em>r.mask.status</em> reports information about the 2D raster mask and its
-status. If the mask is present, the tool reports a full name of the raster (name
-including the mapset) which represents the mask. It can also report full name of
-the underlying raster if the mask is reclassified from another raster.
-
-<p></p>
+status. The tool reports whether the mask is present or not. For both active
+and inactive mask, the tool reports a full name of the raster (name including
+the mapset) which represents or would represent the mask.
+It can also report full name of the underlying raster if the mask is
+reclassified from another raster.
+
+The tool can be used to check if the mask is currently set
+(<code>present</code> boolean in JSON), what is raster name used to represent
+the mask (<code>name</code> string in JSON), and whether the raster is
+reclassifed from another (<code>name</code> string or null in JSON).
+YAML and shell script style outputs are following the JSON output if possible.
+The plain text format outputs multi-line human-readable information in natural
+language.
+
+<p>
 With the <b>-t</b> flag, no output is printed, instead a return code is used to
 indicate presence or absence. The convention is the same same the POSIX
 <em>test</em> utility, so <em>r.mask.status</em> returns 0 when the mask is

raster/r.mask.status/tests/r_mask_status_test.py

@@ -15,10 +15,11 @@ def test_json_no_mask(session_no_data):
     session = session_no_data
     data = gs.parse_command("r.mask.status", format="json", env=session.env)
     assert "present" in data
-    assert "full_name" in data
+    assert "name" in data
+    assert data["name"], "Mask name needs to be always set"
+    assert data["name"] == "MASK@PERMANENT", "Default mask name and current mapset"
     assert "is_reclass_of" in data
     assert data["present"] is False
-    assert not data["full_name"]
     assert not data["is_reclass_of"]
 
 
@@ -28,13 +29,13 @@ def test_json_with_r_mask(session_with_data):
     gs.run_command("r.mask", raster="a", env=session.env)
     data = gs.parse_command("r.mask.status", format="json", env=session.env)
     assert data["present"] is True
-    assert data["full_name"] == "MASK@PERMANENT"
+    assert data["name"] == "MASK@PERMANENT"
     assert data["is_reclass_of"] == "a@PERMANENT"
     # Now remove the mask.
     gs.run_command("r.mask", flags="r", env=session.env)
     data = gs.parse_command("r.mask.status", format="json", env=session.env)
     assert data["present"] is False
-    assert not data["full_name"]
+    assert data["name"] == "MASK@PERMANENT"
     assert not data["is_reclass_of"]
 
 
@@ -44,13 +45,13 @@ def test_json_with_g_copy(session_with_data):
     gs.run_command("g.copy", raster="a,MASK", env=session.env)
     data = gs.parse_command("r.mask.status", format="json", env=session.env)
     assert data["present"] is True
-    assert data["full_name"] == "MASK@PERMANENT"
+    assert data["name"] == "MASK@PERMANENT"
     assert not data["is_reclass_of"]
     # Now remove the mask.
     gs.run_command("g.remove", type="raster", name="MASK", flags="f", env=session.env)
     data = gs.parse_command("r.mask.status", format="json", env=session.env)
     assert data["present"] is False
-    assert not data["full_name"]
+    assert data["name"] == "MASK@PERMANENT"
     assert not data["is_reclass_of"]
 
 
@@ -60,13 +61,13 @@ def test_shell(session_with_data):
     gs.run_command("r.mask", raster="a", env=session.env)
     data = gs.parse_command("r.mask.status", format="shell", env=session.env)
     assert int(data["present"])
-    assert data["full_name"] == "MASK@PERMANENT"
+    assert data["name"] == "MASK@PERMANENT"
     assert data["is_reclass_of"] == "a@PERMANENT"
     # Now remove the mask.
     gs.run_command("r.mask", flags="r", env=session.env)
     data = gs.parse_command("r.mask.status", format="shell", env=session.env)
     assert not int(data["present"])
-    assert not data["full_name"]
+    assert data["name"] == "MASK@PERMANENT"
     assert not data["is_reclass_of"]
 
 
@@ -78,14 +79,14 @@ def test_yaml(session_with_data):
     text = gs.read_command("r.mask.status", format="yaml", env=session.env)
     data = yaml.safe_load(text)
     assert data["present"] is True
-    assert data["full_name"] == "MASK@PERMANENT"
+    assert data["name"] == "MASK@PERMANENT"
     assert data["is_reclass_of"] == "a@PERMANENT"
     # Now remove the mask.
     gs.run_command("r.mask", flags="r", env=session.env)
     text = gs.read_command("r.mask.status", format="yaml", env=session.env)
     data = yaml.safe_load(text)
     assert data["present"] is False
-    assert not data["full_name"]
+    assert data["name"] == "MASK@PERMANENT"
     assert not data["is_reclass_of"]
 
 
@@ -101,6 +102,8 @@ def test_plain(session_with_data):
     gs.run_command("r.mask", flags="r", env=session.env)
     text = gs.read_command("r.mask.status", format="plain", env=session.env)
     assert text
+    assert "MASK@PERMANENT" in text
+    assert "a@PERMANENT" not in text
 
 
 def test_without_parameters(session_no_data):