% $Id: ldif.tex,v 1.8 2006/08/15 11:55:08 stroeder Exp $

% ==== 1. ====
% The section prologue.  Give the section a title and provide some
% meta-information.  References to the module should use
% \refbimodindex, \refstmodindex, \refexmodindex or \refmodindex, as
% appropriate.

\section{\module{ldif} ---
         LDIF parser and generator}

\declaremodule{standard}{ldif}

% Author of the module code;
\moduleauthor{python-ldap developers}{python-ldap-dev@lists.sourceforge.net}
% Author of the documentation,
\sectionauthor{Michael Str\"oder}{michael@stroeder.com}

% Leave at least one blank line after this, to simplify ad-hoc tools
% that are sometimes used to massage these files.
\modulesynopsis{Parses and generates LDIF files}


% ==== 2. ====
% Give a short overview of what the module does.
% If it is platform specific, mention this.
% Mention other important restrictions or general operating principles.

This module parses and generates LDAP data in the format LDIF.

It is implemented in pure Python and does not rely on any
non-standard modules. Therefore it can be used stand-alone without
the rest of the python-ldap package.

\begin{seealso}
\seerfc{2849}{The LDAP Data Interchange Format (LDIF) - Technical Specification}{}
\end{seealso}

\subsection{Example \label{ldif-example}}

The following example demonstrates how to write LDIF output
of an LDAP entry with \module{ldif} module.

\begin{verbatim}
>>> import sys,ldif
>>> entry={'objectClass':['top','person'],'cn':['Michael Stroeder'],'sn':['Stroeder']}
>>> dn='cn=Michael Stroeder,ou=Test'
>>> ldif_writer=ldif.LDIFWriter(sys.stdout)
>>> ldif_writer.unparse(dn,entry)
dn: cn=Michael Stroeder,ou=Test
cn: Michael Stroeder
objectClass: top
objectClass: person
sn: Stroeder

>>> 
\end{verbatim}

The following example demonstrates how to parse an LDIF file
with \module{ldif} module, skip some entries and write the result
to stdout.

\begin{verbatim}
import sys
from ldif import LDIFParser, LDIFWriter

skip_dn = ["uid=foo,ou=People,dc=example,dc=com", 
    "uid=bar,ou=People,dc=example,dc=com"]

class MyLDIF(LDIFParser):
    def __init__(self, input, output):
        LDIFParser.__init__(self, input)
        self.writer = LDIFWriter(output)

    def handle(self, dn, entry):
        for i in skip_dn:
            if i == dn: return
	self.writer.unparse(dn, entry)

parser = MyLDIF(open("input.ldif", 'r'), sys.stdout)
parser.parse()
\end{verbatim}

