rtp-connect 1.6 → 1.11

data/lib/rtp-connect/prescription.rb

@@ -9,7 +9,7 @@ module RTP
   class Prescription < Record
 
     # The Record which this instance belongs to.
-    attr_reader :parent
+    attr_accessor :parent
     # The SiteSetup record (if any) that belongs to this Prescription.
     attr_reader :site_setup
     # An array of SimulationField records (if any) that belongs to this Prescription.
@@ -36,28 +36,8 @@ module RTP
     # @raise [ArgumentError] if given a string containing an invalid number of elements
     #
     def self.load(string, parent)
-      # Get the quote-less values:
-      values = string.to_s.values
-      low_limit = 4
-      high_limit = 13
-      raise ArgumentError, "Invalid argument 'string': Expected at least #{low_limit} elements, got #{values.length}." if values.length < low_limit
-      RTP.logger.warn "The number of elements (#{values.length}) for this Prescription record exceeds the known number of data items for this record (#{high_limit}). This may indicate an invalid record or that the RTP format has recently been expanded with new items." if values.length > high_limit
       p = self.new(parent)
-      # Assign the values to attributes:
-      p.keyword = values[0]
-      p.course_id = values[1]
-      p.rx_site_name = values[2]
-      p.technique = values[3]
-      p.modality = values[4]
-      p.dose_spec = values[5]
-      p.rx_depth = values[6]
-      p.dose_ttl = values[7]
-      p.dose_tx = values[8]
-      p.pattern = values[9]
-      p.rx_note = values[10]
-      p.number_of_fields = values[11]
-      p.crc = values[-1]
-      return p
+      p.load(string)
     end
 
     # Creates a new Prescription site.
@@ -65,6 +45,7 @@ module RTP
     # @param [Record] parent a record which is used to determine the proper parent of this instance
     #
     def initialize(parent)
+      super('RX_DEF', 4, 13)
       # Child objects:
       @site_setup = nil
       @fields = Array.new
@@ -72,7 +53,22 @@ module RTP
       # Parent relation (may get more than one type of record here):
       @parent = get_parent(parent.to_record, Plan)
       @parent.add_prescription(self)
-      @keyword = 'RX_DEF'
+      @attributes = [
+        # Required:
+        :keyword,
+        :course_id,
+        :rx_site_name,
+        # Optional:
+        :technique,
+        :modality,
+        :dose_spec,
+        :rx_depth,
+        :dose_ttl,
+        :dose_tx,
+        :pattern,
+        :rx_note,
+        :number_of_fields
+      ]
     end
 
     # Checks for equality.
@@ -97,6 +93,7 @@ module RTP
     #
     def add_field(child)
       @fields << child.to_field
+      child.parent = self
     end
 
     # Adds a simulation field record to this instance.
@@ -105,6 +102,7 @@ module RTP
     #
     def add_simulation_field(child)
       @simulation_fields << child.to_simulation_field
+      child.parent = self
     end
 
     # Adds a site setup record to this instance.
@@ -113,6 +111,7 @@ module RTP
     #
     def add_site_setup(child)
       @site_setup = child.to_site_setup
+      child.parent = self
     end
 
     # Collects the child records of this instance in a properly sorted array.
@@ -123,73 +122,57 @@ module RTP
       return [@site_setup, @simulation_fields, @fields].flatten.compact
     end
 
-    # Computes a hash code for this object.
+    # Removes the reference of the given instance from this instance.
     #
-    # @note Two objects with the same attributes will have the same hash code.
+    # @param [Field, SimulationField, SiteSetup] record a child record to be removed from this instance
     #
-    # @return [Fixnum] the object's hash code
-    #
-    def hash
-      state.hash
+    def delete(record)
+      case record
+      when Field
+        delete_child(:fields, record)
+      when SimulationField
+        delete_child(:simulation_fields, record)
+      when SiteSetup
+        delete_site_setup
+      else
+        logger.warn("Unknown class (record) given to Prescription#delete: #{record.class}")
+      end
     end
 
