plist4r 0.2.2 → 1.0.0

data/lib/plist4r/mixin/table.rb

@@ -0,0 +1,435 @@
+
+require 'plist4r/mixin/ruby_stdlib'
+
+module Plist4r
+  
+  # A data type representation for tables. The underlying store is an array of arrays (2d).
+  # The addressing scheme is based on (column, row) order, with Range objects to specify 
+  # the bounds of any rectangle of elements withing the table.
+  # 
+  # A variety of methods are provided for manipulating the table data, including flipping, 
+  # inserting, replacing and deleting. Operations can be column-based, row-based, or both.
+  class Table
+    class << self
+      # This class only understands a range addressing scheme, which is used to specify
+      # table locations in a [columns, rows] caresian system starting at col 0, row 0.
+      # 
+      # Convert any Integer numbers into range objects. Check that all input ranges are 
+      # positive, starting (and including) zero as the first index.
+      def sanitize_ranges *ranges
+        sanitized_ranges = []
+        ranges.flatten.each do |range|
+          case range
+          when Range
+            if range.exclude_end?
+              range = range.first..(range.last - 1)
+            end
+          when Integer
+            range = (range..range)
+          else
+            raise "Unsupported type"
+          end
+          if range.first < 0 || range.last < 0
+            raise "range cannot cover negative values"
+          end
+          sanitized_ranges << range
+        end
+        sanitized_ranges
+      end
+    end
+
+    # The value to assign to an empty cell
+    EmptyCell  = nil
+
+    # The range of valid values for which match the empty cell criteria (for which the cell are ignored)
+    EmptyCells = [nil, false]
+
+    # When allocating the arrays for a new table, the minimum size to pad around with empty cells.
+    MinPadSize = 10
+
+    OptionsHash = %w[ size array pad_all fill_all ]
+
+    def initialize *args, &blk
+      @array = []
+
+      case args[0]
+      when nil
+        resize 0..0, 0..0
+
+      when Hash
+        parse_opts args[0]
+
+      when Plist4r::Table
+        %w[ col_range row_range array ].each do |a|
+          self.send a.to_sym, args[0].send(a.to_sym).deep_clone
+        end
+
+      else
+        raise "unsupported type"
+      end
+
+      resize 0..0, 0..0 unless @cr && @rr
+    end
+
+    # Sets up those valid (settable) attributes as found the options hash.
+    # Normally we dont call this method directly. Called from {#initialize}.
+    # @param [Hash <OptionsHash>] opts The options hash, containing keys of {OptionsHash}
+    # @see #initialize
+    def parse_opts opts
+      self.class::OptionsHash.each do |opt|
+        if opts[opt.to_sym]
+          value = opts[opt.to_sym]
+          eval "self.#{opt}(value)"
+        end
+      end
+    end
+
+    def ascii_col_width
+      lines = self.inspect.split "\n"
+      lines[0].length
+    end
+
+    def inspect start_col=0
+      cell_width = Plist4r::Table.new :size => [@cr, 0..0], :fill_all => 5
+      @cr.each do |col|
+        @rr.each do |row|
+          cell_size = @array[col][row].inspect.size
+          cell_width.cell(col, 0, cell_size) if cell_size > cell_width.cell(col,0)
+        end
+      end
+
+      col_pad_pre  = " "
+      col_pad_post = " "
+
+      vert_border = "|"
+      horz_border = "-"
+
+      row_sep = ""
+      row_sep << " " * start_col
+      @cr.each do |col|
+        row_sep << vert_border + horz_border * (col_pad_pre.size + cell_width.cell(col,0) + col_pad_post.size)
+      end
+      row_sep << vert_border
+
+      o = ""
+      o << row_sep << "\n"
+      @rr.each do |row|
+        o << " " * start_col
+        @cr.each do |col|
+          cell_str = vert_border + col_pad_pre + " " * cell_width.cell(col,0) + col_pad_post
+          cell_str[vert_border.size+col_pad_pre.size,@array[col][row].inspect.size] = @array[col][row].inspect
+          o << cell_str
+        end
+        o << vert_border
+        o << "\n"
+        o << row_sep << "\n"
+      end
+      return o
+    end
+
+    def col_range
+      @cr
+    end
+
+    def row_range
+      @rr
+    end
+
+    def cell col, row, value=nil
+      raise "unsupported type" unless col.is_a?(Integer) && row.is_a?(Integer)
+      return nil if col < 0 || row < 0
+
+      case value
+      when nil
+        @array[col][row]
+      else
+        if value.is_a? Plist4r::Table
+          @array[col][row] = value.cell col, row
+        else
+          @array[col][row] = value
+        end
+      end
+    end
+
+    def first value=nil
+      cell @cr.first, @rr.first, value
+    end
+
+    def map col_range=nil, row_range=nil, &blk
+      col_range = @cr if col_range.nil? ; row_range = @rr if row_range.nil?
+      col_range, row_range = Plist4r::Table.sanitize_ranges col_range, row_range
+
+      t = Plist4r::Table.new :size => [col_range, row_range]
+      row_range.each do |row|
+        col_range.each do |col|
+          t.cell col, row, yield(cell(col, row))
+        end
+      end
+      t
+    end
+
+    def each col_range=nil, row_range=nil, &blk
+      col_range = @cr if col_range.nil? ; row_range = @rr if row_range.nil?
+      col_range, row_range = Plist4r::Table.sanitize_ranges col_range, row_range
+      row_range.each do |row|
+        col_range.each do |col|
+          yield cell(col, row)
+        end
+      end
+    end
+
+    def array array=nil
+      case array
+      when nil
+        @array
+      when Array
+        if array.multidim?
+          @array = array
+          auto_size unless @cr && @rr
+        else
+          raise "array type not supported"
+        end
+      else
+        raise "Unsupported type"
+      end
+    end
+
+    def size *args
+      if args.empty?
+        [@cr, @rr]
+      else
+        col_range, row_range = args.flatten
+        resize col_range, row_range
+      end
+    end
+
+    def resize col_range, row_range
+      col_range, row_range = Plist4r::Table.sanitize_ranges col_range, row_range
+
+      @cr = col_range
+      @rr = row_range
+      pad @cr, @rr, EmptyCell
+    end
+
+    def auto_size      
+      ce = @array.size - 1
+      unless @cr && (0..ce).include_range?(@cr)
+        @cr = 0..ce
+      end
+
+      re = 0
+      @array.each do |col|
+        re = col.size - 1 if col.size - 1 > re
+      end
+
+      unless @rr && (0..re).include_range?(@rr)
+        @rr = 0..re
+      end
+    end
+
+    def pad col_range, row_range, data
+      col_range, row_range = Plist4r::Table.sanitize_ranges col_range, row_range
+
+      if EmptyCells.include? data
+        if col_range.end < MinPadSize - 1
+          col_range = 0..(MinPadSize - 1)
+        else
+          col_range = 0..(col_range.end)
+        end
+
+        if row_range.end < MinPadSize - 1
+          row_range = 0..(MinPadSize - 1)
+        else
+          row_range = 0..(row_range.end)
+        end
+      end
+
+      (col_range.end - @array.size + 1).times do
+        @array << []
+      end
+
+      col_range.each do |col|
+        row_range.each do |row|
+          @array[col][row] = data.deep_clone if EmptyCells.include? @array[col][row]
+        end
+      end
+    end
+
+    def pad_all data
+      pad @cr, @rr, data
+    end
+
+    def crop col_range, row_range
+      col_range, row_range = Plist4r::Table.sanitize_ranges col_range, row_range
+
+      pad col_range, row_range, EmptyCell
+      crop_obj = self.class.new :size => [0..(col_range.size - 1), 0..(row_range.size - 1)]
+
+      col_range.each do |col|
+        row_range.each do |row|
+          crop_obj.array[col-col_range.first][row-row_range.first] = @array[col][row].deep_clone
+        end
+      end
+      crop_obj
+    end
+
+    def fill col_range, row_range, data=nil
+      col_range, row_range = Plist4r::Table.sanitize_ranges col_range, row_range
+      data = EmptyCell unless data
+
+      pad col_range, row_range, EmptyCell
+      col_range.each do |c|
+        row_range.each do |r|
+          @array[c][r] = data.deep_clone
+        end
+      end
+    end
+
+    def fill_all data
+      fill @cr, @rr, data
+    end
+
+    def inverse_fill col_range, row_range, data=nil
+      col_range, row_range = Plist4r::Table.sanitize_ranges col_range, row_range
+      data = EmptyCell unless data
+
+      crop_obj = crop col_range, row_range
+      fill @cr, @rr, data
+      replace col_range, row_range, crop_obj
+    end
+
+    def transpose col_range=nil, row_range=nil, keep_bounds=false
+      col_range = @cr if col_range.nil? ; row_range = @rr if row_range.nil?
+      col_range, row_range = Plist4r::Table.sanitize_ranges col_range, row_range
+
+      if col_range == @cr && row_range == @rr && @cr.first == @rr.first
+        @array = @array.transpose
+        if keep_bounds
+          @cr,@rr = [[@cr,@rr].min,[@cr,@rr].min]
+        else
+          @cr,@rr = [@rr, @cr]
+        end
+        self
+      else
+        col_range, row_range = Plist4r::Table.sanitize_ranges col_range, row_range
+
+        crop_obj = crop col_range, row_range
+        crop_obj.transpose
+        fill col_range, row_range, EmptyCell
+
+        ocr,orr = [col_range,row_range]
+        col_range = (ocr.begin)..(ocr.begin+orr.size-1)
+        row_range = (orr.begin)..(orr.begin+ocr.size-1)
+
+        if keep_bounds && col_range.size != row_range.size
+          if ocr.size > orr.size
+            row_range = (row_range.begin)..(orr.end)
+          else
+            col_range = (col_range.begin)..(ocr.end)
+          end
+        end
+        replace col_range, row_range, crop_obj
+      end
+      self
+    end
+
+    def data_replace col_range, row_range, other_data
+      col_range, row_range = Plist4r::Table.sanitize_ranges col_range, row_range
+
+      self.pad col_range, row_range, EmptyCell
+      o = other_data.deep_clone
+
+      if o.col_range.size < col_range.size
+        col_range = (col_range.first)..(row_range.first + o.col_range.size - 1)
+      end
+
+      if o.row_range.size < row_range.size
+        row_range = (row_range.first)..(row_range.first + o.row_range.size - 1)
+      end
+
+      col_range.each do |col|
+        row_range.each do |row|
+          # @array[col][row] = o.array[col-col_range.first+o.col_range.first][row-row_range.first+o.row_range.first].deep_clone
+          cell col, row, o.cell(col-col_range.first+o.col_range.first,row-row_range.first+o.row_range.first).deep_clone
+        end
+      end
+    end
+
+    def replace col_range, row_range, data
+      col_range, row_range = Plist4r::Table.sanitize_ranges col_range, row_range
+
+      case data
+      when Plist4r::Table
+        data_replace col_range, row_range, data
+      else
+        fill col_range, row_range, data
+      end
+      self
+    end
+
+    def col_replace col_range, data
+      col_range = Plist4r::Table.sanitize_ranges col_range
+      replace col_range, @rr.first..@rr.last, data
+    end
+
+    def row_replace row_range, data
+      row_range = Plist4r::Table.sanitize_ranges row_range
+      replace @cr.first..@cr.last, row_range, data
+    end
+
+    def translate col_range, row_range, vector
+      col_range, row_range = Plist4r::Table.sanitize_ranges col_range, row_range
+
+      crop_obj = crop col_range, row_range
+      fill col_range, row_range, EmptyCell
+      col_range = (col_range.begin+vector[0])..(col_range.end+vector[0])
+      row_range = (row_range.begin+vector[1])..(row_range.end+vector[1])
+      replace col_range, row_range, crop_obj
+    end
+
+    def col_insert col_range, row_range, other_data, resize=true
+      col_range, row_range = Plist4r::Table.sanitize_ranges col_range, row_range
+      translate col_range.first..@cr.last, @rr, [col_range.size, 0]
+      replace col_range, row_range, other_data
+      @cr = @cr.first..(@cr.last + col_range.size) if resize
+    end
+
+    def row_insert col_range, row_range, other_data, resize=true
+      col_range, row_range = Plist4r::Table.sanitize_ranges col_range, row_range
+      translate @cr, row_range.first..@rr.last, [0, row_range.size]
+      replace col_range, row_range, other_data
+      @rr = @rr.first..(@rr.last + row_range.size) if resize
+    end
+
+    def cells col_range=nil, row_range=nil, value=nil
+      col_range = @cr if col_range.nil? ; row_range = @rr if row_range.nil?
+      col_range, row_range = Plist4r::Table.sanitize_ranges col_range, row_range
+
+      replace col_range, row_range, value if value
+      self.class.new :array => @array, :size => [col_range, row_range]        
+    end
+
+    def col col_range, value=nil
+      col_range = Plist4r::Table.sanitize_ranges col_range
+
+      case value
+      when nil
+        cells col_range, @rr
+      else
+        col_replace col_range, value
+      end
+    end
+    
+    def row row_range, value=nil
+      row_range = Plist4r::Table.sanitize_ranges row_range
+
+      case value
+      when nil
+        cells @cr, row_range
+      else
+        row_replace row_range, value
+      end
+    end
+
+  end
+end

