mediator 0.0.0

data/.autotest

@@ -0,0 +1,63 @@
+require "autotest/restart"
+
+Autotest.add_hook :initialize do |at|
+  at.testlib = "minitest/autorun"
+
+  # Autotest's defaults don't match our idiom, so we'll build the
+  # mappings by hand.
+
+  at.clear_mappings
+
+  # Changed tests always run themselves.
+
+  at.add_mapping %r{^test/.*_test.rb$} do |f, _|
+    [f]
+  end
+
+  # Run corresponding unit tests if something in lib changes.
+
+  at.add_mapping %r{^(?:lib)/(.*)\.rb$} do |f, m|
+    ["test/#{m[1]}_test.rb"]
+  end
+
+  at.add_exception ".autotest"
+  at.add_exception ".git"
+  at.add_exception "Gemfile"
+  at.add_exception "README.md"
+  at.add_exception "Rakefile"
+  at.add_exception "mediator.gemspec"
+  at.add_exception "pkg"
+end
+
+class Autotest
+  TESTFILES = Dir["test/*_test.rb"]
+
+  # Because MiniTest::Spec's generated class names (very
+  # understandably) can't map reliably to test files, try to guess a
+  # file by turning the describe block's class name into a file path
+  # and gradually making it more general until something matches.
+
+  def consolidate_failures failed
+    filters = new_hash_of_arrays
+
+    failed.each do |method, klass|
+      fragments = klass.sub(/Spec$/, "").
+        gsub(/([A-Z]+)([A-Z][a-z])/,'\1_\2').
+        gsub(/([a-z\d])([A-Z])/,'\1_\2').
+        downcase.split "_"
+
+      until fragments.empty?
+        candidate = "test/#{fragments.join '_'}_test.rb"
+
+        if TESTFILES.include? candidate
+          filters[candidate] << method
+          break
+        end
+
+        fragments.pop
+      end
+    end
+
+    filters
+  end
+end

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/Gemfile

@@ -0,0 +1,2 @@
+source :rubygems
+gemspec

data/README.md

@@ -0,0 +1,81 @@
+# Mediator
+
+## Notes on Render
+
+    # taken from the old notation in a bunch of different models, just
+    # examples of shit that needs to work
+
+    def render! r
+
+      # from Account
+
+      if context.root?
+        r.key :color
+        r.key :key, self[:domain]
+      end
+
+      if subject.is? :sso
+        r.key :sso, private: sso_private
+      end
+
+      # from Album
+
+      if inside? artist
+        r.key :artist, id: artist.id, name: artist.name
+      end
+
+      # from Artist
+
+      r.array :albums
+      r.obj   :contact
+
+      # from Collaborator
+
+      r.ids :tracks, tracks.active
+      r.id  :pro # WAS: a.set :pro, pro.id if pro
+
+      # from Model
+
+      r.key :created, from: :created_at
+    end
+
+## TODO
+
+* Nested collections or objects, like `r.array :albums` or `r.obj
+  :contact` in the example above. Should create a new mediator stack
+  for each entry in the collection but somehow mark the current
+  mediator as the parent.
+
+* For `r.ids`, just value.map(&:id). Should check for `_ids` shortcut
+  first though, but only if an explicit value isn't provided.
+
+* For `r.id :pro`, should first check for `pro_id` and then
+  fall back on `pro.id`.
+
+* Nested collections should always exist in rendered output even if
+  they're empty or missing.
+
+* Benchmarks and micro-opts, esp. around object allocation.
+
+## License (MIT)
+
+Copyright 2011 Audiosocket (tech@audiosocket.com)
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+'Software'), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/Rakefile

@@ -0,0 +1,4 @@
+require "bundler/gem_tasks"
+
+desc "Run the tests."
+task(:default) { $: << "./lib"; Dir["test/*_test.rb"].each { |f| load f } }

data/lib/mediator/parser.rb

@@ -0,0 +1,33 @@
+class Mediator
+  class Parser
+    attr_reader :data
+    attr_reader :mediator
+
+    def initialize mediator, data = {}
+      @data     = data
+      @mediator = mediator
+    end
+
+    def get name
+      data[name] || data[name.to_s]
+    end
+
+    def has? name
+      !!get(name)
+    end
+
+    def key name, options = nil, &block
+      selector = (options && options[:from]) || name
+      value  ||= get(selector) || (options && options[:value])
+
+      return if value.nil? or value.respond_to?(:empty?) && value.empty?
+
+      value = block[value] if block_given?
+      key! name, value
+    end
+
+    def key! name, value
+      mediator.set name, value
+    end
+  end
+end

