tty 0.7.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 45114097bee0b394b6ed154cffaadbf5611a1049
-  data.tar.gz: 718b5f44f5390caff017ae31acf186c99bb5e5c4
+  metadata.gz: fadf60f672e1f406309e7a026b181e0672b104a3
+  data.tar.gz: 5052f53049b8d32d32b8e17cd0d46a55815ed3f2
 SHA512:
-  metadata.gz: 3769ed6a9226548f2c18398d9942d8886c547fc50cc3a6e00d066f548b5341da67d039c1b466a9699d0feeefd76807c43b8f3dc5dec44c8198345a51c175ae6e
-  data.tar.gz: e751e71398166c48c5de6f6d31f3f53049dc93d44f54a9f6ff3090c8416b950352e1ea3b7476f8776a8f7e9435a7258ae4bf951cf2cdd886ae0d00a8ea827139
+  metadata.gz: 55da8f56e48079e9b195dd1c0bf3f45e8ab5e3ba449a4723075463e3761124c78b880607a93acd6cac2254925765926d0e168c0a43d0030a8c29c1bf57fcee69
+  data.tar.gz: 6d0f13a347de0903b1940dd6e75f4e3431b22075dd8002ca8d98c3faac7285c4b0f60183f53ecc33c07155b6c3c6d770b8f40a06c01ef0724d1f8b33ccc2e921

data/.rspec

@@ -1,4 +1,4 @@
 --color
---format progress
+--require spec_helper
+--format documentation
 --order random
---warnings

data/.travis.yml

@@ -1,15 +1,25 @@
 ---
+env:
+  global:
+    - CC_TEST_REPORTER_ID=76c3cb8a84b67e1e18aadacbe5a77861bc723dc1448f044bae995795b261569b
 language: ruby
 sudo: false
-cache: bundler
 bundler_args: --without yard guard benchmarks
+before_install: "gem install bundler -v 1.16.0"
+before_script:
+   - curl -L https://codeclimate.com/downloads/test-reporter/test-reporter-latest-linux-amd64 > ./cc-test-reporter
+   - chmod +x ./cc-test-reporter
+   - ./cc-test-reporter before-build
 script: "bundle exec rake ci"
+after_script:
+  - ./cc-test-reporter after-build --exit-code $TRAVIS_TEST_RESULT
 rvm:
   - 2.0.0
   - 2.1.10
-  - 2.2.6
-  - 2.3.3
-  - 2.4.0
+  - 2.2.8
+  - 2.3.6
+  - 2.4.3
+  - 2.5.0
   - ruby-head
   - jruby-9000
   - jruby-head
@@ -17,6 +27,7 @@ matrix:
   allow_failures:
     - rvm: ruby-head
     - rvm: jruby-head
+    - rvm: jruby-9000
   fast_finish: true
 branches:
   only: master

data/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Change log
 
+This file documents notable changes in reverse chronological order.
+
+## [v0.8.0] - 2018-05-31
+
+### Added
+* Add teletype executable for jump starting new CLI apps
+* Add TTY::CLI for scaffolding new console applications
+* Add Commands::New for generating new command line applications
+* Add Commands::Add for adding new commands & subcommands
+* Add Plugins#load_from to allow loading dependencies from gemspec
+* Add tty-tree component
+* Add tty-markdown component
+* Add tty-font component
+* Add tty-config component
+
+### Changed
+* Remove Plugins#find
+* Change Plugins#load to Plugins#activate
+* Remove metrics rake tasks
+* Update dependencies
+
 ## [v0.7.0] - 2017-03-26
 
 ### Changed
@@ -122,6 +143,7 @@
 
 * Initial release
 
+[v0.8.0]: https://github.com/piotrmurach/tty/compare/v0.7.0...v0.8.0
 [v0.7.0]: https://github.com/piotrmurach/tty/compare/v0.6.1...v0.7.0
 [v0.6.1]: https://github.com/piotrmurach/tty/compare/v0.6.0...v0.6.1
 [v0.6.0]: https://github.com/piotrmurach/tty/compare/v0.5.0...v0.6.0

data/Gemfile

@@ -3,18 +3,15 @@ source 'https://rubygems.org'
 gemspec
 
 group :development do
-  gem 'rspec',   '~> 3.5.0'
-  gem 'yard',    '~> 0.8.7'
-  gem 'timecop', '~> 0.7.1'
+  gem 'yard',    '~> 0.9.12'
+  gem 'timecop', '~> 0.9.1'
 end
 
 group :metrics do