data/lib/plist4r/plist.rb

@@ -3,18 +3,20 @@ require 'plist4r/mixin/ordered_hash'
 require 'plist4r/mixin/ruby_stdlib'
 require 'plist4r/plist_cache'
 require 'plist4r/plist_type'
-Dir.glob(File.dirname(__FILE__) + "/plist_type/**/*.rb").each {|t| require File.expand_path t}
-require 'plist4r/backend'
+Dir.glob(File.dirname(__FILE__) + "/plist_type/*.rb").each {|t| require File.expand_path t}
+# require 'plist4r/backend'
 
 module Plist4r
+  # See {file:README} and {file:InfoPlistExample} for usage examples. Also see {file:EditingPlistFiles}
   class Plist
     # Recognised keys of the options hash. Passed when instantiating a new Plist Object
     # @see #initialize
     # @see #parse_opts
-    PlistOptionsHash = %w[filename path file_format plist_type strict_keys backends from_string]
-    # The plist file formats, written as symbols. 
+    OptionsHash = %w[filename path file_format plist_type strict_keys backends from_string]
+
+    # The plist file formats, written as symbols.
     # @see #file_format
-    FileFormats      = %w[binary xml next_step]
+    FileFormats      = %w[binary xml gnustep]
 
     # Instantiate a new Plist4r::Plist object. We usually set our per-application defaults in {Plist4r::Config} beforehand.
     # 
