dimmykar/microrl-remaster

Micro Read Line library for small and embedded devices [REMASTER]

Micro Read Line library for small and embedded devices with basic VT100 support

This library is a remaster of the microrl library, which author stopped its development in 2017.

Description

Microrl library is designed to help implement command line interface in small and embedded devices. Main goal is to write compact, small memory consuming but powerful interfaces, with support navigation through command line with cursor, HOME, END keys, hot key like Ctrl+U and other, history and completion feature.

Features

• microrl_config.h and microrl_user_config.h files

  • Turn on/off feature for add functional/decrease memory via config files.

• Pass the pointer to microrl_t to all callbacks so that the operations can be specific to a particular instance of microrl

• Hot keys support

  • Backspace, cursor arrows, HOME, END keys
  • Ctrl+U (cut line from cursor to begin)
  • Ctrl+K (cut line from cursor to end)
  • Ctrl+A (like HOME)
  • Ctrl+E (like END)
  • Ctrl+H (like backspace)
  • Ctrl+D (delete one character forward)
  • Ctrl+B (like cursor arrow left)
  • Ctrl+F (like cursor arrow right)
  • Ctrl+P (like cursor arrow up)
  • Ctrl+N (like cursor arrow down)
  • Ctrl+R (retype prompt and partial command)
  • Ctrl+C (call sigint() callback, only for embedded system)

• History (optional)

  • Static ring buffer history for memory saving. Number of commands saved to history depends from commands length and buffer size (defined in config)

• Completion (optional)

  • Command completion via completion callback

• Quoting (optional)

  • Use single ' or double " quotes around a command argument that needs to include space characters

• Echo control (optional)

  • Use microrl_set_echo() function to turn on or turn off echo
  • Could be used to print * or other specified character insted of real characters to mask secret input like passwords

Source code organization

src/                             - library sources
src/microrl
  microrl.c                      - microrl routines
src/include/microrl
  microrl.h                      - lib interface and data type
  microrl_config.h               - file with default configs
  microrl_user_config_template.h - customisation config-file template
examples/                        - library usage examples
  avr_misc/                      - avr specific routines for avr example
  esp8266_example/               - esp8266 (platformio) example with echo off feature
  stm32_example/                 - stm32 (STM32CubeIDE) example with full library functionality
  unix_misc/                     - unix specific routines for desktop example
  example.c                      - common part of example, for build demonstrating example for various platform
  example_misc.h                 - interface to platform specific routines for example build (avr, unix, stm32, esp8266)
  Makefile                       - unix example build (gcc)
  Makefile.avr                   - avr example build (avr-gcc)

Install

Requirements: C compiler with support for C99 standard (GNU GCC, Keil, IAR) with standard C library (libc, uClibc or other compatible). Also you have to implement several routines in your own code for library to work.

NOTE: need add -std=gnu99 arg for gcc

For embed lib to you project, you need to do few simple steps:

a) Include microrl.h file to you project.

b) Create microrl_t object, and call microrl_init() func, with print callback pointer and your routine callback pointer, that will be called if user press Enter in terminal.
Print callback pointer is pointer to function that call by library if it's need to put text to terminal. Text string always is null terminated. For example on linux PC print callback may be:

/* Print callback for microrl library */
int print(microrl_t* mrl, char* str) {
    return fprintf(stdout, "%s", str);
}

Execute callback pointer give a argc, argv parametrs, like main() func in application. All token in argv is null terminated. So you can simply walk through argv and handle commands.

c) If you want completion support if user press TAB key, call microrl_set_complete_callback() and set you callback. It also give argc and argv arguments, so iterate through it and return set of complete variants.

d) Rename microrl_user_config_template.h to microrl_user_config.h. Look at microrl_config.h file and tune library in microrl_user_config.h. To do this, copy the default configs from microrl_config.h to microrl_user_config.h and change them for you requiring. Then replace microrl_user_config.h to libraries confuguration folder of your project.

e) Now you just call microrl_processing_input() on each input string (or one char) received from input stream (usart, network, etc).

Example of code:

int main (int argc, char** argv) {
    /* Create microrl instance */
    microrl_t rl;

    /* Initialize library with microrl instance and print and execute callbacks */
    microrl_init(&rl, print, execute);

    /* Set callback for completion (optionally) */
    microrl_set_complete_callback(&rl, complet);

    /* Set callback for Ctrl+C handling (optionally) */
    microrl_set_sigint_callback(&rl, sigint);
    
    while (1) {
        /* Put received char from stdin to microrl instance */
        char ch = get_char();
        microrl_processing_input(&rl, &ch, 1);
    }

    return 0;
}

