Merge pull request #795 from Homebrew/plist-readme

Add vendored `plist` to ReadMe.

7 files changed, 370 insertions, 104 deletions

diff --git a/Library/Homebrew/cask/lib/hbc.rb b/Library/Homebrew/cask/lib/hbc.rb
index a9a23f997..29fad59af 100644
--- a/Library/Homebrew/cask/lib/hbc.rb
+++ b/Library/Homebrew/cask/lib/hbc.rb
@@ -36,7 +36,7 @@ require "hbc/utils"
 require "hbc/verify"
 require "hbc/version"
 
-require "vendor/plist"
+require "vendor/plist/plist"
 
 module Hbc
   include Hbc::Locations
diff --git a/Library/Homebrew/cask/spec/cask/system_command_result_spec.rb b/Library/Homebrew/cask/spec/cask/system_command_result_spec.rb
new file mode 100644
index 000000000..7eb4fb722
--- /dev/null
+++ b/Library/Homebrew/cask/spec/cask/system_command_result_spec.rb
@@ -0,0 +1,49 @@
+require "spec_helper"
+
+describe Hbc::SystemCommand::Result do
+  describe "::_parse_plist" do
+    let(:command) { Hbc::SystemCommand.new("/usr/bin/true", {}) }
+    let(:hdiutil_output) {
+      <<-EOS.undent
+        Hello there! I am in no way XML am I?!?!
+
+          That's a little silly... you were expexting XML here!
+
+        What is a parser to do?
+
+        Hopefully <not> explode!
+
+        <?xml version="1.0" encoding="UTF-8"?>
+        <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+        <plist version="1.0">
+        <dict>
+          <key>system-entities</key>
+          <array>
+            <dict>
+              <key>content-hint</key>
+              <string>Apple_HFS</string>
+              <key>dev-entry</key>
+              <string>/dev/disk3s2</string>
+              <key>mount-point</key>
+              <string>/private/tmp/dmg.BhfS2g</string>
+              <key>potentially-mountable</key>
+              <true/>
+              <key>unmapped-content-hint</key>
+              <string>Apple_HFS</string>
+              <key>volume-kind</key>
+              <string>hfs</string>
+            </dict>
+          </array>
+        </dict>
+        </plist>
+      EOS
+    }
+
+    it "ignores garbage output before xml starts" do
+      parsed = described_class._parse_plist(command, hdiutil_output)
+
+      expect(parsed.keys).to eq(["system-entities"])
+      expect(parsed["system-entities"].length).to eq(1)
+    end
+  end
+end
diff --git a/Library/Homebrew/cask/test/plist/parser_test.rb b/Library/Homebrew/cask/test/plist/parser_test.rb
index a73d1f7f5..173541a72 100644
--- a/Library/Homebrew/cask/test/plist/parser_test.rb
+++ b/Library/Homebrew/cask/test/plist/parser_test.rb
@@ -2,51 +2,51 @@ require "test_helper"
 
 describe Plist do
   it "parses some hdiutil output okay" do