@@ -33,9 +35,10 @@ module Plist4r
     # Plist4r::Plist.new({ :filename => "example.plist", :path => plist_working_dir, :backends => ["libxml4r","ruby_cocoa"]})
     #  => #<Plist4r::Plist:0x111546c @file_format=nil, ...>
     # @return [Plist4r::Plist] The new Plist object
+    # @yield An optional block to instance_eval &blk, and apply an edit on creation
     def initialize *args, &blk
       @hash             = ::Plist4r::OrderedHash.new
-      @plist_type       = plist_type :plist
+      plist_type :plist
 
       @strict_keys = Config[:strict_keys]
       @backends         = Config[:backends]
@@ -57,6 +60,8 @@ module Plist4r
       end
       
       @plist_cache ||= PlistCache.new self
+
+      edit(&blk) if block_given?
     end
 
     # Reinitialize plist object from string (overwrites the current contents). Usually called from {Plist#initialize}
@@ -64,7 +69,7 @@ module Plist4r
     # plist = Plist4r::Plist.new
     #  => #<Plist4r::Plist:0x11e161c @file_format=nil, ...>
     # plist.from_string "{ \"key1\" = \"value1\"; \"key2\" = \"value2\"; }"
-    #  => #<Plist4r::Plist:0x11e161c @file_format="next_step", ...>
+    #  => #<Plist4r::Plist:0x11e161c @file_format="gnustep", ...>
     def from_string string=nil
       case string
       when String
