sod 0.0.0 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4ed0e633c091b67d809287f755ef22f95c8625bb62a381033d2460fcc674a0cd
-  data.tar.gz: 0556220a0042ef1ee187c5b6ef042de2c948ed360350e6100cd4d4efcd47863f
+  metadata.gz: c23697cbcb0d37aa7c92b530d1952f535e8f8d338a1bfb1bc8a0f1279b589eb6
+  data.tar.gz: 2cbeba3bf1b3a47507735469537db88a8f9ea47fe98277a4802816d25eaf7163
 SHA512:
-  metadata.gz: c6a68109cf04ecbc9c030061b04bc7dac9974464a3756b7be2ee3a6af792a7001078367d889e50f914572af940c255467969602308287bf4e8deff68939ec4b4
-  data.tar.gz: 9f9e4015d492451a15b350bd5ee343c9e8976f067798ff0c0363f9e6c28785c69e683cb932a4bbc54006f570aa0996af522ca53af3dd650619aa7a951fcfa08f
+  metadata.gz: 003a046aacafec0865dd1b64b450b4fe3e4b1f6896fed015110f3df766a99f4c56fc5188fdd8c7fd1fdd94fb04cc8046b81fb67e2aeafaa6d311709cc488b7fb
+  data.tar.gz: d4c84e4ab0c83cfd4a537e8584c6f62ad6d5b5af737a94244b8222f1dd0a93afb6b340befe1da7d7c7ffc869c7593428c5dcf1306e4ca3ee3132e8edec69c056

data/README.adoc

@@ -3,7 +3,6 @@
 :figure-caption!:
 
 :cogger_link: link:https://alchemists.io/projects/cogger[Cogger]
-:dry_container_link: link:https://dry-rb.org/gems/dry-container[Dry Container]
 :etcher_link: link:https://alchemists.io/projects/etcher[Etcher]
 :gemsmith_link: link:https://alchemists.io/projects/gemsmith[Gemsmith]
 :git-lint_link: link:https://alchemists.io/projects/git-lint[Git Lint]
@@ -13,7 +12,6 @@
 :option_parser_link: link:https://rubyapi.org/o/s?q=OptionParser[Option Parser]
 :pennyworth_link: link:https://alchemists.io/projects/pennyworth[Pennyworth]
 :pragmater_link: link:https://alchemists.io/projects/pragmater[Pragmater]
-:rake_link: link:https://github.com/ruby/rake[Rake]
 :rubysmith_link: link:https://alchemists.io/projects/rubysmith[Rubysmith]
 :runcom_link: link:https://alchemists.io/projects/runcom[Runcom]
 :spek_link: link:https://alchemists.io/projects/spek[Spek]
@@ -43,11 +41,11 @@ toc::[]
 
 *DSL*
 
-image::https://alchemists.io/images/projects/sod/screenshots/dsl.png[A screenshot of the DSL syntax,width=597,height=512,role=focal_point]
+image::https://alchemists.io/images/projects/sod/screenshots/dsl.png[A screenshot of the DSL syntax,width=539,height=479,role=focal_point]
 
 *Output*
 
-image::https://alchemists.io/images/projects/sod/screenshots/output.png[A screenshot of the generated help documentation,width=473,height=500,role=focal_point]
+image::https://alchemists.io/images/projects/sod/screenshots/output.png[A screenshot of the generated help documentation,width=472,height=498,role=focal_point]
 
 == Requirements
 
@@ -122,8 +120,8 @@ Notice, with only a few extra lines of code, you can build upon the initial _bla
 cli = Sod.new :demo, banner: "Demo 0.0.0: A demonstration." do
   on Sod::Prefabs::Actions::Help, self
 
-  on "generate", "Generate project templates."
-  on "db", "Manage database."
+  on :generate, "Generate project templates."
+  on :db, "Manage database."
 end
 
 cli.call
@@ -208,11 +206,11 @@ You've already seen some of the DSL syntax, via the earlier examples, but now we
 [source,ruby]
 ----
 Sod.new :demo, banner: "Demo 0.0.0: A demonstration." do
