bracket_tree 0.1.0

data/.gitignore

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

data/.travis.yml

@@ -0,0 +1,7 @@
+language: ruby
+rvm:
+  - 1.9.3
+notifications:
+  email:
+    recipients:
+      - anordman@majorleaguegaming.com

data/Gemfile

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

data/README.md

@@ -0,0 +1,187 @@
+# BracketTree [![Build Status](https://secure.travis-ci.org/agoragames/bracket_tree.png)](http://travis-ci.org/agoragames/bracket_tree)
+
+BracketTree is a bracketing system built around the BracketTree Data Specification,
+which uses a three-section data structure built on top of JSON to convey the visual
+representation, progression logic, and seed mapping in a serializable format.  For
+more information on the data specification, please read the 
+[BracketTree Data Specification](https://github.com/agoragames/bracket_tree/wiki/BracketTree-Data-Specification).
+
+BracketTree builds upon the specification by providing Ruby classes for programmatically
+generating templates for brackets and generating brackets from those templates. It
+also contains a number of common bracket template types like Single Elimination and
+Double Elimination, with the ability to put your own extensions on their logic and
+representation.
+
+BracketTree is broken into two fundamental components: Templates and Brackets.
+
+## BracketTree Templates
+
+Templates in BracketTree are the instructions on how a Bracket is to be constructed,
+containing the three components of a BracketTree specification:
+
+- `starting_seats`
+- `seats`
+- `nodes`
+
+BracketTree comes with a number of default templates included. To access one, call
+the `by_size` method on the template class.  For example, to generate an eight-player,
+double-elimination bracket template:
+
+```
+template = BracketTree::Template::DoubleElimination.by_size(8)
+```
+
+The resulting BracketTree::Template::DoubleElimination object contains the necessary
+details to create a bracket using its information.
+
+If you need to make customizations, you can manipulate the template per object, like
+in this example where we reverse the seed order of the template:
+
+```
+template = BracketTree::Template::DoubleElimination.by_size(8)
+template.starting_seats # => [1,3,5,7,9,11,13,15]
+template.starting_seats = [15,13,11,9,7,5,3,1]
+```
+
+However, you may wish to generate your own Template class. To do so, subclass the 
+`BracketTree::Template::Base` class and define `location` to be the location of the
+JSON files that conform to the [BracketTree Data Specification](https://github.com/agoragames/bracket_tree/wiki/BracketTree-Data-Specification).
+In this example, we create a class for the MLG Double Elimination format, where the 
+templates are located in the `mlg_double` directory:
+
+```
+class BracketTree::Template::MLGDouble < BracketTree::Template::Base
+  def location ; File.join File.dirname(__FILE__), 'mlg_double' ; end
+end
+```
+
+If you happen to have the JSON already stored as a hash and want to create a Template
+from that, you can use the `from_json` method to generate a new template:
+
+```
+hash = {
+  'startingSeats' => [1,3,5,7],
+  'seats' => [
+    { 'position' => 4 },
+    { 'position' => 2 },
+    { 'position' => 6 },
+    { 'position' => 1 },
+    { 'position' => 3 },
+    { 'position' => 5 },
+    { 'position' => 7 }
+  ],
+  'nodes' => []
+}
+
+template = BracketTree::Template::Base.from_json hash
+```
+
+## BracketTree Brackets
+
+Brackets are derived from BracketTree::Bracket::Base or its sub-classes.  BracketTree
+provides two subclasses, `BracketTree::Bracket::SingleElimination` and 
+`BracketTree::Bracket::DoubleElimination`, to quickly generate blank brackets based on
+the popular standard formats:
+
+```
+single_elim_bracket = BracketTree::Bracket::SingleElimination.by_size 4
+double_elim_bracket = BracketTree::Bracket::DoubleElimination.by_size 64
+```
+
+For those who wish to create a custom bracket Template class, doing so is straightforward.
+Create a subclass of `BracketTree::Bracket::Base` and use the `template` method to
+specify your template class, like the below `MLGDouble` bracket:
+
+```
+class MLGDoubleTemplate < BracketTree::Template::Base
+  def self.location
+    File.join File.dirname(__FILE__), 'templates', 'mlg_double'
+  end
+end
+
+class MLGDouble < BracketTree::Bracket::Base
+  template MLGDoubleTemplate
+end
+```
+
+Once we've generated a bracket from a template, we're able to start populating and
+controlling the bracket information.  All bracket objects derive from 
+`BracketTree::Bracket::Base`. If you generate a bracket from this class, it will
+have a blank binary tree.  If you happen to know the math involved in hand-crafting a
+binary tree reflective of your particular tournament type, then you could use `add` 
+to start adding nodes in the bracket:
+
+```
+bracket = BracketTree::Bracket::Base.new
+bracket.add 2, { player: 'player1' }
+bracket.add 1, { player: 'player1' }
+bracket.add 3, { player: 'player2' }
+```
+
+While this is not the most difficult thing to do on a small scale, doing this for
+larger tournaments is extremely cumbersome, so we generate Brackets from Templates
+instead.  Please review 'BracketTree Templates' for more information on this.
+
+When you generate a blank bracket from a template, it adds empty hashes as 
+placeholders for all of the seats in the Bracket.  To replace these placeholders, use
+the `replace` method with the seat position and the object you would like to replace
+it with.
+
+In this example, we handle seeding a two-player, single elimination bracket:
+
+```
+bracket = BracketTree::Bracket::SingleElimination.by_size 2
+bracket.replace 1, { player: 'player1' }
+bracket.replace 3, { player: 'player3' }
+```
+
+Again, this is not the most difficult thing to do, but seeding is a pretty common
+thing.  For actions like this, use the `seed` method.
+
+Under the hood, each seat position in the Bracket is held as the payload of a `Node`
+object.  This contains the binary tree traversal controls, as well as a `payload`
+property that contains the object being stored at the node.  When using any iterator
+methods from `Enumerable` on a bracket, know that they are in the context of a `Node`
+ rather than whatever you have chosen to store inside the `Node`.  This allows the 
+following:
+
+```
+bracket = BracketTree::Bracket::SingleElimination.by_size 2
+bracket.replace 2, { player: 'player1 }
+
+node = bracket.at(2)
+node.payload # => { player: 'player1' }
+node.payload[:seed_value] = 3
+```
+
+## Example
+
+Below is an example of creating a 32-player, double elimination tournament bracket
+template, generating a blank bracket, seeding from an array of players, and filling
+some results from round 1:
+
+```
+players = []
+32.times do |n| 
+  players << { login: "Player#{n}", seed_value: n }
+end
+
+bracket = BracketTree::Bracket::DoubleElimination.by_size 32
+bracket.seed players
+
+# Player1 wins Rd 1
+bracket.match_winner(1)
+bracket.at(1).payload[:winner] = true
+
+# Player3 wins Rd 1
+bracket.match_winner(5)
+bracket.at(1).payload[:winner] = true
+```
+
+## Contributions
+
+Contributions are awesome.  Feature branch pull requests are the preferred method.
+
+## Author
+
+Written by [Andrew Nordman](http://github.com/cadwallion)

data/Rakefile

@@ -0,0 +1,8 @@
+require "bundler/gem_tasks"
+require 'rspec/core/rake_task'
+
+
+task :default => :spec
+
+desc "Run specs"
+RSpec::Core::RakeTask.new(:spec)

data/bracket_tree.gemspec

@@ -0,0 +1,20 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+
+Gem::Specification.new do |s|
+  s.name        = "bracket_tree"
+  s.version     = '0.1.0'
+  s.authors     = ["Andrew Nordman"]
+  s.email       = ["anordman@majorleaguegaming.com"]
+  s.homepage    = "https://github.com/agoragames/bracket_tree"
+  s.summary     = %q{Binary Tree based bracketing system}
+  s.description = %q{Binary Tree based bracketing system}
+
+  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"
+  s.add_development_dependency "rake"
+end

data/lib/bracket_tree.rb

@@ -0,0 +1,9 @@
+require 'json'
+require 'bracket_tree/match'
+require 'bracket_tree/bracket'
+require 'bracket_tree/template'
+require 'bracket_tree/templates/double_elimination'
+require 'bracket_tree/templates/single_elimination'
+
+module BracketTree
+end

data/lib/bracket_tree/bracket.rb

@@ -0,0 +1,12 @@
+require 'bracket_tree/node'
+require 'bracket_tree/bracket/base'
+module BracketTree
+  module Bracket
+    class NoSeedOrderError < Exception ; end
+    class SeedLimitExceededError < Exception ; end
+
+    autoload :Base,               'bracket_tree/bracket/base'
+    autoload :SingleElimination,  'bracket_tree/bracket/single_elimination'
+    autoload :DoubleElimination,  'bracket_tree/bracket/double_elimination'
+  end
+end

data/lib/bracket_tree/bracket/base.rb

@@ -0,0 +1,228 @@
+module BracketTree
+  module Bracket
+    # Basic bracketing functionality.  If you wish to create a custom bracket type,
+    # inherit from this class to provide easy access to bracketing.
+    #
+    # Example:
+    #   class MLGDouble < BracketTree::Bracket::Base
+    #     template BracketTree::Template::DoubleElimination
+    #   end
+    #   
+    #   bracket = MLGDouble.by_size 8
+    #
+    # This creates a bracket based on the standard double elimination template class.
+    # The template parameter can be any class that inherits from BracketTree::Template::Base,
+    # though.
+    #
+    #  class MLGDoubleTemplate < BracketTree::Template::Base
+    #    def self.location
+    #      File.join File.dirname(__FILE__), 'templates', 'mlg_double'
+    #    end
+    #  end
+    #
+    #  class MLGDouble < BracketTree::Bracket::Base
+    #    template MLGDoubleTemplate
+    #  end
+    class Base
+      class NoTemplateError < Exception ; end
+
+      class << self
+        def by_size size, options = {}
+          generate_from_template @template, size
+        end
+
+        def template class_name
+          @template = class_name
+        end
+
+        # Generates a blank bracket object from the passed Template class for the 
+        # passed size
+        #
+        # @param BracketTree::Template::Base template - the Template the bracket is
+        #   based on
+        # @param Fixnum size - bracket size
+        # @return BracketTree::Bracket::Base bracket - a blank bracket with hash placeholders
+        def generate_from_template template, size
+          template = template.by_size size
+          bracket = new(matches: template.matches, seed_order: template.seed_order)
+
+          template.seats.each do |position|
+            bracket.add position, {}
+          end
+
+          bracket
+        end
+      end
+
+      include Enumerable
+      attr_accessor :root, :seed_order, :matches, :insertion_order
+
+      def initialize options = {}
+        @insertion_order = []
+        @matches = []
+
+        if options[:matches]
+          options[:matches].each do |m|
+            @matches << Match.new(m)
+          end
+        end
+
+        @seed_order = options[:seed_order] if options[:seed_order]
+      end
+
+      # Adds a Node at the given position, setting the data as the payload. Maps to
+      # binary tree under the hood.  The `data` can be any serializable object.
+      #
+      # @param Fixnum position - Seat position to add
+      # @param Object data - the player object to store in the Seat position
+      def add position, data
+        node = Node.new position, data
+        @insertion_order << position
+
+        if @root.nil?
+          @root = node
+        else
+          current = @root
+          loop do
+            if node.position < current.position
+              if current.left.nil?
+                current.left = node
+                break
+              else
+                current = current.left
+              end
+            elsif node.position > current.position
+              if current.right.nil?
+                current.right = node
+                break
+              else
+                current = current.right
+              end
+            else
+              break
+            end
+          end
+        end
+      end
+
+      # Replaces the data at a given node position with new payload. This is useful
+      # for updating bracket data, replacing placeholders with actual data, seeding,
+      # etc..
+      #
+      # @param [Fixnum] position - the node position to replace
+      # @param payload - the new payload object to replace
+      def replace position, payload
+        node = at position
+        if node
+          node.payload = payload
+          true
+        else
+          nil
+        end
+      end
+
+      # Seeds bracket based on `seed_order` value of bracket.  Provide an iterator
+      # with players that will be inserted in the appropriate location.  Will raise a
+      # SeedLimitExceededError if too many players are sent, and a NoSeedOrderError if
+      # the `seed_order` attribute is nil
+      #
+      # @param [Enumerable] players - players to be seeded
+      def seed players
+        if @seed_order.nil?
+          raise NoSeedOrderError, 'Bracket does not have a seed order.'
+        elsif players.size > @seed_order.size
+          raise SeedLimitExceededError, 'cannot seed more players than seed order list.'
+        else
+          @seed_order.each do |position|
+            replace position, players.shift
+          end
+        end
+      end
+
+      def winner
+        @root.payload
+      end
+
+      def each(&block)
+        in_order(@root, block)
+      end
+
+      def to_h
+        @root.to_h
+      end
+
+      # Array of Seats mapping to the individual positions of the bracket tree. The
+      # order of the nodes is important, as insertion in this order maintains the
+      # binary tree
+      #
+      # @return Array seats
+      def seats
+        entries.sort_by { |node| @insertion_order.index(node.position) }
+      end
+
+      alias_method :to_a, :seats
+
+      def at position
+        find { |n| n.position == position }
+      end
+
+      alias_method :size, :count
+
+      # Progresses the bracket by using the stored `matches` to copy data to the winning
+      # and losing seats.  This facilitates match progression without manually
+      # manipulating bracket positions
+      #
+      # @param Fixnum seat - winning seat position
+      # @return Boolean result - result of progression
+      def match_winner seat
+        match = @matches.find { |m| m.include? seat }
+
+        if match
+          losing_seat = match.seats.find { |s| s != seat }
+
+          if match.winner_to
+            replace match.winner_to, at(seat).payload
+          end
+
+          if match.loser_to
+            replace match.loser_to, at(losing_seat).payload
+          end
+
+          return true
+        else
+          return false
+        end
+      end
+
+      # Inverse of `match_winner`, progresses the bracket based on seat. See `match_winner`
+      # for more details
+      #
+      # @param Fixnum seat - losing seat position
+      # @return Boolean result - result of progression
+      def match_loser seat
+        match = @matches.find { |m| m.include? seat }
+        
+        if match
+          winning_seat = match.seats.find { |s| s != seat }
+          match_winner winning_seat
+        else
+          return false
+        end
+      end
+
+      def in_order(node, block)
+        if node
+          unless node.left.nil?
+            in_order(node.left, block)
+          end
+
+          block.call(node)
+
+          unless node.right.nil?
+            in_order(node.right, block)
+          end
+        end
+      end
+    end
+  end
+end