lib: add at_parser library

* Introduces the `at_parser` library for parsing AT command responses,
  notifications, or events.
  It exports an API that lets the user iterate through an AT command
  string and retrieve any of its elements based on their indices,
  efficiently and without heap allocations.
  Under the hood, this library leverages the power of regular
  expressions converted to deterministic finite automata by the free
  and open-source lexer generator `re2c`.

* In the `at_cmd_parser` library, renames the function
  `at_parser_cmd_type_get` to `at_parser_at_cmd_type_get` to prevent
  name collisions with the function `at_parser_cmd_type_get` in the
  `at_parser` library.

* Deprecates the `at_cmd_parser` library. It will be removed in a future
  version.

Signed-off-by: Mirko Covizzi <[email protected]>
Co-authored-by: Bartosz Gentkowski <[email protected]>

Author: 2 people

CODEOWNERS

@@ -111,6 +111,7 @@ Kconfig*                                  @tejlmand
 /lib/boot_banner/                         @nordicjm
 /lib/adp536x/                             @nrfconnect/ncs-cia
 /lib/at_cmd_parser/                       @rlubos
+/lib/at_parser/                           @MirkoCovizzi
 /lib/at_cmd_custom/                       @eivindj-nordic
 /lib/at_host/                             @rlubos
 /lib/at_monitor/                          @lemrey @rlubos
@@ -313,6 +314,7 @@ Kconfig*                                  @tejlmand
 /tests/drivers/nrfx_integration_test/     @anangl
 /tests/drivers/pwm/gpio_loopback/         @nrfconnect/ncs-low-level-test
 /tests/lib/at_cmd_parser/                 @rlubos
+/tests/lib/at_parser/                     @MirkoCovizzi
 /tests/lib/at_cmd_custom/                 @eivindj-nordic
 /tests/lib/date_time/                     @trantanen @tokangas
 /tests/lib/edge_impulse/                  @pdunaj @MarekPieta

applications/serial_lte_modem/src/slm_at_host.c

@@ -871,7 +871,7 @@ int slm_at_cb_wrapper(char *buf, size_t len, char *at_cmd, slm_at_callback *cb)
 	if (err) {
 		return err;
 	}
