opt_parse_builder 0.1.0

data/Rakefile

@@ -0,0 +1,13 @@
+require "rubygems"
+require "bundler"
+
+begin
+  Bundler.setup(:default, :development)
+rescue Bundler::BundlerError => e
+  $stderr.puts e.message
+  $stderr.puts "Run `bundle install` to install missing gems"
+  exit e.status_code
+end
+
+$:.unshift(File.dirname(__FILE__) + "/lib")
+Dir["rake/**/*.rake"].sort.each { |path| load path }

data/examples/hello_world.rb

@@ -0,0 +1,20 @@
+#!/usr/bin/env ruby
+
+require "opt_parse_builder"
+
+ARG_PARSER = OptParseBuilder.build_parser do |args|
+  args.banner "A simple example"
+  args.add do |arg|
+    arg.key :path
+    arg.required_operand
+  end
+  args.add do |arg|
+    arg.key :verbose
+    arg.on "-v", "--verbose", "Be verbose"
+  end
+  args.separator "Some explanatory text at the bottom"
+end
+
+arg_values = ARG_PARSER.parse!
+p arg_values.verbose
+p arg_values.path

data/lib/opt_parse_builder.rb

@@ -0,0 +1,156 @@
+require "optparse"
+
+require_relative "opt_parse_builder/argument"
+require_relative "opt_parse_builder/argument_builder"
+require_relative "opt_parse_builder/argument_bundle"
+require_relative "opt_parse_builder/argument_bundle_builder"
+require_relative "opt_parse_builder/argument_values"
+require_relative "opt_parse_builder/banner_argument"
+require_relative "opt_parse_builder/constant_argument"
+require_relative "opt_parse_builder/errors"
+require_relative "opt_parse_builder/formats_operand_name"
+require_relative "opt_parse_builder/has_value"
+require_relative "opt_parse_builder/null_argument"
+require_relative "opt_parse_builder/option_argument"
+require_relative "opt_parse_builder/optional_operand_argument"
+require_relative "opt_parse_builder/parser"
+require_relative "opt_parse_builder/parser_builder"
+require_relative "opt_parse_builder/required_operand_argument"
+require_relative "opt_parse_builder/separator_argument"
+require_relative "opt_parse_builder/splat_operand_argument"
+require_relative "opt_parse_builder/stable_sort"
+
+# The namespace of this library, and the sole entry point.  You never
+# have to (and never should) explicitly refer to any other class or
+# module of this library than this one.  There are a few other classes
+# you will use, but they will be created for you by methods of this
+# module.
+#
+# Minimal example:
+#
+#     arg_parser = OptParseBuilder.build_parser
+#     arg_parser.parse!
+#
+# An example with a little bit of everything
+#
+#     arg_parser = OptParseBuilder.build_parser do |p|
+#       parser.banner "A short description of the program"
+#       parser.add do |arg|
+#         arg.key :output_path
+#         arg.required_operand
+#       end
+#       parser.add do |arg|
+#         arg.key :input_paths
+#         arg.splat_operand
+#       end
+#       parser.add do |arg|
+#         arg.key :quiet
+#         arg.on "-q", "--quiet", "Be quiet"
+#       end
+#       parser.add do |arg|
+#         arg.key :size
+#         arg.default 1024
+#         arg.on "--size=N", Integer
+#         arg.on "Size in bytes (default _DEFAULT_)"
+#       end
+#       parser.separator "Explanatory text at the bottom"
+#     end
+#     arg_values = arg_parser.parse!
+#     p arg_values.quiet          # nil or true
+#     p arg_values.size           # An Integer
+#     p arg_values.output_path    # A string
+#     p arg_values.input_paths    # An array of strings
+module OptParseBuilder
+
+  # Create a new parser.  If called without a block, returns a parser
+  # than you can then add arguments to:
+  #
+  #     arg_parser = OptParseBuilder.build_parser
+  #     arg_parser.add do |arg|
+  #       arg.key :force
+  #       arg.on "--force", "Force dangerous operation"
+  #     end
+  #
+  # If called with a block, yields itself to the block:
+  #
+  #     arg_parser = OptParseBuilder.build_parser do |args|
+  #       args.add do |arg|
+  #         arg.key :force
+  #         arg.on "--force", "Force dangerous operation"
+  #       end
+  #     end
+  #
+  # Note that the parser constructed using the block form can still
+  # be added onto:
+  #
+  #     arg_parser.add do |arg|
+  #       arg.key :size
+  #       arg.on "--size=N", Integer, "File size in bytes"
+  #     end
+  #    
+  def self.build_parser
+    parser_builder = ParserBuilder.new
+    yield parser_builder if block_given?
+    parser_builder.parser
+  end
+
+  # Build an argument that can be added to a parser.  Yields an
+  # ArgumentBuilder.  Returns the  argument created by the builder.
+  #
+  #     VERBOSE = OptParseBuilder.build_argument do |arg|
+  #       arg.key :verbose
+  #       arg.on "-v", "--verbose", "Print extra output"
+  #     end
+  #
+  #     arg_parser = OptParseBuilder.build_parser do |args|
+  #       args.add VERBOSE
+  #     end
+  #
+  # See the README for argument examples.
+  #
+  # Raises BuildError if the argument cannot be built or added.
+  #
+  # This is most useful when you are building a related suite of
+  # programs that share some command-line arguments in common.  Most
+  # of the time you will just add the argument using the block form of
+  # OptParseBuilder#add.
+  def self.build_argument
+    builder = ArgumentBuilder.new
+    yield builder
+    builder.argument
+  end
+
+  # Build a bundle of arguments that can be added to a parser
+  # together.  Yields an ArgumentBundleBuilder.
+  #
+  # This is useful when you have a group of arguments that go
+  # together:
+  #
+  #     bundle = OptParseBuilder.build_bundle do |args|
+  #       args.add do |arg|
+  #         arg.key :x
+  #         op.on "-x", Integer, "X coordinate"
+  #       end
+  #       args.add do |arg|
+  #         arg.key :y
+  #         op.on "-y", Integer, "Y coordinate"
+  #       end
+  #     end
+  #
+  #     arg_parser = OptParseBuilder.build_parser do |args|
+  #       args.add bundle
+  #     end
+  #
+  # Raises BuildError if the argument cannot be built or added.
+  #
+  # This is most useful when you are building a related suite of
+  # programs that share some command-line arguments in common.  Most
+  # of the time you will just add the arguments using the block form
+  # of OptParseBuilder#add.
+  def self.build_bundle
+    bundler = ArgumentBundleBuilder.new
+    yield bundler
+    bundler.argument
+  end
+
+end

