docs/man/* et al: document upscli_str_contains_token() and upscli_str_add_unique_token() [#2852, #2859]

Signed-off-by: Jim Klimov <[email protected]>

Author: jimklimov

NEWS.adoc

@@ -387,6 +387,10 @@ This requirement compromises usability of `make distcheck` on platforms without
    * Updated `upsmon` client with setting to toggle whether an `ALARM`
      status can prompt the UPS to become critical in certain situations.
 
+ - New `libupsclient` API methods added, `upscli_str_add_unique_token()` and
+   `upscli_str_contains_token()`, to help C NUT clients process `ups.status` and
+   similarly structured strings same way as NUT core code base. [#2852, #2859]
+
  - upsmon:
    * it was realized that the `POWERDOWNFLAG` must be explicitly set in the
      configuration file, there is no built-in default in the binary program

UPGRADING.adoc

@@ -71,6 +71,10 @@ Changes from 2.8.2 to 2.8.3
   OS distribution package recipes that deliver the module separately (e.g.
   as part of Python ecosystem rather than NUT) may have to adjust. [#2773]
 
+- New `libupsclient` API methods added, `upscli_str_add_unique_token()` and
+  `upscli_str_contains_token()`, to help C NUT clients process `ups.status` and
+  similarly structured strings same way as NUT core code base. [#2852, #2859]
+
 - Updated man page generation with `configure` script options to specify that
   manual sections on the target platform differ from (Linux-based) defaults
   hard-coded into page sources; this should allow to simplify NUT packaging

docs/man/Makefile.am

@@ -464,6 +464,8 @@ SRC_DEV_PAGES = \
 	upscli_ssl.txt \
 	upscli_strerror.txt \
 	upscli_upserror.txt \
+	upscli_str_add_unique_token.txt \
+	upscli_str_contains_token.txt \
 	libnutclient.txt \
 	libnutclient_commands.txt \
 	libnutclient_devices.txt \
@@ -581,6 +583,8 @@ INST_MAN_DEV_API_PAGES = \
 	upscli_ssl.$(MAN_SECTION_API) \
 	upscli_strerror.$(MAN_SECTION_API) \
 	upscli_upserror.$(MAN_SECTION_API) \
+	upscli_str_add_unique_token.$(MAN_SECTION_API) \
+	upscli_str_contains_token.$(MAN_SECTION_API) \
 	libnutclient.$(MAN_SECTION_API) \
 	libnutclient_commands.$(MAN_SECTION_API) \
 	$(LIBNUTCLIENT_COMMANDS_DEPS) \
@@ -687,6 +691,8 @@ INST_HTML_DEV_MANS = \
 	upscli_ssl.html \
 	upscli_strerror.html \
 	upscli_upserror.html \
+	upscli_str_add_unique_token.html \
+	upscli_str_contains_token.html \
 	libnutclient.html \
 	libnutclient_commands.html \
 	libnutclient_devices.html \

docs/man/index.txt

@@ -106,6 +106,8 @@ Client library
 - linkman:upscli_ssl[3]
 - linkman:upscli_strerror[3]
 - linkman:upscli_upserror[3]
+- linkman:upscli_str_add_unique_token[3]
+- linkman:upscli_str_contains_token[3]
 
 [[devscan]]
 Device discovery library

docs/man/upscli_str_add_unique_token.txt

@@ -0,0 +1,64 @@
+UPSCLI_STR_ADD_UNIQUE_TOKEN(3)
+==============================
+
+NAME
+----
+
+upscli_str_add_unique_token - Add a unique token into a string buffer,
+    with optional callbacks as needed by implementation
+
+SYNOPSIS
+--------
+
+------
+	#include <upsclient.h>
+
+	int	upscli_str_add_unique_token(char *tgt, size_t tgtsize, const char *token,
+				int (*callback_always)(char *, size_t, const char *),
+				int (*callback_unique)(char *, size_t, const char *) );
+------
+
+DESCRIPTION
+-----------
+
+The *upscli_str_add_unique_token*() function takes the pointer 'tgt' to a
+caller-provided `char *` buffer of size 'tgtsize', and the pointer 'token'
+to a contiguous token that should be added to the end of 'tgt' buffer, if
+it is not there yet.
+
+The 'token' contents are stripped of surrounding space characters, and the
+method recurses to independently process each space-separated token inside
+(if there are any spaces left).
+
+The resulting 'tgt' buffer would eventually collect a string comprised of
+unique 'token' values in order of first mention, separated by single space
+characters (ASCII '0x20').
+
+Optionally calls 'callback_always' (if not `NULL`) after checking the input
+for spaces (and maybe recursing) and before checking if the token is already
+there, and/or 'callback_unique' (if not `NULL`) after checking for uniqueness
+and just before going to add a newly seen token.
+
+* If such callback returns '0', abort the addition of 'token' and return '-3'.
+
+It is up to the caller to dynamically or statically allocate the 'tgt' buffer
+and *free*() it if needed.  As far as this method is concerned, the buffer
+may be recycled (in data processing loops) by setting the initial character
+to `'\0'`, making it an empty string again.
+
+RETURN VALUE
+------------
+
+The *upscli_str_add_unique_token*() function returns a numeric code:
+
+* '0' if the 'token' value was already there in 'tgt' buffer;
+* '1' if 'token' was added successfully;
+* '-1' if we needed to add the 'token', but it did not fit under the 'tgtsize'
+  limit;
+* '-2' if either 'token' or 'tgt' string was `NULL`, or if 'token' was empty;
+* '-3' if the 'token' was rejected by the optional callback method returning '0'.
+
+SEE ALSO
+--------
+
+linkman:upscli_str_contains_token[3]

docs/man/upscli_str_contains_token.txt

@@ -0,0 +1,39 @@
+UPSCLI_STR_CONTAINS_TOKEN(3)
+============================
+
+NAME
+----
+
+upscli_str_contains_token - Verify that an unique token is present in the string
+
+SYNOPSIS
+--------
+
+------
+	#include <upsclient.h>
+
+	int	upscli_str_contains_token(const char *string, const char *token);
+------
+
+DESCRIPTION
+-----------
+
+The *upscli_str_contains_token*() function takes the pointer 'tgt' to a
+caller-provided `const char *` buffer, comprised of unique tokens separated
+by single space characters (ASCII '0x20'), and the pointer 'token' to a
+presumed-contiguous token value that should be found in the 'tgt' buffer.
+
+RETURN VALUE
+------------
+
+The *upscli_str_contains_token*() function returns a numeric code:
+
+* 'non-zero' if the 'token' value was found in 'tgt' buffer (possibly
+  surrounded by space characters, or being at start/end of the string);
+* '0' if 'token' was not found, or if either 'token' or 'tgt' string
+  was `NULL` or empty.
+
+SEE ALSO
+--------
+
+linkman:upscli_str_add_unique_token[3]

docs/man/upsclient.txt

@@ -58,6 +58,19 @@ to disconnect from *upsd* and release any dynamic memory associated
 with the `UPSCONN_t` structure.  Failure to call this function will result
 in memory and file descriptor leaks in your program.
 
+STRING FUNCTIONS
+----------------
+
+To parse the `ups.status` values (check whether a particular token is present)
+you are encouraged to use the linkman:upscli_str_contains_token[3] method.
+
+To collect unique tokens into a string in the same manner a NUT driver does,
+the linkman:upscli_str_add_unique_token[3] can be helpful.
+
+You are welcome to consult the NUT source code base for use of equivalent
+methods to implement such features as `status_init()`, `status_get()`,
+`status_set()` and `status_commit()` methods in its data-processing loops.
+
 ERROR HANDLING
 --------------
 
@@ -79,5 +92,6 @@ linkman:upscli_getvar[3], linkman:upscli_list_next[3],
 linkman:upscli_list_start[3], linkman:upscli_readline[3],
 linkman:upscli_sendline[3],
 linkman:upscli_splitaddr[3], linkman:upscli_splitname[3],
-linkman:upscli_ssl[3], linkman:upscli_strerror[3],
-linkman:upscli_upserror[3]
+linkman:upscli_ssl[3],
+linkman:upscli_strerror[3], linkman:upscli_upserror[3],
+linkman:upscli_str_add_unique_token[3], linkman:upscli_str_contains_token[3]

docs/nut.dict

@@ -1,4 +1,4 @@
-personal_ws-1.1 en 3349 utf-8
+personal_ws-1.1 en 3353 utf-8
 AAC
 AAS
 ABI
@@ -2762,6 +2762,8 @@ rebasing
 rebootdelay
 rebranded
 reconnection
+recurses
+recursing
 recv
 redistributors
 reentrancy
@@ -3062,6 +3064,8 @@ testtime
 testuser
 textproc
 tgcware
+tgt
+tgtsize
 tgz
 th
 timeframe