TTY is a toolbox for developing beautiful command line clients in Ruby. It provides a fluid interface for gathering input from the user, querying system and terminal and displaying information back. It is not another command line options parser, rather a plumbing library that helps in common tasks.

Motivation

All too often libraries that interact with command line create their own interface logic that gathers input from users and displays information back. Many times utility files are created that contain methods for reading system or terminal properties. Shouldn’t we focus our energy on building the actual client?

Even more so, any command line application needs a clear way of communicating its results back to terminal whether in tabular form, column form or colorfully indented text. Our time and energy should be spent in creating the tools not the foundation.

Features

Jump-start development of your command line app the Unix way.
Fully modular, choose out of many components to suit your needs.
All tty components are small packages that do one thing well.
Fully tested with major ruby interpreters.

Installation

Add this line to your application’s Gemfile to install all components:

gem 'tty'

or install a particular component:

gem 'tty-*'

And then execute:

$ bundle

Or install it yourself as:

$ gem install tty

1. Overview
2. Components

1. Overview

TTY provides you with many tools to get the job done in terminal.

To ask for user input use TTY::Prompt:

```ruby require ‘tty’

prompt = TTY::Prompt.new prompt.yes?(‘Do you like Ruby?’) # => Do you like Ruby? (Y/n)

or ask to select from list

prompt.select(“Choose your destiny?”, %w(Scorpion Kano Jax)) # => # Choose your destiny? (Use arrow keys, press Enter to select) # ‣ Scorpion # Kano # Jax ```

To print tabular output use TTY::Table:

ruby table = TTY::Table[['a1', 'a2', 'a3'], ['b1', 'b2', 'b3']] table.to_s # => a1 a2 a3 b1 b2 b3

To create a progress bar use TTY::ProgressBar:

ruby bar = TTY::ProgressBar.new("downloading [:bar]", total: 30) 30.times { bar.advance }

To create a spinner use TTY::Spinner:

ruby spinner = TTY::Spinner.new('Loading ... ', format: :spin_2) 30.times { spinner.spin }

To colorize your strings use Pastel:

ruby pastel = Pastel.new pastel.green.on_red.bold('Piotr')

To page very long input use TTY::Pager:

ruby pager = TTY::Pager.new pager.page('Very long text...')

To run external commands with output logging, capturing stdout and stderr use TTY::Command:

ruby cmd = TTY::Command.new out, err = cmd.run('cat ~/.bashrc | grep alias')

To measure screen size use TTY::Screen:

ruby screen = TTY::Screen.new screen.size # => [51, 280] screen.width # => 280 screen.height # => 51

TTY::Color allows you to check if terminal supports color and the color mode:

ruby TTY::Color.supports? # => true TTY::Color.mode # => 64

For instance, to find out if less utility is actually supported by the system do:

ruby TTY::Which.which('less') # => '/usr/bin/less'

To move cursor around the terminal use TTY::Cursor:

ruby cursor = TTY::Cursor print cursor.up(5) + cursor.forward(2)

2. Components

Component	Description	API docs
pastel	Terminal strings styling with intuitive and clean API.	docs
tty-color	Terminal color capabilities detection.	docs
tty-command	Execute shell commands with pretty logging and capture stdout, stderr and exit status.	docs
tty-cursor	Move terminal cursor around.	docs
tty-editor	Open a file or text in the user preferred editor.	docs
tty-file	File manipulation utility methods.	docs
tty-pager	Terminal output paging in a cross-platform way.	docs
tty-platform	Detecting different operating systems.	docs
tty-progressbar	A flexible progress bars drawing in terminal emulators.	docs
tty-prompt	A beautiful and powerful interactive command line prompt.	docs
tty-screen	Terminal screen properties detection.	docs
tty-spinner	A terminal spinner for tasks with non-deterministic time.	docs
tty-table	A flexible and intuitive table output generator.	docs
tty-which	Platform independent implementation of Unix which command.	docs

Contributing

You can contribute by posting feature requests, evaluating the APIs or simply by hacking on TTY components:

Fork it
Create your feature branch (git checkout -b my-new-feature)
Commit your changes (git commit -am 'Add some feature')
Push to the branch (git push origin my-new-feature)
Create new Pull Request

This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.