dev-ui 0.1.0 → 0.1.1

data/lib/dev/ui/color.rb

@@ -4,6 +4,16 @@ module Dev
   module UI
     class Color
       attr_reader :sgr, :name, :code
+
+      # Creates a new color mapping
+      # Signatures can be found here:
+      # https://en.wikipedia.org/wiki/ANSI_escape_code#Colors
+      #
+      # ==== Attributes
+      #
+      # * +sgr+ - The color signature
+      # * +name+ - The name of the color
+      #
       def initialize(sgr, name)
         @sgr  = sgr
         @code = Dev::UI::ANSI.sgr(sgr)
@@ -44,12 +54,23 @@ module Dev
         end
       end
 
+      # Looks up a color code by name
+      #
+      # ==== Raises
+      # Raises a InvalidColorName if the color is not available
+      # You likely need to add it to the +MAP+ or you made a typo
+      #
+      # ==== Returns
+      # Returns a color code
+      #
       def self.lookup(name)
         MAP.fetch(name)
       rescue KeyError
         raise InvalidColorName, name
       end
 
+      # All available colors by name
+      #
       def self.available
         MAP.keys
       end

data/lib/dev/ui/formatter.rb

@@ -6,6 +6,11 @@ require 'strscan'
 module Dev
   module UI
     class Formatter
+      # Available mappings of formattings
+      # To use any of them, you can use {{<key>:<string>}}
+      # There are presentational (colours and formatters)
+      # and semantic (error, info, command) formatters available
+      #
       SGR_MAP = {
         # presentational
         'red'       => '31',
@@ -32,14 +37,14 @@ module Dev
 
       SCAN_FUNCNAME = /\w+:/
       SCAN_GLYPH    = /.}}/
-      SCAN_BODY     = /
+      SCAN_BODY     = %r{
         .*?
         (
           #{BEGIN_EXPR} |
           #{END_EXPR}   |
           \z
         )
-      /mx
+      }mx
 
       DISCARD_BRACES = 0..-3
 
@@ -55,10 +60,26 @@ module Dev
         end
       end
 
+      # Initialize a formatter with text.
+      #
+      # ===== Attributes
+      #
+      # * +text+ - the text to format
+      #
       def initialize(text)
         @text = text
       end
 
+      # Format the text using a map.
+      #
+      # ===== Attributes
+      #
+      # * +sgr_map+ - the mapping of the formattings. Defaults to +SGR_MAP+
+      #
+      # ===== Options
+      #
+      # * +:enable_color+ - enable color output? Default is true
+      #
       def format(sgr_map = SGR_MAP, enable_color: true)
         @nodes = []
         stack = parse_body(StringScanner.new(@text))

data/lib/dev/ui/frame.rb

@@ -3,15 +3,50 @@ require 'dev/ui'
 module Dev
   module UI
     module Frame
+      class UnnestedFrameException < StandardError; end
       class << self
         DEFAULT_FRAME_COLOR = Dev::UI.resolve_color(:cyan)
 
+        # Opens a new frame. Can be nested
         # Can be invoked in two ways: block and blockless
