From c0d5815fbf238d2612e56d501f157ef51678165a Mon Sep 17 00:00:00 2001 From: Ben Bleything Date: Fri, 8 Jan 2010 08:41:02 -0800 Subject: inline USAGE and LICENSE into README; update Rakefile for new README name --- README.rdoc | 130 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++-- Rakefile | 6 +-- docs/USAGE | 104 ------------------------------------------------ 3 files changed, 129 insertions(+), 111 deletions(-) delete mode 100644 docs/USAGE 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 + + + + + + FirstName + John + + LastName + Public + + StreetAddr1 + 123 Anywhere St. + + StateProv + CA + + City + Some Town + + CountryName + United States + + AreaCode + 555 + + LocalPhoneNumber + 5551212 + + ZipPostal + 12345 + + + +=== 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 and containers (respectively). +* +IO+ (and its descendants) and +StringIO+ objects are read from and their contents placed in a element. +* User classes may implement +to_plist_node+ to dictate how they should be serialized; otherwise the object will be passed to Marshal.dump and the result placed in a 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 Plist::Emit (which is already done for +Array+ and +Hash+), you can simply call +to_plist+: + + obj.to_plist + +This is equivalent to calling Plist::Emit.dump(obj). Either one will yield: + + + + + + 1 + two + + c + 13 + + + + +You can also dump plist fragments by passing +false+ as the second parameter: + + Plist::Emit.dump('holy cow!', false) + => "holy cow!" + +==== 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 "#{self.defancify}" + 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 Marshal.dump instead. == Links [Project Page] http://plist.rubyforge.org -[Subversion repository] svn://rubyforge.org//var/svn/plist +[*GitHub*] http://github.com/bleything/plist +[Git repository] svn://rubyforge.org//var/svn/plist [RDoc (on RubyForge)] 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 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. diff --git a/Rakefile b/Rakefile index acfd5cf..e27f00a 100644 --- a/Rakefile +++ b/Rakefile @@ -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 - - - - - - FirstName - John - - LastName - Public - - StreetAddr1 - 123 Anywhere St. - - StateProv - CA - - City - Some Town - - CountryName - United States - - AreaCode - 555 - - LocalPhoneNumber - 5551212 - - ZipPostal - 12345 - - - -== 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 and containers (respectively). -* +IO+ (and its descendants) and +StringIO+ objects are read from and their contents placed in a element. -* User classes may implement +to_plist_node+ to dictate how they should be serialized; otherwise the object will be passed to Marshal.dump and the result placed in a 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 Plist::Emit (which is already done for +Array+ and +Hash+), you can simply call +to_plist+: - - obj.to_plist - -This is equivalent to calling Plist::Emit.dump(obj). Either one will yield: - - - - - - 1 - two - - c - 13 - - - - -You can also dump plist fragments by passing +false+ as the second parameter: - - Plist::Emit.dump('holy cow!', false) - => "holy cow!" - -==== 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 "#{self.defancify}" - 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 Marshal.dump instead. -- cgit v1.2.1