cypher-dsl 0.1.0.alpha.1

data/lib/cypher_dsl/statement_builder.rb

@@ -0,0 +1,294 @@
+# frozen_string_literal: true
+
+module CypherDSL
+  # Builds a {Statement} clause by clause. Every method returns a new builder;
+  # the last clause stays open for refinement (WHERE on MATCH/WITH, ORDER BY,
+  # SKIP and LIMIT on RETURN/WITH) until the next clause is added.
+  #
+  # `and` is overloaded as in the Java API: after `where` it extends the
+  # condition, after `order_by` it adds another sort item.
+  class StatementBuilder
+    def initialize(clauses = [], mode = nil)
+      @clauses = clauses.freeze
+      @mode = mode
+      freeze
+    end
+
+    # --- reading ---------------------------------------------------------
+
+    # `match(pattern, …)` or, as in Java, `match(optional, pattern, …)` with a leading flag.
+    def match(*pattern_elements)
+      optional = [true, false].include?(pattern_elements.first) ? pattern_elements.shift : false
+      append(Clauses::Match.new(optional:, pattern_elements: pattern_elements.flatten.freeze, where: nil), :condition)
+    end
+
+    def optional_match(*pattern_elements) = match(true, *pattern_elements)
+
+    def where(condition)
+      if @clauses.last.is_a?(Clauses::CallSubquery)
+        raise ArgumentError, 'A CALL{} clause requires to WITH before you can add further conditions'
+      end
+
+      update_last(:condition) { |clause| clause.with(where: Condition.coerce(condition)) }
+    end
+
+    def and(argument)
+      case @mode
+      when :order then add_sort_item(argument)
+      when :condition then update_last(:condition) { |clause| clause.with(where: clause.where.and(argument)) }
+      else raise ArgumentError, '`and` needs a preceding WHERE or ORDER BY.'
+      end
+    end
+
+    def or(condition) = update_last(:condition) { |clause| clause.with(where: clause.where.or(condition)) }
+    def xor(condition) = update_last(:condition) { |clause| clause.with(where: clause.where.xor(condition)) }
+
+    # --- projecting ------------------------------------------------------
+
+    def returning(*expressions) = append(return_clause(false, expressions), :projection)
+    def returning_distinct(*expressions) = append(return_clause(true, expressions), :projection)
+
+    # A projection rendered without the RETURN keyword, for raw fragments that carry their own.
+    def returning_raw(*expressions) = append(Clauses::RawReturn.new(items: coerce_items(expressions)), :projection)
+
+    def with(*expressions)
+      append(Clauses::With.new(distinct: false, items: coerce_items(expressions), order: nil, skip: nil, limit: nil,
+                               where: nil), :condition)
+    end
+
+    def with_distinct(*expressions)
+      append(Clauses::With.new(distinct: true, items: coerce_items(expressions), order: nil, skip: nil, limit: nil,
+                               where: nil), :condition)
+    end
+
+    def order_by(*sort_items)
+      update_last(:order) { |clause| clause.with(order: Clauses::Order.new(items: coerce_sort_items(sort_items))) }
+    end
+
+    def ascending = update_last_sort_item(&:ascending)
+    def descending = update_last_sort_item(&:descending)
+
+    def skip(amount) = update_last(@mode) { |clause| clause.with(skip: optional_expression(amount)) }
+    def limit(amount) = update_last(@mode) { |clause| clause.with(limit: optional_expression(amount)) }
+    alias take limit # Arel spelling
+
+    # `unwind(list).as(:item)`; `as` completes the clause. Several arguments, or
+    # an array, form a list literal.
+    def unwind(*expressions)
+      single = expressions.size == 1 && !expressions.first.is_a?(Array)
+      OngoingUnwind.new(self, single ? coerce_items(expressions).first : ListExpression.of(expressions.flatten))
+    end
+
+    # --- updating --------------------------------------------------------
+
+    def create(*pattern_elements) = append(Clauses::Create.new(pattern_elements: pattern_elements.flatten.freeze), nil)
+
+    def merge(*pattern_elements)
+      append(Clauses::Merge.new(pattern_elements: pattern_elements.flatten.freeze, actions: [].freeze), nil)
+    end
+
+    # `on_match.set(…)` / `on_create.mutate(…)` after a MERGE.
+    def on_match = MergeActionBuilder.new(self, :on_match)
+    def on_create = MergeActionBuilder.new(self, :on_create)
+
+    # Accepts operations (`n.p.to(x)`, `n.mutate(map)`), a node followed by
+    # labels (`set(n, 'A', 'B')`), or an even list of target/value pairs.
+    def set(*arguments) = append(Clauses::Set.new(operations: operations_for_set(arguments)), nil)
+
+    # `SET target += expression`.
+    def mutate(target, expression) = set(Operation.new(target, '+=', Expression.coerce(expression)))
+
+    # Accepts properties, or a node followed by labels (`remove(n, 'A', 'B')`).
+    def remove(*arguments)
+      arguments = arguments.flatten
+      items = label_operation?(arguments) ? [LabelOperation.new(arguments.first, arguments.drop(1))] : arguments
+      append(Clauses::Remove.new(items: items.freeze), nil)
+    end
+
+    def delete(*expressions) = append(Clauses::Delete.new(detach: false, expressions: coerce_items(expressions)), nil)
+
+    def detach_delete(*expressions)
+      append(Clauses::Delete.new(detach: true, expressions: coerce_items(expressions)), nil)
+    end
+
+    # `foreach(:i).in(list).apply(clause, …)`.
+    def foreach(variable) = OngoingForeach.new(self, SymbolicName.of(variable))
+
+    # `call('db.labels').with_args(…).yield(…)` for a procedure, or
+    # `call(statement, imports…)` for a `CALL { subquery }`.
+    def call(*arguments)
+      return StandaloneCall.new(arguments, builder: self) unless arguments.first.is_a?(Statement)
+
+      statement, *imports = arguments
+      append(subquery_clause(statement, imports, in_transactions: false, rows: nil), nil)
+    end
+
+    # `CALL { subquery } IN TRANSACTIONS [OF n ROWS]`; `call_in_transactions(statement, [rows], imports…)`.
+    def call_in_transactions(statement, *arguments)
+      rows = arguments.first.is_a?(Integer) ? arguments.shift : nil
+      append(subquery_clause(statement, arguments, in_transactions: true, rows:), nil)
+    end
+
+    # `CALL (*) { raw cypher }`.
+    def call_raw_cypher(cypher)
+      body = RawExpression.new(cypher)
+      append(Clauses::CallSubquery.new(body:, imports: [], in_transactions: false, rows: nil), nil)
+    end
+
+    # `load_csv('file:///x.csv').as(:line)`.
+    def load_csv(uri, with_headers: false) = OngoingLoadCsv.new(self, uri.to_s, with_headers)
+
+    # The statement built so far as an `EXISTS { … }` condition.
+    def as_condition = ExistsCondition.new(build)
+
+    # --- finishing -------------------------------------------------------
+
+    # Continues with the clauses of another statement, e.g. after a `CALL … YIELD`.
+    def and_then(statement) = StatementBuilder.new(@clauses + statement.clauses, nil)
+
+    def finish = append(Clauses::Finish.new, nil)
+
+    def build = Statement.new(@clauses)
+    def explain = Statement.new(@clauses, prefix: 'EXPLAIN')
+    def profile = Statement.new(@clauses, prefix: 'PROFILE')
+
+    # Intermediate state of `unwind(expression)` waiting for `as(variable)`.
+    class OngoingUnwind
+      def initialize(builder, expression)
+        @builder = builder
+        @expression = expression
+        freeze
+      end
+
+      def as(variable)
+        @builder.send(:append, Clauses::Unwind.new(expression: @expression, variable: SymbolicName.of(variable)), nil)
+      end
+    end
+
+    # Intermediate states of `foreach(variable)`: `in(list)` then `apply(clauses…)`.
+    class OngoingForeach
+      def initialize(builder, variable, list = nil)
+        @builder = builder
+        @variable = variable
+        @list = list
+        freeze
+      end
+
+      def in(list) = OngoingForeach.new(@builder, @variable, Expression.coerce(list))
+
+      def apply(*clauses)
+        foreach = Clauses::Foreach.new(variable: @variable, list: @list, clauses: clauses.flatten.freeze)
+        @builder.send(:append, foreach, nil)
+      end
+    end
+
+    # Intermediate state of `load_csv(uri)` waiting for `as(alias)`.
+    class OngoingLoadCsv
+      def initialize(builder, uri, with_headers)
+        @builder = builder
+        @uri = uri
+        @with_headers = with_headers
+        freeze
+      end
+
+      def as(alias_name)
+        clause = Clauses::LoadCsv.new(uri: @uri, with_headers: @with_headers, alias_name: SymbolicName.of(alias_name))
+        @builder.send(:append, clause, nil)
+      end
+    end
+
+    # Intermediate state after `on_match` / `on_create`, waiting for `set` or `mutate`.
+    class MergeActionBuilder
+      def initialize(builder, type)
+        @builder = builder
+        @type = type
+        freeze
+      end
+
+      def set(*arguments) = @builder.send(:add_merge_action, @type, @builder.send(:operations_for_set, arguments))
+
+      def mutate(target, expression) = set(Operation.new(target, '+=', Expression.coerce(expression)))
+    end
+
+    private
+
+    attr_reader :clauses
+
+    def append(clause, mode) = StatementBuilder.new(@clauses + [clause], mode)
+
+    def subquery_clause(statement, imports, in_transactions:, rows:)
+      Clauses::CallSubquery.new(body: statement, imports: coerce_items(imports), in_transactions:, rows:)
+    end
+
+    def add_merge_action(type, operations)
+      update_last(nil) do |clause|
+        raise ArgumentError, 'ON CREATE / ON MATCH need a preceding MERGE.' unless clause.is_a?(Clauses::Merge)
+
+        clause.with(actions: clause.actions + [MergeAction.new(type:, operations:)])
+      end
+    end
+
+    def operations_for_set(arguments)
+      arguments = arguments.flatten
+      if arguments.any? { |argument| argument.is_a?(LabelOperation) && argument.remove? }
+        raise ArgumentError, 'REMOVE operations are not supported in a SET clause'
+      end
+      return [LabelOperation.new(arguments.first, arguments.drop(1))].freeze if label_operation?(arguments)
+      return arguments.freeze if arguments.all? { |argument| operation?(argument) }
+      raise ArgumentError, 'The list of expression to set must be even.' if arguments.size.odd?
+
+      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)
+
+    def label_operation?(arguments)
+      arguments.size > 1 && arguments.first.is_a?(Node) &&
+        arguments.drop(1).all? { |argument| argument.is_a?(String) || argument.is_a?(Symbol) }
+    end
+
+    def optional_expression(value) = value.nil? ? nil : Expression.coerce(value)
+
+    def update_last(mode)
+      raise ArgumentError, 'There is no clause to refine yet.' if @clauses.empty?
+
+      StatementBuilder.new(@clauses[0...-1] + [yield(@clauses.last)], mode)
+    end
+
+    def return_clause(distinct, expressions)
+      Clauses::Return.new(distinct:, items: coerce_items(expressions), order: nil, skip: nil, limit: nil)
+    end
+
+    def add_sort_item(expression)
+      update_last(:order) do |clause|
+        clause.with(order: Clauses::Order.new(items: clause.order.items + coerce_sort_items([expression])))
+      end
+    end
+
+    def update_last_sort_item
+      update_last(:order) do |clause|
+        items = clause.order.items
+        clause.with(order: Clauses::Order.new(items: items[0...-1] + [yield(items.last)]))
+      end
+    end
+
+    # RETURN/WITH items: strings and symbols name variables, nodes and
+    # relationships stand for their (possibly generated) names, everything else
+    # is an expression.
+    def coerce_items(expressions)
+      expressions.flatten.map do |item|
+        case item
+        when String, Symbol then SymbolicName.of(item)
+        when Node, Relationship then item.required_symbolic_name
+        else Expression.coerce(item)
+        end
+      end.freeze
+    end
+
+    def coerce_sort_items(sort_items)
+      sort_items.flatten.map do |item|
+        item.is_a?(SortItem) ? item : SortItem.new(Expression.coerce(item), nil)
+      end.freeze
+    end
+  end
+end

