fhirpath 0.2.0.pre4 → 0.2.0.pre5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: eacb9dc2934ca76d58acb3c6aab97acc1f2d602f436d28d1518a0ee26a25c14d
-  data.tar.gz: 7460ad33f47fd12408aaa905318285cec5e05f4db3503dcfd3ea4612c2d3ab53
+  metadata.gz: 85f3b8a5df3dbd8edd95959a40260bd4a12eeb03b09c862befacf50439ea95a1
+  data.tar.gz: 17a74859ea3503d853acac89bad663de21f3d14c0e5fa755b29c415adf063c16
 SHA512:
-  metadata.gz: 3e5de5efdbd7037022c0e36587dbebec79ab0406da23b76067b858d49f47b9edfecff975ef9e048fb19fd3455c1e2e704ad4491f77bffb47517abc46e3d5fc64
-  data.tar.gz: 5e7b7ec8152d3534464c70b739e025d63b06490f3c3fe8dcb16dc26017af0597d888243057de6600ac5a922eddda05035a7a5254773085a6d738ef339b65d494
+  metadata.gz: 02f4d65b6b8b760ac5e6583e093fa998508fbc623eb025453f9354b41de8a843e127c95863d9a3958dd7ca4301bc3253f5b926972e6eafcb66b48260d22a4df1
+  data.tar.gz: 1ad8cd8dfb6d77003b6d2dbf9528fac97a30434f8f74f8330faa9beed66c48b7881a6752a6b3b4b9e30d13798a83c9350f16e97ab5e4de27f87404e55d05e2d3

data/CHANGELOG.md

@@ -4,7 +4,7 @@ All notable changes to this project are documented here. The project is pre-1.0;
 
 ## [Unreleased]
 
