Ruby
Latest commit cbc5621 Jan 29, 2017 @piotrmurach committed on GitHub Merge pull request #30 from enderahmetyurt/patch-1
Update README.md

README.md

tty logo


Gem Version Build Status Build status Code Climate Coverage Status Inline docs Gitter

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

Contents

1. Overview

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

To ask for user input use TTY::Prompt:

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:

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:

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

To create a spinner use TTY::Spinner:

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

To colorize your strings use Pastel:

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

To page very long input use TTY::Pager:

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

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

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

To measure screen size use TTY::Screen:

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:

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

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

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

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

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:

  1. Fork it
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. 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.

Copyright

Copyright (c) 2012-2017 Piotr Murach. See LICENSE for further details.