cypher-dsl 0.1.0.alpha.1

data/lib/cypher_dsl/relationship_chain.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module CypherDSL
+  # A chain of relationships sharing nodes, `(a)-[]->(b)-[]->(c)`. Modifiers
+  # such as `named`, `min` or `properties` apply to the last relationship.
+  class RelationshipChain
+    attr_reader :relationships
+
+    def initialize(relationships)
+      @relationships = relationships.freeze
+      freeze
+    end
+
+    def relationship_to(other, *types) = add(:ltr, other, types)
+    def relationship_from(other, *types) = add(:rtl, other, types)
+    def relationship_between(other, *types) = add(:uni, other, types)
+
+    def named(name) = update_last { |relationship| relationship.named(name) }
+    def with_properties(*keys_and_values) = update_last { it.with_properties(*keys_and_values) }
+    alias properties with_properties
+    def min(minimum) = update_last { |relationship| relationship.min(minimum) }
+    def max(maximum) = update_last { |relationship| relationship.max(maximum) }
+    def length(minimum, maximum) = update_last { |relationship| relationship.length(minimum, maximum) }
+    def unbounded = update_last(&:unbounded)
+    def where(condition) = update_last { |relationship| relationship.where(condition) }
+    def quantify_relationship(quantifier) = update_last { it.quantify_relationship(quantifier) }
+
+    # `((a)-[]->(b)-[]->(c)){1,3}`: a quantifier on the whole chain.
+    def quantify(quantifier) = QuantifiedPathPattern.new(self, quantifier)
+
+    # The chain as a predicate.
+    def as_condition = RelationshipPatternCondition.new(self)
+
+    private
+
+    def add(direction, other, types)
+      RelationshipChain.new(relationships + [Relationship.create(relationships.last.right, direction, other, types)])
+    end
+
+    def update_last
+      RelationshipChain.new(relationships[0...-1] + [yield(relationships.last)])
+    end
+  end
+end

data/lib/cypher_dsl/relationship_pattern_condition.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module CypherDSL
+  # A relationship pattern used as a predicate, e.g. `WHERE (a)-->(b)`.
+  class RelationshipPatternCondition < Condition
+    attr_reader :pattern
+
+    def initialize(pattern)
+      super()
+      @pattern = pattern
+      freeze
+    end
+  end
+end

data/lib/cypher_dsl/renderer/configuration.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module CypherDSL
+  class Renderer
+    # Rendering options.
+    #
+    # - `always_escape_names`: backtick-escape labels and relationship types even
+    #   when they are plain identifiers, as the Java default renderer does.
+    # - `dialect`: one of {Dialect::ALL}.
+    # - `pretty_print`: one clause per line, indented subqueries, conditions and maps.
+    # - `indent_size` / `indent_style` (`:space` or `:tab`): the indentation unit.
+    class Configuration
+      attr_reader :always_escape_names, :dialect, :pretty_print, :indent_size, :indent_style
+
+      # `always_escape_names` defaults to true, except when pretty printing, where
+      # names are escaped only when necessary (as upstream does).
+      def initialize(always_escape_names: nil, dialect: Dialect::NEO4J_5_23, pretty_print: false, indent_size: 2,
+                     indent_style: :space)
+        raise ArgumentError, "Unknown dialect #{dialect.inspect}" unless Dialect::ALL.include?(dialect)
+        raise ArgumentError, "Unknown indent style #{indent_style.inspect}" unless %i[space tab].include?(indent_style)
+
+        @always_escape_names = always_escape_names.nil? ? !pretty_print : always_escape_names
+        @dialect = dialect
+        @pretty_print = pretty_print
+        @indent_size = indent_size
+        @indent_style = indent_style
+        freeze
+      end
+
+      DEFAULT = new
+
+      # Mirrors `Configuration.newConfig()…build()`.
+      def self.new_config = Builder.new
+
+      # Mirrors `Configuration.prettyPrinting()`: pretty printed, names escaped only when needed.
+      def self.pretty_printing = new(pretty_print: true)
+
+      # `CALL { WITH imports … }` (older dialects) rather than `CALL (imports) { … }`.
+      def legacy_subquery_syntax? = Dialect::LEGACY_SUBQUERY_SYNTAX.include?(dialect)
+
+      def indent_unit = indent_style == :tab ? "\t" : ' ' * indent_size
+
+      # Fluent builder; each setter returns the builder.
+      class Builder
+        def initialize
+          @options = {}
+        end
+
+        def always_escape_names(value) = option(:always_escape_names, value)
+        def with_dialect(dialect) = option(:dialect, dialect)
+        def with_pretty_print(value) = option(:pretty_print, value)
+        def with_indent_size(size) = option(:indent_size, size)
+        def with_indent_style(style) = option(:indent_style, style)
+
+        def build = Configuration.new(**@options)
+
+        private
+
+        def option(name, value)
+          @options[name] = value
+          self
+        end
+      end
+    end
+  end
+end

