playhouse 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 7ee92d35c5cc99200df7de30aa77d0936c7a6b6f
+  data.tar.gz: 1bf5df285920713b73c523645869286351ee6440
+SHA512:
+  metadata.gz: e17951ca5e9cbdc74c41b2a9d1a663943c7b92aa9c8d9e7c2614762d69576156c3e8dbbca453de3015a3a48ac6e120c9b64e0eb719239d7af976c586cb15a15c
+  data.tar.gz: 9b907d2714c1462d8210fb1c3e07d712fffbd212b5961389020c91264b2e2a8bd5aadcdd79b5727c837377b79aa1128b0d6eb938079c1a7bdcd91df942e3cd4c

data/.gitignore

@@ -0,0 +1 @@
+.idea

data/.ruby-version

@@ -0,0 +1 @@
+ruby-2.0.0-p195

data/.travis.yml

@@ -0,0 +1,10 @@
+rvm:
+  - "2.0.0"
+script: "rake ci"
+before_script: "rake setup_ci"
+notifications:
+  hipchat:
+    rooms:
+      - 3d318fc3e1f401238a50171784b534@Craftworks General
+    template: '%{repository}#%{build_number} (%{branch} - %{commit} : %{author}): %{message} (<a href="%{build_url}">Details</a>/<a href="%{compare_url}">Change view</a>)'
+    format: html

data/CHANGELOG.md

@@ -0,0 +1,3 @@
+# 0.1.1 - Feb 25
+
+Adding the ability for contexts to inherit actors from a parent context. All methods on a play have a new [context]_with_parent method and the talent scout is now parent aware.

data/Gemfile

@@ -0,0 +1,6 @@
+source "http://rubygems.org"
+
+gem 'rake'
+gem 'playhouse', path: '.'
+gem 'rspec', '2.14.1'
+gem 'coveralls'

data/Gemfile.lock

@@ -0,0 +1,69 @@
+PATH
+  remote: .
+  specs:
+    playhouse (0.1.1)
+      activerecord
+      activesupport
+      rake
+
+GEM
+  remote: http://rubygems.org/
+  specs:
+    activemodel (4.0.2)
+      activesupport (= 4.0.2)
+      builder (~> 3.1.0)
+    activerecord (4.0.2)
+      activemodel (= 4.0.2)
+      activerecord-deprecated_finders (~> 1.0.2)
+      activesupport (= 4.0.2)
+      arel (~> 4.0.0)
+    activerecord-deprecated_finders (1.0.3)
+    activesupport (4.0.2)
+      i18n (~> 0.6, >= 0.6.4)
+      minitest (~> 4.2)
+      multi_json (~> 1.3)
+      thread_safe (~> 0.1)
+      tzinfo (~> 0.3.37)
+    arel (4.0.1)
+    atomic (1.1.14)
+    builder (3.1.4)
+    colorize (0.5.8)
+    coveralls (0.6.3)
+      colorize
+      multi_json (~> 1.3)
+      rest-client
+      simplecov (>= 0.7)
+      thor
+    diff-lcs (1.2.5)
+    i18n (0.6.9)
+    mime-types (1.21)
+    minitest (4.7.5)
+    multi_json (1.7.3)
+    rake (10.0.4)
+    rest-client (1.6.7)
+      mime-types (>= 1.16)
+    rspec (2.14.1)
+      rspec-core (~> 2.14.0)
+      rspec-expectations (~> 2.14.0)
+      rspec-mocks (~> 2.14.0)
+    rspec-core (2.14.7)
+    rspec-expectations (2.14.4)
+      diff-lcs (>= 1.1.3, < 2.0)
+    rspec-mocks (2.14.4)
+    simplecov (0.7.1)
+      multi_json (~> 1.0)
+      simplecov-html (~> 0.7.1)
+    simplecov-html (0.7.1)
+    thor (0.18.0)
+    thread_safe (0.1.3)
+      atomic
+    tzinfo (0.3.38)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  coveralls
+  playhouse!
+  rake
+  rspec (= 2.14.1)

data/README.md