-## [0.2.0.pre4] - 2026-09-07
+## [0.2.0.pre5] - 2026-09-07
 - Add the `aggregate()` function with `$this`, `$total`, and `$index` variables for general-purpose collection aggregation (issue #43). The function signature is `aggregate(expression, initial)` where the expression is evaluated per item with the accumulator as `$total`. Empty collections return the initial value (or empty if omitted). Closes issue #43.
 - Add keyword-named functions (`contains`, `in`) usable after member access (`Patient.name.contains('John')`) — the lexer previously classified these as binary operators only, preventing function-call syntax after `.` (issue #66). Also registers both as standard functions with arity 1.
 - Accept raw JSON strings in `FHIRPath.evaluate()` and `CompiledExpression#evaluate`: strings starting with `{` or `[` after optional whitespace are parsed via `JSON.parse` once per call; malformed JSON raises `JSONInputError` (code `:invalid_json`); `Hash`/`Array` inputs pass through unchanged; other strings remain singleton string values (issue #56).

data/README.md

@@ -42,8 +42,6 @@ documented limitations before using this implementation in production.
 
 ## Quick start
 
-## Quick start
-
 ```ruby
 require "fhirpath"
 
@@ -51,7 +49,7 @@ require "fhirpath"
 data = { items: [1, 2, 3, 4, 5] }
 FHIRPath.evaluate(data, "items.where($this > 3)")   # => [4, 5]
 
-# FHIR R4 model adapter
+# FHIR R4 model adapter — Ruby Hash
 observation = {
   "resourceType" => "Observation",
   "id" => "obs-1",
@@ -65,6 +63,25 @@ FHIRPath.evaluate(observation, "valueQuantity.value > 5.0", model: :r4)  # => [t
 FHIRPath.evaluate(observation, "valueQuantity.unit", model: :r4)         # => ["mmol/L"]
 FHIRPath.evaluate(observation, "code.coding.system", model: :r4)         # => ["http://loinc.org"]
 
+# Raw JSON string input — evaluate FHIR resources directly from HTTP responses
+patient_json = <<~JSON
+  {
+    "resourceType": "Patient",
+    "id": "pat-1",
+    "name": [{ "use": "official", "family": "Chalmers", "given": ["Peter", "James"] }],
+    "gender": "male",
+    "birthDate": "1974-12-25",
+    "address": [{ "use": "home", "city": "PleasantVille", "state": "Vic", "postalCode": "3999" }]
+  }
+JSON
+
+FHIRPath.evaluate(patient_json, "Patient.name.where(use='official').family", model: :r4)
+# => ["Chalmers"]
+FHIRPath.evaluate(patient_json, "Patient.birthDate", model: :r4)
+# => ["1974-12-25"]
+FHIRPath.evaluate(patient_json, "Patient.address.city", model: :r4)
+# => ["PleasantVille"]
+
 # Type filtering with ofType()
 bundle = {
   "resourceType" => "Bundle",
@@ -74,6 +91,13 @@ bundle = {
   ]
 }
 FHIRPath.evaluate(bundle, "entry.resource.ofType(Observation)", model: :r4)  # => [Observation resource]
+
+# Compiled expression reuse
+program = FHIRPath.compile("Patient.name.family")
+program.evaluate({ "resourceType" => "Patient", "name" => [{ "family" => "Lovelace" }] }).to_a
+# => ["Lovelace"]
+program.call(patient_json).to_a  # also accepts raw JSON strings
+# => ["Chalmers"]
 ```
 
 FHIR R4 JSON can be selected explicitly through the versioned provider. The

data/docs/api.md

@@ -65,6 +65,54 @@ Returns a `FHIRPath::Collection`. Empty results are collections with `empty? ==
 
 The `resource` argument may be an already-parsed Hash/Array (used directly, never re-serialized) or a raw JSON document String. Strings that open with `{` or `[` after leading whitespace are parsed with `JSON.parse` once per call; a malformed document raises `FHIRPath::JSONInputError` (code `:invalid_json`) with a generic public message that does not echo document contents, while `original_cause` retains the underlying `JSON::ParserError` for programmatic diagnostics. Any other String — plain text, JSON scalar text such as `"null"` or `"123"`, or a quoted JSON primitive like `"\"Ada\""` — keeps its pre-existing meaning as a singleton FHIRPath string value and is never parsed. Parsing builds a fresh structure per call; the caller's String and any Hash/Array resource are never mutated or frozen. `CompiledExpression#evaluate` and `#call` apply the same resource handling.
 
+**Resource input handling summary:**
+
+| Input type | Behavior |
+|------------|----------|
+| `Hash` / `Array` | Used directly (never re-serialized) |
+| String starting with `{` or `[` (after whitespace) | Parsed as JSON document via `JSON.parse` once per call; malformed JSON raises `JSONInputError` (code `invalid_json`) |
+| Any other String | Treated as a singleton FHIRPath string value (never parsed) |
+
+```ruby
+# Hash input — used directly
+FHIRPath.evaluate({ "resourceType" => "Patient" }, "Patient.id")
+
+# JSON object string — parsed as JSON document
+json = '{ "resourceType": "Patient", "id": "123" }'
+FHIRPath.evaluate(json, "Patient.id")  # => ["123"]
+
+# JSON array string — parsed as JSON document
+FHIRPath.evaluate('[1, 2, 3]', 'count()')  # => [3]
+
+# Whitespace before { or [ is ignored
+FHIRPath.evaluate("  \n{ \"resourceType\": \"Patient\" }", "Patient.id")
+
+# Plain string — NOT parsed, treated as FHIRPath string value
+FHIRPath.evaluate("just text", "$this")  # => ["just text"]
+
+# JSON scalar text — NOT parsed (not an object/array)
+FHIRPath.evaluate("123", "$this")        # => ["123"] (string, not number)
+FHIRPath.evaluate("true", "$this")       # => ["true"] (string, not Boolean)
+FHIRPath.evaluate("null", "$this")       # => ["null"] (string, not empty)
+
+# Quoted JSON primitive — NOT parsed
+FHIRPath.evaluate('"Ada"', "$this")      # => ["\"Ada\""] (string with quotes)
+```
+
+**Error handling:**
+
+```ruby
+# Malformed JSON raises structured JSONInputError
+begin
+  FHIRPath.evaluate('{ "resourceType": "Patient", invalid: }', "Patient.id")
+rescue FHIRPath::JSONInputError => e
+  e.code           # => :invalid_json
+  e.message        # => "resource string is not valid JSON" (no document contents)
+  e.to_h[:code]    # => :invalid_json
+  e.original_cause # => JSON::ParserError (for programmatic diagnostics)
+end
+```
+
 `variables:` supplies external constants using either String or Symbol keys:
 
 ```ruby

data/lib/fhirpath/version.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module FHIRPath
-  VERSION = '0.2.0.pre4'
+  VERSION = '0.2.0.pre5'
   # 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,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: fhirpath
 version: !ruby/object:Gem::Version
-  version: 0.2.0.pre4
+  version: 0.2.0.pre5
 platform: ruby
 authors:
 - Nicco Reyes