miniparse 0.3.0

data/lib/miniparse/control.rb

@@ -0,0 +1,67 @@
+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 
+  @behaviour_controls = {}
+  @behaviour_controls.merge! DEFAULT_CONTROLS
+end
+
+self.reset_controls
+
+# raises a KeyError if key is not a recognized control
+# TODO consider raising SyntaxError with a custom msg instead of KeyError
+def self.control(key)
+  @behaviour_controls.fetch(key)
+end
+
+# raises a KeyError if any key is not a recognized control
+def self.set_control(opts = {})
+  opts.keys.each  { |key|  @behaviour_controls.fetch key }
+  @behaviour_controls.merge! opts
+  nil
+end
+
+
+
+end

data/lib/miniparse/option_broker.rb

@@ -0,0 +1,113 @@
+module Miniparse 
+
+
+
+class OptionBroker
+
+  attr_reader :parsed_values
+
+  def initialize(&block)
+    @parsed_values = {}
+    @added_options = {}
+    if block
+      add_option(spec: "--help", negatable: false, &block) 
+    end
+  end
+
+  def add_option(args, &block)
+    opt = new_option(args, &block)
+    # FEATURE duplicate option overwrite the old one
+    # NOTE defining a switch option and a flag option with the same name doesn't work (the first one gets overwritten)
+    if opt.shortable
+      duplicate = added_options.values.collect { |o|  
+         (o.shortable && o.name.to_s[0] == opt.name.to_s[0])? o.name : nil }
+      duplicate.compact!
+      unless duplicate.empty? || duplicate.include?(opt.name)
+        raise SyntaxError, "shortable option '#{opt.name}' conflicts with previously defined '" + duplicate.join(', ') + "'"
+      end
+    end
+    @added_options[opt.name] = opt
+  end
+
+  # @param argv is like ARGV but just for this broker
+  # @return unprocessed arguments
+  def parse_argv(argv)
+    av = argv.dup
+    rest_argv = []
+    while av.size > 0
+      arg = av.shift
+      opt = check_arg(arg)
+      if opt
+        val = opt.parse_value(arg)
+	    if val.nil? && (av.size > 0) && (av[0][0] != '-')
+	      new_arg = arg + "=" + av.shift
+	      val = opt.parse_value(new_arg)
+        end
+	    if val.nil?
+        raise ArgumentError, "#{opt.class} invalid invocation format '#{arg}'"
+	    end
+      else
+        if Miniparse.control(:raise_on_unrecognized) && (arg[0] == '-')
+          raise ArgumentError, "unrecognized option '#{arg}'"
+        end
+        rest_argv << arg
+      end
+    end
+    update_parsed_values
+    rest_argv
+  end
+ 
+  def help_usage
+    helps = added_options.values.collect do |opt|
+      opt.help_usage 
+    end
+    helps.compact.join(" ")
+  end
+
+  def help_desc
+    helps = added_options.values.collect { |opt| opt.help_desc }
+    helps.compact.join("\n")
+  end
+
+protected
+
+  attr_reader :added_options
+
+  def new_option(args, &block)
+    if SwitchOption.valid_spec args[:spec]
+      SwitchOption.new(args, &block)
+    elsif FlagOption.valid_spec args[:spec]
+      FlagOption.new(args, &block)
+    else
+      raise SyntaxError, 
+          "unknown or invalid option specification '#{args[:spec]}'"
+    end
+  end
+
+  def check_arg(arg)
+    match = added_options.values.collect { |opt|  opt.check(arg) ? opt : nil }
+    match.compact!
+    if match.size > 1
+      # NOTE this shouldn't be happening, just a sanity check
+      names = match.collect { |opt|  opt.name }
+      raise "Ambiguous options: '" + names.join(', ') + "'"
+    elsif match.size > 0
+      match[0]
+    else      
+      nil
+    end
+  end
+
+  def update_parsed_values
+    @parsed_values = {}
+    added_options.values.each do |opt| 
+      @parsed_values[opt.name] = opt.value    if opt.value != nil
+    end
+    parsed_values
+  end
+
+end
+
+
+
+end

data/lib/miniparse/parser.rb