See examples of library usage.

Author: Eugene Samoylov aka Helius ([email protected])
01.09.2011

Remastered by: Dmitry Karasev aka dimmykar ([email protected])
27.09.2021

microrl-remaster's Issues

A small bug and some warnings while compiling

Hi,
here are some small comments about microrl.
I'm in the process of testing your lib with a test project because it seems like exactly what I need.

---

microrl is not compiling because size_t is not defined.
Simple fix: add #include <stdlib.h> to line 33.

In some of my projects, I'm required to compile with warning levels.
Here are some of my finding:

../App/Lib/microrl.c:166:44: warning: comparison of integer expressions of different signedness: 'int' and 'size_t' {aka 'unsigned int'} [-Wsign-compare]
  166 |                 if (!((str - mrl->cmdline) < limit)) {
      |                                            ^
../App/Lib/microrl.c:371:20: warning: comparison of integer expressions of different signedness: 'size_t' {aka 'unsigned int'} and 'int32_t' {aka 'long int'} [-Wsign-compare]
  371 |         *j++ = ((i >= mrl->echo_off_pos) && (mrl->echo != MICRORL_ECHO_ON)) ? '*' : mrl->cmdline[i];
      |                    ^~
../App/Lib/microrl.c:372:23: warning: comparison of integer expressions of different signedness: 'int' and 'size_t' {aka 'unsigned int'} [-Wsign-compare]
  372 |         if ((j - str) == strlen(str)) {
      |                       ^~
../App/Lib/microrl.c:379:31: warning: comparison of integer expressions of different signedness: 'int' and 'unsigned int' [-Wsign-compare]
  379 |     if ((j - str + 3 + 6 + 1) > MICRORL_ARRAYSIZE(str)) {
      |                               ^
../App/Lib/microrl.c: In function 'microrl_processing_input':
../App/Lib/microrl.c:1017:46: warning: comparison of integer expressions of different signedness: 'size_t' {aka 'unsigned int'} and 'int32_t' {aka 'long int'} [-Wsign-compare]
 1017 |                             if ((mrl->cursor >= mrl->echo_off_pos) && (mrl->echo != MICRORL_ECHO_ON)) {

If you want to reproduce, you can add the following in your makefile

CCFLAGS   = -Wall $(DEBUG) -Wextra -pedantic -std=gnu99 -I../src/include/microrl -I../examples -iquote unix_misc

Thanks for your work!
Very interesting and useful project.

Quality of Life Improvement

Hi, I was wondering how impactful to code, as a whole, would changing the execute function to a list of callbacks per command.
Or have a different configuration mode to do that.

I successfully did that to my own clone of your repo. This way I can more easily setup a new shell for anything I want and without having to worry about determining the validity of the command in each instance I use MicroRL.

What do you think?

Also, how do I properly document my changes to the code, so I can publicly host them on GitHub? I had to really refactor the whole file structure. Its a mess.

Control Signal field in mircrol_t

I think it would be very useful to have a more generic option to act on any control signal.

For me, I have it set so that can catch ^W to change my execute function back to the original execute function with out having to change any hardware data streams (uart). That is, I have access to all the nice stuff of typing into a command line while not having to muck around with updating my hardware input, if that makes sense.

The change would be here prv_control_char_process where you just set the signal value of mrl to ch and call the signal interrupt function provided by the user, which can have its own switch case to determine what to do.

I hope this makes sense to you. And I could just put in my own branch, but I think it should be here as well.

Fix cmdline reset by cursor UP/DOWN key

History navigation resets the command line content, even if the history is empty or cursor DOWN key is pressed when the command is typing

microrl drop argument when using multiple spaces in command

When entering a command with two spaces between the arguments, microrl drops the second argument.

For example, the input 123 456.

In the debugger, you can see that argc is 2, but argv only includes the first arguments.

argv is still a valid string, but if you rely on argc to be correct, it could be a problem.

Compilation error when MICRORL_CFG_USE_ECHO_OFF=0

Some vars and definitions are still in use when option is set MICRORL_CFG_USE_ECHO_OFF=0 (Release 2.4.0)

microrl.c:748:12: error: 'microrl_t' {aka 'struct microrl'} has no member named 'echo'
microrl.c:748:22: error: 'MICRORL_ECHO_ON' undeclared (first use in this function); did you mean 'MICRORL_ESC_END'?

btw, ECHO_OFF=0 is default fallback setting if not configured in user headers