@@ -83,7 +88,7 @@ module Plist4r
       end
     end
 
-    # Set or return the filename attribute of the plist object.
+    # Set or return the filename attribute of the plist object. Used in cojunction with the {#path} attribute
     # @param [String] filename either a relative path or absolute
     # @return The plist's filename
     # @see Plist::Plist#open
@@ -122,7 +127,7 @@ module Plist4r
     # @see filename
     # @see path
     def filename_path filename_path=nil
-      case path
+      case filename_path
       when String
         @filename = File.basename filename_path
         @path     = File.dirname  filename_path
@@ -135,7 +140,7 @@ module Plist4r
 
     # The file format of the plist file we are loading / saving. Written as a symbol.
     # One of {Plist4r::Plist.FileFormats}. Defaults to :xml
-    # @param [Symbol, String] file_format Can be :binary, :xml, :next_step
+    # @param [Symbol, String] file_format Can be :binary, :xml, :gnustep
     # @return The file format associated to this current plist object
     # @see Plist4r::Plist.FileFormats
     def file_format file_format=nil
@@ -157,7 +162,7 @@ module Plist4r
     # using an algorithm that stats the plist data. The plist types with the highest stat (score) 
     # is chosen to be the object's "Plist Type".
     # @see Plist4r::PlistType
