clickhouse-ruby 0.1.0

data/lib/clickhouse_ruby/types/parser.rb

@@ -0,0 +1,244 @@
+# frozen_string_literal: true
+
+module ClickhouseRuby
+  module Types
+    # AST-based parser for ClickHouse type strings
+    #
+    # This parser correctly handles nested types like:
+    # - Array(Tuple(String, UInt64))
+    # - Map(String, Array(Nullable(Int32)))
+    # - Nullable(LowCardinality(String))
+    #
+    # The parser does NOT validate types - it only handles syntax.
+    # Type validation is delegated to ClickHouse.
+    #
+    # Grammar:
+    #   type := simple_type | parameterized_type
+    #   parameterized_type := identifier "(" type_list ")"
+    #   type_list := type ("," type)*
+    #   simple_type := identifier
+    #   identifier := [a-zA-Z_][a-zA-Z0-9_]*
+    #
+    # @example
+    #   parser = Parser.new
+    #   parser.parse('String')
+    #   # => { type: 'String' }
+    #
+    #   parser.parse('Array(UInt64)')
+    #   # => { type: 'Array', args: [{ type: 'UInt64' }] }
+    #
+    #   parser.parse('Map(String, Array(Tuple(String, UInt64)))')
+    #   # => { type: 'Map', args: [
+    #   #      { type: 'String' },
+    #   #      { type: 'Array', args: [
+    #   #        { type: 'Tuple', args: [
+    #   #          { type: 'String' },
+    #   #          { type: 'UInt64' }
+    #   #        ]}
+    #   #      ]}
+    #   #    ]}
+    #
+    class Parser
+      # Error raised when parsing fails
+      class ParseError < ClickhouseRuby::Error
+        attr_reader :position, :input
+
+        def initialize(message, position: nil, input: nil)
+          @position = position
+          @input = input
+          full_message = position ? "#{message} at position #{position}" : message
+          full_message += ": '#{input}'" if input
+          super(full_message)
+        end
+      end
+
+      # Parses a ClickHouse type string into an AST
+      #
+      # @param type_string [String] the type string to parse
+      # @return [Hash] the parsed AST with :type and optional :args keys
+      # @raise [ParseError] if the type string is invalid
+      def parse(type_string)
+        raise ParseError.new('Type string cannot be nil') if type_string.nil?
+
+        @input = type_string.strip
+        @pos = 0
+
+        raise ParseError.new('Type string cannot be empty', input: type_string) if @input.empty?
+
+        result = parse_type
+        skip_whitespace
+
+        # Ensure we consumed the entire input
+        unless @pos >= @input.length
+          raise ParseError.new("Unexpected character '#{@input[@pos]}'", position: @pos, input: type_string)
+        end
+
+        result
+      end
+
+      private
+
+      # Parses a single type (simple or parameterized) or literal value
+      #
+      # ClickHouse type parameters can be:
+      # - Type names: String, UInt64
+      # - Numeric literals: 3 (precision), 9 (scale)
+      # - String literals: 'UTC' (timezone)
+      #
+      # @return [Hash] the parsed type/value
+      def parse_type
+        skip_whitespace
+
+        # Handle numeric literals (e.g., DateTime64(3))
+        if numeric_char?(peek)
+          value = parse_numeric
+          return { type: value }
+        end
+
+        # Handle string literals (e.g., DateTime64(3, 'UTC'))
+        if peek == "'"
+          value = parse_string_literal
+          return { type: value }
+        end
+
+        name = parse_identifier
+
+        skip_whitespace
+        if peek == '('
+          consume('(')
+          args = parse_type_list
+          consume(')')
+          { type: name, args: args }
+        else
+          { type: name }
+        end
+      end
+
+      # Parses a comma-separated list of types
+      #
+      # @return [Array<Hash>] the list of parsed types
+      def parse_type_list
+        types = []
+        skip_whitespace
+
+        # Handle empty argument list
+        return types if peek == ')'
+
+        types << parse_type
+
+        while peek == ','
+          consume(',')
+          types << parse_type
+        end
+
+        types
+      end
+
+      # Parses an identifier (type name)
+      #
+      # @return [String] the identifier
+      # @raise [ParseError] if no identifier is found
+      def parse_identifier
+        skip_whitespace
+        start_pos = @pos
+
+        # First character must be letter or underscore
+        unless @pos < @input.length && identifier_start_char?(@input[@pos])
+          raise ParseError.new('Expected type name', position: @pos, input: @input)
+        end
+
+        @pos += 1
+
+        # Subsequent characters can be letters, digits, or underscores
+        while @pos < @input.length && identifier_char?(@input[@pos])
+          @pos += 1
+        end
+
+        @input[start_pos...@pos]
+      end
+
+      # Checks if a character can start an identifier
+      #
+      # @param char [String] the character to check
+      # @return [Boolean] true if valid
+      def identifier_start_char?(char)
+        char =~ /[a-zA-Z_]/
+      end
+
+      # Checks if a character can be part of an identifier
+      #
+      # @param char [String] the character to check
+      # @return [Boolean] true if valid
+      def identifier_char?(char)
+        char =~ /[a-zA-Z0-9_]/
+      end
+
+      # Checks if a character is numeric
+      #
+      # @param char [String] the character to check
+      # @return [Boolean] true if numeric
+      def numeric_char?(char)
+        char =~ /[0-9]/
+      end
+
+      # Parses a numeric literal
+      #
+      # @return [String] the numeric value
+      def parse_numeric
+        start_pos = @pos
+
+        while @pos < @input.length && numeric_char?(@input[@pos])
+          @pos += 1
+        end
+
+        @input[start_pos...@pos]
+      end
+
+      # Parses a string literal (single-quoted)
+      #
+      # @return [String] the string value (without quotes)
+      def parse_string_literal
+        consume("'")
+        start_pos = @pos
+
+        while @pos < @input.length && @input[@pos] != "'"
+          # Handle escaped quotes
+          @pos += 1 if @input[@pos] == '\\' && @pos + 1 < @input.length
+          @pos += 1
+        end
+
+        value = @input[start_pos...@pos]
+        consume("'")
+        value
+      end
+
+      # Returns the current character without consuming it
+      #
+      # @return [String, nil] the current character or nil if at end
+      def peek
+        skip_whitespace
+        @pos < @input.length ? @input[@pos] : nil
+      end
+
+      # Consumes an expected character
+      #
+      # @param expected [String] the expected character
+      # @raise [ParseError] if the character doesn't match
+      def consume(expected)
+        skip_whitespace
+        actual = @pos < @input.length ? @input[@pos] : 'end of input'
+
+        unless actual == expected
+          raise ParseError.new("Expected '#{expected}', got '#{actual}'", position: @pos, input: @input)
+        end
+
+        @pos += 1
+      end
+
+      # Skips whitespace characters
+      def skip_whitespace
+        @pos += 1 while @pos < @input.length && @input[@pos] =~ /\s/
+      end
+    end
+  end
+end

