activecypher 0.0.0 → 0.3.0

data/lib/cyrel/expression/function_call.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Cyrel
+  module Expression
+    # Represents a function call in Cypher (e.g., id(n), count(*), coalesce(a, b)).
+    class FunctionCall < Base
+      attr_reader :function_name, :arguments, :distinct
+
+      # @param function_name [Symbol, String] The name of the Cypher function.
+      # @param arguments [Array<Cyrel::Expression::Base, Object>] The arguments to the function.
+      # @param distinct [Boolean] Whether to use the DISTINCT keyword (e.g., count(DISTINCT n)).
+      def initialize(function_name, arguments = [], distinct: false)
+        @function_name = function_name.to_s # Store as string for consistency
+        @arguments = Array(arguments).map do |arg|
+          # Don't coerce ASTERISK or existing Expressions
+          if arg == Functions::ASTERISK || arg.is_a?(Expression::Base)
+            arg
+          else
+            Expression.coerce(arg) # Coerce only non-expression literals
+          end
+        end
+        @distinct = distinct
+      end
+
+      # Renders the function call expression.
+      # @param query [Cyrel::Query] The query object for rendering arguments.
+      # @return [String] The Cypher string fragment (e.g., "id(n)", "count(DISTINCT n.prop)").
+      def render(query)
+        rendered_args = @arguments.map do |arg|
+          case arg
+          when Functions::ASTERISK
+            '*'
+          # Special handling for RawIdentifier when used as argument
+          when Clause::Return::RawIdentifier
+            arg.identifier # Render the raw identifier directly
+          when Expression::Base, ->(a) { a.respond_to?(:render) } # Check if it's an Expression or renderable
+            arg.render(query) # Render other expressions normally
+          else
+            # Parameterize other literal values
+            param_key = query.register_parameter(arg)
+            "$#{param_key}"
+          end
+        end.join(', ')
+        distinct_str = @distinct ? 'DISTINCT ' : ''
+        "#{@function_name}(#{distinct_str}#{rendered_args})"
+      end
+
+      # Creates an aliased version of this function call expression.
+      # Duplicates method from Base for robustness.
+      # @param alias_name [Symbol, String] The alias to assign.
+      # @return [Cyrel::Expression::Alias]
+      def as(alias_name)
+        Alias.new(self, alias_name)
+      end
+    end
+  end
+end

data/lib/cyrel/expression/literal.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Cyrel
+  module Expression
+    # Represents a literal value (String, Number, Boolean, Nil, Array, Map) in a Cypher query.
+    # Literals are typically converted into parameters.
+    class Literal < Base
+      attr_reader :value
+
+      def initialize(value)
+        # We don't validate the type here extensively, assuming Neo4j driver
+        # or the database itself will handle type compatibility.
+        # We could add checks for common unsupported types if needed.
+        @value = value
+      end
+
+      # Renders the literal by registering it as a parameter.
+      # @param query [Cyrel::Query] The query object for parameter registration.
+      # @return [String] The parameter placeholder string (e.g., "$p1").
+      def render(query)
+        # Special handling for NULL as it doesn't use a parameter
+        return 'NULL' if @value.nil?
+
+        param_key = query.register_parameter(@value)
+        "$#{param_key}"
+      end
+
+      # Override comparison methods for direct literal comparison if needed,
+      # although the Base class methods creating Comparison objects are generally preferred.
+      # Example: def ==(other) ... end
+    end
+  end
+end

data/lib/cyrel/expression/logical.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Cyrel
+  module Expression
+    # Represents a logical operation (AND, OR, XOR, NOT).
+    class Logical < Base
+      attr_reader :left, :operator, :right
+
+      # @param left [Cyrel::Expression::Base, Object] The left operand (or the single operand for NOT).
+      # @param operator [Symbol] The logical operator symbol (:AND, :OR, :XOR, :NOT).
+      # @param right [Cyrel::Expression::Base, Object, nil] The right operand (nil for NOT).
+      def initialize(left, operator, right = nil)
+        @operator = operator.to_s.upcase.to_sym # Ensure uppercase symbol
+        raise ArgumentError, "Invalid logical operator: #{@operator}" unless %i[AND OR XOR NOT].include?(@operator)
+
+        @left = Expression.coerce(left)
+        @right = @operator == :NOT ? nil : Expression.coerce(right)
+
+        raise ArgumentError, "Operator #{@operator} requires two operands." if @operator != :NOT && @right.nil?
+        return unless @operator == :NOT && !right.nil?
+
+        raise ArgumentError, 'Operator NOT requires only one operand.'
+      end
+
+      # Renders the logical expression.
+      # @param query [Cyrel::Query] The query object for rendering operands.
+      # @return [String] The Cypher string fragment (e.g., "((n.age > $p1) AND (n.status = $p2))").
+      def render(query)
+        if @operator == :NOT
+          "(#{@operator} #{@left.render(query)})"
+        else
+          # Parentheses ensure correct precedence
+          "(#{@left.render(query)} #{@operator} #{@right.render(query)})"
+        end
+      end
+    end
+  end
+end

