plist4r 0.0.0 → 0.1.0

data/README.rdoc

@@ -1,17 +1,128 @@
 = plist4r
 
-Description goes here.
+Welcome to Plist4r, a ruby library for reading and writing plist files.
 
-== Note on Patches/Pull Requests
+Current project status: in alpha
+
+== Installation
+
+  gem install plist4r
+
+== Quick Start
+
+  Plist4r::Config.default_dir "/Library/LaunchDaemons"
+  filename = "com.github.myservice.plist"
+  p = Plist4r.open(filename)
+
+  p.plist_type
+  # => :launchd
+
+  p.file_format
+  # => :xml
+
+  p.<< do
+    ProgramArguments ["/usr/local/bin/myservice"]
+  end
+
+  p.edit do
+    WatchPaths ["/var/db/myservice"]
+  end
+
+  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.
+
+Backends often only need to be a single ruby file, which implements the Plist4r API methods and calls out to other (existing) ruby code. No single backend has to provide the whole API. Instead, Plist4r simply iterates over all of the backends it knows about, and then calls the first backend that can responds to the API method.
+
+There are just 6 supported API methods
+
+  ApiMethods = %w[from_string to_xml to_binary to_next_step open save]
+
+And (as above) the 3 supported Plist file formats are
+
+  FileFormats = %w[binary xml next_step]
+
+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.
+
+== More Examples
+
+	module ::Plist4r::Backend::MyPlistReaderWriter
+	  # implement some plist4r api calls here
+	end
+
+  # append my backend to the end of the list
+	Plist4r::Config[:backends] << :my_plist_reader_writer
+	
+	# or to the front of the list (executes first)
+	Plist4r::Config[:backends].insert 0 :my_plist_reader_writer
+
+	# The default directory to load / save files from
+	Plist4r::Config.default_path "/Library/Cars"
+	
+	car = Plist4r.new("car.plist")
+	
+	car.load	
+
+	car.file_format :binary
+  # car.plist_type  :car # not implemented *yet*
+	
+	car.save
+	
+	car.<< do
+	  road_legal true
+	  brake_light_color "red"
+	end
+	
+	car.save_as("car2.plist", :binary => true)
+	
+	car.<< do
+	  eyes "blue"
+	end
+	# => Exception, invalid plist key name "Eyes"
+	
+	car.<< do
+	  tyres "Pirelli"
+	end
+	
+	car.to_xml
+	# => xml string
+
+== Remaining Work
+
+Plist4r is currently alpha - quality software. Yet to be completed...
+
+* 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)
+
+== Notes on Patches/Pull Requests
  