-    # @return [true] always
+    # @return The plist's known type, written as a symbol. Will be a sublcass of Plist4r::PlistType. Defaults to :plist
     def detect_plist_type
       stat_m = {}
       stat_r = {}
@@ -167,6 +172,7 @@ module Plist4r
           t = eval "::Plist4r::PlistType::#{t.to_s.camelcase}"
         when Class
           t = t
+        when nil
         else
           raise "Unrecognized plist type: #{t.inspect}"
         end
@@ -190,7 +196,6 @@ module Plist4r
       else
         plist_type stat_m[most_matches]
       end
-      return true
     end
 
     # Set or return the plist_type of the current object. We can use this to override the automatic type detection.
@@ -202,7 +207,8 @@ module Plist4r
       begin
         case plist_type
         when Class
-          unless plist_type.is_a? ::Plist4r::PlistType
+          # unless plist_type.is_a? ::Plist4r::PlistType # .is_a? returns false in spec
+          unless plist_type.ancestors.include? Plist4r::PlistType
             raise "Unrecognized Plist type. Class #{plist_type.inspect} isnt inherited from ::Plist4r::PlistType"
           end
         when Symbol, String
@@ -236,16 +242,26 @@ module Plist4r
 
     # An array of strings, symbols or class names which correspond to the active Plist4r::Backends for this object.
     # The priority order in which backends are executed is determined by the in sequence array order.
-    # @param [Array] backends Inherited from {Plist4r::Config}[:backends]
-    # @return The backends for this object
-    # @example Execute haml before resorting to RubyCocoa
+    # @param [Array <Symbol,String>] A new list of backends to use, in Priority order
+    # @return [Array <Symbol>] The plist's backends, each written as a symbol. Must be a sublcass of Plist4r::Backend
+    # Defaults to {Plist4r::Config}[:backends]
+    # @example
     # plist.backends [:haml, :ruby_cocoa]
     # @see Plist4r::Backend
     # @see Plist4r::Backend::Example
     def backends backends=nil
       case backends
       when Array
-        @backends = backends
+        @backends = backends.collect do |b| 
+          case b
+          when Symbol, String
+            eval "Plist4r::Backend::#{b.to_s.camelcase}"
+            b.to_sym
+          when nil
+          else
+            raise "Backend #{b.inspect} is of unsupported type: #{b.class}"
+          end
+        end
       when nil
         @backends
       else
@@ -254,21 +270,21 @@ module Plist4r
     end
   
     # Sets up those valid (settable) plist attributes as found the options hash.
-    # Normally we dont call this method ourselves. Called from {#initialize}.
-    # @param [Hash <PlistOptionsHash>] opts The options hash, containing keys of {PlistOptionsHash}
+    # Normally we dont call this method directly. Called from {#initialize}.
+    # @param [Hash <OptionsHash>] opts The options hash, containing keys of {OptionsHash}
     # @see #initialize
     def parse_opts opts
-      PlistOptionsHash.each do |opt|
+      OptionsHash.each do |opt|
         if opts[opt.to_sym]
           value = opts[opt.to_sym]
-          eval "self.#{opt}(value)"
+          self.send opt, value
         end
       end
     end
 
     # Opens a plist file
     # 
-    # @param [String] filename plist file to load. Uses the @filename attribute when nil
+    # @param [String] filename plist file to load. Uses the {#filename} attribute when nil
     # @return [Plist4r::Plist] The loaded Plist object
     # @example Load from file
     # plist = Plist4r.new
@@ -282,7 +298,7 @@ module Plist4r
     # An alias of {#edit}
     # @example
     #  plist.<< do
-    #    set "PFReleaseVersion" "0.1.1"
+    #    store "PFReleaseVersion" "0.1.1"
     #  end
     # @see #edit
     def << *args, &blk
@@ -291,36 +307,35 @@ module Plist4r
 
     # Edit a plist object. Set or return plist keys. Add or remove a selection of keys.
     # Plist key accessor methods are snake-cased versions of the key string.
-    # @example Set some arbitrary keys and values via {DataMethods#set}
+    # @example Edit some keys and values with {#[]} and {#store}
     #  plist.edit do
-    #    set "PFInstance" "4982394823"
-    #    set "PFReleaseVersion" "0.1.1"
+    #    store "PFInstance" "4982394823"
+    #    store "PFReleaseVersion" "0.1.1"
     #  end
