dev-ui 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: '0088aa409f65b6130d130f404bb71662a06a6f3d'
-  data.tar.gz: a1a7e7da5c2b8534882f67b22953d4fe886f4d4b
+  metadata.gz: cb7feeed4cd2083e294dd368521e85d4240cb954
+  data.tar.gz: d87bb0bab774010578bfaed70966e87e8a0222b6
 SHA512:
-  metadata.gz: d8dc9c83e8145df6ba606ad805b9c2fd1444c372ad00cbd34e534878ba1a3f0180d00488371cac76706f22bd4d8335e1dc51a3b144fc00e08496ecd07eac471e
-  data.tar.gz: b89f0a81a0840ed0ffde9b9f118ae4d9552b0ac4fde6505158a63ecd2bddcb4fdc8a1a74db78ffd9a7a0a27acc970cc68321905a1cfa89135299d1ad2883e2f0
+  metadata.gz: b371ef8177c5d3626d75c940d56b3afa40924a70fbdc0bb941b3f33c1e5253eb41118a023c6c3a72e92bd15df2bacc65dc361874cc9f4dd08162d402c9215100
+  data.tar.gz: 0dfc477dd137c74de7a99336478c7c120c3cd394c5e259e2b758a6777a7d1fe1eae0ab859c0728c9a224d80bd0f28601e5c2088488bf4ba4025c32dc0b42005f

data/Gemfile

@@ -1,6 +1,8 @@
 # NOTE: These are development-only dependencies
 source "https://rubygems.org"
 
+gemspec
+
 group :development, :test do
   gem 'rubocop'
   gem 'byebug'

data/Gemfile.lock

@@ -1,3 +1,8 @@
+PATH
+  remote: .
+  specs:
+    dev-ui (0.1.0)
+
 GEM
   remote: https://rubygems.org/
   specs:
@@ -21,7 +26,7 @@ GEM
     powerpack (0.1.1)
     rainbow (2.2.2)
       rake
-    rake (12.0.0)
+    rake (10.5.0)
     rubocop (0.49.1)
       parallel (~> 1.10)
       parser (>= 2.3.3.1, < 3.0)
@@ -36,12 +41,15 @@ PLATFORMS
   ruby
 
 DEPENDENCIES
+  bundler (~> 1.15)
   byebug
+  dev-ui!
   method_source
   minitest (>= 5.0.0)
   minitest-reporters
   mocha
+  rake (~> 10.0)
   rubocop
 
 BUNDLED WITH
-   1.15.0
+   1.16.0

data/README.md

