highline 2.0.0.pre.develop.2 → 2.0.0.pre.develop.4

data/lib/highline/style.rb

@@ -1,48 +1,77 @@
 # coding: utf-8
 
 #--
-# color_scheme.rb
+# originally color_scheme.rb
 #
 # Created by Richard LeBer on 2011-06-27.
 # Copyright 2011.  All rights reserved
 #
 # This is Free Software.  See LICENSE and COPYING for details
 
+
 class HighLine
 
+  # Creates a style using {.find_or_create_style} or
+  # {.find_or_create_style_list}
+  # @param args [Array<Style, Hash, String>] style properties
+  # @return [Style]
   def self.Style(*args)
     args = args.compact.flatten
     if args.size==1
-      arg = args.first
-      if arg.is_a?(Style)
-        Style.list[arg.name] || Style.index(arg)
-      elsif arg.is_a?(::String) && arg =~ /^\e\[/ # arg is a code
-        if styles = Style.code_index[arg]
-          styles.first
-        else
-          Style.new(:code=>arg)
-        end
-      elsif style = Style.list[arg]
-        style
-      elsif HighLine.color_scheme && HighLine.color_scheme[arg]
-        HighLine.color_scheme[arg]
-      elsif arg.is_a?(Hash)
-        Style.new(arg)
-      elsif arg.to_s.downcase =~ /^rgb_([a-f0-9]{6})$/
-        Style.rgb($1)
-      elsif arg.to_s.downcase =~ /^on_rgb_([a-f0-9]{6})$/
-        Style.rgb($1).on
+      find_or_create_style(args.first)
+    else
+      find_or_create_style_list(*args)
+    end
+  end
+
+  # Search for a Style with the given properties and return it.
+  # If there's no matched Style, it creates one.
+  # You can pass a Style, String or a Hash.
+  # @param arg [Style, String, Hash] style properties
+  # @return [Style] found or creted Style
+  def self.find_or_create_style(arg)
+    if arg.is_a?(Style)
+      Style.list[arg.name] || Style.index(arg)
+    elsif arg.is_a?(::String) && arg =~ /^\e\[/ # arg is a code
+      if styles = Style.code_index[arg]
+        styles.first
       else
-        raise NameError, "#{arg.inspect} is not a defined Style"
+        Style.new(:code=>arg)
       end
+    elsif style = Style.list[arg]
+      style
+    elsif HighLine.color_scheme && HighLine.color_scheme[arg]
+      HighLine.color_scheme[arg]
+    elsif arg.is_a?(Hash)
+      Style.new(arg)
+    elsif arg.to_s.downcase =~ /^rgb_([a-f0-9]{6})$/
+      Style.rgb($1)
+    elsif arg.to_s.downcase =~ /^on_rgb_([a-f0-9]{6})$/
+      Style.rgb($1).on
     else
-      name = args
-      Style.list[name] || Style.new(:list=>args)
+      raise NameError, "#{arg.inspect} is not a defined Style"
     end
   end
 
+  # Find a Style list or create a new one.
+  # @param args [Array<Symbol>] an Array of Symbols of each style
+  #   that will be on the style list.
+  # @return [Style] Style list
+  # @example Creating a Style list of the combined RED and BOLD styles.
+  #   style_list = HighLine.find_or_create_style_list(:red, :bold)
+
+  def self.find_or_create_style_list(*args)
+    name = args
+    Style.list[name] || Style.new(:list=>args)
+  end
+
+  # ANSI styles to be used by HighLine.
   class Style
 
+    # Index the given style.
+    # Uses @code_index (Hash) as repository.
+    # @param style [Style]
+    # @return [Style] the given style
     def self.index(style)
       if style.name
         @styles ||= {}
@@ -57,6 +86,9 @@ class HighLine
       style
     end
 
+    # Clear all custom Styles, restoring the Style index to
+    # builtin styles only.
+    # @return [void]
     def self.clear_index
       # reset to builtin only styles
       @styles = list.select { |name, style| style.builtin }
@@ -64,16 +96,40 @@ class HighLine
       @styles.each { |name, style| index(style) }
     end
 
+    # Converts all given color codes to hexadecimal and
+    # join them in a single string. If any given color code
+    # is already a String, doesn't perform any convertion.
+    #
+    # @param colors [Array<Numeric, String>] color codes
+    # @return [String] all color codes joined
+    # @example
+    #   HighLine::Style.rgb_hex(9, 10, "11") # => "090a11"
     def self.rgb_hex(*colors)
       colors.map do |color|
         color.is_a?(Numeric) ? '%02x'%color : color.to_s
       end.join
     end
 
+    # Split an rgb code string into its 3 numerical compounds.
+    # @param hex [String] rgb code string like "010F0F"
+    # @return [Array<Numeric>] numerical compounds like [1, 15, 15]
+    # @example
+    #   HighLine::Style.rgb_parts("090A0B") # => [9, 10, 11]
+
     def self.rgb_parts(hex)
       hex.scan(/../).map{|part| part.to_i(16)}
     end
 
+    # Search for or create a new Style from the colors provided.
+    # @param colors (see .rgb_hex)
+    # @return [Style] a Style with the rgb colors provided.
+    # @example Creating a new Style based on rgb code
+    #   rgb_style = HighLine::Style.rgb(9, 10, 11)
+    #
+    #   rgb_style.name #  => :rgb_090a0b
+    #   rgb_style.code #  => "\e[38;5;16m"
+    #   rgb_style.rgb  #  => [9, 10, 11]
+    #
     def self.rgb(*colors)
       hex = rgb_hex(*colors)
       name = ('rgb_' + hex).to_sym
@@ -85,34 +141,58 @@ class HighLine
       end
     end
 
+    # Returns the rgb number to be used as escape code on ANSI terminals.
+    # @param parts [Array<Numeric>] three numerical codes for red, green and blue
+    # @return [Numeric] to be used as escape code on ANSI terminals
     def self.rgb_number(*parts)
       parts = parts.flatten
       16 + parts.inject(0) {|kode, part| kode*6 + (part/256.0*6.0).floor}
     end
 
+    # From an ANSI number (color escape code), craft an 'rgb_hex' code of it
+    # @param ansi_number [Integer] ANSI escape code
+    # @return [String] all color codes joined as {.rgb_hex}
     def self.ansi_rgb_to_hex(ansi_number)
       raise "Invalid ANSI rgb code #{ansi_number}" unless (16..231).include?(ansi_number)
       parts = (ansi_number-16).to_s(6).rjust(3,'0').scan(/./).map{|d| (d.to_i*255.0/6.0).ceil}
       rgb_hex(*parts)
     end
 
+    # @return [Hash] list of all cached Styles
     def self.list
       @styles ||= {}
     end
 
+    # @return [Hash] list of all cached Style codes
     def self.code_index
       @code_index ||= {}
     end
 
+    # Remove any ANSI color escape sequence of the given String.
+    # @param string [String]
+    # @return [String] 
     def self.uncolor(string)
       string.gsub(/\e\[\d+(;\d+)*m/, '')
     end
 
-    attr_reader :name, :list
-    attr_accessor :rgb, :builtin
+    # Style name
+    # @return [Symbol] the name of the Style
+    attr_reader :name
+
+    # When a compound Style, returns a list of its components.
+    # @return [Array<Symbol>] components of a Style list
+    attr_reader :list
+
+    # @return [Array] the three numerical rgb codes. Ex: [10, 12, 127]
+    attr_accessor :rgb
+
+    # @return [Boolean] true if the Style is builtin or not.
+    attr_accessor :builtin
 
     # Single color/styles have :name, :code, :rgb (possibly), :builtin
     # Compound styles have :name, :list, :builtin
+    #
+    # @param defn [Hash] options for the Style to be created.
     def initialize(defn = {})
       @definition = defn
       @name    = defn[:name]
@@ -129,18 +209,27 @@ class HighLine
       self.class.index self unless defn[:no_index]
     end
 
+    # Duplicate current Style using the same definition used to create it.
+    # @return [Style] duplicated Style
     def dup
       self.class.new(@definition)
     end
 
+    # @return [Hash] the definition used to create this Style
     def to_hash
       @definition
     end
 
+    # Uses the Style definition to add ANSI color escape codes
+    # to a a given String
+    # @param string [String] to be colored
+    # @return [String] an ANSI colored string
     def color(string)
       code + string + HighLine::CLEAR
     end
 
+    # @return [String] all codes of the Style list joined together (if a Style list)
+    # @return [String] the Style code
     def code
       if @list
         @list.map{|element| HighLine.Style(element).code}.join
@@ -149,18 +238,25 @@ class HighLine
       end
     end
 
+    # @return [Integer] the RED component of the rgb code
     def red
       @rgb && @rgb[0]
     end
 
+    # @return [Integer] the GREEN component of the rgb code
     def green
       @rgb && @rgb[1]
     end
 
+    # @return [Integer] the BLUE component of the rgb code
     def blue
       @rgb && @rgb[2]
     end
 
+    # Duplicate Style with some minor changes
+    # @param new_name [Symbol]
+    # @param options [Hash] Style attributes to be changed
+    # @return [Style] new Style with changed attributes
     def variant(new_name, options={})
       raise "Cannot create a variant of a style list (#{inspect})" if @list
       new_code = options[:code] || code
@@ -172,15 +268,19 @@ class HighLine
       self.class.new(self.to_hash.merge(:name=>new_name, :code=>new_code, :rgb=>new_rgb))
     end
 
+    # Uses the color as background and return a new style.
+    # @return [Style]
     def on
       new_name = ('on_'+@name.to_s).to_sym
       self.class.list[new_name] ||= variant(new_name, :increment=>10)
     end
 
+    # @return [Style] a brighter version of this Style
     def bright
       create_bright_variant(:bright)
     end
 
+    # @return [Style] a lighter version of this Style
     def light
       create_bright_variant(:light)
     end

data/lib/highline/template_renderer.rb

@@ -3,13 +3,29 @@
 require 'forwardable'
 
 class HighLine
+  # Renders an erb template taking a {Question} and a {HighLine} instance
+  # as context.
   class TemplateRenderer
     extend Forwardable
 
     def_delegators :@highline, :color, :list, :key
     def_delegators :@source, :answer_type, :prompt, :header, :answer
 
-    attr_reader :template, :source, :highline
+    # @return [ERB] ERB template being rendered
+    attr_reader :template
+
+    # @return [Question, Menu] Question instance used as context
+    attr_reader :source
+
+    # @return [HighLine] HighLine instance used as context
+    attr_reader :highline
+
+    # Initializes the TemplateRenderer object with its template and
+    # HighLine and Question contexts.
+    #
+    # @param template [ERB] ERB template.
+    # @param source [Question] question object.
+    # @param highline [HighLine] HighLine instance.
 
     def initialize(template, source, highline)
       @template = template
@@ -17,20 +33,28 @@ class HighLine
       @highline = highline
     end
 
+    # @return [String] rendered template
     def render
       template.result(binding)
     end
 
+    # Returns an error message when the called method
+    # is not available.
+    # @return [String] error message.
     def method_missing(method, *args)
       "Method #{method} with args #{args.inspect} " +
       "is not available on #{self.inspect}. " +
       "Try #{methods(false).sort.inspect}"
     end
 
+    # @return [Question, Menu] {#source} attribute.
     def menu
       source
     end
 
+    # If some constant is missing at this TemplateRenderer instance,
+    # get it from HighLine. Useful to get color and style contants.
+    # @param name [Symbol] automatically passed constant's name as Symbol
     def self.const_missing(name)
       HighLine.const_get(name)
     end

data/lib/highline/terminal.rb

@@ -12,7 +12,14 @@
 require "highline/compatibility"
 
 class HighLine
+  # Basic Terminal class which HighLine will direct
+  # input and output to.
+  # The specialized Terminals all decend from this HighLine::Terminal class
   class Terminal
+
+    # Probe for and return a suitable Terminal instance
+    # @param input [IO] input stream
+    # @param output [IO] output stream
     def self.get_terminal(input, output)
       terminal = nil
 
@@ -34,22 +41,37 @@ class HighLine
       terminal
     end
 
-    attr_reader :input, :output
+    # @return [IO] input stream
+    attr_reader :input
+
+    # @return [IO] output stream
+    attr_reader :output
 
+    # Creates a terminal instance based on given input and output streams.
+    # @param input [IO] input stream
+    # @param output [IO] output stream
     def initialize(input, output)
       @input  = input
       @output = output
     end
 
+    # An initialization callback.
+    # It is called by {.get_terminal}.
     def initialize_system_extensions
     end
 
+    # @return [Array<Integer, Integer>] two value terminal
+    #   size like [columns, lines]
     def terminal_size
+      [80, 24]
     end
 
+    # Enter Raw No Echo mode.
     def raw_no_echo_mode
     end
 
+    # Yieds a block to be executed in Raw No Echo mode and
+    # then restore the terminal state.
     def raw_no_echo_mode_exec
       raw_no_echo_mode
       yield
@@ -57,22 +79,123 @@ class HighLine
       restore_mode
     end
 
+    # Restore terminal to its default mode
     def restore_mode
     end
 
+    # Get one character from the terminal
+    # @return [String] one character
     def get_character
     end
 
+    # Get one line from the terminal and format accordling.
+    # Use readline if question has readline mode set.
+    # @param question [HighLine::Question]
+    # @param highline [HighLine]
+    # @param options [Hash]
+    def get_line(question, highline, options={})
+      raw_answer =
+      if question.readline
+        get_line_with_readline(question, highline, options={})
+      else
+        get_line_default(highline)
+      end
+
+      question.format_answer(raw_answer)
+    end
+
+    # Get one line using #readline_read
+    # @param (see #get_line)
+    def get_line_with_readline(question, highline, options={})
+      require "readline"    # load only if needed
+
+      question_string = highline.render_statement(question)
+
+      raw_answer = readline_read(question_string, question)
+
+      if !raw_answer and highline.track_eof?
+        raise EOFError, "The input stream is exhausted."
+      end
+
+      raw_answer || ""
+    end
+
+    # Use readline to read one line
+    # @param prompt [String] Readline prompt
+    # @param question [HighLine::Question] question from where to get
+    #   autocomplete candidate strings
+    def readline_read(prompt, question)
+      # prep auto-completion
+      unless question.selection.empty?
+        Readline.completion_proc = lambda do |str|
+          question.selection.grep(/\A#{Regexp.escape(str)}/)
+        end
+      end
+
+      # work-around ugly readline() warnings
+      old_verbose = $VERBOSE
+      $VERBOSE    = nil
+
+      raw_answer  = run_preserving_stty do
+        Readline.readline(prompt, true)
+      end
+
+      $VERBOSE    = old_verbose
+
+      raw_answer
+    end
+
+    # Get one line from terminal using default #gets method.
+    # @param highline (see #get_line)
+    def get_line_default(highline)
+      raise EOFError, "The input stream is exhausted." if highline.track_eof? and
+                                                            highline.input.eof?
+      highline.input.gets
+    end
+
+    # @!group Enviroment queries
+
+    # Running on JRuby?
     def jruby?
       defined?(RUBY_ENGINE) && RUBY_ENGINE == 'jruby'
     end
 
+    # Running on Rubinius?
     def rubinius?
       defined?(RUBY_ENGINE) && RUBY_ENGINE == 'rbx'
     end
 
+    # Running on Windows?
     def windows?
       defined?(RUBY_PLATFORM) && (RUBY_PLATFORM =~ /mswin|mingw|cygwin/)
     end
+
+    # @!endgroup
+
+    # Returns the class name as String. Useful for debuggin.
+    # @return [String] class name. Ex: "HighLine::Terminal::IOConsole"
+    def character_mode
+      self.class.name
+    end
+
+    private
+
+    # Yield a block using stty shell commands to preserve the terminal state.
+    def run_preserving_stty
+      save_stty
+      yield
+    ensure
+      restore_stty
+    end
+
+    # Saves terminal state using shell stty command.
+    def save_stty
+      @stty_save = `stty -g`.chomp rescue nil
+    end
+
+    # Restores terminal state using shell stty command.
+    def restore_stty
+      system("stty", @stty_save) if @stty_save
+    end
   end
 end