fhirpath 0.2.0.pre1 → 0.2.0.pre2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '0759fa82ecea31aef7e8fb5ffc0c8a1fc023d834ffe49eb296d706bf42ff7ed8'
-  data.tar.gz: 0156774a1f73b8099001478f57704e8ee969738454f1019a09d398b9420aa64d
+  metadata.gz: 214b8bf3637ea378e16e6a60c8427b8ef7ba6e6fa25a8c9612d43ee4b4e710aa
+  data.tar.gz: e581ba72d78a0c59a90eac7c882ec1f2e1069415022ce029529e643c3158ecbb
 SHA512:
-  metadata.gz: 0cd68f2b5a80fd409a066965422a067d1a0664a2bd6c65c215b82c19655a8064ec4da47a54bc4b6767d0f65f7f38ee997815d63796a9097d43df3efcfe6ad448
-  data.tar.gz: 42a9413ad029f7a5e77bbfd2e796db4d37debd2152f3f9f1c3e28d4a74100027ef56abb6a63cd2a8bc383c83519546f6d18949f8db38a3dccf73d43aa7b4747b
+  metadata.gz: 29028eef4e40be4d55d69c5bebd874ae19cf606cef528d34296dc84960e00c5e5e99fa06ff8ebe2196250f857499d817511fcca71df70518dfbb06026721714b
+  data.tar.gz: 26e1734ac098eeaf716bca1955993da406b06652bf1ccf0b238e17d7ff8a015b2cd23b6bfbaf69dc420ca5c6663e8c055c47998676bf66bca014f2b8dce25952

data/CHANGELOG.md

@@ -4,6 +4,41 @@ All notable changes to this project are documented here. The project is pre-1.0;
 
 ## [Unreleased]
 
