thor_enhance 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b07825b4f1216de172d6ce7b7ec2052bccee6793c38ceca8b50f094bcbf3deae
-  data.tar.gz: 4458ad58f0148f4a77da324893a538e40c1def979eb26305cdb2e005afa500f7
+  metadata.gz: 921021cfeb7e6d2528aa29efeeeb0b282208b08cecef9dff992dd421696f13d6
+  data.tar.gz: e43f824f5d32922d71c385722b50f31f34a7c7912eb2e6b93e1cb507e7e9f8e3
 SHA512:
-  metadata.gz: a10dfebf316a1ad8a5c6b63a91f90b7fe95391b3f40379bbe37dcfd2e89f9cffe8d48a975fa147210a229376ec736927301eaa042def05a146960646ac0e81ba
-  data.tar.gz: 0d96db3833f42a605f7c341dd8a0a43788f1d447767df9d632a0950543bec63f05adc620b8c298b46184e44f236ac39692ecafe7cf857c091261ecda005e3031
+  metadata.gz: 74090f01c075d963fbffd046cb4f3968901cb5683d8bf1f1f91a181de618e75f1ec20368fd0d04815ed76962f00c12a409c24639e03e7c80b647e6ad980ddafd
+  data.tar.gz: 2d815c6bc7957019524de7785b4678d8b10ccaa38f9d172ea383f21241cfaf80cf9601573d859140c7e4b29b9d14cdc3ce5f492c3a2bd282f8b5be33100e81eb

data/CHANGELOG.md

@@ -5,22 +5,11 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased]
 
-## [0.2.0] - 2022-06-18
+## [0.3.0]
+- remove `warn` hook in favor of enriched `deprecate` hook
+- method name validation on entry
+- Add examples and better documentation
 
-### Added
-- New feature 1
-- New feature 2
-
-### Changed
-- Changed feature 1
-- Changed feature 2
-
-### Removed
-- Removed feature 1
-- Removed feature 2
-
-### Fixed
-- Bug fix 1
-- Bug fix 2
+## [0.2.0]
+- Stable Release

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    thor_enhance (0.2.0)
+    thor_enhance (0.3.0)
       thor (~> 1.3)
 
 GEM

data/docs/command.md

@@ -0,0 +1,54 @@
+# Command Method Injection
+
+Command Method injection allows you to easily enrich Thor Commands with additional data.
+
+## When to use:
+This should be used when you want to enrich your command data. This data can then be retrieved by using the [ThorEnhance::Tree](tree.md) class.
+
+## How to use
+
+Additional configuration is needed prior to loading the your Thor instance
+
+```ruby
+# thor_enhance_config.rb
+ThorEnhance.configure do |c|
+  # Adds `example` method to the command
+  # Value can be anything and is a repeatable command
+  c.add_command_method_enhance "example", repeatable: true
+
+  # Adds `validate` method to the command
+  # Value must be one of :some or :thing
+  c.add_command_method_enhance "validate", enum: [:some, :thing]
+
+  # Adds `enhace` method to the command
+  # Value must be of type CustomClass
+  # It is repeatble and required
+  c.add_command_method_enhance "enhance", allowed_klasses: [CustomClass], repeatable: true, required: true
+end
+```
+The `add_option_enhance` takes the name as argument 1 followed by options.
+
+The available options are:
+
+**enums**:
+- When provided, the value of the `name` must be a value in the `enums` array
+EX: `publish: true` succeeds. `publish: :fail` fails.
+- Default: `nil`
+
+**allowed_klasses**
+- When provided, this is expected to be an array of class types the value can be.
+- Default: `nil`
+
+**required**
+- When flag is set to true, this option will be required on all `method_option` immediately. An error is raised if validation fails
+- Default: `false`
+
+**repeatable**
+- When flag is set to true, this option will allow the same command to reference the method multiple times. The value will be retreable as an Array from [ThorEnhance::Tree](tree.md) class.
+- Default: `false`
+
+# Examples:
+
+[Basic Example](../examples/basic_example.md)
+[Basic Example with Subcommand](../examples/basic_example_with_subcommand.md)
+

