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

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5430e442ecb75b449cefb44e0b4d1e06ccdc80ca8a4dc10a7f3da2366a8cb049
-  data.tar.gz: 393b61210b500da83e53ea17706bc8e8e691ed3f813f69c1557c85a6be86e182
+  metadata.gz: a83e4601b0dc6294144bb3e5a87463cf322861e94927fc5ccfa7c14ab5389e0c
+  data.tar.gz: f7475774c957b6ad901caf376774ef2d09d97731874f3cd1b569aec141219089
 SHA512:
-  metadata.gz: 15d7b9bedab4f4d8072928d4d8dd207b3ab3fa4e7b4dc8c98422af314806cc5b00441a478b672640f626e4e2b0320202323990c710f0f6a1eac3c9abb52c8c8f
-  data.tar.gz: d0634d9fc01f6375253637d9bdd4e94a1357dce52ab0be19188c8aed5fcecadd56932e0d88a60ce65a6b7e5f721be3161ce0e7c91b9f4ce7d3b529bfa6a94ea7
+  metadata.gz: ef77aec97883fc7445c7ecf759d4d6438c614818bb27cbd6c85fe239d9757a0508cf9f0e2348871a2b291f101756a453ccc5930e76eecb6ecb61db6120e4f8d9
+  data.tar.gz: 0a37e339fa998ae143fc5691a4c50b4d18f8aa322e21ca9f66065ee1d1005304603928cfbe9884bb16905cb55f870eb8bd6facc5cd19f6df2c82c10f48639340

data/CHANGELOG.md

@@ -7,6 +7,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.1.0.alpha.3] - 2026-11-01
+
+The release activegraph's `ActiveGraph::Core::Query` builds on.
+
+### Added
+
+- Raw fragments for host DSLs built on strings (Ruby-only, no Java counterpart): `Cypher.raw`
+  is accepted as a pattern element in MATCH/CREATE/MERGE, as a condition (also as operand of
+  `and`/`or`/`xor`/`not`), as a complete SET / ON CREATE SET / ON MATCH SET operation, and
+  `StatementBuilder#raw_clause(format, *args)` renders a whole clause verbatim.
+- Raw operands of a compound condition are parenthesised unless they already form one group,
+  so `Cypher.raw('a OR b').as_condition.and(c)` renders `((a OR b) AND c)`.
+
 ## [0.1.0.alpha.2] - 2026-11-01
 
 Second pre-release. The whole upstream core test suite that applies to Ruby is now
@@ -79,6 +92,7 @@ collection, IssueRelatedIT, FunctionsIT).
 - Renderer with dialects (Neo4j 4, 5, 5.23+), pretty printing, identifier escaping,
   parameter collection (`Statement#catalog`).
 
-[Unreleased]: https://github.com/neo4jrb/cypher-dsl/compare/v0.1.0.alpha.2...HEAD
+[Unreleased]: https://github.com/neo4jrb/cypher-dsl/compare/v0.1.0.alpha.3...HEAD
+[0.1.0.alpha.3]: https://github.com/neo4jrb/cypher-dsl/compare/v0.1.0.alpha.2...v0.1.0.alpha.3
 [0.1.0.alpha.2]: https://github.com/neo4jrb/cypher-dsl/compare/v0.1.0.alpha.1...v0.1.0.alpha.2
 [0.1.0.alpha.1]: https://github.com/neo4jrb/cypher-dsl/releases/tag/v0.1.0.alpha.1

data/README.md

