plist4r 0.2.1 → 0.2.2

data/.gitignore

@@ -19,3 +19,5 @@ rdoc
 pkg
 
 ## PROJECT::SPECIFIC
+.yardoc
+doc

data/.yardopts

@@ -0,0 +1 @@
+--no-private

data/README.rdoc

@@ -1,12 +1,10 @@
 = plist4r
 
-Welcome to Plist4r, a ruby library for reading and writing plist files.
+Plist4r is a friendly ruby library for reading and writing plist files.
 
-Current status: `Beta`, 0.2.x series
+==== Current status: Beta, 0.2.x series
 
-We can read / write a `:launchd` plist. So thats pretty good. The API interfaces (for the pluggable backends and plist_types) are not going to change any more. The user API seems to work. If anyone would like to review the Plist4r code and give feedback / suggestions. Now is the time (whilst were still in beta).
-
-Future `Stable` will be targeted, 0.3.x series.
+We can read / write various kinds of plist files reliably. The API interfaces (for the pluggable backends and plist_types) are mature. The user API works well. Searchable Documentation is included, complete with examples.
 
 == Installation
 
@@ -36,20 +34,6 @@ Future `Stable` will be targeted, 0.3.x series.
 
   p.save
 
-== Plist 'Types'
-
-A Plist type can be one of `%w[info launchd]`, and is the data type for the whole plist file. A plist data type can provide convenience methods to set Type-specific plist structures. For example "Sockets" in a launchd plist.
-
-Plist types are also useful to disallow keys which arent recognized or supported by that format. Flicking `:unsupported_keys` the Plist4r config will enable this:
-
-  ::Plist4r::Config[:unsupported_keys] = false
-
-Or individually, per plist object with
-
-  plist.unsupported_keys false
-  
-Default is true, which allows editing of any plist keys. We think thats a good choice, since unsupported keys can already be present in existing plist files, which are loadable by Plist4r.
-
 == Plist4r Backends
 
 There are now a number of ruby libraries which can read / write plist files. The aim of plist4r is to utilize the individual best features from all of those libraries, as a series of "backends". And hide those behind a "frontend" that is easy to work with.
@@ -66,6 +50,20 @@ And (as above) the 3 supported Plist file formats are
 
 We believe thats allright for most uses, and decided to include `next_step` for completeness. `NextStep` is also known by other names such as `OpenStep` and (more updated version) `GNU Step`. For example the apple `defaults` command on Mac OS-X will still return `NextStep` formatted plist data.
 
+== Plist4r Types
+
+A Plist type can be one of `%w[plist info launchd]`, and is the data type for the whole plist file. The plist data type provides convenience methods for setting the Type-specific data structures. For example "Sockets" in a launchd plist.
+
+Plist types are also useful to disallow keys which arent recognized or supported by that format. Setting `:strict_keys true` the Plist4r::Config object will globaly enable strict keys.
+
+  ::Plist4r::Config[:unsupported_keys] = true
+
+Or individually, per plist object with
+
+  plist.strict_keys false
+  
+Default is false, which allows editing of any arbitrary plist keys. We think thats a good choice, since unsupported keys can already be present in many existing plist files.
+
 == More Examples
 
 	module ::Plist4r::Backend::MyPlistReaderWriter
@@ -116,11 +114,8 @@ Plist4r has now moved from alpha to beta - quality software. TBC...
 * Regression Tests (rspec)
 * Test harness for the backends
 * Testing of the individual backends
-* Tests for Plist Types
-* RDoc Documentation
-* Script for embedding / inlining Plist4r into Homebrew
 * A Plist Type for Info.plist
-* Command line interface (hopefully mixlib-cli)
+* Tests for Plist Types
 
 == Notes on Patches/Pull Requests
  

data/Rakefile

@@ -47,11 +47,20 @@ end
 
 task :default => :spec
 
-begin
-  require 'yard'
-  YARD::Rake::YardocTask.new
-rescue LoadError
-  task :yardoc do
-    abort "YARD is not available. In order to run yardoc, you must: sudo gem install yard"
-  end
+require 'yard'
+YARD::Rake::YardocTask.new do |t|
+  t.after = lambda { `touch doc/.nojekyll` }
 end
+
+Jeweler::GhpagesTasks.new do |ghpages|
+  ghpages.push_on_release   = true
+  ghpages.set_repo_homepage = true
+  ghpages.user_github_com   = false
+  ghpages.doc_task    = "yard"
+  ghpages.keep_files  = []
+  ghpages.map_paths   = {
+    ".nojekyll" => "",
+    "doc" => "",
+  }
+end
+

