pacer 1.0.3-java → 1.1.0-java

data/Gemfile

@@ -13,12 +13,7 @@ group :development do
   # pacer-* gems are required for testing pacer.
   # If you have the gem repos cloned locally, we'll use them.
   #
-  libs = [
-    ['pacer-neo4j', '2.0.0.pre'],
-    ['pacer-orient', '2.0.0.pre'],
-    ['pacer-dex', '2.0.0.pre']
-  ] 
-  libs.each do |lib, version|
+  [ 'pacer-neo4j', 'pacer-orient', 'pacer-dex'].each do |lib|
     if File.directory? "../#{lib}"
       gem lib, :path => "../#{lib}" 
     end

data/lib/pacer.rb

@@ -42,6 +42,10 @@ module Pacer
   require 'pacer/loader'
 
   class << self
+    def help(section = nil)
+      Pacer.tg.help section
+    end
+
     # A global place for pacer to put debug info if it's tucked deep in
     # its internals. Should typically not be used unless a mysterious
     # bug needs to be analyzed but that never really happens ;)

data/lib/pacer/blueprints/payload_elements.rb

@@ -0,0 +1,44 @@
+module Pacer
+  module Payload
+    class Element
+      include com.tinkerpop.blueprints.Element
+      extend Forwardable
+
+      def initialize(element, payload = nil)
+        @element = element
+        self.payload = payload
+      end
+
+      def inspect
+        "#<Payload #{ element.inspect } -- #{ payload.inspect }>"
+      end
+
+      attr_reader :element
+      attr_accessor :payload
+    end
+
+    class Edge < Element
+      include com.tinkerpop.blueprints.Edge
+
+      def_delegators :@element,
+        # Object
+        :equals, :toString, :hashCode,
+        # Element
+        :getId, :getPropertyKeys, :getProperty, :setProperty, :removeProperty, :getRawElement,
+        # Edge
+        :getLabel, :getVertex, :getRawEdge
+    end
+
+    class Vertex < Element
+      include com.tinkerpop.blueprints.Vertex
+
+      def_delegators :@element,
+        # Object
+        :equals, :toString, :hashCode,
+        # Element
+        :getId, :getPropertyKeys, :getProperty, :setProperty, :removeProperty, :getRawElement,
+        # Vertex
+        :getEdges, :getVertices, :query, :getRawVertex
+    end
+  end
+end

data/lib/pacer/core/graph.rb

@@ -11,3 +11,4 @@ require 'pacer/core/graph/element_route'
 require 'pacer/core/graph/edges_route'
 require 'pacer/core/graph/vertices_route'
 require 'pacer/core/graph/mixed_route'
+require 'pacer/core/graph/path_route'

data/lib/pacer/core/graph/element_route.rb

@@ -40,8 +40,9 @@ module Pacer::Core::Graph
     # Create a new TinkerGraph based on the paths of all matching elements.
     #
     # @return [TinkerGraph] the subgraph
-    def subgraph opts = {}
-      paths.subgraph nil, opts
+    def subgraph(graph = nil, opts = {})
+      graph, opts = [nil, graph] if graph.is_a? Hash
+      paths.subgraph graph, opts
     end
 
     # Delete all matching elements.

data/lib/pacer/core/graph/path_route.rb

