sod 0.13.0 → 0.14.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 064c2b356590ff7c74a2f64a269fcadc1d7bfc46fc8c7867b8627a43d4719850
-  data.tar.gz: 481aa201574305f457cd4613aedfde6ee6e6b07ac736395eabefeccf8ee618dd
+  metadata.gz: c85d0a0011997592a071b7238743f7bd3fbaa8f82c91ace66199412030c35185
+  data.tar.gz: cedce56c426c4e6ca1f02fea043ef6f83d76aada4430bd4d41df16579b1c47e9
 SHA512:
-  metadata.gz: 628ba8d427d6899ba4e775001b80ed36179719b18517bd0a0aa7cd3f212745d26db1532c1dc0e7f4d14b4ea65133a453409d4c0bc0cfa7d86df6bbd5b9c907bf
-  data.tar.gz: c8d810bdd5f57bedd874220bc5ca4b0b1d51c81d470383ecfa8222452069d37678645f11e87b5c4638cc1f69575912a6fa8c5be548a447604f2d8fe49efc60d8
+  metadata.gz: 11de476bc015d7563655dd99b34b532aa638bfe97384b7e7f00837903248ad8ac294b61c65eaa0cd22c509645817e9e49c49a01c057dbb8ef68226c692e761ba
+  data.tar.gz: 3a8a383dfd4eaf2df98c1f93b8ecd7a53c722e4f4d716f6ac396dca8a76b0c56fed023473195d76b622098952037a57d55826383c2122536acce1468795560cb

data/README.adoc

@@ -292,23 +292,43 @@ With the above in mind, let's look at a few examples of what you can do when you
 
 ===== Booleans
 
-Boolean flags are long alases only, take _no arguments_, and use `[no-]` syntax after the double dashes. Here's a minimal implementation:
+Boolean are long alases only, use `[no-]` syntax after the double dashes, and provide the boolean value for use within your action. Here's a minimal implementation:
 
 [source,ruby]
 ----
-class Demo < Sod::Action
+class Action < Sod::Action
   on "--[no-]run"
 
-  def call(value) = puts "Got: #{value}"
+  def call(boolean) = puts boolean
+end
+
+cli = Sod.new { on Action }
+
+cli.call %w[--run]     # "true"
+cli.call %w[--no-run]  # "false"
+----
+
+Because a value is always provided when using a boolean flag, you can make it a required positional parameter via your method definition (i.e. `call(boolean)`). You don't need to worry about type safety because {option_parser_link} will pass in `true` or `false` as you can see from the output above.
+
+===== Flags
+
+Flags are similar to _Booleans_ but take _no arguments_ and allow short or long aliases. When a flag is supplied, the action is _enabled_ which means you can execute custom functionality. Otherwise, when a flag isn't supplied (i.e. default), then the action is _disabled_ and nothing happens.
+
+[source,ruby]
+----
+class Action < Sod::Action
+  on %w[-m --max]
+
+  def call(*) = puts "Maximum enabled."
 end
 
-cli = Sod.new { on Demo }
+cli = Sod.new { on Action }
 
-cli.call %w[--run]     # "Got: true"
-cli.call %w[--no-run]  # "Got: false"
+cli.call %w[--max]  # "Maximum enabled."
+cli.call            # Nothing happens.
 ----
 
-Because a value is always provided when using a boolean flag, you can make it a required positional parameter via your method definition (i.e. `call(value)`). You don't need to worry about type safety because {option_parser_link} will either pass in a `true` or `false` value as you can see from the output above.
+Since `#call` expects an argument, you can use `call(+*+)` for the method signature to ignore all arguments since you don't need them.
 
 ===== Arguments
 
@@ -316,13 +336,13 @@ Arguments inform {option_parser_link} how to parse values as either _optional_ o
 
 [source,ruby]
 ----
-class Demo < Sod::Action
+class Action < Sod::Action
   on %w[-e --echo], argument: "[TEXT]"
 
   def call(text = nil) = puts "Got: #{text}"
 end
 