data/VERSION

@@ -1 +1 @@
-0.2.1
+0.2.2

data/bin/plist4r

@@ -0,0 +1,8 @@
+#!/usr/bin/env ruby
+
+dir = File.expand_path "../lib", File.dirname(__FILE__)
+$LOAD_PATH.unshift dir unless $LOAD_PATH.include?(dir)
+
+require 'plist4r/application'
+app = Plist4r::Application.new
+

data/lib/plist4r.rb

@@ -4,26 +4,44 @@ $LOAD_PATH.unshift dir unless $LOAD_PATH.include?(dir)
 
 require 'plist4r/plist'
 
+# Almost everything required by Plist4r is fully encapsulated within the {Plist4r} namespace.
+# However there are a few exceptions. We had to add a couple methods to {Object} and {String}.
 module Plist4r
   class << self
+    
+    # Calls Plist4r::Plist.new with the supplied arguments and block
+    # 
+    # @return [Plist4r::Plist] The new Plist object
+    # @see Plist4r::Plist#initialize
+    # @example Create new, empty plist
+    # Plist4r.new => #<Plist4r::Plist:0x111546c @file_format=nil, ...>
     def new *args, &blk
       # puts args.inspect
       return Plist.new *args, &blk
     end
 
+    # Opens a plist file
+    # 
+    # @param [String] filename plist file to load
+    # @return [Plist4r::Plist] The loaded Plist object
+    # @example Load from file
+    # Plist4r.open("example.plist") => #<Plist4r::Plist:0x1152d1c @file_format="xml", ...>
+    # @see Plist4r::Plist#initialize
+    # @see Plist4r::Plist#open
     def open filename, *args, &blk
-      # puts args.inspect
       p = Plist.new filename, *args, &blk
       p.open
     end
-    
+
+    # Given an string of Plist data, peek the first few bytes and detect the file format
+    # 
+    # @param [String] string of plist data
+    # @return [Symbol] A Symbol representing the plist data type. One of: Plist4r::Plist.FileFormats
+    # @see Plist4r::Plist.FileFormats
+    # @example
+    # Plist4r.string_detect_format("{ \"key1\" = \"value1\"; \"key2\" = \"value2\"; }") => :next_step
     def string_detect_format string
-      # puts "in string_detect_format"
-      # puts "string = #{string.inspect}"
-      # s = string.strip
       string.strip! if string[0,1] =~ /\s/
-      # s = string
-      # puts "s = #{s.inspect}"
       case string[0,1]
       when "{","("
         :next_step
@@ -44,6 +62,11 @@ module Plist4r
       end
     end
 
+    # Given a Plist filename, peek the first few bytes and detect the file format
+    # 
+    # @param [String] filename plist file to check
+    # @see Plist4r.string_detect_format
+    # @see Plist4r::Plist.FileFormats
     def file_detect_format filename
       string_detect_format File.read(filename)
     end
@@ -51,6 +74,11 @@ module Plist4r
 end
 
 class String
+
+  # Converts a string of plist data into a new Plist4r::Plist object
+  # 
+  # @return [Plist4r::Plist] The new Plist object
+  # @see Plist4r::Plist#initialize
   def to_plist
     return ::Plist4r.new(:from_string => self)
   end

data/lib/plist4r/application.rb

@@ -0,0 +1,19 @@
+require 'plist4r/config'
+require 'plist4r/options'
+require 'plist4r/commands'
+
+module Plist4r
+  # The Plist4r Application Object. Instantiated for command-line mode
+  # @see Plist4r::CLI
+  class Application
+
+    def initialize *args, &blk
+      @cli = Plist4r::CLI.new
+      Plist4r::Config[:args] = @cli.parse
+
+      puts "Plist4r::Config[:args] = " + Plist4r::Config[:args].inspect
+      @commands = Plist4r::Commands.new
+      @commands.run
+    end
+  end
+end

data/lib/plist4r/backend.rb

@@ -4,9 +4,17 @@ require 'plist4r/backend_base'
 require 'plist4r/mixin/ordered_hash'
 
 module Plist4r
+  # This class is the Backend broker. The purpose of this object is to manage and handle API
+  # calls, passing them over to the appropriate Plist4r backends.
   class Backend
+    # The list of known backend API methods. Any combination or subset of API methods
+    # can be implemented by an individual backend.
+    # @see Plist4r::Backend::Example
     ApiMethods = %w[from_string to_xml to_binary to_next_step open save]
