[pdf-devel] Object layer API

[jemarch]

Hi.

I just committed in the trunk the first draft of the object layer
public API. It is documented in the "Object Layer" chapter of the
reference manual.

Briefly, the API is built around two main concepts:

- Object Documents.

  Hierarchy of objects that may compound a PDF document (not every
  object document conform to a valid PDF document).

  The API provides facilities to both create a new empty object
  document and to open an existing one. The access to the objects
  composing an object document is made by getting the root object (the
  catalog dictionary) of the document.

  The client application can create both direct and indirect objects
  in the document.

  The object documents support the notion of "object collections",
  that are eventually translated into one or more linked object
  streams.

- Objects: simple types, dictionaries, arrays and streams.

  This part of the API provides functions to create and manipulate
  PDF objects: add key-value pairs to dictionaries, elements to
  arrays, etc.

Please take a look and send your comments to discuss: it is capital to
come with a useful and complete API for the object layer.

Note that:

1) The document layer (managing annotations, the document page
   structure, etc) will be built using the object layer API.

2) Would be good to publish the API of the parser, but it is not
   included in this draft.

3) It is not clear to me where to put the pdf creation functions
   (currently pdf_obj_new_array, etc). Since every object is
   associated with a document, it may be advisable to move the
   function names to pdf_obj_doc_new_array, etc...

4) Not all of the usage examples are written: to write more examples
   is a good way to proof the consistency and usefulness of the API:
   missing examples are welcome :)

5) The object layer is wrapping all the lexical, syntactic and
   organizational aspects of the object hierarchy. This includes:

   + Cross references tables.
   + Cross references streams.
   + Object streams.
   + linearized documents.

   The client of the object layer should not be aware of those issues.

6) I am still working in the first draft of the internal architecture
   of the layer. Don't assume that the pdf_obj_doc_t type will be
   implemented in a different module than the pdf_obj_t type, for
   instance.


-- 
Jose E. Marchesi  <address@hidden>
                  http://www.jemarch.net
GNU Project       http://www.gnu.org