openehr 1.3.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a8b6b9646daa3a967d9addfb4effc70408a402ff746a52fc549bff5ed150593b
-  data.tar.gz: 9390b872a07e6b3e3291489cfd1dc2ef87cc8eb41f3d2906aab829cfeb317937
+  metadata.gz: 6f34e667ae737ff2718bb8d2e676d75711b0753fd2fb39f64cba6e6eb3bef59a
+  data.tar.gz: bfede641c16301632b2a3647727a10036dff325b2e8bed288bbca1aa820e075c
 SHA512:
-  metadata.gz: a4d0d99c554e80da635c8d4d4bbbef09c5937dede153582e68793611e4708afac008eef063b2ca4a2b57cb7d25f6e18cf0db0914e9f74bf4463b200dd60a764a
-  data.tar.gz: 2b57b5b3556a2d431e7643936026067438d8d1405a9ad443cc7cd237cc7cd37f9b8dbf83085f3aa4d5407d3e3957a01945664b3e00fffa82299a23ab82387a60
+  metadata.gz: 1eabc54006e29b679f16d9d085f097ddb808037a97190611331161b435d1dc77fd7f53ae08f686eda74c3186094a0a15f45351e5fc4d1e1079c13029a10be4e9
+  data.tar.gz: 035d2e2a083d64cb84984c20c7362c4cb8a40912406855a9472c0d1fc240ec43e97547bd17fa83f29f3026b7d55483106b53691f45ceefd813ef858f36026fef

data/README.rdoc

