backstack 0.1.0

data/.document

@@ -0,0 +1,5 @@
+lib/**/*.rb
+bin/*
+- 
+features/**/*.feature
+LICENSE.txt

data/Gemfile

@@ -0,0 +1,13 @@
+source "http://rubygems.org"
+# Add dependencies required to use your gem here.
+# Example:
+#   gem "activesupport", ">= 2.3.5"
+
+# Add dependencies to develop your gem here.
+# Include everything needed to run rake, tests, features, etc.
+group :development do
+  gem "minitest", ">= 0"
+  gem "bundler", "~> 1.0.0"
+  gem "jeweler", "~> 1.6.0"
+  gem "rcov", ">= 0"
+end

data/Gemfile.lock

@@ -0,0 +1,20 @@
+GEM
+  remote: http://rubygems.org/
+  specs:
+    git (1.2.5)
+    jeweler (1.6.3)
+      bundler (~> 1.0)
+      git (>= 1.2.5)
+      rake
+    minitest (2.3.1)
+    rake (0.9.2)
+    rcov (0.9.9)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  bundler (~> 1.0.0)
+  jeweler (~> 1.6.0)
+  minitest
+  rcov

data/LICENSE.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2011 Kevin Swope
+
+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.rdoc

@@ -0,0 +1,38 @@
+= backstack
+
+This is in extreme beta.  The docs are not yet written and will
+probably be supplimented with an illustrated blog posting.
+
+Backstack is a gem plugin (currently just rails) that dynamically and
+intelligently generates a "back" link, or breadcrumb trail.  Sounds so
+simple, why wouldn't it be?
+
+To get a quick idea of what it does, goes to the test/rails_root
+directory and 'rails server'
+
+The plugin guts are in:
+https://github.com/kswope/backstack/blob/master/lib/backstack.rb and
+https://github.com/kswope/backstack/blob/master/lib/backstacklib.rb
+
+Non-plugin  tests are in:
+https://github.com/kswope/backstack/blob/master/test/neutral/test_backstacklib.rb
+
+Most rails tests are in:
+https://github.com/kswope/backstack/blob/master/test/rails_root/test/integration/backstack_test.rb
+
+
+== Contributing to backstack
+ 
+* Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet
+* Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it
+* Fork the project
+* Start a feature/bugfix branch
+* Commit and push until you are happy with your contribution
+* Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
+* Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.
+
+== Copyright
+
+Copyright (c) 2011 Kevin Swope. See LICENSE.txt for
+further details.
+

data/Rakefile

@@ -0,0 +1,54 @@
+# encoding: utf-8
+
+require 'rubygems'
+require 'bundler'
+
+begin
+  Bundler.setup(:default, :development)
+rescue Bundler::BundlerError => e
+  $stderr.puts e.message
+  $stderr.puts "Run `bundle install` to install missing gems"
+  exit e.status_code
+end
+
+require 'rake'
+
+require 'jeweler'
+Jeweler::Tasks.new do |gem|
+  # gem is a Gem::Specification... see http://docs.rubygems.org/read/chapter/20 for more options
+  gem.name = "backstack"
+  gem.homepage = "http://github.com/kswope/backstack"
+  gem.license = "MIT"
+  gem.summary = %Q{Rails plugin used to generate "back" links or a breadcrumb trail.}
+  gem.description = %Q{Rails plugin used to dynamically and intelligently generate "back" links or a breadcrumb trail.}
+  gem.email = "git-kevdev@snkmail.com"
+  gem.authors = ["Kevin Swope"]
+  # dependencies defined in Gemfile
+end
+Jeweler::RubygemsDotOrgTasks.new
+
+task :default => :test
+task :test => [:test_neutral, :test_rails]
+
+require 'rake/testtask'
+Rake::TestTask.new(:test_neutral) do |test|
+  test.libs << 'lib' << 'test/neutral'
+  test.pattern = 'test/neutral/**/test_*.rb'
+  test.verbose = true
+end
+
+# Bundler.setup (above) sets this and ruins rail's chance for loading
+# properly in the test below.  Somebody tell me why a gem is setting
+# ENV variables.
+ENV['BUNDLE_GEMFILE'] = nil
+
+desc "Run tests in rails root"
+rails_root = "test/rails_root"
+command = "rake"
+task :test_rails do |t|
+  chdir rails_root do
+    puts "*** descending into #{rails_root} and running '#{command}'"
+    system command
+  end
+end
+

