pacer-jogger 0.0.1

data/.document

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

data/Gemfile

@@ -0,0 +1,9 @@
+source "http://rubygems.org"
+
+group :development do
+  gem "shoulda"
+  gem "bundler", "~> 1.0.0"
+  gem "jeweler", "~> 1.7.0"
+  gem "rspec"
+  gem "yard"
+end

data/Gemfile.lock

@@ -0,0 +1,34 @@
+GEM
+  remote: http://rubygems.org/
+  specs:
+    diff-lcs (1.1.3)
+    git (1.2.5)
+    jeweler (1.7.0)
+      bundler (~> 1.0)
+      git (>= 1.2.5)
+      rake
+      rdoc
+    json (1.6.5)
+    rake (0.9.2.2)
+    rdoc (3.12)
+      json (~> 1.4)
+    rspec (2.8.0)
+      rspec-core (~> 2.8.0)
+      rspec-expectations (~> 2.8.0)
+      rspec-mocks (~> 2.8.0)
+    rspec-core (2.8.0)
+    rspec-expectations (2.8.0)
+      diff-lcs (~> 1.1.2)
+    rspec-mocks (2.8.0)
+    shoulda (2.11.3)
+    yard (0.7.4)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  bundler (~> 1.0.0)
+  jeweler (~> 1.7.0)
+  rspec
+  shoulda
+  yard

data/LICENSE.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2012 Jannis Hermanns
+
+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.markdown

