[Boost-commit] svn:boost r51067 - in sandbox/thread_safe_signals/trunk/libs/signals2: doc doc/snippets example

Subject: [Boost-commit] svn:boost r51067 - in sandbox/thread_safe_signals/trunk/libs/signals2: doc doc/snippets example
From: fmhess_at_[hidden]
Date: 2009-02-06 16:48:37

Author: fmhess
Date: 2009-02-06 16:48:35 EST (Fri, 06 Feb 2009)
New Revision: 51067
URL: http://svn.boost.org/trac/boost/changeset/51067

Log:
Hacked up a little program for extracting code snippets from example
programs, and included some of the snippets into the tutorial.

Added:
   sandbox/thread_safe_signals/trunk/libs/signals2/doc/snippets/
   sandbox/thread_safe_signals/trunk/libs/signals2/doc/snippets/good_morining_def_code_snippet.txt   (contents, props changed)
   sandbox/thread_safe_signals/trunk/libs/signals2/doc/snippets/good_morning_def_code_snippet.txt   (contents, props changed)
   sandbox/thread_safe_signals/trunk/libs/signals2/doc/snippets/hello_def_code_snippet.txt   (contents, props changed)
   sandbox/thread_safe_signals/trunk/libs/signals2/doc/snippets/hello_world_def_code_snippet.txt   (contents, props changed)
   sandbox/thread_safe_signals/trunk/libs/signals2/doc/snippets/hello_world_multi_code_snippet.txt   (contents, props changed)
   sandbox/thread_safe_signals/trunk/libs/signals2/doc/snippets/hello_world_ordered_code_snippet.txt   (contents, props changed)
   sandbox/thread_safe_signals/trunk/libs/signals2/doc/snippets/hello_world_ordered_invoke_code_snippet.txt   (contents, props changed)
   sandbox/thread_safe_signals/trunk/libs/signals2/doc/snippets/hello_world_single_code_snippet.txt   (contents, props changed)
   sandbox/thread_safe_signals/trunk/libs/signals2/doc/snippets/snippet_extractor.cpp   (contents, props changed)
   sandbox/thread_safe_signals/trunk/libs/signals2/doc/snippets/world_def_code_snippet.txt   (contents, props changed)
Text files modified: 
   sandbox/thread_safe_signals/trunk/libs/signals2/doc/tutorial.xml                   |   135 ++++++++++----------------------------- 
   sandbox/thread_safe_signals/trunk/libs/signals2/example/hello_world_multi_slot.cpp |     6 +                                       
   sandbox/thread_safe_signals/trunk/libs/signals2/example/hello_world_slot.cpp       |     4 +                                       
   sandbox/thread_safe_signals/trunk/libs/signals2/example/ordering_slots.cpp         |     7 ++                                      
   4 files changed, 54 insertions(+), 98 deletions(-)

Added: sandbox/thread_safe_signals/trunk/libs/signals2/doc/snippets/good_morining_def_code_snippet.txt
==============================================================================
--- (empty file)
+++ sandbox/thread_safe_signals/trunk/libs/signals2/doc/snippets/good_morining_def_code_snippet.txt	2009-02-06 16:48:35 EST (Fri, 06 Feb 2009)
@@ -0,0 +1,7 @@
+struct GoodMorning
+{
+  void operator()() const
+  {
+    std::cout << "... and good morning!" << std::endl;
+  }
+};

Added: sandbox/thread_safe_signals/trunk/libs/signals2/doc/snippets/good_morning_def_code_snippet.txt
==============================================================================
--- (empty file)
+++ sandbox/thread_safe_signals/trunk/libs/signals2/doc/snippets/good_morning_def_code_snippet.txt	2009-02-06 16:48:35 EST (Fri, 06 Feb 2009)
@@ -0,0 +1,7 @@
+struct GoodMorning
+{
+  void operator()() const
+  {
+    std::cout << "... and good morning!" << std::endl;
+  }
+};

Added: sandbox/thread_safe_signals/trunk/libs/signals2/doc/snippets/hello_def_code_snippet.txt
==============================================================================
--- (empty file)
+++ sandbox/thread_safe_signals/trunk/libs/signals2/doc/snippets/hello_def_code_snippet.txt	2009-02-06 16:48:35 EST (Fri, 06 Feb 2009)
@@ -0,0 +1,7 @@
+struct Hello
+{
+  void operator()() const
+  {
+    std::cout << "Hello";
+  }
+};

