feat(esp_repl): Add esp_linenoise and esp_commands dependencies

Author: SoucheSouche

esp_repl/CMakeLists.txt

@@ -5,4 +5,4 @@ set(srcs "esp_repl.c")
 idf_component_register(
                     SRCS ${srcs}
                     INCLUDE_DIRS include
-                    PRIV_INCLUDE_DIRS private_include)
+                    REQUIRES esp_linenoise esp_commands)

esp_repl/README.md

@@ -0,0 +1,118 @@
+# esp_repl Component
+
+The `esp_repl` component provides a **Runtime Evaluation Loop (REPL)** mechanism for ESP-IDF-based applications.  
+It allows developers to build interactive command-line interfaces (CLI) that support user-defined commands, history management, and customizable callbacks for command execution.
+
+This component integrates with [`esp_linenoise`](../esp_linenoise) for line editing and input handling, and with [`esp_commands`](../esp_commands) for command parsing and execution.
+
+---
+
+## Features
+
+- Modular REPL management with explicit `start` and `stop` control
+- Integration with [`esp_linenoise`](../esp_linenoise) for input and history
+- Support for command sets through [`esp_commands`](../esp_commands)
+- Configurable callbacks for:
+  - Pre-execution processing
+  - Post-execution handling
+  - On-stop and on-exit events
+- Thread-safe operation using FreeRTOS semaphores
+- Optional command history persistence to filesystem
+
+---
+
+## Usage
+
+A typical use case involves:
+
+1. Initializing `esp_linenoise` and `esp_commands`
+2. Creating the REPL instance with `esp_repl_create()`
+3. Running `esp_repl()` in a task
+4. Starting and stopping the REPL using `esp_repl_start()` and `esp_repl_stop()`
+5. Destroying the instance with `esp_repl_destroy()` when done
+
+### Example
+
+```c
+#include "esp_repl.h"
+#include "esp_linenoise.h"
+#include "esp_commands.h"
+#include "esp_log.h"
+#include "freertos/FreeRTOS.h"
+#include "freertos/task.h"
+
+static const char *TAG = "repl_example";
+
+void repl_task(void *arg)
+{
+    esp_repl_handle_t repl_hdl = (esp_repl_handle_t)arg;
+
+    // Run REPL loop (blocking until esp_repl_stop() is called)
+    // The loop won't be reached until esp_repl_start() is called
+    esp_repl(repl_hdl);
+
+    ESP_LOGI(TAG, "REPL task exiting");
+    vTaskDelete(NULL);
+}
+
+void app_main(void)
+{
+    esp_err_t ret;
+    esp_repl_handle_t repl = NULL;
+
+    // Initialize esp_linenoise (mandatory)
+    esp_linenoise_handle_t esp_linenoise_hdl = esp_linenoise_create();
+
+    // Initialize command set (optional)
+    esp_command_set_handle_t esp_commands_cmd_set = esp_commands_create();
+
+    esp_repl_config_t repl_cfg = {
+        .linenoise_handle = esp_linenoise_hdl,
+        .command_set_handle = esp_commands_cmd_set, /* optional */
+        .max_cmd_line_size = 256,
+        .history_save_path = "/spiffs/repl_history.txt", /* optional */
+    };
+
+    ret = esp_repl_create(&repl, &repl_cfg);
+    if (ret != ESP_OK) {
+        ESP_LOGE(TAG, "Failed to create REPL instance (%s)", esp_err_to_name(ret));
+        return;
+    }
+
+    // Create REPL task
+    if (xTaskCreate(repl_task, "repl_task", 4096, repl, 5, NULL) != pdPASS) {
+        ESP_LOGE(TAG, "Failed to create REPL task");
+        esp_repl_destroy(repl);
+        return;
+    }
+
+    ESP_LOGI(TAG, "Starting REPL...");
+    ret = esp_repl_start(repl);
+    if (ret != ESP_OK) {
+        ESP_LOGE(TAG, "Failed to start REPL (%s)", esp_err_to_name(ret));
+        esp_repl_destroy(repl);
+        return;
+    }
+
+    // Application logic can run in parallel while REPL runs in its own task
+    // [...]
+    vTaskDelay(pdMS_TO_TICKS(10000)); // Example delay
+
+    // Stop REPL
+    ret = esp_repl_stop(repl);
+    if (ret != ESP_OK) {
+        ESP_LOGW(TAG, "Failed to stop REPL (%s)", esp_err_to_name(ret));
+    }
+
+    ESP_LOGI(TAG, "REPL exited");
+
+    // Destroy REPL instance and clean up
+    ret = esp_repl_destroy(repl);
+    if (ret != ESP_OK) {
+        ESP_LOGW(TAG, "Failed to destroy REPL instance cleanly (%s)", esp_err_to_name(ret));
+    }
+
+    ESP_LOGI(TAG, "REPL example finished");
+}
+
+```