data/VERSION

@@ -0,0 +1 @@
+0.1.0

data/backstack.gemspec

@@ -0,0 +1,127 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE DIRECTLY
+# Instead, edit Jeweler::Tasks in Rakefile, and run 'rake gemspec'
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{backstack}
+  s.version = "0.1.0"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Kevin Swope"]
+  s.date = %q{2011-07-09}
+  s.description = %q{Rails plugin used to dynamically and intelligently generate "back" links or a breadcrumb trail.}
+  s.email = %q{git-kevdev@snkmail.com}
+  s.extra_rdoc_files = [
+    "LICENSE.txt",
+    "README.rdoc"
+  ]
+  s.files = [
+    ".document",
+    "Gemfile",
+    "Gemfile.lock",
+    "LICENSE.txt",
+    "README.rdoc",
+    "Rakefile",
+    "VERSION",
+    "art/bowling_pins.graffle",
+    "backstack.gemspec",
+    "lib/backstack.rb",
+    "lib/backstacklib.rb",
+    "test/neutral/helper.rb",
+    "test/neutral/test_backstacklib.rb",
+    "test/rails_root/.gitignore",
+    "test/rails_root/Gemfile",
+    "test/rails_root/Gemfile.lock",
+    "test/rails_root/README",
+    "test/rails_root/Rakefile",
+    "test/rails_root/app/controllers/application_controller.rb",
+    "test/rails_root/app/controllers/c1_controller.rb",
+    "test/rails_root/app/controllers/c2_controller.rb",
+    "test/rails_root/app/controllers/c3_controller.rb",
+    "test/rails_root/app/controllers/c4_controller.rb",
+    "test/rails_root/app/helpers/application_helper.rb",
+    "test/rails_root/app/helpers/c1_helper.rb",
+    "test/rails_root/app/helpers/c2_helper.rb",
+    "test/rails_root/app/helpers/c3_helper.rb",
+    "test/rails_root/app/helpers/c4_helper.rb",
+    "test/rails_root/app/views/c1/a.html.erb",
+    "test/rails_root/app/views/c2/b.html.erb",
+    "test/rails_root/app/views/c2/c.html.erb",
+    "test/rails_root/app/views/c3/d.html.erb",
+    "test/rails_root/app/views/c3/e.html.erb",
+    "test/rails_root/app/views/c3/f.html.erb",
+    "test/rails_root/app/views/c4/g.html.erb",
+    "test/rails_root/app/views/c4/h.html.erb",
+    "test/rails_root/app/views/c4/i.html.erb",
+    "test/rails_root/app/views/c4/j.html.erb",
+    "test/rails_root/app/views/layouts/_pins.html.erb",
+    "test/rails_root/app/views/layouts/application.html.erb",
+    "test/rails_root/config.ru",
+    "test/rails_root/config/application.rb",
+    "test/rails_root/config/boot.rb",
+    "test/rails_root/config/environment.rb",
+    "test/rails_root/config/environments/development.rb",
+    "test/rails_root/config/environments/production.rb",
+    "test/rails_root/config/environments/test.rb",
+    "test/rails_root/config/initializers/backtrace_silencers.rb",
+    "test/rails_root/config/initializers/inflections.rb",
+    "test/rails_root/config/initializers/mime_types.rb",
+    "test/rails_root/config/initializers/secret_token.rb",
+    "test/rails_root/config/initializers/session_store.rb",
+    "test/rails_root/config/locales/en.yml",
+    "test/rails_root/config/routes.rb",
+    "test/rails_root/db/seeds.rb",
+    "test/rails_root/lib/tasks/.gitkeep",
+    "test/rails_root/public/404.html",
+    "test/rails_root/public/422.html",
+    "test/rails_root/public/500.html",
+    "test/rails_root/public/favicon.ico",
+    "test/rails_root/public/images/rails.png",
+    "test/rails_root/public/javascripts/.gitkeep",
+    "test/rails_root/public/javascripts/application.js",
+    "test/rails_root/public/robots.txt",
+    "test/rails_root/public/stylesheets/.gitkeep",
+    "test/rails_root/public/stylesheets/application.css",
+    "test/rails_root/script/rails",
+    "test/rails_root/test/functional/c1_controller_test.rb",
+    "test/rails_root/test/functional/c2_controller_test.rb",
+    "test/rails_root/test/functional/c3_controller_test.rb",
+    "test/rails_root/test/functional/c4_controller_test.rb",
+    "test/rails_root/test/integration/backstack_test.rb",
+    "test/rails_root/test/performance/browsing_test.rb",
+    "test/rails_root/test/test_helper.rb",
+    "test/rails_root/test/unit/helpers/c1_helper_test.rb",
+    "test/rails_root/test/unit/helpers/c2_helper_test.rb",
+    "test/rails_root/test/unit/helpers/c3_helper_test.rb",
+    "test/rails_root/test/unit/helpers/c4_helper_test.rb",
+    "test/rails_root/vendor/plugins/.gitkeep"
+  ]
+  s.homepage = %q{http://github.com/kswope/backstack}
+  s.licenses = ["MIT"]
+  s.require_paths = ["lib"]
+  s.rubygems_version = %q{1.6.2}
+  s.summary = %q{Rails plugin used to generate "back" links or a breadcrumb trail.}
+
+  if s.respond_to? :specification_version then
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
+      s.add_development_dependency(%q<minitest>, [">= 0"])
+      s.add_development_dependency(%q<bundler>, ["~> 1.0.0"])
+      s.add_development_dependency(%q<jeweler>, ["~> 1.6.0"])
+      s.add_development_dependency(%q<rcov>, [">= 0"])
+    else
+      s.add_dependency(%q<minitest>, [">= 0"])
+      s.add_dependency(%q<bundler>, ["~> 1.0.0"])
+      s.add_dependency(%q<jeweler>, ["~> 1.6.0"])
+      s.add_dependency(%q<rcov>, [">= 0"])
+    end
+  else
+    s.add_dependency(%q<minitest>, [">= 0"])
+    s.add_dependency(%q<bundler>, ["~> 1.0.0"])
+    s.add_dependency(%q<jeweler>, ["~> 1.6.0"])
+    s.add_dependency(%q<rcov>, [">= 0"])
+  end
+end
+

data/lib/backstack.rb

@@ -0,0 +1,161 @@
+require "backstacklib"
+
+
+module BackStack
+
+  def self.included(base)
+    base.send :extend, ClassMethods
+  end
+
+  module InstanceMethods
+    # maybe later
+  end
+
+  module ClassMethods
+
+    include BackStackLib
+
+    # Normalize controller and action to "controller#action", unless
+    # second param already has "#".  This is up here in the class methods
+    # because normalizing controller/actions is utilized both here
+    # and in the ApplicationControllers objects
+    def bs_action_normal(controller, x)
+      x.to_s.index("#") ? "#{x}" : "#{controller}##{x}"
+    end
+
+    # This is the "macro" you put at the top of your controllers
+    def backstack(edges)
+
+      # Note: its a little hard to follow but @bs_graph is a instance
+      # variable of the class ApplicationController::Base (not an
+      # object of AC::B).  There will only be one in the rails runtime,
+      # and may behave differently depending on whether we're in dev
+      # or prod mode, because dev mode reloads classes with each
+      # request, and prod hopefully doesn't.  We'll write this module
+      # to work correctly under both circumstances.
+
+      # In rails we're going to use the string "controller#action" to
+      # identify the page.  We're NOT going to let bs_add_edges
+      # normalize that because it might be used for other frameworks.
+      # If the user didn't pass in the controller we'll add it here.
+      # The complete value should look like "controller#action", for
+      # both keys and values.
+      normalizer = lambda {|x| bs_action_normal(controller_name, x) }
+
+      # Add new edges to existing graph, and extract out the names.
+      # bs_add_edges will also accumulate names for us.
+      @bs_graph, @bs_names = bs_add_edges(@bs_graph, @bs_names, 
+                                          edges, normalizer)
+
+    end
+
+    # So ApplicationController methods can reach @bs_graph and
+    # @bs_names.  I wanted to use @@bs_graph, so both AC::B and the
+    # instance of AC could reach it, but this mysteriously breaks
+    # rails routing!  So here are getters than we can use and access
+    # from the AC instance as self.class.get_bs_graph.  RoR can be a
+    # real pit of dispair sometimes.
+    def get_bs_graph
+      @bs_graph
+    end
+
+    def get_bs_names
+      @bs_names
+    end
+
+    send :include, InstanceMethods
+
+  end
+
+  # These functions will be available in views
+  module Helpers
+
+    def backstack_link(text, *args)
+
+      bs_graph = controller.class.get_bs_graph # found it! lol
+
+      # If we don't have these we can't do anything
+      return unless session[:bs_stack] && bs_graph
+
+      # If the top of stack (current location) is stacked on top of
+      # link the graph indicates it closes to, then create a link from
+      # that.
+      current = session[:bs_stack][-1]
+      previous = session[:bs_stack][-2]
+
+      if current && previous && bs_graph[current.first].include?(previous.first)
+        return link_to(text, previous.second, *args)
+      end
+
+    end
+
+    # Iterator to build breadcrumb trails
+    def backstack_trail
+
+      hashify = lambda{|x|
+        c, a = x[0].split /#/
+        {:controller => c, :action => a, :fullpath => x[1], :name => x[2]}
+      }
+
+      if block_given?
+        session[:bs_stack].each { |x| yield hashify.call(x) }
+      else # return an array
+        session[:bs_stack].map { |x| hashify.call(x) }        
+      end
+
+    end
+
+  end
+
+
+end
+
+
+ActionController::Base.send :include, BackStack
+ActionView::Helpers.send :include, BackStack::Helpers
+
+
+# note, do not do this here:
+# class ApplicationController < ActionController::Base
+# it will prevent application_controller.rb from loading
+class ActionController::Base
+
+  include BackStackLib
+
+  # Debugging method for calling inside controller, probably best as
+  # before_filter :backstack_dump
+  # in application_controller.rb
+  def backstack_dump
+
+    # don't accidentally run in production
+    return unless Rails.env == 'development'
+
+    puts "=== backstack_dump() " + '=' * 50
+
+    puts "backstack graph: #{self.class.get_bs_graph}"
+    puts "backstack names: #{self.class.get_bs_names}"
+    puts "backstack stack: #{session[:bs_stack]}"
+
+    puts '=' * 71
+
+  end
+
+
+
+  def bs_pusher
+
+    action = self.class.bs_action_normal(controller_name, action_name)
+    
+    session[:bs_stack] = bs_push(self.class.get_bs_graph,
+                                 session[:bs_stack], 
+                                 action,
+                                 request.fullpath,
+                                 self.class.get_bs_names[action])
+
+  end
+
+  before_filter :bs_pusher
+
+end
+
+

data/lib/backstacklib.rb

@@ -0,0 +1,115 @@
+# BackStackLib should know nothing about rails, sinatra or whatever
+# framework this gem is supporting.  It should also have no storage of
+# its own.  Keep it that way.
+module BackStackLib
+
+  # Combine a "graph", described by connected nodes, in hash form,
+  # with another.
+  #
+  # Input graph must be normalized and described like this (could also
+  # be {}).  Normalized means key is not a collection data type (not
+  # an array) but the value IS an array.
+  #
+  # In other words, don't pass as the first argument anything that hasn't
+  # been already normalized by this method, or use {} to start
+  #
+  # An example of normalized is {:b=>[:a], :c=>[:a], :z=>[:a, :x]}
+  # which reads "b is connected to a and c is connected to a and z is
+  # connected to both :a and :x", or more relevantly "b closes to a
+  # and c closes to a and z closes to both a and x".
+  #
+  # When this method is run it combines the *already* normalized graph
+  # (could be {}), with a another graph description, which for
+  # convenience can be in more of a shorthand, like {[:f, :e, :d] =>
+  # :c}, which reads "f, e, and d all close to c"
+  #
+  # The returned value will be a combination of the graphs, in a
+  # normalized form, for example {:b=>[:a], :c=>[:a], :f=>[:b, :c],
+  # :e=>[:b, :c], :d=>[:b, :c]}
+  #
+  # Note: the shorthand form of the edges parameter can be taken as far as
+  # something like this {[:d, :e, :f] => [:b, :c]}
+  #
+  # New feature: named nodes.  Instead of {:c => :a}, the "key" can be
+  # named like this {{:c => "Charlie"} => :a}.  We're going to remove
+  # those named keys, replace them with just the key, and return them as
+  # the second value
+  #
+  # Decided to allow user to pass a normalizer proc/lambda in to
+  # modify all the keys and values.
+  def bs_add_edges(graph, names, edges, normalizer=nil)
+
+    graph ||= {}
+    names ||= {}
+
+    edges.each do |k,v| # k is a scalar or array, same with v
+
+      # Does this [x].flatten idiom make it less readable?
+      [k].flatten.each do |x|
+
+        # Extract names out into their own hash, and normalize key
+        if x.class == Hash # if its a hash it contains a name
+          names[x.first[0]] = x.first[1]
+          x = x.first[0] # remove name and replace with normal key
+        end
+
+        # Run normalizer on all keys and values of new edges
+        if normalizer
+          x = normalizer.call(x)
+          v = [v].flatten.map{|y| normalizer.call(y)}
+          # also run normalizer on names keys
+          names = Hash[names.map {|k,v| [normalizer.call(k), v]}]
+        end
+
+        # If merge finds dupe keys it will use block to determine
+        # value, which in our case is to combine the two values.
+        graph.merge!(x => [v].flatten) do |key, old_v, new_v|
+          [old_v, new_v].flatten
+        end
+
+      end
+
+    end
+
+    [graph, names]
+
+  end
+
+  # Judging by graph, push onto stack if appropriate.  Pushing doesn't
+  # necessarily build stack up, it might cause a rewind and actually
+  # shrink stack.
+  def bs_push(graph, stack, action, fullpath, name=nil)
+
+    # bs_push might be called before there is a graph or stack
+    graph ||= {}
+    stack ||= []
+
+    element = [action, fullpath, name]
+
+    # if action closes to what's on top of stack, build stack up
+    if graph[action] && stack.last && graph[action].include?(stack.last.first)
+      stack.push element
+      return stack
+    end
+
+    # if action already in stack rewind *past* it and place on stack
+    # (we rewind past it and push because the path part might be
+    # different)
+    if i = stack.find_index {|x| x.first == action}
+      stack = stack.slice(0,i)
+      stack.push element
+      return stack
+    end
+
+    # if none of the clever stuff above happened then just replace top
+    # of stack
+    if stack.empty?
+      return [element]
+    else
+      stack[-1] = element
+      return stack
+    end
+
+  end
+
+end

data/test/neutral/helper.rb

@@ -0,0 +1,27 @@
+
+require "backstacklib"
+require 'minitest/autorun'
+
+# All this following stuff is already in the Rakefile, why is it also
+# here jeweler? -kswope
+
+# require 'rubygems'
+# require 'bundler'
+
+# begin
+#   Bundler.setup(:default, :development)
+# rescue Bundler::BundlerError => e
+#   $stderr.puts e.message
+#   $stderr.puts "Run `bundle install` to install missing gems"
+#   exit e.status_code
+# end
+# require 'minitest/unit'
+
+# #$LOAD_PATH.unshift(File.dirname(__FILE__))
+# #$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+# require 'backstacklib'
+
+# class MiniTest::Unit::TestCase
+# end
+
+# MiniTest::Unit.autorun