dicom 0.8 → 0.9

data/lib/dicom/{super_parent.rb → parent.rb}

@@ -1,17 +1,15 @@
-#    Copyright 2008-2010 Christoffer Lervag
-
 module DICOM
 
   # Super class which contains common code for all parent elements.
   #
   # === Inheritance
   #
-  # Since all parent elements inherit from this class, these methods are available to instances of the following classes:
+  # Since all parents inherit from this class, these methods are available to instances of the following classes:
   # * DObject
   # * Item
   # * Sequence
   #
-  class SuperParent
+  class Parent
 
     # Returns the specified child element.
     # If the requested data element isn't found, nil is returned.
@@ -35,7 +33,7 @@ module DICOM
       return @tags[tag]
     end
 
-    # Adds a DataElement or Sequence instance to self (where self can be either a DObject or Item instance).
+    # Adds a Element or Sequence instance to self (where self can be either a DObject or an Item).
     #
     # === Restrictions
     #
@@ -43,28 +41,37 @@ module DICOM
     #
     # === Parameters
     #
-    # * <tt>element</tt> -- An element (DataElement or Sequence).
+    # * <tt>element</tt> -- An element (Element or Sequence).
+    # * <tt>options</tt> -- A hash of parameters.
+    #
+    # === Options
+    #
+    # * <tt>:no_follow</tt> -- Boolean. If true, the method does not update the parent attribute of the child that is added.
     #
     # === Examples
     #
     #   # Set a new patient's name to the DICOM object:
-    #   obj.add(DataElement.new("0010,0010", "John_Doe"))
+    #   obj.add(Element.new("0010,0010", "John_Doe"))
     #   # Add a previously defined element roi_name to the first item in the following sequence:
-    #   obj["3006,0020"][1].add(roi_name)
+    #   obj["3006,0020"][0].add(roi_name)
     #
-    def add(element)
+    def add(element, options={})
       unless element.is_a?(Item)
         unless self.is_a?(Sequence)
+          # Does the element's binary value need to be reencoded?
+          reencode = true if element.is_a?(Element) && element.endian != stream.str_endian
           # If we are replacing an existing Element, we need to make sure that this Element's parent value is erased before proceeding.
           self[element.tag].parent = nil if exists?(element.tag)
           # Add the element, and set its parent attribute:
           @tags[element.tag] = element
-          element.parent = self
+          element.parent = self unless options[:no_follow]
+          # As the element has been moved in place, perform re-encode if indicated:
+          element.value = element.value if reencode
         else
-          raise "A Sequence is not allowed to have elements added to it. Use the method add_item() instead if the intention is to add an Item."
+          raise "A Sequence is only allowed to have Item elements added to it. Use add_item() instead if the intention is to add an Item."
         end
       else
-        raise "An Item is not allowed as a parameter to the add() method. Use add_item() instead."
+        raise ArgumentError, "An Item is not allowed as a parameter to the add() method. Use add_item() instead."
       end
     end
 
@@ -72,7 +79,8 @@ module DICOM
     # If no existing Item is specified, an empty item will be added.
     #
     # === Notes
-    # * Items are specified by index (starting at 1) instead of a tag string!
+    #
+    # * Items are specified by index (starting at 0) instead of a tag string!
     #
     # === Parameters
     #
@@ -82,6 +90,7 @@ module DICOM
     # === Options
     #
     # * <tt>:index</tt> -- Fixnum. If the Item is to be inserted at a specific index (Item number), this option parameter needs to set.
+    # * <tt>:no_follow</tt> -- Boolean. If true, the method does not update the parent attribute of the child that is added.
     #
     # === Examples
     #
@@ -97,9 +106,9 @@ module DICOM
             if options[:index]
               # This Item will take a specific index, and all existing Items with index higher or equal to this number will have their index increased by one.
               # Check if index is valid (must be an existing index):
-              if options[:index] >= 1
+              if options[:index] >= 0
                 # If the index value is larger than the max index present, we dont need to modify the existing items.
