riker 0.1.0.pre4 → 0.1.0.pre6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e87101245bca559270ab4ae68b854ddedcf0bcd3a946bdae50571ddb9717b074
-  data.tar.gz: 702df1dedeacc6dd92dda5a9e90f0640fb1763d9c766e613c4e9669727cae002
+  metadata.gz: bd22e31d55bf8c4144736d6b657463e2550b8a602711adfcc4e8339a164d16c6
+  data.tar.gz: 83b5819f498d4f86f89531f81df7ca845540b108a5cac03274a0fc9d9f0b1ede
 SHA512:
-  metadata.gz: 4fa7e7eef30b47313061ed59cf958b7fb94ca4db2ea461ca94485b9253a3b52223734729ef51fe97bb33456403731aa68281255486aef21218625db708b06609
-  data.tar.gz: 7c24626c3b722677bd57cb5f83fd092e042b2b06fa170b7edc7fa1e18e2c1eb2cb06cd871bcabfd0cba06046502e9a47eb112f2882c40ee16daabceeac5c9514
+  metadata.gz: 7777cf030f8bf79ceaabd4da1a826b32be8cfcc8be0f32b262d1219839dd1268d24596ad3d83320d5eb6da2f15eb9dd31a870ef3f3d12eea53eec61f8bd27982
+  data.tar.gz: 818646ea533fefd5fe79580127585ed365af10352ee0f467aa84017a967a6afcdb0ed639f3933fc6c371bd0535b57c8d156b9b6d5066f32ea168e2372ed9bfbe

data/Gemfile

@@ -5,6 +5,7 @@ source 'https://rubygems.org'
 # Specify your gem's dependencies in riker.gemspec
 gemspec
 
+gem 'pry', '~> 0.14'
 gem 'rake', '~> 13.0'
 gem 'rspec', '~> 3.0'
 gem 'rubocop'

data/Gemfile.lock

@@ -1,17 +1,22 @@
 PATH
   remote: .
   specs:
-    riker (0.1.0.pre4)
+    riker (0.1.0.pre5)
 
 GEM
   remote: https://rubygems.org/
   specs:
     ast (2.4.2)
+    coderay (1.1.3)
     diff-lcs (1.5.0)
     json (2.6.2)
+    method_source (1.0.0)
     parallel (1.22.1)
     parser (3.1.2.1)
       ast (~> 2.4.1)
+    pry (0.14.1)
+      coderay (~> 1.1)
+      method_source (~> 1.0)
     rainbow (3.1.1)
     rake (13.0.6)
     regexp_parser (2.5.0)
@@ -49,6 +54,7 @@ PLATFORMS
   x86_64-linux
 
 DEPENDENCIES
+  pry (~> 0.14)
   rake (~> 13.0)
   riker!
   rspec (~> 3.0)

data/README.md

@@ -12,7 +12,7 @@ High-Performance, Dependency-Free Command Pattern For Ruby
 ### In your gemfile:
 
 ```ruby
-gem 'riker', '0.1.0.pre4'
+gem 'riker', '0.1.0.pre6'
 ```
 
 ### In your code:
@@ -26,6 +26,11 @@ class SimpleGreeting
   param :punctuation, default: '.'
 
   execute do
+    if first_name == 'Voldemort'
+      errors.add(:first_name, 'He who shall not be named!')
+      return
+    end
+
     return "Hello #{first_name}#{punctuation}" if last_name.nil?
 
     "Hello #{first_name} #{last_name}#{punctuation}"
@@ -44,6 +49,24 @@ SimpleGreeting.run!(first_name: 'Will', last_name: 'Riker')
 
 SimpleGreeting.run!(first_name: 'Will', last_name: 'Riker', punctuation: '!')
 # => "Hello Will Riker!"
+
+SimpleGreeting.run!(first_name: 'Voldemort')
+# => Riker::Outcome::ExecutionError => e
+# =>   e.errors.messages == ['He who shall not be named!']
+
+outcome = SimpleGreeting.run(first_name: 'Will')
+outcome.valid?
+# => true
+outcome.result
+# => "Hello Will."
+
+outcome = SimpleGreeting.run(first_name: 'Voldemort')
+outcome.invalid?
+# => true
+outcome.result
+# => nil
+outcome.errors.messages
+# => ['He who shall not be named!']
 ```
 
 ## Default Procs
@@ -72,3 +95,39 @@ CaptainsLog.run!(message: "The Borg are attacking!")
 CaptainsLog.run(message: "We've traveled back in time!", stardate: 42.1337)
 # => "Captain's Log; Stardate: 42.1337\n\nWe've traveled back in time!"
 ```
