skywalker 1.2.2 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 94d9ef276bef39177c861b711c7511b1fc92bcaa
-  data.tar.gz: f51dec3775158214e5df6ee43b5f86086f724a60
+  metadata.gz: dee046be5564b0553dc68ccb39100a40156404fb
+  data.tar.gz: afec05026a60744290c39d3fed58377864019dc1
 SHA512:
-  metadata.gz: 139095d5a12396bb21202fb9ec889e4c684e4c96cc563acdf73022db254ba8041551f9b52d902a99d4be0b1eaacabd891209b640154c7657834ee962edc55cf0
-  data.tar.gz: 095d970db31f2eacb5557f0ab4d800a609df68ceb64d139e575ce22676f60c6ca758e31a296fd07cf6526f79f5c0e3ced09c6116f7a5a3d464e603bf47ba3965
+  metadata.gz: 8b1432945db2c162d1775d00e07e7c1373b463ef7db0ac921e0a75373b6e6da30f0352ace272bb1dc5286a16296b4297e155d0fdb49919fa3885ab33eb1e446e
+  data.tar.gz: 4c5e09daaaceb2550c3a361181d83e6af830f527fa7a875afd05939d763711754e2129c1d6b9f74183955319025dda21e4457e364f2c39eb495831dbedcf67e7

data/CHANGELOG.md

@@ -1,5 +1,10 @@
 All commits by Rob Yurkowski unless otherwise noted.
 
+## 2.0.0 (2015-05-02)
+
+- Refactors guts of commands to extract kwarg instantiation pattern into `Acceptable` module.
+- Improves inline documentation.
+
 ## 1.2.2 (2015-03-26)
 
 - Loosen restrictions on ActiveRecord version.

data/README.md

