lev 4.0.0 → 4.1.0

checksums.yaml

@@ -0,0 +1,15 @@
+---
+!binary "U0hBMQ==":
+  metadata.gz: !binary |-
+    NmIyODE2NzY1ZTAwZjA4YzZmY2NmYzYyNzFiZmVmOGJhMWE4MzNkYw==
+  data.tar.gz: !binary |-
+    MWE4YzcxOWFkYmU2ZTQ5ZjllMDg0MWQ3NTdkZTVhNjZjYjFjZWUzMA==
+SHA512:
+  metadata.gz: !binary |-
+    ZTExN2U3Njg2MmM2OTQ0NTk0NDZmYjk2NDU4NmE1NjBmOTIwNDJlMzY3MGRk
+    MTc5NmRiMjJhNTljMjc3Yzg2OGE2NmU1Y2IwMDQ1ZDlkYTA4MjI4N2QzODA0
+    NzZlMGMyYWYzMzEyM2QyM2UyN2EzY2NlN2FjYjdlMjQyYWU0NjA=
+  data.tar.gz: !binary |-
+    MzA2YjM3ZTRiOWRlNzJiZWNjZDRhZWE5NWU1MjI5OGQ0OWZhMDdlZmJkNjFi
+    ZTE5YWRlNjljNDE4NTQ2ZWU3OTIzN2FhZTYyZGM2ODk0N2MyZjBkOGZhODRh
+    NzJhNTk5NDUyYjk3MGE0NGZkYTM0OGViNDA4MTA4MmNhNzhjYjM=

data/README.md

@@ -17,7 +17,7 @@ Lev introduces two main constructs to get around these issues: **Routines** and
 
 ## Routines
 
-Lev's Routines are pieces of code that have all the responsibility for making one thing (one use case) happen, e.g. "add an email to a user", "register a student to a class", etc), normally acting on objects from more than one model.  
+Lev's Routines are pieces of code that have all the responsibility for making one thing (one use case) happen, e.g. "add an email to a user", "register a student to a class", etc), normally acting on objects from more than one model.
 
 Routines...
 
@@ -30,12 +30,12 @@ In an OO/MVC world, an operation that involves multiple objects might be impleme
 Routines typically don't have any persistent state that is used over and over again; they are created, used, and forgotten.  A routine is a glorified function with a special single-responsibility purpose.
 
 A class becomes a routine by calling `lev_routine` in its definition, e.g.:
-  
+
     class MyRoutine
-      lev_routine  
+      lev_routine
       ...
 
-Other than that, all a routine has to do is implement an "exec" method (typically `protected`) that takes arbitrary arguments and that adds errors to an internal array-like "errors" object and outputs to a "outputs" hash.  Two convenience methods are provided for adding errors: 
+Other than that, all a routine has to do is implement an "exec" method (typically `protected`) that takes arbitrary arguments and that adds errors to an internal array-like "errors" object and outputs to a "outputs" hash.  Two convenience methods are provided for adding errors:
 
 Errors can be recorded in a number of ways.  You can manually add errors to the built-in `errors` object:
 
@@ -62,7 +62,7 @@ Here's an example setting an error and an output:
         outputs[:bar] = foo * 2
       end
     end
-  
+
 Additionally, see below for a discussion on how to transfer errors from ActiveRecord models.
 
 Any `StandardError` raised within a routine will be caught and transformed into a fatal error with `:kind` set to `:exception`.  The caller of this routine can choose to reraise this exception by calling `reraise_exception!` on the returned errors object:
@@ -79,13 +79,13 @@ By default `raise_exception_if_any!` will raise a `StandardError` with a message
 
 A routine will automatically get both class- and instance-level `call`
 methods that take the same arguments as the `exec` method.  The class-level