esp_repl/esp_repl.c

@@ -1,15 +1,17 @@
+
 /*
- * SPDX-FileCopyrightText: 2025 Espressif Systems (Shanghai) CO LTD
- *
- * SPDX-License-Identifier: Apache-2.0
- */
+* SPDX-FileCopyrightText: 2025 Espressif Systems (Shanghai) CO LTD
+*
+* SPDX-License-Identifier: Apache-2.0
+*/
 #include <stdbool.h>
 #include <string.h>
 #include "freertos/FreeRTOS.h"
 #include "freertos/semphr.h"
 #include "esp_repl.h"
 #include "esp_err.h"
-
+#include "esp_commands.h"
+#include "esp_linenoise.h"
 typedef enum {
     ESP_REPL_STATE_RUNNING,
     ESP_REPL_STATE_STOPPED
@@ -27,15 +29,14 @@ typedef struct esp_repl_instance {
 } esp_repl_instance_t;
 
 #define ESP_REPL_CHECK_INSTANCE(handle) do {                                                          \
-    if((handle == NULL) || ((esp_repl_instance_t*)handle->self != (esp_repl_instance_t*)handle)) {    \
-        return ESP_ERR_INVALID_ARG;                                                                   \
-    }                                                                                                 \
-} while(0)
+        if((handle == NULL) || ((esp_repl_instance_t*)handle->self != (esp_repl_instance_t*)handle)) {    \
+            return ESP_ERR_INVALID_ARG;                                                                   \
+        }                                                                                                 \
+    } while(0)
 
