openehr 2.1.0 → 2.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9e728b70dac1326f832dd44e631442ae3e9ed8b3a3c81a2b5300c23e01a9068e
-  data.tar.gz: 0003101647c193f7d35d575a3eef1a92a8e34038a849719a0598e34109f92a52
+  metadata.gz: 10d6fc971443c1c8014d60bebd609c71757870ba0bb0d710cc35f014981b7ca1
+  data.tar.gz: 93b4ce3dd288a4943c0b4112d6ec9cb55ee1438d0411f66a7c47d5d26ea8b4b9
 SHA512:
-  metadata.gz: 334d9390f1e59a2a68a812fda1c946ddf3a74504b4234f6363dddee9e42d8763b01d8bbee50fed8c894318c4bec794b4ba743310961e4ba482164ccf9ec660e7
-  data.tar.gz: 611283bb569b4bc0672a502d09b6c485db8ca47131dd8393fdb6ac67589bbdfeb305d0a98a628997a6091ffd6dda03d57695560a61308104f96c06f7e95a9c98
+  metadata.gz: cdb1ec0e04bda30a3d15fed92ef940f0a4aacde6f4e6570f8f5c5f6b0c6e14320166f88834c0a657a1b37d6973edc63650ce641bc1f43d92043289a90b95f5ed
+  data.tar.gz: 4b42fece35848e073eb3111d5f7abd8b85d02986799433df8330ff65bbbf5c1b8d979cf2d16bee175d4faf4d908c7cf78479a8dd9adfa3c2c6035c84a51d59a5

data/README.rdoc

@@ -7,9 +7,9 @@ A Ruby implementation of the openEHR specifications
 
 = Requirements
 
-* Supports the Ruby versions currently maintained upstream by Ruby core: 3.2, 3.4, and 4.0.
-* Developed with CRuby 4.0.6 on Linux; CI covers 3.2, 3.4, and 4.0.
-* Other versions, including 3.1 and 3.3, are not supported.
+* Supports the Ruby versions currently maintained upstream by Ruby core: 3.3, 3.4, and 4.0.
+* Developed with CRuby 4.0.6 on Linux; CI covers 3.3, 3.4, and 4.0.
+* Other versions, including 3.1 and 3.2, are not supported (both reached EOL).
 
 =Description
 
@@ -25,6 +25,9 @@ The intention is to have a sample EHR to deploy quickly with Ruby on Rails for d
 
 This package includes:
 * ADL 1.4 parser
+* An XML archetype parser (reads the canonical openEHR ITS-XML shape
+  that this gem's own XMLSerializer produces, sharing its constraint-
+  tree node builders with the OPT parser)
 * AM/RM packages based on the openEHR specification 1.0.2, plus RM 1.1.0 deltas
 * ADL/XML/JSON serializers and an ADL archetype validator
 * AQL (Archetype Query Language): a parser plus an in-memory execution
@@ -32,7 +35,6 @@ This package includes:
   already have in memory (see "Querying with AQL" below)
 
 This package excludes:
-* An XML archetype parser (in progress)
 * Persistent data stores and search indexes - AQL here only ever
   queries in-memory RM object graphs; the moment your data lives in a
   database, that integration (e.g. openehr-rails) owns fetching it out
@@ -69,13 +71,24 @@ way, from RM 1.1.0 onward.
   FEEDER_AUDIT_DETAILS.other_details         1.1.0       Optional ITEM_STRUCTURE meta-data (SPECRM-74)
   ACTIVITY.timing                            1.1.0       Now optional (was mandatory pre-1.1.0)
   ISM_TRANSITION.reason                      1.1.0       Optional List<DV_TEXT>
