README.rdoc in plist4r-0.2.2 vs README.rdoc in plist4r-1.0.0
- old
+ new
@@ -1,153 +1,56 @@
= plist4r
-Plist4r is a friendly ruby library for reading and writing plist files.
+Plist4r is a friendly rubygem / ruby lib for handling plist files.
-==== Current status: Beta, 0.2.x series
+* Documentation at http://dreamcat4.github.com/plist4r
-We can read / write various kinds of plist files reliably. The API interfaces (for the pluggable backends and plist_types) are mature. The user API works well. Searchable Documentation is included, complete with examples.
-
== Installation
gem install plist4r
== Quick Start
require 'plist4r'
- Plist4r::Config.default_dir "/Library/LaunchDaemons"
+ Plist4r::Config.default_path = "/Library/LaunchDaemons"
filename = "com.github.myservice.plist"
p = Plist4r.open(filename)
p.plist_type
# => :launchd
p.file_format
# => :xml
- p.<< do
- ProgramArguments ["/usr/local/bin/myservice"]
- end
-
p.edit do
- WatchPaths ["/var/db/myservice"]
+ program_arguments ["/usr/local/bin/myservice"]
+ watch_paths ["/var/db/myservice"]
end
p.save
-== Plist4r Backends
+== Overview
-There are now a number of ruby libraries which can read / write plist files. The aim of plist4r is to utilize the individual best features from all of those libraries, as a series of "backends". And hide those behind a "frontend" that is easy to work with.
+* For convenience we invoke {Plist4r.open} and {Plist4r.new} to initially create a plist object.
-Backends often only need to be a single ruby file, which implements the Plist4r API methods and calls out to other (existing) ruby code. No single backend has to provide the whole API. Instead, Plist4r simply iterates over all of the backends it knows about, and then calls the first backend that can responds to the API method.
+* And use {Plist4r::Config} to set any global configuration defaults.
-There are just 6 supported API methods
+* See {file:Backends} for the backends performance data.
- ApiMethods = %w[from_string to_xml to_binary to_next_step open save]
+Examples
+* See {file:InfoPlistExample}
+* See {file:LaunchdPlistExample}
-And (as above) the 3 supported Plist file formats are
+Recommended reading
+* See {file:EditingPlistFiles}
+* See {file:PlistKeyNames}
+* Please see the inline source-code documentation on {Plist4r::Plist}
- FileFormats = %w[binary xml next_step]
+How to contribute
+* {file:DeveloperGuide}
-We believe thats allright for most uses, and decided to include `next_step` for completeness. `NextStep` is also known by other names such as `OpenStep` and (more updated version) `GNU Step`. For example the apple `defaults` command on Mac OS-X will still return `NextStep` formatted plist data.
-
-== Plist4r Types
-
-A Plist type can be one of `%w[plist info launchd]`, and is the data type for the whole plist file. The plist data type provides convenience methods for setting the Type-specific data structures. For example "Sockets" in a launchd plist.
-
-Plist types are also useful to disallow keys which arent recognized or supported by that format. Setting `:strict_keys true` the Plist4r::Config object will globaly enable strict keys.
-
- ::Plist4r::Config[:unsupported_keys] = true
-
-Or individually, per plist object with
-
- plist.strict_keys false
-
-Default is false, which allows editing of any arbitrary plist keys. We think thats a good choice, since unsupported keys can already be present in many existing plist files.
-
-== More Examples
-
- module ::Plist4r::Backend::MyPlistReaderWriter
- # implement some plist4r api calls here
- end
-
- # append my backend to the end of the list
- Plist4r::Config[:backends] << :my_plist_reader_writer
-
- # or to the front of the list (executes first)
- Plist4r::Config[:backends].insert 0 :my_plist_reader_writer
-
- # The default directory to load / save files from
- Plist4r::Config.default_path "/Library/Cars"
-
- car = Plist4r.new("car.plist")
-
- car.load
-
- car.file_format :binary
- # car.plist_type :car # not implemented *yet*
-
- car.save
-
- car.<< do
- road_legal true
- brake_light_color "red"
- end
-
- car.save_as("car2.plist", :binary => true)
-
- car.<< do
- eyes "blue"
- end
- # => Exception, invalid plist key name "Eyes"
-
- car.<< do
- tyres "Pirelli"
- end
-
- car.to_xml
- # => xml string
-
-== Remaining Work
-
-Plist4r has now moved from alpha to beta - quality software. TBC...
-
-* Regression Tests (rspec)
-* Test harness for the backends
-* Testing of the individual backends
-* A Plist Type for Info.plist
-* Tests for Plist Types
-
-== Notes on Patches/Pull Requests
-
-* Fork the project, and create a topic branch as per {these instructions}[http://wiki.opscode.com/display/opscode/Working+with+Git].
-* Make your feature addition or bug fix.
-* Include documentation for it.
-* Include a regression test for it. So I dont break it in a future version unintentionally.
-
-== Contributors
-
-Popen4
-* Ara T Howard
-
-ActiveSupport::OrderedHash
-* Copyright (c) 2005 David Hansson,
-* Copyright (c) 2007 Mauricio Fernandez, Sam Stephenson
-* Copyright (c) 2008 Steve Purcell, Josh Peek
-* Copyright (c) 2009 Christoffer Sawicki
-
-Mixlib::Config
-* Author:: Adam Jacob
-* Author:: Nuo Yan
-* Author:: Christopher Brown
-* Copyright:: Copyright (c) 2008 Opscode, Inc.
-
-Backends...
-
-Haml, Libxml4r, RubyCocoa
-* Dreamcat4
-
== Copyright
-Copyright (c) 2010 Dreamcat4. See LICENSE for details.
+Plist4r is Copyright (c) 2009 under MIT License. See {file:LICENSE} for details.