-    hdiutil_output = <<-HDIUTILOUTPUT
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
-<plist version="1.0">
-<dict>
-  <key>system-entities</key>
-  <array>
-    <dict>
-      <key>content-hint</key>
-      <string>Apple_partition_map</string>
-      <key>dev-entry</key>
-      <string>/dev/disk3s1</string>
-      <key>potentially-mountable</key>
-      <false/>
-      <key>unmapped-content-hint</key>
-      <string>Apple_partition_map</string>
-    </dict>
-    <dict>
-      <key>content-hint</key>
-      <string>Apple_partition_scheme</string>
-      <key>dev-entry</key>
-      <string>/dev/disk3</string>
-      <key>potentially-mountable</key>
-      <false/>
-      <key>unmapped-content-hint</key>
-      <string>Apple_partition_scheme</string>
-    </dict>
-    <dict>
-      <key>content-hint</key>
-      <string>Apple_HFS</string>
-      <key>dev-entry</key>
-      <string>/dev/disk3s2</string>
-      <key>mount-point</key>
-      <string>/private/tmp/dmg.BhfS2g</string>
-      <key>potentially-mountable</key>
-      <true/>
-      <key>unmapped-content-hint</key>
-      <string>Apple_HFS</string>
-      <key>volume-kind</key>
-      <string>hfs</string>
-    </dict>
-  </array>
-</dict>
-</plist>
-    HDIUTILOUTPUT
+    hdiutil_output = <<-EOS.undent
+      <?xml version="1.0" encoding="UTF-8"?>
+      <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+      <plist version="1.0">
+      <dict>
+        <key>system-entities</key>
+        <array>
+          <dict>
+            <key>content-hint</key>
+            <string>Apple_partition_map</string>
+            <key>dev-entry</key>
+            <string>/dev/disk3s1</string>
+            <key>potentially-mountable</key>
+            <false/>
+            <key>unmapped-content-hint</key>
+            <string>Apple_partition_map</string>
+          </dict>
+          <dict>
+            <key>content-hint</key>
+            <string>Apple_partition_scheme</string>
+            <key>dev-entry</key>
+            <string>/dev/disk3</string>
+            <key>potentially-mountable</key>
+            <false/>
+            <key>unmapped-content-hint</key>
+            <string>Apple_partition_scheme</string>
+          </dict>
+          <dict>
+            <key>content-hint</key>
+            <string>Apple_HFS</string>
+            <key>dev-entry</key>
+            <string>/dev/disk3s2</string>
+            <key>mount-point</key>
+            <string>/private/tmp/dmg.BhfS2g</string>
+            <key>potentially-mountable</key>
+            <true/>
+            <key>unmapped-content-hint</key>
+            <string>Apple_HFS</string>
+            <key>volume-kind</key>
+            <string>hfs</string>
+          </dict>
+        </array>
+      </dict>
+      </plist>
+    EOS
 
     parsed = Plist.parse_xml(hdiutil_output)
 
@@ -59,47 +59,6 @@ describe Plist do
                                                                     ]
   end
 
-  it "can ignore garbage output before xml starts" do
-    hdiutil_output = <<-HDIUTILOUTPUT
-Hello there! I am in no way XML am I?!?!
-
-  That's a little silly... you were expexting XML here!
-
-What is a parser to do?
-
-Hopefully <not> explode!
-
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
-<plist version="1.0">
-<dict>
-  <key>system-entities</key>
-  <array>
-    <dict>
-      <key>content-hint</key>
-      <string>Apple_HFS</string>
-      <key>dev-entry</key>
-      <string>/dev/disk3s2</string>
-      <key>mount-point</key>
-      <string>/private/tmp/dmg.BhfS2g</string>
-      <key>potentially-mountable</key>
-      <true/>
-      <key>unmapped-content-hint</key>
-      <string>Apple_HFS</string>
-      <key>volume-kind</key>
-      <string>hfs</string>
-    </dict>
-  </array>
-</dict>
-</plist>
-    HDIUTILOUTPUT
-
-    parsed = Plist.parse_xml(hdiutil_output)
-
-    parsed.keys.must_equal ["system-entities"]
-    parsed["system-entities"].length.must_equal 1
-  end
-
   it "does not choke on empty input" do
     Plist.parse_xml("").must_equal {}
   end
diff --git a/Library/Homebrew/vendor/README.md b/Library/Homebrew/vendor/README.md
index 848ce703f..b3fff49f4 100644
--- a/Library/Homebrew/vendor/README.md
+++ b/Library/Homebrew/vendor/README.md
@@ -1,7 +1,9 @@
 Vendored Dependencies
 =====================
 
