Boost logo

Boost-Commit :

Date view Thread view Subject view Author view

Subject: [Boost-commit] svn:boost r53295 - in trunk/libs/spirit/repository: doc/html doc/html/spirit_repository doc/karma doc/qi example/karma
From: hartmut.kaiser_at_[hidden]
Date: 2009-05-26 22:08:45

Author: hkaiser
Date: 2009-05-26 22:08:43 EDT (Tue, 26 May 2009)
New Revision: 53295
URL: http://svn.boost.org/trac/boost/changeset/53295

Log:
Spirit: more work on first repository example
Added:
   trunk/libs/spirit/repository/doc/qi/
   trunk/libs/spirit/repository/example/karma/confix.cpp (contents, props changed)
Text files modified:
   trunk/libs/spirit/repository/doc/html/index.html | 4
   trunk/libs/spirit/repository/doc/html/spirit_repository/karma_components.html | 221 ++++++++++++++++++++++++---------------
   trunk/libs/spirit/repository/doc/html/spirit_repository/preface.html | 8
   trunk/libs/spirit/repository/doc/karma/confix.qbk | 67 ++++++++---
   4 files changed, 193 insertions(+), 107 deletions(-)

Modified: trunk/libs/spirit/repository/doc/html/index.html
==============================================================================
--- trunk/libs/spirit/repository/doc/html/index.html (original)
+++ trunk/libs/spirit/repository/doc/html/index.html 2009-05-26 22:08:43 EDT (Tue, 26 May 2009)
@@ -34,7 +34,7 @@
 <div><p class="copyright">Copyright © 2001-2009 Joel
       de Guzman, Hartmut Kaiser</p></div>
 <div><div class="legalnotice" title="Legal Notice">