Added: sandbox/thread_safe_signals/trunk/libs/signals2/doc/snippets/hello_world_def_code_snippet.txt
==============================================================================
--- (empty file)
+++ sandbox/thread_safe_signals/trunk/libs/signals2/doc/snippets/hello_world_def_code_snippet.txt	2009-02-06 16:48:35 EST (Fri, 06 Feb 2009)
@@ -0,0 +1,7 @@
+struct HelloWorld
+{
+  void operator()() const
+  {
+    std::cout << "Hello, World!" << std::endl;
+  }
+};

Added: sandbox/thread_safe_signals/trunk/libs/signals2/doc/snippets/hello_world_multi_code_snippet.txt
==============================================================================
--- (empty file)
+++ sandbox/thread_safe_signals/trunk/libs/signals2/doc/snippets/hello_world_multi_code_snippet.txt	2009-02-06 16:48:35 EST (Fri, 06 Feb 2009)
@@ -0,0 +1,6 @@
+  boost::signals2::signal<void ()> sig;
+
+  sig.connect(Hello());
+  sig.connect(World());
+
+  sig();

Added: sandbox/thread_safe_signals/trunk/libs/signals2/doc/snippets/hello_world_ordered_code_snippet.txt
==============================================================================
--- (empty file)
+++ sandbox/thread_safe_signals/trunk/libs/signals2/doc/snippets/hello_world_ordered_code_snippet.txt	2009-02-06 16:48:35 EST (Fri, 06 Feb 2009)
@@ -0,0 +1,4 @@
+  boost::signals2::signal<void ()> sig;
+
+  sig.connect(1, World());  // connect with group 1
+  sig.connect(0, Hello());  // connect with group 0

Added: sandbox/thread_safe_signals/trunk/libs/signals2/doc/snippets/hello_world_ordered_invoke_code_snippet.txt
==============================================================================
--- (empty file)
+++ sandbox/thread_safe_signals/trunk/libs/signals2/doc/snippets/hello_world_ordered_invoke_code_snippet.txt	2009-02-06 16:48:35 EST (Fri, 06 Feb 2009)
@@ -0,0 +1,8 @@
+  // by default slots are connected at the end of the slot list
+  sig.connect(GoodMorning());
+
+  // slots are invoked this order:
+  // 1) ungrouped slots connected with boost::signals2::at_front
+  // 2) grouped slots according to ordering of their groups
+  // 3) ungrouped slots connected with boost::signals2::at_back
+  sig();

Added: sandbox/thread_safe_signals/trunk/libs/signals2/doc/snippets/hello_world_single_code_snippet.txt
==============================================================================
--- (empty file)
+++ sandbox/thread_safe_signals/trunk/libs/signals2/doc/snippets/hello_world_single_code_snippet.txt	2009-02-06 16:48:35 EST (Fri, 06 Feb 2009)
@@ -0,0 +1,9 @@
+  // Signal with no arguments and a void return value
+  boost::signals2::signal<void ()> sig;
+
+  // Connect a HelloWorld slot
+  HelloWorld hello;
+  sig.connect(hello);
+
+  // Call all of the slots
+  sig();

