cypher-dsl 0.1.0.alpha.1

data/lib/cypher_dsl/renderer/visitor.rb

@@ -0,0 +1,298 @@
+# frozen_string_literal: true
+
+module CypherDSL
+  class Renderer
+    # Walks a statement and produces Cypher text. One instance per render call:
+    # it remembers which named nodes have already been rendered with their
+    # content, so later occurrences render as `(name)` only.
+    class Visitor
+      include Patterns
+      include Expressions
+
+      def initialize(configuration)
+        @configuration = configuration
+        @visited_names = Set.new
+        @defined_aliases = {}
+        @generated_names = {}.compare_by_identity
+        @parameter_uses = {}
+        @anonymous_parameters = []
+        @level = 0
+      end
+
+      # The parameters seen while rendering; see {Renderer#catalog}.
+      def catalog = StatementCatalog.from_uses(@parameter_uses)
+
+      def render(statement)
+        return render_union(statement) if statement.is_a?(UnionQuery)
+
+        rendered = statement.clauses.each_with_index.map do |clause, index|
+          @first_clause = index.zero? && @visited_names.empty?
+          render_clause(clause)
+        end.join(break_line)
+        statement.prefix ? "#{statement.prefix} #{rendered}" : rendered
+      end
+
+      private
+
+      # --- pretty printing ------------------------------------------------
+
+      def pretty? = @configuration.pretty_print
+
+      # A clause or entry separator: a newline plus indentation when pretty printing, a space otherwise.
+      def break_line(level = @level)
+        pretty? ? "\n#{@configuration.indent_unit * level}" : ' '
+      end
+
+      # Renders the block one level deeper, e.g. the body of a subquery.
+      def nested
+        @level += 1
+        yield
+      ensure
+        @level -= 1
+      end
+
+      # `opening` + body on its own indented lines + `closing`, or inline when not pretty printing.
+      def block(opening, closing, inline_padding: ' ', &body)
+        body = nested(&body)
+        return "#{opening}#{inline_padding}#{body}#{inline_padding}#{closing}" unless pretty?
+
+        "#{opening}#{break_line(@level + 1)}#{body}#{break_line}#{closing}"
+      end
+
+      public
+
+      # Each statement of a union starts from the scope the union was entered with.
+      def render_union(union)
+        entry_names = @visited_names.dup
+        entry_aliases = @defined_aliases.dup
+        keyword = union.all ? ' UNION ALL' : ' UNION'
+        union.statements.map do |statement|
+          @visited_names = entry_names.dup
+          @defined_aliases = entry_aliases.dup
+          render(statement)
+        end.join("#{keyword}#{break_line}")
+      end
+
+      # Unresolved symbolic names get a generated, render-stable name.
+      def resolve_name(symbolic_name)
+        return symbolic_name.value if symbolic_name.resolved?
+
+        @generated_names[symbolic_name] ||= "#{symbolic_name.hint}#{format('%03d', @generated_names.size + 1)}"
+      end
+
+      private
+
+      # --- clauses ---------------------------------------------------------
+
+      def render_clause(clause)
+        case clause
+        when Clauses::Match then render_match(clause)
+        when Clauses::With then render_with(clause)
+        when Clauses::Return then render_projection('RETURN', clause, nil)
+        when Clauses::RawReturn then clause.items.map { |item| render_projection_item(item) }.join(', ')
+        when Clauses::Create then "CREATE #{render_pattern_elements(clause.pattern_elements)}"
+        when Clauses::Merge then render_merge(clause)
+        when Clauses::Set then "SET #{render_operations(clause.operations)}"
+        when Clauses::Remove then "REMOVE #{render_operations(clause.items)}"
+        when Clauses::Delete then render_delete(clause)
+        when Clauses::Unwind
+          "UNWIND #{render_expression(clause.expression)} AS #{render_expression(clause.variable)}"
+        when Clauses::Finish then 'FINISH'
+        when Clauses::Foreach then render_foreach(clause)
+        when Clauses::Call then render_call(clause)
+        when Clauses::CallSubquery then render_call_subquery(clause)
+        when Clauses::LoadCsv then render_load_csv(clause)
+        when Clauses::Use then "USE #{clause.graph.is_a?(String) ? clause.graph : render_expression(clause.graph)}"
+        else raise ArgumentError, "Cannot render clause #{clause.inspect}"
+        end
+      end
+
+      def render_load_csv(clause)
+        headers = clause.with_headers ? ' WITH HEADERS' : ''
+        "LOAD CSV#{headers} FROM #{render_literal(clause.uri)} AS #{render_expression(clause.alias_name)}"
+      end
+
+      def render_call(clause)
+        name = clause.name_parts.map { |part| Escaper.escape_if_necessary(part) }.join('.')
+        arguments = clause.arguments.map { |argument| render_expression(argument) }.join(', ')
+        parts = ["CALL #{name}(#{arguments})"]
+        yields = clause.yield_items.map { |item| render_projection_item(item) }
+        parts << "YIELD #{yields.join(', ')}" unless yields.empty?
+        parts << "WHERE #{render_expression(clause.where)}" if clause.where && !clause.where.is_a?(NoCondition)
+        parts.join(' ')
+      end
+
+      # `CALL (imports) { body }` on Neo4j 5.23+, `CALL { WITH imports body }` before.
+      # A subquery is its own scope: only imported names count as visited inside.
+      # A leading WITH of plain names in the body is an import list itself.
+      def render_call_subquery(clause)
+        body, imports = subquery_body_and_imports(clause)
+        suffix = clause.in_transactions ? " IN TRANSACTIONS#{" OF #{clause.rows} ROWS" if clause.rows}" : ''
+        if @configuration.legacy_subquery_syntax?
+          prefix = imports.empty? ? nil : "WITH #{imports.map { |import| render_expression(import) }.join(', ')}"
+          opening = 'CALL {'
+        else
+          list = imports.map { |import| render_expression(import) }.join(', ')
+          list = @first_clause ? '' : '*' if imports.empty?
+          prefix = nil
+          opening = "CALL (#{list}) {"
+        end
+        rendered = block(opening, '}', inline_padding: '') do
+          [prefix, render_in_scope(body, scope_of(imports))].compact.join(break_line)
+        end
+        "#{rendered}#{suffix}"
+      end
+
+      # An aliased import (`nodes AS x`) imports the name and renames it with a
+      # leading `WITH nodes AS x` inside the body.
+      def subquery_body_and_imports(clause)
+        body = clause.body
+        return [body, clause.imports] if clause.imports.any? && clause.imports.none?(AliasedExpression)
+        return renamed_imports(body, clause.imports) if clause.imports.any?
+        return [body, []] if body.is_a?(RawExpression) || body.is_a?(UnionQuery)
+
+        first = body.clauses.first
+        return [body, []] unless importing_with?(first)
+
+        legacy = @configuration.legacy_subquery_syntax?
+        [legacy ? body : Statement.new(body.clauses.drop(1), prefix: body.prefix), legacy ? [] : first.items]
+      end
+
+      def renamed_imports(body, imports)
+        names = imports.map { |import| import.is_a?(AliasedExpression) ? import.delegate : import }
+        rename = Clauses::With.new(distinct: false, items: imports, order: nil, skip: nil, limit: nil, where: nil)
+        [Statement.new([rename] + body.clauses, prefix: body.prefix), names]
+      end
+
+      def importing_with?(clause)
+        clause.is_a?(Clauses::With) && !clause.distinct && clause.order.nil? && clause.skip.nil? &&
+          clause.limit.nil? && clause.where.nil? &&
+          clause.items.all? { |item| item.is_a?(SymbolicName) || item.is_a?(Asterisk) }
+      end
+
+      # Imported names form the subquery's scope; `*` imports the whole current scope.
+      def scope_of(imports)
+        return @visited_names.dup if imports.any?(Asterisk)
+
+        imports.filter_map { |import| import.is_a?(SymbolicName) ? resolve_name(import) : nil }.to_set
+      end
+
+      def render_in_scope(body, scope)
+        return body.content if body.is_a?(RawExpression)
+
+        outer_scope = @visited_names
+        @visited_names = scope
+        rendered = render(body)
+        @visited_names = outer_scope
+        rendered
+      end
+
+      # A subquery statement rendered within the current scope (EXISTS / COLLECT).
+      def render_subquery(statement, imports = [])
+        outer_scope = @visited_names.dup
+        prefix = imports.empty? ? '' : "WITH #{imports.map { |import| render_projection_item(import) }.join(', ')} "
+        rendered = render(statement)
+        @visited_names = outer_scope
+        "#{prefix}#{rendered}"
+      end
+
+      # The body of a FOREACH is its own scope: names rendered inside it do not
+      # count as visited outside.
+      def render_foreach(clause)
+        outer_scope = @visited_names.dup
+        body = clause.clauses.map { |inner| render_clause(inner) }.join(' ')
+        @visited_names = outer_scope
+        "FOREACH (#{render_expression(clause.variable)} IN #{render_expression(clause.list)} | #{body})"
+      end
+
+      def render_match(clause)
+        [('OPTIONAL ' if clause.optional), 'MATCH ', render_pattern_elements(clause.pattern_elements),
+         render_where(clause.where)].join
+      end
+
+      def render_merge(clause)
+        actions = clause.actions.map do |action|
+          separator = pretty? ? break_line(@level + 1) : ' '
+          "#{separator}ON #{action.type == :on_match ? 'MATCH' : 'CREATE'} SET #{render_operations(action.operations)}"
+        end
+        "MERGE #{render_pattern_elements(clause.pattern_elements)}#{actions.join}"
+      end
+
+      def render_operations(operations)
+        operations.map { |operation| render_expression(operation) }.join(', ')
+      end
+
+      def render_delete(clause)
+        expressions = clause.expressions.map { |expression| render_expression(expression) }
+        "#{'DETACH ' if clause.detach}DELETE #{expressions.join(', ')}"
+      end
+
+      # WITH ends a query part: only the names it projects stay in scope, so a
+      # node that is not carried over renders with its labels again afterwards.
+      def render_with(clause)
+        rendered = render_projection('WITH', clause, clause.where)
+        @visited_names = clause.items.include?(Asterisk::INSTANCE) ? @visited_names : exported_names(clause.items)
+        rendered
+      end
+
+      def exported_names(items)
+        items.filter_map do |item|
+          case item
+          when AliasedExpression then resolve_name(item.alias_name)
+          when SymbolicName then resolve_name(item)
+          when Node, Relationship then item.symbolic_name && resolve_name(item.symbolic_name)
+          end
+        end.to_set
+      end
+
+      def render_projection(keyword, clause, where)
+        items = clause.items.map { |item| render_projection_item(item) }.join(', ')
+        parts = ["#{keyword} #{'DISTINCT ' if clause.distinct}#{items}"]
+        parts << "ORDER BY #{clause.order.items.map { |item| render_sort_item(item) }.join(', ')}" if clause.order
+        parts << "SKIP #{render_expression(clause.skip)}" if clause.skip
+        parts << "LIMIT #{render_expression(clause.limit)}" if clause.limit
+        "#{parts.join(' ')}#{render_where(where)}"
+      end
+
+      # In RETURN/WITH an aliased expression is defined once (`expr AS alias`);
+      # afterwards, and anywhere else, it is a reference and renders as the alias.
+      def render_projection_item(item)
+        return render_expression(item) unless item.is_a?(AliasedExpression)
+
+        alias_name = resolve_name(item.alias_name)
+        return Escaper.escape_if_necessary(alias_name) if alias_defined?(item, alias_name)
+
+        rendered = "#{render_expression(item.delegate)} AS #{render_expression(item.alias_name)}"
+        @defined_aliases[alias_name] = item.delegate
+        rendered
+      end
+
+      def render_aliased_reference(item)
+        alias_name = resolve_name(item.alias_name)
+        return Escaper.escape_if_necessary(alias_name) if alias_defined?(item, alias_name)
+
+        render_expression(item.delegate)
+      end
+
+      # The same alias may be given to another expression later (`WITH a AS x RETURN count(*) AS x`).
+      def alias_defined?(item, alias_name)
+        @defined_aliases.key?(alias_name) && @defined_aliases[alias_name] == item.delegate
+      end
+
+      def render_pattern_elements(elements)
+        elements.map { |element| render_pattern_element(element) }.join(', ')
+      end
+
+      # WHERE goes on its own line when pretty printing.
+      def render_where(condition)
+        return nil if condition.nil? || condition.is_a?(NoCondition)
+
+        "#{break_line}WHERE #{render_expression(condition)}"
+      end
+
+      def render_sort_item(item)
+        [render_expression(item.expression), item.direction&.to_s&.upcase].compact.join(' ')
+      end
+    end
+  end
+end