-        # In block form, the frame is closed automatically when the block returns
-        # In blockless form, caller MUST call Frame.close when the frame is
-        #   logically done.
-        # blockless form is strongly discouraged in cases where block form can be
-        #   made to work.
+        # * In block form, the frame is closed automatically when the block returns
+        # * In blockless form, caller MUST call +Frame.close+ when the frame is logically done
+        # * Blockless form is strongly discouraged in cases where block form can be made to work
+        #
+        # https://user-images.githubusercontent.com/3074765/33799861-cb5dcb5c-dd01-11e7-977e-6fad38cee08c.png
+        #
+        # The return value of the block determines if the block is a "success" or a "failure"
+        #
+        # ==== Attributes
+        #
+        # * +text+ - (required) the text/title to output in the frame
+        #
+        # ==== Options
+        #
+        # * +:color+ - The color of the frame. Defaults to +DEFAULT_FRAME_COLOR+
+        # * +:failure_text+ - If the block failed, what do we output? Defaults to nil
+        # * +:success_text+ - If the block succeeds, what do we output? Defaults to nil
+        # * +:timing+ - How long did the frame content take? Invalid for blockless. Defaults to true for the block form
+        #
+        # ==== Example
+        # 
+        # ===== Block Form (Assumes +Dev::UI::StdoutRouter.enable+ has been called)
+        #
+        #   Dev::UI::Frame.open('Open') { puts 'hi' }
+        #
+        # Output:
+        #   ┏━━ Open ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+        #   ┃ hi
+        #   ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ (0.0s) ━━
+        # 
+        # ===== Blockless Form
+        #
+        #   Dev::UI::Frame.open('Open')
+        #
+        # Output:
+        #   ┏━━ Open ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+        #
+        # 
         def open(
           text,
           color: DEFAULT_FRAME_COLOR,
@@ -64,6 +99,26 @@ module Dev
           end
         end
 
+        # Closes a frame
+        # Automatically called for a block-form +open+
+        #
+        # ==== Attributes
+        #
+        # * +text+ - (required) the text/title to output in the frame
+        #
+        # ==== Options
+        #
+        # * +:color+ - The color of the frame. Defaults to +DEFAULT_FRAME_COLOR+
+        # * +:elapsed+ - How long did the frame take? Defaults to nil
+        #
+        # ==== Example
+        #
+        #   Dev::UI::Frame.close('Close')
+        #
+        # Output:
+        #   ┗━━ Close ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+        #
+        # 
         def close(text, color: DEFAULT_FRAME_COLOR, elapsed: nil)
           color = Dev::UI.resolve_color(color)
 
@@ -77,9 +132,35 @@ module Dev
           end
         end
 
+        # Adds a divider in a frame
+        # Used to separate information within a single frame
+        #
+        # ==== Attributes
+        #
+        # * +text+ - (required) the text/title to output in the frame
+        #
+        # ==== Options
+        #
+        # * +:color+ - The color of the frame. Defaults to +DEFAULT_FRAME_COLOR+
+        #
+        # ==== Example
+        #
+        #   Dev::UI::Frame.open('Open') { Dev::UI::Frame.divider('Divider') }
+        #
+        # Output:
+        #   ┏━━ Open ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+        #   ┣━━ Divider ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+        #   ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+        #
+        # ==== Raises
+        #
+        # MUST be inside an open frame or it raises a +UnnestedFrameException+
+        #
         def divider(text, color: nil)
+          fs_item = FrameStack.pop
+          raise UnnestedFrameException, "no frame nesting to unnest" unless fs_item
           color = Dev::UI.resolve_color(color)
-          item  = Dev::UI.resolve_color(FrameStack.pop)
+          item  = Dev::UI.resolve_color(fs_item)
 
           Dev::UI.raw do
             puts edge(text, color: (color || item), first: Dev::UI::Box::Heavy::DIV)
@@ -87,6 +168,12 @@ module Dev
           FrameStack.push(item)
         end
 
+        # Determines the prefix of a frame entry taking multi-nested frames into account
+        #
+        # ==== Options
+        #
+        # * +:color+ - The color of the prefix. Defaults to +Thread.current[:devui_frame_color_override]+ or nil
+        #
         def prefix(color: nil)
           pfx = String.new
           items = FrameStack.items
@@ -101,6 +188,12 @@ module Dev
           pfx
         end
 
+        # Override a color for a given thread. 
+        #
+        # ==== Attributes
+        #
+        # * +color+ - The color to override to
+        #
         def with_frame_color_override(color)
           prev = Thread.current[:devui_frame_color_override]
           Thread.current[:devui_frame_color_override] = color
@@ -109,6 +202,8 @@ module Dev
           Thread.current[:devui_frame_color_override] = prev
         end
 
+        # The width of a prefix given the number of Frames in the stack 
+        #
         def prefix_width
           w = FrameStack.items.size
           w.zero? ? 0 : w + 1
@@ -154,18 +249,41 @@ module Dev
 
           o = String.new
 
+          is_ci = ![0, '', nil].include?(ENV['CI'])
+
+          # Jumping around the line can cause some unwanted flashes
+          o << Dev::UI::ANSI.hide_cursor
+
+          if is_ci
+            # In CI, we can't use absolute horizontal positions because of timestamps.
+            # So we move around the line by offset from this cursor position.
+            o << Dev::UI::ANSI.cursor_save
+          else
+            # Outside of CI, we reset to column 1 so that things like ^C don't
+            # cause output misformatting.
+            o << "\r"
+          end
+
           o << color.code
           o << Dev::UI::Box::Heavy::HORZ * termwidth # draw a full line
-          o << Dev::UI::ANSI.cursor_horizontal_absolute(1 + prefix_start)
-          o << prefix
-          o << Dev::UI::ANSI.cursor_horizontal_absolute(1 + suffix_start)
-          o << suffix
+          o << print_at_x(prefix_start, prefix, is_ci)
+          o << color.code
+          o << print_at_x(suffix_start, suffix, is_ci)
           o << Dev::UI::Color::RESET.code
+          o << Dev::UI::ANSI.show_cursor
           o << "\n"
 
           o
         end
 
+        def print_at_x(x, str, is_ci)
+          if is_ci
+            Dev::UI::ANSI.cursor_restore + Dev::UI::ANSI.cursor_forward(x) + str
+          else
+            Dev::UI::ANSI.cursor_horizontal_absolute(1 + x) + str
+          end
+        end
+
         module FrameStack
           ENVVAR = 'DEV_FRAME_STACK'
 

data/lib/dev/ui/glyph.rb

@@ -3,9 +3,28 @@ require 'dev/ui'
 module Dev
   module UI
     class Glyph
-      MAP = {}
+      class InvalidGlyphHandle < ArgumentError
+        def initialize(handle)
+          @handle = handle
+        end
+
+        def message
+          keys = Glyph.available.join(',')
+          "invalid glyph handle: #{@handle} " \
+            "-- must be one of Dev::UI::Glyph.available (#{keys})"
+        end
+      end
 
       attr_reader :handle, :codepoint, :color, :char, :to_s, :fmt
+
+      # Creates a new glyph
+      #
+      # ==== Attributes
+      #
+      # * +handle+ - The handle in the +MAP+ constant
+      # * +codepoint+ - The codepoint used to create the glyph (e.g. +0x2717+ for a ballot X)
+      # * +color+ - What color to output the glyph. Check +Dev::UI::Color+ for options.
+      #
       def initialize(handle, codepoint, color)
         @handle    = handle
         @codepoint = codepoint
@@ -17,30 +36,36 @@ module Dev
         MAP[handle] = self
       end
 
-      STAR     = new('*', 0x2b51,  Color::YELLOW) # BLACK SMALL STAR
-      INFO     = new('i', 0x1d4be, Color::BLUE)   # MATHEMATICAL SCRIPT SMALL I
-      QUESTION = new('?', 0x003f,  Color::BLUE)   # QUESTION MARK
-      CHECK    = new('v', 0x2713,  Color::GREEN)  # CHECK MARK
-      X        = new('x', 0x2717,  Color::RED)    # BALLOT X
-
-      class InvalidGlyphHandle < ArgumentError
-        def initialize(handle)
-          @handle = handle
-        end
-
-        def message
-          keys = Glyph.available.join(',')
-          "invalid glyph handle: #{@handle} " \
-            "-- must be one of Dev::UI::Glyph.available (#{keys})"
-        end
-      end
+      # Mapping of glyphs to terminal output
+      MAP = {}
+      # YELLOw SMALL STAR (⭑)
+      STAR     = new('*', 0x2b51,  Color::YELLOW)
+      # BLUE MATHEMATICAL SCRIPT SMALL i (𝒾)
+      INFO     = new('i', 0x1d4be, Color::BLUE)
+      # BLUE QUESTION MARK (?)
+      QUESTION = new('?', 0x003f,  Color::BLUE)
+      # GREEN CHECK MARK (✓)
+      CHECK    = new('v', 0x2713,  Color::GREEN)
+      # RED BALLOT X (✗)
+      X        = new('x', 0x2717,  Color::RED)
 
+      # Looks up a glyph by name
+      #
+      # ==== Raises
+      # Raises a InvalidGlyphHandle if the glyph is not available
+      # You likely need to create it with +.new+ or you made a typo
+      #
+      # ==== Returns
+      # Returns a terminal output-capable string
+      #
       def self.lookup(name)
         MAP.fetch(name.to_s)
       rescue KeyError
         raise InvalidGlyphHandle, name
       end
 
+      # All available glyphs by name
+      #
       def self.available
         MAP.keys
       end

data/lib/dev/ui/interactive_prompt.rb

@@ -3,18 +3,40 @@ require 'io/console'
 module Dev
   module UI
     class InteractivePrompt
+      # Prompts the user with options
+      # 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/33797984-0ebb5e64-dcdf-11e7-9e7e-7204f279cece.gif
+      #
+      # ==== Example Usage:
+      #
+      # Ask an interactive question
+      #   Dev::UI::InteractivePrompt.call(%w(rails go python))
+      #
       def self.call(options)
         list = new(options)
         options[list.call - 1]
       end
 
+      # Initializes a new +InteractivePrompt+
+      # Usually called from +self.call+
+      #
+      # ==== Example Usage:
+      #
+      #   Dev::UI::InteractivePrompt.new(%w(rails go python))
+      #
       def initialize(options)
         @options = options
         @active = 1
         @marker = '>'
         @answer = nil
+        @state = :root
       end
 
+      # Calls the +InteractivePrompt+ and asks the question
+      # Usually used from +self.call+
+      #
       def call
         Dev::UI.raw { print(ANSI.hide_cursor) }
         while @answer.nil?
@@ -24,7 +46,8 @@ module Dev
           # This will put us back at the beginning of the options
           # When we redraw the options, they will be overwritten
           Dev::UI.raw do
-            @options.size.times { print(ANSI.previous_line) }
+            num_lines = @options.join("\n").split("\n").reject(&:empty?).size
+            num_lines.times { print(ANSI.previous_line) }
             print(ANSI.previous_line + ANSI.end_of_line + "\n")
           end
         end
@@ -39,47 +62,60 @@ module Dev
 
       private
 
+      ESC = "\e"
+
+      def up
+        @active = @active - 1 >= 1 ? @active - 1 : @options.length
+      end
+
+      def down
+        @active = @active + 1 <= @options.length ? @active + 1 : 1
+      end
+
+      def select_n(n)
+        @active = n
+        @answer = n
+      end
+
+      def select_bool(char)
+        return unless (@options - %w(yes no)).empty?
+        opt = @options.detect { |o| o.start_with?(char) }
+        @active = @options.index(opt) + 1
+        @answer = @options.index(opt) + 1
+      end
+
+      # rubocop:disable Style/WhenThen,Layout/SpaceBeforeSemicolon
       def wait_for_user_input
         char = read_char
-        char = char.chomp unless char.chomp.empty?
-        case char
-        when "\e[A", 'k'    # up
-          @active = @active - 1 >= 1 ? @active - 1 : @options.length
-        when "\e[B", 'j'    # down
-          @active = @active + 1 <= @options.length ? @active + 1 : 1
-        when " ", "\r"      # enter/select
-          @answer = @active
-        when ('1'..@options.size.to_s)
-          @active = char.to_i
-          @answer = char.to_i
-        when 'y', 'n'
-          return unless (@options - %w(yes no)).empty?
-          opt = @options.detect { |o| o.start_with?(char) }
-          @active = @options.index(opt) + 1
-          @answer = @options.index(opt) + 1
-        when "\u0003", "\e" # Control-C or escape
-          raise Interrupt
+        case @state
+        when :root
+          case char
+          when ESC                       ; @state = :esc
+          when 'k'                       ; up
+          when 'j'                       ; down
+          when ('1'..@options.size.to_s) ; select_n(char.to_i)
+          when 'y', 'n'                  ; select_bool(char)
+          when " ", "\r", "\n"           ; @answer = @active # <enter>
+          when "\u0003"                  ; raise Interrupt   # Ctrl-c
+          end
+        when :esc
+          case char
+          when '[' ; @state = :esc_bracket
+          else     ; raise Interrupt # unhandled escape sequence.
+          end
+        when :esc_bracket
+          @state = :root
+          case char
+          when 'A' ; up
+          when 'B' ; down
+          else     ; raise Interrupt # unhandled escape sequence.
+          end
         end
       end
+      # rubocop:enable Style/WhenThen,Layout/SpaceBeforeSemicolon
 
-      # Will handle 2-3 character sequences like arrow keys and control-c
       def read_char
-        raw_tty! do
-          input = $stdin.getc.chr
-          return input unless input == "\e"
-
-          input << begin
-              $stdin.read_nonblock(3)
-            rescue
-              ''
-            end
-          input << begin
-              $stdin.read_nonblock(2)
-            rescue
-              ''
-            end
-          input
-        end
+        raw_tty! { $stdin.getc.chr }
       rescue IOError
         "\e"
       end
@@ -95,8 +131,15 @@ module Dev
       def render_options
         @options.each_with_index do |choice, index|
           num = index + 1
-          message = "  #{num}. {{bold:#{choice}}}"
-          message = "{{blue:> #{message.strip}}}" if num == @active
+          message = "  #{num}."
+          message += choice.split("\n").map { |l| " {{bold:#{l}}}" }.join("\n")
+
+          if num == @active
+            message = message.split("\n").map.with_index do |l, idx|
+              idx == 0 ? "{{blue:> #{l.strip}}}" : "{{blue:>#{l.strip}}}"
+            end.join("\n")
+          end
+
           Dev::UI.with_frame_color(:blue) do
             puts Dev::UI.fmt(message)
           end