Skip to content
Terminal user interface library
Branch: master
Clone or download
lugray Merge pull request #64 from cFire/master
Fixes #63 by ignoring left and right keypresses
Latest commit 8fa2293 Mar 31, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github Add dev-infra as codeowner Mar 29, 2019
bin Rename constants/paths Dec 15, 2017
lib/cli Fixes #63 by ignoring left and right keypresses Mar 31, 2019
test
.gitignore gitignore gemfile.lock Jan 3, 2018
.rubocop.yml Run rubocop on codebase Dec 13, 2017
.travis.yml Initial May 31, 2017
Gemfile Fix Gemfile, update README Dec 9, 2017
LICENSE.txt Initial May 31, 2017
README.md Add input selection and filtering Jan 28, 2019
Rakefile Get tests running, fix hilarious f&r fails Dec 15, 2017
cli-ui.gemspec bundler, whatever Jan 15, 2019
dev.yml Better test command for internal dev.yml Dec 13, 2017

README.md

CLI UI

CLI UI is a small framework for generating nice command-line user interfaces

Installation

gem install cli-ui

or add the following to your Gemfile:

gem 'cli-ui'

In your code, simply add a require 'cli/ui'. Most options assume CLI::UI::StdoutRouter.enable has been called.

Features

This may not be an exhaustive list. Please check our documentation for more information.


Nested framing

To handle content flow (see example below)

CLI::UI::StdoutRouter.enable
CLI::UI::Frame.open('Frame 1') do
  CLI::UI::Frame.open('Frame 2') { puts "inside frame 2" }
  puts "inside frame 1"
end

Nested Framing


Interactive Prompts

Prompt user with options and ask them to choose. Can answer using arrow keys, vim bindings (j/k), or numbers (or y/n for yes/no questions).

For large numbers of options, using e, :, or G will toggle "line select" mode which allows numbers greater than 9 to be typed and f or / will allow the user to filter options using a free-form text input.

CLI::UI.ask('What language/framework do you use?', options: %w(rails go ruby python))

Can also assign callbacks to each option

CLI::UI::Prompt.ask('What language/framework do you use?') do |handler|
  handler.option('rails')  { |selection| selection }
  handler.option('go')     { |selection| selection }
  handler.option('ruby')   { |selection| selection }
  handler.option('python') { |selection| selection }
end
  • Note that the two examples provided above are identical in functionality

Interactive Prompt


Free form text prompts

CLI::UI.ask('Is CLI UI Awesome?', default: 'It is great!')

Free form text prompt


Spinner groups

Handle many multi-threaded processes while suppressing output unless there is an issue. Can update title to show state.

spin_group = CLI::UI::SpinGroup.new
spin_group.add('Title')   { |spinner| sleep 3.0 }
spin_group.add('Title 2') { |spinner| sleep 3.0; spinner.update_title('New Title'); sleep 3.0 }
spin_group.wait

Spinner Group


Text Color formatting

e.g. {{red:Red}} {{green:Green}}

puts CLI::UI.fmt "{{red:Red}} {{green:Green}}"

Text Format


Symbol/Glyph Formatting

e.g. {{*}} => a yellow ⭑

puts CLI::UI.fmt "{{*}} {{x}} {{?}} {{v}}"

Symbol Formatting


Progress Bar

Show progress of a process or operation.

CLI::UI::Progress.progress do |bar|
  100.times do
    bar.tick
  end
end

Progress Bar


Example Usage

The following code makes use of nested-framing, multi-threaded spinners, formatted text, and more.

require 'cli/ui'

CLI::UI::StdoutRouter.enable

CLI::UI::Frame.open('{{*}} {{bold:a}}', color: :green) do
  CLI::UI::Frame.open('{{i}} b', color: :magenta) do
    CLI::UI::Frame.open('{{?}} c', color: :cyan) do
      sg = CLI::UI::SpinGroup.new
      sg.add('wow') do |spinner|
        sleep(2.5)
        spinner.update_title('second round!')
        sleep (1.0)
      end
      sg.add('such spin') { sleep(1.6) }
      sg.add('many glyph') { sleep(2.0) }
      sg.wait
    end
  end
  CLI::UI::Frame.divider('{{v}} lol')
  puts CLI::UI.fmt '{{info:words}} {{red:oh no!}} {{green:success!}}'
  sg = CLI::UI::SpinGroup.new
  sg.add('more spins') { sleep(0.5) ; raise 'oh no' }
  sg.wait
end

Output:

Example Output

Development

  • Run tests using bundle exec rake test. All code should be tested.
  • No code, outside of development and tests needs, should use dependencies. This is a self contained library

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/Shopify/cli-ui.

License

The code is available as open source under the terms of the MIT License.

You can’t perform that action at this time.