@@ -314,7 +314,6 @@ undefined method `call' for nil:NilClass
 This means that the command failed and you didn't specify an `on_failure` callback. You can stick a debugger
 inside of `run_failure_callbacks`, and get the failure exception as `self.error`. You can also reraise the exceptiong to achieve a better result summary, but this is not done by default, as you may also want to test error handling.
 
-
 ## Contributing
 
 1. Fork it ( https://github.com/robyurkowski/skywalker/fork )

data/examples/Gemfile.lock

@@ -1,33 +1,33 @@
 PATH
   remote: ../
   specs:
-    skywalker (1.2.2)
+    skywalker (2.0.0)
       activerecord (>= 4.0)
 
 GEM
   remote: https://rubygems.org/
   specs:
-    activemodel (4.1.8)
-      activesupport (= 4.1.8)
+    activemodel (4.2.1)
+      activesupport (= 4.2.1)
       builder (~> 3.1)
-    activerecord (4.1.8)
-      activemodel (= 4.1.8)
-      activesupport (= 4.1.8)
-      arel (~> 5.0.0)
-    activesupport (4.1.8)
-      i18n (~> 0.6, >= 0.6.9)
+    activerecord (4.2.1)
+      activemodel (= 4.2.1)
+      activesupport (= 4.2.1)
+      arel (~> 6.0)
+    activesupport (4.2.1)
+      i18n (~> 0.7)
       json (~> 1.7, >= 1.7.7)
       minitest (~> 5.1)
-      thread_safe (~> 0.1)
+      thread_safe (~> 0.3, >= 0.3.4)
       tzinfo (~> 1.1)
-    arel (5.0.1.20140414130214)
+    arel (6.0.0)
     builder (3.2.2)
     coderay (1.1.0)
     diff-lcs (1.2.5)
-    i18n (0.6.11)
-    json (1.8.1)
+    i18n (0.7.0)
+    json (1.8.2)
     method_source (0.8.2)
-    minitest (5.4.3)
+    minitest (5.6.1)
     pry (0.10.1)
       coderay (~> 1.1.0)
       method_source (~> 0.8.1)
@@ -45,7 +45,7 @@ GEM
       rspec-support (~> 3.1.0)
     rspec-support (3.1.2)
     slop (3.6.0)
-    thread_safe (0.3.4)
+    thread_safe (0.3.5)
     tzinfo (1.2.2)
       thread_safe (~> 0.1)
 

data/lib/skywalker/acceptable.rb

@@ -0,0 +1,70 @@
+module Skywalker
+  module Acceptable
+
+    #
+    # Creates an `_args` accessor on inclusion.
+    #
+    # @since 2.0.0
+    #
+    def self.included(klass)
+      klass.send(:attr_accessor, :_args)
+    end
+
+
+    #
+    # Instantiates an object, setting all kwargs as accessors.
+    #
+    # @since 2.0.0
+    #
+    def initialize(**args)
+      self._args = args
+      self._args.freeze
+
+      validate_arguments!
+      parse_arguments
+    end
+
+
+    #
+    # Ensures required keys are present.
+    #
+    # @since 2.0.0
+    #
+    private def validate_arguments!
+      missing_args = required_args.map(&:to_s) - _args.keys.map(&:to_s)
+
+      raise ArgumentError, "#{missing_args.join(", ")} required but not given" \
+        if missing_args.any?
+    end
+
+
+    #
+    # Specifies required arguments to the object. Should be an array of objects
+    # that are coercible to keyword names via `to_s`.
+    #
+    # @since 2.0.0
+    #
+    private def required_args
+      []
+    end
+
+
+    #
+    # Creates an attr_accessor for each passed kwarg and assigns the argument.
+    #
+    # @since 2.0.0
+    #
+    private def parse_arguments
+      _args.each_pair do |reader_method, value|
+        writer_method = "#{reader_method}="
+
+        singleton_class.class_eval do
+          send(:attr_reader, reader_method) unless respond_to?(reader_method)
+          send(:attr_writer, reader_method) unless respond_to?(writer_method)
+        end
+
+        self.send(writer_method, value)
+      end
+    end
+  end
+end

data/lib/skywalker/command.rb

@@ -1,71 +1,35 @@
 require 'active_record'
+require 'skywalker/acceptable'
 
 module Skywalker
   class Command
+    include Acceptable
+
     ################################################################################
     # Class interface
     ################################################################################
+
+    #
+    # Provides a convenient way to call a command without having to instantiate
+    # and call.
+    #
+    # @since 1.0.0
+    #
     def self.call(*args)
       new(*args).call
     end
 
 
-    ################################################################################
-    # Instantiates command, setting all arguments.
-    ################################################################################
-    def initialize(**args)
-      self.args = args
-      self.args.freeze
-
-      parse_arguments
-      validate_arguments!
-
-    end
-
-
     attr_accessor :on_success,
                   :on_failure,
-                  :error,
-                  :args
-
-
-    ################################################################################
-    # Ensure required keys are present.
-    ################################################################################
-    private def validate_arguments!
-      missing_args = required_args.map(&:to_s) - args.keys.map(&:to_s)
-
-      raise ArgumentError, "#{missing_args.join(", ")} required but not given" \
-        if missing_args.any?
-    end
-
-
-    ################################################################################
-    # Any required keys should go here as either strings or symbols.
-    ################################################################################
-    private def required_args
-      []
-    end
+                  :error
 
 
-
-    private def parse_arguments
-      args.each_pair do |reader_method, value|
-        writer_method = "#{reader_method}="
-
-        singleton_class.class_eval do
-          send(:attr_reader, reader_method) unless respond_to?(reader_method)
-          send(:attr_writer, reader_method) unless respond_to?(writer_method)
-        end
-
-        self.send(writer_method, value)
-      end
-    end
-
-
-    ################################################################################
+    #
     # Call: runs the transaction and all operations.
-    ################################################################################
+    #
+    # @since 1.0.0
+    #
     def call
       transaction do
         execute!
@@ -78,42 +42,69 @@ module Skywalker
     end
 
 
-    ################################################################################
-    # Operations should be defined in this method.
-    ################################################################################
-    private def execute!
+    #
+    # Procedural execution method. This should be implemented inside subclasses
+    # to add operations.
+    #
+    # @since 1.0.0
+    #
+    protected def execute!
     end
 
+
     ################################################################################
-    # Override to customize.
+    # Private interface
     ################################################################################
+
+
+    #
+    # Wraps the given block in transactional logic.
+    #
+    # @since 1.0.0
+    #
     private def transaction(&block)
       ::ActiveRecord::Base.transaction(&block)
     end
 
-
-    ################################################################################
-    # Trigger the given callback on success
-    ################################################################################
+    #
+    # Triggers the given callback on success
+    #
+    # @since 1.0.0
+    #
     private def confirm_success
       run_success_callbacks
     end
 
 
+    #
+    # Runs success callback if given. Override to specify additional callbacks
+    # or to add branching logic here.
+    #
+    # @since 1.1.0
+    #
     private def run_success_callbacks
       on_success.call(self) unless on_success.nil?
     end
 
 
-    ################################################################################
-    # Set the error so we can get it with `command.error`, and trigger error.
-    ################################################################################
+    #
+    # Triggered on failure of transaction. Sets `#error` so the exception can
+    # be retrieved, and triggers the error callbacks.
+    #
+    # @since 1.0.0
+    #
     private def confirm_failure(error)
       self.error = error
       run_failure_callbacks
     end
 
 
