Merge branch 'master' into gh-pages

.github/workflows/macos-12.yml

@@ -2,9 +2,9 @@ name: macos-12 - Clang 13
 
 on:
   push:
-    branches: [ master, develop ]
+    branches: [ master, develop, boost_review_changes ]
   pull_request:
-    branches: [ master, develop ]
+    branches: [ master, develop, boost_review_changes ]
 
 env:
   # Customize the CMake build type here (Release, Debug, RelWithDebInfo, etc.)

.github/workflows/ubuntu-20.04.yml

@@ -2,9 +2,9 @@ name: Ubuntu-20.04 - GCC 9,10
 
 on:
   push:
-    branches: [ master, develop ]
+    branches: [ master, develop, boost_review_changes ]
   pull_request:
-    branches: [ master, develop ]
+    branches: [ master, develop, boost_review_changes ]
 
 env:
   # Customize the CMake build type here (Release, Debug, RelWithDebInfo, etc.)

.github/workflows/ubuntu-22.04.yml

@@ -2,9 +2,9 @@ name: Ubuntu-22.04 - GCC 10,11
 
 on:
   push:
-    branches: [ master, develop ]
+    branches: [ master, develop, boost_review_changes ]
   pull_request:
-    branches: [ master, develop ]
+    branches: [ master, develop, boost_review_changes ]
 
 env:
   # Customize the CMake build type here (Release, Debug, RelWithDebInfo, etc.)

.github/workflows/windows-2019.yml

@@ -2,9 +2,9 @@ name: windows-2019 - Visual Studio 2019
 
 on:
   push:
-    branches: [ master, develop ]
+    branches: [ master, develop, boost_review_changes ]
   pull_request:
-    branches: [ master, develop ]
+    branches: [ master, develop, boost_review_changes ]
 
 env:
   # Customize the CMake build type here (Release, Debug, RelWithDebInfo, etc.)

.github/workflows/windows-2022.yml

@@ -2,9 +2,9 @@ name: windows-2022 - Visual Studio 2022
 
 on:
   push:
-    branches: [ master, develop ]
+    branches: [ master, develop, boost_review_changes ]
   pull_request:
-    branches: [ master, develop ]
+    branches: [ master, develop, boost_review_changes ]
 
 env:
   # Customize the CMake build type here (Release, Debug, RelWithDebInfo, etc.)

CMakeLists.txt

@@ -12,6 +12,8 @@ if (CMAKE_CXX_COMPILER_ID STREQUAL Clang)
     add_definitions(-g -Wall)
 elseif (CMAKE_CXX_COMPILER_ID STREQUAL GNU)
     add_definitions(-g -Wall)
+elseif (CMAKE_CXX_COMPILER_ID STREQUAL MSVC)
+    add_definitions(/W3)
 endif ()
 
 ##################################################

doc/Jamfile.v2

@@ -24,6 +24,7 @@ doxygen parser_reference
         # note that there is no detail::unspecified -- this is a hack to get all
         # the SFINAE code out of the API docs.
         <doxygen:param>"PREDEFINED=\"BOOST_PARSER_DOXYGEN=1\" \\
+                                   \"BOOST_PARSER_USE_CONCEPTS=1\" \\
                                    \"enable_if=detail::unspecified\""
         <doxygen:param>HIDE_UNDOC_MEMBERS=NO
         <doxygen:param>EXTRACT_PRIVATE=NO
@@ -37,7 +38,7 @@ doxygen parser_reference
 
 }
 
