[#except]
[section except]

[h1 Synopsis]

  template <class P, class Result, class ErrorMsg>
  struct except;

This is a [link parser_combinator parser combinator].

[table Arguments
  [[Name]       [Type]]
  [[`P`]        [[link parser parser]]]
  [[`Result`]   [[link metaprogramming_value template metaprogramming value]]]
  [[`ErrorMsg`] [[link parsing_error_message parsing error message]]]
]

[h1 Description]

`except` accepts the input when `P` rejects it and the result of parsing is the
`Result` argument. When `P` accepts the input, `except` rejects it and the
reason is `ErrorMsg`.

[h1 Header]

  #include <boost/metaparse/except.hpp>

[h1 Expression semantics]

For any `p` parser, `c` class, `msg` parsing error message, `s` compile-time
string and `pos` source position the following are equivalent

  get_result<except<p, c, msg>, s, pos>::type
  c

  get_remaining<except<p, c, msg>, s, pos>::type
  s

  get_position<except<p, c, msg>, s, pos>::type
  pos

when `p` rejects the input. The result of the parser is an error with the error
message `msg` otherwise.

[h1 Example]

  #include <boost/metaparse/except.hpp>
  #include <boost/metaparse/int_.hpp>
  #include <boost/metaparse/string.hpp>
  #include <boost/metaparse/start.hpp>
  #include <boost/metaparse/get_result.hpp>
  #include <boost/metaparse/get_message.hpp>
  #include <boost/metaparse/define_error.hpp>
  
  #include <type_traits>
  
  using namespace boost::metaparse;
  
  BOOST_METAPARSE_DEFINE_ERROR(
    number_is_not_allowed,
    "numbers are not allowed here"
  );
  
  using except_int =
    except<int_, std::integral_constant<int, 1>, number_is_not_allowed>;
  
  static_assert(
    get_result<
      except_int::apply<BOOST_METAPARSE_STRING("foo"), start>
    >::type::value == 1,
    "it should accept the input when it is not an integer"
  );
  
  static_assert(
    std::is_same<
      number_is_not_allowed,
      get_message<except_int::apply<BOOST_METAPARSE_STRING("13"), start>>::type
    >::type::value,
    "it should reject the input when it is an integer"
  );

[endsect]