ruby-hl7 0.3 → 1.0

data/README.rdoc

@@ -0,0 +1,40 @@
+= Ruby HL7 Library README
+
+A simple way to parse and create HL7 2.x messages with Ruby.
+
+Examples can be found in HL7::Message.
+
+The version id can be found in the HL7::VERSION constant.
+
+* Git:          http://github.com/ruby-hl7/ruby-hl7.git
+* Docs:         http://ruby-hl7.rubyforge.org
+* Rubyforge:    http://rubyforge.org/projects/ruby-hl7
+
+Lists
+
+* Developers: mailto:ruby-hl7-devel@rubyforge.org
+* Users: mailto:ruby-hl7-users@rubyforge.org
+* Google group: http://groups.google.com/group/ruby-hl7
+
+Copyright (C) 2006-2010 Mark Guzman
+
+Maintained by the Collaborative Software Initiative
+
+* http://csinitiative.com
+* http://trisano.org
+* http://github.com/csinitiative/trisano
+
+== Download and Installation
+
+=== Rubygems
+Install the gem using the following command:
+
+  gem install ruby-hl7
+
+=== Bundler
+In your Gemfile:
+
+  gem 'ruby-hl7'
+
+== License
+See the LICENSE file.

data/lib/ruby-hl7.rb

@@ -1,18 +1,19 @@
+# encoding: UTF-8
 #= ruby-hl7.rb
 # Ruby HL7 is designed to provide a simple, easy to use library for
 # parsing and generating HL7 (2.x) messages.
 #
 #
-# Author:    Mark Guzman  (mailto:segfault@hasno.info)  
+# Author:    Mark Guzman  (mailto:segfault@hasno.info)
 #
-# Copyright: (c) 2006-2007 Mark Guzman  
+# Copyright: (c) 2006-2009 Mark Guzman
 #
-# License:   BSD  
+# License:   BSD
 #
 #  $Id$
-# 
+#
 # == License
-# see the LICENSE file 
+# see the LICENSE file
 #
 
 require 'rubygems'
@@ -20,7 +21,7 @@ require "stringio"
 require "date"
 
 module HL7 # :nodoc:
-  VERSION = "0.3" 
+  VERSION = "1.0"
   def self.ParserConfig
     @parser_cfg ||= { :empty_segment_is_error => true }
   end
@@ -45,32 +46,32 @@ end
 # Ruby Object representation of an hl7 2.x message
 # the message object is actually a "smart" collection of hl7 segments
 # == Examples
-# 
+#
 # ==== Creating a new HL7 message
-# 
+#
 #  # create a message
 #  msg = HL7::Message.new
-# 
+#
 #  # create a MSH segment for our new message
 #  msh = HL7::Message::Segment::MSH.new
 #  msh.recv_app = "ruby hl7"
 #  msh.recv_facility = "my office"
 #  msh.processing_id = rand(10000).to_s
-#  
+#
 #  msg << msh # add the MSH segment to the message
-#  
+#
 #  puts msg.to_s # readable version of the message
-# 
+#
 #  puts msg.to_hl7 # hl7 version of the message (as a string)
-# 
+#
 #  puts msg.to_mllp # mllp version of the message (as a string)
-# 
-# ==== Parse an existing HL7 message 
-# 
+#
+# ==== Parse an existing HL7 message
+#
 #  raw_input = open( "my_hl7_msg.txt" ).readlines
 #  msg = HL7::Message.new( raw_input )
-#  
-#  puts "message type: %s" % msg[:MSH].message_type 
+#
+#  puts "message type: %s" % msg[:MSH].message_type
 #
 #
 class HL7::Message
@@ -86,7 +87,7 @@ class HL7::Message
     @segments = []
     @segments_by_name = {}
     @item_delim = "^"
-    @element_delim = '|' 
+    @element_delim = '|'
     @segment_delim = "\r"
 
     parse( raw_msg ) if raw_msg
@@ -118,7 +119,7 @@ class HL7::Message
   # value:: an HL7::Message::Segment object
   def []=( index, value )
     unless ( value && value.kind_of?(HL7::Message::Segment) )