data/docs/hooks.md

@@ -0,0 +1,59 @@
+# Hooks:
+
+Hooks allow you to slowly deprecate options over time. There are three basic Hooks available on every method_option
+
+## Arguments:
+Both `deprecate` and `hook` are expected to be a `proc`. The input arguments will be `input, options`
+
+### Argument: Input
+The `input` argument is the first argument. It is the value that the user inputted. When there is no user input, the hook will not run.
+
+### Argument: Option
+The `option` argument is the second argument. It is the `Thor::Option` struct for that existing method. The instance will have all ThorEnhance methods available.
+
+## Deprecate:
+The `deprecate` hook is available on every `method_option`. It expects a `Proc` class. The returned value from the proc is expected as either an Hash or a String.
+
+This hook should be used when you want to either immediately depreacte a method or over time deprecate a command while migrating to a new command. The decision to raise or warn is dynamic in real time.
+
+### When returned an String
+If the method option is provided, it will raise `ThorEnhance::OptionDeprecated` every time
+
+### When returned a Hash
+**hash[:raise]**: Expected a boolean value on weather to raise or warn. When true, it will raise `ThorEnhance::OptionDeprecated`. When false it will send WARNING to console
+**hash[:warn]**: Console message used when `:raise` is false. Does not output when `:raise` is true
+**hash[:msg]**: Message for both raise and warn. This should a short message on how to migrate to new command or syntax
+
+```ruby
+# When provided `--value1 "string"`:
+# This will raise `ThorEnhance::OptionDeprecated` with a message that looks like:
+# Passing value for option --value1 is deprecated. Provided `string`. Please migrate to `--value4`
+method_option :value1, type: :string, deprecate: ->(input, option) { "Please migrate to `--value4`" }
+
+# When provided `--value2 "string"` and deprecated criteria is not met:
+# This will send a WARNING message to the console. It will resemble:
+# Passing value for option --value1 is deprecated. Provided `string`. Please migrate to `--value4`
+method_option :value2, type: :string, deprecate: ->(input, option) { { raise: Date.today > Date.today, warn: "This option will deprecate after #{Date.today}", msg: "Please migrate to --value4"} }
+
+# When provided `--value3 "string"` and deprecated criteria is:
+# This will raise `ThorEnhance::OptionDeprecated` with a message that looks like:
+# Passing value for option --value3 is deprecated. Provided `string`. Please migrate to `--value4`
+method_option :value3, type: :string, deprecate: ->(input, option) { { raise: true, warn: "This option will deprecate after #{Date.today}", msg: "Please migrate to --value4"} }
+```
+
+## Hook
+The `hook` hook is available on every `method_option`. It expects a `Proc` class. No return value is expected. When the input is provided, custom code can get executed
+
+```ruby
+# When provided `--value1 "string"`:
+# This will raise `ThorEnhance::OptionDeprecated` with a message that looks like:
+# Passing value for option --value1 is deprecated. Provided `string`. Please migrate to `--value4`
+method_option :value1, type: :string, hook: ->(input, option) { Kernel.puts "#{input} is a good choice for #{option.name}" }
+```
+
+---
+
+# Examples
+
+For examples, [please navigate here](../examples/hooks.md)
+

data/docs/method_option.md