@@ -0,0 +1,138 @@
+module Pacer::Core::Graph
+  module PathRoute
+    def help(section = nil)
+      case section
+      when :paths
+        puts <<HELP
+The following path helper methods are available:
+
+#transpose       Works the same as Array transpase
+
+#subgraph(target_graph, opts)   Add each element in the path to the graph
+    target_graph: PacerGraph (optional) if not specified creates a new TG.
+    opts:
+      create_vertices: Boolean          Create vertices for edges if needed
+          Edges can not be created without both vertices being present. If
+          this option is not set and a vertex is missing, raises a
+          Pacer::ElementNotFound exception.
+      ignore_missing_vertices: Boolean  Squelches the above mentioned exception
+      show_missing_vertices: Boolean    Complain about missing vertices
+
+#compact_paths      Removes nils from paths
+
+#heads              Route to only the first element from each path
+
+#tails              Route to only the last element from each path
+
+#pairs(head, tail)  Route to a mini path of only the first and last elements
+    head: Number    Array index of the : first  : element in the pair
+    tail: Number                       : second :
+
+#len(n)             Filter paths by length
+    n: Number | Range
+
+#hashify            Make a hash of the properties and relationships of the path
+    This is just a simple view on the data to facilitate analysis
+
+HELP
+      else
+        super
+      end
+      description
+    end
+
+    def transpose
+      collect { |arraylist| arraylist.to_a }.transpose
+    end
+
+    def subgraph(target_graph = nil, opts = {})
+      raise "Can't create a subgraph within itself." if target_graph == graph
+      target_graph ||= Pacer.tg
+      target_graph.vertex_name ||= graph.vertex_name
+      missing_edges = Set[]
+      bulk_job(nil, target_graph) do |path|
+        path.select { |e| e.is_a? Pacer::Vertex }.each do |vertex|
+          vertex.clone_into target_graph
+        end
+        path.select { |e| e.is_a? Pacer::Edge }.each do |edge|
+          unless edge.clone_into target_graph, ignore_missing_vertices: true
+            missing_edges << edge
+          end
+        end
+      end
+      if missing_edges.any?
+        missing_edges.to_route(graph: graph, element_type: :edge).bulk_job nil, target_graph do |edge|
+          edge.clone_into target_graph,
+            ignore_missing_vertices: opts[:ignore_missing_vertices],
+            show_missing_vertices: opts[:show_missing_vertices]
+        end
+      end
+      target_graph
+    end
+
+    def payloads
+      map element_type: :path, route_name: 'payloads' do |path|
+        path.map do |e|
+          if e.is_a? Pacer::Payload::Element
+            e.payload
+          elsif e.is_a? Pacer::Wrappers::ElementWrapper
+            e.element_payload
+          end
+        end
+      end
+    end
+
+    def compact_paths
+      map element_type: :path, route_name: 'compact' do |path|
+        path.compact
+      end
+    end
+
+    def heads(et = :vertex)
+      map element_type: et, route_name: 'heads' do |path|
+        path.first
+      end
+    end
+
+    def tails(et = :vertex)
+      map element_type: et, route_name: 'tails' do |path|
+        path.last
+      end
+    end
+
+    def pairs(head = 0, tail = -1)
+      map element_type: :path, route_name: "pairs[#{ head },#{ tail }]" do |path|
+        [path[head], path[tail]]
+      end
+    end
+
+    def len(n)
+      select do |path|
+        n === path.length
+      end
+    end
+
+    def hashify
+      map(element_type: :hash, route_name: 'trees') do |path|
+        path.to_a.reverse.reduce({}) do |tree, element|
+          if element.element_type == :vertex
+            tree.merge element.properties
+          else
+            { element.label => [tree] }
+          end
+        end
+      end
+    end
+    protected
+
+    def configure_iterator(iter)
+      if respond_to? :graph
+        pipe = Pacer::Pipes::PathWrappingPipe.new(graph)
+        pipe.setStarts iter
+        pipe
+      else
+        iter
+      end
+    end
+  end
+end

data/lib/pacer/core/route.rb

@@ -156,6 +156,148 @@ module Pacer
         nil
       end
 