+  ISM_TRANSITION.transition                  1.1.0       Now optional (was mandatory pre-1.1.0)
+  DV_IDENTIFIER.issuer/assigner/type         1.0.4       Optional (only id remains 1..1 mandatory)
+  PARTICIPATION.mode                         1.0.4       Now optional (was mandatory pre-1.0.4)
+  EHR.contributions / EHR.compositions       1.1.0       Now optional (was mandatory pre-1.1.0)
+  DV_MULTIMEDIA.size                         1.1.0       Optional Integer; falls back to the inherited
+                                                          value-based size when not given explicitly
+  ELEMENT.null_reason                        1.1.0       Optional DV_TEXT; requires null_flavor to be set
   COMPOSITION.category = "episodic"          1.1.0       A terminology value, not a code change (SPECRM-89);
                                                           already supported via the pluggable
                                                           OpenEHR::TerminologyService seam
 
+DV_DATE/DV_TIME/DV_DATE_TIME now support #add/#subtract against a
+DV_DURATION (calendar-aware: month-end clamping, leap years, and
+day/timezone wraparound), and DV_DURATION supports +/-/multiply
+against another DV_DURATION.
+
 Not yet incorporated from RM 1.1.0 / BASE 1.2.0: ITEM_TAG (still in a
-development branch, not yet in a released RM version) and the finer
-points of DV_DURATION arithmetic beyond negation/unary minus.
+development branch, not yet in a released RM version).
 
 =Querying with AQL
 

data/lib/openehr/aql/engine/contains_resolver.rb

@@ -11,15 +11,18 @@ module OpenEHR
     # CONTAINS chain searching a matched Locatable's *entire* subtree
     # (any depth, via Pathable#path_children) for the next class,
     # archetype-predicate filtering, AND/OR-grouped sibling branches
-    # (cross-product / union of each branch's matches) and NOT CONTAINS
-    # (parent matches survive only when the negated class is absent).
-    # standardPredicate/nodePredicate filtering and an EHR-level
-    # predicate (e.g. "[ehr_id/value=$ehr_id]") are added by a later
-    # engine milestone.
+    # (cross-product / union of each branch's matches), NOT CONTAINS
+    # (parent matches survive only when the negated class is absent),
+    # and an EHR-level standardPredicate (e.g. "[ehr_id/value=$ehr_id]",
+    # reusing PathEvaluator/PredicateEvaluator's existing comparison
+    # machinery rather than new bespoke logic). standardPredicate/
+    # nodePredicate filtering on non-EHR CONTAINS classes is added by a
+    # later engine milestone (see predicate_matches? below).
     class ContainsResolver
-      def initialize(from_clause, dataset)
+      def initialize(from_clause, dataset, params: {})
         @root = from_clause.containment
         @dataset = dataset
+        @params = params
       end
 
       def each_binding
@@ -56,7 +59,11 @@ module OpenEHR
       end
 
       def resolve_class_expression(class_expression, ehr_record, pool)
-        return [[variables_for(class_expression, ehr_record), ehr_record]] if ehr_root?(class_expression)
+        if ehr_root?(class_expression)
+          return [] unless ehr_predicate_matches?(ehr_record, class_expression.predicate)
+
+          return [[variables_for(class_expression, ehr_record), ehr_record]]
+        end
 
         pool.select { |candidate| matches?(candidate, class_expression) }
             .map { |candidate| [variables_for(class_expression, candidate), candidate] }
@@ -142,11 +149,95 @@ module OpenEHR
           true
         when Model::ArchetypePredicate
           candidate.respond_to?(:archetype_node_id) && candidate.archetype_node_id == predicate.archetype_id
+        when Model::NodePredicate
+          node_predicate_matches?(candidate, predicate)
+        when Model::StandardPredicate
+          standard_predicate_matches?(candidate, predicate)
+        when Model::PredicateAnd
+          predicate_matches?(candidate, predicate.left) && predicate_matches?(candidate, predicate.right)
+        when Model::PredicateOr
+          predicate_matches?(candidate, predicate.left) || predicate_matches?(candidate, predicate.right)
         else
           raise ExecutionError, "cannot evaluate a #{predicate.class} predicate yet"
         end
       end
 