-	err = cb(at_parser_cmd_type_get(at_cmd), list, at_params_valid_count_get(list));
+	err = cb(at_parser_at_cmd_type_get(at_cmd), list, at_params_valid_count_get(list));
 	if (!err) {
 		err = at_cmd_custom_respond(buf, len, "OK\r\n");
 		if (err) {

doc/nrf/libraries/modem/at_cmd_parser.rst

@@ -7,6 +7,10 @@ AT command parser
    :local:
    :depth: 2
 
+.. note::
+
+   This library is deprecated in favor of the :ref:`at_parser_readme` library.
+
 The AT command parser is a library which parses any of the following:
 
 * A string response returned after issuing an AT command

doc/nrf/libraries/modem/at_parser.rst

@@ -0,0 +1,100 @@
+.. _at_parser_readme:
+
+AT parser
+#########
+
+.. contents::
+   :local:
+   :depth: 2
+
+The AT parser is a library that parses AT command responses, notifications, and events.
+
+Overview
+========
+
+The library exports an API that lets the user iterate through an AT command string and retrieve any of its elements based on their indices, efficiently and without heap allocations.
+Under the hood, this library uses regular expressions converted to deterministic finite automata by the free and open-source lexer generator ``re2c``.
+
+Configuration
+=============
+
+To begin using the AT parser, you first need to initialize it.
+This is done by invoking the :c:func:`at_parser_init` function, where you provide a pointer to the AT parser and the AT command string that needs to be parsed.
+
+The following code snippet shows how to initialize the AT parser for an AT command response:
+
+.. code-block:: c
+
+   int err;
+   struct at_parser parser;
+   const char *at_response = "+CFUN: 1";
+
+   err = at_parser_init(&parser, at_response);
+   if (err) {
+      return err;
+   }
+
+Usage
+=====
+
+Based on the type of the element at a given index, you can obtain its value by calling the type-generic macro :c:macro:`at_parser_num_get` for integer values, or the function :c:func:`at_params_string_get` for string values.
+
+The following code snippet shows how to retrieve the prefix, a ``uint16_t`` value, and a string value from an AT command response using the AT parser:
+
+.. code-block:: c
+
+   int err;
+   struct at_parser parser;
+   const char *at_response = "+CGCONTRDP: 0,,\"internet\",\"\",\"\",\"10.0.0.1\",\"10.0.0.2\",,,,,1028";
+   uint16_t num;
+   char buffer[16] = { 0 };
+   size_t len = sizeof(buffer);
+
+   err = at_parser_init(&parser, at_response);
+   if (err) {
+      return err;
+   }
+
+   /* Retrieve the AT command response prefix, at index 0 of the AT command string. */
+   err = at_parser_string_get(&parser, 0, buffer, &len);
+   if (err) {
+      return err;
+   }
+
+   /* "Prefix: `+CGCONTRDP`" */
+   printk("Prefix: `%s`\n", buffer);
+
+   /* Retrieve the first subparameter, at index 1 of the AT command string.
+    * `at_parser_num_get` is a type-generic macro that retrieves an integer based on the type
+    * of the passed variable. In this example, the preprocessor will expand the macro to the
+    * function corresponding to the `uint16_t` type, which is the function `at_parser_uint16_get`.
+    */
+   err = at_parser_num_get(&parser, 1, &num);
+   if (err) {
+      return err;
+   }
+
+   /* "First subparameter: 0" */
+   printk("First subparameter: %u\n", num);
+
+   /* Reset the buffer length. */
+   len = sizeof(buffer);
+
+   /* Retrieve the third subparameter, at index 3 of the AT command string. */
+   err = at_parser_string_get(&parser, 3, buffer, &len);
+   if (err) {
+      return err;
+   }
+
+   /* "Third subparameter: `internet`" */
+   printk("Third subparameter: `%s`\n", buffer);
+
+API documentation
+*****************
+
+| Header file: :file:`include/modem/at_parser.h`
+| Source file: :file:`lib/at_parser/src/at_parser.c`
+
+.. doxygengroup:: at_parser
+   :project: nrf
+   :members:

doc/nrf/releases_and_maturity/migration/migration_guide_2.8.rst

@@ -55,6 +55,13 @@ LTE link control library
        Use the :kconfig:option:`CONFIG_LTE_NETWORK_MODE_LTE_M_NBIOT` or :kconfig:option:`CONFIG_LTE_NETWORK_MODE_LTE_M_NBIOT_GPS` Kconfig option instead.
        In addition, you can control the priority between LTE-M and NB-IoT using the :kconfig:option:`CONFIG_LTE_MODE_PREFERENCE` Kconfig option.
 
+AT command parser
+-----------------
+
+.. toggle::
+
+  * The :c:func:`at_parser_cmd_type_get` has been renamed to :c:func:`at_parser_at_cmd_type_get`.
+
 .. _migration_2.8_recommended:
 
 Recommended changes
@@ -74,4 +81,193 @@ Libraries
 
 This section describes the changes related to libraries.
 
-|no_changes_yet_note|
+AT command parser
+-----------------
+
+.. toggle::
+
+  * The :ref:`at_cmd_parser_readme` library has been deprecated in favor of the :ref:`at_parser_readme` library and will be removed in a future version.
+
+    You can follow this guide to migrate your application to use the :ref:`at_parser_readme` library.
+    This will reduce the footprint of the application and will decrease memory requirements on the heap.
+
+    To replace :ref:`at_cmd_parser_readme` with the :ref:`at_parser_readme`, complete the following steps:
+
+    1. Replace the :kconfig:option:`CONFIG_AT_CMD_PARSER` Kconfig option with the :kconfig:option:`CONFIG_AT_PARSER` Kconfig option.
+
+    #. Replace header files:
+
+       * Remove:
+
+         .. code-block:: C
+
+          #include <modem/at_cmd_parser.h>
+          #include <modem/at_params.h>
+
+       * Add:
+
+         .. code-block:: C
+
+          #include <modem/at_parser.h>
+
+    #. Replace AT parameter list:
+
+       * Remove:
+
+         .. code-block:: C
+
+          struct at_param_list param_list;
+
+       * Add:
+
+         .. code-block:: C
+
+          struct at_parser parser;
+
+    #. Replace AT parameter list initialization:
+
+       * Remove:
+
+         .. code-block:: C
+
+          /* `param_list` is a pointer to the AT parameter list.
+           * `AT_PARAMS_COUNT` is the maximum number of parameters of the list.
+           */
+          at_params_list_init(&param_list, AT_PARAMS_COUNT);
+
+          /* Other code. */
+
+          /* `at_string` is the AT command string to be parsed.
+           * `&remainder` is a pointer to the returned remainder after parsing.
+           * `&param_list` is a pointer to the AT parameter list.
+           */
+          at_parser_params_from_str(at_string, &remainder, &param_list);
+
+       * Add:
+
+         .. code-block:: C
+
+          /* `&at_parser` is a pointer to the AT parser.
+           * `at_string` is the AT command string to be parsed.
+           */
+          at_parser_init(&at_parser, at_string);
+
+         .. note::
+
+            Remember to check the returned error codes from the :ref:`at_parser_readme` functions.
+            For the sake of simplicity, they have been omitted in this migration guide.
+            Refer to the :ref:`at_parser_readme` documentation for more information on the API and the returned error codes.
+
+    #. Replace integer parameter retrieval:
+
+       * Remove:
+
+         .. code-block:: C
+
+          int value;
+
+          /* `&param_list` is a pointer to the AT parameter list.
+           * `index` is the index of the parameter to retrieve.
+           * `&value` is a pointer to the output integer variable.
+           */
+          at_params_int_get(&param_list, index, &value);
+
+          uint16_t value;
+          at_params_unsigned_short_get(&param_list, index, &value);
+
+          /* Other variants: */
+          at_params_short_get(&param_list, index, &value);
+          at_params_unsigned_int_get(&param_list, index, &value);
+          at_params_int64_get(&param_list, index, &value);
+
+       * Add:
+
+         .. code-block:: C
+
+          int value;
+
+          /* `&at_parser` is a pointer to the AT parser.
+           * `index` is the index of the parameter to retrieve.
+           * `&value` is a pointer to the output integer variable.
+           *
+           * Note: this function is type-generic on the type of the output integer variable.
+           */
+          err = at_parser_num_get(&at_parser, index, &value);
+
+          uint16_t value;
+          /* Note: this function is type-generic on the type of the output integer variable. */
+          err = at_parser_num_get(&at_parser, index, &value);
+
+    #. Replace string parameter retrieval:
+
+       * Remove:
+
+         .. code-block:: C
+
+          /* `&param_list` is a pointer to the AT parameter list.
+           * `index` is the index of the parameter to retrieve.
+           * `value` is the output buffer where the string is copied into.
+           * `&len` is a pointer to the length of the copied string.
+           *
+           * Note: the copied string is not null-terminated.
+           */
+          at_params_string_get(&param_list, index, value, &len);
+
+          /* Null-terminate the string. */
+          value[len] = '\0';
+
+       * Add:
+
+         .. code-block:: C
+
+          /* `&at_parser` is a pointer to the AT parser.
+           * `index` is the index of the parameter to retrieve.
+           * `value` is the output buffer where the string is copied into.
+           * `&len` is a pointer to the length of the copied string.
+           *
+           * Note: the copied string is null-terminated.
+           */
+          at_parser_string_get(&at_parser, index, value, &len);
+
+    #. Replace parameter count retrieval:
+
+       * Remove:
+
+         .. code-block:: C
+
+          /* `&param_list` is a pointer to the AT parameter list.
+           * `count` is the returned parameter count.
+           */
+          uint32_t count = at_params_valid_count_get(&param_list);
+
+       * Add:
+
+         .. code-block:: C
+
+          size_t count;
+
+          /* `&at_parser` is a pointer to the AT parser.
+           * `&count` is a pointer to the returned parameter count.
+           */
+          at_parser_cmd_count_get(&at_parser, &count);
+
+    #. Replace command type retrieval:
+
+       * Remove:
+
+         .. code-block:: C
+
+          /* `at_string` is the AT string that we want to retrieve the command type of.
+           */
+          enum at_cmd_type type = at_parser_at_cmd_type_get(at_string);
+
+       * Add:
+
+         .. code-block:: C
+
+          enum at_parser_cmd_type type;
+
+          /* `&at_parser` is a pointer to the AT parser.
+           * `&type` pointer to the returned command type.
+           */
+          at_parser_cmd_type_get(&at_parser, &type);

doc/nrf/releases_and_maturity/releases/release-notes-changelog.rst

@@ -482,6 +482,25 @@ Gazell libraries
 Modem libraries
 ---------------
 
+* Added:
+
+   * The :ref:`at_parser_readme` library.
+     The :ref:`at_parser_readme` is a library that parses AT command responses, notifications, and events.
+     Compared to the deprecated :ref:`at_cmd_parser_readme` library, it does not allocate memory dynamically and has a smaller footprint.
+     For more information on how to transition from the :ref:`at_cmd_parser_readme` library to the :ref:`at_parser_readme` library, see the :ref:`migration guide <migration_2.8_recommended>`.
+
+* :ref:`at_cmd_parser_readme` library:
+
+  * Deprecated:
+
+    * The :ref:`at_cmd_parser_readme` library in favor of the :ref:`at_parser_readme` library.
+      The :ref:`at_cmd_parser_readme` library will be removed in a future version.
+      For more information on how to transition from the :ref:`at_cmd_parser_readme` library to the :ref:`at_parser_readme` library, see the :ref:`migration guide <migration_2.8_recommended>`.
+    * The :kconfig:option:`CONFIG_AT_CMD_PARSER`.
+      This option will be removed in a future version.
+
+  * Renamed the :c:func:`at_parser_cmd_type_get` function to :c:func:`at_parser_at_cmd_type_get` to prevent a name collision.
+
 * :ref:`lte_lc_readme` library:
 
   * Removed:

include/modem/at_cmd_parser.h

@@ -127,7 +127,7 @@ enum at_cmd_type {
  *
  * @return Command type.
  */
-enum at_cmd_type at_parser_cmd_type_get(const char *at_cmd);
+enum at_cmd_type at_parser_at_cmd_type_get(const char *at_cmd);
 
 /** @} */