- Implemented the following doc-programming directives:

    * docAssert
    * docAssign
    * docElse
    * docIf
    * docExec
    * docPara
    * docWhile

CHANGES.txt

@@ -32,6 +32,16 @@ CHANGES
   flexible lists to be created. Also implemented a complimentary ``listStyle``
   directive.
 
+- Implemented the following doc-programming directives:
+
+    * docAssert
+    * docAssign
+    * docElse
+    * docIf
+    * docExec
+    * docPara
+    * docWhile
+
 - Don't show "doc" namespace in reference snippets.
 
 - Create a list of RML2PDF and z3c.rml differences.

RML-DIFFERENCES.txt

@@ -26,20 +26,6 @@ naming.
 
 - blockTable: -repeatRows, -alignment
 
-- docAssert (reportlab.platypus.flowables.DocAssert) (Test 39)
-
-- docAssign (reportlab.platypus.flowables.DocAssign)
-
-- docElse (reportlab.platypus.flowables.DocIf)
-
-- docIf (reportlab.platypus.flowables.DocIf)
-
-- docExec (reportlab.platypus.flowables.DocExec)
-
-- docPara (reportlab.platypus.flowables.DocPara)
-
-- docWhile (reportlab.platypus.flowables.DocWhile)
-
 - drawing
 
 - widget

src/z3c/rml/doclogic.py

@@ -0,0 +1,169 @@
+##############################################################################
+#
+# Copyright (c) 2012 Zope Foundation and Contributors.
+# All Rights Reserved.
+#
+# This software is subject to the provisions of the Zope Public License,
+# Version 2.1 (ZPL).  A copy of the ZPL should accompany this distribution.
+# THIS SOFTWARE IS PROVIDED "AS IS" AND ANY AND ALL EXPRESS OR IMPLIED
+# WARRANTIES ARE DISCLAIMED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+# WARRANTIES OF TITLE, MERCHANTABILITY, AGAINST INFRINGEMENT, AND FITNESS
+# FOR A PARTICULAR PURPOSE.
+#
+##############################################################################
+"""``doc*`` directives.
+"""
+import reportlab.platypus
+from z3c.rml import attr, directive, flowable, interfaces, occurence
+
+class IDocAssign(interfaces.IRMLDirectiveSignature):
+    """Assign a value to the namesapce."""
+
+    var = attr.String(
+        title=u'Variable Name',
+        description=u'The name under which the value is stored.',
+        required=True)
+
+    expr = attr.String(
+        title=u'Expression',
+        description=u'The expression that creates the value when evaluated.',
+        required=True)
+
+class DocAssign(flowable.Flowable):
+    signature = IDocAssign
+    klass = reportlab.platypus.flowables.DocAssign
+
+
+class IDocExec(interfaces.IRMLDirectiveSignature):
+    """Execute a statement."""
+
+    stmt = attr.String(
+        title=u'Statement',
+        description=u'The statement to be executed.',
+        required=True)
+
+class DocExec(flowable.Flowable):
+    signature = IDocExec
+    klass = reportlab.platypus.flowables.DocExec
+
+
+class IDocPara(interfaces.IRMLDirectiveSignature):
+    """Create a paragraph with the value returned from the expression."""
+
+    expr = attr.String(
+        title=u'Expression',
+        description=u'The expression to be executed.',
+        required=True)
+
+    format = attr.String(
+        title=u'Format',
+        description=u'The format used to render the expression value.',
+        required=False)
+
+    style = attr.Style(
+        title=u'Style',
+        description=u'The style of the paragraph.',
+        required=False)
+
+    escape = attr.Boolean(
+        title=u'Escape Text',
+        description=u'When set (default) the expression value is escaped.',
+        required=False)
+
+class DocPara(flowable.Flowable):
+    signature = IDocPara
+    klass = reportlab.platypus.flowables.DocPara
+
+
+class IDocAssert(interfaces.IRMLDirectiveSignature):
+    """Assert a certain condition."""
+
+    cond = attr.String(
+        title=u'Condition',
+        description=u'The condition to be asserted.',
+        required=True)
+
+    format = attr.String(
+        title=u'Format',
+        description=u'The text displayed if assertion fails.',
+        required=False)
+
+class DocAssert(flowable.Flowable):
+    signature = IDocAssert
+    klass = reportlab.platypus.flowables.DocAssert
+
+
+class IDocElse(interfaces.IRMLDirectiveSignature):
+    """Starts 'else' block."""
+
+class DocElse(flowable.Flowable):
+    signature = IDocElse
+
+    def process(self):
+        if not isinstance(self.parent, DocIf):
+            raise ValueError("<docElse> can only be placed inside a <docIf>")
+        self.parent.flow = self.parent.elseFlow
+
+
+class IDocIf(flowable.IFlow):
+    """Display story flow based on the value of the condition."""
+
+    cond = attr.String(
+        title=u'Condition',
+        description=u'The condition to be tested.',
+        required=True)
+
+class DocIf(flowable.Flow):
+    signature = IDocAssert
+    klass = reportlab.platypus.flowables.DocIf
+
+    def __init__(self, *args, **kw):
+        super(flowable.Flow, self).__init__(*args, **kw)
+        self.thenFlow = self.flow = []
+        self.elseFlow = []
+
+    def process(self):
+        args = dict(self.getAttributeValues())
+        self.processSubDirectives()
+        dif = self.klass(
+            thenBlock = self.thenFlow, elseBlock = self.elseFlow, **args)
+        self.parent.flow.append(dif)
+
+class IDocWhile(flowable.IFlow):
+    """Repeat the included directives as long as the condition is true."""
+
+    cond = attr.String(
+        title=u'Condition',
+        description=u'The condition to be tested.',
+        required=True)
+
+class DocWhile(flowable.Flow):
+    signature = IDocAssert
+    klass = reportlab.platypus.flowables.DocWhile
+
+    def process(self):
+        args = dict(self.getAttributeValues())
+        self.processSubDirectives()
+        dwhile = self.klass(whileBlock = self.flow, **args)
+        self.parent.flow.append(dwhile)
+
+
+flowable.Flow.factories['docAssign'] = DocAssign
+flowable.Flow.factories['docExec'] = DocExec
+flowable.Flow.factories['docPara'] = DocPara
+flowable.Flow.factories['docAssert'] = DocAssert
+flowable.Flow.factories['docIf'] = DocIf
+flowable.Flow.factories['docElse'] = DocElse
+flowable.Flow.factories['docWhile'] = DocWhile
+
+flowable.IFlow.setTaggedValue(
+    'directives',
+    flowable.IFlow.getTaggedValue('directives') +
+    (occurence.ZeroOrMore('docAssign', IDocAssign),
+     occurence.ZeroOrMore('docExec', IDocExec),
+     occurence.ZeroOrMore('docPara', IDocPara),
+     occurence.ZeroOrMore('docIf', IDocIf),
+     occurence.ZeroOrMore('docElse', IDocElse),
+     occurence.ZeroOrMore('docWhile', IDocWhile),
+     )
+    )

