Module: OSX::PropertyList

Defined in:

ext/plist/plist.c,
lib/osx/plist.rb,
ext/plist/plist.c

Overview

The PropertyList module provides a means of converting a Ruby Object to a Property List.

The various Objects that can be converted are the ones with an equivalent in CoreFoundation. This includes: String, Integer, Float, Boolean, Time, Hash, and Array.

See also: String#blob?, String#blob=, and Object#to_plist

Constant Summary

EPOCH =

The Cocoa epoch of January 1st, 2001

Time.gm(2001)

Class Method Summary

• .dump(io, obj, format = :xml1) ⇒ Object

  Writes the property list representation of obj to the IO stream (must be open for writing).

• .dump_file(filepath, obj, format = :xml1) ⇒ Object

  Writes the property list representation of obj to the file at filepath using OSX::PropertyList.dump.

• .load(obj, format = false) ⇒ Object

  Loads a property list from an IO stream or a String and creates an equivalent Object from it.

• .load_file(filepath, format = false) ⇒ Object

  Loads a property list from the file at filepath using OSX::PropertyList.load.

Class Method Details

.dump(io, obj, format = :xml1) ⇒ Object

Writes the property list representation of obj to the IO stream (must be open for writing).

format can be one of :xml1 or :binary1.

Returns the number of bytes written, or nil if the object could not be represented as a property list

# File 'ext/plist/plist.c', line 330

VALUE plist_dump(int argc, VALUE *argv, VALUE self) {
	VALUE io, obj, type;
	int count = rb_scan_args(argc, argv, "21", &io, &obj, &type);
	if (count < 3) {
		type = id_xml;
	} else {
		type = rb_to_id(type);
	}
	if (!RTEST(rb_respond_to(io, id_write))) {
		rb_raise(rb_eArgError, "Argument 1 must be an IO object");
		return Qnil;
	}
	CFPropertyListFormat format;
	if (type == id_xml) {
		format = kCFPropertyListXMLFormat_v1_0;
	} else if (type == id_binary) {
		format = kCFPropertyListBinaryFormat_v1_0;
	} else if (type == id_openstep) {
		format = kCFPropertyListOpenStepFormat;
	} else {
		rb_raise(rb_eArgError, "Argument 3 must be one of :xml1, :binary1, or :openstep");
		return Qnil;
	}
	CFPropertyListRef plist = convertObject(obj);
	VALUE data = convertPlistToString(plist, format);
	if (NIL_P(data)) {
		return Qnil;
	} else {
		return rb_funcall(io, id_write, 1, data);
	}
}

.dump_file(filepath, obj, format = :xml1) ⇒ Object

Writes the property list representation of obj to the file at filepath using OSX::PropertyList.dump.

# File 'lib/osx/plist.rb', line 12

def self.dump_file(filepath, obj, format = :xml1)
  File.open(filepath, "w") do |f|
    OSX::PropertyList.dump(f, obj, format)
  end
end

.load(obj, format = false) ⇒ Object

Loads a property list from an IO stream or a String and creates an equivalent Object from it.

If format is true, it returns an array of [object, format] where format is one of :xml1, :binary1, or :openstep.

# File 'ext/plist/plist.c', line 115

VALUE plist_load(int argc, VALUE *argv, VALUE self) {
	VALUE io, retFormat;
	int count = rb_scan_args(argc, argv, "11", &io, &retFormat);
	if (count < 2) retFormat = Qfalse;
	VALUE buffer;
	if (RTEST(rb_respond_to(io, id_read))) {
		// Read from IO
		buffer = rb_funcall(io, id_read, 0);
	} else {
		StringValue(io);
		buffer = io;
	}
	// For some reason, the CFReadStream version doesn't work with input < 6 characters
	// but the CFDataRef version doesn't return format
	// So lets use the CFDataRef version unless format is requested
	CFStringRef error = NULL;
	CFPropertyListRef plist;
	CFPropertyListFormat format;
	if (RTEST(retFormat)) {
		// Format was requested
		// now just in case, if the input is < 6 characters, we will pad it out with newlines
		// we could do this in all cases, but I don't think it will work with binary
		// even though binary shouldn't be < 6 characters
		UInt8 *bytes;
		int len;
		if (RSTRING_LEN(buffer) < 6) {
			bytes = ALLOC_N(UInt8, 6);
			memset(bytes, '\n', 6);
			MEMCPY(bytes, RSTRING_PTR(buffer), UInt8, RSTRING_LEN(buffer));
			len = 6;
		} else {
			bytes = (UInt8 *)RSTRING_PTR(buffer);
			len = RSTRING_LEN(buffer);
		}
		CFReadStreamRef readStream = CFReadStreamCreateWithBytesNoCopy(kCFAllocatorDefault, bytes, len, kCFAllocatorNull);
		CFReadStreamOpen(readStream);
		plist = CFPropertyListCreateFromStream(kCFAllocatorDefault, readStream, 0, kCFPropertyListImmutable, &format, &error);
		CFReadStreamClose(readStream);
		CFRelease(readStream);
	} else {
		// Format wasn't requested
		CFDataRef data = CFDataCreateWithBytesNoCopy(kCFAllocatorDefault, (const UInt8*)RSTRING_PTR(buffer), RSTRING_LEN(buffer), kCFAllocatorNull);
		plist = CFPropertyListCreateFromXMLData(kCFAllocatorDefault, data, kCFPropertyListImmutable, &error);
		CFRelease(data);
	}
	if (error) {
		raiseError(error);
		CFRelease(error);
		return Qnil;
	}
	VALUE obj = convertPropertyListRef(plist);
	CFRelease(plist);
	if (RTEST(retFormat)) {
		VALUE ary = rb_ary_new();
		rb_ary_push(ary, obj);
		if (format == kCFPropertyListOpenStepFormat) {
			retFormat = id_openstep;
		} else if (format == kCFPropertyListXMLFormat_v1_0) {
			retFormat = id_xml;
		} else if (format == kCFPropertyListBinaryFormat_v1_0) {
			retFormat = id_binary;
		} else {
			retFormat = rb_intern("unknown");
		}
		rb_ary_push(ary, ID2SYM(retFormat));
		return ary;
	} else {
		return obj;
	}
}

.load_file(filepath, format = false) ⇒ Object

Loads a property list from the file at filepath using OSX::PropertyList.load.

# File 'lib/osx/plist.rb', line 6

def self.load_file(filepath, format = false)
  File.open(filepath, "r") do |f|
    OSX::PropertyList.load(f, format)
  end
end