action_command 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 87d1121215dc01fba0fddbb6f7f33e6465e59c47
-  data.tar.gz: ff9229f8fbafcc73acd0c9f787b7ff0d6b9fa1d5
+  metadata.gz: 0ff531e1eca24b2ebde5421dc5bfb145a3060658
+  data.tar.gz: 157affdb256a84d6a8afd79ef73b2dbf7b684917
 SHA512:
-  metadata.gz: f650e9313684e1bf93c798a4f28ab86479d711645f6a69a716fa7d4cf3f0d5f390eb9283d2a0af9242e04363cc7d0137863ec4e5806cafaba4df122001b71404
-  data.tar.gz: 596f8d569c692586c246ab41a863aa2a803bfbb244eea42617f2a3f10783af8f4b0d15c79e82a214159dcd475a842a3133ad3b53cbb7825f070eb4a8db4a4562
+  metadata.gz: a23a99e55f8fbd985631f5e55f983f0f6bb8f7fa76f96b81c371bfade67f76628dbfa8e949e72a8eae87df7d9555d8259d6be7c9467e9a2ab67750d5118dbeb9
+  data.tar.gz: 107d8d93f7d3877f171b0bafc7b605e4bd49f251e1d6681d0fdc830701c9e574bd2b8fb2187eef120919b87ea83b66c9d2643acf76fe1a7c3cf361187d7ebb66

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    action_command (0.1.0)
+    action_command (0.1.1)
 
 GEM
   remote: https://rubygems.org/

data/README.md

@@ -25,7 +25,112 @@ Or install it yourself as:
 
 ## Usage
 
-TODO: Write usage instructions here
+`action_command` is designed to help you centralize logic which might otherwise end up in a controller or model, and easily invoke it from a controller, a test,
+or a rake command.  I read placing logic in 'actions' rather than models in the book [Rails 4 Test Prescriptions](http://www.amazon.com/Rails-Test-Prescriptions-Healthy-Codebase/dp/1941222196)
+and liked it.
+
+### HelloWorld
+
+You can declare an action with inputs and outputs
+
+```ruby
+class HelloWorldCommand < ActionCommand::Executable
+
+  # You need to declare an attr_accessor for each named parameter
+  attr_accessor :name
+
+  # You can optional describe the input and output of the command,
+  # the text is used to provide help if you create a rake version of the command.
+  def self.describe_io
+    # the text in here is only
+    return ActionCommand.describe_io(self, 'Say hello to someone') do |io|
+      io.input(:name, 'Name of person to say hello to')
+      io.output(:greeting, 'Greeting for the person')
+    end
+  end
+  
+  protected
+
+  # Override the execute internal method to provide logic for your action, and
+  # assign results to the result.   You can also use methods like result.fail or 
+  # result.info.
+  def execute_internal(result)
+    result[:greeting] = "Hello #{@name}" unless no_output
+  end
+end
+```
+
+#### HelloWorld: Execute from Rails
+
+You can execute it from rails:
+
+```ruby
+  result = ActionCommand.execute_rails(HelloWorldCommand, { name: 'Chris' })
+```
+
+#### HelloWorld: Execute from Rake
+
+When building a system, I find it useful to be able to easily run my actions from 
+the command-line as well.  In rails, you can create a lib/tasks/my_rake.task, and
+configure your actions as task with one line:
+
+```
+namespace :my_namespace do
+
+  # use [:initialize] as the last parameter if you want to do things that require
+  # rails startup in your command, like connecting to your database.
+  ActionCommand.install_rake(self, :hello_world, HelloWorldCommand, [])
+  
+end
+```
+
+You can always invoke your rake task with [help] to see help on the input and output
+of the action.
+
+#### HelloWorld: Execute from rspec/etc
+
+Or, you can execute it from a testing framework.  
+
+```ruby
+  it 'says hello world' do
+    result = ActionCommand.execute_test(self, HelloWorldCommand, name: 'Chris')
+    expect(result).to be_ok
+    expect(result[:greeting]).to eq('Hello Chris')
+  end
+```
+
+If your command does a lot, you might like to do some internal verifications during the testing process to aid
+debugging.   Inside a command's execute_internal method, you can use a block like this
+
+```ruby
+  def execute_internal(result)
+    # ... do some logic
+    
+    # t is the parameter you passed as the first argument to execute_test.  
+    # so, if you are using rspec, this code block will only be executed when you are 
+    # running in a testing context.
+    testing do |t|
+      t.expect(my_val).to t.eq(10)
+    end
+    
+  end
+
+### Child Actions
+
+Actions can execute their own child actions.  Within an action's execute_internal method
+you should call additional actions via:
+
+```ruby
+  def execute_internal
+    @names.each_with_index do |name, i|
+      # the i parameter will cause the result of the child command to be nested
+      # in the result under that value.  For example, here I would expect
+      # result[i][:greeting] to contain the greeting for each subcommand after
+      # execution.
+      ActionCommand.execute_child(self, HelloWorldCommand, result, i, name: name)
+    end
+  end
+```
 
 ## Development
 

data/Rakefile

@@ -4,6 +4,8 @@ require 'rubocop/rake_task'
 require 'yard'
 require 'rake_command_filter'
 
+load './spec/test_rake/helloworld.rake'
+
 RSpec::Core::RakeTask.new(:spec)
 RuboCop::RakeTask.new(:rubocop)
 YARD::Rake::YardocTask.new(:yard)