-esp_err_t   esp_repl_create(esp_repl_handle_t *handle, const esp_repl_config_t *config)
+esp_err_t esp_repl_create(esp_repl_handle_t *handle, const esp_repl_config_t *config)
 {
-    if ((config->executor.func == NULL) ||
-            (config->reader.func == NULL) ||
+    if ((config->linenoise_handle == NULL) ||
             (config->max_cmd_line_size == 0)) {
         return ESP_ERR_INVALID_ARG;
     }
@@ -55,7 +56,7 @@ esp_err_t   esp_repl_create(esp_repl_handle_t *handle, const esp_repl_config_t *
     }
 
     /* take the mutex right away to prevent the task to start running until
-     * the user explicitly calls esp_repl_start */
+    * the user explicitly calls esp_repl_start */
     xSemaphoreTake(instance->state.mux, portMAX_DELAY);
 
     *handle = instance;
@@ -106,7 +107,21 @@ esp_err_t esp_repl_stop(esp_repl_handle_t handle)
     /* update the state to force the while loop in esp_repl to return */
     state->state = ESP_REPL_STATE_STOPPED;
 
-    /* Call the on_stop callback to let the user unblock reader.func, if provided */
+    /* Call the abort function from esp_linenoise to force esp_linenoise_get_line to return.
+    * This function is expected to return ESP_OK only if the user has registered a custom
+    * read to the esp_linenoise instance and if the abort function succeeds.
+    * ESP_ERR_INVALID_STATE is expected to be returned by esp_linenoise_abort if it is called
+    * when the user has registered a custom read to the esp_linenoise instance. From the point
+    * of view of esp_repl_stop, this return value if indicating that the user will have to take
+    * care of returning from its own custom read by himself through the call of the on_stop callback,
+    * therefore set the return value of esp_repl_stop to ESP_OK. */
+    esp_err_t ret_val = esp_linenoise_abort(config->linenoise_handle);
+    if (ret_val == ESP_ERR_INVALID_STATE) {
+        ret_val = ESP_OK;
+    }
+
+    /* Call the on_stop callback to let the user unblock esp_linenoise
+    * if a custom read is provided */
     if (config->on_stop.func != NULL) {
         config->on_stop.func(config->on_stop.ctx, handle);
     }
@@ -117,7 +132,7 @@ esp_err_t esp_repl_stop(esp_repl_handle_t handle)
     /* give it back so destroy can also take/give symmetrically */
     xSemaphoreGive(state->mux);
 
-    return ESP_OK;
+    return ret_val;
 }
 
 void esp_repl(esp_repl_handle_t handle)
@@ -137,17 +152,28 @@ void esp_repl(esp_repl_handle_t handle)
     }
 
     /* Waiting for task notify. This happens when `esp_repl_start`
-     * function is called. */
+    * function is called. */
     xSemaphoreTake(state->mux, portMAX_DELAY);
 
