Plist4r Backends
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.
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.
There are only 3 generally recognized Plist file formats. (the gnustep plist format also goes by the names openstep, and nextstep)
FileFormats = %w[ binary xml gnustep ]
A plist4r backend can implement any number of these 6 supported API methods
ApiMethods = %w[ from_xml from_binary from_gnustep to_xml to_binary to_gnustep ]
Other API methods are “generated” methods, which translate the call onto real backend API methods. A good example is from_string(), which gets resolved to from_binary or from_xml. Generally speaking, those Plist4r::Backend::PrivateApiMethods methods are cached and should not be provided by a Plist4r backend
PrivateApiMethods = %w[ from_string open save ]
For backends performance data see Backends.
Plist4r Types
A Plist type can be one of %w[plist info launchd], and is the data type for the whole plist file. A PlistType can provide special convenience methods for its Type-specific data structures. For example Plist4r::PlistType::Launchd#socket.
We re-use common support objects when writing a new PlistType
Contributing to Plist4r
- Fork the project, and create a topic branch as per these instructions
- Make the appropriate source code changes
- Raise a new issue in Github Issues, with a name that corresponds to the topic branch name
For a change in the Plist4r Core library
- Please update the inline source code documentation, generate locally with rake yard
- Please run the regression tests with rake spec and rake backends:test
- Please update the existing regression tests (in RSpec) or write new ones
For a Plist4r::Backend
- Please include attribution with an @author tag in the yard inline comments
- If requires new gem dependencies, be add to the Rakefile and run +rake gemspec+
For a Plist4r::PlistType
- Conform to the conventions used by Plist4r::PlistType::Info and Plist4r::PlistType::Launchd
- Use Plist4r::OrderedHash instead of Hash or {}
- Try to use Plist4r::DataMethods and Plist4r::ArrayDict for storing the data
- Use yard to help document any custom key functions and rake yard afterward