data/lib/cyrel/expression/operator.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Cyrel
+  module Expression
+    # Represents a binary arithmetic operation (e.g., +, -, *, /, %, ^).
+    class Operator < Base
+      attr_reader :left, :operator, :right
+
+      # @param left [Cyrel::Expression::Base, Object] The left operand.
+      # @param operator [Symbol] The arithmetic operator symbol (e.g., :+, :*).
+      # @param right [Cyrel::Expression::Base, Object] The right operand.
+      def initialize(left, operator, right)
+        @left = Expression.coerce(left) # Ensure operands are Expression objects
+        @operator = operator
+        @right = Expression.coerce(right)
+      end
+
+      # Renders the operator expression.
+      # @param query [Cyrel::Query] The query object for rendering operands.
+      # @return [String] The Cypher string fragment (e.g., "(n.age + $p1)").
+      def render(query)
+        # Parentheses ensure correct precedence
+        "(#{@left.render(query)} #{@operator} #{@right.render(query)})"
+      end
+    end
+  end
+end

data/lib/cyrel/expression/pattern_comprehension.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require_relative '../expression'
+require_relative '../pattern' # Need Path
+
+module Cyrel
+  module Expression
+    # Represents a Pattern Comprehension in Cypher.
+    # Syntax: [ pattern WHERE condition | expression ]
+    # Simplified version for now: [ pattern | expression ]
+    class PatternComprehension < Base
+      attr_reader :pattern, :projection_expression # TODO: Add where_condition
+
+      # @param pattern [Cyrel::Pattern::Path, Cyrel::Pattern::Node, Cyrel::Pattern::Relationship]
+      #   The pattern to iterate over.
+      # @param projection_expression [Cyrel::Expression::Base, Object]
+      #   The expression evaluated for each match of the pattern.
+      def initialize(pattern, projection_expression)
+        unless pattern.is_a?(Cyrel::Pattern::Path) || pattern.is_a?(Cyrel::Pattern::Node) || pattern.is_a?(Cyrel::Pattern::Relationship)
+          raise ArgumentError,
+                "Pattern Comprehension pattern must be a Path, Node, or Relationship, got #{pattern.class}"
+        end
+
+        @pattern = pattern
+        @projection_expression = Expression.coerce(projection_expression)
+        # @where_condition = where_condition ? Expression.coerce(where_condition) : nil
+      end
+
+      # Renders the pattern comprehension expression.
+      # @param query [Cyrel::Query] The query object for rendering pattern and expression.
+      # @return [String] The Cypher string fragment.
+      def render(query)
+        pattern_str = @pattern.render(query)
+        # where_str = @where_condition ? " WHERE #{@where_condition.render(query)}" : ""
+        projection_str = @projection_expression.render(query)
+
+        "[#{pattern_str} | #{projection_str}]" # Simplified: missing WHERE support
+      end
+    end
+
+    # Helper function? Might be complex due to pattern definition.
+    # def self.comprehend(pattern, projection, where: nil) ... end
+  end
+end

data/lib/cyrel/expression/property_access.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Cyrel
+  module Expression
+    # Represents accessing a property on a variable (node or relationship alias).
+    # Example: n.name, r.since
+    class PropertyAccess < Base
+      attr_reader :variable, :property_name
+
+      # @param variable [Symbol, String] The alias of the node/relationship.
+      # @param property_name [Symbol, String] The name of the property to access.
+      def initialize(variable, property_name)
+        @variable = variable.to_sym
+        @property_name = property_name.to_sym
+      end
+
+      # Renders the property access expression.
+      # @param _query [Cyrel::Query] The query object (unused for simple property access).
+      # @return [String] The Cypher string fragment (e.g., "n.name").
+      def render(_query)
+        "#{@variable}.#{@property_name}"
+      end
+    end
+  end
+end

