hasanen / tty

Toolbox for developing CLI clients.

TTY is a toolbox for developing beautiful command line clients in Ruby with a fluid interface for gathering input, querying terminal properties and displaying information.

Motivation

All too often libraries that interact with terminals 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?

Building terminal tools takes time. I believe that modular components put together in a single package with project scaffolding will help people build things faster and produce higher quality results. It is easy to jump start a new project with available scaffolding and mix and match components to create new tooling.

Features

• Jump-start development of your command line app the Unix way with scaffold provided by teletype.
• Fully modular, choose out of many components to suit your needs or use any 3rd party ones.
• 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
• 2. Bootstrapping
  • 2.1 new command
    • 2.1.1 --license, -l flag
  • 2.2 add command
  • 2.3 working with commands
  • 2.4 working with flags
• 3. Components

1. Overview

TTY provides you with many tasks and components to get you onto the path of bulding awesome terminal applications.

To simply jump start a new command line application use teletype executable:

$ teletype new cliapp

and then to add more commands:

$ teletype add config

2. Bootstrapping

2.1 new command

The teletype new [app-name] command will create a brand new application. This tasks will bootstrap an entire project file structure. The project structure is based on the bundler gem command with additional files and folders.

To create a new command line application use the new task with the application's name as a first argument:

$ teletype new [app-name]

The output will contain all the files that have been created similar to bundler output:

Creating gem 'app'
    create app/Gemfile
    create app/.gitignore
    create app/lib/app.rb
    create app/lib/app/version.rb
    ...

This will generate the following structure familiar to anyone who has created a gem beforehand:

▾ app/
├── ▾ exe/
│   └── app
├── ▾ lib/
│   ├── ▾ app/
│   │   ├── cli.rb
│   │   └── version.rb
│   └── app.rb
├── CODE_OF_CONDUCT.md
├── Gemfile
├── LICENSE.txt
├── README.md
├── Rakefile
└── app.gemspec

Run the new command with --help flag to see all available options:

$ teletype new --help

Execute teletype to see all available tasks.

2.1.1 --license, -l flag

The teletype generator comes prepackaged with most popular open source licenses: agplv3, apache, bsd2, bsd3, gplv2, gplv3, lgplv3, mit, mplv2, custom. By default the mit license is used. To change that do:

$ teletype new app --license bsd3

2.2 add command

Once application has been initialized, you can create additional command by using teletype add [command-name] task:

$ teletype add config
$ teletype add create

This will add create.rb and config.rb commands to the CLI client:

▾ app/
├── ▾ commands/
│   ├── config.rb
│   └── create.rb
├── cli.rb
└── version.rb

Then you will be able to call the new commands like so:

$ app config
$ app create

The commands require you to specify the actual logic in their execute methods.

Please note that command names should be provided as camelCase or snake_case. For example:

$ teletype add addConfigCommand   # => correct
$ teletype add add_config_command # => correct
$ teletype add add-config-command # => incorrect

2.3 working with commands

After using the teletype add config command the following strcuture will be created.

▾ app/
├── ▾ commands/
│   └── config.rb
├── cli.rb
└── version.rb

The lib/app/cli.rb file will contain generated command entry:

desc 'config', 'Command description...'
def config(*)
  if options[:help]
    invoke :help, ['config']
  else
    require_relative 'commands/config'
    App::Commands::Config.new(options).execute
  end
end

And the commands/config.rb will allow you to specify all the command logic in execute call:

module App
  module Commands
    class Config < App::Cmd
      def initialize(options)
        @options = options
      end

      def execute
        # Command logic goes here ...
      end
    end
  end
end

2.4 Working with flags

Flags and optiosn allow to customize how particular command is invoked and provide additional configuration.

3. Components

The TTY allows you to mix & match any components you need to get your job done. The command line applications generated with teletype executable references all of the below 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-reader	A set of methods for processing keyboard input in character, line and multiline modes.	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-tree	Print directory or structured data in a tree like format.	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.txt for further details.