data/lib/opt_parse_builder/argument.rb

@@ -0,0 +1,62 @@
+module OptParseBuilder
+
+  # The base class for all arguments.  You don't create arguments
+  # explicitly; they are created by for you when you use the builder
+  # API.
+  class Argument
+
+    def key # :nodoc:
+    end
+
+    # Get an argument's value.  Returns nil if the argument has no
+    # value.  This is made public for the use of a handler proc (See
+    # ArgumentBuilder#handler).
+    def value
+    end
+
+    # Set the argument's value.  Does nothing if the argument has no
+    # value.  This is made public for the use of a handler proc (See
+    # ArgumentBuilder#handler).
+    def value=(_v)
+    end
+
+    def banner_lines # :nodoc:
+      []
+    end
+
+    def operand_notation # :nodoc:
+    end
+
+    def separator_lines # :nodoc:
+      []
+    end
+
+    def apply_option(_op) # :nodoc:
+    end
+
+    def shift_operand(_argv) # :nodoc:
+    end
+
+    def reset # :nodoc:
+    end
+
+    def to_a # :nodoc:
+      [self]
+    end
+
+    # Convert from a required operand to an optional one, returning a
+    # new argument.  Raises an error if that isn't possible.
+    def optional
+      raise BuildError,
+            "cannot convert #{self.class.name} to an optional operand"
+    end
+
+    # Convert from a required operand to an optional one, returning a
+    # new argument.  Raises an error if that isn't possible.
+    def required
+      raise BuildError,
+            "cannot convert #{self.class.name} to a required operand"
+    end
+       
+  end
+end

data/lib/opt_parse_builder/argument_builder.rb

