Tekkotsu Homepage
Demos
Overview
Downloads
Dev. Resources
Reference
Credits

plist.h

Go to the documentation of this file.
00001 //-*-c++-*-
00002 #ifndef INCLUDED_PListSupport_h_
00003 #define INCLUDED_PListSupport_h_
00004 
00005 #include "plistBase.h"
00006 #include "plistPrimitives.h"
00007 #include "plistCollections.h"
00008 
00009 /*! The plist namespace provides convenient serialization for persistent storage, 
00010  *  dynamic introspection, and polymorphic primitive values.  The classes happen
00011  *  to use Apple's XML-based "property list" format for serialization, using libxml2
00012  *  for the low level parsing.
00013  *
00014  *  The choice of storage format was based on a desire for human readability,
00015  *  including per-value comments and inline documentation, as well as the desire
00016  *  to make use of syntax hilighting or high-level editing tools.
00017  *  
00018  *  Individual values are based on templated instances of the Primitive<T> class,
00019  *  while groups of values are based on the Collection interface.  Currently, the
00020  *  concrete collections available are Array (one dimensional ordered list of mixed
00021  *  primitive types), ArrayOf<T> (ordered list of a single type), or Dictionary (unordered
00022  *  mapping from string names to mixed primitives).
00023  *
00024  *  Generally, there are two ways you might use the functionality contained within
00025  *  this namespace.  One is as an external storage interface, such as the STL
00026  *  vector and map classes are used.  This might be only a intermediary instance
00027  *  for conversion to and from existing data structures, as a higher-level interface
00028  *  than directly accessing libxml.
00029  *
00030  *  However, to fully benefit from this namespace's functionality, you will generally
00031  *  want your classes to inherit from plist::Dictionary, define your members
00032  *  as public plist Primitives and Collections, and register listeners for notification
00033  *  when these values are modified (either by loading from file or programmatic
00034  *  modification.)
00035  *
00036  *  Example usage is shown below, you can find this code and more in Tekkotsu/tools/test/plist/.
00037  *  @include plist-example.cc
00038  */
00039 namespace plist {
00040   
00041   //! From the name of @a node, will instantiate a new ObjectBase subclass to load it
00042   /*! The mapping from node names to actual instantiated types is: 
00043    *    - 'array' -> Vector
00044    *    - 'dict' -> Map
00045    *    - 'real' -> Primitive<double>
00046    *    - 'integer' -> Primitive<long>
00047    *    - 'string' -> Primitive<std::string>
00048    *    - 'true', 'false' -> Primitive<bool>
00049    *  
00050    *  If successful, returns a pointer to a newly allocated region, which the caller is
00051    *  responsible for freeing.  If an error occurs, NULL is returned.
00052    */
00053   ObjectBase* loadXML(xmlNode* node);
00054   
00055   //! Attempts to parse the file found at @a file, using plist::loadXML()
00056   ObjectBase* loadFile(const std::string& file);
00057   
00058   //! Attempts to parse the buffer found at @a buf, using plist::loadXML()
00059   ObjectBase* loadBuffer(const char* buf, unsigned int len);
00060   
00061 } //namespace plist
00062 
00063 /*! @file
00064  * @brief Provides the plist namespace, a collection of classes to implement the Propery List data storage format, a XML standard used by Apple and others
00065  * @author Ethan Tira-Thompson (ejt) (Creator)
00066  *
00067  * $Author: ejt $
00068  * $Name: tekkotsu-4_0 $
00069  * $Revision: 1.13 $
00070  * $State: Exp $
00071  * $Date: 2007/11/09 03:33:58 $
00072  */
00073 
00074 #endif

Tekkotsu v4.0
Generated Thu Nov 22 00:54:54 2007 by Doxygen 1.5.4