-  on "db", "Manage database." do
+  on :db, "Manage database." do
     on Start
     on Stop
 
-    on "structure", "Manage database structure." do
+    on :structure, "Manage database structure." do
       on Dump
     end
   end
@@ -265,11 +263,11 @@ To further understand the DSL, commands, and actions you'll need to start with a
 
 ==== Actions
 
-Actions are the lowest building blocks of the DSL which allow you to quickly implement, test, reuse, and compose more complex architectures. They provide a nice wrapper around native {option_parser_link} functionality so if you are familiar with how `OptionParser#on` works, then you'll feel at home with actions.
+Actions are the lowest building blocks of the DSL which allow you to quickly implement, test, reuse, and compose more complex architectures. They provide a nice layer atop native `OptionParser#on` functionality.
 
 There are two kinds of actions: custom and prefabricated. We'll start with custom actions and explore prefabricated actions later. Custom actions allow you to define your own functionality by inheriting from `Sod::Action` and leveraging the DSL that comes with it. Here's a high level breakdown of the macros you can use:
 
-* `description`: Optional (but strongly encouraged). Allows you to describe your action and appears within help documentation. If the description is not defined, then your action will be runnable while hidden from help documentation (this is similar to how {rake_link} task descriptions work).
+* `description`: Optional (but strongly encouraged). Allows you to describe your action and appears within help documentation. If the description is not defined, then only your action's handle (i.e. aliases) will be shown.
 * `ancillary`: Optional. Allows you to provide supplemental text in addition to your description that might be helpful to know about when displaying help documentation. This can accept single or multiple arguments. Order matters since each argument will appear on a separate line in the order listed.
 * `on`: Required. Allows you to define the behavior of your action through keyword arguments. Otherwise, if not defined, the action will be ignored. This macro mimics {option_parser_link} `#on` behavior via the following positional and keyword arguments:
 ** `aliases`: Required. This is a positional argument and defines the short and long form aliases of your action. Your aliases can be a single string (i.e. `on "--version"`) or an array of short and long form aliases. For example, using `on %w[-v --version]` would allow you to use `-v` or `--version` from the command line to call your action. You can also use boolean aliases such as `--build` or `--[no-]build` which the option parser will supply to your `#call` method as a boolean value.
@@ -283,7 +281,7 @@ There are two kinds of actions: custom and prefabricated. We'll start with custo
 ** `default`: Optional. Allows you to supply a default value and is a handy for simple values which don't require lazy evaluation via the corresponding default macro. ⚠️ This is ignored if the corresponding macro is used so ensure you use one or the other but not both.
 ** `description`: Optional. Allows you to define a description. Handy for short descriptions that can fit on a single line. Otherwise, for longer descriptions, use the macro. ⚠️ This is ignored if the corresponding macro is used so ensure you use one or the other but not both.
 ** `ancillary`: Optional. Allows you to define ancillary text to supplement your description. It can accept a string or an array. Handy for short, supplementary, text that can fit on a single line. Otherwise, for more verbose details, use the macro. ⚠️ This is ignored if the corresponding macro is used so ensure you use one or the other but not both.
-* `default`: Optional. Uses a block, which is lazy evaluated, so you can define a default value. This is most helpful when used in combination with an _optional_ `argument` and/or `type` which can fallback to a safe default. This information shows up in the help text too. If your default value is a boolean then it will be color coded green for `true` and red for `false`.
+* `default`: Optional. Uses a block, which is lazy evaluated, so you can define a default value. This is most helpful when used in combination with an _optional_ `argument` and/or `type` which can fallback to a safe default. This information shows up in the help text where the value will be rendered green text. In the case of booleans, they will be rendered as green for `true` and red for `false`.
 
 At a minimum, you want to define the `description` and `on` macros while implementing the `#call` message. Here's an example of implementing an action that echoes input as output:
 
@@ -451,53 +449,57 @@ Commands are a step up from actions in that they allow you to organize and group
 
 [source,ruby]
 ----
-options = {}
+#! /usr/bin/env ruby
+# frozen_string_literal: true
+
+# Save as `snippet`, then `chmod 755 snippet`, and run as `./snippet`.
+
+require "optparse"
+
+input = {}
 
 # Command
