Boost-Commit :

Date view	Thread view	Subject view	Author view

Subject: [Boost-commit] svn:boost r67933 - in sandbox/local/libs/local/doc: . images qbk
From: lorcaminiti_at_[hidden]
Date: 2011-01-10 16:15:28

Author: lcaminiti
Date: 2011-01-10 16:15:26 EST (Mon, 10 Jan 2011)
New Revision: 67933
URL: http://svn.boost.org/trac/boost/changeset/67933

Log:
Added doc files.
Added:
   sandbox/local/libs/local/doc/images/
   sandbox/local/libs/local/doc/images/smiley.png (contents, props changed)
   sandbox/local/libs/local/doc/jamfile.jam (contents, props changed)
   sandbox/local/libs/local/doc/qbk/
   sandbox/local/libs/local/doc/qbk/acknowledgements.qbk (contents, props changed)
   sandbox/local/libs/local/doc/qbk/advanced.qbk (contents, props changed)
   sandbox/local/libs/local/doc/qbk/alternatives.qbk (contents, props changed)
   sandbox/local/libs/local/doc/qbk/bibliography.qbk (contents, props changed)
   sandbox/local/libs/local/doc/qbk/examples.qbk (contents, props changed)
   sandbox/local/libs/local/doc/qbk/grammar.qbk (contents, props changed)
   sandbox/local/libs/local/doc/qbk/introduction.qbk (contents, props changed)
   sandbox/local/libs/local/doc/qbk/local.qbk (contents, props changed)
   sandbox/local/libs/local/doc/qbk/releases.qbk (contents, props changed)
   sandbox/local/libs/local/doc/qbk/starting.qbk (contents, props changed)
   sandbox/local/libs/local/doc/qbk/tutorial.qbk (contents, props changed)
Properties modified:
   sandbox/local/libs/local/doc/ (props changed)

Added: sandbox/local/libs/local/doc/images/smiley.png
==============================================================================
Binary file. No diff available.

Added: sandbox/local/libs/local/doc/jamfile.jam
==============================================================================
--- (empty file)
+++ sandbox/local/libs/local/doc/jamfile.jam 2011-01-10 16:15:26 EST (Mon, 10 Jan 2011)
@@ -0,0 +1,52 @@
+
+# Copyright (C) 2009-2011 Lorenzo Caminiti
+# Use, modification, and distribution is subject to the
+# Boost Software License, Version 1.0
+# (see accompanying file LICENSE_1_0.txt or a copy at
+# http://www.boost.org/LICENSE_1_0.txt).
+
+import quickbook ;
+using boostbook ;
+
+doxygen reference
+ :
+ ../../../boost/local/function.hpp
+ ../../../boost/local/block.hpp
+ ../../../boost/local/exit.hpp
+ ../../../boost/local/function_ref.hpp
+ ../../../boost/local/config.hpp
+ ../../../boost/utility/identity.hpp
+ :
+ <doxygen:param>QUIET=YES
+ <doxygen:param>ALIASES=" Params=\"Parameters: <table border="0">\" Param{2}=\"<tr><td><tt>\\1</tt></td><td>\\2</td></tr>\" EndParams=\"</table>\" Returns=\"Returns:\" Note=\"Note:\" Warning=\"Warning:\" See=\"See:\" RefSect{1}=\"\\xmlonly<link linkend='boost_local.\\1'>\\1</link>\\endxmlonly\" RefClass{1}=\"\\xmlonly<computeroutput><classname alt='\\1'>\\1</classname></computeroutput>\\endxmlonly\" RefMacro{1}=\"\\xmlonly<computeroutput><macroname alt='\\1'>\\1</macroname></computeroutput>\\endxmlonly\" "
+ <reftitle>"Reference"
+ ;
+
+xml doc
+ :
+ qbk/local.qbk
+ :
+ <dependency>qbk/introduction.qbk
+ <dependency>qbk/starting.qbk
+ <dependency>qbk/tutorial.qbk
+ <dependency>qbk/advanced.qbk
+ <dependency>reference
+ <dependency>qbk/grammar.qbk
+ <dependency>qbk/alternatives.qbk
+ <dependency>qbk/examples.qbk
+ <dependency>qbk/releases.qbk
+ <dependency>qbk/bibliography.qbk
+ <dependency>qbk/acknowledgements.qbk
+ ;
+
+boostbook standalone
+ :
+ doc
+ :
+ <xsl:param>toc.section.depth=3
+ <xsl:param>toc.max.depth=1
+ <xsl:param>generate.section.toc.level=10
+ <xsl:param>boost.root=../../../..
+ <xsl:param>boost.defaults=Boost
+ ;
+

