pacer-jogger 0.0.1 → 0.0.2

data/README.markdown

@@ -1,56 +1,61 @@
-# Jogger
+# Jogger - almost like named scopes
 
 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?
+# What does Jogger do? TL;DR
+
+Remember the _named scopes_ from back in the days when you were using rails? They were handy, weren't they? Jogger gives you _named traversals_ and is a little bit like named scopes. Jogger groups multiple pacer traversals together and give them a name. Pacer traversals are are like pipes. What are pipes? [Pipes are great!](http://markorodriguez.com/2011/08/03/on-the-nature-of-pipes/)!
+
+The most important conceptual difference is, that the order in which named traversals are called matter, while it usually doesn't matter in which order you call named scopes.
 
 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.
+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 a TL;DR gif followed by some hands on examples.
 
-# Example time!
+![TL;DR](http://dl.dropbox.com/u/1953503/gifs/berneydidnotread.gif)
 
-## 1. Keep track of the current traversal
+
+# Feature #1 (not so important): keep 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.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 }
+    t = t.group_count{ |v| v }
 
 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:
+So here's the Jogger way of expressing this:
 
     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 }
+    t.group_count{ |v| v }
 
 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.
+Just saying, you can chain your methods, but I don't like it cause I can only focus on 72 characters per line at max. If you want the current traversal, just call `result` on your Jogger instance.
 
-## 2. Named traversals
+## Feature #2 (pretty useful): 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:
+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. 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.
+No problem. Just define named traversals that aggregate different pipes and give them a name:
 
     class Jogger
       module NamedTraversals
@@ -60,13 +65,12 @@ No problem. Just define a few named traversals that do exactly this.
           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
@@ -75,16 +79,24 @@ These are silly examples, but if you look at your traversals I guarantee that yo
 
 # 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:
+First, you need to load pacer and whatever graph db connector you need (we use 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
+and 
 
     require 'jogger'
 
-or if you're using bundler, add this to your Gemfile and bundle:
+or for your Gemfile
 
     gem "pacer-jogger", :require => "jogger"
 
 That's it!
+
+# Documentation
+
+I gave YARD a shot, so to open the documentation in your browser just do this in the jogger directory:
+
+    yard server & sleep 3 && open http://localhost:8808/docs/file/README.markdown
+
+Or you can (browse the documentation online)[http://rubydoc.info/github/jayniz/jogger/master/frames]

data/VERSION

@@ -1 +1 @@
-0.0.1
+0.0.2

data/lib/jogger.rb

@@ -2,21 +2,25 @@
 # 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}.
+# All named traversals are defined in {Jogger::NamedTraversals},
+# so that's where you should define your own.
 #
 # Instances have a @current_traversal variable that is
-# updated with each chained call of {#traverse}.
+# updated with each call. Beware: Jogger 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,
+# e.g. call count on it:
 #
-# 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.go.some.where.count
+#
+# Everything except for {Jogger#result} is called on the
+# `@current_traversal`, so what you really want to do to get the
+# count of your traversal would be
 #
 #     t = Jogger.new(some_node)
-#     t.traverse(:some).traverse(:where).count
+#     t.go.some.where.result.count
 #
-# So everything except for {#traverse} is called on the
-# @current_traversal
 class Jogger
 
 
@@ -40,7 +44,7 @@ class Jogger
   # This is useful for more traversals after named routes.
   #
   # @return [Jogger] Returns itself so you can chain multiple
-  # {#traverse} calls
+  #   calls just like you would do with pacer
   def method_missing(method, *args, &block)
     begin
       traversal_args = [method, args].flatten.compact

data/pacer-jogger.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = "pacer-jogger"
-  s.version = "0.0.1"
+  s.version = "0.0.2"
 
   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.date = "2012-01-25"
   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 = [

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pacer-jogger
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
   prerelease: 
 platform: ruby
 authors:
@@ -9,11 +9,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-01-23 00:00:00.000000000Z
+date: 2012-01-25 00:00:00.000000000Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: shoulda
-  requirement: &70246624766620 !ruby/object:Gem::Requirement
+  requirement: &70106294753680 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -21,10 +21,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70246624766620
+  version_requirements: *70106294753680
 - !ruby/object:Gem::Dependency
   name: bundler
-  requirement: &70246624765680 !ruby/object:Gem::Requirement
+  requirement: &70106294753160 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -32,10 +32,10 @@ dependencies:
         version: 1.0.0
   type: :development
   prerelease: false
-  version_requirements: *70246624765680
+  version_requirements: *70106294753160
 - !ruby/object:Gem::Dependency
   name: jeweler
-  requirement: &70246624765080 !ruby/object:Gem::Requirement
+  requirement: &70106294752640 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -43,10 +43,10 @@ dependencies:
         version: 1.7.0
   type: :development
   prerelease: false
-  version_requirements: *70246624765080
+  version_requirements: *70106294752640
 - !ruby/object:Gem::Dependency
   name: rspec
-  requirement: &70246624764500 !ruby/object:Gem::Requirement
+  requirement: &70106294752040 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -54,10 +54,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70246624764500
+  version_requirements: *70106294752040
 - !ruby/object:Gem::Dependency
   name: yard
-  requirement: &70246624763920 !ruby/object:Gem::Requirement
+  requirement: &70106294751440 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -65,7 +65,7 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70246624763920
+  version_requirements: *70106294751440
 description: Allows to group traversal fragments/pipes to named traversals and call
   them like they were pacer pipes.
 email: jannis@gmail.com
@@ -101,7 +101,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -4043812696808555855
+      hash: 3011242392760856399
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements: