opt_parse_builder 0.2.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 39695b1c1e778b1f947bc02eae0b0942405f686e1b2295db180b47056c6bf8a3
-  data.tar.gz: 1daba7a89dc175c9c5b087ff9a03fb50e7ede303f0bdf7289b23e994cd6161af
+  metadata.gz: b030936035ec1d79b8d22024f239664a8b8bf47c7fc00ac80d7d183a49859126
+  data.tar.gz: 3b771b01a70ddfbf2d4109f2554558100e729cb994c464625e49b35652d364f4
 SHA512:
-  metadata.gz: '0876b80178845db9da8786262ffd10a0c00a3ca63f980efb99c9d1aff03422afce8dc10c2ba9fc9dba67ca18c3c32466b0c65860fb89280b39560811ed654e33'
-  data.tar.gz: 705942c096e316892af5f7b5a70083da538556d0d2559b67a091e0fe3b7e1b4d8aa5966e8550327e63e90213e205bf076576e779fd7939f3b225fd4715a54a61
+  metadata.gz: 0140ca5bf9a14f8efd29040e75902d627331ec4be3d8c89dd4010da75cf38fd1f1b55321c53e8b5ebb4aa4b6c3ba94905efe6c8249dd95aade6e670f58135c12
+  data.tar.gz: f7f76918a1fa34779168c0e398f9adac38b82cd51e799a99c9e28ba9f6c2bbedfa606d9221590c2a65d1652cb93ecfc0670104813ba8a541140a6ad2a0bda083

data/.gitignore

@@ -1,3 +1,4 @@
 html
 *.gem
 temp
+.claude/

data/.ruby-version

@@ -1 +1 @@
-ruby-3.4.4
+ruby-3.4.7

data/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 # Development
 
+# 1.1.0 - 2025-11-28
+
+* Add footer method for text at bottom of help output (recommended)
+* Add footer: parameter to separator method
+  - separator(line, footer: true) - deprecated, emits warning
+  - separator(line, footer: false) - new positional behavior
+  - Provides clear migration path to v2.0.0
+
+# 1.0.0 - 2025-11-28
+
+* Declare API stability by bumping version to 1.0.0
+* Update gems
+* Update Ruby to 3.4.7
+
 # 0.2.0 - 2025-07-06
 
 * Update gems

data/Gemfile.lock

@@ -1,26 +1,26 @@
 PATH
   remote: .
   specs:
-    opt_parse_builder (0.2.0)
+    opt_parse_builder (1.1.0)
 
 GEM
   remote: https://rubygems.org/
   specs:
     diff-lcs (1.6.2)
-    rake (13.3.0)
-    rspec (3.13.1)
+    rake (13.3.1)
+    rspec (3.13.2)
       rspec-core (~> 3.13.0)
       rspec-expectations (~> 3.13.0)
       rspec-mocks (~> 3.13.0)
-    rspec-core (3.13.5)
+    rspec-core (3.13.6)
       rspec-support (~> 3.13.0)
     rspec-expectations (3.13.5)
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.13.0)
-    rspec-mocks (3.13.5)
+    rspec-mocks (3.13.7)
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.13.0)
-    rspec-support (3.13.4)
+    rspec-support (3.13.6)
 
 PLATFORMS
   ruby
@@ -32,4 +32,4 @@ DEPENDENCIES
   rspec (~> 3.10)
 
 BUNDLED WITH
-   2.6.9
+   2.7.2

data/README.md

@@ -62,7 +62,7 @@ arg_parser = OptParseBuilder.build_parser do |args|
     arg.key :verbose
     arg.on "-v", "--verbose", "Be verbose"
   end
-  args.separator "Some explanatory text at the bottom"
+  args.footer "Some explanatory text at the bottom"
 end
 
 arg_values = arg_parser.parse!
@@ -262,27 +262,67 @@ Applicable builder methods:
 
 Banner text can be added to any argument.
 