-OptionParser.new do |parser|
+parser = OptionParser.new do |instance|
   # Actions
-  parser.on("--one", "One.") { |value| options[:one] = value }
-  parser.on("--two", "Two.") { |value| options[:two] = value }
-  parser.on("--three", "Three.") { |value| options[:three] = value }
+  instance.on("--[no-]one", "One.") { |value| input[:one] = value }
+  instance.on("--[no-]two", "Two.") { |value| input[:two] = value }
 end
+
+parser.parse ["--one", "--no-two"]
+puts input
+
+# {:one=>true, :two=>false}
 ----
 
 The equivalent of the above, as provided by this gem, is:
 
 [source,ruby]
 ----
-require "dry/container"
-require "infusible"
-require "refinements/structs"
-require "sod"
+#! /usr/bin/env ruby
+# frozen_string_literal: true
 
-module Container
-  extend Dry::Container::Mixin
+# Save as `snippet`, then `chmod 755 snippet`, and run as `./snippet`.
 
-  register(:input, memoize: true) { Hash.new }
-end
+require "bundler/inline"
 
-Import = Infusible.with Container
+gemfile true do
+  source "https://rubygems.org"
+  gem "sod", path: "~/Engineering/OSS/sod"
+end
 
 class One < Sod::Action
-  include Import[:input]
-
   on "--[no-]one", description: "One."
 
-  def call(value) = input[:one] = value
+  def call(value) = context.input[:one] = value
 end
 
 class Two < Sod::Action
-  include Import[:input]
-
   on "--[no-]two", description: "Two."
 
-  def call(value) = input[:two] = value
+  def call(value) = context.input[:two] = value
 end
 
 class Demo < Sod::Command
-  include Import[:input]
-
   handle "demo"
 
   description "A demonstration command."
@@ -505,11 +507,13 @@ class Demo < Sod::Command
   on One
   on Two
 
-  def call = puts input
+  def call = puts context.input
 end
 
-cli = Sod.new :demo, banner: "Demo 0.0.0: A demonstration" do
-  on Demo
+context = Sod::Context[input: {}]
+
+cli = Sod.new banner: "Demo 0.0.0: A demonstration" do
+  on(Demo, context:)
   on Sod::Prefabs::Actions::Help, self
 end
 
@@ -518,15 +522,13 @@ cli.call ["demo", "--one", "--no-two"]
 # {:one => true, :two => false}
 ----
 
-You might be thinking: "Hey, that's more lines of code!" True but -- more importantly -- you get the benefit of composible and reusable architectures -- because each command/action is encapsulated -- which you don't get with {option_parser_link}.
-
-By the way, the above example uses the {dry_container_link} gem for defining dependencies and the {infusible_link} gem for injecting those dependencies. You'll also notice that the `input` hash is memoized within the container to allow for mutation. The fact that you have to mutate input is a bummer and you should strive to avoid mutation whenever you can. In this case, mutation is necessary because the underlining architecture of the {option_parser_link} doesn't provide any other way to share state amongst your commands and actions. So this is one example of how you can do that.
+You might be thinking: "Hey, that's more lines of code!" True but -- more importantly -- you get the benefit of composible and reusable architectures -- because each command/action is encapsulated -- which you don't get with {option_parser_link}. You'll also notice that the `input` hash is mutated. The fact that you have to mutate input is a bummer and you should strive to avoid mutation whenever you can. In this case, mutation is necessary because the underlining architecture of the {option_parser_link} doesn't provide any other way to share state amongst your commands and actions. So this is one example of how you can do that.
 
-You'll also notice, as mentioned with actions earlier, that commands share, roughly, the same DSL as actions with a few differences in terms of macros:
+As mentioned earlier with actions, commands share a similar DSL with a few differences in terms of macros:
 