-  gem 'coveralls', '~> 0.8.1'
-  gem 'simplecov', '~> 0.10.0'
+  gem 'simplecov', '~> 0.16.1'
   gem 'yardstick', '~> 0.9.9'
-  gem 'term-ansicolor', '=1.3.2'
 end
 
 group :benchmarks do
-  gem 'benchmark_suite', '~> 1.0.0'
+  gem 'benchmark-ips', '~> 2.7.2'
 end

data/README.md

@@ -6,31 +6,31 @@
 [![Gem Version](https://badge.fury.io/rb/tty.svg)][gem]
 [![Build Status](https://secure.travis-ci.org/piotrmurach/tty.svg?branch=master)][travis]
 [![Build status](https://ci.appveyor.com/api/projects/status/0a85w6yr40lmuo3o?svg=true)][appveyor]
-[![Code Climate](https://codeclimate.com/github/piotrmurach/tty/badges/gpa.svg)][codeclimate]
-[![Coverage Status](https://coveralls.io/repos/piotrmurach/tty/badge.svg?branch=master)][coveralls]
+[![Maintainability](https://api.codeclimate.com/v1/badges/b7656caaf3bdb1fd4c04/maintainability)][codeclimate]
+[![Test Coverage](https://api.codeclimate.com/v1/badges/b7656caaf3bdb1fd4c04/test_coverage)][coverage]
 [![Inline docs](http://inch-ci.org/github/piotrmurach/tty.svg?branch=master)][inchpages]
 [![Gitter](https://badges.gitter.im/Join%20Chat.svg)][gitter]
 
 [gem]: http://badge.fury.io/rb/tty
 [travis]: http://travis-ci.org/piotrmurach/tty
 [appveyor]: https://ci.appveyor.com/project/piotrmurach/tty
-[codeclimate]: https://codeclimate.com/github/piotrmurach/tty
-[coveralls]: https://coveralls.io/r/piotrmurach/tty
+[codeclimate]: https://codeclimate.com/github/piotrmurach/tty/maintainability
+[coverage]: https://codeclimate.com/github/piotrmurach/tty/test_coverage
 [inchpages]: http://inch-ci.org/github/piotrmurach/tty
 [gitter]: https://gitter.im/piotrmurach/tty
 
-> 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.
+> 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 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?
+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?
 
-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.
+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.
-* Fully modular, choose out of many [components](#2-components) to suit your needs.
+* Jump-start development of your command line app the Unix way with scaffold provided by [teletype](#2-bootstrapping).
+* Fully modular, choose out of many [components](#3-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.
 
@@ -55,105 +55,691 @@ Or install it yourself as:
 ## Contents
 
 * [1. Overview](#1-overview)
-* [2. Components](#2-components)
+* [2. Bootstrapping](#2-bootstrapping)
+  * [2.1 new command](#21-new-command)
+    * [2.1.1 --author, -a flag](#211---author--a-flag)
+    * [2.1.2 --ext flag](#212---ext-flag)
+    * [2.1.3 --license, -l flag](#213---license--l-flag)
+    * [2.1.4 --test, -t flag](#214---test--t-flag)
+  * [2.2 add command](#22-add-command)
+    * [2.2.1 --args flag](#221---args-flag)
+    * [2.2.2 --desc flag](#222---desc-flag)
+    * [2.2.3 --force flag](#223---desc-flag)
+  * [2.3 Working with Commands](#23-working-with-commands)
+  * [2.4 Arguments](#24-arguments)
+  * [2.5 Description](#25-description)
+  * [2.6 Options and Flags](#26-options-and-flags)
+  * [2.7 Global Flags](#27-global-flags)
+  * [2.8 Working with Subcommands](#28-working-with-subcommands)
+* [3. Components](#3-components)
 
 ## 1. Overview
 
-**TTY** provides you with many tools to get the job done in terminal.
+**TTY** provides you with commands and many components to get you onto the path of bulding awesome terminal applications in next to no time.
 
-To ask for user input use `TTY::Prompt`:
+To simply jump start a new command line application use `teletype` executable:
+
+```bash
+$ teletype new app
+```
+
+and then to add more commands:
+
+```bash
+$ teletype add config
+```
+
+Throughout the rest of this guide, I will assume a generated application called `app` and a newly created bare command `config`.
+
+## 2. Bootstrapping
+
+### 2.1 `new` command
+
+Running `teletype new [app-name]` will bootstrap an entire project file structure based on the bundler `gem` command setup enhanced by additional files and folders related to command application development.
+
+For example, to create a new command line application called `app` do:
 
 ```ruby
-require 'tty'
+$ teletype new app
+```
 
-prompt = TTY::Prompt.new
-prompt.yes?('Do you like Ruby?')
-# => Do you like Ruby? (Y/n)
+The output will contain all the files that have been created during setup:
 
-# or ask to select from list
+```
+Creating gem 'app'
+    create app/Gemfile
+    create app/.gitignore
+    create app/lib/app.rb
+    create app/lib/app/version.rb
+    ...
+```
 
-prompt.select("Choose your destiny?", %w(Scorpion Kano Jax))
-# =>
-# Choose your destiny? (Use arrow keys, press Enter to select)
-# ‣ Scorpion
-#   Kano
-#   Jax
+In turn, the following files and directories will be generated in the `app` folder familiar to anyone who has created a gem beforehand:
+
+```
+▾ app/
+├── ▾ exe/
+│   └── app
+├── ▾ lib/
+│   ├── ▾ app/
+│   │   ├── ▸ commands/
+│   │   ├── ▸ templates/
+│   │   ├── cli.rb
+│   │   ├── command.rb
+│   │   └── version.rb
+│   └── app.rb
+├── CODE_OF_CONDUCT.md
+├── Gemfile
+├── LICENSE.txt
+├── README.md
+├── Rakefile
+└── app.gemspec
 ```
 
-To print tabular output use `TTY::Table`:
+By convention the file `lib/app/cli.rb` provides the main entry point to your command line application:
 
 ```ruby
-table = TTY::Table[['a1', 'a2', 'a3'], ['b1', 'b2', 'b3']]
-table.to_s
-# => a1  a2  a3
-     b1  b2  b3
+module App
+  class CLI < Thor
+    # Error raised by this runner
+    Error = Class.new(StandardError)
+
+    desc 'version', 'app version'
+    def version
+      require_relative 'version'
+      puts "v#{App::VERSION}"
+    end
+    map %w(--version -v) => :version
+  end
+end
 ```
 
-To create a progress bar use `TTY::ProgressBar`:
+This is where all your application commands and subcommands will be defined.
+
+Teletype uses `Thor` as an option parsing library by directly inheriting from it.
+
+And also by convention the `start` method is used to parse the command line arguments inside the `app` executable:
 
 ```ruby
-bar = TTY::ProgressBar.new("downloading [:bar]", total: 30)
-30.times { bar.advance }
+App::CLI.start
 ```
 
-To create a spinner use `TTY::Spinner`:
+Run the new command with `--help` or `-h` flag to see all available options:
 
 ```ruby
-spinner = TTY::Spinner.new('Loading ... ', format: :spin_2)
-30.times { spinner.spin }
+$ teletype new --help
+$ teletype new -h
+```
+
+Execute `teletype` to see all available commands.
+
+#### 2.1.1 `--author`, `-a` flag
+
+The `teletype` generator can inject name into documentation for you:
+
+```bash
+$ teletype new app --author 'Piotr Murach'
 ```
 
-To colorize your strings use `Pastel`:
+#### 2.1.2 `--ext` flag
+
+To specify that `teletype` should create a binary executable (as `exe/GEM_NAME`) in the generated project use the `--ext` flag. This binary will also be included in the `GEM_NAME.gemspec` manifest. This is disabled by default, to enable do:
+
+```bash
+$ teletype new app --ext
+```
+
+#### 2.1.3 `--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:
 
 ```ruby
-pastel = Pastel.new
-pastel.green.on_red.bold('Piotr')
+$ teletype new app --license bsd3
 ```
 
-To page very long input use `TTY::Pager`:
+#### 2.1.4 `--test`, `-t` flag
+
+The `teletype` comes configured to work with `rspec` and `minitest` frameworks which are the only two acceptables values. The `GEM_NAME.gemspec` will be configured will be configured and appropriate testing directory setup. By default the `RSpec` framework is used.
 
 ```ruby
-pager = TTY::Pager.new
-pager.page('Very long text...')
+$ teletype new app --test=minitest
+$ teletype new app -t=minitest
 ```
 
-To run external commands with output logging, capturing stdout and stderr use `TTY::Command`:
+### 2.2 `add` command
+
+Once application has been initialized, you can create additional command by using `teletype add [command-name]` task:
 
 ```ruby
-cmd = TTY::Command.new
-out, err = cmd.run('cat ~/.bashrc | grep alias')
+$ 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
+├── ▸ templates/
+│   ├── ▸ config/
+│   └── ▸ create/
+├── command.rb
+├── cli.rb
+└── version.rb
 ```
 
-To measure screen size use `TTY::Screen`:
+Then you will be able to call the new commands like so:
 
 ```ruby
-screen = TTY::Screen.new
-screen.size     # => [51, 280]
-screen.width    # => 280
-screen.height   # => 51
+$ 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.2.1 `--args` flag
+
+You can specify that `teletype` should add a command with a variable number of arguments using the `--args` flag. The `--args` flag accepts space delimited variable names. To specify required argument use a string name, for an optional argument pass `name = nil` enclosed in quote marks and any variable number of arguments needs to be preceeded by asterisk:
+
+```bash
+$ teletype add config --args name           # required argument
+$ teletype add config --args "name = nil"   # optional argument
+$ teletype add config --args *names         # variadic argument
+```
+
+For more in-depth usage see [2.4 Arguments](#24-arguments).
+
+#### 2.2.2 `--desc` flag
+
+Every generated command will have a default description 'Command description...', however whilst generating a command you can and should specify a custom description to provide more context with `--desc` flag:
+
+```bash
+$ teletype add config --desc 'Set and get configuration options'
+```
+
+For more in-depth usage see [2.5 Description](#25-description).
+
+#### 2.2.3 `--force` flag
 
-`TTY::Color` allows you to check if terminal supports color and the color mode:
+If you wish to overwrite currently implemented command use `--force` flag:
+
+```bash
+$ teletype add config --force
+```
+
+### 2.3 Working with Commands
+
+Running
+
+```
+teletype add config
+```
+
+a new command `config` will be added to `commands` folder creating the following files structure inside the `lib` folder:
+
+```shell
+▾ app/
+├── ▾ commands/
+│   └── config.rb
+├── ▾ templates/
+│   └── ▸ config/
+├── cli.rb
+├── command.rb
+└── version.rb
+```
+
+The `lib/app/cli.rb` file will contain generated command entry which handles the case where the user asked for the `config` command help or invokes the actual command:
+
+```ruby
+module App
+  class CLI < Thor
+    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
+  end
+end
+```
+
+And the `lib/app/commands/config.rb` will allow you to specify all the command logic. In the `Config` class which by convention matches the command name, the `execute` method provids place to implement the command logic:
+
+```ruby
+module App
+  module Commands
+    class Config < App::Command
+      def initialize(options)
+        @options = options
+      end
+
+      def execute
+        # Command logic goes here ...
+      end
+    end
+  end
+end
+```
+
+Notice that `Config` inherits from `App::Cmd` class which you have full access to. This class is meant to provide all the convenience methods to lay foundation for any command development. It will lazy load many [tty components](#3-components) inside helper methods which you have access to by opening up the `lib/app/command.rb` file.
+
+For example in the `lib/app/command.rb` file, you have access to `prompt` helper for gathering user input:
+
+```ruby
+# The interactive prompt
+#
+# @see http://www.rubydoc.info/gems/tty-prompt
+#
+# @api public
+def prompt(**options)
+  require 'tty-prompt'
+  TTY::Prompt.new(options)
+end
+```
+
+or a `command` helper for running external commands:
+
+```ruby
+# The external commands runner
+#
+# @see http://www.rubydoc.info/gems/tty-command
+#
+# @api public
+def command(**options)
+  require 'tty-command'
+  TTY::Command.new(options)
+end
+```
+
+You have full control of the file, so you can use only the [tty components](#3-components) that you require. Please bear in mind that all the components are added by default in your `app.gemspec` which you can change to suite your needs and pick only `tty` components that fit your case.
+
+### 2.4 Arguments
+
+A command may accept a variable number of arguments.
+
+For example, if we wish to have a `config` command that accepts a location of configuration file, then we can run `teletype add` command passing `--args` flag:
+
+```bash
+$ teletype add config --args file
+```
+
+which will include the required `file` as an argument to the `config` method:
+
+```ruby
+module App
+  class CLI < Thor
+    desc 'config FILE', 'Set and get configuration options'
+    def config(file)
+      ...
+    end
+  end
+end
+```
+
+Similarly, if we want to generate command with two required arguments, we run `teletype add` command with `--args` flag that can accept variable names delimited by space character:
+
+```bash
+$ teletype add set --args name value
+```
+
+will generate the following:
 
 ```ruby
-TTY::Color.supports?  # => true
-TTY::Color.mode # => 64
+module App
+  class CLI < Thor
+    desc 'set NAME VALUE', 'Set configuration option'
+    def config(name, value)
+      ...
+    end
+  end
+end
+```
+
+If we want to have a command that has an optional argument, for example, the `file` argument is an optional argument in the `config` command, then you need to enclose `--args` argument in parentheses:
+
+```bash
+$ teletype add config --args 'file = nil'
 ```
 
-For instance, to find out if `less` utility is actually supported by the system do:
+In well behaved command line application, any optional argument in a command will be enclosed in square brackets:
 
 ```ruby
-TTY::Which.which('less')  # => '/usr/bin/less'
+module App
+  class CLI < Thor
+    desc 'config [FILE]', 'Set and get configuration options'
+    def config(file = nil)
+      ...
+    end
+  end
+end
+```
+
+If you intend for your command to accept any number of arguments, you need to prefix such argument with an asterisk. For example, if we wish to accept many configuration names:
+
+```bash
+$ teletype add get --args *names
 ```
 
-To move cursor around the terminal use `TTY::Cursor`:
+which will append `...` to the argument description:
 
 ```ruby
-cursor = TTY::Cursor
-print cursor.up(5) + cursor.forward(2)
+module App
+  class CLI < Thor
+    desc 'get NAMES...', 'Get configuration options'
+    def config(*names)
+      ...
+    end
+  end
+end
 ```
 
-## 2. Components
+You can mix and match all the above styles of arguments definitions:
+
+```bash
+$ teletype add config --args file *names
+```
+
+### 2.5 Description
+
+Use the `desc` method call to describe your command when displayed in terminal. There are two arguments to this method. First, specifies the command name and the actual positional arguments it will accept. The second argument is an actual text description of what the command does.
+
+For example, given the command `config` generated in [add command](#22-add-command) section, we can add description like so:
+
+```ruby
+module App
+  class CLI < Thor
+    desc 'config [FILE]', 'Set and get configuration options'
+    def config(file = nil)
+      ...
+    end
+  end
+end
+```
+
+Running `app` executable will include the new description:
+
+```
+Commands:
+  app config [FILE]  # Set and get configuration options
+```
+
+To provide long form description of your command use `long_desc` method.
+
+```ruby
+module App
+  class CLI < Thor
+    desc 'config [FILE]', 'Set and get configuration options'
+    long_desc <<-DESC
+      You can query/set/replace/unset options with this command.
+
+      The name is is an option key separated by a dot, and the value will be escaped.
+
+      This command will fail with non-zero status upon error.
+    DESC
+    def config(file = nil)
+      ...
+    end
+  end
+end
+```
+
+Running `app config --help` will produce the following output:
+
+```
+Usage:
+  app config
+
+You can query/set/replace/unset options with this command.
+
+The name is is an option key separated by a dot, and the value will be escaped.
+
+This command will fail with non-zero status upon error.
+```
+
+### 2.6 Options and Flags
+
+Flags and options allow to customize how particular command is invoked and provide additional configuration.
+
+To specify individual flag or option use `method_option` before the command method. All the flags and options can be accessed inside method body via the `options` hash.
+
+Available metadata for an option are:
+
+* `:aliases` - A list of aliases for this option.
+* `:banner` — A description of the value if the option accepts one.
+* `:default` - The default value of this option if it is not provided.
+* `:lazy_default` — A default that is only passed if the cli option is passed without a value.
+* `:desc` - The short description of the option, printed out in the usage description.
+* `:required` — Indicates that an option is required.
+* `:type` - `:string`, `:hash`, `:array`, `:numeric`, `:boolean`
+* `:enum` — A list of allowed values for this option.
+
+The values for `:type` option are:
+
+* `:boolean` is parsed as `--option`
+* `:string` is parsed as `--option=VALUE` or `--option VALUE`
+* `:numeric` is parsed as `--option=N` or `--option N`
+* `:array` is parsed as `--option=one two three` or `--option one two three`
+* `:hash` is parsed as `--option=name:string age:integer`
+
+For example, you wish to add an option that allows you to add a new line to a configuration file for a given key with a value thus being able to run `app config --add name value`. To do this, you would need to specify `:array` type for accepting more than one value and `:banner` to provide meaningful description of values:
+
+```ruby
+method_option :add, type: :array, banner: "name value", desc: "Adds a new line the config file. "
+```
+
+The above option would be included in the `config` method like so:
+
+```ruby
+module App
+  class CLI < Thor
+    desc 'config [<file>]', 'Set and get configuration options'
+    method_option :add, type: :array, banner: "name value",
+                        desc: "Adds a new line the config file. "
+    def config(*)
+      ...
+    end
+  end
+end
+```
+
+Running `app help config` will output new option:
+
+```
+Usage:
+  app config [<file>]
+
+  Options:
+    [--add=name value]  # Adds a new line the config file.
+```
+
+You can also specify an option as a flag without an associated value. Let us assume you want to be able to open a configuration file in your system editor when running `app config --edit` or `app config -e`. This can be achieved by adding the following option:
+
+```ruby
+method_option :edit, type: :boolean, aliases: ['-e'],
+                     desc: "Opens an editor to modify the specified config file."
+```
+
+And adding it to the `config` method:
+
+```ruby
+module App
+  class CLI < Thor
+    desc 'config [<file>]', 'Set and get configuration options'
+    method_option :edit, type: :boolean, aliases: ['-e'],
+                         desc: "Opens an editor to modify the specified config file."
+    def config(*)
+      ...
+    end
+  end
+end
+```
+
+Next, running `app help config` will produce:
+
+```
+Usage:
+  app config [<file>]
+
+Options:
+      [--add=name value]     # Adds a new line the config file.
+  -e, [--edit], [--no-edit]  # Opens an editor to modify the specified config file.
+```
+
+You can use `method_options` as a shorthand for specifying multiple options at once.
+
+```ruby
+method_options %w(list -l) => :boolean, :system => :boolean, :local => :boolean
+```
+
+Once all the command options and flags have been setup, you can access them via `options` hash in command file `lib/app/commands/config.rb`:
+
+```ruby
+module App
+  module Commands
+    class Config < App::Command
+      def initialize(options)
+        @options = options
+      end
+
+      def execute
+        if options[:edit]
+          editor.open('path/to/config/file')
+        end
+      end
+    end
+  end
+end
+```
+
+### 2.7 Global Flags
+
+You can specify an option or a flag that is applicable to all commands and subcommands within a given class by using the `class_option` method. This method takes exactly the same parameters as `method_option` for an individual command. The `options` hash in a given command will always include a global level flag information.
+
+For example, if you want a global flag `debug` that is visible to all commands in your tool then you need to add it to your `CLI` class like so:
+
+```ruby
+module App
+  class CLI < Thor
+    class_option :debug, type: :boolean, default: false, desc: 'Run in debug mode'
+
+    ...
+  end
+end
+```
+
+### 2.8. Working with Subcommands
+
+If your tool grows in complexity you may want to add more refined behaviour for each individual command, a subcommand is a great choice to accomplish this. For example, `git` utility and its `git remote` command have various subcommands `add`, `rename`, `remove`, `set-url`, `prune` and so on that themselves accept many options and arguments.
+
+The `teletype` executable allows you to easily create new subcommands by issuing the same `add` command for generating commands. The only difference is that you need to provide the original command name and a new subcommand name. For example, let say we want the `config` command and we want to add `set` subcommand with a description and two positional arguments `name` and `value`:
+
+```bash
+$ teletype add config set --desc 'Set configuration option' --args name value
+```
+
+This will add `set.rb` command to the `commands/config` folder:
+
+```
+▾ app/
+├── ▾ commands/
+│   ├── ▾ config/
+│   │   └── set.rb
+│   └── config.rb
+├── ▾ templates/
+│   └── ▾ config/
+│       └── ▸ set/
+├── cli.rb
+├── command.rb
+└── version.rb
+```
+
+The `lib/app/cli.rb` will contain code that registers config namespace with our `CLI` root application:
+
+```ruby
+module App
+  class CLI < Thor
+    require_relative 'commands/config'
+    register App::Commands::Config, 'config', 'config [SUBCOMMAND]', 'Set configuration option'
+  end
+end
+```
+
+The `lib/app/commands/config.rb` will contain code that handles dispatching subcommands to the `Config` instance:
+
+```ruby
+# frozen_string_literal: true
+
+require 'thor'
+
+module App
+  module Commands
+    class Config < Thor
+
+      namespace :config
+
+      desc 'set NAME VALUE', 'Set configuration option'
+      def set(name, value)
+        if options[:help]
+          invoke :help, ['set']
+        else
+          require_relative 'config/set'
+          App::Commands::Config::Set.new(name, value, options).execute
+        end
+      end
+    end
+  end
+end
+```
+
+And finally, the `lib/app/commands/config/set.rb` will contain the actual `set` command implementation:
+
+```ruby
+# frozen_string_literal: true
+
+require_relative '../../command'
+
+module App
+  module Commands
+    class Config
+      class Set < App::Command
+        def initialize(name, value, options)
+          @name = name
+          @value = value
+          @options = options
+        end
+
+        def execute
+          # Command logic goes here ...
+        end
+      end
+    end
+  end
+end
+```
+
+You can now run your command in terminal:
+
+```ruby
+bundle exec app config set debug true
+```
+
+## 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 |
 | ------------ | ----------- | -------- |
@@ -163,13 +749,17 @@ print cursor.up(5) + cursor.forward(2)
 | [tty-cursor](https://github.com/piotrmurach/tty-cursor) | Move terminal cursor around. | [docs](http://www.rubydoc.info/gems/tty-cursor) |
 | [tty-editor](https://github.com/piotrmurach/tty-editor) | Open a file or text in the user preferred editor. | [docs](http://www.rubydoc.info/gems/tty-editor) |
 | [tty-file](https://github.com/piotrmurach/tty-file) | File manipulation utility methods. | [docs](http://www.rubydoc.info/gems/tty-file) |
+| [tty-font](https://github.com/piotrmurach/tty-font) | Write text in large stylized characters using a variety of terminal fonts. | [docs](http://www.rubydoc.info/gems/tty-font) |
+| [tty-markdown](https://github.com/piotrmurach/tty-markdown) | Convert a markdown document or text into a terminal friendly output. | [docs](http://www.rubydoc.info/gems/tty-markdown) |
 | [tty-pager](https://github.com/piotrmurach/tty-pager) | Terminal output paging in a cross-platform way. | [docs](http://www.rubydoc.info/gems/tty-pager) |
 | [tty-platform](https://github.com/piotrmurach/tty-platform) | Detecting different operating systems. | [docs](http://www.rubydoc.info/gems/tty-platform) |
 | [tty-progressbar](https://github.com/piotrmurach/tty-progressbar) | A flexible progress bars drawing in terminal emulators. | [docs](http://www.rubydoc.info/gems/tty-progressbar) |
 | [tty-prompt](https://github.com/piotrmurach/tty-prompt) | A beautiful and powerful interactive command line prompt. | [docs](http://www.rubydoc.info/gems/tty-prompt) |
+| [tty-reader](https://github.com/piotrmurach/tty-reader) | A set of methods for processing keyboard input in character, line and multiline modes. | [docs](http://www.rubydoc.info/gems/tty-reader) |
 | [tty-screen](https://github.com/piotrmurach/tty-screen) | Terminal screen properties detection. | [docs](http://www.rubydoc.info/gems/tty-screen)
 | [tty-spinner](https://github.com/piotrmurach/tty-spinner) | A terminal spinner for tasks with non-deterministic time.| [docs](http://www.rubydoc.info/gems/tty-spinner) |
 | [tty-table](https://github.com/piotrmurach/tty-table) | A flexible and intuitive table output generator. | [docs](http://www.rubydoc.info/gems/tty-table) |
+| [tty-tree](https://github.com/piotrmurach/tty-tree) | Print directory or structured data in a tree like format. | [docs](http://www.rubydoc.info/gems/tty-tree) |
 | [tty-which](https://github.com/piotrmurach/tty-which) | Platform independent implementation of Unix which command. | [docs](http://www.rubydoc.info/gems/tty-which) |
 
 ## Contributing
@@ -186,4 +776,4 @@ This project is intended to be a safe, welcoming space for collaboration, and co
 
 ## Copyright
 
-Copyright (c) 2012-2017 Piotr Murach. See LICENSE for further details.
+Copyright (c) 2012-2018 Piotr Murach. See LICENSE.txt for further details.