miniparse 0.3.2 → 0.3.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 4542b4d6cc48edf83bbe51d1d40628635582be4b
-  data.tar.gz: e811d691eccf6f72f88e19e440ba51ff0293d933
+  metadata.gz: bd0805b6bb2f315ae9df2c2ccea6c314f8cc7d69
+  data.tar.gz: 925c5bbe738870df5cceba609983d82a32ab8500
 SHA512:
-  metadata.gz: 70582bc36e4956f8f61dee11a0401edc83c23ad4df9daf6ec2481fbcedb76a3db0fa2642d4521717606ceec675dfd3a95bc79543288913a8f52a24b141c1fba8
-  data.tar.gz: 99f7f80c4a86ed3cb4cbfe347b0e57a9316595cfd5739bbce381b58368d618c27c3c41fff7e5c3487753fbdc7c16701ce4adc3928b649b60e7bb5872a0eefc40
+  metadata.gz: 40a6e76211a8a40bdd394878fd91efd47026a517516ac75c602ccba55cf04065a7804279207500d6d84626bcb172ce1fe7dc7f8a008a5f8566b1e95daa1bb3fe
+  data.tar.gz: 6cba205c6f3ec89acf6e71f96c98d03fde95fad7e81d20edd64ead076ff079da3711f98d5b47484c80d9295a21134a0a459146f68233cc76638530a099645141

data/.gitignore

@@ -1,6 +1,7 @@
 # editor files
 *.swp
 *~
+*.bak
 
 # temp files or dirs
 kk*

data/.yardopts

@@ -0,0 +1,2 @@
+--no-private --markup markdown lib/**/*.rb ext/**/*.c - README.md FAQ.md LICENSE.txt
+

data/FAQ.md

@@ -3,7 +3,7 @@
 
 ---
 