+      def help(section = nil)
+        general_topics = <<HELP
+Some general help sections:
+:routes     What are Pacer's routes?
+:basics     Simple usage examples
+:creation   How to create records
+:tools      Some things you can do
+:graphs     Available graphs
+:help       How to contribute to Pacer's inline help
+HELP
+        if section == :help
+          puts <<HELP
+Contributions of help topics will be greatly apreciated.
+
+Help topics should be added to the modules that they describe. General topics
+help can be added here for now but will likely be moved eventually.
+
+See lib/pacer/transform/map.rb for an example of how to define contextual help
+topics.
+
+If you add a general topic, remember to add it to the list above.
+
+Remember to call super for unrecognized sections! :)
+
+HELP
+        elsif section == :routes
+          puts <<HELP
+Pacer's routes are a very efficient and fast way to deal with data.
+
+The fundamental thing about them is that they are lazily evaluated, which
+allows very expensive traversals to be defined, yet nearly always produces
+results immediately with very low memory requirements, too.
+
+
+
+HELP
+        elsif section == :basics
+          puts <<HELP
+Pacer basics:
+
+g = Pacer.tg                           # create an in-memory graph
+                                       # - help(:graphs) for other types
+g.v                                    # create a route to all vertices in the graph
+                                       # vertices are your basic documents.
+g.e                                    # ... or all edges
+                                       # edges connect documents. They can have properties, too!
+g.v(name: 'Sue', gender: 'male')       # find all boys named Sue
+                                       # all elements are schemaless, so you
+                                       # can specify any properties
+g.v(name: 'Sue', gender: 'male').count # how many are there?
+                                       # see how we can chain calls? Powerful
+                                       # traversals can be defined this way.
+g.v.out_e(:friend)                     # see Sue's 'friend' relationships
+g.v.out_e(:friend).in_v                # continue on to his friends
+g.v.out_e(:friend).in_v.out(:friends)  # continue on to his friends-of-friends
+g.v.in(:friend)                        # see who has friended Sue.
+                                       # all edges are directional to follow an
+                                       # edge, use #out or #out_e; to go
+                                       # backwards along an edge, use #in or
+                                       # #in_e
+
+#{general_topics}
+
+HELP
+        elsif section == :creation
+          puts <<HELP
+How we can create records in a Pacer graph:
+
+g = Pacer.tg                          # create a new in-memory graph to play with
+sue = g.create_vertex name: 'Sue', gender: 'male'
+                                      # create a record with properties
+ghost = g.create_vertex               # get lazy and create an empty one
+sue.add_edges_to :friend, ghost       # Sue has friended the ghost.
+                                      # This relationship can be traversed in
+                                      # both directions so a reverse
+                                      # relationship is *not* required, but can
+                                      # be created:
+ghost.add_edges_to :friend, sue, type: 'spooky'
+                                      # We can also create edges with properties
+sue[:age] = 27                        # It's that easy to add or change a property
+sue['fav foods'] = [pie, donuts]      # Pacer can shoehorn any data into the
+                                      # graph as long as it's serializable.
+
+#{general_topics}
+
+HELP
+        elsif section == :tools
+          puts <<HELP
+
+HELP
+        elsif section == :graphs or section == :plugins
+          puts <<HELP
+Various graphs are supported in their own Rubygems. Check out pacer-neo4j,
+pacer-orient, pacer-dex for now. New graphs emerge frequently and I hope to
+support many of them.
+
+Search rubygems.org or github for projects that start with "pacer-" to see what
+other plugins exist as well.
+
+#{general_topics}
+
+HELP
+        else
+          if section
+            puts "Unrecognized help section specified"
+            puts
+          elsif not is_a? Graph
+            puts "No specialized help has been defined for this step yet."
+            puts
+          end
+          puts <<HELP
+How to use Pacer's inline help:
+
+You can use Pacer.help(:section) to print help on general topics, or get
+context-specific help by calling help on any route. For example:
+
+    graph.v.out_e.map.help  # will give you help about the map command.
+
+#{general_topics}
+
+General options (may not be available for all methods)
+
+  element_type: Symbol  Set what type of element is emitted from this step.
+      registered types: #{ Pacer::RouteBuilder.current.element_types.keys.map(&:inspect).join ', ' }
+
+  graph: PacerGraph     If the route contains graph elements, specify that they
+                        are from this graph
+
+  route_name: String    Name for this route when inspecting it in IRB.
+
+  info: String          Put what you want here. Appears when the route is inspected.
+
+  extensions: [Module]  Extra extensions to add to the route.
+
+  wrapper: Class         Wrap elements in this class.
+      For each element, wrapper.new(graph, element) happens
+
+HELP
+        end
+        description
+      end
+
       def description(join = ' -> ')
         "#<#{inspect_strings.join(join)}>"
       end