-cli = Sod.new { on Demo }
+cli = Sod.new { on Action }
 
 cli.call %w[-e]         # "Got: "
 cli.call %w[--echo]     # "Got: "
@@ -334,13 +354,13 @@ The method definition of `call(text = nil)` is important because if you call the
 
 [source,ruby]
 ----
-class Demo < Sod::Action
+class Action < Sod::Action
   on %w[-e --echo], argument: "TEXT"
 
   def call(text) = puts "Got: #{text}"
 end
 
-cli = Sod.new { on Demo }
+cli = Sod.new { on Action }
 
 cli.call %w[-e]         # "🛑 Missing argument: -e"
 cli.call %w[--echo]     # "🛑 Missing argument: --echo"
@@ -348,10 +368,10 @@ cli.call %w[-e hi]      # "Got: hi"
 cli.call %w[--echo hi]  # "Got: hi"
 ----
 
-There are only three major differences between the earlier _optional_ example and the above _required_ example:
+There are three major differences between a _required_ and _optional_ argument:
 
 * The argument is required because it's not wrapped in brackets.
-* The method definition requires a `text` parameter.
+* The method definition requires a parameter (i.e. `text` in the above example).
 * You get an error when not providing an argument.
 
 ===== Types
@@ -360,13 +380,13 @@ Types are optional but worth having when you need the safety check. Here's a min
 
 [source,ruby]
 ----
-class Demo < Sod::Action
+class Action < Sod::Action
   on %w[-e --echo], argument: "NUMBER", type: Float
 
   def call(number) = puts "Got: #{number}"
 end
 
-cli = Sod.new { on Demo }
+cli = Sod.new { on Action }
 
 cli.call %w[--echo 123]   # "Got: 123.0"
 cli.call %w[--echo 1.5]   # "Got: 1.5"
@@ -381,13 +401,13 @@ Allows give you the ability to define what is acceptable as input and need to ma
 
 [source,ruby]
 ----
-class Demo < Sod::Action
+class Action < Sod::Action
   on %w[-e --echo], argument: "TEXT", allow: %w[hi hello]
 
   def call(text) = puts "Got: #{text}"
 end
 
-cli = Sod.new { on Demo }
+cli = Sod.new { on Action }
 
 cli.call %w[--echo hi]     # "Got: hi"
 cli.call %w[--echo hello]  # "Got: hello"
