rtp-connect 1.1 → 1.2

data/lib/rtp-connect/logging.rb

@@ -1,158 +1,155 @@
-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
+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.
+  #
+  # @note For more information, please read the Standard library Logger documentation.
+  #
+  # @example Various logger use cases:
+  #   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"
+  #
+  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
+
+    # Class methods which the Logging module is extended with.
+    #
+    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.
+        #
+        # @param [Logger] target 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).
+        #
+        # @example Inside the RTP module or an external class with 'include RTP::Logging':
+        #   logger.info "message"
+        #
+        # @example 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 getter.
+      #
+      # If a logger instance is not pre-defined, it sets up a Standard
+      # logger or (if in a Rails environment) the Rails logger.
+      #
+      # @example Inside the RTP module (or a class with 'include RTP::Logging'):
+      #   logger # => Logger instance
+      #
+      # @example Accessing from outside the RTP module:
+      #   RTP.logger # => Logger instance
+      #
+      # @return [ProxyLogger] the logger class variable
+      #
+      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
+
+      # The logger object setter.
+      # This method is used to replace the default logger instance with
+      # a custom logger of your own.
+      #
+      # @param [Logger] l a logger instance
+      #
+      # @example Multiple log files
+      #   # Create a logger which ages logfile once it reaches a certain size,
+      #   # leaving 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
+
+    end
+
+    # A logger object getter.
+    # Forwards the call to the logger class method of the Logging module.
+    #
+    # @return [ProxyLogger] the logger class variable
+    #
+    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

@@ -8,11 +8,10 @@ module RTP
 
     # 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.
+    # @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(',')

data/lib/rtp-connect/plan.rb

@@ -1,4 +1,4 @@
-#    Copyright 2011 Christoffer Lervag
+#    Copyright 2011-2012 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
@@ -15,18 +15,17 @@
 #
 module RTP
 
-  # The Plan class is the highest level of objects in the RTPConnect hierarchy,
+  # 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.
   #
-  # === Relations
-  #
-  # * Parent: none
-  # * Children: Prescription, DoseTracking
+  # @note Relations:
+  #   * Parent: nil
+  #   * Children: Prescription, DoseTracking
   #
   class Plan < Record
     include Logging
 
-    # The Record which this instance belongs to (nil by definition)
+    # 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
@@ -61,14 +60,11 @@ module RTP
 
     # 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.
+    # @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:
@@ -107,12 +103,11 @@ module RTP
       return rtp
     end
 
-    # Creates an RTP::Plan instance by parsing a RTPConnect string
-    # (i.e. multiple lines, containing multiple definitions).
+    # Creates a Plan instance by parsing an RTPConnect string.
     #
-    # === Parameters
-    #
-    # * <tt>string</tt> -- An RTPConnect ascii 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")
@@ -133,11 +128,11 @@ module RTP
       return rtp
     end
 
-    # Creates an RTP::Plan instance by reading and parsing an RTPConnect file.
-    #
-    # === Parameters
+    # Creates an Plan instance by reading and parsing an RTPConnect file.
     #
-    # * <tt>file</tt> -- A string which specifies the path of the RTPConnect file to be loaded.
+    # @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)
@@ -181,7 +176,13 @@ module RTP
       @keyword = 'PLAN_DEF'
     end
 
-    # Returns true if the argument is an instance with attributes equal to self.
+    # 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)
@@ -191,26 +192,44 @@ module RTP
 
     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
 
-    # Returns the a properly sorted array of the child records of this instance.
+    # 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
 
-    # Generates a Fixnum hash value for this instance.
+    # 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 the values of this instance in an array.
-    # The values does not include the CRC.
+    # 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 [
@@ -246,13 +265,25 @@ module RTP
 
     # Returns self.
     #
+    # @return [Plan] self
+    #
     def to_plan
       self
     end
 
-    # Writes the Plan object + any hiearchy of child objects,
+    # 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|
@@ -266,9 +297,7 @@ module RTP
     # 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.
+    # @param [String] file a path/file string
     #
     def write(file)
       f = open_file(file)
@@ -278,6 +307,10 @@ module RTP
 
     # 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"
@@ -286,6 +319,8 @@ module RTP
 
     # 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
@@ -298,144 +333,192 @@ module RTP
 
     # 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
@@ -446,20 +529,25 @@ module RTP
 
     # Creates a control point record from the given string.
     #
-    # === Parameters
-    #
-    # * <tt>string</tt> -- An single line string from an RTPConnect ascii file.
+    # @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 an extended treatment field record from the given string.
+    # Creates a dose tracking record from the given string.
     #
-    # === Parameters
+    # @param [String] string a string line containing a dose tracking definition
     #
-    # * <tt>string</tt> -- An single line string from an RTPConnect ascii file.
+    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)
@@ -468,9 +556,8 @@ module RTP
 
     # 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.
+    # @param [String] file a path/file string
+    # @raise if the given file cannot be created
     #
     def open_file(file)
       # Check if file already exists:
@@ -502,9 +589,7 @@ module RTP
 
     # Creates a prescription site record from the given string.
     #
-    # === Parameters
-    #
-    # * <tt>string</tt> -- An single line string from an RTPConnect ascii file.
+    # @param [String] string a string line containing a prescription site definition
     #
     def prescription_site(string)
       p = Prescription.load(string, @current_parent)
@@ -513,24 +598,23 @@ module RTP
 
     # Creates a site setup record from the given string.
     #
-    # === Parameters
-    #
-    # * <tt>string</tt> -- An single line string from an RTPConnect ascii file.
+    # @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
 
-    # Returns the attributes of this instance in an array (for comparison purposes).
+    # 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.
     #
-    # === Parameters
-    #
-    # * <tt>string</tt> -- An single line string from an RTPConnect ascii file.
+    # @param [String] string a string line containing a treatment field definition
     #
     def treatment_field(string)
       f = Field.load(string, @current_parent)