@@ -308,7 +450,9 @@ module Pacer
       # @return [java.util.Iterator]
       def source_iterator
         if @source
-          iterator_from_source(@source)
+          iter = iterator_from_source(@source)
+          iter.enablePath(true) if iter.respond_to? :enablePath
+          iter
         elsif @back
           @back.send(:source_iterator)
         end

data/lib/pacer/filter/empty_filter.rb

@@ -70,6 +70,8 @@ module Pacer
               'Obj'
             when :mixed
               'Elem'
+            else
+              element_type.to_s.capitalize
             end
         s = "#{s} #{ @info }" if @info
         s

data/lib/pacer/filter/loop_filter.rb

@@ -47,6 +47,91 @@ module Pacer
       attr_reader :looping_route
       attr_accessor :while_description
 
+      def help(section = nil)
+        case section
+        when nil
+          puts <<HELP
+Loops allow you to define repetative paths and paths of indeterminate length.
+As a path is expanded within a loop, a control block that you define can
+determine whether the given vertex should be emitted or not and whether it
+should be used to continue looping or not.
+
+There are two minor variations of the loop pipe. This is much more efficient
+because it does not need to keep track of every element's path.
+
+  g.v.
+    loop { |route| route.out_e.in_v }.
+    while { |element, depth| :loop_and_emit }
+
+This is less efficient but having the path available to you can be very
+powerful:
+
+  g.v.
+    loop { |route| route.out_e.in_v }.
+    while { |element, depth, path| :loop_and_emit }
+
+Control block arguments:
+  element         - the element that could be emitted or looped on
+  depth           - each initial element is depth 0 and has not had the loop route applied to it yet.
+  path            - (optional) the full array of elements that got us to where we are
+
+From the while block, you can give back one of three symbols:
+  :loop           - loop on this element; don't include it in results
+  :emit           - don't loop on this element; include it in the results
+  :discard        - don't loop on this element; don't include it in the results
+  :loop_and_emit  - loop on this element and include it in the results
+
+In addition:
+  false | nil     - maps to :discard
+  anything else   - maps to :loop_and_emit
+
+See the :examples section for some interesting ways to use the loop pipe.
+
+HELP
+        when :examples
+          puts <<HELP
+Range from 1 to 9:
+
+  [1].to_route.loop { |r| r.map { |n| n + 1 } }.while { |n, depth| n < 10 }
+  #==> 1 2 3 4 5 6 7 8 9
+
+Why didn't this give me even numbers?
+
+  [1].to_route.loop { |r| r.map { |n| n + 1 } }.while { |n, depth| n.even? ? :emit : :emit_and_loop }
+  #==> 1 2
+
+Odd numbers:
+
+  [1].to_route.loop { |r| r.map { |n| n + 1 } }.while { |n, depth| n.even? ? :loop : :emit_and_loop }.limit(10)
+  #==> 1  3  5  7  9  11 13 15 17 19
+
+Fibonacci sequence:
+
+  [[0, 1]].to_route(element_type: :path).
+    loop { |r| r.map { |a, b| [b, a+b] } }.
+    while { true }.limit(40).
+    tails(element_type: :number)
+  #==> 1         1         2         3         5         8         13        21
+  #==> 34        55        89        144       233       377       610       987
+  #==> 1597      2584      4181      6765      10946     17711     28657     46368
+  #==> 75025     121393    196418    317811    514229    832040    1346269   2178309
+  #==> 3524578   5702887   9227465   14930352  24157817  39088169  63245986  102334155
+
+You usually won't mean to do these, but you can:
+
+  [1].to_route.loop { |r| 123 }.while { true }.limit(10)
+  #==> 123 123 123 123 123 123 123 123 123 123
+
+  [1].to_route.loop { |r| r }.while { true }.limit(10)
+  #==> 1 1 1 1 1 1 1 1 1 1
+
+HELP
+        else
+          super
+        end
+        description
+      end
+
       def looping_route=(route)
         if route.is_a? Proc
           @looping_route = Pacer::Route.block_branch(self, route)