-call method simply instantiates a new instance of the routine and calls 
-the instance-level call method (side note here is that this means that 
+call method simply instantiates a new instance of the routine and calls
+the instance-level call method (side note here is that this means that
 routines aren't typically instantiated with state).
 
 When called, a routine returns a `Result` object, which is just a simple wrapper
-of the outputs and errors objects. 
-  
+of the outputs and errors objects.
+
     result = MyRoutine.call(42)
     puts result.outputs[:bar]    # => 84
 
@@ -93,71 +93,71 @@ of the outputs and errors objects.
 ### Nesting Routines
 
 As mentioned above, routines can call other routines.  While this is of course possible just by calling the other routine's call method directly, it is strongly recommended that one routine call another routine using the provided `run` method.  This method takes the name of the routine class and the arguments/block it expects in its call/exec methods.  By using the `run` method, the called routine will be hooked into the common error and transaction mechanisms.
-  
+
 When one routine is called within another using the `run` method, there is only one transaction used (barring any explicitly made in the code) and its isolation level is sufficiently strict for all routines involved.
-  
+
 It is highly recommend, though not required, to call the `uses_routine` method to let the routine know which subroutines will be called within it.  This will let a routine set its isolation level appropriately, and will enforce that only one transaction be used and that it be rolled back appropriately if any errors occur.
-  
+
 Once a routine has been registered with the `uses_routine` call, it can be run by passing run the routine's Class or a symbol identifying the routine.  This symbol can be set with the `:as` option.  If not set, the symbol will be automatically set by converting the routine class' full name to a symbol. e.g:
-  
+
     uses_routine CreateUser
                  as: :cu
-  
+
 and then you can call this routine with any of the following:
 
 * `run(:cu, ...)`
 * `run(:create_user, ...)`
 * `run(CreateUser, ...)`
 * `CreateUser.call(...)`  (not recommended)
-  
+
 #### Errors from Nested Routines
 
-`uses_routine` also provides a way to specify how errors relate to routine 
-inputs. Take the following example.  A `User` model calls `Routine1` which calls 
+`uses_routine` also provides a way to specify how errors relate to routine
+inputs. Take the following example.  A `User` model calls `Routine1` which calls
 `Routine2`.
-  
+
     User --> Routine1.call(foo: "abcd4") --> Routine2.call(bar: "abcd4")
-  
+
 An error occurs in `Routine2`, and Routine2 notes that the error is related
 to its `bar` input.  If that error and its metadata bubble up to the `User`,
 the `User` won't have any idea what `bar` relates to -- the `User` only knows
 about the interface to `Routine1` and the `foo` parameter it gave it.
-  
+
 `Routine1` knows that it will call `Routine2` and knows what its interface is.  It can then specify how to map terminology from `Routine2` into `Routine1`'s context.  E.g., in the following class:
-  
+
     class Routine1
       lev_routine
       uses_routine Routine2,
-                   translations: { 
+                   translations: {
                      inputs: { map: {bar: :foo} }
                    }
       def exec(options)
         run(Routine2, bar: options[:foo])
       end
     end
-  
+
 `Routine1` notes that any errors coming back from the call to `Routine2` related to `:bar` should be transfered into `Routine1`'s errors object as being related to `:foo`.  In this way, the caller of `Routine1` will see errors related to the arguments he understands.
 
 In addition to the `map:` configuration for input transferral, there are three other configurations:
 
-1. **Scoped** - Appends the provided scoping symbol (or symbol array) to the input symbol.  
-  
+1. **Scoped** - Appends the provided scoping symbol (or symbol array) to the input symbol.
+
     `{scope: SCOPING_SYMBOL_OR_SYMBOL_ARRAY}`
-  
+
     e.g. with `{scope: :register}` and a call to a routine that has an input
-    named `:first_name`, an error in that called routine related to its 
-    `:first_name` input will be translated so that the offending input is 
+    named `:first_name`, an error in that called routine related to its
+    `:first_name` input will be translated so that the offending input is
     `[:register, :first_name]`.
-  
+
 2. **Verbatim** - Uses the same term in the caller as the callee.
-  
+
      `{type: :verbatim}`
-  
+
 3. **Mapped** - Give an explicit, custom mapping:
-  
+
      `{map: {called_input1: caller_input1, called_input2: :caller_input2}}`
-  
-4. **Scoped and mapped** - Give an explicit mapping, and also scope the 
+
+4. **Scoped and mapped** - Give an explicit mapping, and also scope the
      translated terms.  Just use `scope:` and `map:` from above in the same hash.
 
 If an input translation is unspecified, the default is scoped, with `SCOPING_SYMBOL_OR_ARRAY` equal to the `as:` option passed to `uses_routine`, if provided, or if that is not provided then the symbolized name of the routine class.  E.g. for:
@@ -170,10 +170,10 @@ an errors generated on the `foo` input in `OtherRoutine` will be transferred up
 
 Via the `uses_routine` call, you can also ignore specified errors that occur
 in the called routine. e.g.:
-  
+
     uses_routine DestroyUser,
                  ignored_errors: [:cannot_destroy_non_temp_user]
-  
+
 ignores errors with the provided code.  The `ignore_errors` key must point
 to an array of code symbols or procs.  If a proc is given, the proc will
 be called with the error that the routine is trying to add.  If the proc
@@ -187,12 +187,12 @@ In addition to errors being transferred from subroutines to calling routines, a
     class Routine1
       lev_routine
       uses_routine Routine2,
-                   translations: { 
+                   translations: {
                      outputs: { type: :verbatim }
                    }
 
       def exec(options)
-        run(Routine2, bar: options[:foo])  
+        run(Routine2, bar: options[:foo])
         # Assuming Routine2 generates an output named "x", then outputs[:x] will be
         # available as of this line
       end
@@ -202,7 +202,7 @@ If the output translations are not specified, they will be scoped exactly like h
 
 
 Note if multiple outputs are transferred into the same named output (e.g. by calling the same routine over and over in a loop), an array of those outputs will be stored under that name.
-    
+
 #### Overriding `uses_routine` Options
 
 Any option passed to uses_routine can also be passed directly to the run
@@ -234,20 +234,20 @@ When errors are captured inside an `ActiveRecord` errors object, you can use `tr
 ### Specifying Transaction Isolations
 
 A routine is automatically run within a transaction.  The isolation level of the routine can be set by passing a `:transaction` option to the `lev_routine` call (or to the `lev_handler` call, if appropriate).  The value must be one of the following:
-  
+
 * `:no_transaction`
 * `:read_uncommitted`
 * `:read_committed`
 * `:repeatable_read`
 * `:serializable`
-  
+
 Note that by setting an isolation level, you are stating the minimum isolation level at which a routine must be run.  When routines are nested inside each other, the highest-specified isolation level from any one of them is used in the one transaction in which all of a routines' subroutines run.
 
 For example, if you write a routine that does a complex query, you might not need any transaction:
 
     class MyQueryRoutine
       lev_routine transaction: :no_transaction
-  
+
 If unspecified, the default isolation is `:repeatable_read`.
 
 ### delegate_to_routine
@@ -266,12 +266,112 @@ When `delegate_to_routine` is called, the provided method will call the routine
 
 will alias the old `destroy` method as `destroy_original` and add a new `destroy` method that calls the `DestroyProduct` routine.
 
+### Express Calling of Routines
+
+Routines commonly return one output.  These routines are often named things like `GetUserEmail` or `IsFinalized`.  Particularly
+for boolean queries like `IsBlahBlah`, it is onerous to say:
+
+```ruby
+if IsBlahBlah.call(arg1, arg2).outputs.some_output_containing_the_true_false_value
+```
+
+As a convenience, routines can be called "expressly" (as in compactly) using the bracket operator.  For example with the
+following routine:
+
+```ruby
+class AreArgumentsEqual
+  lev_routine
+
+  def exec(arg1, arg2)
+    outputs[:are_arguments_equal] = (arg1 == arg2)
+  end
+end
+```
+
+you could call it in the normal way:
+
+```ruby
+if AreArgumentsEqual.call(201, 202).outputs.are_arguments_equal
+  # do something
+end
+```
+
+or you can call it using brackets:
+
+```ruby
+if AreArgumentsEqual[201, 202]
+  # do something
+end
+```
+
+When using this bracket style of calling routines, Lev assumes that the value to be returned is named with the underscored
+version of the routine name, e.g. `AreArgumentsEqual` has a default return value of `are_arguments_equal`.  Module names
+are disregarded when computing the default name.
+
+The `express_output` can be overriden:
+
+```ruby
+class AreArgumentsEqual
+  lev_routine, express_output: :answer
+
+  def exec(arg1, arg2)
+    outputs[:answer] = (arg1 == arg2)
+  end
+end
+```
+
+When calling with the bracket operator, any errors accumulated by the routine are raised in an exception (have to do this
+since you have no other way to pay attention to the errors).
+
+### Delegates
+
+If you have
+
+```ruby
+class BarRoutine
+  lev_routine
+
+  def exec(alpha:, beta:)
+    # Do work
+  end
+end
+```
+
+you might have a reason to wrap this routine inside another, in which case you could write:
+
+```ruby
+class FooRoutine
+  lev_routine
+
+  uses_routine BarRoutine,
+               translations: {
+                 outputs: { type: :verbatim },
+                 inputs: { type: :verbatim }
+               }
+
+  def exec(alpha:, beta:)
+    run(BarRoutine, alpha: alpha, beta: beta)
+  end
+end
+```
+
+or if you use the `delegates_to:` shortcut, you can instead equivalently wrap `BarRoutine` with:
+
+```ruby
+class ShorterFooRoutine
+  lev_routine delegates_to: BarRoutine
+end
+```
+
+When using `delegates_to`, any `express_output` value set in the delegated routine is automatically
+used again by the delegating routine.
+
 ### Other Routine Methods
-  
+
 Routine class have access to a few other methods:
 
 1. a `runner` accessor which points to the routine which called it. If
-   runner is nil that means that no other routine called it (some other 
+   runner is nil that means that no other routine called it (some other
    code did)
 2. a `topmost_runner` accessor which points to the highest routine in the calling
    hierarchy (that routine whose 'runner' is nil)
@@ -289,7 +389,7 @@ Handlers...
 4. Map one-to-one with controller actions; by keeping the logic in each controller action encapsulated in a Handler, the code becomes independently-testable and also prevents the controller from being "fat" with 7 different actions all containing disparate logic touching different models.
 
 A class becomes a handler by calling `lev_handler` in its definition, e.g.:
-  
+
     class MyHandler
       lev_handler
       ...
@@ -310,10 +410,10 @@ Additionally, the handler provides attributes to return the `errors` object and
 
 The `handle` method that you define should not return anything; they just set values in the errors and results objects.  The documentation for each handler should explain what the results will be and any nonstandard data required to be passed in in the options.
 
-In addition to the class- and instance-level `call` methods provided by Lev::Routine, Handlers have a class-level `handle` method (an alias of the class-level `call` method).  The convention for handlers is that the `call` methods (and this class-level `handle` method) take a hash of options/inputs.  The instance-level `handle` method doesn't take any arguments since the arguments have been stored as instance variables by the time the instance-level handle method is called.  
-    
+In addition to the class- and instance-level `call` methods provided by Lev::Routine, Handlers have a class-level `handle` method (an alias of the class-level `call` method).  The convention for handlers is that the `call` methods (and this class-level `handle` method) take a hash of options/inputs.  The instance-level `handle` method doesn't take any arguments since the arguments have been stored as instance variables by the time the instance-level handle method is called.
+
   Example:
-  
+
     class MyHandler
       lev_handler
     protected
@@ -327,7 +427,7 @@ In addition to the class- and instance-level `call` methods provided by Lev::Rou
 
 ### paramify
 
-By declaring one or more `paramify` blocks in a handler, you can declare, group, cast, and validate parts of the `params` hash.  Think of `paramify` as a way to declare an ad-hoc `ActiveModel` class to wrap incoming parameters.  Normally, you only get easy validation of input parameters when those parameters are passed to an application model that is validated during a save.  `paramify` lets you do this for any arbitrary collection of incoming parameters without requiring those parameters to live in application models.  
+By declaring one or more `paramify` blocks in a handler, you can declare, group, cast, and validate parts of the `params` hash.  Think of `paramify` as a way to declare an ad-hoc `ActiveModel` class to wrap incoming parameters.  Normally, you only get easy validation of input parameters when those parameters are passed to an application model that is validated during a save.  `paramify` lets you do this for any arbitrary collection of incoming parameters without requiring those parameters to live in application models.
 
 The first argument to `paramify` is the key in params which points to a hash of params to be paramified.  If this first argument is unspecified (or specified as `:paramify`, a reserved symbol), the entire params hash will be paramified.  The block passed to paramify looks just like the guts of an ActiveAttr model.
 
@@ -338,13 +438,13 @@ For example, when the incoming params includes :search => {:type, :terms, :num_r
       validates :type, presence: true,
                        inclusion: { in: %w(Name Username Any),
                                     message: "is not valid" }
- 
+
       attribute :terms, type: String
       validates :terms, presence: true
- 
+
       attribute :num_results, type: Integer
       validates :num_results, numericality: { only_integer: true,
-                                              greater_than_or_equal_to: 0 }                               
+                                              greater_than_or_equal_to: 0 }
     end
 
 This will result in a `search_params` variable being available.  `search_params.num_results` would be guaranteed to be an integer greater than or equal to zero.  Note that if you want to use a "Boolean" type, you need to type it with a lowercase (`type: boolean`).
@@ -365,9 +465,9 @@ The following is a more complete example using the `paramify` block above:
 
         attribute :num_results, type: Integer
         validates :num_results, numericality: { only_integer: true,
-                                                greater_than_or_equal_to: 0 }                               
+                                                greater_than_or_equal_to: 0 }
       end
-      
+
       def handle
         # By this time, if there were any errors the handler would have
         # already populated the errors object and returned.
@@ -382,23 +482,23 @@ The following is a more complete example using the `paramify` block above:
 ### handle_with
 
 `handle_with` is a utility method for calling handlers from controllers.  To use it, call `include Lev::HandleWith` in your relevant controllers (or in your ApplicationController):
-  
+
     class ApplicationController
       include Lev::HandleWith
       ...
     end
-  
+
 Then, call `handle_with` from your various controller actions, e.g.:
-  
+
     handle_with(MyFormHandler,
                 params: params,
                 success: lambda { redirect_to 'show', notice: 'Success!'},
                 failure: lambda { render 'new', alert: 'Error' })
-  
+
 `handle_with` takes care of calling the handler and populates a `@handler_result` object with results and errors from running the handler.
-  
+
 The 'success' and 'failure' lambdas are called if there aren't or are errors, respectively.  Alternatively, if you supply a 'complete' lambda, that lambda will be called regardless of whether there are any errors.  Inside these lambdas (and inside the views they connect to), the @handler_outcome variable containing the errors and results from the handler will be available.
-  
+
 Specifying 'params' is optional.  If you don't specify it, `handle_with` will use the entire params hash from the request.
 
 Handlers help us clean up controllers in our Rails projects.  Instead of having a different piece of application logic in every controller action, a Lev-oriented app's controllers just end up being responsible for connecting routes to handlers, normally via a quick call to `handle_with`.
@@ -429,7 +529,7 @@ Consider the following example:
       <%= f.submit "Register", id: "register_submit" %>
     <% end %>
 
-Here, the form parameters will include 
+Here, the form parameters will include
 
     :register => {:username => 'bob79', :first_name => 'Bob', :password => 'password', :password_confirmation => 'password'}
 
@@ -507,17 +607,17 @@ When these guidelines are followed, model classes end up being very small and si
 
 ## Naming Conventions
 
-As mentioned above, a handler is intended to replace the logic in one controller action.  As such, one convention that works well is to name a handler based on the controller name and the action name, e.g. for the `ProductsController#show` action, we would have a handler named `ProductsShow`.  
+As mentioned above, a handler is intended to replace the logic in one controller action.  As such, one convention that works well is to name a handler based on the controller name and the action name, e.g. for the `ProductsController#show` action, we would have a handler named `ProductsShow`.
 
 Routines on the other hand are more or less glorified functions that work with multiple models to get something done, so we typically start their names with verbs, e.g. `CreateUser`, `SetPassword`, `ConfirmEmail`, etc.
 
 ## Differences between Lev and Rails' Concerns
 
-Both Lev and Concerns remove lines of code from models, but the major difference between the two is that with Concerns, the code still lives logically in the models whereas code in Lev is completely outside of and separate from the models.  
+Both Lev and Concerns remove lines of code from models, but the major difference between the two is that with Concerns, the code still lives logically in the models whereas code in Lev is completely outside of and separate from the models.
 
-Lev's routines (and handlers) know about models, but the models don't know anything about nor are they dependent on the code in routines*.  This makes the models simpler and more stable (a Good Thing).  
+Lev's routines (and handlers) know about models, but the models don't know anything about nor are they dependent on the code in routines*.  This makes the models simpler and more stable (a Good Thing).
 
-Since a Concern's code is essentially embedded in model code, if that Concern breaks it can potentially break other unrelated features, something that can't happen with routines.  
+Since a Concern's code is essentially embedded in model code, if that Concern breaks it can potentially break other unrelated features, something that can't happen with routines.
 
 Routines are especially good when some use case needs to query or change multiple models.  With a routine all of the logic for that use case is in one file.  With a concern, that code could be in multiple models and multiple concerns.
 

data/lib/lev.rb

@@ -27,12 +27,12 @@ require "lev/transaction_isolation"
 
 module Lev
   class << self
-    
+
     ###########################################################################
     #
     # Configuration machinery.
     #
-    # To configure Lev, put the following code in your applications 
+    # To configure Lev, put the following code in your applications
     # initialization logic (eg. in the config/initializers in a Rails app)
     #
     #   Lev.configure do |config|
@@ -40,7 +40,7 @@ module Lev
     #     ...
     #   end
     #
-    
+
     def configure
       yield configuration
     end
@@ -53,13 +53,15 @@ module Lev
       # This HTML class is added to form fields that caused errors
       attr_accessor :form_error_class
       attr_accessor :security_transgression_error
-      
-      def initialize      
+      attr_accessor :illegal_argument_error
+
+      def initialize
         @form_error_class = 'error'
         @security_transgression_error = Lev::SecurityTransgression
+        @illegal_argument_error = Lev::IllegalArgument
         super
       end
     end
-        
+
   end
 end

data/lib/lev/errors.rb

@@ -1,10 +1,10 @@
 module Lev
 
-  # A collection of Error objects.  
+  # A collection of Error objects.
   #
   class Errors < Array
 
-    def add(fail, args={}) 
+    def add(fail, args={})
       args[:kind] ||= :lev
       error = Error.new(args)
       return if ignored_error_procs.any?{|proc| proc.call(error)}
@@ -16,8 +16,8 @@ module Lev
       proc = arg.is_a?(Symbol) ?
                Proc.new{|error| error.code == arg} :
                arg
-      
-      raise IllegalArgument if !proc.respond_to?(:call)
+
+      raise Lev.configuration.illegal_argument_error if !proc.respond_to?(:call)
 
       ignored_error_procs.push(proc)
     end
@@ -31,6 +31,10 @@ module Lev
       self.any? {|error| [error.offending_inputs].flatten.include? input}
     end
 
+    def raise_exception_if_any!(exception_type = StandardError)
+      raise exception_type, collect{|error| error.message}.join('; ') if any?
+    end
+
   protected
 
     def ignored_error_procs
@@ -38,4 +42,4 @@ module Lev
     end
 
   end
-end
+end

data/lib/lev/exceptions.rb

@@ -1,4 +1,5 @@
 class Lev::IsolationMismatch < StandardError; end
 class Lev::SecurityTransgression < StandardError; end
 class Lev::AlgorithmError < StandardError; end
-class Lev::AbstractMethodCalled < StandardError; end
+class Lev::AbstractMethodCalled < StandardError; end
+class Lev::IllegalArgument < StandardError; end

data/lib/lev/object.rb

@@ -7,6 +7,20 @@ class Object
       # Routine configuration
       options[:transaction] ||= Lev::TransactionIsolation.mysql_default.symbol
       @transaction_isolation = Lev::TransactionIsolation.new(options[:transaction])
+
+      @delegates_to = options[:delegates_to]
+      if @delegates_to
+        uses_routine @delegates_to,
+                     translations: {
+                       outputs: { type: :verbatim },
+                       inputs: { type: :verbatim }
+                     }
+
+        @express_output ||= @delegates_to.express_output
+      end
+
+      # Set this after dealing with "delegates_to" in case it set a value
+      @express_output ||= options[:express_output] || self.name.demodulize.underscore
     end
   end
 
@@ -14,7 +28,7 @@ class Object
     class_eval do
       include Lev::Handler
     end
-    
+
     # Do routine configuration
     options[:skip_routine_include] = true
     lev_routine(options)
@@ -22,4 +36,4 @@ class Object
     # Do handler configuration (none currently)
   end
 
-end
+end

data/lib/lev/routine.rb

@@ -1,15 +1,15 @@
 module Lev
-  
+
   # A "routine" in the Lev world is a piece of code that is responsible for
   # doing one thing, normally acting on one or more other objects.  Routines
-  # are particularly useful when the thing that needs to be done involves 
+  # are particularly useful when the thing that needs to be done involves
   # making changes to multiple other objects.  In an OO/MVC world, an operation
   # that involves multiple objects might be implemented by spreading that logic
   # among those objects.  However, that leads to classes having more
   # responsibilities than they should (and more knowlege of other classes than
   # they should) as well as making the code hard to follow.
   #
-  # Routines typically don't have any persistent state that is used over and 
+  # Routines typically don't have any persistent state that is used over and
   # over again; they are created, used, and forgotten.  A routine is a glorified
   # function with a special single-responsibility purpose.
   #
@@ -22,19 +22,19 @@ module Lev
   #
   # in its definition.
   #
-  # Other than that, all a routine has to do is implement an "exec" method 
+  # Other than that, all a routine has to do is implement an "exec" method
   # that takes arbitrary arguments and that adds errors to an internal
   # array-like "errors" object and outputs to a "outputs" hash.
   #
   # A routine returns an "Result" object, which is just a simple wrapper
-  # of the outputs and errors objects. 
+  # of the outputs and errors objects.
   #
   # A routine will automatically get both class- and instance-level "call"
   # methods that take the same arguments as the "exec" method.  The class-level
-  # call method simply instantiates a new instance of the routine and calls 
-  # the instance-level call method (side note here is that this means that 
+  # call method simply instantiates a new instance of the routine and calls
+  # the instance-level call method (side note here is that this means that
   # routines aren't typically instantiated with state).
-  # 
+  #
   # A routine is automatically run within a transaction.  The isolation level
   # of the routine can be set by passing a :transaction option to the lev_routine
   # call (or to the lev_handler call, if appropriate).  The value must be one of
@@ -53,9 +53,9 @@ module Lev
   # As mentioned above, routines can call other routines.  While this is of
   # course possible just by calling the other routine's call method directly,
   # it is strongly recommended that one routine call another routine using the
-  # provided "run" method.  This method takes the name of the routine class 
+  # provided "run" method.  This method takes the name of the routine class
   # and the arguments/block it expects in its call/exec methods.  By using the
-  # run method, the called routine will be hooked into the common error and 
+  # run method, the called routine will be hooked into the common error and
   # transaction mechanisms.
   #
   # When one routine is called within another using the run method, there is
@@ -65,11 +65,11 @@ module Lev
   # It is highly recommend, though not required, to call the "uses_routine"
   # method to let the routine know which subroutines will be called within it.
   # This will let a routine set its isolation level appropriately, and will
-  # enforce that only one transaction be used and that it be rolled back 
+  # enforce that only one transaction be used and that it be rolled back
   # appropriately if any errors occur.
   #
   # Once a routine has been registered with the "uses_routine" call, it can
-  # be run by passing run the routine's Class or a symbol identifying the 
+  # be run by passing run the routine's Class or a symbol identifying the
   # routine.  This symbol can be set with the :as option.  If not set, the
   # symbol will be automatically set by converting the routine class' full
   # name to a symbol. e.g:
@@ -85,8 +85,8 @@ module Lev
   #
   #   run(:create_user, ...)
   #
-  # uses_routine also provides a way to specify how errors relate to routine 
-  # inputs. Take the following example.  A user calls Routine1 which calls 
+  # uses_routine also provides a way to specify how errors relate to routine
+  # inputs. Take the following example.  A user calls Routine1 which calls
   # Routine2.
   #
   #   User --> Routine1.call(foo: "abcd4") --> Routine2.call(bar: "abcd4")
@@ -96,14 +96,14 @@ module Lev
   # the User won't have any idea what "bar" relates to -- the User only knows
   # about the interface to Routine1 and the "foo" parameter it gave it.
   #
-  # Routine1 knows that it will call Routine2 and knows what its interface is.  
-  # It can then specify how to map terminology from Routine2 into Routine1's 
+  # Routine1 knows that it will call Routine2 and knows what its interface is.
+  # It can then specify how to map terminology from Routine2 into Routine1's
   # context.  E.g., in the following class:
   #
   #   class Routine1
   #     lev_routine
   #     uses_routine Routine2,
-  #                  translations: { 
+  #                  translations: {
   #                    inputs: { map: {bar: :foo} }
   #                  }
   #     def exec(options)
@@ -111,26 +111,26 @@ module Lev
   #     end
   #   end
   #
-  # Routine1 notes that any errors coming back from the call to Routine2 
+  # Routine1 notes that any errors coming back from the call to Routine2
   # related to :bar should be transfered into Routine1's errors object
   # as being related to :foo.  In this way, the caller of Routine1 will see
   # errors related to the arguments he understands.
   #
   # Translations can also be supplied for "outputs" in addition to "inputs".
-  # Output translations control how a called routine's Result outputs are 
+  # Output translations control how a called routine's Result outputs are
   # transfered to the calling routine's outputs.  Note if multiple outputs are
-  # transferred into the same named output, an array of those outputs will be 
-  # store.  The contents of the "inputs" and "outputs" hashes can be of the 
+  # transferred into the same named output, an array of those outputs will be
+  # store.  The contents of the "inputs" and "outputs" hashes can be of the
   # following form:
   #
   # 1) Scoped.  Appends the provided scoping symbol (or symbol array) to
-  #    the input symbol.  
+  #    the input symbol.
   #
   #    {scope: SCOPING_SYMBOL_OR_SYMBOL_ARRAY}
   #
   #    e.g. with {scope: :register} and a call to a routine that has an input
-  #    named :first_name, an error in that called routine related to its 
-  #    :first_name input will be translated so that the offending input is 
+  #    named :first_name, an error in that called routine related to its
+  #    :first_name input will be translated so that the offending input is
   #    [:register, :first_name].
   #
   # 2) Verbatim.  Uses the same term in the caller as the callee.
@@ -141,7 +141,7 @@ module Lev
   #
   #    {map: {called_input1: caller_input1, called_input2: :caller_input2}}
   #
-  # 4) Scoped and mapped.  Give an explicit mapping, and also scope the 
+  # 4) Scoped and mapped.  Give an explicit mapping, and also scope the
   #    translated terms.  Just use scope: and map: from above in the same hash.
   #
   # Via the uses_routine call, you can also ignore specified errors that occur
@@ -170,12 +170,12 @@ module Lev
   # Routine class have access to a few other methods:
   #
   #  1) a "runner" accessor which points to the routine which called it. If
-  #     runner is nil that means that no other routine called it (some other 
+  #     runner is nil that means that no other routine called it (some other
   #     code did)
-  # 
+  #
   #  2) a "topmost_runner" which points to the highest routine in the calling
   #     hierarchy (that routine whose 'runner' is nil)
-  #   
+  #
   # References:
   #   http://ducktypo.blogspot.com/2010/08/why-inheritance-sucks.html
   #
@@ -200,13 +200,19 @@ module Lev
         new.call(*args, &block)
       end
 
+      def [](*args, &block)
+        result = call(*args, &block)
+        result.errors.raise_exception_if_any!
+        result.outputs.send(@express_output)
+      end
+
       # Called at a routine's class level to foretell which other routines will
       # be used when this routine executes.  Helpful for figuring out ahead of
       # time what kind of transaction isolation level should be used.
       def uses_routine(routine_class, options={})
         symbol = options[:as] || class_to_symbol(routine_class)
 
-        raise IllegalArgument, "Routine #{routine_class} has already been registered" \
+        raise Lev.configuration.illegal_argument_error, "Routine #{routine_class} has already been registered" \
           if nested_routines[symbol]
 
         nested_routines[symbol] = {
@@ -221,6 +227,14 @@ module Lev
         @transaction_isolation ||= TransactionIsolation.mysql_default
       end
 
+      def express_output
+        @express_output
+      end
+
+      def delegates_to
+        @delegates_to
+      end
+
       def nested_routines
         @nested_routines ||= {}
       end
@@ -236,9 +250,13 @@ module Lev
       @after_transaction_blocks = []
 
       in_transaction do
-        catch :fatal_errors_encountered do   
+        catch :fatal_errors_encountered do
           begin
-            exec(*args, &block)
+            if self.class.delegates_to
+              run(self.class.delegates_to, *args, &block)
+            else
+              exec(*args, &block)
+            end
           end
         end
       end
@@ -261,7 +279,7 @@ module Lev
 
       if other_routine.is_a? Array
         if other_routine.size != 2
-          raise IllegalArgument, "when first arg to run is an array, it must have two arguments" 
+          raise Lev.configuration.illegal_argument_error, "when first arg to run is an array, it must have two arguments"
         end
 
         other_routine = other_routine[0]
@@ -273,16 +291,16 @@ module Lev
                  other_routine
                when Class
                  self.class.class_to_symbol(other_routine)
-               else 
+               else
                  self.class.class_to_symbol(other_routine.class)
                end
 
       nested_routine = self.class.nested_routines[symbol] || {}
 
       if nested_routine.empty? && other_routine == symbol
-        raise IllegalArgument, 
+        raise Lev.configuration.illegal_argument_error,
               "Routine symbol #{other_routine} does not point to a registered routine"
-      end      
+      end
 
       #
       # Get an instance of the routine and make sure it is a routine
@@ -291,8 +309,9 @@ module Lev
       other_routine = nested_routine[:routine_class] || other_routine
       other_routine = other_routine.new if other_routine.is_a? Class
 
-      raise IllegalArgument, "Can only run another nested routine" \
-        if !(other_routine.includes_module? Lev::Routine)
+      if !(other_routine.includes_module? Lev::Routine)
+        raise Lev.configuration.illegal_argument_error, "Can only run another nested routine"
+      end
 
       #
       # Merge passed-in options with those set in uses_routine, the former taking
@@ -308,10 +327,10 @@ module Lev
 
       options[:translations] ||= {}
 
-      input_mapper  = new_term_mapper(options[:translations][:inputs]) || 
+      input_mapper  = new_term_mapper(options[:translations][:inputs]) ||
                       new_term_mapper({ scope: symbol })
 
-      output_mapper = new_term_mapper(options[:translations][:outputs]) || 
+      output_mapper = new_term_mapper(options[:translations][:outputs]) ||
                       new_term_mapper({ scope: symbol })
 
       #
@@ -357,7 +376,7 @@ module Lev
       errors.add(false, args)
     end
 
-    # Utility method to transfer errors from a source to this routine.  The 
+    # Utility method to transfer errors from a source to this routine.  The
     # provided input_mapper maps the language of the errors in the source to
     # the language of this routine.  If fail_if_errors is true, this routine
     # will throw an error condition that causes execution of this routine to stop
@@ -399,33 +418,33 @@ module Lev
       @runner = runner
 
       if topmost_runner.class.transaction_isolation.weaker_than(self.class.transaction_isolation)
-        raise IsolationMismatch, 
-              "The routine being run has a stronger isolation requirement than " + 
+        raise IsolationMismatch,
+              "The routine being run has a stronger isolation requirement than " +
               "the isolation being used by the routine(s) running it; call the " +
               "'uses' method in the running routine's initializer"
       end
     end
 
-    def in_transaction(options={}) 
+    def in_transaction(options={})
       if transaction_run_by?(self)
         isolation_symbol = self.class.transaction_isolation.symbol
         if ActiveRecord::VERSION::MAJOR >= 4
           begin
-            ActiveRecord::Base.transaction(isolation: isolation_symbol) do 
+            ActiveRecord::Base.transaction(isolation: isolation_symbol) do
               yield
               raise ActiveRecord::Rollback if errors?
             end
           rescue ActiveRecord::TransactionIsolationError
             # Silently ignore isolation errors
-            ActiveRecord::Base.transaction do 
+            ActiveRecord::Base.transaction do
               yield
               raise ActiveRecord::Rollback if errors?
             end
           end
         else
           ActiveRecord::Base.isolation_level(isolation_symbol) do
-            ActiveRecord::Base.transaction do 
-              yield 
+            ActiveRecord::Base.transaction do
+              yield
               raise ActiveRecord::Rollback if errors?
             end
           end
@@ -443,7 +462,7 @@ module Lev
         when :verbatim
           return TermMapper.verbatim
         else
-          raise IllegalArgument, "unknown :type value: #{options[:type]}"
+          raise Lev.configuration.illegal_argument_error, "unknown :type value: #{options[:type]}"
         end
       end
 
@@ -455,4 +474,4 @@ module Lev
     end
 
   end
-end
+end

data/lib/lev/transaction_isolation.rb

@@ -2,7 +2,7 @@ module Lev
   class TransactionIsolation
 
     def initialize(symbol)
-      raise IllegalArgument, "Invalid isolation symbol" if !@@symbols_to_isolation_levels.has_key?(symbol)
+      raise Lev.configuration.illegal_argument_error, "Invalid isolation symbol" if !@@symbols_to_isolation_levels.has_key?(symbol)
       @symbol = symbol
     end
 
@@ -36,7 +36,7 @@ module Lev
     def eql?(other)
       self == other
     end
-    
+
     attr_reader :symbol
 
   protected
@@ -56,4 +56,4 @@ module Lev
     attr_writer :symbol
 
   end
-end
+end

data/lib/lev/utilities.rb

@@ -11,4 +11,16 @@ module Lev
     end
 
   end
-end
+end
+
+module Kernel
+  def eigenclass
+    class << self
+      self
+    end
+  end
+
+  def includes_module?(mod)
+    eigenclass.included_modules.include?(mod)
+  end
+end

data/lib/lev/version.rb

@@ -1,3 +1,3 @@
 module Lev
-  VERSION = "4.0.0"
+  VERSION = "4.1.0"
 end

data/spec/delegates_to_spec.rb

@@ -0,0 +1,15 @@
+require 'spec_helper'
+
+describe DelegatingRoutine do
+
+  it "should delegate" do
+    result = DelegatingRoutine.call(1,8)
+    expect(result.outputs[:answer]).to eq 9
+  end
+
+  it "should delegate with assumed express_output" do
+    result = DelegatingRoutine[1,8]
+    expect(result).to eq 9
+  end
+
+end

data/spec/support/delegated_routine.rb

@@ -0,0 +1,10 @@
+class DelegatedRoutine
+  lev_routine express_output: :answer
+
+  protected
+
+  def exec(alpha, beta)
+    outputs[:answer] = alpha + beta
+  end
+
+end

data/spec/support/delegating_routine.rb

@@ -0,0 +1,5 @@
+require_relative './delegated_routine'
+
+class DelegatingRoutine
+  lev_routine delegates_to: DelegatedRoutine
+end

metadata

@@ -1,20 +1,18 @@
 --- !ruby/object:Gem::Specification
 name: lev
 version: !ruby/object:Gem::Version
-  version: 4.0.0
-  prerelease: 
+  version: 4.1.0
 platform: ruby
 authors:
 - JP Slavinsky
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-03-03 00:00:00.000000000 Z
+date: 2015-04-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activemodel
   requirement: !ruby/object:Gem::Requirement
-    none: false
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
@@ -22,7 +20,6 @@ dependencies:
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
-    none: false
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
@@ -30,7 +27,6 @@ dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
   requirement: !ruby/object:Gem::Requirement
-    none: false
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
@@ -38,7 +34,6 @@ dependencies:
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
-    none: false
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
@@ -46,7 +41,6 @@ dependencies:
 - !ruby/object:Gem::Dependency
   name: actionpack
   requirement: !ruby/object:Gem::Requirement
-    none: false
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
@@ -54,7 +48,6 @@ dependencies:
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
-    none: false
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
@@ -62,7 +55,6 @@ dependencies:
 - !ruby/object:Gem::Dependency
   name: transaction_isolation
   requirement: !ruby/object:Gem::Requirement
-    none: false
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
@@ -70,7 +62,6 @@ dependencies:
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
-    none: false
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
@@ -78,7 +69,6 @@ dependencies:
 - !ruby/object:Gem::Dependency
   name: transaction_retry
   requirement: !ruby/object:Gem::Requirement
-    none: false
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
@@ -86,7 +76,6 @@ dependencies:
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
-    none: false
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
@@ -94,7 +83,6 @@ dependencies:
 - !ruby/object:Gem::Dependency
   name: active_attr
   requirement: !ruby/object:Gem::Requirement
-    none: false
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
@@ -102,7 +90,6 @@ dependencies:
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
-    none: false
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
@@ -110,7 +97,6 @@ dependencies:
 - !ruby/object:Gem::Dependency
   name: hashie
   requirement: !ruby/object:Gem::Requirement
-    none: false
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
@@ -118,7 +104,6 @@ dependencies:
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
-    none: false
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
@@ -126,7 +111,6 @@ dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
-    none: false
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
@@ -134,7 +118,6 @@ dependencies:
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
-    none: false
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
@@ -142,7 +125,6 @@ dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
-    none: false
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
@@ -150,7 +132,6 @@ dependencies:
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
-    none: false
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
@@ -158,7 +139,6 @@ dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
-    none: false
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
@@ -166,7 +146,6 @@ dependencies:
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
-    none: false
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
@@ -174,7 +153,6 @@ dependencies:
 - !ruby/object:Gem::Dependency
   name: sqlite3
   requirement: !ruby/object:Gem::Requirement
-    none: false
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
@@ -182,7 +160,6 @@ dependencies:
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
-    none: false
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
@@ -190,7 +167,6 @@ dependencies:
 - !ruby/object:Gem::Dependency
   name: debugger
   requirement: !ruby/object:Gem::Requirement
-    none: false
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
@@ -198,7 +174,6 @@ dependencies:
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
-    none: false
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
@@ -206,7 +181,6 @@ dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
   requirement: !ruby/object:Gem::Requirement
-    none: false
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
@@ -214,7 +188,6 @@ dependencies:
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
-    none: false
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
@@ -226,6 +199,10 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/lev.rb
 - lib/lev/better_active_model_errors.rb
 - lib/lev/delegate_to_routine.rb
 - lib/lev/error.rb
@@ -244,12 +221,9 @@ files:
 - lib/lev/transaction_isolation.rb
 - lib/lev/utilities.rb
 - lib/lev/version.rb
-- lib/lev.rb
-- LICENSE.txt
-- Rakefile
-- README.md
 - spec/create_sprocket_spec.rb
 - spec/deep_merge_spec.rb
+- spec/delegates_to_spec.rb
 - spec/errors_spec.rb
 - spec/outputs_spec.rb
 - spec/paramify_handler_spec.rb
@@ -258,6 +232,8 @@ files:
 - spec/sprocket_handler_spec.rb
 - spec/sprocket_spec.rb
 - spec/support/create_sprocket.rb
+- spec/support/delegated_routine.rb
+- spec/support/delegating_routine.rb
 - spec/support/paramify_handler_a.rb
 - spec/support/paramify_handler_b.rb
 - spec/support/sprocket.rb
@@ -265,37 +241,31 @@ files:
 homepage: http://github.com/lml/lev
 licenses:
 - MIT
+metadata: {}
 post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
-  none: false
   requirements:
   - - ! '>='
     - !ruby/object:Gem::Version
       version: '0'
-      segments:
-      - 0
-      hash: 2525822979360039563
 required_rubygems_version: !ruby/object:Gem::Requirement
-  none: false
   requirements:
   - - ! '>='
     - !ruby/object:Gem::Version
       version: '0'
-      segments:
-      - 0
-      hash: 2525822979360039563
 requirements: []
 rubyforge_project: 
-rubygems_version: 1.8.23.2
+rubygems_version: 2.4.6
 signing_key: 
-specification_version: 3
+specification_version: 4
 summary: Ride the rails but don't touch them.
 test_files:
 - spec/create_sprocket_spec.rb
 - spec/deep_merge_spec.rb
+- spec/delegates_to_spec.rb
 - spec/errors_spec.rb
 - spec/outputs_spec.rb
 - spec/paramify_handler_spec.rb
@@ -304,6 +274,8 @@ test_files:
 - spec/sprocket_handler_spec.rb
 - spec/sprocket_spec.rb
 - spec/support/create_sprocket.rb
+- spec/support/delegated_routine.rb
+- spec/support/delegating_routine.rb
 - spec/support/paramify_handler_a.rb
 - spec/support/paramify_handler_b.rb
 - spec/support/sprocket.rb