+    #
+    # Runs failure callback if given. Override to specify additional callbacks
+    # or to add branching logic here.
+    #
+    # @since 1.1.0
+    #
     private def run_failure_callbacks
       on_failure.call(self) unless on_failure.nil?
     end

data/lib/skywalker/version.rb

@@ -1,3 +1,3 @@
 module Skywalker
-  VERSION = "1.2.2"
+  VERSION = "2.0.0"
 end

data/spec/lib/skywalker/acceptable_spec.rb

@@ -0,0 +1,45 @@
+require 'spec_helper'
+require 'skywalker/acceptable'
+
+module Skywalker
+  RSpec.describe Acceptable do
+    let(:klass) { Class.new { include Acceptable } }
+
+    describe "instantiation" do
+      it "freezes the arguments given to it" do
+        instance = klass.new(a_symbol: :my_symbol)
+        expect(instance._args).to be_frozen
+      end
+
+      it "accepts a variable list of arguments" do
+        expect { klass.new(a_symbol: :my_symbol, a_string: "my string") }.not_to raise_error
+      end
+
+      it "sets a reader for each argument" do
+        instance = klass.new(a_symbol: :my_symbol)
+        expect(instance).to respond_to(:a_symbol)
+      end
+
+      it "sets a writer for each argument" do
+        instance = klass.new(a_symbol: :my_symbol)
+        expect(instance).to respond_to(:a_symbol=)
+      end
+
+      it "sets the instance variable to the passed value" do
+        instance = klass.new(a_symbol: :my_symbol)
+        expect(instance.a_symbol).to eq(:my_symbol)
+      end
+
+      it "raises an error if an argument in its required_args is not present" do
+        allow_any_instance_of(klass).to receive(:required_args).and_return([:required_arg])
+        expect { klass.new }.to raise_error
+      end
+
+      it "does not raise an error if an argument in its required_args is present" do
+        allow_any_instance_of(klass).to receive(:required_args).and_return([:required_arg])
+        expect { klass.new(required_arg: :blah) }.not_to raise_error
+      end
+    end
+  end
+end
+

data/spec/lib/skywalker/command_spec.rb

@@ -11,43 +11,6 @@ module Skywalker
     end
 
 
-    describe "instantiation" do
-      it "freezes the arguments given to it" do
-        command = Command.new(a_symbol: :my_symbol)
-        expect(command.args).to be_frozen
-      end
-
-      it "accepts a variable list of arguments" do
-        expect { Command.new(a_symbol: :my_symbol, a_string: "my string") }.not_to raise_error
-      end
-
-      it "sets a reader for each argument" do
-        command = Command.new(a_symbol: :my_symbol)
-        expect(command).to respond_to(:a_symbol)
-      end
-
-      it "sets a writer for each argument" do
-        command = Command.new(a_symbol: :my_symbol)
-        expect(command).to respond_to(:a_symbol=)
-      end
-
-      it "sets the instance variable to the passed value" do
-        command = Command.new(a_symbol: :my_symbol)
-        expect(command.a_symbol).to eq(:my_symbol)
-      end
-
-      it "raises an error if an argument in its required_args is not present" do
-        allow_any_instance_of(Command).to receive(:required_args).and_return([:required_arg])
-        expect { Command.new }.to raise_error
-      end
-
-      it "does not raise an error if an argument in its required_args is present" do
-        allow_any_instance_of(Command).to receive(:required_args).and_return([:required_arg])
-        expect { Command.new(required_arg: :blah) }.not_to raise_error
-      end
-    end
-
-
     describe "validity control" do
       let(:command) { Command.new }
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: skywalker
 version: !ruby/object:Gem::Version
-  version: 1.2.2
+  version: 2.0.0
 platform: ruby
 authors:
 - Rob Yurkowski
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-03-26 00:00:00.000000000 Z
+date: 2015-05-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -115,9 +115,11 @@ files:
 - examples/spec/spec_helper.rb
 - examples/spec/tiny_spec_helper.rb
 - lib/skywalker.rb
+- lib/skywalker/acceptable.rb
 - lib/skywalker/command.rb
 - lib/skywalker/version.rb
 - skywalker.gemspec
+- spec/lib/skywalker/acceptable_spec.rb
 - spec/lib/skywalker/command_spec.rb
 - spec/spec_helper.rb
 homepage: https://github.com/robyurkowski/skywalker
@@ -140,10 +142,11 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.2.2
+rubygems_version: 2.4.5
 signing_key: 
 specification_version: 4
 summary: A simple command pattern implementation for transactional operations.
 test_files:
+- spec/lib/skywalker/acceptable_spec.rb
 - spec/lib/skywalker/command_spec.rb
 - spec/spec_helper.rb