-
+    
+    # A new instance of Backend. A single Backend will exist for the the life of
+    # the Plist object. The attribute @plist is set during initialization and 
+    # refers back to the plist instance object.
     def initialize plist, *args, &blk
       @plist = plist
       @backends = plist.backends.collect do |b| 
@@ -22,7 +30,20 @@ module Plist4r
     end
 
     # vv We need a version of this to call our matrix test harness vv
-
+    # Call a Plist4r API Method. Here, we usually pass a {Plist4r::Plist} object
+    # as one of the parameters, which will also contain all the input data to work on.
+    # 
+    # This function loops through the array of available backends, and calls the
+    # same method on the first backend found to implemente the specific request.
+    # 
+    # If the request fails, the call is re-executed on the next available 
+    # backend.
+    # 
+    # The plist object is updated in-place.
+    # 
+    # @raise if no backend is able to sucessfully execute the request.
+    # @param [Symbol] method_sym The API method call to execute
+    # @param *args Any optional arguments to pass to the backend
     def call method_sym, *args, &blk
       # puts "in call"
       # puts "#{method_sym.inspect} #{args.inspect}"

data/lib/plist4r/backend/example.rb

@@ -1,39 +1,77 @@
 
 require 'plist4r/backend_base'
 
+# An example Plist4r Backend. 
+# These examples demonstrate the common convenience methods which are available to your backend.
+# Its not necessary to implement all of the API methods in your backend.
+# You may selectively implement any single method or method(s).
+# 
+# In the case of {from_string} and {open}, the source plist format is not known beforehand.
+# For those cases you should call {Plist4r.string_detect_format} or {Plist4r.file_detect_format} 
+# as appropriate. Then raise an exception for those situation where backend is unable to continue.
+# 
+# For example, if your backend is only able to load :xml files, then it should raise an exception
+# whenever it encounters :binary or :next_step formatted files. This is intentional.
+# By throwing the error, it means the API call can be picked up and passed on to the next available backend.
+# 
+# @see Plist4r::Backend
 module Plist4r::Backend::Example
   class << self
+    
+    # Parse a String of plist data and store it into the supplied {Plist4r::Plist}
+    # * Please click "View Source" for the example.
+    # @param [Plist4r::Plist] plist The plist object to read the string from
+    # @return [Plist4r::Plist] the same plist object, but updated to match its from_string
+    # @see Plist4r::Plist#from_string
+    # @see Plist4r.string_detect_format
     def from_string plist
       plist_string = plist.from_string
       plist_format = Plist4r.string_detect_format plist.from_string
       unless [:supported_fmt1,:supported_fmt2].include? plist_format
         raise "#{self} - cant convert string of format #{plist_format}"
       end
-      hash = ::ActiveSupport::OrderedHash.new
+      hash = ::Plist4r::OrderedHash.new
       # import / convert plist data into ruby ordered hash
       plist.import_hash hash
       plist.file_format plist_format
       return plist
     end
 
+    # Convert a {Plist4r::Plist} into an "xml" formatted plist String
+    # * Please click "View Source" for the example.
+    # @param [Plist4r::Plist] plist The plist object to convert
+    # @return [String] the xml string
     def to_xml plist
       hash = plist.to_hash
       xml_string = "Convert the plists's nested ruby hash into xml here"
       return xml_string
     end
 
-    def to_binary
+    # Convert a {Plist4r::Plist} into an "binary" formatted plist String
+    # * Please click "View Source" for the example.
+    # @param [Plist4r::Plist] plist The plist object to convert
+    # @return [String] the binary string
+    def to_binary plist
       hash = plist.to_hash
       binary_string = "Convert the plists's nested ruby hash into binary format here"
       return binary_string
     end
 
-    def to_next_step
+    # Convert a {Plist4r::Plist} into a "next_step" formatted plist String
+    # * Please click "View Source" for the example.
+    # @param [Plist4r::Plist] plist The plist object to convert
+    # @return [String] the next_step string
+    def to_next_step plist
       hash = plist.to_hash
       next_step_string = "Convert the plists's nested ruby hash into next_step format here"
       return next_step_string
     end
 
+    # Open a plist file and store the contents into the supplied {Plist4r::Plist}
+    # * Please click "View Source" for the example.
+    # @param [Plist4r::Plist] plist The plist object to convert
+    # @return [String] the next_step string
+    # @see Plist4r.file_detect_format
     def open plist
       filename = plist.filename_path
       file_format = Plist4r.file_detect_format filename