@@ -75,6 +75,19 @@ Cypher.returning(Cypher.raw('($E + $E) * $factor', Cypher.parameter(:a), 2, Cyph
   .build.cypher # => "RETURN ($a + 2) * $factor AS r"
 ```
 
+A raw fragment is also accepted as a pattern element, as a condition, as a `SET`
+operation, and `raw_clause` renders a whole clause verbatim. These are escape hatches
+for DSLs that have to pass user-written Cypher through; a raw condition combined with
+others is parenthesised so its precedence survives:
+
+```ruby
+Cypher.match(Cypher.raw('(n)-[:KNOWS]->(m)'))
+  .where(Cypher.property(:n, :age).gt(30).and(Cypher.raw('m.name STARTS WITH "A" OR m.vip')))
+  .raw_clause('CALL db.labels() YIELD label')
+  .returning(:n, :label).build.cypher
+# => "MATCH (n)-[:KNOWS]->(m) WHERE (n.age > 30 AND (m.name STARTS WITH \"A\" OR m.vip)) CALL db.labels() YIELD label RETURN n, label"
+```
+
 Every expression and pattern answers `to_s` with its plain Cypher, e.g.
 `Cypher.node('Person').named(:n).to_s # => "(n:Person)"`.
 
@@ -125,7 +138,7 @@ The flags are `entity_names`, `parameter_names`, `all_aliases`, `internal_aliase
 Pre-releases are not picked up by a bare requirement, so name the version:
 
 ```ruby
-gem 'cypher-dsl', '0.1.0.alpha.2'
+gem 'cypher-dsl', '0.1.0.alpha.3'
 ```
 
 Requires Ruby 3.4 or newer.

data/lib/cypher_dsl/clauses/raw.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module CypherDSL
+  module Clauses
+    # A clause rendered verbatim from a {RawExpression}: the escape hatch for
+    # Cypher the builder does not model (`raw_clause('CALL db.labels()')`).
+    Raw = Data.define(:expression)
+  end
+end

data/lib/cypher_dsl/condition.rb

@@ -10,7 +10,7 @@ module CypherDSL
       case value
       when Condition then value
       when Relationship, RelationshipChain then RelationshipPatternCondition.new(value)
-      when FunctionInvocation then ExpressionCondition.new(value) # boolean functions such as isEmpty()
+      when FunctionInvocation, RawExpression then ExpressionCondition.new(value) # isEmpty(), raw text
       else raise ArgumentError, "#{value.inspect} is not a condition"
       end
     end

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

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module CypherDSL
+  class Renderer
+    class Visitor
+      # Rendering of comparisons and compound conditions.
+      module Conditions
+        private
+
+        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
+
+        # `exists(n.prop)` on Neo4j 4, `n.prop IS NOT NULL` afterwards.
+        def render_property_exists(condition, negated: false)
+          property = render_expression(condition.property)
+          return "exists(#{property})" if @configuration.legacy_functions?
+
+          "#{property} IS #{'NOT ' unless negated}NULL"
+        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
+            if negated.is_a?(PropertyExistsCondition) && !@configuration.legacy_functions?
+              return render_property_exists(negated, negated: true)
+            end
+
+            rendered = render_expression(negated)
+            return negated.is_a?(RelationshipPatternCondition) ? "NOT #{rendered}" : "NOT (#{rendered})"
+          end
+
+          operands = nested { condition.conditions.map { |inner| render_compound_operand(inner) } }
+          "(#{operands.join("#{break_line(@level + 1)}#{condition.operator} ")})"
+        end
+
+        # A raw operand is parenthesised unless it already is one group, so that
+        # `Cypher.raw('a OR b').as_condition.and(c)` keeps its precedence. (Ruby addition; the
+        # Java renderer trusts raw text.)
+        def render_compound_operand(condition)
+          rendered = render_expression(condition)
+          raw_condition?(condition) && !parenthesised?(rendered) ? "(#{rendered})" : rendered
+        end
+
+        def raw_condition?(condition)
+          condition.is_a?(ExpressionCondition) && condition.expression.is_a?(RawExpression)
+        end
+
+        # True when the text is one parenthesised group: `(a OR b)` but not `(a) OR (b)`.
+        def parenthesised?(text)
+          return false unless text.start_with?('(') && text.end_with?(')')
+
+          depth = 0
+          text.each_char.with_index do |char, index|
+            depth += 1 if char == '('
+            depth -= 1 if char == ')'
+            return false if depth.zero? && index < text.size - 1
+          end
+          true
+        end
+      end
+    end
+  end
+end

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

@@ -250,43 +250,6 @@ module CypherDSL
           "#{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)`.
-        # `exists(n.prop)` on Neo4j 4, `n.prop IS NOT NULL` afterwards.
-        def render_property_exists(condition, negated: false)
-          property = render_expression(condition.property)
-          return "exists(#{property})" if @configuration.legacy_functions?
-
-          "#{property} IS #{'NOT ' unless negated}NULL"
-        end
-
-        def render_compound_condition(condition)
-          if condition.negation?
-            negated = condition.conditions.first
-            if negated.is_a?(PropertyExistsCondition) && !@configuration.legacy_functions?
-              return render_property_exists(negated, negated: true)
-            end
-
-            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 do |argument|
             rendered = render_expression(argument)

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

@@ -15,6 +15,7 @@ module CypherDSL
           when RelationshipChain then render_chain(element)
           when NamedPath then render_named_path(element)
           when QuantifiedPathPattern then render_quantified_path_pattern(element)
+          when RawExpression then render_raw(element) # `Cypher.raw('(n)-->(m)')` as a pattern
           else raise ArgumentError, "Cannot render pattern element #{element.inspect}"
           end
         end

data/lib/cypher_dsl/renderer/visitor.rb

@@ -8,6 +8,7 @@ module CypherDSL
     class Visitor
       include Patterns
       include Expressions
+      include Conditions
       include LabelRendering
 
       def initialize(configuration)
@@ -117,18 +118,22 @@ module CypherDSL
         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::Unwind then render_unwind(clause)
         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)}"