data/lib/cypher_dsl/renderer/dialect.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module CypherDSL
+  class Renderer
+    # Target Cypher dialects.
+    #
+    # - NEO4J_4: `CALL { WITH imports … }` subqueries, `elementId(x)` rendered as `toString(id(x))`.
+    # - NEO4J_5: `CALL { WITH imports … }` subqueries, native `elementId`.
+    # - NEO4J_5_23 (default, Neo4j 5.23+): `CALL (imports) { … }` subqueries.
+    module Dialect
+      NEO4J_4 = :neo4j4
+      NEO4J_5 = :neo4j5
+      NEO4J_5_23 = :neo4j5_23 # rubocop:disable Naming/VariableNumber
+      NEO4J_5_DEFAULT_CYPHER = NEO4J_5_23
+
+      ALL = [NEO4J_4, NEO4J_5, NEO4J_5_23].freeze
+      LEGACY_SUBQUERY_SYNTAX = [NEO4J_4, NEO4J_5].freeze
+    end
+  end
+end

data/lib/cypher_dsl/renderer/escaper.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module CypherDSL
+  class Renderer
+    # Backtick escaping of schema names and identifiers.
+    module Escaper
+      IDENTIFIER = /\A[\p{L}_][\p{L}\p{N}_]*\z/
+      # Parameter names may be dotted (`$point.distance`) without escaping.
+      PARAMETER_NAME = /\A[\p{L}_][\p{L}\p{N}_.]*\z/
+      ESCAPED = /\A`.*`\z/m
+
+      module_function
+
+      # Always escapes, unless the name already is.
+      def escape(name)
+        return name if ESCAPED.match?(name)
+
+        "`#{name.gsub('`', '``')}`"
+      end
+
+      # Escapes only names that are not plain identifiers.
+      def escape_if_necessary(name)
+        IDENTIFIER.match?(name) ? name : escape(name)
+      end
+
+      def escape_parameter_name(name)
+        PARAMETER_NAME.match?(name) ? name : escape(name)
+      end
+    end
+  end
+end

data/lib/cypher_dsl/renderer/visitor/expressions.rb