-* [okjson](https://github.com/kr/okjson), version 43.
+* [okjson](https://github.com/kr/okjson), version 43
+
+* [plist](https://github.com/bleything/plist), version 3.1.0
 
 * [ruby-macho](https://github.com/Homebrew/ruby-macho), version 0.2.5
 
@@ -29,6 +31,29 @@ Vendored Dependencies
 > OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 > THE SOFTWARE.
 
+### plist
+
+> Copyright (c) 2006-2010, Ben Bleything and Patrick May
+>
+> Permission is hereby granted, free of charge, to any person obtaining
+> a copy of this software and associated documentation files (the
+> "Software"), to deal in the Software without restriction, including
+> without limitation the rights to use, copy, modify, merge, publish,
+> distribute, sublicense, and/or sell copies of the Software, and to
+> permit persons to whom the Software is furnished to do so, subject to
+> the following conditions:
+>
+> The above copyright notice and this permission notice shall be included
+> in all copies or substantial portions of the Software.
+>
+> THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY
+> KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
+> WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+> NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+> LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+> OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+> WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
 ### ruby-macho
 
 > The MIT License
diff --git a/Library/Homebrew/vendor/plist/plist.rb b/Library/Homebrew/vendor/plist/plist.rb
new file mode 100755
index 000000000..0b828afc6
--- /dev/null
+++ b/Library/Homebrew/vendor/plist/plist.rb
@@ -0,0 +1,21 @@
+#!/usr/bin/env ruby
+#
+# = plist
+#
+# This is the main file for plist. Everything interesting happens in
+# Plist and Plist::Emit.
+#
+# Copyright 2006-2010 Ben Bleything and Patrick May
+# Distributed under the MIT License
+#
+
+require 'base64'
+require 'cgi'
+require 'stringio'
+
+require_relative 'plist/generator'
+require_relative 'plist/parser'
+
+module Plist
+  VERSION = '3.1.0'
+end
diff --git a/Library/Homebrew/vendor/plist/plist/generator.rb b/Library/Homebrew/vendor/plist/plist/generator.rb
new file mode 100644
index 000000000..3b84c301f
--- /dev/null
+++ b/Library/Homebrew/vendor/plist/plist/generator.rb
@@ -0,0 +1,222 @@
+#!/usr/bin/env ruby
+#
+# = plist
+#
+# Copyright 2006-2010 Ben Bleything and Patrick May
+# Distributed under the MIT License
+#
+
+module Plist ; end
+
+# === Create a plist
+# You can dump an object to a plist in one of two ways:
+#
+# * <tt>Plist::Emit.dump(obj)</tt>
+# * <tt>obj.to_plist</tt>
+#   * This requires that you mixin the <tt>Plist::Emit</tt> module, which is already done for +Array+ and +Hash+.
+#
+# The following Ruby classes are converted into native plist types:
+#   Array, Bignum, Date, DateTime, Fixnum, Float, Hash, Integer, String, Symbol, Time, true, false
+# * +Array+ and +Hash+ are both recursive; their elements will be converted into plist nodes inside the <array> and <dict> containers (respectively).
+# * +IO+ (and its descendants) and +StringIO+ objects are read from and their contents placed in a <data> element.
+# * User classes may implement +to_plist_node+ to dictate how they should be serialized; otherwise the object will be passed to <tt>Marshal.dump</tt> and the result placed in a <data> element.
+#
+# For detailed usage instructions, refer to USAGE[link:files/docs/USAGE.html] and the methods documented below.
+module Plist::Emit
+  # Helper method for injecting into classes.  Calls <tt>Plist::Emit.dump</tt> with +self+.
+  def to_plist(envelope = true)
+    return Plist::Emit.dump(self, envelope)
+  end
+
+  # Helper method for injecting into classes.  Calls <tt>Plist::Emit.save_plist</tt> with +self+.
+  def save_plist(filename)
+    Plist::Emit.save_plist(self, filename)
+  end
+
+  # The following Ruby classes are converted into native plist types:
+  #   Array, Bignum, Date, DateTime, Fixnum, Float, Hash, Integer, String, Symbol, Time
+  #
+  # Write us (via RubyForge) if you think another class can be coerced safely into one of the expected plist classes.
+  #
+  # +IO+ and +StringIO+ objects are encoded and placed in <data> elements; other objects are <tt>Marshal.dump</tt>'ed unless they implement +to_plist_node+.
+  #
+  # The +envelope+ parameters dictates whether or not the resultant plist fragment is wrapped in the normal XML/plist header and footer.  Set it to false if you only want the fragment.
+  def self.dump(obj, envelope = true)
+    output = plist_node(obj)
+
+    output = wrap(output) if envelope
+
+    return output
+  end
+
+  # Writes the serialized object's plist to the specified filename.
+  def self.save_plist(obj, filename)
+    File.open(filename, 'wb') do |f|
+      f.write(obj.to_plist)
+    end
+  end
+
+  private
+  def self.plist_node(element)
+    output = ''
+
+    if element.respond_to? :to_plist_node
+      output << element.to_plist_node
+    else
+      case element
+      when Array
+        if element.empty?
+          output << "<array/>\n"
+        else
+          output << tag('array') {
+            element.collect {|e| plist_node(e)}
+          }
+        end
+      when Hash
+        if element.empty?
+          output << "<dict/>\n"
+        else
+          inner_tags = []
+
+          element.keys.sort_by{|k| k.to_s }.each do |k|
+            v = element[k]
+            inner_tags << tag('key', CGI::escapeHTML(k.to_s))
+            inner_tags << plist_node(v)
+          end
+
+          output << tag('dict') {
+            inner_tags
+          }
+        end
+      when true, false
+        output << "<#{element}/>\n"
+      when Time
+        output << tag('date', element.utc.strftime('%Y-%m-%dT%H:%M:%SZ'))
+      when Date # also catches DateTime
+        output << tag('date', element.strftime('%Y-%m-%dT%H:%M:%SZ'))
+      when String, Symbol, Fixnum, Bignum, Integer, Float
+        output << tag(element_type(element), CGI::escapeHTML(element.to_s))
+      when IO, StringIO
+        element.rewind
+        contents = element.read
+        # note that apple plists are wrapped at a different length then
+        # what ruby's base64 wraps by default.
+        # I used #encode64 instead of #b64encode (which allows a length arg)
+        # because b64encode is b0rked and ignores the length arg.
+        data = "\n"
+        Base64::encode64(contents).gsub(/\s+/, '').scan(/.{1,68}/o) { data << $& << "\n" }
+        output << tag('data', data)
+      else
+        output << comment( 'The <data> element below contains a Ruby object which has been serialized with Marshal.dump.' )
+        data = "\n"
+        Base64::encode64(Marshal.dump(element)).gsub(/\s+/, '').scan(/.{1,68}/o) { data << $& << "\n" }
+        output << tag('data', data )
+      end
+    end
+
+    return output
+  end
+
+  def self.comment(content)
+    return "<!-- #{content} -->\n"
+  end
+
+  def self.tag(type, contents = '', &block)
+    out = nil
+
+    if block_given?
+      out = IndentedString.new
+      out << "<#{type}>"
+      out.raise_indent
+
+      out << block.call
+
+      out.lower_indent
+      out << "</#{type}>"
+    else
+      out = "<#{type}>#{contents.to_s}</#{type}>\n"
+    end
+
+    return out.to_s
+  end
+
+  def self.wrap(contents)
+    output = ''
+
+    output << '<?xml version="1.0" encoding="UTF-8"?>' + "\n"
+    output << '<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">' + "\n"
+    output << '<plist version="1.0">' + "\n"
+
+    output << contents
+
+    output << '</plist>' + "\n"
+
+    return output
+  end
+
+  def self.element_type(item)
+    case item
+    when String, Symbol
+      'string'
+
+    when Fixnum, Bignum, Integer
+      'integer'
+
+    when Float
+      'real'
+
+    else
+      raise "Don't know about this data type... something must be wrong!"
+    end
+  end
+  private
+  class IndentedString #:nodoc:
+    attr_accessor :indent_string
+
+    def initialize(str = "\t")
+      @indent_string = str
+      @contents = ''
+      @indent_level = 0
+    end
+
+    def to_s
+      return @contents
+    end
+
+    def raise_indent
+      @indent_level += 1
+    end
+
+    def lower_indent
+      @indent_level -= 1 if @indent_level > 0
+    end
+
+    def <<(val)
+      if val.is_a? Array
+        val.each do |f|
+          self << f
+        end
+      else
+        # if it's already indented, don't bother indenting further
+        unless val =~ /\A#{@indent_string}/
+          indent = @indent_string * @indent_level
+
+          @contents << val.gsub(/^/, indent)
+        else
+          @contents << val
+        end
+
+        # it already has a newline, don't add another
+        @contents << "\n" unless val =~ /\n$/
+      end
+    end
+  end
+end
+
+class Array #:nodoc:
+  include Plist::Emit
+end
+
+class Hash #:nodoc:
+  include Plist::Emit
+end
diff --git a/Library/Homebrew/vendor/plist.rb b/Library/Homebrew/vendor/plist/plist/parser.rb
index 9e469a069..de441fcc5 100644
--- a/Library/Homebrew/vendor/plist.rb
+++ b/Library/Homebrew/vendor/plist/plist/parser.rb
@@ -1,3 +1,4 @@
+#!/usr/bin/env ruby
 #
 # = plist
 #
@@ -5,7 +6,7 @@
 # Distributed under the MIT License
 #
 
-# Plist parses macOS xml property list files into ruby data structures.
+# Plist parses Mac OS X xml property list files into ruby data structures.
 #
 # === Load a plist file
 # This is the main point of the library:
@@ -62,22 +63,15 @@ module Plist
     def initialize( plist_data_or_file, listener )
       if plist_data_or_file.respond_to? :read
         @xml = plist_data_or_file.read
-      elsif File.exists? plist_data_or_file
+      elsif File.exist? plist_data_or_file
         @xml = File.read( plist_data_or_file )
       else
         @xml = plist_data_or_file
       end
 
-      trim_to_xml_start!
-
       @listener = listener
     end
 
-    def trim_to_xml_start!
-      _, xml_tag, rest = @xml.partition(/^<\?xml/)
-      @xml = [xml_tag, rest].join
-    end
-
     TEXT       = /([^<]+)/
     XMLDECL_PATTERN = /<\?xml\s+(.*?)\?>*/um
     DOCTYPE_PATTERN = /\s*<!DOCTYPE\s+(.*?)(\[|>)/um
@@ -108,7 +102,7 @@ module Plist
         elsif @scanner.scan(end_tag)
           @listener.tag_end(@scanner[1])
         else
-          raise ParseError.new("Unimplemented element #{@xml}")
+          raise "Unimplemented element"
         end
       end
     end
@@ -134,7 +128,7 @@ module Plist
     end
 
     def to_ruby
-      raise ParseError.new("Unimplemented: " + self.class.to_s + "#to_ruby on #{self.inspect}")
+      raise "Unimplemented: " + self.class.to_s + "#to_ruby on #{self.inspect}"
     end
   end
 
@@ -162,7 +156,6 @@ module Plist
     end
   end
 
-  require 'cgi'
   class PKey < PTag
     def to_ruby
       CGI::unescapeHTML(text || '')
@@ -217,8 +210,7 @@ module Plist
   require 'base64'
   class PData < PTag
     def to_ruby
-      data = Base64.decode64(text.gsub(/\s+/, ''))
-
+      data = Base64.decode64(text.gsub(/\s+/, '')) unless text.nil?
       begin
         return Marshal.load(data)
       rescue Exception => e
@@ -229,6 +221,4 @@ module Plist
       end
     end
   end
-
-  class ParseError < RuntimeError; end
 end