Added: sandbox/thread_safe_signals/trunk/libs/signals2/doc/snippets/snippet_extractor.cpp
==============================================================================
--- (empty file)
+++ sandbox/thread_safe_signals/trunk/libs/signals2/doc/snippets/snippet_extractor.cpp	2009-02-06 16:48:35 EST (Fri, 06 Feb 2009)
@@ -0,0 +1,69 @@
+// Copyright Frank Mori Hess 2009.
+//
+// Quick hack to extract code snippets from example programs, so
+// they can be included into boostbook.
+//
+// Use, modification and
+// distribution is subject to 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)
+
+#include <fstream>
+#include <iostream>
+#include <sstream>
+#include <stdexcept>
+
+int main(int argc, const char *argv[])
+{
+	static const unsigned num_files = argc - 1;
+	unsigned i;
+	for(i = 0; i < num_files; ++i)
+	{
+		const std::string file_name = argv[1 + i];
+		std::cout << "opening file: " << file_name << std::endl;
+		std::ifstream infile(file_name.c_str());
+		bool inside_snippet = false;
+		std::ofstream snippet_out_file;
+		while(infile.good())
+		{
+			std::string line;
+			getline(infile, line);
+			if(infile.bad()) break;
+			if(inside_snippet)
+			{
+				size_t snippet_end_pos = line.find("//]");
+				if(snippet_end_pos == std::string::npos)
+				{
+					snippet_out_file << line << "\n";
+				}else
+				{
+					inside_snippet = false;
+					std::cout << "done.\n";
+					continue;
+				}
+			}else
+			{
+				size_t snippet_start_pos = line.find("//[");
+				if(snippet_start_pos == std::string::npos)
+				{
+					continue;
+				}else
+				{
+					inside_snippet = true;
+					std::string snippet_name = line.substr(snippet_start_pos + 3);
+					std::istringstream snippet_stream(snippet_name);
+					snippet_stream >> snippet_name;
+					if(snippet_name == "")
+					{
+						throw std::runtime_error("failed to obtain snippet name");
+					}
+					snippet_out_file.close();
+					snippet_out_file.open(std::string(snippet_name + ".txt").c_str());
+					std::cout << "processing snippet \"" << snippet_name << "\"... ";
+					continue;
+				}
+			}
+		}
+	}
+	return 0;
+}

Added: sandbox/thread_safe_signals/trunk/libs/signals2/doc/snippets/world_def_code_snippet.txt
==============================================================================
--- (empty file)
+++ sandbox/thread_safe_signals/trunk/libs/signals2/doc/snippets/world_def_code_snippet.txt	2009-02-06 16:48:35 EST (Fri, 06 Feb 2009)
@@ -0,0 +1,7 @@
+struct World
+{
+  void operator()() const
+  {
+    std::cout << ", World!" << std::endl;
+  }
+};

Modified: sandbox/thread_safe_signals/trunk/libs/signals2/doc/tutorial.xml
==============================================================================
--- sandbox/thread_safe_signals/trunk/libs/signals2/doc/tutorial.xml	(original)
+++ sandbox/thread_safe_signals/trunk/libs/signals2/doc/tutorial.xml	2009-02-06 16:48:35 EST (Fri, 06 Feb 2009)
@@ -51,6 +51,8 @@
 <code>sig</code> like a function to call the slots, which in turns
 invokes <code>HelloWorld::operator()</code> to print "Hello,
 World!".</para>
+<programlisting><xi:include href="./snippets/hello_world_def_code_snippet.txt"
+	xmlns:xi="http://www.w3.org/2001/XInclude" parse="text"/></programlisting>
   <informaltable>
     <tgroup cols="2" align="left">
       <thead>
@@ -62,49 +64,19 @@
       <tbody>
         <row>
           <entry>
-<programlisting>
-struct HelloWorld
-{
-  void operator()() const
-  {
-    std::cout &lt;&lt; "Hello, World!" &lt;&lt; std::endl;
-  }
-};
-
-// ...
-
-// Signal with no arguments and a void return value
-<classname>boost::signals2::signal</classname>&lt;void ()&gt; sig;
-
-// Connect a HelloWorld slot
-HelloWorld hello;
-sig.<methodname>connect</methodname>(hello);
-
-// Call all of the slots
-sig();
-</programlisting>
+<programlisting><xi:include href="./snippets/hello_world_single_code_snippet.txt"
+	xmlns:xi="http://www.w3.org/2001/XInclude" parse="text"/></programlisting>
 </entry>
 <entry>
-<programlisting>
-struct HelloWorld
-{
-  void operator()() const
-  {
-    std::cout &lt;&lt; "Hello, World!" &lt;&lt; std::endl;
-  }
-};
+<programlisting>  // Signal with no arguments and a void return value
+  boost::signals2::signal0&lt;void&gt; sig;
 
-// ...
+  // Connect a HelloWorld slot
+  HelloWorld hello;
+  sig.connect(hello);
 
-// Signal with no arguments and a void return value
-<classname alt="boost::signals2::signalN">boost::signals2::signal0</classname>&lt;void&gt; sig;
-
-// Connect a HelloWorld slot
-HelloWorld hello;
-sig.<methodname>connect</methodname>(hello);
-
-// Call all of the slots
-sig();
+  // Call all of the slots
+  sig();
 </programlisting>
 </entry>
           </row>
@@ -120,26 +92,12 @@
 the work of printing "Hello, World!" into two completely separate
 slots. The first slot will print "Hello" and may look like
 this:</para>