-<a name="id785119"></a><p>
+<a name="id662785"></a><p>
         Distributed under the Boost Software License, Version 1.0. (See accompanying
         file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
       </p>
@@ -70,7 +70,7 @@
 </div>
 </div>
 <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
-<td align="left"><p><small>Last revised: May 26, 2009 at 23:38:37 GMT</small></p></td>
+<td align="left"><p><small>Last revised: May 27, 2009 at 02:06:39 GMT</small></p></td>
 <td align="right"><div class="copyright-footer"></div></td>
 </tr></table>
 <hr>

Modified: trunk/libs/spirit/repository/doc/html/spirit_repository/karma_components.html
==============================================================================
--- trunk/libs/spirit/repository/doc/html/spirit_repository/karma_components.html (original)
+++ trunk/libs/spirit/repository/doc/html/spirit_repository/karma_components.html 2009-05-26 22:08:43 EDT (Tue, 26 May 2009)
@@ -49,7 +49,7 @@
         Confix Generator</a>
 </h4></div></div></div>
 <a name="spirit_repository.karma_components.karma_generator_primitives.karma_confix_generator.description"></a><h6>
-<a name="id785515"></a>
+<a name="id663181"></a>
           <a class="link" href="karma_components.html#spirit_repository.karma_components.karma_generator_primitives.karma_confix_generator.description">Description</a>
         </h6>
 <p>
@@ -66,7 +66,7 @@
 <pre class="programlisting"><span class="identifier">confix</span><span class="special">(</span><span class="identifier">prefix</span><span class="special">,</span> <span class="identifier">suffix</span><span class="special">)[</span><span class="identifier">subject</span><span class="special">]</span>
 </pre>
 <p>
- which results in generating the sequence equivalent to
+ which results in generating a sequence equivalent to
         </p>
 <pre class="programlisting"><span class="identifier">prefix</span> <span class="special">&lt;&lt;</span> <span class="identifier">subject</span> <span class="special">&lt;&lt;</span> <span class="identifier">suffix</span>
 </pre>
@@ -116,19 +116,19 @@
           tag using a simple: <code class="computeroutput"><span class="identifier">ol</span><span class="special">[</span><span class="string">"Some text"</span><span class="special">]</span></code> (which results in <code class="computeroutput"><span class="special">&lt;</span><span class="identifier">ol</span><span class="special">&gt;</span><span class="identifier">Some</span> <span class="identifier">text</span><span class="special">&lt;/</span><span class="identifier">ol</span><span class="special">&gt;</span></code>).
         </p>
 <a name="spirit_repository.karma_components.karma_generator_primitives.karma_confix_generator.header"></a><h6>
-<a name="id786439"></a>
+<a name="id664105"></a>
           <a class="link" href="karma_components.html#spirit_repository.karma_components.karma_generator_primitives.karma_confix_generator.header">Header</a>
         </h6>
 <pre class="programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">spirit</span><span class="special">/</span><span class="identifier">repository</span><span class="special">/</span><span class="identifier">include</span><span class="special">/</span><span class="identifier">karma_confix</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
 </pre>
 <a name="spirit_repository.karma_components.karma_generator_primitives.karma_confix_generator.synopsis"></a><h6>
-<a name="id786508"></a>
+<a name="id664174"></a>
           <a class="link" href="karma_components.html#spirit_repository.karma_components.karma_generator_primitives.karma_confix_generator.synopsis">Synopsis</a>
         </h6>
 <pre class="programlisting"><span class="identifier">confix</span><span class="special">(</span><span class="identifier">prefix</span><span class="special">,</span> <span class="identifier">suffix</span><span class="special">)[</span><span class="identifier">subject</span><span class="special">]</span>
 </pre>
 <a name="spirit_repository.karma_components.karma_generator_primitives.karma_confix_generator.parameters"></a><h6>
-<a name="id786556"></a>
+<a name="id664222"></a>
           <a class="link" href="karma_components.html#spirit_repository.karma_components.karma_generator_primitives.karma_confix_generator.parameters">Parameters</a>
         </h6>
 <div class="informaltable"><table class="table">
@@ -194,95 +194,150 @@
 </tbody>
 </table></div>
 <p>
- All
+ All three parameters can be arbitrary complex generators themselves.
         </p>
-<a name="spirit_repository.karma_components.karma_generator_primitives.karma_confix_generator.model_of"></a><h6>
-<a name="id790012"></a>
- <a class="link" href="karma_components.html#spirit_repository.karma_components.karma_generator_primitives.karma_confix_generator.model_of">Model
- of</a>
+<a name="spirit_repository.karma_components.karma_generator_primitives.karma_confix_generator.attribute"></a><h6>
+<a name="id667679"></a>
+ <a class="link" href="karma_components.html#spirit_repository.karma_components.karma_generator_primitives.karma_confix_generator.attribute">Attribute</a>
         </h6>
 <p>
- Link to concept
+ The <code class="computeroutput"><span class="identifier">confix</span></code> component exposes
+ the attribute type of its subject as its own attribute type. If the <code class="computeroutput"><span class="identifier">subject</span></code> does not expose any attribute
+ (the type is <code class="computeroutput"><span class="identifier">unused_type</span></code>),
+ then the <code class="computeroutput"><span class="identifier">confix</span></code> does not
+ expose anz attribute either.
         </p>
-<a name="spirit_repository.karma_components.karma_generator_primitives.karma_confix_generator.objects"></a><h6>
-<a name="id790029"></a>
- <a class="link" href="karma_components.html#spirit_repository.karma_components.karma_generator_primitives.karma_confix_generator.objects">Objects</a>
+<pre class="programlisting"><span class="identifier">a</span><span class="special">:</span> <span class="identifier">A</span> <span class="special">--&gt;</span> <span class="identifier">confix</span><span class="special">(</span><span class="identifier">p</span><span class="special">,</span> <span class="identifier">s</span><span class="special">)[</span><span class="identifier">a</span><span class="special">]:</span> <span class="identifier">A</span>
+</pre>
+<div class="note" title="Note"><table border="0" summary="Note">
+<tr>
+<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../images/note.png"></td>
+<th align="left">Note</th>
+</tr>
+<tr><td align="left" valign="top"><p>
+ This notation is used all over the Spirit documentation and reads as:
+ Given, <code class="computeroutput"><span class="identifier">a</span></code> is generator,
+ and <code class="computeroutput"><span class="identifier">A</span></code> is the type of
+ the attribute of generator <code class="computeroutput"><span class="identifier">a</span></code>,
+ then the type of the attribute exposed by <code class="computeroutput"><span class="identifier">confix</span><span class="special">(</span><span class="identifier">p</span><span class="special">,</span> <span class="identifier">s</span><span class="special">)[</span><span class="identifier">a</span><span class="special">]</span></code> will be <code class="computeroutput"><span class="identifier">A</span></code>
+ as well.
+ </p></td></tr>
+</table></div>
+<a name="spirit_repository.karma_components.karma_generator_primitives.karma_confix_generator.example"></a><h6>
+<a name="id667854"></a>
+ <a class="link" href="karma_components.html#spirit_repository.karma_components.karma_generator_primitives.karma_confix_generator.example">Example</a>
         </h6>
 <p>
- Objects provided by the library
+ The following example shows simple use cases of the <code class="computeroutput"><span class="identifier">confix</span></code>
+ generator. We will illustrate its usage by generating different comment
+ styles and a function prototype (for the full example code see here: confix.cpp)
         </p>
-<div class="variablelist" title="Notation">
-<p class="title"><b>Notation</b></p>
-<dl>
-<dt><span class="term"><code class="computeroutput"><span class="identifier">xxx</span></code></span></dt>
-<dd><p>
- An XXX
- </p></dd>
-</dl>
-</div>
+<a name="spirit_repository.karma_components.karma_generator_primitives.karma_confix_generator.prerequisites"></a><h6>
+<a name="id667884"></a>
+ <a class="link" href="karma_components.html#spirit_repository.karma_components.karma_generator_primitives.karma_confix_generator.prerequisites">Prerequisites</a>
+ </h6>
 <p>
- Semantics of an expression is defined only where it differs from, or is
- not defined in _concept-of<span class="underline">XXX</span>.
+ In addition to the main header file needed to include the core components
+ implemented in <span class="emphasis"><em>Spirit.Karma</em></span> we add the header file
+ needed for the new <code class="computeroutput"><span class="identifier">confix</span></code>
+ generator.
         </p>
-<div class="informaltable"><table class="table">
-<colgroup>
-<col>
-<col>
-<col>
-<col>
-</colgroup>
-<thead><tr>
-<th>
- <p>
- Expression
- </p>
- </th>
-<th>
- <p>
- Semantics
- </p>
- </th>
-<th>
- <p>
- Return type
- </p>
- </th>
-<th>
- <p>
- Complexity
- </p>
- </th>
-</tr></thead>
-<tbody><tr>
-<td>
- <p>
- <code class="computeroutput"><span class="identifier">xxx</span></code>
- </p>
- </td>
-<td>
- <p>
- Semantics of <code class="computeroutput"><span class="identifier">xxx</span></code>
- </p>
- </td>
-<td>
- <p>
- XXX
- </p>
- </td>
-<td>
- <p>
- Constant
- </p>
- </td>
-</tr></tbody>
-</table></div>
-<a name="spirit_repository.karma_components.karma_generator_primitives.karma_confix_generator.example"></a><h6>
-<a name="id790168"></a>
- <a class="link" href="karma_components.html#spirit_repository.karma_components.karma_generator_primitives.karma_confix_generator.example">Example</a>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">spirit</span><span class="special">/</span><span class="identifier">include</span><span class="special">/</span><span class="identifier">karma</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
+<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">spirit</span><span class="special">/</span><span class="identifier">repository</span><span class="special">/</span><span class="identifier">include</span><span class="special">/</span><span class="identifier">karma_confix</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
+</pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ To make all the code below more readable we introduce the following namespaces.
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting"><span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">spirit</span><span class="special">;</span>
+<span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">spirit</span><span class="special">::</span><span class="identifier">ascii</span><span class="special">;</span>
+<span class="keyword">using</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">spirit</span><span class="special">::</span><span class="identifier">repository</span><span class="special">::</span><span class="identifier">confix</span><span class="special">;</span>
+</pre>
+<p>
+ </p>
+<p>
+ </p>
+<a name="spirit_repository.karma_components.karma_generator_primitives.karma_confix_generator.generating_different_comment_styles"></a><h6>
+<a name="id668127"></a>
+ <a class="link" href="karma_components.html#spirit_repository.karma_components.karma_generator_primitives.karma_confix_generator.generating_different_comment_styles">Generating
+ Different Comment Styles</a>
         </h6>
 <p>
- Real example code. Use Quickbook import mechanism to link to actual working
- code snippets here.
+ We will show how to generate different comment styles. First we will generate
+ a C++ comment:
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting"><span class="comment">// C++ comment
+</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span>
+ <span class="identifier">karma</span><span class="special">::</span><span class="identifier">format_delimited</span><span class="special">(</span>
+ <span class="identifier">confix</span><span class="special">(</span><span class="string">"//"</span><span class="special">,</span> <span class="identifier">eol</span><span class="special">)[</span><span class="identifier">string</span><span class="special">],</span> <span class="comment">// format description
+</span> <span class="identifier">space</span><span class="special">,</span> <span class="comment">// delimiter
+</span> <span class="string">"This is a comment"</span> <span class="comment">// data
+</span> <span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
+</pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ This code snippet will obviouly generate <code class="computeroutput"><span class="comment">//
+ This is a comment \n </span></code>. Similarily generating a 'C'-style
+ comment proves to be straightforward:
+ </p>
+<p>
+ which again will generate <code class="computeroutput"><span class="comment">/* This is a comment
+ */</span> </code>.
+ </p>
+<a name="spirit_repository.karma_components.karma_generator_primitives.karma_confix_generator.generating_a_function_prototype"></a><h6>
+<a name="id668298"></a>
+ <a class="link" href="karma_components.html#spirit_repository.karma_components.karma_generator_primitives.karma_confix_generator.generating_a_function_prototype">Generating
+ a Function Prototype</a>
+ </h6>
+<p>
+ Generating a function prototype given a function name a vector or parameter
+ names is simple as well:
+ </p>
+<p>
+ </p>
+<p>
+
+</p>
+<pre class="programlisting"><span class="comment">// Generate a function call with an arbitrary parameter list
+</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special">&lt;</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span><span class="special">&gt;</span> <span class="identifier">parameters</span><span class="special">;</span>
+<span class="identifier">parameters</span><span class="special">.</span><span class="identifier">push_back</span><span class="special">(</span><span class="string">"par1"</span><span class="special">);</span>
+<span class="identifier">parameters</span><span class="special">.</span><span class="identifier">push_back</span><span class="special">(</span><span class="string">"par2"</span><span class="special">);</span>
+<span class="identifier">parameters</span><span class="special">.</span><span class="identifier">push_back</span><span class="special">(</span><span class="string">"par3"</span><span class="special">);</span>
+
+<span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span>
+ <span class="identifier">karma</span><span class="special">::</span><span class="identifier">format</span><span class="special">(</span>
+ <span class="identifier">string</span> <span class="special">&lt;&lt;</span> <span class="identifier">confix</span><span class="special">(</span><span class="char">'('</span><span class="special">,</span> <span class="char">')'</span><span class="special">)[</span><span class="identifier">string</span> <span class="special">%</span> <span class="char">','</span><span class="special">],</span> <span class="comment">// format description
+</span> <span class="string">"func"</span><span class="special">,</span> <span class="comment">// function name
+</span> <span class="identifier">parameters</span> <span class="comment">// parameter names
+</span> <span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
+</pre>
+<p>
+ </p>
+<p>
+ </p>
+<p>
+ which generates the expected output: <code class="computeroutput"><span class="identifier">func</span><span class="special">(</span><span class="identifier">par1</span><span class="special">,</span> <span class="identifier">par2</span><span class="special">,</span> <span class="identifier">par3</span><span class="special">)</span></code>.
         </p>
 </div>
 </div>

Modified: trunk/libs/spirit/repository/doc/html/spirit_repository/preface.html
==============================================================================
--- trunk/libs/spirit/repository/doc/html/spirit_repository/preface.html (original)
+++ trunk/libs/spirit/repository/doc/html/spirit_repository/preface.html 2009-05-26 22:08:43 EDT (Tue, 26 May 2009)
@@ -27,7 +27,7 @@
 <a name="spirit_repository.preface"></a><a class="link" href="preface.html" title="Preface">Preface</a>
 </h2></div></div></div>
 <a name="spirit_repository.preface.the_spirit_repository"></a><h4>
-<a name="id785149"></a>
+<a name="id662815"></a>
       <a class="link" href="preface.html#spirit_repository.preface.the_spirit_repository">The Spirit
       Repository</a>
     </h4>
@@ -40,7 +40,7 @@
       General List</a>.
     </p>
 <a name="spirit_repository.preface.how_to_use_this_manual"></a><h4>
-<a name="id785183"></a>
+<a name="id662850"></a>
       <a class="link" href="preface.html#spirit_repository.preface.how_to_use_this_manual">How to use
       this manual</a>
     </h4>
@@ -49,7 +49,7 @@
       icons precede some text to indicate:
     </p>
 <div class="table">
-<a name="id785197"></a><p class="title"><b>Table 1. Icons</b></p>
+<a name="id662863"></a><p class="title"><b>Table 1. Icons</b></p>
 <div class="table-contents"><table class="table" summary="Icons">
 <colgroup>
 <col>
@@ -170,7 +170,7 @@
       Tools</a>.
     </p>
 <a name="spirit_repository.preface.support"></a><h4>
-<a name="id785438"></a>
+<a name="id663104"></a>
       <a class="link" href="preface.html#spirit_repository.preface.support">Support</a>
     </h4>
 <p>

Modified: trunk/libs/spirit/repository/doc/karma/confix.qbk
==============================================================================
--- trunk/libs/spirit/repository/doc/karma/confix.qbk (original)
+++ trunk/libs/spirit/repository/doc/karma/confix.qbk 2009-05-26 22:08:43 EDT (Tue, 26 May 2009)
@@ -19,7 +19,7 @@
 
     confix(prefix, suffix)[subject]
 
-which results in generating the sequence equivalent to
+which results in generating a sequence equivalent to
 
     prefix << subject << suffix
 
@@ -90,31 +90,62 @@
                              parts.]]
 ]
 