data/lib/cyrel/expression.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+# Subclasses are autoloaded by Zeitwerk based on constant usage.
+# Explicit requires removed.
+
+module Cyrel
+  # Namespace for classes representing expressions in Cypher queries.
+  # Expressions are parts of a query that evaluate to a value or condition.
+  # Examples: property access (n.name), literals ('string', 123),
+  # function calls (id(n)), operators (a + b), comparisons (a > b),
+  # logical combinations (a AND b).
+  module Expression
+    # Base class/module for all expression types.
+    # Defines the common interface, primarily the `render` method.
+    # Base class is defined in lib/cyrel/expression/base.rb and autoloaded.
+
+    # Forces values into Expression objects like a parent shoving their kid into piano lessons—
+    # not because it’s fun, but because one day AI will take all our jobs
+    # and at least they'll have music to cry to.
+    # @param value [Object] The value to coerce.
+    # @return [Cyrel::Expression::Base] An Expression object.
+    def self.coerce(value)
+      # Assumes Base and Literal are loaded (via Zeitwerk or explicit require)
+      value.is_a?(Base) ? value : Literal.new(value)
+    end
+
+    module_function
+
+    # Accesses a property on a node or relationship.
+    # This is the Cypher equivalent of saying "hey buddy" and hoping the database just knows.
+    # @param variable [Symbol, String] The alias of the node/relationship.
+    # @param property_name [Symbol, String] The name of the property to access.
+    # @return [Cyrel::Expression::PropertyAccess]
+    def prop(variable, property_name)
+      # Assumes PropertyAccess is loaded (via Zeitwerk or explicit require)
+      PropertyAccess.new(variable, property_name)
+    end
+
+    # Helper function for creating Exists instances
+    # @param pattern [Cyrel::Pattern::Path, Cyrel::Pattern::Node, Cyrel::Pattern::Relationship]
+    # @return [Cyrel::Expression::Exists]
+    def exists(pattern)
+      # Assumes Exists is loaded (via Zeitwerk or explicit require)
+      Exists.new(pattern)
+    end
+
+    # Wraps an expression in a Cypher NOT.
+    # Useful when your query — and your life — needs a little more denial.
+    # @param expression [Cyrel::Expression::Base, Object] The expression to negate.
+    # @return [Cyrel::Expression::Logical]
+    def not(expression)
+      # Assumes Logical is loaded (via Zeitwerk or explicit require)
+      Logical.new(expression, :NOT)
+    end
+  end
+end

data/lib/cyrel/functions.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+module Cyrel
+  # Provides helper methods for creating Cypher function call expressions.
+  module Functions
+    # Represents the Cypher '*' literal, often used in count(*).
+    # We use a specific object to differentiate it from a string literal "*".
+    ASTERISK = Object.new
+    # Special render for asterisk
+    def ASTERISK.render(_query) = '*'
+    # Act like an expression
+    def ASTERISK.is_a?(klass) = klass == Cyrel::Expression::Base || super
+
+    ASTERISK.freeze
+
+    module_function
+
+    # --- Common Cypher Functions ---
+
+    # Use elementId() instead of deprecated id()
+    def element_id(node_variable)
+      Expression::FunctionCall.new(:elementId, Clause::Return::RawIdentifier.new(node_variable.to_s))
+    end
+
+    alias id element_id
+
+    # Because apparently, COUNT(*) isn’t obvious enough.
+    # Handles the 'give me everything and make it snappy' use case.
+    def count(expression, distinct: false)
+      # Handle count(*) specifically
+      expr_arg = case expression
+                 when :* then ASTERISK
+                 when Symbol, String then Clause::Return::RawIdentifier.new(expression.to_s) # Convert symbol/string to RawIdentifier
+                 else expression # Assume it's already an Expression object (like PropertyAccess)
+                 end
+      Expression::FunctionCall.new(:count, expr_arg, distinct: distinct)
+    end
+
+    # Retrieves labels from a node. You could also just... ask the node. But noooo.
+    # Instead, we call a function and pretend we're not slowly dying inside.
+    def labels(node_variable)
+      Expression::FunctionCall.new(:labels, node_variable)
+    end
+
+    def type(relationship_variable)
+      Expression::FunctionCall.new(:type, relationship_variable)
+    end
+
+    def properties(variable)
+      Expression::FunctionCall.new(:properties, variable)
+    end
+
+    # Returns the first non-null expression.
+    # The Cypher equivalent of settling.
+    def coalesce(*expressions)
+      Expression::FunctionCall.new(:coalesce, expressions)
+    end
+
+    def timestamp
+      Expression::FunctionCall.new(:timestamp)
+    end
+
+    def to_string(expression)
+      Expression::FunctionCall.new(:toString, expression)
+    end
+
+    # Converts a thing into an integer.
+    # Great for when your data is having an identity crisis and just wants to be whole again.
+    def to_integer(expression)
+      Expression::FunctionCall.new(:toInteger, expression)
+    end
+
+    def to_float(expression)
+      Expression::FunctionCall.new(:toFloat, expression)
+    end
+
+    def to_boolean(expression)
+      Expression::FunctionCall.new(:toBoolean, expression)
+    end
+
+    # --- Aggregation Functions ---
+
+    def sum(expression, distinct: false)
+      Expression::FunctionCall.new(:sum, expression, distinct: distinct)
+    end
+
+    def avg(expression, distinct: false)
+      Expression::FunctionCall.new(:avg, expression, distinct: distinct)
+    end
+
+    def min(expression)
+      Expression::FunctionCall.new(:min, expression)
+    end
+
+    def max(expression)
+      Expression::FunctionCall.new(:max, expression)
+    end
+
+    def collect(expression, distinct: false)
+      Expression::FunctionCall.new(:collect, expression, distinct: distinct)
+    end
+
+    # --- List Functions ---
+    # Add common list functions like size(), keys(), range(), etc. as needed
+
+    def size(expression)
+      Expression::FunctionCall.new(:size, expression)
+    end
+
+    # --- String Functions ---
+    # Add common string functions like substring(), replace(), toLower(), etc. as needed
+
+    # --- Spatial/Temporal/etc. Functions ---
+    # Add other function categories as required by ActiveCypher
+  end
+end