+    esp_linenoise_handle_t l_hdl = config->linenoise_handle;
+    esp_command_set_handle_t c_set = config->command_set_handle;
+
     /* REPL loop */
     while (state->state == ESP_REPL_STATE_RUNNING) {
 
         /* try to read a command line */
-        const esp_err_t read_ret = config->reader.func(config->reader.ctx, cmd_line, cmd_line_size);
+        const esp_err_t read_ret = esp_linenoise_get_line(l_hdl, cmd_line, cmd_line_size);
+
+        /* Add the command to the history */
+        esp_linenoise_history_add(l_hdl, cmd_line);
+
+        /* Save command history to filesystem */
+        if (config->history_save_path) {
+            esp_linenoise_history_save(l_hdl, config->history_save_path);
+        }
 
         /* forward the raw command line to the pre executor callback (e.g., save in history).
-         * this callback is not necessary for the user to register, continue if it isn't */
+        * this callback is not necessary for the user to register, continue if it isn't */
         if (config->pre_executor.func != NULL) {
             config->pre_executor.func(config->pre_executor.ctx, cmd_line, read_ret);
         }
@@ -159,10 +185,10 @@ void esp_repl(esp_repl_handle_t handle)
 
         /* try to run the command */
         int cmd_func_ret;
-        const esp_err_t exec_ret = config->executor.func(config->executor.ctx, cmd_line, &cmd_func_ret);
+        const esp_err_t exec_ret = esp_commands_execute(c_set, -1, cmd_line, &cmd_func_ret);
 
         /* forward the raw command line to the post executor callback (e.g., save in history).
-         * this callback is not necessary for the user to register, continue if it isn't */
+        * this callback is not necessary for the user to register, continue if it isn't */
         if (config->post_executor.func != NULL) {
             config->post_executor.func(config->post_executor.ctx, cmd_line, exec_ret, cmd_func_ret);
         }

esp_repl/idf_component.yml

@@ -2,7 +2,12 @@ version: "1.0.0"
 description: "esp_repl - Read Eval Print Loop component"
 url: https://github.com/espressif/idf-extra-components/tree/master/esp_repl
 dependencies:
-  idf: ">=6.0"
+  SoucheSouche/esp_linenoise:
+    version: "*"
+    registry_url: https://components-staging.espressif.com
+  SoucheSouche/esp_commands:
+    version: "*"
+    registry_url: https://components-staging.espressif.com
 sbom:
   manifests:
     - path: sbom_esp_repl.yml

esp_repl/include/esp_repl.h

@@ -11,31 +11,14 @@ extern "C" {
 
 #include <stdbool.h>
 #include "esp_err.h"
+#include "esp_linenoise.h"
+#include "esp_commands.h"
 
 /**
  * @brief Handle to a REPL instance.
  */
 typedef struct esp_repl_instance *esp_repl_handle_t;
 
-/**
- * @brief Function prototype for reading input for the REPL.
- *
- * @param ctx User-defined context pointer.
- * @param buf Buffer to store the read data.
- * @param buf_size Size of the buffer in bytes.
- *
- * @return ESP_OK on success, error code otherwise.
- */
-typedef esp_err_t (*esp_repl_reader_fn)(void *ctx, char *buf, size_t buf_size);
-
-/**
- * @brief Reader configuration structure for the REPL.
- */
-typedef struct esp_repl_reader {
-    esp_repl_reader_fn func; /**!< Function to read input */
-    void *ctx;               /**!< Context passed to the reader function */
-} esp_repl_reader_t;
-
 /**
  * @brief Function prototype called before executing a command.
  *
@@ -55,25 +38,6 @@ typedef struct esp_repl_pre_executor {
     void *ctx;                      /**!< Context passed to the pre-executor function */
 } esp_repl_pre_executor_t;
 
-/**
- * @brief Function prototype to execute a REPL command.
- *
- * @param ctx User-defined context pointer.
- * @param buf Null-terminated command string.
- * @param ret_val Pointer to store the command return value.
- *
- * @return ESP_OK on success, error code otherwise.
- */
-typedef esp_err_t (*esp_repl_executor_fn)(void *ctx, const char *buf, int *ret_val);
-
-/**
- * @brief Executor configuration structure for the REPL.
- */
-typedef struct esp_repl_executor {
-    esp_repl_executor_fn func; /**!< Function to execute commands */
-    void *ctx;                  /**!< Context passed to the executor function */
-} esp_repl_executor_t;
-
 /**
  * @brief Function prototype called after executing a command.
  *
@@ -133,13 +97,14 @@ typedef struct esp_repl_on_exit {
  * @brief Configuration structure to initialize a REPL instance.
  */
 typedef struct esp_repl_config {
-    size_t max_cmd_line_size;        /**!< Maximum allowed command line size */
-    esp_repl_reader_t reader;        /**!< Reader callback and context */
-    esp_repl_pre_executor_t pre_executor;   /**!< Pre-executor callback and context */
-    esp_repl_executor_t executor;           /**!< Executor callback and context */
-    esp_repl_post_executor_t post_executor; /**!< Post-executor callback and context */
-    esp_repl_on_stop_t on_stop;             /**!< Stop callback and context */
-    esp_repl_on_exit_t on_exit;             /**!< Exit callback and context */
+    esp_linenoise_handle_t linenoise_handle;    /**!< Handle to the esp_linenoise instance */
+    esp_command_set_handle_t command_set_handle;   /**!< Handle to a set of commands */
+    size_t max_cmd_line_size;                   /**!< Maximum allowed command line size */
+    const char *history_save_path;              /**!< Path to file to save the history */
+    esp_repl_pre_executor_t pre_executor;       /**!< Pre-executor callback and context */
+    esp_repl_post_executor_t post_executor;     /**!< Post-executor callback and context */
+    esp_repl_on_stop_t on_stop;                 /**!< Stop callback and context */
+    esp_repl_on_exit_t on_exit;                 /**!< Exit callback and context */
 } esp_repl_config_t;
 
 /**

esp_repl/test_apps/main/CMakeLists.txt

@@ -1,4 +1,5 @@
+
 idf_component_register(SRCS "test_esp_repl.c" "test_main.c"
-                    PRIV_INCLUDE_DIRS "." "include"
+                    PRIV_INCLUDE_DIRS "."
                     PRIV_REQUIRES unity
                     WHOLE_ARCHIVE)