-<programlisting>
-struct Hello
-{
-  void operator()() const
-  {
-    std::cout &lt;&lt; "Hello";
-  }
-};
-</programlisting>
+<programlisting><xi:include href="./snippets/hello_def_code_snippet.txt"
+	xmlns:xi="http://www.w3.org/2001/XInclude" parse="text"/></programlisting>
 <para>The second slot will print ", World!" and a newline, to complete
 the program. The second slot may look like this:</para>
-<programlisting>
-struct World
-{
-  void operator()() const
-  {
-    std::cout &lt;&lt; ", World!" &lt;&lt; std::endl;
-  }
-};
-</programlisting>
+<programlisting><xi:include href="./snippets/world_def_code_snippet.txt"
+	xmlns:xi="http://www.w3.org/2001/XInclude" parse="text"/></programlisting>
 <para>Like in our previous example, we can create a signal
 <code>sig</code> that takes no arguments and has a
 <code>void</code> return value. This time, we connect both a
@@ -156,30 +114,23 @@
       <tbody>
         <row>
           <entry>
-<programlisting>
-<classname>boost::signals2::signal</classname>&lt;void ()&gt; sig;
-
-sig.<methodname>connect</methodname>(Hello());
-sig.<methodname>connect</methodname>(World());
-
-sig();
-</programlisting>
-</entry>
-<entry>
-<programlisting>
-<classname alt="boost::signals2::signalN">boost::signals2::signal0</classname>&lt;void&gt; sig;
+<programlisting><xi:include href="./snippets/hello_world_multi_code_snippet.txt"
+	xmlns:xi="http://www.w3.org/2001/XInclude" parse="text"/></programlisting>
+          </entry>
+          <entry>
+<programlisting>  boost::signals2::signal0&lt;void&gt; sig;
 
-sig.<methodname>connect</methodname>(Hello());
-sig.<methodname>connect</methodname>(World());
+  sig.connect(Hello());
+  sig.connect(World());
 
-sig();
+  sig();
 </programlisting>
 </entry>
             </row>
           </tbody>
         </tgroup>
       </informaltable>
-<para>By default, slots are called in first-in first-out (FIFO) order,
+<para>By default, slots are pushed onto the back of the slot list,
 so the output of this program will be as expected:</para>
 <programlisting>
 Hello, World!
@@ -208,27 +159,21 @@
       <tbody>
         <row>
           <entry>
-<programlisting>
-<classname>boost::signals2::signal</classname>&lt;void ()&gt; sig;
-sig.<methodname>connect</methodname>(1, World());
-sig.<methodname>connect</methodname>(0, Hello());
-sig();
-</programlisting>
+<programlisting><xi:include href="./snippets/hello_world_ordered_code_snippet.txt"
+	xmlns:xi="http://www.w3.org/2001/XInclude" parse="text"/></programlisting>
 </entry>
             <entry>
-<programlisting>
-<classname alt="boost::signals2::signalN">boost::signals2::signal0</classname>&lt;void&gt; sig;
-sig.<methodname>connect</methodname>(1, World());
-sig.<methodname>connect</methodname>(0, Hello());
-sig();
-</programlisting>
+<programlisting>  boost::signals2::signal0&lt;void&gt; sig;
+
+  sig.connect(1, World());  // connect with group 1
+  sig.connect(0, Hello());  // connect with group 0</programlisting>
 </entry>
             </row>
           </tbody>
         </tgroup>
       </informaltable>
 
-<para>This program will correctly print "Hello, World!", because the
+<para>Invoking the signal will correctly print "Hello, World!", because the
 <code>Hello</code> object is in group 0, which precedes group 1 where
 the <code>World</code> object resides. The group
 parameter is, in fact, optional. We omitted it in the first Hello,
@@ -239,7 +184,8 @@
 placed at the front or back of the slot list (by passing
 <code>boost::signals2::at_front</code> or <code>boost::signals2::at_back</code>
 as the last parameter to <code><methodname
-alt="boost::signals2::signalN::connect">connect</methodname></code>, respectively), and defaults to the end of the list. When
+alt="boost::signals2::signalN::connect">connect</methodname></code>, respectively),
+and default to the end of the list. When
 a group is specified, the final <code>at_front</code> or <code>at_back</code>
 parameter describes where the slot
 will be placed within the group ordering.  Ungrouped slots connected with
