yahl7 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ead354fddaf6834942e7a7e23d46a965adf5f318cb730278844fefb728ad0a16
-  data.tar.gz: c6d4c697c4d32e1128401d37024d6518a57b798cb6400b73c4ec730fbf0085f4
+  metadata.gz: 51918fd00971add5c38a8b7755cdc818743073aae001707d0950644abb9bae83
+  data.tar.gz: 39e37efdceacaf25896afba0ba836e7e2db148f4f15b833aea78251043292179
 SHA512:
-  metadata.gz: 3ff7e6dbfdc8b2a2c31c0025da6753c77a6b4c3dd400f57fd31010c6dca0439ecd17c3ad6e2c74140b3d16b970d9273f46d10efaa3c35204ef2b40b98765da71
-  data.tar.gz: f2c9a7572f48cfbc898ba902f3c0415b68a4d3509deb54b855856815bad69e6e33b3c3d41ec0b92d8d36f977d6429177d3ce6f16d3a970ff49e164dc0c4064ff
+  metadata.gz: eb3b7c2633e691d91f499adfae90aa91fc0e408a272eabf5abe7b551556defece6cc6c5d2205d1792f776efee20cebe959ffcde18edb28638d9567c8b7bd72be
+  data.tar.gz: a28b49feca05c217d0335431eb11a16417a63fe7f166eef146d1d89744f66f14e4f37e1d416b7704bc8be1a7c7f8c4c52e5aa67f86406cae89404396a05ad12c

data/CHANGELOG.md

@@ -5,6 +5,64 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.5.0] - 2021-09-02
+
+This release implements a lot of changes, new features, and bug fixes. These are
+largely due to testing the library with a larger set of HL7 messages of various
+versions (2.3 to 2.5).
+
+This should clean up a number of rough edges, but the gem should not be
+considered production-ready, yet.
+
+### Added
+
+- HL7 data types:
+  - `XCN` for extended composite names
+- The `CNN` data type now has a `#full_name` method to match `XPN` and `XCN`.
+- The `NDL` data type now has aliases to the name methods in order to match the
+  API of other name elements.
+- The segment type now overrides `#to_s`
+- The `ORU` message type now has an `#observations_and_notes` method, which
+  returns all `OBX` and `NTE` segments in order for that message. This is useful
+  for building a complete report of test results for applicable messages.
+- Utilize `FT` data type for `OBX.5` for now. This could be various data types,
+  so I will need to figure out a more appropriate way to handle this.
+
+### Changed
+
+- Field values are now normalized so that empty values are returned as `nil`
+  whether they are strings or class instances.
+- The `FT` data type can now handle repeated values.
+- The `XAD` data type can now handle repeated values.
+- The `XTN` data type can now handle repeated values.
+- Mapped the following fields to the `XCN` data type:
+  - `DG1.16`
+  - `EVN.5`
+  - `IN1.30`
+  - `OBR.10`
+  - `OBR.16`
+  - `OBR.28`
+  - `OBX.16`
+  - `ORC.10`
+  - `ORC.11`
+  - `ORC.12`
+  - `ORC.19`
+  - `PD1.4`
+  - `PV1.7`
+  - `PV1.8`
+  - `PV1.9`
+  - `PV1.17`
+  - `PV1.52`
+
+### Fixed
+
+- Messages now display body correctly.
+- The `NDL` data type did not play well with some implementations that do not
+  include all field values.
+- The `#suffixes` method in `YAHL7::V2::AliasPersonName` now deduplicates the
+  suffix entries (i.e., degree and suffix) so that names appear more natural if
+  the generating system uses the same item in both degree and suffix.
+
 ## [0.4.0] - 2021-09-01
 
 ### Added

data/ERRATA.md

@@ -14,3 +14,5 @@ Cannot handle character escape sequence              | Initial               | N
 Cannot handle multi-byte character escape sequence   | Initial               | N/A
 Cannot handle hexadecimal character escape sequence  | Initial               | N/A
 Cannot resolve timestamps to partial-second accuracy | Initial               | N/A