data/lib/cypher_dsl/renderer.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module CypherDSL
+  # Turns a {Statement} into Cypher text according to a {Renderer::Configuration}.
+  class Renderer
+    def self.default = @default ||= new(Configuration::DEFAULT)
+
+    # Mirrors `Renderer.getRenderer(configuration)`.
+    def self.get_renderer(configuration) = new(configuration)
+
+    attr_reader :configuration
+
+    def initialize(configuration)
+      @configuration = configuration
+      freeze
+    end
+
+    def render(statement) = Visitor.new(configuration).render(statement)
+
+    # The statement's parameters as a {StatementCatalog}; raises
+    # {ConflictingParametersException} when a name is bound inconsistently.
+    def catalog(statement)
+      visitor = Visitor.new(configuration)
+      visitor.render(statement)
+      visitor.catalog
+    end
+  end
+end

data/lib/cypher_dsl/sort_item.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module CypherDSL
+  # One item of an ORDER BY: an expression with an optional direction.
+  class SortItem
+    attr_reader :expression, :direction
+
+    def initialize(expression, direction)
+      @expression = expression
+      @direction = direction
+      freeze
+    end
+
+    def ascending = SortItem.new(expression, :asc)
+    def descending = SortItem.new(expression, :desc)
+  end
+end

data/lib/cypher_dsl/standalone_call.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module CypherDSL
+  # `Cypher.call('db.labels')`: a procedure call being built. `with_args` adds
+  # arguments, `yield` selects outputs and continues as a statement builder,
+  # `build` finishes a bare call, `as_function` turns it into a function
+  # invocation instead.
+  class StandaloneCall
+    AGGREGATES = %w[avg collect count max min percentilecont percentiledisc stdev stdevp sum].freeze
+
+    attr_reader :name_parts, :arguments
+
+    # `name_parts` as given to `Cypher.call`: strings, symbols or arrays, dotted names split.
+    def initialize(name_parts, arguments: [], builder: nil)
+      @name_parts = name_parts.flatten.flat_map { |part| part.to_s.split('.') }.freeze
+      @arguments = arguments.freeze
+      @builder = builder
+      freeze
+    end
+
+    def procedure_name = name_parts.join('.')
+
+    def with_args(*expressions)
+      StandaloneCall.new(name_parts, arguments: expressions.flatten.map { |e| Expression.coerce(e) }, builder: @builder)
+    end
+
+    # `YIELD item, item AS alias, …`; continues as a statement builder.
+    def yield(*items)
+      yield_items = items.flatten.map { |item| yield_item(item) }
+      (@builder || StatementBuilder.new).send(:append, clause(yield_items), :condition)
+    end
+
+    def build = Statement.new((@builder&.send(:clauses) || []) + [clause([])])
+
+    # The call without YIELD, continuing as a statement builder (for `VOID` procedures).
+    def without_results = (@builder || StatementBuilder.new).send(:append, clause([]), nil)
+
+    # The procedure as a function invocation; `distinct` only for aggregates.
+    def as_function(distinct = false) # rubocop:disable Style/OptionalBooleanParameter
+      if distinct && !AGGREGATES.include?(procedure_name.downcase)
+        raise ArgumentError, 'The distinct operator can only be applied within aggregate functions.'
+      end
+
+      FunctionInvocation.new(procedure_name, arguments, distinct:)
+    end
+
+    private
+
+    def clause(yield_items)
+      Clauses::Call.new(name_parts:, arguments:, yield_items: yield_items.freeze, where: nil)
+    end
+
+    def yield_item(item)
+      case item
+      when String, Symbol then SymbolicName.of(item)
+      when SymbolicName, AliasedExpression, Asterisk then item
+      else raise ArgumentError, "Cannot yield #{item.inspect}"
+      end
+    end
+  end
+end

