openehr 1.2.999999 → 2.0.0

data/lib/openehr/aql/engine.rb

@@ -0,0 +1,119 @@
+require_relative 'engine/binding'
+require_relative 'engine/contains_resolver'
+require_relative 'engine/path_evaluator'
+require_relative 'engine/predicate_evaluator'
+require_relative 'result_set'
+
+module OpenEHR
+  module AQL
+    # Orchestrates one Query execution against a Dataset, in the order
+    # CONTAINS -> WHERE -> ORDER BY -> SELECT -> DISTINCT -> LIMIT/OFFSET.
+    #
+    # A SELECT clause made entirely of aggregate columns
+    # (Model::AggregateFunctionCall) collapses the whole (post-WHERE)
+    # binding set into a single summary row instead - ORDER BY/DISTINCT/
+    # LIMIT don't apply to it, matching plain SQL aggregate-without-
+    # GROUP-BY semantics. Mixing aggregate and plain columns, and
+    # generic (non-aggregate) function calls, are not yet supported.
+    class Engine
+      def initialize(query)
+        @query = query
+      end
+
+      def execute(dataset, params: {})
+        bindings = ContainsResolver.new(@query.from_clause, Dataset.wrap(dataset)).each_binding
+                                    .select { |binding| where_matches?(binding, params) }
+        rows = aggregate_query? ? [aggregate_row(bindings)] : select_rows(bindings)
+        ResultSet.new(columns: @query.select_clause.columns.map { |column| column_name(column) }, rows: rows)
+      end
+
+      private
+
+      def where_matches?(binding, params)
+        PredicateEvaluator.matches?(@query.where_clause&.expression, binding, params)
+      end
+
+      def select_rows(bindings)
+        rows = project(order(bindings))
+        rows = rows.uniq if @query.select_clause.distinct
+        apply_limit(rows)
+      end
+
+      def order(bindings)
+        order_by = @query.order_by_clause
+        return bindings unless order_by
+
+        bindings.sort { |a, b| compare_bindings(a, b, order_by.items) }
+      end
+
+      def compare_bindings(a, b, order_by_items)
+        order_by_items.each do |item|
+          cmp = compare_values(PathEvaluator.evaluate(item.path, a), PathEvaluator.evaluate(item.path, b))
+          cmp = -cmp if item.direction == :desc
+          return cmp unless cmp.zero?
+        end
+        0
+      end
+
+      # nil (an absent path) sorts after any real value, regardless of
+      # ASC/DESC - the usual SQL "NULLS LAST" convention.
+      def compare_values(a, b)
+        return 0 if a.nil? && b.nil?
+        return 1 if a.nil?
+        return -1 if b.nil?
+
+        a <=> b
+      end
+
+      def project(bindings)
+        columns = @query.select_clause.columns
+        bindings.map { |binding| columns.map { |column| PathEvaluator.evaluate(column.expression, binding) } }
+      end
+
+      def apply_limit(rows)
+        limit_clause = @query.limit_clause
+        return rows unless limit_clause
+
+        rows.drop(limit_clause.offset).take(limit_clause.limit)
+      end
+
+      def aggregate_query?
+        @query.select_clause.columns.any? { |column| column.expression.is_a?(Model::AggregateFunctionCall) }
+      end
+
+      def aggregate_row(bindings)
+        @query.select_clause.columns.map do |column|
+          call = column.expression
+          unless call.is_a?(Model::AggregateFunctionCall)
+            raise ExecutionError, 'mixing aggregate and non-aggregate SELECT columns is not yet supported'
+          end
+
+          evaluate_aggregate(call, bindings)
+        end
+      end
+
+      def evaluate_aggregate(call, bindings)
+        return bindings.size if call.name == :count && call.path.nil?
+
+        values = bindings.map { |binding| PathEvaluator.evaluate(call.path, binding) }.compact
+        values = values.uniq if call.distinct
+
+        case call.name
+        when :count then values.size
+        when :min then values.min
+        when :max then values.max
+        when :sum then values.empty? ? nil : values.sum
+        when :avg then values.empty? ? nil : values.sum.fdiv(values.size)
+        else raise ExecutionError, "cannot evaluate a #{call.name.inspect} aggregate function yet"
+        end
+      end
+
+      def column_name(column)
+        return column.alias_name if column.alias_name
+
+        expression = column.expression
+        expression.is_a?(Model::IdentifiedPath) ? expression.variable : expression.class.name
+      end
+    end
+  end
+end

