[Boost-commit] svn:boost r7073

From: mconsoni_at_[hidden]
Date: 2007-06-15 23:29:07

Author: mconsoni
Date: 2007-06-15 23:29:06 EDT (Fri, 15 Jun 2007)
New Revision: 7073
URL: http://svn.boost.org/trac/boost/changeset/7073

Log:

- tutorial3.qbk: just minor sintactic modifications.
- tutorial4.qbk: new tutorial related to the versioning example. It's shows how to load different libraries in
the same factory, loading classes with the same name with or without the same interface.

Text files modified: 
   sandbox/libs/extension/doc/tutorial3.qbk |     4                                         
   sandbox/libs/extension/doc/tutorial4.qbk |   160 +++++++++++++++++++++++++++++++++++++++ 
   2 files changed, 161 insertions(+), 3 deletions(-)

Modified: sandbox/libs/extension/doc/tutorial3.qbk
==============================================================================
--- sandbox/libs/extension/doc/tutorial3.qbk	(original)
+++ sandbox/libs/extension/doc/tutorial3.qbk	2007-06-15 23:29:06 EDT (Fri, 15 Jun 2007)
@@ -1,8 +1,8 @@
 [section:tutorial03 Tutorial 3]
 
 This tutorial shows how to register and instance classes that have multi-argument constructors (not default constructors) 
-in Boost.Extensions. In the example that we will describe in this tutorial we create a dummy class with a constructor
-that have six arguments. We'll register this class in a factory map and then get it from the main file.
+in Boost.Extensions. In the example that we will describe in this tutorial (examples/parameters) we create a dummy class 
+with a constructor that have six arguments. We'll register this class in a factory map and then get it from the main file.
 
 It is expected that before following this tutorial you have gone trough the first tutorial at least, and you are 
 familiar with the basic use of Boost.Extensions

Modified: sandbox/libs/extension/doc/tutorial4.qbk
==============================================================================
--- sandbox/libs/extension/doc/tutorial4.qbk	(original)
+++ sandbox/libs/extension/doc/tutorial4.qbk	2007-06-15 23:29:06 EDT (Fri, 15 Jun 2007)
@@ -1,5 +1,163 @@
 [section:tutorial04 Tutorial 4]
 
-Insert content here.
+TODO: formatting
+
+In this tutorial we will see different features of the library related to multiple loading of the same library, instance or interface.
+
+We will follow some parts of versions example (examples/versioning/). As we expect that at this point you've gone through
+the first tutorials we will not enter into specific details of the use of the library.
+
+First, we want to show that it is possible to load several libraries into one factory map. We'll create a new HelloWorld library
+very similar to the one that we have described in the first tutorial. 
+
+Let's remember the classes that we have implemented (in hello_world.cpp) for the "hello world" example:
+
+``
+class world : public word
+{
+public:
+  virtual const char * get_val(){return "world!";}
+};
+class hello : public word
+{
+public:
+  virtual const char * get_val(){return "hello";}
+};
+extern "C" void BOOST_EXTENSION_EXPORT_DECL extension_export_word(boost::extensions::factory_map & fm)
+{
+  fm.add<hello, word, int>(1);
+  fm.add<world, word, int>(2);
+}
+``
+
+And now let's see the new version that we've implemented for this example (as defined in hello_world_versions.cpp). The 
+classes have the same name and methods, both implement the same interface, but the get_val() methods differ in the 
+returned string (to be able to recognize each one after loading them).
+
+``
+class world : public word
+{
+public:
+  virtual const char * get_val(){return "world! v2";}
+};
+class hello : public word
+{
+public:
+  virtual const char * get_val(){return "| v2 hello";}
+};
+extern "C" void BOOST_EXTENSION_EXPORT_DECL extension_export_word(boost::extensions::factory_map & fm)
+{
+	fm.add<hello, word, int>(21);	// int could be used as version (v2 word 1)
+	fm.add<world, word, int>(22);	// int could be used as version (v2 word 2)
+}
+``
+
+Also note that we are using the Info int to store some kind of "version", and then we could diferrentiate the classes
+by its int (see Info class tutorial for more information on this).
+
+``
+	factory_map fm;
+
+	// load hello world first version
+	load_single_library(fm, "libHelloWorldLib.extension", "extension_export_word");
+
+	// load hello world second version
+	load_single_library(fm, "libHelloWorldLibv2.extension", "extension_export_word");
+
+	// load hello world second version again
+	load_single_library(fm, "libHelloWorldLibv2.extension", "extension_export_word");
+``
+
+We can see here that loading multiple libraries is as easy as calling load_single_library for each one and
+using the same factory map.
+
+Then you can access them as any other factory_map:
+
+``
+  for(std::list<factory<word, int> >::iterator current_word = factory_list.begin();
+      current_word != factory_list.end(); ++current_word)
+  {
+    std::auto_ptr<word> word_ptr(current_word->create());
+    std::cout << word_ptr->get_val() << " ";
+  }
+  std::cout << std::endl << std::endl;
+``
+
+We get the following output:
+
+TODO: output font
+
+words: 
+hello world! | v2 hello world! v2 | v2 hello world! v2 
+
+The first "hello world" is returned by the first version of the library, and the second and third retruned by the second version.
+
+Finally, we will show another example similar to the former but in this case we implement a different interface, same class
+name ('hello') but with different interface ('salute').
+
+Let's see the interface:
+
+``
+class salute
+{
+public:
+  virtual ~salute(){}
+  virtual const char * say(){return "";}
+};
+``
+
+And the implementations:
+
+``
+class hello : public salute
+{
+public:
+	virtual const char *say(void) {return "hello";}
+};
+
+class bye : public salute
+{
+public:
+	virtual const char *say(void) {return "bye!";}
+};
+
+
+extern "C" void BOOST_EXTENSION_EXPORT_DECL extension_export_salute(boost::extensions::factory_map & fm)
+{
+	fm.add<hello, salute, int>(1);
+	fm.add<bye, salute, int>(2);
+}
+``
+
+Note that we are adding a new class called 'hello' too but that implements 'salute' interface.
+
+\n
+
+Finally in the main function we get the factory list specifying that we want the 'salute' factory. We
+iterate it getting each of the salutes, including hello.
+
+``
+  std::list<factory<salute, int> > & salute_factory_list = fm.get<salute, int>();  
+
+  std::cout << "salutes: " << std::endl;
+  for (std::list<factory<salute, int> >::iterator current_salute = salute_factory_list.begin();
+     current_salute != salute_factory_list.end(); ++current_salute)
+  {
+    std::auto_ptr<salute> salute_ptr(current_salute->create());
+    std::cout << salute_ptr->say() << " ";
+  }
+  std::cout << std::endl;
+``
+
+The output is:
+
+TODO: output
+
+salutes: 
+hello bye! 
+
+
+In conclusion, with Boost.Extension we can implement the same class in different libraries, the same class for different interfaces and
+load multiple libraries into the same factory.
 
 [endsect]
\ No newline at end of file