dci 0.1.0

data/.ruby

@@ -0,0 +1,43 @@
+---
+source:
+- Profile
+authors:
+- name: Thomas Sawyer
+  email: transfire@gmail.com
+copyrights:
+- holder: Thomas Sawyer
+  year: '2012'
+  license: BSD-2-Clause
+replacements: []
+alternatives: []
+requirements:
+- name: detroit
+  groups:
+  - build
+  development: true
+- name: qed
+  groups:
+  - test
+  development: true
+dependencies: []
+conflicts: []
+repositories:
+- uri: git@github.com:rubyworks/dci.git
+  scm: git
+  name: upstream
+resources:
+  home: https://rubyworks.github.com/dci
+  code: https://github.com/rubyworks/dci
+  mail: http://groups.google.com/groups/rubyworks-mailinglist
+extra: {}
+load_path:
+- lib
+revision: 0
+version: 0.1.0
+name: dci
+title: DCI
+summary: DCI for Ruby
+created: '2011-03-04'
+description: Faithful DCI framework for Ruby application development.
+organization: Rubyworks
+date: '2012-02-07'

data/.yardopts

@@ -0,0 +1,7 @@
+--title "DCI"
+--readme README.md
+--protected
+--private
+lib
+-
+[A-Z]*.*

data/COPYING.md

@@ -0,0 +1,36 @@
+# COPYRIGHT
+
+## NOTICES
+
+### Assay
+
+| Project   | Assay                             |
+|-----------|-----------------------------------|
+| Copyright | (c) 2012 Rubyworks                |
+| License   | (r) BSD-2-Clause                  |
+| Website   | http://rubyworks.github.com/assay |
+
+## LICENSES
+
+### BSD-2-Clause License
+
+    Redistribution and use in source and binary forms, with or without
+    modification, are permitted provided that the following conditions are met:
+
+       1. Redistributions of source code must retain the above copyright notice,
+          this list of conditions and the following disclaimer.
+
+       2. Redistributions in binary form must reproduce the above copyright
+          notice, this list of conditions and the following disclaimer in the
+          documentation and/or other materials provided with the distribution.
+
+    THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES,
+    INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
+    FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
+    COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
+    INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
+    NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR  SERVICES; LOSS OF USE,
+    DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY
+    OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+    NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
+    EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/HISTORY.md

@@ -0,0 +1,10 @@
+# HISTORY
+
+## 0.1.0 | 2012-02-07
+
+This is the initial working version of DCI.
+
+Changes:
+
+* Happy Birthday!
+

data/README.md