data/lib/clickhouse_ruby/types/registry.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+module ClickhouseRuby
+  module Types
+    # Registry for ClickHouse type mappings
+    #
+    # Manages the mapping between ClickHouse type strings and Ruby type classes.
+    # Supports both simple types (String, UInt64) and parameterized types
+    # (Array, Map, Nullable).
+    #
+    # @example Register a custom type
+    #   registry = Registry.new
+    #   registry.register('MyType', MyTypeClass)
+    #
+    # @example Look up a type
+    #   type = registry.lookup('Array(String)')
+    #
+    class Registry
+      # Types that wrap other types (parameterized types)
+      WRAPPER_TYPES = %w[Array Nullable LowCardinality].freeze
+
+      # Types that take multiple type arguments
+      MULTI_ARG_TYPES = %w[Map Tuple].freeze
+
+      # DateTime types that take precision/timezone parameters
+      DATETIME_TYPES = %w[DateTime DateTime64].freeze
+
+      def initialize
+        @types = {}
+        @cache = {}
+      end
+
+      # Registers a type class for a type name
+      #
+      # @param name [String] the type name (e.g., 'String', 'UInt64')
+      # @param type_class [Class] the type class
+      def register(name, type_class)
+        @types[name] = type_class
+        @cache.clear  # Invalidate cache when types change
+      end
+
+      # Looks up a type by its ClickHouse type string
+      #
+      # @param type_string [String] the full type string (e.g., 'Array(String)')
+      # @return [Base] the type instance
+      def lookup(type_string)
+        # Check cache first
+        return @cache[type_string] if @cache.key?(type_string)
+
+        # Parse the type string
+        ast = Parser.new.parse(type_string)
+
+        # Build the type instance
+        type = build_type(ast)
+
+        # Cache for future lookups
+        @cache[type_string] = type
+
+        type
+      end
+
+      # Registers all default ClickHouse types
+      def register_defaults
+        # Integer types
+        register('Int8', Integer)
+        register('Int16', Integer)
+        register('Int32', Integer)
+        register('Int64', Integer)
+        register('Int128', Integer)
+        register('Int256', Integer)
+        register('UInt8', Integer)
+        register('UInt16', Integer)
+        register('UInt32', Integer)
+        register('UInt64', Integer)
+        register('UInt128', Integer)
+        register('UInt256', Integer)
+
+        # Float types
+        register('Float32', Float)
+        register('Float64', Float)
+
+        # String types
+        register('String', String)
+        register('FixedString', String)
+
+        # Date/Time types
+        register('Date', DateTime)
+        register('Date32', DateTime)
+        register('DateTime', DateTime)
+        register('DateTime64', DateTime)
+
+        # Other basic types
+        register('UUID', UUID)
+        register('Bool', Boolean)
+
+        # Complex/wrapper types
+        register('Array', Array)
+        register('Map', Map)
+        register('Tuple', Tuple)
+        register('Nullable', Nullable)
+        register('LowCardinality', LowCardinality)
+      end
+
+      private
+
+      # Builds a type instance from a parsed AST
+      #
+      # @param ast [Hash] the parsed type AST
+      # @return [Base] the type instance
+      def build_type(ast)
+        type_name = ast[:type]
+        args = ast[:args]
+
+        type_class = @types[type_name]
+
+        unless type_class
+          # For unknown types, return a generic type that passes through values
+          return Base.new(type_name)
+        end
+
+        if args && !args.empty?
+          if DATETIME_TYPES.include?(type_name)
+            # DateTime types: DateTime64(3) or DateTime64(3, 'UTC')
+            precision = args[0] ? args[0][:type].to_i : nil
+            timezone = args[1] ? args[1][:type] : nil
+            type_class.new(type_name, precision: precision, timezone: timezone)
+          elsif WRAPPER_TYPES.include?(type_name)
+            # Single-argument wrapper (Array, Nullable, LowCardinality)
+            arg_types = args.map { |arg| build_type(arg) }
+            type_class.new(type_name, element_type: arg_types.first)
+          elsif MULTI_ARG_TYPES.include?(type_name)
+            # Multi-argument type (Map, Tuple)
+            arg_types = args.map { |arg| build_type(arg) }
+            type_class.new(type_name, arg_types: arg_types)
+          else
+            # Other parameterized types - pass raw args
+            arg_types = args.map { |arg| build_type(arg) }
+            type_class.new(type_name, arg_types: arg_types)
+          end
+        else
+          # Simple type
+          type_class.new(type_name)
+        end
+      end
+
+    end
+  end
+end

