opt_parse_builder 0.1.0

data/lib/opt_parse_builder/argument_bundle_builder.rb

@@ -0,0 +1,34 @@
+module OptParseBuilder
+
+  # Yielded by OptParseBuilder.bundle_arguments to create an
+  # ArgumentBundle, a collection of arguments that can be treated as
+  # through it is one argument.
+  class ArgumentBundleBuilder
+
+    def initialize # :nodoc:
+      @argument_bundle = ArgumentBundle.new
+    end
+
+    # Add an argument to the bundle.  Takes either the argument to
+    # add, or yields an ArgumentBuilder which builds a new argument
+    # and adds it.
+    #
+    # If adding an existing argument, that argument may itself be an
+    # ArgumentBundle.
+    def add(argument = nil, &block)
+      unless argument.nil? ^ block.nil?
+        raise BuildError, "Need exactly 1 of arg and block"
+      end
+      if argument
+        @argument_bundle << argument
+      else
+        @argument_bundle << OptParseBuilder.build_argument(&block)
+      end
+    end
+
+    def argument # :nodoc:
+      @argument_bundle.simplify
+    end
+
+  end
+end

data/lib/opt_parse_builder/argument_values.rb

@@ -0,0 +1,60 @@
+module OptParseBuilder
+
+  # Like OpenStruct, in that it allows access as through either a Hash
+  # or a Struct, but raises an error if you try to read a value that
+  # has not been set.
+  #
+  # Strings and symbols may be interchanged freely for hash access.
+  #
+  # A value may only by set using hash syntax:
+  #
+  #     arg_values = ArgumentValues.new
+  #     arg_values[:one] = 1
+  #     arg_values["two"] = 2
+  #
+  # But may be retrieved using hash syntax:
+  #
+  #     arg_values["one"]    # => 1
+  #     arg_values[:two]     # => 2
+  #
+  # or struct syntax:
+  #
+  #     arg_values.one    # => 1
+  #     arg_values.two    # => 2
+  class ArgumentValues
+
+    # Create an empty instance.
+    def initialize
+      @h = {}
+    end
+
+    # Return true if the collection is empty.
+    def empty?
+      @h.empty?
+    end
+
+    # Return true if the collection contains the key, which may be
+    # either a symbol or a string.
+    def has_key?(key)
+      @h.has_key?(key.to_sym)
+    end
+
+    # Set a key to a value.  The key may be either a string or a
+    # symbol.
+    def []=(key, value)
+      @h[key.to_sym] = value
+    end
+
+    # Get a value.  The key may be either a string or a symbol.
+    # Raises KeyError if the collection does not have that key.
+    def [](key)
+      @h.fetch(key.to_sym)
+    end
+
+    def method_missing(method, *args) # :nodoc:
+      return super unless has_key?(method)
+      self[method]
+    end
+    
+  end
+end

data/lib/opt_parse_builder/banner_argument.rb

@@ -0,0 +1,11 @@
+module OptParseBuilder
+  class BannerArgument < Argument # :nodoc:
+
+    attr_reader :banner_lines
+
+    def initialize(banner_lines)
+      @banner_lines = banner_lines
+    end
+
+  end
+end

data/lib/opt_parse_builder/constant_argument.rb

@@ -0,0 +1,16 @@
+module OptParseBuilder
+  class ConstantArgument < Argument # :nodoc:
+
+    attr_reader :key
+    attr_reader :value
+
+    def initialize(key, value)
+      unless key
+        raise BuildError, "default requires a key"
+      end
+      @key = key
+      @value = value
+    end
+
+  end
+end

data/lib/opt_parse_builder/errors.rb

@@ -0,0 +1,10 @@
+module OptParseBuilder
+
+  # The base class for all exceptions directly raised by this library.
+  class Error < StandardError ; end
+
+  # Exception raised for an error when building a parser, argument or
+  # argument bundle.
+  class BuildError < Error ; end
+
+end

data/lib/opt_parse_builder/formats_operand_name.rb

@@ -0,0 +1,9 @@
+module OptParseBuilder
+  module FormatsOperandName # :nodoc:
+
+    def format_operand_name(s)
+      s.to_s.gsub(/_/, " ")
+    end
+
+  end
+end

data/lib/opt_parse_builder/has_value.rb

