rtp-connect 1.6 → 1.11

data/lib/rtp-connect/methods.rb

@@ -1,63 +1,86 @@
-module RTP
-
-  class << self
-
-    #--
-    # Module methods:
-    #++
-
-    # Gives an array of MLC leaf position boundaries for a given type of MLC,
-    # specified by its number of leaves at one side.
-    #
-    # @param [Fixnum] nr_leaves the number of leaves (in one leaf bank)
-    # @return [Array<Fixnum>] the leaf boundary positions
-    # @raise [ArgumentError] if an unsupported MLC (nr of leaves) is given
-    #
-    def leaf_boundaries(nr_leaves)
-      case nr_leaves
-      when 29
-        [-200, -135, -125, -115, -105, -95, -85, -75, -65, -55, -45, -35, -25,
-          -15, -5, 5, 15, 25, 35, 45, 55, 65, 75, 85, 95, 105, 115, 125, 135, 200
-        ]
-      when 40
-        Array.new(nr_leaves+1) {|i| (i * 400 / nr_leaves.to_f - 200).to_i}
-      when 41
-        [-200, -195, -185, -175, -165, -155, -145, -135, -125, -115,
-          -105, -95, -85, -75, -65, -55, -45, -35, -25, -15, -5, 5, 15, 25, 35, 45,
-          55, 65, 75, 85, 95, 105, 115, 125, 135, 145, 155, 165, 175, 185, 195, 200
-        ]
-      when 60
-        [-200, -190, -180, -170, -160, -150, -140, -130, -120, -110,
-          -100, -95, -90, -85, -80, -75, -70, -65, -60, -55, -50, -45, -40, -35, -30,
-          -25, -20, -15, -10, -5, 0, 5, 10, 15, 20, 25, 30, 35, 40, 45, 50, 55, 60, 65,
-          70, 75, 80, 85, 90, 95, 100, 110, 120, 130, 140, 150, 160, 170, 180, 190, 200
-        ]
-      when 80
-        Array.new(nr_leaves+1) {|i| (i * 400 / nr_leaves.to_f - 200).to_i}
-      else
-        raise ArgumentError, "Unsupported number of leaves: #{nr_leaves}"
-      end
-    end
-
-    # Computes the CRC checksum of the given line and verifies that
-    # this value corresponds with the checksum given at the end of the line.
-    #
-    # @param [String] line a single line string from an RTPConnect ascii file
-    # @return [Boolean] true
-    # @raise [ArgumentError] if an invalid line/record is given or the string contains an invalid checksum
-    #
-    def verify(line)
-      last_comma_pos = line.rindex(',')
-      raise ArgumentError, "Invalid line encountered; No comma present in the string: #{line}" unless last_comma_pos
-      string_to_check = line[0..last_comma_pos]
-      string_remaining = line[(last_comma_pos+1)..-1]
-      raise ArgumentError, "Invalid line encountered; Valid checksum missing at end of string: #{string_remaining}" unless string_remaining.length >= 3
-      checksum_extracted = string_remaining.value.to_i
-      checksum_computed = string_to_check.checksum
-      raise ArgumentError, "Invalid line encountered: Specified checskum #{checksum_extracted} deviates from the computed checksum #{checksum_computed}." if checksum_extracted != checksum_computed
-      return true
-    end
-
-  end
-
+module RTP
+
+  class << self
+
+    #--
+    # Module methods:
+    #++
+
+    # Gives an array of MLC leaf position boundaries for a given type of MLC,
+    # specified by its number of leaves at one side.
+    #
+    # @param [Fixnum] nr_leaves the number of leaves (in one leaf bank)
+    # @return [Array<Fixnum>] the leaf boundary positions
+    # @raise [ArgumentError] if an unsupported MLC (nr of leaves) is given
+    #
+    def leaf_boundaries(nr_leaves)
+      case nr_leaves
+      when 29
+        leaf_boundaries_odd(29)
+      when 40
+        leaf_boundaries_even(40)
+      when 41
+        leaf_boundaries_odd(41)
+      when 60
+        leaf_boundaries_varian_60
+      when 80
+        leaf_boundaries_even(80)
+      else
+        raise ArgumentError, "Unsupported number of leaves: #{nr_leaves}"
+      end
+    end
+
+    # Gives an array of MLC leaf position boundaries for ordinary even numbered
+    # multi leaf collimators.
+    #
+    # @param [Fixnum] nr_leaves the number of leaves (in one leaf bank)
+    # @return [Array<Fixnum>] the leaf boundary positions
+    #
+    def leaf_boundaries_even(nr_leaves)
+      Array.new(nr_leaves+1) {|i| (i * 400 / nr_leaves.to_f - 200).to_i}
+    end
+
+    # Gives an array of MLC leaf position boundaries for ordinary odd numbered
+    # multi leaf collimators.
+    #
+    # @param [Fixnum] nr_leaves the number of leaves (in one leaf bank)
+    # @return [Array<Fixnum>] the leaf boundary positions
+    #
+    def leaf_boundaries_odd(nr_leaves)
+      Array.new(nr_leaves-1) {|i| (10 * (i - (0.5 * nr_leaves - 1))).to_i}.unshift(-200).push(200)
+    end
+
+    # Gives an array of MLC leaf position boundaries for the Varian 120 leaf MLC (60 leaves on each bank).
+    #
+    # @return [Array<Fixnum>] the leaf boundary positions
+    #
+    def leaf_boundaries_varian_60
+      Array.new(10) {|i| (i * 10 - 200).to_i}
+          .concat(Array.new(41) {|i| (i * 5 - 100).to_i})
+          .concat(Array.new(10) {|i| (i * 10 + 110).to_i})
+    end
+
+    # Computes the CRC checksum of the given line and verifies that
+    # this value corresponds with the checksum given at the end of the line.
+    #
+    # @param [String] line a single line string from an RTPConnect ascii file
+    # @param [Hash] options the options to use for verifying the RTP record
+    # @option options [Boolean] :ignore_crc if true, the verification method will return true even if the checksum is invalid
+    # @return [Boolean] true
+    # @raise [ArgumentError] if an invalid line/record is given or the string contains an invalid checksum
+    #
+    def verify(line, options={})
+      last_comma_pos = line.rindex(',')
+      raise ArgumentError, "Invalid line encountered; No comma present in the string: #{line}" unless last_comma_pos
+      string_to_check = line[0..last_comma_pos]
+      string_remaining = line[(last_comma_pos+1)..-1]
+      raise ArgumentError, "Invalid line encountered; Valid checksum missing at end of string: #{string_remaining}" unless string_remaining.length >= 3
+      checksum_extracted = string_remaining.value.to_i
+      checksum_computed = string_to_check.checksum
+      raise ArgumentError, "Invalid line encountered: Specified checksum #{checksum_extracted} deviates from the computed checksum #{checksum_computed}." if checksum_extracted != checksum_computed && !options[:ignore_crc]
+      return true
+    end
+
+  end
+
 end