+## [0.2.0.pre2] - 2026-09-06
+- Add the `ofType()` function to the standard registry. Filters the receiver
+  collection to items whose runtime type matches the specified type identifier
+  (e.g., `Integer`, `String`, `Decimal`, `Boolean`, `Date`, `DateTime`, `Time`),
+  or whose recorded model type matches an FHIR resource type (e.g.,
+  `Observation`, `Patient`). The new function is implemented against the
+  receiver's parallel `types` array (set during navigation via the
+  `ModelProvider#type_of` hook), so it works on both bare values and resources
+  produced by the FHIR R4 adapter. Closes part of issue #13.
+- Record the model-resolved resource type on every navigation result so the
+  R4 adapter can be filtered by `ofType(ResourceName)` (e.g., filtering a
+  Bundle's `entry.resource` collection to `Observation` only). Previously the
+  evaluator recorded the choice-variant logical type only; the new fallback
+  covers non-choice properties and the resource's own `resourceType`.
+- Add FHIRPath Date/Time/DateTime value types and temporal operations:
+  - Lexer supports the `@YYYY-MM-DD`, `@THH:MM:SS`, `@YYYY-MM-DDTHH:MM:SSZ`,
+    and `@YYYY-MM-DDTHH:MM:SS±HH:MM` temporal-literal syntax.
+  - Nullary functions: `today()` → Date, `now()` → DateTime, `time()` → Time.
+  - Component extractors on singletons: `year()`, `month()`, `day()`,
+    `hour()`, `minute()`, `second()`, `millisecond()`. `millisecond()` on
+    `DateTime` reads `sec_fraction * 1000` (the only fractional-precision
+    path Ruby exposes for DateTime).
+  - Timezone functions: `timezone()` returns the formatted offset string
+    (e.g., `+05:30`); `timezoneOffset()` returns the offset in minutes.
+  - Same-type temporal comparisons via `<`, `<=`, `=`, `>=`, `>` (date/date,
+    datetime/datetime, time/time only — cross-type compares raise
+    `incompatible_comparison`).
+  - `ofType(Date|DateTime|Time)` filtering.
+  - 26 new tests across literals, now/today/time, components, comparison,
+    ofType, and edge cases (empty input, singleton requirement). All pass.
+- Add FHIR primitive-extension accessors (`._<name>`) per FHIRPath 2.0.0
+  spec. `<primitive>._<name>` returns the underlying `{value, extension}`
+  JSON container when the source primitive has a `value`, and empty when
+  only an extension is present. 4 new tests added. Closes part of issue #45.
+
 ## [0.2.0.pre1] - 2026-09-05
 - Add the `sum()`, `avg()`, `max()`, and `min()` aggregate functions to the
   standard registry. These are FHIRPath 3.0.0 STU3 aggregate additions

data/docs/feature-matrix.md

@@ -1,6 +1,6 @@
 # Feature and capability matrix
 
-Status: `0.2.0.pre1`; target release: FHIRPath `2.0.0`; publication contract: [`support-matrix.md`](support-matrix.md)
+Status: `0.2.0.pre2`; target release: FHIRPath `2.0.0`; publication contract: [`support-matrix.md`](support-matrix.md)
 
 This matrix is deliberately conservative. `Supported` means the behavior is exercised by the Ruby test suite or the checked-in vector corpus. `Deferred` means callers should expect a structured unsupported/unknown error. `Host-dependent` requires an adapter or injected service that is not shipped here.
 
@@ -32,7 +32,14 @@ This matrix is deliberately conservative. `Supported` means the behavior is exer
 | Custom registered functions | Supported | API/foundation tests |
 | Compiled-expression reuse | Supported | API/foundation tests |
 | Stable structured engine errors | Supported | API/foundation/parser tests |
-| Date/time literals and values | Deferred | no temporal value implementation |
+| `ofType()` type filter | Supported | `test/oftype_test.rb`; filters collections by built-in (`Integer`, `String`, `Decimal`, `Boolean`, `Date`, `DateTime`, `Time`) and FHIR resource types recorded during navigation; logical-type `is`/`as` previously deferred this slice |
+| Date/Time/DateTime literals (`@...`) | Supported | `test/temporal_literals_test.rb`; ISO 8601 with optional timezone (`Z`/`±HH:MM`) |
+| `today()`, `now()`, `time()` | Supported | `test/temporal_now_test.rb` |
+| Temporal component extractors (`year`, `month`, `day`, `hour`, `minute`, `second`, `millisecond`) | Supported | `test/temporal_components_test.rb`; `millisecond()` on `DateTime` reads `sec_fraction * 1000` |
+| Temporal timezone (`timezone()`, `timezoneOffset()`) | Supported | `test/temporal_components_test.rb` |
+| Temporal same-type comparison | Supported | `test/temporal_comparison_test.rb`; cross-type raises `incompatible_comparison` |
+| Temporal arithmetic with Quantity/Duration | Deferred | no Quantity type yet |
+| FHIR primitive extension accessor (`._<name>`) | Supported | `test/primitive_extensions_test.rb`; returns the underlying `{value, extension}` container or empty per FHIRPath 2.0.0 |
 | Quantity/UCUM | Deferred | no unit service or quantity implementation |
 | Advanced conversion/math/string/regex | Deferred | not in standard registry |
 | FHIR R4 model adapter (`model: :r4`) | Supported | `test/r4_model_test.rb`; dependency-free `FHIRPath::FHIR::R4::ModelProvider` |

data/docs/support-matrix.md

@@ -1,6 +1,6 @@
 # Release support matrix
 
-Status: `pre-release` (`0.2.0.pre1`)
+Status: `pre-release` (`0.2.0.pre2`)
 
 This is the release-facing support matrix. It is deliberately narrower than
 "FHIRPath-compatible": every supported claim must have executable evidence, and
@@ -38,7 +38,10 @@ These stable identifiers describe the behavior included in the current package:
 - `comparison-and-equivalence` — relational comparison, equality, and equivalence;
 - `boolean-logic` — empty-aware Boolean operators;
 - `union-membership-and-type-operators` — union, `in`, `contains`, `is`, and `as`;
-- `collection-functions` — `where`, `select`, `first`, `exists`, `count`, `empty`, `not`, `all`, and Boolean aggregates;
+- `collection-functions` — `where`, `select`, `first`, `exists`, `count`, `empty`, `not`, `all`, Boolean aggregates, and `ofType`;
+- `subsetting-functions` — `tail`, `take`, `skip`, `last`;
+- `temporal-types` — `Date`, `DateTime`, `Time` literals (`@YYYY-MM-DD`, `@THH:MM:SS`, `@YYYY-MM-DDTHH:MM:SS±HH:MM`), `today()`, `now()`, `time()`, component extractors (`year`, `month`, `day`, `hour`, `minute`, `second`, `millisecond`), `timezone()`, `timezoneOffset()`, and same-type comparison;
+- `fhir-primitive-extensions` — `._<name>` accessor returning the underlying `{value, extension}` container or empty per FHIRPath 2.0.0;
 - `focus-variables` — `$this`, `$index`, and `$total`;
 - `external-constants` — explicitly supplied `%name` values;
 - `custom-functions` — explicitly registered functions;

data/lib/fhirpath/evaluator.rb

@@ -100,10 +100,21 @@ module FHIRPath
 
     def navigate(node, context)
       receiver = evaluate(node.receiver, context)
+      return navigate_primitive_extension(receiver, node) if node.name.start_with?('_')
+
       values = []
       model_types = []
       receiver.items.each do |item|
-        append_property(values, model_types, item, node.name, context)
+        produced = Collection.from(context.model.property(item, node.name)).items
+        type = context.model.property_logical_type(item, node.name)
+        values.concat(produced)
+        model_types.concat(Array.new(produced.length, type))
+        # If no choice type was recorded, try to get the resource type from the model
+        next unless type.nil? && context.model.respond_to?(:type_of)
+
+        produced.each do |produced_item|
+          model_types[-produced.length + produced.index(produced_item)] = context.model.type_of(produced_item)
+        end
       end
       Collection.new(values, types: model_types)
     rescue NoMethodError => e
@@ -111,6 +122,16 @@ module FHIRPath
                                                        span: node.span, cause: e)
     end
 