@@ -0,0 +1,90 @@
+# Jogger
+
+Jogger is a JRuby library that enables lazy people to do very expressive graph traversals with the great [pacer gem](https://github.com/pangloss/pacer). If you don't know what the pacer gem is, you should probably not be here and check pacer out first.
+
+# What does it do?
+
+Jogger does two things:
+
+1. Keep the current pacer traversal in an instance variable and allow for method chaining as well as changing the internal state of the traversal
+2. Allows you to group together parts of a traversal (single pipes or groups of them) and give them a name. Named traversals. Helps to stay DRY.
+
+The former is really just a syntax thing, whereas the latter can help you a great deal modeling semantics of your business logic as parts of traversals. These sentences confuse me, so I will give you examples.
+
+# Example time!
+
+## 1. Keep track of the current traversal
+
+To demonstrate why point 1) in the list above can be useful, look at this traversal. It helps me find out what movies my female friends like the most, so I can impress them in a conversation:
+
+    t = my_pacer_vertex.in(:friends)
+    t = t.filter{ |v| v.properties['gender'] == 'female}
+    t = t.out(:likes)
+    t = t.filter{ |v| v.properties['type'] == 'Movie' }
+    t = t.group_count{ |v| v }
+    t = t.sort_by{ |v, c| -c }
+
+Since I'm a very lazy person, I would prefer to write it a little shorter. Especially, since these multi step traversals are a pattern I found in our code at [moviepilot.com](http://moviepilot.com)) a lot.
+
+So here's the Jogger way of expressing the same traversal:
+
+    t = Jogger.new(my_pacer_vertex)
+    t.in(:friends)
+    t.filter{ |v| v.properties['gender'] == 'female' }
+    t.out(:likes)
+    t.filter{ |v| v.properties['type'] == 'Movie' }
+    t.group_count{ |v| v }
+    t.sort_by{ |v, c| -c }
+
+See what I did there? Jogger keeps the current pacer traversal and forwards all method calls to that traversal, and then returns itself. So you could also write (in jogger as well as pacer):
+
+       Jogger.new(my_pacer_node).in(:friends).filter{ … }.out(:likes).group_count{…}
+
+Just saying, you can chain your methods, but I don't like it because I can only focus on 72 characters per line at max. If you want to access the current traversal, just call `result` on your Jogger instance.
+
+## 2. Named traversals
+
+So that traversal above, traversing from a node to all its friends, is pretty simple, but it could be simpler. Especially if it does things that you want to reuse in many other places. If you would explain the traveral to somebody, you'd say something along the lines of "The most popular movies amongst my friends, but only girls". How cool would it be if I just had to write this:
+
+    t = Jogger.new(my_pacer_vertex)
+    t.friends(:female)
+    t.top_list(:movies)
+
+No problem. Just define a few named traversals that do exactly this.
+
+    class Jogger
+      module NamedTraversals
+        
+        # Traverse to somebody's woman friends
+        def self.friends(current_traversal, gender)
+          t = current_traversal.in(:friends)
+          t = t.filter{|v| v.properties['gender'] == gender}
+        end
+        
+        # Group and sort
+        def self.top_list(current_traversal, type)
+          t = current_traversal.out(type)
+          t = t.filter{ |v| v.properties['type'] == 'Movie' }
+          t = t.group_count{ |v| v }
+          t = t.sort_by{ |v, c| -c }
+        end
+      end
+    end
+
+These are silly examples, but if you look at your traversals I guarantee that you will find repeated patterns all over the place, and Jogger can help you stop repeating these and making the actual traversals much easier on the eyes.
+
+# Installation
+
+First, you need to load pacer and whatever graph db connector you need (we use pacer-neo4j, by the way) and define your named traversals as above. Jogger doesn't include these on purpose. Then, you have to:
+
+    gem install pacer-jogger
+
+and
+
+    require 'jogger'
+
+or if you're using bundler, add this to your Gemfile and bundle:
+
+    gem "pacer-jogger", :require => "jogger"
+
+That's it!

data/Rakefile

@@ -0,0 +1,55 @@
+# 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 'yard'
+require 'rspec/core/rake_task'
+
+require 'jeweler'
+Jeweler::Tasks.new do |gem|
+  gem.name = "pacer-jogger"
+  gem.homepage = "http://github.com/jayniz/jogger"
+  gem.license = "MIT"
+  gem.summary = %Q{Pacer traversals for lazy people}
+  gem.description = %Q{Allows to group traversal fragments/pipes to named traversals and call them like they were pacer pipes.}
+  gem.email = "jannis@gmail.com"
+  gem.authors = ["Jannis Hermanns"]
+  # dependencies defined in Gemfile
+end
+Jeweler::RubygemsDotOrgTasks.new
+
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test'
+  test.pattern = 'test/**/test_*.rb'
+  test.verbose = true
+end
+
+#
+#  RSpec
+#
+task :default => [:spec]
+task :test => [:spec]
+desc "run spec tests"
+RSpec::Core::RakeTask.new('spec') do |t|
+  t.pattern = 'spec/**/*_spec.rb'
+end
+
+
+#
+#  Yard
+#
+desc 'Generate documentation'
+YARD::Rake::YardocTask.new do |t|
+  t.files   = ['lib/**/*.rb', '-', 'LICENSE']
+  t.options = ['--main', 'README.md', '--no-private']
+end
+

data/VERSION

@@ -0,0 +1 @@
+0.0.1

data/lib/jogger.rb

@@ -0,0 +1,80 @@
+
+# Allows to formulate traversals by using predefined
+# named traversals. Also allows for method chaining.
+#
+# All named traversals are defined in {PacerTraversal::NamedTraversals}
+# and new ones can be added using {Jogger.add_traversal}.
+#
+# Instances have a @current_traversal variable that is
+# updated with each chained call of {#traverse}.
+#
+# Beware, it also uses method missing to delegate unknown methods to
+# the current traversal. So after you're done chaining things, you can
+# do more stuff with it after you're done, e.g. call count on it:
+#
+#     t = Jogger.new(some_node)
+#     t.traverse(:some).traverse(:where).count
+#
+# So everything except for {#traverse} is called on the
+# @current_traversal
+class Jogger
+
+
+  # @param initial_node [Object] A node to start out with. Can also be
+  #   the result of a prior traversal you did outside of this class
+  def initialize(initial_node = nil)
+    @current_traversal = initial_node
+  end
+
+  # @return [Hash] The current state of the traversal as returned by pacer
+  def result
+    @current_traversal
+  end
+
+  # Runs the traversal with the same name as the called method on the
+  # current traversal and replaces the current traversal (== the state)
+  # with the results of the named traversal.
+  #
+  # If you call a method that is not a named traversal, the method call
+  # is delegated to the @current traversal. Still, this will return self.
+  # This is useful for more traversals after named routes.
+  #
+  # @return [Jogger] Returns itself so you can chain multiple
+  # {#traverse} calls
+  def method_missing(method, *args, &block)
+    begin
+      traversal_args = [method, args].flatten.compact
+      @current_traversal = Jogger.traverse(@current_traversal, *traversal_args)
+    rescue ArgumentError
+      begin
+        @current_traversal = @current_traversal.send(method, *args, &block)
+      rescue NoMethodError
+        raise "Unknown traversal #{method}"
+      end
+    end
+    self
+  end
+
+  # Runs a named traversal on a given traversal. For example, you
+  # could give it a start node as traversal base and a traversal named
+  # :go_to_all_subscribers to go to all subscribers from that node.
+  #
+  # @param traversal_base [Object] The result of a previous traversal
+  #   or a pacer node you want to begin your traversal with
+  # @param named_traversal [Symbol] The name of the predefined traversal
+  #   you want to run on the traversal_base
+  # @param opts [Object] Whatever you want to pass to the named traverser
+  # @return [Object] The result of the traversal.
+  def self.traverse(traversal_base, named_traversal, opts = nil)
+    raise ArgumentError, "Unknown traversal #{named_traversal}" unless valid_traversal?(named_traversal)
+    args = [named_traversal, traversal_base] + [opts].compact
+    Jogger::NamedTraversals.send(*args)
+  end
+
+  private
+
+  def self.valid_traversal?(traversal)
+    Jogger::NamedTraversals.respond_to? traversal
+  end
+
+end

data/pacer-jogger.gemspec

@@ -0,0 +1,62 @@
+# 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 = "pacer-jogger"
+  s.version = "0.0.1"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Jannis Hermanns"]
+  s.date = "2012-01-23"
+  s.description = "Allows to group traversal fragments/pipes to named traversals and call them like they were pacer pipes."
+  s.email = "jannis@gmail.com"
+  s.extra_rdoc_files = [
+    "LICENSE.txt",
+    "README.markdown"
+  ]
+  s.files = [
+    ".document",
+    "Gemfile",
+    "Gemfile.lock",
+    "LICENSE.txt",
+    "README.markdown",
+    "Rakefile",
+    "VERSION",
+    "lib/jogger.rb",
+    "pacer-jogger.gemspec",
+    "spec/lib/jogger_spec.rb",
+    "spec/spec_helper.rb"
+  ]
+  s.homepage = "http://github.com/jayniz/jogger"
+  s.licenses = ["MIT"]
+  s.require_paths = ["lib"]
+  s.rubygems_version = "1.8.10"
+  s.summary = "Pacer traversals for lazy people"
+
+  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<shoulda>, [">= 0"])
+      s.add_development_dependency(%q<bundler>, ["~> 1.0.0"])
+      s.add_development_dependency(%q<jeweler>, ["~> 1.7.0"])
+      s.add_development_dependency(%q<rspec>, [">= 0"])
+      s.add_development_dependency(%q<yard>, [">= 0"])
+    else
+      s.add_dependency(%q<shoulda>, [">= 0"])
+      s.add_dependency(%q<bundler>, ["~> 1.0.0"])
+      s.add_dependency(%q<jeweler>, ["~> 1.7.0"])
+      s.add_dependency(%q<rspec>, [">= 0"])
+      s.add_dependency(%q<yard>, [">= 0"])
+    end
+  else
+    s.add_dependency(%q<shoulda>, [">= 0"])
+    s.add_dependency(%q<bundler>, ["~> 1.0.0"])
+    s.add_dependency(%q<jeweler>, ["~> 1.7.0"])
+    s.add_dependency(%q<rspec>, [">= 0"])
+    s.add_dependency(%q<yard>, [">= 0"])
+  end
+end
+