-                unless options[:index] > @tags.length
+                if options[:index] < @tags.length
                   # Extract existing Hash entries to an array:
                   pairs = @tags.sort
                   @tags = Hash.new
@@ -114,27 +123,29 @@ module DICOM
                   end
                 else
                   # Set the index value one higher than the already existing max value:
-                  options[:index] = @tags.length + 1
+                  options[:index] = @tags.length
                 end
                 #,Add the new Item and set its index:
                 @tags[options[:index]] = item
                 item.index = options[:index]
               else
-                raise "The specified index (#{options[:index]}) is out of range (Minimum allowed index value is 1)."
+                raise ArgumentError, "The specified index (#{options[:index]}) is out of range (Must be a positive integer)."
               end
             else
               # Add the existing Item to this Sequence:
-              index = @tags.length + 1
+              index = @tags.length
               @tags[index] = item
               # Let the Item know what index key it's got in it's parent's Hash:
               item.index = index
             end
+            # Set ourself as this item's new parent:
+            item.set_parent(self) unless options[:no_follow]
           else
-            raise "The specified parameter is not an Item. Only Items are allowed to be added to a Sequence."
+            raise ArgumentError, "The specified parameter is not an Item. Only Items are allowed to be added to a Sequence."
           end
         else
           # Create an empty Item with self as parent.
-          index = @tags.length + 1
+          index = @tags.length
           item = Item.new(:parent => self)
         end
       else
@@ -193,7 +204,50 @@ module DICOM
       return total_count
     end
 
-    # Re-encodes the binary data strings of all child DataElement instances.
+    # Iterates the children of this parent, calling <tt>block</tt> for each child.
+    #
+    def each(&block)
+      children.each_with_index(&block)
+    end
+
+    # Iterates the child elements of this parent, calling <tt>block</tt> for each element.
+    #
+    def each_element(&block)
+      elements.each_with_index(&block) if children?
+    end
+
+    # Iterates the child items of this parent, calling <tt>block</tt> for each item.
+    #
+    def each_item(&block)
+      items.each_with_index(&block) if children?
+    end
+
+    # Iterates the child sequences of this parent, calling <tt>block</tt> for each sequence.
+    #
+    def each_sequence(&block)
+      sequences.each_with_index(&block) if children?
+    end
+
+    # Iterates the child tags of this parent, calling <tt>block</tt> for each tag.
+    #
+    def each_tag(&block)
+      @tags.each_key(&block)
+    end
+
+    # Returns all child elements of this parent in an array.
+    # If no child elements exists, returns an empty array.
+    #
+    def elements
+      children.select { |child| child.is_a?(Element)}
+    end
+
+    # A boolean which indicates whether the parent has any child elements.
+    #
+    def elements?
+      elements.any?
+    end
+
+    # Re-encodes the binary data strings of all child Element instances.
     # This also includes all the elements contained in any possible child elements.
     #
     # === Notes
@@ -210,7 +264,7 @@ module DICOM
       children.each do |element|
         if element.children?
           element.encode_children(old_endian)
-        elsif element.is_a?(DataElement)
+        elsif element.is_a?(Element)
           encode_child(element, old_endian)
         end
       end
@@ -221,7 +275,7 @@ module DICOM
     #
     # === Parameters
     #
-    # * <tt>tag</tt> -- A tag string which identifies the data element that is queried (Exception: In the case of an Item query, an index (Fixnum) is used instead).
+    # * <tt>tag</tt> -- A tag string which identifies the data element that is queried (Exception: In the case of an Item query, an index integer is used instead).
     #
     # === Examples
     #
@@ -243,6 +297,7 @@ module DICOM
     # * <tt>group_string</tt> -- A group string (the first 4 characters of a tag string).
     #
     def group(group_string)
+      raise ArgumentError, "Expected String, got #{group_string.class}." unless group_string.is_a?(String)
       found = Array.new
       children.each do |child|
         found << child if child.tag.group == group_string
@@ -290,7 +345,7 @@ module DICOM
         # Formatting: Name (and Tag)
         if element.tag == ITEM_TAG
           # Add index numbers to the Item names:
-          name = "#{element.name} (\##{i+1})"
+          name = "#{element.name} (\##{i})"
         else
           name = element.name
         end
@@ -301,7 +356,7 @@ module DICOM
         # Formatting: Length
         l_s = s*(max_length-element.length.to_s.length)
         # Formatting Value:
-        if element.is_a?(DataElement)
+        if element.is_a?(Element)
           value = element.value.to_s
         else
           value = ""
@@ -344,6 +399,12 @@ module DICOM
       return elements.flatten, index
     end
 
+    # Returns a string containing a human-readable hash representation of the element.
+    #
+    def inspect
+      to_hash.inspect
+    end
+
     # Checks if an element is a parent.
     # Returns true for all parent elements.
     #
@@ -351,8 +412,74 @@ module DICOM
       return true
     end
 
+    # Returns all child items of this parent in an array.
+    # If no child items exists, returns an empty array.
+    #
+    def items
+      children.select { |child| child.is_a?(Item)}
+    end
+
+    # A boolean which indicates whether the parent has any child items.
+    #
+    def items?
+      items.any?
+    end
+
+    # Handles missing methods, which in our case is intended to be dynamic
+    # method names matching DICOM elements in the dictionary.
+    #
+    # === Notes
+    #
+    # * When a dynamic method name is matched against a DICOM element, this method:
+    # * Returns the element if the method name suggests an element retrieval, and the element exists.
+    # * Returns nil if the method name suggests an element retrieval, but the element doesn't exist.
+    # * Returns a boolean, if the method name suggests a query (?), based on whether the matched element exists or not.
+    # * When the method name suggests assignment (=), an element is created with the supplied arguments, or if the argument is nil, the element is removed.
+    #
+    # * When a dynamic method name is not matched against a DICOM element, and the method is not defined by the parent, a NoMethodError is raised.
+    #
+    # === Parameters
+    #
+    # * <tt>sym</tt> -- Symbol. A method name.
+    #
+    def method_missing(sym, *args, &block)
+      # Try to match the method against a tag from the dictionary:
+      tag = LIBRARY.as_tag(sym.to_s) || LIBRARY.as_tag(sym.to_s[0..-2])
+      if tag
+        if sym.to_s[-1..-1] == '?'
+          # Query:
+          return self.exists?(tag)
+        elsif sym.to_s[-1..-1] == '='
+          # Assignment:
+          unless args.length==0 || args[0].nil?
+            # What kind of element to create?
+            if tag == "FFFE,E000"
+              return self.add_item
+            elsif LIBRARY.tags[tag][0][0] == "SQ"
+              return self.add(Sequence.new(tag))
+            else
+              return self.add(Element.new(tag, *args))
+            end
+          else
+            return self.remove(tag)
+          end
+        else
+          # Retrieval:
+          return self[tag] rescue nil
+        end
+      end
+      # Forward to Object#method_missing:
+      super
+    end
+
     # Sets the length of a Sequence or Item.
     #
+    # === Notes
+    #
+    # Currently, Ruby DICOM does not use sequence/item lengths when writing DICOM files
+    # (it sets the length to -1, which means UNDEFINED). Therefore, in practice, it isn't
+    # necessary to use this method, at least as far as writing (valid) DICOM files is concerned.
+    #
     # === Parameters
     #
     # * <tt>new_length</tt> -- Fixnum. The new length to assign to the Sequence/Item.
@@ -368,6 +495,7 @@ module DICOM
     # Prints all child elements of this particular parent.
     # Information such as tag, parent-child relationship, name, vr, length and value is gathered for each data element
     # and processed to produce a nicely formatted output.
+    # Returns an array of formatted data elements.
     #
     # === Parameters
     #
@@ -392,6 +520,7 @@ module DICOM
     # FIXME: Speed. The new print algorithm may seem to be slower than the old one (observed on complex, hiearchical DICOM files). Perhaps it can be optimized?
     #
     def print(options={})