+      # nodePredicate "[atNNNN]" matches by archetype_node_id alone;
+      # "[atNNNN, 'Name']" additionally requires the node's own `name`
+      # DV_TEXT to equal the given display name.
+      def node_predicate_matches?(candidate, predicate)
+        return false unless candidate.respond_to?(:archetype_node_id) && candidate.archetype_node_id == predicate.code
+        return true unless predicate.value
+
+        unless predicate.value.is_a?(String)
+          raise ExecutionError, "cannot evaluate a #{predicate.value.class} node predicate value yet"
+        end
+
+        node_name_matches?(candidate, predicate.value)
+      end
+
+      def node_name_matches?(candidate, value)
+        return false unless candidate.respond_to?(:name)
+
+        name = candidate.name
+        name.respond_to?(:value) && name.value == value
+      end
+
+      # standardPredicate on a CONTAINS class expression reuses the same
+      # operand-resolution/comparison machinery the E10 EHR-root
+      # predicate already established, just rooted at the matched
+      # candidate instead of the Dataset::EHRRecord.
+      def standard_predicate_matches?(candidate, predicate)
+        left = predicate_operand(candidate, predicate.path)
+        right = predicate_operand(candidate, predicate.operand)
+        return false if left.nil? || right.nil?
+
+        PredicateEvaluator.compare(left, predicate.operator, right)
+      end
+
+      # An EHR-root predicate (e.g. "[ehr_id/value=$ehr_id]") is a
+      # standardPredicate/PredicateAnd/PredicateOr tree evaluated against
+      # the Dataset::EHRRecord itself, reusing PathEvaluator.navigate
+      # (which already special-cases EHRRecord) and
+      # PredicateEvaluator.compare/lookup_param rather than new
+      # comparison code.
+      def ehr_predicate_matches?(ehr_record, predicate)
+        case predicate
+        when nil
+          true
+        when Model::StandardPredicate
+          standard_ehr_predicate_matches?(ehr_record, predicate)
+        when Model::PredicateAnd
+          ehr_predicate_matches?(ehr_record, predicate.left) && ehr_predicate_matches?(ehr_record, predicate.right)
+        when Model::PredicateOr
+          ehr_predicate_matches?(ehr_record, predicate.left) || ehr_predicate_matches?(ehr_record, predicate.right)
+        else
+          raise ExecutionError, "cannot evaluate a #{predicate.class} EHR predicate yet"
+        end
+      end
+
+      def standard_ehr_predicate_matches?(ehr_record, predicate)
+        left = predicate_operand(ehr_record, predicate.path)
+        right = predicate_operand(ehr_record, predicate.operand)
+        return false if left.nil? || right.nil?
+
+        PredicateEvaluator.compare(left, predicate.operator, right)
+      end
+
+      # Shared by both the EHR-root and the CONTAINS-class-expression
+      # standardPredicate paths - `root` is whichever object the
+      # predicate's path is rooted at (a Dataset::EHRRecord or a
+      # CONTAINS-matched Pathable candidate); PathEvaluator.navigate
+      # already special-cases EHRRecord and falls through to ordinary
+      # Pathable navigation for everything else.
+      def predicate_operand(root, operand)
+        return PredicateEvaluator.lookup_param(operand, @params) if operand.is_a?(Model::Parameter)
+        return operand.value if operand.is_a?(Model::Literal)
+        return operand unless operand.is_a?(Model::ObjectPath)
+
+        operand.segments.reduce(root) { |current, segment| current.nil? ? nil : PathEvaluator.navigate(current, segment) }
+      end
+
       def variables_for(class_expression, matched)
         return {} unless class_expression.variable
 

data/lib/openehr/aql/engine/dataset.rb

@@ -95,7 +95,9 @@ module OpenEHR
           ehr_id: ehr.ehr_id,
           ehr: ehr,
           ehr_status: ehr.ehr_status&.latest_version&.data,