+
+## Measurement Code
+
+Sometimes you'll want to do some logic around your commands to record
+their performance, number of calls, etc.  Rike allows for this with `around`.
+The result of your measurement code in no way effects the result from
+the command.
+
+```ruby
+module SensorArray
+  class << self
+    # the class and args of the command are provided
+    def deep_scan(klass, args)
+      # anything before code runs
+
+      # code runs here
+      yield
+
+      # anything after you want
+    end
+  end
+end
+
+class CheckWarpDrive
+  extend Riker
+
+  param :stardate
+  param :engineer
+
+  around &SensorArray.method(:deep_scan)
+
+  execute do
+    "WarpDrive checked by #{engineer} on #{stardate}"
+  end
+end
+```

data/lib/riker/command/fallible_methods.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Riker
+  class Command
+    # Fallible Methods
+    #
+    # Every command has fallible functionality.  This is
+    # how you can convey something has gone wrong to the
+    # caller of your command.
+    #
+    module FallibleMethods
+      # @return [Riker::Outcome::Errors]
+      def errors
+        @errors ||= Riker::Outcome::Errors.new
+      end
+
+      # @return [Boolean]
+      def errored?
+        defined?(@errors) && @errors.any?
+      end
+    end
+  end
+end

data/lib/riker/command/function_writer.rb

@@ -2,6 +2,7 @@
 
 require_relative 'run_bang_function'
 require_relative 'initialize_function'
+require_relative 'run_function'
 
 module Riker
   class Command
@@ -13,9 +14,14 @@ module Riker
     class FunctionWriter
       DEFAULT_FUNCTIONS = [
         RunBangFunction,
+        RunFunction,
         InitializeFunction
       ].freeze
 
+      INSTANCE_METHOD_MODULES = [
+        FallibleMethods
+      ].freeze
+
       # @return [Riker::Command]
       attr_reader :command
 
@@ -34,6 +40,7 @@ module Riker
         define_default_setters!(klass)
         define_attr_readers!(klass)
         write_functions!(klass)
+        include_instance_methods!(klass)
       end
 
       private
@@ -57,6 +64,13 @@ module Riker
           param.default.build_default_function!(klass)
         end
       end
+
+      # @param klass [Class]
+      def include_instance_methods!(klass)
+        INSTANCE_METHOD_MODULES.each do |mod|
+          klass.include(mod)
+        end
+      end
     end
   end
 end

data/lib/riker/command/parameters.rb

@@ -12,6 +12,11 @@ module Riker
       include Enumerable
       class ParamNameTaken < ::Riker::Error; end
       class InvalidParamName < ::Riker::Error; end
+      class ReservedAttributeName < ::Riker::Error; end
+
+      RESERVED_ATTR_NAMES = %i[
+        errors
+      ].to_set.freeze
 
       def initialize
         # @var [Hash<Symbol, Parameter>]
@@ -47,6 +52,7 @@ module Riker
 
       def validate_name!(name)
         raise InvalidParamName unless name.is_a?(Symbol)
+        raise ReservedAttributeName if RESERVED_ATTR_NAMES.include?(name)
         raise ParamNameTaken if @params.key?(name)
       end
     end

data/lib/riker/command/run_bang_function.rb

@@ -14,11 +14,43 @@ module Riker
 
       # @return [Riker::Command::FunctionDetails]
       def details
+        if command.around_block
+          with_around_function_block
+        else
+          without_around_block_function
+        end
+      end
+
+      private
+
+      # @return [Riker::Command::FunctionDetails]
+      def without_around_block_function
+        FunctionDetails.new(<<~RUBY, __FILE__, __LINE__ + 1)
+          def self.run!(**arguments)          # def self.run!(**arguments)
+            command = new(**arguments)        #   command = new(**arguments)
+            result = command.execute          #   result = command.execute
+            if command.errored?               #   if command.errored?
+              command.errors.raise!           #     command.errors.raise!
+            end                               #   end
+            result                            #   result
+          end                                 # end
+        RUBY
+      end
+
+      # @return [Riker::Command::FunctionDetails]
+      def with_around_function_block
         FunctionDetails.new(<<~RUBY, __FILE__, __LINE__ + 1)