@@ -1,3 +1,125 @@
+Dev UI
+---
+
+Dev UI is a small framework who's only responsibility is to print pretty to the terminal
+
+- [Master Documentation](http://www.rubydoc.info/github/Shopify/dev-ui/master/Dev/UI)
+- [Documentation of the Rubygems version](http://www.rubydoc.info/gems/dev-ui/)
+- [Rubygems](https://rubygems.org/gems/dev-ui)
+
+## Installation
+
+```bash
+gem install dev-ui
+```
+
+or add the following to your Gemfile:
+
+```ruby
+gem 'dev-ui'
+```
+
+In your code, simply add a `require 'dev/ui'`. Most options assume `Dev::UI::StdoutRouter.enable` has been called.
+
+## Features
+
+This may not be an exhaustive list. Please check our [documentation](http://www.rubydoc.info/github/Shopify/dev-ui/master/Dev/UI) for more information.
+
+---
+
+### Nested framing
+To handle content flow (see example below)
+
+```ruby
+Dev::UI::StdoutRouter.enable
+Dev::UI::Frame.open('Frame 1') do
+  Dev::UI::Frame.open('Frame 2') { puts "inside frame 2" }
+  puts "inside frame 1" 
+end
+```
+
+![Nested Framing](https://user-images.githubusercontent.com/3074765/33799861-cb5dcb5c-dd01-11e7-977e-6fad38cee08c.png)
+
+---
+
+### Interactive Prompts
+Prompt user with options and ask them to choose. Can answer using arrow keys, numbers, or vim bindings (or y/n for yes/no questions)
+
+```ruby
+Dev::UI.ask('What language/framework do you use?', options: %w(rails go ruby python))
+Dev::UI::InteractivePrompt.call(%w(rails go ruby python))
+```
+
+![Interactive Prompt](https://user-images.githubusercontent.com/3074765/33797984-0ebb5e64-dcdf-11e7-9e7e-7204f279cece.gif)
+
+---
+
+### Free form text prompts
+
+```ruby
+Dev::UI.ask('Is Dev UI Awesome?', default: 'It is great!')
+```
+
+  ![Free form text prompt](https://user-images.githubusercontent.com/3074765/33799822-47f23302-dd01-11e7-82f3-9072a5a5f611.png)
+
+---
+
+### Spinner groups
+Handle many multi-threaded processes while suppressing output unless there is an issue. Can update title to show state.
+
+```ruby
+spin_group = Dev::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](https://user-images.githubusercontent.com/3074765/33798295-d94fd822-dce3-11e7-819b-43e5502d490e.gif)
+
+---
+
+### Text Color formatting
+e.g. `{{red:Red}} {{green:Green}}`
+
+```ruby
+puts Dev::UI.fmt "{{red:Red}} {{green:Green}}"
+```
+
+![Text Format](https://user-images.githubusercontent.com/3074765/33799827-6d0721a2-dd01-11e7-9ab5-c3d455264afe.png)
+
+---
+
+### Symbol/Glyph Formatting
+e.g. `{{*}}` => a yellow ⭑
+
+```ruby
+puts Dev::UI.fmt "{{*}} {{x}} {{?}} {{v}}"
+```
+
+![Symbol Formatting](https://user-images.githubusercontent.com/3074765/33799847-9ec03fd0-dd01-11e7-93f7-5f5cc540e61e.png)
+
+---
+
+### Progress Bar
+
+Show progress of a process or operation.
+
+```ruby
+Dev::UI::Progress.progress do |bar|
+  100.times do
+    bar.tick
+  end
+end
+```
+
+![Progress Bar](https://user-images.githubusercontent.com/3074765/33799794-cc4c940e-dd00-11e7-9bdc-90f77ec9167c.gif)
+
+---
+
+## Example Usage
+
+The following code makes use of nested-framing, multi-threaded spinners, formatted text, and more.
+
 ```ruby
 require 'dev/ui'
 
@@ -7,16 +129,24 @@ Dev::UI::Frame.open('{{*}} {{bold:a}}', color: :green) do
   Dev::UI::Frame.open('{{i}} b', color: :magenta) do
     Dev::UI::Frame.open('{{?}} c', color: :cyan) do
       sg = Dev::UI::SpinGroup.new
-      sg.add('wow') { sleep(2.5) }
+      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
   Dev::UI::Frame.divider('{{v}} lol')
-  puts 'words'
+  puts Dev::UI.fmt '{{info:words}} {{red:oh no!}} {{green:success!}}'
   sg = Dev::UI::SpinGroup.new
   sg.add('more spins') { sleep(0.5) ; raise 'oh no' }
   sg.wait
 end
 ```
+
+Output:
+
+![Example Output](https://user-images.githubusercontent.com/3074765/33797758-7a54c7cc-dcdb-11e7-918e-a47c9689f068.gif)

data/dev.yml

@@ -1,5 +1,4 @@
 up:
-  - homebrew:
   - ruby: 2.3.3
   - bundler
 

data/lib/dev/ui.rb

@@ -12,16 +12,27 @@ module Dev
     autoload :Formatter,          'dev/ui/formatter'
     autoload :Spinner,            'dev/ui/spinner'
 
-
-    # TODO: this, better
+    # Convenience accessor to +Dev::UI::Spinner::SpinGroup+
     SpinGroup = Spinner::SpinGroup
 
-    # TODO: test
+    # Glyph resolution using +Dev::UI::Glyph.lookup+
+    # Look at the method signature for +Glyph.lookup+ for more details
+    #
+    # ==== Attributes
+    #
+    # * +handle+ - handle of the glyph to resolve
+    #
     def self.glyph(handle)
       Dev::UI::Glyph.lookup(handle)
     end
 
-    # TODO: test
+    # Color resolution using +Dev::UI::Color.lookup+
+    # Will lookup using +Color.lookup+ if a symbol, otherwise we assume it is a valid color and return it
+    #
+    # ==== Attributes
+    #
+    # * +input+ - color to resolve
+    #
     def self.resolve_color(input)
       case input
       when Symbol
@@ -31,35 +42,96 @@ module Dev
       end
     end
 
+    # Conviencence Method for +Dev::UI::Prompt.confirm+
+    #
+    # ==== Attributes
+    #
+    # * +question+ - question to confirm
+    #
     def self.confirm(question)
       Dev::UI::Prompt.confirm(question)
     end
 
+    # Conviencence Method for +Dev::UI::Prompt.ask+
+    #
+    # ==== Attributes
+    #
+    # * +question+ - question to ask
+    # * +kwargs+ - arugments for +Prompt.ask+
+    #
     def self.ask(question, **kwargs)
       Dev::UI::Prompt.ask(question, **kwargs)
     end
 
+    # Conviencence Method to resolve text using +Dev::UI::Formatter.format+
+    # Check +Dev::UI::Formatter::SGR_MAP+ for available formatting options
+    #
+    # ==== Attributes
+    #
+    # * +input+ - input to format
+    #
     def self.resolve_text(input)
       return input if input.nil?
       Dev::UI::Formatter.new(input).format
     end
 
+    # Conviencence Method to format text using +Dev::UI::Formatter.format+
+    # Check +Dev::UI::Formatter::SGR_MAP+ for available formatting options
+    #
+    # https://user-images.githubusercontent.com/3074765/33799827-6d0721a2-dd01-11e7-9ab5-c3d455264afe.png
+    # https://user-images.githubusercontent.com/3074765/33799847-9ec03fd0-dd01-11e7-93f7-5f5cc540e61e.png
+    #
+    # ==== Attributes
+    #
+    # * +input+ - input to format
+    #
+    # ==== Options
+    #
+    # * +enable_color+ - should color be used? default to true
+    #
     def self.fmt(input, enable_color: true)
       Dev::UI::Formatter.new(input).format(enable_color: enable_color)
     end
 
+    # Conviencence Method for +Dev::UI::Frame.open+
+    #
+    # ==== Attributes
+    #
+    # * +args+ - arguments for +Frame.open+
+    # * +block+ - block for +Frame.open+
+    #
     def self.frame(*args, &block)
       Dev::UI::Frame.open(*args, &block)
     end
 
+    # Conviencence Method for +Dev::UI::Spinner.spin+
+    #
+    # ==== Attributes
+    #
+    # * +args+ - arguments for +Spinner.open+
+    # * +block+ - block for +Spinner.open+
+    #
     def self.spinner(*args, &block)
       Dev::UI::Spinner.spin(*args, &block)
     end
 
+    # Conviencence Method to override frame color using +Dev::UI::Frame.with_frame_color+
+    #
+    # ==== Attributes
+    #
+    # * +color+ - color to override to
+    # * +block+ - block for +Frame.with_frame_color_override+
+    #
     def self.with_frame_color(color, &block)
       Dev::UI::Frame.with_frame_color_override(color, &block)
     end
 
+    # Duplicate output to a file path
+    #
+    # ==== Attributes
+    #
+    # * +path+ - path to duplicate output to
+    #
     def self.log_output_to(path)
       if Dev::UI::StdoutRouter.duplicate_output_to
         raise "multiple logs not allowed"
@@ -73,6 +145,12 @@ module Dev
       end
     end
 
+    # Disable all framing within a block
+    #
+    # ==== Attributes
+    #
+    # * +block+ - block in which to disable frames
+    #
     def self.raw
       prev = Thread.current[:no_devui_frame_inset]
       Thread.current[:no_devui_frame_inset] = true

data/lib/dev/ui/ansi.rb

@@ -7,9 +7,9 @@ module Dev
 
       # ANSI escape sequences (like \x1b[31m) have zero width.
       # when calculating the padding width, we must exclude them.
-      # This also implements a *reaaaallly* shitty version of utf8 character
-      # width calculation like we could get for real from something like
-      # utf8proc.
+      # This also implements a basic version of utf8 character width calculation like
+      # we could get for real from something like utf8proc.
+      #
       def self.printing_width(str)
         zwj = false
         strip_codes(str).codepoints.reduce(0) do |acc, cp|
@@ -27,10 +27,23 @@ module Dev
         end
       end
 
+      # Strips ANSI codes from a str
+      #
+      # ==== Attributes
+      #
+      # - +str+ - The string from which to strip codes
+      #
       def self.strip_codes(str)
         str.gsub(/\x1b\[[\d;]+[A-z]|\r/, '')
       end
 
+      # Returns an ANSI control sequence
+      #
+      # ==== Attributes
+      #
+      # - +args+ - Argument to pass to the ANSI control sequence
+      # - +cmd+ - ANSI control sequence Command
+      #
       def self.control(args, cmd)
         ESC + "[" + args + cmd
       end
@@ -42,50 +55,98 @@ module Dev
 
       # Cursor Movement
 
+      # Move the cursor up n lines
+      #
+      # ==== Attributes
+      #
+      # * +n+ - number of lines by which to move the cursor up
+      #
       def self.cursor_up(n = 1)
         return '' if n.zero?
         control(n.to_s, 'A')
       end
 
+      # Move the cursor down n lines
+      #
+      # ==== Attributes
+      #
+      # * +n+ - number of lines by which to move the cursor down
+      #
       def self.cursor_down(n = 1)
         return '' if n.zero?
         control(n.to_s, 'B')
       end
 
+      # Move the cursor forward n columns
+      #
+      # ==== Attributes
+      #
+      # * +n+ - number of columns by which to move the cursor forward
+      #
       def self.cursor_forward(n = 1)
         return '' if n.zero?
         control(n.to_s, 'C')
       end
 
+      # Move the cursor back n columns
+      #
+      # ==== Attributes
+      #
+      # * +n+ - number of columns by which to move the cursor back
+      #
       def self.cursor_back(n = 1)
         return '' if n.zero?
         control(n.to_s, 'D')
       end
 
+      # Move the cursor to a specific column
+      #
+      # ==== Attributes
+      #
+      # * +n+ - The column to move to
+      #
       def self.cursor_horizontal_absolute(n = 1)
         control(n.to_s, 'G')
       end
 
-      # Cursor Visibility
-
+      # Show the cursor
+      #
       def self.show_cursor
         control('', "?25h")
       end
 
+      # Hide the cursor
+      #
       def self.hide_cursor
         control('', "?25l")
       end
 
-      # Line Handling
+      # Save the cursor position
+      #
+      def self.cursor_save
+        control('', 's')
+      end
+
+      # Restore the saved cursor position
+      #
+      def self.cursor_restore
+        control('', 'u')
+      end
 
+      # Move to the next line
+      #
       def self.next_line
         cursor_down + control('1', 'G')
       end
 
+      # Move to the previous line
+      #
       def self.previous_line
         cursor_up + control('1', 'G')
       end
 
+      # Move to the end of the line
+      #
       def self.end_of_line
         control("\033[", 'C')
       end