-    # Collects the values (attributes) of this instance.
-    #
-    # @note The CRC is not considered part of the actual values and is excluded.
-    # @return [Array<String>] an array of attributes (in the same order as they appear in the RTP string)
-    #
-    def values
-      return [
-        @keyword,
-        @course_id,
-        @rx_site_name,
-        @technique,
-        @modality,
-        @dose_spec,
-        @rx_depth,
-        @dose_ttl,
-        @dose_tx,
-        @pattern,
-        @rx_note,
-        @number_of_fields
-      ]
+    # Removes all field references from this instance.
+    #
+    def delete_fields
+      delete_children(:fields)
     end
 
-    # Returns self.
+    # Removes all simulation_field references from this instance.
     #
-    # @return [Prescription] self
+    def delete_simulation_fields
+      delete_children(:simulation_fields)
+    end
+
+    # Removes the site setup reference from this instance.
     #
-    def to_prescription
-      self
+    def delete_site_setup
+      delete_child(:site_setup)
     end
 
-    # Encodes the Prescription object + any hiearchy of child objects,
-    # to a properly formatted RTPConnect ascii string.
+    # Computes a hash code for this object.
     #
-    # @return [String] an RTP string with a single or multiple lines/records
+    # @note Two objects with the same attributes will have the same hash code.
     #
-    def to_s
-      str = encode
-      if children
-        children.each do |child|
-          str += child.to_s
-        end
-      end
-      return str
+    # @return [Fixnum] the object's hash code
+    #
+    def hash
+      state.hash
     end
 
-    alias :to_str :to_s
-
-    # Sets the keyword attribute.
+    # Returns self.
     #
-    # @note Since only a specific string is accepted, this is more of an argument check than a traditional setter method
-    # @param [#to_s] value the new attribute value
-    # @raise [ArgumentError] if given an unexpected keyword
+    # @return [Prescription] self
     #
-    def keyword=(value)
-      value = value.to_s.upcase
-      raise ArgumentError, "Invalid keyword. Expected 'RX_DEF', got #{value}." unless value == "RX_DEF"
-      @keyword = value
+    def to_prescription
+      self
     end
 
     # Sets the course_id attribute.

data/lib/rtp-connect/record.rb

