optimist 3.1.0 → 3.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 87e142709336212fa484755022a85b8d833de889579b69a1b2fc35933bac88fd
-  data.tar.gz: 4ac2b33acae583f3ce444c105112c144a32affc52a8ab52980ab9772a107f8c3
+  metadata.gz: 416ba2a0bcc410fa9e8a746b73335cff35b550634d4f26a7c1c17547db2ba61b
+  data.tar.gz: 1a2b555e3a7ec6eef5af0976d660454151888052e9492695ac5d932090e858ee
 SHA512:
-  metadata.gz: 7ccadd2b388b3877e3a075e224b7b9f1ed3b48a4dd68a72a6ca7f8ca9120c999a366d0619bf1cfcec0018fd80baeab83fd8e686e35f91109668c4d0210e08ddd
-  data.tar.gz: '0312801235dc1952812a79d01d68b71cff4db8187040cbc74f299bb519d926dc01fed15f0c656ca7d09e18dcd18289b1d951917cc31c8a8e1bfaa1377cbcde99'
+  metadata.gz: 0ce87d7db57a7840f84cb9be3c0aad95e9dd227becbf873309ea7256175be969b937742ca781b0f5345e71ca73a6cc508e5d1e0953d03391fb44e5efa43e681c
+  data.tar.gz: a760065b4b8e4477e9fd90644b92e7b802eff249cc6f742d83cb8f891e1d35b9cbfbc9380a2fb6fc6f75f69cd2a1741336ee900a61b6e4abae23d82005b75b06

data/.codeclimate.yml

@@ -12,5 +12,5 @@ plugins:
   rubocop:
     enabled: true
     config: ".rubocop_cc.yml"
-    channel: rubocop-0-82
+    channel: rubocop-1-56-3
 version: '2'

data/.github/workflows/ci.yaml

@@ -20,11 +20,12 @@ jobs:
         - '3.0'
         - '3.1'
         - '3.2'
+        - '3.3'
         - jruby-9.3
         - ruby-head
         - jruby-head
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v4
     - name: Set up Ruby
       uses: ruby/setup-ruby@v1
       with:
@@ -32,3 +33,4 @@ jobs:
         bundler-cache: true
     - name: Run tests
       run: bundle exec rake
+      continue-on-error: ${{ matrix.ruby-version == 'ruby-head' }}

data/CHANGELOG.md

