opt_parse_builder 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 28f64f160f1a3940a3884f5f56ecba366ba6078be1c3032b625f0cded4124259
+  data.tar.gz: d81a3b030a5e8b60b97577148c5e91810c7a9125e0f08c6ad01e68f76a0d58ff
+SHA512:
+  metadata.gz: d48ea90e1d556a24a649124d33ca1329c743384066da239472c240aec47b9b113785a9e321365b2fac1b4f90ef08e9a370664693c330b326e0a510f666d650d4
+  data.tar.gz: 68ccc121fe7a7703f16d2bac471a69abcf0af241a7c85aef53554de9c1609bb464e2a8a5eba3ad1fd39a382d91d5f433cab554e55be6a072347ed96d24fb2f27

data/.gitignore

@@ -0,0 +1,2 @@
+html
+*.gem

data/.rspec

@@ -0,0 +1 @@
+--require spec_helper

data/.ruby-version

@@ -0,0 +1 @@
+ruby-2.7.2

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+# -*- mode: fundamental -*-
+	
+# Development
+
+* Initial release

data/Gemfile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+git_source(:github) {|repo_name| "https://github.com/#{repo_name}" }
+
+# Specify your gem's dependencies in opt_parse_builder.gemspec
+gemspec

data/Gemfile.lock

@@ -0,0 +1,35 @@
+PATH
+  remote: .
+  specs:
+    opt_parse_builder (0.1.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    diff-lcs (1.4.4)
+    rake (13.0.1)
+    rspec (3.10.0)
+      rspec-core (~> 3.10.0)
+      rspec-expectations (~> 3.10.0)
+      rspec-mocks (~> 3.10.0)
+    rspec-core (3.10.0)
+      rspec-support (~> 3.10.0)
+    rspec-expectations (3.10.0)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.10.0)
+    rspec-mocks (3.10.0)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.10.0)
+    rspec-support (3.10.0)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  bundler (~> 2.1)
+  opt_parse_builder!
+  rake (~> 13.0)
+  rspec (~> 3.10)
+
+BUNDLED WITH
+   2.1.4

data/LICENSE