data/lib/cypher_dsl/statement_catalog.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module CypherDSL
+  # What a statement uses: its parameter names, and the values of the
+  # parameters that carry one. Built from a rendering pass.
+  class StatementCatalog
+    attr_reader :parameters, :parameter_names
+
+    # `uses` maps each parameter name to every value it was given, in render
+    # order, with {Parameter::NO_VALUE} for unbound uses.
+    def self.from_uses(uses)
+      conflicts = uses.filter_map { |name, values| [name, values.uniq.to_set] if values.uniq.size > 1 }.to_h
+      raise ConflictingParametersException, conflicts unless conflicts.empty?
+
+      bound = uses.filter_map { |name, values| [name, values.first] unless values.first.equal?(Parameter::NO_VALUE) }
+      new(parameters: bound.to_h, parameter_names: uses.keys)
+    end
+
+    def initialize(parameters:, parameter_names:)
+      @parameters = parameters.freeze
+      @parameter_names = parameter_names.freeze
+      freeze
+    end
+  end
+end

data/lib/cypher_dsl/subquery_with.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module CypherDSL
+  # `Cypher.subquery_with(imports…)`: imports for an EXISTS or COLLECT subquery,
+  # rendered as a leading `WITH` inside the braces.
+  class SubqueryWith
+    def initialize(imports)
+      @imports = imports.flatten.map { |import| Expression.coerce(import) }.freeze
+      freeze
+    end
+
+    def collect(statement) = CollectExpression.new(statement, @imports)
+    def exists(statement_or_pattern) = ExistsCondition.new(statement_or_pattern, @imports)
+  end
+end

