openehr 1.3.0 → 2.0.0

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

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

@@ -0,0 +1,50 @@
+module OpenEHR
+  module AQL
+    module Model
+      # orderByClause : ORDER BY orderByExpr (SYM_COMMA orderByExpr)* ;
+      class OrderByClause
+        attr_reader :items
+
+        def initialize(items:)
+          @items = items.freeze
+          freeze
+        end
+      end
+
+      # orderByExpr : identifiedPath order=(DESCENDING|DESC|ASCENDING|ASC)? ;
+      # `direction` is always :asc or :desc - the grammar's four spellings
+      # (ASC/ASCENDING/DESC/DESCENDING) collapse to one of these two.
+      class OrderByItem
+        attr_reader :path, :direction
+
+        def initialize(path:, direction: :asc)
+          @path = path
+          @direction = direction
+          freeze
+        end
+      end
+
+      # limitClause : LIMIT limit=INTEGER (OFFSET offset=INTEGER)? ;
+      class LimitClause
+        attr_reader :limit, :offset
+
+        def initialize(limit:, offset: 0)
+          @limit = limit
+          @offset = offset
+          freeze
+        end
+      end
+
+      # top : TOP INTEGER direction=(FORWARD|BACKWARD)? ; (deprecated)
+      class Top
+        attr_reader :count, :direction
+
+        def initialize(count:, direction: nil)
+          @count = count
+          @direction = direction
+          freeze
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,84 @@
+module OpenEHR
+  module AQL
+    module Model
+      # standardPredicate : objectPath COMPARISON_OPERATOR pathPredicateOperand ;
+      # (nodePredicate's 4th alternative has this identical shape - see
+      # Parser#parse_standard_predicate's comment.)
+      class StandardPredicate
+        attr_reader :path, :operator, :operand
+
+        def initialize(path:, operator:, operand:)
+          @path = path
+          @operator = operator
+          @operand = operand
+          freeze
+        end
+      end
+
+      # archetypePredicate : ARCHETYPE_HRID (SYM_COMMA (STRING | PARAMETER | TERM_CODE | AT_CODE | ID_CODE))? | PARAMETER ;
+      # `value` is the optional SYM_COMMA suffix: a raw String (for
+      # STRING/AT_CODE/ID_CODE) or a Parameter. The bare-PARAMETER
+      # alternative (a whole predicate substituted at execution time,
+      # e.g. "[$archetypeId]") isn't needed by any current example and is
+      # deferred - see Parser#parse_predicate_primary.
+      class ArchetypePredicate
+        attr_reader :archetype_id, :value
+
+        def initialize(archetype_id:, value: nil)
+          @archetype_id = archetype_id
+          @value = value
+          freeze
+        end
+      end
+
+      # nodePredicate : (ID_CODE | AT_CODE) (SYM_COMMA (STRING | PARAMETER | TERM_CODE | AT_CODE | ID_CODE))? | ... ;
+      # `value` is the optional SYM_COMMA suffix, same shape as
+      # ArchetypePredicate#value.
+      class NodePredicate
+        attr_reader :code, :value
+
+        def initialize(code:, value: nil)
+          @code = code
+          @value = value
+          freeze
+        end
+      end
+
+      # nodePredicate : ... | nodePredicate AND nodePredicate | ... ;
+      # Combines any pathPredicate-body primaries (ArchetypePredicate,
+      # NodePredicate, Parameter, StandardPredicate). AND binds tighter
+      # than OR, same precedence-climbing convention used for whereExpr
+      # (M5) and containsExpr (M7).
+      class PredicateAnd
+        attr_reader :left, :right
+
+        def initialize(left:, right:)
+          @left = left
+          @right = right
+          freeze
+        end
+      end
+
+      # nodePredicate : ... | nodePredicate OR nodePredicate ;
+      class PredicateOr
+        attr_reader :left, :right
+
+        def initialize(left:, right:)
+          @left = left
+          @right = right
+          freeze
+        end
+      end
+
+      # PARAMETER: '$' IDENTIFIER_CHAR ;
+      class Parameter
+        attr_reader :name
+
+        def initialize(name:)
+          @name = name
+          freeze
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,24 @@
+module OpenEHR
+  module AQL
+    module Model
+      # The parsed, immutable representation of an AQL selectQuery.
+      # Clauses that a milestone hasn't implemented yet are nil.
+      class Query
+        attr_reader :select_clause, :from_clause, :where_clause, :order_by_clause, :limit_clause
+
+        def initialize(select_clause:, from_clause:, where_clause: nil, order_by_clause: nil, limit_clause: nil)
+          @select_clause = select_clause
+          @from_clause = from_clause
+          @where_clause = where_clause
+          @order_by_clause = order_by_clause
+          @limit_clause = limit_clause
+          freeze
+        end
+
+        def execute(dataset, params: {})
+          OpenEHR::AQL::Engine.new(self).execute(dataset, params: params)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,29 @@
+module OpenEHR
+  module AQL
+    module Model
+      # selectClause : SELECT DISTINCT? top? selectExpr (SYM_COMMA selectExpr)* ;
+      class SelectClause
+        attr_reader :columns, :distinct, :top
+        alias distinct? distinct
+
+        def initialize(columns:, distinct: false, top: nil)
+          @columns = columns.freeze
+          @distinct = distinct
+          @top = top
+          freeze
+        end
+      end
+
+      # selectExpr : columnExpr (AS aliasName=IDENTIFIER)? ;
+      class SelectColumn
+        attr_reader :expression, :alias_name
+
+        def initialize(expression:, alias_name: nil)
+          @expression = expression
+          @alias_name = alias_name
+          freeze
+        end
+      end
+    end
+  end
+end