[Boost-commit] svn:boost r86404 - in trunk/libs/log: doc example/doc

Subject: [Boost-commit] svn:boost r86404 - in trunk/libs/log: doc example/doc
From: andrey.semashev_at_[hidden]
Date: 2013-10-23 10:09:36

Author: andysem
Date: 2013-10-23 10:09:36 EDT (Wed, 23 Oct 2013)
New Revision: 86404
URL: http://svn.boost.org/trac/boost/changeset/86404

Log:
Refs #9291. Corrected the docs wrt the problems of using attribute keywords with phoenix::bind or phoenix::function.

Text files modified: 
   trunk/libs/log/doc/expressions.qbk                |     8 ++++++--                                
   trunk/libs/log/doc/tutorial.qbk                   |     2 ++                                      
   trunk/libs/log/example/doc/tutorial_filtering.cpp |     5 +++--                                   
   3 files changed, 11 insertions(+), 4 deletions(-)

Modified: trunk/libs/log/doc/expressions.qbk
==============================================================================
--- trunk/libs/log/doc/expressions.qbk	Wed Oct 23 09:11:31 2013	(r86403)
+++ trunk/libs/log/doc/expressions.qbk	2013-10-23 10:09:36 EDT (Wed, 23 Oct 2013)	(r86404)
@@ -46,7 +46,7 @@
 
 The call to `set_filter` registers a composite filter that consists of two elementary subfilters: the first one checks the severity level, and the second checks the channel name. The call to `set_formatter` installs a formatter that composes a string containing the severity level and the channel name along with the message text.
 
-[heading Customizing fallback policy]
+[section:fallback_policies Customizing fallback policy]
 
 By default, when the requested attribute value is not found in the record, `attr` will return an empty reference. In case of filters, this will result in `false` in any ordering expressions, and in case of formatters the output from the placeholder will be empty. This behavior can be changed:
 
@@ -72,7 +72,9 @@
 
 In `bind` expressions, the bound function object will still receive the [link log.detailed.utilities.value_ref `value_ref`]-wrapped values in place of the modified `attr` placeholder. Even though both `or_throw` and `or_default` modifiers guarantee that the bound function will receive a filled reference, [link log.detailed.utilities.value_ref `value_ref`] is still needed if the value type is specified as a type sequence. Also, the reference wrapper may contain a tag type which may be useful for formatting customization.
 
-[heading Attribute tags and custom formatting operators]
+[endsect]
+
+[section:tags Attribute tags and custom formatting operators]
 
 The `TagT` type in the [link log.detailed.expressions.attr abstract description] of `attr` above is optional and by default is `void`. This is an attribute tag which can be used to customize the output formatters produce for different attributes. This tag is forwarded to the [link log.detailed.utilities.manipulators.to_log `to_log`] manipulator when the extracted attribute value is put to a stream (this behavior is warranted by [link log.detailed.utilities.value_ref `value_ref`] implementation). Here's a quick example:
 
@@ -84,6 +86,8 @@
 
 [endsect]
 
+[endsect]
+
 [section:attr_keywords Defining attribute keywords]
 
     #include <``[boost_log_expressions_keyword_fwd_hpp]``>

Modified: trunk/libs/log/doc/tutorial.qbk
==============================================================================
--- trunk/libs/log/doc/tutorial.qbk	Wed Oct 23 09:11:31 2013	(r86403)
+++ trunk/libs/log/doc/tutorial.qbk	2013-10-23 10:09:36 EDT (Wed, 23 Oct 2013)	(r86404)
@@ -342,6 +342,8 @@
 
 As you can see, the custom formatter receives attribute values wrapped into the [link log.detailed.utilities.value_ref `value_ref`] template. This wrapper contains an optional reference to the attribute value of the specified type; the reference is valid if the log record contains the attribute value of the required type. The relational operators used in `my_filter` can be applied unconditionally because they will automatically return `false` if the reference is not valid. The rest is done with the `bind` expression which will recognize the `severity` and `tag_attr` keywords and extract the corresponding values before passing them to `my_filter`.
 
+[note Because of limitations related to the integration with __boost_phoenix__ (see [ticket 7996]), it is required to explicitly specify the fallback policy in case if the attribute value is missing, when attribute keywords are used with `phoenix::bind` or `phoenix::function`. In the example above, this is done by calling `or_none`, which results in an empty [link log.detailed.utilities.value_ref `value_ref`] if the value is not found. In other contexts this policy is the default. There are [link log.detailed.expressions.attr.fallback_policies other policies] that can be used instead.]
+
 You can try how this works by compiling and running the [@boost:/libs/log/example/doc/tutorial_filtering.cpp test].
 
 [endsect]

Modified: trunk/libs/log/example/doc/tutorial_filtering.cpp
==============================================================================
--- trunk/libs/log/example/doc/tutorial_filtering.cpp	Wed Oct 23 09:11:31 2013	(r86403)
+++ trunk/libs/log/example/doc/tutorial_filtering.cpp	2013-10-23 10:09:36 EDT (Wed, 23 Oct 2013)	(r86404)
@@ -111,7 +111,8 @@
 #if 0
 
 //[ example_tutorial_filtering_bind
-bool my_filter(logging::value_ref< severity_level > const& level, logging::value_ref< std::string > const& tag)
+bool my_filter(logging::value_ref< severity_level, tag::severity > const& level,
+               logging::value_ref< std::string, tag::tag_attr > const& tag)
 {
     return level >= warning || tag == "IMPORTANT_MESSAGE";
 }
@@ -152,7 +153,7 @@
     // ...
 
     namespace phoenix = boost::phoenix;
-    sink->set_filter(phoenix::bind(&my_filter, severity, tag_attr));
+    sink->set_filter(phoenix::bind(&my_filter, severity.or_none(), tag_attr.or_none()));
 
     // ...
     //<-