+Does not handle repeated fields in all cases         | Initial               | N/A
+OBX.5 is always parsed as formatted text             | 0.5.0                 | N/A

data/lib/yahl7/v2/alias_field_names.rb

@@ -22,17 +22,56 @@ module YAHL7
         base.extend(ClassMethods)
       end
 
+      def normalize_value(value)
+        value.nil? || value == '' ? nil : value
+      end
+
+      def make_field(klass, value)
+        value = normalize_value(value)
+        return nil if value.nil?
+
+        if klass.respond_to?(:repeated?) && klass.repeated?(value)
+          value.map { |v| new_class_value(klass, v) }
+        else
+          new_class_value(klass, value)
+        end
+      end
+
+      def new_class_value(klass, value)
+        case klass.name
+        when 'YAHL7::V2::DataType::FT' then klass.new(value, parse_options)
+        else klass.new(value)
+        end
+      end
+
       # This is the module that actually extends the segment.
       module ClassMethods
+        # This method is used to define the field name mappings for the data
+        # type / segment.
+        #
+        # It is possible to return a string, in which case you can use an
+        # integer value. If you want to return a specific data type, you must
+        # use a hash instead, in the form of (for example):
+        #
+        #     define_field_names({
+        #       some_field: 0,
+        #       some_other_field: { index: 1, class: YAHL7::V2::DataType::TS }
+        #     })
+        #
+        # This defines the method `some_field` which returns a string, while
+        # the other method `some_other_field` returns either a `nil` value or a
+        # `YAHL7::V2::DataType::TS` value.
+        #
+        # It is possible that the field is repeatable. If so, it is up to the
+        # data type to define a `::repeated?` method that receives the raw
+        # value and then it determines if the field was repeated or not. If it
+        # is repeatable and it is determined to be repeated, an array of that
+        # type is returned.
         def define_field_names(mappings)
           mappings.each do |name, mapping|
             case mapping
-            when Integer then define_method(name) { self[mapping] }
-            when Hash
-              define_method(name) do
-                value = self[mapping[:index]]
-                value.nil? || value == '' ? nil : mapping[:class].new(value)
-              end
+            when Integer then define_method(name) { normalize_value(self[mapping]) }
+            when Hash then define_method(name) { make_field(mapping[:class], self[mapping[:index]]) }
             end
           end
         end

data/lib/yahl7/v2/alias_person_name.rb

@@ -46,6 +46,8 @@ module YAHL7
       def suffixes
         [suffix, degree]
           .reject { |p| p.nil? || p == '' }
+          .map(&:strip)
+          .uniq
           .join(', ')
       end
 

data/lib/yahl7/v2/data_type/cnn.rb

@@ -23,6 +23,14 @@ module YAHL7
                              assigning_authority_universal_id: 9,
                              assigning_authority_universal_id_type: 10
                            })
+
+        def full_name
+          assemble_name_given_first
+        end
+
+        def self.repeated?(value)
+          !value.nil? && value[0].is_a?(Array)
+        end
       end
     end
   end

data/lib/yahl7/v2/data_type/ft.rb

@@ -7,10 +7,19 @@ module YAHL7
     class DataType
       # This is the HL7 data type for formatted text
       class FT < YAHL7::V2::DataType
+        def initialize(value, parse_options)
+          @value = value
+          @formatter = YAHL7::V2::Formatter.new(parse_options)
+        end
+
         def formatted
           @formatted ||= parse_value
         end
 
+        def self.repeated?(value)
+          value.is_a?(Array)
+        end
+
         private
 
         def parse_value
@@ -18,7 +27,7 @@ module YAHL7
         end
 
         def parse_body(body)
-          YAHL7::V2::Formatter.format(body)
+          @formatter.format(body)
         end
       end
     end

data/lib/yahl7/v2/data_type/ndl.rb

@@ -24,6 +24,32 @@ module YAHL7
                              building: 9,
                              floor: 10
                            })