@@ -398,56 +418,25 @@ Here you can see the first two examples pass while the last one fails because `"
 
 ===== Defaults
 
-Defaults are not something that {option_parser_link} supports out-of-the-box but are handy for documentation purposes and within your implementation as fallback values. Here's a minimal example:
+Defaults are not supported by {option_parser_link} but are handy for documentation purposes and within your implementation as fallback values. Here's a minimal example:
 
 [source,ruby]
 ----
-class Demo < Sod::Action
+class Action < Sod::Action
   on %w[-e --echo], argument: "[TEXT]", default: "fallback"
 
-  def call(text = nil) = puts "Got: #{text || default}"
+  def call(text = default) = puts "Got: #{text}"
 end
 
-cli = Sod.new { on Demo }
+cli = Sod.new { on Action }
 
 cli.call %w[--echo]     # "Got: fallback"
 cli.call %w[--echo hi]  # "Got: hi"
 ----
 
-Notice how the default is printed when no value is given but is overwritten when an actual value is supplied. This is the correct way to handle defaults but might not be what you are used to. If you're thinking that you'd rather write the implementation like this:
-
-[source,ruby]
-----
-def call(text = default) = puts "Got: #{text}"
-----
-
-...you'd not be wrong. In fact, if you initialized and called the action, you'd get what you'd expect:
-
-[source,ruby]
-----
-demo = Demo.new
-
-demo.call       # "Got: fallback"
-demo.call "hi"  # "Got: hi"
-----
-
-The reason the above is a problem is because {option_parser_link} ignores _optional_ parameters and all keywords. Here's the fully modified example:
-
-[source,ruby]
-----
-class Demo < Sod::Action
-  on %w[-e --echo], argument: "[TEXT]", default: "fallback"
-
-  def call(text = default) = puts "Got: #{text}"
-end
+Notice how the default is printed when no value is given but is overwritten when an actual value is supplied.
 
-cli = Sod.new { on Demo }
-
-cli.call %w[--echo]     # "Got: "
-cli.call %w[--echo hi]  # "Got: hi"
-----
-
-Notice how there is surprising behavior with the first result (i.e. an empty string). This is because when {option_parser_link} completely ignores the value of the _optional_ parameter. I've logged an link:https://github.com/ruby/optparse/issues/55[issue] if you want to know more. For now, be aware of this quirk as it can be confusing if you are not familiar with {option_parser_link}.
+💡 If you need to lazy compute a default value, then use the block syntax instead.
 
 ===== Examples
 
@@ -464,7 +453,7 @@ class Echo < Sod::Action
 
   default { "hello" }
 
-  def call(text = nil) = puts(text || default)
+  def call(text = default) = puts text
 end
 
 cli = Sod.new :demo, banner: "Demo 0.0.0: A demonstration" do
@@ -737,7 +726,9 @@ class Demo < Sod::Command
 end
 ----
 
-One major difference between _reusable_ and _inline_ commands is that _reusable_ commands allow you implement a `#call` method. This method is optional, so if you don't need it, you don't have to implement it. However, if you do, this means you can process the input from your actions. This method is called _after_ the option parser has parsed all command line input for your actions which gives you a handy way to process all collected input via a single command. 💡 This is how the {rubysmith_link}, {gemsmith_link}, and {hanamismith_link} gems all build new Ruby projects for you based on the actions passed to them via the CLI.
+One major difference between _reusable_ and _inline_ commands is that _reusable_ commands allow you implement a `#call` method. This method is optional, so if you don't need it, you don't have to implement it. However, if you do, this means you can process the input from your actions. This method is called _after_ the option parser has parsed all command line input for your actions which gives you a handy way to process all collected input via a single command.
+
+💡 This is how the {rubysmith_link}, {gemsmith_link}, and {hanamismith_link} gems all build new Ruby projects for you based on the actions passed to them via the CLI.
 
 ==== Initialization
 
@@ -775,7 +766,7 @@ context = Sod::Context.new defaults_path: "path/to/defaults.yml", version_label:
 context = Sod::Context[defaults_path: "path/to/defaults.yml", version_label: "Demo 0.0.0"]
 ----
 
-Once you have an instance, you can use it as follows:
+Once you have an instance, you can use as follows:
 
 [source,ruby]
 ----
@@ -805,7 +796,7 @@ end
 
 Types are a way to extend default {option_parser_link} functionality. Here are a few types -- not provided by {option_parser_link} -- worth knowing about:
 
-**Pathname**
+===== Pathname
 
 Provided by this gem and must be manually required since it's disabled by default. Example:
 
@@ -821,7 +812,7 @@ end
 
 With the above, you'll always get a link:https://rubyapi.org/o/s?q=Pathname[Pathname] instance as input to your action.
 
-**Version**
+===== Version
 
 Provided via the {versionaire_link} gem which gives you a `Version` type when dealing with link:https://semver.org[semantic versions]. Here's how to leverage it:
 
@@ -835,7 +826,7 @@ class Demo < Sod::Action
 end
 ----
 
-**Custom**
+===== Custom
 
 Creating a custom type requires minimal effort and can be implemented in only a few files:
 

data/lib/sod/graph/loader.rb

@@ -6,7 +6,7 @@ module Sod
     class Loader
       include Import[:client]
 
-      using Refines::OptionParsers
+      using Refines::OptionParser
 
       def initialize(graph, **)
         super(**)

data/lib/sod/graph/runner.rb

@@ -6,7 +6,7 @@ module Sod
     class Runner
       include Import[:client, :logger]
 