data/lib/clickhouse_ruby/types/string.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module ClickhouseRuby
+  module Types
+    # Type handler for ClickHouse string types
+    #
+    # Handles: String, FixedString(N)
+    #
+    # ClickHouse strings are byte sequences, not necessarily valid UTF-8.
+    # However, most usage is with UTF-8 text.
+    #
+    class String < Base
+      # The fixed length for FixedString types
+      # @return [Integer, nil] the fixed length or nil for String type
+      attr_reader :length
+
+      def initialize(name, length: nil)
+        super(name)
+        @length = length
+      end
+
+      # Converts a Ruby value to a string
+      #
+      # @param value [Object] the value to convert
+      # @return [String, nil] the string value
+      def cast(value)
+        return nil if value.nil?
+
+        str = value.to_s
+
+        # For FixedString, pad or truncate to length
+        if @length
+          str = str.ljust(@length, "\0")[0, @length]
+        end
+
+        str
+      end
+
+      # Converts a value from ClickHouse to Ruby String
+      #
+      # @param value [Object] the value from ClickHouse
+      # @return [String, nil] the string value
+      def deserialize(value)
+        return nil if value.nil?
+
+        str = value.to_s
+
+        # For FixedString, remove trailing null bytes
+        if @length
+          str = str.gsub(/\0+\z/, '')
+        end
+
+        str
+      end
+
+      # Converts a string to SQL literal with proper escaping
+      #
+      # @param value [String, nil] the value to serialize
+      # @return [String] the SQL literal
+      def serialize(value)
+        return 'NULL' if value.nil?
+
+        escaped = escape_string(value.to_s)
+        "'#{escaped}'"
+      end
+
+      private
+
+      # Escapes a string for use in ClickHouse SQL
+      #
+      # @param value [String] the string to escape
+      # @return [String] the escaped string
+      def escape_string(value)
+        value.gsub("\\", "\\\\")
+             .gsub("'", "\\'")
+             .gsub("\n", "\\n")
+             .gsub("\r", "\\r")
+             .gsub("\t", "\\t")
+             .gsub("\0", "\\0")
+      end
+    end
+  end
+end

data/lib/clickhouse_ruby/types/tuple.rb