+
+        def initialize(value)
+          @value = if value.nil?
+                     []
+                   elsif value.is_a?(String) || value[0].is_a?(String)
+                     [value]
+                   else
+                     value
+                   end
+        end
+
+        def full_name
+          name&.full_name
+        end
+
+        def bare_name_given_first
+          name&.bare_name_given_first
+        end
+
+        def bare_name_family_first
+          name&.bare_name_family_first
+        end
+
+        def self.repeated?(value)
+          !value.nil? && value[0].is_a?(Array) && value[0][0].is_a?(Array)
+        end
       end
     end
   end

data/lib/yahl7/v2/data_type/xad.rb

@@ -25,6 +25,10 @@ module YAHL7
                              effective_date: { index: 12, class: YAHL7::V2::DataType::TS },
                              expiration_date: { index: 13, class: YAHL7::V2::DataType::TS }
                            })
+
+        def self.repeated?(value)
+          !value.nil? && value[0].is_a?(Array)
+        end
       end
     end
   end

data/lib/yahl7/v2/data_type/xcn.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require 'date'
+
+module YAHL7
+  module V2
+    class DataType
+      # This is the HL7 data type for an extended composite name and ID number.
+      class XCN < YAHL7::V2::DataType
+        include YAHL7::V2::AliasPersonName
+        include YAHL7::V2::AliasFieldNames
+
+        define_field_names({
+                             id_number: 0,
+                             family_name: 1,
+                             given_name: 2,
+                             middle_name: 3,
+                             suffix: 4,
+                             prefix: 5,
+                             degree: 6,
+                             source_table: 7,
+                             assigning_authority: 8,
+                             name_type_code: 9,
+                             identifier_check_digit: 10,
+                             check_digit_scheme: 11,
+                             identifier_type_code: 12,
+                             assigning_facility: 13,
+                             name_representation_code: 14,
+                             name_context: 15,
+                             name_validity_range: 16,
+                             name_assembly_order: 17,
+                             effective_date: 18,
+                             expiration_date: { index: 19, class: YAHL7::V2::DataType::TS },
+                             professional_suffix: { index: 20, class: YAHL7::V2::DataType::TS },
+                             assigning_jurisdiction: 21,
+                             assigning_agency_or_department: 22
+                           })
+
+        def full_name
+          case name_assembly_order&.downcase
+          when 'f' then assemble_name_family_first
+          else assemble_name_given_first
+          end
+        end
+
+        def self.repeated?(value)
+          !value.nil? && value[0].is_a?(Array)
+        end
+      end
+    end
+  end
+end

data/lib/yahl7/v2/data_type/xtn.rb

@@ -23,6 +23,10 @@ module YAHL7
                              speed_dial_code: 10,
                              unformatted_telephone_number: 11
                            })
+
+        def self.repeated?(value)
+          !value.nil? && value[0].is_a?(Array)
+        end
       end
     end
   end

data/lib/yahl7/v2/message/oru.rb

@@ -5,6 +5,14 @@ module YAHL7
     class Message
       # ORU messages contain unsolicited observation results about a patient.
       class ORU < YAHL7::V2::Message
+        OBSERVATION_AND_NOTE_TYPES = %w[NTE OBX].freeze
+
+        # This method is used to return all NTE and OBX segments in their
+        # original order. This can be useful for building a report of test
+        # results in applicable messages.
+        def observations_and_notes
+          segments.filter { |s| OBSERVATION_AND_NOTE_TYPES.include?(s.type) }
+        end
       end
     end
   end

data/lib/yahl7/v2/message.rb

@@ -18,7 +18,7 @@ module YAHL7
       end
 
       def to_s
-        @to_s ||= segments.join(parse_options.segment_sep)
+        @to_s ||= segments.map(&:to_s).join(parse_options.segment_sep)
       end
 
       def [](index)

data/lib/yahl7/v2/segment/dg1.rb

@@ -23,7 +23,7 @@ module YAHL7
                              outlier_cost: 13,
                              grouper_version_and_type: 14,
                              diagnostic_priority: 15,
-                             diagnosing_clinician: 16,
+                             diagnosing_clinician: { index: 16, class: YAHL7::V2::DataType::XCN },
                              diagnosis_classification: 17,
                              confidential_indicator: 18,
                              attestation_datetime: { index: 19, class: YAHL7::V2::DataType::TS },

