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

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 7f330e1d4093d9a373e0471827e2acdf89076eac
-  data.tar.gz: 1bba362856956f240a80312fe26e74966790b783
+  metadata.gz: fe7f4a2acbc139058d22c6e720cf45f3d8807278
+  data.tar.gz: 4a2e208bb898d2498f5911efaa695095341cb43c
 SHA512:
-  metadata.gz: 36049605dccd8943c87037214ca65c02feab5ead5f1ca4579ba5491b0b8b966c9a49377c40f9fb99d53bd5a63ea86ef664c55cae40158cc53bef31b4413249cf
-  data.tar.gz: fdd91732e30725625a9197226d70d2a8bf99002c3a029094617bbed2048a3dadc93a3f95012eca5a87a0ca3f0f69ac5fb9007a3afc48cc6d253afaa81b4236d9
+  metadata.gz: 3f276ad26eb858d757254770be10c6a007b0c4032078ef7f750b677499ed19c43315b0518d802480fd3cb9b8f2804286bdfd255ea647a85f5209be312dd8ab90
+  data.tar.gz: ab6323e8a8a16a5912328700cb207ca9009a60f05772102bf643db3ca8dd4b21dc7a527d79aad8113cbb32f2d6a1ed66297220d3faf86c3ca43d8befa85a8034

data/Changelog.md

@@ -2,6 +2,34 @@
 
 Below is a complete listing of changes for each revision of HighLine.
 
+### 2.0.0-develop.4 / 2015-12-14
+This versions makes the code documentation 100% 'A' grade on inch.
+We have used inch and http://inch-ci.org to guide the priorities
+on documentation production.
+
+The grade 'A' (on inch) number of objects on master branch was 44,22% (153/346).
+After this PR we have a 100% grade 'A' (344 objects).
+
+There's already a inch-ci.org badge on README.md. And now it's all green!
+
+We also bring some improvement on CodeClimate scores.
+
+#### CHANGES SUMMARY
+
+* PR #179 - Make inch happy. Grade "A" for the whole HighLine documentation. By Abinoam Jr. (@abinoam)
+* PR #178 - Improve score on Code Climate by applying some refactoring. By Abinoam Jr. (@abinoam)
+* PR #172 - Initial work on documentation by Abinoam Jr. (@abinoam)
+  * Use yard
+  * Use inch
+  * New Readme file
+* Fix #166 with PR #173 by (@matugm)
+
+
+### 2.0.0-develop.3 / 2015-10-28
+
+This version brings some improvements on documentation (switch to Yardoc).
+This is the first 2.0.0-develop.x version to be release as gem.
+
 ### 2.0.0-develop.2 / 2015-09-09
 
 (by Abinoam P. Marques Jr. - @abinoam)

data/README.md