data/lib/cypher_dsl/symbolic_name.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module CypherDSL
+  # A variable name, such as the `n` in `MATCH (n)`.
+  #
+  # An *unresolved* name has no value yet: it is handed out when an unnamed
+  # node or relationship needs a name, and the renderer generates one for it.
+  class SymbolicName
+    include Expression
+
+    attr_reader :value, :hint
+
+    def self.of(value)
+      value.is_a?(SymbolicName) ? value : new(value.to_s)
+    end
+
+    # A name to be generated at render time; `hint` seeds the generated name (letters only).
+    def self.unresolved(hint) = new(nil, hint: hint.to_s.gsub(/[^a-zA-Z]/, ''))
+
+    def initialize(value, hint: nil)
+      raise ArgumentError, 'A symbolic name must not be empty.' if value && value.empty?
+
+      @value = value
+      @hint = hint
+      freeze
+    end
+
+    def resolved? = !value.nil?
+
+    # A name is its own name; lets names stand in for named elements (e.g. `nodes(p)`).
+    def required_symbolic_name = self
+
+    # The map projection `name{…}`.
+    def project(*entries) = MapProjection.new(self, entries.flatten)
+
+    def property(*names) = Property.new(self, names)
+
+    # Resolved names are equal by value; unresolved ones only to themselves.
+    def ==(other)
+      return equal?(other) unless resolved?
+
+      other.is_a?(SymbolicName) && other.value == value
+    end
+    alias eql? ==
+    def hash = resolved? ? [self.class, value].hash : object_id.hash
+    def to_s = value || 'Unresolved SymbolicName'
+  end
+end

