https://github.com/robotdana/tty_string
render strings like a tty
https://github.com/robotdana/tty_string
ansi-colors ansi-escape ansi-escape-codes ansi-escape-sequences ansi-terminal ruby tty
Last synced: 12 days ago
JSON representation
render strings like a tty
- Host: GitHub
- URL: https://github.com/robotdana/tty_string
- Owner: robotdana
- License: mit
- Created: 2019-09-06T15:12:41.000Z (over 5 years ago)
- Default Branch: main
- Last Pushed: 2025-01-25T09:55:14.000Z (3 months ago)
- Last Synced: 2025-03-24T11:38:23.216Z (29 days ago)
- Topics: ansi-colors, ansi-escape, ansi-escape-codes, ansi-escape-sequences, ansi-terminal, ruby, tty
- Language: Ruby
- Size: 102 KB
- Stars: 2
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE.txt
Awesome Lists containing this project
README
# TTYString
[](https://travis-ci.com/robotdana/tty_string)
[](https://rubygems.org/gems/tty_string)
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_=`1` _m_=`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:
```ruby
gem 'tty_string', '~> 1.0'
```
And then execute:
$ bundle
Or install it yourself as:
$ gem install tty_string
## Usage
```ruby
TTYString.parse("th\ta string\e[3Gis is")
=> "this is a string"
```
Styling information is dropped by default:
```ruby
TTYString.parse("th\ta \e[31mstring\e[0m\e[3Gis is")
=> "this is a string"
```
But can be rendered:
```ruby
TTYString.parse("th\ta \e[31mstring\e[0m\e[3Gis is", style: :render)
=> "this is a \e[31mstring\e[0m"
```
```ruby
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:
```ruby
["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](https://opensource.org/licenses/MIT).