TTYString

Render to a string like your terminal does by (narrowly) parsing ANSI TTY codes. Intended for use in tests of command line interfaces.

Features

• supports ruby 2.4 - 3.0.0.preview1, and jruby
• has no dependencies outside ruby stdlib

Supported codes

Code	Description	Default
\a	bell: suppressed
\b	backspace: clear the character to the left of the cursor and move the cursor back one column
\n	newline: move the cursor to the start of the next line
\r	return: move the cursor to the start of the current line
\t	tab: move the cursor to the next multiple-of-8 column
\e[nA	move the cursor up n lines	n=1
\e[nB	move the cursor down n lines	n=1
\e[nC	move the cursor right n columns	n=1
\e[nD	move the cursor left n columns	n=1
\e[nE	move the cursor down n lines, and to the start of the line	n=1
\e[nF	move the cursor up n lines, and to the start of the line	n=1
\e[nG	move the cursor to column n. 1 is left-most column	n=1
\e[n;mH \e[n;mf	move the cursor to row n, column m. 1;1 is top left corner	n=1m=1
\e[nJ	n=0: clear the screen from the cursor forward n=1: clear the screen from the cursor backward n=2 or n=3: clear the screen	n=0
\e[nK	n=0: clear the line from the cursor forward n=1: clear the line from the cursor backward n=2: clear the line	n=0
\e[nS	scroll up n rows	n=1
\e[nT	scroll down n rows	n=1
\e[m	styling codes: dropped with style: :drop (default), rendered with style: :render.
\e[?5h	reverse the screen: dropped
\e[?5l	normal the screen: dropped
\e[?25h	show the cursor: dropped
\e[?25l	hide the cursor: dropped
\e[?1004h	enable reporting focus: dropped
\e[?1004l	disable reporting focus: dropped
\e[?1049h	enable alternate screen buffer: dropped
\e[?1049l	disable alternate screen buffer: dropped
\e[?2004h	enable bracketed paste mode: dropped
\e[?2004l	disable bracketed paste mode: dropped
\e[200~	bracketed paste start: dropped
\e[201~	bracketed paste end: dropped
\e[	any other valid CSI code: dropped with unknown: :drop (default), raises TTYString::Error with unknown: :raise.

Installation

Add this line to your application's Gemfile:

gem'tty_string','~> 1.0'

And then execute:

$ bundle

Or install it yourself as:

$ gem install tty_string

Usage

TTYString.parse("th\ta string\e[3Gis is")=>"this is a string"

Styling information is dropped by default:

TTYString.parse("th\ta \e[31mstring\e[0m\e[3Gis is")=>"this is a string"

But can be rendered:

TTYString.parse("th\ta \e[31mstring\e[0m\e[3Gis is",style: :render)=>"this is a \e[31mstring\e[0m"

TTYString.parse("th\ta \e[31mstring\e[0m\e[3Gis is",style: :render)=>"this is a \e[31mstring\e[0m"

Just for fun TTYString.to_proc provides the parse method as a lambda, so:

["th\ta string\e[3Gis is"].each(&TTYString)=>["this is a string"]

Limitations

• Various terminals are wildly variously permissive with what they accept, so this doesn't even try to cover all possible cases

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake to run the tests and linters. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/robotdana/tty_string.

License

The gem is available as open source under the terms of the MIT License.