data/lib/cypher_dsl/unary_operation.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module CypherDSL
+  # A prefix operation such as `-x` or `+x`.
+  class UnaryOperation
+    include Expression
+
+    attr_reader :operator, :expression
+
+    def initialize(operator, expression)
+      @operator = operator
+      @expression = expression
+      freeze
+    end
+  end
+end

data/lib/cypher_dsl/union_query.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module CypherDSL
+  # Several statements combined with UNION or UNION ALL.
+  class UnionQuery < Statement
+    attr_reader :statements, :all
+
+    # Appends to an existing union when the first statement already is one of the same kind.
+    def self.create(statements, all:)
+      statements = statements.flatten
+      raise ArgumentError, 'A union needs at least two statements.' if statements.size < 2
+
+      first = statements.first
+      return new(statements, all:) unless first.is_a?(UnionQuery)
+      raise ArgumentError, 'Cannot mix union and union all!' unless first.all == all
+
+      new(first.statements + statements.drop(1), all:)
+    end
+
+    def initialize(statements, all:)
+      super([])
+      @statements = statements.freeze
+      @all = all
+    end
+
+    def result_statement? = true
+    def multi_part_query? = false
+  end
+end

data/lib/cypher_dsl/version.rb

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

data/lib/cypher_dsl.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require 'zeitwerk'
+
+loader = Zeitwerk::Loader.for_gem
+loader.inflector.inflect('cypher_dsl' => 'CypherDSL')
+loader.setup
+
+# A Ruby DSL for building Cypher statements.
+#
+# The entry point is {CypherDSL::Cypher}; everything else is reached from there.
+module CypherDSL
+end

metadata