-          def self.run!(**arguments)    # def initialize(**arguments)
-            command = new(**arguments)  #   command = new(**arguments)
-            command.execute             #   command.execute
-          end                           # end
+          def self.run!(**arguments)                            # def self.run!(**arguments)
+            result = nil                                        #   result = nil
+            self.command.around_block.call(self, arguments) do  #   self.command.around_block.call(klass, arguments) do
+              command = new(**arguments)                        #     command = new(**arguments)
+              result = command.execute                          #     result = command.execute
+              if command.errored?                               #     if command.errored?
+                command.errors.raise!                           #       command.errors.raise!
+              end                                               #     end
+            end                                                 #   end
+            result                                              #   result
+          end                                                   # end
         RUBY
       end
     end

data/lib/riker/command/run_function.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Riker
+  class Command
+    # Run!
+    #
+    # Represents the `run!` static method for your command
+    #
+    class RunFunction < Function
+      # @return [Symbol]
+      def name
+        :run
+      end
+
+      # @return [Riker::Command::FunctionDetails]
+      def details
+        if command.around_block
+          with_around_block_function
+        else
+          without_around_block_function
+        end
+      end
+
+      private
+
+      def without_around_block_function
+        FunctionDetails.new(<<~RUBY, __FILE__, __LINE__ + 1)
+          def self.run(**arguments)                   # def self.run!(**arguments)
+            command = new(**arguments)                #   command = new(**arguments)
+            result = command.execute                  #   result = command.execute
+            if command.errored?                       #   if command.errored?
+              Riker::Outcome.invalid(command.errors)  #     Riker::Outcome.invalid(command.errors)
+            else                                      #   else
+              Riker::Outcome.valid(result)            #     Riker::Outcome.valid(result)
+            end                                       #   end
+          end                                         # end
+        RUBY
+      end
+
+      def with_around_block_function
+        FunctionDetails.new(<<~RUBY, __FILE__, __LINE__ + 1)
+          def self.run(**arguments)                             # def self.run!(**arguments)
+            outcome = nil                                       #   outcome = nil
+            self.command.around_block.call(self, arguments) do  #   self.command.around_block.call(self, arguments) do
+              command = new(**arguments)                        #     command = new(**arguments)
+              result = command.execute                          #     result = command.execute
+              outcome = if command.errored?                     #     outcome = if command.errored?
+                Riker::Outcome.invalid(command.errors)          #       Riker::Outcome.invalid(command.errors)
+              else                                              #     else
+                Riker::Outcome.valid(result)                    #       Riker::Outcome.valid(result)
+              end                                               #     end
+            end                                                 #   end
+            outcome                                             #   outcome
+          end                                                   # end
+        RUBY
+      end
+    end
+  end
+end

data/lib/riker/command.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative 'command/parameters'
+require_relative 'command/fallible_methods'
 require_relative 'command/function'
 require_relative 'command/function_details'
 require_relative 'command/function_writer'
@@ -21,6 +22,9 @@ module Riker
     # @return [Proc, nil]
     attr_accessor :execute_block
 
+    # @return [Proc, nil]
+    attr_accessor :around_block
+
     def initialize
       @parameters = Parameters.new
       @function_writer = FunctionWriter.new(self)

data/lib/riker/outcome/errors.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Riker
+  class Outcome
+    # Outcome Errors
+    #
+    # A wrapper to keep track of and report on errors
+    # that happened during the execution of a command.
+    #
+    class Errors
+      # @!method any?
+      #   @return [Boolean]
+      # @!method none?
+      #   @return [Boolean]
+      extend Forwardable
+      def_delegators :@errors, :any?, :none?
+
+      def initialize
+        @errors = Hash.new { |hash, key| hash[key] = [] }
+      end
+
+      # @param key [Symbol]
+      # @param error [String]
+      # @return [void]
+      def add(key, error)
+        @errors[key] << error
+
+        nil
+      end
+
+      # @return [Array<String>]
+      def messages
+        @errors.values.flatten!
+      end
+
+      # @raise [Riker::ExecutionError]
+      def raise!
+        raise as_execution_error
+      end
+
+      private
+
+      def as_execution_error
+        Riker::Outcome::ExecutionError.new(self)
+      end
+    end
+  end
+end

