source: trunk/docs/api/zoo-format.txt @ 817

.. _api-zoo-format:

ZOO.Format
==========

Base class for format reading/writing a variety of formats.

Properties      
----------

.. list-table::
   :widths: 30 50
   :header-rows: 1

   * - NAME
     - DESCRIPTION
   * - :ref:`options <options>`
     - {Object} A reference to options passed to the constructor.
   * - :ref:`externalProjection <externalProjection>`
     - {ZOO.Projection} When passed a externalProjection and internalProjection, the format will reproject the geometries it reads or writes.
   * - :ref:`internalProjection <internalProjection>`
     - {ZOO.Projection} When passed a externalProjection and internalProjection, the format will reproject the geometries it reads or writes.
   * - :ref:`data <data>`
     - {Object} When keepData is true, this is the parsed string sent to read.
   * - :ref:`keepData <keepData>`
     - {Object} Maintain a reference (data) to the most recently read data.   
     
Functions       
---------

.. list-table::
   :widths: 12 50
   :header-rows: 1

   * - NAME
     - DESCRIPTION
   * - :ref:`ZOO.Format <ZOO.Format>`
     - Instances of this class are not useful.
   * - :ref:`destroy <destroy>`
     - Clean up.
   * - :ref:`read <read>`
     - Read data from a string, and return an object whose type depends on the subclass.
   * - :ref:`data <data>`
     - {Object} When keepData is true, this is the parsed string sent to read.
   * - :ref:`write <write>`
     - Accept an object, and return a string.     
        
**Properties**

.. _options:   

options 
  ``{Object}`` A reference to options passed to the constructor.
  
.. _externalProjection:   

externalProjection      
  :ref:`{ZOO.Projection} <api-zoo-projection>` When passed a externalProjection and internalProjection, 
  the format will reproject the geometries it reads or writes. The externalProjection is the projection 
  used by the content which is passed into read or which comes out of write.  In order to reproject, 
  a projection transformation function for the specified projections must be available.  This support 
  is provided via zoo-proj4js.

.. _internalProjection:   

internalProjection      
  :ref:`{ZOO.Projection} <api-zoo-projection>` When passed a externalProjection and internalProjection, 
  the format will reproject the geometries it reads or writes. The internalProjection is the projection 
  used by the geometries which are returned by read or which are passed into write.  In order to reproject, 
  a projection transformation function for the specified projections must be available.  This support 
  is provided via zoo-proj4js.

.. _data:   

data    
  ``{Object}`` When :ref:`keepData <keepData>` is true, this is the parsed string sent to :ref:`read <read>`.

.. _keepData:   

keepData        
  ``{Object}`` Maintain a reference (:ref:`data <data>`) to the most recently read data.  Default is false.

**Functions**

.. _ZOO.Format:   

ZOO.Format      
  Instances of this class are not useful.  See one of the subclasses.

  *Parameters*
  
  ``options {Object}`` An optional object with properties to set on the format
  
  *Valid options*

  ``keepData {Boolean}`` If true, upon read, the data property will be set to the parsed object (e.g. the json or xml object).

  *Returns*

  An instance of ZOO.Format
  
.. _destroy:     
  
destroy 
  ::
  
    destroy: function()

  Clean up.

.. _read:     
  
read    
  ::
  
    read: function(data)

  Read data from a string, and return an object whose type depends on the subclass.

  *Parameters*
  
  ``data {string}`` Data to read/parse.

  *Returns*

  Depends on the subclass

.. _write:     

write   
  ::
  
    write: function(data)

  Accept an object, and return a string.   

  *Parameters*
  
  ``object {Object}`` Object to be serialized
  
  *Returns*

  ``{String}`` A string representation of the object.