-      raise HL7::Exception.new( "attempting to assign something other than an HL7 Segment" ) 
+      raise HL7::Exception.new( "attempting to assign something other than an HL7 Segment" )
     end
 
     if index.kind_of?(Range) || index.kind_of?(Fixnum)
@@ -136,7 +137,7 @@ class HL7::Message
   # value:: is expected to be a string
   def index( value )
     return nil unless (value && value.respond_to?(:to_sym))
-    
+
     segs = @segments_by_name[ value.to_sym ]
     return nil unless segs
 
@@ -147,7 +148,7 @@ class HL7::Message
   # * will force auto set_id sequencing for segments containing set_id's
   def <<( value )
     unless ( value && value.kind_of?(HL7::Message::Segment) )
-      raise HL7::Exception.new( "attempting to append something other than an HL7 Segment" ) 
+      raise HL7::Exception.new( "attempting to append something other than an HL7 Segment" )
     end
 
     value.segment_parent = self unless value.segment_parent
@@ -157,12 +158,42 @@ class HL7::Message
     sequence_segments unless @parsing # let's auto-set the set-id as we go
   end
 
-  # parse a String or Enumerable object into an HL7::Message if possible
-  # * returns a new HL7::Message if successful
-  def self.parse( inobj )
-    HL7::Message.new do |msg| 
-      msg.parse( inobj ) 
-    end  
+  class << self
+    def parse_batch(batch) # :yields: message
+      raise HL7::ParseError, 'badly_formed_batch_message' unless
+        batch.hl7_batch?
+
+      # JRuby seems to change our literal \r characters in sample
+      # messages (from here documents) into newlines.  We make a copy
+      # here, reverting to carriage returns.  The input is unchanged.
+      #
+      # This does not occur when posts are received with CR
+      # characters, only in sample messages from here documents.  The
+      # expensive copy is only incurred when the batch message has a
+      # newline character in it.
+      batch = batch.gsub("\n", "\r") if batch.include?("\n")
+
+      raise HL7::ParseError, 'empty_batch_message' unless
+        match = /\rMSH/.match(batch)
+
+      match.post_match.split(/\rMSH/).each_with_index do |_msg, index|
+        if md = /\rBTS/.match(_msg)
+          # TODO: Validate the message count in the BTS segment
+          # should == index + 1
+          _msg = md.pre_match
+        end
+
+        yield 'MSH' + _msg
+      end
+    end
+
+    # parse a String or Enumerable object into an HL7::Message if possible
+    # * returns a new HL7::Message if successful
+    def parse( inobj )
+      HL7::Message.new do |msg|
+        msg.parse( inobj )
+      end
+    end
   end
 
   # parse the provided String or Enumerable object into this message
@@ -183,7 +214,7 @@ class HL7::Message
     return unless @segments
     @segments.each { |s| yield s }
   end
-  
+
   # return the segment count
   def length
     0 unless @segments
@@ -191,13 +222,13 @@ class HL7::Message
   end
 
   # provide a screen-readable version of the message
-  def to_s    
-    @segments.collect { |s| s if s.to_s.length > 0 }.join( "\n" )                               
+  def to_s
+    @segments.collect { |s| s if s.to_s.length > 0 }.join( "\n" )
   end
 
   # provide a HL7 spec version of the message
   def to_hl7
-    @segments.collect { |s| s if s.to_s.length > 0 }.join( @segment_delim ) 
+    @segments.collect { |s| s if s.to_s.length > 0 }.join( @segment_delim )
   end
 
   # provide the HL7 spec version of the message wrapped in MLLP
@@ -232,12 +263,12 @@ class HL7::Message
   def parse_element_delim(str)
     (str && str.kind_of?(String)) ? str.slice(3,1) : "|"
   end
-  
+
   # Get the item delimiter from an MSH segment
   def parse_item_delim(str)
     (str && str.kind_of?(String)) ? str.slice(4,1) : "^"
   end
-  
+
   def parse_enumerable( inary )
     #assumes an enumeration of strings....
     inary.each do |oary|
@@ -261,7 +292,7 @@ class HL7::Message
     @parsing = true
     last_seg = nil
     ary.each do |elm|
-      if elm.slice(0,3) == "MSH" 
+      if elm.slice(0,3) == "MSH"
         @item_delim = parse_item_delim(elm)
         @element_delim = parse_element_delim(elm)
       end