@@ -0,0 +1,274 @@
+# frozen_string_literal: true
+
+module CypherDSL
+  class Renderer
+    class Visitor
+      # Rendering of expressions, conditions, operations, functions and subquery expressions.
+      module Expressions
+        private
+
+        def render_expression(expression)
+          case expression
+          when SymbolicName then Escaper.escape_if_necessary(resolve_name(expression))
+          when Node, Relationship then render_expression(expression.required_symbolic_name)
+          when Property then render_property(expression)
+          when Literal then render_literal(expression.value)
+          when Parameter then render_parameter(expression)
+          when Asterisk then '*'
+          when AliasedExpression then render_aliased_reference(expression)
+          when NamedPath then render_expression(expression.symbolic_name)
+          when RawExpression then expression.content
+          when CollectExpression
+            block('COLLECT {', '}') { render_subquery(expression.statement, expression.imports) }
+          when CountExpression then render_count(expression)
+          when FunctionInvocation then render_function_invocation(expression)
+          when SortItem then render_sort_item(expression)
+          when CaseExpression then render_case(expression)
+          when UnaryOperation then "#{expression.operator}#{render_expression(expression.expression)}"
+          when ListOperator then render_list_operator(expression)
+          else render_container_expression(expression)
+          end
+        end
+
+        def render_case(case_expression)
+          parts = ['CASE']
+          parts << render_expression(case_expression.subject) if case_expression.subject
+          case_expression.whens.each do |condition, value|
+            parts << "WHEN #{render_expression(condition)} THEN #{render_expression(value)}"
+          end
+          parts << "ELSE #{render_expression(case_expression.default)}" if case_expression.default
+          parts << 'END'
+          parts.join(' ')
+        end
+
+        def render_list_operator(operator)
+          list = render_expression(operator.list)
+          return "#{list}[#{render_expression(operator.start_index)}]" unless operator.slice
+
+          from = operator.start_index && render_expression(operator.start_index)
+          to = operator.end_index && render_expression(operator.end_index)
+          "#{list}[#{from}..#{to}]"
+        end
+
+        def render_container_expression(expression)
+          case expression
+          when MapExpression then render_map(expression)
+          when ListExpression then "[#{expression.elements.map { |element| render_expression(element) }.join(', ')}]"
+          when PatternComprehension then render_pattern_comprehension(expression)
+          when ListComprehension then render_list_comprehension(expression)
+          when MapProjection then render_map_projection(expression)
+          when LabelOperation then render_labels(expression.node, expression.labels)
+          when Reduction then render_reduction(expression)
+          when PatternExpression then render_pattern_expression(expression.pattern)
+          else render_condition_or_operation(expression)
+          end
+        end
+
+        def render_reduction(reduction)
+          accumulator = "#{render_expression(reduction.accumulator)} = #{render_expression(reduction.initial_value)}"
+          "reduce(#{accumulator}, #{render_expression(reduction.variable)} IN #{render_expression(reduction.list)} " \
+            "| #{render_expression(reduction.mapper)})"
+        end
+
+        def render_labels(node, labels)
+          "#{render_expression(node)}#{labels.map { |label| ":#{escape_schema_name(label)}" }.join}"
+        end
+
+        def render_condition_or_operation(expression)
+          case expression
+          when Comparison then render_comparison(expression)
+          when CompoundCondition then render_compound_condition(expression)
+          when ConstantCondition then expression.value.to_s
+          when ExpressionCondition then render_expression(expression.expression)
+          when ExistsCondition then render_exists(expression)
+          when RelationshipPatternCondition then render_pattern_expression(expression.pattern)
+          when ListPredicate then render_list_predicate(expression)
+          when HasLabelCondition then render_labels(expression.node, expression.labels)
+          when Operation then render_operation(expression)
+          else raise ArgumentError, "Cannot render expression #{expression.inspect}"
+          end
+        end
+
+        def render_operation(operation)
+          left = render_expression(operation.left)
+          right = render_expression(operation.right)
+          return "#{left}^#{right}" if operation.operator == '^'
+
+          rendered = "#{left} #{operation.operator} #{right}"
+          operation.assignment? ? rendered : "(#{rendered})"
+        end
+
+        # A plain relationship pattern uses the `exists()` function; quantified
+        # patterns and statements need the `EXISTS { }` subquery form.
+        def render_exists(condition)
+          body = condition.body
+          return block('EXISTS {', '}') { render_subquery(body, condition.imports) } if body.is_a?(Statement)
+          return "EXISTS { #{render_in_own_scope { render_pattern_elements(body) }} }" if body.is_a?(Array)
+          return "EXISTS { #{render_pattern_element(body)} }" if quantified?(body)
+
+          "exists(#{render_pattern_expression(body)})"
+        end
+
+        def render_count(count)
+          body = count.body
+          return block('COUNT {', '}') { render_subquery(body, count.imports) } if body.is_a?(Statement)
+
+          "COUNT { #{render_in_own_scope { render_pattern_element(body) }} }"
+        end
+
+        # Renders with the current scope, discarding names introduced inside.
+        def render_in_own_scope
+          outer_scope = @visited_names.dup
+          yield
+        ensure
+          @visited_names = outer_scope
+        end
+
+        def quantified?(pattern)
+          case pattern
+          when QuantifiedPathPattern then true
+          when Relationship then !pattern.details.quantifier.nil?
+          when RelationshipChain then pattern.relationships.any? { |relationship| quantified?(relationship) }
+          else false
+          end
+        end
+
+        # The predicate's variable is in scope inside its WHERE.
+        def render_list_predicate(predicate)
+          variable = render_expression(predicate.variable)
+          condition = with_names_in_scope([variable]) { render_expression(predicate.condition) }
+          "#{predicate.predicate}(#{variable} IN #{render_expression(predicate.list)} WHERE #{condition})"
+        end
+
+        def with_names_in_scope(names)
+          added = names.reject { |name| @visited_names.include?(name) }
+          @visited_names.merge(added)
+          yield
+        ensure
+          @visited_names.subtract(added)
+        end
+
+        def render_map_projection(projection)
+          subject = render_expression(projection.subject)
+          render_entries("#{subject}#{' ' if pretty?}{", '}') do
+            projection.entries.map do |kind, *args|
+              case kind
+              when :all then '.*'
+              when :lookup then ".#{Escaper.escape_if_necessary(args.first)}"
+              when :property then ".#{Escaper.escape_if_necessary(args.first.names.first)}"
+              when :pair then "#{Escaper.escape_if_necessary(args.first)}: #{render_expression(args.last)}"
+              else render_expression(args.first)
+              end
+            end
+          end
+        end
+
+        # A pattern comprehension is its own scope: names it introduces do not
+        # count as visited outside of it.
+        def render_pattern_comprehension(comprehension)
+          outer_scope = @visited_names.dup
+          parts = [render_pattern_element(comprehension.pattern)]
+          parts << "WHERE #{render_expression(comprehension.where_condition)}" if comprehension.where_condition
+          projection = comprehension.projection.map { |expression| render_expression(expression) }
+          parts << "| #{projection.size == 1 ? projection.first : "[#{projection.join(', ')}]"}"
+          @visited_names = outer_scope
+          "[#{parts.join(' ')}]"
+        end
+
+        def render_list_comprehension(comprehension)
+          parts = ["#{render_expression(comprehension.variable)} IN #{render_expression(comprehension.list)}"]
+          parts << "WHERE #{render_expression(comprehension.where_condition)}" if comprehension.where_condition
+          parts << "| #{render_expression(comprehension.projection)}" if comprehension.projection
+          "[#{parts.join(' ')}]"
+        end
+
+        # Records every use for the catalog; anonymous parameters get `pcdslNN`,
+        # shared between anonymous parameters with equal values.
+        def render_parameter(parameter)
+          name = parameter.anonymous? ? anonymous_parameter_name(parameter) : parameter.name
+          (@parameter_uses[name] ||= []) << parameter.value
+          "$#{Escaper.escape_parameter_name(name)}"
+        end
+
+        def anonymous_parameter_name(parameter)
+          index = @anonymous_parameters.index(parameter)
+          unless index
+            @anonymous_parameters << parameter
+            index = @anonymous_parameters.size - 1
+          end
+          format('pcdsl%02d', index + 1)
+        end
+
+        def render_property(property)
+          lookups = property.names.map do |name|
+            name.is_a?(Expression) ? "[#{render_expression(name)}]" : ".#{Escaper.escape_if_necessary(name)}"
+          end
+          "#{render_expression(property.container)}#{lookups.join}"
+        end
+
+        def render_literal(value)
+          case value
+          when String then "'#{value.gsub('\\') { '\\\\' }.gsub("'") { "\\'" }}'"
+          when nil then 'NULL'
+          when true, false, Numeric then value.to_s
+          else raise ArgumentError, "Cannot render literal #{value.inspect}"
+          end
+        end
+
+        def render_map(map)
+          render_entries('{', '}') do
+            map.entries.map { |key, value| "#{Escaper.escape_if_necessary(key)}: #{render_expression(value)}" }
+          end
+        end
+
+        # Comma separated entries, one per indented line when pretty printing.
+        def render_entries(opening, closing, &entries)
+          entries = nested(&entries)
+          return "#{opening}#{entries.join(', ')}#{closing}" unless pretty?
+
+          "#{opening}#{break_line(@level + 1)}#{entries.join(",#{break_line(@level + 1)}")}#{break_line}#{closing}"
+        end
+
+        def render_comparison(comparison)
+          left = render_operand(comparison.left)
+          return "#{left} #{comparison.operator}" if comparison.unary?
+
+          "#{left} #{comparison.operator} #{render_operand(comparison.right)}"
+        end
+
+        # A comparison nested inside another comparison is parenthesised: `(1 > 2) = true`.
+        def render_operand(expression)
+          rendered = render_expression(expression)
+          expression.is_a?(Comparison) ? "(#{rendered})" : rendered
+        end
+
+        # Pretty printed, each further operand starts an indented line: `(a\n  AND b)`.
+        def render_compound_condition(condition)
+          if condition.negation?
+            negated = condition.conditions.first
+            rendered = render_expression(negated)
+            return negated.is_a?(RelationshipPatternCondition) ? "NOT #{rendered}" : "NOT (#{rendered})"
+          end
+
+          operands = nested { condition.conditions.map { |inner| render_expression(inner) } }
+          "(#{operands.join("#{break_line(@level + 1)}#{condition.operator} ")})"
+        end
+
+        def render_function_invocation(invocation)
+          arguments = invocation.arguments.map { |argument| render_expression(argument) }
+          name = invocation.function_name
+          legacy = @configuration.dialect == Dialect::NEO4J_4
+          # Neo4j 4 has no elementId(); the closest equivalent is the stringified internal id.
+          return "toString(id(#{arguments.join(', ')}))" if name == 'elementId' && legacy
+
+          name = 'point.distance' if name == 'distance' && !legacy
+          "#{name}(#{'DISTINCT ' if invocation.distinct}#{arguments.join(', ')})"
+        end
+
+        def escape_schema_name(name)
+          @configuration.always_escape_names ? Escaper.escape(name) : Escaper.escape_if_necessary(name)
+        end
+      end
+    end
+  end
+end

data/lib/cypher_dsl/renderer/visitor/patterns.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+module CypherDSL
+  class Renderer
+    class Visitor
+      # Rendering of nodes, relationships, chains, named paths and quantified path patterns.
+      module Patterns
+        private
+
+        def render_pattern_element(element)
+          case element
+          when Node then render_node(element)
+          when Relationship
+            render_node(element.left) + render_relationship_details(element) + render_node(element.right)
+          when RelationshipChain then render_chain(element)
+          when NamedPath then render_named_path(element)
+          when QuantifiedPathPattern then render_quantified_path_pattern(element)
+          else raise ArgumentError, "Cannot render pattern element #{element.inspect}"
+          end
+        end
+
+        def render_named_path(path)
+          selector = path.selector && "#{path.selector.keyword} "
+          "#{render_expression(path.symbolic_name)} = #{selector}#{render_pattern_element(path.pattern)}"
+        end
+
+        def render_quantified_path_pattern(quantified)
+          inner = render_pattern_element(quantified.pattern)
+          inner += " WHERE #{render_expression(quantified.where_condition)}" if quantified.where_condition
+          "(#{inner})#{quantified.quantifier.to_cypher}"
+        end
+
+        def render_chain(chain)
+          chain.relationships.each_with_index.map do |relationship, index|
+            left = index.zero? ? render_node(relationship.left) : ''
+            left + render_relationship_details(relationship) + render_node(relationship.right)
+          end.join
+        end
+
+        # A named node renders in full once per scope and as `(name)` afterwards.
+        # Inside a pattern expression (a pattern used as a condition) no new
+        # variables may be introduced, so an unknown name is left out.
+        def render_node(node)
+          name = node.symbolic_name && resolve_name(node.symbolic_name)
+          return "(#{name})" if name && @visited_names.include?(name)
+
+          @visited_names << name if name && !@in_pattern_expression
+          name = nil if @in_pattern_expression
+          labels = node.labels.map { |label| ":#{render_label(label)}" }.join
+          properties = node.properties && " #{render_expression(node.properties)}"
+          where = node.where_condition && " WHERE #{render_expression(node.where_condition)}"
+          "(#{name}#{labels}#{properties}#{where})"
+        end
+
+        def render_label(label)
+          label.is_a?(LabelExpression) ? render_label_expression(label) : escape_schema_name(label)
+        end
+
+        # `A|B`, `A&B`, `!A`; operands of another kind are parenthesised.
+        def render_label_expression(expression)
+          case expression.type
+          when :leaf then escape_schema_name(expression.value)
+          when :negation then "!#{render_label_operand(expression.operands.first, expression)}"
+          else
+            operator = expression.type == :conjunction ? '&' : '|'
+            expression.operands.map { |operand| render_label_operand(operand, expression) }.join(operator)
+          end
+        end
+
+        def render_label_operand(operand, parent)
+          rendered = render_label_expression(operand)
+          operand.leaf? || operand.type == parent.type || operand.type == :negation ? rendered : "(#{rendered})"
+        end
+
+        # A pattern used as a condition: known names render bare, unknown ones are dropped.
+        def render_pattern_expression(pattern)
+          @in_pattern_expression = true
+          render_pattern_element(pattern)
+        ensure
+          @in_pattern_expression = false
+        end
+
+        # Like nodes, a named relationship renders in full once and as `[name]` afterwards.
+        def render_relationship_details(relationship)
+          details = relationship.details
+          name = relationship.symbolic_name && resolve_name(relationship.symbolic_name)
+          inner = if name && @visited_names.include?(name)
+                    "[#{name}]"
+                  else
+                    @visited_names << name if name && !@in_pattern_expression
+                    content = render_details_content(relationship)
+                    # A name dropped from a pattern expression leaves its brackets behind: `-[]->`.
+                    content.empty? && !(name && @in_pattern_expression) ? '' : "[#{content}]"
+                  end
+          quantifier = details.quantifier&.to_cypher
+          case relationship.direction
+          when :ltr then "-#{inner}->#{quantifier}"
+          when :rtl then "<-#{inner}-#{quantifier}"
+          else "-#{inner}-#{quantifier}"
+          end
+        end
+
+        def render_details_content(relationship)
+          details = relationship.details
+          types = details.types.map { |type| escape_schema_name(type) }.join('|')
+          name = relationship.symbolic_name && !@in_pattern_expression ? resolve_name(relationship.symbolic_name) : nil
+          [
+            name,
+            (":#{types}" unless types.empty?),
+            render_length(details),
+            details.properties && " #{render_expression(details.properties)}",
+            details.where && " WHERE #{render_expression(details.where)}"
+          ].join
+        end
+
+        def render_length(details)
+          return nil unless details.length?
+          return '*' if details.unbounded && details.min.nil? && details.max.nil?
+
+          "*#{details.min}..#{details.max}"
+        end
+      end
+    end
+  end
+end