cypher-dsl 0.1.0.alpha.1 → 0.1.0.alpha.2

data/lib/cypher_dsl/literal.rb

@@ -1,11 +1,17 @@
 # frozen_string_literal: true
 
+require 'date'
+require 'time'
+
 module CypherDSL
-  # A literal value rendered inline: strings, numbers, booleans, NULL and lists.
-  # Hashes become a {MapExpression}; expressions are returned unchanged.
+  # A literal value rendered inline: strings, numbers, booleans, NULL, dates and
+  # times. Hashes become a {MapExpression}, arrays a {ListExpression}; expressions
+  # are returned unchanged.
   class Literal
     include Expression
 
+    SUPPORTED_TYPES = [String, Numeric, TrueClass, FalseClass, NilClass, Date, Time].freeze
+
     attr_reader :value
 
     def self.of(value)
@@ -13,15 +19,31 @@ module CypherDSL
       when Expression then value
       when Hash then MapExpression.of(value)
       when Array then ListExpression.of(value)
+      when true then Literal::TRUE
+      when false then Literal::FALSE
+      when nil then Literal::NULL
       else new(value)
       end
     end
 
+    # `'…'`, with backslashes and quotes escaped; `nil` quotes to `''`.
+    def self.quote(string) = "'#{escape_string(string)}'"
+
+    # The content of a string literal: backslashes, single and double quotes get a backslash.
+    def self.escape_string(string) = string&.gsub(/['"\\]/) { |character| "\\#{character}" }
+
     def initialize(value)
+      unless SUPPORTED_TYPES.any? { |type| value.is_a?(type) }
+        raise ArgumentError, "Unsupported literal type: #{value.class}"
+      end
+
       @value = value.frozen? ? value : value.dup.freeze
       freeze
     end
 
+    # The literal as Cypher, as the Java `Literal#asString`.
+    def as_string = to_s
+
     TRUE = new(true)
     FALSE = new(false)
     NULL = new(nil)

data/lib/cypher_dsl/named_path.rb

@@ -40,16 +40,19 @@ module CypherDSL
 
     # `Cypher.any_shortest` and friends: a path selector waiting for `named`.
     class Selector
-      attr_reader :keyword
+      # `legacy_function` is the pre-5.21 spelling (`shortestPath`, `allShortestPaths`), if any.
+      attr_reader :keyword, :legacy_function
 
       def self.shortest_k(count, groups: false)
         raise ArgumentError, 'The path count needs to be greater than 0.' unless count.positive?
 
-        new("SHORTEST #{count}#{' GROUPS' if groups}")
+        legacy_function = count == 1 && !groups ? 'shortestPath' : nil
+        new("SHORTEST #{count}#{' GROUPS' if groups}", legacy_function:)
       end
 
-      def initialize(keyword)
+      def initialize(keyword, legacy_function: nil)
         @keyword = keyword
+        @legacy_function = legacy_function
         freeze
       end
 

data/lib/cypher_dsl/node.rb

@@ -40,14 +40,19 @@ module CypherDSL
     def name_hint = labels.first.is_a?(String) ? labels.first.downcase : 'n'
     alias as_expression required_symbolic_name
 
-    def property(*names) = Property.new(required_symbolic_name, names)
+    # `n.prop`; the property keeps this node as its container (index hints need the label),
+    # the name is settled now so generated names keep their order.
+    def property(*names)
+      required_symbolic_name
+      Property.new(self, names)
+    end
 
     # The condition `n:Label`, checking the node for the given labels.
     def has_labels(*labels) = HasLabelCondition.new(self, labels)
 
-    # `n += {…}` and `n = {…}`, for use in SET.
-    def mutate(expression) = Operation.new(self, '+=', Expression.coerce(expression))
-    def set(expression) = Operation.new(self, '=', Expression.coerce(expression))
+    # `n += {…}` and `n = {…}`, for use in SET; the node must be named.
+    def mutate(expression) = Operation.new(named_for_update, '+=', Expression.coerce(expression))
+    def set(expression) = Operation.new(named_for_update, '=', Expression.coerce(expression))
 
     # The map projection `n{…}`, built on the (possibly generated) name.
     def project(*entries) = MapProjection.new(required_symbolic_name, entries.flatten)
@@ -76,6 +81,12 @@ module CypherDSL
 
     private
 
+    def named_for_update
+      raise ArgumentError, 'A property container must be named to be mutated.' unless named?
+
+      self
+    end
+
     def with(**changes)
       Node.new(labels:, symbolic_name: @symbolic_name, properties:, where_condition:, **changes)
     end

data/lib/cypher_dsl/property.rb

@@ -6,18 +6,25 @@ module CypherDSL
   class Property
     include Expression
 
-    attr_reader :container, :names
+    attr_reader :container, :names, :external_reference
 
-    def initialize(container, names)
+    def initialize(container, names, external_reference: nil)
       @container = container
       @names = names.map { |name| name.is_a?(Expression) ? name : name.to_s }.freeze
       raise ArgumentError, 'A property needs at least one name.' if @names.empty?
 
+      @external_reference = external_reference
       freeze
     end
 
     def nested? = names.size > 1
 
+    # The dotted name (`address.city`), or the external reference if one was given.
+    def name = external_reference || names.join('.')
+
+    # The same property known under another name, e.g. the attribute it maps to.
+    def referenced_as(reference) = Property.new(container, names, external_reference: reference.to_s)
+
     # `n.prop = value`, for use in SET.
     def to(expression) = Operation.new(self, '=', Expression.coerce(expression))
   end

data/lib/cypher_dsl/property_exists_condition.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module CypherDSL
+  # `Cypher.exists(n.prop)`: `exists(n.prop)` on Neo4j 4, `n.prop IS NOT NULL`
+  # from Neo4j 5 on (and `n.prop IS NULL` when negated).
+  class PropertyExistsCondition < Condition
+    attr_reader :property
+
+    def initialize(property)
+      super()
+      @property = property
+      freeze
+    end
+  end
+end

data/lib/cypher_dsl/raw_expression.rb

@@ -2,14 +2,87 @@
 
 module CypherDSL
   # A fragment of Cypher text rendered verbatim: the escape hatch, like `Arel.sql`.
+  #
+  # `RawExpression.create(format, *arguments)` mirrors `Cypher.raw(format, args…)`:
+  # every `$E` in the format is replaced by the next argument (expressions as they are,
+  # anything else as a literal); `\$E` stands for a literal `$E`. A `$name` matching a
+  # named parameter among the arguments is bound to that parameter.
   class RawExpression
     include Expression
 
-    attr_reader :content
+    PLACEHOLDER = /((\\?\$(\w+))(?:\s*|$))/
+    EXPRESSION_PLACEHOLDER = '$E'
+    private_constant :PLACEHOLDER, :EXPRESSION_PLACEHOLDER
 
-    def initialize(content)
-      @content = content.to_s
+    # Strings and expressions, in order.
+    attr_reader :parts
+
+    def self.create(format, *mixed_arguments)
+      raise ArgumentError, 'Cannot create a raw literal without a format.' if format.nil? || format.strip.empty?
+
+      new(Parser.new(format, mixed_arguments).parts)
+    end
+
+    # `parts` is a string or a list of strings and expressions.
+    def initialize(parts)
+      @parts = Array(parts).filter_map do |part|
+        next part unless part.is_a?(String)
+
+        part.gsub('\$E', EXPRESSION_PLACEHOLDER) unless part.empty?
+      end.freeze
       freeze
     end
+
+    # The text, with expressions in their default rendering.
+    def content = parts.join
+
+    # Splits a format into text and the expressions bound to its placeholders.
+    class Parser
+      def initialize(format, mixed_arguments)
+        @format = format
+        @parameters = mixed_arguments.grep(Parameter).reject(&:anonymous?).to_h { |p| [p.name, p] }
+        @positional = mixed_arguments.dup
+        @matches = format.enum_for(:scan, PLACEHOLDER).map { Regexp.last_match }
+        # Placeholders naming an actual parameter take it with precedence over the positional ones.
+        @matches.each { |match| @positional.delete(@parameters[match[3]]) if @parameters.key?(match[3]) }
+        @parts = []
+        @index = 0
+        @count = 0
+      end
+
+      def parts
+        @matches.each { |match| consume(match) }
+        raise ArgumentError, "Too many arguments for the raw literal format `#{@format}`." if @count < @positional.size
+
+        @parts + [@format[@index..]]
+      end
+
+      private
+
+      def consume(match)
+        if match[2] == EXPRESSION_PLACEHOLDER
+          bind(match, next_positional)
+        elsif @parameters.key?(match[3])
+          bind(match, @parameters[match[3]])
+        else
+          @parts << @format[@index...match.end(0)]
+          @index = match.end(0)
+        end
+      end
+
+      def bind(match, expression)
+        @parts << @format[@index...match.begin(2)] << expression
+        @index = match.end(2)
+      end
+
+      def next_positional
+        raise ArgumentError, "Too few arguments for the raw literal format `#{@format}`." if @count >= @positional.size
+
+        argument = @positional[@count]
+        @count += 1
+        Expression.coerce(argument)
+      end
+    end
+    private_constant :Parser
   end
 end

data/lib/cypher_dsl/relationship.rb

@@ -32,6 +32,9 @@ module CypherDSL
     end
 
     def initialize(left, direction, right, details)
+      raise ArgumentError, 'Left node is required.' if left.nil?
+      raise ArgumentError, 'Right node is required.' if right.nil?
+
       @left = left
       @direction = direction
       @right = right
@@ -72,7 +75,11 @@ module CypherDSL
     # The pattern as a predicate, `WHERE (a)-[:X]->(b)`.
     def as_condition = RelationshipPatternCondition.new(self)
 
-    def property(*names) = Property.new(required_symbolic_name, names)
+    # `r.prop`; the property keeps this relationship as its container (index hints need the type).
+    def property(*names)
+      required_symbolic_name
+      Property.new(self, names)
+    end
 
     # `r += {…}` and `r = {…}`, for use in SET.
     def mutate(expression) = Operation.new(self, '+=', Expression.coerce(expression))

data/lib/cypher_dsl/relationship_chain.rb

@@ -31,6 +31,9 @@ module CypherDSL
     # The chain as a predicate.
     def as_condition = RelationshipPatternCondition.new(self)
 
+    # The pattern as Cypher, names escaped only when necessary.
+    def to_s = Renderer.plain.render_fragment(self)
+
     private
 
     def add(direction, other, types)

data/lib/cypher_dsl/renderer/configuration.rb

@@ -9,13 +9,22 @@ module CypherDSL
     # - `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.
+    # - `disable_dynamic_labels`: render label expressions statically even on dialects
+    #   that support `n:$($labels)`.
+    # - `generated_names`: rewrite names while rendering (`v0`, `v1`, … and `p0`, `p1`, …);
+    #   `true` for all of {GENERATED_NAMES}, or a subset of those flags.
     class Configuration
-      attr_reader :always_escape_names, :dialect, :pretty_print, :indent_size, :indent_style
+      # The Java `GeneratedNames` enum: which names get rewritten. `reuse_aliases` makes an alias
+      # that is defined again reuse its generated name instead of getting a new one.
+      GENERATED_NAMES = %i[entity_names parameter_names all_aliases internal_aliases_only reuse_aliases].freeze
+
+      attr_reader :always_escape_names, :dialect, :pretty_print, :indent_size, :indent_style, :disable_dynamic_labels,
+                  :generated_names
 
       # `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)
+      def initialize(always_escape_names: nil, dialect: Dialect::NEO4J_5_DEFAULT_CYPHER, pretty_print: false,
+                     indent_size: 2, indent_style: :space, disable_dynamic_labels: false, generated_names: false)
         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)
 
@@ -24,10 +33,25 @@ module CypherDSL
         @pretty_print = pretty_print
         @indent_size = indent_size
         @indent_style = indent_style
+        @disable_dynamic_labels = disable_dynamic_labels
+        @generated_names = generated_name_flags(generated_names)
         freeze
       end
 
-      DEFAULT = new
+      def use_generated_names? = !generated_names.empty?
+
+      # Every option by name; configurations with equal options are equal.
+      def to_h
+        { always_escape_names:, dialect:, pretty_print:, indent_size:, indent_style:, disable_dynamic_labels:,
+          generated_names: }
+      end
+
+      def ==(other) = other.is_a?(Configuration) && other.to_h == to_h
+      alias eql? ==
+      def hash = to_h.hash
+
+      # The default configuration, as used by `Statement#cypher`.
+      def self.default = @default ||= new
 
       # Mirrors `Configuration.newConfig()…build()`.
       def self.new_config = Builder.new
@@ -38,6 +62,18 @@ module CypherDSL
       # `CALL { WITH imports … }` (older dialects) rather than `CALL (imports) { … }`.
       def legacy_subquery_syntax? = Dialect::LEGACY_SUBQUERY_SYNTAX.include?(dialect)
 
+      # `shortestPath()` / `allShortestPaths()` functions rather than `SHORTEST 1` / `ALL SHORTEST` selectors.
+      def legacy_path_selectors? = Dialect::LEGACY_PATH_SELECTORS.include?(dialect)
+
+      # `exists(n.prop)` and `distance()` rather than `n.prop IS NOT NULL` and `point.distance()`.
+      def legacy_functions? = dialect == Dialect::NEO4J_4
+
+      # `n:$($labels)` is available and wanted.
+      def dynamic_labels? = Dialect::DYNAMIC_LABELS.include?(dialect) && !disable_dynamic_labels
+
+      # The `CYPHER 5 ` / `CYPHER 25 ` statement prefix of the dialect, if any.
+      def prefix = Dialect::PREFIXES[dialect]
+
       def indent_unit = indent_style == :tab ? "\t" : ' ' * indent_size
 
       # Fluent builder; each setter returns the builder.
@@ -52,6 +88,13 @@ module CypherDSL
         def with_indent_size(size) = option(:indent_size, size)
         def with_indent_style(style) = option(:indent_style, style)
 
+        def disable_dynamic_labels(value = true) # rubocop:disable Style/OptionalBooleanParameter -- Java signature
+          option(:disable_dynamic_labels, value)
+        end
+
+        # `true`, `false` or a list of {Configuration::GENERATED_NAMES} flags.
+        def with_generated_names(value) = option(:generated_names, value)
+
         def build = Configuration.new(**@options)
 
         private
@@ -61,6 +104,20 @@ module CypherDSL
           self
         end
       end
+
+      private
+
+      def generated_name_flags(value)
+        flags = case value
+                when true then GENERATED_NAMES
+                when false, nil then []
+                else value.to_a.map(&:to_sym)
+                end
+        unknown = flags - GENERATED_NAMES
+        raise ArgumentError, "Unknown generated name flags #{unknown.inspect}" unless unknown.empty?
+
+        flags.to_set.freeze
+      end
     end
   end
 end

data/lib/cypher_dsl/renderer/dialect.rb

@@ -2,19 +2,36 @@
 
 module CypherDSL
   class Renderer
-    # Target Cypher dialects.
+    # Target Cypher dialects, mirroring the Java enum.
     #
-    # - 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.
+    # - NEO4J_4: `CALL { WITH imports … }` subqueries, `shortestPath()` functions,
+    #   `exists(n.prop)`, `distance()`, `elementId(x)` rendered as `toString(id(x))`.
+    # - NEO4J_5: as above with native `elementId`, `point.distance()` and `n.prop IS NOT NULL`.
+    # - NEO4J_5_23: `CALL (imports) { … }` subqueries and `SHORTEST k` path selectors.
+    # - NEO4J_5_26: adds dynamic labels (`n:$($labels)`) and the `CYPHER 5` prefix.
+    # - NEO4J_5_DEFAULT_CYPHER (default): like NEO4J_5_26 without the prefix.
+    # - NEO4J_5_CYPHER_5 / NEO4J_5_CYPHER_25: with an explicit `CYPHER 5` / `CYPHER 25` prefix.
+    # - NEO4J_2025: like NEO4J_5_23.
     module Dialect
+      # rubocop:disable Naming/VariableNumber
       NEO4J_4 = :neo4j4
       NEO4J_5 = :neo4j5
-      NEO4J_5_23 = :neo4j5_23 # rubocop:disable Naming/VariableNumber
-      NEO4J_5_DEFAULT_CYPHER = NEO4J_5_23
+      NEO4J_5_23 = :neo4j5_23
+      NEO4J_5_26 = :neo4j5_26
+      NEO4J_5_DEFAULT_CYPHER = :neo4j5_default_cypher
+      NEO4J_5_CYPHER_5 = :neo4j5_cypher_5
+      NEO4J_5_CYPHER_25 = :neo4j5_cypher_25
+      NEO4J_2025 = :neo4j2025
+      # rubocop:enable Naming/VariableNumber
 
-      ALL = [NEO4J_4, NEO4J_5, NEO4J_5_23].freeze
+      ALL = [NEO4J_4, NEO4J_5, NEO4J_5_23, NEO4J_5_26, NEO4J_5_DEFAULT_CYPHER, NEO4J_5_CYPHER_5, NEO4J_5_CYPHER_25,
+             NEO4J_2025].freeze
       LEGACY_SUBQUERY_SYNTAX = [NEO4J_4, NEO4J_5].freeze
+      LEGACY_PATH_SELECTORS = [NEO4J_4, NEO4J_5].freeze
+      DYNAMIC_LABELS = [NEO4J_5_26, NEO4J_5_DEFAULT_CYPHER, NEO4J_5_CYPHER_5, NEO4J_5_CYPHER_25].freeze
+      PREFIXES = {
+        NEO4J_5_26 => 'CYPHER 5 ', NEO4J_5_CYPHER_5 => 'CYPHER 5 ', NEO4J_5_CYPHER_25 => 'CYPHER 25 '
+      }.freeze
     end
   end
 end

data/lib/cypher_dsl/renderer/escaper.rb

@@ -2,24 +2,27 @@
 
 module CypherDSL
   class Renderer
-    # Backtick escaping of schema names and identifiers.
+    # Backtick escaping of schema names and identifiers, following the upstream
+    # rules: the text ``` stands for a backtick, doubled backticks are
+    # collapsed first, then every backtick is doubled and the name wrapped.
     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
+      UNICODE_BACKTICK = "#{92.chr}u0060".freeze
 
       module_function
 
-      # Always escapes, unless the name already is.
+      # Always escapes.
       def escape(name)
-        return name if ESCAPED.match?(name)
-
-        "`#{name.gsub('`', '``')}`"
+        normalized = name.gsub(UNICODE_BACKTICK, '`').gsub('``', '`')
+        "`#{normalized.gsub('`', '``')}`"
       end
 
-      # Escapes only names that are not plain identifiers.
+      # Escapes only names that are not plain identifiers; `nil` stays `nil`.
       def escape_if_necessary(name)
+        return nil if name.nil?
+
         IDENTIFIER.match?(name) ? name : escape(name)
       end
 

data/lib/cypher_dsl/renderer/generated_name_resolver.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+module CypherDSL
+  class Renderer
+    # Rewrites names to `v0`, `v1`, … per scope and parameters to `p0`, `p1`, …,
+    # controlled by the flags of `Configuration::GENERATED_NAMES` (the Java
+    # `GeneratedNames` enum).
+    class GeneratedNameResolver < NameResolver
+      def initialize(flags)
+        super()
+        @flags = flags.to_set
+        @parameter_count = 0
+        @counters = []
+        @lookups = []
+        @used = []
+        enter_scope([])
+      end
+
+      # `imports` are the identifiables visible inside the new scope, or `:all`.
+      def enter_scope(imports)
+        outer = @lookups.last
+        lookup = {}
+        used = Set.new
+        if outer
+          lookup = imports == :all ? outer.dup : imports.to_h { |import| [key_of(import), outer[key_of(import)]] }
+          lookup.compact!
+          used.merge(outer.values)
+        end
+        @counters << 0
+        @lookups << lookup
+        @used << used
+      end
+
+      # `exports` are the identifiables the scope returns to its outer scope, or `:all`.
+      def leave_scope(exports)
+        @counters.pop
+        inner = @lookups.pop
+        @used.pop
+        outer = @lookups.last
+        if exports == :all
+          outer.merge!(inner)
+        else
+          exports.each { |export| outer[key_of(export)] = exported_name(export, inner) }
+        end
+        @used.last.merge(inner.values)
+      end
+
+      def resolve(symbolic_name, in_entity: false)
+        key = key_of(symbolic_name)
+        lookup = @lookups.last
+        if !flag?(:entity_names) || (!in_entity && !flag?(:all_aliases) && !flag?(:internal_aliases_only))
+          return lookup[key] if lookup.key?(key)
+
+          return super
+        end
+
+        lookup[key] ||= new_name
+      end
+
+      def resolve_alias(aliased, define: false, in_last_return: false)
+        return super unless flag?(:all_aliases) || (flag?(:internal_aliases_only) && !in_last_return)
+
+        key = key_of(aliased)
+        lookup = @lookups.last
+        return lookup[key] ||= new_name if flag?(:reuse_aliases)
+        return lookup.fetch(key) { super } unless define
+
+        lookup[key] = new_name
+      end
+
+      def resolve_parameter(parameter)
+        return super if !flag?(:parameter_names) || parameter.anonymous?
+
+        @lookups.last[[:parameter, parameter.name]] ||= begin
+          name = "p#{@parameter_count}"
+          @parameter_count += 1
+          name
+        end
+      end
+
+      private
+
+      def flag?(flag) = @flags.include?(flag)
+
+      def key_of(object)
+        case object
+        when AliasedExpression then object.alias_name
+        when Node, Relationship then object.required_symbolic_name
+        else object
+        end
+      end
+
+      def exported_name(export, inner)
+        key = key_of(export)
+        return inner[key] if inner.key?(key)
+
+        context_name(key)
+      end
+
+      def new_name
+        used = @used.last
+        loop do
+          name = "v#{@counters.last}"
+          @counters[-1] += 1
+          return name unless used.include?(name)
+        end
+      end
+    end
+  end
+end

data/lib/cypher_dsl/renderer/name_resolver.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module CypherDSL
+  class Renderer
+    # Resolves symbolic names, aliases and parameter names while rendering.
+    # The base strategy keeps the given names and invents `hint001`-style names
+    # for elements that were referenced without ever being named.
+    class NameResolver
+      def initialize
+        @context_names = {}.compare_by_identity
+      end
+
+      def resolve(symbolic_name, in_entity: false) # rubocop:disable Lint/UnusedMethodArgument
+        context_name(symbolic_name)
+      end
+
+      def resolve_alias(aliased, define: false, in_last_return: false) # rubocop:disable Lint/UnusedMethodArgument
+        context_name(aliased.alias_name)
+      end
+
+      def resolve_parameter(parameter) = parameter.name
+
+      def enter_scope(imports); end
+      def leave_scope(exports); end
+
+      private
+
+      def context_name(symbolic_name)
+        return symbolic_name.value if symbolic_name.resolved?
+
+        @context_names[symbolic_name] ||= "#{symbolic_name.hint}#{format('%03d', @context_names.size + 1)}"
+      end
+    end
+  end
+end