@@ -276,9 +307,11 @@ class HL7::Message
         raise HL7::ParseError.new if HL7.ParserConfig[:empty_segment_is_error] || false
         return nil
       end
-      
+
       seg_name = seg_parts[0]
-      if HL7::Message::Segment.constants.index(seg_name) # do we have an implementation?
+      if RUBY_VERSION < "1.9" && HL7::Message::Segment.constants.index(seg_name) # do we have an implementation?
+        kls = eval("HL7::Message::Segment::%s" % seg_name)
+      elsif RUBY_VERSION >= "1.9" && HL7::Message::Segment.constants.index(seg_name.to_sym)
         kls = eval("HL7::Message::Segment::%s" % seg_name)
       else
         # we don't have an implementation for this segment
@@ -287,13 +320,13 @@ class HL7::Message
       end
       new_seg = kls.new( elm, [@element_delim, @item_delim] )
       new_seg.segment_parent = self
-      
+
       if last_seg && last_seg.respond_to?(:children) && last_seg.accepts?( seg_name )
         last_seg.children << new_seg
         new_seg.is_child_segment = true
         return last_seg
       end
-        
+
       @segments << new_seg
 
       # we want to allow segment lookup by name
@@ -303,9 +336,9 @@ class HL7::Message
         @segments_by_name[ seg_sym ] << new_seg
       end
 
-      new_seg 
+      new_seg
   end
-end                
+end
 
 # Ruby Object representation of an hl7 2.x message segment
 # The segments can be setup to provide aliases to specific fields with
@@ -321,10 +354,10 @@ end
 #    add_field :block_example do |value|
 #      raise HL7::InvalidDataError.new unless value.to_i < 100 && value.to_i > 10
 #      return value
-#    end 
+#    end
 #    # this block will be executed when seg.block_example= is called
 #    # and when seg.block_example is called
-#      
+#
 class HL7::Message::Segment
   attr :segment_parent, true
   attr :element_delim
@@ -334,14 +367,14 @@ class HL7::Message::Segment
   # setup a new HL7::Message::Segment
   # raw_segment:: is an optional String or Array which will be used as the
   #               segment's field data
-  # delims:: an optional array of delimiters, where 
+  # delims:: an optional array of delimiters, where
   #               delims[0] = element delimiter
   #               delims[1] = item delimiter
   def initialize(raw_segment="", delims=[], &blk)
     @segments_by_name = {}
     @field_total = 0
     @is_child = false
-    
+
     @element_delim = (delims.kind_of?(Array) && delims.length>0) ? delims[0] : "|"
     @item_delim = (delims.kind_of?(Array) && delims.length>1) ? delims[1] : "^"
 
@@ -350,33 +383,41 @@ class HL7::Message::Segment
     else
       @elements = raw_segment.split( @element_delim, -1 )
       if raw_segment == ""
-        @elements[0] = self.class.to_s.split( "::" ).last 
+        @elements[0] = self.class.to_s.split( "::" ).last
         @elements << ""
       end
     end
 
     if block_given?
-      callctx = eval( "self", blk )
+      callctx = eval( "self", blk.binding )
       def callctx.__seg__(val=nil)
         @__seg_val__ ||= val
       end
       callctx.__seg__(self)
       # TODO: find out if this pollutes the calling namespace permanently...
-      
+
       to_do = <<-END
       def method_missing( sym, *args, &blk )
-        __seg__.send( sym, args, blk )  
+        __seg__.send( sym, args, blk )
       end
       END
 
-      eval( to_do, blk )
-      yield self 
-      eval( "undef method_missing", blk )
+      eval( to_do, blk.binding )
+      yield self
+      eval( "undef method_missing", blk.binding )
+    end
+  end
+
+  def self.add_child_type(child_type)
+    if @child_types
+      @child_types << child_type.to_sym
+    else
+      has_children [ child_type.to_sym ]
     end
   end
 
   def to_info
-    "%s: empty segment >> %s" % [ self.class.to_s, @elements.inspect ] 
+    "%s: empty segment >> %s" % [ self.class.to_s, @elements.inspect ]
   end
 
   # output the HL7 spec version of the segment