@@ -0,0 +1,206 @@
+# frozen_string_literal: true
+
+module ClickhouseRuby
+  module Types
+    # Type handler for ClickHouse Tuple type
+    #
+    # Tuples are fixed-size collections where each position has its own type.
+    # Similar to Ruby arrays but heterogeneous and fixed-size.
+    #
+    # @example
+    #   type = Tuple.new('Tuple', arg_types: [String.new('String'), Integer.new('UInt64')])
+    #   type.cast(['hello', 42])
+    #   type.serialize(['hello', 42]) # => "('hello', 42)"
+    #
+    class Tuple < Base
+      # @return [Array<Base>] the types of each tuple element
+      attr_reader :element_types
+
+      # @param name [String] the type name
+      # @param arg_types [Array<Base>] the element types
+      def initialize(name, arg_types: nil)
+        super(name)
+        @element_types = arg_types || []
+      end
+
+      # Converts a Ruby value to a tuple (Array)
+      #
+      # @param value [Object] the value to convert
+      # @return [Array, nil] the tuple value
+      # @raise [TypeCastError] if the value cannot be converted
+      def cast(value)
+        return nil if value.nil?
+
+        arr = case value
+              when ::Array
+                value
+              when ::String
+                parse_tuple_string(value)
+              else
+                raise TypeCastError.new(
+                  "Cannot cast #{value.class} to Tuple",
+                  from_type: value.class.name,
+                  to_type: to_s,
+                  value: value
+                )
+              end
+
+        cast_elements(arr)
+      end
+
+      # Converts a value from ClickHouse to a Ruby Array
+      #
+      # @param value [Object] the value from ClickHouse
+      # @return [Array, nil] the tuple value
+      def deserialize(value)
+        return nil if value.nil?
+
+        arr = case value
+              when ::Array
+                value
+              when ::String
+                parse_tuple_string(value)
+              else
+                [value]
+              end
+
+        deserialize_elements(arr)
+      end
+
+      # Converts a tuple to SQL literal
+      #
+      # @param value [Array, nil] the value to serialize
+      # @return [String] the SQL literal
+      def serialize(value)
+        return 'NULL' if value.nil?
+
+        elements = value.each_with_index.map do |v, i|
+          type = @element_types[i] || Base.new('String')
+          type.serialize(v)
+        end
+
+        "(#{elements.join(', ')})"
+      end
+
+      # Returns the full type string including element types
+      #
+      # @return [String] the type string
+      def to_s
+        type_strs = @element_types.map(&:to_s).join(', ')
+        "Tuple(#{type_strs})"
+      end
+
+      private
+
+      # Casts each element using its corresponding type
+      #
+      # @param arr [Array] the array to cast
+      # @return [Array] the cast array
+      def cast_elements(arr)
+        arr.each_with_index.map do |v, i|
+          type = @element_types[i] || Base.new('String')
+          type.cast(v)
+        end
+      end
+
+      # Deserializes each element using its corresponding type
+      #
+      # @param arr [Array] the array to deserialize
+      # @return [Array] the deserialized array
+      def deserialize_elements(arr)
+        arr.each_with_index.map do |v, i|
+          type = @element_types[i] || Base.new('String')
+          type.deserialize(v)
+        end
+      end
+
+      # Parses a ClickHouse tuple string representation
+      #
+      # @param value [String] the string to parse
+      # @return [Array] the parsed tuple
+      def parse_tuple_string(value)
+        stripped = value.strip
+
+        # Handle empty tuple
+        return [] if stripped == '()'
+
+        # Remove outer parentheses
+        unless stripped.start_with?('(') && stripped.end_with?(')')
+          raise TypeCastError.new(
+            "Invalid tuple format: '#{value}'",
+            from_type: 'String',
+            to_type: to_s,
+            value: value
+          )
+        end
+
+        inner = stripped[1...-1]
+        return [] if inner.strip.empty?
+
+        # Parse elements
+        parse_elements(inner)
+      end
+
+      # Parses comma-separated elements, handling nesting and quotes
+      #
+      # @param str [String] the inner tuple string
+      # @return [Array] the parsed elements
+      def parse_elements(str)
+        elements = []
+        current = ''
+        depth = 0
+        in_string = false
+        escape_next = false
+
+        str.each_char do |char|
+          if escape_next
+            current += char
+            escape_next = false
+            next
+          end
+
+          case char
+          when '\\'
+            escape_next = true
+            current += char
+          when "'"
+            in_string = !in_string
+            current += char
+          when '(', '[', '{'
+            depth += 1 unless in_string
+            current += char
+          when ')', ']', '}'
+            depth -= 1 unless in_string
+            current += char
+          when ','
+            if depth.zero? && !in_string
+              elements << parse_element(current.strip)
+              current = ''
+            else
+              current += char
+            end
+          else
+            current += char
+          end
+        end
+
+        # Don't forget the last element
+        elements << parse_element(current.strip) unless current.strip.empty?
+
+        elements
+      end
+
+      # Parses a single element, removing quotes if necessary
+      #
+      # @param str [String] the element string
+      # @return [Object] the parsed element
+      def parse_element(str)
+        if str.start_with?("'") && str.end_with?("'")
+          str[1...-1].gsub("\\'", "'")
+        else
+          str
+        end
+      end
+    end
+  end
+end