This is an automated email from the ASF dual-hosted git repository.
acassis pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/nuttx.git
The following commit(s) were added to refs/heads/master by this push:
new 95b1f7dbf1c Documentation: document cle library.
95b1f7dbf1c is described below
commit 95b1f7dbf1cfcfb6f49ae321a9b2fc01e820caaf
Author: hanzhijian <[email protected]>
AuthorDate: Wed May 27 19:06:06 2026 +0800
Documentation: document cle library.
Refs #11081
Signed-off-by: hanzj <[email protected]>
Signed-off-by: hanzhijian <[email protected]>
---
Documentation/applications/system/cle/index.rst | 169 ++++++++++++++++++++++++
1 file changed, 169 insertions(+)
diff --git a/Documentation/applications/system/cle/index.rst
b/Documentation/applications/system/cle/index.rst
index 0ecec5a4b12..c7bf31d6a71 100644
--- a/Documentation/applications/system/cle/index.rst
+++ b/Documentation/applications/system/cle/index.rst
@@ -1,3 +1,172 @@
======================================
``cle`` EMACS-like Command Line Editor
======================================
+
+Overview
+========
+
+The ``cle`` library provides an EMACS-like command line editor for NuttX
+applications. It is similar to GNU ``readline`` but much smaller, making it
+suitable for resource-constrained embedded systems. ``cle`` is not a
+standalone command; it is a library that applications call to get interactive
+line editing with history and key bindings.
+
+The editor assumes a VT100-compatible terminal and a fixed-width character
+set (such as Courier). It does not support word-oriented operations or
+keypad cursor control.
+
+Configuration
+=============
+
+Enable the editor with ``CONFIG_SYSTEM_CLE``. The following options are
+available when ``CONFIG_SYSTEM_CLE`` is enabled:
+
+``CONFIG_SYSTEM_COLOR_CLE``
+ Add simple color highlighting to the prompt, command text, and output.
+ The colors are hardcoded: yellow for the prompt, cyan for command text,
+ and green for output.
+
+``CONFIG_SYSTEM_CLE_CMD_HISTORY``
+ Enable Unix-style command history using the up and down arrow keys.
+ The history is stored in an in-memory circular buffer.
+
+ In FLAT and PROTECTED builds the history is shared by all threads; in
+ KERNEL builds each process has its own history buffer.
+
+``CONFIG_SYSTEM_CLE_CMD_HISTORY_LINELEN``
+ Maximum length of one command line in the history buffer. Default: 64
+ (when ``CONFIG_DEFAULT_SMALL`` is set) or 80.
+
+``CONFIG_SYSTEM_CLE_CMD_HISTORY_LEN``
+ Number of history records to keep. Default: 4 (when
+ ``CONFIG_DEFAULT_SMALL`` is set) or 16.
+
+``CONFIG_SYSTEM_CLE_DEBUGLEVEL``
+ Debug output level. 0 = off, 1 = errors on console, 2 = full debug
+ information. Debug output is sent via ``syslog()``.
+
+Usage
+=====
+
+``cle`` is a library, not a standalone command. Applications call one of
+the following functions:
+
+.. code-block:: c
+
+ #include <system/cle.h>
+
+ int cle_fd(FAR char *line, FAR const char *prompt, uint16_t linelen,
+ int infd, int outfd);
+
+ #ifdef CONFIG_FILE_STREAM
+ int cle(FAR char *line, FAR const char *prompt, uint16_t linelen,
+ FAR FILE *instream, FAR FILE *outstream);
+ #endif
+
+Parameters
+----------
+
+``line``
+ Buffer to store the edited line.
+
+``prompt``
+ Prompt string displayed before the cursor.
+
+``linelen``
+ Maximum length of the line buffer.
+
+``infd`` / ``instream``
+ Input file descriptor (``cle_fd``) or FILE stream (``cle``).
+
+``outfd`` / ``outstream``
+ Output file descriptor (``cle_fd``) or FILE stream (``cle``).
+
+Return Value
+------------
+
+Both functions return the number of characters in the edited line, or a
+negative error code on failure.
+
+Key Bindings
+============
+
+``cle`` uses EMACS-style control key bindings:
+
+``Ctrl-A``
+ Move cursor to the start of the current line.
+
+``Ctrl-B``
+ Move cursor left one character.
+
+``Ctrl-D``
+ Delete the character at the cursor position.
+
+``Ctrl-E``
+ Move cursor to the end of the current line.
+
+``Ctrl-F``
+ Move cursor right one character.
+
+``Ctrl-H`` (Backspace)
+ Delete the character to the left of the cursor.
+
+``Ctrl-K``
+ Delete from the cursor to the end of the line.
+
+``Ctrl-L``
+ Clear the screen and redraw the current line.
+
+``Ctrl-N``
+ Move down one line (when command history is enabled).
+
+``Ctrl-P``
+ Move up one line (when command history is enabled).
+
+``Ctrl-U``
+ Delete the entire line.
+
+``\\`` (backslash)
+ Quote the next character; the quoted character is inserted literally.
+
+Examples
+========
+
+Use ``cle`` in an application to get interactive line editing:
+
+.. code-block:: c
+
+ #include <system/cle.h>
+ #include <stdio.h>
+
+ int main(void)
+ {
+ char line[128];
+ int len;
+
+ printf("Enter a command: ");
+ len = cle(line, "> ", sizeof(line), stdin, stdout);
+ if (len > 0)
+ {
+ printf("You typed: %s\n", line);
+ }
+
+ return 0;
+ }
+
+Notes
+=====
+
+- ``cle`` requires a VT100-compatible terminal. It uses VT100 escape
+ sequences for cursor movement, line editing, and screen clearing.
+
+- The editor uses a fixed-width character set assumption. Variable-width
+ fonts may cause display issues.
+
+- When ``CONFIG_SYSTEM_CLE_CMD_HISTORY`` is enabled, the history buffer
+ is shared across all threads in FLAT and PROTECTED builds. In KERNEL
+ builds, each process has its own history buffer.
+
+- Memory usage is approximately 1.5–2 KB.
+
+- ``cle`` does not support word-oriented operations (move by word, delete
+ word, etc.) or keypad cursor control.
\ No newline at end of file