-      using Refines::OptionParsers
+      using Refines::OptionParser
 
       HELP_PATTERN = /
         \A       # Start of string.
@@ -48,6 +48,8 @@ module Sod
           usage(*arguments)
         else
           parser, node = registry.fetch lineage, client
+          alter_callback_for parser
+
           parser.order! arguments, command: node do |command|
             lineage.concat(" ", command).tap(&:strip!)
             visit arguments
@@ -55,6 +57,15 @@ module Sod
         end
       end
 
+      # :reek:FeatureEnvy
+      def alter_callback_for parser
+        parser.define_singleton_method :callback! do |function, max_arity, *positionals|
+          return function.call if function.arity == -1 && positionals.empty?
+
+          super(function, max_arity, *positionals)
+        end
+      end
+
       def usage(*arguments)
         commands = arguments.grep_v help_pattern
         commands = lineage.split if commands.empty?

data/lib/sod/refines/{option_parsers.rb → option_parser.rb}

@@ -5,10 +5,10 @@ require "optparse"
 module Sod
   module Refines
     # Provides additional enhancements to the option parser primitive.
-    module OptionParsers
-      refine OptionParser do
-        def order!(argument = default_argv, into: nil, command: nil, &)
-          super(argument, into:, &)
+    module OptionParser
+      refine ::OptionParser do
+        def order!(argument = default_argv, into: nil, command: nil, **, &)
+          super(argument, into:, **, &)
           command.call if command
         end
 

data/sod.gemspec

@@ -2,7 +2,7 @@
 
 Gem::Specification.new do |spec|
   spec.name = "sod"
-  spec.version = "0.13.0"
+  spec.version = "0.14.0"
   spec.authors = ["Brooke Kuhlmann"]
   spec.email = ["brooke@alchemists.io"]
   spec.homepage = "https://alchemists.io/projects/sod"
@@ -26,7 +26,8 @@ Gem::Specification.new do |spec|
   spec.add_dependency "cogger", "~> 0.21"
   spec.add_dependency "containable", "~> 0.2"
   spec.add_dependency "infusible", "~> 3.8"
-  spec.add_dependency "refinements", "~> 12.5"
+  spec.add_dependency "optparse", "~> 0.5"
+  spec.add_dependency "refinements", "~> 12.7"
   spec.add_dependency "tone", "~> 1.0"
   spec.add_dependency "zeitwerk", "~> 2.6"
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sod
 version: !ruby/object:Gem::Version
-  version: 0.13.0
+  version: 0.14.0
 platform: ruby
 authors:
 - Brooke Kuhlmann
@@ -35,7 +35,7 @@ cert_chain:
   3n5C8/6Zh9DYTkpcwPSuIfAga6wf4nXc9m6JAw8AuMLaiWN/r/2s4zJsUHYERJEu
   gZGm4JqtuSg8pYjPeIJxS960owq+SfuC+jxqmRA54BisFCv/0VOJi7tiJVY=
   -----END CERTIFICATE-----
-date: 2024-07-08 00:00:00.000000000 Z
+date: 2024-08-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: cogger
@@ -79,20 +79,34 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.8'
+- !ruby/object:Gem::Dependency
+  name: optparse
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.5'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.5'
 - !ruby/object:Gem::Dependency
   name: refinements
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '12.5'
+        version: '12.7'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '12.5'
+        version: '12.7'
 - !ruby/object:Gem::Dependency
   name: tone
   requirement: !ruby/object:Gem::Requirement
@@ -153,7 +167,7 @@ files:
 - lib/sod/prefabs/commands/config.rb
 - lib/sod/presenters/action.rb
 - lib/sod/presenters/node.rb
-- lib/sod/refines/option_parsers.rb
+- lib/sod/refines/option_parser.rb
 - lib/sod/shell.rb
 - lib/sod/types/pathname.rb
 - sod.gemspec
@@ -183,7 +197,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.14
+rubygems_version: 3.5.17
 signing_key:
 specification_version: 4
 summary: A domain specific language for creating composable command line interfaces.