# HG changeset patch
# User Franz Glasner <fzglas.hg@dom66.de>
# Date 1729638033 -7200
# Node ID 03350d2a2af6a1ff5a0679ed71ddfc6b857e83a2
# Parent  53d05f470f4a60ba69667992c273ba2c1e92513b
farray.sh: Add public functions to check whether a given value refers to a object (array, alist).

Implemented also "farray_isref()", "falist_isref()" and "fobject_isref()".

diff -r 53d05f470f4a -r 03350d2a2af6 share/local-bsdtools/farray.sh
--- a/share/local-bsdtools/farray.sh	Tue Oct 22 11:48:39 2024 +0200
+++ b/share/local-bsdtools/farray.sh	Wed Oct 23 01:00:33 2024 +0200
@@ -443,10 +443,10 @@
 
 
 #:
-#: Implementation of typing
+#: Implementation of variable typing
 #:
 #: Args:
-#:   $1 (str): The (variable) name of an object
+#:   $1 (str): The variable name of an object
 #:
 #: Output (stdout):
 #:   - array: an array
@@ -495,6 +495,30 @@
 
 
 #:
+#: Check whether a given value is an array or alist reference.
+#:
+#: Args:
+#:   $1 (str): The value to check
+#:
+#: Returns:
+#:   int: 0 (truthy) if `$1` is a reference to an object (array or alist),
+#:        1 otherwise
+#:
+fobject_isref() {
+    case "$1" in
+        '')
+            return 1;;
+        "${_farr_array_token_prefix}"*)
+            return 0;;
+        "${_farr_alist_token_prefix}"*)
+            return 0;;
+        *)
+            return 1;;
+    esac
+}
+
+
+#:
 #: Just an official alias for `fobject_type`
 #:
 farray_type() {
@@ -503,10 +527,32 @@
 
 
 #:
+#: Check whether a given value is an array reference.
+#:
+#: Args:
+#:   $1 (str): The value to check
+#:
+#: Returns:
+#:   int: 0 (truthy) if `$1` is a reference to an array,
+#:        1 otherwise
+#:
+farray_isref() {
+    case "$1" in
+        '')
+            return 1;;
+        "${_farr_array_token_prefix}"*)
+            return 0;;
+        *)
+            return 1;;
+    esac
+}
+
+
+#:
 #: Test whether `$1` is an array.
 #:
 #: Args:
-#:   $1 (str): The name of an object
+#:   $1 (str): The variable name of an object
 #:
 #: Returns:
 #:   int: 0 if `$1` is an array, 1 otherwise
@@ -2052,10 +2098,32 @@
 
 
 #:
+#: Check whether a given value is an alist reference.
+#:
+#: Args:
+#:   $1 (str): The value to check
+#:
+#: Returns:
+#:   int: 0 (truthy) if `$1` is a reference to an alist,
+#:        1 otherwise
+#:
+falist_isref() {
+    case "$1" in
+        '')
+            return 1;;
+        "${_farr_alist_token_prefix}"*)
+            return 0;;
+        *)
+            return 1;;
+    esac
+}
+
+
+#:
 #: Test whether `$1` is an alist.
 #:
 #: Args:
-#:   $1 (str): The name of an object
+#:   $1 (str): The variable name of an object
 #:
 #: Returns:
 #:   int: 0 if `$1` is an alist, 1 otherwise
diff -r 53d05f470f4a -r 03350d2a2af6 tests/farray-alist.t
--- a/tests/farray-alist.t	Tue Oct 22 11:48:39 2024 +0200
+++ b/tests/farray-alist.t	Wed Oct 23 01:00:33 2024 +0200
@@ -921,6 +921,13 @@
   $ falist_type LIST
   alist (no-eol)
   $ falist_isalist LIST
+
+  $ falist_isref "$LIST"
+  $ falist_isref LIST
+  [1]
+  $ falist_isref ''
+  [1]
+
   $ falist_release LIST
   $ check_no_alist_artifacts
 
diff -r 53d05f470f4a -r 03350d2a2af6 tests/farray-array.t
--- a/tests/farray-array.t	Tue Oct 22 11:48:39 2024 +0200
+++ b/tests/farray-array.t	Wed Oct 23 01:00:33 2024 +0200
@@ -1254,6 +1254,13 @@
   $ falist_type TEST
   array (no-eol)
   $ farray_isarray TEST
+
+  $ farray_isref "$TEST"
+  $ farray_isref TEST
+  [1]
+  $ farray_isref ''
+  [1]
+
   $ farray_release TEST
   $ check_no_array_artifacts
 
diff -r 53d05f470f4a -r 03350d2a2af6 tests/farray-object.t
--- a/tests/farray-object.t	Tue Oct 22 11:48:39 2024 +0200
+++ b/tests/farray-object.t	Wed Oct 23 01:00:33 2024 +0200
@@ -22,6 +22,11 @@
   array (no-eol)
   $ falist_type ARRAY1
   array (no-eol)
+  $ fobject_isref "$ARRAY1"
+  $ fobject_isref ARRAY1
+  [1]
+  $ fobject_isref ''
+  [1]
   $ farray_create ITEM1 i11 i22
   $ farray_append ARRAY1 "$ITEM1"
   $ farray_release ITEM1
@@ -60,6 +65,11 @@
   alist (no-eol)
   $ farray_type LIST1
   alist (no-eol)
+  $ fobject_isref "$LIST1"
+  $ fobject_isref LIST1
+  [1]
+  $ fobject_isref ''
+  [1]
   $ falist_create ITEM1 k11 v11 k22 v22 k33 v33 k44 v44
   $ falist_set LIST1 k2 "$ITEM1"
   $ falist_release ITEM1