-    # @example Retrieve, and modify a plist key, value pair, with {DataMethods#set} and {DataMethods#value_of}
+    # 
     #  plist.edit do
-    #    new_ver = value_of("PFReleaseVersion") + 0.1
-    #    set "PFReleaseVersion" new_ver
+    #    new_ver = self["PFReleaseVersion"] + 0.1
+    #    store "PFReleaseVersion" new_ver
     #  end
-    # @example Modify a Launchd plist, by camel-cased accessor methods
+    # @example Edit with implicit methods. Calls method_missing()
     #  plist.edit do
-    #    new_ver = value_of("PFReleaseVersion") + 0.1
-    #    set "PFReleaseVersion" new_ver
+    #    new_ver = p_f_release_version + 0.1
+    #    p_f_release_version(new_ver)
     #  end
     def edit *args, &blk
       @plist_type.hash @hash
       instance_eval *args, &blk
-      detect_plist_type
-      @plist_cache.update_checksum
+      detect_plist_type if plist_type == :plist
     end
   
     # Pass down unknown method calls to the selected plist_type, to set or return plist keys.
     # All plist data manipulation API is called through method_missing -> PlistType -> DataMethods.
-    # @example This will actually call {DataMethods#set}
-    # plist.set "CFBundleVersion" "0.1.0"
+    # @example This will actually call {DataMethods#method_missing}
+    # plist.store "CFBundleVersion" "0.1.0"
     # @see Plist4r::DataMethods#method_missing
     # @see #plist_type
     def method_missing method_sym, *args, &blk
-      @plist_type.send method_sym, *args, &blk
+      @plist_type.method_missing method_sym, *args, &blk
     end
   
     # Backend method to set or return all new plist data resulting from a backend API. Used in load operations.
@@ -337,11 +352,204 @@ module Plist4r
         raise "Please use ::Plist4r::OrderedHash.new for your hashes"
       end
     end