-          compositions: ehr.compositions.map { |versioned_composition| versioned_composition.latest_version.data }
+          # EHR.compositions is optional (0..1) since RM 1.1.0 - Array()
+          # normalizes a nil (no compositions at all) to an empty list.
+          compositions: Array(ehr.compositions).map { |versioned_composition| versioned_composition.latest_version.data }
         )
       end
 

data/lib/openehr/aql/engine/predicate_evaluator.rb

@@ -2,14 +2,24 @@ module OpenEHR
   module AQL
     # Evaluates a WHERE clause's boolean expression tree against a
     # Binding and the query's runtime params. E5 scope: comparisons
-    # (reusing PathEvaluator for both sides), AND/OR/NOT and EXISTS.
-    # LIKE, MATCHES and functionCall operands are added by later engine
-    # milestones.
+    # (reusing PathEvaluator for both sides), AND/OR/NOT and EXISTS. E12
+    # adds LIKE (glob match, not SQL's %/_); E13 adds MATCHES against a
+    # literal value list (a URI/TERMINOLOGY(...) operand names an
+    # external value-set lookup this engine has no terminology service
+    # wired for, so those raise a clear ExecutionError rather than
+    # silently matching everything). Generic functionCall operands are
+    # added by a later engine milestone.
     module PredicateEvaluator
       COMPARATORS = {
         '=' => :==, '!=' => :!=, '<' => :<, '<=' => :<=, '>' => :>, '>=' => :>=
       }.freeze
 
+      # LIKE's glob syntax (AQL spec, not SQL's %/_): '?' matches exactly
+      # one character, '*' matches zero or more, anything else is a
+      # literal character - and the whole value must match, not a
+      # substring.
+      GLOB_TO_REGEXP = { '*' => '.*', '?' => '.' }.freeze
+
       module_function
 
       # `expression` is nil when there is no WHERE clause at all.
@@ -27,11 +37,68 @@ module OpenEHR
           !matches?(expression.operand, binding, params)
         when Model::ExistsExpr
           !PathEvaluator.evaluate(expression.path, binding).nil?
+        when Model::LikeExpr
+          evaluate_like(expression, binding, params)
+        when Model::MatchesExpr
+          evaluate_matches(expression, binding, params)
         else
           raise ExecutionError, "cannot evaluate a #{expression.class} WHERE expression yet"
         end
       end
 
+      def evaluate_like(like_expr, binding, params)
+        value = PathEvaluator.evaluate(like_expr.path, binding)
+        pattern = resolve_operand(like_expr.operand, binding, params)
+        return false if value.nil? || pattern.nil?
+
+        like_regexp(pattern).match?(value.to_s)
+      end
+
+      def like_regexp(pattern)
+        body = pattern.chars.map { |char| GLOB_TO_REGEXP[char] || Regexp.escape(char) }.join
+        Regexp.new("\\A#{body}\\z", Regexp::MULTILINE)
+      end
+
+      def evaluate_matches(matches_expr, binding, params)
+        value = PathEvaluator.evaluate(matches_expr.path, binding)
+        return false if value.nil?
+
+        case matches_expr.operand
+        when Model::MatchesValueList
+          matches_value_list?(value, matches_expr.operand, params)
+        when Model::UriRef, Model::TerminologyFunctionCall
+          raise ExecutionError,
+                "MATCHES against a #{matches_expr.operand.class} names an external terminology service lookup " \
+                '(a value-set expansion), which this engine has none wired in for - ' \
+                'OpenEHR::TerminologyService only validates a single known code, it cannot expand a value set'
+        else
+          raise ExecutionError, "cannot evaluate a #{matches_expr.operand.class} MATCHES operand yet"
+        end
+      end
+
+      def matches_value_list?(value, value_list, params)
+        value_list.items.any? do |item|
+          candidate = matches_list_item_value(item, params)
+          !candidate.nil? && value == candidate
+        end
+      end
+
+      def matches_list_item_value(item, params)
+        case item
+        when Model::Parameter
+          lookup_param(item, params)
+        when Model::Literal
+          item.value
+        when Model::TerminologyFunctionCall
+          raise ExecutionError,
+                "MATCHES against a #{item.class} names an external terminology service lookup " \
+                '(a value-set expansion), which this engine has none wired in for - ' \
+                'OpenEHR::TerminologyService only validates a single known code, it cannot expand a value set'
+        else
+          raise ExecutionError, "cannot evaluate a #{item.class} MATCHES value-list item yet"
+        end
+      end
+
       # A comparison against an absent (nil) value is neither true nor
       # false in AQL/SQL terms - it simply fails to select the row, the
       # same as SQL's NULL-comparison-is-UNKNOWN convention.

