rtp-connect 1.0

data/lib/rtp-connect/logging.rb

@@ -0,0 +1,158 @@
+module RTP
+
+  # This module handles logging functionality.
+  #
+  # Logging functionality uses the Standard library's Logger class.
+  # To properly handle progname, which inside the RTP module is simply
+  # "RTP", in all cases, we use an implementation with a proxy class.
+  #
+  # === Examples
+  #
+  #   require 'rtp-connect'
+  #   include RTP
+  #
+  #   # Logging to STDOUT with DEBUG level:
+  #   RTP.logger = Logger.new(STDOUT)
+  #   RTP.logger.level = Logger::DEBUG
+  #
+  #   # Logging to a file:
+  #   RTP.logger = Logger.new('my_logfile.log')
+  #
+  #   # Combine an external logger with RTP:
+  #   logger = Logger.new(STDOUT)
+  #   logger.progname = "MY_APP"
+  #   RTP.logger = logger
+  #   # Now you can call the logger in the following ways:
+  #   RTP.logger.info "Message"               # => "RTP: Message"
+  #   RTP.logger.info("MY_MODULE) {"Message"} # => "MY_MODULE: Message"
+  #   logger.info "Message"                     # => "MY_APP: Message"
+  #
+  #   For more information, please read the Standard library Logger documentation.
+  #
+  module Logging
+
+    require 'logger'
+
+    # Inclusion hook to make the ClassMethods available to whatever
+    # includes the Logging module, i.e. the RTP module.
+    #
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    module ClassMethods
+
+      # We use our own ProxyLogger to achieve the features wanted for RTP logging,
+      # e.g. using RTP as progname for messages logged within the RTP module
+      # (for both the Standard logger as well as the Rails logger), while still allowing
+      # a custom progname to be used when the logger is called outside the RTP module.
+      #
+      class ProxyLogger
+
+        # Creating the ProxyLogger instance.
+        #
+        # === Parameters
+        #
+        # * <tt>target</tt> -- A Logger instance (e.g. Standard Logger or ActiveSupport::BufferedLogger).
+        #
+        def initialize(target)
+          @target = target
+        end
+
+        # Catches missing methods.
+        # In our case, the methods of interest are the typical logger methods,
+        # i.e. log, info, fatal, error, debug, where the arguments/block are
+        # redirected to the logger in a specific way so that our stated logger
+        # features are achieved (this behaviour depends on the logger
+        # (Rails vs Standard) and in the case of Standard logger,
+        # whether or not a block is given).
+        #
+        # === Examples
+        #
+        #   # Inside the RTP module or an external class with 'include RTP::Logging':
+        #   logger.info "message"
+        #
+        #   # Calling from outside the RTP module:
+        #   RTP.logger.info "message"
+        #
+        def method_missing(method_name, *args, &block)
+          if method_name.to_s =~ /(log|debug|info|warn|error|fatal)/
+            # Rails uses it's own buffered logger which does not
+            # work with progname + block as the standard logger does:
+            if defined?(Rails)
+              @target.send(method_name, "RTP: #{args.first}")
+            elsif block_given?
+              @target.send(method_name, *args) { yield }
+            else
+              @target.send(method_name, "RTP") { args.first }
+            end
+          else
+            @target.send(method_name, *args, &block)
+          end
+        end
+
+      end
+
+      # The logger class variable (must be initialized
+      # before it is referenced by the object setter).
+      #
+      @@logger = nil
+
+      # The logger object setter.
+      # This method is used to replace the default logger instance with
+      # a custom logger of your own.
+      #
+      # === Parameters
+      #
+      # * <tt>l</tt> -- A Logger instance (e.g. a custom standard Logger).
+      #
+      # === Examples
+      #
+      #   # Create a logger which ages logfile once it reaches a certain size,
+      #   # leaves 10 "old log files" with each file being about 1,024,000 bytes:
+      #   RTP.logger = Logger.new('foo.log', 10, 1024000)
+      #
+      def logger=(l)
+        @@logger = ProxyLogger.new(l)
+      end
+
+      # The logger object getter.
+      # Returns the logger class variable, if defined.
+      # If not defined, sets up the Rails logger (if in a Rails environment),
+      # or a Standard logger if not.
+      #
+      # === Examples
+      #
+      #   # Inside the RTP module (or a class with 'include RTP::Logging'):
+      #   logger # => Logger instance
+      #
+      #   # Accessing from outside the RTP module:
+      #   RTP.logger # => Logger instance
+      #
+      def logger
+        @@logger ||= lambda {
+          if defined?(Rails)
+            ProxyLogger.new(Rails.logger)
+          else
+            l = Logger.new(STDOUT)
+            l.level = Logger::INFO
+            ProxyLogger.new(l)
+          end
+        }.call
+      end
+
+    end
+
+    # A logger object getter.
+    # Forwards the call to the logger class method of the Logging module.
+    #
+    def logger
+      self.class.logger
+    end
+
+  end
+
+  # Include the Logging module so we can use RTP.logger.
+  include Logging
+
+end