@@ -0,0 +1,188 @@
+HighLine
+========
+
+[![Build Status](https://travis-ci.org/JEG2/highline.svg?branch=master)](https://travis-ci.org/JEG2/highline)
+[![Build status](https://ci.appveyor.com/api/projects/status/4p05fijpah77d28x/branch/master?svg=true)](https://ci.appveyor.com/project/JEG2/highline/branch/master)
+[![Gem Version](https://badge.fury.io/rb/highline.svg)](https://badge.fury.io/rb/highline)
+[![Code Climate](https://codeclimate.com/github/JEG2/highline/badges/gpa.svg)](https://codeclimate.com/github/JEG2/highline)
+[![Test Coverage](https://codeclimate.com/github/JEG2/highline/badges/coverage.svg)](https://codeclimate.com/github/JEG2/highline/coverage)
+[![Inline docs](http://inch-ci.org/github/JEG2/highline.svg?branch=master)](http://inch-ci.org/github/JEG2/highline)
+
+Description
+-----------
+
+Welcome to HighLine.
+
+HighLine was designed to ease the tedious tasks of doing console input and
+output with low-level methods like ```gets``` and ```puts```. HighLine provides a
+robust system for requesting data from a user, without needing to code all the
+error checking and validation rules and without needing to convert the typed
+Strings into what your program really needs.  Just tell HighLine what you're
+after, and let it do all the work.
+
+Documentation
+-------------
+
+See: [Rubydoc.info for HighLine](http://www.rubydoc.info/github/JEG2/highline/master).
+Specially [HighLine](http://www.rubydoc.info/github/JEG2/highline/master/HighLine) and [HighLine::Question](http://www.rubydoc.info/github/JEG2/highline/master/HighLine/Question).
+
+Usage
+-----
+
+```ruby
+
+require 'highline'
+
+# Basic usage
+
+cli = HighLine.new
+answer = cli.ask "What do you think?"
+puts "You have answered: #{answer}"
+
+
+# Default answer
+
+cli.ask("Company?  ") { |q| q.default = "none" }
+
+
+# Validation
+
+cli.ask("Age?  ", Integer) { |q| q.in = 0..105 }
+cli.ask("Name?  (last, first)  ") { |q| q.validate = /\A\w+, ?\w+\Z/ }
+
+
+# Type conversion for answers:
+
+cli.ask("Birthday?  ", Date)
+cli.ask("Interests?  (comma sep list)  ", lambda { |str| str.split(/,\s*/) })
+
+
+# Reading passwords:
+
+cli.ask("Enter your password:  ") { |q| q.echo = false }
+cli.ask("Enter your password:  ") { |q| q.echo = "x" }
+
+
+# ERb based output (with HighLine's ANSI color tools):
+
+cli.say("This should be <%= color('bold', BOLD) %>!")
+
+
+# Menus:
+
+cli.choose do |menu|
+  menu.prompt = "Please choose your favorite programming language?  "
+  menu.choice(:ruby) { say("Good choice!") }
+  menu.choices(:python, :perl) { say("Not from around here, are you?") }
+end
+```
+
+If you want to save some characters, you can inject/import HighLine methods on Kernel by doing the following. Just be sure to avoid name collisions in the top-level namespace.
+
+
+```ruby
+require 'highline/import'
+
+say "Now you can use #say directly"
+```
+
+For more examples see the examples/ directory of this project.
+
+Requirements
+------------
+
+HighLine from version >= 1.7.0 requires ruby >= 1.9.3
+
+Installing
+----------
+
+To install HighLine, use the following command:
+
+```sh
+$ gem install highline
+```
+
+(Add `sudo` if you're installing under a POSIX system as root)
+
+If you're using [Bundler](http://bundler.io/), add this to your Gemfile:
+
+```ruby
+source "https://rubygems.org"
+gem 'highline'
+```
+
+And then run:
+
+```sh
+$ bundle
+```
+
+If you want to build the gem locally, use the following command from the root of the sources:
+
+```sh
+$ rake package
+```
+
+You can also build and install directly:
+
+```sh
+$ rake install
+```
+
+Contributing
+------------
+
+1. Open an issue
+  - https://github.com/JEG2/highline/issues
+
+2. Fork the repository
+  - https://github.com/JEG2/highline/fork
+
+3. Clone it locally
+  - ```git clone git@github.com:YOUR-USERNAME/highline.git```
+
+4. Add the main HighLine repository as the __upstream__ remote
+  - ```cd highline``` # to enter the cloned repository directory.
+  - ```git remote add -v upstream https://github.com/JEG2/highline```
+
+5. Keep your fork in sync with __upstream__
+  - ```git fetch upstream```
+  - ```git checkout master```
+  - ```git merge upstream/master```
+
+6. Create your feature branch
+  - ```git checkout -b your_branch```
+
+7. Hack the source code and run the tests
+  - ```rake test```
+  - ```rake acceptance```
+
+8. Commit your changes
+  - ```git commit -am "Your commit message"```
+
+9. Push it
+  - ```git push```
+
+10. Open a pull request
+  - https://github.com/JEG2/highline/pulls
+
+Details on:
+
+* GitHub Guide to Contributing to Open Source - https://guides.github.com/activities/contributing-to-open-source/
+* GitHub issues - https://guides.github.com/features/issues/
+* Forking - https://help.github.com/articles/fork-a-repo/
+* Cloning - https://help.github.com/articles/cloning-a-repository/
+* Adding upstream - https://help.github.com/articles/configuring-a-remote-for-a-fork/
+* Syncing your fork - https://help.github.com/articles/syncing-a-fork/
+* Branching - https://git-scm.com/book/en/v2/Git-Branching-Basic-Branching-and-Merging
+* Commiting - https://git-scm.com/book/en/v2/Git-Basics-Recording-Changes-to-the-Repository
+* Pushing - https://git-scm.com/book/en/v2/Git-Basics-Working-with-Remotes
+
+The Core HighLine Team
+----------------------
+
+* [James Edward Gray II](https://github.com/JEG2) - Author
+* [Gregory Brown](https://github.com/practicingruby) - Core contributor
+* [Abinoam P. Marques Jr.](https://github.com/abinoam) - Core contributor
+
+_For a list of people who have contributed to the codebase, see [GitHub's list of contributors](https://github.com/JEG2/highline/contributors)._

data/Rakefile

@@ -1,4 +1,3 @@
-require "rdoc/task"
 require "rake/testtask"
 require "rubygems/package_task"
 require "bundler/gem_tasks"
@@ -15,16 +14,6 @@ Rake::TestTask.new do |test|
   test.test_files = FileList['test/test*.rb']
 end
 
-RDoc::Task.new do |rdoc|
-  rdoc.rdoc_files.include( "README.rdoc", "INSTALL",
-                           "TODO", "Changelog.md",
-                           "AUTHORS", "COPYING",
-                           "LICENSE", "lib/**/*.rb")
-  rdoc.main     = "README.rdoc"
-  rdoc.rdoc_dir = "doc/html"
-  rdoc.title    = "HighLine Documentation"
-end
-
 Gem::PackageTask.new(SPEC) do |package|
   # do nothing:  I just need a gem but this block is required
 end

data/highline.gemspec

@@ -13,10 +13,8 @@ SPEC = Gem::Specification.new do |spec|
   spec.files    = `git ls-files`.split("\n")
 
   spec.test_files       =  `git ls-files -- test/*.rb`.split("\n")
-  spec.has_rdoc         =  true
-  spec.extra_rdoc_files =  %w[README.rdoc INSTALL TODO Changelog.md LICENSE]
-  spec.rdoc_options     << '--title' << 'HighLine Documentation' <<
-                           '--main'  << 'README'
+  spec.has_rdoc         =  'yard'
+  spec.extra_rdoc_files =  %w[README.md TODO Changelog.md LICENSE]
 
   spec.require_path      = 'lib'
 

data/lib/highline.rb

@@ -29,12 +29,17 @@ require "highline/builtin_styles"
 #
 # A HighLine object is a "high-level line oriented" shell over an input and an
 # output stream.  HighLine simplifies common console interaction, effectively
-# replacing puts() and gets().  User code can simply specify the question to ask
+# replacing {Kernel#puts} and {Kernel#gets}.  User code can simply specify the question to ask
 # and any details about user interaction, then leave the rest of the work to
-# HighLine.  When HighLine.ask() returns, you'll have the answer you requested,
+# HighLine.  When {HighLine#ask} returns, you'll have the answer you requested,
 # even if HighLine had to ask many times, validate results, perform range
 # checking, convert types, etc.
 #
+# @example Basic usage
+#   cli = HighLine.new
+#   answer = cli.ask "What do you think?"
+#   puts "You have answered: #{answer}"
+
 class HighLine
   include BuiltinStyles
   include CustomErrors
@@ -72,6 +77,7 @@ class HighLine
     @track_eof
   end
 
+  # (see HighLine.track_eof?)
   def track_eof?
     self.class.track_eof?
   end
@@ -101,14 +107,22 @@ class HighLine
     reset_color_scheme
   end
 
+  # Reset color scheme to default (+nil+)
   def self.reset_color_scheme
     self.color_scheme = nil
   end
 
   #
-  # Create an instance of HighLine, connected to the streams _input_
-  # and _output_.
+  # Create an instance of HighLine connected to the given _input_
+  # and _output_ streams.
   #
+  # @param input [IO] the default input stream for HighLine.
+  # @param output [IO] the default output stream for HighLine.
+  # @param wrap_at [Integer] all statements outputed through
+  #   HighLine will be wrapped to this column size if set.
+  # @param page_at [Integer] page size and paginating.
+  # @param indent_size [Integer] indentation size in spaces.
+  # @param indent_level [Integer] how deep is indentated.
   def initialize( input = $stdin, output = $stdout,
                   wrap_at = nil, page_at = nil, indent_size=3, indent_level=0 )
     @input   = input
@@ -128,24 +142,38 @@ class HighLine
     @terminal = HighLine::Terminal.get_terminal(input, output)
   end
 
-  # The current column setting for wrapping output.
+  # @return [Integer] The current column setting for wrapping output.
   attr_reader :wrap_at
-  # The current row setting for paging output.
+
+  # @return [Integer] The current row setting for paging output.
   attr_reader :page_at
-  # Indentation over multiple lines
+
+  # @return [Boolean] Indentation over multiple lines
   attr_accessor :multi_indent
-  # The indentation size
+
+  # @return [Integer] The indentation size in characters
   attr_accessor :indent_size
-  # The indentation level
+
+  # @return [Integer] The indentation level
   attr_accessor :indent_level
 
-  attr_reader :input, :output
+  # @return [IO] the default input stream for a HighLine instance
+  attr_reader :input
 
+  # @return [IO] the default output stream for a HighLine instance
+  attr_reader :output
+
+  # When gathering a Hash with {QuestionAsker#gather_hash},
+  # it tracks the current key being asked.
+  #
+  # @todo We should probably move this into the HighLine::Question
+  #   object.
   attr_accessor :key
 
   # System specific that responds to #initialize_system_extensions,
   # #terminal_size, #raw_no_echo_mode, #restore_mode, #get_character.
   # It polymorphically handles specific cases for different platforms.
+  # @return [HighLine::Terminal]
   attr_reader :terminal
 
   #
@@ -157,6 +185,9 @@ class HighLine
   #
   # Raises EOFError if input is exhausted.
   #
+  # @param yes_or_no_question [String] a question that accepts yes and no as answers
+  # @param character [Boolean, :getc] character mode to be passed to Question#character
+  # @see Question#character
   def agree( yes_or_no_question, character = nil )
     ask(yes_or_no_question, lambda { |yn| yn.downcase[0] == ?y}) do |q|
       q.validate                 = /\Ay(?:es)?|no?\Z/i
@@ -172,12 +203,14 @@ class HighLine
   # This method is the primary interface for user input.  Just provide a
   # _question_ to ask the user, the _answer_type_ you want returned, and
   # optionally a code block setting up details of how you want the question
-  # handled.  See HighLine.say() for details on the format of _question_, and
-  # HighLine::Question for more information about _answer_type_ and what's
+  # handled.  See {#say} for details on the format of _question_, and
+  # {Question} for more information about _answer_type_ and what's
   # valid in the code block.
   #
   # Raises EOFError if input is exhausted.
   #
+  # @param (see Question.build)
+  # @return answer converted to the class in answer_type
   def ask(template_or_question, answer_type = nil, &details)
     question = Question.build(template_or_question, answer_type, &details)
 
@@ -203,6 +236,9 @@ class HighLine
   #
   # Raises EOFError if input is exhausted.
   #
+  # @param items [Array<String>]
+  # @param details [Proc] to be passed to Menu.new
+  # @return [String] answer
   def choose( *items, &details )
     menu = Menu.new(&details)
     menu.choices(*items) unless items.empty?
@@ -210,21 +246,9 @@ class HighLine
     # Set auto-completion
     menu.completion = menu.options
 
-    shell_style_lambda = lambda do |command|    # shell-style selection
-      first_word = command.to_s.split.first || ""
-
-      options = menu.options
-      options.extend(OptionParser::Completion)
-      answer = options.complete(first_word)
-
-      raise Question::NoAutoCompleteMatch unless answer
-
-      [answer.last, command.sub(/^\s*#{first_word}\s*/, "")]
-    end
-
     # Set _answer_type_ so we can double as the Question for ask().
     # menu.option = normal menu selection, by index or name
-    menu.answer_type = menu.shell ? shell_style_lambda : menu.options
+    menu.answer_type = menu.shell ? shell_style_lambda(menu) : menu.options
 
     selected = ask(menu)
 
@@ -235,6 +259,24 @@ class HighLine
     end
   end
 
+  # Convenience method to craft a lambda suitable for
+  # beind used in autocompletion operations by {#choose}
+  # @return [lambda] lambda to be used in autocompletion operations
+
+  def shell_style_lambda(menu)
+    lambda do |command|    # shell-style selection
+      first_word = command.to_s.split.first || ""
+
+      options = menu.options
+      options.extend(OptionParser::Completion)
+      answer = options.complete(first_word)
+
+      raise Question::NoAutoCompleteMatch unless answer
+
+      [answer.last, command.sub(/^\s*#{first_word}\s*/, "")]
+    end
+  end
+
   #
   # This method provides easy access to ANSI color sequences, without the user
   # needing to remember to CLEAR at the end of each sequence.  Just pass the
@@ -246,36 +288,65 @@ class HighLine
   # This method returns the original _string_ unchanged if HighLine::use_color?
   # is +false+.
   #
+  # @param string [String] string to be colored
+  # @param colors [Array<Symbol>] array of colors like [:red, :blue]
+  # @return [String] (ANSI escaped) colored string
+  # @example
+  #    HighLine.color("Sustainable", :green, :bold)
+  #    # => "\e[32m\e[1mSustainable\e[0m"
   def self.color( string, *colors )
     return string unless self.use_color?
     Style(*colors).color(string)
   end
 
-  # In case you just want the color code, without the embedding and the CLEAR
+  # (see .color)
+  # Convenience instance method. It delegates to the class method.
+  def color(string, *colors)
+    self.class.color(string, *colors)
+  end
+
+  # In case you just want the color code, without the embedding and
+  # the CLEAR sequence.
+  #
+  # @param colors [Array<Symbol>]
+  # @return [String] ANSI escape code for the given colors.
+  #
+  # @example
+  #   s = HighLine.Style(:red, :blue)
+  #   s.code # => "\e[31m\e[34m"
+  #
+  #   HighLine.color_code(:red, :blue) # => "\e[31m\e[34m"
+
   def self.color_code(*colors)
     Style(*colors).code
   end
 
-  # Works as an instance method, same as the class method
+  # (see HighLine.color_code)
+  # Convenience instance method. It delegates to the class method.
   def color_code(*colors)
     self.class.color_code(*colors)
   end
 
-  # Works as an instance method, same as the class method
-  def color(*args)
-    self.class.color(*args)
-  end
-
-  # Remove color codes from a string
+  # Remove color codes from a string.
+  # @param string [String] to be decolorized
+  # @return [String] without the ANSI escape sequence (colors)
   def self.uncolor(string)
     Style.uncolor(string)
   end
 
-  # Works as an instance method, same as the class method
+  # (see .uncolor)
+  # Convenience instance method. It delegates to the class method.
+
   def uncolor(string)
     self.class.uncolor(string)
   end
 
+  # Renders a list of itens using a {ListRenderer}
+  # @param items [Array]
+  # @param mode [Symbol]
+  # @param option
+  # @return [String]
+  # @see ListRenderer#initialize ListRenderer#initialize for parameter details
   def list(items, mode = :rows, option = nil)
     ListRenderer.new(items, mode, option, self).render
   end
@@ -290,6 +361,7 @@ class HighLine
   # instance's binding for providing easy access to the ANSI color constants
   # and the HighLine#color() method.
   #
+  # @param statement [Statement, String] what to be said
   def say(statement)
     statement = render_statement(statement)
     return if statement.empty?
@@ -306,6 +378,9 @@ class HighLine
     end
   end
 
+  # Renders a statement using {HighLine::Statement}
+  # @param statement [String] any string
+  # @return [Statement] rendered statement
   def render_statement(statement)
     Statement.new(statement, self).to_s
   end
@@ -340,6 +415,11 @@ class HighLine
   #
   # Executes block or outputs statement with indentation
   #
+  # @param increase [Integer] how much to increase indentation
+  # @param statement [Statement, String] to be said
+  # @param multiline [Boolean]
+  # @return [void]
+  # @see #multi_indent
   def indent(increase=1, statement=nil, multiline=nil)
     @indent_level += increase
     multi = @multi_indent
@@ -385,6 +465,8 @@ class HighLine
     return 24
   end
 
+  # Call #puts on the HighLine's output stream
+  # @param args [String] same args for Kernel#puts
   def puts(*args)
     @output.puts(*args)
   end
@@ -426,6 +508,17 @@ class HighLine
     answers.respond_to?(:values) ? answers.values.last : answers.last
   end
 
+  # Get response one line at time
+  # @param question [Question]
+  # @return [String] response
+  def get_response_line_mode(question)
+    if question.echo == true and !question.limit
+      get_line(question)
+    else
+      get_line_raw_no_echo_mode(question)
+    end
+  end
+
   #
   # Read a line of input from the input stream and process whitespace as
   # requested by the Question object.
@@ -439,47 +532,58 @@ class HighLine
     terminal.get_line(question, self)
   end
 
-  def get_response_line_mode(question)
-    if question.echo == true and !question.limit
-      get_line(question)
-    else
-      line = ""
-
-      terminal.raw_no_echo_mode_exec do
-        while character = terminal.get_character
-          break if character == "\n" or character == "\r"
-
-          # honor backspace and delete
-          if character == "\b"
-            chopped = line.chop!
-            output_erase_char if chopped and question.echo
-          else
-            line << character
-            @output.print(line[-1]) if question.echo == true
-            @output.print(question.echo) if question.echo and question.echo != true
-          end
-
-          @output.flush
+  def get_line_raw_no_echo_mode(question)
+    line = ""
 
-          break if question.limit and line.size == question.limit
+    terminal.raw_no_echo_mode_exec do
+      while character = terminal.get_character
+        break if ["\n", "\r"].include? character
+
+        # honor backspace and delete
+        if character == "\b"
+          chopped = line.chop!
+          output_erase_char if chopped and question.echo
+        else
+          line << character
+          say_last_char_or_echo_char(line, question)
         end
-      end
 
-      if question.overwrite
-        @output.print("\r#{HighLine.Style(:erase_line).code}")
         @output.flush
-      else
-        say("\n")
+
+        break if line_overflow_for_question?(line, question)
       end
+    end
+
+    say_new_line_or_overwrite(question)
+
+    question.format_answer(line)
+  end
 
-      question.format_answer(line)
+  def say_new_line_or_overwrite(question)
+    if question.overwrite
+      @output.print("\r#{HighLine.Style(:erase_line).code}")
+      @output.flush
+    else
+      say("\n")
     end
   end
 
+  def say_last_char_or_echo_char(line, question)
+    @output.print(line[-1]) if question.echo == true
+    @output.print(question.echo) if question.echo and question.echo != true
+  end
+
+  def line_overflow_for_question?(line, question)
+    question.limit and line.size == question.limit
+  end
+
   def output_erase_char
     @output.print("\b#{HighLine.Style(:erase_char).code}")
   end
 
+  # Get response using #getc
+  # @param question [Question]
+  # @return [String] response
   def get_response_getc_mode(question)
     terminal.raw_no_echo_mode_exec do
       response = @input.getc
@@ -487,13 +591,16 @@ class HighLine
     end
   end
 
+  # Get response each character per turn
+  # @param question [Question]
+  # @return [String] response
   def get_response_character_mode(question)
     terminal.raw_no_echo_mode_exec do
       response = terminal.get_character
       if question.overwrite
         erase_current_line
       else
-        echo = get_echo(question, response)
+        echo = question.get_echo_for_response(response)
         say("#{echo}\n")
       end
       question.format_answer(response)
@@ -505,16 +612,6 @@ class HighLine
     @output.flush
   end
 
-  def get_echo(question, response)
-    if question.echo == true
-      response
-    elsif question.echo != false
-      question.echo
-    else
-      ""
-    end
-  end
-
   public :get_response_character_mode, :get_response_line_mode
   public :get_response_getc_mode