diff options
author | Ben Bleything <ben@bleything.net> | 2010-01-08 08:41:02 -0800 |
---|---|---|
committer | Ben Bleything <ben@bleything.net> | 2010-01-11 16:07:46 -0800 |
commit | c0d5815fbf238d2612e56d501f157ef51678165a (patch) | |
tree | 53c4de5d720d5240eb9d0f801f26caa131667b01 | |
parent | a183a9dfb22f9ce229e91d26ef82822847c2823f (diff) | |
download | plist-c0d5815fbf238d2612e56d501f157ef51678165a.tar.gz |
inline USAGE and LICENSE into README; update Rakefile for new README name
-rw-r--r-- | README.rdoc | 130 | ||||
-rw-r--r-- | Rakefile | 6 | ||||
-rw-r--r-- | docs/USAGE | 104 |
3 files changed, 129 insertions, 111 deletions
diff --git a/README.rdoc b/README.rdoc index 05b4cd0..d44e332 100644 --- a/README.rdoc +++ b/README.rdoc @@ -4,12 +4,116 @@ Plist is a library to manipulate Property List files, also known as plists. It == Usage -See USAGE[link:files/docs/USAGE.html]. +=== Parsing + + result = Plist::parse_xml('path/to/example.plist') + + result.class + => Hash + + "#{result['FirstName']} #{result['LastName']}" + => "John Public" + + result['ZipPostal'] + => "12345" + +==== Example Property List + + <?xml version="1.0" encoding="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> + <key>FirstName</key> + <string>John</string> + + <key>LastName</key> + <string>Public</string> + + <key>StreetAddr1</key> + <string>123 Anywhere St.</string> + + <key>StateProv</key> + <string>CA</string> + + <key>City</key> + <string>Some Town</string> + + <key>CountryName</key> + <string>United States</string> + + <key>AreaCode</key> + <string>555</string> + + <key>LocalPhoneNumber</key> + <string>5551212</string> + + <key>ZipPostal</key> + <string>12345</string> + </dict> + </plist> + +=== Generation + +plist also provides the ability to generate plists from Ruby objects. 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. See below for more details. + +==== Creating a plist + +There are two ways to generate complete plists. Given an object: + + obj = [1, :two, {'c' => 0xd}] + +If you've mixed in <tt>Plist::Emit</tt> (which is already done for +Array+ and +Hash+), you can simply call +to_plist+: + + obj.to_plist + +This is equivalent to calling <tt>Plist::Emit.dump(obj)</tt>. Either one will yield: + + <?xml version="1.0" encoding="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"> + <array> + <integer>1</integer> + <string>two</string> + <dict> + <key>c</key> + <integer>13</integer> + </dict> + </array> + </plist> + +You can also dump plist fragments by passing +false+ as the second parameter: + + Plist::Emit.dump('holy cow!', false) + => "<string>holy cow!</string>" + +==== Custom serialization + +If your class can be safely coerced into a native plist datatype, you can implement +to_plist_node+. Upon encountering an object of a class it doesn't recognize, the plist library will check to see if it responds to +to_plist_node+, and if so, insert the result of that call into the plist output. + +An example: + + class MyFancyString + ... + + def to_plist_node + return "<string>#{self.defancify}</string>" + end + end + +When you attempt to serialize a +MyFancyString+ object, the +to_plist_node+ method will be called and the object's contents will be defancified and placed in the plist. + +If for whatever reason you can't add this method, your object will be serialized with <tt>Marshal.dump</tt> instead. == Links [<b>Project Page</b>] http://plist.rubyforge.org -[<b>Subversion repository</b>] svn://rubyforge.org//var/svn/plist +[*GitHub*] http://github.com/bleything/plist +[<b>Git repository</b>] svn://rubyforge.org//var/svn/plist [<b>RDoc (on RubyForge)</b>] http://plist.rubyforge.org == Credits @@ -31,6 +135,24 @@ Portions of the code (notably the Rakefile) contain code pulled and/or adapted f === MIT License -:include: LICENSE - +Copyright (c) 2006-2010, Ben Bleything <ben@bleything.net> and Patrick May <patrick@hexane.org> + +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. @@ -32,7 +32,7 @@ RUBYFORGE_USER = ENV['RUBYFORGE_USER'] TEST_FILES = Dir.glob('test/test_*').delete_if { |item| item.include?( "\.svn" ) } TEST_ASSETS = Dir.glob('test/assets/*').delete_if { |item| item.include?( "\.svn" ) } LIB_FILES = Dir.glob('lib/**/*').delete_if { |item| item.include?( "\.svn" ) } -RELEASE_FILES = [ "Rakefile", "README", "LICENSE", "docs/USAGE" ] + LIB_FILES + TEST_FILES + TEST_ASSETS +RELEASE_FILES = [ "Rakefile", "README.rdoc", "LICENSE", "docs/USAGE" ] + LIB_FILES + TEST_FILES + TEST_ASSETS task :default => [ :test ] # Run the unit tests @@ -107,9 +107,9 @@ end Rake::RDocTask.new { |rdoc| rdoc.rdoc_dir = 'rdoc' rdoc.title = "All-purpose Property List manipulation library" - rdoc.options << '-SNmREADME' + rdoc.options << '-SNmREADME.rdoc' rdoc.template = "docs/jamis-template.rb" - rdoc.rdoc_files.include('README', 'LICENSE', 'CHANGELOG') + rdoc.rdoc_files.include('README.rdoc', 'LICENSE', 'CHANGELOG') rdoc.rdoc_files.include Dir.glob('docs/**').delete_if {|f| f.include? 'jamis' } rdoc.rdoc_files.include('lib/**') } diff --git a/docs/USAGE b/docs/USAGE deleted file mode 100644 index 55612fe..0000000 --- a/docs/USAGE +++ /dev/null @@ -1,104 +0,0 @@ -== Parsing - - result = Plist::parse_xml('path/to/example.plist') - - result.class - => Hash - - "#{result['FirstName']} #{result['LastName']}" - => "John Public" - - result['ZipPostal'] - => "12345" - -==== Example Property List - - <?xml version="1.0" encoding="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> - <key>FirstName</key> - <string>John</string> - - <key>LastName</key> - <string>Public</string> - - <key>StreetAddr1</key> - <string>123 Anywhere St.</string> - - <key>StateProv</key> - <string>CA</string> - - <key>City</key> - <string>Some Town</string> - - <key>CountryName</key> - <string>United States</string> - - <key>AreaCode</key> - <string>555</string> - - <key>LocalPhoneNumber</key> - <string>5551212</string> - - <key>ZipPostal</key> - <string>12345</string> - </dict> - </plist> - -== Generation - -plist also provides the ability to generate plists from Ruby objects. 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. See below for more details. - -==== Creating a plist - -There are two ways to generate complete plists. Given an object: - - obj = [1, :two, {'c' => 0xd}] - -If you've mixed in <tt>Plist::Emit</tt> (which is already done for +Array+ and +Hash+), you can simply call +to_plist+: - - obj.to_plist - -This is equivalent to calling <tt>Plist::Emit.dump(obj)</tt>. Either one will yield: - - <?xml version="1.0" encoding="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"> - <array> - <integer>1</integer> - <string>two</string> - <dict> - <key>c</key> - <integer>13</integer> - </dict> - </array> - </plist> - -You can also dump plist fragments by passing +false+ as the second parameter: - - Plist::Emit.dump('holy cow!', false) - => "<string>holy cow!</string>" - -==== Custom serialization - -If your class can be safely coerced into a native plist datatype, you can implement +to_plist_node+. Upon encountering an object of a class it doesn't recognize, the plist library will check to see if it responds to +to_plist_node+, and if so, insert the result of that call into the plist output. - -An example: - - class MyFancyString - ... - - def to_plist_node - return "<string>#{self.defancify}</string>" - end - end - -When you attempt to serialize a +MyFancyString+ object, the +to_plist_node+ method will be called and the object's contents will be defancified and placed in the plist. - -If for whatever reason you can't add this method, your object will be serialized with <tt>Marshal.dump</tt> instead. |