data/lib/mediator.rb

@@ -0,0 +1,148 @@
+require "mediator/parser"
+
+# Helps translate an object to and from more primitive, untyped
+# forms. Mediators should subclass and implement `parse` and `render`,
+# or use the class-level helpers to declare the necessary
+# transformations.
+
+class Mediator
+
+  # This lambda takes a single argument, does nothing, and returns `nil`.
+
+  NOTHING = lambda { |_| nil }
+
+  # State information availble during `parse` and `render`. This is
+  # often an application-specific object that provides authentication
+  # and authorization data, but it can be just about anything.
+
+  attr_reader :context
+
+  # An optional parent mediator. Used during nested mediation: See
+  # `array`, `obj`, etc.
+
+  attr_reader :parent
+
+  # The subject of this mediation. A rich(er) domain object that needs
+  # to be translated back and forth.
+
+  attr_reader :subject
+
+  # Create a new mediator with a `subject` and a mediation
+  # `context`. If the context is a Mediator, it will be set as this
+  # instance's parent and its context will be reused.
+
+  def initialize subject, context = nil
+    @context = context
+    @subject = subject
+
+    if Mediator === context
+      @parent  = @context
+      @context = @parent.context
+    end
+  end
+
+  # Is `subject` the subject of one of the ancestral mediators?
+
+  def inside? subject
+    parent && (parent.subject == subject || parent.inside?(subject))
+  end
+
+  # Is this mediator nested inside a `parent`?
+
+  def nested?
+    !!parent
+  end
+
+  # Folds, spindles, and mutilates `data`, then applies to `subject`
+  # and returns it. Subclasses should override `parse!` instead of
+  # this method.
+
+  def parse data
+    parse! Mediator::Parser.new(self, data)
+    subject
+  end
+
+  # The actual parse implementation. Subclasses should override and
+  # consistently call `super`. Default implementation is empty.
+
+  def parse! parser
+  end
+
+  # Create a more primitive representation of `subject`. Depending on
+  # app design and `context`, the output of `render` may not always be
+  # valid input to `parse`. Implement in subclasses.
+
+  def render
+    raise NotImplementedError, "Implement #{self.class.name}#render."
+  end
+
+  # Set `name` to `value` on `subject`. The default implementation
+  # calls a matching mutator method.
+
+  def set name, value
+    subject.send "#{name}=", setting(name, value)
+  end
+
+  # Called when setting `name` to `value` on `subject`. Can be used to
+  # transform incoming values, e.g., trimming all strings. The default
+  # implementation returns `value` unchanged.
+
+  def setting name, value
+    value
+  end
+
+  # Find and instantiate a mediator for `subject` by consulting
+  # `map`. Returns `nil` if no mediator can be found. Inheritance is
+  # respected for mediators registered by class, so:
+  #
+  #     A = Class.new
+  #     B = Class.new A
+  #     M = Class.new Mediator
+  #
+  #     M.subject A
+  #     Mediator.for B.new  #  => A
+
+  def self.for subject, context = nil
+    map.each do |criteria, mediator|
+      return mediator.new subject, context if criteria === subject
+    end
+
+    nil
+  end
+
+  # An alias of `for`.
+
+  def self.[] subject, context = nil
+    self.for subject, context
+  end
+
+  # A Hash of mappings from subject to Mediator subclass.
+
+  def self.map
+    @@map
+  end
+
+  @@map = {}
+
+  # Register this Mediator subclass's interest in one or more subject
+  # classes. If more detailed selection behavior is necessary,
+  # `subject` can take a block instead. When the mediator for a
+  # subject is discovered with `Mediator.for` the given block will be
+  # passed the subject and can return `true` or `false`.
+
+  def self.subject *klasses, &block
+    raise "Only call subject on #{name} subclasses." if Mediator == self
+
+    if block_given?
+      unless klasses.empty?
+        raise ArgumentError, "Can't provide both classes and a block."
+      end
+
+      map[block] = self
+    end
+
+    klasses.each { |k| map[k] = self }
+
+    self
+  end
+end

data/mediator.gemspec

@@ -0,0 +1,15 @@
+Gem::Specification.new do |gem|
+  gem.authors       = ["Audiosocket"]
+  gem.email         = ["tech@audiosocket.com"]
+  gem.description   = "A go-between for models."
+  gem.summary       = "Translates models to and from primitive representations."
+  gem.homepage      = "https://github.com/audiosocket/mediator"
+
+  gem.files         = `git ls-files`.split "\n"
+  gem.test_files    = `git ls-files -- test/*`.split "\n"
+  gem.name          = "mediator"
+  gem.require_paths = ["lib"]
+  gem.version       = "0.0.0"
+
+  gem.required_ruby_version = ">= 1.9.2"
+end

data/test/mediator_parser_test.rb

@@ -0,0 +1,80 @@
+require "mediator"
+require "mediator/parser"
+require "minitest/autorun"
+require "ostruct"
+
+describe Mediator::Parser do
+  before do
+    @subject  = OpenStruct.new
+    @mediator = Mediator.new @subject
+  end
+
+  it "has data" do
+    p = Mediator::Parser.new :mediator, :data
+    assert_equal :data, p.data
+  end
+
+  it "has default data" do
+    assert_equal Hash.new, Mediator::Parser.new(:mediator).data
+  end
+
+  describe "declaring keys explicitly" do
+    before do
+      @parser = Mediator::Parser.new @mediator,
+        emptystring: "", emptyarray: [], isnil: nil
+    end
+
+    it "sets unconditionally with key!" do
+      @parser.key! :foo, :bar
+      assert_equal :bar, @subject.foo
+    end
+
+    it "can pull from the options hash" do
+      @parser.key :foo, value: :bar
+      assert_equal :bar, @subject.foo
+    end
+
+    it "ignores empty values" do
+      @parser.key :emptystring
+      assert_nil @subject.emptystring
+
+      @parser.key :emptyarray
+      assert_nil @subject.emptyarray
+    end
+
+    it "ignores nil values" do
+      @parser.key :isnil
+      assert_nil @subject.isnil # heh
+    end
+  end
+
+  describe "setting values from data" do
+    it "grabs from data like it's a Hash" do
+      p = Mediator::Parser.new @mediator, foo: "bar"
+      p.key :foo
+
+      assert_equal "bar", @subject.foo
+    end
+
+    it "works with strings and symbols" do
+      p = Mediator::Parser.new @mediator, "foo" => "bar"
+      p.key :foo
+
+      assert_equal "bar", @subject.foo
+    end
+
+    it "transforms values with a block" do
+      p = Mediator::Parser.new @mediator, foo: "bar"
+      p.key(:foo) { |d| d.upcase }
+
+      assert_equal "BAR", @subject.foo
+    end
+
+    it "can declaratively alias a name with :from" do
+      p = Mediator::Parser.new @mediator, quux: "bar"
+      p.key :foo, from: :quux
+
+      assert_equal "bar", @subject.foo
+    end
+  end
+end

data/test/mediator_test.rb

