API PDB: resource-get-by-name return NULL instead of error

Without this, there is no easy way to quietly check for existence of a resource by name.
Needed when plugin authors can name defaults for resource args by name.

Add tests to script-fu/test/tests

app/pdb/brush-cmds.c

@@ -98,9 +98,8 @@ brush_get_by_name_invoker (GimpProcedure         *procedure,
     {
       brush = GIMP_BRUSH (gimp_pdb_get_resource (gimp, GIMP_TYPE_BRUSH, name,
                                                  GIMP_PDB_DATA_ACCESS_READ, error));
-
+      /* Ignore "not found" error, just return NULL. */
-      if (! brush)
+      g_clear_error (error);
-        success = FALSE;
     }
 
   return_vals = gimp_procedure_get_return_values (procedure, success,
@@ -806,7 +805,7 @@ register_brush_procs (GimpPDB *pdb)
                                "gimp-brush-get-by-name");
   gimp_procedure_set_static_help (procedure,
                                   "Returns the brush with the given name.",
-                                  "Search and return an existing brush with the name in argument, or nothing if no brush has this name.",
+                                  "Return an existing brush having the given name. Returns %NULL when no brush exists of that name.",
                                   NULL);
   gimp_procedure_set_static_attribution (procedure,
                                          "Michael Natterer <mitch@gimp.org>",
@@ -823,7 +822,7 @@ register_brush_procs (GimpPDB *pdb)
                                    gimp_param_spec_brush ("brush",
                                                           "brush",
                                                           "The brush",
-                                                          FALSE,
+                                                          TRUE,
                                                           GIMP_PARAM_READWRITE));
   gimp_pdb_register_procedure (pdb, procedure);
   g_object_unref (procedure);

app/pdb/font-cmds.c

@@ -86,9 +86,8 @@ font_get_by_name_invoker (GimpProcedure         *procedure,
   if (success)
     {
       font = GIMP_FONT (gimp_pdb_get_resource (gimp, GIMP_TYPE_FONT, name, GIMP_PDB_DATA_ACCESS_READ, error));
-
+      /* Ignore "not found" error, just return NULL. */
-      if (! font)
+      g_clear_error (error);
-        success = FALSE;
     }
 
   return_vals = gimp_procedure_get_return_values (procedure, success,
@@ -195,7 +194,8 @@ register_font_procs (GimpPDB *pdb)
   gimp_procedure_set_static_help (procedure,
                                   "Returns a font with the given name.",
                                   "If several fonts are named identically, the one which is returned by this function should be considered random. This can be used when you know you won't have multiple fonts of this name or that you don't want to choose (non-interactive scripts, etc.).\n"
-                                  "If you need more control, you should use 'gimp-fonts-get-by-name' instead.",
+                                  "If you need more control, you should use 'gimp-fonts-get-by-name' instead.\n"
+                                  "Returns %NULL when no font exists of that name.",
                                   NULL);
   gimp_procedure_set_static_attribution (procedure,
                                          "Michael Natterer <mitch@gimp.org>",
@@ -212,7 +212,7 @@ register_font_procs (GimpPDB *pdb)
                                    gimp_param_spec_font ("font",
                                                          "font",
                                                          "The font",
-                                                         FALSE,
+                                                         TRUE,
                                                          GIMP_PARAM_READWRITE));
   gimp_pdb_register_procedure (pdb, procedure);
   g_object_unref (procedure);

app/pdb/gradient-cmds.c

@@ -96,8 +96,8 @@ gradient_get_by_name_invoker (GimpProcedure         *procedure,
       gradient = GIMP_GRADIENT (gimp_pdb_get_resource (gimp, GIMP_TYPE_GRADIENT, name,
                                                        GIMP_PDB_DATA_ACCESS_READ, error));
 
-      if (! gradient)
+      /* Ignore "not found" error, just return NULL. */
-        success = FALSE;
+      g_clear_error (error);
     }
 
   return_vals = gimp_procedure_get_return_values (procedure, success,
@@ -1293,7 +1293,7 @@ register_gradient_procs (GimpPDB *pdb)
                                "gimp-gradient-get-by-name");
   gimp_procedure_set_static_help (procedure,
                                   "Returns the gradient with the given name.",
-                                  "Returns the gradient with the given name.",
+                                  "Returns an existing gradient having the given name. Returns %NULL when no gradient exists of that name.",
                                   NULL);
   gimp_procedure_set_static_attribution (procedure,
                                          "Michael Natterer <mitch@gimp.org>",
@@ -1310,7 +1310,7 @@ register_gradient_procs (GimpPDB *pdb)
                                    gimp_param_spec_gradient ("gradient",
                                                              "gradient",
                                                              "The gradient",
-                                                             FALSE,
+                                                             TRUE,
                                                              GIMP_PARAM_READWRITE));
   gimp_pdb_register_procedure (pdb, procedure);
   g_object_unref (procedure);

app/pdb/palette-cmds.c

@@ -94,8 +94,8 @@ palette_get_by_name_invoker (GimpProcedure         *procedure,
       palette = GIMP_PALETTE (gimp_pdb_get_resource (gimp, GIMP_TYPE_PALETTE, name,
                                                      GIMP_PDB_DATA_ACCESS_READ, error));
 
-      if (! palette)
+      /* Ignore "not found" error, just return NULL. */
-        success = FALSE;
+      g_clear_error (error);
     }
 
   return_vals = gimp_procedure_get_return_values (procedure, success,
@@ -493,7 +493,7 @@ register_palette_procs (GimpPDB *pdb)
                                "gimp-palette-get-by-name");
   gimp_procedure_set_static_help (procedure,
                                   "Returns the palette with the given name.",
-                                  "Returns the palette with the given name.",
+                                  "Returns an existing palette having the given name. Returns %NULL when no palette exists of that name.",
                                   NULL);
   gimp_procedure_set_static_attribution (procedure,
                                          "Michael Natterer <mitch@gimp.org>",
@@ -510,7 +510,7 @@ register_palette_procs (GimpPDB *pdb)
                                    gimp_param_spec_palette ("palette",
                                                             "palette",
                                                             "The palette",
-                                                            FALSE,
+                                                            TRUE,
                                                             GIMP_PARAM_READWRITE));
   gimp_pdb_register_procedure (pdb, procedure);
   g_object_unref (procedure);

app/pdb/pattern-cmds.c

@@ -63,8 +63,8 @@ pattern_get_by_name_invoker (GimpProcedure         *procedure,
     {
       pattern = GIMP_PATTERN (gimp_pdb_get_resource (gimp, GIMP_TYPE_PATTERN, name, GIMP_PDB_DATA_ACCESS_READ, error));
 
-      if (! pattern)
+      /* Ignore "not found" error, just return NULL. */
-        success = FALSE;
+      g_clear_error (error);
     }
 
   return_vals = gimp_procedure_get_return_values (procedure, success,
@@ -181,7 +181,7 @@ register_pattern_procs (GimpPDB *pdb)
                                "gimp-pattern-get-by-name");
   gimp_procedure_set_static_help (procedure,
                                   "Returns the pattern with the given name.",
-                                  "Returns the pattern with the given name.",
+                                  "Returns an existing pattern having the given name. Returns %NULL when no pattern exists of that name.",
                                   NULL);
   gimp_procedure_set_static_attribution (procedure,
                                          "Michael Natterer <mitch@gimp.org>",
@@ -198,7 +198,7 @@ register_pattern_procs (GimpPDB *pdb)
                                    gimp_param_spec_pattern ("pattern",
                                                             "pattern",
                                                             "The pattern",
-                                                            FALSE,
+                                                            TRUE,
                                                             GIMP_PARAM_READWRITE));
   gimp_pdb_register_procedure (pdb, procedure);
   g_object_unref (procedure);

app/pdb/resource-cmds.c

@@ -68,9 +68,11 @@ resource_get_by_name_invoker (GimpProcedure         *procedure,
     {
       resource = gimp_pdb_get_resource (gimp, g_type_from_name (type_name), resource_name,
                                         GIMP_PDB_DATA_ACCESS_READ, error);
-
+      /* gimp_pdb_get_resource can return errors about writeable or renameable when not ACCESS_READ,
-      if (! resource)
+       * but only "not found" error for ACCESS_READ.
-        success = FALSE;
+       * Ignore "not found" error, just return NULL.
+       */
+       g_clear_error (error);
     }
 
   return_vals = gimp_procedure_get_return_values (procedure, success,
@@ -515,7 +517,8 @@ register_resource_procs (GimpPDB *pdb)
                                "gimp-resource-get-by-name");
   gimp_procedure_set_static_help (procedure,
                                   "Returns a resource with the given name.",
-                                  "Returns a resource with the given name.",
+                                  "Returns an existing resource having the given name. Returns %NULL when no resource exists of that name.\n"
+                                  "There may be many fonts having the same name. See 'gimp-font-get-by-name'.",
                                   NULL);
   gimp_procedure_set_static_attribution (procedure,
                                          "Jehan",
@@ -524,7 +527,7 @@ register_resource_procs (GimpPDB *pdb)
   gimp_procedure_add_argument (procedure,
                                gimp_param_spec_string ("type-name",
                                                        "type name",
-                                                       "The name of the resource type",
+                                                       "The name of the resource type e.g. GimpFont",
                                                        FALSE, FALSE, TRUE,
                                                        NULL,
                                                        GIMP_PARAM_READWRITE));
@@ -539,7 +542,7 @@ register_resource_procs (GimpPDB *pdb)
                                    gimp_param_spec_resource ("resource",
                                                              "resource",
                                                              "The resource",
-                                                             FALSE,
+                                                             TRUE,
                                                              GIMP_PARAM_READWRITE));
   gimp_pdb_register_procedure (pdb, procedure);
   g_object_unref (procedure);

libgimp/gimpbrush_pdb.c

@@ -78,10 +78,10 @@ gimp_brush_new (const gchar *name)
  *
  * Returns the brush with the given name.
  *
- * Search and return an existing brush with the name in argument, or
+ * Return an existing brush having the given name. Returns %NULL when
- * nothing if no brush has this name.
+ * no brush exists of that name.
  *
- * Returns: (transfer none): The brush.
+ * Returns: (nullable) (transfer none): The brush.
  *
  * Since: 3.0
  **/

libgimp/gimpfont_pdb.c

@@ -83,8 +83,9 @@ _gimp_font_get_lookup_name (GimpFont *font)
  * want to choose (non-interactive scripts, etc.).
  * If you need more control, you should use gimp_fonts_get_by_name()
  * instead.
+ * Returns %NULL when no font exists of that name.
  *
- * Returns: (transfer none): The font.
+ * Returns: (nullable) (transfer none): The font.
  *
  * Since: 3.0
  **/

libgimp/gimpgradient_pdb.c

@@ -78,9 +78,10 @@ gimp_gradient_new (const gchar *name)
  *
  * Returns the gradient with the given name.
  *
- * Returns the gradient with the given name.
+ * Returns an existing gradient having the given name. Returns %NULL
+ * when no gradient exists of that name.
  *
- * Returns: (transfer none): The gradient.
+ * Returns: (nullable) (transfer none): The gradient.
  *
  * Since: 3.0
  **/

libgimp/gimppalette_pdb.c

@@ -81,9 +81,10 @@ gimp_palette_new (const gchar *name)
  *
  * Returns the palette with the given name.
  *
- * Returns the palette with the given name.
+ * Returns an existing palette having the given name. Returns %NULL
+ * when no palette exists of that name.
  *
- * Returns: (transfer none): The palette.
+ * Returns: (nullable) (transfer none): The palette.
  *
  * Since: 3.0
  **/

libgimp/gimppattern_pdb.c

@@ -42,9 +42,10 @@
  *
  * Returns the pattern with the given name.
  *
- * Returns the pattern with the given name.
+ * Returns an existing pattern having the given name. Returns %NULL
+ * when no pattern exists of that name.
  *
- * Returns: (transfer none): The pattern.
+ * Returns: (nullable) (transfer none): The pattern.
  *
  * Since: 3.0
  **/

libgimp/gimpresource_pdb.c

@@ -38,14 +38,17 @@
 
 /**
  * _gimp_resource_get_by_name:
- * @type_name: The name of the resource type.
+ * @type_name: The name of the resource type e.g. GimpFont.
  * @resource_name: The name of the resource.
  *
  * Returns a resource with the given name.
  *
- * Returns a resource with the given name.
+ * Returns an existing resource having the given name. Returns %NULL
+ * when no resource exists of that name.
+ * There may be many fonts having the same name. See
+ * gimp_font_get_by_name().
  *
- * Returns: (transfer none): The resource.
+ * Returns: (nullable) (transfer none): The resource.
  *
  * Since: 3.0
  **/

pdb/groups/brush.pdb

@@ -53,8 +53,8 @@ CODE
 sub brush_get_by_name {
     $blurb = "Returns the brush with the given name.";
     $help = <<'HELP';
-Search and return an existing brush with the name in argument, or nothing if no
+Return an existing brush having the given name.
-brush has this name.
+Returns %NULL when no brush exists of that name.
 HELP
 
     &mitch_pdb_misc('2023', '3.0');
@@ -65,7 +65,10 @@ HELP
     );
 
     @outargs = (
-      ${brush_arg_spec}
+      { name => 'brush',
+        type => 'brush',
+        desc => 'The brush',
+        none_ok => 1 }
     );
 
     %invoke = (
@@ -73,9 +76,8 @@ HELP
 {
   brush = GIMP_BRUSH (gimp_pdb_get_resource (gimp, GIMP_TYPE_BRUSH, name,
                                              GIMP_PDB_DATA_ACCESS_READ, error));
-
+  /* Ignore "not found" error, just return NULL. */
-  if (! brush)
+  g_clear_error (error);
-    success = FALSE;
 }
 CODE
     );

pdb/groups/font.pdb

@@ -73,6 +73,8 @@ have multiple fonts of this name or that you don't want to choose
 (non-interactive scripts, etc.).
 
 If you need more control, you should use gimp_fonts_get_by_name() instead.
+
+Returns %NULL when no font exists of that name.
 HELP
 
     &mitch_pdb_misc('2023', '3.0');
@@ -83,17 +85,18 @@ HELP
     );
 
     @outargs = (
-      { name => 'font', type => 'font', non_empty => 1,
+      { name => 'font',
-        desc => 'The font' }
+        type => 'font',
+        desc => 'The font',
+        none_ok => 1 }
     );
 
     %invoke = (
         code => <<'CODE'
 {
   font = GIMP_FONT (gimp_pdb_get_resource (gimp, GIMP_TYPE_FONT, name, GIMP_PDB_DATA_ACCESS_READ, error));
-
+  /* Ignore "not found" error, just return NULL. */
-  if (! font)
+  g_clear_error (error);
-    success = FALSE;
 }
 CODE
     );

pdb/groups/gradient.pdb

@@ -70,8 +70,10 @@ CODE
 
 sub gradient_get_by_name {
     $blurb = "Returns the gradient with the given name.";
-    $help  = "Returns the gradient with the given name.";
+    $help  = <<HELP;
-
+Returns an existing gradient having the given name.
+Returns %NULL when no gradient exists of that name.
+HELP
     &mitch_pdb_misc('2023', '3.0');
 
     @inargs = (
@@ -80,7 +82,10 @@ sub gradient_get_by_name {
     );
 
     @outargs = (
-      ${gradient_arg_spec}
+      { name => 'gradient',
+        type => 'gradient',
+        desc => 'The gradient',
+        none_ok => 1 }
     );
 
     %invoke = (
@@ -89,8 +94,8 @@ sub gradient_get_by_name {
   gradient = GIMP_GRADIENT (gimp_pdb_get_resource (gimp, GIMP_TYPE_GRADIENT, name,
                                                    GIMP_PDB_DATA_ACCESS_READ, error));
 
-  if (! gradient)
+  /* Ignore "not found" error, just return NULL. */
-    success = FALSE;
+  g_clear_error (error);
 }
 CODE
     );

pdb/groups/palette.pdb

@@ -56,7 +56,10 @@ CODE
 
 sub palette_get_by_name {
     $blurb = "Returns the palette with the given name.";
-    $help  = "Returns the palette with the given name.";
+    $help  = <<HELP;
+Returns an existing palette having the given name.
+Returns %NULL when no palette exists of that name.
+HELP
 
     &mitch_pdb_misc('2023', '3.0');
 
@@ -66,8 +69,10 @@ sub palette_get_by_name {
     );
 
     @outargs = (
-      { name => 'palette', type => 'palette', non_empty => 1,
+      { name => 'palette',
-        desc => 'The palette' }
+        type => 'palette',
+        desc => 'The palette',
+        none_ok => 1 }
     );
 
     %invoke = (
@@ -76,8 +81,8 @@ sub palette_get_by_name {
   palette = GIMP_PALETTE (gimp_pdb_get_resource (gimp, GIMP_TYPE_PALETTE, name,
                                                  GIMP_PDB_DATA_ACCESS_READ, error));
 
-  if (! palette)
+  /* Ignore "not found" error, just return NULL. */
-    success = FALSE;
+  g_clear_error (error);
 }
 CODE
     );

pdb/groups/pattern.pdb

@@ -26,7 +26,10 @@ $pattern_arg_spec = { name => 'pattern', type => 'pattern', non_empty => 1,
 
 sub pattern_get_by_name {
     $blurb = "Returns the pattern with the given name.";
-    $help  = "Returns the pattern with the given name.";
+    $help  = <<HELP;
+Returns an existing pattern having the given name.
+Returns %NULL when no pattern exists of that name.
+HELP
 
     &mitch_pdb_misc('2023', '3.0');
 
@@ -36,8 +39,10 @@ sub pattern_get_by_name {
     );
 
     @outargs = (
-      { name => 'pattern', type => 'pattern', non_empty => 1,
+      { name => 'pattern',
-        desc => 'The pattern' }
+        type => 'pattern',
+        desc => 'The pattern',
+        none_ok => 1 }
     );
 
     %invoke = (
@@ -45,8 +50,8 @@ sub pattern_get_by_name {
 {
   pattern = GIMP_PATTERN (gimp_pdb_get_resource (gimp, GIMP_TYPE_PATTERN, name, GIMP_PDB_DATA_ACCESS_READ, error));
 
-  if (! pattern)
+  /* Ignore "not found" error, just return NULL. */
-    success = FALSE;
+  g_clear_error (error);
 }
 CODE
     );

pdb/groups/resource.pdb

@@ -18,7 +18,13 @@
 
 sub resource_get_by_name {
     $blurb = "Returns a resource with the given name.";
-    $help  = "Returns a resource with the given name.";
+    $help  = <<HELP;
+Returns an existing resource having the given name.
+Returns %NULL when no resource exists of that name.
+
+There may be many fonts having the same name.
+See gimp_font_get_by_name().
+HELP
 
     &jehan_pdb_misc('2023', '3.0');
 
@@ -26,7 +32,7 @@ sub resource_get_by_name {
 
     @inargs = (
         { name => 'type_name', type => 'string', non_empty => 1,
-          desc => 'The name of the resource type' },
+          desc => 'The name of the resource type e.g. GimpFont' },
 	{ name => 'resource_name', type => 'string', non_empty => 1,
 	  desc => 'The name of the resource' }
     );
@@ -34,7 +40,8 @@ sub resource_get_by_name {
     @outargs = (
       { name => 'resource',
         type => 'resource',
-        desc => "The resource" }
+        desc => "The resource",
+        none_ok => 1}
     );
 
     %invoke = (
@@ -42,9 +49,11 @@ sub resource_get_by_name {
 {
   resource = gimp_pdb_get_resource (gimp, g_type_from_name (type_name), resource_name,
                                     GIMP_PDB_DATA_ACCESS_READ, error);
-
+  /* gimp_pdb_get_resource can return errors about writeable or renameable when not ACCESS_READ,
-  if (! resource)
+   * but only "not found" error for ACCESS_READ.
-    success = FALSE;
+   * Ignore "not found" error, just return NULL.
+   */
+   g_clear_error (error);
 }
 CODE
     );

plug-ins/script-fu/test/tests/PDB/resource/resource-ops.scm

@@ -1,8 +1,93 @@
 ; test operations on resource pool
 
-; TODO
+; tests of specific named gimp-brush-delete etc. are elsewhere
+; This tests the generic methods named like gimp-resource-<op>
+
+
+(script-fu-use-v3)
+
+; setup
+(define systemFont (gimp-resource-get-by-name "GimpFont" "Sans-serif"))
+(define systemBrush (gimp-resource-get-by-name "GimpBrush" "2. Star"))
+
+
+
+(test! "resource get by name")
+
+; get-by-name, which is generic and takes a "resource type name"
+
+; get-by-name on non-existent name returns C NULL i.e. invalid ID
+(assert `(= (gimp-resource-get-by-name "GimpBrush" "Agate")
+            -1))
+
+; each of the specific get-by-name returns C NULL i.e. invalid ID
+; on invalid name
+(assert `(= (gimp-brush-get-by-name    "Agate") -1))
+(assert `(= (gimp-font-get-by-name     "Agate") -1))
+(assert `(= (gimp-gradient-get-by-name "Agate") -1))
+(assert `(= (gimp-palette-get-by-name  "Agate") -1))
+(assert `(= (gimp-pattern-get-by-name  "Agate") -1))
+
+
+
+; get-by-name on invalid type name returns error
+; FIXME throws critical but does not return an error, returns NULL i.e. ID 0
+; Low priority to fix, it only happens during development of a plugin.
+; (assert-error `(gimp-resource-get-by-name "FooType" "Agate")
+;             "Error")
+
+; get-by-name on existent name returns valid positive ID
+(assert `(> (gimp-resource-get-by-name "GimpFont" "Sans-serif")
+            0))
+
+(assert `(> (gimp-brush-get-by-name    "2. Star")      0))
+(assert `(> (gimp-font-get-by-name     "Sans-serif")   0))
+(assert `(> (gimp-gradient-get-by-name "Default")      0))
+(assert `(> (gimp-palette-get-by-name  "Default")      0))
+(assert `(> (gimp-pattern-get-by-name  "Maple Leaves") 0))
+
+
+
+(test! "ops on system resources")
+
+; operations outlawed on a system resource
+; i.e. one not created by script or installed by user
+
+; Can't delete system font
+(assert-error `(gimp-resource-delete ,systemFont)
+              "Procedure execution of gimp-resource-delete failed")
+
+; Can't rename system font
+(assert-error `(gimp-resource-rename ,systemFont "newName")
+              "Procedure execution of gimp-resource-rename failed")
+              ; on invalid input arguments: Resource 'Sans-serif' is not renamable
+
+; Can't duplicate a system font
+; ??? Why are fonts different from brush re duplication?
+(assert-error `(gimp-resource-duplicate ,systemFont)
+              "Procedure execution of gimp-resource-duplicate failed")
+
+
+
+(test! "resource duplicate, rename, delete")
+
+; Can duplicate a system brush
+(define duplicatedSystemBrush (gimp-resource-duplicate systemBrush))
+
+; test duplicate is effective, id is a brush
+(assert `(gimp-resource-id-is-brush ,duplicatedSystemBrush))
+
+; name of duplicated font is generated by appending " copy" and later "#x"
+; This fails on retry if cleanup delete fails
+(assert `(string=? (gimp-resource-get-name ,duplicatedSystemBrush)
+                   "2. Star copy"))
+
+; can rename a duplicated brush
+(assert `(gimp-resource-rename ,duplicatedSystemBrush "NewName"))
+; rename is effective
+(assert `(string=? (gimp-resource-get-name ,duplicatedSystemBrush)
+                   "NewName"))
+
+; can delete a duplicated font
+(assert `(gimp-resource-delete ,duplicatedSystemBrush))
 
-; gimp-resource-rename
-; gimp-resource-duplicate
-; gimp-resource-delete
-; gimp-resource-rename