aye_commander 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: fa72a9da4e159367e9e08edd1a76360e61f105e7
+  data.tar.gz: 3c9cbe60d130049f9d6a16db3eadf6c8df609914
+SHA512:
+  metadata.gz: 17422f08ebb5442a8f43f9a00cd48439957d4ba194bc39440ded506f28d44f547a37dba268b0f568063e4b2b6d7cbb61481da8a6f5d104755a03635726318aa7
+  data.tar.gz: df4f7f0e63fa53bbf4e99d388253f20089b3f70cd311620e700641baea51a92317038a50837be04d62011e77ce45b1790678d1787e4f1f56c5163d0c1d884cc3

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2016 Juan Ramón
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.adoc

@@ -0,0 +1,720 @@
+// Asciidoctor Source
+// AyeCommander README
+//
+// Original author:
+// - pyzlnar
+//
+// Notes:
+// Compile with: $ asciidoctor README.adoc
+
+= AyeCommander
+[A small command gem]
+:toc:
+:showtitle:
+:source-highlighter: coderay
+
+image:https://travis-ci.org/pyzlnar/aye_commander.svg?branch=master["Build Status", link="https://travis-ci.org/pyzlnar/aye_commander"]
+image:https://codeclimate.com/github/pyzlnar/aye_commander/badges/gpa.svg["Code Climate", link="https://codeclimate.com/github/pyzlnar/aye_commander"]
+image:https://codeclimate.com/github/pyzlnar/aye_commander/badges/coverage.svg["Test Coverage", link="https://codeclimate.com/github/pyzlnar/aye_commander/coverage"]
+
+== Requirements
+
+- Ruby version >= 2.0
+
+== Installation
+
+To use AyeCommander add it to your Gemfile:
+
+[source,ruby]
+gem 'aye_commander'
+
+And bundle!
+
+[source,ruby]
+bundle install
+
+Or to use without bundler, install the gem:
+
+[source,ruby]
+gem install aye_commander
+
+And then require it from your code
+
+[source,ruby]
+require 'aye_commander'
+
+== Introduction
+
+AyeCommander is a gem that helps to develop classes that follow the command pattern.
+
+=== What is a Command?
+
+[quote, Russ Oslen]
+____
+A command is an object that does nothing but wait to be executed and, when executed, goes out and
+performs an application-specific task.
+____
+
+Simply put, a command is an object that does but one thing. So if only does one thing... why would
+you need to use them?
+
+=== When to use a Command
+
+Let's imagine that we have to do a complicated operation in a web application, like charging money.
+Just the charging alone might involved consuming one or more services to authorize and charge the
+card, save several records with information about the payments and so on and so forth.
+
+Writing all this code in a model is not exactly correct since it handles way more than just one
+model and using a controller would not only make a fat controller, but also harder to read.
+
+If we instead write all this logic in one (or more) commands, the code becomes not only easier to
+read and understand, but also easier to reuse on a different context.
+
+[source,ruby]
+----
+# Instead of letting the model handle more responsability than it should
+class Order
+  def create_order
+    charge_card
+    save_payment
+    update_order
+  end
+end
+
+# Or polluting the controller with more than just, "How to respond to the end user?"
+class OrdersController
+  def create
+    charge_card
+    save_payment
+    update_order
+    flash[:notice] = "Everything went well"
+  end
+end
+
+# Why not extract it all a command
+class CheckoutOrderCommand
+  include AyeCommander::Command
+  def call
+    charge_card
+    save_payment
+    update_order
+  end
+end
+
+# Or maybe even several commands
+class CheckoutOrderCommand
+  include AyeCommander::Commander
+  execute ChargeCardCommand, SavePaymentCommand, UpdateOrderCommand
+end
+----
+
+=== When to NOT use a Command
+
+As stated before a command is an object that does one thing. +
+This simple definition may make it tempting to write commands left and right, but never forget that
+you need to https://en.wikipedia.org/wiki/KISS_principle[KISS]. If what you're trying to do is
+simple it doesn't really need be extracted into a command.
+
+Ok, lets get cracking!
+
+== The Command
+
+Creating a command is really easy, you only need to do two things to get rocking:
+
+- Include the `AyeCommander::Command` module
+- Define a method named `call`
+
+[source,ruby]
+----
+class ObtainRandomCommand
+  include AyeCommander::Command
+
+  def call
+    @random = array.sample
+  end
+end
+----
+
+To use the command, you simply call it from somewhere else.
+
+[source,ruby]
+----
+result = ObtainRandomCommand.call(array: [1, 2, 3])
+=> #<ObtainRandomCommand::Result @status: success, @array: [1, 2, 3], @random: 3>
+
+result.random
+=> 3
+----
+
+It really doesn't get simpler than that, but there's actually more to a command than that, so lets
+have a look at the more complicated parts.
+
+== Limiting the arguments
+
+As you keep working with commands, you may realize that's actually a bit complicated to know what a
+command expects to receive as arguments, what's the minimum necessary it needs to work and which of
+all the variables returned in the result are actually relevant to you.
+
+=== Receiving Arguments
+
+AyeCommander comes with two ways of limiting the arguments that your command needs to be able to
+run: `requires` and `receives`.
+
+A `requires` tells the command that it can't run properly without having said arguments so it will
+in fact raise a `MissingRequiredArgumentError` if the command is called without said arguments.
+
+A `receives` tells the command that it can *ONLY* run the command with that set of arguments, and
+that receiving any extra is actually an error. In this case if a command receives any surplus, an
+error is raised.
+
+Arguments in `requires` are automatically added to `receives`, but no exception error is raised
+unless you actually use a `receives`.
+
+All validations can be skipped by sending the `:skip_validations` option when calling the command.
+
+=== Returning Arguments
+
+So now that your command ran, your result might end up with a bunch of variables that you may
+actually not even need. If that's the case then you can use the `returns` method which as you might
+imagine, cleans up the result by just returning the variables that you specified.
+
+=== Limiters Examples
+
+[source,ruby]
+----
+class SimpleCommand
+  include AyeCommander::Command
+end
+
+# At this point, our command will receive and return everything and anything.
+SimpleCommand.call(something: :or, other: :var)
+=> #<SimpleCommand::Result @status: success, @something: or, @other: var>
+
+class SimpleCommand
+  requires :these, :two
+end
+
+# Now calling the command without :these and :two will raise an error
+SimpleCommand.call
+=> AyeCommander::MissingRequiredArgumentError: Missing required arguments: [:these, :two]
+
+SimpleCommand.call(these: 1, two: 2)
+=> #<SimpleCommand::Result @status: success, @these: 1, @two: 2>
+
+# Adding any extras at this point is still ok!
+SimpleCommand.call(these: 1, two: 2, three: 3)
+=> #<SimpleCommand::Result @status: success, @these: 1, @two: 2, @three: 3>
+
+class SimpleCommand
+  receives :four
+end
+
+# Now that a receives has been used, any extra arguments sent will raise an error
+SimpleCommand.call(these: 1, two: 2, three: 3)
+=> AyeCommander::UnexpectedReceivedArgumentError: Received unexpected arguments: [:three]
+
+SimpleCommand.call(these: 1, two: 2, four: 4)
+=> #<SimpleCommand::Result @status: success, @these: 1, @two: 2, @four: 4>
+
+# Not sending something that is on the receives is ok as well!
+SimpleCommand.call(these: 1, two: 2)
+=> #<SimpleCommand::Result @status: success, @these: 1, @two: 2>
+
+class SimpleCommand
+  returns :sum
+
+  def call
+    @sum = these + two
+  end
+end
+
+# Finally a returns will help clean up the result at the end!
+SimpleCommand.call(these: 1, two: 2, four: 4)
+=> #<SimpleCommand::Result @status: success, @sum: 3>
+
+# At any point you can override the receives requires or returns.
+
+# Skips receives and requires
+SimpleCommand.call(skip_validations: true)
+
+# Skips either
+SimpleCommand.call(skip_validations: :receives)
+SimpleCommand.call(skip_validations: :requires)
+
+# Skips result cleanup
+SimpleCommand.call(skip_cleanup: true)
+----
+
+== What's in a status?
+
+As you may have noticed by now, every time a command is called a `status` is returned regardless
+of whether or not we cleanup. So what exactly is a status?
+
+Well, at its simplest form the status tells us the whether or not the command has succeeded. By
+default a command will be successful, and will fail if you change the status to *ANYTHING* that's
+not `:success`.
+
+[source,ruby]
+----
+class ReactorStatusCommand
+  include AyeCommander::Command
+
+  def call?
+    success? # => true
+    @status = :meltdown
+    success? # => false
+  end
+end
+
+ReactorStatusCommand.call.failure?
+=> true
+----
+
+As a side note you can use the `fail!` method to fail the command at any point.
+[source,ruby]
+----
+def call
+  # These lines are functionally identical
+  @status = :failure
+  fail!
+
+  # So are these
+  @status = :meltdown
+  fail!(:meltdown)
+end
+----
+
+NOTE: Failing a command *WILL NOT* stop the rest of the code from running. (More on that later)
+
+=== Multiple succeeds
+
+Up to this point the status may seem a bit bland... And you may be right!
+
+A status can tell you more than just a simple suceed and fail! It can tell you how it succeeded or
+how it failed. Doing this with failures is fairly easy, since anything that's not `:success` is
+considered a failure, but how do you we add more statuses as successes?
+
+[source,ruby]
+----
+class CreateUserTokenCommand
+  include AyeCommander::Command
+  succeeds_with :previously_created
+
+  def call
+    status # => :success
+    if user.token.present?
+      @status = :previously_created
+      success? # => true
+    else
+      user.create_random_token
+      fail!(:token_not_created) if user.token.blank?
+    end
+  end
+end
+----
+
+This contrived example hopefully helps you understand when multiple success status can be useful.
+In fact, you can actually even exclude success from the successful status. If you do, the status
+will be initialized as the first in your successful statuses.
+
+[source,ruby]
+----
+class ProcessCommand
+  include AyeCommander::Command
+  succeeds_with :started, :progress, :complete, exclude_success: true
+
+  def call
+    status # => :started
+    do_something
+    @status = :progress
+    do_something_else
+    @status = everything_ok? ? :complete : :failure
+  end
+end
+----
+
+== Abort!
+
+Now let's imagine that at point in time you want stop running the command. Not necessarily because
+something went wrong, but you don't need to do anything more for the time being. What can you do?
+
+Well the most obvious (and possibly more correct) answer is you can use `return` to exit out of the
+flow. However at times you may define other methods in a command you kinda wish to exit from them,
+something you can't do with a return.
+
+[source,ruby]
+----
+def call
+  do_something
+  # A return may work here
+  return if status == :cant_do_next
+end
+
+private
+
+def do_something
+  # But it doesn't work if you want to use it from here instead
+  return if status == :cant_do_next
+end
+----
+
+To solve this problem, command has a method named `#abort!`.
+Calling abort will stop the command on it's trails and will immediately return the result. It *WILL
+NOT* change the status so if you need change or fail the status, do it before aborting.
+
+[source,ruby]
+----
+class ProcessCommand
+  include AyeCommander::Command
+  succeeds_with :processed
+
+  def call
+    do_something
+    # These lines will never be called
+    do_something_else
+  end
+
+  private
+
+  def do_something
+    if true
+      @status = :processed
+      abort!
+    end
+  end
+
+  def do_something_else
+    @status = :something_else
+  end
+end
+
+ProcessCommand.call
+=> #<SimpleCommand::Result @status: processed>
+----
+
+== Getting Hooked
+
+A command also comes with your standard set of before, around and after hooks to tweak the command.
+Additionaly commands come bundled with a fourth kind of hook, the aborted hook.  The easiest way to
+understand them, it to see the order of execution of a command.
+
+[source,ruby]
+----
+# Rough representation of your typical call command
+def call
+  initialize_command
+  validate_args
+  before_hooks
+  around_hooks { call_command }
+  after_hooks
+  aborted_hooks if aborted
+  return_result
+end
+----
+
+Before going deeper into each kind of hook it's worth mentioning the behavior which all hooks share:
+
+- All hooks can be declared either using a block, a symbol, a proc or a lambda.
+- Multiple hooks of the same kind can be declared, they will always be run from the first one that
+  was declared to the last one.
+- If you need a hook to be run before some that have already been declared, you can use the
+  `prepend: true` option.
+- It might be obvious but worth noting that hooks are run in the command instance; as such you have
+  access to everything the command has.
+
+[source,ruby]
+----
+# Basic hook order
+before do
+  # I run first!
+  # If I wanted, I could abort the rest of the command from here!
+end
+
+before :my_hook
+
+lambda_from_somewhere_else = -> { "I run third!" }
+before lambda_from_somewhere_else
+
+private
+
+def my_hook
+  # I run second
+end
+----
+
+[source,ruby]
+----
+# More complicated hook behavior
+after :third do
+  # fourth
+end
+
+after :first, :second, prepend: true
+----
+
+IMPORTANT: Just because there's a lot of liberty with hook order it doesn't mean that its
+recommended to abuse it. Always try to keep the order of your hooks clear, and use `prepend` only
+if you *NEED* to.
+
+=== Before Hooks
+
+The most important thing to note of before hooks is that while indeed they're called before the
+command, they're also called *AFTER* the validations have run. This is important because it does
+mean that you if your command requires any arguments they can't be added through a before hook.
+
+While it was possible to make the before hooks run before the validations this decision was taken
+because `requires` and `receives` are meant to be *ARGUMENT* validators. This also means a couple of
+things:
+
+- Receives and requires become a way to tell the _users_ of your command how to use it properly
+- When a validator error is raised you always know it's because of the arguments you sent
+
+=== After Hooks
+
+After hooks are the easiest to understand. They run after your command was called, but before the
+result is created, so if you need to tweak your results a bit you can do it in here!
+
+=== Aborted Hooks
+
+As you might imagine, these hooks are only run if you abort the command. Why do we need them in the
+first place? Well as you may remember, calling `abort!` will stop the command on its tracks and
+return the result immediately. This means that if you call `abort!` during `call`, after_hooks
+*WILL NOT* run. For these cases, you might want to use an abort hook instead.
+
+=== Around Hooks
+
+Oh man, around hooks. It seems that every time I see an implementation of around hooks they work in
+a different way, so it's kinda hard to standarize them.
+
+Around hooks in a command are sadly no different, as they just try to make sense.
+
+First things first, when you use an around hook you must compromise to *ALWAYS* be able to receive
+an object and call it at some point in your method/block. If you don't, your command will never be
+called.
+
+Now, when there are multiple around hooks the first one will call the second one and so forth until
+the command is called. This means that before the `call` the code is run in the order the arounds
+were, but after the `call` it is run in the *REVERSE* order.
+
+Always keep this in mind.
+
+[source,ruby]
+----
+around do |next_step|
+  puts "First before call"
+  next_step.call
+  puts "First after call"
+end
+
+around do |next_step|
+  puts "Second before call"
+  next_step.call
+  puts "Second after call"
+end
+
+def call
+  puts "Command called"
+end
+
+# Would output:
+=> First before call
+=> Second before call
+=> Command called
+=> Second after call
+=> First after call
+----
+
+== Aye Aye Commander!
+
+I've been waiting this whole README to write that.
+
+A commander is actually a command which task is to run other commands. There are two ways to do this
+so lets start with the simpler one.
+
+=== Run and Done
+
+Similarly to the command, on its simplest form you only need to do two things to use a commander.
+
+- Include `AyeCommander::Commander`, not `AyeCommander::Command`
+- Use `execute` with the `Command` s you want to be runned.
+
+Calling the commander will run the commands one by one... and that's pretty much it.
+
+[source,ruby]
+----
+class Palpatine
+  include AyeCommander::Commander
+  execute HelpRepublic, Order66, BuildEmpire
+end
+
+Palpatine.call
+=> #<Palpatine::Result @status: success, @executed: [#<HelpRepublic @status: success>, #<Order66 @status: success>, #<BuildEmpire @status: success>]>
+----
+
+==== Commander Result
+
+As you may have noticed, the commander result not only includes a status, but also an array with
+the instances of the command that were run. Handy!
+
+The commander result will not only contain this set of variables; at the end it will take all the
+variables that were present on the last executed command. Which brings us to an important point:
+commands run by the commander *ALWAYS* skip both cleanup and receives validations (requires are
+still run).
+
+This is done so that the complete set of variable is sent to the next command to be run. If you want
+to cleanup the commander, you must declare its own set of returns.
+
+[source,ruby]
+----
+class BadgerCommand
+  include AyeCommander::Command
+  returns :badger
+end
+
+class TheCommander
+  include AyeCommander::Commander
+end
+
+# Notice how the command returns is ignored
+TheCommander.call(extra: :params)
+=> #<TheCommander::Result @status: success, @executed: [...], @extra: params>
+
+class TheCommander
+  returns :extra
+end
+
+# With returns defined, commander now cleans up the result
+TheCommander.call(extra: :params)
+=> #<TheCommander::Result @status: success, @extra: params>
+----
+
+==== Aborting and Failing
+
+So what happens when the command we're running aborts? Absolutely Nothing! Remember that we can
+abort! on success, so a commander doesn't really cares.
+
+On the other hand if the command we're running *fails* the commander itself will fail and abort.
+
+[source,ruby]
+----
+class Palpatine
+  include AyeCommander::Commander
+  execute HelpRepublic, Order66, BuildEmpire
+end
+
+# If Order66 were to fail
+Palpatine.call
+=> #<Palpatine::Result @status: failure, @executed: [#<HelpRepublic @status: success>, #<Order66 @status: jedi_escaped>]>
+----
+
+=== When we need more tweaking
+
+Now, while executing several commands in a row is nice, sometimes you need a bit more of control on
+when to run command A or B.
+
+Don't worry, AyeCommander has you covered!
+The only thing you need to do is define your own call method!
+
+[source,ruby]
+----
+class PickyCommander
+  include AyeCommander::Commander
+
+  def call
+    execute FirstCommand
+
+    if command.failure?
+      execute ThisCommand, ThatCommand
+    else
+      execute AnotherCommand
+    end
+  end
+end
+----
+
+There are a couple of things that we must notice here.
+
+First of all, the `command` instance variable. This variable will always have the last command that
+was executed. If no command has been run yet, it will have an anonymous command instance to which
+you can add extras for the following commands to run.
+
+[source,ruby]
+----
+before do
+  command.extra_arg = 'This extra arg'
+end
+
+after do
+  command.some_other = 'This' if command.that.blank?
+end
+
+def call
+  # Command instance will have extra_arg available
+  execute Command
+  # Commander Result will have some_other if that is blank after running Command
+end
+----
+
+IMPORTANT: The `command` variable is available for *BOTH* kinds of commanders, so you can use it to
+prepare and finalize your commander. This marks the biggest difference between a `Commander` and a
+`Command`. While everything in a command operates on it's own instance, a commander operates over
+the instance of the commands it executes.
+
+The second thing to notice is that as opposed to their simple counterpart, the commander *DOES NOT*
+abort nor fail when one of the commands you run fails. This is done so you can tweak the behavior
+of the commander to your necessities, however recognizing that it is quite likely that you want
+that behaviour for your commander there are ways to reenable it.
+
+[source,ruby]
+----
+class UndecisiveCommander
+  include AyeCommander::Commander
+
+  # Using this will re-enable failing on all commands
+  abort_on_failure
+
+  def call
+    # But even with that option, you override it at an instance level
+
+    # Will always abort on failure
+    execute ThisCommand, abort_on_failure: true
+
+    # Will never abort on failure
+    execute ThatCommand, OtherCommand, abort_on_failure: false
+  end
+end
+----
+
+== Top tips and tricks
+
+- Never forget when and when not to use a command
+
+- Have naming conventions +
+I really suggest that for commands (and commanders), you finish their names with `Command`. This
+clears up what they are and maybe what they do just by looking at the name.
+
+- Use private methods to know what your command does at first glance +
+
+[source,ruby]
+----
+class UpdateExchangeRatesCommand
+  include AyeCommander::Command
+
+  def call
+    fetch_todays_exchange_rates
+    save_exchange_rates
+  end
+end
+----
+
+- But if the logic is too complicated, split it into more commands
+
+[source,ruby]
+----
+class UpdateExchangeRatesCommand
+  include AyeCommander::Commander
+  execute FetchExchangeRatesCommand, SaveExchangeRates
+end
+----
+
+- Write code, have fun!