-* Fork the project.
+* Fork the project, and create a topic branch as per {these instructions}[http://wiki.opscode.com/display/opscode/Working+with+Git].
 * Make your feature addition or bug fix.
-* Add tests for it. This is important so I don't break it in a
-  future version unintentionally.
-* Commit, do not mess with rakefile, version, or history.
-  (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
-* Send me a pull request. Bonus points for topic branches.
+* Include documentation for it.
+* Include a regression test for it. So I don't break it in a future version unintentionally.
 
 == Copyright
 
-Copyright (c) 2010 dreamcat4. See LICENSE for details.
+Copyright (c) 2010 Dreamcat4. See LICENSE for details.

data/VERSION

@@ -1 +1 @@
-0.0.0
+0.1.0

data/lib/plist4r.rb

@@ -0,0 +1,54 @@
+
+$:.unshift(File.dirname(__FILE__)) unless
+  $:.include?(File.dirname(__FILE__)) || $:.include?(File.expand_path(File.dirname(__FILE__)))
+
+require 'plist4r/plist'
+
+module Plist4r
+  class << self
+    def new *args, &blk
+      puts args.inspect
+      return Plist.new *args, &blk
+    end
+
+    def open filename, *args, &blk
+      puts args.inspect
+      return Plist.new filename, *args, &blk
+    end
+    
+    def string_detect_format string
+      s.strip!
+      case s[0,1]
+      when "{","("
+        :next_step
+      when "b"
+        if s =~ /^bplist/
+          :binary
+        else
+          nil
+        end
+      when "<"
+        if s =~ /^\<\?xml/ && s =~ /\<\!DOCTYPE plist/
+          :xml
+        else
+          nil
+        end
+      else
+        nil
+      end
+    end
+
+    def file_detect_format filename
+      string_detect_format File.read(filename)
+    end
+  end
+end
+
+class String
+  def to_plist
+    return ::Plist4r.new(:from_string => self)
+  end
+end
+
+
+

data/lib/plist4r/backend.rb

@@ -0,0 +1,52 @@
+
+require 'plist4r/config'
+require 'plist4r/mixin/ordered_hash'
+
+class Plist4r::Backend
+  ApiMethods = %w[from_string to_xml to_binary to_next_step open save]
+
+  def initialize plist, *args, &blk
+    @plist = plist
+    @backends = Config[:backends].collect do |b| 
+      case b
+      when Module
+        b
+      when Symbol, String
+        eval "::Plist4r::Backend::#{b.to_s.camelcase}"
+      else
+        raise "Backend #{b.inspect} is of unsupported type: #{b.class}"
+      end
+    end
+  end
+
+  def call method_sym, *args, &blk
+    raise "Unsupported api call #{method_sym.inspect}" unless ApiMethods.include? method_sym.to_s
+    exceptions = []
+    @backends.each do |backend|
+      if backend.respond_to? method_sym
+        begin
+          return backend.send(method_sym, @plist, *args, &blk)
+        rescue LoadError
+          exceptions << $!
+        rescue
+          exceptions << $!
+        end
+      end
+      if Config[:raise_any_failure] && exceptions.first
+        raise exceptions.first
+      end
+    end
+    if exceptions.empty?
+      raise "Plist4r: No backend found to handle method #{method_sym.inspect}. Could not execute method #{method_sym.inspect} on plist #{@plist.inspect}"
+    else
+      $stderr.puts "Couldn't execute method #{method_sym.inspect} on plist #{@plist.inspect}."
+      exceptions.each do |e|
+        $stderr.puts e.inspect
+      end
+      raise exceptions.first
+    end
+  end
+end
+
+
+

data/lib/plist4r/backend/example.rb

@@ -0,0 +1,69 @@
+
+require 'plist4r/backend'
+
+module Plist4r::Backend::Example
+  class << self
+    def from_string plist, string
+      plist_format = Plist4r.string_detect_format string
+      unless [:supported_fmt1,:supported_fmt2].include? plist_format
+        raise "#{self} - cant convert string of format #{plist_format}"
+      end
+      hash = ::ActiveSupport::OrderedHash.new
+      # import / convert plist data into ruby ordered hash
+      plist.import_hash hash
+      plist.file_format = plist_format
+      return plist
+    end
+
+    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
+      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
+      hash = plist.to_hash
+      next_step_string = "Convert the plists's nested ruby hash into next_step format here"
+      return next_step_string
+    end
+
+    def open plist
+      filename = plist.filename_path
+      file_format = Plist4r.file_detect_format filename
+      unless [:supported_fmt1,:supported_fmt2].include? file_format
+        raise "#{self} - cant load file of format #{file_format}"
+      end
+      plist_file_as_string = File.read(filename)
+      hash = ::ActiveSupport::OrderedHash.new
+      # import / convert plist data into ruby ordered hash
+      plist.import_hash hash
+      plist.file_format = file_format
+      return plist
+    end
+
+    def save plist
+      filename = plist.filename_path
+      file_format = plist.file_format || Config[:default_format]
+      unless [:xml,:binary].include? file_format
+        raise "#{self} - cant save file of format #{file_format}"
+      end
+      hash = plist.to_hash
+      output_string = String.new
+      # convert plist's @hash representation into an output_string, 
+      # and formatted to your supported plist file_format(s)
+      File.open(filename,'w') do |out|
+        out << output_string
+      end
+      return true
+    end
+  end
+end
+
+
+

data/lib/plist4r/backend/haml.rb

@@ -0,0 +1,74 @@
+
+require 'plist4r/backend'
+
+module Plist4r::Backend::HamlXmlWriter
+  class << self
+    def to_xml_haml
+      @to_xml_haml ||= <<-'EOC'
+!!! XML UTF-8
+<!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN"
+"http://www.apple.com/DTDs/PropertyList-1.0.dtd" >
+%plist{ :version => '1.0' }
+	%dict
+		- p = Proc.new do |data, block| 
+			- data.each_pair do |k,v|
+				- raise "Invalid input. Hash: #{data.inspect} can only contain keys of type Symbol or String. Found key #{k.inspect}, of type: \"#{k.class}\"" unless [Symbol,String].include? k.class
+				- case v
+					- when TrueClass, FalseClass
+						%key #{k}
+						<#{v}/>
+					- when String
+						%key #{k}
+						%string #{v}
+					- when Fixnum
+						%key #{k}
+						%integer #{v}
+					- when Array
+						%key #{k}
+						%array
+							- v.compact.each do |e|
+								- case e
+									- when TrueClass, FalseClass
+										<#{v}/>
+									- when String
+										%string #{e}
+									- when Fixnum
+										%integer #{v}
+									- when Hash
+										%dict
+											- tab_up ; block.call(e, block) ; tab_down
+									- else
+										- raise "Invalid input. Array: #{v.inspect} can only contain elements of type String (<string>) or Hash (<dict>). Found element: #{e.inspect} of type: \"#{e.class}\""
+					- when Hash
+						%key #{k}
+						%dict
+							- tab_up ; block.call(v, block) ; tab_down
+					- else
+						- raise "Invalid input. Hash: #{data.inspect} can only contain values of type true, false, String (<string>) Fixnum (<integer>) Array (<array>) or Hash (<dict>). Found value: #{v.inspect} of type: \"#{v.class}\""
+		- p.call( @hash, p)
+EOC
+    end
+
+    def to_xml plist
+      require 'haml'
+      # engine = Haml::Engine.new File.read("launchd_plist.haml")
+      engine = Haml::Engine.new to_xml_haml
+      rendered_xml_output = engine.render self
+      File.open(@filename,'w') do |o|
+        o << rendered_xml_output
+      end
+    end
+
+    def save plist
+      file_format = plist.file_format || Config[:default_format]
+      raise "#{self} - cant save file format #{file_format}" unless file_format == :xml
+
+      hash = plist.to_hash
+      filename = plist.filename_path
+      File.open(filename,'w') do |out|
+        out << to_xml plist
+      end
+    end
+  end
+end
+

data/lib/plist4r/backend/libxml4r.rb

@@ -0,0 +1,80 @@
+
+require 'plist4r/backend'
+
+module Plist4r::Backend::Libxml4rXmlReader
+  class << self
+    def tree_hash n
+      hash = ::ActiveSupport::OrderedHash.new
+      n_xml_keys = n.nodes["key"]
+      n_xml_keys.each do |n|
+        k = n.inner_xml
+        vnode = n.next
+        case vnode.name
+        when "true", "false"
+          hash[k] = eval(vnode.name)
+        when "string"
+          hash[k] = vnode.inner_xml
+        when "integer"
+          hash[k] = vnode.inner_xml.to_i
+        when "array"
+          hash[k] = tree_array(vnode)
+        when "dict"
+          hash[k] = tree_hash(vnode)
+        else
+          raise "Unsupported / not recognized plist key: #{vnode.name}"
+        end
+      end
+      return hash
+    end
+
+    def tree_array n
+      array = []
+      n.children.each do |node|
+        case node.name
+        when "true", "false"
+          array << eval(node.name)
+        when "string"
+          array << node.inner_xml
+        when "integer"
+          array << node.inner_xml.to_i
+        when "array"
+          array << tree_array(node)
+        when "dict"
+          array << tree_hash(node)
+        else
+          raise "Unsupported / not recognized plist key: #{vnode.name}"
+        end
+      end
+      return array
+    end
+
+    def parse_plist_xml string
+      require 'libxml4r'
+      ::LibXML::XML.default_keep_blanks = false
+      doc = string.to_xmldoc
+      doc.strip!
+      root = doc.node["/plist/dict"]
+      ordered_hash = tree_hash root
+    end
+
+    def from_string plist, string
+      plist_format = Plist4r.string_detect_format string
+      raise "#{self} - cant convert string of format #{plist_format}" unless plist_format == :xml
+
+      hash = parse_plist_xml string
+      plist.import_hash hash
+      plist.file_format = file_format
+      return plist
+    end
+
+    def open plist
+      filename = plist.filename_path
+      file_format = Plist4r.file_detect_format filename
+      raise "#{self} - cant load file of format #{file_format}" unless file_format == :xml
+
+      return from_string plist, File.read(filename)
+    end
+  end
+end
+
+