@@ -41,13 +79,16 @@ module Plist4r::Backend::Example
         raise "#{self} - cant load file of format #{file_format}"
       end
       plist_file_as_string = File.read(filename)
-      hash = ::ActiveSupport::OrderedHash.new
+      hash = ::Plist4r::OrderedHash.new
       # import / convert plist data into ruby ordered hash
       plist.import_hash hash
       plist.file_format file_format
       return plist
     end
 
+    # @param [Plist4r::Plist] plist The plist object to read the filename from
+    # @return [Plist4r::Plist] the same plist object, but updated to match the file contents
+    # @see Plist4r::Plist#filename_path
     def save plist
       filename = plist.filename_path
       file_format = plist.file_format || Config[:default_format]

data/lib/plist4r/backend/haml.rb

@@ -1,6 +1,7 @@
 
 require 'plist4r/backend_base'
 
+# Requires Haml. Implements writing and saving for the :xml file format only.
 module Plist4r::Backend::Haml
   class << self
     def to_xml_haml

data/lib/plist4r/backend/libxml4r.rb

@@ -1,10 +1,11 @@
 
 require 'plist4r/backend_base'
 
+# Requires Libxml4r. Implements loading / parsing for the :xml file format only.
 module Plist4r::Backend::Libxml4r
   class << self
     def tree_hash n
-      hash = ::ActiveSupport::OrderedHash.new
+      hash = ::Plist4r::OrderedHash.new
       n_xml_keys = n.nodes["key"]
       n_xml_keys.each do |n|
         k = n.inner_xml
@@ -62,7 +63,7 @@ module Plist4r::Backend::Libxml4r
       else
         root = doc.node["/plist/array"]
         if root
-          ordered_hash = ::ActiveSupport::OrderedHash.new
+          ordered_hash = ::Plist4r::OrderedHash.new
           ordered_hash["Array"] = tree_array root
         end
       end

data/lib/plist4r/backend/plutil.rb

@@ -1,8 +1,11 @@
 
 require 'plist4r/backend_base'
 
+# This backend does not implement any official Plist4r API methods.
+# But can be used to enhance and add functionality to other backends.
+# 
+# (Mac OSX operating systems only)
 module Plist4r::Backend::Plutil
-  # maybe this could be useful as a helper, used by other backends
   class << self
     def convert_file_to_xml
       system "plutil -convert xml1 #{@filename}"

data/lib/plist4r/backend/ruby_cocoa.rb

@@ -1,6 +1,13 @@
 
 require 'plist4r/backend_base'
 
+# This backend only works on MacOSX. It supports everything except {Backend::Example.to_next_step}, 
+# and saving in the :next_step file format. Here we are calling the stock OSX Ruby in a seperate process. 
+# It isolates the runtime from any shared lib (.so) LoadErrors. And allows calling from other installed 
+# Ruby instances (eg REE), which dont usually have RubyCocoa enabled.
+# 
+# This Backend should work for any 10.5 (Leopard), 10.6 (Snow Leopard) Mac OSX distribution.
+# It will do nothing on non-mac platforms (eg Linux, etc).
 module Plist4r::Backend::RubyCocoa
   class << self
     def ruby_cocoa_wrapper_rb
@@ -30,7 +37,7 @@ class OSX::NSObject
     when OSX::NSArray
       self.to_a.map { |x| x.is_a?(OSX::NSObject) ? x.to_ruby : x }
     when OSX::NSDictionary
-      h = ::ActiveSupport::OrderedHash.new
+      h = ::Plist4r::OrderedHash.new
       self.each do |x, y| 
         x = x.to_ruby if x.is_a?(OSX::NSObject)
         y = y.to_ruby if y.is_a?(OSX::NSObject)
@@ -63,7 +70,7 @@ module Plist
     else
       plist_array = ::OSX::NSArray.arrayWithContentsOfFile(filename) unless plist_dict
       raise "Couldnt parse file: #{filename}" unless plist_array
-      plist_dict = ::ActiveSupport::OrderedHash.new
+      plist_dict = ::Plist4r::OrderedHash.new
       plist_dict["Array"] = plist_array.to_ruby
       puts "#{plist_dict.inspect}"
     end
@@ -159,7 +166,7 @@ EOC
       result = ruby_cocoa_exec "open(\"#{filename}\")"
       case result[1].exitstatus
       when 0
-        hash = ::ActiveSupport::OrderedHash.new
+        hash = ::Plist4r::OrderedHash.new
         eval("hash.replace("+result[2]+")")
         plist.import_hash hash
       else