-* `handle`: Required. The name of your command or the _namespace_ for which you group multiple actions. Otherwise, if not defined, then your command won't be runnable.
-* `description`: Optional (but strongly recommended). Defines what your command is about and shows up in the help documentation. Otherwise, if not provided, your command's description will be blank.
-* `ancillary`: Optional. Allows you to provide supplemental text for your description that might be helpful to know about when displaying help documentation. This can accept single or multiple arguments. Order matters since each argument will appear on a separate line in the order listed.
+* `handle`: Required. The name of your command or the _namespace_ for which you group multiple actions. Must be a string. Otherwise, if not defined, you'll get a `Sod::Error`.
+* `description`: Optional (but strongly recommended). Defines what your command is about and shows up in the help documentation. Otherwise, if not provided, only your command's handle will be shown.
+* `ancillary`: Optional. Allows you to provide supplemental text for your description. Can accept single or multiple arguments. Order matters since each argument will appear on a separate line in the order listed below your description.
 * `on`: Required. The syntax for this is identical to the CLI DSL where you define your action (constant) as the first positional argument followed by any number of positional and/or keyword arguments that you want to feed into your action when the `.new` method is called.
 
 If we reuse the above example and print the help documentation, you'll see the following output:
@@ -573,7 +575,7 @@ Inline commands provide a lightweight way to namespace your actions when you don
 [source,ruby]
 ----
 cli = Sod.new :demo, banner: "Demo 0.0.0: A demonstration" do
-  on "demo", "A demonstration command." do
+  on :demo, "A demonstration command." do
     on One
     on Two
   end
@@ -587,7 +589,7 @@ Inline commands can have ancillary text by passing in additional arguments _afte
 [source,ruby]
 ----
 cli = Sod.new :demo, banner: "Demo 0.0.0: A demonstration" do
-  on "demo", "A demonstration command.", "Some text.", "Some more text."
+  on :demo, "A demonstration command.", "Some text.", "Some more text."
 end
 ----
 
