dev-ui 0.1.0 → 0.1.1

data/lib/dev/ui/progress.rb

@@ -3,25 +3,33 @@ require 'dev/ui'
 module Dev
   module UI
     class Progress
-      FILLED_BAR = Dev::UI::Glyph.new("◾", 0x2588, Color::CYAN)
-      UNFILLED_BAR = Dev::UI::Glyph.new("◽", 0x2588, Color::WHITE)
+      # A Cyan filled block
+      FILLED_BAR = "\e[46m"
+      # A bright white block
+      UNFILLED_BAR = "\e[1;47m"
 
+      # Add a progress bar to the terminal output
+      #
+      # https://user-images.githubusercontent.com/3074765/33799794-cc4c940e-dd00-11e7-9bdc-90f77ec9167c.gif
+      #
+      # ==== Example Usage:
+      #
       # Set the percent to X
-      # Dev::UI::Progress.progress do |bar|
-      #   bar.tick(set_percent: percent)
-      # end
+      #   Dev::UI::Progress.progress do |bar|
+      #     bar.tick(set_percent: percent)
+      #   end
       #
-      # Increase the percent by 1
-      # Dev::UI::Progress.progress do |bar|
-      #   bar.tick
-      # end
+      # Increase the percent by 1 percent
+      #   Dev::UI::Progress.progress do |bar|
+      #     bar.tick
+      #   end
       #
       # Increase the percent by X
-      # Dev::UI::Progress.progress do |bar|
-      #   bar.tick(percent: 5)
-      # end
-      def self.progress
-        bar = Progress.new
+      #   Dev::UI::Progress.progress do |bar|
+      #     bar.tick(percent: 5)
+      #   end
+      def self.progress(width: Terminal.width)
+        bar = Progress.new(width: width)
         print Dev::UI::ANSI.hide_cursor
         yield(bar)
       ensure
@@ -32,11 +40,26 @@ module Dev
         end
       end
 
+      # Initialize a progress bar. Typically used in a +Progress.progress+ block
+      #
+      # ==== Options
+      # One of the follow can be used, but not both together
+      #
+      # * +:width+ - The width of the terminal
+      #
       def initialize(width: Terminal.width)
         @percent_done = 0
         @max_width = width
       end
 
+      # Set the progress of the bar. Typically used in a +Progress.progress+ block
+      #
+      # ==== Options
+      # One of the follow can be used, but not both together
+      #
+      # * +:percent+ - Increment progress by a specific percent amount
+      # * +:set_percent+ - Set progress to a specific percent
+      #
       def tick(percent: 0.01, set_percent: nil)
         raise ArgumentError, 'percent and set_percent cannot both be specified' if percent != 0.01 && set_percent
         @percent_done += percent
@@ -48,6 +71,8 @@ module Dev
         print Dev::UI::ANSI.end_of_line + "\n"
       end
 
+      # Format the progress bar to be printed to terminal
+      #
       def to_s
         suffix = " #{(@percent_done * 100).round(2)}%"
         workable_width = @max_width - Frame.prefix_width - suffix.size
@@ -55,9 +80,9 @@ module Dev
         unfilled = workable_width - filled
 
         Dev::UI.resolve_text [
-          (FILLED_BAR.to_s * filled),
-          (UNFILLED_BAR.to_s * unfilled),
-          suffix
+          FILLED_BAR + ' ' * filled,
+          UNFILLED_BAR + ' ' * unfilled,
+          Dev::UI::Color::RESET.code + suffix
         ].join
       end
     end

data/lib/dev/ui/prompt.rb

@@ -5,6 +5,50 @@ module Dev
   module UI
     module Prompt
       class << self
+        # Ask a user a question with either free form answer or a set of answers
+        # Do not use this method for yes/no questions. Use +confirm+
+        # Can use arrows, y/n, numbers, and vim bindings to control
+        #
+        # * Handles free form answers (options are nil)
+        # * Handles default answers for free form text
+        # * Handles file auto completion for file input
+        # * Handles interactively choosing answers using +InteractivePrompt+
+        #
+        # https://user-images.githubusercontent.com/3074765/33799822-47f23302-dd01-11e7-82f3-9072a5a5f611.png
+        #
+        # ==== Attributes
+        #
+        # * +question+ - (required) The question to ask the user
+        #
+        # ==== Options
+        #
+        # * +:options+ - Options to ask the user. Will use +InteractivePrompt+ to do so
+        # * +:default+ - The default answer to the question (e.g. they just press enter and don't input anything)
+        # * +:is_file+ - Tells the input to use file auto-completion (tab completion)
+        # * +:allow_empty+ - Allows the answer to be empty
+        #
+        # Note:
+        # * +:options+ conflicts with +:default+ and +:is_file+, you cannot set options with either of these keywords
+        # * +:default+ conflicts with +:allow_empty:, you cannot set these together
+        #
+        # ==== Example Usage:
+        #
+        # Free form question
+        #   Dev::UI::Prompt.ask('What color is the sky?')
+        #
+        # Free form question with a file answer
+        #   Dev::UI::Prompt.ask('Where is your Gemfile located?', is_file: true)
+        #
+        # Free form question with a default answer
+        #   Dev::UI::Prompt.ask('What color is the sky?', default: 'blue')
+        #
+        # Free form question when the answer can be empty
+        #   Dev::UI::Prompt.ask('What is your opinion on this question?', allow_empty: true)
+        #
+        # Question with answers
+        #   Dev::UI::Prompt.ask('What kind of project is this?', options: %w(rails go ruby python))
+        #
+        #
         def ask(question, options: nil, default: nil, is_file: nil, allow_empty: true)
           if (default && !allow_empty) || (options && (default || is_file))
             raise(ArgumentError, 'conflicting arguments')