-### What's the meaning of x.y.z in your version numbers?
+### What's the meaning of _x.y.z_ in your version numbers?
 
 We use a [Semantic Versioning](http://semver.org/) like scheme of MAJOR.MINOR.PATCH:
 
@@ -17,6 +17,22 @@ Additionally a `b` will be added for beta (i.e. pre-release) versions.
 
 ---
 
+### What do you mean with _public interface_?
+
+At the moment the complete public interface is restricted to the class Parser, the control Miniparse class methods and the optional module App
+
+You can find the complete specification in the public methods and constants on these files:
+
+  * [miniparse.rb](https://github.com/jmrod4/miniparse/blob/master/lib/miniparse/constants.rb)
+ 
+  * [miniparse/parser.rb](https://github.com/jmrod4/miniparse/blob/master/lib/miniparse/parser.rb)
+
+  * [miniparse/control.rb](https://github.com/jmrod4/miniparse/blob/master/lib/miniparse/control.rb)
+
+  * [miniparse/app.rb](https://github.com/jmrod4/miniparse/blob/master/lib/miniparse/app.rb)	
+	
+---
+
 ### Why have you `protected` methods in your classes?
 
 It is the tersest way we found of defining a public interface. Please note that the non-public interface can be changed at any time, even when just releasing minor patches.

data/README.md

@@ -3,14 +3,34 @@
 
 **Miniparse is an easy to use yet flexible and powerful ruby library for parsing command-line options.**
 
-The main objetive of this implementation is minimun boiler plate with ease of use but keeping a self documenting specification. 
+The main objetive of this implementation is to get minimun boiler plate but keep ease of use and a self documenting specification. 
 
 Additionally the library is quite flexible and allows a lot of customization but always with sane defaults so **you don't need to learn nothing to start using it**.
 
-## How to use
+## How to Use
 
 Please find below a short but meaningful example, then you can **[get more examples](https://github.com/jmrod4/miniparse/tree/master/examples)** at [Github miniparse repository](https://github.com/jmrod4/miniparse).
 
+You can find also a nice autogenerated documentation from the current gem at  http://www.rubydoc.info/gems/miniparse/
+
+And finally, for the source files for the complete public interface you can see the class Parser in:
+
+  * [miniparse/parser.rb](https://github.com/jmrod4/miniparse/blob/master/lib/miniparse/parser.rb)
+
+The control class methods in:
+
+  * [miniparse/control.rb](https://github.com/jmrod4/miniparse/blob/master/lib/miniparse/control.rb)
+  
+And the constants in: 
+  
+  * [miniparse.rb](https://github.com/jmrod4/miniparse/blob/master/lib/miniparse/constants.rb)
+  
+If you use the optional App module you can find the source here:
+
+  * [miniparse/app.rb](https://github.com/jmrod4/miniparse/blob/master/lib/miniparse/app.rb)		
+
+## Simple Example
+
 Let's try putting the following code in `myprogram.rb`
 
     require 'miniparse'
@@ -41,7 +61,7 @@ or even get the auto generated help
     
     $ ruby yourprogram.rb --help
     
-    usage: ex01_readme.rb [--help] [--debug] <args>
+    usage: ex01_simple.rb [--help] [--debug] <args>
 
     Options:
        --debug          activate debugging
@@ -55,10 +75,14 @@ You can install it as an standard ruby gem with
 then to use you can require it adding the following to the top of your ruby source file
 
     require 'miniparse'
+	
+## F.A.Q.
+
+There is a FAQ available at https://github.com/jmrod4/miniparse/blob/master/FAQ.md
     
 ## Contributing
 
-Bug reports and pull requests are welcome at https://github.com/jmrod4/miniparse.
+Bug reports and pull requests are most welcome at https://github.com/jmrod4/miniparse.
 
 After checking out the repo you can:
 
@@ -70,6 +94,6 @@ After checking out the repo you can:
 
 ## License
 
-This library is copyrighted software and it's available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
+This library has Copyright 2016 Juanma Rodriguez and it's available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
 
 You can find the source code at https://github.com/jmrod4/miniparse.

data/Rakefile

@@ -2,17 +2,25 @@ require "bundler/gem_tasks"
 
 
 require "rake/testtask"
-
 Rake::TestTask.new(:test) do |t|
   t.libs << "test"
   t.libs << "lib"
   t.test_files = FileList['test/**/*_test.rb']
 end
-
 #task :default => :test
 
-require "rspec/core/rake_task"
 
+
+require "rspec/core/rake_task"
 RSpec::Core::RakeTask.new(:spec)
 
+
+
+desc "Generate yard documentation"
+task :doc do
+  sh "yard doc"
+end
+
+
+
 task :default => :spec

data/lib/miniparse.rb

@@ -1,51 +1,16 @@
 # TODO consider inserting here instructions about how to use or how to find help
 
+
 # other modules
 require "miniparse/word_wrap"
 
-module Miniparse
-  # error exit codes
-#  module ErrorCodes
-    ERR_HELP_REQ = 1
-    ERR_ARGUMENT = 2
-#  end
-#  include ErrorCodes
-end
-
 # module miniparse
+require "miniparse/constants"
 require "miniparse/command"
 require "miniparse/commander"
 require "miniparse/control"
+require "miniparse/internals"
 require "miniparse/option_broker"
 require "miniparse/parser"
 require "miniparse/version"
 
-
-
-module Miniparse
-  
-
-  
-def self.help_usage_format(right_text)
-  left_text = "usage: #{File.basename($PROGRAM_NAME)}"
-  if Miniparse.control(:formatted_help)
-    width_display = Miniparse.control(:width_display)
-    width_left = left_text.size
-    WordWrap.two_cols_word_wrap(left_text, ' ', right_text, 
-        width_left, width_display - 1 - width_left)
-  else
-    left_text + " " + right_text
-  end
-end
- 
-
-def self.debug(msg)
-  puts "\nDEBUG #{caller[0]}: #{msg}" 
-end
-
-  
-
-end
-
-
-

data/lib/miniparse/app.rb

@@ -1,5 +1,33 @@
 require 'miniparse'
 
+# this optional module allows an easy integration of parsing and trivial output,
+# in your application
+# 
+# simple example of use:
+#
+#     require "miniparse/app"
+#    
+#     App.configure_parser do |parser|
+#       Miniparse.set_control(
+#           autoshortable: true,
+#           )
+#       parser.add_program_description "my program help introduction\n"
+#       parser.add_option("--list", "list something")
+#       parser.parse ARGV
+#     end
+#    
+#     # to see App.debug you have to specify the --debug option
+#     # for example: 'ruby ex08_app_simple.rb --debug' 
+#     App.debug App.options   # to stdout
+#     App.info App.options    # to stdout
+#     App.warn App.options    # to stderr
+#     App.error App.options   # to stderr (note: it doesn't exit)
+#    
+#     # you have direct access to the parser object
+#     puts "parser object: #{App.parser}"
+#    
+#     puts 'Done.'
+#
 module App
  
   # error exit codes
@@ -9,33 +37,45 @@ module App
   @parser = nil
   @do_configure_parser = lambda { |parser| parser.parse ARGV }
   
+  # @param msg [string] is the message to output
+  # @return [void]
   def self.error(msg)
     $stderr.puts "error: #{msg}"  
   end
   
+  # @param msg [string] is the message to output
+  # @return [void]
   def self.warn(msg)
     $stderr.puts "warning: #{msg}"  
   end
   
+  # @param msg [string] is the message to output
+  # @return [void]
   def self.info(msg)
     $stdout.puts "info: #{msg}"  
   end
   
+  # @param msg [string] is the message to output
+  # @return [void]
   def self.debug(msg)
     $stdout.puts "debug: #{msg}"    if App.options[:debug]
   end
   
+  # @return [hash] parsed options, i.e. specified in argv
   def self.options
     parser.options  
   end
 
+  # defines a block that takes parser as parameter and configures and parses it
+  # @return [void] specified block
   def self.configure_parser(&block)
     reset_parser
-    @do_configure_parser = block
-    nil    
+    @do_configure_parser = block    
   end
   
-  # lazy parser creation  
+  # (the first time it is called after ##configure_parser, it does a lazy 
+  # parser creation using the block defined in ##configure_parser)  
+  # @return [Parser] parser 
   def self.parser
     return @parser   if @parser
     @parser = Miniparse::Parser.new
@@ -44,7 +84,8 @@ module App
     parser
   end     
     
-  # re-initialize the parser (but doesn't affect the configuration)
+  # re-initialize the parser (it doesn't change the configuration)
+  # @return [void]
   def self.reset_parser
     @parser = nil
   end

data/lib/miniparse/command.rb

@@ -1,7 +1,7 @@
 module Miniparse
 
 
-
+# @private  
 class Command
 
   def self.spec_to_name(spec)
@@ -86,6 +86,7 @@ end
 
 # TODO FEATURE consider doing unambiguous matches for shortened options
 # TODO FEATURE consider the option default value setting the type
+# @private  
 class Option < Command
   
   attr_reader :value, :shortable
@@ -129,6 +130,7 @@ end
 
 
 
+# @private  
 class SwitchOption < Option
 
   def self.spec_to_name(spec)
@@ -170,6 +172,7 @@ end
 
 
 
+# @private  
 class FlagOption < Option
 
   def self.spec_to_name(spec)

data/lib/miniparse/commander.rb

@@ -1,20 +1,26 @@
 module Miniparse
 
-# TODO create external documentation, maybe auto
-
 # TODO this class maybe does too much, separate a command broker or something similar
 
+
+# @private
 class Commander
 
-  attr_reader :current_command, :parsed_command, :parsed_args
+  # command ready to add options to
+  attr_reader :current_command_name
+  # command found while parsing arguments
+  attr_reader :parsed_command_name
+  # remaining command args after parsing the options for the parsed command 
+  attr_reader :parsed_args
   
+  # @return [hash] parsed option values for the parsed command
   def parsed_values
-    brokers[parsed_command].parsed_values  if parsed_command
+    brokers[parsed_command_name].parsed_values  if parsed_command_name
   end
   
-  # @return current command broker or nil
+  # @return [Broker] current command broker or nil if there is not current command
   def current_broker
-    brokers[current_command]
+    brokers[current_command_name]
   end
 
   def initialize
@@ -22,12 +28,12 @@ class Commander
     @brokers = {}
   end
     
-  # @param name is the command name (ex. either "kill" or :kill)
-  #
-  # @param desc is a short description of the command
-  # 
-  # @param opts are the options to apply to the command
-  # :no_options  indicates the command has no command line options
+  # @param args [hash] can have keys:
+  #   * :name is the command name (ex. either "kill" or :kill)
+  #   * :desc is a short description of the command
+  #   * :opts are the options to apply to the command, can have keys: 
+  #     * :no_options  indicates the command has no command line options
+  # @return [Command] the command added
   def add_command(args, &block)
     spec = args[:spec]
     unless name = Command.spec_to_name(spec)
@@ -43,12 +49,12 @@ class Commander
       puts help_command_text(name)
       exit ERR_HELP_REQ
     end
-    @current_command = name    unless args[:no_options]
+    @current_command_name = name    unless args[:no_options]
     cmd
   end  
 
-  # @param argv is ARGV like
-  # @return an array of argv parts: [global_argv, command_name, command_argv] 
+  # @param argv [array] is ARGV like
+  # @return [array] of argv parts: [global_argv, command_name, command_argv] 
   def split_argv(argv)
     index = index_command(argv)
     if index
@@ -60,18 +66,21 @@ class Commander
     end
   end
     
+  # @param name [symbol] command name
+  # @param argv [array] is ARGV like to parse
+  # @return [array] #parsed_args
   def parse_argv(name, argv)
     cmd = commands.fetch(name)
-    @parsed_command = cmd.name
+    @parsed_command_name = cmd.name
     @parsed_args = brokers[cmd.name].parse_argv(argv)
     commands[cmd.name].run(parsed_args)
     parsed_args
   end
   
-  # @return the command general help for the commands in the commander 
+  # @return [string] the command general help for the commands in the commander 
   def help_desc
     text = ""
-    if current_command
+    if current_command_name
       names_wo_desc = []
       desc_texts = commands.sort.collect do |name, cmd| 
         if cmd.desc
@@ -97,7 +106,9 @@ class Commander
 protected 
 
   attr_reader :commands, :brokers 
-
+  
+  # @param name [symbol] command name
+  # @return [string] text help for the specified command
   def help_command_text(name)
     header = "Command #{name}:  #{commands[name].desc}"
     text = "\n"
@@ -113,6 +124,8 @@ protected
     text
   end
   
+  # adds a default help command
+  # @return [void]
   def add_help_command
     add_command(spec: :help, desc: nil, no_options: true) do |args|
       index = index_command(args)
@@ -126,8 +139,8 @@ protected
     end
   end
 
-  # @param argv is like ARGV
-  # @return index number of the first found command, nil if not found
+  # @param argv [array] is like ARGV
+  # @return [int|nil] index number of the first found command, nil if not found
   def index_command(argv)
     commands.values.each do |cmd|
       index = argv.find_index  { |arg|  cmd.check(arg) }

data/lib/miniparse/constants.rb

@@ -0,0 +1,49 @@
+
+module Miniparse
+
+  ERR_HELP_REQ = 1
+  ERR_ARGUMENT = 2
+  
+
+  DEFAULT_CONTROLS = {
+    # gives an error if there is an unrecognized option either short or long
+    # (if not then passes them as arguments) 
+    raise_on_unrecognized: true, 
+    
+    # intercepts .parse ArgumentError (i.e. the commandline user introduced 
+    # wrong or invalid options) and exits with a helpful msg  
+    rescue_argument_error: true,
+    
+    # gives usage help and exits if commandline is empty
+    # useful if your app always needs args or options to work
+    help_cmdline_empty: false,
+    
+    # raises an ArgumentError if there are global args 
+    # (after parsing options and commands)
+    # useful if you don't expect any args
+    raise_global_args: false,
+
+    # formats help output with the width_... controls
+    formatted_help: true,
+    
+    width_display: 79,
+    width_indent: 3,
+    width_left: 18,
+    
+    # use a detailed options help usage msg or a generic one
+    detailed_usage: true,
+
+    # uses --no-... options for all options
+    # useful if you want all your options to be negatable by default
+    autonegatable: false,
+    
+    # uses short options (besides long ones) for all options
+    # useful if you want all your options to be shortable by default
+    autoshortable: false,
+    
+    # TODO: consider adding following control
+    # admits -h besides --help in help predefined option
+    # shortable_help: false,
+    }
+
+end

data/lib/miniparse/control.rb

@@ -1,65 +1,32 @@
 module Miniparse
 
-
-DEFAULT_CONTROLS = {
-  # gives an error if there is an unrecognized option either short or long
-  # (if not then passes them as arguments) 
-  raise_on_unrecognized: true, 
-  
-  # intercepts .parse ArgumentError (i.e. the commandline user introduced 
-  # wrong or invalid options) and exits with a helpful msg  
-  rescue_argument_error: true,
-  
-  # gives usage help and exits if commandline is empty
-  # useful if your app always needs args or options to work
-  help_cmdline_empty: false,
-  
-  # raises an ArgumentError if there are global args 
-  # (after parsing options and commands)
-  # useful if you don't expect any args
-  raise_global_args: false,
-
-  # formats help output with the width_... controls
-  formatted_help: true,
-  
-  width_display: 79,
-  width_indent: 3,
-  width_left: 18,
-  
-  # use a detailed options help usage msg or a generic one
-  detailed_usage: true,
-
-  # uses --no-... options for all options
-  # useful if you want all your options to be negatable by default
-  autonegatable: false,
-  
-  # uses short options (besides long ones) for all options
-  # useful if you want all your options to be shortable by default
-  autoshortable: false,
-  
-  # TODO: consider adding this option
-  # admits -h besides --help in help predefined option
-  # shortable_help: false,
-  }
-
-def self.reset_controls 
+# @return [void]
+def self.reset_default_controls 
   @behaviour_controls = {}
   @behaviour_controls.merge! DEFAULT_CONTROLS
 end
 
-self.reset_controls
+self.reset_default_controls
 
-# raises a KeyError if key is not a recognized control
 # TODO consider raising SyntaxError with a custom msg instead of KeyError
+
+# @param key [symbol] must be a known control, if not it raises a KeyError
+# @return [boolean] the current value of specified control
 def self.control(key)
   @behaviour_controls.fetch(key)
 end
 
-# raises a KeyError if any key is not a recognized control
+# sets the control values specified in the hash, modern abbreviated notation can 
+# be used like e.g.
+#
+#     set_control(autoshortable: true)
+#     set_control(autoshortable: true, autonegatable: true)
+#
+# @param opts [hash] must contain only known controls, if not it raises a KeyError
+# @return [void]
 def self.set_control(opts = {})
   opts.keys.each  { |key|  @behaviour_controls.fetch key }
   @behaviour_controls.merge! opts
-  nil
 end
 
 

data/lib/miniparse/internals.rb

@@ -0,0 +1,22 @@
+module Miniparse
+  
+
+  
+# @private  
+# @param right_text [string] is a usage text to be displayed to the right
+# @return [string] the formatted text to the right with an usage header to the left 
+def self.help_usage_format(right_text)
+  left_text = "usage: #{File.basename($PROGRAM_NAME)}"
+  if Miniparse.control(:formatted_help)
+    width_display = Miniparse.control(:width_display)
+    width_left = left_text.size
+    WordWrap.two_cols_word_wrap(left_text, ' ', right_text, 
+        width_left, width_display - 1 - width_left)
+  else
+    left_text + " " + right_text
+  end
+end
+
+
+
+end

data/lib/miniparse/option_broker.rb

@@ -1,7 +1,7 @@
 module Miniparse 
 
 
-
+# @private
 class OptionBroker
 
   attr_reader :parsed_values

data/lib/miniparse/parser.rb

@@ -3,23 +3,41 @@ module Miniparse
 # TODO create external documentation, maybe auto
 
 
+# this is the key class to the miniparse library, 
+# please find below an example of use:
+#
+#     require 'miniparse'
+#    
+#     parser = Miniparse::Parser.new
+#     parser.add_option "--debug", "activate debugging"
+#     parser.parse ARGV
+#    
+#     if parser.options[:debug]
+#       puts "DEBUG ACTIVATED!"
+#     else
+#       puts "run silently"
+#     end
+#
 class Parser
 
-  # @return after parsing (i.e. specified) rest of arguments 
+  # @return [array] rest of arguments after parsing 
   attr_reader :args
   
-  # @return parsed (i.e. specified) global options
+  # @return [hash] parsed, i.e. specified, global options
   def options; global_broker.parsed_values; end
   
-  # @return  parsed (i.e. specified) command (nil if none), options and arguments
-  def command; commander.parsed_command; end
+  # @return [symbol|nil] name of command parsed , i.e. specified, (or nil if none)
+  def command_name; commander.parsed_command_name; end
+
+  # @return [hash] parsed option values for the parsed command
   def command_options; commander.parsed_values; end
+  
+  # @return [array] remaining command args after parsing the options for the parsed command 
   def command_args; commander.parsed_args; end
   
-  # @return the command the next add_option will apply to
-  def current_command; commander.current_command; end
+  # @return [symbol] the name of the command the next #add_option will apply to
+  def current_command_name; commander.current_command_name; end
 
-  
   def initialize
     @commander = Commander.new
     @program_desc = nil     
@@ -30,40 +48,42 @@ class Parser
       exit ERR_HELP_REQ
     end
   end
-  
-  
+ 
+  # @param desc [string] is the program description to display on help msgs
+  # @return [void] same argument  
   def add_program_description(desc)
     @program_desc = desc
   end
   
-  
-  # @param spec is the option specification, similar to the option invocation 
-  # in the command line (ex. "--debug" or "--verbose LEVEL")
+  # @param spec [string] is the option specification, similar to the option
+  #   invocation in the command line (e.g. `--debug` or `--verbose LEVEL`)
+  # @param desc [string|nil] is a short description of the option
+  # @param opts [hash] are the options to apply to the option, keys can include:
   #
-  # @param desc is a short description of the option
-  # 
-  # @param opts are the options to apply to the option
-  # :default
-  # :negatable (used only for switches)
-  # :shortable
+  #   * :default
+  #   * :negatable (used only for switches)
+  #   * :shortable
+  #
+  # @return [void] added Option
   def add_option(spec, desc, opts={}, &block)
     args = opts.merge(spec: spec, desc: desc)
     current_broker.add_option(args, &block)
   end
 
-  # @param name is the command name (ex. either "kill" or :kill)
+  # @param name [symbol|string] is the command name
+  # @param desc [string|nil] is a short description of the command
+  # @param opts [hash] are the options to apply to the command, keys can be:
+  #
+  #   * :no_options  indicates the command has no command line options
   #
-  # @param desc is a short description of the command
-  # 
-  # @param opts are the options to apply to the command
-  # :no_options  indicates the command has no command line options
+  # @return [void] added Command
   def add_command(name, desc, opts={}, &block)
     args = opts.merge(spec: name, desc: desc)
     commander.add_command(args, &block)
   end
 
   # @param argv is like ARGV but just for this parser
-  # @return unprocessed arguments
+  # @return [array] unprocessed arguments
   def parse(argv)
     if Miniparse.control(:help_cmdline_empty) && argv.empty?
       puts help_usage
@@ -77,14 +97,14 @@ class Parser
       end
       if Miniparse.control(:raise_global_args) && (! args.empty?)
         # FIXME review this logic later
-        error = current_command  ?  "unrecognized command"  :  "extra arguments"
+        error = current_command_name  ?  "unrecognized command"  :  "extra arguments"
         raise ArgumentError, "#{error} '#{args[0]}'"
       end
       args      
     end
   end
 
-  # @return a help message with the short descriptions
+  # @return [string] a help message with the short descriptions
   def help_desc
     #FIXME
     text = ""
@@ -96,17 +116,17 @@ class Parser
     text
   end
 
-  # @return a usage message
+  # @return [string] a usage message
   def help_usage
     #FIXME
     if Miniparse.control(:detailed_usage)
       right_text = @global_broker.help_usage
-    elsif current_command
+    elsif current_command_name
       right_text = "[global_options]"   
     else
       right_text = "[options]"
     end
-    if current_command
+    if current_command_name
       right_text += " <command> [command_options]"
     end
     right_text += " <args>"

data/lib/miniparse/version.rb

@@ -1,8 +1,8 @@
 module Miniparse
 
 
-
-VERSION = "0.3.2"
+# semantic versioning MAJOR.MINOR.PATCH [b]eta
+VERSION = "0.3.3"
 
 
 

data/lib/miniparse/word_wrap.rb

@@ -1,13 +1,14 @@
+# @private
 module WordWrap
 
 
 
-# wrap a text at word boundaries
+# wrap a text at word boundaries with a given line width 
 # 
-# @param text: the text to wrap
-# @param width: the maximum width allowed for on line before inserting line breaks
-# @param reformat: if true then the previous line breaks are removed and then the text wrappeed
-# @return text with line breaks inserted as necessasry 
+# @param text [string] is the text to wrap
+# @param width [numeric] is the maximum width allowed for one line before inserting line breaks
+# @param reformat [boolean] if true then the existing line breaks are removed from the text before wrapping it
+# @return text with line breaks inserted as necessary
 def self.word_wrap(text, width, reformat:false)
   text = text.gsub(/\s*\n/, ' ') if reformat
   
@@ -25,8 +26,12 @@ def self.word_wrap_lines(*args)
 end
 
 
-# same as two_cols_word_wrap(...) but returns an array of lines
+# wrap two texts in two separate columns
 #
+# @param text_left [string] is the text in the left column 
+# @param text_right [string] is the text in the right column 
+# @param separator [string] is inserted at every line between the two columns, typical are ' ' or ' | ' 
+# @param reformat [boolean] like in word_wrap(...)
 # @return an array of lines containing the merged and rearranged texts
 def self.two_cols_word_wrap_lines(text_left, separator, text_right, 
       width_left, width_right, reformat:false)
@@ -46,9 +51,8 @@ def self.two_cols_word_wrap_lines(text_left, separator, text_right,
 end
 
 
-# wrap two texts in two separate columms
+# same as two_cols_word_wrap_lines(...) but returns a text with \n inserted
 #
-# @param separator: a string of characters inserted at every line between the two collums, for example ' ' or ' | ' 
 # @return text with line breaks inserted as necessary 
 def self.two_cols_word_wrap(*args)
   two_cols_word_wrap_lines(*args).join("\n")

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: miniparse
 version: !ruby/object:Gem::Version
-  version: 0.3.2
+  version: 0.3.3
 platform: ruby
 authors:
 - Juanma Rodriguez
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2016-03-19 00:00:00.000000000 Z
+date: 2016-03-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -76,6 +76,7 @@ files:
 - ".gitignore"
 - ".rspec"
 - ".travis.yml"
+- ".yardopts"
 - FAQ.md
 - Gemfile
 - LICENSE.txt
@@ -95,7 +96,9 @@ files:
 - lib/miniparse/app.rb
 - lib/miniparse/command.rb
 - lib/miniparse/commander.rb
+- lib/miniparse/constants.rb
 - lib/miniparse/control.rb
+- lib/miniparse/internals.rb
 - lib/miniparse/option_broker.rb
 - lib/miniparse/parser.rb
 - lib/miniparse/version.rb