data/lib/rtp-connect/methods.rb

@@ -0,0 +1,31 @@
+module RTP
+
+  class << self
+
+    #--
+    # Module methods:
+    #++
+
+    # Computes the CRC checksum of the given line and verifies that
+    # this value corresponds with the checksum given at the end of the line.
+    # Raises an error if the two values does not match.
+    #
+    # === Parameters
+    #
+    # * <tt>line</tt> -- An single line string from an RTPConnect ascii file.
+    #
+    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
+
+end

data/lib/rtp-connect/plan.rb

@@ -0,0 +1,545 @@
+#    Copyright 2011 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 of objects in the RTPConnect hierarchy,
+  # and the one the user will interact with to read, modify and write files.
+  #
+  # === Relations
+  #
+  # * Parent: none
+  # * 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).
+    #
+    # === Notes
+    #
+    # * This method does not perform crc verification on the given string.
+    # * If such verification is desired, use methods ::parse or ::read instead.
+    #
+    # === Parameters
+    #
+    # * <tt>string</tt> -- A string containing a plan definition record.
+    #
+    def self.load(string)
+      raise ArgumentError, "Invalid argument 'string'. Expected String, got #{string.class}." unless string.is_a?(String)
+      # Get the quote-less values:
+      values = string.values
+      raise ArgumentError, "Invalid argument 'string': Expected exactly 28 elements, got #{values.length}." unless values.length == 28
+      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[27]
+      return rtp
+    end
+
+    # Creates an RTP::Plan instance by parsing a RTPConnect string
+    # (i.e. multiple lines, containing multiple definitions).
+    #
+    # === Parameters
+    #
+    # * <tt>string</tt> -- An RTPConnect ascii string.
+    #
+    def self.parse(string)
+      raise ArgumentError, "Invalid argument 'string'. Expected String, got #{string.class}." unless string.is_a?(String)
+      raise ArgumentError, "Invalid argument 'string': String too short to contain valid RTP data (length: #{string.length})." if string.length < 10
+      #lines = string.lines
+      lines = string.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 RTP::Plan instance by reading and parsing an RTPConnect file.
+    #
+    # === Parameters
+    #
+    # * <tt>file</tt> -- A string which specifies the path of the RTPConnect file to be loaded.
+    #
+    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") { |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
+
+    # Adds a prescription site record to this instance.
+    #
+    def add_prescription(child)
+      raise ArgumentError, "Invalid argument 'child'. Expected RTP::Prescription, got #{child.class}." unless child.is_a?(RTP::Prescription)
+      @prescriptions << child
+    end
+
+    # Returns the a properly sorted array of the child records of this instance.
+    #
+    def children
+      return [@prescriptions, @dose_trackings].flatten.compact
+    end
+
+    # Returns the values of this instance in an array.
+    # The values does not include the CRC.
+    #
+    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
+
+    # Writes the Plan object + any hiearchy of child objects,
+    # to a properly formatted RTPConnect ascii string.
+    #
+    def to_str
+      str = encode #.force_encoding('utf-8')
+      children.each do |child|
+        str += child.to_str #.force_encoding('utf-8')
+      end
+      return str
+    end
+
+    # Writes the Plan object, along with its hiearchy of child objects,
+    # to a properly formatted RTPConnect ascii file.
+    #
+    # === Parameters
+    #
+    # * <tt>file</tt> -- A path/file string.
+    #
+    def write(file)
+      f = open_file(file)
+      f.write(to_str)
+      f.close
+    end
+
+    # Sets the keyword attribute.
+    #
+    def keyword=(value)
+      raise ArgumentError, "Invalid argument 'value'. Expected String, got #{value.class}." unless value.is_a?(String)
+      raise ArgumentError, "Invalid keyword. Expected 'PLAN_DEF', got #{value}." unless value.upcase == "PLAN_DEF"
+      @keyword = value
+    end
+
+    # Sets the patient_id attribute.
+    #
+    def patient_id=(value)
+      raise ArgumentError, "Invalid argument 'value'. Expected String, got #{value.class}." unless value.is_a?(String)
+      @patient_id = value
+    end
+
+    # Sets the patient_last_name attribute.
+    #
+    def patient_last_name=(value)
+      raise ArgumentError, "Invalid argument 'value'. Expected String, got #{value.class}." unless value.is_a?(String)
+      @patient_last_name = value
+    end
+
+    # Sets the patient_first_name attribute.
+    #
+    def patient_first_name=(value)
+      raise ArgumentError, "Invalid argument 'value'. Expected String, got #{value.class}." unless value.is_a?(String)
+      @patient_first_name = value
+    end
+
+    # Sets the patient_middle_initial attribute.
+    #
+    def patient_middle_initial=(value)
+      raise ArgumentError, "Invalid argument 'value'. Expected String, got #{value.class}." unless value.is_a?(String)
+      @patient_middle_initial = value
+    end
+
+    # Sets the plan_id attribute.
+    #
+    def plan_id=(value)
+      raise ArgumentError, "Invalid argument 'value'. Expected String, got #{value.class}." unless value.is_a?(String)
+      @plan_id = value
+    end
+
+    # Sets the plan_date attribute.
+    #
+    def plan_date=(value)
+      raise ArgumentError, "Invalid argument 'value'. Expected String, got #{value.class}." unless value.is_a?(String)
+      @plan_date = value
+    end
+
+    # Sets the plan_time attribute.
+    #
+    def plan_time=(value)
+      raise ArgumentError, "Invalid argument 'value'. Expected String, got #{value.class}." unless value.is_a?(String)
+      @plan_time = value
+    end
+
+    # Sets the course_id attribute.
+    #
+    def course_id=(value)
+      raise ArgumentError, "Invalid argument 'value'. Expected String, got #{value.class}." unless value.is_a?(String)
+      @course_id = value
+    end
+
+    # Sets the diagnosis attribute.
+    #
+    def diagnosis=(value)
+      raise ArgumentError, "Invalid argument 'value'. Expected String, got #{value.class}." unless value.is_a?(String)
+      @diagnosis = value
+    end
+
+    # Sets the md_last_name attribute.
+    #
+    def md_last_name=(value)
+      raise ArgumentError, "Invalid argument 'value'. Expected String, got #{value.class}." unless value.is_a?(String)
+      @md_last_name = value
+    end
+
+    # Sets the md_first_name attribute.
+    #
+    def md_first_name=(value)
+      raise ArgumentError, "Invalid argument 'value'. Expected String, got #{value.class}." unless value.is_a?(String)
+      @md_first_name = value
+    end
+
+    # Sets the md_middle_initial attribute.
+    #
+    def md_middle_initial=(value)
+      raise ArgumentError, "Invalid argument 'value'. Expected String, got #{value.class}." unless value.is_a?(String)
+      @md_middle_initial = value
+    end
+
+    # Sets the md_approve_last_name attribute.
+    #
+    def md_approve_last_name=(value)
+      raise ArgumentError, "Invalid argument 'value'. Expected String, got #{value.class}." unless value.is_a?(String)
+      @md_approve_last_name = value
+    end
+
+    # Sets the md_approve_first_name attribute.
+    #
+    def md_approve_first_name=(value)
+      raise ArgumentError, "Invalid argument 'value'. Expected String, got #{value.class}." unless value.is_a?(String)
+      @md_approve_first_name = value
+    end
+
+    # Sets the md_approve_middle_initial attribute.
+    #
+    def md_approve_middle_initial=(value)
+      raise ArgumentError, "Invalid argument 'value'. Expected String, got #{value.class}." unless value.is_a?(String)
+      @md_approve_middle_initial = value
+    end
+
+    # Sets the phy_approve_last_name attribute.
+    #
+    def phy_approve_last_name=(value)
+      raise ArgumentError, "Invalid argument 'value'. Expected String, got #{value.class}." unless value.is_a?(String)
+      @phy_approve_last_name = value
+    end
+
+    # Sets the phy_approve_first_name attribute.
+    #
+    def phy_approve_first_name=(value)
+      raise ArgumentError, "Invalid argument 'value'. Expected String, got #{value.class}." unless value.is_a?(String)
+      @phy_approve_first_name = value
+    end
+
+    # Sets the phy_approve_middle_initial attribute.
+    #
+    def phy_approve_middle_initial=(value)
+      raise ArgumentError, "Invalid argument 'value'. Expected String, got #{value.class}." unless value.is_a?(String)
+      @phy_approve_middle_initial = value
+    end
+
+    # Sets the author_last_name attribute.
+    #
+    def author_last_name=(value)
+      raise ArgumentError, "Invalid argument 'value'. Expected String, got #{value.class}." unless value.is_a?(String)
+      @author_last_name = value
+    end
+
+    # Sets the author_first_name attribute.
+    #
+    def author_first_name=(value)
+      raise ArgumentError, "Invalid argument 'value'. Expected String, got #{value.class}." unless value.is_a?(String)
+      @author_first_name = value
+    end
+
+    # Sets the author_middle_initial attribute.
+    #
+    def author_middle_initial=(value)
+      raise ArgumentError, "Invalid argument 'value'. Expected String, got #{value.class}." unless value.is_a?(String)
+      @author_middle_initial = value
+    end
+
+    # Sets the rtp_mfg attribute.
+    #
+    def rtp_mfg=(value)
+      raise ArgumentError, "Invalid argument 'value'. Expected String, got #{value.class}." unless value.is_a?(String)
+      @rtp_mfg = value
+    end
+
+    # Sets the rtp_model attribute.
+    #
+    def rtp_model=(value)
+      raise ArgumentError, "Invalid argument 'value'. Expected String, got #{value.class}." unless value.is_a?(String)
+      @rtp_model = value
+    end
+
+    # Sets the rtp_version attribute.
+    #
+    def rtp_version=(value)
+      raise ArgumentError, "Invalid argument 'value'. Expected String, got #{value.class}." unless value.is_a?(String)
+      @rtp_version = value
+    end
+
+    # Sets the rtp_if_protocol attribute.
+    #
+    def rtp_if_protocol=(value)
+      raise ArgumentError, "Invalid argument 'value'. Expected String, got #{value.class}." unless value.is_a?(String)
+      @rtp_if_protocol = value
+    end
+
+    # Sets the rtp_if_version attribute.
+    #
+    def rtp_if_version=(value)
+      raise ArgumentError, "Invalid argument 'value'. Expected String, got #{value.class}." unless value.is_a?(String)
+      @rtp_if_version = value
+    end
+
+
+    private
+
+
+    # Creates a control point record from the given string.
+    #
+    # === Parameters
+    #
+    # * <tt>string</tt> -- An single line string from an RTPConnect ascii file.
+    #
+    def control_point(string)
+      cp = ControlPoint.load(string, @current_parent)
+      @current_parent = cp
+    end
+
+    # Creates an extended treatment field record from the given string.
+    #
+    # === Parameters
+    #
+    # * <tt>string</tt> -- An single line string from an RTPConnect ascii file.
+    #
+    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.
+    #
+    # === Parameters
+    #
+    # * <tt>file</tt> -- A path/file string.
+    #
+    def open_file(file)
+      # Check if file already exists:
+      if File.exist?(file)
+        # Is (the existing file) writable?
+        unless File.writable?(file)
+          #logger.error("The program does not have permission or resources to create this file: #{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")
+    end
+
+    # Creates a prescription site record from the given string.
+    #
+    # === Parameters
+    #
+    # * <tt>string</tt> -- An single line string from an RTPConnect ascii file.
+    #
+    def prescription_site(string)
+      p = Prescription.load(string, @current_parent)
+      @current_parent = p
+    end
+
+    # Creates a site setup record from the given string.
+    #
+    # === Parameters
+    #
+    # * <tt>string</tt> -- An single line string from an RTPConnect ascii file.
+    #
+    def site_setup(string)
+      s = SiteSetup.load(string, @current_parent)
+      @current_parent = s
+    end
+
+    # Creates a treatment field record from the given string.
+    #
+    # === Parameters
+    #
+    # * <tt>string</tt> -- An single line string from an RTPConnect ascii file.
+    #
+    def treatment_field(string)
+      f = Field.load(string, @current_parent)
+      @current_parent = f
+    end
+
+  end
+
+end