@@ -250,17 +196,10 @@
 <para>
   If we add a new slot to our example like this:
 </para>
-<programlisting>
-struct GoodMorning
-{
-  void operator()() const
-  {
-    std::cout &lt;&lt; "... and good morning!" &lt;&lt; std::endl;
-  }
-};
-
-sig.<methodname>connect</methodname>(GoodMorning());
-</programlisting>
+<programlisting><xi:include href="./snippets/good_morning_def_code_snippet.txt"
+	xmlns:xi="http://www.w3.org/2001/XInclude" parse="text"/></programlisting>
+<programlisting><xi:include href="./snippets/hello_world_ordered_invoke_code_snippet.txt"
+	xmlns:xi="http://www.w3.org/2001/XInclude" parse="text"/></programlisting>
 <para>... we will get the result we wanted:</para>
 <programlisting>
 Hello, World!

Modified: sandbox/thread_safe_signals/trunk/libs/signals2/example/hello_world_multi_slot.cpp
==============================================================================
--- sandbox/thread_safe_signals/trunk/libs/signals2/example/hello_world_multi_slot.cpp	(original)
+++ sandbox/thread_safe_signals/trunk/libs/signals2/example/hello_world_multi_slot.cpp	2009-02-06 16:48:35 EST (Fri, 06 Feb 2009)
@@ -11,6 +11,7 @@
 #include <iostream>
 #include <boost/signals2/signal.hpp>
 
+//[ hello_def_code_snippet
 struct Hello
 {
   void operator()() const
@@ -18,7 +19,9 @@
     std::cout << "Hello";
   }
 };
+//]
 
+//[ world_def_code_snippet
 struct World
 {
   void operator()() const
@@ -26,15 +29,18 @@
     std::cout << ", World!" << std::endl;
   }
 };
+//]
 
 int main()
 {
+//[ hello_world_multi_code_snippet
   boost::signals2::signal<void ()> sig;
 
   sig.connect(Hello());
   sig.connect(World());
 
   sig();
+//]
 
   return 0;
 };

Modified: sandbox/thread_safe_signals/trunk/libs/signals2/example/hello_world_slot.cpp
==============================================================================
--- sandbox/thread_safe_signals/trunk/libs/signals2/example/hello_world_slot.cpp	(original)
+++ sandbox/thread_safe_signals/trunk/libs/signals2/example/hello_world_slot.cpp	2009-02-06 16:48:35 EST (Fri, 06 Feb 2009)
@@ -11,6 +11,7 @@
 #include <iostream>
 #include <boost/signals2/signal.hpp>
 
+//[ hello_world_def_code_snippet
 struct HelloWorld
 {
   void operator()() const
@@ -18,9 +19,11 @@
     std::cout << "Hello, World!" << std::endl;
   }
 };
+//]
 
 int main()
 {
+//[ hello_world_single_code_snippet
   // Signal with no arguments and a void return value
   boost::signals2::signal<void ()> sig;
 
@@ -30,6 +33,7 @@
 
   // Call all of the slots
   sig();
+//]
 
   return 0;
 };

Modified: sandbox/thread_safe_signals/trunk/libs/signals2/example/ordering_slots.cpp
==============================================================================
--- sandbox/thread_safe_signals/trunk/libs/signals2/example/ordering_slots.cpp	(original)
+++ sandbox/thread_safe_signals/trunk/libs/signals2/example/ordering_slots.cpp	2009-02-06 16:48:35 EST (Fri, 06 Feb 2009)
@@ -27,6 +27,7 @@
   }
 };
 
+//[ good_morning_def_code_snippet
 struct GoodMorning
 {
   void operator()() const
@@ -34,13 +35,18 @@
     std::cout << "... and good morning!" << std::endl;
   }
 };
+//]
 
 int main()
 {
+//[ hello_world_ordered_code_snippet
   boost::signals2::signal<void ()> sig;
 
   sig.connect(1, World());  // connect with group 1
   sig.connect(0, Hello());  // connect with group 0
+//]
+
+//[ hello_world_ordered_invoke_code_snippet
   // by default slots are connected at the end of the slot list
   sig.connect(GoodMorning());
 
@@ -49,6 +55,7 @@
   // 2) grouped slots according to ordering of their groups
   // 3) ungrouped slots connected with boost::signals2::at_back
   sig();
+//]
 
   return 0;
 };