@@ -1,4 +1,4 @@
-{<img src="https://travis-ci.org/skoba/openehr-ruby.png?branch=master" alt="Build Status" />}[https://travis-ci.org/skoba/openehr-ruby]
+{<img src="https://github.com/skoba/openehr-ruby/actions/workflows/ci.yml/badge.svg" alt="CI" />}[https://github.com/skoba/openehr-ruby/actions/workflows/ci.yml]
 =Synopsis
 
 A Ruby implementation of the openEHR specifications
@@ -7,17 +7,17 @@ A Ruby implementation of the openEHR specifications
 
 = Requirements
 
-* Supports CRuby 2.5.0  or later.
-* Developed with CRuby 3.0.0 on FreeBSD and Linux.
-* Ruby 2.4 or earlier are no longer supported.
+* Supports CRuby 3.1 or later.
+* Developed with CRuby 3.4 on Linux; CI covers 3.1-3.4.
+* Ruby 3.0 or earlier are no longer supported.
 
 =Description
 
 This is a stable release of Ruby openEHR implementation project.
-This release is based on openEHR specification release 1.0.2.
-We implemented almost of the specifications of the openEHR.
-The work is still in progress to implement related tools, such as
-archetype validator or serializer. Formerly, we named this package
+This release targets openEHR specification release 1.0.2 as its
+baseline, with a growing set of RM 1.1.0 / BASE 1.2.0 deltas layered on
+top (see "RM 1.0.2 vs RM 1.1.0 semantics" below for exactly which
+classes/attributes are 1.1.0-only). Formerly, we named this package
 as open_ehr, but changed to openehr from release 1.1.0. 1.0.x versions
 are obsoleted.
 
@@ -25,12 +25,18 @@ The intention is to have a sample EHR to deploy quickly with Ruby on Rails for d
 
 This package includes:
 * ADL 1.4 parser
-* AM/RM packages based on the openEHR specification 1.0.2
+* 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
+  engine that evaluates queries directly against RM object graphs you
+  already have in memory (see "Querying with AQL" below)
 
 This package excludes:
-* ADL serializer(in progress)
-* ADL validator(in progress)
-* Data store/retrieve would be separate to the other project.
+* 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
+  and this gem's AQL engine stays completely unaware of how
 * Terminology service(moved to openehr-terminology package)
 * Rails plugin(moved to openehr-rails package
 
@@ -43,6 +49,81 @@ and so on. We have therefore postponed implementations of these classes.
 Terminology and Demographic servers will be implemented in other
 projects.
 
+=RM 1.0.2 vs RM 1.1.0 semantics
+
+This gem's baseline is openEHR RM 1.0.2, with the following RM 1.1.0 /
+BASE 1.2.0 deltas incorporated so far. Everything not listed here keeps
+its 1.0.2 meaning; anything listed only exists, or only behaves this
+way, from RM 1.1.0 onward.
+
+  Class / attribute                          RM version  Notes
+  ------------------------------------------  ----------  ---------------------------------------------
+  DV_SCALE (new class)                       1.1.0       Like DV_ORDINAL, but Real-valued (SPECRM-19)
+  DV_QUANTITY.units_system                   1.1.0       Optional; identifies a non-UCUM units system
+  DV_QUANTITY.units_display_name             1.1.0       Optional displayable form of units (SPECRM-65)
+  CODE_PHRASE.preferred_term                 1.1.0       Optional preferred term for code_string
+  DV_PARAGRAPH                               deprecated  Deprecated since RM 1.0.4; still legal, warns
+  DV_DURATION negative values ("-P10D")      1.1.0       Consistently supported (SPECRM-96)
+  EHR.folders                                1.1.0       List<OBJECT_REF>; directory = folders.item(1)
+  FOLDER.details                             1.1.0       Optional ITEM_STRUCTURE meta-data
+  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>
+  COMPOSITION.category = "episodic"          1.1.0       A terminology value, not a code change (SPECRM-89);
+                                                          already supported via the pluggable
+                                                          OpenEHR::TerminologyService seam
+
+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.
+
+=Querying with AQL
+
+  query  = OpenEHR::AQL.parse(aql_string)                    # => a parsed, immutable Query
+  result = query.execute(dataset, params: { ehr_id: '...' })  # => a ResultSet (Enumerable, plus #to_json)
+  result = OpenEHR::AQL.execute(aql_string, dataset, params: {})  # one-shot
+
+The engine evaluates queries against <tt>OpenEHR::AQL::Dataset</tt>, its
+one and only input boundary - and the whole of its independence from
+any particular web framework or O/R mapper. Everything under
+<tt>lib/openehr/aql/</tt> talks to "wherever your data lives"
+exclusively through <tt>Dataset</tt>, which itself depends on nothing
+but Ruby's own <tt>Enumerable</tt>/<tt>#each</tt> protocol and this
+gem's own RM classes - no ActiveRecord, no Rails, no Sequel, anywhere
+in this gem, ever.
+
+==Supplying data to AQL
+
+<tt>Dataset</tt> accepts any Enumerable of records shaped like
+<tt>{ehr_id:, compositions:, ehr_status: (optional)}</tt> (a Hash with
+symbol or string keys, or a duck-typed object responding to the same
+methods), or a full <tt>OpenEHR::RM::EHR::EHR</tt> if you already have
+one. Every element yielded by a record's <tt>compositions</tt> must be
+one of this gem's own RM objects (<tt>is_a?(OpenEHR::RM::Common::Archetyped::Pathable)</tt>) -
+anything else raises <tt>OpenEHR::AQL::DatasetError</tt> immediately,
+naming the offending class and index, rather than half-working via
+loose duck typing.
+
+Construction never iterates its source, so a lazily-produced
+Enumerable stays lazy all the way through <tt>execute</tt>. A
+hypothetical Rails + ActiveRecord integration (e.g. openehr-rails)
+might look like this - note this is entirely outside this gem, shown
+only to make the boundary concrete:
+
+  records = Ehr.find_each.lazy.map { |row|
+    { ehr_id: row.uid,
+      compositions: row.composition_records.lazy.map { |cr|
+        OpenEHR::RM::CompositionFactory.create_from_json(cr.canonical_json) } } }
+  OpenEHR::AQL.execute(aql, OpenEHR::AQL::Dataset.new(ehrs: records))
+
+Swapping to Sinatra + Sequel, or any other framework/ORM, only changes
+the two <tt>.map</tt> bodies above - nothing in this gem's AQL code
+needs to know or care. For quick, non-database scripts:
+
+  c1 = OpenEHR::RM::CompositionFactory.create_from_json(composition_json)  # or build one by hand
+  OpenEHR::AQL.execute(aql, OpenEHR::AQL::Dataset.of_compositions([c1, c2]))
+  # or even just: OpenEHR::AQL.execute(aql, [c1, c2])  # via Dataset.wrap
+
 =Main codebase authors
 * Shinji Kobayashi and Akimichi Tatsukawa of http://openehr.jp
 * ADL parser test cases are derived from Java and Eiffel reference implementation project of the openEHR.

data/lib/openehr/am/archetype/constraint_model/primitive.rb

@@ -61,6 +61,10 @@ module OpenEHR
               return @false_valid
             end
 
+            def valid_value?(value)
+              (value == true && true_valid?) || (value == false && false_valid?)
+            end
+
             private
             def binary_consistency(true_valid, false_valid)
               if (true_valid == false) && (false_valid == false)
@@ -77,6 +81,7 @@ module OpenEHR
 
           class CString < CPrimitive
             attr_reader :pattern, :list
+            attr_accessor :list_open
 
             def initialize(args = { })
               args[:type] = 'String'
@@ -84,6 +89,7 @@ module OpenEHR
               consistency(args[:pattern], args[:list])
               @pattern = args[:pattern]
               @list = args[:list]
+              @list_open = args[:list_open]
             end
 
             def pattern=(pattern)
@@ -96,9 +102,20 @@ module OpenEHR
               @list = list
             end
 
+            def valid_value?(value)
+              return false unless value.is_a?(String)
+              return true if pattern.nil? && list.nil?
+              return list.include?(value) if list
+
+              Regexp.new(pattern).match?(value)
+            end
+
             private
+            # C_STRING may be fully unconstrained (neither pattern nor
+            # list, i.e. any_allowed); only having both set
+            # simultaneously is a genuine contradiction.
             def consistency(pattern, list)
-              if pattern.nil? == list.nil?
+              if !pattern.nil? && !list.nil?
                 raise ArgumentError, 'consistency invaild'
               end
             end
@@ -125,12 +142,28 @@ module OpenEHR
               @range = range
             end
 
+            def valid_value?(value)
+              return false unless value.is_a?(Integer)
+
+              constrained_value?(value)
+            end
+
             private
+            # C_INTEGER may be fully unconstrained (neither list nor range,
+            # i.e. any_allowed); only having both set simultaneously is a
+            # genuine contradiction.
             def consistency(list, range)
-              if list.nil? == range.nil?
+              if !list.nil? && !range.nil?
                 raise ArgumentError, 'consistency invalid'
               end
             end
+
+            def constrained_value?(value)
+              return true if list.nil? && range.nil?
+              return list.include?(value) if list
+
+              range.has?(value)
+            end
           end
 
           class CReal < CInteger
@@ -138,11 +171,17 @@ module OpenEHR
               args[:type] = 'Real'
               super
             end
+
+            def valid_value?(value)
+              return false unless value.is_a?(Numeric)
+
+              constrained_value?(value)
+            end
           end
 
           module CDateModule
             attr_accessor :timezone_validity, :day_validity, :range, :list
-            attr_reader :month_validity, :day_validity, :range, :pattern
+            attr_reader :month_validity, :pattern
 
             def month_validity=(month_validity)
               if (month_validity == ValidityKind::OPTIONAL &&
@@ -163,6 +202,13 @@ module OpenEHR
               return !@range.nil?
             end
 
+            def valid_value?(value)
+              date = as_date(value)
+              return false if date.nil?
+
+              date_fields_valid?(date) && constrained_date?(date)
+            end
+
             protected
             def valid_pattern?(pattern)
               if /^([Yy?X]{4})(-([Mm?X]{2})(-([Dd?X]{2}))?)?$/ =~ pattern
@@ -172,9 +218,43 @@ module OpenEHR
               end
             end
 
+            def date_fields_valid?(date)
+              validity_satisfied?(month_validity, !date.month_unknown?) &&
+                validity_satisfied?(day_validity, !date.day_unknown?)
+            end
+
+            def validity_satisfied?(validity, field_present)
+              case validity
+              when ValidityKind::DISALLOWED then !field_present
+              when ValidityKind::MANDATORY then field_present
+              else
+                true
+              end
+            end
+
             private
             def consistency_validity(month_validity, day_validity)
             end
+
+            # A String value is parsed as a DV_DATE (matching the
+            # concrete type this codebase's range/list bounds actually
+            # use, so Comparable/Interval#has? compare like with like);
+            # a malformed string surfaces as ArgumentError, caught below.
+            def as_date(value)
+              return value if value.respond_to?(:month_unknown?)
+              return nil unless value.is_a?(String)
+
+              OpenEHR::RM::DataTypes::Quantity::DateTime::DvDate.new(:value => value)
+            rescue ArgumentError
+              nil
+            end
+
+            def constrained_date?(date)
+              return true if range.nil? && list.nil?
+              return list.any? { |item| as_date(item) == date } if list
+
+              range.has?(date)
+            end
           end
 
           class CDate < CPrimitive
@@ -212,7 +292,7 @@ module OpenEHR
           end
 
           module CTimeModule
-            attr_accessor :range, :list
+            attr_accessor :range, :list, :timezone_validity
             attr_reader :minute_validity, :second_validity,
                         :millisecond_validity, :pattern
             def pattern=(pattern)
@@ -247,6 +327,13 @@ module OpenEHR
               return !@range.nil?
             end
 
+            def valid_value?(value)
+              time = as_time(value)
+              return false if time.nil?
+
+              time_fields_valid?(time) && constrained_time?(time)
+            end
+
             protected
             def valid_pattern?(pattern)
               if /^([Hh?X]{2})(:([Mm?X]{2})(:([Ss?X]{2}))?)?$/ =~ pattern
@@ -255,6 +342,43 @@ module OpenEHR
                 false
               end
             end
+
+            def time_fields_valid?(time)
+              validity_satisfied?(minute_validity, !time.minute_unknown?) &&
+                validity_satisfied?(second_validity, !time.second_unknown?) &&
+                validity_satisfied?(millisecond_validity, time.has_fractional_second?)
+            end
+
+            def validity_satisfied?(validity, field_present)
+              case validity
+              when ValidityKind::DISALLOWED then !field_present
+              when ValidityKind::MANDATORY then field_present
+              else
+                true
+              end
+            end
+
+            private
+
+            # A String value is parsed as a DV_TIME (matching the
+            # concrete type this codebase's range/list bounds actually
+            # use, so Comparable/Interval#has? compare like with like);
+            # a malformed string surfaces as ArgumentError, caught below.
+            def as_time(value)
+              return value if value.respond_to?(:minute_unknown?)
+              return nil unless value.is_a?(String)
+
+              OpenEHR::RM::DataTypes::Quantity::DateTime::DvTime.new(:value => value)
+            rescue ArgumentError
+              nil
+            end
+
+            def constrained_time?(time)
+              return true if range.nil? && list.nil?
+              return list.any? { |item| as_time(item) == time } if list
+
+              range.has?(time)
+            end
           end
 
           class CTime < CPrimitive
@@ -286,9 +410,9 @@ module OpenEHR
               self.millisecond_validity = args[:millisecond_validity]
               self.second_validity = args[:second_validity]
               self.minute_validity = args[:minute_validity]
-              self.hour_validity = args[:hour_vaildity]
+              self.hour_validity = args[:hour_validity]
               self.day_validity = args[:day_validity]
-              self.month_validity = args[:day_validity]
+              self.month_validity = args[:month_validity]
             end
 
             def hour_validity=(hour_validity)
@@ -313,6 +437,15 @@ module OpenEHR
               @day_validity = day_validity
             end
 
+            def valid_value?(value)
+              datetime = as_datetime(value)
+              return false if datetime.nil?
+
+              date_fields_valid?(datetime) && time_fields_valid?(datetime) &&
+                validity_satisfied?(hour_validity, !datetime.hour_unknown?) &&
+                constrained_datetime?(datetime)
+            end
+
             protected
             def valid_pattern?(pattern)
               if /^([Yy?X]{4})(-([Mm?X]{2})(-([Dd?X]{2}))?)?[T ]?([Hh?X]{2})(:([Mm?X]{2})(:([Ss?X]{2}))?)?$/ =~ pattern
@@ -321,6 +454,28 @@ module OpenEHR
                 false
               end
             end
+
+            private
+
+            # A String value is parsed as a DV_DATE_TIME (matching the
+            # concrete type this codebase's range/list bounds actually
+            # use, so Comparable/Interval#has? compare like with like);
+            # a malformed string surfaces as ArgumentError, caught below.
+            def as_datetime(value)
+              return value if value.respond_to?(:hour_unknown?)
+              return nil unless value.is_a?(String)
+
+              OpenEHR::RM::DataTypes::Quantity::DateTime::DvDateTime.new(:value => value)
+            rescue ArgumentError
+              nil
+            end
+
+            def constrained_datetime?(datetime)
+              return true if range.nil? && list.nil?
+              return list.any? { |item| as_datetime(item) == datetime } if list
+
+              range.has?(datetime)
+            end
           end
 
           class CDuration < CPrimitive
@@ -335,6 +490,49 @@ module OpenEHR
               self.pattern = args[:pattern]
               self.list = args[:list]
               self.range = args[:range]
+              self.years_allowed = args[:years_allowed]
+              self.months_allowed = args[:months_allowed]
+              self.weeks_allowed = args[:weeks_allowed]
+              self.days_allowed = args[:days_allowed]
+              self.hours_allowed = args[:hours_allowed]
+              self.minutes_allowed = args[:minutes_allowed]
+              self.seconds_allowed = args[:seconds_allowed]
+              self.fractional_seconds_allowed = args[:fractional_seconds_allowed]
+            end
+
+            def valid_value?(value)
+              duration = as_duration(value)
+              return false if duration.nil?
+              return false unless fields_allowed?(duration)
+              return true if list.nil? && range.nil?
+              return list.any? { |item| as_duration(item).to_seconds == duration.to_seconds } if list
+
+              range.has?(duration)
+            end
+
+            private
+
+            # A String value is parsed as a DV_DURATION (matching the
+            # concrete type this codebase's range/list bounds actually
+            # use, so Comparable/Interval#has? compare like with like);
+            # a malformed string surfaces as ArgumentError, caught below.
+            def as_duration(value)
+              return value if value.respond_to?(:to_seconds)
+              return nil unless value.is_a?(String)
+
+              OpenEHR::RM::DataTypes::Quantity::DateTime::DvDuration.new(:value => value)
+            rescue ArgumentError
+              nil
+            end
+
+            def fields_allowed?(duration)
+              [[years_allowed, duration.years], [months_allowed, duration.months],
+               [weeks_allowed, duration.weeks], [days_allowed, duration.days],
+               [hours_allowed, duration.hours], [minutes_allowed, duration.minutes],
+               [seconds_allowed, duration.seconds],
+               [fractional_seconds_allowed, duration.fractional_second]].all? do |allowed, field|
+                allowed != false || field.nil?
+              end
             end
           end
         end # of Primitive