brassbound-dci 0.5.0

data/.gitignore

@@ -0,0 +1,4 @@
+*.gem
+.bundle
+Gemfile.lock
+pkg/*

data/Gemfile

@@ -0,0 +1,4 @@
+source "http://rubygems.org"
+
+# Specify your gem's dependencies in brassbound-dci.gemspec
+gemspec

data/README.rdoc

@@ -0,0 +1,78 @@
+= Brassbound
+
+Brassbound is a simple but strict implementation of the Data, Context, and Interaction (DCI) paradigm for Ruby.
+
+= Example
+
+The canonical DCI example is the transfer of funds between a money source
+and money sink. In this example, source and sink are both roles
+that are attached to data objects, and the transfer of funds is orchestrated
+by the context. Here's how the example looks using Brassbound.
+
+  require 'brassbound'
+
+  # Domain/data objects are plain old Ruby objects.
+  class Account
+    # Pretend to lookup accounts in a database.
+    def self.find(account_id)
+      case account_id
+      when 1
+        Account.new(account_id, 2000)
+      when 2
+        Account.new(account_id, 1000)
+      end
+    end
+
+    attr_reader   :id
+    attr_accessor :balance
+
+    def initialize(id, balance)
+      @id = id
+      @balance = balance
+    end
+  end
+
+  # Roles are plain old Ruby modules, and automatically have access to
+  # the invoking context.
+  module MoneySource
+    def transfer_out(amount)
+      puts("Transferring #{amount} from account #{self.id} to account #{context.money_sink.id}")
+      self.balance -= amount
+      puts("Source account new balance: #{self.balance}")
+      context.money_sink.transfer_in(amount)
+    end
+  end
+
+  module MoneySink
+    def transfer_in(amount)
+      self.balance += amount
+      puts("Destination account new balance: #{self.balance}")
+    end
+  end
+
+  # Contexts are Ruby classes that include the Brassbound::Context module.
+  # The common idiom is for the initialize method to create all of the
+  # necessary objects and declare how they are bound to roles.
+  # Then, within the scope of the execute method, the objects will have been
+  # bound to the declared roles, and can be accessed by the role name
+  # (convert to lower case with underscores by default).
+  class TransferFunds
+    include Brassbound::Context
+
+    def initialize(source_account_id, dest_account_id, amount)
+      @amount = amount
+
+      role MoneySource, Account.find(source_account_id)
+      role MoneySink, Account.find(dest_account_id)
+    end
+
+    def execute
+      # Here, money_source refers to the object bound to the MoneySource role
+      # in the initialize method.
+      money_source.transfer_out(@amount)
+    end
+  end
+
+  # Now let's create and execute our context.
+  TransferFunds.new(1, 2, 100).call
+

data/Rakefile

@@ -0,0 +1 @@
+require 'bundler/gem_tasks'

data/brassbound-dci.gemspec

@@ -0,0 +1,22 @@
+# -*- encoding: utf-8 -*-
+
+$:.push File.expand_path("../lib", __FILE__)
+require 'brassbound/version'
+require 'rake'
+
+Gem::Specification.new do |s|
+  s.name        = "brassbound-dci"
+  s.version     = Brassbound::VERSION
+  s.authors     = ["Jason Voegele"]
+  s.email       = ["jason@jvoegele.com"]
+  s.homepage    = ""
+  s.summary     = "Simple but strict DCI framework"
+  s.description = "Brassbound is a simple but strict implementation of the Data, Context, and Interaction (DCI) paradigm for Ruby."
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+
+  s.add_development_dependency 'rspec', '~> 2.10.0'
+end

data/examples/money_transfer.rb

@@ -0,0 +1,67 @@
+require 'brassbound'
+
+# Domain/data objects are plain old Ruby objects.
+class Account
+  # Pretend to lookup accounts in a database.
+  def self.find(account_id)
+    case account_id
+    when 1
+      Account.new(account_id, 2000)
+    when 2
+      Account.new(account_id, 1000)
+    end
+  end
+
+  attr_reader   :id
+  attr_accessor :balance
+
+  def initialize(id, balance)
+    @id = id
+    @balance = balance
+  end
+end
+
+# Roles are plain old Ruby modules, and automatically have access to
+# the invoking context.
+module MoneySource
+  def transfer_out(amount)
+    puts("Transferring #{amount} from account #{self.id} to account #{context.money_sink.id}")
+    self.balance -= amount
+    puts("Source account new balance: #{self.balance}")
+    context.money_sink.transfer_in(amount)
+  end
+end
+
+module MoneySink
+  def transfer_in(amount)
+    self.balance += amount
+    puts("Destination account new balance: #{self.balance}")
+  end
+end
+
+# Contexts are Ruby classes that include the Brassbound::Context module.
+# The common idiom is for the initialize method to create all of the
+# necessary objects and declare how they are bound to roles.
+# Then, within the scope of the execute method, the objects will have been
+# bound to the declared roles, and can be accessed by the role name
+# (convert to lower case with underscores by default).
+class TransferFunds
+  include Brassbound::Context
+
+  def initialize(source_account_id, dest_account_id, amount)
+    @amount = amount
+
+    role MoneySource, Account.find(source_account_id)
+    role MoneySink, Account.find(dest_account_id)
+  end
+
+  def execute
+    # Here, money_source refers to the object bound to the MoneySource role
+    # in the initialize method.
+    money_source.transfer_out(@amount)
+  end
+end
+
+# Now let's create and execute our context.
+TransferFunds.new(1, 2, 100).call
+

data/examples/wedding.rb

@@ -0,0 +1,52 @@
+require 'brassbound'
+
+class Person
+  attr_accessor :first_name, :last_name
+
+  def initialize(first_name, last_name)
+    @first_name = first_name
+    @last_name = last_name
+  end
+end
+
+module WifeToBe
+  def marry(husband)
+    self.last_name = husband.last_name
+  end
+end
+
+module HusbandToBe
+  def marry(wife)
+  end
+end
+
+module Minister
+  def administer_marraige
+    context.husband.marry(context.wife)
+    context.wife.marry(context.husband)
+    puts("I, #{first_name} #{last_name}, now pronounce you Mr. and Mrs. #{context.wife.last_name}")
+  end
+end
+
+# In a traditional wedding, a man and a woman are married by a minister.
+class TraditionalWedding
+  include Brassbound::Context
+
+  def initialize(man_first_name, man_last_name,
+                 woman_first_name, woman_last_name)
+    @man = Person.new(man_first_name, man_last_name)
+    @woman = Person.new(woman_first_name, woman_last_name)
+    @mark = Person.new('Mark', 'Schlafman')
+
+    role :husband, HusbandToBe, @man
+    role :wife, WifeToBe, @woman
+    role Minister, @mark
+  end
+
+  def execute
+    minister.administer_marraige
+  end
+end
+
+TraditionalWedding.new('Jason', 'Voegele', 'Jennifer', 'Bollinger').call
+

data/lib/brassbound/context.rb

@@ -0,0 +1,163 @@
+# This module represents the notion of the Context in the DCI paradigm.
+#
+# According to http://en.wikipedia.org/wiki/Data,_context_and_interaction
+#
+#   The Context is the class (or its instance) whose code includes the roles
+#   for a given algorithm, scenario, or use case, as well as the code to map
+#   these roles into objects at run time and to enact the use case. Each role
+#   is bound to exactly one object during any given use case enactment; however,
+#   a single object may simultaneously play several roles. A context is
+#   instantiated at the beginning of the enactment of an algorithm, scenario,
+#   or use case. In summary, a Context comprises use cases and algorithms in
+#   which data objects are used through specific Roles.
+#
+# In Brassbound, context implementations are classes that include this module.
+# Context implementations can use the #role method to bind roles to objects,
+# and must provide an #execute method that enacts the use case behavior.
+#
+# Brassbound enforces the fact that each role is bound to exactly one object,
+# since each role must have a unique name. However, any given object may
+# simultaneously play several roles.
+#
+# Note that no special support is required for the role module or data object
+# implementations; they are normal Ruby modules and objects, respectively.
+# The context manages the necessary plumbing to bind roles to objects and to
+# provide access to the context for the roles. In other words, role modules do
+# not have to include any other modules or adhere to any particular conventions,
+# and neither do the objects to which the roles are bound need to inherit from
+# any other class or include any other modules.
+module Brassbound::Context
+
+  require 'brassbound/util'
+
+  def self.current
+    Thread.current[:brassbound_context]
+  end
+
+  RoleMapping = Struct.new(:role_module, :data_object)
+
+  # A Hash containing all of the declared role mappings for this context.
+  # The keys of the Hash are the declared role names, while the values
+  # are the associated RoleMapping objects.
+  #
+  # Role mappings are declared using the #role method, which see for
+  # further details.
+  def roles
+    @declared_roles ||= Hash.new
+  end
+
+  # Declare a role mapping.
+  #
+  # This method accepts either two or three arguments. In the three argument
+  # form, the arguments are as follows:
+  #
+  #   role_name:: The name of the role in this context.
+  #   role_module:: The module that serves as the "methodful role".
+  #   obj:: The data object to which the role_module will be attached.
+  #
+  # In the two argument form, the role_name is omitted and the role_name
+  # is derived from the name of the role_module by converting from
+  # CamelCaseName to underscore_name. For instance, if the role_name
+  # is not specified, then a role_module called MoneySource would be
+  # named money_source.
+  #
+  # This method adds the role mapping to the Hash returned by the #roles
+  # method. If the context is already executing when this method is
+  # invoked, it will call #apply_role to reify the role mapping
+  # immediately. Otherwise, all role mappings are applied when the
+  # context begins execution.
+  def role(*args)
+    case args.size
+    when 2
+      role_module = args[0]
+      obj = args[1]
+      role_name = Util.underscore(role_module.name).to_sym
+    when 3
+      role_name = args[0]
+      role_module = args[1]
+      obj = args[2]
+    else
+      raise ArgumentError
+    end
+
+    self.roles[role_name] = RoleMapping.new(role_module, obj)
+
+    if ::Brassbound::Context.current.equal?(self)
+      # If we are already in the execute method, apply the role mapping.
+      apply_role(role_name)
+    end
+  end
+
+  # Apply the role identified by role_name to the associated object.
+  # This has several effects. First, the object is extended with the
+  # role module (i.e. the "methodful role" in DCI terminology), thus
+  # adding all of the role module's methods to the object. Second,
+  # the object has a :context method added to it, which provides
+  # the role implementation access to this context. Finally, a new
+  # method is added to this context object, which is named after the
+  # role_name and which returns the object which is mapped to that role.
+  def apply_role(role_name)
+    role_mapping = self.roles[role_name]
+    role_module, obj = role_mapping.role_module, role_mapping.data_object
+    obj.extend(role_module)
+    obj.instance_variable_set(:@__brassbound_context, self)
+    class << obj
+      def context
+        @__brassbound_context
+      end
+    end
+    self.singleton_class.send(:define_method, role_name) do
+      obj
+    end
+  end
+
+  # Undo (most of) the effects of #apply_role. This method will remove all of
+  # the methods that were added to the mapped data object by #apply role, but
+  # the fact that the object has been extended with the role module cannot be
+  # undone. Therefore, <tt>obj.kind_of?(role_module)</tt> will still be true,
+  # even though the methods defined in role_module will have been removed from
+  # the object.
+  def unapply_role(role_name)
+    role_mapping = self.roles[role_name]
+    role_module, obj = role_mapping.role_module, role_mapping.data_object
+    obj.instance_variable_set(:@__brassbound_context, nil)
+    class << obj
+      remove_method(:context)
+    end
+    role_module.instance_methods.each do |m|
+      obj.singleton_class.send(:undef_method, m)
+    end
+    self.singleton_class.send(:undef_method, role_name)
+  end
+
+  def undef_role(role_module, obj)
+    obj.instance_variable_set(:@__brassbound_context, nil)
+    class << obj
+      remove_method(:context)
+    end
+    role_module.instance_methods.each do |m|
+      obj.singleton_class.send(:undef_method, m)
+    end
+  end
+
+  # Begin execution of this context. Note that context implementations must
+  # provide an #execute method, and should not override this #call method.
+  # This method will first set Context.current to self, apply all of the
+  # role mappings that have been declared with the #role method, and then
+  # call the #execute method.
+  #
+  # After the #execute method has returned, it will unapply all role mappings
+  # and set the current context back to its previous value.
+  def call(*args)
+    old_context = ::Brassbound::Context.current
+    Thread.current[:brassbound_context] = self
+
+    roles.each_key(&method(:apply_role))
+    begin
+      self.execute(*args)
+    ensure
+      roles.each_key(&method(:unapply_role))
+      Thread.current[:brassbound_context] = old_context
+    end
+  end
+end

data/lib/brassbound/util.rb

@@ -0,0 +1,9 @@
+module Util
+  def self.underscore(str)
+    str.gsub(/::/, '/').
+      gsub(/([A-Z]+)([A-Z][a-z])/,'\1_\2').
+      gsub(/([a-z\d])([A-Z])/,'\1_\2').
+      tr("-", "_").
+      downcase
+  end
+end

data/lib/brassbound/version.rb

@@ -0,0 +1,3 @@
+module Brassbound
+  VERSION = "0.5.0"
+end

data/lib/brassbound.rb

@@ -0,0 +1,7 @@
+require 'brassbound/version'
+
+module Brassbound
+end
+
+require 'brassbound/context'
+

data/spec/context_spec.rb

@@ -0,0 +1,90 @@
+require 'spec_helper'
+include Brassbound
+
+class Account
+  def self.find(account_id)
+    case account_id
+    when 1
+      Account.new(200)
+    when 2
+      Account.new(100)
+    end
+  end
+
+  attr_accessor :balance
+
+  def initialize(balance)
+    @balance = balance
+  end
+end
+
+module MoneySource
+  def transfer_out(amount)
+    self.balance -= amount
+    context.dest_account.transfer_in(amount)
+  end
+end
+
+module MoneySink
+  def transfer_in(amount)
+    self.balance += amount
+  end
+end
+
+class TransferFunds
+  include Context
+
+  def initialize(source_account_id, dest_account_id, amount)
+    @source_account_id = source_account_id
+    @dest_account_id = dest_account_id
+    @amount = amount
+
+    role :source_account, MoneySource, Account.find(@source_account_id)
+    role :dest_account, MoneySink, Account.find(@dest_account_id)
+  end
+
+  def execute
+    source_account.transfer_out(@amount)
+    # Allow spec to access the executing context for testing
+    yield self if block_given?
+  end
+end
+
+describe Context do
+  include Context
+
+  let(:source_account_id) { 1 }
+  let(:dest_account_id) { 2 }
+  let(:source_account) { Account.find(source_account_id) }
+  let(:dest_account) { Account.find(dest_account_id) }
+
+  let(:transfer_funds_context) {
+    TransferFunds.new(source_account_id, dest_account_id, 50)
+  }
+
+  context "#role" do
+    it "declares a role mapping" do
+      role MoneySource, source_account
+      mapping = roles[:money_source]
+      mapping.role_module.should == MoneySource
+      mapping.data_object.should == source_account
+
+      role :money_sink, MoneySink, dest_account
+      mapping = roles[:money_sink]
+      mapping.role_module.should == MoneySink
+      mapping.data_object.should == dest_account
+    end
+  end
+
+  context "#call" do
+    it "binds all roles to their mapped objects" do
+      transfer_funds_context.call do |ctx|
+        ctx.source_account.should == source_account
+        ctx.source_account.should be_kind_of(MoneySource)
+        ctx.dest_account.should == dest_account
+        ctx.dest_account.should be_kind_of(MoneySink)
+      end
+    end
+  end
+end
+

data/spec/spec_helper.rb

@@ -0,0 +1,2 @@
+require 'brassbound'
+

metadata

@@ -0,0 +1,72 @@
+--- !ruby/object:Gem::Specification
+name: brassbound-dci
+version: !ruby/object:Gem::Version
+  version: 0.5.0
+  prerelease: 
+platform: ruby
+authors:
+- Jason Voegele
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-05-05 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: &70190658979080 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 2.10.0
+  type: :development
+  prerelease: false
+  version_requirements: *70190658979080
+description: Brassbound is a simple but strict implementation of the Data, Context,
+  and Interaction (DCI) paradigm for Ruby.
+email:
+- jason@jvoegele.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- Gemfile
+- README.rdoc
+- Rakefile
+- brassbound-dci.gemspec
+- examples/money_transfer.rb
+- examples/wedding.rb
+- lib/brassbound.rb
+- lib/brassbound/context.rb
+- lib/brassbound/util.rb
+- lib/brassbound/version.rb
+- spec/context_spec.rb
+- spec/spec_helper.rb
+homepage: ''
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.15
+signing_key: 
+specification_version: 3
+summary: Simple but strict DCI framework
+test_files:
+- spec/context_spec.rb
+- spec/spec_helper.rb