data/lib/riker/outcome/execution_error.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Riker
+  class Outcome
+    # Execution Error
+    #
+    # This exception is raised when a problem has happened
+    # with your command.  It is the result normall of having
+    # errors.
+    #
+    # @see Riker::Command::FallibleMethods
+    #
+    class ExecutionError < Error
+      # @return [Riker::Outcome::Errors]
+      attr_reader :errors
+
+      # @param errors [Riker::Outcome::Errors]
+      def initialize(errors)
+        super()
+        @errors = errors
+      end
+    end
+  end
+end

data/lib/riker/outcome.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require_relative 'outcome/errors'
+require_relative 'outcome/execution_error'
+
+module Riker
+  # Wrapped Outcome of a Command
+  #
+  # Commands may be fallible; and in that case
+  # they return an outcome that will either detail
+  # the errors that came up during execution or the
+  # expected data if it was success.
+  #
+  class Outcome
+    # @return [Object]
+    attr_reader :result
+
+    class << self
+      # @param result [Object]
+      # @return [Riker::Outcome]
+      def valid(result)
+        new(:valid, result)
+      end
+
+      def invalid(errors)
+        new(:invalid, errors)
+      end
+
+      private :new
+    end
+
+    # @param state [:valid, :invalid]
+    # @data [Object, Riker::Outcome::Errors]
+    def initialize(state, data)
+      if state == :valid
+        @result = data
+      else
+        @errors = data
+      end
+    end
+
+    # @return [Boolean]
+    def valid?
+      return true unless defined?(@errors)
+
+      @errors.none?
+    end
+
+    # @return [Boolean]
+    def invalid?
+      return false unless defined?(@errors)
+
+      @errors.any?
+    end
+
+    # @return [Riker::Outcome::Errors]
+    def errors
+      @errors ||= Errors.new
+    end
+  end
+end

data/lib/riker/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Riker
-  VERSION = '0.1.0.pre4'
+  VERSION = '0.1.0.pre6'
 end

data/lib/riker.rb

@@ -1,9 +1,13 @@
 # frozen_string_literal: true
 
+require 'forwardable'
+require 'set'
+
 require_relative 'riker/version'
 require_relative 'riker/error'
 require_relative 'riker/command'
 require_relative 'riker/parameter'
+require_relative 'riker/outcome'
 
 # The Commander of the USS Enterprise
 module Riker
@@ -27,4 +31,11 @@ module Riker
     command.execute_block = block
     command.function_writer.write!(self)
   end
+
+  # @block the logic to run around a command
+  def around(&block)
+    raise Error, "around block already called for #{self}!" if command.around_block
+
+    command.around_block = block
+  end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: riker
 version: !ruby/object:Gem::Version
-  version: 0.1.0.pre4
+  version: 0.1.0.pre6
 platform: ruby
 authors:
 - Benjamin Falk
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2022-10-07 00:00:00.000000000 Z
+date: 2022-11-01 00:00:00.000000000 Z
 dependencies: []
 description: High-Performance, Dependency-Free Command Pattern For Ruby
 email:
@@ -29,13 +29,18 @@ files:
 - bin/setup
 - lib/riker.rb
 - lib/riker/command.rb
+- lib/riker/command/fallible_methods.rb
 - lib/riker/command/function.rb
 - lib/riker/command/function_details.rb
 - lib/riker/command/function_writer.rb
 - lib/riker/command/initialize_function.rb
 - lib/riker/command/parameters.rb
 - lib/riker/command/run_bang_function.rb
+- lib/riker/command/run_function.rb
 - lib/riker/error.rb
+- lib/riker/outcome.rb
+- lib/riker/outcome/errors.rb
+- lib/riker/outcome/execution_error.rb
 - lib/riker/parameter.rb
 - lib/riker/parameter/default_value.rb
 - lib/riker/version.rb