@@ -4,9 +4,229 @@ This project adheres to [Semantic Versioning](http://semver.org/).
 
 ## [Unreleased]
 
+## [3.2.0] - 2024-11-11
+### Added
+- Align the short and long forms into their own columns in the help output ([#145](https://github.com/ManageIQ/optimist/pull/145) - thanks @akhoury6)
+- Add support for DidYouMean when long options are spelled incorrectly ([#150](https://github.com/ManageIQ/optimist/pull/150) - thanks @nanobowers)
+- Using `permitted:` restricts the allowed values that a end-user inputs to a pre-defined list ([#147](https://github.com/ManageIQ/optimist/pull/147) - thanks @akhoury6)
+- Add exact_match to settings, defaulting to inexact matching ([#154](https://github.com/ManageIQ/optimist/pull/154) - thanks @nanobowers)
+- Add setting to disable implicit short options ([#155](https://github.com/ManageIQ/optimist/pull/155) - thanks @nanobowers)
+- Add alt longname and multiple char support ([#151](https://github.com/ManageIQ/optimist/pull/151) - thanks @nanobowers)
+- Permitted regexp/range support ([#158](https://github.com/ManageIQ/optimist/pull/158), [#159](https://github.com/ManageIQ/optimist/pull/159) - thanks @nanobowers)
+- Add some examples ([#161](https://github.com/ManageIQ/optimist/pull/161) - thanks @nanobowers)
+
+### Changed
+- Enable frozen_string_literal for future-ruby support ([#149](https://github.com/ManageIQ/optimist/pull/149), [#153](https://github.com/ManageIQ/optimist/pull/153)  - thanks @nanobowers)
+- Refactor constraints ([#156](https://github.com/ManageIQ/optimist/pull/156) - thanks @nanobowers)
+- Fix assert_raises to assert_raises_errmatch ([#160](https://github.com/ManageIQ/optimist/pull/160) - thanks @nanobowers)
+
 ## [3.1.0] - 2023-07-24
 ### Added
-- Implement `either` command ([#130](https://github.com/ManageIQ/optimist/pull/130))
+- Implement `either` command ([#130](https://github.com/ManageIQ/optimist/pull/130) - thanks @alezummo)
+
+## [3.0.1] - 2020-04-20
+
+- Add a LICENSE.txt file to the released package
+- Test fixes (thanks @aried3r, @neontapir, @npras)
+
+## [3.0.0] - 2018-08-24
+
+- The gem has been officially renamed to optimist
+
+## [2.1.3] - 2018-07-05
+
+- Refactor each option type into subclasses of Option.  Define a registry for the registration of each option.  This makes the code more modular and facilitates extension by allowing additional Option subclasses. (thanks @clxy)
+- Fixed implementation of ignore_invalid_options. (thanks @metcalf)
+- Various warning cleanup for ruby 2.1, 2.3, etc. (thanks @nanobowers)
+- Optimist.die can now accept an error code.
+- fixed default (thanks @nanobowers)
+- Change from ruby license to MIT license in the code.
+
+## [2.1.2] - 2015-03-10
+
+- loosen mime-types requirements (for better ruby 1.8.7 support)
+- use io/console gem instead of curses (for better jruby support)
+- fix parsing bug when chronic gem is not available
+- allow default array to be empty if a type is specified
+- better specified license and better spec coverage
+
+## [2.1.1] - 2015-01-03
+
+- Remove curses as a hard dependency. It is optional. This can leverage the gem if it is present.
+- Fix ruby -w warnings
+
+## 2.1.0 - 2015-01-02
+
+- Integer parser now supports underscore separator.
+- Add Parser#usage and Parser#synopsis commands for creating a standard banner
+  message. Using Parser#banner directly will override both of those.
+- Add Parser#ignore_invalid_options to prevent erroring on unknown options.
+- Allow flags to act as switches if they have defaults set and no value is
+  passed on the commandline
+- Parser#opt learned to accept a block or a :callback option which it will call
+  after parsing the option.
+- Add Optimist::educate which displays the help message and dies.
+- Reformat help message to be more GNUish.
+- Fix command name in help message when script has no extension.
+- Fix handling of newlines inside descriptions
+- Documentation and other fixes.
+
+## 2.0 - 2012-08-11
+
+- Change flag logic: --no-X will always be false, and --X will always be true,
+  regardless of default.
+- For flags that default to true, display --no-X instead of --X in the help
+  menu. Accept both versions on the commandline.
+- Fix a spurious warning
+- Update Rakefile to 1.9
+- Minor documentation fixes
+
+## 1.16.2 - 2010-04-06
+
+- Bugfix in Optimist::options. Thanks to Brian C. Thomas for pointing it out.
+
+## 1.16.1 - 2010-04-05
+
+- Bugfix in Optimist::die method introduced in last release.
+
+## 1.16 - 2010-04-01
+
+- Add Optimist::with_standard_exception_handling method for easing the use of Parser directly.
+- Handle scientific notation in float arguments, thanks to Will Fitzgerald.
+- Drop hoe dependency.
+
+## 1.15 - 2009-09-30
+
+- Don't raise an exception when out of short arguments (thanks to Rafael
+  Sevilla for pointing out how dumb this behavior was).
+
+## 1.14 - 2009-06-19
+- Make :multi arguments default to [], not nil, when not set on the commandline.
+- Minor commenting and error message improvements
+
+## 1.13 - 2009-03-16
+
+- Fix parsing of "--longarg=<value with spaces>".
+
+## 1.12 - 2009-01-30
+
+- Fix some unit test failures in the last release. Should be more careful.
+- Make default short options only be assigned *after- all user-specified
+  short options. Now there's a little less juggling to do when you just
+  want to specify a few short options.
+
+## 1.11 - 2009-01-29
+
+- Set <opt>_given keys in the results hash for options that were specified
+  on the commandline.
+
+## 1.10.2 - 2008-10-23
+
+- No longer try `stty size` for screen size detection. Just use curses, and
+  screen users will have to deal with the screen clearing.
+
+## 1.10.1 - 2008-10-22
+
+- Options hash now responds to method calls as well as standard hash lookup.
+- Default values for multi-occurrence parameters now autoboxed.
+- The relationship between multi-value, multi-occurrence, and default values
+  improved and explained.
+- Documentation improvements.
+
+## 1.10 - 2008-10-21
+
+- Added :io type for parameters that point to IO streams (filenames, URIs, etc).
+- For screen size detection, first try `stty size` before loading Curses.
+- Improved documentation.
+
+## 1.9 - 2008-08-20
+
+- Added 'stop_on_unknown' command to stop parsing on any unknown argument.
+  This is useful for handling sub-commands when you don't know the entire
+  set of commands up front. (E.g. if the initial arguments can change it.)
+- Added a :multi option for parameters, signifying that they can be specified
+  multiple times.
+- Added :ints, :strings, :doubles, and :floats option types, which can take
+  multiple arguments.
+
+## 1.8.2 - 2008-06-25
+
+- Bugfix for #conflicts and #depends error messages
+
+## 1.8.1 - 2008-06-24
+
+- Bugfix for short option autocreation
+- More aggressive documentation
+
+## 1.8 - 2008-06-16
+
+- Sub-command support via Parser#stop_on
+
+## 1.7.2 - 2008-01-16
+
+- Ruby 1.9-ify. Apparently this means replacing :'s with ;'s.
+
+## 1.7.1 - 2008-01-07
+
+- Documentation improvements
+
+## 1.7 - 2007-06-17
+
+- Fix incorrect error message for multiple missing required arguments
+  (thanks to Neill Zero)
+
+## 1.6 - 2007-04-01
+
+- Don't attempt curses screen-width magic unless running on a terminal.
+
+## 1.5 - 2007-03-31
+
+- --help and --version do the right thing even if the rest of the
+  command line is incorrect.
+- Added #conflicts and #depends to model dependencies and exclusivity
+  between arguments.
+- Minor bugfixes.
+
+## 1.4 - 2007-03-26
+
+- Disable short options with :short => :none.
+- Minor bugfixes and error message improvements.
+
+## 1.3 - 2007-01-31
+
+- Wrap at (screen width - 1) instead of screen width.
+- User can override --help and --version.
+- Bugfix in handling of -v and -h.
+- More tests to confirm the above.
+
+## 1.2 - 2007-01-31
+
+- Minor documentation tweaks.
+- Removed hoe dependency.
+
+## 1.1 - 2007-01-30
+
+- Optimist::options now passes any arguments as block arguments. Since
+  instance variables are not properly captured by the block, this
+  makes it slightly less noisy to pass them in as local variables.
+  (A real-life use for _why's cloaker!)
+- Help display now preserves original argument order.
+- Optimist::die now also has a single string form in case death is not
+  due to a single argument.
+- Parser#text now an alias for Parser#banner, and can be called
+  multiple times, with the output being placed in the right position
+  in the help text.
+- Slightly more indicative formatting for parameterized arguments.
+
+## 1.0 - 2007-01-29
+
+- Initial release.
 
-[Unreleased]: https://github.com/ManageIQ/optimist/compare/v3.1.0...HEAD
+[Unreleased]: https://github.com/ManageIQ/optimist/compare/v3.2.0...HEAD
+[3.2.0]: https://github.com/ManageIQ/optimist/compare/v3.1.0...v3.2.0
 [3.1.0]: https://github.com/ManageIQ/optimist/compare/v3.0.1...v3.1.0
+[3.0.1]: https://github.com/ManageIQ/optimist/compare/v3.0.0...v3.0.1
+[3.0.0]: https://github.com/ManageIQ/optimist/compare/v2.1.3...v3.0.0
+[2.1.3]: https://github.com/ManageIQ/optimist/compare/v2.1.2...v2.1.3
+[2.1.2]: https://github.com/ManageIQ/optimist/compare/v2.1.1...v2.1.2
+[2.1.1]: https://github.com/ManageIQ/optimist/compare/v2.1.0...v2.1.1

data/examples/a_basic_example.rb

@@ -0,0 +1,10 @@
+#!/usr/bin/env ruby
+require_relative '../lib/optimist'
+
+opts = Optimist::options do
+  opt :monkey, "Use monkey mode"                    # flag --monkey, default false
+  opt :name, "Monkey name", :type => :string        # string --name <s>, default nil
+  opt :num_limbs, "Number of limbs", :default => 4  # integer --num-limbs <i>, default to 4
+end
+p opts
+

data/examples/alt_names.rb

@@ -0,0 +1,20 @@
+#!/usr/bin/env ruby
+require_relative '../lib/optimist'
+
+opts = Optimist::options do
+  # 'short:' can now take more than one short-option character
+  #   you can specify 'short:' as a string/symbol or an array of strings/symbols
+  # 'alt:' adds additional long-opt choices (over the original name or the long: name)
+  #   you can specify 'alt:' as a string/symbol or an array of strings/symbols.
+  # 
+  opt :concat, 'concatenate flag', short: ['-C', 'A'], alt: ['cat', '--append']
+  opt :array_len, 'set Array length', long: 'size', alt: 'length', type: Integer
+end
+
+p opts
+
+# $ ./alt_names.rb -h
+# Options:
+#   -C, -A, --concat, --cat, --append    concatenate flag
+#   -s, --size, --length=<i>             set Array length
+#   -h, --help                           Show this message

data/examples/banners1.rb

@@ -0,0 +1,11 @@
+#!/usr/bin/env ruby
+require_relative '../lib/optimist'
+
+Optimist::options do
+  synopsis "Overall synopsis of this program"
+  version "cool-script v0.3 (code-name: apple-cake)"
+  opt :juice, "use juice"
+  opt :milk, "use milk"
+  opt :litres, "quantity of liquid", :default => 2.0
+  opt :brand, "brand name of the liquid", :type => :string
+end

data/examples/banners2.rb

@@ -0,0 +1,12 @@
+#!/usr/bin/env ruby
+require_relative '../lib/optimist'
+
+Optimist::options do
+  synopsis "Overall synopsis of this program"
+  version "cool-script v0.3.1 (code-name: apple-cake)"
+  banner "My Banner"
+  opt :juice, "use juice"
+  opt :milk, "use milk"
+  opt :litres, "quantity of liquid", :default => 2.0
+  opt :brand, "brand name of the liquid", :type => :string
+end

data/examples/banners3.rb

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+require_relative '../lib/optimist'
+
+Optimist::options do
+  version "cool-script v0.3.2 (code-name: apple-cake)"
+  banner self.version  ## print out the version in the banner
+  banner "drinks"
+  opt :juice, "use juice"
+  opt :milk, "use milk"
+  banner "drink control"    ## can be used for categories
+  opt :litres, "quantity of liquid", :default => 2.0
+  opt :brand, "brand name of the liquid", :type => :string
+  banner "other controls"
+end

data/examples/constraints.rb

@@ -0,0 +1,28 @@
+#!/usr/bin/env ruby
+require_relative '../lib/optimist'
+
+opts = Optimist::options do
+  opt :dog, "user is dog"
+  opt :cat, "user is cat"
+  opt :rat, "user is rat"
+  conflicts :dog, :cat, :rat
+
+  opt :wash, "pet wash"
+  opt :dry, "pet dry"
+  depends :wash, :dry
+
+  opt :credit, "pay creditcard"
+  opt :cash, "pay cash"
+  opt :cheque, "pay cheque"
+  either :credit, :cash, :cheque
+end
+p opts
+
+# $ ./constraints.rb --dog --cat
+# Error: only one of --dog, --cat, --rat can be given.
+
+# $ ./constraints.rb --dog --wash
+# Error: --wash, --dry have a dependency and must be given together.
+
+# $ ./constraints.rb --cash --cheque --rat --wash --dry
+# Error: one and only one of --credit, --cash, --cheque is required.

data/examples/didyoumean.rb

@@ -0,0 +1,26 @@
+#!/usr/bin/env ruby
+require_relative '../lib/optimist'
+
+opts = Optimist::options do
+  opt :cone, "Ice cream cone"
+  opt :zippy, "It zips"
+  opt :zapzy, "It zapz"
+  opt :big_bug, "Madagascar cockroach"
+end
+p opts
+
+# $ ./didyoumean.rb --one
+# Error: unknown argument '--one'.  Did you mean: [--cone] ?.
+# Try --help for help.
+
+# $ ./didyoumean.rb --zappy
+# Error: unknown argument '--zappy'.  Did you mean: [--zapzy, --zippy] ?.
+# Try --help for help.
+
+# $ ./didyoumean.rb --big_bug
+# Error: unknown argument '--big_bug'.  Did you mean: [--big-bug] ?.
+# Try --help for help.
+
+# $ ./didyoumean.rb --bigbug
+# Error: unknown argument '--bigbug'.  Did you mean: [--big-bug] ?.
+# Try --help for help.

data/examples/medium_example.rb

@@ -0,0 +1,15 @@
+#!/usr/bin/env ruby
+require_relative '../lib/optimist'
+
+opts = Optimist::options do
+  version "cool-script v0.1 (code-name: bananas foster)"
+  banner "This script is pretty cool."
+  opt :juice, "use juice"
+  opt :milk, "use milk"
+  opt :litres, "quantity of liquid", :default => 2.0
+  opt :brand, "brand name of the liquid", :type => :string
+  opt :config, "config file path", :type => String, :required => true
+  opt :drinkers, "number of people drinking the liquid", :default => 6
+end
+Optimist::die :drinkers, "must be value a greater than zero" if opts[:drinkers] < 1
+Optimist::die :config, "must point to an existing file" unless File.exist?(opts[:config]) if opts[:config]

data/examples/partialmatch.rb

@@ -0,0 +1,18 @@
+#!/usr/bin/env ruby
+require_relative '../lib/optimist'
+
+opts = Optimist::options(ARGV, exact_match: false) do
+  opt :apple, "An apple"
+  opt :apple_sauce, "Cooked apple puree"
+  opt :atom, "Smallest unit of ordinary matter"
+  opt :anvil, "Heavy metal"
+  opt :anteater, "Eats ants"
+end
+p opts
+
+# $ ./partialmatch.rb  --anv 1
+# {:apple=>false, :apple_sauce=>false, :atom=>false, :anvil=>true, :anteater=>false, :help=>false, :anvil_given=>true}
+#
+# $ ./partialmatch.rb  --an 1
+# Error: ambiguous option '--an' matched keys (anvil,anteater).
+# Try --help for help.

data/examples/permitted.rb

@@ -0,0 +1,29 @@
+#!/usr/bin/env ruby
+require_relative '../lib/optimist'
+
+opts = Optimist::options do
+  opt :french, "starts with french", type: String,
+      permitted: %w(fries toast),
+      permitted_response: "option %{arg} must be something that starts " +
+      "with french, e.g. %{permitted} but you gave '%{given}'"
+  opt :dog, "starts with dog", permitted: %r/(house|bone|tail)/, type: String
+  opt :zipcode, "zipcode", permitted: %r/^[0-9]{5}$/, default: '39759',
+      permitted_response: "option %{arg} must be a zipcode, a five-digit number from 00000..99999"
+  opt :adult, "adult age", permitted: (18...99), type: Integer
+  opt :minor, "minor age", permitted: (0..18), type: Integer
+  opt :letter, "a letter", permitted: ('a'...'z'), type: String
+end
+
+p opts
+
+# $ ./permitted.rb -z 384949
+# Error: option -z must be a zipcode, a five-digit number from 00000..99999.
+# Try --help for help.
+#
+# $ ./permitted.rb --minor 19
+# Error: option '--minor' only accepts value in range of: 0..18.
+# Try --help for help.
+#
+# $ ./permitted.rb -f frog
+# Error: option -f must be something that starts with french, e.g. ["fries", "toast"] but you gave 'frog'.
+# Try --help for help.

data/examples/types_custom.rb

@@ -0,0 +1,43 @@
+#!/usr/bin/env ruby
+require_relative '../lib/optimist'
+
+class ZipCode
+  REGEXP = %r/^(?<zip>[0-9]{5})(\-(?<plusfour>[0-9]{4}))?$/
+  def initialize(zipstring)
+    matcher = REGEXP.match(zipstring)
+    raise "Invalid zip-code" unless matcher
+    @zip = matcher[:zip]
+    @plusfour = matcher[:plusfour]
+  end
+end
+
+#module Optimist
+class ZipCodeOption < Optimist::Option
+  # register_alias registers with the global parser.
+  register_alias :zipcode
+  def type_format ; "=<zip>" ; end # optional for use with help-message
+  def parse(paramlist, _neg_given)
+    paramlist.map do |plist|
+      plist.map do |param_string|
+        raise Optimist::CommandlineError, "option '#{self.name}' should be formatted as a zipcode" unless param_string=~ ZipCode::REGEXP
+        ZipCode.new(param_string)
+      end
+    end
+  end
+end
+
+opts = Optimist::options do
+  opt :zipcode, "United states postal code", :type => :zipcode 
+end
+
+p opts[:zipcode]
+
+# $ ./types_custom.rb --zipcode 39759
+# <ZipCode:0x0000000000a34968 @zip="39759", @plusfour=nil>
+#
+# $ ./types_custom.rb --zipcode 39759-0001
+# <ZipCode:0x000000000117a100 @zip="39759", @plusfour="0001">
+#
+# $ ./types_custom.rb --zipcode 384134
+# Error: option 'zipcode' should be formatted as a zipcode.
+# Try --help for help.