[Boost-commit] svn:boost r7115

From: mconsoni_at_[hidden]
Date: 2007-06-20 16:43:40

Author: mconsoni
Date: 2007-06-20 16:43:39 EDT (Wed, 20 Jun 2007)
New Revision: 7115
URL: http://svn.boost.org/trac/boost/changeset/7115

Log:

New section describing the Info class. It shows the basic Hello World MultiLanguage example and then
summarizes the concepts. 

More on this in tutorial 6.. (I'll describe the IM example).

Added:
   sandbox/libs/extension/doc/info.qbk
Text files modified: 
   sandbox/libs/extension/doc/extension.qbk |     6 ++++--                                  
   1 files changed, 4 insertions(+), 2 deletions(-)

Modified: sandbox/libs/extension/doc/extension.qbk
==============================================================================
--- sandbox/libs/extension/doc/extension.qbk	(original)
+++ sandbox/libs/extension/doc/extension.qbk	2007-06-20 16:43:39 EDT (Wed, 20 Jun 2007)
@@ -1,7 +1,7 @@
 [library Boost.Extension
     [quickbook 1.3]
     [version 1.0]
-    [copyright 2007 Jeremy Pack]
+    [copyright 2007 Jeremy Pack, Mariano G. Consoni]
     [purpose Factory management and facilities for using shared libraries]
     [license
         Distributed under the Boost Software License, Version 1.0.
@@ -21,5 +21,7 @@
 [include tutorials.qbk]
 [include factories.qbk]
 [include shared_libraries.qbk]
+[include info.qbk]
 [include performance_analysis.qbk]
-[include appendices.qbk]
\ No newline at end of file
+[include appendices.qbk]
+

Added: sandbox/libs/extension/doc/info.qbk
==============================================================================
--- (empty file)
+++ sandbox/libs/extension/doc/info.qbk	2007-06-20 16:43:39 EDT (Wed, 20 Jun 2007)
@@ -0,0 +1,153 @@
+[section:info Info Classes]
+
+In this section we explain how to use Info classes in Boost.Extensions. 
+
+Info classes is a mechanism that allows you to store important information of each implementation. The 
+type and utility of this information is arbitrary as the Info class is a template argument of the factories where 
+the user registers its own implementations, and for that reason any kind of information could be stored.
+
+Let's see how can we use it with an example first and then we will be able to summarize the concepts. 
+
+Surely you remember our very first example, that of course it's called 
+HelloWorld. Well, let's imagine that we now want a multi-language Hello World. Of course there are better ways of
+designing it, but as we want to picture how the Info class could be used we'll take this approach.
+
+First, we define an implementation of the =word= interface for each combination of word and language. Then we
+have for example the class =monde= that implements the =word= interface for the french language in this case. 
+
+Let's see the code:
+
+``
+class world : public word
+{
+public:
+	virtual const char * get_val(){return "world!";}
+};
+
+class mundo : public word
+{
+public:
+	virtual const char * get_val(){return "mundo!";}
+};
+
+class monde : public word
+{
+public:
+	virtual const char * get_val(){return "monde!";}
+};
+
+class mondo : public word
+{
+public:
+	virtual const char * get_val(){return "mondo!";}
+};
+
+
+class hello : public word
+{
+public:
+	virtual const char * get_val(){return "hello";}
+};
+
+class hola : public word
+{
+public:
+	virtual const char * get_val(){return "hola";}
+};
+
+class bonjour : public word
+{
+public:
+	virtual const char * get_val(){return "bonjour";}
+};
+
+class buonasera : public word
+{
+public:
+	virtual const char * get_val(){return "buonasera";}
+};
+``
+
+Now we have the word 'hello' and 'world' implemented in several languages.
+
+
+And then, how can we specify, given an implementation of =word= interface, in which language is the translation and
+which is the original word (in a reference language, english in this case)? Well, as we want to store implementation 
+specific information we could use the Info class for this implementations.
+
+We define a new class called =word_description= where we can define the language and the original word. This will
+be our Info class:
+
+``
+struct word_description
+{
+	std::string language;
+	std::string english_translation;
+
+	word_description(std::string language, std::string english_translation)
+		: language(language), english_translation(english_translation) {}
+};
+``
+
+Finally, just store a =word_description= instance when adding the words to the factory map, describing the original
+word and the language:
+
+``
+extern "C" void BOOST_EXTENSION_EXPORT_DECL extension_export_multilanguage_word(boost::extensions::factory_map & fm)
+{
+	fm.add<hola, word, word_description>(word_description("spanish", "hello"));
+	fm.add<mundo, word, word_description>(word_description("spanish", "world!"));
+
+	fm.add<bonjour, word, word_description>(word_description("french", "hello"));
+	fm.add<monde, word, word_description>(word_description("french", "world!"));
+
+	fm.add<buonasera, word, word_description>(word_description("italian", "hello"));
+	fm.add<mondo, word, word_description>(word_description("italian", "world!"));
+
+	fm.add<hello, word, word_description>(word_description("english", "hello"));
+	fm.add<world, word, word_description>(word_description("english", "world!"));
+}
+``
+
+In the code we could see that add argument is a Info class instance. In this case is =word_description=
+which receives the language and word as arguments.
+
+Now we could start using that information in the main code. Rerieving Info class is easy, you should just call
+=get_info()= method of the factory. 
+
+Let's see some code using the multilanguage hello world words:
+
+``
+  for (std::list<factory<word, word_description> >::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() << " is " << current_word->get_info().english_translation 
+           << " in " << current_word->get_info().language << std::endl;
+  }
+  std::cout << std::endl;
+``
+
+And we get the following output:
+
+[table 
+[[[^hola is hello in spanish\n
+mundo! is world! in spanish\n
+bonjour is hello in french\n
+monde! is world! in french\n
+buonasera is hello in italian\n
+mondo! is world! in italian\n
+hello is hello in english\n
+world! is world! in english\n]]]]
+
+Now that we have described our example the major parts could be summarized:
+
+# We just define our interface and implementations normally.
+# We define the Info class.
+# When we add the implementations to the factory_map we construct a new Info class instance
+for each implementation, storing the needed data.
+# Finally, we could use the =get_info= method in the main file to retrieve the data.
+
+Tutorial 5  describes a more complex example of the use of the Info class.
+
+[endsect]
\ No newline at end of file