@@ -0,0 +1,21 @@
+module OptParseBuilder
+  module HasValue # :nodoc:
+
+    attr_reader :key
+    attr_accessor :value
+
+    def init_value(key, default)
+      unless key
+        raise BuildError, "argument with value requires a key"
+      end
+      @key = key
+      @default = default
+      reset
+    end
+
+    def reset
+      @value = @default
+    end
+    
+  end
+end

data/lib/opt_parse_builder/null_argument.rb

@@ -0,0 +1,4 @@
+module OptParseBuilder
+  class NullArgument < Argument # :nodoc:
+  end
+end

data/lib/opt_parse_builder/option_argument.rb

@@ -0,0 +1,33 @@
+module OptParseBuilder
+  class OptionArgument < Argument # :nodoc:
+
+    include HasValue
+
+    DEFAULT_HANDLER = ->(argument, value) { argument.value = value }
+
+    def initialize(key, default, on, handler)
+      init_value(key, default)
+      @on = on
+      @handler = handler || DEFAULT_HANDLER
+    end
+
+    def apply_option(op)
+      op.on(*edited_on) do |value|
+        @handler.call(self, value)
+      end
+    end
+
+    private
+
+    def edited_on
+      @on.map do |s|
+        if s.respond_to?(:gsub!)
+          s.gsub(/_DEFAULT_/, @default.to_s)
+        else
+          s
+        end
+      end
+    end
+
+  end
+end

data/lib/opt_parse_builder/optional_operand_argument.rb

@@ -0,0 +1,29 @@
+module OptParseBuilder
+  class OptionalOperandArgument < Argument # :nodoc:
+
+    include FormatsOperandName
+    include HasValue
+
+    def initialize(key, default, help_name)
+      init_value(key, default)
+      @help_name = help_name || key
+    end
+
+    def operand_notation
+      "[<#{format_operand_name(@help_name)}>]"
+    end
+
+    def shift_operand(argv)
+      @value = argv.shift
+    end
+
+    def optional
+      self
+    end
+
+    def required
+      RequiredOperandArgument.new(@key, @default, @help_name)
+    end
+    
+  end
+end

data/lib/opt_parse_builder/parser.rb

