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.
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.
- 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.
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
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 cliappand then to add more commands:
$ teletype add configThe 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 --helpExecute teletype to see all available tasks.
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 bsd3Once application has been initialized, you can create additional command by using teletype add [command-name] task:
$ teletype add config
$ teletype add createThis will add create.rb and config.rb commands to the CLI client:
▾ app/
├── ▾ commands/
│ ├── config.rb
│ └── create.rb
├── cli.rb
└── version.rbThen you will be able to call the new commands like so:
$ app config
$ app createThe 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
After using the teletype add config command the following strcuture will be created.
▾ app/
├── ▾ commands/
│ └── config.rb
├── cli.rb
└── version.rbThe 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
endAnd 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
endFlags and optiosn allow to customize how particular command is invoked and provide additional configuration.
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 |
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.
Copyright (c) 2012-2017 Piotr Murach. See LICENSE.txt for further details.