miniparse 0.3.0

data/lib/miniparse.rb

@@ -0,0 +1,51 @@
+# 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/command"
+require "miniparse/commander"
+require "miniparse/control"
+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

@@ -0,0 +1,51 @@
+require 'miniparse'
+
+module App
+ 
+  # error exit codes
+  ERR_NOT_FOUND = 3
+  ERR_IO = 4
+
+  @parser = nil
+  @do_configure_parser = lambda { |parser| parser.parse ARGV }
+  
+  def self.error(msg)
+    $stderr.puts "error: #{msg}"  
+  end
+  
+  def self.warn(msg)
+    $stderr.puts "warning: #{msg}"  
+  end
+  
+  def self.info(msg)
+    $stdout.puts "info: #{msg}"  
+  end
+  
+  def self.debug(msg)
+    $stdout.puts "debug: #{msg}"    if App.options[:debug]
+  end
+  
+  def self.options
+    parser.options  
+  end
+
+  def self.configure_parser(&block)
+    reset_parser
+    @do_configure_parser = block     
+  end
+  
+  # lazy parser creation  
+  def self.parser
+    return @parser   if @parser
+    @parser = Miniparse::Parser.new
+    parser.add_option("--debug", nil, negatable: false)
+    @do_configure_parser.call(parser)
+    parser
+  end     
+    
+  # unset the parser (but doesn't affect the configuration)
+  def self.reset_parser
+    @parser = nil
+  end
+
+end

data/lib/miniparse/command.rb