data/lib/rtp-connect/plan.rb

@@ -1,637 +1,646 @@
-#    Copyright 2011-2013 Christoffer Lervag
-#
-#    This program is free software: you can redistribute it and/or modify
-#    it under the terms of the GNU General Public License as published by
-#    the Free Software Foundation, either version 3 of the License, or
-#    (at your option) any later version.
-#
-#    This program is distributed in the hope that it will be useful,
-#    but WITHOUT ANY WARRANTY; without even the implied warranty of
-#    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-#    GNU General Public License for more details.
-#
-#    You should have received a copy of the GNU General Public License
-#    along with this program.  If not, see <http://www.gnu.org/licenses/>.
-#
-module RTP
-
-  # The Plan class is the highest level Record in the RTPConnect records hierarchy,
-  # and the one the user will interact with to read, modify and write files.
-  #
-  # @note Relations:
-  #   * Parent: nil
-  #   * Children: Prescription, DoseTracking
-  #
-  class Plan < Record
-    include Logging
-
-    # The Record which this instance belongs to (nil by definition).
-    attr_reader :parent
-    # An array of Prescription records (if any) that belongs to this Plan.
-    attr_reader :prescriptions
-    # An array of DoseTracking records (if any) that belongs to this Plan.
-    attr_reader :dose_trackings
-    attr_reader :patient_id
-    attr_reader :patient_last_name
-    attr_reader :patient_first_name
-    attr_reader :patient_middle_initial
-    attr_reader :plan_id
-    attr_reader :plan_date
-    attr_reader :plan_time
-    attr_reader :course_id
-    attr_reader :diagnosis
-    attr_reader :md_last_name
-    attr_reader :md_first_name
-    attr_reader :md_middle_initial
-    attr_reader :md_approve_last_name
-    attr_reader :md_approve_first_name
-    attr_reader :md_approve_middle_initial
-    attr_reader :phy_approve_last_name
-    attr_reader :phy_approve_first_name
-    attr_reader :phy_approve_middle_initial
-    attr_reader :author_last_name
-    attr_reader :author_first_name
-    attr_reader :author_middle_initial
-    attr_reader :rtp_mfg
-    attr_reader :rtp_model
-    attr_reader :rtp_version
-    attr_reader :rtp_if_protocol
-    attr_reader :rtp_if_version
-
-    # Creates a new Plan by loading a plan definition string (i.e. a single line).
-    #
-    # @note This method does not perform crc verification on the given string.
-    #   If such verification is desired, use methods ::parse or ::read instead.
-    # @param [#to_s] string the plan definition record string line
-    # @return [Plan] the created Plan instance
-    # @raise [ArgumentError] if given a string containing an invalid number of elements
-    #
-    def self.load(string)
-      # Get the quote-less values:
-      values = string.to_s.values
-      low_limit = 10
-      high_limit = 28
-      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 Plan 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
-      rtp = self.new
-      # Assign the values to attributes:
-      rtp.keyword = values[0]
-      rtp.patient_id = values[1]
-      rtp.patient_last_name = values[2]
-      rtp.patient_first_name = values[3]
-      rtp.patient_middle_initial = values[4]
-      rtp.plan_id = values[5]
-      rtp.plan_date = values[6]
-      rtp.plan_time = values[7]
-      rtp.course_id = values[8]
-      rtp.diagnosis = values[9]
-      rtp.md_last_name = values[10]
-      rtp.md_first_name = values[11]
-      rtp.md_middle_initial = values[12]
-      rtp.md_approve_last_name = values[13]
-      rtp.md_approve_first_name = values[14]
-      rtp.md_approve_middle_initial = values[15]
-      rtp.phy_approve_last_name = values[16]
-      rtp.phy_approve_first_name = values[17]
-      rtp.phy_approve_middle_initial = values[18]
-      rtp.author_last_name = values[19]
-      rtp.author_first_name = values[20]
-      rtp.author_middle_initial = values[21]
-      rtp.rtp_mfg = values[22]
-      rtp.rtp_model = values[23]
-      rtp.rtp_version = values[24]
-      rtp.rtp_if_protocol = values[25]
-      rtp.rtp_if_version = values[26]
-      rtp.crc = values[-1]
-      return rtp
-    end
-
-    # Creates a Plan instance by parsing an RTPConnect string.
-    #
-    # @param [#to_s] string an RTPConnect ascii string (with single or multiple lines/records)
-    # @return [Plan] the created Plan instance
-    # @raise [ArgumentError] if given an invalid string record
-    #
-    def self.parse(string)
-      lines = string.to_s.split("\r\n")
-      # Create the Plan object:
-      line = lines.first
-      RTP::verify(line)
-      rtp = self.load(line)
-      lines[1..-1].each do |line|
-        # Validate, determine type, and process the line accordingly to
-        # build the hierarchy of records:
-        RTP::verify(line)
-        values = line.values
-        keyword = values.first
-        method = RTP::PARSE_METHOD[keyword]
-        raise ArgumentError, "Unknown keyword #{keyword} extracted from string." unless method
-        rtp.send(method, line)
-      end
-      return rtp
-    end
-
-    # Creates an Plan instance by reading and parsing an RTPConnect file.
-    #
-    # @param [String] file a string which specifies the path of the RTPConnect file to be loaded
-    # @return [Plan] the created Plan instance
-    # @raise [ArgumentError] if given an invalid file or the file given contains an invalid record
-    #
-    def self.read(file)
-      raise ArgumentError, "Invalid argument 'file'. Expected String, got #{file.class}." unless file.is_a?(String)
-      # Read the file content:
-      str = nil
-      unless File.exist?(file)
-        logger.error("Invalid (non-existing) file: #{file}")
-      else
-        unless File.readable?(file)
-          logger.error("File exists but I don't have permission to read it: #{file}")
-        else
-          if File.directory?(file)
-            logger.error("Expected a file, got a directory: #{file}")
-          else
-            if File.size(file) < 10
-              logger.error("This file is too small to contain valid RTP information: #{file}.")
-            else
-              str = File.open(file, 'rb:ISO8859-1') { |f| f.read }
-            end
-          end
-        end
-      end
-      # Parse the file contents and create the RTP::Connect object:
-      if str
-        rtp = self.parse(str)
-      else
-        raise "An RTP::Plan object could not be created from the specified file. Check the log for more details."
-      end
-      return rtp
-    end
-
-    # Creates a new Plan.
-    #
-    def initialize
-      @current_parent = self
-      # Child records:
-      @prescriptions = Array.new
-      @dose_trackings = Array.new
-      # No parent (by definition) for the Plan record:
-      @parent = nil
-      @keyword = 'PLAN_DEF'
-    end
-
-    # Checks for equality.
-    #
-    # Other and self are considered equivalent if they are
-    # of compatible types and their attributes are equivalent.
-    #
-    # @param other an object to be compared with self.
-    # @return [Boolean] true if self and other are considered equivalent
-    #
-    def ==(other)
-      if other.respond_to?(:to_plan)
-        other.send(:state) == state
-      end
-    end
-
-    alias_method :eql?, :==
-
-    # Adds a dose tracking record to this instance.
-    #
-    # @param [DoseTracking] child a DoseTracking instance which is to be associated with self
-    #
-    def add_dose_tracking(child)
-      @dose_trackings << child.to_dose_tracking
-    end
-
-    # Adds a prescription site record to this instance.
-    #
-    # @param [Prescription] child a Prescription instance which is to be associated with self
-    #
-    def add_prescription(child)
-      @prescriptions << child.to_prescription
-    end
-
-    # Collects the child records of this instance in a properly sorted array.
-    #
-    # @return [Array<Prescription, DoseTracking>] a sorted array of self's child records
-    #
-    def children
-      return [@prescriptions, @dose_trackings].flatten.compact
-    end
-
-    # Computes a hash code for this object.
-    #
-    # @note Two objects with the same attributes will have the same hash code.
-    #
-    # @return [Fixnum] the object's hash code
-    #
-    def hash
-      state.hash
-    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,
-        @patient_id,
-        @patient_last_name,
-        @patient_first_name,
-        @patient_middle_initial,
-        @plan_id,
-        @plan_date,
-        @plan_time,
-        @course_id,
-        @diagnosis,
-        @md_last_name,
-        @md_first_name,
-        @md_middle_initial,
-        @md_approve_last_name,
-        @md_approve_first_name,
-        @md_approve_middle_initial,
-        @phy_approve_last_name,
-        @phy_approve_first_name,
-        @phy_approve_middle_initial,
-        @author_last_name,
-        @author_first_name,
-        @author_middle_initial,
-        @rtp_mfg,
-        @rtp_model,
-        @rtp_version,
-        @rtp_if_protocol,
-        @rtp_if_version
-      ]
-    end
-
-    # Returns self.
-    #
-    # @return [Plan] self
-    #
-    def to_plan
-      self
-    end
-
-    # Returns self.
-    #
-    # @return [Plan] self
-    #
-    def to_rtp
-      self
-    end
-
-    # Encodes the Plan object + any hiearchy of child objects,
-    # to a properly formatted RTPConnect ascii string.
-    #
-    # @return [String] an RTP string with a single or multiple lines/records
-    #
-    def to_s
-      str = encode #.force_encoding('utf-8')
-      children.each do |child|
-        str += child.to_s #.force_encoding('utf-8')
-      end
-      return str
-    end
-
-    alias :to_str :to_s
-
-    # Writes the Plan object, along with its hiearchy of child objects,
-    # to a properly formatted RTPConnect ascii file.
-    #
-    # @param [String] file a path/file string
-    #
-    def write(file)
-      f = open_file(file)
-      f.write(to_s)
-      f.close
-    end
-
-    # Sets the 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 new attribute value
-    # @raise [ArgumentError] if given an unexpected keyword
-    #
-    def keyword=(value)
-      value = value.to_s.upcase
-      raise ArgumentError, "Invalid keyword. Expected 'PLAN_DEF', got #{value}." unless value == "PLAN_DEF"
-      @keyword = value
-    end
-
-    # Sets the patient_id attribute.
-    #
-    # @param [nil, #to_s] value the new attribute value
-    #
-    def patient_id=(value)
-      @patient_id = value && value.to_s
-    end
-
-    # Sets the patient_last_name attribute.
-    #
-    def patient_last_name=(value)
-      @patient_last_name = value && value.to_s
-    end
-
-    # Sets the patient_first_name attribute.
-    #
-    # @param [nil, #to_s] value the new attribute value
-    #
-    def patient_first_name=(value)
-      @patient_first_name = value && value.to_s
-    end
-
-    # Sets the patient_middle_initial attribute.
-    #
-    # @param [nil, #to_s] value the new attribute value
-    #
-    def patient_middle_initial=(value)
-      @patient_middle_initial = value && value.to_s
-    end
-
-    # Sets the plan_id attribute.
-    #
-    # @param [nil, #to_s] value the new attribute value
-    #
-    def plan_id=(value)
-      @plan_id = value && value.to_s
-    end
-
-    # Sets the plan_date attribute.
-    #
-    # @param [nil, #to_s] value the new attribute value
-    #
-    def plan_date=(value)
-      @plan_date = value && value.to_s
-    end
-
-    # Sets the plan_time attribute.
-    #
-    # @param [nil, #to_s] value the new attribute value
-    #
-    def plan_time=(value)
-      @plan_time = value && value.to_s
-    end
-
-    # Sets the course_id attribute.
-    #
-    # @param [nil, #to_s] value the new attribute value
-    #
-    def course_id=(value)
-      @course_id = value && value.to_s
-    end
-
-    # Sets the diagnosis attribute.
-    #
-    # @param [nil, #to_s] value the new attribute value
-    #
-    def diagnosis=(value)
-      @diagnosis = value && value.to_s
-    end
-
-    # Sets the md_last_name attribute.
-    #
-    # @param [nil, #to_s] value the new attribute value
-    #
-    def md_last_name=(value)
-      @md_last_name = value && value.to_s
-    end
-
-    # Sets the md_first_name attribute.
-    #
-    # @param [nil, #to_s] value the new attribute value
-    #
-    def md_first_name=(value)
-      @md_first_name = value && value.to_s
-    end
-
-    # Sets the md_middle_initial attribute.
-    #
-    # @param [nil, #to_s] value the new attribute value
-    #
-    def md_middle_initial=(value)
-      @md_middle_initial = value && value.to_s
-    end
-
-    # Sets the md_approve_last_name attribute.
-    #
-    # @param [nil, #to_s] value the new attribute value
-    #
-    def md_approve_last_name=(value)
-      @md_approve_last_name = value && value.to_s
-    end
-
-    # Sets the md_approve_first_name attribute.
-    #
-    # @param [nil, #to_s] value the new attribute value
-    #
-    def md_approve_first_name=(value)
-      @md_approve_first_name = value && value.to_s
-    end
-
-    # Sets the md_approve_middle_initial attribute.
-    #
-    # @param [nil, #to_s] value the new attribute value
-    #
-    def md_approve_middle_initial=(value)
-      @md_approve_middle_initial = value && value.to_s
-    end
-
-    # Sets the phy_approve_last_name attribute.
-    #
-    # @param [nil, #to_s] value the new attribute value
-    #
-    def phy_approve_last_name=(value)
-      @phy_approve_last_name = value && value.to_s
-    end
-
-    # Sets the phy_approve_first_name attribute.
-    #
-    # @param [nil, #to_s] value the new attribute value
-    #
-    def phy_approve_first_name=(value)
-      @phy_approve_first_name = value && value.to_s
-    end
-
-    # Sets the phy_approve_middle_initial attribute.
-    #
-    # @param [nil, #to_s] value the new attribute value
-    #
-    def phy_approve_middle_initial=(value)
-      @phy_approve_middle_initial = value && value.to_s
-    end
-
-    # Sets the author_last_name attribute.
-    #
-    # @param [nil, #to_s] value the new attribute value
-    #
-    def author_last_name=(value)
-      @author_last_name = value && value.to_s
-    end
-
-    # Sets the author_first_name attribute.
-    #
-    # @param [nil, #to_s] value the new attribute value
-    #
-    def author_first_name=(value)
-      @author_first_name = value && value.to_s
-    end
-
-    # Sets the author_middle_initial attribute.
-    #
-    # @param [nil, #to_s] value the new attribute value
-    #
-    def author_middle_initial=(value)
-      @author_middle_initial = value && value.to_s
-    end
-
-    # Sets the rtp_mfg attribute.
-    #
-    # @param [nil, #to_s] value the new attribute value
-    #
-    def rtp_mfg=(value)
-      @rtp_mfg = value && value.to_s
-    end
-
-    # Sets the rtp_model attribute.
-    #
-    # @param [nil, #to_s] value the new attribute value
-    #
-    def rtp_model=(value)
-      @rtp_model = value && value.to_s
-    end
-
-    # Sets the rtp_version attribute.
-    #
-    # @param [nil, #to_s] value the new attribute value
-    #
-    def rtp_version=(value)
-      @rtp_version = value && value.to_s
-    end
-
-    # Sets the rtp_if_protocol attribute.
-    #
-    # @param [nil, #to_s] value the new attribute value
-    #
-    def rtp_if_protocol=(value)
-      @rtp_if_protocol = value && value.to_s
-    end
-
-    # Sets the rtp_if_version attribute.
-    #
-    # @param [nil, #to_s] value the new attribute value
-    #
-    def rtp_if_version=(value)
-      @rtp_if_version = value && value.to_s
-    end
-
-
-    private
-
-
-    # Creates a control point record from the given string.
-    #
-    # @param [String] string a string line containing a control point definition
-    #
-    def control_point(string)
-      cp = ControlPoint.load(string, @current_parent)
-      @current_parent = cp
-    end
-
-    # Creates a dose tracking record from the given string.
-    #
-    # @param [String] string a string line containing a dose tracking definition
-    #
-    def dose_tracking(string)
-      dt = DoseTracking.load(string, @current_parent)
-      @current_parent = dt
-    end
-
-    # Creates an extended treatment field record from the given string.
-    #
-    # @param [String] string a string line containing an extended treatment field definition
-    #
-    def extended_treatment_field(string)
-      ef = ExtendedField.load(string, @current_parent)
-      @current_parent = ef
-    end
-
-    # Tests if the path/file is writable, creates any folders if necessary, and opens the file for writing.
-    #
-    # @param [String] file a path/file string
-    # @raise if the given file cannot be created
-    #
-    def open_file(file)
-      # Check if file already exists:
-      if File.exist?(file)
-        # Is (the existing file) writable?
-        unless File.writable?(file)
-          raise "The program does not have permission or resources to create this file: #{file}"
-        end
-      else
-        # File does not exist.
-        # Check if this file's path contains a folder that does not exist, and therefore needs to be created:
-        folders = file.split(File::SEPARATOR)
-        if folders.length > 1
-          # Remove last element (which should be the file string):
-          folders.pop
-          path = folders.join(File::SEPARATOR)
-          # Check if this path exists:
-          unless File.directory?(path)
-            # We need to create (parts of) this path:
-            require 'fileutils'
-            FileUtils.mkdir_p(path)
-          end
-        end
-      end
-      # It has been verified that the file can be created:
-      return File.new(file, 'wb:ISO8859-1')
-    end
-
-    # Creates a prescription site record from the given string.
-    #
-    # @param [String] string a string line containing a prescription site definition
-    #
-    def prescription_site(string)
-      p = Prescription.load(string, @current_parent)
-      @current_parent = p
-    end
-
-    # Creates a site setup record from the given string.
-    #
-    # @param [String] string a string line containing a site setup definition
-    #
-    def site_setup(string)
-      s = SiteSetup.load(string, @current_parent)
-      @current_parent = s
-    end
-
-    # Collects the attributes of this instance.
-    #
-    # @note The CRC is not considered part of the attributes of interest and is excluded
-    # @return [Array<String>] an array of attributes
-    #
-    alias_method :state, :values
-
-    # Creates a treatment field record from the given string.
-    #
-    # @param [String] string a string line containing a treatment field definition
-    #
-    def treatment_field(string)
-      f = Field.load(string, @current_parent)
-      @current_parent = f
-    end
-
-    # Creates a simulation field record from the given string.
-    #
-    # @param [String] string a string line containing a simulation field definition
-    #
-    def simulation_field(string)
-      sf = SimulationField.load(string, @current_parent)
-      @current_parent = sf
-    end
-
-  end
-
+#    Copyright 2011-2020 Christoffer Lervag
+#
+#    This program is free software: you can redistribute it and/or modify
+#    it under the terms of the GNU General Public License as published by
+#    the Free Software Foundation, either version 3 of the License, or
+#    (at your option) any later version.
+#
+#    This program is distributed in the hope that it will be useful,
+#    but WITHOUT ANY WARRANTY; without even the implied warranty of
+#    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+#    GNU General Public License for more details.
+#
+#    You should have received a copy of the GNU General Public License
+#    along with this program.  If not, see <http://www.gnu.org/licenses/>.
+#
+module RTP
+
+  # The Plan class is the highest level Record in the RTPConnect records hierarchy,
+  # and the one the user will interact with to read, modify and write files.
+  #
+  # @note Relations:
+  #   * Parent: nil
+  #   * Children: Prescription, DoseTracking
+  #
+  class Plan < Record
+    include Logging
+
+    # The Record which this instance belongs to (nil by definition).
+    attr_reader :parent
+    # An array of Prescription records (if any) that belongs to this Plan.
+    attr_reader :prescriptions
+    # The ExtendedPlan record (if any) that belongs to this Plan.
+    attr_reader :extended_plan
+    # An array of DoseTracking records (if any) that belongs to this Plan.
+    attr_reader :dose_trackings
+    attr_reader :patient_id
+    attr_reader :patient_last_name
+    attr_reader :patient_first_name
+    attr_reader :patient_middle_initial
+    attr_reader :plan_id
+    attr_reader :plan_date
+    attr_reader :plan_time
+    attr_reader :course_id
+    attr_reader :diagnosis
+    attr_reader :md_last_name
+    attr_reader :md_first_name
+    attr_reader :md_middle_initial
+    attr_reader :md_approve_last_name
+    attr_reader :md_approve_first_name
+    attr_reader :md_approve_middle_initial
+    attr_reader :phy_approve_last_name
+    attr_reader :phy_approve_first_name
+    attr_reader :phy_approve_middle_initial
+    attr_reader :author_last_name
+    attr_reader :author_first_name
+    attr_reader :author_middle_initial
+    attr_reader :rtp_mfg
+    attr_reader :rtp_model
+    attr_reader :rtp_version
+    attr_reader :rtp_if_protocol
+    attr_reader :rtp_if_version
+
+    # Creates a new Plan by loading a plan definition string (i.e. a single line).
+    #
+    # @note This method does not perform crc verification on the given string.
+    #   If such verification is desired, use methods ::parse or ::read instead.
+    # @param [#to_s] string the plan definition record string line
+    # @param [Hash] options the options to use for loading the plan definition string
+    # @option options [Boolean] :repair if true, a record containing invalid CSV will be attempted fixed and loaded
+    # @return [Plan] the created Plan instance
+    # @raise [ArgumentError] if given a string containing an invalid number of elements
+    #
+    def self.load(string, options={})
+      rtp = self.new
+      rtp.load(string, options)
+    end
+
+    # Creates a Plan instance by parsing an RTPConnect string.
+    #
+    # @param [#to_s] string an RTPConnect ascii string (with single or multiple lines/records)
+    # @param [Hash] options the options to use for parsing the RTP string
+    # @option options [Boolean] :ignore_crc if true, the RTP records will be successfully loaded even if their checksums are invalid
+    # @option options [Boolean] :repair if true, any RTP records containing invalid CSV will be attempted fixed and loaded
+    # @option options [Boolean] :skip_unknown if true, unknown records will be skipped, and record instances will be built from the remaining recognized string records
+    # @return [Plan] the created Plan instance
+    # @raise [ArgumentError] if given an invalid string record
+    #
+    def self.parse(string, options={})
+      lines = string.to_s.split("\r\n")
+      # Create the Plan object:
+      line = lines.first
+      RTP.verify(line, options)
+      rtp = self.load(line, options)
+      lines[1..-1].each do |line|
+        # Validate, determine type, and process the line accordingly to
+        # build the hierarchy of records:
+        RTP.verify(line, options)
+        values = line.values(options[:repair])
+        keyword = values.first
+        method = RTP::PARSE_METHOD[keyword]
+        if method
+          rtp.send(method, line)
+        else
+          if options[:skip_unknown]
+            logger.warn("Skipped unknown record definition: #{keyword}")
+          else
+            raise ArgumentError, "Unknown keyword #{keyword} extracted from string."
+          end
+        end
+      end
+      return rtp
+    end
+
+    # Creates an Plan instance by reading and parsing an RTPConnect file.
+    #
+    # @param [String] file a string which specifies the path of the RTPConnect file to be loaded
+    # @param [Hash] options the options to use for reading the RTP file
+    # @option options [Boolean] :ignore_crc if true, the RTP records will be successfully loaded even if their checksums are invalid
+    # @option options [Boolean] :repair if true, any RTP records containing invalid CSV will be attempted fixed and loaded
+    # @option options [Boolean] :skip_unknown if true, unknown records will be skipped, and record instances will be built from the remaining recognized string records
+    # @return [Plan] the created Plan instance
+    # @raise [ArgumentError] if given an invalid file or the file given contains an invalid record
+    #
+    def self.read(file, options={})
+      raise ArgumentError, "Invalid argument 'file'. Expected String, got #{file.class}." unless file.is_a?(String)
+      # Read the file content:
+      str = nil
+      unless File.exist?(file)
+        logger.error("Invalid (non-existing) file: #{file}")
+      else
+        unless File.readable?(file)
+          logger.error("File exists but I don't have permission to read it: #{file}")
+        else
+          if File.directory?(file)
+            logger.error("Expected a file, got a directory: #{file}")
+          else
+            if File.size(file) < 10
+              logger.error("This file is too small to contain valid RTP information: #{file}.")
+            else
+              str = File.open(file, 'rb:ISO8859-1') { |f| f.read }
+            end
+          end
+        end
+      end
+      # Parse the file contents and create the RTP instance:
+      if str
+        rtp = self.parse(str, options)
+      else
+        raise "An RTP::Plan object could not be created from the specified file. Check the log for more details."
+      end
+      return rtp
+    end
+
+    # Creates a new Plan.
+    #
+    def initialize
+      super('PLAN_DEF', 10, 28)
+      @current_parent = self
+      # Child records:
+      @extended_plan = nil
+      @prescriptions = Array.new
+      @dose_trackings = Array.new
+      # No parent (by definition) for the Plan record:
+      @parent = nil
+      @attributes = [
+        # Required:
+        :keyword,
+        :patient_id,
+        :patient_last_name,
+        :patient_first_name,
+        :patient_middle_initial,
+        :plan_id,
+        :plan_date,
+        :plan_time,
+        :course_id,
+        # Optional:
+        :diagnosis,
+        :md_last_name,
+        :md_first_name,
+        :md_middle_initial,
+        :md_approve_last_name,
+        :md_approve_first_name,
+        :md_approve_middle_initial,
+        :phy_approve_last_name,
+        :phy_approve_first_name,
+        :phy_approve_middle_initial,
+        :author_last_name,
+        :author_first_name,
+        :author_middle_initial,
+        :rtp_mfg,
+        :rtp_model,
+        :rtp_version,
+        :rtp_if_protocol,
+        :rtp_if_version
+      ]
+    end
+
+    # Checks for equality.
+    #
+    # Other and self are considered equivalent if they are
+    # of compatible types and their attributes are equivalent.
+    #
+    # @param other an object to be compared with self.
+    # @return [Boolean] true if self and other are considered equivalent
+    #
+    def ==(other)
+      if other.respond_to?(:to_plan)
+        other.send(:state) == state
+      end
+    end
+
+    alias_method :eql?, :==
+
+    # Adds a dose tracking record to this instance.
+    #
+    # @param [DoseTracking] child a DoseTracking instance which is to be associated with self
+    #
+    def add_dose_tracking(child)
+      @dose_trackings << child.to_dose_tracking
+      child.parent = self
+    end
+
+    # Adds an extended plan record to this instance.
+    #
+    # @param [ExtendedPlan] child an ExtendedPlan instance which is to be associated with self
+    #
+    def add_extended_plan(child)
+      @extended_plan = child.to_extended_plan
+      child.parent = self
+    end
+
+    # Adds a prescription site record to this instance.
+    #
+    # @param [Prescription] child a Prescription instance which is to be associated with self
+    #
+    def add_prescription(child)
+      @prescriptions << child.to_prescription
+      child.parent = self
+    end
+
+    # Collects the child records of this instance in a properly sorted array.
+    #
+    # @return [Array<Prescription, DoseTracking>] a sorted array of self's child records
+    #
+    def children
+      return [@extended_plan, @prescriptions, @dose_trackings].flatten.compact
+    end
+
+    # Removes the reference of the given instance from this instance.
+    #
+    # @param [ExtendedPlan, Prescription, DoseTracking] record a child record to be removed from this instance
+    #
+    def delete(record)
+      case record
+      when Prescription
+        delete_child(:prescriptions, record)
+      when DoseTracking
+        delete_child(:dose_trackings, record)
+      when ExtendedPlan
+        delete_extended_plan
+      else
+        logger.warn("Unknown class (record) given to Plan#delete: #{record.class}")
+      end
+    end
+
+    # Removes all dose_tracking references from this instance.
+    #
+    def delete_dose_trackings
+      delete_children(:dose_trackings)
+    end
+
+    # Removes the extended plan reference from this instance.
+    #
+    def delete_extended_plan
+      delete_child(:extended_plan)
+    end
+
+    # Removes all prescription references from this instance.
+    #
+    def delete_prescriptions
+      delete_children(:prescriptions)
+    end
+
+    # Computes a hash code for this object.
+    #
+    # @note Two objects with the same attributes will have the same hash code.
+    #
+    # @return [Fixnum] the object's hash code
+    #
+    def hash
+      state.hash
+    end
+
+    # Returns self.
+    #
+    # @return [Plan] self
+    #
+    def to_plan
+      self
+    end
+
+    # Returns self.
+    #
+    # @return [Plan] self
+    #
+    def to_rtp
+      self
+    end
+
+    # Writes the Plan object, along with its hiearchy of child objects,
+    # to a properly formatted RTPConnect ascii file.
+    #
+    # @param [String] file a path/file 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
+    #
+    def write(file, options={})
+      f = open_file(file)
+      f.write(to_s(options))
+      f.close
+    end
+
+    # Sets the patient_id attribute.
+    #
+    # @param [nil, #to_s] value the new attribute value
+    #
+    def patient_id=(value)
+      @patient_id = value && value.to_s
+    end
+
+    # Sets the patient_last_name attribute.
+    #
+    def patient_last_name=(value)
+      @patient_last_name = value && value.to_s
+    end
+
+    # Sets the patient_first_name attribute.
+    #
+    # @param [nil, #to_s] value the new attribute value
+    #
+    def patient_first_name=(value)
+      @patient_first_name = value && value.to_s
+    end
+
+    # Sets the patient_middle_initial attribute.
+    #
+    # @param [nil, #to_s] value the new attribute value
+    #
+    def patient_middle_initial=(value)
+      @patient_middle_initial = value && value.to_s
+    end
+
+    # Sets the plan_id attribute.
+    #
+    # @param [nil, #to_s] value the new attribute value
+    #
+    def plan_id=(value)
+      @plan_id = value && value.to_s
+    end
+
+    # Sets the plan_date attribute.
+    #
+    # @param [nil, #to_s] value the new attribute value
+    #
+    def plan_date=(value)
+      @plan_date = value && value.to_s
+    end
+
+    # Sets the plan_time attribute.
+    #
+    # @param [nil, #to_s] value the new attribute value
+    #
+    def plan_time=(value)
+      @plan_time = value && value.to_s
+    end
+
+    # Sets the course_id attribute.
+    #
+    # @param [nil, #to_s] value the new attribute value
+    #
+    def course_id=(value)
+      @course_id = value && value.to_s
+    end
+
+    # Sets the diagnosis attribute.
+    #
+    # @param [nil, #to_s] value the new attribute value
+    #
+    def diagnosis=(value)
+      @diagnosis = value && value.to_s
+    end
+
+    # Sets the md_last_name attribute.
+    #
+    # @param [nil, #to_s] value the new attribute value
+    #
+    def md_last_name=(value)
+      @md_last_name = value && value.to_s
+    end
+
+    # Sets the md_first_name attribute.
+    #
+    # @param [nil, #to_s] value the new attribute value
+    #
+    def md_first_name=(value)
+      @md_first_name = value && value.to_s
+    end
+
+    # Sets the md_middle_initial attribute.
+    #
+    # @param [nil, #to_s] value the new attribute value
+    #
+    def md_middle_initial=(value)
+      @md_middle_initial = value && value.to_s
+    end
+
+    # Sets the md_approve_last_name attribute.
+    #
+    # @param [nil, #to_s] value the new attribute value
+    #
+    def md_approve_last_name=(value)
+      @md_approve_last_name = value && value.to_s
+    end
+
+    # Sets the md_approve_first_name attribute.
+    #
+    # @param [nil, #to_s] value the new attribute value
+    #
+    def md_approve_first_name=(value)
+      @md_approve_first_name = value && value.to_s
+    end
+
+    # Sets the md_approve_middle_initial attribute.
+    #
+    # @param [nil, #to_s] value the new attribute value
+    #
+    def md_approve_middle_initial=(value)
+      @md_approve_middle_initial = value && value.to_s
+    end
+
+    # Sets the phy_approve_last_name attribute.
+    #
+    # @param [nil, #to_s] value the new attribute value
+    #
+    def phy_approve_last_name=(value)
+      @phy_approve_last_name = value && value.to_s
+    end
+
+    # Sets the phy_approve_first_name attribute.
+    #
+    # @param [nil, #to_s] value the new attribute value
+    #
+    def phy_approve_first_name=(value)
+      @phy_approve_first_name = value && value.to_s
+    end
+
+    # Sets the phy_approve_middle_initial attribute.
+    #
+    # @param [nil, #to_s] value the new attribute value
+    #
+    def phy_approve_middle_initial=(value)
+      @phy_approve_middle_initial = value && value.to_s
+    end
+
+    # Sets the author_last_name attribute.
+    #
+    # @param [nil, #to_s] value the new attribute value
+    #
+    def author_last_name=(value)
+      @author_last_name = value && value.to_s
+    end
+
+    # Sets the author_first_name attribute.
+    #
+    # @param [nil, #to_s] value the new attribute value
+    #
+    def author_first_name=(value)
+      @author_first_name = value && value.to_s
+    end
+
+    # Sets the author_middle_initial attribute.
+    #
+    # @param [nil, #to_s] value the new attribute value
+    #
+    def author_middle_initial=(value)
+      @author_middle_initial = value && value.to_s
+    end
+
+    # Sets the rtp_mfg attribute.
+    #
+    # @param [nil, #to_s] value the new attribute value
+    #
+    def rtp_mfg=(value)
+      @rtp_mfg = value && value.to_s
+    end
+
+    # Sets the rtp_model attribute.
+    #
+    # @param [nil, #to_s] value the new attribute value
+    #
+    def rtp_model=(value)
+      @rtp_model = value && value.to_s
+    end
+
+    # Sets the rtp_version attribute.
+    #
+    # @param [nil, #to_s] value the new attribute value
+    #
+    def rtp_version=(value)
+      @rtp_version = value && value.to_s
+    end
+
+    # Sets the rtp_if_protocol attribute.
+    #
+    # @param [nil, #to_s] value the new attribute value
+    #
+    def rtp_if_protocol=(value)
+      @rtp_if_protocol = value && value.to_s
+    end
+
+    # Sets the rtp_if_version attribute.
+    #
+    # @param [nil, #to_s] value the new attribute value
+    #
+    def rtp_if_version=(value)
+      @rtp_if_version = value && value.to_s
+    end
+
+
+    private
+
+
+    # Creates a control point record from the given string.
+    #
+    # @param [String] string a string line containing a control point definition
+    #
+    def control_point(string)
+      cp = ControlPoint.load(string, @current_parent)
+      @current_parent = cp
+    end
+
+    # Creates a dose tracking record from the given string.
+    #
+    # @param [String] string a string line containing a dose tracking definition
+    #
+    def dose_tracking(string)
+      dt = DoseTracking.load(string, @current_parent)
+      @current_parent = dt
+    end
+
+    # Creates an extended plan record from the given string.
+    #
+    # @param [String] string a string line containing an extended plan definition
+    #
+    def extended_plan_def(string)
+      ep = ExtendedPlan.load(string, @current_parent)
+      @current_parent = ep
+    end
+
+    # Creates an extended treatment field record from the given string.
+    #
+    # @param [String] string a string line containing an extended treatment field definition
+    #
+    def extended_treatment_field(string)
+      ef = ExtendedField.load(string, @current_parent)
+      @current_parent = ef
+    end
+
+    # Tests if the path/file is writable, creates any folders if necessary, and opens the file for writing.
+    #
+    # @param [String] file a path/file string
+    # @raise if the given file cannot be created
+    #
+    def open_file(file)
+      # Check if file already exists:
+      if File.exist?(file)
+        # Is (the existing file) writable?
+        unless File.writable?(file)
+          raise "The program does not have permission or resources to create this file: #{file}"
+        end
+      else
+        # File does not exist.
+        # Check if this file's path contains a folder that does not exist, and therefore needs to be created:
+        folders = file.split(File::SEPARATOR)
+        if folders.length > 1
+          # Remove last element (which should be the file string):
+          folders.pop
+          path = folders.join(File::SEPARATOR)
+          # Check if this path exists:
+          unless File.directory?(path)
+            # We need to create (parts of) this path:
+            require 'fileutils'
+            FileUtils.mkdir_p(path)
+          end
+        end
+      end
+      # It has been verified that the file can be created:
+      return File.new(file, 'wb:ISO8859-1')
+    end
+
+    # Creates a prescription site record from the given string.
+    #
+    # @param [String] string a string line containing a prescription site definition
+    #
+    def prescription_site(string)
+      p = Prescription.load(string, @current_parent)
+      @current_parent = p
+    end
+
+    # Creates a site setup record from the given string.
+    #
+    # @param [String] string a string line containing a site setup definition
+    #
+    def site_setup(string)
+      s = SiteSetup.load(string, @current_parent)
+      @current_parent = s
+    end
+
+    # Collects the attributes of this instance.
+    #
+    # @note The CRC is not considered part of the attributes of interest and is excluded
+    # @return [Array<String>] an array of attributes
+    #
+    alias_method :state, :values
+
+    # Creates a treatment field record from the given string.
+    #
+    # @param [String] string a string line containing a treatment field definition
+    #
+    def treatment_field(string)
+      f = Field.load(string, @current_parent)
+      @current_parent = f
+    end
+
+    # Creates a simulation field record from the given string.
+    #
+    # @param [String] string a string line containing a simulation field definition
+    #
+    def simulation_field(string)
+      sf = SimulationField.load(string, @current_parent)
+      @current_parent = sf
+    end
+
+  end
+
 end