-All
+All three parameters can be arbitrary complex generators themselves.
 
-[heading Model of]
+[heading Attribute]
 
-Link to concept
+The `confix` component exposes the attribute type of its subject as its own
+attribute type. If the `subject` does not expose any attribute (the type is
+`unused_type`), then the `confix` does not expose anz attribute either.
 
-[heading Objects]
+ a: A --> confix(p, s)[a]: A
 
-Objects provided by the library
+[note This notation is used all over the Spirit documentation and reads as:
+ Given, `a` is generator, and `A` is the type of the attribute of generator
+ `a`, then the type of the attribute exposed by `confix(p, s)[a]` will be
+ `A` as well.]
 
-[variablelist Notation
- [[`xxx`] [An XXX]]
-]
+[heading Example]
 
-Semantics of an expression is defined only where it differs from, or is not
-defined in _concept-of_XXX_.
+The following example shows simple use cases of the `confix` generator. We will
+illustrate its usage by generating different comment styles and a function
+prototype (for the full example code see here:
+[@../../example/karma/confix.cpp confix.cpp])
 
-[table
- [[Expression] [Semantics] [Return type] [Complexity]]
- [[`xxx`] [Semantics of `xxx`] [XXX] [Constant]]
-]
+[import ../example/karma/confix.cpp]
 