@@ -0,0 +1,23 @@
+Copyright 2020 Wayne Conrad
+
+This software is distributed under the [MIT
+License](http://opensource.org/licenses/MIT):
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,434 @@
+# opt_parse_builder
+
+A Ruby Gem for processing CLI arguments using optparse.  Adds to
+optparse a compact builder-style DSL, operand (positional argument)
+parsing, and composability for sharing argument definitions within a
+suite of commands.
+
+Features:
+
+* A  compact, simple [builder style DSL](#label-Terminology)
+
+* Composability - Arguments can be [defined separately from their
+  use](#label-Composability), allowing common arguments to be shared
+  shared within a suite of programs.
+
+* Operand parsing - Adds [parsing of
+  operands](#label-Required+Operand)) (aka positional arguments)
+
+* Builds on solid ground - Uses tried and true OptParse.
+
+* Familiarity - Arguments to OptParse#on are passed through with very
+  little change, so you don't have to learn a new syntax for defining
+  options.
+
+* Not a framework - This library provides _only_ improved argument
+  parsing.  There is no base class for your program to inherit from,
+  no module for it to include, and no imposed structure.
+
+* No magic, no surprises - Plain and explicit.
+
+* Cohesion - Everything about an argument is defined in one place.
+  You don't have to define the argument's help text in one place, the
+  default value in another, etc.
+
+* Narrow API - Simple and easy to use.
+
+* Fully documented - Includes full code documentation and examples.
+
+* Stable API - Uses [semantic
+  versioning](ttps://semver.org/spec/v2.0.0.html).  Promises not to
+  break your program without incrementing the major version number.
+
+* Programmed simply - Easy to understand and modify.
+
+* Fully tested - Extensive unit test suite.
+
+# Hello, World
+
+It is valuable to provide a simple example which can be modified and
+expanded upon:
+
+```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
+```
+
+# Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'opt_parse_builder'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install opt_parse_builder
+
+# Explanation of some features
+
+## Builder style DSL
+
+You build an argument parser using a builder style DSL, like this:
+
+```ruby
+arg_parser = OptParseBuilder.build_parser do |args|
+  args.add do |arg|
+    arg.key :verbose
+    arg.on "-v", "--verbose", "Be verbose"
+  end
+end
+```
+
+Once built, a parser is normally used like this:
+
+    arg_values = arg_parser.parse!
+
+and argument values retrieved using struct or hash notation:
+
+    p arg_values.verbose
+    p arg_values[:verbose]
+
+## Composability
+
+An argument definition can be created separately from its use:
+
+```ruby
+VERBOSE = OptParseBuilder.build_argument do |arg|
+  arg.key :verbose
+  arg.on "-v", "--verbose", "Print extra output"
+end
+
+parser = OptParseBuilder.build_parser do |args|
+  args.add VERBOSE
+end
+```
+
+This is especially useful where a suite of programs share some
+arguments in common.  Instead of defining common arguments over and
+over, you can define them once and then reuse them in each program:
+
+```ruby
+# common_arguments.rb
+
+require "opt_parse_builder"
+
+module CommonArguments
+  VERBOSE = OptParseBuilder.build_argument do |arg|
+    arg.key :verbose
+    arg.on "-v", "--verbose", "Print extra output"
+  end
+end
+```
+
+```ruby
+# read_input.rb
+
+require_relative "common_arguments"
+
+ARG_PARSER = OptParseBuilder.build_parser do |args|
+  args.banner "Read and store the input data"
+  args.add do |arg|
+    arg.key 
+    arg.required_operand
+  end
+  args.add CommonArguments::VERBOSE
+end
+```
+
+```ruby
+# write_report.rb
+
+require_relative "common_arguments"
+
+ARG_PARSER = OptParseBuilder.build_parser do |args|
+  args.banner "Print a report based on data previously read"
+  args.add CommonArguments::VERBOSE
+  args.add do |arg|
+    arg.key :detail
+    arg.on "-d", "--detail", "Add the detail section to the report"
+  end
+end
+```
+
+When adding a pre-built operand to a parser, you can change change
+it from required to optional:
+
+```
+PATH = OptParseBuilder.build_argument do |arg|
+  arg.key :path
+  arg.required_operand
+end
+
+ARG_PARSER = OptParser.build_parser do |args|
+  args.add PATH.optional
+end
+```
+
+or from optional to required:
+
+```
+PATH = OptParseBuilder.build_argument do |arg|
+  arg.key :path
+  arg.optional_operand
+end
+
+ARG_PARSER = OptParser.build_parser do |args|
+  args.add PATH.required
+end
+```
+
+# Argument Building Examples
+
+Most of these examples use a shorthand where the surrounding code
+is not shown:
+
+    arg.key = :foo
+    arg.on "-f"
+
+With the surrounding code, that would be this:
+
+    parser = OptparserBuilder.new do |args|
+      args.add do |arg|
+        arg.key = :foo
+        arg.on = "-f"
+      end
+    end
+
+or this:
+
+    arg = OptParseBuilder.build_argument do |arg|
+      arg.key = :foo
+      arg.on = "-f"
+    end
+
+## Null argument
+
+A null argument, having no value or visible effect:
+
+    OptParseBuilder.build_argument do |arg|
+    end
+
+This has little value to you, but it fell out of the design for
+free, and it is useful in the implementation.
+
+## Banner only
+
+An argument with only banner text (but see OptParseBuilder#banner
+for the usual way to do this).  "Banner" is how OptParse describes
+text that appears at the top of the --help output.
+
+    OptParseBuilder.build_argument do |arg|
+      arg.banner "Some banner text"
+      arg.banner "A second line of banner text"
+      arg.banner <<~BANNER
+        A third line
+        A fourth line
+      BANNER
+    end
+
+Applicable builder methods:
+
+* banner
+
+Banner text can be added to any argument.
+
+## Separator only
+
+An argument with only separator text (but see
+OptParseBuilder#banner for the usual way to do this).  "Separator"
+is how OptParse describes text that appears at the bottom of the
+--help output.
+
+    OptParseBuilder.build_argument do |arg|
+      arg.serparator "Separator text"
+      arg.serparator "A second line of separator text"
+      arg.serparator <<~SERPARATOR
+        A third line
+        A fourth line
+      SERPARATOR
+    end
+
+Applicable builder methods:
+
+* separator
+
+Separator text can be added to any argument.
+
+## Constant value
+
+An argument with a constant value.
+
+    OptParseBuilder.build_argument do |arg|
+      arg.key :limit
+      arg.default 12345
+    end
+
+Applicable builder methods:
+
+* key
+* default
+* banner (optional)
+* separator (optional)
+
+This is of limited value, but it fell out of the design for free.
+
+## Simple option
+
+A simple option parsed by OptParse:
+
+    OptParseBuilder.build_argument do |arg|
+      arg.key :quiet
+      arg.on "-q", "--quiet", "Suppress normal output"
+    end
+
+Applicable builder methods:
+
+* key
+* on
+* default (optional)
+* handler (optional)
+* banner (optional)
+* separator (optional)
+
+## Option with value
+
+A value option parsed by OptParse:
+
+    OptParseBuilder.build_argument do |arg|
+      arg.key :iterations
+      arg.default 100
+      arg.on "-i", "--iterations=N",
+      arg.on "Number of iterations (default _DEFAULT_)"
+    end
+
+Applicable builder methods:
+
+* key
+* on
+* default (optional)
+* handler (optional)
+* banner (optional)
+* separator (optional)
+
+## Required Operand
+
+A required operand consumes one argument, with an error if there
+isn't one to consume.
+
+This example overrides the help name, which is used to describe
+the operand in the --help text.  Optional and splat arguments can
+also have a help name override.
+
+    OptParseBuilder.build_argument do |arg|
+      arg.key :group
+      arg.required_operand help_name: "resource group"
+      arg.optional_operand
+    end
+
+Applicable builder methods:
+
+* key
+* required_operand
+* default (optional)
+* banner (optional)
+* separator (optional)
+
+## Optional operand
+
+An optional operand consumes one argument.  If there isn't an
+argument to consume, then the value is either nil (if no default
+was specified), or the specified default value.
+
+    OptParseBuilder.build_argument do |arg|
+      arg.key :group_name
+      arg.default "main"
+      arg.optional_operand
+    end
+
+Applicable builder methods:
+
+* key
+* optional_operand
+* default (optional)
+* banner (optional)
+* separator (optional)
+
+## Splat Operand
+
+A "splat" operand consumes all remaining arguments.  Its value is
+always an array.
+
+    OptParseBuilder.build_argument do |arg|
+      arg.key :input_path
+      arg.optional_operand
+    end
+
+Applicable builder methods:
+
+* key
+* splat_operand
+* default (optional)
+* banner (optional)
+* separator (optional)
+
+# Development
+
+After checking out the repo, run `bundle` to install dependencies.
+Then run `rake test` to run the tests.
+
+To install this gem onto your local machine, run `bundle exec rake
+install`.  To release a new version, update the version number in
+`version.rb`, and then run `bundle exec rake release`, which will
+create a git tag for the version, push git commits and tags, and push
+the `.gem` file to [rubygems.org](https://rubygems.org).
+
+# Contributing
+
+Bug reports and pull requests are welcome on GitHub at
+https://github.com/wconrad/opt_parse_builder.
+
+# Terminology
+
+These terms are used in this library's code and documentation:
+
+* Argument - An option or operand; a single element of ARGV
+
+* Option - An argument parsed by optparse, like `-v` or `--size=12`
+
+* Switch - An option that is either present or not, like `-v`
+
+* Value option - An option with a value, like `--size=12`
+
+* Operand - An argument not parsed by optparse, like
+  `/path/to/my/file`.  Also called a "positional argument."
+  
+* Required operand - An operand that must be present or an error
+  results.
+
+* Optional operand - An operand that may be present or not; if not
+  present, it receives either `nil` or a default that you set.
+
+* Splat operand - An operand that consumes all remaining operands,
+  resulting in an array (possibly empty) of strings.