Espressif ESP32-S2 Programming Manual page 809

Chapter 2. API Reference
Line editing
Line editing feature lets users compose commands by typing them, erasing symbols using 'backspace'key, navi-
gating within the command using left/right keys, navigating to previously typed commands using up/down keys, and
performing autocompletion using 'tab'key.
Note: This feature relies on ANSI escape sequence support in the terminal application. As such, serial monitors
which display raw UART data can not be used together with the line editing library. If you see [6n or similar escape
sequence when running system/console
monitor does not support escape sequences. Programs which are known to work are GNU screen, minicom, and
idf_monitor.py (which can be invoked using idf.py monitor from project directory).
Here is an overview of functions provided by
Configuration Linenoise library does not need explicit initialization. However, some configuration defaults may
need to be changed before invoking the main line editing function.
linenoiseClearScreen() Clear terminal screen using an escape sequence and position the cursor at the top
left corner.
linenoiseSetMultiLine() Switch between single line and multi line editing modes. In single line mode, if
the length of the command exceeds the width of the terminal, the command text is scrolled within the line to
show the end of the text. In this case the beginning of the text is hidden. Single line needs less data to be sent
to refresh screen on each key press, so exhibits less glitching compared to the multi line mode. On the flip side,
editing commands and copying command text from terminal in single line mode is harder. Default is single
line mode.
linenoiseAllowEmpty() Set whether linenoise library will return a zero-length string (if true) or NULL (if
false) for empty lines. By default, zero-length strings are returned.
linenoiseSetMaxLineLen() Set maximum length of the line for linenoise library. Default length is 4096.
If you need optimize RAM memory usage, you can do it by this function by setting a value less than default
4kB.
Main loop
linenoise() In most cases, console applications have some form of read/eval loop. linenoise() is the single
function which handles user's key presses and returns completed line once 'enter'key is pressed. As such,
it handles the 'read'part of the loop.
linenoiseFree() This function must be called to release the command line buffer obtained from
linenoise() function.
Hints and completions
linenoiseSetCompletionCallback() When user presses'tab' key, linenoise library invokes completion
callback. The callback should inspect the contents of the command typed so far and provide a list of possible
completions using calls to linenoiseAddCompletion() function. linenoiseSetCompletion-
Callback() function should be called to register this completion callback, if completion feature is desired.
console component provides a ready made function to provide completions for registered commands,
esp_console_get_completion()
linenoiseAddCompletion() Function to be called by completion callback to inform the library about pos-
sible completions of the currently typed command.
linenoiseSetHintsCallback() Whenever user input changes, linenoise invokes hints callback. This call-
back can inspect the command line typed so far, and provide a string with hints (which can include list of
command arguments, for example). The library then displays the hint text on the same line where editing
happens, possibly with a different color.
linenoiseSetFreeHintsCallback() If hint string returned by hints callback is dynamically allocated
or needs to be otherwise recycled, the function which performs such cleanup should be registered via
linenoiseSetFreeHintsCallback().
Espressif Systems
example instead of a command prompt (e.g. esp> ), it means that the serial
linenoise library.
(see below).
798
Submit Document Feedback
Release v4.4