src/z3c/rml/document.py

@@ -24,8 +24,9 @@
 from reportlab.lib import colors, fonts
 from reportlab.platypus import tableofcontents
 
-from z3c.rml import attr, canvas, directive, interfaces, list, occurence
-from z3c.rml import pdfinclude, special, storyplace, stylesheet, template
+from z3c.rml import attr, canvas, directive, doclogic, interfaces, list
+from z3c.rml import occurence, pdfinclude, special, storyplace, stylesheet
+from z3c.rml import template
 
 
 class IRegisterType1Face(interfaces.IRMLDirectiveSignature):

src/z3c/rml/template.py

@@ -166,22 +166,23 @@ class IPageTemplate(interfaces.IRMLDirectiveSignature):
         description=u'The Page Size.',
         required=False)
 
-    rotation = attr.Integer(
-        title=u'Rotation',
-        description=u'The rotation of the page in multiples of 90 degrees.',
+    autoNextTemplate = attr.String(
+        title=u'Auto Next Page Template',
+        description=u'The page template to use automatically for the next page.',
         required=False)
 
 
 
 class PageTemplate(directive.RMLDirective):
     signature = IPageTemplate
+    attrMapping = {'autoNextTemplate': 'autoNextPageTemplate'}
     factories = {
         'frame': Frame,
         'pageGraphics': PageGraphics,
         }
 
     def process(self):
-        args = dict(self.getAttributeValues())
+        args = dict(self.getAttributeValues(attrMapping=self.attrMapping))
         pagesize = args.pop('pagesize', None)
 
         self.frames = []

src/z3c/rml/tests/input/rml-examples-039-doc-programming.rml

@@ -0,0 +1,149 @@
+<!DOCTYPE document SYSTEM "rml_1_0.dtd">
+<document filename="test_039_doc_programming.pdf" invariant="1">
+
+<template pageSize="letter" leftMargin="72" showBoundary="1">
+<pageTemplate id="main" pageSize="letter portrait">
+	<pageGraphics>
+		<setFont name="Helvetica-Bold" size="18"/>
+		    <drawString x="35" y="760">RML Example 40: Doc_programming</drawString>
+			<image file="logo_no_bar.png" preserveAspectRatio="1" x="488" y="730" width="72" height="72"/>
+    		<image file="strapline.png" preserveAspectRatio="1" x="35" y="0" width="525" />
+	</pageGraphics>
+	<frame id="second" x1="35" y1="45" width="525" height="590"/>
+	</pageTemplate>
+
+	<pageTemplate id="main2" pageSize="letter portrait">
+	<pageGraphics>
+		<setFont name="Helvetica-Bold" size="18"/>
+		    <drawString x="35" y="760">RML Example 40: Doc_programming</drawString>
+			<image file="logo_no_bar.png" preserveAspectRatio="1" x="488" y="730" width="72" height="72"/>
+    		<image file="strapline.png" preserveAspectRatio="1" x="35" y="0" width="525" />
+		<drawRightString x="523" y="800">RML2PDF Test Suite</drawRightString>
+	</pageGraphics>
+	<frame id="second" x1="35" y1="45" width="525" height="685"/>
+	</pageTemplate>
+	<pageTemplate id="autoNextTemplate" pageSize="letter portrait" autoNextTemplate="autoFollow">
+		<pageGraphics>
+			<setFont name="Helvetica-Bold" size="18"/>
+		    <drawString x="35" y="760">RML Example 40: Doc_programming</drawString>
+			<image file="logo_no_bar.png" preserveAspectRatio="1" x="488" y="730" width="72" height="72"/>
+    		<image file="strapline.png" preserveAspectRatio="1" x="35" y="0" width="525" />
+			<drawString x="72" y="72">template is autoNextTemplate</drawString>
+		</pageGraphics>
+		<frame id="second" x1="35" y1="45" width="525" height="685"/>
+	</pageTemplate>
+	<pageTemplate id="autoFollow" pageSize="letter portrait">
+		<pageGraphics>
+			<setFont name="Helvetica-Bold" size="18"/>
+		    <drawString x="35" y="760">RML Example 40: Doc_programming</drawString>
+			<image file="logo_no_bar.png" preserveAspectRatio="1" x="488" y="730" width="72" height="72"/>
+    		<image file="strapline.png" preserveAspectRatio="1" x="35" y="0" width="525" />
+			<drawString x="72" y="72">template is autoFollow</drawString>
+		</pageGraphics>
+		<frame id="second" x1="35" y1="45" width="525" height="685"/>
+	</pageTemplate>
+</template>
+
+<stylesheet>
+	<initialize>
+	<alias id="style.normal" value="style.Normal"/>
+	</initialize>
+	<paraStyle name="h1" fontName="Helvetica-BoldOblique" fontSize="32" leading="36"/>
+	<paraStyle name="normal" fontName="Helvetica" fontSize="10" leading="12"/>
+	<paraStyle name="spaced" fontName="Helvetica" fontSize="10" leading="12"
+		spaceBefore="12" spaceAfter="12"/>
+		<paraStyle name="intro"  fontName="Helvetica" fontSize="12" leading="12" spaceAfter="12"/>
+</stylesheet>
+
+<story>
+<storyPlace x="35" y="660" width="525" height="73" origin="page">
+<para style="intro">RML (Report Markup Language) is ReportLab's own language for specifying the appearance of a printed page, which is converted into PDF by the utility rml2pdf.</para>
+<hr color="white" thickness="8pt"/>
+<para style="intro">These RML samples showcase techniques and features for generating various types of ouput and are distributed within our commercial package as test cases. Each should be self explanatory and stand alone.</para>
+<illustration height="3" width="525" align="center">
+<fill color= "(0,0.99,0.97,0.0)" />
+<rect x="0" y = "-12" width="525" height="3" round="1" fill="1" stroke = "Yes" />
+</illustration>
+</storyPlace>
+<setNextTemplate name="main2"/>
+	<para style="normal">Hello World.  This is a normal paragraph. Blah <font color="red">IPO</font> blah blah blah blah growth forecast blah
+blah blah forecast blah.Blah blah blah blah blah blah blah blah blah blah blah profit blah blah blah blah blah
+blah blah blah blah blah IPO.Blah blah blah blah blah blah blah reengineering blah growth blah blah blah
+proactive direction strategic blah blah blah forward-thinking blah.Blah blah doubletalk blah blah blah blah
+blah profit blah blah growth blah blah blah blah blah profit.Blah blah blah blah venture capital blah blah blah
+blah blah forward-thinking blah. Here are some common characters &amp;#x92; = &#x92;
+	</para>
+	<para style="normal">This is another normal paragraph. Blah IPO blah blah blah blah growth forecast blah
+blah blah forecast blah.Blah blah blah blah blah blah blah blah blah blah blah profit blah blah blah blah blah
+blah blah blah blah blah IPO.Blah blah blah blah blah blah blah reengineering blah growth blah blah blah
+proactive direction strategic blah blah blah forward-thinking blah.Blah blah doubletalk blah blah blah blah
+blah profit blah blah growth blah blah blah blah blah profit.Blah blah blah blah venture capital blah blah blah
+blah blah forward-thinking blah.
+	</para>
+	<para style="normal">
+	I should NOT have a tiny leading space in front of me!
+	</para>
+	<para style="spaced">This is spaced.  There should be 12 points before and after.</para>
+	<para style="normal">Hello World.  This is a normal paragraph. Blah IPO blah blah blah blah growth forecast blah
+blah blah forecast blah.Blah blah blah blah blah blah blah blah blah blah blah profit blah blah blah blah blah
+blah blah blah blah blah IPO.Blah blah blah blah blah blah blah reengineering blah growth blah blah blah
+proactive direction strategic blah blah blah forward-thinking blah.Blah blah doubletalk blah blah blah blah
+blah profit blah blah growth blah blah blah blah blah profit.Blah blah blah blah venture capital blah blah blah
+blah blah forward-thinking blah.
+	</para>
+<docAssign var='currentFrame' expr='doc.frame.id'/>
+<docAssign var='currentPageTemplate' expr='doc.pageTemplate.id'/>
+<docAssign var='aW' expr='availableWidth'/>
+<docAssign var='aH' expr='availableHeight'/>
+<docAssign var='aWH' expr='availableWidth,availableHeight'/>
+<docAssign var='i' expr="3"/>
+<docIf cond='i&gt;3'>
+	<para style="normal">The value of i is larger than 3</para>
+<docElse/>
+	<para style="normal">The value of i is not larger than to 3</para>
+</docIf>
+<docIf cond='i==3'>
+	<para style="normal">The value of i is equal to 3</para>
+<docElse/>
+	<para style="normal">The value of i is not equal to 3</para>
+</docIf>
+<docIf cond='i&lt;3'>
+	<para style="normal">The value of i is less than 3</para>
+<docElse/>
+	<para style="normal">The value of i is not less than to 3</para>
+</docIf>
+<docWhile cond='i'>
+	<docPara expr='i' format='The value of i is %(__expr__)d'/>
+	<docExec stmt='i-=1'/>
+</docWhile>
+<docPara expr='repr(doc._nameSpace)' escape="1"/>
+<docWhile cond="doc.page&lt;3">
+	<nextPage/>
+	<docIf cond="doc.page&lt;3">
+		<para style="normal">This is the thenPart</para>
+		<para style="normal">thenPart.....</para>
+	<docElse/>
+		<para style="normal">This is the elsePart</para>
+		<para style="normal">elsePart.....</para>
+	</docIf>
+</docWhile>
+<para style="normal">Now we should be on page 3</para>
+<setNextTemplate name="autoNextTemplate"/>
+<nextPage/>
+<para style="normal">This should be on a template called autoNextTemplate</para>
+<docAssert cond="doc.pageTemplate.id=='autoNextTemplate'" format="expected doc.pageTemplate.id=='autoNextTemplate'"/>
+<nextPage/>
+<para style="normal">This should be on a template called autoFollow</para>
+<docAssert cond="doc.pageTemplate.id=='autoFollow'" format="expected doc.pageTemplate.id=='autoFollow'"/>
+<setNextTemplate name="autoNextTemplate"/>
+<nextPage/>
+<para style="normal">(2)This should be on a template called autoNextTemplate</para>
+<docAssert cond="doc.pageTemplate.id=='autoNextTemplate'" format="expected doc.pageTemplate.id=='autoNextTemplate'"/>
+<setNextTemplate name="main"/>
+<nextPage/>
+<para style="normal">This should be on a template called main</para>
+<docAssert cond="doc.pageTemplate.id=='main'" format="expected doc.pageTemplate.id=='main'"/>
+
+</story>
+
+</document>