data/lib/openehr/aql/engine.rb

@@ -7,23 +7,27 @@ 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.
+    # CONTAINS -> WHERE -> ORDER BY -> SELECT -> DISTINCT -> TOP/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.
+    # TOP/LIMIT don't apply to it, matching plain SQL aggregate-without-
+    # GROUP-BY semantics. A SELECT mixing aggregate and non-aggregate
+    # columns implicitly groups by every non-aggregate column's value
+    # (the standard SQL reading when no explicit GROUP BY is given) -
+    # zero surviving bindings therefore means zero groups/rows, unlike
+    # the all-aggregate case's single row of aggregate defaults. 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
+        bindings = ContainsResolver.new(@query.from_clause, Dataset.wrap(dataset), params: params).each_binding
                                     .select { |binding| where_matches?(binding, params) }
-        rows = aggregate_query? ? [aggregate_row(bindings)] : select_rows(bindings)
+        rows = aggregate_query? ? aggregate_rows(bindings) : select_rows(bindings)
         ResultSet.new(columns: @query.select_clause.columns.map { |column| column_name(column) }, rows: rows)
       end
 
@@ -36,7 +40,7 @@ module OpenEHR
       def select_rows(bindings)
         rows = project(order(bindings))
         rows = rows.uniq if @query.select_clause.distinct
-        apply_limit(rows)
+        apply_limit(apply_top(rows))
       end
 
       def order(bindings)
@@ -77,18 +81,47 @@ module OpenEHR
         rows.drop(limit_clause.offset).take(limit_clause.limit)
       end
 
+      # TOP is deprecated in favour of LIMIT (still grammatical); combined
+      # with LIMIT it has no defined meaning, so raise rather than guess.
+      def apply_top(rows)
+        top = @query.select_clause.top
+        return rows unless top
+        raise ExecutionError, 'combining SELECT TOP with LIMIT is not supported - use LIMIT alone' if @query.limit_clause
+
+        top.direction == :backward ? rows.last(top.count) : rows.take(top.count)
+      end
+
       def aggregate_query?
         @query.select_clause.columns.any? { |column| column.expression.is_a?(Model::AggregateFunctionCall) }
       end
 
+      def all_aggregate_columns?
+        @query.select_clause.columns.all? { |column| column.expression.is_a?(Model::AggregateFunctionCall) }
+      end
+
+      # All-aggregate columns collapse every surviving binding into one
+      # summary row, same as plain SQL aggregate-without-GROUP-BY. A mix
+      # groups by the non-aggregate columns' values instead - every
+      # binding in a group shares those values by construction, so the
+      # group's first binding is as good as any for reading them back.
+      def aggregate_rows(bindings)
+        return [aggregate_row(bindings)] if all_aggregate_columns?
+
+        bindings.group_by { |binding| group_key(binding) }.map { |_key, group| aggregate_row(group) }
+      end
+
+      def group_key(binding)
+        @query.select_clause.columns.map do |column|
+          next nil if column.expression.is_a?(Model::AggregateFunctionCall)
+
+          PathEvaluator.evaluate(column.expression, binding)
+        end
+      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)
+          call.is_a?(Model::AggregateFunctionCall) ? evaluate_aggregate(call, bindings) : PathEvaluator.evaluate(call, bindings.first)
         end
       end