@@ -0,0 +1,193 @@
+module OptParseBuilder
+
+  # Builds arguments using a builder style DSL.  You never create an
+  # instance of this class yourself.  Instead, an instance is yielded
+  # to you by OptParseBuilder.
+  #
+  # See the README for examples.
+  class ArgumentBuilder
+
+    def initialize # :nodoc:
+      @key = nil
+      @default = nil
+      @on = []
+      @handler = nil
+      @operand_class = nil
+      @operand_help_name = nil
+      @banner_lines = []
+      @separator_lines = []
+    end
+
+    # Set the argument's key.  Accepts either a string or a symbol.
+    def key(v)
+      @key = v.to_sym
+    end
+
+    # Set the argument's default value.  This it the value an argument
+    # has before parsing, or if parsing does not set the value.
+    #
+    # If an argument's default value is not explicitly set, then the
+    # default value is `nil`.
+    def default(v)
+      @default = v
+    end
+
+    # Declares the argument to be an option that is handled by
+    # OptParse.  The arguments are passed to OptParse exactly as you
+    # give them, except that the string _DEFAULT_ is replaced with the
+    # argument's default value.
+    #
+    # Simple example:
+    #
+    #     arg = OptParseBuilder.build_argument do |arg|
+    #       arg.key :quiet
+    #       arg.on "-q", "Be very veru quiet", "We're hunting rabbit!"
+    #     end
+    #
+    # You may split up a long argument list by calling this method
+    # more than once.  This is equivalent to the above:
+    #
+    #     arg = OptParseBuilder.build_argument do |arg|
+    #       arg.key :quiet
+    #       arg.on "-q", "Be very veru quiet",
+    #       arg.on "We're hunting rabbit!"
+    #     end
+    #
+    # So that the option's help may print the default without having
+    # to duplicate it, the string _DEFAULT_ is replaced with the
+    # argument's default value:
+    #
+    #     arg = OptParseBuilder.build_argument do |arg|
+    #       arg.key :size
+    #       arg.default 1024
+    #       arg.on "--size=N", Integer,
+    #       arg.on "Size in bytes (default _DEFAULT_)"
+    #     end
+    #
+    # When the `--help` text for this argument is printed, it will
+    # read:
+    #
+    #     --size-N               Size in bytes (default 1024)
+    def on(*option_args)
+      @on.concat(option_args)
+    end
+
+    # Set a handler, a proc that will will process the argument's
+    # value.  The proc takes two arguments:
+    #
+    # * The Argument
+    # * The value
+    #
+    # If no handler is set, it defaults to
+    #
+    #     `->(argument, value) { argument.value = value }
+    #
+    # Applies to these argument types:
+    #
+    # * Simple option
+    # * Option with value
+    #
+    # Example:
+    #
+    #     arg = OptParseBuilder.build_argument do |arg|
+    #       arg.key :square
+    #       arg.on "-v", "Increase verbosity (can give more than once)"
+    #       arg.handler do |argument, _value|
+    #         argument.value += 1
+    #       end
+    #     end
+    def handler(&block)
+      @handler = block
+    end
+
+    # Add to the banner text shown first in the --help output.  You
+    # may call this more than once; each call adds another line of
+    # text to the banner.
+    #
+    # Any type of argument may have banner text.
+    #
+    # See also OptParseBuilder#banner
+    def banner(line)
+      @banner_lines << line
+    end
+
+    # Add to the separator text shown last in the --help output.  You
+    # may call this more than once; each call adds another line of
+    # text to the separator.
+    #
+    # Any type of argument may have separator text.
+    #
+    # See also OptParseBuilder#separator
+    def separator(line)
+      @separator_lines << line
+    end
+
+    # Declare the operand to be an optional operand.  An optional
+    # operand consumes one argument.  If the argument is not present,
+    # value is either the default (if provided), or nil (if no default
+    # was provided).
+    def optional_operand(help_name: nil)
+      check_operand_class_not_set
+      @operand_class = OptionalOperandArgument
+      @operand_help_name = help_name
+    end
+
+    # Declare the operand to be a required operand.  A required
+    # operand consumes one argument, generating an error if there is
+    # not one.
+    def required_operand(help_name: nil)
+      check_operand_class_not_set
+      @operand_class = RequiredOperandArgument
+      @operand_help_name = help_name
+    end
+
+    # Declare the argument to be a "splat" operand.  A splat operand
+    # consumes all remaining arguments.
+    def splat_operand(help_name: nil)
+      check_operand_class_not_set
+      @operand_class = SplatOperandArgument
+      @operand_help_name = help_name
+    end
+
+    def argument # :nodoc:
+      check_for_build_errors
+      bundle = ArgumentBundle.new
+      unless @banner_lines.empty?
+        bundle << BannerArgument.new(@banner_lines)
+      end
+      unless @separator_lines.empty?
+        bundle << SeparatorArgument.new(@separator_lines)
+      end
+      if !@on.empty?
+        bundle << OptionArgument.new(@key, @default, @on, @handler)
+      elsif @operand_class
+        bundle << @operand_class.new(
+          @key,
+          @default,
+          @operand_help_name,
+        )
+      else
+        if @key || @default
+          bundle << ConstantArgument.new(@key, @default)
+        end
+      end
+      bundle.simplify
+    end
+
+    private
+
+    def check_operand_class_not_set
+      if @operand_class
+        raise BuildError, "Argument is already an operand"
+      end
+    end
+
+    def check_for_build_errors
+      if !@on.empty? && @operand_class
+        raise BuildError,
+              "Argument cannot be both an option and an operand"
+      end
+    end
+    
+  end
+end

data/lib/opt_parse_builder/argument_bundle.rb

@@ -0,0 +1,30 @@
+module OptParseBuilder
+  class ArgumentBundle < Argument # :nodoc:
+
+    def initialize
+      @arguments = []
+    end
+
+    def <<(argument)
+      @arguments << argument
+    end
+
+    def to_a
+      @arguments.reduce([]) do |a, arg|
+        a + arg.to_a
+      end
+    end
+
+    def simplify
+      case @arguments.count
+      when 0
+        NullArgument.new
+      when 1
+        @arguments.first
+      else
+        self
+      end
+    end
+
+  end
+end