+      elements = Array.new
       # We first gather some properties that is necessary to produce a nicely formatted printout (max_lengths, count_all),
       # then the actual information is gathered (handle_print),
       # and lastly, we pass this information on to the methods which print the output (print_file or print_screen).
@@ -408,6 +537,7 @@ module DICOM
       else
         puts "Notice: Object #{self} is empty (contains no data elements)!"
       end
+      return elements
     end
 
     # Finds and returns the maximum character lengths of name and length which occurs for any child element,
@@ -446,23 +576,42 @@ module DICOM
     # === Parameters
     #
     # * <tt>tag</tt> -- A tag string which specifies the element to be removed (Exception: In the case of an Item removal, an index (Fixnum) is used instead).
+    # * <tt>options</tt> -- A hash of parameters.
+    #
+    # === Options
+    #
+    # * <tt>:no_follow</tt> -- Boolean. If true, the method does not update the parent attribute of the child that is removed.
     #
     # === Examples
     #
-    #   # Remove a DataElement from a DObject instance:
+    #   # Remove a Element from a DObject instance:
     #   obj.remove("0008,0090")
     #   # Remove Item 1 from a specific Sequence:
     #   obj["3006,0020"].remove(1)
     #
-    def remove(tag)
+    def remove(tag, options={})
+      if tag.is_a?(String) or tag.is_a?(Integer)
+        raise ArgumentError, "Argument (#{tag}) is not a valid tag string." if tag.is_a?(String) && !tag.tag?
+        raise ArgumentError, "Negative Integer argument (#{tag}) is not allowed." if tag.is_a?(Integer) && tag < 0
+      else
+        raise ArgumentError, "Expected String or Integer, got #{tag.class}."
+      end
       # We need to delete the specified child element's parent reference in addition to removing it from the tag Hash.
       element = @tags[tag]
       if element
-        element.parent = nil
+        element.parent = nil unless options[:no_follow]
         @tags.delete(tag)
       end
     end
 
+    # Removes all child elements from this parent.
+    #
+    def remove_children
+      @tags.each_key do |tag|
+        remove(tag)
+      end
+    end
+
     # Removes all data elements of the specified group from this parent.
     #
     # === Parameters
@@ -509,29 +658,112 @@ module DICOM
       end
     end
 
-    # Returns the value of a specific DataElement child of this parent.
+    # Returns true if the parent responds to the given method (symbol) (method is defined).
+    # Returns false if the method is not defined.
+    #
+    # === Parameters
+    #
+    # * <tt>method</tt> -- Symbol. A method name who's response is tested.
+    # * <tt>include_private</tt> -- (Not used by ruby-dicom) Boolean. If true, private methods are included in the search.
+    #
+    def respond_to?(method, include_private=false)
+      # Check the library for a tag corresponding to the given method name symbol:
+      return true unless LIBRARY.as_tag(method.to_s).nil?
+      # In case of a query (xxx?) or assign (xxx=), remove last character and try again:
+      return true unless LIBRARY.as_tag(method.to_s[0..-2]).nil?
+      # Forward to Object#respond_to?:
+      super
+    end
+
+    # Returns all child sequences of this parent in an array.
+    # If no child sequences exists, returns an empty array.
+    #
+    def sequences
+      children.select { |child| child.is_a?(Sequence) }
+    end
+
+    # A boolean which indicates whether the parent has any child sequences.
+    #
+    def sequences?
+      sequences.any?
+    end
+
+    # Builds and returns a nested hash containing all children of this parent.
+    # Keys are determined by the key_representation attribute, and data element values are used as values.
+    #
+    # === Notes
+    #
+    # * For private elements, the tag is used for key instead of the key representation, as private tags lacks names.
+    # * For child-less parents, the key_representation attribute is used as value.
+    #
+    def to_hash
+      as_hash = Hash.new
+      unless children?
+        if self.is_a?(DObject)
+          as_hash = {}
+        else
+          as_hash[(self.tag.private?) ? self.tag : self.send(DICOM.key_representation)] = nil
+        end
+      else
+        children.each do |child|
+          if child.tag.private?
+            hash_key = child.tag
+          elsif child.is_a?(Item)
+            hash_key = "Item #{child.index}"
+          else
+            hash_key = child.send(DICOM.key_representation)
+          end
+          if child.is_a?(Element)
+            as_hash[hash_key] = child.to_hash[hash_key]
+          else
+            as_hash[hash_key] = child.to_hash
+          end
+        end
+      end
+      return as_hash
+    end
+
+    # Returns a json string containing a human-readable representation of the element.
+    #
+    def to_json
+      to_hash.to_json
+    end
+
+    # Returns a yaml string containing a human-readable representation of the element.
+    #
+    def to_yaml
+      to_hash.to_yaml
+    end
+
+    # Returns the value of a specific Element child of this parent.
     # Returns nil if the child element does not exist.
     #
     # === Notes
     #