@@ -0,0 +1,207 @@
+#Playhouse
+
+A framework for structing a ruby application using the DCI (Data, Context and Interaction)
+pattern. Playhouse makes no assumptions about whether it's a web app (or any other sort),
+it just helps you to structure your application logic. Playhouse is not used to structure
+presentation logic, it is typically connected to some sort of delivery layer.
+
+[![Code Climate](https://codeclimate.com/github/enspiral/playhouse.png)](https://codeclimate.com/github/enspiral/playhouse)
+[![Build Status](https://travis-ci.org/enspiral/playhouse.png)](https://travis-ci.org/enspiral/playhouse)
+[![Coverage Status](https://coveralls.io/repos/enspiral/playhouse/badge.png?branch=master)](https://coveralls.io/r/enspiral/playhouse)
+
+##Status
+
+Playhouse is not yet at version 1.0.
+
+It is being used for its first production apps now, but its interface may change rapidly and
+at any point, so doing so is not advised unless you are actively involved in Playhouse
+development.
+
+##Installation
+
+```ruby
+  gem 'playhouse', git: 'git://github.com/enspiral/playhouse.git'
+```
+
+You may wish to organise your app such that the three main parts of the DCI pattern have their
+own folders. We are currently using:
+
+```
+  lib/entities
+  lib/roles
+  lib/context
+```
+
+##Getting Started
+
+There are three main parts of a Playhouse app, Entities, Roles and Contexts. Additionally,
+there is some overall structure that makes it easy to create an entry point to the
+application logic.
+
+###Entities
+
+Entities are the "Data" part of DCI. They represent your Domain models that you probably
+want to persist to a data store of some sort. To avoid the sort of complexity that often
+occurs in models in Rails apps, Playhouse entities should have no functionality other than
+defining their data structure and connecting to the persistance layer.
+
+Playhouse does not care what persistance library you use. ActiveRecord works fine, just add
+the gem to your app and start using it. We recommend you don't use validations (Contexts do
+validations in Playhouse), keep relationships to necessary ones only, and don't use scopes
+(queries go in Roles).
+
+Playhouse actually has no Entity class. This is just a concept that you need to create yourself.
+
+Entities are often used as Actors by Contexts. Actors can also be other basic types (or indeed
+any object).
+
+### Roles
+
+Roles are modules that are mixed into to Actors at runtime. Specifically note that they are
+used to extend objects, not classes. If you're not familiar with this, go read up on DCI.
+
+Playhouse defines a Role module to provide this behaviour, although it is implemented just
+using Ruby's `extend` method. A role in your Playhouse app looks as follows:
+
+```ruby
+require 'playhouse/role'
+
+module YourApp
+  module TransferSource
+    include Playhouse::Role
+
+    actor_dependency :minimum_balance
+    actor_dependency :bank
+
+    def some_method
+      # do something
+    end
+  end
+end
+```
+
+Using a role is as simple as:
+
+```ruby
+TransferSource.cast_actor(my_account)
+```
+
+Although Contexts will do this for you automatically. Specifying actor dependencies on your
+role is a good way of documenting the duck type that the role expects to extend. When you
+call cast_actor, then it will raise an exception if the actor you supply does not support
+the methods specified (minimum_balance and bank in the above example).
+
+###Contexts
+
+Each of your contexts is a command that your app performs, which you could also think of as
+a use case. In essence, a context is supplied with Actors, "casts" them in various Roles and
+then executes some behaviour. In keeping with conventions of most people using DCI in ruby,
+executing a context is done by calling its `call` method.
+
+Playhouse provides a base Context class for you to derive from. Rather than implementing
+`call` directly though, please override our `perform` method so that we can perform some
+checks before your code executes. Here's an example.
+
+```ruby
+require 'playhouse/context'
+require 'economatic/roles/account_transaction_collection'
+require 'economatic/entities/account'
+
+module Economatic
+  class AccountBalanceEnquiry < Playhouse::Context
+    actor :account, role: AccountTransactionCollection, repository: Account
+
+    def perform
+      account.balance
+    end
+  end
+end
+```
+This Balance enquiry context is fairly simple. Your context perform method might have more
+lines than this, and it might be good if it lists the main high level steps for
+performing this feature. However, the serious application logic goes into your roles.
+
+To calculate a balance, this context just needs one actor, an account, and it casts it
+as a role (AccountTransactionCollection) which actually knows how to calculate a balance
+by summing transactions. Actors are all required by default (unless you specify the
+`optional: true` option), and so building this context without an account will raise an
+exception. Specifying the Account repository can be used to find accounts, allows other
+parts of Playhouse to build this Context by asking Account to fetch an account given an
+id. Remember as well that the AccountTransactionCollection role will check that the account
+has the methods it is dependent on.
+
+The return value from your context is returned to the code calling your application
+(which is often your delivery layer or another application), and we suggest that this
+should be a fairly dumb object. Context should return data, you shouldn't use their return value
+in ways that transform it, save data, etc.
+
+##An Interface to Your Application
+
+The external interface of your application is essentially the Contexts that are available
+to be called, although some Contexts might be just for calling from other Contexts. To
+organise these a bit to present to the outside world, you can group these into an API
+object which Playhouse calls a Play.
+
+```ruby
+require 'playhouse/play'
+
+module Economatic
+  class Play < Playhouse::Play
+    context AccountBalanceEnquiry
+    context ApproveTransfer
+    context BankBalanceEnquiry
+    context TransferMoney
+  end
+end
+```
+
+Contexts can be called via the play just as methods:
+
+```ruby
+play = Economatic::Play.new
+play.account_balance_enquiry(account: some_account_object)
+```
+
+If you call a context this way, we also use our TalentScout to process the parameters you
+supply and find actors if given ids, or build actors that are composed of several parts,
+for example, this will work if calling via the play (but wouldn't work if you construct
+the Context manually):
+
+```ruby
+play.account_balance_enquiry(account_id: 1)
+```
+
+The other advantage of a Play is that you can ask it about the context that it supports,
+and the parts available for Actors in that context. This allows you to present structured
+information about your API, such as auto-generating documentation.
+
+###A Delivery Layer
+
+While you can call methods on a Play directly, often this will be done from some user input
+of some sort. This layer knows about how you are delivering your app (as a JSON web service,
+a console app, a GUI app, etc), and it knows about your application somewhat (often by
+interrogating your Plays). However, your core application should never know about your
+delivery layer(s). Even if you're expecting to build a web app, don't put web concepts
+into your app, make it generic.
+
+Playhouse doesn't do delivery layers for you, but it provides a known structure to allow
+other gems to help you out with this. We suggest you first try out our playhouse-console
+gem which provides you with a simple console app with one command for each Context.
+
+For a web app, it's quite possible to use Sinatra or Rails as your delivery layer.
+
+##Licence
+
+Playhouse is licenced under the MIT licence. Copyright 2013 Enspiral Services Ltd.
+
+##Contributing
+
+Your contributions are welcome. Send us a pull request, or start a discussion in the github
+issues first.
+
+##Credits
+
+From Enspiral Craftworks:
+
+* Craig Ambrose (@craigambrose)
+* Joshua Vial (@joshuavial)

data/Rakefile

@@ -0,0 +1,16 @@
+require 'rspec/core/rake_task'
+
+desc "Run specs"
+RSpec::Core::RakeTask.new do |t|
+end
+
+desc "Setup this library to perform ci task"
+task :setup_ci do
+  puts "nothing to setup"
+end
+
+desc "Test this console interface"
+task :ci => [:spec] do
+end
+
+task default: :ci

data/lib/playhouse/context.rb

@@ -0,0 +1,120 @@
+require 'active_support/core_ext/string/inflections'
+require 'playhouse/part'
+require 'playhouse/validation/actors_validator'
+
+module Playhouse
+  class Context
+    class << self
+
+      def parts
+        @actor_definitions ||= []
+      end
+
+      def actor(name, options = {})
+        raise InvalidActorKeyError.new(self.class.name, name) unless name.is_a?(Symbol)
+
+        parts << Part.new(name, options)
+
+        define_method name do
+          @actors[name]
+        end
+      end
+
+      def part_for(name)
+        raise InvalidActorKeyError.new(self.class.name, name) unless name.is_a?(Symbol)
+        parts.detect {|definition| definition.name == name}
+      end
+
+      def method_name
+        context_name_parts.join('').underscore.to_sym
+      end
+
+      def http_method(method=:post)
+        @http_methods ||= []
+        if method.is_a?(Array)
+          @http_methods.concat method
+        else
+          @http_methods << method
+        end
+      end
+
+      def http_methods
+        return [:get] if @http_methods.nil?
+        @http_methods.uniq
+      end
+
+      private
+
+      def context_name_parts
+        name.split('::')[1..-1].reverse
+      end
+    end
+
+    def initialize(actors = {})
+      store_expected_actors(actors)
+    end
+
+    def inherit_actors_from(parent)
+      parent.send(:actors).each do |name, actor|
+        if actors[name].nil? && self.class.part_for(name)
+          store_actor name, actor
+        end
+      end
+    end
+
+    def call
+      validate_actors
+      cast_actors
+      perform
+    end
+
+    def perform
+      raise NotImplementedError.new("Context #{self.class.name} needs to override the perform method")
+    end
+
+    protected
+
+      def validator
+        ActorsValidator.new
+      end
+
+    private
+
+      def validate_actors
+        validator.validate_actors(self.class.parts, @actors)
+      end
+
+      def store_expected_actors(actors)
+        @actors = {}
+        actors.each do |name, actor|
+          store_actor name, actor
+        end
+      end
+
+      def store_actor(name, actor)
+        part = self.class.part_for(name)
+        if part
+          @actors[name] = actor
+        else
+          raise UnknownActorKeyError.new(self.class.name, name)
+        end
+      end
+
+      def cast_actors
+        @actors.each do |name, actor|
+          part = self.class.part_for(name)
+          @actors[name] = part.cast(actor)
+        end
+      end
+
+      def actors
+        @actors
+      end
+
+      def actors_except(*exceptions)
+        actors.reject do |key, value|
+          exceptions.include?(key)
+        end
+      end
+  end
+end