Readme for Linecook

1. What is Linecook?
2. Why does Linecook exist?
3. How do you build/install Linecook?
4. What editing commands exist in Linecook?

What is Linecook?

Linecook is a C library for editing the command line, much like the readline library used in bash and gdb.

An example of a Read Eval Print Loop (REPL) using Linecook looks like this:

printf( "simple echo test, type 'q' to quit\n" );
for (;;) {
  int n = lc_tty_get_line( tty ); /* retry line and run timed events */
  if ( n == 0 )
    n = lc_tty_poll_wait( tty, 60000 ); /* wait at most 60 seconds */
  if ( n < 0 ) /* if error in one of the above */
    break;
  if ( tty->lc_status == LINE_STATUS_EXEC ) { /* if there is one available */
    lc_tty_normal_mode( tty );     /* set terminal to normal mode */
    printf( "[%s]\n", tty->line ); /* which translates \n to \r\n */
    if ( tty->line_len == 1 && tty->line[ 0 ] == 'q' ) /* type 'q' to quit */
      break;
    lc_tty_log_history( tty );
  }
}

Credits, inspiration

Some people and projects that inspired this library:

1. Salvatore Sanfilippo for linenoise. I started with this library. I believe it is not possible, 20,000 lines are necessary :).

2. Bob Steagall for UTF-32. Easy to follow, problem solving with SSE (even though I didn't use that part).

3. Joshua Rubin for wcwidth9. He pointed me in the correct direction, double width chars was not something I thought about.

4. The awesome Fish shell. I think it sets the bar for command line shell integration.

5. The ubiquitous Bash/readline. It is the reason that we have command line editing in everything.

6. The es-shell. I am using this shell at the moment, with Linecook integration, in desh. This still needs some work and baking.

Why does Linecook exist?

There are many programs that come with command line editing and some libraries which implement these features, but I could not find one that fit my needs.

1. Asynchronous. Network ready.

Linecook does not presume input comes from a terminal. My plan is to use it as a backend for a web based console using xterm.js. The only example of something similar is DomTerm (AFAIK).

2. Vi Mode input.

Most of the libraries I found were oriented towards completion and hinting with a Emacs style editing base. Examples of these are Linenoise, Linenoise NG, replxx. These are all fine libraries with nice features. I also tried the line editing within these shells zsh, fish, elvish. They all have very nice features as well as Vi mode (in Zsh and Fish cases), although the line editing within shells tends to be integrated tightly with the shell language... completions call out to shell scripts, etc.

3. BSD License.

Readline is GPL licensed rather than LGPL. This means anything linked with must also be released with a GPL license. This is the reason that rlwrap exists.

What platforms does Linecook support?

Linux. With C11 for Unicode char32_t support (from 2012 -- glibc 2.16)

What features does Linecook have?

Linecook aims to be a readline replacement.

I am a lifelong user of the bash shell mainly because of readline. I have also used readline in previous projects. It has a large feature set and it is highly configurable. Most of the readline editing commands are supported in Linecook, but it is not API compatible. Whenever I was adding an feature I would always try it in bash first, to see how it works there. The history operations is slightly different, but most other things operate as the would in readline. Most of my experience within bash is in Vi mode using set -o vi. Many of the Emacs commands I learned as I coded them. I have only used emacs from time to time, and use vim nearly daily.

Visual Select editing

The Visual Select method of editing text in vim exists in Linecook as 'ctrl-v' in Emacs or Vi Insert mode, and 'v' in Vi Command mode. This is the vim feature that I miss most within readline. The fish shell also has this now.

Combined Vi and Emacs modes (EVIL mode)

Unlike readline and like Emacs EVIL mode (I presume), most all of Emacs mode is available within Vi Insert mode. The only difference between Emacs and Vi mode is that the 'esc' key can be used as a 'meta-' (or 'alt-') substitute, whereas in Vi mode, that toggles between Vi Insert and Vi Command. Still, Emacs mode can be useful when the window manager or terminal multiplexer steals 'alt-' keycodes for it's own use. The default mode in Linecook is Vi Insert mode and 'meta-m' switches between Vi mode and Emacs mode (and 'meta-' is really emacs notation for 'alt-', there was a time keyboards actually had a meta key).

History Searching

The history is searched as in readline Vi mode, with '/' and '?' in Vi Command mode. The 'ctrl-r' and 'ctrl-s' which normally map to Emacs mode "reverse-i-search" and "i-search", map to '/' and '?' in Linecook instead. The "reverse-i-search" method of history search does not currently exist. That may change in the future, since the "i-search" does have completion properties that '/' does not. There is no builtin handling of history expansion, ex: '!!', '!-1', '!cp:^'. This is also on the todo list.

TAB Completions

The method for TAB completions is also different than readline. Unlike readline Linecook allows completion selection like fish and zsh. Completion selection uses the TAB key to cycle through alternatives and movement (ctrl-n, ctrl-p, arrow keys) to move a selection cursor over the desired completion string.

UTF-32 Unicode

Internally, Unicode is supported as UTF-32, so each character in memory is a 32 bit character, using the type char32_t. Externally, the characters are converted to UTF-8. Any I/O that occurs causes UTF-32 to UTF-8 translation. Double-wide characters, such as Han or Kanji characters, and Emoji symbols are supported. The code that determines whether a character is double wide is commonly derived by Linecook and many other applications, from wcwidth.c by Markus Kuhn.

ANSI Terminal Management

All screen movements that manage the layout of screen elements are using this minimal set of ANSI control codes:

1. EL (Erase Line) ESC [ n K -- erase to EOL (n=0), erase to BOL (n=1), erase line (n=2)

2. CUF (Cursor Foward) ESC [ n C -- move forward 'n' characters.

3. CUB (Cursor Backward) ESC [ n D -- move backward 'n' characters.

4. CUU (Cursor Up) ESC [ n A -- move cursor up 'n' characters.

5. CUD (Cursor Down) ESC [ n B -- move cursor down 'n' characters.

Color control sequences are parsed and passed through to the terminal. Nearly every terminal shares these control codes, going back to VT100. Most terminals within a modern Linux distribution support Color control sequences these days and newer Font libraries such as Nerd Fonts also support Emoji codes.

How do you build/install Linecook?

Install these and type make.

$ sudo dnf install make gcc-c++ chrpath pcre2-devel rpm-build

Or

$ sudo apt-get install make g++ gcc chrpath libpcre2-dev devscripts debhelper

The build directory is created and populated by the build in OS_rel_cpu/{bin,lib64,obj,dep}. If you wish to install it, there is an 'dist_rpm' target for RedHat like systems. This requires the rpm-build package to be installed.

$ make dist_rpm

# Install

$ sudo rpm -i rpmbuild/RPMS/x86_64/linecook-1.1.0-14.fc27.x86_64.rpm

For Debian style, do this instead.

$ make dist_dpkg

$ sudp dpkg -i dpkgbuild/linecook_1.1.0-14_amd64.deb

For rpms, the prefix option works, as in --prefix=/opt/rai

$ sudo rpm --prefix=/opt/rai -i rpmbuild/RPMS/x86_64/linecook-1.0.0-1.fc27.x86_64.rpm
$ rpm -ql linecook
/opt/rai/bin/lc_example
/opt/rai/include/linecook
/opt/rai/include/linecook/kewb_utf.h
/opt/rai/include/linecook/keycook.h
/opt/rai/include/linecook/linecook.h
/opt/rai/include/linecook/ttycook.h
/opt/rai/include/linecook/xwcwidth9.h
/opt/rai/lib/.build-id
/opt/rai/lib/.build-id/4f
/opt/rai/lib/.build-id/4f/1519b3809a3afdfbdeceb9badceb3e3620afcb
/opt/rai/lib/.build-id/62
/opt/rai/lib/.build-id/62/20397653a6db5da601b7920be7b395ba8860d7
/opt/rai/lib64/liblinecook.a
/opt/rai/lib64/liblinecook.so
/opt/rai/lib64/liblinecook.so.1.1
/opt/rai/lib64/liblinecook.so.1.1.0-14

Optionally install debuginfo and debugsource for gdb.

$ sudo rpm -i rpmbuild/RPMS/x86_64/linecook-debugsource-1.0.0-1.fc27.x86_64.rpm
$ sudo rpm -i rpmbuild/RPMS/x86_64/linecook-debuginfo-1.0.0-1.fc27.x86_64.rpm

Removing the packages from the system.

$ sudo rpm -e linecook linecook-debugsource linecook-debuginfo

What editing commands exist in Linecook?

This list is generated by 'print_keys' in the build. It shows the builtin mapping of keystroke sequence to commands that is compiled into the library. This is a table, but it is not currently file loadable as would be necessary for runtime configuration (todo).

There are 5 modal states which have keybindings. These are:

1. E = Emacs mode.

This mode is the same as Vi Insert mode, except that 'esc' is a 'meta-' prefix rather than a switch between Vi Insert and Vi Command mode.

2. I = Vi Insert mode.

Text is inserted or replaced as chars are entered. Most all of the control keys and meta keys have functions that map to (mostly) Emacs commands.

3. C = Vi Command mode.

All keys are Vi commands. Movement, Editing, Yanking, Pasting, etc.

4. S = History Search mode.

The search text is manipulated.

5. V = Visual Select mode.

The movement keys are used to control the area that surrounds the text which is yanked or deleted.

This is table that is loaded at startup in keycook.cpp.