0
@@ -21,7 +21,7 @@
0
  *     :xml1, :binary1, or :openstep
0
  *
0
  * PropertyList::dump(io, obj, type = :xml1)
0
- *     Takes an IO stream (open for writing) and an  object
0
+ *     Takes an IO stream (open for writing) and an  object
0
  *     Writes the object to the IO stream as a property list
0
  *     Posible type values are :xml1 and :binary1
0
  *
0
@@ -43,6 +43,19 @@
0
  *
0
  */
0
 
0
+/*
0
+ * Document-class: PropertyList
0
+ *
0
+ * The PropertyList module provides a means of converting a
0
+ * Ruby Object to a Property List.
0
+ *
0
+ * The various Objects that can be converted are the ones
0
+ * with an equivalent in CoreFoundation. This includes: String,
0
+ * Integer, Float, Boolean, Time, Hash, and Array.
0
+ *
0
+ * See also: String#blob?, String#blob=, and Object#to_plist
0
+ */
0
+
0
 #include <ruby.h>
0
 #include <st.h>
0
 #include <CoreFoundation/CoreFoundation.h>
0
@@ -80,6 +93,7 @@
0
 VALUE str_blob(VALUE self);
0
 VALUE str_setBlob(VALUE self, VALUE b);
0
 
0
+// Raises a Ruby exception with the given string
0
 void raiseError(CFStringRef error) {
0
     char *errBuffer = (char *)CFStringGetCStringPtr(error, kCFStringEncodingUTF8);
0
     int freeBuffer = 0;
0
@@ -96,6 +110,16 @@
0
     if (freeBuffer) free(errBuffer);
0
 }
0
 
0
+/* call-seq:
0
+ *    PropertyList.load(obj)         -> object
0
+ *    PropertyList.load(obj, format) -> [object, format]
0
+ *
0
+ * Loads a property list from an IO stream or a String and creates
0
+ * an equivalent Object from it.
0
+ *
0
+ * If +format+ is provided, it returns one of
0
+ * <tt>:xml1</tt>, <tt>:binary1</tt>, or <tt>:openstep</tt>.
0
+ */
0
 VALUE plist_load(int argc, VALUE *argv, VALUE self) {
0
   VALUE io, retFormat;
0
   int count = rb_scan_args(argc, argv, "11", &io, &retFormat);
0
@@ -167,6 +191,7 @@
0
   }
0
 }
0
 
0
+// Maps the property list object to a ruby object
0
 VALUE convertPropertyListRef(CFPropertyListRef plist) {
0
   CFTypeID typeID = CFGetTypeID(plist);
0
   if (typeID == CFStringGetTypeID()) {
0
@@ -188,6 +213,7 @@
0
   }
0
 }
0
 
0
+// Converts a CFStringRef to a String
0
 VALUE convertStringRef(CFStringRef plist) {
0
   CFIndex byteCount;
0
   CFRange range = CFRangeMake(0, CFStringGetLength(plist));
0
0
0
0
@@ -204,20 +230,24 @@
0
   return retval;
0
 }
0
 
0
+// Converts the keys and values of a CFDictionaryRef
0
 void dictionaryConverter(const void *key, const void *value, void *context) {
0
   rb_hash_aset((VALUE)context, convertPropertyListRef(key), convertPropertyListRef(value));
0
 }
0
 
0
+// Converts a CFDictionaryRef to a Hash
0
 VALUE convertDictionaryRef(CFDictionaryRef plist) {
0
   VALUE hash = rb_hash_new();
0
   CFDictionaryApplyFunction(plist, dictionaryConverter, (void *)hash);
0
   return hash;
0
 }
0
 
0
+// Converts the values of a CFArrayRef
0
 void arrayConverter(const void *value, void *context) {
0
   rb_ary_push((VALUE)context, convertPropertyListRef(value));
0
 }
0
 
0
+// Converts a CFArrayRef to an Array
0
 VALUE convertArrayRef(CFArrayRef plist) {
0
   VALUE array = rb_ary_new();
0
   CFRange range = CFRangeMake(0, CFArrayGetCount(plist));
0
@@ -225,6 +255,7 @@
0
   return array;
0
 }
0
 
0
+// Converts a CFNumberRef to a Number
0
 VALUE convertNumberRef(CFNumberRef plist) {
0
   if (CFNumberIsFloatType(plist)) {
0
     double val;
0
@@ -243,6 +274,7 @@
0
   }
0
 }
0
 
0
+// Converts a CFBooleanRef to a Boolean
0
 VALUE convertBooleanRef(CFBooleanRef plist) {
0
   if (CFBooleanGetValue(plist)) {
0
     return Qtrue;
0
@@ -251,6 +283,7 @@
0
   }
0
 }
0
 
0
+// Converts a CFDataRef to a String (with blob set to true)
0
 VALUE convertDataRef(CFDataRef plist) {
0
   const UInt8 *bytes = CFDataGetBytePtr(plist);
0
   CFIndex len = CFDataGetLength(plist);
0
@@ -259,6 +292,7 @@
0
   return str;
0
 }
0
 