data/lib/cypher_dsl/statement.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module CypherDSL
+  # A built, immutable statement: an ordered list of clauses. Rendering with the
+  # default renderer is memoised, as in the Java `Statement#getCypher`.
+  class Statement
+    attr_reader :clauses, :prefix
+
+    # An empty builder, as `Statement.builder()` in Java.
+    def self.builder = StatementBuilder.new
+
+    # A statement from a list of clause objects, as `Statement.of(clauses)` in Java.
+    def self.of(clauses) = new(clauses)
+
+    # `prefix` is `EXPLAIN` or `PROFILE` for the corresponding statement kinds.
+    def initialize(clauses, prefix: nil)
+      @clauses = clauses.freeze
+      @prefix = prefix
+      @cypher = nil
+    end
+
+    def cypher
+      @cypher ||= Renderer.default.render(self).freeze
+    end
+
+    # Parameter names and bound values; raises {ConflictingParametersException}
+    # when a name is bound inconsistently. Memoised, like `cypher`.
+    def catalog
+      @catalog ||= Renderer.default.catalog(self)
+    end
+
+    # `name => value` for every parameter that carries a value.
+    def parameters = catalog.parameters
+
+    # Every parameter name used, bound or not.
+    def parameter_names = catalog.parameter_names
+
+    # True when the statement produces rows: it ends with RETURN, or is a
+    # procedure call with YIELD.
+    def result_statement?
+      last = clauses.last
+      last.is_a?(Clauses::Return) || last.is_a?(Clauses::RawReturn) ||
+        (last.is_a?(Clauses::Call) && !last.yield_items.empty?)
+    end
+
+    # True when the statement is a bare procedure call, with or without YIELD.
+    def procedure_call? = clauses.size == 1 && clauses.first.is_a?(Clauses::Call)
+
+    # True when the statement contains no WITH, i.e. has a single query part.
+    def single_query? = !multi_part_query?
+
+    def multi_part_query? = clauses.any?(Clauses::With)
+
+    def to_s = cypher
+  end
+end