@@ -602,7 +604,7 @@ A _reusable_ command is what you saw earlier where you can subclass from `Sod::C
 [source,ruby]
 ----
 class Demo < Sod::Command
-  handle "demo"
+  handle :demo
 
   description "A demonstration command."
 
@@ -664,7 +666,7 @@ context.defaults_path               # "path/to/defaults.yml"
 context["my/path", :defaults_path]  # "my/path"
 ----
 
-The override is handy for situations where you have a default value that you would prefer to use (i.e. first argument) but want to fallback to the `:defaults_path` if the override is `nil`. When you put all of this together, this means you can build a single context and use it within your commands and actions by injecting it:
+The override is handy for situations where you have a value (first argument) that you would prefer to use while still being able to fallback to the `:defaults_path` if the override is `nil`. When you put all of this together, this means you can build a single context and use it within your commands and actions by injecting it:
 
 [source,ruby]
 ----
@@ -681,7 +683,7 @@ end
 
 ==== Types
 
-Types are a way to extend default {option_parser_link} functionality. Two types, not provided by {option_parser_link}, that are worth being aware of are:
+Types are a way to extend default {option_parser_link} functionality. Two types -- not provided by {option_parser_link} -- worth being aware of are:
 
 **Pathname**
 
@@ -843,7 +845,7 @@ class Echo < Sod::Action
 end
 
 cli = Sod.new :demo, banner: "Demo 0.0.0: A demonstration." do
-  on "db", "Manage database." do
+  on :db, "Manage database." do
     on Start
     on Stop
   end
@@ -925,6 +927,12 @@ You can also use the IRB console for direct access to all objects:
 bin/console
 ----
 
+=== Architecture
+
+The architecture of this gem is built entirely around {option_parser_link} by using a graph of nodes (i.e. commands) which can be walked since each node within the graph may or may not have children (i.e. nesting).
+
+image::https://alchemists.io/images/projects/sod/doc/architecture.svg[Architecture Diagram]
+
 == Tests
 
 To test, run:

data/lib/sod/action.rb

@@ -8,9 +8,9 @@ module Sod
   class Action
     extend Forwardable
 
-    def self.inherited base
+    def self.inherited subclass
       super
-      base.class_eval { @attributes = {} }
+      subclass.class_eval { @attributes = {} }
     end
 
     def self.description text
@@ -42,11 +42,12 @@ module Sod
 
       @record = model[
         **klass.instance_variable_get(:@attributes),
-        description: klass.instance_variable_get(:@description),
-        ancillary: Array(klass.instance_variable_get(:@ancillary)).compact,
+        description: load(:description),
+        ancillary: Array(load(:ancillary)).compact,
         default: load_default
       ]
 
+      verify_aliases
       verify_argument
     end
 
@@ -68,12 +69,23 @@ module Sod
 
     private
 
+    def verify_aliases
+      fail Error, "Aliases must be defined." unless aliases
+    end
+
     def verify_argument
       return unless argument && !argument.start_with?("[") && default
 
       fail Error, "Required argument can't be used with default."
     end
 
+    def load attribute
+      klass = self.class
+      fallback = klass.instance_variable_get(:@attributes)[attribute]
+
+      klass.instance_variable_get("@#{attribute}") || fallback
+    end
+
     def load_default
       klass = self.class
       fallback = klass.instance_variable_get(:@attributes)[:default].method :itself

data/lib/sod/command.rb

@@ -10,9 +10,9 @@ module Sod
 
     include Import[:logger]
 
-    def self.inherited base
+    def self.inherited subclass
       super
-      base.class_eval { @actions = Set.new }
+      subclass.class_eval { @actions = Set.new }
     end
 
     def self.handle text
@@ -35,16 +35,10 @@ module Sod
 
     def initialize(context: Context::EMPTY, model: Models::Command, **)
       super(**)
-      klass = self.class
       @context = context
+      @record = build_record model
 
-      @record = model[
-        handle: klass.instance_variable_get(:@handle),
-        description: klass.instance_variable_get(:@description),
-        ancillary: Array(klass.instance_variable_get(:@ancillary)).compact,
-        actions: Set[*build_actions],
-        operation: method(:call)
-      ]
+      verify_handle
     end
 
     def call
@@ -65,10 +59,26 @@ module Sod
 
     private
 
+    def build_record model
+      klass = self.class
+
+      model[
+        handle: klass.instance_variable_get(:@handle),
+        description: klass.instance_variable_get(:@description),
+        ancillary: Array(klass.instance_variable_get(:@ancillary)).compact,
+        actions: Set[*build_actions],
+        operation: method(:call)
+      ]
+    end
+
     def build_actions
       self.class.instance_variable_get(:@actions).map do |action, positionals, keywords|
         action.new(*positionals, **keywords.merge!(context:))
       end
     end
+
+    def verify_handle
+      fail Error, "Invalid handle: #{handle.inspect}. Must be a string." unless handle in String
+    end
   end
 end

data/lib/sod/context.rb

@@ -11,11 +11,10 @@ module Sod
       @attributes = attributes
     end
 
-    # :reek:ControlParameter
-    def [] default, fallback
-      default || public_send(fallback)
+    def [] override, fallback
+      override || public_send(fallback)
     rescue NoMethodError
-      raise Error, "Invalid context. Default or fallback (#{fallback.inspect}) values are missing."
+      raise Error, "Invalid context. Override or fallback (#{fallback.inspect}) values are missing."
     end
 
     def to_h = attributes.dup

data/lib/sod/graph/node.rb

@@ -28,14 +28,12 @@ module Sod
 
       def get_child(*lineage, node: self) = lineage.empty? ? node : get(lineage, node, __method__)
 
-      def on(object, *, **, &block)
+      def on(object, *, **, &)
         lineage.clear if depth.zero?
 
         process(object, *, **)
-
-        increment
-        instance_eval(&block) if block
-        decrement
+        visit(&)
+        self
       end
 
       def call = (operation.call if operation)
@@ -46,8 +44,6 @@ module Sod
 
       attr_accessor :depth
 
-      # :reek:TooManyStatements
-      # rubocop:todo Metrics/AbcSize
       def process(object, *, **)
         ancestry = object.is_a?(Class) ? object.ancestors : []
 
@@ -61,7 +57,6 @@ module Sod
           fail Error, "Invalid command or action. Unable to add: #{object.inspect}."
         end
       end
-      # rubocop:enable Metrics/AbcSize
 
       def add_inline_command handle, *positionals
         description, *ancillary = positionals
@@ -99,6 +94,12 @@ module Sod
         public_send(message, *lineage, node:)
       end
 
+      def visit &block
+        increment
+        instance_eval(&block) if block
+        decrement
+      end
+
       def increment = self.depth += 1
 
       def decrement = self.depth -= 1

data/lib/sod/presenters/node.rb

@@ -16,7 +16,7 @@ module Sod
       using Refinements::Arrays
       using Refinements::Strings
 
-      delegate Graph::Node.members => :node
+      delegate %i[handle description ancillary operation children] => :node
 
       attr_reader :actions
 
@@ -32,9 +32,9 @@ module Sod
       # rubocop:enable Metrics/ParameterLists
 
       def to_s
-        [banner, "", *usage, "", *colored_actions, "", *colored_commands].tap(&:compact!)
-                                                                         .join("\n")
-                                                                         .strip
+        [banner, body, "", *usage, "", *colored_actions, "", *colored_commands].tap(&:compact!)
+                                                                               .join("\n")
+                                                                               .strip
       end
 
       private
@@ -43,6 +43,8 @@ module Sod
 
       def banner = color[description, :bold]
 
+      def body = ancillary.empty? ? nil : ancillary.join("\n").prepend("\n")
+
       def usage
         actions = "  #{colored_handle} [OPTIONS]" unless all.empty?
         commands = "  #{colored_handle} COMMAND [OPTIONS]" unless children.empty?

data/sod.gemspec

@@ -2,11 +2,11 @@
 
 Gem::Specification.new do |spec|
   spec.name = "sod"
-  spec.version = "0.0.0"
+  spec.version = "0.1.0"
   spec.authors = ["Brooke Kuhlmann"]
   spec.email = ["brooke@alchemists.io"]
   spec.homepage = "https://alchemists.io/projects/sod"
-  spec.summary = "A Domain Specific Language for creating composable Command Line Interfaces."
+  spec.summary = "A domain specific language for creating composable command line interfaces."
   spec.license = "Hippocratic-2.1"
 
   spec.metadata = {

data.tar.gz.sig

@@ -1,4 +1,3 @@
-�ē�U����{�RAm����\�o�CO�%�~���}h�%J�p�g�}�o�ދ[_��N���	��-ǩ2��&Y�'9���(�$�؍���v�q�����"W���Ǽa��a`)p�.p�0(z2���Gp)r5g��u�X���a����ć��LW�
-��F���o��c`��'���U�$�^�`cTe!P��
-���z�����-R?�I%d{L�62=�#}�Pp��ʫ6sVѣ�H
-i�����7/v|
+I�n�����M`U�sbÉn�aV����m�-ᭌ�bi���1�U	����%�8���Y���x�mV�j���n��t��JQ�tx�gH��i��z*y�����~�iV٢�X�R4z o�.S��,z��3�w{
+i���ȖR��a�J�Kjx��l�aA-�w �M�z�"t/B��H[�1Ę��F@O��
+^(�RF���~(x���X׳�r��|6�^).�r?�m�O�\�x�y�0�

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sod
 version: !ruby/object:Gem::Version
-  version: 0.0.0
+  version: 0.1.0
 platform: ruby
 authors:
 - Brooke Kuhlmann
@@ -35,7 +35,7 @@ cert_chain:
   3n5C8/6Zh9DYTkpcwPSuIfAga6wf4nXc9m6JAw8AuMLaiWN/r/2s4zJsUHYERJEu
   gZGm4JqtuSg8pYjPeIJxS960owq+SfuC+jxqmRA54BisFCv/0VOJi7tiJVY=
   -----END CERTIFICATE-----
-date: 2023-06-15 00:00:00.000000000 Z
+date: 2023-06-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: cogger
@@ -186,5 +186,5 @@ requirements: []
 rubygems_version: 3.4.14
 signing_key:
 specification_version: 4
-summary: A Domain Specific Language for creating composable Command Line Interfaces.
+summary: A domain specific language for creating composable command line interfaces.
 test_files: []