+    # Handle the FHIR primitive-extension accessor (`_<name>`) on a primitive
+    # JSON element that is split into `{ value, extension }` per the FHIR spec.
+    # Per FHIRPath 2.0.0, `<primitive>._<name>` returns the underlying primitive
+    # container (the `{value, extension}` shape) when the source element already
+    # has a value, and empty when the primitive has only an extension.
+    def navigate_primitive_extension(receiver, _node)
+      values = receiver.items.select { |item| item.is_a?(Hash) && (item.key?('value') || item.key?(:value)) }
+      Collection.new(values)
+    end
+
     # Resolves one property and records, per produced item, the logical type
     # name the model declares for the resolved value (nil when the model has no
     # metadata for this property, e.g. PlainModel or a non-choice field).
@@ -192,6 +213,18 @@ module FHIRPath
         all(receiver, node.arguments.first, context)
       when 'allTrue', 'anyTrue', 'allFalse', 'anyFalse'
         boolean_aggregate(receiver, node.name, node)
+      when 'ofType'
+        of_type(receiver, node, context)
+      when 'today'
+        temporal_now(receiver, node, context, :date)
+      when 'now'
+        temporal_now(receiver, node, context, :datetime)
+      when 'time'
+        temporal_now(receiver, node, context, :time)
+      when 'year', 'month', 'day', 'hour', 'minute', 'second', 'millisecond'
+        temporal_component(receiver, node, context, node.name)
+      when 'timezone', 'timezoneOffset'
+        temporal_timezone(receiver, node, context, node.name)
       else
         invoke_registered(node, receiver, context, spec)
       end
@@ -562,6 +595,101 @@ module FHIRPath
       Collection.new([left.items.any? { |candidate| equal?(candidate, value) }])
     end
 