-  
-    # The primary storage object for plist data
+
+    # Element Reference — Retrieve the value object corresponding to the key object. If not found, returns nil
+    # @param [Symbol, String] key The plist key name, either a snake-cased symbol, or literal string
+    # @return The value associated with the plist key
+    # @example
+    #   plist["CFBundleIdentifier"]   # => "com.apple.myapp"
+    # @example
+    #   plist[:c_f_bundle_identifier] # => "com.apple.myapp"
+    def [] key
+      @plist_type.set_or_return key
+    end
+
+
+    # Element Assignment — Assign a value to the given plist key
+    # @param [Symbol, String] key The plist key name, either a snake-cased symbol, or literal string
+    # @param value The value to store under the plist key name
+    # @example
+    #   plist["CFBundleIdentifier"]   = "com.apple.myapp"
+    # @example
+    #   plist[:c_f_bundle_identifier] = "com.apple.myapp"
+    def []= key, value
+      store key, value
+    end
+
+    # Element Assignment — Assign a value to the given plist key
+    # @param [Symbol, String] key The plist key name, either a snake-cased symbol, or literal string
+    # @param value The value to store under the plist key name
+    # @example
+    #   plist.store "CFBundleIdentifier",   "com.apple.myapp"
+    # @example
+    #   plist.store :c_f_bundle_identifier, "com.apple.myapp"
+    def store key, value
+      @plist_type.set_or_return key, value
+    end
+
+    # Element selection - Keep selected plist keys and discard others.
+    # @param [Array, *args] keys List of Plist Keys to keep. Can be an array, or method argument list
+    # @yield Keep every key-value pair for which the passed block evaluates to true. Works as per the ruby core classes Hash#select method
+    def select *keys, &blk
+      if block_given?
+        a = @hash.select &blk
+        old_hash = @hash.deep_clone
+        clear
+        a.each do |pair|
+          store pair[0], pair[1]
+        end
+        keys.each do |k|
+          store k, old_hash[k]
+        end
+      else
+        @plist_type.array_dict :select, *keys
+      end
+    end
+
+    # Invokes block &blk once for each key-value pair in plist. Similar to the ruby core classes Array#map.
+    # Replaces the plist keys and values with the [key,value] pairs returned by &blk.
+    # @yield For each iteration of the block, must return a 2-element Array which is a [key,value] pair to replace the original [key,value] pair from the plist.
+    # Key names can be given as either snake_case'd Symbol or camelcased String
+    def map &blk
+      if block_given?
+        old_hash = @hash.deep_clone
+        clear
+
+        old_hash.each do |k,v|
+          pair = yield k,v
+          case pair
+          when Array
+            store pair[0], pair[1]
+          when nil
+          else
+            raise "The supplied block must return plist [key, value] pairs, or nil"
+          end
+        end
+      else
+        raise "No block given"
+      end
+    end
+
+    # Alias for {#map}
+    def collect &blk
+      map &blk
+    end
+
+    # Alias for {#delete}
+    def unselect *keys
+      delete *keys
+    end
+
+    # Delete plist keys from the object.
+    # @param [Array, *args] keys The list of Plist Keys to delete unconditionally. Can be an array, or argument list
+    # Key names can be given as either snake_case'd Symbol or camelcased String
+    # @example
+    #   plist.delete :c_f_bundle_identifier
+    def delete *keys
+      @plist_type.array_dict :unselect, *keys
+    end
+
+    # Conditionally delete plist keys from the object.
+    # @param [Array, *args] keys The list of Plist Keys to delete unconditionally. Can be an array, or argument list
+    # @yield Delete a key-value pair if block evaluates to true.
+    # @example
+    #   plist.delete_if "CFBundleIdentifier"
+    # @example
+    #   plist.delete_if { |k,v| k.length > 20 }
+    # @example
+    #   plist.delete_if { |k,v| k =~ /Identifier/ }
+    def delete_if *keys, &blk
+      delete *keys
+      @hash.delete_if &blk
+      @plist_type.hash @hash
+    end
+
+    # Clears all plist keys and their contents
+    # @example
+    #   plist.clear
+    #   plist.size # => 0
+    def clear
+      @plist_type.array_dict :unselect_all
+    end
+
+    # Merge together plist objects.
+    # Adds the contents of other_plist to the current object, overwriting any entries of the same key name with those from other_plist.
+    # Other attributes (filename, plist_type, file_format, etc) remain unaffected
+    # @param [Plist4r::Plist] other_plist The other plist to merge with
+    def merge! other_plist
+      if plist_type == other_plist.plist_type
+        @hash.merge! other_plist.to_hash
+        @plist_type.hash @hash
+      else
+        raise "plist_type differs, one is #{plist_type.inspect}, and the other is #{plist.plist_type.inspect}"
+      end
+      self
+    end
+
+    # Check if key exists in plist
+    # This is equivalent to the ruby core classes method Hash#include?
+    # @param [String, Symbol] key The plist key name
+    # @return [true,false] True if the plist has the specified key
+    def include? key
+      key.to_s.camelcase if key.class == Symbol
+      @hash.include? key
+    end
+
+    # Alias of {#include?}
+    # @param [String, Symbol] key The plist key name
+    # @return [true,false] True if the plist has the specified key
+    def has_key? key
+      key.to_s.camelcase if key.class == Symbol
+      @hash.has_key? key
+    end
+
+    # This is equivalent to the ruby core classes method Array#empty?
+    def empty?
+      @hash.empty?
+    end
+
+    # This is equivalent to the ruby core classes method Hash#each
+    # @yield A block to execute for each key, value pair in plist
+    # @example
+    #   plist.each do |k,v|
+    #     puts "key = #{k.inspect}, value = #{v.inspect}"
+    #   end
+    def each &blk
+      @hash.each &blk
+    end
+
+    # This is equivalent to the ruby core classes method Array#length
+    # @example
+    #   plist.length # => 14
+    def length
+      @hash.length
+    end
+
+    # This is equivalent to the ruby core classes method Array#size
+    #   plist.size # => 14
+    def size
+      @hash.size
+    end
+
+    # This is equivalent to the ruby core classes method Hash#keys
+    # @example
+    #   plist.keys # => ["Key1", "Key2", "Key3", "etc.."]
+    # @return [Array <String, Symbol>] The keys of the plist
+    def keys
+      @hash.keys
+    end
+
+    # The internal data storage object for the plist data
+    # 
+    # This is a pretty standard (either ActiveSupport or Ruby 1.9) ordered hash.
+    # Key names - regular ruby strings of arbitrary length.
     # 