+        when Clauses::Raw then render_raw(clause.expression)
         else raise ArgumentError, "Cannot render clause #{clause.inspect}"
         end
       end
 
+      def render_unwind(clause)
+        "UNWIND #{render_expression(clause.expression)} AS #{render_expression(clause.variable)}"
+      end
+
       def render_load_csv(clause)
         parts = []
         if clause.periodic_commit

data/lib/cypher_dsl/statement_builder.rb

@@ -177,6 +177,18 @@ module CypherDSL
     # The statement built so far as an `EXISTS { … }` condition.
     def as_condition = ExistsCondition.new(build)
 
+    # --- escape hatch ----------------------------------------------------
+
+    # A clause rendered verbatim, for Cypher the builder does not model, e.g.
+    # `raw_clause('CALL db.labels() YIELD label')`. Takes the arguments of
+    # `Cypher.raw` (a format with `$E` placeholders) or a ready {RawExpression}.
+    # The next clause starts afresh: a raw clause cannot be refined with WHERE,
+    # ORDER BY, SKIP or LIMIT.
+    def raw_clause(format, *)
+      expression = format.is_a?(RawExpression) ? format : RawExpression.create(format, *)
+      append(Clauses::Raw.new(expression:), nil)
+    end
+
     # --- finishing -------------------------------------------------------
 
     # Continues with the clauses of another statement, e.g. after a `CALL … YIELD`.
@@ -283,7 +295,8 @@ module CypherDSL
       arguments.each_slice(2).map { |target, value| Operation.new(target, '=', Expression.coerce(value)) }.freeze
     end
 
-    def operation?(argument) = argument.is_a?(Operation) || argument.is_a?(LabelOperation)
+    # A raw fragment such as `Cypher.raw("n.name = 'x'")` counts as a complete operation.
+    def operation?(argument) = [Operation, LabelOperation, RawExpression].any? { |type| argument.is_a?(type) }
 
     def label_operation?(arguments)
       arguments.size > 1 && arguments.first.is_a?(Node) &&

data/lib/cypher_dsl/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module CypherDSL
-  VERSION = '0.1.0.alpha.2'
+  VERSION = '0.1.0.alpha.3'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cypher-dsl
 version: !ruby/object:Gem::Version
-  version: 0.1.0.alpha.2
+  version: 0.1.0.alpha.3
 platform: ruby
 authors:
 - Heinrich Klobuczek
@@ -50,6 +50,7 @@ files:
 - lib/cypher_dsl/clauses/match.rb
 - lib/cypher_dsl/clauses/merge.rb
 - lib/cypher_dsl/clauses/order.rb
+- lib/cypher_dsl/clauses/raw.rb
 - lib/cypher_dsl/clauses/raw_return.rb
 - lib/cypher_dsl/clauses/remove.rb
 - lib/cypher_dsl/clauses/return.rb
@@ -104,6 +105,7 @@ files:
 - lib/cypher_dsl/renderer/generated_name_resolver.rb
 - lib/cypher_dsl/renderer/name_resolver.rb
 - lib/cypher_dsl/renderer/visitor.rb
+- lib/cypher_dsl/renderer/visitor/conditions.rb
 - lib/cypher_dsl/renderer/visitor/expressions.rb
 - lib/cypher_dsl/renderer/visitor/label_rendering.rb
 - lib/cypher_dsl/renderer/visitor/patterns.rb