data/lib/yahl7/v2/segment/evn.rb

@@ -13,7 +13,7 @@ module YAHL7
                              recorded_datetime: { index: 2, class: YAHL7::V2::DataType::TS },
                              planned_event_datetime: { index: 3, class: YAHL7::V2::DataType::TS },
                              event_reason_code: 4,
-                             operator_id: 5,
+                             operator_id: { index: 5, class: YAHL7::V2::DataType::XCN },
                              event_occurred: { index: 6, class: YAHL7::V2::DataType::TS },
                              event_facility: 7
                            })

data/lib/yahl7/v2/segment/in1.rb

@@ -37,7 +37,7 @@ module YAHL7
                              release_information_code: 27,
                              preadmit_certification: 28,
                              verification_datetime: 29,
-                             verification_by: 30,
+                             verification_by: { index: 30, class: YAHL7::V2::DataType::XCN },
                              type_of_agreement_code: 31,
                              billing_status: 32,
                              lifetime_reserve_days: 33,

data/lib/yahl7/v2/segment/obr.rb

@@ -17,13 +17,13 @@ module YAHL7
                              observation_datetime: { index: 7, class: YAHL7::V2::DataType::TS },
                              observation_end_datetime: { index: 8, class: YAHL7::V2::DataType::TS },
                              collection_volume: 9,
-                             collector_identifier: 10,
+                             collector_identifier: { index: 10, class: YAHL7::V2::DataType::XCN },
                              specimen_action_code: 11,
                              danger_code: 12,
                              relevant_clinical_information: 13,
                              specimen_received_datetime: { index: 14, class: YAHL7::V2::DataType::TS },
                              specimen_source: 15,
-                             ordering_provider: 16,
+                             ordering_provider: { index: 16, class: YAHL7::V2::DataType::XCN },
                              order_callback_phone_number: { index: 17, class: YAHL7::V2::DataType::XTN },
                              placer_field1: 18,
                              placer_field2: 19,
@@ -35,7 +35,7 @@ module YAHL7
                              result_status: 25,
                              parent_result: 26,
                              quantity_timing: { index: 27, class: YAHL7::V2::DataType::TQ },
-                             result_copies_to: 28,
+                             result_copies_to: { index: 28, class: YAHL7::V2::DataType::XCN },
                              parent: 29,
                              transportation_mode: 30,
                              reason_for_study: 31,

data/lib/yahl7/v2/segment/obx.rb

@@ -12,8 +12,7 @@ module YAHL7
                              value_type: 2,
                              observation_identifier: 3,
                              observation_sub_id: 4,
-                             # Skip observation_value; the logic here is
-                             # somewhat complex
+                             observation_value: { index: 5, class: YAHL7::V2::DataType::FT },
                              units: 6,
                              reference_range: 7,
                              abnormal_flags: 8,
@@ -24,15 +23,11 @@ module YAHL7
                              user_defined_access_checks: 13,
                              observation_datetime: { index: 14, class: YAHL7::V2::DataType::TS },
                              producer_id: 15,
-                             responsible_observer: 16,
+                             responsible_observer: { index: 16, class: YAHL7::V2::DataType::XCN },
                              observation_method: 17,
                              equipment_instance_identifier: 18,
                              analysis_datetime: { index: 19, class: YAHL7::V2::DataType::TS }
                            })
-
-        def observation_value
-          self[5]
-        end
       end
     end
   end

data/lib/yahl7/v2/segment/orc.rb

@@ -17,16 +17,16 @@ module YAHL7
                              quantity_timing: { index: 7, class: YAHL7::V2::DataType::TQ },
                              parent_order: 8,
                              transaction_datetime: 9,
-                             entered_by: 10,
-                             verified_by: 11,
-                             ordering_provider: 12,
+                             entered_by: { index: 10, class: YAHL7::V2::DataType::XCN },
+                             verified_by: { index: 11, class: YAHL7::V2::DataType::XCN },
+                             ordering_provider: { index: 12, class: YAHL7::V2::DataType::XCN },
                              enterer_location: 13,
                              callback_phone_number: { index: 14, class: YAHL7::V2::DataType::XTN },
                              order_effective_datetime: { index: 15, class: YAHL7::V2::DataType::TS },
                              order_control_code_reason: 16,
                              entering_organization: 17,
                              entering_device: 18,