-[heading Example]
+[heading Prerequisites]
+
+In addition to the main header file needed to include the core components
+implemented in __karma__ we add the header file needed for the new `confix`
+generator.
+
+[karma_confix_includes]
+
+To make all the code below more readable we introduce the following namespaces.
+
+[karma_confix_namespace]
+
+[heading Generating Different Comment Styles]
+
+We will show how to generate different comment styles. First we will generate
+a C++ comment:
+
+[karma_confix_cpp_comment]
+
+This code snippet will obviouly generate `// This is a comment \n `. Similarily
+generating a 'C'-style comment proves to be straightforward:
+
+
+which again will generate `/* This is a comment */ `.
+
+[heading Generating a Function Prototype]
+
+Generating a function prototype given a function name a vector or parameter
+names is simple as well:
+
+[karma_confix_function]
 
-Real example code. Use Quickbook import mechanism to link to actual
-working code snippets here.
+which generates the expected output: `func(par1,par2,par3)`.
 
 [endsect]

Added: trunk/libs/spirit/repository/example/karma/confix.cpp
==============================================================================
--- (empty file)
+++ trunk/libs/spirit/repository/example/karma/confix.cpp 2009-05-26 22:08:43 EDT (Tue, 26 May 2009)
@@ -0,0 +1,63 @@
+// Copyright (c) 2001-2009 Hartmut Kaiser
+//
+// Distributed under the Boost Software License, Version 1.0. (See accompanying
+// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+
+// The purpose of this example is to demonstrate different use cases for the
+// confix generator.
+
+#include <iostream>
+#include <string>
+#include <vector>
+
+//[karma_confix_includes
+#include <boost/spirit/include/karma.hpp>
+#include <boost/spirit/repository/include/karma_confix.hpp>
+//]
+
+//[karma_confix_namespace
+using namespace boost::spirit;
+using namespace boost::spirit::ascii;
+using boost::spirit::repository::confix;
+//]
+
+int main()
+{
+//[karma_confix_cpp_comment
+ // C++ comment
+ std::cout <<
+ karma::format_delimited(
+ confix("//", eol)[string], // format description
+ space, // delimiter
+ "This is a comment" // data
+ ) << std::endl;
+//]
+
+//[karma_confix_c_comment
+ // C comment
+ std::cout <<
+ karma::format_delimited(
+ confix("/*", "*/")[string], // format description
+ space, // delimiter
+ "This is a comment" // data
+ ) << std::endl;
+//]
+
+//[karma_confix_function
+ // Generate a function call with an arbitrary parameter list
+ std::vector<std::string> parameters;
+ parameters.push_back("par1");
+ parameters.push_back("par2");
+ parameters.push_back("par3");
+
+ std::cout <<
+ karma::format(
+ string << confix('(', ')')[string % ','], // format description
+ "func", // function name
+ parameters // parameter names
+ ) << std::endl;
+//]
+
+ return 0;
+}
+

Date view Thread view Subject view Author view

Boost-Commit list run by bdawes at acm.org, david.abrahams at rcn.com, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk