Index: /main/waeup.sirp/trunk/src/waeup/sirp/accesscodes/catalog.txt
===================================================================
--- /main/waeup.sirp/trunk/src/waeup/sirp/accesscodes/catalog.txt	(revision 5097)
+++ /main/waeup.sirp/trunk/src/waeup/sirp/accesscodes/catalog.txt	(revision 5097)
@@ -0,0 +1,106 @@
+:mod:`waeup.sirp.accesscodes.catalog` -- Cataloging access-codes
+****************************************************************
+
+.. module:: waeup.sirp.accesscodes.catalog
+
+Components that support cataloging and searching accesscodes inside a
+WAeUP SIRP site.
+
+:Test-Layer: functional
+
+.. contents::
+
+
+The `catalog` module of `waeup.sirp.accesscodes` provides a catalog
+for search :class:`waeup.sirp.accesscode.interfaces.IAccessCode`
+objects.
+
+Components
+==========
+
+:class:`AccessCodeCatalog`
+--------------------------
+
+.. class:: AccessCodeCatalog
+
+  .. attribute:: grok.site(waeup.sirp.interfaces.IUniversity)
+  .. attribute:: grok.name('accesscode_catalog')
+  .. attribute:: grok.context(waeup.sirp.accesscodes.interfaces.IAccessCode)
+
+  A catalog is registered each time an IUniversity instance is created
+  and stored in the ZODB:
+
+    >>> from waeup.sirp.app import University
+    >>> u = University()
+    >>> getRootFolder()['u'] = u
+
+  It is setup as a local utility named ``accesscode_catalog``. As a
+  local utility it only catalogs objects of the 'current' site aka
+  `University` object and does not interfere with catalogs for
+  different sites. This means you can safely run different
+  Universities in one instance which won't share their data.
+
+  Furthermore AccessCodeCatalog objects catalog objects of type
+  :class:`waeup.sirp.accesscodes.interfaces.IAccessCode`` only.
+
+    >>> from zope.site.hooks import setSite
+    >>> setSite(u)
+
+    >>> from zope.component import getUtility
+    >>> from zope.catalog.interfaces import ICatalog
+    >>> catalog = getUtility(ICatalog, name=u'accesscode_catalog')
+    >>> catalog
+    <zope.catalog.catalog.Catalog object at 0x...>
+
+  It provides several indexes:
+
+    >>> from pprint import pprint
+    >>> pprint(sorted(list(catalog.items())))
+    [(u'invalidated', <zope...FieldIndex object at 0x...>),
+     (u'name', <zope...FieldIndex object at 0x...>),
+     (u'student_id', <zope...FieldIndex object at 0x...>),
+     (u'text', <zope...text.TextIndex object at 0x...>)]
+
+  The ``invalidated`` index keeps references to the
+  ``invalidation_date`` field of
+  :class:`waeup.sirp.accesscodes.AccessCode` instances. This also
+  means, that you have to look for ``datetime.datetime`` type values.
+
+  The ``text`` and ``name`` indexes both store the ``representation``
+  field of AccessCode instances. While the first is a text index, it
+  allows searching using wildcards. The latter is a field index used
+  in internal search functions.
+
+  ``student_id`` finally is an index to the search for student ids or
+  similar when an access code gets invalidated.
+
+Examples
+========
+
+We register some AccessCodes and search them afterwards.
+
+    >>> from datetime import datetime
+    >>> from waeup.sirp.accesscodes.accesscodes import AccessCodeBatch
+    >>> batch = AccessCodeBatch(
+    ...   datetime(2009, 12, 23), 'Fred','APP', 12.12, 3, num=10)
+    >>> u['accesscodes'].addBatch(batch)
+
+    >>> from zope.site.hooks import setSite
+    >>> setSite(u)
+
+We use the :class:`waeup.sirp.catalog.WAeUPQuery` object defined in
+:mod:`waeup.sirp.catalog`:
+
+    >>> from hurry.query.interfaces import IQuery
+    >>> from zope.component import getUtility
+    >>> q = getUtility(IQuery)
+    >>> q
+    <waeup.sirp.catalog.WAeUPQuery object at 0x...>
+
+    >>> from hurry.query import Text
+    >>> r1 = q.searchResults(
+    ...   Text(('accesscode_catalog', 'text'), 'APP*'))
+    >>> list(r1)
+    [<...AccessCode object at 0x...>,
+     <...AccessCode object at 0x...>,
+     <...AccessCode object at 0x...]