-    # @return [::Plist4r::OrderedHash] Nested hash of ruby objects. The raw Plist data
-    # @see ::Plist4r::OrderedHash
+    # Values - Must only store generic Ruby objects data such as TrueClass, FalseClass, Integer, Float, String, Time, Array, Hash, and Data
+    # 
+    # Data (NSData / CFData) - see {file:EditingPlistFiles}
+    # 
+    # @return [Plist4r::OrderedHash] Nested hash of ruby objects. The raw Plist data
+    # @see Plist4r::OrderedHash
     # @example 
     # plist = "{ \"key1\" = \"value1\"; \"key2\" = \"value2\"; }".to_plist
     # plist.to_hash => {"key1"=>"value1", "key2"=>"value2"}
@@ -349,7 +557,17 @@ module Plist4r
       @hash
     end
 
-    # Calls out to the plist cache
+    # # The internal ruby data representation for the plist data.
+    # # This is a pretty standard (either ActiveSupport or Ruby 1.9) ordered hash.
+    # # Key names - regular ruby strings of arbitrary length.
+    # # Values - Must only store generic Ruby objects data such as TrueClass, FalseClass, Integer, Float, String, Time, Array, Hash, and Data
+    # # @return [Plist4r::OrderedHash] Nested hash of ruby objects. The raw Plist data
+    # def hash
+    #   @hash
+    # end
+
+    # Export the plist to xml string representation.
+    # Calls through the plist cache
     # 
     # @return [String] An xml string which represents the entire plist, as would be the plist xml file
     # @example 
@@ -359,8 +577,12 @@ module Plist4r
     def to_xml
       @plist_cache.to_xml
     end
-  
-    # @example 
+
+    # Write out a binary string representation of the plist
+    # 
+    # Looking for how to store a bytestream in CFData / NSData? See {file:EditingPlistFiles}
+    # 
+    # @example
     # plist = "{ \"key1\" = \"value1\"; \"key2\" = \"value2\"; }".to_plist
     # plist.to_binary
     #  => "bplist00\322\001\002\003\004Tkey2Tkey1Vvalue2Vvalue1\b\r\022\027\036\000\000\000\000\000\000\001\001\000\000\000\000\000\000\000\005\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000%"
@@ -368,23 +590,21 @@ module Plist4r
       @plist_cache.to_binary
     end
 
-    # @todo Needs a backend
-    #   We are missing a backend for writing out :next_step strings and saving :next_step files to disk
-    def to_next_step
-      @plist_cache.to_next_step
+    # We are missing a backend for writing out plist strings in Gnustep / Nextstep / Openstep format. Contributions appreciated.
+    def to_gnustep
+      @plist_cache.to_gnustep
     end
   
-    # Save plist to #filename
+    # Save plist to {#filename_path}
     # @raise [RuntimeError] if the {#filename} attribute is nil
-    # @see #filename
-    # @see #path
+    # @see #filename_path
     def save
       raise "No filename specified" unless @filename
       @plist_cache.save
     end
   
     # Save the plist under a new filename
-    # @param [String] filename The new file name to save as. If a relative path, will be concactenated to plist.path
+    # @param [String] filename The new file name to save as. If relative, will be appended to {#path}
     # @see #save
     def save_as filename
       @filename = filename
@@ -393,47 +613,5 @@ module Plist4r
   end
 end
 
-module Plist4r
-  # @private
-  class OldPlist
-  
-    def initialize path_prefix, plist_str, &blk
-      plist_str << ".plist" unless plist_str =~ /\.plist$/
-
-      @filename = nil
-      if plist_str =~ /^\//
-        @filename = plist_str
-      else
-        @filename = "#{path_prefix}/#{plist_str}"
-      end
-    
-      @label = @filename.match(/^.*\/(.*)\.plist$/)[1]
-      @shortname = @filename.match(/^.*\.(.*)$/)[1]
-
-      @block = blk
-      @hash = @orig = ::Plist4r::OrderedHash.new
-
-      instance_eval(&@block) if @block
-    end
-
-    def override_plist_keys?
-      return true unless @label == @filename.match(/^.*\/(.*)\.plist$/)[1]
-      vars = self.instance_variables - ["@filename","@label","@shortname","@block","@hash","@obj"]
-      return true unless vars.empty?
-    end
-
-    def finalize
-      if File.exists? @filename
-        if override_plist_keys?
-          # @hash = @obj = ::LibxmlLaunchdPlistParser.new(@filename).plist_struct
-          # eval_plist_block(&@block) if @block
-          # write_plist
-        end
-      else
-        # write_plist
-      end
-    end  
-  end
-end