Merge pull request #4 from steffann/master

Add example support to SchemaType

ZConfig/info.py

@@ -317,6 +317,7 @@ def __init__(self, name, keytype, valuetype, datatype, registry, types):
         self.valuetype = valuetype
         self.handler = None
         self.description = None
+        self.example = None
         self.registry = registry
         self._children = []    # [(key, info), ...]
         self._attrmap = {}     # {attribute: info, ...}
@@ -504,6 +505,7 @@ def createDerivedSchema(base):
                      base.handler, base.url, base.registry)
     new._components.update(base._components)
     new.description = base.description
+    new.example = base.example
     new._children[:] = base._children
     new._attrmap.update(base._attrmap)
     new._keymap.update(base._keymap)

ZConfig/schema.py

@@ -56,7 +56,7 @@ class BaseParser(xml.sax.ContentHandler):
         "description": ["key", "section", "multikey", "multisection",
                         "sectiontype", "abstracttype",
                         "schema", "component"],
-        "example": ["key", "section", "multikey", "multisection"],
+        "example": ["schema", "sectiontype", "key", "multikey"],
         "metadefault": ["key", "section", "multikey", "multisection"],
         "default": ["key", "multikey"],
         "import": ["schema", "component"],
@@ -280,6 +280,9 @@ def characters_description(self, data):
         self._stack[-1].description = data
 
     def characters_example(self, data):
+        if self._stack[-1].example is not None:
+            self.error(
+                "at most one <example> may be used for each element")
         self._stack[-1].example = data
 
     def characters_metadefault(self, data):

ZConfig/tests/test_schema.py

@@ -1084,6 +1084,77 @@ def test_srepr(self):
         self.assertEqual(_srepr('foo'), "'foo'")
         self.assertEqual(_srepr(FOO), "'foo'")
 
+    def test_schema_example(self):
+        schema = self.load_schema_text("""\
+            <schema>
+                <example>  This is an example  </example>
+            </schema>
+            """)
+        self.assertEqual(schema.example, 'This is an example')
+
+    def test_key_example(self):
+        schema = self.load_schema_text("""\
+            <schema>
+                <sectiontype name="abc">
+                    <key name="def">
+                        <example>  This is an example  </example>
+                    </key>
+                </sectiontype>
+            </schema>
+            """)
+        self.assertEqual(schema.gettype('abc').getinfo('def').example, 'This is an example')
+
+    def test_multikey_example(self):
+        schema = self.load_schema_text("""\
+            <schema>
+                <sectiontype name="abc">
+                    <multikey name="def">
+                        <example>  This is an example  </example>
+                    </multikey>
+                </sectiontype>
+            </schema>
+            """)
+        self.assertEqual(schema.gettype('abc').getinfo('def').example, 'This is an example')
+
+    def test_sectiontype_example(self):
+        schema = self.load_schema_text("""\
+            <schema>
+                <sectiontype name="abc">
+                    <example>  This is an example  </example>
+                </sectiontype>
+                <section type="abc" name="def"/>
+            </schema>
+            """)
+        self.assertEqual(schema.gettype('abc').example, 'This is an example')
+
+    def test_multiple_examples_is_error(self):
+        self.assertRaises(ZConfig.SchemaError, self.load_schema_text, """\
+            <schema>
+                <example>  This is an example  </example>
+                <example>  This is an example  </example>
+            </schema>
+            """)
+
+    def test_section_example_is_error(self):
+        self.assertRaises(ZConfig.SchemaError, self.load_schema_text, """\
+            <schema>
+                <sectiontype name="abc"/>
+                <section type="abc" name="def">
+                    <example>  This is an example  </example>
+                </section>
+            </schema>
+            """)
+
+    def test_multisection_example_is_error(self):
+        self.assertRaises(ZConfig.SchemaError, self.load_schema_text, """\
+            <schema>
+                <sectiontype name="abc"/>
+                <multisection type="abc" name="*" attribute="things">
+                    <example>  This is an example  </example>
+                </multisection>
+            </schema>
+            """)
+
 
 def test_suite():
     return unittest.makeSuite(SchemaTestCase)

doc/schema.dtd

@@ -46,7 +46,7 @@
 <!ELEMENT metadefault (#PCDATA)*>
 <!ELEMENT example     (#PCDATA)*>
 
-<!ELEMENT sectiontype (description?, 
+<!ELEMENT sectiontype (description?, example?
                        (section | key | multisection | multikey)*)>
 <!ATTLIST sectiontype
           name       NMTOKEN  #REQUIRED

doc/zconfig.tex

@@ -415,7 +415,7 @@ \subsection{Schema Elements \label{elements}}
   \end{attributedesc}
 \end{elementdesc}
 
-\begin{elementdesc}{sectiontype}{description?, (section | key |
+\begin{elementdesc}{sectiontype}{description?, example?, (section | key |
                                   multisection | multikey)*}
   Define a concrete section type.