data/lib/openehr/aql/errors.rb

@@ -0,0 +1,27 @@
+# Error hierarchy for the AQL subsystem (parsing, semantic checks, and
+# execution). Kept in its own file so lexer.rb/parser.rb/engine.rb can
+# each require just this, without pulling in the rest of the subsystem.
+module OpenEHR
+  module AQL
+    class Error < StandardError; end
+
+    # Raised by the Lexer/Parser on malformed AQL source. Carries the
+    # 1-based line/column of the offending token so the message can point
+    # at the exact spot, e.g. "line 2, column 8: ...".
+    class ParseError < Error
+      attr_reader :line, :column
+
+      def initialize(message, line: nil, column: nil)
+        @line = line
+        @column = column
+        location = line && column ? " (line #{line}, column #{column})" : ''
+        super("#{message}#{location}")
+      end
+    end
+
+    class SemanticError < Error; end
+    class UnboundParameterError < Error; end
+    class ExecutionError < Error; end
+    class DatasetError < Error; end
+  end
+end

data/lib/openehr/aql/lexer.rb

@@ -0,0 +1,295 @@
+require_relative 'errors'
+
+# OpenEHR::AQL::Lexer tokenizes AQL source text, following the official
+# ANTLR4 lexer grammar (AqlLexer.g4,
+# https://specifications.openehr.org/releases/QUERY/latest/AQL.html) as
+# the reference spec. It is a hand-written scanner (no parser-generator
+# dependency is added) so that maximal-munch tie-breaks between
+# overlapping token shapes - e.g. "openEHR-EHR-OBSERVATION.blood_pressure.v1"
+# (ARCHETYPE_HRID) vs "openEHR" (IDENTIFIER), or "id5" (ID_CODE) vs "id5x"
+# (IDENTIFIER) - can be resolved explicitly per token category, matching
+# ANTLR's longest-match-wins / first-rule-wins-on-tie semantics.
+#
+# Scope (M0 milestone): keywords (case-insensitive), identifiers,
+# ARCHETYPE_HRID, AT_CODE/ID_CODE, STRING, INTEGER/REAL/SCI_*, BOOLEAN,
+# $PARAMETER, comparison operators, structural symbols, and '--' comments.
+# DATE/TIME/DATETIME literals, TERM_CODE, URI, CONTAINED_REGEX and a
+# Unicode BOM are deferred to the milestone that first needs them - none
+# of the official AQL examples this gem targets require them yet.
+module OpenEHR
+  module AQL
+    class Token
+      attr_reader :type, :value, :line, :column
+
+      def initialize(type, value, line:, column:)
+        @type = type
+        @value = value
+        @line = line
+        @column = column
+        freeze
+      end
+
+      def ==(other)
+        other.is_a?(Token) && type == other.type && value == other.value
+      end
+      alias eql? ==
+
+      def hash
+        [type, value].hash
+      end
+
+      def to_s
+        "#{type}(#{value.inspect})@#{line}:#{column}"
+      end
+    end
+
+    class Lexer
+      KEYWORDS = {
+        'select' => :select, 'as' => :as, 'from' => :from, 'where' => :where,
+        'order' => :order, 'by' => :by, 'desc' => :desc, 'descending' => :descending,
+        'asc' => :asc, 'ascending' => :ascending, 'limit' => :limit, 'offset' => :offset,
+        'distinct' => :distinct, 'version' => :version, 'latest_version' => :latest_version,
+        'all_versions' => :all_versions, 'null' => :null,
+        'top' => :top, 'forward' => :forward, 'backward' => :backward,
+        'contains' => :contains, 'and' => :and, 'or' => :or, 'not' => :not, 'exists' => :exists,
+        'like' => :like, 'matches' => :matches,
+        'count' => :count, 'min' => :min, 'max' => :max, 'sum' => :sum, 'avg' => :avg,
+        'terminology' => :terminology,
+        'length' => :length, 'position' => :position, 'substring' => :substring,
+        'concat' => :concat, 'concat_ws' => :concat_ws,
+        'abs' => :abs, 'mod' => :mod, 'ceil' => :ceil, 'floor' => :floor, 'round' => :round,
+        'now' => :now, 'current_date' => :current_date, 'current_time' => :current_time,
+        'current_date_time' => :current_date_time, 'current_timezone' => :current_timezone
+      }.freeze
+
+      ARCHETYPE_HRID_RE = /\A[A-Za-z][A-Za-z0-9_]*-[A-Za-z][A-Za-z0-9_]*-[A-Za-z][A-Za-z0-9_]*
+                            \.[A-Za-z][A-Za-z0-9_-]*
+                            \.v\d+(?:\.\d+)*(?:-(?:rc|alpha)(?:\.\d+)?)?/x
+      AT_ID_CODE_RE = /\A(?:at|id)\d+(?:\.\d+)*/
+      IDENTIFIER_RE = /\A[A-Za-z][A-Za-z0-9_]*/
+      URI_CHAR = %r{[A-Za-z0-9\-._~%!$&'()*+,;=:@/]}.source
+      URI_RE = %r{\A[A-Za-z][A-Za-z0-9+.-]*:(?://)?#{URI_CHAR}*(?:\?#{URI_CHAR}*)?(?:\##{URI_CHAR}*)?}o
+      NUMBER_RE = /\A(?:\d*\.\d+|\d+)(?:[eE][+-]?\d+)?/
+
+      ESCAPES = {
+        '\\' => "\\", "'" => "'", '"' => '"', '?' => '?',
+        'a' => "\a", 'b' => "\b", 'f' => "\f", 'n' => "\n",
+        'r' => "\r", 't' => "\t", 'v' => "\v"
+      }.freeze
+
+      SYMBOLS = {
+        ',' => :comma, '/' => :slash, '*' => :asterisk, '+' => :plus,
+        '(' => :left_paren, ')' => :right_paren,
+        '[' => :left_bracket, ']' => :right_bracket,
+        '{' => :left_curly, '}' => :right_curly
+      }.freeze
+
+      def initialize(source)
+        raise ArgumentError, 'source must be a String' unless source.is_a?(String)
+
+        @chars = source.chars
+        @pos = 0
+        @line = 1
+        @column = 1
+      end
+
+      def tokenize
+        tokens = []
+        loop do
+          skip_whitespace_and_comments
+          start_line, start_column = @line, @column
+          if at_end?
+            tokens << Token.new(:eof, nil, line: start_line, column: start_column)
+            break
+          end
+          tokens << next_token(start_line, start_column)
+        end
+        tokens.freeze
+      end
+
+      private
+
+      def at_end?
+        @pos >= @chars.length
+      end
+
+      def peek(offset = 0)
+        @chars[@pos + offset]
+      end
+
+      def advance
+        c = @chars[@pos]
+        @pos += 1
+        if c == "\n"
+          @line += 1
+          @column = 1
+        else
+          @column += 1
+        end
+        c
+      end
+
+      def remaining
+        @chars[@pos..].join
+      end
+
+      def skip_whitespace_and_comments
+        loop do
+          if !at_end? && peek =~ /[ \t\r\n]/
+            advance
+          elsif peek == '-' && peek(1) == '-' && comment_ahead?
+            skip_comment
+          else
+            break
+          end
+        end
+      end
+
+      # A "--" starts a COMMENT only when followed by a space (a
+      # "-- text" line comment) or immediately by newline/EOF (an empty
+      # comment). Any other following character means the "--" itself is
+      # a SYM_DOUBLE_DASH token, handled by next_token instead.
+      def comment_ahead?
+        after = peek(2)
+        after.nil? || after == ' ' || after == "\n" || after == "\r"
+      end
+
+      def skip_comment
+        advance # first '-'
+        advance # second '-'
+        advance while !at_end? && peek != "\n"
+      end
+
+      def next_token(line, column)
+        c = peek
+        return read_string(line, column) if c == "'" || c == '"'
+        return read_parameter(line, column) if c == '$'
+        return read_number(line, column) if c =~ /\d/
+        return read_word(line, column) if c =~ /[A-Za-z]/
+        return read_double_dash_or_symbol(line, column) if c == '-'
+        return read_comparison_operator(line, column) if c =~ /[=!<>]/
+        return read_symbol(line, column) if SYMBOLS.key?(c)
+
+        raise ParseError.new("unexpected character #{c.inspect}", line: line, column: column)
+      end
+
+      def read_word(line, column)
+        hrid = ARCHETYPE_HRID_RE.match(remaining)&.to_s
+        at_id = AT_ID_CODE_RE.match(remaining)&.to_s
+        uri = URI_RE.match(remaining)&.to_s
+        plain = IDENTIFIER_RE.match(remaining)&.to_s
+
+        candidates = [
+          [hrid, :archetype_hrid, 0],
+          [at_id, :at_id_code, 1],
+          [uri, :uri, 2],
+          [plain, :plain_word, 3]
+        ].select { |text, _type, _pri| text }
+        text, kind, = candidates.max_by { |t, _k, pri| [t.length, -pri] }
+
+        text.length.times { advance }
+
+        case kind
+        when :archetype_hrid
+          Token.new(:archetype_hrid, text, line: line, column: column)
+        when :at_id_code
+          type = text.start_with?('at') ? :at_code : :id_code
+          Token.new(type, text, line: line, column: column)
+        when :uri
+          Token.new(:uri, text, line: line, column: column)
+        else
+          build_word_token(text, line, column)
+        end
+      end
+
+      def build_word_token(text, line, column)
+        downcased = text.downcase
+        if downcased == 'true' || downcased == 'false'
+          Token.new(:boolean, downcased == 'true', line: line, column: column)
+        elsif KEYWORDS.key?(downcased)
+          Token.new(KEYWORDS[downcased], text, line: line, column: column)
+        else
+          Token.new(:identifier, text, line: line, column: column)
+        end
+      end
+
+      def read_number(line, column)
+        text = NUMBER_RE.match(remaining).to_s
+        text.length.times { advance }
+        real = text.include?('.')
+        sci = text =~ /[eE]/
+        type = if real && sci
+                 :sci_real
+               elsif real
+                 :real
+               elsif sci
+                 :sci_integer
+               else
+                 :integer
+               end
+        value = real || sci ? Float(text) : Integer(text)
+        Token.new(type, value, line: line, column: column)
+      end
+
+      def read_string(line, column)
+        quote = advance
+        buffer = +''
+        loop do
+          raise ParseError.new('unterminated string literal', line: line, column: column) if at_end?
+
+          ch = advance
+          if ch == quote
+            break
+          elsif ch == '\\'
+            raise ParseError.new('unterminated string literal', line: line, column: column) if at_end?
+
+            esc = advance
+            buffer << (ESCAPES[esc] || esc)
+          else
+            buffer << ch
+          end
+        end
+        Token.new(:string, buffer, line: line, column: column)
+      end
+
+      def read_parameter(line, column)
+        advance # '$'
+        name = IDENTIFIER_RE.match(remaining)&.to_s
+        if name.nil? || name.empty?
+          raise ParseError.new('expected an identifier after $', line: line, column: column)
+        end
+
+        name.length.times { advance }
+        Token.new(:parameter, name, line: line, column: column)
+      end
+
+      def read_double_dash_or_symbol(line, column)
+        if peek(1) == '-'
+          advance
+          advance
+          Token.new(:double_dash, '--', line: line, column: column)
+        else
+          advance
+          Token.new(:minus, '-', line: line, column: column)
+        end
+      end
+
+      def read_comparison_operator(line, column)
+        c = advance
+        if (c == '!' || c == '<' || c == '>') && peek == '='
+          advance
+          Token.new(:comparison_operator, "#{c}=", line: line, column: column)
+        elsif c == '!'
+          raise ParseError.new("unexpected character \"!\"", line: line, column: column)
+        else
+          Token.new(:comparison_operator, c, line: line, column: column)
+        end
+      end
+
+      def read_symbol(line, column)
+        c = advance
+        Token.new(SYMBOLS.fetch(c), c, line: line, column: column)
+      end
+    end
+  end
+end

data/lib/openehr/aql/model/containment.rb

@@ -0,0 +1,45 @@
+module OpenEHR
+  module AQL
+    module Model
+      # containsExpr's "classExprOperand (NOT? CONTAINS containsExpr)?"
+      # shape: a right-recursive chain (A CONTAINS B CONTAINS C ...), so
+      # `child` is itself a ClassExpression, another Containment, or (from
+      # M7) a ContainmentAnd/ContainmentOr grouping of sibling branches.
+      class Containment
+        attr_reader :parent, :child, :negated
+        alias negated? negated
+
+        def initialize(parent:, child:, negated: false)
+          @parent = parent
+          @child = child
+          @negated = negated
+          freeze
+        end
+      end
+
+      # containsExpr : ... | containsExpr AND containsExpr | ... ;
+      # Groups sibling containment branches that must ALL be present
+      # under the same parent, e.g. "CONTAINS (OBSERVATION o1 AND OBSERVATION o2)".
+      class ContainmentAnd
+        attr_reader :left, :right
+
+        def initialize(left:, right:)
+          @left = left
+          @right = right
+          freeze
+        end
+      end
+
+      # containsExpr : ... | containsExpr OR containsExpr | ... ;
+      class ContainmentOr
+        attr_reader :left, :right
+
+        def initialize(left:, right:)
+          @left = left
+          @right = right
+          freeze
+        end
+      end
+    end
+  end
+end

data/lib/openehr/aql/model/from_clause.rb

@@ -0,0 +1,35 @@
+module OpenEHR
+  module AQL
+    module Model
+      # fromClause : FROM fromExpr ; fromExpr : containsExpr ;
+      # `containment` holds the root of the containsExpr tree. Until M3/M7
+      # add archetype/node predicates and CONTAINS nesting, it is always a
+      # single, unpredicated ClassExpression.
+      class FromClause
+        attr_reader :containment
+
+        def initialize(containment:)
+          @containment = containment
+          freeze
+        end
+      end
+
+      # classExprOperand's #classExpression alternative:
+      #   IDENTIFIER variable=IDENTIFIER? pathPredicate?
+      # A bare RM class name (e.g. "COMPOSITION"), optionally bound to a
+      # variable and constrained by a predicate. Until M3 adds
+      # archetypePredicate/nodePredicate, `predicate` can only be a
+      # StandardPredicate (or nil).
+      class ClassExpression
+        attr_reader :class_name, :variable, :predicate
+
+        def initialize(class_name:, variable: nil, predicate: nil)
+          @class_name = class_name
+          @variable = variable
+          @predicate = predicate
+          freeze
+        end
+      end
+    end
+  end
+end

data/lib/openehr/aql/model/function_call.rb

@@ -0,0 +1,56 @@
+module OpenEHR
+  module AQL
+    module Model
+      # aggregateFunctionCall : name=COUNT SYM_LEFT_PAREN (DISTINCT? identifiedPath | SYM_ASTERISK) SYM_RIGHT_PAREN
+      #                       | name=(MIN | MAX | SUM | AVG) SYM_LEFT_PAREN identifiedPath SYM_RIGHT_PAREN ;
+      # `path` is nil only for the COUNT(*) form; `distinct` is only ever
+      # true for COUNT (the grammar doesn't allow DISTINCT on MIN/MAX/SUM/AVG).
+      class AggregateFunctionCall
+        attr_reader :name, :path, :distinct
+
+        def initialize(name:, path: nil, distinct: false)
+          @name = name
+          @path = path
+          @distinct = distinct
+          freeze
+        end
+      end
+
+      # functionCall : terminologyFunction
+      #              | name=(STRING_FUNCTION_ID | NUMERIC_FUNCTION_ID | DATE_TIME_FUNCTION_ID | IDENTIFIER)
+      #                SYM_LEFT_PAREN (terminal (SYM_COMMA terminal)*)? SYM_RIGHT_PAREN ;
+      class FunctionCall
+        attr_reader :name, :arguments
+
+        def initialize(name:, arguments: [])
+          @name = name
+          @arguments = arguments.freeze
+          freeze
+        end
+      end
+
+      # terminologyFunction : TERMINOLOGY SYM_LEFT_PAREN STRING SYM_COMMA STRING SYM_COMMA STRING SYM_RIGHT_PAREN ;
+      # The grammar doesn't name the three STRING arguments (their meaning
+      # - expand-operation, terminology id, value-set expression - is
+      # spec prose, not grammar), so they're kept as a plain positional list.
+      class TerminologyFunctionCall
+        attr_reader :args
+
+        def initialize(args:)
+          @args = args.freeze
+          freeze
+        end
+      end
+
+      # matchesOperand's bare-URI alternative: SYM_LEFT_CURLY URI SYM_RIGHT_CURLY ;
+      class UriRef
+        attr_reader :uri
+
+        def initialize(uri:)
+          @uri = uri
+          freeze
+        end
+      end
+    end
+  end
+end

data/lib/openehr/aql/model/identified_path.rb

@@ -0,0 +1,20 @@
+module OpenEHR
+  module AQL
+    module Model
+      # identifiedPath : IDENTIFIER pathPredicate? (SYM_SLASH objectPath)? ;
+      # A variable reference, optionally constrained by a predicate on the
+      # variable itself (e.g. "c[at001 or at002]"), optionally followed by
+      # an object path rooted at that variable (e.g. "o/data[at0001]/.../value").
+      class IdentifiedPath
+        attr_reader :variable, :predicate, :path
+
+        def initialize(variable:, predicate: nil, path: nil)
+          @variable = variable
+          @predicate = predicate
+          @path = path
+          freeze
+        end
+      end
+    end
+  end
+end

data/lib/openehr/aql/model/literal.rb

@@ -0,0 +1,15 @@
+module OpenEHR
+  module AQL
+    module Model
+      # primitive : STRING | numericPrimitive | DATE | TIME | DATETIME | BOOLEAN | NULL ;
+      class Literal
+        attr_reader :value
+
+        def initialize(value:)
+          @value = value
+          freeze
+        end
+      end
+    end
+  end
+end

data/lib/openehr/aql/model/object_path.rb

@@ -0,0 +1,34 @@
+module OpenEHR
+  module AQL
+    module Model
+      # objectPath : pathPart (SYM_SLASH pathPart)* ;
+      class ObjectPath
+        attr_reader :segments
+
+        def initialize(segments:)
+          @segments = segments.freeze
+          freeze
+        end
+
+        def to_s
+          segments.map(&:to_s).join('/')
+        end
+      end
+
+      # pathPart : IDENTIFIER pathPredicate? ;
+      class PathPart
+        attr_reader :attribute, :predicate
+
+        def initialize(attribute:, predicate: nil)
+          @attribute = attribute
+          @predicate = predicate
+          freeze
+        end
+
+        def to_s
+          predicate ? "#{attribute}[#{predicate}]" : attribute
+        end
+      end
+    end
+  end
+end