@@ -34,6 +78,14 @@ module Dev
           end
         end
 
+        # Asks the user a yes/no question.
+        # Can use arrows, y/n, numbers (1/2), and vim bindings to control
+        #
+        # ==== Example Usage:
+        #
+        # Free form question
+        #   Dev::UI::Prompt.confirm('Is the sky blue?')
+        #
         def confirm(question)
           puts_question("#{question} {{yellow:(choose with ↑ ↓ ⏎)}}")
           InteractivePrompt.call(%w(yes no)) == 'yes'
@@ -76,7 +128,8 @@ module Dev
           prompt = prefix + Dev::UI.fmt('{{blue:> }}{{yellow:')
 
           begin
-            Readline.readline(prompt, true).chomp
+            line = Readline.readline(prompt, true)
+            line.to_s.chomp
           rescue Interrupt
             Dev::UI.raw { STDERR.puts('^C' + Dev::UI::Color::RESET.code) }
             raise

data/lib/dev/ui/spinner.rb

@@ -3,7 +3,11 @@ require 'dev/ui'
 module Dev
   module UI
     module Spinner
+      autoload :Async,      'dev/ui/spinner/async'
+      autoload :SpinGroup,  'dev/ui/spinner/spin_group'
+
       PERIOD = 0.1 # seconds
+      TASK_FAILED = :task_failed
 
       begin
         runes = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏']
@@ -12,157 +16,33 @@ module Dev
         GLYPHS = colors.zip(runes).map(&:join)
       end
 
-      def self.spin(title, &block)
-        sg = SpinGroup.new
+      # Adds a single spinner
+      # Uses an interactive session to allow the user to pick an answer
+      # Can use arrows, y/n, numbers (1/2), and vim bindings to control
+      #
+      # https://user-images.githubusercontent.com/3074765/33798295-d94fd822-dce3-11e7-819b-43e5502d490e.gif
+      #
+      # ==== Attributes
+      #
+      # * +title+ - Title of the spinner to use
+      #
+      # ==== Options
+      #
+      # * +:auto_debrief+ - Automatically debrief exceptions? Default to true
+      #
+      # ==== Block
+      #
+      # * *spinner+ - Instance of the spinner. Can call +update_title+ to update the user of changes
+      #
+      # ==== Example Usage:
+      #
+      #   Dev::UI::Spinner.spin('Title') { sleep 1.0 }
+      #
+      def self.spin(title, auto_debrief: true, &block)
+        sg = SpinGroup.new(auto_debrief: auto_debrief)
         sg.add(title, &block)
         sg.wait
       end