@@ -0,0 +1,52 @@
+# Method Option Injection
+
+Method option injection allows you to easily add additional flags to the `method_option` for commands. You can set them as required for every option. You can even set allowable values or allowable classes
+
+## When to use:
+This should be used when you want to enrich your command data. This data can then be retrieved by using the [ThorEnhance::Tree](tree.md) class.
+
+## How to use
+
+Additional configuration is needed prior to loading the your Thor instance
+
+```ruby
+# thor_enhance_config.rb
+ThorEnhance.configure do |c|
+  # Adds `classify` method to the option class
+  # Value of classify must be one of the enums
+  # It is not a required field on every method
+  c.add_option_enhance "classify", allowed_klasses: [String, Symbol, NilClass], required: false
+
+  # Adds `publish` method to the option
+  # Value of classify must be one of the enums
+  # It is a required field on every option
+  c.add_option_enhance :publish, enums: [true, false], required: true
+
+  # Adds `avoid method to the option
+  # Value is not restricted to any type or enum
+  # Not a required field
+  c.add_option_enhance :avoid
+end
+```
+The `add_option_enhance` takes the name as argument 1 followed by options.
+
+The available options are:
+
+**enums**:
+- When provided, the value of the `name` must be a value in the `enums` array
+EX: `publish: true` succeeds. `publish: :fail` fails.
+- Default: `nil`
+
+**allowed_klasses**
+- When provided, this is expected to be an array of class types the value can be.
+- Default: `nil`
+
+**required**
+- When flag is set to true, this option will be required on all `method_option` immediately. An error is raised if validation fails
+- Default: `false`
+
+# Examples:
+
+[Basic Example](../examples/basic_example.md)
+[Basic Example with Subcommand](../examples/basic_example_with_subcommand.md)
+

data/docs/tree.md

@@ -0,0 +1,42 @@
+# ThorEnhance::Tree
+
+The thor tree is a powerful tool to do introspection on all Thor commands within a repo.
+
+## How to use:
+
+MyTestClass definitiona can be found in [spec_helper.rb](../spec/spec_helper.rb)
+
+```ruby
+require "thor_enhance"
+
+tree = ThorEnhance::Tree.tree(base: MyTestClass)
+
+# View all commands on parent tree:
+tree.children.map(&:command)
+
+# View all commands including subcommands
+
+def iterate_base(base:)
+  tree.map do |name, object|
+    if object.children?
+      iterate_base(base: object)
+    else
+      object.command
+    end
+  end.flatten
+end
+
+iterate_base(base: tree)
+
+# View specific command
+command = tree["test_meth"].command
+
+# View specific sub command
+sub_command_innard = tree["sub"].children["innard"].command
+
+# View Options on specific command
+command.options
+
+# View specific Option on specific command
+sub_command_innard.options[:t]
+```

data/examples/basic_example.md

@@ -0,0 +1,47 @@
+```ruby
+# thor_enhance_config.rb
+
+require "thor_enhance"
+
+ThorEnhance.configure do |c|
+  # Adds `classify` method to the option class
+  # Value of classify must be one of the enums
+  # It is not a required field on every method
+  c.add_option_enhance "classify", enums: [:allowed, :future, :existing], required: false
+
+  # Adds `publish` method to the option
+  # Value of classify must be one of the enums
+  # It is a required field on every option
+  c.add_option_enhance :publish, enums: [true, false], required: true
+
+  # Adds `example` method to the command
+  # Value can be anything and is a repeatable command
+  c.add_command_method_enhance "example", repeatable: true
+end
+```
+
+```ruby
+# thor_cli.rb
+
+require "rubygems"
+require "bundler/setup"
+require "thor_enhance_config"
+
+class ThorEnhancement < Thor
+
+  dec "test", "Testing method"
+  example "thor_cli.rb test --value 'This is rad'"
+  example "thor_cli.rb test"
+  method_option :value, type: :string, publish: true
+  def test
+    command = ThorEnhance::Tree.tree(base: self.class)["test"].command
+    # example was set as `repeatable` so it gets returned as an array
+    command.example.each { puts _1 }
+
+    command.options[:value].publish == true
+    command.options[:value].classify == nil
+  end
+end
+
+ThorEnhancement.start
+```

data/examples/example_with_subcommand.md

@@ -0,0 +1,73 @@
+```ruby
+# thor_enhance_config.rb
+
+require "thor_enhance"
+
+ThorEnhance.configure do |c|
+  # Adds `classify` method to the option class
+  # Value of classify must be one of the enums
+  # It is not a required field on every method
+  c.add_option_enhance :classify, allowed_klasses: [Symbol], required: false
+
+  # Adds `publish` method to the option
+  # Value of classify must be one of the enums
+  # It is a required field on every option
+  c.add_option_enhance "publish", allowed_klasses: [TrueClass, FalseClass], required: true
+
+  # Adds `example` method to the command
+  # Value can be anything and is a repeatable command
+  c.add_command_method_enhance :example, repeatable: true
+end
+```
+
+```ruby
+# thor_cli.rb
+
+require "rubygems"
+require "bundler/setup"
+require "thor_enhance_config"
+
+class ThorEnhancement < Thor
+
+  dec "test", "Testing method"
+  example "thor_cli.rb test --value 'This is rad'"
+  example "thor_cli.rb test"
+  method_option :value, type: :string, publish: true
+  def test
+    command = ThorEnhance::Tree.tree(base: self.class)["test"].command
+    # example was set as `repeatable` so it gets returned as an array
+    command.example.each { puts _1 }
+
+    command.options[:value].publish == true
+    command.options[:value].classify == nil
+  end
+
+  class SubCommand < Thor
+    desc "sub_command", "Command for SubCommand"
+    example "bin/thor sub_command innard -t something -s better"
+    example "bin/thor sub_command innard -s better"
+    example "bin/thor sub_command innard"
+
+    method_option :t, type: :string, classify: :allowed, publish: true
+    method_option :s, type: :string, classify: :erase, publish: false
+    def sub_command
+      parent = ThorEnhance::Tree.tree(base: self.class)["sub"]
+      parent.example.each { puts _1 } # 1 example
+
+      command = parent.children["sub_command"].command
+      command.children? == false
+
+      command.example.each { puts _1 } # 3 examples
+
+      command.options[:t].publish == true
+      command.options[:t].classify == :allowed
+    end
+  end
+
+  desc "sub", "Submodule command line"
+  example "bin/thor sub ***"
+  subcommand "sub", SubCommand
+end
+
+ThorEnhancement.start
+```

data/examples/hooks.md

@@ -0,0 +1,57 @@
+# Hook Examples
+
+For more information on how to use hooks, [view documentation here](../docs/hooks.md)
+
+```ruby
+# thor_enhance_config.rb
+
+require "thor_enhance"
+
+ThorEnhance.configure do |c|
+  # Adds `classify` method to the option class
+  # Value of classify must be one of the enums
+  # It is not a required field on every method
+  c.add_option_enhance "classify", enums: [:allowed, :future, :existing], required: false
+
+  # Adds `publish` method to the option
+  # Value of classify must be one of the enums
+  # It is a required field on every option
+  c.add_option_enhance :publish, enums: [true, false], required: true
+
+  # Adds `example` method to the command
+  # Value can be anything and is a repeatable command
+  c.add_command_method_enhance "example", repeatable: true
+end
+```
+
+```ruby
+# thor_cli.rb
+
+require "rubygems"
+require "bundler/setup"
+require "thor_enhance_config"
+
+VERSION = Gem::Version.new("1.2.3")
+MAX_VERSION = Gem::Version.new("2.0.0")
+class ThorEnhancement < Thor
+
+  dec "test", "Testing method"
+  example "thor_cli.rb test --value 'This is rad'"
+  example "thor_cli.rb test"
+  method_option :value, type: :string, publish: true, deprecate: ->(input, option) { { raise: VERSION > MAX_VERSION, warn: "This option will deprecate with version #{MAX_VERSION}", msg: "Please migrate to --value4"} }
+
+  # Deprecate hook
+  method_option :option, type: :string, publish: false,
+  method_option :test, type: :string, publish: false,
+  def test
+    command = ThorEnhance::Tree.tree(base: self.class)["test"].command
+    # example was set as `repeatable` so it gets returned as an array
+    command.example.each { puts _1 }
+
+    command.options[:value].publish == true
+    command.options[:value].classify == nil
+  end
+end
+
+ThorEnhancement.start
+```

data/lib/thor_enhance/command_hook.rb

@@ -23,13 +23,23 @@ module ThorEnhance
           input_tags = [option.switch_name] + option.aliases
           next unless input_tags.any? { raw_args.include?(_1) }
 
-          proc_value = proclamation.(given_value)
+          proc_value = proclamation.(given_value, option)
 
-          case object[:behavior]
-          when :raise
-            raise ThorEnhance::OptionDeprecated, "Passing value for option #{option.switch_name} is deprecated. Provided `#{given_value}`. #{proc_value}"
-          when :warn
-            Kernel.warn("WARNING: Provided `#{given_value}` for option #{option.switch_name}. #{proc_value}")
+          if object[:behavior] == :request
+            if Hash === proc_value && proc_value.keys.sort == [:raise, :warn, :msg].sort
+              warn_msg = proc_value[:warn].to_s
+              msg = proc_value[:msg].to_s
+              if proc_value[:raise]
+                raise ThorEnhance::OptionDeprecated, "Passing value for option #{option.switch_name} is deprecated. " \
+                  "Provided `#{given_value}`. #{proc_value[:msg]}"
+              else
+                Kernel.warn("WARNING: Provided `#{given_value}` for option #{option.switch_name}. " \
+                  "#{proc_value[:warn]}. #{proc_value[:msg]}")
+              end
+            else
+              raise ThorEnhance::OptionDeprecated, "Passing value for option #{option.switch_name} is deprecated. " \
+                "Provided `#{given_value}`. #{proc_value}"
+            end
           end
         end
       end

