neo4j-cypher 1.0.0.rc1

data/Gemfile

@@ -0,0 +1,15 @@
+source :gemcutter
+
+gemspec
+
+group 'development' do
+  gem 'pry'
+  gem 'simplecov'
+end
+
+group 'test' do
+  gem "rake", ">= 0.8.7"
+  gem "rspec"
+  gem "its" # its(:with, :arguments) { should be_possible }
+end
+

data/README.rdoc

@@ -0,0 +1,71 @@
+== neo4j-cypher {<img src="https://secure.travis-ci.org/andreasronge/neo4j-cypher.png" />}[http://travis-ci.org/andreasronge/neo4j-cypher]
+
+A Ruby DSL for the Neo4j Cypher query language for both MRI and JRuby.
+The JRuby neo4j-core gem's cypher dsl has been moved to this gem.
+
+=== Docs
+
+See {Neo4j Wiki Cypher}[https://github.com/andreasronge/neo4j/wiki/Neo4j::Core-Cypher]
+
+See the rspecs ! (> 99% test coverage)
+
+
+=== Random Examples
+
+Notice the last value returned is the return value (if possible).
+Matching relationships can be done with operators: <,>, -, and <=> or with the both, incoming and outgoing methods.
+
+"START v1=node(3) MATCH v2 = (v1)-[:`r`]->(x) RETURN v2"
+
+  Neo4j::Cypher.query do
+    node(3) > :r > :x
+  end
+
+
+"START v2=node(1) MATCH (v2)-[v1:`knows`]->(other) WHERE v1.since > 1994 and other.name = "foo" RETURN other"
+
+  Neo4j::Cypher.query do
+    node(1) > (rel(:knows)[:since] > 1994) > (node(:other)[:name] == 'foo'); :other
+  end
+
+
+"START v2=node(1) MATCH (v2)-[v1:`friends`]->(v3) WHERE (v1.since = 1994) RETURN v3"
+
+  Neo4j::Cypher.query do
+    node(1).outgoing(rel(:friends).where{|r| r[:since] == 1994})
+  end
+
+
+"START v1=node(2,3,4,1) RETURN count(v1.property?"
+
+  Neo4j::Cypher.query do
+    node(2, 3, 4, 1)[:property?].count
+  end
+
+"START v1=node(42) MATCH (v1)-[:`favorite`]->(stuff)<-[:`favorite`]-(person) WHERE not((v1)-[:`friend`]-(person)) RETURN person.name,count(stuff) ORDER BY count(stuff) DESC"
+
+  Neo4j::Cypher.query do
+    node(42).where_not { |m| m - :friend - :person } > :favorite > :stuff < :favorite < :person
+    ret(node(:person)[:name], count(:stuff).desc)
+  end
+
+
+== Complex Example
+
+"START n=node(42) MATCH (n)-[r]->(m) WITH n,collect(type(r)) as out_types,collect(m) as outgoing MATCH (n)<-[r]-(m) RETURN n,outgoing,out_types,collect(m) as incoming,collect(type(r)) as in_types"
+
+  Neo4j::Cypher.query do
+    n = node(42).as(:n)
+    r = rel('r')
+    m = node(:m)
+    rel_types = r.rel_type.collect
+    end_nodes = m.collect
+
+    n.with_match(rel_types.as(:out_types), end_nodes.as(:outgoing)) { |n, _, _| n < r < m } > r > m
+
+    ret([n,
+         :outgoing,
+         :out_types,
+         end_nodes.as(:incoming),
+         rel_types.as(:in_types)])
+ end

data/lib/neo4j-cypher.rb

@@ -0,0 +1,47 @@
+require 'neo4j-cypher/version'
+
+require 'neo4j-cypher/context'
+require 'neo4j-cypher/mixins'
+require 'neo4j-cypher/clause'
+require 'neo4j-cypher/clause_list'
+require 'neo4j-cypher/argument'
+require 'neo4j-cypher/root'
+require 'neo4j-cypher/start'
+require 'neo4j-cypher/create'
+require 'neo4j-cypher/match'
+require 'neo4j-cypher/return'
+require 'neo4j-cypher/node_var'
+require 'neo4j-cypher/rel_var'
+require 'neo4j-cypher/property'
+require 'neo4j-cypher/predicate'
+require 'neo4j-cypher/with'
+require 'neo4j-cypher/operator'
+require 'neo4j-cypher/where'
+require 'neo4j-cypher/result_wrapper'
+require 'neo4j-cypher/result'
+
+module Neo4j
+  module Cypher
+
+    # Creates a Cypher DSL query.
+    # To create a new cypher query you must initialize it either an String or a Block.
+    #
+    # @example <tt>START n0=node(3) MATCH (n0)--(x) RETURN x</tt> same as
+    #   Cypher.query { start n = node(3); match n <=> :x; ret :x }.to_s
+    #
+    # @example <tt>START n0=node(3) MATCH (n0)-[:`r`]->(x) RETURN r</tt> same as
+    #   Cypher.query { node(3) > :r > :x; :r }
+    #
+    # @example <tt>START n0=node(3) MATCH (n0)-->(x) RETURN x</tt> same as
+    #   Cypher.query { node(3) >> :x; :x }
+    #
+    # @param args the argument for the dsl_block
+    # @yield the block which will be evaluated in the context of this object in order to create an Cypher Query string
+    # @yieldreturn [Return, Object] If the return is not an instance of Return it will be converted it to a Return object (if possible).
+    # @return [Cypher::Result]
+    def self.query(*args, &dsl_block)
+      Result.new(*args, &dsl_block)
+    end
+
+  end
+end

data/lib/neo4j-cypher/argument.rb

@@ -0,0 +1,39 @@
+module Neo4j
+  module Cypher
+
+    class Argument
+      include Referenceable
+      include Clause
+
+      def initialize(clause_list, expr, var_name)
+        super(clause_list, :argument, EvalContext)
+        var_name ||= self.var_name
+        @expr = var_name
+        as_alias(var_name)
+        @return_value = (expr != var_name.to_s) ? "#{expr} as #{var_name}" : expr
+      end
+
+      def return_value
+        @return_value
+      end
+
+      def self.new_arg_from_clause(clause)
+        Argument.new(clause.clause_list, clause.return_value, clause.as_alias? && clause.var_name)
+      end
+
+      def self.new_arg_from_string(string, clause_list)
+        Argument.new(clause_list, string.to_s, string)
+      end
+
+      class EvalContext
+        include Context
+        include Comparable
+        include MathOperator
+        include MathFunctions
+        include PredicateMethods
+        include Aggregate
+      end
+
+    end
+  end
+end

data/lib/neo4j-cypher/clause.rb

@@ -0,0 +1,76 @@
+module Neo4j
+  module Cypher
+
+    # Responsible for order of the clauses
+    # Does expect a #clause method when included
+    module Clause
+
+      ORDER = [:start, :match, :create, :where, :with, :foreach, :set, :delete, :return, :order_by, :skip, :limit]
+      NAME = {:start => 'START', :create => 'CREATE', :match => 'MATCH', :where => "WHERE", :with => 'WITH',
+              :return => 'RETURN', :order_by => 'ORDER BY', :skip => 'SKIP', :limit => 'LIMIT', :set => 'SET',
+              :delete => 'DELETE', :foreach => 'FOREACH'}
+
+      attr_accessor :clause_type, :clause_list, :eval_context, :expr, :insert_order
+
+      def initialize(clause_list, clause_type, eval_context = Context::Empty)
+        @clause_type = clause_type
+        @clause_list = clause_list
+        if eval_context.is_a?(Class)
+          @eval_context = eval_context.new(self)
+        else
+          @eval_context = eval_context
+        end
+        self.insert_order = 0
+        clause_list.insert(self)
+      end
+
+      def <=>(other)
+        clause_position == other.clause_position ? insert_order <=> other.insert_order : clause_position <=> other.clause_position
+      end
+
+      def clause_position
+        valid_clause?
+        ORDER.find_index(clause_type)
+      end
+
+      def valid_clause?
+        raise "Unknown clause_type '#{clause_type}' on #{self}" unless ORDER.include?(clause_type)
+      end
+
+      def separator
+        ','
+      end
+
+      def match_value=(mv)
+        @match_value = mv
+      end
+
+      def match_value
+        @match_value || expr || var_name
+      end
+
+      # Used in return clause to generate the last part of the return cypher clause string
+      def return_value
+        var_name
+      end
+
+      def prefix
+        NAME[clause_type]
+      end
+
+      def create_clause_args_for(args)
+        args.map do |arg|
+          case arg
+            when Neo4j::Cypher::ReturnItem::EvalContext, Neo4j::Cypher::Property::EvalContext
+              Argument.new_arg_from_clause(arg.clause)
+            when String, Symbol
+              Argument.new_arg_from_string(arg, clause_list)
+            else
+              arg.clause
+          end
+        end
+      end
+    end
+
+  end
+end

data/lib/neo4j-cypher/clause_list.rb

@@ -0,0 +1,101 @@
+module Neo4j
+  module Cypher
+
+    class ClauseList
+      attr_accessor :variables
+      include Enumerable
+
+      def initialize(variables = [])
+        @variables = variables
+        @clause_list = []
+        @insert_order = 0
+      end
+
+      def empty?
+        !first
+      end
+
+      def include?(clause_type)
+        @clause_list.find { |c| c.clause_type == clause_type }
+      end
+
+      def each
+        @clause_list.each { |c| yield c }
+      end
+
+      def push
+        raise "Only support stack of depth 2" if @old_clause_list
+        @old_clause_list = @clause_list
+        @clause_list = []
+        self
+      end
+
+      def pop
+        @clause_list = @old_clause_list
+        @clause_list.sort!
+        @old_clause_list = nil
+        self
+      end
+
+      def insert(clause)
+        ctype = clause.clause_type
+
+        if Clause::ORDER.include?(ctype)
+          # which list should we add the cluase to, the root or the sub list ?
+          # ALl the start and return clauses should move to the clause_list
+          c = (@old_clause_list && (ctype == :start || ctype == :return)) ? @old_clause_list : @clause_list
+          c << clause
+          @insert_order += 1
+          clause.insert_order = @insert_order
+          c.sort!
+        end
+        self
+      end
+
+      def last
+        @clause_list.last
+      end
+
+      def delete(clause_or_context)
+        c = clause_or_context.respond_to?(:clause) ? clause_or_context.clause : clause_or_context
+        @clause_list.delete(c)
+      end
+
+      #def debug
+      #  puts "ClauseList id: #{object_id}, vars: #{variables.size}"
+      #  @clause_list.each_with_index { |c, i| puts "  #{i} #{c.clause_type.inspect}, #{c.class} id: #{c.object_id} order #{c.insert_order}" }
+      #end
+
+      def create_variable(var)
+        raise "Already included #{var}" if @variables.include?(var)
+        @variables << var
+        "v#{@variables.size}".to_sym
+      end
+
+      def group_by_clause
+        prev_clause = nil
+        inject([]) do |memo, clause|
+          memo << [] if clause.clause_type != prev_clause
+          prev_clause = clause.clause_type
+          memo.last << clause
+          memo
+        end
+      end
+
+      def join_group(list)
+        list.map { |c| c.to_cypher }.join(list.first.separator)
+      end
+
+      def to_cypher
+        # Sub lists, like in with clause should not have a clause prefix like WHERE or MATCH
+        group_by_clause.map { |list| "#{prefix(list)}#{join_group(list)}" }.join(' ')
+      end
+
+      def prefix(list)
+        @old_clause_list && ![:set, :delete, :create].include?(list.first.clause_type) ? '' : "#{list.first.prefix} "
+      end
+
+    end
+  end
+
+end

data/lib/neo4j-cypher/context.rb

@@ -0,0 +1,411 @@
+module Neo4j
+  module Cypher
+    module Context
+      # @return [Neo4j::Cypher:Clause]
+      attr_accessor :clause
+
+      # @param [Neo4j::Cypher:Clause] clause the clause for this eval context
+      def initialize(clause)
+        @clause = clause
+
+      end
+
+      # @return [Array<Neo4j::Cypher:Clause>] the sorted clause list
+      def clause_list
+        @clause.clause_list
+      end
+
+      # Used for eval context for a clause which does not allow any more method chaining.
+      class Empty
+        include Context
+      end
+
+      module Alias
+        # Typically used in a WITH statement for a count.as(:stuff) or node(42).as(:foo)
+        def as(name)
+          clause.as_alias(name)
+          self
+        end
+      end
+
+      module MathFunctions
+        def abs(value=nil)
+          _add_math_func(:abs, value)
+        end
+
+        def sqrt(value=nil)
+          _add_math_func(:sqrt, value)
+        end
+
+        def round(value=nil)
+          _add_math_func(:round, value)
+        end
+
+        def sign(value=nil)
+          _add_math_func(:sign, value)
+        end
+
+        # @private
+        def _add_math_func(name, value)
+          value ||= clause.to_cypher
+          clause_list.delete(clause)
+          ReturnItem.new(clause_list, "#{name}(#{value})").eval_context
+        end
+      end
+
+      module MathOperator
+        def -(other)
+          Operator.new(clause_list, clause, other, '-').eval_context
+        end
+
+        def +(other)
+          Operator.new(clause_list, clause, other, '+').eval_context
+        end
+      end
+
+      module Comparable
+        def <(other)
+          Operator.new(clause_list, clause, other, '<').eval_context
+        end
+
+        def <=(other)
+          Operator.new(clause_list, clause, other, '<=').eval_context
+        end
+
+        def =~(other)
+          Operator.new(clause_list, clause, other, '=~').eval_context
+        end
+
+        def >(other)
+          Operator.new(clause_list, clause, other, '>').eval_context
+        end
+
+        def >=(other)
+          Operator.new(clause_list, clause, other, '>=').eval_context
+        end
+
+        ## Only in 1.9
+        if RUBY_VERSION > "1.9.0"
+          eval %{
+            def !=(other)
+              Operator.new(clause_list, clause, other, "<>").eval_context
+            end  }
+        end
+
+        def ==(other)
+          Operator.new(clause_list, clause, other, "=").eval_context
+        end
+      end
+
+      module PredicateMethods
+        def all?(&block)
+          self.respond_to?(:iterable)
+          Predicate.new(clause_list, :op => 'all', :clause => :where, :input => input, :iterable => iterable, :predicate_block => block).eval_context
+        end
+
+        def extract(&block)
+          Predicate.new(clause_list, :op => 'extract', :clause => :return_item, :input => input, :iterable => iterable, :predicate_block => block).eval_context
+        end
+
+        def filter(&block)
+          Predicate.new(clause_list, :op => 'filter', :clause => :return_item, :input => input, :iterable => iterable, :predicate_block => block).eval_context
+        end
+
+        def any?(&block)
+          Predicate.new(clause_list, :op => 'any', :clause => :where, :input => input, :iterable => iterable, :predicate_block => block).eval_context
+        end
+
+        def none?(&block)
+          Predicate.new(clause_list, :op => 'none', :clause => :where, :input => input, :iterable => iterable, :predicate_block => block).eval_context
+        end
+
+        def single?(&block)
+          Predicate.new(clause_list, :op => 'single', :clause => :where, :input => input, :iterable => iterable, :predicate_block => block).eval_context
+        end
+
+        def foreach(&block)
+          Predicate.new(clause_list, :op => '', :clause => :foreach, :input => input, :iterable => iterable, :predicate_block => block, :separator => ' FOREACH ').eval_context
+          input.eval_context
+        end
+      end
+
+      module Returnable
+        # Specifies a return statement.
+        # Notice that this is not needed, since the last value of the DSL block will be converted into one or more
+        # return statements.
+        # @param [Symbol, #var_name] returns a list of variables we want to return
+        # @return [ReturnItem]
+        def ret(*returns, &block)
+          options = returns.last.is_a?(Hash) ? returns.pop : {}
+          returns = [self] if returns.empty? # return self unless not specified what to return
+          returns = [RootClause::EvalContext.new(self).instance_exec(self, &block)].flatten if block
+          r = Return.new(clause_list, returns, options, &block).eval_context
+          (self.is_a?(RootClause::EvalContext)) ? r : self
+        end
+
+      end
+
+      module Sortable
+        def _sort_args(prop)
+          return self if prop.nil?
+          prop.is_a?(Symbol) ? Property.new(clause, prop).eval_context : prop
+        end
+
+        def asc(*props)
+          @return_item ||= ReturnItem.new(clause_list, self).eval_context
+          @return_item.asc(_sort_args(props.first))
+        end
+
+        def desc(*props)
+          @return_item ||= ReturnItem.new(clause_list, self).eval_context
+          @return_item.desc(_sort_args(props.first))
+        end
+
+      end
+
+      module ReturnOrder
+        def _sort_args(props)
+          return [self] if props.empty?
+          props.map { |p| p.is_a?(Symbol) ? Property.new(clause, p).eval_context : p }
+        end
+
+        # Specifies an <tt>ORDER BY</tt> cypher query
+        # @param [Property] props the properties which should be sorted
+        # @return self
+        def asc(*props)
+          @order_by ||= OrderBy.new(clause_list, self)
+          clause_list.delete(props.first)
+          @order_by.asc(_sort_args(props))
+          self
+        end
+
+        # Specifies an <tt>ORDER BY</tt> cypher query
+        # @param [Property] props the properties which should be sorted
+        # @return self
+        def desc(*props)
+          @order_by ||= OrderBy.new(clause_list, self)
+          clause_list.delete(props.first)
+          @order_by.desc(_sort_args(props))
+          self
+        end
+
+        # Creates a <tt>SKIP</tt> cypher clause
+        # @param [Fixnum] val the number of entries to skip
+        # @return self
+        def skip(val)
+          Skip.new(clause_list, val, self)
+          self
+        end
+
+        # Creates a <tt>LIMIT</tt> cypher clause
+        # @param [Fixnum] val the number of entries to limit
+        # @return self
+        def limit(val)
+          Limit.new(clause_list, val, self)
+          self
+        end
+
+      end
+
+      module Aggregate
+        def distinct
+          ReturnItem.new(clause_list, "distinct(#{clause.return_value})").eval_context
+        end
+
+        def count
+          ReturnItem.new(clause_list, "count(#{clause.return_value})").eval_context
+        end
+
+        def sum
+          ReturnItem.new(clause_list, "sum(#{clause.return_value})").eval_context
+        end
+
+        def avg
+          ReturnItem.new(clause_list, "avg(#{clause.return_value})").eval_context
+        end
+
+        def min
+          ReturnItem.new(clause_list, "min(#{clause.return_value})").eval_context
+        end
+
+        def max
+          ReturnItem.new(clause_list, "max(#{clause.return_value})").eval_context
+        end
+
+        def collect
+          ReturnItem.new(clause_list, "collect(#{clause.return_value})").eval_context
+        end
+
+
+        def last
+          ReturnItem.new(clause_list, "last(#{clause.return_value})").eval_context
+        end
+
+        def tail
+          ReturnItem.new(clause_list, "tail(#{clause.return_value})").eval_context
+        end
+
+        def head
+          ReturnItem.new(clause_list, "head(#{clause.return_value})").eval_context
+        end
+
+      end
+
+      module Variable
+        def where(&block)
+          x = block.call(self)
+          clause_list.delete(x)
+          Operator.new(clause_list, x.clause, nil, "").unary!
+          self
+        end
+
+        def where_not(&block)
+          x = block.call(self)
+          clause_list.delete(x)
+          Operator.new(clause_list, x.clause, nil, "not").unary!
+          self
+        end
+
+        def [](prop_name)
+          Property.new(clause, prop_name).eval_context
+        end
+
+        # generates a <tt>ID</tt> cypher fragment.
+        def neo_id
+          Property.new(clause, 'ID').to_function!
+        end
+
+        # generates a <tt>has</tt> cypher fragment.
+        def property?(p)
+          p = Property.new(clause, p)
+          Operator.new(clause_list, p, nil, "has").unary!
+        end
+
+        def []=(p, value)
+          left = Property.new(clause, p).eval_context
+          Operator.new(clause_list, left, value, "=", :set)
+          self
+        end
+
+        def del
+          Delete.new(clause_list, clause)
+          self
+        end
+
+        # Can be used instead of [_classname] == klass
+        def is_a?(klass)
+          return super if klass.class != Class || !klass.respond_to?(:_load_wrapper)
+          self[:_classname] == klass.to_s
+        end
+      end
+
+      module Matchable
+
+        def with(*args, &cypher_dsl)
+          With.new(clause_list, :where, self, *args, &cypher_dsl)
+          self
+        end
+
+        def with_match(*args, &cypher_dsl)
+          With.new(clause_list, :match, self, *args, &cypher_dsl)
+          self
+        end
+
+        def create_path(*args, &cypher_dsl)
+          CreatePath.new(clause_list, self, *args, &cypher_dsl)
+          self
+        end
+
+        def create_unique_path(*args, &cypher_dsl)
+          CreatePath.new(clause_list, self, *args, &cypher_dsl).unique!
+          self
+        end
+
+
+        # This operator means related to, without regard to type or direction.
+        # @param [Symbol, #var_name] other either a node (Symbol, #var_name)
+        # @return [MatchRelLeft, MatchNode]
+        def <=>(other)
+          MatchStart.new_match_node(clause, other, :both).eval_context
+        end
+
+        # This operator means outgoing related to
+        # @param [Symbol, #var_name, String] other the relationship
+        # @return [MatchRelLeft, MatchNode]
+        def >(other)
+          MatchStart.new(clause).new_match_rel(other).eval_context
+        end
+
+        # This operator means any direction related to
+        # @param (see #>)
+        # @return [MatchRelLeft, MatchNode]
+        def -(other)
+          MatchStart.new(clause).new_match_rel(other).eval_context
+        end
+
+        # This operator means incoming related to
+        # @param (see #>)
+        # @return [MatchRelLeft, MatchNode]
+        def <(other)
+          MatchStart.new(clause).new_match_rel(other).eval_context
+        end
+
+        # Outgoing relationship to other node
+        # @param [Symbol, #var_name] other either a node (Symbol, #var_name)
+        # @return [MatchRelLeft, MatchNode]
+        def >>(other)
+          MatchStart.new_match_node(clause, other, :outgoing).eval_context
+        end
+
+        # Incoming relationship to other node
+        # @param [Symbol, #var_name] other either a node (Symbol, #var_name)
+        # @return [MatchRelLeft, MatchNode]
+        def <<(other)
+          MatchStart.new_match_node(clause, other, :incoming).eval_context
+        end
+
+        def outgoing(*rel_types)
+          node = _get_or_create_node(rel_types)
+          MatchStart.new(clause).new_match_rels(rel_types).eval_context > node
+          node.eval_context
+        end
+
+        def _get_or_create_node(rel_types)
+          rel_types.last.kind_of?(Matchable) ? rel_types.pop.clause : NodeVar.new(clause.clause_list)
+        end
+
+        def outgoing?(*rel_types)
+          node = _get_or_create_node(rel_types)
+          MatchStart.new(clause).new_match_rels?(rel_types).eval_context > node
+          node.eval_context
+        end
+
+        def incoming(*rel_types)
+          node = _get_or_create_node(rel_types)
+          MatchStart.new(clause).new_match_rels(rel_types).eval_context < node
+          node.eval_context
+        end
+
+        def incoming?(*rel_types)
+          node = _get_or_create_node(rel_types)
+          MatchStart.new(clause).new_match_rels?(rel_types).eval_context < node
+          node.eval_context
+        end
+
+        def both(*rel_types)
+          node = _get_or_create_node(rel_types)
+          MatchStart.new(clause).new_match_rels(rel_types).eval_context - node
+          node.eval_context
+        end
+
+        def both?(*rel_types)
+          node = _get_or_create_node(rel_types)
+          MatchStart.new(clause).new_match_rels?(rel_types).eval_context - node
+          node.eval_context
+        end
+      end
+
+
+    end
+  end
+end