@@ -0,0 +1,136 @@
+module Miniparse
+
+# TODO create external documentation, maybe auto
+
+
+class Parser
+
+  # @return after parsing (i.e. specified) rest of arguments 
+  attr_reader :args, :program_desc
+  # @return 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
+  def command_options; commander.parsed_values; end
+  def command_args; commander.parsed_args; end
+  
+  # @return the command the next add_option will apply to
+  def current_command; commander.current_command; end
+
+  
+  def initialize(program_description = '')
+    @global_broker = OptionBroker.new do
+      puts program_desc
+      puts help_usage
+      puts help_desc
+      exit ERR_HELP_REQ
+    end
+    @commander = Commander.new
+    @program_desc = program_description     
+  end
+
+  # @param spec is the option specification, similar to the option invocation 
+  # in the command line (ex. "--debug" or "--verbose LEVEL")
+  #
+  # @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
+  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 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
+  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
+  def parse(argv)
+    if Miniparse.control(:help_cmdline_empty) && argv.empty?
+      puts help_usage
+      exit ERR_HELP_REQ  
+    end
+    try_argument do
+      global_argv, cmd_name, cmd_argv = commander.split_argv(argv)
+      @args = global_broker.parse_argv(global_argv)
+      if cmd_name
+        commander.parse_argv(cmd_name, cmd_argv)
+      end
+      if Miniparse.control(:raise_global_args) && (! args.empty?)
+        # FIXME review this logic later
+        error = current_command  ?  "unrecognized command"  :  "extra arguments"
+        raise ArgumentError, "#{error} '#{args[0]}'"
+      end
+      args      
+    end
+  end
+
+  # @return a help message with the short descriptions
+  def help_desc
+    #FIXME
+    text = ""
+    if (global = global_broker.help_desc).size > 0
+      text += "\nOptions:\n"
+      text += global
+    end
+    text += commander.help_desc   
+    text
+  end
+
+  # @return a usage message
+  def help_usage
+    #FIXME
+    if Miniparse.control(:detailed_usage)
+      right_text = @global_broker.help_usage
+    elsif current_command
+      right_text = "[global_options]"   
+    else
+      right_text = "[options]"
+    end
+    if current_command
+      right_text += " <command> [command_options]"
+    end
+    right_text += " <args>"
+    Miniparse.help_usage_format(right_text)
+  end
+
+protected
+
+  attr_reader :commander, :global_broker
+
+  def current_broker
+    commander.current_broker || global_broker
+  end
+
+  def try_argument
+    #FIXME
+    begin
+      yield
+    rescue ArgumentError => except
+      raise    unless Miniparse.control(:rescue_argument_error)
+      prg = File.basename($PROGRAM_NAME)
+      $stderr.puts "#{prg}: error: #{except.message}"
+      $stderr.puts
+      $stderr.puts help_usage
+      # (#{except.backtrace[-1]})")
+      exit ERR_ARGUMENT
+    end
+  end
+    
+end
+
+
+
+end

data/lib/miniparse/version.rb

@@ -0,0 +1,9 @@
+module Miniparse
+
+
+
+VERSION = "0.3.0"
+
+
+
+end

data/lib/miniparse/word_wrap.rb

@@ -0,0 +1,59 @@
+module WordWrap
+
+
+
+# wrap a text at word boundaries
+# 
+# @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 
+def self.word_wrap(text, width, reformat:false)
+  text = text.gsub(/\s*\n/, ' ') if reformat
+  
+  clean = (text[-1] != "\n")
+  res = text.gsub(/(.{1,#{width-1}}\S)(\s+|$)/, "\\1\n")
+  (clean)? res.chomp : res 
+end
+
+  
+# same as word_wrap(...) but returns an array of lines
+#
+# @return an array of lines containing the rearranged text
+def self.word_wrap_lines(*args)
+  word_wrap(*args).split("\n")
+end
+
+
+# same as two_cols_word_wrap(...) but returns an array of lines
+#
+# @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)
+  left = word_wrap_lines(text_left, width_left, reformat:reformat)
+  right = word_wrap_lines(text_right, width_right, reformat:reformat)
+
+  top = [left.size, right.size].max
+  lines = []
+  i = 0
+  while i < top
+    l_part = left[i] || ''
+    r_part = right[i] || ''
+    lines << "%-*s%s%s" % [width_left, l_part, separator, r_part] 
+    i += 1
+  end
+  lines
+end
+
+
+# wrap two texts in two separate columms
+#
+# @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")
+end
+
+
+
+end  

data/miniparse.gemspec

@@ -0,0 +1,34 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'miniparse/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "miniparse"
+  spec.version       = Miniparse::VERSION
+  spec.authors       = ["Juanma Rodriguez"]
+  spec.email         = ["jmrod4@gmail.com"]
+
+  spec.summary       = %q{Miniparse is a easy to use yet flexible and powerful ruby library for parsing command-line options.}
+#  spec.description   = %q{TODO: Write a longer description or delete this line.}
+  spec.homepage      = "https://github.com/jmrod4/miniparse"
+  spec.license       = "MIT"
+
+  # Prevent pushing this gem to RubyGems.org by setting 'allowed_push_host', or
+  # delete this section to allow pushing this gem to any host.
+#  if spec.respond_to?(:metadata)
+#    spec.metadata['allowed_push_host'] = "TODO: Set to 'http://mygemserver.com'"
+#  else
+#    raise "RubyGems 2.0 or newer is required to protect against public gem pushes."
+#  end
+
+  spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 1.11"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "minitest", "~> 5.0"
+  spec.add_development_dependency "rspec", "~> 3.0"
+end

metadata

@@ -0,0 +1,129 @@
+--- !ruby/object:Gem::Specification
+name: miniparse
+version: !ruby/object:Gem::Version
+  version: 0.3.0
+platform: ruby
+authors:
+- Juanma Rodriguez
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2016-03-19 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.11'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.11'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+description: 
+email:
+- jmrod4@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rspec"
+- ".travis.yml"
+- FAQ.md
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- bin/console
+- bin/setup
+- examples/ex01_simple.rb
+- examples/ex02_options.rb
+- examples/ex03_commands.rb
+- examples/ex04_mixed.rb
+- examples/ex05_block.rb
+- examples/ex06_task_app.rb
+- examples/ex07_controls.rb
+- lib/miniparse.rb
+- lib/miniparse/app.rb
+- lib/miniparse/command.rb
+- lib/miniparse/commander.rb
+- lib/miniparse/control.rb
+- lib/miniparse/option_broker.rb
+- lib/miniparse/parser.rb
+- lib/miniparse/version.rb
+- lib/miniparse/word_wrap.rb
+- miniparse.gemspec
+homepage: https://github.com/jmrod4/miniparse
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.4.8
+signing_key: 
+specification_version: 4
+summary: Miniparse is a easy to use yet flexible and powerful ruby library for parsing
+  command-line options.
+test_files: []
+has_rdoc: