yzz 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 86214ab87ff3d7b69aa7dbc97c29abcd49b54d13
+  data.tar.gz: 25f05cecae9791711642b5ca7a8e57db6ffad447
+SHA512:
+  metadata.gz: 4eb9074c30c908c2ede65fe40498f680af6780a339f5cae54b2b8d1c83dddba82f242f490b6d93abea4c5e10ca7a0131b222c13836b2ed6857f4320362be4212
+  data.tar.gz: 2c9138c9a46f60259f3bbc443f27c593f51d4a535eb7e77f608f971906e8a90f8a618f9da656e8a0148c22d7b6031221fd1142c61d28fb824d714885a2b24971

data/.gitignore

@@ -0,0 +1,20 @@
+*~
+.#*
+\#*#
+*.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,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in yzz.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2013 boris
+
+MIT License
+
+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/README.md

@@ -0,0 +1,30 @@
+# Yzz
+
+y_ted is a Zz structure domain model
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'yzz'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install yzz
+
+## Usage
+
+Zz structures have been described by Ted Nelson. Yzz provides mixin that
+imbues objects with zz structure qualities.
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

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

data/lib/yzz/side.rb

@@ -0,0 +1,110 @@
+#encoding: utf-8
+
+# Ted Nelson calls zz objects 'cells', and defines posward and negward cell
+# side in each dimension. This is represented by Side class here, which is
+# a quadruple [zz object, dimension, direction, neighbor].
+# 
+class Yzz::Side
+  OPPOSITE = { posward: :negward, negward: :posward }
+
+  attr_reader :zz, :dimension, :direction, :neighbor
+
+  # Standard constructor. 3 compulsory arguments (:zz, :dimension, :direction),
+  # 1 optional argument :neighbor.
+  # 
+  def initialize( zz: ( raise ArgumentError, ":zz missing!" ),
+                  dimension: ( raise ArgumentError, ":dimension missing!" ),
+                  direction: ( raise ArgumentError, ":direction missing!" ),
+                  neighbor: nil )
+    raise TypeError, "Wrong :zz type!" unless zz.is_a_zz?
+    @zz, @dimension, @direction = zz, dimension, direction.to_sym
+    raise TypeError, "Direction must be either :posward or :negward!" unless
+      [ :posward, :negward ].include? direction.to_sym
+    set_neighbor! neighbor
+  end
+
+  # Links a new neighbor, unlinking and returning the old one. Cares about
+  # the argument type (Zz descendant or nil required), and has concerns not
+  # to break the new neighbor's conflicting connectivity, if any.
+  # 
+  def link new_neighbor
+    return unlink if new_neighbor.nil?
+    raise TypeError, "Zz object or nil expected!" unless new_neighbor.is_a_zz?
+
+    conflicter = opposite_side( of: new_neighbor ).neighbor # have concerns
+    return new_neighbor if conflicter == self # no neighbor change
+    raise TypeError, "Suggested new neighbor (#{new_neighbor}) already " +
+      "has a conflicting #{direction.opposite} link along dimension " +
+      "#{dimension} !" if conflicter.is_a_zz?
+
+    begin # FIXME: This should be an atomic transaction.
+      old_neighbor = set_neighbor! new_neighbor
+      opposite_side( of: new_neighbor ).set_neighbor! zz
+    end
+    return old_neighbor
+  end # def <<
+  alias << link
+
+  # Sets a new neighbor, crossing over the conflicting link, if present, with
+  # the old neighbor.
+  # 
+  def crossover new_neighbor
+    return unlink if new_neighbor.nil?
+    raise TypeError, "Zz object or nil expected!" unless new_neighbor.is_a_zz?
+
+    conflicter = opposite_side( of: new_neighbor ).neighbor
+    return new_neighbor if conflicter == self # no neighbor change
+
+    # FIXME: this should be an atomic transaction.
+    begin
+      old_neighbor = set_neighbor! new_neighbor
+      opposite_side( of: new_neighbor ).set_neighbor! zz
+      same_side( of: conflicter ).set_neighbor! old_neighbor # cross over
+      opposite_side( of: old_neighbor ).set_neighbor! conflicter # cross over
+    end
+    return old_neighbor
+  end
+  alias * crossover
+
+  # Returns the string briefly describing the instance.
+  # 
+  def to_s
+    "#<YTed::Zz::Side: #{direction} side of #{zz} along #{dimension}>"
+  end
+
+  # Given a zz object (named argument :of), returns its side along same
+  # dimension, in the direction same as self.
+  # 
+  def same_side( of: raise( ArgumentError, "Zz object (:of) absent!" ) )
+    of.along( dimension ).send direction
+  end
+
+  # Given a zz object, returns its side along same dimension, in the direction
+  # opposite than self.
+  # 
+  def opposite_side( of: zz )
+    of.along( dimension ).send ::Yzz::Side::OPPOSITE[ direction ]
+  end
+
+  # Unlinks the neighbor, returning it.
+  # 
+  def unlink
+    unlink!.tap do |neighbor|
+      opposite_side( of: neighbor ).unlink! if neighbor.is_a_zz?
+    end
+  end
+
+  protected
+
+  # Sets neighbor carelessly, returning the old neighbor.
+  # 
+  def set_neighbor! new_neighbor
+    neighbor.tap { @neighbor = new_neighbor }
+  end
+
+  # Unlinks the neighbor carelessly, returning it.
+  # 
+  def unlink!
+    set_neighbor! nil
+  end
+end # class YTed::Zz::Side

data/lib/yzz/side_pair.rb

@@ -0,0 +1,51 @@
+#encoding: utf-8
+
+# Represents a pair of Zz::Side instances pertaining to a Zz object along a
+# particular dimension.
+# 
+class Yzz::SidePair
+  attr_reader :zz, :dimension, :negward, :posward
+  alias p posward
+  alias n negward
+
+  def initialize( zz: ( raise ArgumentError, ":zz missing!" ),
+                  dimension: ( raise ArgumentError, ":dimension missing!" ),
+                  negward_neighbor: nil,
+                  posward_neighbor: nil )
+    @zz, @dimension = zz, dimension
+    @negward = Yzz::Side.new( zz: zz,
+                              dimension: dimension,
+                              direction: :negward,
+                              neighbor: negward_neighbor )
+    @posward = Yzz::Side.new( zz: zz,
+                              dimension: dimension,
+                              direction: :posward,
+                              neighbor: posward_neighbor )
+  end
+
+  # Links a neighbor posward.
+  # 
+  def >> new_neighbor
+    new_neighbor.along( dimension ).tap { posward << new_neighbor }
+  end
+
+  # Crossovers a new neighbor posward.
+  # 
+  def * new_neighbor
+    posward * new_neighbor
+  end
+
+  # Returns posward neighbor.
+  # 
+  def P; posward.neighbor end
+
+  # Returns negward neighbor.
+  # 
+  def N; negward.neighbor end
+
+  # Returns the string briefly describing the instance.
+  # 
+  def to_s
+    "#<YTed::Zz::SidePair: #{zz} along dimension #{dimension} >"
+  end
+end # class YTed::Zz::SidePair

data/lib/yzz/version.rb

@@ -0,0 +1,3 @@
+module Yzz
+  VERSION = "1.0.0"
+end

data/lib/yzz.rb

@@ -0,0 +1,54 @@
+# -*- coding: utf-8 -*-
+require_relative 'yzz/version'
+require_relative 'yzz/side'
+require_relative 'yzz/side_pair'
+
+# Yzz implements Ted Nelson's zz (hyperorthogonal, Zig-Zag...) structure. It
+# provides a mixin that imbues objects with zz properties.
+# 
+# A zz structure consists of zz objects, which exist in multiple dimensions. Zz
+# objects can be connected by directed edges -- connections. Connected objects
+# are called neighbors. Each connection belongs to some dimension. A zz object
+# is considered as having two <em>sides</em> in each dimension: posward side and
+# negward side. A connection always points away from the posward side, and
+# towards the neighbor's negward side. In each dimension, zz object can have at
+# most one posward and one negward neighbor. A zz object can be connected to
+# itself, forming a loop.
+# 
+# To these basic properties, Ted Nelson adds a bunch of other terminology.
+# A rank is a series of zz objects connected along one dimension. A rank viewed
+# horizontally is referred to as row. A rank viewed vertically is referred to
+# as column.
+
+# Mixin defining Zz structure (aka. hyperorthogonal structure). As represented
+# by YTed::Zz, a Zz structure is a collection of objects, whose connectivity is
+# defined in a multidimensional space in such way, that each object, along each
+# dimension, has at most one posward neighbor, and one negward neighbor. The
+# relation is bijective: If B is a posward neighbor of A along some dimension,
+# then A must be a negward neighbor of B along that dimension, and vice-versa.
+# 
+module Yzz
+  # Adds initialization of the @zz_dimensions hash to #initialize.
+  # 
+  def initialize *args
+    @zz_dimensions = Hash.new { |ꜧ, missing_dimension|
+      ꜧ[ missing_dimension ] = Yzz::SidePair
+        .new( zz: self, dimension: missing_dimension )
+    } # initialize the @zz_dimensions hash
+    super # and proceed as usual
+  end
+
+  # Returns a SidePair instance along the requested dimension.
+  # 
+  def along dimension
+    @zz_dimensions[ dimension ]
+  end
+  alias call along
+end
+
+class Object
+  def is_a_zz?
+    is_a? ::Yzz
+    # class_complies? ::YTed::Zz
+  end
+end

data/test/yzz_test.rb

@@ -0,0 +1,78 @@
+#! /usr/bin/ruby
+# -*- coding: utf-8 -*-
+
+require 'minitest/spec'
+require 'minitest/autorun'
+
+# Until they alias it in the core.
+require 'active_support/core_ext/string/starts_ends_with'
+
+require 'yzz'          # tested component itself
+
+describe Yzz do
+  before do
+    @ç = Class.new do
+      include Yzz
+      attr_accessor :value
+      def to_s; "ZzEnabledObject<#{object_id}>" end
+    end
+  end
+
+  it "reacts to #is_a_zz?" do
+    assert @ç.new.is_a_zz?
+    # ordinary objets know the method, but return false
+    assert ! Object.new.is_a_zz?
+  end
+
+  it "provides #along instance method" do
+    zz = @ç.new
+    assert_kind_of Yzz::SidePair, zz.along( :row )
+    assert_equal zz.along( :row ), zz.(:row)
+  end
+
+  describe 'basic zz object behavior' do
+    before do
+      @a = @ç.new
+    end
+
+    it "provides two sides, #opposite_side also tested" do
+      assert_equal @a.(:row).posward, @a.(:row).n.opposite_side
+      assert_equal @a.(:row).negward, @a.(:row).p.opposite_side
+    end
+
+    it "has #to_s" do
+      assert @a.(:row).to_s.starts_with? "#<YTed::Zz::SidePair"
+    end
+
+    describe 'more advanced zz object behavior' do
+      it "has #same_side" do
+        zz = @ç.new
+        assert_equal zz.(:row).p, @a.(:row).p.same_side( of: zz )
+        assert_equal zz.(:row).n, @a.(:row).n.same_side( of: zz )
+      end
+
+      it "works" do
+        a, b, c = @ç.new, @ç.new, @ç.new
+        assert ( b.(:row).posward << c ).nil?
+        assert_equal c, b.(:row).P
+        assert_equal b, c.(:row).N
+        assert ( b.(:row).negward << a ).nil?
+        assert_equal a, b.(:row).N
+        assert_equal b, a.(:row).P
+        assert_equal b, c.(:row).negward.unlink
+        assert_equal b, a.(:row).posward.unlink
+        a.(:row) >> b >> c
+        assert_equal b, a.(:row).posward * c
+        assert_equal b, b.(:row) * c
+        assert_equal b, a.(:row).P
+        assert_equal c, b.(:row).P
+        # TODO:
+        # assert_equal [a, c], b.connections.map { |side| side.neighbor }
+        # assert_equal [a, c], b.neighbors
+        # assert_equal [ b.(:row).negward ], b.connections( to: a )
+        # assert_equal [ b.(:row).posward ], b.connections( to: c )
+        # TODO: Rename YTed to Zz
+      end
+    end
+  end
+end

data/yzz.gemspec

@@ -0,0 +1,23 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'yzz/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "yzz"
+  spec.version       = Yzz::VERSION
+  spec.authors       = ["boris"]
+  spec.email         = ["\"boris@iis.sinica.edu.tw\""]
+  spec.description   = %q{A zz structure domain model.}
+  spec.summary       = %q{Yzz module is a mixin that imbues object with zz qualities.}
+  spec.homepage      = ""
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files`.split($/)
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 1.3"
+  spec.add_development_dependency "rake"
+end

metadata

@@ -0,0 +1,84 @@
+--- !ruby/object:Gem::Specification
+name: yzz
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- boris
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-04-28 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.3'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: A zz structure domain model.
+email:
+- '"boris@iis.sinica.edu.tw"'
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/yzz.rb
+- lib/yzz/side.rb
+- lib/yzz/side_pair.rb
+- lib/yzz/version.rb
+- test/yzz_test.rb
+- yzz.gemspec
+homepage: ''
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.0.0
+signing_key: 
+specification_version: 4
+summary: Yzz module is a mixin that imbues object with zz qualities.
+test_files:
+- test/yzz_test.rb