@@ -0,0 +1,345 @@
+require "optparse"
+
+require_relative "stable_sort"
+
+module OptParseBuilder
+
+  # A command-line parser.  Create an instance of this by calling
+  # OptParseBuilder.build_parser.
+  #
+  # Note: The constructor for this class is not part of the public
+  # API.
+  class Parser
+
+    include StableSort
+
+    # Controls whether unparsed arguments are an error.
+    #
+    # If `false` (the default), then unparsed arguments cause an
+    # error:
+    #
+    #     arg_parser = OptParseBuilder.build_parser do |args|
+    #       args.allow_unparsed_operands = false
+    #       args.add do |arg|
+    #         arg.key :quiet
+    #         arg.on "-q", "--quiet", "Suppress normal output"
+    #       end
+    #     end
+    #
+    #     ARGV = ["-q", "/tmp/file1", "/tmp/file2"]
+    #     arg_values = arg_parser.parse!
+    #     # aborts with "needless argument: /tmp/file1"
+    #
+    # If `true`, then unparsed operands are not considered an error, and
+    # they remain unconsumed.  Use this setting when you want unparsed
+    # operands to remain in `ARGV` so that they can be used by, for
+    # example, `ARGF`:
+    #
+    #     arg_parser = OptParseBuilder.build_parser do |args|
+    #       args.allow_unparsed_operands = true
+    #       args.add do |arg|
+    #         arg.key :quiet
+    #         arg.on "-q", "--quiet", "Suppress normal output"
+    #       end
+    #     end
+    #
+    #     ARGV = ["-q", "/tmp/file1", "/tmp/file2"]
+    #     arg_values = arg_parser.parse!
+    #     # ARGV now equals ["/tmp/file1", "/tmp/file2"]
+    #     ARGF.each_line do |line|
+    #       puts line unless arg_values.quiet
+    #     end
+    attr_accessor :allow_unparsed_operands
+
+    def initialize # :nodoc:
+      @arguments = []
+      @allow_unparsed_operands = false
+    end
+
+    # Reset to the state after construction, before #parse! was called.
+    # Each argument is set to its default value.  An argument with no
+    # explicit default is set to `nil`.
+    #
+    # This is called implicitly when you call #parse!, so there's seldom
+    # any need for it to be called explicitly.
+    def reset
+      @arguments.each(&:reset)
+      sort_arguments
+    end
+
+    # Parse arguments, consuming them from the array.
+    #
+    # After parsing, there are numerous ways to access the value of the arguments:
+    #
+    #     arg_parser = OptParseBuilder.build_parser do |args|
+    #       args.add do |arg|
+    #         arg.key :num
+    #         arg.on "--num=N", Integer, "A number"
+    #       end
+    #     end
+    #     arg_values = arg_parser.parse!(["--num=123"])
+    #     p arg_parser[:num]     # => 123
+    #     p arg_parser["num"]    # => 123
+    #     p arg_values[:num]     # => 123
+    #     p arg_values["num"]    # => 123
+    #     p arg_values.num       # => 123
+    #
+    # If there are operands (positional arguments) in the array that are
+    # not consumed, an error normally results.  This behavior can be
+    # changed using #allow_unparsed_operands.
+    #
+    # The #parse! method defaults to parsing `ARGV`, which is what is
+    # usually wanted, but you can pass in any array of strings, as the
+    # above example does.
+    #
+    # Design note: A method that modifies its argument _and_ modifies
+    # its object _and_ returns a value is not the best design, violating
+    # the good principle of command-query separation.  However, that
+    # violation is more useful in this case than it is sinful, and it's
+    # the only place in this library that violates that principle.
+    def parse!(argv = ARGV)
+      reset
+      begin
+        op = optparse
+        op.parse!(argv)
+        @arguments.each do |arg|
+          arg.shift_operand(argv)
+        end
+        unless @allow_unparsed_operands || argv.empty?
+          raise OptionParser::NeedlessArgument, argv.first
+        end
+        values
+      rescue OptionParser::ParseError => e
+        abort e.message
+      end
+    end
+
+    # Add a line to the banner.  The banner is text that appears at the
+    # top of the help text.
+    #
+    # A new-line will automatically be added to the end of the line.
+    # Although it's called a "line," you can embed new-lines in it so
+    # that it is actually more than one line.
+    #
+    # This example:
+    #
+    #     arg_parser = OptParseBuilder.build_parser do |args|
+    #       args.banner "This is my program"
+    #       args.banner <<~BANNER
+    #         There are many programs like it,
+    #         but this program is mine.
+    #       BANNER
+    #     end
+    #     arg_parser.parse!(["--help"])
+    #
+    # Results in `--help` output like this:
+    #
+    #     This is my program
+    #     There are many programs like it,
+    #     but this program is mine.
+    #     Usage: example [options] <path>
+    def banner(line)
+      add do |arg|
+        arg.banner(line)
+      end
+    end
+
+    # Add a line to the separator.  The separator is text that appears
+    # at the bottom of the help text.
+    #
+    # A new-line will automatically be added to the end of the line.
+    # Although it's called a "line," you can embed new-lines in it so
+    # that it is actually more than one line.
+    #
+    # This example:
+    #
+    #     arg_parser = OptParseBuilder.build_parser do |args|
+    #       args.separator "Here I explain more about my program"
+    #       args.separator <<~SEPARATOR
+    #         For such a small program,
+    #         it has a lot of text at the end.
+    #       SEPARATOR
+    #     end
+    #     arg_parser.parse!(["--help"])
+    #
+    # Results in `--help` output like this:
+    #
+    #     Usage: example [options] <path>
+    #     Here I explain more about my program
+    #     For such a small program,
+    #     it has a lot of text at the end.
+    def separator(line)
+      add do |arg|
+        arg.separator(line)
+      end
+    end
+
+    # Add an argument.  Must be passed either the argument to add, or
+    # given a block.  If given a block, yields an ArgumentBuilder.
+    #
+    # Example using a pre-built argument:
+    #
+    #     DRY_RUN = OptParseBuilder.build_argument do |arg|
+    #       arg.key :dry_run
+    #       arg.on "-d", "--dry-run", "Make no changes"
+    #     end
+    #     arg_parser = OptParseBuilder.build_parser do |args|
+    #       args.add DRY_RUN
+    #     end
+    #
+    # Example using a block to build the argument in-place:
+    #
+    #     arg_parser = OptParseBuilder.build_parser do |args|
+    #       args.add do |arg|
+    #         arg.key :dry_run
+    #         arg.on "-d", "--dry-run", "Make no changes"
+    #       end
+    #     end
+    #
+    # This is equivalent to:
+    #
+    #     arg_parser = OptParseBuilder.build_parser do |args|
+    #       args.add OptParseBuilder.build_argument do |arg|
+    #         arg.key :dry_run
+    #         arg.on "-d", "--dry-run", "Make no changes"
+    #       end
+    #     end
+    #
+    # See the README for details of the different options available
+    # for an argument.
+    #
+    # Raises BuildError if the argument cannot be built or added.
+    def add(argument = nil, &block)
+      unless argument.nil? ^ block.nil?
+        raise BuildError, "Need exactly 1 of arg and block"
+      end
+      if argument
+        add_argument(argument)
+      else
+        add_argument(OptParseBuilder.build_argument(&block))
+      end
+    end
+
+    # Returns the value of an argument, given either a symbol or a
+    # string with its name.  If the key does not exist, raises KeyError.
+    #
+    #     arg_parser = OptParseBuilder.build_parser do |args|
+    #       args.add do |arg|
+    #         arg.key :x
+    #         arg.default 123
+    #       end
+    #     end
+    #     arg_parser[:x]     # => 123
+    #     arg_parser["x"]    # => 123
+    #     arg_parser[:y]     # KeyError (key not found :y)
+    #
+    # See also:
+    #
+    #   * method #values - returns a collection of all argument values
+    #   * method #has_key? - find out if the parser knows about a key
+    def [](key)
+      find_argument!(key).value
+    end
+
+    # Return a collection with all of the argument values.  The
+    # collection can be accessed in several ways:
+    #
+    #     arg_parser = OptParseBuilder.build_parser do |args|
+    #       args.add do |arg|
+    #         arg.key :num
+    #         arg.on "--num=N", Integer, "A number"
+    #       end
+    #     end
+    #     arg_parser.parse!(["--num=123"])
+    #     arg_values = arg_parser.values
+    #     p arg_values[:num]     # => 123
+    #     p arg_values["num"]    # => 123
+    #     p arg_values.num       # => 123
+    def values
+      av = ArgumentValues.new
+      @arguments.each do |arg|
+        av[arg.key] = arg.value if arg.key
+      end
+      av
+    end
+
+    # Return true if the parser has the named key, which may be either a
+    # string or a symbol.
+    #
+    #     arg_parser = OptParseBuilder.build_parser do |args|
+    #       args.add do |arg|
+    #         arg.key :quiet
+    #       end
+    #     end
+    #     arg_parser.has_key?(:quiet)      # => true
+    #     arg_parser.has_key?("quiet")     # => true
+    #     arg_parser.has_key?(:verbose)    # => false
+    def has_key?(key)
+      !!find_argument(key)
+    end
+
+    private
+
+    def sort_arguments
+      stable_sort_by!(@arguments) do |arg|
+        case arg
+        when RequiredOperandArgument
+          1
+        when OptionalOperandArgument
+          2
+        when SplatOperandArgument
+          3
+        else
+          0
+        end
+      end
+    end
+
+    def find_argument!(key)
+      argument = find_argument(key)
+      unless argument
+        raise Key, "key not found #{key.inspect}"
+      end
+      argument
+    end
+
+    def find_argument(key)
+      key = key.to_sym
+      @arguments.find do |arg|
+        arg.key == key
+      end
+    end
+
+    def optparse
+      op = OptParse.new
+      op.banner = banner_prefix + op.banner + banner_suffix
+      @arguments.each { |arg| arg.apply_option(op) }
+      @arguments.each do |argument|
+        argument.separator_lines.each do |line|
+          op.separator(line)
+        end
+      end
+      op
+    end
+
+    def add_argument(argument)
+      if argument.key && has_key?(argument.key)
+        raise BuildError, "duplicate key #{argument.key}"
+      end
+      @arguments.concat(argument.to_a.map(&:dup))
+    end
+
+    def banner_prefix
+      @arguments.flat_map(&:banner_lines).map do |line|
+        line + "\n"
+      end.join
+    end
+
+    def banner_suffix
+      suffix = @arguments.map(&:operand_notation).compact.join(" ")
+      suffix = " " + suffix unless suffix.empty?
+      suffix
+    end
+
+  end
+end