@@ -1,58 +1,226 @@
-module RTP
-
-  # The Record class contains attributes and methods that are common
-  # for the various record types defined in the RTPConnect standard.
-  #
-  class Record
-
-    # The keyword defines the record type of a particular RTP string line.
-    attr_reader :keyword
-    # The CRC is used to validate the integrity of the content of the RTP string line.
-    attr_reader :crc
-
-    # Sets the crc (checksum) attribute.
-    #
-    # @note This value is not used when creating an RTP string from a record (a new crc is calculated)
-    # @param [#to_s] value the new attribute value
-    #
-    def crc=(value)
-      @crc = value.to_s
-    end
-
-    # Encodes a string from the contents of this instance.
-    #
-    # This produces the full record string line, including a computed CRC checksum.
-    #
-    # @return [String] a proper RTPConnect type CSV string
-    #
-    def encode
-      content = CSV.generate_line(values, force_quotes: true, row_sep: '') + ","
-      checksum = content.checksum
-      # Complete string is content + checksum (in double quotes) + carriage return + line feed
-      return (content + checksum.to_s.wrap + "\r\n").encode('ISO8859-1')
-    end
-
-    # Follows the tree of parents until the appropriate parent of the requesting record is found.
-    #
-    # @param [Record] last_parent the previous parent (the record from the previous line in the RTP file)
-    # @param [Record] klass the expected parent record class of this record (e.g. Plan, Field)
-    #
-    def get_parent(last_parent, klass)
-      if last_parent.is_a?(klass)
-        return last_parent
-      else
-        return last_parent.get_parent(last_parent.parent, klass)
-      end
-    end
-
-    # Returns self.
-    #
-    # @return [Record] self
-    #
-    def to_record
-      self
-    end
-
-  end
-
+module RTP
+
+  # The Record class contains attributes and methods that are common
+  # for the various record types defined in the RTPConnect standard.
+  #
+  class Record
+
+    # For most record types, there are no surplus (grouped) attributes.
+    NR_SURPLUS_ATTRIBUTES = 0
+
+    # An array of the record's attributes.
+    attr_reader :attributes
+    # The keyword defines the record type of a particular RTP string line.
+    attr_reader :keyword
+    # The CRC is used to validate the integrity of the content of the RTP string line.
+    attr_reader :crc
+
+    # Creates a new Record.
+    #
+    # @param [String] keyword the keyword which identifies this record
+    # @param [Integer] min_elements the minimum number of data elements required for this record
+    # @param [Integer] max_elements the maximum supported number of data elements for this record
+    #
+    def initialize(keyword, min_elements, max_elements)
+      @keyword = keyword
+      @min_elements = min_elements
+      @max_elements = max_elements
+    end
+
+    # Sets the crc (checksum) attribute.
+    #
+    # @note This value is not used when creating an RTP string from a record (a new crc is calculated)
+    # @param [#to_s] value the new attribute value
+    #
+    def crc=(value)
+      @crc = value.to_s
+    end
+
+    # Encodes a string from the contents of this instance.
+    #
+    # This produces the full record string line, including a computed CRC checksum.
+    #
+    # @param [Hash] options an optional hash parameter
+    # @option options [Float] :version the Mosaiq compatibility version number (e.g. 2.4) used for the output
+    # @return [String] a proper RTPConnect type CSV string
+    #
+    def encode(options={})
+      encoded_values = values.collect {|v| v && v.encode('ISO8859-1')}
+      encoded_values = discard_unsupported_attributes(encoded_values, options) if options[:version]
+      content = CSV.generate_line(encoded_values, force_quotes: true, row_sep: '') + ","
+      checksum = content.checksum
+      # Complete string is content + checksum (in double quotes) + carriage return + line feed
+      return (content + checksum.to_s.wrap + "\r\n").encode('ISO8859-1')
+    end
+
+    # Follows the tree of parents until the appropriate parent of the requesting record is found.
+    #
+    # @param [Record] last_parent the previous parent (the record from the previous line in the RTP file)
+    # @param [Record] klass the expected parent record class of this record (e.g. Plan, Field)
+    #
+    def get_parent(last_parent, klass)
+      if last_parent.is_a?(klass)
+        return last_parent
+      else
+        return last_parent.get_parent(last_parent.parent, klass)
+      end
+    end
+
+    # Verifies a proposed keyword attribute.
+    #
+    # @note Since only a specific string is accepted, this is more of an argument check than a traditional setter method.
+    # @param [#to_s] value the proposed keyword attribute
+    # @raise [ArgumentError] if given an unexpected keyword
+    #
+    def keyword=(value)
+      value = value.to_s.upcase
+      raise ArgumentError, "Invalid keyword. Expected '#{@keyword}', got #{value}." unless value == @keyword
+    end
+
+    # Sets up a record by parsing a RTPConnect string line.
+    #
+    # @param [#to_s] string the extended treatment field definition record string line
+    # @return [Record] the updated Record instance
+    # @raise [ArgumentError] if given a string containing an invalid number of elements
+    #
+    def load(string, options={})
+      # Extract processed values:
+      values = string.to_s.values(options[:repair])
+      raise ArgumentError, "Invalid argument 'string': Expected at least #{@min_elements} elements for #{@keyword}, got #{values.length}." if values.length < @min_elements
+      RTP.logger.warn "The number of given elements (#{values.length}) exceeds the known number of data elements for this record (#{@max_elements}). This may indicate an invalid string record or that the RTP format has recently been expanded with new elements." if values.length > @max_elements
+      self.send(:set_attributes, values)
+      self
+    end
+
+    # Returns self.
+    #
+    # @return [Record] self
+    #
+    def to_record
+      self
+    end
+
+    # Encodes the record + any hiearchy of child objects,
+    # to a properly formatted RTPConnect ascii string.
+    #
+    # @param [Hash] options an optional hash parameter
+    # @option options [Float] :version the Mosaiq compatibility version number (e.g. 2.4) used for the output
+    # @return [String] an RTP string with a single or multiple lines/records
+    #
+    def to_s(options={})
+      str = encode(options)
+      children.each do |child|
+        # Note that the extended plan record was introduced in Mosaiq 2.5.
+        str += child.to_s(options) unless child.class == ExtendedPlan && options[:version].to_f < 2.5
+      end
+      str
+    end
+
+    alias :to_str :to_s
+
+    # Collects the values (attributes) of this instance.
+    #
+    # @note The CRC is not considered part of the actual values and is excluded.
+    # @return [Array<String>] an array of attributes (in the same order as they appear in the RTP string)
+    #
+    def values
+      @attributes.collect {|attribute| self.send(attribute)}
+    end
+
+
+    private
+
+
+    # Removes the reference of the given instance from the attribute of this record.
+    #
+    # @param [Symbol] attribute the name of the child attribute from which to remove a child
+    # @param [Record] instance a child record to be removed from this instance
+    #
+    def delete_child(attribute, instance=nil)
+      if self.send(attribute).is_a?(Array)
+        deleted = self.send(attribute).delete(instance)
+        deleted.parent = nil if deleted
+      else
+        self.send(attribute).parent = nil if self.send(attribute)
+        self.instance_variable_set("@#{attribute}", nil)
+      end
+    end
+
+    # Removes all child references of the given type from this instance.
+    #
+    # @param [Symbol] attribute the name of the child attribute to be cleared
+    #
+    def delete_children(attribute)
+      self.send(attribute).each { |c| c.parent = nil }
+      self.send(attribute).clear
+    end
+
+    # Sets the attributes of the record instance.
+    #
+    # @param [Array<String>] values the record attributes (as parsed from a record string)
+    #
+    def set_attributes(values)
+      import_indices([values.length - 1, @max_elements - 1].min).each_with_index do |indices, i|
+        param = nil
+        if indices
+          param = values.values_at(*indices)
+          param = param[0] if param.length == 1
+        end
+        self.send("#{@attributes[i]}=", param)
+      end
+      @crc = values[-1]
+    end
+
+    # Gives an array of indices indicating where the attributes of this record gets its
+    # values from in the comma separated string which the instance is created from.
+    #
+    # @param [Integer] length the number of elements to create in the indices array
+    #
+    def import_indices(length)
+      Array.new(length - NR_SURPLUS_ATTRIBUTES) { |i| [i] }
+    end
+
+    # Removes any attributes that are newer than the given compatibility target version.
+    # E.g. if a compatibility version of Mosaiq 2.4 is specified, attributes that were
+    # introduced in Mosaiq 2.5 or later is removed before the RTP string is created.
+    #
+    # @param [Array<String>] values the complete set of values of this record
+    # @param [Hash] options an optional hash parameter
+    # @option options [Float] :version the Mosaiq compatibility version number (e.g. 2.4) used for the output
+    # @return [Array<String>] an array of attributes where some of the recent attributes may have been removed
+    #
+    def discard_unsupported_attributes(values, options={})
+      ver = options[:version].to_f
+      case self
+      when SiteSetup
+        if ver >= 2.81
+          values
+        elsif ver >= 2.65
+          values[0..-3]
+        elsif ver >= 2.6
+          values[0..-7]
+        else
+          values[0..-10]
+        end
+      when Field
+        ver >= 2.64 ? values : values[0..-4]
+      when ExtendedField
+        if ver >= 2.65
+          values
+        elsif ver >= 2.4
+          values[0..-3]
+        else
+          values[0..-7]
+        end
+      when ControlPoint
+        ver >= 2.64 ? values : values[0..31] + values[35..-1]
+      when ExtendedPlan
+        ver >= 2.81 ? values : values[0..-2]
+      else
+        values
+      end
+    end
+
+  end
+
 end