data/lib/thor_enhance/configuration.rb

@@ -6,7 +6,7 @@ module ThorEnhance
   class Configuration
 
     # Order is important -- Ensure deoreacte is first
-    HOOKERS = [DEPRECATE = :deprecate, WARNING = :warn, HOOK = :hook]
+    HOOKERS = [DEPRECATE = :deprecate, HOOK = :hook]
 
     class << self
       attr_accessor :allow_changes
@@ -41,8 +41,7 @@ module ThorEnhance
 
     def option_enhance
       @option_enhance ||= {
-        WARNING => { allowed_klasses: [Proc], behavior: :warn, required: false },
-        DEPRECATE => { allowed_klasses: [Proc], behavior: :raise, required: false },
+        DEPRECATE => { allowed_klasses: [Proc], behavior: :request, required: false },
         HOOK => { allowed_klasses: [Proc], behavior: nil, required: false },
       }
     end
@@ -64,6 +63,16 @@ module ThorEnhance
     private
 
     def add_to_variable(storage, methods, name, allowed_klasses, enums, required, repeatable = false)
+      # Reject if the name is not a Symbol or a string
+      if [String, Symbol].none? { _1 === name }
+        raise ArgumentError, "Invalid name type received. Received [#{name}] of type [#{name.class}]. Expected to be of type String or Symbol"
+      end
+
+      # If name contains characters other than upper or lower case letters and _ FAIL
+      unless name =~ /^[A-Za-z_]+$/
+        raise ArgumentError, "Invalid name received. Received [#{name}] does not match /^[A-Za-z_]+$/."
+      end
+
       if methods.include?(name.to_sym)
         raise OptionNotAllowed, "[#{name}] is not allowed as an enhancement"
       end

data/lib/thor_enhance/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ThorEnhance
-  VERSION = "0.2.0"
+  VERSION = "0.3.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: thor_enhance
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Matt Taylor
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2023-11-21 00:00:00.000000000 Z
+date: 2023-11-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: thor
@@ -102,6 +102,13 @@ files:
 - bin/console
 - bin/setup
 - docker-compose.yml
+- docs/command.md
+- docs/hooks.md
+- docs/method_option.md
+- docs/tree.md
+- examples/basic_example.md
+- examples/example_with_subcommand.md
+- examples/hooks.md
 - lib/thor_enhance.rb
 - lib/thor_enhance/command.rb
 - lib/thor_enhance/command_hook.rb