-
-      class SpinGroup
-        def initialize
-          @m = Mutex.new
-          @consumed_lines = 0
-          @tasks = []
-        end
-
-        class Task
-          attr_reader :title, :exception, :success, :stdout, :stderr
-
-          def initialize(title, &block)
-            @title = title
-            @thread = Thread.new do
-              cap = Dev::UI::StdoutRouter::Capture.new(with_frame_inset: false, &block)
-              begin
-                cap.run
-              ensure
-                @stdout = cap.stdout
-                @stderr = cap.stderr
-              end
-            end
-
-            @done      = false
-            @exception = nil
-            @success   = false
-          end
-
-          def check
-            return true if @done
-            return false if @thread.alive?
-
-            @done = true
-            begin
-              status = @thread.join.status
-              @success = (status == false)
-            rescue => exc
-              @exception = exc
-              @success = false
-            end
-
-            @done
-          end
-
-          def render(index, force = true)
-            return full_render(index) if force
-            partial_render(index)
-          end
-
-          private
-
-          def full_render(index)
-            inset + glyph(index) + Dev::UI::Color::RESET.code + ' ' + Dev::UI.resolve_text(title)
-          end
-
-          def partial_render(index)
-            Dev::UI::ANSI.cursor_forward(inset_width) + glyph(index) + Dev::UI::Color::RESET.code
-          end
-
-          def glyph(index)
-            if @done
-              @success ? Dev::UI::Glyph::CHECK.to_s : Dev::UI::Glyph::X.to_s
-            else
-              GLYPHS[index]
-            end
-          end
-
-          def inset
-            @inset ||= Dev::UI::Frame.prefix
-          end
-
-          def inset_width
-            @inset_width ||= Dev::UI::ANSI.printing_width(inset)
-          end
-        end
-
-        def add(title, &block)
-          @m.synchronize do
-            @tasks << Task.new(title, &block)
-          end
-        end
-
-        def wait
-          idx = 0
-
-          loop do
-            all_done = true
-
-            @m.synchronize do
-              Dev::UI.raw do
-                @tasks.each.with_index do |task, int_index|
-                  nat_index = int_index + 1
-                  task_done = task.check
-                  all_done = false unless task_done
-
-                  if nat_index > @consumed_lines
-                    print(task.render(idx, true) + "\n")
-                    @consumed_lines += 1
-                  else
-                    offset = @consumed_lines - int_index
-                    move_to   = Dev::UI::ANSI.cursor_up(offset) + "\r"
-                    move_from = "\r" + Dev::UI::ANSI.cursor_down(offset)
-
-                    print(move_to + task.render(idx, idx.zero?) + move_from)
-                  end
-                end
-              end
-            end
-
-            break if all_done
-
-            idx = (idx + 1) % GLYPHS.size
-            sleep(PERIOD)
-          end
-
-          debrief
-        end
-
-        def debrief
-          @m.synchronize do
-            @tasks.each do |task|
-              next if task.success
-
-              e = task.exception
-              out = task.stdout
-              err = task.stderr
-
-              Dev::UI::Frame.open('Task Failed: ' + task.title, color: :red) do
-                if e
-                  puts"#{e.class}: #{e.message}"
-                  puts "\tfrom #{e.backtrace.join("\n\tfrom ")}"
-                end
-
-                Dev::UI::Frame.divider('STDOUT')
-                out = "(empty)" if out.nil? || out.strip.empty?
-                puts out
-
-                Dev::UI::Frame.divider('STDERR')
-                err = "(empty)" if err.nil? || err.strip.empty?
-                puts err
-              end
-            end
-            @tasks.all?(&:success)
-          end
-        end
-      end
     end
   end
 end

data/lib/dev/ui/spinner/async.rb

@@ -0,0 +1,40 @@
+module Dev
+  module UI
+    module Spinner
+      class Async
+        # Convenience method for +initialize+
+        #
+        def self.start(title)
+          new(title)
+        end
+
+        # Initializes a new asynchronous spinner with no specific end.
+        # Must call +.stop+ to end the spinner
+        #
+        # ==== Attributes
+        #
+        # * +title+ - Title of the spinner to use
+        #
+        # ==== Example Usage:
+        #
+        #   Dev::UI::Spinner::Async.new('Title')
+        #
+        def initialize(title)
+          require 'thread'
+          sg = Dev::UI::Spinner::SpinGroup.new
+          @m = Mutex.new
+          @cv = ConditionVariable.new
+          sg.add(title) { @m.synchronize { @cv.wait(@m) } }
+          @t = Thread.new { sg.wait }
+        end
+
+        # Stops an asynchronous spinner
+        #
+        def stop
+          @m.synchronize { @cv.signal }
+          @t.value
+        end
+      end
+    end
+  end
+end

data/lib/dev/ui/spinner/spin_group.rb