Added: sandbox/local/libs/local/doc/qbk/acknowledgements.qbk
==============================================================================
--- (empty file)
+++ sandbox/local/libs/local/doc/qbk/acknowledgements.qbk 2011-01-10 16:15:26 EST (Mon, 10 Jan 2011)
@@ -0,0 +1,26 @@
+
+[/ Copyright (C) 2009-2011 Lorenzo Caminiti ]
+[/ Use, modification, and distribution is subject to the ]
+[/ Boost Software License, Version 1.0 ]
+[/ (see accompanying file LICENSE_1_0.txt or a copy at ]
+[/ http://www.boost.org/LICENSE_1_0.txt). ]
+
+[section:Acknowledgments Acknowledgments]
+
+This section attempts to recognize the contributions of /all/ the different people that participated directly or indirectly to the design and development of this library.
+
+Thanks to Steven Watanabe and Vicente Botet for suggesting to use __Boost_ScopeExit__ binding to emulate local functions (in the context of constant-correct checking of block invariants).
+
+Thanks to Alexander Nasonov for clarifying how __Boost_ScopeExit__ binding could be used to implement local functions.
+
+Thanks to Pierre Morcello for suggesting to use `return;` to exit local blocks (in the context of a discussion about a possible [@http://lists.boost.org/Archives/boost/2009/09/156012.php Boost.Breakable] library).
+Thanks to Pierre also for sharing some code that already experimented with implementing local functions using __Boost_ScopeExit__ binding (even if this library was not developed using such a code).
+
+Thanks to John Bytheway for refining the authors' technique that allows this library to pass local functions as template parameters.
+
+Thanks to Jeffrey Lee Hellrung for suggesting the use of the "keyword" `bind` to bind variables in scope.
+
+Finally, many thanks to the entire __Boost__ community and [@http://lists.boost.org mailing list] for providing valuable comments about this library and great insights on the C++ programming language.
+
+[endsect]
+

Added: sandbox/local/libs/local/doc/qbk/advanced.qbk
==============================================================================
--- (empty file)
+++ sandbox/local/libs/local/doc/qbk/advanced.qbk 2011-01-10 16:15:26 EST (Mon, 10 Jan 2011)
@@ -0,0 +1,407 @@
+
+[/ Copyright (C) 2009-2011 Lorenzo Caminiti ]
+[/ Use, modification, and distribution is subject to the ]
+[/ Boost Software License, Version 1.0 ]
+[/ (see accompanying file LICENSE_1_0.txt or a copy at ]
+[/ http://www.boost.org/LICENSE_1_0.txt). ]
+
+[section:Advanced Advanced]
+
+This section illustrates advanced usages of this library.
+At the end of this section there is also a list of limitations of this library.
+
+[section Commas in Macro Parameters]
+
+The C++ preprocessor does not allow commas "`,`" within macro parameters unless they are wrapped by the round parenthesis `()`.
+The elements of the parenthesized signature are internally used as macro parameters while they are being processed by the parsing macros.
+Therefore, commas within parenthesized signature elements will generate (cryptic) preprocessor errors unless they are wrapped within extra round parenthesis `()` as explained here.
+
+[note
+*Macro parameters with commas* which are already wrapped by round parenthesis `()` are fine (function calls, etc).
+However, macro parameters with commas that are not wrapped by round parenthesis need to be wrapped by an extra set of round parenthesis `()` as described here.
+Therefore, also macro parameters with commas wrapped by angular parenthesis `<>` (templates, etc) or square parenthesis `[]` (multidimensional array access, etc) need to be wrapped by the extra round parenthesis `()` as explained here (this is because the preprocessor only recognizes the round parenthesis and it does not recognize angular, square, or any other type of parenthesis).
+]
+
+For example, let's consider the following parenthesized signature (see the complete example code later in this section):
+
+ (void) (print)(
+ (const std::map<std::string, size_t>&)(m) // (1) Error.
+ (const size_t&)(factor)(default)
+ (key_size<std::string, size_t>::value) // (2) Error.
+ (const std::string&)(separator)(default)(cat(":", " ")) // (3) OK.
+ (::sign_t)(sign)(default)(-1) // (4) Error.
+ )
+
+[*(1)] The parenthesized signature element `const std::map<std::string, size_t>&` contains a comma "`,`" after the first template parameter `std::string`.
+This comma is not wrapped by any round parenthesis `()` (the outer parenthesis `()` that make this a parenthesized signature element do not count) thus it will cause a preprocessor error.
+The macro `__BOOST_IDENTITY_TYPE__(`/parenthesized-type/`)` can be used to wrap a type within extra parenthesis `()` so to overcome this issue:
+
+ (void) (print)(
+ ``*(*``__BOOST_IDENTITY_TYPE__``*((*``const std::map<std::string, size_t>&``*)))*``(m) // OK.
+ ...
+ )
+
+This macro expands to an expression that evaluates (at compile-time) exactly to the specified type.
+Note that a total of three set of parenthesis `()` are needed:
+
+# Parenthesis to wrap the parenthesized signature element.
+# Parenthesis to call the `__BOOST_IDENTITY_TYPE__` macro.
+# Parenthesis to wrap the type expression (and therefore any commas "`,`" that it contains) passed as parameter to the `__BOOST_IDENTITY_TYPE__` macro.
+
+[*(2)] The parenthesized signature element `key_size<std::string, size_t>::value` contains a comma "`,`" after the first template parameter `std::string`.
+Again, this comma is not wrapped by any parenthesis `()` so it will cause a preprocessor error.
+Because this is a value expression (and not a type expression), the macro `__BOOST_IDENTITY_VALUE__(`/parenthesized-value/`)` is used to overcome this issue:
+
+ (void) (print)(
+ ...
+ (const size_t&)(factor)(default)
+ ``*(*``__BOOST_IDENTITY_VALUE__``*((*``key_size<std::string, size_t>::value``*)))*`` // OK.
+ ...
+ )
+
+This macro expands to an expression that evaluates (at run-time) exactly to the specified value.
+Note again that a total of three set of parenthesis `()` are needed similarly to `__BOOST_IDENTITY_TYPE__`.
+
+[*(3)] The parenthesized signature element `cat(':', ' ')` is instead fine because it contains a comma "`,`" which is already wrapped by the parenthesis `()` of the function call `cat(...)`.
+
+[*(4)] The parenthesized signature elements `::sign_t` and `-1` (the type and default value of the `sign` parameter) start with the non-alphanumeric symbols "`::`" and "`-`" respectively thus they cannot be used by the parenthesized syntax.
+The macros `__BOOST_IDENTITY_TYPE__` and `__BOOST_IDENTITY_VALUE__` can also be used to overcome these issues:
+
+ (void) (print)(
+ ...
+ (__BOOST_IDENTITY_TYPE__((::sign_t)))(sign)(default)
+ (__BOOST_IDENTITY_VALUE__((-1))) // OK.
+ )
+
+This way the parenthesized signature elements became `(__BOOST_IDENTITY_TYPE__((::sign_t)))` and `(__BOOST_IDENTITY_VALUE__((-1)))` which start with the alphanumeric symbols of the macro names and they can be used by the parenthesized syntax.
+
+Often, there might be better ways to overcome this limitation that lead to code which is more readable than the one using these macros.
+For example, in this case the symbol "`::`" could be dropped and `-1` could be wrapped within `int(...)` to obtain the following, more readable, and still valid parenthesized signature code:
+
+ (void) (print)(
+ ...
+ (sign_t)(sign)(default)(int(-1)) // OK.
+ )
+
+Consider the following complete example:
+[footnote
+We recognize that the use of the /identity macros/ adds extra parenthesis to the already significant number of parenthesis required by the parenthesized syntax.
+However, parenthesized signatures usually do not contain unwrapped commas "`,`" (unless template metaprogramming is being used).
+]
+
+[print_map_cpp]
+
+[endsect]
+
+[section Recursive Local Functions]
+
+A local function can recursively call itself as usual with C++ functions.
+
+For example, the following local function is used to recursively calculate and print the factorial of the specified numbers:
+
+[factorial_cpp]
+
+The original local function name as specified in the parenthesized signature passed to `__BOOST_LOCAL_FUNCTION__` must always be used for recursive calls even when the function is renamed using `__BOOST_LOCAL_FUNCTION_END_RENAME__` (see renamed local functions later in this section).
+
+[endsect]
+
+[section Exception Specifications]
+
+It is possible to program exception specifications for local functions, local blocks, and local exits.
+
+Exception specifications are programmed just before the body (and outside the macros).
+For example:
+
+[add_except_cpp]
+
+[endsect]
+
+[section Optimizers: `inline`, `auto`, and `register`]
+
+As specified in the __Grammar__ section, the parenthesized signature also supports `inline`d local functions, and the `auto` and `register` classifiers for local function parameters.
+
+[note
+However, note that local functions will always add some overhead because of the functor object used to internally implement them.
+Compilers might not be able to optimize away the local function overhead even when `inline`, `auto`, and `register` are used.
+]
+
+For example:
+
+[add_optimizers_cpp]
+
+[endsect]
+
+[section References to Local Functions]
+
+It is possible to obtain a reference to a local function so to assign it to a variable, to pass it as a function parameter, etc.
+
+[important
+Local functions are never copied by value.
+You can only obtain a reference to a local function therefore you need to make sure that the *local function survives the scope of its reference* otherwise the reference will be invalid and its use will generate a run-time error (as usual with C++ references).
+[footnote
+The suffix `ref` of `boost::local::__function_ref__` is meant to help programmers remember that they are dealing with references to (and not copies of) local functions.
+]
+]
+
+For this purpose, it is possible to assign a `boost::function` functor to a local function (see also __Boost_Function__).
+However, it is in general preferable to use the `boost::local::__function_ref__` functor instead because its API also supports default parameters.
+
+The `boost::local::__function_ref__` template takes two parameters (see the __Reference__ section):
+
+ template<typename F, size_t defaults = 0>
+ class __function_ref__ { ... };
+
+Where:
+
+* The template parameter `F` specifies the function signature using the same
+syntax as __Boost_Function__'s preferred syntax.
+For example:
+
+ __function_ref__< int() > // Returns `int` and takes no parameter.
+ __function_ref__< int(double, char) > // Returns `int`and takes two parameters: a `double` followed by a `char`.
+
+* The template parameter `defaults` specifies the number of defaults parameters counting from the last parameter: `0` if no parameter is optional, `1` if the last parameter is optional, `2` if the last two parameters are optional, etc.
+This template parameter must be between `0` and the total number of parameters as specified by `F`.
+This template parameter is optional and it is `0` by default.
+For example:
+
+ __function_ref__< int(double, char) > // No default: All parameters must be specified.
+ __function_ref__< int(double, char), 1 > // 1 default: The last `char` parameter is optional.
+ __function_ref__< int(double, char), 2 > // 2 defaults: All parameters are optional.
+
+For example:
+
+[doit_cpp]
+
+[endsect]
+
+[section Renaming Local Functions]
+
+Local functions can be renamed using the `__BOOST_LOCAL_FUNCTION_END_RENAME__` macro instead of `__BOOST_LOCAL_FUNCTION_END__`:
+
+ __BOOST_LOCAL_FUNCTION_END_RENAME__(``/new-local-function-name/``)
+
+Where the /new-local-function-name/ no longer has to match the local function name as originally specified in the parenthesized signature passed to `__BOOST_LOCAL_FUNCTION__`.
+For example:
+[footnote
+*Rationale.*
+Local functions are often named `l` in the casual examples of this documentation because the name of the author starts with the letter "`l`". [$../images/smiley.png]
+]
+
+ {
+ __BOOST_LOCAL_FUNCTION__(
+ (void) (l)( (int)(x) )
+ ) {
+ ... // Body uses original name `l`.
+ } __BOOST_LOCAL_FUNCTION_END_RENAME__(m) // Renamed to `m`.
+
+ ... // Enclosing scope uses new name `m`.
+ }
+
+Note that the local function is renamed only after the call to `__BOOST_LOCAL_FUNCTION_END_RENAME__`.
+Therefore, within the local function body the original local function name as specified by `__BOOST_LOCAL_FUNCTION__` must be used (e.g., to recursively call the local function).
+However, within the enclosing scope only the new local function name as specified by `__BOOST_LOCAL_FUNCTION_END_RENAME__` is available.
+
+A limitation is that renamed local functions cannot be directly passed as template parameters (e.g., they cannot be passed to STL algorithms like `std::for_each`).
+However, it is possible to workaround this limitation by obtaining a reference of the renamed local function and then passing the reference as template parameter.
+For example:
+
+[renamed_print_cpp]
+
+[h5 Motivation]
+
+The motivation for renaming a local function might not be obvious at first.
+In fact, in most cases programmers will not need to rename local functions.
+
+Renaming local functions might be useful at least to program macros that expand using local functions and that do not want to pass the local function body as a macro parameter (so to retain the usual meaning of compiler error line numbers for the body code).
+Consider the following example that implements a simple version of the local exit macros using a renamed local function:
+
+[renamed_exit_cpp]
+
+[endsect]
+
+[section Limitations: Overloading, Nesting, Operators, Etc]
+
+This is a list of limitations of this library's local functions compared to usual features of C++ functions.
+
+[h5 Overloading]
+
+It is not possible to overload local functions.
+Declaring multiple local functions with the same name within the same enclosing scope generates a compile-time error (even if the different declarations specify different parameters).
+[footnote
+*Rationale.*
+This is because a local function is a functor object declared as a local variable within the enclosing scope.
+Therefore, declaring two local functions with the same name within the same enclosing scope declares two local variables with the same name within the same scope and that is not allowed in C++.
+]
+
+For example, the following code will *not* compile:
+
+ void f() {
+ __BOOST_LOCAL_FUNCTION__(
+ (void) (l)( (const int&)(i) )
+ ) {
+ std::cout << i << std::endl;
+ } __BOOST_LOCAL_FUNCTION_END__(l)
+
+ __BOOST_LOCAL_FUNCTION__(
+ (void) (l)( (const double&)(d) )
+ ) {
+ std::cout << d << std::endl;
+ } __BOOST_LOCAL_FUNCTION_END__(l) // Error: Cannot overload.
+
+ ...
+ }
+
+[h5 Nesting]
+
+It is not possible to nest local functions, local blocks, or local exits within each other.
+Nesting will generate a compile-time error.
+[footnote
+*Rationale.*
+This is because within a nested code block only global or static variables can be accessed while __Boost_ScopeExit__ variable [@http://lists.boost.org/Archives/boost/2006/11/113658.php binding mechanism] requires to access local variables that hold the bound variables.
+]
+
+For example, the following code will *not* compile:
+
+ void f() {
+ __BOOST_LOCAL_FUNCTION__(
+ (int) (l)( (int)(i) )
+ ) {
+ __BOOST_LOCAL_FUNCTION__( // Error: Cannot nest.
+ (int) (m)( (int)(j) )
+ ) {
+ return j * 10;
+ } __BOOST_LOCAL_FUNCTION_END__(m)
+
+ return m(i) * 10;
+ } __BOOST_LOCAL_FUNCTION_END__(l)
+
+ ...
+ }
+
+[h5 Operators]
+
+Local functions cannot be operators.
+Naming a local function `operator...` will generate a compile-time error.
+[footnote
+*Rationale.*
+This is the because a local function name must be a valid local variable name (the local variable to hold the local functor object) and operators cannot be used as local variable names.
+]
+
+For example, the following code will *not* compile:
+
+ void f() {
+ struct point {
+ double x;
+ double y;
+ };
+
+ __BOOST_LOCAL_FUNCTION__( // Error: Cannot be `operator==`.
+ (bool) (operator==)( (const point&)(p) (const point&)(q) )
+ ) {
+ return p.x == q.x && p.y == q.y;
+ ) __BOOST_LOCAL_FUNCTION_END__(operator==)
+
+ ...
+ }
+
+[h5 Etc]
+
+Some usual C++ function features like `inline` and default parameters are supported for local functions while other features are not supported.
+The parenthesized syntax itself (see the __Grammar__ section) could be extended to support /all/ C++ function features even with the addition of concepts and named parameters (see __Contractpp__):
+
+ ``/parenthesized-signature:/``
+ ``/[/``(export)``/]/`` ``/[/``(template)(``/template-parameter-list/``)``/]/`` ``/[/``(requires)(``/concept-list/``)``/]/``
+ ``/[/``(explicit)``/]/``
+ ``/[/``(inline)``/]/`` ``/[/``(extern)``/]/``
+ ``/[/``(static)``/]/`` ``/[/``(virtual)``/]/``
+ (``/result-type/``) (``/function-name/``)(``/parameter-list/``)
+ ``/[/``(const)``/]/`` ``/[/``(volatile)``/]/``
+
+However, not all these features apply to local functions:
+
+[table
+[
+ [ C++ Function Feature ]
+ [ Local Function Support ]
+ [ Rationale ]
+]
+[
+ [ `(export)` ]
+ [ No ]
+ [ This is not supported because local functions cannot be templates (plus most C++ compilers do not implement `export`). ]
+]
+[
+ [ `(template)(`/template-parameter-list/`)` ]
+ [ No ]
+ [ This is not supported because local functions are implemented using local classes and C++ local classes cannot be templates. ]
+]
+[
+ [ `(requires)(`/concept-list/`)` ]
+ [ No ]
+ [ This library could internally use __Boost_ConceptCheck__ to check the concepts specified by using the parenthesized syntax. However, concept checking is not supported because local functions cannot be templates. ]
+]
+[
+ [ `(explicit)` ]
+ [ No ]
+ [ This is not supported because local functions are not constructors. ]
+]
+[
+ [ `(inline)` ]
+ [ Yes ]
+ [ This is supported (see the __Advanced__ section). ]
+]
+[
+ [ `(extern)` ]
+ [ No ]
+ [ This is not supported because local functions are always defined locally within the enclosing scope and together with their declarations. ]
+]
+[
+ [ `(static)` ]
+ [ No ]
+ [ This is not supported because local functions are not member functions. ]
+]
+[
+ [ `(virtual)` ]
+ [ No ]
+ [ This is not supported because local functions are not member functions.
+
+In theory, it would be possible for a local functor class to inherit from another local functor class.
+The parenthesized syntax could be extended to specify the eventual base local functor class within the parenthesized signature (e.g., using `... (extends)(`/base/`)`).
+However, this "inheritance" feature is not implemented because it seems of [@http://lists.boost.org/Archives/boost/2010/09/170895.php no use] given that local functions can be bound to one another thus they can simply call each other directly without recurring to dynamic binding or base function call.
+ ]
+]
+[
+ [ `(`/result-type/`)` ]
+ [ Yes ]
+ [ This is supported (see the __Tutorial__ section). ]
+]
+[
+ [ `(`/function-name/`)` ]
+ [ Yes ]
+ [ This is supported but it cannot be overloaded and it cannot be an operator (see the __Tutorial__ and __Advanced__ sections). ]
+]
+[
+ [ `(`/parameter-list/`)` ]
+ [ Yes ]
+ [ This is supported and it also supports the `auto` and `register` parameter classifiers, default parameters, and binding of variables in scope (see the __Tutorial__ and __Advanced__ sections).
+
+In addition, the parenthesized syntax could support named parameters introducing the "keywords" `(in)`, `(out)`, `(inout)`, and then using __Boost_Parameter__ to internally implement named parameters.
+However, local functions cannot be templates so they cannot be used with __Boost_Parameter__ thus named parameters are not supported for local functions. ]
+]
+[
+ [ Trailing `(const)` ]
+ [ No ]
+ [ This is not supported because local functions are not member functions. ]
+]
+[
+ [ Trailing `(volatile)` ]
+ [ No ]
+ [ This is not supported because local functions are not member functions. ]
+]
+]
+
+[endsect]
+
+[endsect]
+

Added: sandbox/local/libs/local/doc/qbk/alternatives.qbk
==============================================================================
--- (empty file)
+++ sandbox/local/libs/local/doc/qbk/alternatives.qbk 2011-01-10 16:15:26 EST (Mon, 10 Jan 2011)
@@ -0,0 +1,77 @@
+
+[/ Copyright (C) 2009-2011 Lorenzo Caminiti ]
+[/ Use, modification, and distribution is subject to the ]
+[/ Boost Software License, Version 1.0 ]
+[/ (see accompanying file LICENSE_1_0.txt or a copy at ]
+[/ http://www.boost.org/LICENSE_1_0.txt). ]
+
+[section:Alternatives Appendix: Alternatives]
+
+This section compares the features offered by this library with similar features offered by other libraries and by the new C++0x standard.
+
+[section Local Functions]
+
+The following table compares local function features.
+
+[table
+[
+ [ Local Function Feature ]
+ [ This Library ]
+ [ Local Classes ]
+ [ __CPP0x_lambda__ ]
+ [ __Boost_Lambda__ ]
+ [ __Boost_Phoenix__ ]
+]
+[
+ [ ['Program body using usual C++ syntax] ]
+ [ Yes. ]
+ [ Yes. ]
+ [ Yes. ]
+ [ No. ]
+ [ No. ]
+]
+[
+ [ ['Can be passed as template parameter (e.g., to STL algorithms)] ]
+ [ Yes. ]
+ [ No (see "local class" in __StroustrupGlossary__). ]
+ [ Yes. ]
+ [ Yes. ]
+ [ Yes. ]
+]
+[
+ [ ['Bind variables in scope] ]
+ [ Yes, bind by value, constant value, reference, and constant reference (also bind the object `this`). ]
+ [ No. ]
+ [ Yes, but no bind by constant (value or reference). ]
+ [ No. ]
+ [ No. ]
+]
+[
+ [ ['Can be defined within expressions] ]
+ [ No, defined only within declarations. ]
+ [ No, defined only within declarations. ]
+ [ Yes. ]
+ [ Yes. ]
+ [ Yes. ]
+]
+]
+
+[endsect]
+
+[section Local Blocks]
+
+The authors know of no other library or language feature that supports local blocks (i.e., with the ability to bind by constant value or reference).
+
+[endsect]
+
+[section Local Exits]
+
+This library local exits provide a functionality very similar to the one provided by __Boost_ScopeExit__ but with the following additional features:
+
+* Bind by constant (value or reference).
+* Bind the object `this`.
+
+[endsect]
+
+[endsect]
+

Added: sandbox/local/libs/local/doc/qbk/bibliography.qbk
==============================================================================
--- (empty file)
+++ sandbox/local/libs/local/doc/qbk/bibliography.qbk 2011-01-10 16:15:26 EST (Mon, 10 Jan 2011)
@@ -0,0 +1,21 @@
+
+[/ Copyright (C) 2009-2011 Lorenzo Caminiti ]
+[/ Use, modification, and distribution is subject to the ]
+[/ Boost Software License, Version 1.0 ]
+[/ (see accompanying file LICENSE_1_0.txt or a copy at ]
+[/ http://www.boost.org/LICENSE_1_0.txt). ]
+
+[section:Bibliography Bibliography]
+
+This section lists all the bibliographic references cited by this documentation.
+
+__N2511__ Alisdair Meredith. /Named Lambdas and Local Functions./ The C++ Standards Committee, document no. N2511=08-0021, 2008.
+
+__N2529__ Jaakko Jarvi, John Freeman, Lawrence Crowl. /Lambda Expressions and Closures: Wording for Monomorphic Lambdas (Revision 3)./ The C++ Standards Committee, document no. N2529=08-0039, 2008.
+
+__N2550__ Jaakko Jarvi, John Freeman, Lawrence Crowl. /Lambda Expressions and Closures: Wording for Monomorphic Lambdas (Revision 4)./ The C++ Standards Committee, document no. N2550=08-0060, 2008.
+
+__StroustrupGlossary__ Bjarne Stroustrup. /Bjarne Stroustrup's C++ Glossary./
+
+[endsect]
+

Added: sandbox/local/libs/local/doc/qbk/examples.qbk
==============================================================================
--- (empty file)
+++ sandbox/local/libs/local/doc/qbk/examples.qbk 2011-01-10 16:15:26 EST (Mon, 10 Jan 2011)
@@ -0,0 +1,64 @@
+
+[/ Copyright (C) 2009-2011 Lorenzo Caminiti ]
+[/ Use, modification, and distribution is subject to the ]
+[/ Boost Software License, Version 1.0 ]
+[/ (see accompanying file LICENSE_1_0.txt or a copy at ]
+[/ http://www.boost.org/LICENSE_1_0.txt). ]
+
+[section:Examples Appendix: Examples]
+
+This section lists the complete source code of some examples that can be compiled and executed using this library (see also the many examples listed within the text of this documentation).
+
+[table
+[
+ [ Adapted From ]
+ [ Name ]
+ [ Description ]
+ [ Source File(s) ]
+]
+[
+ [ __Boost_ScopeExit__ documentation ]
+ [ Local Exit ]
+ [ Local exits with user defined types registered using __Boost_Typeof__. ]
+ [ [@../../example/exit.cpp exit.cpp] ]
+]
+[
+ [ N/A ]
+ [ STL Transform ]
+ [ Bind a local function to another local function. ]
+ [ [@../../example/transform.cpp transform.cpp] ]
+]
+[
+ [ __N2550__ ]
+ [ STL Find ]
+ [ Pass a local function to `std::find_if`. ]
+ [ [@../../example/find_if.cpp find_if.cpp] ]
+]
+[
+ [ __N2529__ ]
+ [ Bind This ]
+ [ Bind object `this` to a local function. ]
+ [ [@../../example/this.cpp this.cpp] ]
+]
+[
+ [ N/A ]
+ [ Local Block ]
+ [ Local blocks with biding (constant, non-constant, and `this`) and `return`. ]
+ [ [@../../example/block.cpp block.cpp] ]
+]
+[
+ [ N/A ]
+ [ Parameters Permutations ]
+ [ Exhaustively shows all possible parameter permutations (with/without parameters, with/without binding constant and not, with/without `this` binding constant and not). ]
+ [ [@../../example/params.cpp params.cpp] ]
+]
+[
+ [ N/A ]
+ [ Same Line ]
+ [ Two local functions defined on the same line of code. ]
+ [ [@../../example/same_line.cpp same_line.cpp] ]
+]
+]
+
+[endsect]
+

Added: sandbox/local/libs/local/doc/qbk/grammar.qbk
==============================================================================
--- (empty file)
+++ sandbox/local/libs/local/doc/qbk/grammar.qbk 2011-01-10 16:15:26 EST (Mon, 10 Jan 2011)
@@ -0,0 +1,112 @@
+
+[/ Copyright (C) 2009-2011 Lorenzo Caminiti ]
+[/ Use, modification, and distribution is subject to the ]
+[/ Boost Software License, Version 1.0 ]
+[/ (see accompanying file LICENSE_1_0.txt or a copy at ]
+[/ http://www.boost.org/LICENSE_1_0.txt). ]
+
+[section:Grammar Appendix: Grammar]
+
+This section describes the complete grammar of the /parenthesized syntax/ used by this library to specify the local function signature with binding of variables in scope.
+
+This should be considered a reference section.
+See the __Tutorial__ and the __Advanced__ sections for explanations and examples on how to use the parenthesized syntax.
+
+[note
+The parsers of the parenthesized syntax are implemented using macros and the __Boost_Preprocessor__ library so *the parenthesized syntax is parsed by the preprocessor*.
+
+Using preprocessor metaprogramming allows the parsers to introduce new "keywords" at the same syntactic level as the usual C++ keywords but that are used to support new features specific to this library (for example the new "keyword" `bind` which is used to bind variables in scope).
+However, the use of the preprocessor also requires using a significant number of extra parenthesis `()` with respect to usual C++ syntax (from which the parenthesized syntax's name).
+
+In addition, there is only a limited amount of syntactic error checking that can be done using macros thus sometimes a parenthesized syntax error generates cryptic preprocessor errors.
+When the macros can catch syntactic errors, these errors are reported as compile-time errors (using static assertions) with names of the form `ERROR_`/description_text/.
+]
+
+Macros using the parenthesized syntax (see the __Reference__ section):
+
+ __BOOST_LOCAL_FUNCTION__( ``/parenthesized-signature/`` )
+ __BOOST_LOCAL_BLOCK__( ``/parenthesized-binding/`` )
+ __BOOST_LOCAL_EXIT__( ``/parenthesized-binding/`` )
+
+Additional "keywords":
+
+ bind ``used to bind variables in scope``
+ default ``used to specify default parameters``
+
+Terminals:
+
+ ``*result-type*`` ``a function return type (can be ``void``)``
+ ``*function-name*`` ``a function name (cannot be an operator)``
+
+ ``*parameter-type*`` ``a parameter type``
+ ``*parameter-name*`` ``a parameter name``
+ ``*parameter-default*`` ``a valid default value for the specified parameter``
+
+ ``*variable-name*`` ``the name of a variable in scope (can be ``this``)``
+
+Lexical conventions:
+
+ ``/a | b/`` ``symbol /a/ or symbol /b/``
+ ``/[a]/`` ``the symbol /a/ is optional and it can be omitted``
+ ``/a+/`` ``symbol /a/ repeated one or more times``
+
+Parenthesized syntax:
+
+ ``/parenthesized-signature:/``
+ ``/[/``(inline)``/]/`` (``*result-type*``) (``*function-name*``)( ``/parameter-list/`` )
+
+ ``/parenthesized-binding:/``
+ (void) // No bindings.
+ ``/| bindings/`` // Bindings (constant and/or not).
+
+ ``/parameter-list:/``
+ (void) // No parameters and no bindings.
+ ``/| parameters/`` // Only parameters.
+ ``/| bindings/`` // Only bindings.
+ ``/| parameters bindings/`` // Both parameters and bindings (must appear in this order).
+
+Function parameters:
+
+ ``/parameters:/``
+ ``/parameter+/`` // Only required parameters.
+ ``/| optional-parameter+/`` // Only optional parameters.
+ ``/| parameter+ optional-parameter+/`` // Both required and optional parameters (must appear in this order).
+
+ ``/parameter:/``
+ ``/[/``(auto) ``/|/`` (register)``/]/`` // Optional parameter classifier `auto` or `register`.
+ (``*parameter-type*``)(``*parameter-name*``)
+
+ ``/optional-parameter:/``
+ ``/parameter/``
+ (default)(``*parameter-default*``) // Default value for this optional parameter.
+
+Binding variables in scope:
+[footnote
+*Rationale.*
+The alternative syntax `(bind)((const& x)...)` would have been preferred because `const` appears before the reference as usual in C++ and because a single `bind` sequence is used for both plain and constant binding (e.g., the single sequence `(bind)((a)(&b)(const a)(const& b))` would bind by value, by constant value, by reference, and by constant reference respectively).
+However, the parenthesized syntax parsers cannot process both `const& x` and `&x` because if they inspect the beginning of the token `&x` to search for the leading `const` they will find the non-alphanumeric symbol `&` which cannot be used for token concatenation thus generating preprocessor errors.
+The tokens `&x` and `x` can instead be processed by the parsing macros because they do not need to be inspected from the front (they are instead inspected from the back to check if a token matches `this` and that is fine because the non-alphanumeric symbol `&` never appears in the back).
+]
+[footnote
+*Rationale.*
+Binding is used within the function parameter list because this syntax seemed natural given that the bound variables are used by the function body as if they were function parameters (only their type is not explicitly specified by the function signature and the caller does not explicitly pass their values).
+However, the parenthesized syntax could be modified to accept `(const bind)(...)` and `(bind)(...)` outside the parameter list (e.g., at the very end or beginning of the function signature) if an alternative syntax was to be identified as more intuitive.
+]
+
+ ``/bindings:/``
+ ``/const-bindings/`` // Only constant binding.
+ ``/| plain-bindings/`` // Only plain binding.
+ ``/| const-bindings plain-bindings/`` // Both constant and plain bindings (must appear in this order).
+
+ ``/const-bindings:/``
+ (const bind)(``/bound-variable+/``) // Force constant type for bound variable.
+
+ ``/plain-bindings/``:
+ (bind)(``/bound-variable+/``) // Use bound variable's plain type (constant or not).
+
+ ``/bound-variable/``:
+ (``*variable-name*``) // Bind by value.
+ | (&``*variable-name*``) // Bind by reference.
+
+[endsect]
+

Added: sandbox/local/libs/local/doc/qbk/introduction.qbk
==============================================================================
--- (empty file)
+++ sandbox/local/libs/local/doc/qbk/introduction.qbk 2011-01-10 16:15:26 EST (Mon, 10 Jan 2011)
@@ -0,0 +1,40 @@
+
+[/ Copyright (C) 2009-2011 Lorenzo Caminiti ]
+[/ Use, modification, and distribution is subject to the ]
+[/ Boost Software License, Version 1.0 ]
+[/ (see accompanying file LICENSE_1_0.txt or a copy at ]
+[/ http://www.boost.org/LICENSE_1_0.txt). ]
+
+[section:Introduction Introduction]
+
+/Local functions/ are a form of /information hiding/ and are useful for dividing procedural tasks into subtasks which are only meaningful locally, avoiding cluttering other parts of the program with functions, variables, etc unrelated to those parts.
+Local functions therefore complement other structuring possibilities such as namespaces and classes.
+Local functions are a feature of many programming languages, notably [@http://en.wikipedia.org/wiki/Nested_function#An_example Pascal] and [@http://en.wikipedia.org/wiki/Nesting_(computing)#In_programming Ada], yet lacking from C++ (see also __N2511__).
+
+This library supports the following features for local functions (see the __Alternatives__ section for a comparison between this library and features offered by C++ local class members, __CPP0x_lambda__ functions, __Boost_Lambda__, __Boost_Phoenix__, and __Boost_ScopeExit__):
+
+* Local functions can access, or better [@http://en.wikipedia.org/wiki/Name_binding /bind/], any of the variables from the enclosing scope.
+Furthermore, local functions defined within a member function can bind the enclosing object `this`.
+* The local function body is programmed using the usual C++ syntax.
+* Local functions can be passed as template parameters (so they can be conveniently passed to STL algorithms, etc).
+* However, local functions must be defined within a declarative context (e.g., at a point in the code where local variables can be declared) thus they cannot be defined within an expression.
+
+In addition to local functions, this library also supports the following features:
+
+* /Local blocks/ which define blocks of code that bind variables from the enclosing scope.
+Local blocks allow programmers to bind variables as constants (/constant binding/) so to prevent local chunks of code from modifying selected variables.
+* /Local exits/ which define blocks of code that are executed when the enclosing scope is exited (again with support for constant binding and binding of the object `this`).
+
+[h5 An Example]
+
+The following example illustrates a simple use of this library and it starts introducing the library API (see the __Tutorial__ section for more details on how to use this library):
+
+* A local function is passed to the STL `std::for_each` algorithm to add together the values of an array.
+Variables in scope are bound to the local function by both constant value and non-constant reference.
+* A local exit is used to automatically release the array's memory at scope exit.
+* A local block is used to assert the correct final value of the summation in a constant-correct context (therefore preventing the assertion from mistakenly changing any of the variables in scope).
+
+[add_cpp]
+
+[endsect]
+

Added: sandbox/local/libs/local/doc/qbk/local.qbk
==============================================================================
--- (empty file)
+++ sandbox/local/libs/local/doc/qbk/local.qbk 2011-01-10 16:15:26 EST (Mon, 10 Jan 2011)
@@ -0,0 +1,98 @@
+
+[/ Copyright (C) 2009-2011 Lorenzo Caminiti ]
+[/ Use, modification, and distribution is subject to the ]
+[/ Boost Software License, Version 1.0 ]
+[/ (see accompanying file LICENSE_1_0.txt or a copy at ]
+[/ http://www.boost.org/LICENSE_1_0.txt). ]
+
+[preface Boost.Local
+ [quickbook 1.5]
+ [version 0.1.1 ]
+ [/ purpose Local functions for C++]
+ [/ category Function objects and higher-order programming]
+ [authors [Caminiti, Lorenzo]]
+ [copyright 2009-2011 Lorenzo Caminiti]
+ [license
+ Use, modification, and distribution is subject to the
+ Boost Software License, Version 1.0
+ (see accompanying file LICENSE_1_0.txt or a copy at
+ [@http://www.boost.org/LICENSE_1_0.txt]).
+ ]
+]
+
+[def __Boost__ [@http://www.boost.org/ Boost]]
+[def __Boost_ScopeExit__ [@http://www.boost.org/doc/libs/release/libs/scope_exit/doc/html/index.html Boost.ScopeExit]]
+[def __Boost_Lambda__ [@http://www.boost.org/doc/libs/release/doc/html/lambda.html Boost.Lambda]]
+[def __Boost_Phoenix__ [@http://www.boost.org/doc/libs/release/libs/spirit/phoenix/index.html Boost.Phoenix]]
+[def __Boost_Preprocessor__ [@http://www.boost.org/doc/libs/release/libs/preprocessor/doc/index.html Boost.Preprocessor]]
+[def __Boost_MPL__ [@http://www.boost.org/doc/libs/release/libs/mpl/doc/index.html Boost.MPL]]
+[def __Boost_ConceptCheck__ [@http://www.boost.org/doc/libs/release/libs/concept_check/doc/index.html Boost.ConceptCheck]]
+[def __Boost_Parameter__ [@http://www.boost.org/doc/libs/release/libs/parameter/doc/index.html Boost.Paramater]]
+[def __Boost_Typeof__ [@http://www.boost.org/doc/libs/release/doc/html/typeof.html Boost.Typeof]]
+[def __Boost_Function__ [@http://www.boost.org/doc/libs/release/doc/html/function.html Boost.Function]]
+[def __Boost_TypeTraits__ [@http://www.boost.org/doc/libs/release/libs/type_traits/doc/html/index.html Boost.TypeTraits]]
+[def __CPP0x_lambda__ [@http://en.wikipedia.org/wiki/C%2B%2B0x#Lambda_functions_and_expressions C++0x lambda]]
+[def __LISP__ [@http://en.wikipedia.org/wiki/Lisp_(programming_language) LISP]]
+[def __Contractpp__ [@http://sourceforge.net/projects/contractpp Contract++]]
+
+[def __N2511__ [@http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2008/n2511.html \[N2511\]]]
+[def __N2529__ [@http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2008/n2529.pdf \[N2529\]]]
+[def __N2550__ [@http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2008/n2550.pdf \[N2550\]]]
+[def __StroustrupGlossary__ [@http://www2.research.att.com/~bs/glossary.html \[StroustupGlossary\]]]
+
+[def __Introduction__ [link boost_local.Introduction Introduction]]
+[def __Starting__ [link boost_local.Starting Starting]]
+[def __Tutorial__ [link boost_local.Tutorial Tutorial]]
+[def __Advanced__ [link boost_local.Advanced Advanced]]
+[def __Reference__ [@reference.html Reference]]
+[def __Grammar__ [link boost_local.Grammar Grammar]]
+[def __Alternatives__ [link boost_local.Alternatives Alternatives]]
+[def __Examples__ [link boost_local.Examples Examples]]
+[def __Releases__ [link boost_local.Releases Releases]]
+[def __Bibliography__ [link boost_local.Bibliography Bibliography]]
+[def __Acknowledgments__ [link boost_local.Acknowledgments Acknowledgments]]
+
+[def __BOOST_LOCAL_FUNCTION__ [macroref BOOST_LOCAL_FUNCTION]]
+[def __BOOST_LOCAL_FUNCTION_TPL__ [macroref BOOST_LOCAL_FUNCTION_TPL]]
+[def __BOOST_LOCAL_FUNCTION_END__ [macroref BOOST_LOCAL_FUNCTION_END]]
+[def __BOOST_LOCAL_FUNCTION_END_RENAME__ [macroref BOOST_LOCAL_FUNCTION_END_RENAME]]
+[def __BOOST_LOCAL_BLOCK__ [macroref BOOST_LOCAL_BLOCK]]
+[def __BOOST_LOCAL_BLOCK_TPL__ [macroref BOOST_LOCAL_BLOCK_TPL]]
+[def __BOOST_LOCAL_BLOCK_END__ [macroref BOOST_LOCAL_BLOCK_END]]
+[def __BOOST_LOCAL_EXIT__ [macroref BOOST_LOCAL_EXIT]]
+[def __BOOST_LOCAL_EXIT_TPL__ [macroref BOOST_LOCAL_EXIT_TPL]]
+[def __BOOST_LOCAL_EXIT_END__ [macroref BOOST_LOCAL_EXIT_END]]
+[def __BOOST_IDENTITY_TYPE__ [macroref BOOST_IDENTITY_TYPE]]
+[def __BOOST_IDENTITY_VALUE__ [macroref BOOST_IDENTITY_VALUE]]
+[def __function_ref__ [classref boost::local::function_ref function_ref]]
+
+[import ../../example/add.cpp]
+[import ../../example/add_num.cpp]
+[import ../../example/add_num_sum.cpp]
+[import ../../example/add_num_factor_sum.cpp]
+[import ../../example/add_this.cpp]
+[import ../../example/add_block.cpp]
+[import ../../example/add_exit.cpp]
+[import ../../example/add_template.cpp]
+[import ../../example/print_map.cpp]
+[import ../../example/factorial.cpp]
+[import ../../example/doit.cpp]
+[import ../../example/add_except.cpp]
+[import ../../example/renamed_print.cpp]
+[import ../../example/renamed_exit.cpp]
+[import ../../example/add_optimizers.cpp]
+
+The Boost Local library implements local functions, local blocks, and local exits for the C++ programming language.
+
+[include introduction.qbk]
+[include starting.qbk]
+[include tutorial.qbk]
+[include advanced.qbk]
+[xinclude ../reference.xml]
+[include grammar.qbk]
+[include alternatives.qbk]
+[include examples.qbk]
+[include releases.qbk]
+[include bibliography.qbk]
+[include acknowledgements.qbk]
+

Added: sandbox/local/libs/local/doc/qbk/releases.qbk
==============================================================================
--- (empty file)
+++ sandbox/local/libs/local/doc/qbk/releases.qbk 2011-01-10 16:15:26 EST (Mon, 10 Jan 2011)
@@ -0,0 +1,32 @@
+
+[section:Releases Releases]
+
+[section Version 0.1.1]
+
+# Uploaded library source into Boost SVN sandbox.
+# Fixed prev/next arrows and other minor layouts in documentation.
+# Added Release section to documentation.
+
+[endsect]
+
+[section Version 0.1.0]
+
+# Shared with Boost for first round of comments.
+
+[endsect]
+
+[section Version 0.0.1]
+
+# Completed development, examples, and documentation.
+
+[endsect]
+
+[section TODO]
+
+# Finish local function parenthesized syntax validation macros.
+# Add examples to Alternatives section for Local Classes, C++0x lambads, Boost.Lambda, and Boost.Phoenix (ask boosters).
+
+[endsect]
+
+[endsect]
+

Added: sandbox/local/libs/local/doc/qbk/starting.qbk
==============================================================================
--- (empty file)
+++ sandbox/local/libs/local/doc/qbk/starting.qbk 2011-01-10 16:15:26 EST (Mon, 10 Jan 2011)
@@ -0,0 +1,102 @@
+
+[/ Copyright (C) 2009-2011 Lorenzo Caminiti ]
+[/ Use, modification, and distribution is subject to the ]
+[/ Boost Software License, Version 1.0 ]
+[/ (see accompanying file LICENSE_1_0.txt or a copy at ]
+[/ http://www.boost.org/LICENSE_1_0.txt). ]
+
+[section:Starting Starting]
+
+This section explains how to setup your system to use this library.
+
+[section This Documentation]
+
+Programmers should be ready to use this library, at least at a basic level, after reading the following sections of this documentation:
+
+* The __Introduction__ section provides an overview on the library and its features.
+* The __Starting__ section explains how to read this documentation, how to install the library to work with the supported compilers and platforms.
+* The __Tutorial__ section provides a good explanation of basic usages of the library with extensive examples.
+
+The following sections could be consulted at a later point to gain a more in-depth knowledge of the library features:
+
+* The __Advanced__ section explains advanced usages of the library.
+* The __Reference__ section is the reference manual of the library public API.
+* The __Grammar__ section formally describes the parenthesized syntax used by this library to specify the local function signatures.
+* The __Alternatives__ section describes alternatives to this library to implement local functions.
+* The __Examples__ section lists the source code of a few additional examples that use this library.
+
+The following sections are for reference only:
+
+* The __Releases__ section contains short release notes.
+* The __Bibliography__ section lists references that were consulted in the design and development of this library.
+* The __Acknowledgments__ section attempts to recognize all the people that contributes directly or indirectly to the design and development of this library.
+
+Furthermore, some footnotes are marked by the word "*Rationale*" because they explain reasons behind decisions made during the design and implementation of this library.
+
+[endsect]
+
+[section Compilers and Platforms]
+
+The implementation of this library uses preprocessor and template metaprogramming (as supported by __Boost_Preprocessor__ and __Boost_MPL__), templates with partial specializations and function pointers (to support an interface similar to the one of __Boost_Function__).
+As a consequence, this library is fairly demanding on compilers' compliance with the ISO C++ standard.
+At present, this library has been successfully compiled and tested on the following compilers and platforms:
+
+# GCC 4.2.4 on Ubuntu Linux.
+# GCC 3.4.4 on Cygwin.
+# Miscrosoft Visual Studio 8.0 on Windows XP.
+
+This library has not yet been tested on any other compiler or platform.
+
+[endsect]
+
+[section Installation]
+
+This library is composed of header files only.
+Therefore there is no pre-compiled object file which needs to be installed.
+Programmers can simply instruct the C++ compiler where to find the library header files (`-I` option for GCC, `/I` option for MSVC, etc) and they can start compiling the code from the __Examples__ section, the code cut-and-pasted from the examples in this documentation, and their own programs that use this library.
+
+This library implementation uses a number of __Boost__ libraries among which: __Boost_Preprocessor__, __Boost_ScopeExit__, __Boost_Typeof__, __Boost_TypeTraits__, and __Boost_MPL__.
+These __Boost__ libraries must be properly installed on your system in order for this library to work.
+
+[endsect]
+
+[section File Structure]
+
+The header files of this library are divided as follow:
+
+ ``[headerref boost/local/function.hpp] /local functions/``
+ ``[headerref boost/local/block.hpp] /local blocks/``
+ ``[headerref boost/local/exit.hpp] /local exits/``
+ ``[headerref boost/local/function_ref.hpp] /references to local functions/``
+
+[endsect]
+
+[section Symbols]
+
+The following symbols are part of the library private API, they are not documented, and they should not be directly used by programmers:
+[footnote
+*Rationale.*
+This library concatenates symbols specified by the programmers (e.g., the local function name) with other symbols (e.g., special prefixes or preprocessor line numbers) to make internal symbols with unique names to avoid name clashes.
+These symbols are separated by the letter "`X`" when they are concatenated so they can be read more easily while debugging the library.
+The underscore character "`_`" could not be used instead of the letter "`X`" because if the original symbols already contain a leading or trailing underscore the concatenation would result in a symbol with double underscores "`__`" which is reserved by the C++ standard.
+]
+
+* Any symbol defined by files within the `"boost/local/aux_/"` directory (these header files should not be directly included by programmers).
+* Any symbol prefixed by `BOOST_LOCAL_AUX`.
+* Any symbol within the `boost::local::aux` namespace.
+* Any symbol prefixed by `boost_local_aux` (regardless of its namespace).
+
+[endsect]
+
+[section Compile-Time Configuration]
+
+Some of the library behaviour can be changed at compile-time by defining special /configuration macros/.
+If a configuration macro is left undefined, the library will use an appropriate default value for it.
+
+All configuration macros have names prefixed by `BOOST_LOCAL_CONFIG` (see __Reference__ section).
+It is strongly recommended not to change this library configuration macros unless strictly necessary.
+
+[endsect]
+
+[endsect]
+

Added: sandbox/local/libs/local/doc/qbk/tutorial.qbk
==============================================================================
--- (empty file)
+++ sandbox/local/libs/local/doc/qbk/tutorial.qbk 2011-01-10 16:15:26 EST (Mon, 10 Jan 2011)
@@ -0,0 +1,414 @@
+
+[/ Copyright (C) 2009-2011 Lorenzo Caminiti ]
+[/ Use, modification, and distribution is subject to the ]
+[/ Boost Software License, Version 1.0 ]
+[/ (see accompanying file LICENSE_1_0.txt or a copy at ]
+[/ http://www.boost.org/LICENSE_1_0.txt). ]
+
+[section:Tutorial Tutorial]
+
+This section illustrates basic usages of local functions, local blocks, and local exits.
+
+[section Parenthesized Syntax]
+
+The /parenthesized syntax/ is used to pass the syntactic elements of a function signature as macro parameters in a way that resembles the usual C++ syntax.
+All the function signature elements are wrapped within round parenthesis `()` to form a __Boost_Preprocessor__ sequence called /parenthesized signature/.
+This allows to program preprocessor macros that can parse the parenthesized syntax expanding differently based on the different elements that are specified in the signature (if the function has parameters or not, if the result type token matches the `void` keyword or not, etc).
+
+[important
+The *general rules to program the parenthesized signature* are:
+
+1. Wrap all the signature syntactic elements within parenthesis `()`.
+[footnote
+The parenthesized syntax owes its name to the indeed large number of parenthesis `()` that are required to wrap its elements.
+Programmers might notice some similarities between the parenthesized syntax and the syntax of the __LISP__ programming language.
+However, these similarities are not intentional in that they were not a design choice but rather a consequence of the fact that both __LISP__ sequences and __Boost_Preprocessor__ sequences are formed by wrapping tokens within round parenthesis `()`.
+]
+
+2. If a token does not start with an alphanumeric symbol (i.e., `a-z`, `A-Z`, or `0-9`), replace the token with its alphanumeric equivalent (as indicated in the __Grammar__ section).
+[footnote
+*Rationale.*
+This constraint comes form the fact that the C++ preprocessor can only concatenate =##= alphanumeric symbols.
+]
+
+3. Empty parenthesis `()` are not allowed.
+[footnote
+*Rationale.*
+This constraint comes from the fact that the ISO C++ standard preprocessor forbids empty macro parameters (this is different for C99 and other more recent preprocessors).
+]
+
+4. Spaces and newlines do not matter and they can be used anywhere.
+]
+
+For example, let's rewrite the following C++ function signature using the parenthesized syntax:
+
+ int l(double& y, const double& x = 0.0)
+
+[*Step 1.]
+We start by wrapping all the syntactic elements within round parenthesis `()`:
+
+ (int) (l)( (double&)(y) (,) (const double&)(x)(=)(0.0) ) ``[*=/* wrap all elements within parenthesis `()` */=]``
+
+Note how parameter types are wrapped within parenthesis separately from parameter names.
+However, all the tokens of a parameter type are wrapped together within a single set of parenthesis because the parameter type is one single syntactic element of the function signature.
+For example, `x`'s type is specified by `(const double&)` and not by `(const)(double)(&)`.
+
+[*Step 2.]
+We note that the element `(,)` wraps the non-alphanumeric symbol "`,`" so it needs to be replaced.
+The parenthesized syntax requires no special delimiter to separate function parameters (see the __Grammar__ section) so `(,)` can simply be removed (if you like, you can use a space or a newline to separate the function parameters):
+
+ (int) (l)( (double&)(y) ``[*=/* use spaces or newlines instead of commas to separate parameters */=]`` (const double&)(x)(=)(0.0) )
+
+[*Step 3.]
+We note also that the element `(=)` wraps the non-alphanumeric symbol "`=`" so it also needs to be replaced.
+The parenthesized syntax uses the keyword `default` to specify a parameter default value (see the __Grammar__ section) so `(=)` is replaced by `(default)`:
+
+ (int) (l)( (double&)(y) (const double&)(x)``*(default)*``(0.0) )
+
+We are done.
+The following is the valid parenthesized signature:
+
+ (int) (l)( (double&)(y) (const double&)(x)(default)(0.0) )
+
+for a function:
+
+* With `int` result type.
+* Named `l`.
+* With one required parameter of type `double&` and named `y`.
+* With an optional parameter of type `const double&`, named `x`, and with default value `0.0`.
+
+[warning
+Unfortunately, there are intrinsic limitations to the amount of syntactic error checking that can be done by the parsing macros implemented using the preprocessor.
+As a consequence, an error in using the parenthesized syntax might result in *cryptic preprocessor errors*.
+The best way to identify and correct these errors is usually to visually inspect the signature comparing it with the parenthesized syntax grammar (see the __Grammar__ section).
+When syntactic errors can be detected by the parsing macros, they are raised at compile-time using error messages of the form `ERROR_`/description_text/.
+[footnote
+While there are fundamental limitations to the amount of parenthesized syntax error checking that can be done using the preprocessor (e.g., there is no way to gracefully detect and report a missing parenthesis "`)`"), the current implementation of the parsing macros does not perform all the error checking that could be done.
+Improving the parenthesized syntax error checking is a work in progress.
+Programmers are encouraged to report cryptic error messages they experience because of parenthesized syntax errors so to help this development effort.
+]
+]
+
+[h5 Functions With No Parameters]
+
+Let's rewrite the following C++ signature for a function with no parameters using the parenthesized syntax:
+
+ int l()
+
+If we wrap all the elements within parenthesis we have:
+
+ (int) (l)``*()*`` // Error: Empty parenthesis `()` cannot be used.
+
+However, this is not a valid parenthesized signature because it contains the empty parenthesis `()`.
+
+[note
+This limitation applies to the ISO C++ standard preprocessor but it does not apply to the C99 and other more recent preprocessors.
+This library allows the *use of empty parenthesis* `()` if the preprocessor used supports empty macro parameters.
+However, programmers should be well aware that if they use empty parenthesis in the parenthesized syntax, the code is not C++ ISO standard compliant and it will be less portable (that is why the use of empty parenthesis is excluded by the __Grammar__ section).
+]
+
+C++ also allows to use the keyword `void` to specify empty parameter lists.
+Therefore, the original C++ function signature can be equivalently rewritten as:
+
+ int l(void)
+
+If we now wrap all the elements within parenthesis we obtain the valid parenthesized signature:
+
+ (int) (l)( (void) ) // OK: Use `(void)` for empty parameter lists.
+
+In conclusion, the parenthesized syntax requires to use `(void)` to indicate an empty parameter list (see the __Grammar__ section).
+
+[endsect]
+
+[section Local Functions]
+
+Local functions are defined using the following macros (see the __Reference__ section) from within a declarative context (this is a limitation with respect to __CPP0x_lambda__ functions which can instead appear within expressions):
+
+ { // Some declarative context.
+ ...
+
+ __BOOST_LOCAL_FUNCTION__(
+ ``/parenthesized-signature/``
+ ) {
+ ``/local-function-body/``
+ } __BOOST_LOCAL_FUNCTION_END__(``/local-function-name/``)
+
+ ...
+ }
+
+This creates a functor object with the local function name that can be called from the enclosing scope.
+Note that:
+
+* The usual C++ scope visibility rules apply to local functions for which a local function is visible and can be called only within the enclosing scope in which it is defined.
+* The local function signature is expressed using the parenthesized syntax and passed to the `__BOOST_LOCAL_FUNCTION__` macro.
+* The local function body is defined in a code block `{ ... }` using the usual C++ syntax.
+The body is specified outside any of the macros so eventual compiler error messages and line numbers retain their usual meaning.
+[footnote
+*Rationale.*
+If the local function body were instead passed as a macro parameter, it would be expanded on a single line of code (because macros always expand as a single line of code).
+Therefore, eventual compiler error line numbers would all have the same value and would no longer be useful to pinpoint the error.
+]
+* The macro `__BOOST_LOCAL_FUNCTION_END__` is used to end the local function definition and it must repeat the local function name.
+[footnote
+*Rationale.*
+The local function name must be passed to the ending macro `__BOOST_LOCAL_FUNCTION_END__` so this macro can declare a local variable with the local function name to hold the local functor object.
+At the same time, the local function name must also be passed to the declaration macro `__BOOST_LOCAL_FUNCTION__` to allow the local function to recursively call itself.
+The local function declaration and ending macros are kept as two separate macros so that the local function body does not have to be passed as a macro parameter (otherwise, the compiler error line numbers will all appear on the same line and they will no longer be useful to pinpoint the errors).
+]
+The compiler will generate an error if the name specified by this macro does not match the one from the local function signature (see `__BOOST_LOCAL_FUNCTION_END_RENAME__` to remove this constraint).
+
+For example, let's program a local function `add` similar to the one in the example from the __Introduction__ section.
+We start by rewriting its signature:
+
+ void add(double num)
+
+using the parenthesized syntax:
+
+ (void) (add)( (double)(num) )
+
+For simplicity, we will not bind any of the variables in scope just yet (binding is explained later in this section).
+
+Then we pass the parenthesized signature to the `__BOOST_LOCAL_FUNCTION__` macro, we implement a simple body that prints the number, and we pass the local function name `add` to the `__BOOST_LOCAL_FUNCTION_END__` macro:
+
+[add_num_cpp]
+
+This creates a local function `add` that can be called from within the enclosing scope as for example by the `add(100.0);` instruction.
+
+[endsect]
+
+[section Binding]
+
+Variables in scope (local variables, enclosing function parameters, member variables, the object `this`, etc) can be bound to a local function declaration.
+Variables in scope can be bound by reference, by constant reference, by value, or by constant value.
+The types of bound variables are automatically deduced by this library using __Boost_Typeof__.
+[footnote
+*Rationale.*
+By binding a variable in scope, the local function declaration is specifying that such a variable should be accessible within the local function body regardless of its type.
+Semantically, this binding should be seen as an "extension" of the scope of the bound variable from the enclosing scope to the scope of the local function body.
+Contrary to the semantics of a function parameter passing, in-scope variable binding does not depend on the variable type but just on the variable name: "The variable in scope named /x/ should be accessible within the local function named /l/".
+This is especially useful for maintenance so if a bound variable type is changed, the local function declaration does not have to change.
+]
+
+[important
+User defined *types need to be manually registered* as usual when using __Boost_Typeof__ (see __Boost_Typeof__ documentation and the Local Exit example from the __Examples__ section).
+]
+
+The parenthesized syntax introduces the additional "keyword" `bind` which is used to list all the bound variable names wrapped within parenthesis at the end of the local function parameter list (see the __Grammar__ section):
+
+ (``/result-type/``) (``function-name``)( ``/parameters/`` ``*(bind)(*``(``/var1/``)(``/var2/``)``/.../``(``/varN/``)``*)*`` )
+
+Where /var/ is the name of the variable in scope to bind and it is prefixed by `&` if the variable is bound by reference, otherwise is it bound by value.
+
+For example, let's assume we want to bind two variables in scope `a` and `b` to the local function `l` shown before.
+Let's also assume we want to bind `a` by value and `b` by reference.
+Then we use the following parenthesized signature for the local function:
+
+ (int) (l)( (double&)(y) (const double&)(x)(default)(0.0) (bind)((a)(&b)) )
+
+If a variable is bound by value, then a copy of the variable value is taken at the point of the local function declaration.
+If a variable is bound by reference instead, the variable will refer to the value it has at the point of the local function call.
+Furthermore, it is the programmers' responsibility to ensure that variables bound by reference survive the scope of declaration of the local function otherwise the bound references will be invalid causing run-time errors (in other words, the usual care in using C++ references must be used for variables in scope bound by reference).
+It is also possible to bind a local function to another local function as shown in the STL Transform example from the __Examples__ section (note that local functions cannot be copied so they are always bound by reference even if `&` is not specified).
+
+The type of bound variables is automatically deduced and it is the exact same type used to declare such variables in the enclosing scope.
+Therefore:
+
+* If a bound variable was declared constant using the `const` qualifier then it will be bound by constant value or reference.
+* If a bound variable was not declared constant then it will not be bound as constant.
+This library allows to force constant biding even for variables that are not originally declared constant using `(const bind)(...)` as explained below.
+* You might want to bind variables of complex types by (constant) reference instead than by value to avoid expensive copy operations when these variables are automatically passed to the local function (as usual with C++ function parameter passing).
+
+For example, let's continue to program a local function `add` similar to the one from the example in __Introduction__ section.
+We bind the local variable `sum` by (non-constant) reference and update the body to perform the summation:
+
+[add_num_sum_cpp]
+
+[h5 Constant Binding]
+
+Constant binding allows to bind variables in scope by constant reference or constant value (constant binding is not supported by __CPP0x_lambda__ functions).
+[footnote
+An historical note: Constant binding of variables in scope was the main use case that originally motivated the authors in developing this library.
+The authors needed to locally create a chuck of code to assert some correctness conditions while these assertions were not supposed to modify any of the variables they were using (see the __Contractpp__ library).
+This was achieved by binding by constant reference the variables needed by the assertions and then by programming the local function body to check the assertions (or more conveniently by using `__BOOST_LOCAL_BLOCK__`).
+This way if any of the assertions mistakenly changes a bound variable (for example confusing the operator `==` with `=`), the compiler correctly generates an error because the bound variable is of `const` type within the local function body.
+]
+
+The parenthesized syntax uses the "keywords" `const bind` to list constant bound variables wrapped within parenthesis at the end of the function parameter list (see the __Grammar__ section):
+
+ (``/result-type/``) (``function-name``)( ``/parameters/`` ``*(const bind)(*``(``/cvar1/``)(``/cvar2/``)``/.../``(``/cvarM/``)``*)*`` )
+
+Where /cvar/ is the name of the variable in scope to bind by constant and it is prefixed by `&` if the variable is bound by constant reference, otherwise it is bound by constant value.
+If both constant and plain bindings are used, constant bindings must be specified before plain bindings (see the __Grammar__ section):
+
+ (``/result-type/``) (``function-name``)( ``/parameters/`` (const bind)((``/cvar1/``)(``/cvar2/``)``/.../``(``/cvarM/``)) (bind)((``/var1/``)(``/var2/``)``/.../``(``/varN/``)) ) /* `(const bind)(...)` before `(bind)(...)` */
+
+For example, let's assume we want to bind two variables in scope `c` and `d` to the local function `l` shown before.
+Let's also assume we want to bind `c` by constant value and `b` by costant reference.
+Then we use the following parenthesized signature for the local function:
+
+ (int) (l)( (double&)(y) (const double&)(x)(default)(0.0) (const bind)((c)(&d)) )
+
+If the variables in scope `a` and `b` are also bound but by (plain) value and reference respectively then the parenthesized signature becomes:
+
+ (int) (l)( (double&)(y) (const double&)(x)(default)(0.0) (const bind)((c)(&d)) (bind)((a)(&b)) )
+
+Note how `(const bind)(...)` must always be used before `(bind)(...)` when they are both present.
+
+For example, let's continue to program a local function `add` similar to the one in the example from the __Introduction__ section.
+We bind the local variable `factor` by constant value and update the body to perform the factor scaling:
+
+[add_num_factor_sum_cpp]
+
+[h5 Binding the Object `this`]
+
+It is also possible to bind the object `this` when it is in scope (from enclosing member functions, etc).
+This is done by using `this` as the name of the variable to bind and by using the special symbol `this_` (instead of `this`) to access the object within the local function body.
+Note that:
+
+* The object `this` can be bound by value using `(bind)((this)...)`.
+In this case the local function will be able to modify the object when the enclosing scope is a non-constant member, or it will not be able to modify the object when the enclosing scope is a constant member.
+* The object `this` can be bound by constant value `(const bind)((this)...)`.
+In this case the local function will never be able to modify the object (regardless of whether the enclosing scope is a constant member or not).
+* Finally, the object `this` can never be bound by reference because C++ does not allow to get a reference to `this`.
+You will get a compile-time error if you try to use `(bind)((&this)...)` or `(const bind)((&this)...)`.
+However, `this` is a pointer so the object is not copied even if it is bound by value.
+(Note that it is not possible to bind `*this` because it starts with `*` and it is not a variable name.)
+
+[important
+When the object `this` is bound to a local function, the local function *body must use the special symbol* `this_` (instead of `this`) to access the bound object.
+[footnote
+*Rationale.*
+This limitation comes from the fact that `this` is a reserved C++ keyword so it cannot be used as the name of the internal parameter passing the bound object to the local function body.
+It would be possible to use `this` (instead of `this_`) within the local function body either at the expenses of copying the bound object (which would introduce run-time overhead and also the stringent requirement that the bound object must have a deep copy constructor) or by relying on an [@http://groups.google.com/group/comp.lang.c++.moderated/browse_thread/thread/d3a86f27277f713b undefined behaviour of `static_cast`] (which might not work on all platforms at the cost of portability).
+]
+Using `this` within the local function body will generate a compile-time error so programmers cannot mistakenly confuse the use of `this_` with `this`.
+[footnote
+*Rationale.*
+This is because the body function is implemented as static function of the local functor class.
+]
+]
+
+For example, let's rewrite a local function `add` similar to the one in the example from the __Introduction__ section but using a member function to illustrate how to bind the object `this`:
+
+[add_this_cpp]
+
+[endsect]
+
+[section Local Blocks]
+
+Local blocks are defined using the following macros within a declarative context (see the __Reference__ section):
+
+ { // Some declarative context.
+ ...
+
+ __BOOST_LOCAL_BLOCK__( ``/parenthesized-binding/`` ) {
+ ``/block-body/``
+ } __BOOST_LOCAL_BLOCK_END__
+
+ ...
+ }
+
+This expands to code that executes the body instructions in place where the block is defined.
+However, only bound variables specified by the /parenthesized-binding/ are accessible from within the local block body.
+
+Adopting a parenthesized syntax similar to the one used for local functions (see the __Grammar__ section), the /parenthesized-binding/ can specify to bind no variable:
+
+ (void)
+
+Or, to bind variables by constant type only:
+
+ (const bind)((``/cvar1/``)(``/cvar2/``)``/.../``(``/cvarM/``))
+
+Or, to bind variables by plain type only:
+
+ (bind)((``/var1/``)(``/var2/``)``/.../``(``/varN/``))
+
+Or, to bind variables by both constant and plain types:
+
+ (const bind)((``/cvar1/``)(``/cvar2/``)``/.../``(``/cvarM/``)) (bind)((``/var1/``)(``/var2/``)``/.../``(``/varN/``))
+
+Where /cvar/ and /var/ are the names of the variables in scope to bind.
+They can be prefixed by `&` to bind by reference instead of by value, and one of them can be `this` to bind the object when it is in scope.
+
+[important
+A `return;` instruction from within a local block jumps to the end of the local block body and *it does not return the enclosing scope*.
+[footnote
+*Rationale.*
+Programmers might expect `return;` to exit the enclosing function instead of the local block (or local exit), especially if the enclosing function has a `void` result type.
+However, using `return;` to exit local blocks (and local exits) seemed to follow a more natural syntax and also it is the same syntax already provided by __Boost_ScopeExit__ (in fact, `return;` is used by __Boost_ScopeExit__ to exit the local scope and not to exit the enclosing scope).
+However, if programmers were to find this use of `return;` confusing, this library API could be changed to forbid the use of `return` from within local blocks (and local exits) generating a compile-time error, and to use a different instruction (e.g., `break;` or a special macro instruction like `BOOST_LOCAL_RETURN;`) to exit local blocks (and local exits).
+]
+]
+
+For example, let's program a local block similar to the one in the example from the __Introduction__ section:
+
+[add_block_cpp]
+
+[endsect]
+
+[section Local Exits]
+
+Local exits are defined using the following macros within a declarative context (see the __Reference__ section):
+
+ { // Some declarative context.
+ ...
+
+ __BOOST_LOCAL_EXIT__( ``/parenthesized-binding/`` ) {
+ ``/exit-body/``
+ } __BOOST_LOCAL_EXIT_END__
+
+ ...
+ }
+
+This expands to code that executes the body instructions when the enclosing scope is exited (i.e., at the very end of the enclosing scope).
+If multiple local exits are defined within the same scope, their bodies will be executed in the reverse order in which they have been defined.
+Only bound variables specified by /parenthesized-binding/ are accessible from within the local exit body.
+The /parenthesized-biding/ is specified following the exact same syntax as for the one used by local blocks.
+
+[note
+A `return;` instruction from within a local exit jumps to the end of the local exit body and *it does not return the enclosing scope*.
+]
+
+For example, let's program a local exit similar to the one in the example from the __Introduction__ section:
+
+[add_exit_cpp]
+
+Local exits are very similar to the functionality already provided by __Boost_ScopeExit__ with the addition that they also support constant binding and the binding of the object `this`.
+[footnote
+*Rationale.*
+This library could be merged together with __Boost_ScopeExit__ into a new library named Boost.Scope (from the meaning of the word "[@http://en.wikipedia.org/wiki/Scope_(programming) scope]" in computer programming).
+This would be justified by the fact that `__BOOST_LOCAL_EXIT__` simply extends the functionality already provided by `BOOST_SCOPE_EXIT`.
+The headers will be `"boost/scope/function.hpp"`, `"boost/scope/block.hpp"`, and `"boost/scope/exit.hpp"`.
+For backward compatibility with __Boost_ScopeExit__, the header `"boost/scope_exit.hpp"` could also be kept and it would be equivalent to including `"boost/scope/exit.hpp"`.
+In addition and again for backward compatibility, the `BOOST_SCOPE_EXIT` macro could be extended to accept either the original __Boost_ScopeExit__ sequence of `(var1)...(varN)` without the `bind` "keyword" (which would be equivalent to plain binding) or the parenthesized binding sequence with the `(bind)(...)` and `(const bind)(...)` "keywords" plus the binding of the object `this`.
+Local blocks would be named "scope blocks" and they would be provided by the `BOOST_SCOPE_BLOCK...` macros.
+However, local functions would have to be named "scope functions" and they would be provided by the `BOOST_SCOPE_FUNCTION...` macros.
+This might not be ideal because local functions are not known under the name of "scope functions" (they are indeed known by the name of "local functions" or "[@http://gcc.gnu.org/onlinedocs/gcc/Nested-Functions.html nested functions]").
+]
+
+[endsect]
+
+[section Templates]
+
+When local functions, local blocks, and local exits are programmed within templates, they need to be declared using the following special macros ending with the `TPL` postfix (see the __Reference__ section):
+[footnote
+*Rationale.*
+Within templates, this library needs to use `typename` to explicitly indicate that some expressions evaluate to a type.
+Because C++ does not allow this use of `typename` outside templates, the special `TPL` macros are used to indicate that the enclosing scope is a template so this library can safety use `typename` to resolve expression type ambiguities.
+]
+
+ __BOOST_LOCAL_FUNCTION_TPL__( ``/parenthesized-signature/`` )
+ __BOOST_LOCAL_BLOCK_TPL__( ``/parenthesized-binding/`` )
+ __BOOST_LOCAL_EXIT_TPL__( ``/parenthesized-binding/`` )
+
+These macros have the exact same API as their equivalents without the `TPL` postfix that we have seen so far.
+The local function, local block, and local exit ending macros (with the `END` postfix) can be used unchanged within templates.
+
+For example, let's rewrite an example similar to the one from the __Introduction__ section but wrapped within a template:
+
+[add_template_cpp]
+
+[endsect]
+
+[endsect]
+

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