+    def of_type(receiver, node, _context)
+      # FHIRPath ofType() filters the collection to items matching the specified type
+      # The argument is a type identifier (e.g., Integer, String, Decimal, Boolean,
+      # or FHIR resource types like Observation, Patient)
+      type_arg = node.arguments.first
+      unless type_arg.is_a?(AST::Identifier)
+        raise TypeError.new('ofType requires a type identifier', code: :expected_type, span: type_arg.span)
+      end
+
+      type_name = type_arg.name.downcase
+
+      # Use the receiver's recorded types (parallel to items) for model types,
+      # fall back to logical_type? for built-in types
+      matching_items = receiver.items.each_with_index.select do |item, index|
+        item_type = receiver.types&.at(index)
+        (item_type && item_type.downcase == type_name) || logical_type?(item, type_name)
+      end.map(&:first)
+      Collection.new(matching_items)
+    end
+
+    def temporal_now(receiver, _node, _context, type)
+      return Collection.empty if receiver.empty?
+
+      # today(), now(), time() are nullary functions - receiver is ignored
+      case type
+      when :date
+        Collection.new([Date.today])
+      when :datetime
+        Collection.new([DateTime.now])
+      when :time
+        Collection.new([Time.now])
+      end
+    end
+
+    def temporal_component(receiver, node, _context, component)
+      return Collection.empty if receiver.empty?
+
+      value = require_singleton(receiver, node.span)
+      result = case component
+               when 'year'
+                 value.respond_to?(:year) ? value.year : nil
+               when 'month'
+                 value.respond_to?(:month) ? value.month : nil
+               when 'day'
+                 value.respond_to?(:day) ? value.day : nil
+               when 'hour'
+                 value.respond_to?(:hour) ? value.hour : nil
+               when 'minute'
+                 value.respond_to?(:min) ? value.min : nil
+               when 'second'
+                 value.respond_to?(:sec) ? value.sec : nil
+               when 'millisecond'
+                 if value.is_a?(DateTime)
+                   # DateTime stores fractional seconds as a Rational
+                   (value.sec_fraction * 1000).to_i
+                 elsif value.respond_to?(:msec)
+                   value.msec
+                 elsif value.respond_to?(:nsec)
+                   (value.nsec / 1_000_000).to_i
+                 end
+               end
+      if result.nil?
+        raise TypeError.new("temporal component #{component} not supported on #{value.class}",
+                            code: :unsupported_temporal, span: node.span)
+      end
+
+      Collection.new([result])
+    end
+
+    def temporal_timezone(receiver, node, _context, component)
+      return Collection.empty if receiver.empty?
+
+      value = require_singleton(receiver, node.span)
+      unless value.respond_to?(:zone) || value.respond_to?(:offset)
+        raise TypeError.new("timezone not supported on #{value.class}", code: :unsupported_temporal, span: node.span)
+      end
+
+      result = if component == 'timezone'
+                 value.respond_to?(:zone) ? value.zone : format_offset(value.offset)
+               else
+                 # timezoneOffset returns minutes
+                 value.respond_to?(:offset) ? (value.offset * 24 * 60).to_i : nil
+               end
+      Collection.new([result])
+    end
+
+    def format_offset(offset)
+      return '+00:00' if offset.nil? || offset.zero?
+
+      hours = (offset * 24).to_i
+      minutes = ((offset * 24 * 60) % 60).to_i
+      sign = hours >= 0 ? '+' : '-'
+      format('%s%02d:%02d', sign, hours.abs, minutes.abs)
+    end
+
     def type_operator(node, context)
       left = evaluate(node.left, context)
       type_name = type_name_from(node.right, node.span)
@@ -597,6 +725,9 @@ module FHIRPath
       when 'decimal' then value.is_a?(BigDecimal) || (value.is_a?(::Float) && value.finite?)
       when 'number' then numeric?(value)
       when 'string' then value.is_a?(::String)
+      when 'date' then value.is_a?(Date)
+      when 'datetime' then value.is_a?(DateTime)
+      when 'time' then value.is_a?(Time)
       else false
       end
     end
@@ -604,7 +735,10 @@ module FHIRPath
     def compare_values(left, right, span)
       if numeric?(left) && numeric?(right)
         decimal(left) <=> decimal(right)