@@ -0,0 +1,223 @@
+module Dev
+  module UI
+    module Spinner
+      class SpinGroup
+        # Initializes a new spin group
+        # This lets you add +Task+ objects to the group to multi-thread work
+        #
+        # ==== Options
+        #
+        # * +:auto_debrief+ - Automatically debrief exceptions? Default to true
+        #
+        # ==== Example Usage
+        #
+        #  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
+        #
+        # Output:
+        #
+        # https://user-images.githubusercontent.com/3074765/33798558-c452fa26-dce8-11e7-9e90-b4b34df21a46.gif
+        #
+        def initialize(auto_debrief: true)
+          @m = Mutex.new
+          @consumed_lines = 0
+          @tasks = []
+          @auto_debrief = auto_debrief
+        end
+
+        class Task
+          attr_reader :title, :exception, :success, :stdout, :stderr
+
+          # Initializes a new Task
+          # This is managed entirely internally by +SpinGroup+
+          #
+          # ==== Attributes
+          #
+          # * +title+ - Title of the task
+          # * +block+ - Block for the task, will be provided with an instance of the spinner
+          #
+          def initialize(title, &block)
+            @title = title
+            @thread = Thread.new do
+              cap = Dev::UI::StdoutRouter::Capture.new(self, with_frame_inset: false, &block)
+              begin
+                cap.run
+              ensure
+                @stdout = cap.stdout
+                @stderr = cap.stderr
+              end
+            end
+
+            @force_full_render = false
+            @done      = false
+            @exception = nil
+            @success   = false
+          end
+
+          # Checks if a task is finished
+          #
+          def check
+            return true if @done
+            return false if @thread.alive?
+
+            @done = true
+            begin
+              status = @thread.join.status
+              @success = (status == false)
+              @success = false if @thread.value == TASK_FAILED
+            rescue => exc
+              @exception = exc
+              @success = false
+            end
+
+            @done
+          end
+
+          # Re-renders the task if required
+          #
+          # ==== Attributes
+          #
+          # * +index+ - index of the task
+          # * +force+ - force rerender of the task
+          #
+          def render(index, force = true)
+            return full_render(index) if force || @force_full_render
+            partial_render(index)
+          ensure
+            @force_full_render = false
+          end
+
+          # Update the spinner title
+          #
+          # ==== Attributes
+          #
+          # * +title+ - title to change the spinner to
+          #
+          def update_title(new_title)
+            @title = new_title
+            @force_full_render = true
+          end
+
+          private
+
+          def full_render(index)
+            inset + glyph(index) + Dev::UI::Color::RESET.code + ' ' + Dev::UI.resolve_text(title) + "\e[K"
+          end
+
+          def partial_render(index)
+            Dev::UI::ANSI.cursor_forward(inset_width) + glyph(index) + Dev::UI::Color::RESET.code
+          end
+
+          def glyph(index)
+            if @done
+              @success ? Dev::UI::Glyph::CHECK.to_s : Dev::UI::Glyph::X.to_s
+            else
+              GLYPHS[index]
+            end
+          end
+
+          def inset
+            @inset ||= Dev::UI::Frame.prefix
+          end
+
+          def inset_width
+            @inset_width ||= Dev::UI::ANSI.printing_width(inset)
+          end
+        end
+
+        # Add a new task
+        #
+        # ==== Attributes
+        #
+        # * +title+ - Title of the task
+        # * +block+ - Block for the task, will be provided with an instance of the spinner
+        #
+        # ==== Example Usage:
+        #   spin_group = Dev::UI::SpinGroup.new
+        #   spin_group.add('Title') { |spinner| sleep 1.0 }
+        #   spin_group.wait
+        #
+        def add(title, &block)
+          @m.synchronize do
+            @tasks << Task.new(title, &block)
+          end
+        end
+
+        # Tells the group you're done adding tasks and to wait for all of them to finish
+        #
+        # ==== Example Usage:
+        #   spin_group = Dev::UI::SpinGroup.new
+        #   spin_group.add('Title') { |spinner| sleep 1.0 }
+        #   spin_group.wait
+        #
+        def wait
+          idx = 0
+
+          loop do
+            all_done = true
+
+            @m.synchronize do
+              Dev::UI.raw do
+                @tasks.each.with_index do |task, int_index|
+                  nat_index = int_index + 1
+                  task_done = task.check
+                  all_done = false unless task_done
+
+                  if nat_index > @consumed_lines
+                    print(task.render(idx, true) + "\n")
+                    @consumed_lines += 1
+                  else
+                    offset = @consumed_lines - int_index
+                    move_to   = Dev::UI::ANSI.cursor_up(offset) + "\r"
+                    move_from = "\r" + Dev::UI::ANSI.cursor_down(offset)
+
+                    print(move_to + task.render(idx, idx.zero?) + move_from)
+                  end
+                end
+              end
+            end
+
+            break if all_done
+
+            idx = (idx + 1) % GLYPHS.size
+            sleep(PERIOD)
+          end
+
+          debrief if @auto_debrief
+        end
+
+        # Debriefs failed tasks is +auto_debrief+ is true
+        #
+        def debrief
+          @m.synchronize do
+            @tasks.each do |task|
+              next if task.success
+
+              e = task.exception
+              out = task.stdout
+              err = task.stderr
+
+              Dev::UI::Frame.open('Task Failed: ' + task.title, color: :red) do
+                if e
+                  puts"#{e.class}: #{e.message}"
+                  puts "\tfrom #{e.backtrace.join("\n\tfrom ")}"
+                end
+
+                Dev::UI::Frame.divider('STDOUT')
+                out = "(empty)" if out.nil? || out.strip.empty?
+                puts out
+
+                Dev::UI::Frame.divider('STDERR')
+                err = "(empty)" if err.nil? || err.strip.empty?
+                puts err
+              end
+            end
+            @tasks.all?(&:success)
+          end
+        end
+      end
+    end
+  end
+end