@@ -0,0 +1,203 @@
+require "mediator"
+require "minitest/autorun"
+require "ostruct"
+
+describe Mediator do
+  before do
+    Mediator.map.clear
+  end
+
+  describe "initialization" do
+    it "takes a subject and a context" do
+      m = Mediator.new :subject, :context
+
+      assert_equal :context, m.context
+      assert_equal :subject, m.subject
+    end
+
+    it "optionally takes a parent context" do
+      m = Mediator.new :s, :c
+      n = Mediator.new :t, m
+
+      assert_equal :c, n.context
+      assert_equal m, n.parent
+    end
+  end
+
+  describe "nesting" do
+    it "is inside another mediator when a parent exists" do
+      m = Mediator.new :s, :c
+
+      refute m.nested?
+      assert Mediator.new(:s, m).nested?
+    end
+
+    it "can narrow inside? by checking subjects" do
+      m = Mediator.new :s, :c
+      n = Mediator.new :t, m
+      o = Mediator.new :u, n
+
+      assert n.inside? :s
+      assert o.inside? :s
+    end
+  end
+
+  describe "parsing" do
+    it "is a noop by default" do
+      m = Mediator.new :subject
+      m.parse :data
+    end
+
+    it "builds a Parser and delegates to parse!" do
+      c = Class.new Mediator do
+        def parse! parser
+          parser.key :foo
+        end
+      end
+
+      s = OpenStruct.new
+      m = c.new s
+
+      m.parse foo: :bar
+      assert_equal :bar, s.foo
+    end
+
+    it "always returns the subject" do
+      c = Class.new Mediator do
+        def self.parser
+          lambda { |p| :useless! }
+        end
+      end
+
+      m = c.new :subject
+      assert_equal :subject, m.parse(:data)
+    end
+  end
+
+  it "will render at some point" do
+    ex = assert_raises NotImplementedError do
+      Mediator.new(:s).render
+    end
+
+    assert_equal "Implement Mediator#render.", ex.message
+  end
+
+  describe "setting values on the subject" do
+    it "calls a setter by default" do
+      s = OpenStruct.new
+      m = Mediator.new s
+
+      m.set :foo, :bar
+      assert_equal :bar, s.foo
+    end
+
+    it "can transform incoming values" do
+      c = Class.new Mediator do
+        def setting name, value
+          case value
+          when String then value.upcase
+          else value
+          end
+        end
+      end
+
+      s = OpenStruct.new
+      m = c.new s
+
+      m.set :foo, "bar"
+      assert_equal "BAR", s.foo
+    end
+  end
+
+  describe ".for" do
+    it "gets a mediator by class" do
+      c = Class.new(Mediator) { subject Symbol }
+      m = Mediator.for :foo
+
+      assert_instance_of c, m
+    end
+
+    it "gets a mediator for a subclass" do
+      x = Class.new
+      y = Class.new x
+      c = Class.new(Mediator) { subject x }
+      m = Mediator.for y.new
+
+      assert_instance_of c, m
+    end
+
+    it "gets a mediator by block eval" do
+      c = Class.new Mediator do
+        subject do |s|
+          "hello" == s
+        end
+      end
+
+      assert_instance_of c, Mediator.for("hello")
+      assert_nil Mediator.for "Hello!"
+    end
+
+    it "is also available as []" do
+      c = Class.new(Mediator) { subject Symbol }
+      assert_instance_of c, Mediator[:foo]
+    end
+  end
+
+  describe ".subject" do
+    it "can only be called on subclasses" do
+      ex = assert_raises RuntimeError do
+        Mediator.subject
+      end
+
+      assert_equal "Only call subject on Mediator subclasses.", ex.message
+    end
+
+    it "can register a class" do
+      c = Class.new Mediator do
+        subject Symbol
+      end
+
+      assert_equal c, Mediator.map[Symbol]
+    end
+
+    it "can register multiple classes" do
+      c = Class.new Mediator do
+        subject String, Symbol
+      end
+
+      assert_equal c, Mediator.map[String]
+      assert_equal c, Mediator.map[Symbol]
+    end
+
+    it "can register with a block" do
+      c = Class.new Mediator do
+        subject do |s|
+          Symbol === s
+        end
+      end
+
+      b = Mediator.map.keys.first
+      refute_nil b
+
+      assert b[:foo]
+      refute b["bar"]
+    end
+
+    it "doesn't allow classes and a block to be mixed" do
+      ex = assert_raises ArgumentError do
+        Class.new Mediator do
+          subject String do
+            # ...
+          end
+        end
+      end
+
+      assert_equal "Can't provide both classes and a block.", ex.message
+    end
+
+    it "returns self" do
+      c = Class.new Mediator
+      assert_equal c, c.subject
+    end
+  end
+end

metadata

@@ -0,0 +1,57 @@
+--- !ruby/object:Gem::Specification
+name: mediator
+version: !ruby/object:Gem::Version
+  version: 0.0.0
+  prerelease: 
+platform: ruby
+authors:
+- Audiosocket
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-01-09 00:00:00.000000000Z
+dependencies: []
+description: A go-between for models.
+email:
+- tech@audiosocket.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .autotest
+- .gitignore
+- Gemfile
+- README.md
+- Rakefile
+- lib/mediator.rb
+- lib/mediator/parser.rb
+- mediator.gemspec
+- test/mediator_parser_test.rb
+- test/mediator_test.rb
+homepage: https://github.com/audiosocket/mediator
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: 1.9.2
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.10
+signing_key: 
+specification_version: 3
+summary: Translates models to and from primitive representations.
+test_files:
+- test/mediator_parser_test.rb
+- test/mediator_test.rb