-run_doxygen [ glob ../include/boost/parser/*.hpp ] : "Reference" ;
+run_doxygen [ glob ../include/boost/parser/*.hpp : ../include/boost/parser/concepts.hpp ] : "Reference" ;
 
 xml parser
     :

doc/intro.qbk

@@ -163,7 +163,8 @@ However, it does not suit user needs in some ways.
   rule.
 
 * Spirit X3 is missing many of the convenient interfaces to parsers that
-  Spirit 2 had.  For instance, you cannot add parameters to a parser.
+  Spirit 2 had.  For instance, you cannot add parameters to a parser (see
+  description of _locals_ in _more_about_rules_).
 
 * All versions of Spirit have Unicode support, but it is quite difficult to
   get working.
@@ -184,10 +185,104 @@ that have been retained in _Parser_.  Both libraries:
 * use approximately the same set of directives to influence the parse
   (e.g. `lexeme[]`);
 
-* provide loosely-coupled rules that are separately compilable (at least for
-  Spirit X3); and
-
 * are built around a flexible parse context object that has state added to and
   removed from it during the parse (again, comparing to Spirit X3).
 
+[heading The Spirit X3 rule problem]
+
+Some readers have wanted a concrete example of my claim that Spirit X3's rules
+do not compose well.  Consider this program.
+
+    #include <boost/spirit/home/x3.hpp>
+
+    #include <iostream>
+    #include <set>
+    #include <string>
+    #include <vector>
+
+
+    namespace x3 = boost::spirit::x3;
+    using ints_type = x3::rule<class ints, std::vector<int>>;
+    BOOST_SPIRIT_DECLARE(ints_type);
+
+    x3::rule<class ints, std::vector<int>> ints = "ints";
+    constexpr auto ints_def = x3::int_ % ',';
+    BOOST_SPIRIT_DEFINE(ints);
+
+    #define FIXED_ATTRIBUTE 0
+
+
+    int main()
+    {
+        std::string input = "43, 42";
+        auto first = input.begin();
+        auto const last = input.end();
+    #if FIXED_ATTRIBUTE
+        std::vector<int> result;
+    #else
+        std::set<int> result;
+    #endif
+        bool success = x3::phrase_parse(first, last, ints, x3::space, result);
+        if (success) {
+            // We want this to print "43 42\n".
+            for (auto x : result) {
+                std::cout << x << ' ';
+            }
+            std::cout << "\n";
+        }
+
+        return 0;
+    }
+
+Defining `FIXED_ATTRIBUTE` to be `1` leads to a well-formed program that
+prints `"42 43\n"` instead of the desired result.  The problem here is that if
+you feed an attribute out-param to `x3::phrase_parse()`, you get the
+loose-match semantics that Spirit X3 and _Parser_ both do.  This is a problem,
+because the user explicitly asserted that the type of the `ints` rule's
+attribute should be `std::vector<int>`.  In my opinion, this code should be
+ill-formed with `FIXED_ATTRIBUTE == 1`.  To make it well-formed again, the
+user could use `ints_def` directly, since it does not specify an attribute
+type.
+
+When the user explicitly states that a type is some fixed `T`, a library
+should not ignore that.  As a user of X3, I was bitten by this in such a way
+that I considered X3 to be a nonviable option for my uses.  I ran into a
+problem that resulted from X3's ignoring one or more of my rules' attributes
+so that it made the parse produce the wrong result, and I could see no way to
+fix it.
+
+When a library provides wider use cases via genericity, we generally consider
+this a good thing.  If it is too loose in its semantics, we generally say that
+it is type-unsafe.  Using _rs_ to nail down type flexibility is one way
+_Parser_ tries to enable genericity where it is desired, and let the user turn
+it off where it is not.
+
+[endsect]
+
+[section Cheat Sheet]
+
+Here are all the tables containing the various _Parser_ parsers, examples,
+etc., all in one place.  These are repeated elsewhere in different sections of
+the tutorial.
+
+[heading The parsers]
+
+[table_parsers_and_their_semantics]
+
+[heading Operators defined on parsers]
+
+[table_combining_operations]
+
+[heading Attribute generation for certain parsers]
+
+[table_attribute_generation]
+
+[heading Attributes for operations on parsers]
+
+[table_attribute_combinations]
+
+[heading More attributes for operations on parsers]
+
+[table_seq_or_attribute_combinations]
+
 [endsect]

doc/parser.qbk

@@ -39,6 +39,9 @@
 [import ../example/parsing_into_a_class.cpp]
 [import ../example/struct_rule.cpp]
 [import ../example/user_error_handler.cpp]
+[import ../test/parser.cpp]
+[import ../test/parser_rule.cpp]
+[import ../test/parser_quoted_string.cpp]
 
 [import ../include/boost/parser/concepts.hpp]
 [import ../include/boost/parser/error_handling_fwd.hpp]
@@ -67,6 +70,17 @@
 [def _cb_r_                [classref boost::parser::callback_rule `callback_rule`]]
 [def _cb_rs_               [classref boost::parser::callback_rules `callback_rule`s]]
 
+[def _skp_p_               [classref boost::parser::skip_parser `skip_parser`]]
+[def _xfm_p_               [classref boost::parser::transform_parser `tranform_parser`]]
+[def _noc_p_               [classref boost::parser::no_case_parser `no_case_parser`]]
+[def _sv_p_                [classref boost::parser::string_view_parser `string_view_parser`]]
+[def _raw_p_               [classref boost::parser::raw_parser `raw_parser`]]
+[def _omt_p_               [classref boost::parser::omit_parser `omit_parser`]]
+[def _rpt_p_               [classref boost::parser::repeat_parser `repeat_parser`]]
+[def _lex_p_               [classref boost::parser::lexeme_parser `lexeme_parser`]]
+[def _seq_p_               [classref boost::parser::seq_parser `seq_parser`]]
+[def _seq_ps_              [classref boost::parser::seq_parser `seq_parser`s]]
+
 [def _bp_tup_              [classref boost::parser::tuple `boost::parser::tuple`]]
 [def _bp_get_              [funcref boost::parser::get `boost::parser::get`]]
 [def _bh_tup_              `boost::hana::tuple`]
@@ -105,6 +119,9 @@
 [def _cbp_                 [funcref boost::parser::callback_parse `callback_parse()`]]
 [def _cbpp_                [funcref boost::parser::callback_prefix_parse `callback_prefix_parse()`]]
 
+[def _attr_                [classref boost::parser::attribute `attribute`]]
+[def _attr_t_              [classref boost::parser::attribute_t `attribute_t`]]
+
 [def _w_glb_               [funcref boost::parser::with_globals `with_globals()`]]
 [def _w_eh_                [funcref boost::parser::with_error_handler `with_error_handler()`]]
 
@@ -182,6 +199,7 @@
 [def _skip_                [globalref boost::parser::skip `skip[]`]]
 [def _merge_               [globalref boost::parser::merge `merge[]`]]
 [def _sep_                 [globalref boost::parser::separate `separate[]`]]
+[def _transform_           [globalref boost::parser::transform `transform(f)[]`]]
 
 [def _omit_np_             [globalref boost::parser::omit `omit`]]
 [def _raw_np_              [globalref boost::parser::raw `raw`]]
@@ -191,6 +209,7 @@
 [def _skip_np_             [globalref boost::parser::skip `skip`]]
 [def _merge_np_            [globalref boost::parser::merge `merge`]]
 [def _sep_np_              [globalref boost::parser::separate `separate`]]
+[def _transform_np_        [globalref boost::parser::transform `transform`]]
 
 [def _blank_               [globalref boost::parser::blank `blank`]]
 [def _control_             [globalref boost::parser::control `control`]]
@@ -200,16 +219,19 @@
 [def _lower_               [globalref boost::parser::lower `lower`]]
 [def _upper_               [globalref boost::parser::upper `upper`]]
 
+[def _quot_str_            [globalref boost::parser::quoted_string `quoted_string`]]
+
 [def _RES_                 ['[^RESOLVE]]`()`]
 [def _RES_np_              ['[^RESOLVE]]]
 [def _ATTR_                ['[^ATTR]]`()`]
 [def _ATTR_np_             ['[^ATTR]]]
 
 [def _p_api_               [link boost_parser__proposed_.tutorial.the__parse____api The `parse()` API]]
+[def _parsers_uses_        [link boost_parser__proposed_.tutorial.the_parsers_and_their_uses The Parsers And Their Uses]]
 [def _parse_ctx_           [link boost_parser__proposed_.tutorial.the_parse_context The Parse Context]]
 [def _rule_parsers_        [link boost_parser__proposed_.tutorial.rule_parsers Rule Parsers]]
 [def _parsing_structs_     [link boost_parser__proposed_.tutorial.parsing_into__struct_s_and__class_es Parsing into `struct`s and `class`es]]
-[def _expect_pts_          [link boost_parser__proposed_.tutorial.backtracking.html#boost_parser__proposed_.tutorial.backtracking.expectation_points Expectation points]]
+[def _expect_pts_          [link boost_parser__proposed_.tutorial.backtracking.expectation_points Expectation points]]
 [def _attr_gen_            [link boost_parser__proposed_.tutorial.attribute_generation Attribute Generation]]
 [def _directives_          [link boost_parser__proposed_.tutorial.directives Directives]]
 [def _eh_debugging_        [link boost_parser__proposed_.tutorial.error_handling_and_debugging Error Handling and Debugging]]
@@ -235,6 +257,7 @@
 
 [def _emdash_              \u2014]
 
+[include tables.qbk]
 [include intro.qbk]
 [include tutorial.qbk]
 [include examples.qbk]