-      elsif left.is_a?(::String) && right.is_a?(::String)
+      elsif (left.is_a?(::String) && right.is_a?(::String)) ||
+            (left.is_a?(Date) && right.is_a?(Date)) ||
+            (left.is_a?(DateTime) && right.is_a?(DateTime)) ||
+            (left.is_a?(Time) && right.is_a?(Time))
         left <=> right
       else
         raise TypeError.new('comparison requires compatible values', code: :incompatible_comparison,

data/lib/fhirpath/functions.rb

@@ -13,10 +13,13 @@ module FHIRPath
 
   class FunctionRegistry
     STANDARD_NAMES = %w[
-      where select first last tail take skip
+      where select first last tail take skip ofType
       exists count empty not all
       allTrue anyTrue allFalse anyFalse
       sum avg max min
+      today now time
+      year month day hour minute second millisecond
+      timezone timezoneOffset
     ].freeze
     DELAYED_NAMES = %w[where select exists all].freeze
 
@@ -38,7 +41,7 @@ module FHIRPath
 
     def self.standard_arity(name)
       return 0..1 if name == 'exists'
-      return 1 if name == 'all' || %w[where select take skip].include?(name)
+      return 1 if name == 'all' || %w[where select take skip ofType].include?(name)
 
       0
     end

data/lib/fhirpath/parser.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 require 'bigdecimal'
+require 'date'
+require 'time'
 
 module FHIRPath
   class Token
@@ -22,7 +24,8 @@ module FHIRPath
       '=' => :equals, '+' => :plus, '-' => :minus,
       '*' => :multiply, '/' => :divide,
       '<' => :less_than, '>' => :greater_than,
-      '|' => :union, '&' => :concatenate, '~' => :equivalent
+      '|' => :union, '&' => :concatenate, '~' => :equivalent,
+      '@' => :temporal
     }.freeze
 
     TWO_CHARACTER = {
@@ -85,6 +88,8 @@ module FHIRPath
 
       char = @source[@index]
       if SINGLE.key?(char)
+        return temporal_token(start) if char == '@'
+
         @index += 1
         return token(SINGLE.fetch(char), char, start)
       end
@@ -210,6 +215,98 @@ module FHIRPath
       token(:identifier, text, start)
     end
 
+    def temporal_token(start)
+      @index += 1 # skip '@'
+      temporal_start = @index
+
+      has_date = parse_date_part?
+      has_time = parse_time_part?
+      parse_timezone_part
+
+      text = @source[temporal_start...@index]
+      raise_error('empty temporal literal', start) if text.empty?
+
+      value, type = parse_temporal_value(text, has_date, has_time)
+      token(type, value, start)
+    rescue ArgumentError => e
+      raise_error("invalid temporal literal: #{e.message}", start, code: :invalid_temporal)
+    end
+
+    def parse_date_part?
+      return false if eof? || !@source[@index].match?(/[0-9]/)
+
+      @index += 4 # YYYY
+      return false if eof? || @source[@index] != '-'
+
+      @index += 1
+      @index += 2 # MM
+      return false if eof? || @source[@index] != '-'
+
+      @index += 1
+      @index += 2 # DD
+      true
+    end
+
+    def parse_time_part?
+      return false if eof? || @source[@index] != 'T'
+
+      @index += 1
+      return false if eof? || !@source[@index, 2].match?(/^\d{2}$/)
+
+      @index += 2 # HH
+      return false if eof? || @source[@index] != ':'
+
+      @index += 1
+      return false if eof? || !@source[@index, 2].match?(/^\d{2}$/)
+
+      @index += 2 # MM
+      return false if eof? || @source[@index] != ':'
+
+      @index += 1
+      return false if eof? || !@source[@index, 2].match?(/^\d{2}$/)
+
+      @index += 2 # SS
+
+      # Optional milliseconds
+      if !eof? && @source[@index] == '.'
+        @index += 1
+        @index += 1 while !eof? && @source[@index].match?(/[0-9]/)
+      end
+      true
+    end
+
+    def parse_timezone_part
+      return if eof? || !@source[@index].match?(/[Z+-]/)
+
+      if @source[@index] == 'Z'
+        @index += 1
+      else
+        @index += 1 # + or -
+        @index += 2 # HH
+        @index += 1 if !eof? && @source[@index] == ':'
+        @index += 2
+      end
+    end
+
+    def parse_temporal_value(text, has_date, has_time)
+      if has_date && has_time
+        [DateTime.parse(text), :datetime]
+      elsif has_date
+        [Date.parse(text), :date]
+      elsif has_time
+        time_text = text
+        time_text = time_text[1..] if time_text.start_with?('T')
+        value = if time_text.include?('Z') || time_text.match?(/[+-]\d{2}:?\d{2}$/)
+                  DateTime.parse("2000-01-01T#{time_text}").to_time
+                else
+                  Time.parse("2000-01-01T#{time_text}")
+                end
+        [value, :time]
+      else
+        raise ArgumentError, 'invalid temporal literal'
+      end
+    end
+
     def token(type, value, start)
       Token.new(type: type, value: value,
                 span: SourceSpan.new(offset: start, length: @index - start))
@@ -341,7 +438,7 @@ module FHIRPath
     def parse_primary
       token = advance
       node = case token.type
-             when :string, :integer, :decimal
+             when :string, :integer, :decimal, :date, :time, :datetime
                AST::Literal.new(value: token.value, span: token.span)
              when :identifier
                if %w[true false].include?(token.value)

data/lib/fhirpath/version.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module FHIRPath
-  VERSION = '0.2.0.pre1'
+  VERSION = '0.2.0.pre2'
   # A stable release requires the complete release gate to be deliberately
   # promoted. Keep pre-release status explicit while the shared-suite and
   # model-adapter work remains incomplete.

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: fhirpath
 version: !ruby/object:Gem::Version
-  version: 0.2.0.pre1
+  version: 0.2.0.pre2
 platform: ruby
 authors:
 - Nicco Reyes
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-05 00:00:00.000000000 Z
+date: 2026-09-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bigdecimal