-                             action_by: 19,
+                             action_by: { index: 19, class: YAHL7::V2::DataType::XCN },
                              advanced_beneficiary_notice_code: 20,
                              ordering_facility_name: 21,
                              ordering_facility_address: { index: 22, class: YAHL7::V2::DataType::XAD },

data/lib/yahl7/v2/segment/pd1.rb

@@ -11,7 +11,7 @@ module YAHL7
                              living_dependency: 1,
                              living_arrangement: 2,
                              patient_primary_facility: 3,
-                             patient_primary_care_provider: 4,
+                             patient_primary_care_provider: { index: 4, class: YAHL7::V2::DataType::XCN },
                              student_indicator: 5,
                              handicap: 6,
                              living_will_code: 7,

data/lib/yahl7/v2/segment/pv1.rb

@@ -14,9 +14,9 @@ module YAHL7
                              admission_type: 4,
                              preadmit_number: 5,
                              prior_patient_location: 6,
-                             attending_doctor: 7,
-                             referring_doctor: 8,
-                             consulting_doctor: 9,
+                             attending_doctor: { index: 7, class: YAHL7::V2::DataType::XCN },
+                             referring_doctor: { index: 8, class: YAHL7::V2::DataType::XCN },
+                             consulting_doctor: { index: 9, class: YAHL7::V2::DataType::XCN },
                              hospital_service: 10,
                              temporary_location: 11,
                              preadmit_test_indicator: 12,
@@ -24,7 +24,7 @@ module YAHL7
                              admit_source: 14,
                              ambulatory_status: 15,
                              vip_indicator: 16,
-                             admitting_doctor: 17,
+                             admitting_doctor: { index: 17, class: YAHL7::V2::DataType::XCN },
                              patient_type: 18,
                              visit_number: 19,
                              financial_class: 20,
@@ -59,7 +59,7 @@ module YAHL7
                              total_payouts: 49,
                              alternate_visit_id: 50,
                              visit_indicator: 51,
-                             other_healthcare_provider: 52
+                             other_healthcare_provider: { index: 52, class: YAHL7::V2::DataType::XCN }
                            })
       end
     end

data/lib/yahl7/v2/segment.rb

@@ -16,16 +16,22 @@ module YAHL7
     # Subsequent data access will be cached, however, so the performance hit of
     # subsequent calls should be negligable.
     class Segment
-      attr_accessor :parts, :field_parser
+      attr_accessor :body, :parts, :field_parser, :parse_options
 
       def initialize(body, parse_options)
-        @parts = body.split(parse_options.repetition_sep)
+        @body = body
+        @parts = @body.split(parse_options.repetition_sep)
         @parsed = Array.new(@parts.count)
         @field_parser = FieldParser.new(parse_options)
+        @parse_options = parse_options
 
         return unless defined?(FIELD_MAPPING)
       end
 
+      def to_s
+        @body
+      end
+
       # This method allows users to use an index to get a field out of a segment
       # at a given position. This allows data to be fetched from segments like
       # arrays as shown below:

data/lib/yahl7/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module YAHL7
-  VERSION = '0.4.0'
+  VERSION = '0.5.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: yahl7
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Mylan Connolly
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2021-09-01 00:00:00.000000000 Z
+date: 2021-09-02 00:00:00.000000000 Z
 dependencies: []
 description: A simple HL7 parser that focuses on being robust and easy to use
 email:
@@ -46,6 +46,7 @@ files:
 - lib/yahl7/v2/data_type/tq.rb
 - lib/yahl7/v2/data_type/ts.rb
 - lib/yahl7/v2/data_type/xad.rb
+- lib/yahl7/v2/data_type/xcn.rb
 - lib/yahl7/v2/data_type/xpn.rb
 - lib/yahl7/v2/data_type/xtn.rb
 - lib/yahl7/v2/date_time.rb