data/spec/lib/jogger_spec.rb

@@ -0,0 +1,58 @@
+require_relative '../spec_helper'
+
+class MyFakedPacerResult
+  def some_existing_pacer_method
+    :is_there
+  end
+end
+
+class Jogger
+  module NamedTraversals
+    # This just multiplies the current traversal with x.
+    # In a real use case you would take the current traversal,
+    # traverse some more, and yield the result of your traversal.
+    def self.test_traverser(current_traversal, x)
+      (current_traversal || 1) * x
+    end
+
+    def self.no_argument_traverser(current_traversal)
+      :worked
+    end
+
+    def self.method_missing_dummy(current_traversal)
+      MyFakedPacerResult.new
+    end
+
+  end
+end
+
+describe Jogger do
+
+
+  it "runs the named proc and replaces the current traversal with its result" do
+    p = Jogger.new
+    p.test_traverser(2)
+    p.result.should == 2
+  end
+
+  it "allows for method chaining" do
+    p = Jogger.new
+    p.test_traverser(2).test_traverser(3)
+    p.result.should == 6
+  end
+
+  it "doesn't allow to run a non existant traversal" do
+    lambda do
+      p = Jogger.new
+      p.this_does_not_exist
+    end.should raise_error("Unknown traversal this_does_not_exist")
+  end
+
+  it "works for traversals without arguments" do
+    Jogger.new.no_argument_traverser.result.should == :worked
+  end
+
+  it "delegates method calls to the current traversal" do
+    Jogger.new.method_missing_dummy.some_existing_pacer_method.result.should == :is_there
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,7 @@
+require 'bundler'
+
+Bundler.setup
+Bundler.require :default, :test
+
+
+require_relative '../lib/jogger'

metadata

@@ -0,0 +1,117 @@
+--- !ruby/object:Gem::Specification
+name: pacer-jogger
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+  prerelease: 
+platform: ruby
+authors:
+- Jannis Hermanns
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-01-23 00:00:00.000000000Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: shoulda
+  requirement: &70246624766620 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *70246624766620
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: &70246624765680 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 1.0.0
+  type: :development
+  prerelease: false
+  version_requirements: *70246624765680
+- !ruby/object:Gem::Dependency
+  name: jeweler
+  requirement: &70246624765080 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 1.7.0
+  type: :development
+  prerelease: false
+  version_requirements: *70246624765080
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: &70246624764500 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *70246624764500
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: &70246624763920 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *70246624763920
+description: Allows to group traversal fragments/pipes to named traversals and call
+  them like they were pacer pipes.
+email: jannis@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files:
+- LICENSE.txt
+- README.markdown
+files:
+- .document
+- Gemfile
+- Gemfile.lock
+- LICENSE.txt
+- README.markdown
+- Rakefile
+- VERSION
+- lib/jogger.rb
+- pacer-jogger.gemspec
+- spec/lib/jogger_spec.rb
+- spec/spec_helper.rb
+homepage: http://github.com/jayniz/jogger
+licenses:
+- MIT
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+      segments:
+      - 0
+      hash: -4043812696808555855
+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: Pacer traversals for lazy people
+test_files: []