@@ -0,0 +1,210 @@
+module Miniparse
+
+
+
+class Command
+
+  def self.spec_to_name(spec)
+    spec_pattern_to_name(spec, /\A(\w[\w-]*)\z/)
+  end
+  def self.valid_spec(*args); spec_to_name(*args); end
+
+  attr_reader :name, :desc
+
+  # uses args:
+  #   :spec
+  #   :desc
+  def initialize(args, &block)
+    @spec = args.fetch(:spec) 
+    @desc = args[:desc] 
+    @block = block
+    @name = self.class.spec_to_name(spec)
+    raise SyntaxError, "invalid specification '#{spec}'"    if name.nil?
+    post_initialize(args)
+  end
+
+  # runs the associated block with specified arguments
+  #
+  # @param args is arguments passed to the block
+  def run(*args)
+    block.call(*args)    if block 
+  end
+
+  # @param arg is like an ARGV element
+  # @return true if arg specifies this object
+  def check(arg)
+    arg.to_s == name.to_s
+  end
+
+  # @return text of an option specification and description
+  def help_desc
+    return nil    unless desc
+    
+    separator = '  '
+    width_indent = Miniparse.control(:width_indent)
+    width_left = Miniparse.control(:width_left) -
+                 Miniparse.control(:width_indent)
+    width_right = Miniparse.control(:width_display) - 
+                  separator.size -
+                  Miniparse.control(:width_left)
+
+    if Miniparse.control(:formatted_help)
+      lines = WordWrap.two_cols_word_wrap_lines(
+              spec.to_s + add_spec, separator, 
+              desc + add_desc,
+              width_left, width_right)
+      lines.collect! { |line|  " "*width_indent + line  }
+      lines.join("\n")
+    else
+      s = "%*s" % [width_indent, separator]
+      s += "%-*s" % [width_left, spec.to_s + add_spec]
+      s += '  '
+      s += desc + add_desc
+    end
+  end
+
+protected
+
+  def self.spec_pattern_to_name(spec, pattern)
+    (spec =~ pattern)  ?  $1.to_sym  :  nil
+  end
+
+private_class_method :spec_pattern_to_name
+
+  attr_reader :spec, :block 
+
+  # subclass hook for initializing
+  def post_initialize(args); nil; end 
+     
+  # subclass hook for changing description/specification
+  def add_desc; ""; end
+  def add_spec; ""; end
+
+end
+
+
+
+# TODO FEATURE consider doing unambiguous matches for shortened options
+# TODO FEATURE consider the option default value setting the type
+class Option < Command
+  
+  attr_reader :value, :shortable
+
+  def check(arg)
+    arg_to_value(arg) != nil
+  end
+
+  def arg_to_value(arg)
+    raise NotImplementedError, "#{self.class} cannot respond to '#{__method__}'"
+  end
+
+  def parse_value(arg)
+    val = arg_to_value(arg)
+    if val != nil
+      @value = val
+      run(val)
+    end
+    val
+  end
+
+  def help_usage
+    raise NotImplementedError, "#{self.class} cannot respond to '#{__method__}'"
+  end
+
+protected
+  
+  # uses args:
+  #   :default
+  def post_initialize(args)
+    super(args)
+    @value = args[:default]
+    @shortable = args.fetch(:shortable, Miniparse.control(:autoshortable))
+  end
+  
+  def add_spec
+    shortable ? ', -' + name.to_s[0] : ""
+  end
+
+end
+
+
+
+class SwitchOption < Option
+
+  def self.spec_to_name(spec)
+    spec_pattern_to_name(spec, /\A--(\w[\w-]+)\z/)
+  end
+
+  def arg_to_value(arg)
+    if arg == "--#{name}"
+      true
+    elsif negatable && (arg == "--no-#{name}")
+      false
+    elsif shortable && (arg == '-' + name.to_s[0])
+      true
+    else
+      nil
+    end
+  end
+  
+  def help_usage
+    negatable  ?  "[--[no-]#{name}]"  :  "[--#{name}]"
+  end
+  
+protected
+
+  attr_reader :negatable
+
+  # uses args:
+  #   negatable:true
+  def post_initialize(args)
+    super(args)
+    @negatable = args.fetch(:negatable, Miniparse.control(:autonegatable))
+  end
+
+  def add_desc
+    value ? " (on by default)" : "" 
+  end
+  
+end
+
+
+
+class FlagOption < Option
+
+  def self.spec_to_name(spec)
+    spec_pattern_to_name(spec, /\A--(\w[\w-]+)[=| ]\S+\z/)
+  end
+  
+  # @param arg is like an ARGV element
+  # @return true if arg specifies this option
+  def check(arg)
+     super(arg) || (arg =~ /\A--#{name}\z/) ||
+      (shortable && (arg =~ /\A-#{name.to_s[0]}\z/))
+  end
+
+  def arg_to_value(arg)
+    if arg =~ /\A--#{name}[=| ](.+)\z/
+      $1
+    elsif shortable && (arg =~ /\A-#{name.to_s[0]}[=| ](.+)\z/)
+      $1
+    else
+      nil
+    end
+  end
+  
+  def help_usage
+    "[#{spec}]"
+  end
+
+protected
+
+  def add_desc
+    value ? " (#{value})" : "" 
+  end
+
+end
+
+
+
+end

data/lib/miniparse/commander.rb

@@ -0,0 +1,143 @@
+module Miniparse
+
+# TODO create external documentation, maybe auto
+
+# TODO this class maybe does too much, separate a command broker or something similar
+
+class Commander
+
+  attr_reader :current_command, :parsed_command, :parsed_args
+  
+  def parsed_values
+    brokers[parsed_command].parsed_values  if parsed_command
+  end
+  
+  # @return current command broker or nil
+  def current_broker
+    brokers[current_command]
+  end
+
+  def initialize
+    @commands = {}
+    @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
+  def add_command(args, &block)
+    spec = args[:spec]
+    unless name = Command.spec_to_name(spec)
+      raise SyntaxError, "unknown or invalid command specification '#{spec}'"
+    end
+    # only run before first command get added
+    # and the user isn't trying to add his own help command
+    add_help_command    if name != :help && commands.empty?
+    cmd = Command.new(args, &block)
+    # FEATURE if a command already exists it gets quietly overwritten (and its options lost)
+    @commands[name] = cmd
+    @brokers[name] = OptionBroker.new do
+      puts help_command_text(name)
+      exit ERR_HELP_REQ
+    end
+    @current_command = name    unless args[:no_options]
+    cmd
+  end  
+
+  # @param argv is ARGV like
+  # @return an array of argv parts: [global_argv, command_name, command_argv] 
+  def split_argv(argv)
+    index = index_command(argv)
+    if index
+      global_argv = (index == 0)  ?  []  :  argv[0..index-1]
+      command_argv = argv[index+1..-1]
+      [global_argv, Command.spec_to_name(argv[index]), command_argv]
+    else  
+      [argv, nil, []]
+    end
+  end
+    
+  def parse_argv(name, argv)
+    cmd = commands.fetch(name)
+    @parsed_command = 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 
+  def help_desc
+    text = ""
+    if current_command
+      names_wo_desc = []
+      desc_texts = commands.sort.collect do |name, cmd| 
+        if cmd.desc
+          cmd.help_desc
+        else
+          names_wo_desc << name
+          nil
+        end
+      end
+      unless desc_texts.compact!.empty?
+        text += "\nCommands:\n"
+        text += desc_texts.join("\n") 
+      end
+      unless names_wo_desc.empty?
+        text += "\nMore commands: \n"
+        text += ' '*Miniparse.control(:width_indent)
+        text += names_wo_desc.join(", ")
+      end
+    end
+    text
+  end
+  
+protected 
+
+  attr_reader :commands, :brokers 
+
+  def help_command_text(name)
+    header = "Command #{name}:  #{commands[name].desc}"
+    text = "\n"
+    text += WordWrap.word_wrap(header, Miniparse.control(:width_display))
+    text += "\n\n"
+    text += Miniparse.help_usage_format(
+        "#{name} #{brokers[name].help_usage}")
+    if (options_desc = brokers[name].help_desc).size > 0
+      text += "\n\nOptions:\n"
+      text += options_desc
+    end
+    text += "\n\n"
+    text
+  end
+  
+  def add_help_command
+    add_command(spec: :help, desc: nil, no_options: true) do |args|
+      index = index_command(args)
+      if index
+        name = args[index].to_sym
+        puts help_command_text(name)
+        exit ERR_HELP_REQ
+      else
+        raise ArgumentError, "no command specified, use 'help <command>' to get help"
+      end
+    end
+  end
+
+  # @param argv is like ARGV
+  # @return 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) }
+      return index if    index
+    end
+    nil
+  end
+
+end
+
+
+
+end