-## Separator only
+## Footer 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.
+An argument with only footer text (but see
+OptParseBuilder#footer for the usual way to do this).  Footer text
+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
+      arg.footer "Footer text at the bottom"
+      arg.footer "A second line of footer text"
+      arg.footer <<~FOOTER
         A third line
         A fourth line
-      SERPARATOR
+      FOOTER
     end
 
 Applicable builder methods:
 
-* separator
+* footer
 
-Separator text can be added to any argument.
+Footer text can be added to any argument.
+
+## Positional separator
+
+A separator that appears between options in the --help output,
+useful for grouping related options.
+
+    OptParseBuilder.build_argument do |arg|
+      arg.key :verbose
+      arg.on "-v", "--verbose", "Be verbose"
+      arg.separator "--- Advanced options ---", footer: false
+    end
+
+The separator will appear immediately after the option it's
+attached to, allowing you to divide your options into sections.
+
+Applicable builder methods:
+
+* separator (with footer: false parameter)
+
+## Separator only (deprecated)
+
+**Note:** Using `separator` without the `footer:` parameter is
+deprecated in v1.1.0 and will change behavior in v2.0.0. Use
+`footer` for text at the bottom, or `separator(text, footer: false)`
+for positional text.
+
+    # Deprecated - emits warning
+    OptParseBuilder.build_argument do |arg|
+      arg.separator "Text at bottom"
+    end
+
+    # Recommended alternatives:
+    # For bottom text:
+    OptParseBuilder.build_argument do |arg|
+      arg.footer "Text at bottom"
+    end
+
+    # For positional text:
+    OptParseBuilder.build_argument do |arg|
+      arg.separator "Between options", footer: false
+    end
 
 ## Constant value
 

data/doc/publishing.md

@@ -0,0 +1,42 @@
+Publishing a New Release
+
+# Checklist
+
+* Update `lib/opt_parse_builder/version.rb`
+* Update `CHANGELOG.md` with version and date
+* Run tests: `rake`
+* Commit: `git commit -am "Bump version to X.X.X"`
+* Release: `rake release`
+* Verify at https://rubygems.org/gems/opt_parse_builder
+
+# Notes
+
+Semantic Versioning: MAJOR.MINOR.PATCH (breaking.feature.bugfix)
+
+What `rake release` does:
+
+* Builds the gem
+* Creates git tag vX.X.X
+* Pushes tag to GitHub
+* Publishes gem to rubygems.org
+
+Dry run: `gem_push=no rake release` (tags but doesn't publish)
+
+# Troubleshooting
+
+No RubyGems credentials: `gem signin`
+
+Release failed mid-way:
+
+```bash
+git tag -d vX.X.X              # Delete local tag
+git push origin :vX.X.X        # Delete remote tag
+rake release                   # Try again
+```
+
+Manual publish (if rake release fails):
+
+```bash
+gem build opt_parse_builder.gemspec
+gem push opt_parse_builder-X.X.X.gem
+```

data/examples/hello_world.rb

@@ -1,6 +1,6 @@
 #!/usr/bin/env ruby
 
-require "opt_parse_builder"
+require_relative "lib/setup_example"
 
 ARG_PARSER = OptParseBuilder.build_parser do |args|
   args.banner "A simple example"

data/examples/lib/setup_example.rb

@@ -0,0 +1,8 @@
+require "bundler/setup"
+
+lib_dir = File.join(__dir__, "../../lib")
+if File.directory?(lib_dir)
+  $:.prepend lib_dir
+end
+                    
+require "opt_parse_builder"

data/lib/opt_parse_builder/argument.rb

@@ -31,6 +31,10 @@ module OptParseBuilder
       []
     end
 
+    def footer_lines # :nodoc:
+      []
+    end
+
     def apply_option(_op) # :nodoc:
     end
 

data/lib/opt_parse_builder/argument_builder.rb

@@ -16,6 +16,7 @@ module OptParseBuilder
       @operand_help_name = nil
       @banner_lines = []
       @separator_lines = []
+      @footer_lines = []
     end
 
     # Set the argument's key.  Accepts either a string or a symbol.
@@ -115,11 +116,38 @@ module OptParseBuilder
     # may call this more than once; each call adds another line of
     # text to the separator.
     #
+    # The footer: parameter controls where the text appears:
+    # * footer: true (default in v1.x) - text appears at bottom
+    #   (DEPRECATED: use footer method instead)
+    # * footer: false - text appears positionally between options
+    #   (will be default in v2.0.0)
+    #
     # Any type of argument may have separator text.
     #
-    # See also OptParseBuilder#separator
-    def separator(line)
-      @separator_lines << line
+    # See also OptParseBuilder#separator and OptParseBuilder#footer
+    def separator(line, footer: true)
+      if footer
+        warn "separator with footer text is deprecated and will" +
+          " become positional in v2.0.0. Use footer(line) instead or" +
+          " separator(line, footer: false) for positional."
+        @footer_lines << line
+      else
+        @separator_lines << line
+      end
+    end
+
+    # Add to the footer text shown at the bottom of --help output.
+    # You may call this more than once; each call adds another line
+    # of text to the footer.
+    #
+    # This is the recommended way to add text at the bottom of help
+    # output in v1.1.0 and later.
+    #
+    # Any type of argument may have footer text.
+    #
+    # See also OptParseBuilder#footer
+    def footer(line)
+      @footer_lines << line
     end
 
     # Declare the operand to be an optional operand.  An optional
@@ -155,9 +183,6 @@ module OptParseBuilder
       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
@@ -171,6 +196,12 @@ module OptParseBuilder
           bundle << ConstantArgument.new(@key, @default)
         end
       end
+      unless @separator_lines.empty?
+        bundle << SeparatorArgument.new(@separator_lines)
+      end
+      unless @footer_lines.empty?
+        bundle << FooterArgument.new(@footer_lines)
+      end
       bundle.simplify
     end
 

data/lib/opt_parse_builder/footer_argument.rb

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

data/lib/opt_parse_builder/parser.rb

@@ -151,14 +151,20 @@ module OptParseBuilder
     # Although it's called a "line," you can embed new-lines in it so
     # that it is actually more than one line.
     #
+    # The footer: parameter controls where the text appears:
+    # * footer: true (default in v1.x) - text appears at bottom
+    #   (DEPRECATED: use footer method instead)
+    # * footer: false - text appears positionally between options
+    #   (will be default in v2.0.0)
+    #
     # This example:
     #
     #     arg_parser = OptParseBuilder.build_parser do |args|
-    #       args.separator "Here I explain more about my program"
-    #       args.separator <<~SEPARATOR
+    #       args.footer "Here I explain more about my program"
+    #       args.footer <<~FOOTER
     #         For such a small program,
     #         it has a lot of text at the end.
-    #       SEPARATOR
+    #       FOOTER
     #     end
     #     arg_parser.parse!(["--help"])
     #
@@ -168,9 +174,42 @@ module OptParseBuilder
     #     Here I explain more about my program
     #     For such a small program,
     #     it has a lot of text at the end.
-    def separator(line)
+    def separator(line, footer: true)
       add do |arg|
-        arg.separator(line)
+        arg.separator(line, footer: footer)
+      end
+    end
+
+    # Add a line to the footer.  The footer 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 is the recommended way to add text at the bottom of help
+    # output in v1.1.0 and later.
+    #
+    # This example:
+    #
+    #     arg_parser = OptParseBuilder.build_parser do |args|
+    #       args.footer "Here I explain more about my program"
+    #       args.footer <<~FOOTER
+    #         For such a small program,
+    #         it has a lot of text at the end.
+    #       FOOTER
+    #     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 footer(line)
+      add do |arg|
+        arg.footer(line)
       end
     end
 
@@ -313,12 +352,17 @@ module OptParseBuilder
     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|
+      @arguments.each do |arg|
+        arg.apply_option(op)
+        arg.separator_lines.each do |line|
           op.separator(line)
         end
       end
+      @arguments.each do |argument|
+        argument.footer_lines.each do |line|
+          op.on_tail(line)
+        end
+      end
       op
     end
 

data/lib/opt_parse_builder/parser_builder.rb

@@ -11,7 +11,7 @@ module OptParseBuilder
       @parser = Parser.new
     end
 
-    def_delegators :@parser,  :add, :banner, :separator
+    def_delegators :@parser,  :add, :banner, :separator, :footer
 
   end
 end

data/lib/opt_parse_builder/version.rb

@@ -1,6 +1,6 @@
 module OptParseBuilder
 
   # Library version.  Follows Semantic Versioning 2.0
-  VERSION = "0.2.0"
+  VERSION = "1.1.0"
   
 end

data/lib/opt_parse_builder.rb

@@ -8,6 +8,7 @@ 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/footer_argument"
 require_relative "opt_parse_builder/formats_operand_name"
 require_relative "opt_parse_builder/has_value"
 require_relative "opt_parse_builder/null_argument"
@@ -53,7 +54,7 @@ require_relative "opt_parse_builder/stable_sort"
 #         arg.on "--size=N", Integer
 #         arg.on "Size in bytes (default _DEFAULT_)"
 #       end
-#       parser.separator "Explanatory text at the bottom"
+#       parser.footer "Explanatory text at the bottom"
 #     end
 #     arg_values = arg_parser.parse!
 #     p arg_values.quiet          # nil or true

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: opt_parse_builder
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Wayne Conrad
@@ -71,7 +71,9 @@ files:
 - LICENSE
 - README.md
 - Rakefile
+- doc/publishing.md
 - examples/hello_world.rb
+- examples/lib/setup_example.rb
 - lib/opt_parse_builder.rb
 - lib/opt_parse_builder/argument.rb
 - lib/opt_parse_builder/argument_builder.rb
@@ -81,6 +83,7 @@ files:
 - lib/opt_parse_builder/banner_argument.rb
 - lib/opt_parse_builder/constant_argument.rb
 - lib/opt_parse_builder/errors.rb
+- lib/opt_parse_builder/footer_argument.rb
 - lib/opt_parse_builder/formats_operand_name.rb
 - lib/opt_parse_builder/has_value.rb
 - lib/opt_parse_builder/null_argument.rb
@@ -117,7 +120,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.7
+rubygems_version: 3.6.9
 specification_version: 4
 summary: Builder DSL for optparse, with more
 test_files: []