opt_parse_builder 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ae59f7036ba75769d0965d67ec2b8d79c9d1965d3867898ee40b1a6e39d63395
-  data.tar.gz: d92e59065fc880fb4b0182f4a9f3d608bc88d69333a37267f7edaae36efd41b2
+  metadata.gz: b030936035ec1d79b8d22024f239664a8b8bf47c7fc00ac80d7d183a49859126
+  data.tar.gz: 3b771b01a70ddfbf2d4109f2554558100e729cb994c464625e49b35652d364f4
 SHA512:
-  metadata.gz: 688195cd6207f2a4dbb5aebb66851efe094a17a1e3c55d87cd38f62ffe72cc15acd665c1ad64e203abe806f8a5cb767dd4ff46123f4c521f003b70e570a883b8
-  data.tar.gz: 97a98d23c58dbbeda7136b5399455bde1d00840c2748409f8ae85dce667d06f4b114ac7e00ea110bd5bdd8a58758af11ba0d34b975960acea67db21cc80aa325
+  metadata.gz: 0140ca5bf9a14f8efd29040e75902d627331ec4be3d8c89dd4010da75cf38fd1f1b55321c53e8b5ebb4aa4b6c3ba94905efe6c8249dd95aade6e670f58135c12
+  data.tar.gz: f7f76918a1fa34779168c0e398f9adac38b82cd51e799a99c9e28ba9f6c2bbedfa606d9221590c2a65d1652cb93ecfc0670104813ba8a541140a6ad2a0bda083

data/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 # 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

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    opt_parse_builder (1.0.0)
+    opt_parse_builder (1.1.0)
 
 GEM
   remote: https://rubygems.org/

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

@@ -2,9 +2,9 @@ Publishing a New Release
 
 # Checklist
 
-* Run tests: `rake`
 * 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

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 = "1.0.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: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Wayne Conrad
@@ -83,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