@@ -408,7 +449,7 @@ class HL7::Message::Segment
     else
 
       if args.length > 0
-        write_field( base_sym, args )
+        write_field( base_sym, args.flatten.select { |arg| arg } )
       else
         read_field( base_sym )
       end
@@ -417,7 +458,7 @@ class HL7::Message::Segment
   end
 
   # sort-compare two Segments, 0 indicates equality
-  def <=>( other ) 
+  def <=>( other )
     return nil unless other.kind_of?(HL7::Message::Segment)
 
     # per Comparable docs: http://www.ruby-doc.org/core/classes/Comparable.html
@@ -426,7 +467,7 @@ class HL7::Message::Segment
     return 1 if diff < 0
     return 0
   end
-  
+
   # get the defined sort-weight of this segment class
   # an alias for self.weight
   def weight
@@ -434,7 +475,7 @@ class HL7::Message::Segment
   end
 
 
-  # return true if the segment has a parent 
+  # return true if the segment has a parent
   def is_child_segment?
     (@is_child_segment ||= false)
   end
@@ -473,6 +514,7 @@ class HL7::Message::Segment
   end
 
 
+
   # allows a segment to store other segment objects
   # used to handle associated lists like one OBR to many OBX segments
   def self.has_children(child_types)
@@ -513,19 +555,19 @@ class HL7::Message::Segment
         t = t.to_sym if t && (t.to_s.length > 0) && t.respond_to?(:to_sym)
         child_types.index t
       end
-    end 
-  end 
+    end
+  end
 
-  # define a field alias 
+  # define a field alias
   # * name is the alias itself (required)
-  # * options is a hash of parameters 
+  # * options is a hash of parameters
   #   * :id is the field number to reference (optional, auto-increments from 1
   #      by default)
   #   * :blk is a validation proc (optional, overrides the second argument)
   # * blk is an optional validation proc which MUST take a parameter
   #   and always return a value for the field (it will be used on read/write
   #   calls)
-  def self.add_field( name, options={}, &blk ) 
+  def self.add_field( name, options={}, &blk )
     options = { :idx =>-1, :blk =>blk}.merge!( options )
     name ||= :id
     namesym = name.to_sym
@@ -534,10 +576,10 @@ class HL7::Message::Segment
       options[:idx] = @field_cnt # provide default auto-incrementing
     end
     @field_cnt = options[:idx].to_i + 1
-    
+
     singleton.module_eval do
       @fields ||= {}
-      @fields[ namesym ] = options  
+      @fields[ namesym ] = options
     end
 
     self.class_eval <<-END
@@ -551,7 +593,7 @@ class HL7::Message::Segment
       end
 
       def #{name}=(value)
-        write_field( :#{namesym}, value ) 
+        write_field( :#{namesym}, value )
       end
     END
   end
@@ -577,7 +619,7 @@ class HL7::Message::Segment
   def read_field( name ) #:nodoc:
     idx, field_blk = field_info( name )
     return nil unless idx
-    return nil if (idx >= @elements.length) 
+    return nil if (idx >= @elements.length)
 
     ret = @elements[ idx ]
     ret = ret.first if (ret.kind_of?(Array) && ret.length == 1)
@@ -596,6 +638,7 @@ class HL7::Message::Segment
       @elements += missing
     end
 
+    value = value.first if (value && value.kind_of?(Array) && value.length == 1)
     value = field_blk.call( value ) if field_blk
     @elements[ idx ] = value.to_s
   end
@@ -618,8 +661,8 @@ end
 #end
 
 # Provide a catch-all information preserving segment
-# * no aliases are not provided BUT you can use the numeric element accessor
-# 
+# * nb: aliases are not provided BUT you can use the numeric element accessor
+#
 #  seg = HL7::Message::Segment::Default.new
 #  seg.e0 = "NK1"
 #  seg.e1 = "SOMETHING ELSE"
@@ -628,7 +671,7 @@ end
 class HL7::Message::Segment::Default < HL7::Message::Segment
   def initialize(raw_segment="", delims=[])
     segs = [] if (raw_segment == "")
-    segs ||= raw_segment 
+    segs ||= raw_segment
     super( segs, delims )
   end
 end