-    # * Only DataElement instances have values. Parent elements like Sequence and Item have no value themselves.
+    # * Only Element instances have values. Parent elements like Sequence and Item have no value themselves.
     #   If the specified <tt>tag</tt> is that of a parent element, <tt>value()</tt> will raise an exception.
     #
     # === Parameters
     #
-    # * <tt>tag</tt> -- A tag string which identifies the child DataElement.
+    # * <tt>tag</tt> -- A tag string which identifies the child Element.
     #
     # === Examples
     #
     #   # Get the patient's name value:
     #   name = obj.value("0010,0010")
     #   # Get the Frame of Reference UID from the first item in the Referenced Frame of Reference Sequence:
-    #   uid = obj["3006,0010"][1].value("0020,0052")
+    #   uid = obj["3006,0010"][0].value("0020,0052")
     #
     def value(tag)
+      if tag.is_a?(String) or tag.is_a?(Integer)
+        raise ArgumentError, "Argument (#{tag}) is not a valid tag string." if tag.is_a?(String) && !tag.tag?
+        raise ArgumentError, "Negative Integer argument (#{tag}) is not allowed." if tag.is_a?(Integer) && tag < 0
+      else
+        raise ArgumentError, "Expected String or Integer, got #{tag.class}."
+      end
       if exists?(tag)
         if @tags[tag].is_parent?
-          raise "Illegal parameter '#{tag}'. Parent elements, like the referenced '#{@tags[tag].class}', have no value. Only DataElement tags are valid."
+          raise ArgumentError, "Illegal parameter '#{tag}'. Parent elements, like the referenced '#{@tags[tag].class}', have no value. Only Element tags are valid."
         else
           return @tags[tag].value
         end
@@ -545,12 +777,12 @@ module DICOM
     private
 
 
-    # Re-encodes the value of a child DataElement (but only if the DataElement encoding is
+    # Re-encodes the value of a child Element (but only if the Element encoding is
     # influenced by a shift in endianness).
     #
     # === Parameters
     #
-    # * <tt>element</tt> -- The DataElement who's value will be re-encoded.
+    # * <tt>element</tt> -- The Element who's value will be re-encoded.
     # * <tt>old_endian</tt> -- The previous endianness of the element binary (used for decoding the value).
     #
     #--
@@ -565,14 +797,13 @@ module DICOM
       else
         # Not all types of tags needs to be reencoded when switching endianness:
         case element.vr
-          when "US", "SS", "UL", "SL", "FL", "FD", "OF", "OW" # Numbers
+          when "US", "SS", "UL", "SL", "FL", "FD", "OF", "OW", "AT" # Numbers or tag reference
             # Re-encode, as long as it is not a group 0002 element (which must always be little endian):
             unless element.tag.group == "0002"
               stream_old_endian = Stream.new(element.bin, old_endian)
-              numbers = stream_old_endian.decode(element.length, element.vr)
-              element.value = numbers
+              formatted_value = stream_old_endian.decode(element.length, element.vr)
+              element.value = formatted_value # (the value=() method also encodes a new binary for the element)
             end
-          #when "AT" # Tag reference
         end
       end
     end