@@ -0,0 +1,32 @@
+# DCI for Ruby
+
+[Home](http://rubyworks.github.com/dci) /
+[Code](http://github.com/rubyworks/dci) /
+[Bugs](http://github.com/rubyworks/dci/issues) /
+[Mail](http://groups.google.com/groups/rubyworks-mailinglist)
+
+
+## Description
+
+The DCI library for Ruby is a fairly faithful implementation of the DCI
+concpets developed by Trygve Reenskaug, Reenskaug and James O. Coplien.
+
+It define two reusable base classes, the Role and Context. The best way
+to understand their usage is to look at the QED documentation provided
+([for example](https://github.com/rubyworks/dci/blob/master/demo/account_example.md)).
+
+
+## Installation
+
+The ususal RubyGems install procedure:
+
+    $ gem install dci
+
+
+## Copyrights
+
+Copyright (c) 2012 Rubyworks. All rights reserved.
+
+DCI for Ruby is distributable under the terms of **BSD-2-Clause** license.
+
+See COPYING.md file for license details.

data/demo/account_example.md

@@ -0,0 +1,74 @@
+# Account Balance Transfer
+
+The Account Balance Transfre is the classic example of using DCI.
+
+First we need our Data model. In the example that is the Account class.
+To keep our example simple we will initialize new accounts with
+a balance of $100. (We're generous like that.)
+
+    class Account
+      def initialize(account_id)
+        @account_id = account_id
+        @balance    = 100
+      end
+      def account_id
+        @account_id
+      end
+      def available_balance
+        @balance
+      end
+      def increase_balance(amount)
+        @balance += amount
+      end
+      def decrease_balance(amount)
+        @balance -= amount
+      end
+    end
+
+We set up two Roles, one role for withdrawing money from an account,
+and one for depositing money into an account.
+
+    class Account::TransferWithdraw < Role
+      def transfer(amount)
+        decrease_balance(amount)
+        #log "Tranfered $#{amount} from account ##{account_id}."
+      end
+    end
+
+    class Account::TransferDeposit < Role
+      def transfer(amount)
+        increase_balance(amount)
+        #log "Tranfered $#{amount} into account ##{account_id}."
+      end
+    end
+
+Now we create a Context which will assign accounts to the roles
+and used to perfomr the transfer.
+
+    # We can think of a context as setting a scene.
+    class Account::Transfer < Context
+      role :source_account      => Account::TransferWithdraw
+      role :destination_account => Account::TransferDeposit
+
+      def initialize(source_account, destination_account)
+        self.source_account      = source_account
+        self.destination_account = destination_account
+      end
+
+      def transfer(amount)
+        #log "Begin transfer."
+        roles.each{ |role| role.transfer(amount) }
+        #log "Transfer complete."
+      end
+    end
+
+Let's give it a try.
+
+    acct1 = Account.new(000100)
+    acct2 = Account.new(000200)
+
+    Account::Transfer.new(acct1, acct2).transfer(50)
+
+    acct1.available_balance  #=>  50
+    acct2.available_balance  #=> 150
+

data/demo/applique/dci.rb

@@ -0,0 +1 @@
+require 'dci'

data/lib/dci.rb

@@ -0,0 +1,38 @@
+# Data, Context and Interaction (DCI) is a paradigm used in computer software to
+# program systems of communicating objects. Its goals are:
+#
+# * To improve the readability of object-oriented code by giving system behavior
+# first-class status;
+#
+# * To cleanly separate code for rapidly changing system behavior (what the system does)
+# from code for slowly changing domain knowledge (what the system is), instead
+# of combining both in one class interface;
+#
+# * To help software developers reason about system-level state and behavior
+# instead of only object state and behavior;
+#
+# * To support an object style of thinking that is close to peoples' mental
+# models, rather than the class style of thinking that overshadowed object
+# thinking early in the history of object-oriented programming languages.
+#
+# The paradigm separates the domain model (data) from use cases (context) and roles
+# that objects play (interaction). DCI is complementary to model–view–controller (MVC).
+# MVC as a pattern language is still used to separate the data and its processing from
+# presentation.
+#
+# DCI was invented by Trygve Reenskaug, also the inventor of MVC. The current formulation
+# of DCI is mostly the work of Reenskaug and James O. Coplien.
+#
+#     acct1 = Account.new(10500)
+#     acct2 = Account.new(10010)
+#
+#     Balance::Transfer.new(acct1, acct2).transfer(50)
+#
+module DCI
+end
+
+require 'dci/object'  # data
+require 'dci/context' # context
+require 'dci/role'    # interation
+
+

data/lib/dci/context.rb

@@ -0,0 +1,89 @@
+# Context - 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.
+#
+# Each context represents one or more use cases. A context object is instantiated
+# for each enactment of a use case for which it is responsible. Its main job
+# is to identify the objects that will participate in the use case and to
+# assign them to play the Roles which carry out the use case through their
+# responsibilities. A role may comprise methods, and each method is some small
+# part of the logic of an algorithm implementing a use case. Role methods run
+# in the context of an object that is selected by the context to play that role
+# for the current use case enactment. The role-to-object bindings that take place
+# in a context can be contrasted with the polymorphism of vernacular object-oriented
+# programming. The overall business functionality is the sum of complex, dynamic
+# networks of methods decentralized in multiple contexts and their roles.
+#
+# Each context is a scope that includes identifiers that correspond to its roles.
+# Any role executing within that context can refer to the other roles in that
+# context through these identifiers. These identifiers have come to be called
+# methodless roles. At use case enactment time, each and every one of these
+# identifiers becomes bound to an object playing the corresponding Role for
+# this Context.
+#
+# An example of a context could be a wire transfer between two accounts,
+# where data models (the banking accounts) are used through roles named
+# SourceAccount and # DestinationAccount. 
+#
+#     class Account::Transfer < Context
+#       role :source_account      => Account::TransferWithdraw
+#       role :destination_account => Account::TransferDeposit
+#
+#       def initialize(source_account, destination_account)
+#         self.source_account      = source_account
+#         self.destination_account = destination_account
+#       end
+#
+#       def transfer(amount)
+#         roles.each{ |role| role.transfer(amount) }
+#       end
+#     end
+#
+class Context
+
+  # Define a role given the name the role will use in this context,
+  # and the role class that is to be played.
+  #
+  def self.role(name_to_role)
+    name_to_role.each do |name, role|
+      define_method("role_#{name}"){ role }
+
+      module_eval %{
+        def #{name}=(data)
+          @#{name} = role_#{name}.new(data)
+        end
+
+        def #{name}
+          @#{name}
+        end
+      }
+    end
+  end
+
+  # The default contructor can be used to assign roles via
+  # a settings hash.
+  #
+  def initialize(settings={})
+    settings.each do |k,v|
+      __send__("#{k}=", v)
+    end
+  end
+
+  # Returns a list of all roles in the context.
+  #
+  # @todo Return value should probably be cached.
+  def roles
+    list = []
+    methods.each do |name|
+      next unless name.to_s.start_with?('role_')
+      list << __send__(name.to_s.sub('role_',''))
+    end
+    list
+  end
+
+end

data/lib/dci/object.rb

@@ -0,0 +1,47 @@
+# Data - The data are "what the system is." The data part of the DCI architecture
+# is its (relatively) static data model with relations. The data design is usually
+# coded up as conventional classes that represent the basic domain structure of
+# the system. These classes are barely smart data, and they explicitly lack the
+# functionality that is peculiar to support of any particular use case. These
+# classes commonly encapsulate the physical storage of the data. These data
+# implement an information structure that comes from the mental model of end
+# users, domain experts, programmers, and other people in the system. They may
+# correspond closely to the model objects of MVC.
+#
+# An example of a data object could be a bank account. Its interface would have
+# basic operations for increasing and decreasing the balance and for inquiring
+# about the current balance. The interface would likely not offer operations that
+# involve transactions, or which in any way involve other objects or any user
+# interaction. So, for example, while a bank account may offer a primitive for
+# increasing the balance, it would have no method called deposit. Such operations
+# belong instead in the interaction part of DCI.
+#
+# Data objects are instances of classes that might come from domain-driven design,
+# and such classes might use subtyping relationships to organize domain data.
+# Though it reduces to classes in the end, DCI reflects a computational model
+# dominated by object thinking rather than class thinking. Therefore, when
+# thinking "data" in DCI, it means thinking more about the instances at run time
+# than about the classes from which they were instantiated. 
+#
+#     class Account
+#       def initialize(accountId)
+#         @account_id = accountId
+#         @balance    = 0
+#       end
+#       def account_id
+#         @account_id
+#       end
+#       def available_balance
+#         @balance
+#       end
+#       def increase_balance(amount)
+#         @balance += amount
+#       end
+#       def decrease_balance(amount)
+#         @balance -= amount
+#       end
+#     end
+#
+# @todo Should objects track the roles in which they are presently particiapting?
+class Object
+end

data/lib/dci/role.rb

@@ -0,0 +1,53 @@
+# Interaction - The Interaction is "what the system does." The Interaction
+# is implemented as Roles which are played by objects at run time. These objects
+# combine the state and methods of a Data (domain) object with methods (but no
+# state, as Roles are stateless) from one or more Roles. In good DCI style,
+# a Role addresses another object only in terms of its (methodless) Role. There
+# is a special Role called `@self` which binds to the object playing the current
+# Role. Code within a Role method may invoke a method on `@self` and thereby
+# invoke a method of the Data part of the current object. One curious aspect
+# of DCI is that these bindings are guaranteed to be in place only at run time
+# (using a variety of approaches and conventions; C++ templates can be used to
+# guarantee that the bindings will succeed). This means that Interactions—the
+# Role methods—are generic. In fact, some DCI implementations use generics or
+# templates for Roles.
+#
+# A Role is a stateless programming construct that corresponds to the end user's
+# mental model of some entity in the system. A Role represents a collection of 
+# responsibilities. Whereas vernacular object-oriented programming speaks of
+# objects or classes as the loci of responsibilities, DCI ascribes them to Roles.
+# An object participating in a use case has responsibilities: those that it takes
+# on as a result of playing a particular Role.
+#
+# In the money transfer use case, for example, the role methods in the
+# SourceAccount and DestinationAccount enact the actual transfer.
+#
+#     class Account::TransferWithdraw < Role
+#       def transfer(amount)
+#         decrease_balance(amount)
+#         log "Tranfered from account #{account_id} $#{amount}"
+#       end
+#     end
+#
+#     class Account::TransferDepoit < Role
+#       def transfer(amount)
+#         increase_balance(amount)
+#         log "Tranfered into account #{account_id} $#{amount}"
+#       end
+#     end
+#
+class Role
+
+  #
+  def initialize(player)
+    @self = player
+  end
+
+  #
+  # @todo Should use #public_send?
+  def method_missing(s, *a, &b)
+    @self.__send__(s, *a, &b)
+  end
+
+end
+

metadata

@@ -0,0 +1,82 @@
+--- !ruby/object:Gem::Specification
+name: dci
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+  prerelease: 
+platform: ruby
+authors:
+- Thomas Sawyer
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-02-07 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: detroit
+  requirement: &12149120 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *12149120
+- !ruby/object:Gem::Dependency
+  name: qed
+  requirement: &12148360 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *12148360
+description: Faithful DCI framework for Ruby application development.
+email:
+- transfire@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files:
+- COPYING.md
+- HISTORY.md
+- README.md
+files:
+- .ruby
+- .yardopts
+- demo/account_example.md
+- demo/applique/dci.rb
+- lib/dci/context.rb
+- lib/dci/object.rb
+- lib/dci/role.rb
+- lib/dci.rb
+- COPYING.md
+- HISTORY.md
+- README.md
+homepage: https://rubyworks.github.com/dci
+licenses:
+- BSD-2-Clause
+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.11
+signing_key: 
+specification_version: 3
+summary: DCI for Ruby
+test_files: []