Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

added rdoc to lib/plist/binary.rb

  • Loading branch information...
commit b03939f41c05ebbab1c63403f3e2b208d4f86ceb 1 parent a7e679a
Dana Contreras authored
Showing with 80 additions and 15 deletions.
  1. +80 −15 lib/plist/binary.rb
View
95 lib/plist/binary.rb
@@ -5,6 +5,8 @@
module Plist
module Binary
+ # Encodes +obj+ as a binary property list. If +obj+ is an Array, Hash, or
+ # Set, the property list includes its contents.
def self.binary_plist(obj)
encoded_objs = flatten_collection(obj)
encoded_objs.collect! {|o| binary_plist_obj(o)}
@@ -29,22 +31,56 @@ def self.binary_plist(obj)
plist
end
- CFBinaryPlistMarkerNull = 0x00
- CFBinaryPlistMarkerFalse = 0x08
- CFBinaryPlistMarkerTrue = 0x09
- CFBinaryPlistMarkerFill = 0x0F
- CFBinaryPlistMarkerInt = 0x10
- CFBinaryPlistMarkerReal = 0x20
- CFBinaryPlistMarkerDate = 0x33
- CFBinaryPlistMarkerData = 0x40
- CFBinaryPlistMarkerASCIIString = 0x50
- CFBinaryPlistMarkerUnicode16String = 0x60
- CFBinaryPlistMarkerUID = 0x80
- CFBinaryPlistMarkerArray = 0xA0
- CFBinaryPlistMarkerSet = 0xC0
- CFBinaryPlistMarkerDict = 0xD0
- NSTimeIntervalSince1970 = 978307200.0
+ private
+ # These marker bytes are prefixed to objects in a binary property list to
+ # indicate the type of the object.
+ CFBinaryPlistMarkerNull = 0x00 # :nodoc:
+ CFBinaryPlistMarkerFalse = 0x08 # :nodoc:
+ CFBinaryPlistMarkerTrue = 0x09 # :nodoc:
+ CFBinaryPlistMarkerFill = 0x0F # :nodoc:
+ CFBinaryPlistMarkerInt = 0x10 # :nodoc:
+ CFBinaryPlistMarkerReal = 0x20 # :nodoc:
+ CFBinaryPlistMarkerDate = 0x33 # :nodoc:
+ CFBinaryPlistMarkerData = 0x40 # :nodoc:
+ CFBinaryPlistMarkerASCIIString = 0x50 # :nodoc:
+ CFBinaryPlistMarkerUnicode16String = 0x60 # :nodoc:
+ CFBinaryPlistMarkerUID = 0x80 # :nodoc:
+ CFBinaryPlistMarkerArray = 0xA0 # :nodoc:
+ CFBinaryPlistMarkerSet = 0xC0 # :nodoc:
+ CFBinaryPlistMarkerDict = 0xD0 # :nodoc:
+
+ # POSIX uses a reference time of 1970-01-01T00:00:00Z; Cocoa's reference
+ # time is in 2001. This interval is for converting between the two.
+ NSTimeIntervalSince1970 = 978307200.0 # :nodoc:
+
+ # Takes an object (nominally a collection, like an Array, Set, or Hash, but
+ # any object is acceptable) and flattens it into a one-dimensional array.
+ # Non-collection objects appear in the array as-is, but the contents of
+ # Arrays, Sets, and Hashes are modified like so: (1) The contents of the
+ # collection are added, one-by-one, to the one-dimensional array. (2) The
+ # collection itself is modified so that it contains indexes pointing to the
+ # objects in the one-dimensional array. Here's an example with an Array:
+ #
+ # ary = [:a, :b, :c]
+ # flatten_collection(ary) # => [[1, 2, 3], :a, :b, :c]
+ #
+ # In the case of a Hash, keys and values are both appended to the one-
+ # dimensional array and then replaced with indexes.
+ #
+ # hsh = {:a => "blue", :b => "purple", :c => "green"}
+ # flatten_collection(hsh)
+ # # => [{1 => 2, 3 => 4, 5 => 6}, :a, "blue", :b, "purple", :c, "green"]
+ #
+ # An object will never be added to the one-dimensional array twice. If a
+ # collection refers to an object more than once, the object will be added
+ # to the one-dimensional array only once.
+ #
+ # ary = [:a, :a, :a]
+ # flatten_collection(ary) # => [[1, 1, 1], :a]
+ #
+ # The +obj_list+ and +id_refs+ parameters are private; they're used for
+ # descending into sub-collections recursively.
def self.flatten_collection(collection, obj_list = [], id_refs = {})
case collection
when Array, Set
@@ -81,6 +117,30 @@ def self.flatten_collection(collection, obj_list = [], id_refs = {})
end
end
+ # Returns a binary property list fragment that represents +obj+. The
+ # returned string is not a complete property list, just a fragment that
+ # describes +obj+, and is not useful without a header, offset table, and
+ # trailer.
+ #
+ # The following classes are recognized: String, Float, Integer, the Boolean
+ # classes, Time, IO, StringIO, Array, Set, and Hash. IO and StringIO
+ # objects are rewound, read, and the contents stored as data (i.e., Cocoa
+ # applications will decode them as NSData). All other classes are dumped
+ # with Marshal and stored as data.
+ #
+ # Note that subclasses of the supported classes will be encoded as though
+ # they were the supported superclass. Thus, a subclass of (for example)
+ # String will be encoded and decoded as a String, not as the subclass:
+ #
+ # class ExampleString < String
+ # ...
+ # end
+ #
+ # s = ExampleString.new("disquieting plantlike mystery")
+ # encoded_s = binary_plist_obj(s)
+ # decoded_s = decode_binary_plist_obj(encoded_s)
+ # puts decoded_s.class # => String
+ #
def self.binary_plist_obj(obj)
case obj
when String
@@ -182,6 +242,11 @@ def self.binary_plist_obj(obj)
end
end
+ # Returns a binary property list fragment that represents a data object
+ # with the contents of the string +data+. A Cocoa application would decode
+ # this fragment as NSData. Like binary_plist_obj, the value returned by
+ # this method is not usable by itself; it is only useful as part of a
+ # complete binary property list with a header, offset table, and trailer.
def self.binary_plist_data(data)
result = (CFBinaryPlistMarkerData |
(data.length < 15 ? data.length : 0xf)).chr
Please sign in to comment.
Something went wrong with that request. Please try again.