0
+// Converts a CFDateRef to a Time
0
 VALUE convertDateRef(CFDateRef plist) {
0
   CFAbsoluteTime seconds = CFDateGetAbsoluteTime(plist);
0
   return rb_funcall(timeEpoch, id_plus, 1, rb_float_new(seconds));
0
@@ -266,6 +300,7 @@
0
 
0
 CFPropertyListRef convertObject(VALUE obj);
0
 
0
+// Converts a PropertyList object to a string representation
0
 VALUE convertPlistToString(CFPropertyListRef plist, CFPropertyListFormat format) {
0
   CFWriteStreamRef writeStream = CFWriteStreamCreateWithAllocatedBuffers(kCFAllocatorDefault, kCFAllocatorDefault);
0
   CFWriteStreamOpen(writeStream);
0
@@ -283,8 +318,18 @@
0
   return plistData;
0
 }
0
 
0
-// io, obj, type = :xml1
0
-// also takes :binary1
0
+/* call-seq:
0
+ *    PropertyList.dump(io, obj)         -> Integer
0
+ *    PropertyList.dump(io, obj, format) -> Integer
0
+ *
0
+ * Writes the property list representation of +obj+
0
+ * to the IO stream (must be open for writing).
0
+ *
0
+ * +format+ can be one of <tt>:xml1</tt> or <tt>:binary1</tt>.
0
+ *
0
+ * Returns the number of bytes written, or +nil+ if
0
+ * the object could not be represented as a property list
0
+ */
0
 VALUE plist_dump(int argc, VALUE *argv, VALUE self) {
0
   VALUE io, obj, type;
0
   int count = rb_scan_args(argc, argv, "21", &io, &obj, &type);
0
@@ -318,7 +363,15 @@
0
   }
0
 }
0
 
0
-// type = :xml1
0
+/* call-seq:
0
+ *    object.to_plist         -> String
0
+ *    object.to_plist(format) -> String
0
+ *
0
+ * Converts the object to a property list representation
0
+ * and returns it as a string.
0
+ *
0
+ * +format+ can be one of <tt>:xml1</tt> or <tt>:binary1</tt>.
0
+ */
0
 VALUE obj_to_plist(int argc, VALUE *argv, VALUE self) {
0
   VALUE type;
0
   int count = rb_scan_args(argc, argv, "01", &type);
0
@@ -354,6 +407,7 @@
0
 CFNumberRef convertNumber(VALUE obj);
0
 CFDateRef convertTime(VALUE obj);
0
 
0
+// Converts an Object to a CFTypeRef
0
 CFPropertyListRef convertObject(VALUE obj) {
0
   switch (TYPE(obj)) {
0
     case T_STRING: return convertString(obj); break;
0
@@ -370,6 +424,7 @@
0
   return NULL;
0
 }
0
 
0
+// Converts a String to a CFStringRef
0
 CFPropertyListRef convertString(VALUE obj) {
0
   if (RTEST(str_blob(obj))) {
0
     // convert to CFDataRef
0
@@ -388,6 +443,7 @@
0
   }
0
 }
0
 
0
+// Converts the keys and values of a Hash to CFTypeRefs
0
 int iterateHash(VALUE key, VALUE val, VALUE dict) {
0
   CFPropertyListRef dKey = convertObject(key);
0
   CFPropertyListRef dVal = convertObject(val);
0
@@ -397,6 +453,7 @@
0
   return ST_CONTINUE;
0
 }
0
 
0
+// Converts a Hash to a CFDictionaryREf
0
 CFDictionaryRef convertHash(VALUE obj) {
0
   CFIndex count = (CFIndex)RHASH(obj)->tbl->num_entries;
0
   CFMutableDictionaryRef dict = CFDictionaryCreateMutable(kCFAllocatorDefault, count, &kCFTypeDictionaryKeyCallBacks, &kCFTypeDictionaryValueCallBacks);
0
@@ -404,6 +461,7 @@
0
   return dict;
0
 }
0
 
0
+// Converts an Array to a CFArrayRef
0
 CFArrayRef convertArray(VALUE obj) {
0
   CFIndex count = (CFIndex)RARRAY(obj)->len;
0
   CFMutableArrayRef array = CFArrayCreateMutable(kCFAllocatorDefault, count, &kCFTypeArrayCallBacks);
0
@@ -416,6 +474,7 @@
0
   return array;
0
 }
0
 
0
+// Converts a Number to a CFNumberRef
0
 CFNumberRef convertNumber(VALUE obj) {
0
   void *valuePtr;
0
   CFNumberType type;
0
0
@@ -451,13 +510,18 @@
0
   return number;
0
 }
0
 
0
+// Converts a Time to a CFDateRef
0
 CFDateRef convertTime(VALUE obj) {
0
   VALUE secs = rb_funcall(obj, id_minus, 1, timeEpoch);
0
   CFDateRef date = CFDateCreate(kCFAllocatorDefault, NUM2DBL(secs));
0
   return date;
0
 }
0
 
0
-
0
+/* call-seq:
0
+ *    str.blob? -> Boolean
0
+ *
0
+ * Returns whether or not +str+ is a blob.
0
+ */
0
 VALUE str_blob(VALUE self) {
0
   VALUE blob = rb_attr_get(self, id_blob);
0
   if (NIL_P(blob)) {
0
@@ -467,6 +531,11 @@
0
   }
0
 }
0
 
0
+/* call-seq:
0
+ *    str.blob = bool -> bool
0
+ *
0
+ * Sets the blob status of +str+.
0
+ */
0
 VALUE str_setBlob(VALUE self, VALUE b) {
0
   if (TYPE(b) == T_TRUE || TYPE(b) ==  T_FALSE) {
0
     return rb_ivar_set(self, id_blob, b);
0
@@ -476,6 +545,9 @@
0
   }
0
 }
0
 
0
+/* Bridge to CoreFoundation for reading/writing Property Lists.
0
+ * Only works when CoreFoundation is available.
0
+ */
0
 void Init_plist() {
0
   mPlist = rb_define_module("PropertyList");
0
   rb_define_module_function(mPlist, "load", plist_load, -1);