@@ -0,0 +1,140 @@
+--- !ruby/object:Gem::Specification
+name: cypher-dsl
+version: !ruby/object:Gem::Version
+  version: 0.1.0.alpha.1
+platform: ruby
+authors:
+- Heinrich Klobuczek
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: zeitwerk
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.6'
+description: An immutable, part-aware builder and renderer for Cypher statements,
+  modelled on the design of Neo4j's Cypher-DSL for Java.
+email:
+- heinrich@mail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- NOTICE
+- README.md
+- lib/cypher_dsl.rb
+- lib/cypher_dsl/aliased_expression.rb
+- lib/cypher_dsl/asterisk.rb
+- lib/cypher_dsl/case_expression.rb
+- lib/cypher_dsl/clauses.rb
+- lib/cypher_dsl/clauses/call.rb
+- lib/cypher_dsl/clauses/call_subquery.rb
+- lib/cypher_dsl/clauses/create.rb
+- lib/cypher_dsl/clauses/delete.rb
+- lib/cypher_dsl/clauses/finish.rb
+- lib/cypher_dsl/clauses/foreach.rb
+- lib/cypher_dsl/clauses/load_csv.rb
+- lib/cypher_dsl/clauses/match.rb
+- lib/cypher_dsl/clauses/merge.rb
+- lib/cypher_dsl/clauses/order.rb
+- lib/cypher_dsl/clauses/raw_return.rb
+- lib/cypher_dsl/clauses/remove.rb
+- lib/cypher_dsl/clauses/return.rb
+- lib/cypher_dsl/clauses/set.rb
+- lib/cypher_dsl/clauses/unwind.rb
+- lib/cypher_dsl/clauses/use.rb
+- lib/cypher_dsl/clauses/with.rb
+- lib/cypher_dsl/collect_expression.rb
+- lib/cypher_dsl/comparison.rb
+- lib/cypher_dsl/compound_condition.rb
+- lib/cypher_dsl/condition.rb
+- lib/cypher_dsl/conflicting_parameters_exception.rb
+- lib/cypher_dsl/constant_condition.rb
+- lib/cypher_dsl/count_expression.rb
+- lib/cypher_dsl/cypher.rb
+- lib/cypher_dsl/exists_condition.rb
+- lib/cypher_dsl/expression.rb
+- lib/cypher_dsl/expression_condition.rb
+- lib/cypher_dsl/function_invocation.rb
+- lib/cypher_dsl/functions.rb
+- lib/cypher_dsl/has_label_condition.rb
+- lib/cypher_dsl/label_expression.rb
+- lib/cypher_dsl/label_operation.rb
+- lib/cypher_dsl/list_comprehension.rb
+- lib/cypher_dsl/list_expression.rb
+- lib/cypher_dsl/list_operator.rb
+- lib/cypher_dsl/list_predicate.rb
+- lib/cypher_dsl/literal.rb
+- lib/cypher_dsl/map_expression.rb
+- lib/cypher_dsl/map_projection.rb
+- lib/cypher_dsl/merge_action.rb
+- lib/cypher_dsl/named_path.rb
+- lib/cypher_dsl/no_condition.rb
+- lib/cypher_dsl/node.rb
+- lib/cypher_dsl/operation.rb
+- lib/cypher_dsl/parameter.rb
+- lib/cypher_dsl/pattern_comprehension.rb
+- lib/cypher_dsl/pattern_expression.rb
+- lib/cypher_dsl/property.rb
+- lib/cypher_dsl/quantified_path_pattern.rb
+- lib/cypher_dsl/raw_expression.rb
+- lib/cypher_dsl/reduction.rb
+- lib/cypher_dsl/relationship.rb
+- lib/cypher_dsl/relationship_chain.rb
+- lib/cypher_dsl/relationship_pattern_condition.rb
+- lib/cypher_dsl/renderer.rb
+- lib/cypher_dsl/renderer/configuration.rb
+- lib/cypher_dsl/renderer/dialect.rb
+- lib/cypher_dsl/renderer/escaper.rb
+- lib/cypher_dsl/renderer/visitor.rb
+- lib/cypher_dsl/renderer/visitor/expressions.rb
+- lib/cypher_dsl/renderer/visitor/patterns.rb
+- lib/cypher_dsl/sort_item.rb
+- lib/cypher_dsl/standalone_call.rb
+- lib/cypher_dsl/statement.rb
+- lib/cypher_dsl/statement_builder.rb
+- lib/cypher_dsl/statement_catalog.rb
+- lib/cypher_dsl/subquery_with.rb
+- lib/cypher_dsl/symbolic_name.rb
+- lib/cypher_dsl/unary_operation.rb
+- lib/cypher_dsl/union_query.rb
+- lib/cypher_dsl/version.rb
+homepage: https://github.com/neo4jrb/cypher-dsl
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/neo4jrb/cypher-dsl
+  changelog_uri: https://github.com/neo4jrb/cypher-dsl/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/neo4jrb/cypher-dsl/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.4'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.20
+specification_version: 4
+summary: A Ruby DSL (builder) for the Cypher query language
+test_files: []