Determine Whether a Component Handles Container Attributes (Qi and Karma)

handles_container

The template handles_container is a template meta-function used as an attribute customization point. It is invoked by the Qi Sequence (>>) and Karma Sequence (<<) operators in order to determine whether a sequence element (component) handles container attributes directly. This customization point is invoked for container attributes only, and only if the sequence is compatible with the supplied container attribute.

If a component, which is part of a sequence is able to handle a container attribute directly, the sequence passes the attribute to the component without any additional action. In Spirit.Qi the component uses the attribute to directly store all matched attributes. In Spirit.Karma the generator component extracts the attributes needed for output generation directly from this attribute.

If a component, which is part of a sequence is not able to handle container attributes, in Spirit.Qi the sequence passes a new instance of the container attributes' value_type to the parser component, inserting the result into the attribute on behalf of the parser component. In Spirit.Karma the sequence extracts the next container element on behalf of the generator component and passing it the extracted value.

Header

#include <boost/spirit/home/support/handles_container.hpp>

Also, see Include Structure.

	Note
	This header file does not need to be included directly by any user program as it is normally included by other Spirit header files relying on its content.

Namespace

Name
`boost::spirit::traits`

Synopsis

template <
    typename Component, typename Attribute, typename Context,
    typename Iterator, typename Enable>
struct handles_container
{
    <unspecified>;
};

Template parameters

Parameter	Description	Default
`Component`	The component type `Component` which needs to be tested whether it handles container attributes directly.	none
`Attribute`	The attribute type `Attribute` as passed to the sequence operator.	none
`Context`	This is the type of the current component execution context.	`unused_type`
`Iterator`	The type, `Iterator` is the type of the iterators used to invoke the component.	`unused_type`
`Enable`	Helper template parameter usable to selectively enable or disable certain specializations of `is_container` utilizing SFINAE (i.e. `boost::enable_if` or `boost::disable_if`).	`void`

Notation

Component: A component type to be tested whether it directly handles container attributes in the context of sequences.
Attribute: A container attribute type as passed to the sequence.
T1, T2, ...: Arbitrary types

Expression Semantics

Expression	Semantics
`handles_container<Component, Attribute>::type`	Result of the metafunction that evaluates to `mpl::true_` if a given component type `Component`, handles container attributes directly, `mpl::false_` otherwise. Generally, any implementation of `handles_container` needs to behave as if if was a MPL Boolean Constant.

Predefined Specializations

Spirit predefines specializations of this customization point for several types. The following table lists those types together with the conditions for which the corresponding specializations will evaluate to mpl::true_ (see MPL Boolean Constant):

Template Parameters	Semantics
`Component`, `Attribute`	Always returns `mpl::false_` (the default).
`rule<Iterator, T1, T2, T3, T4>`, `Attribute`	Returns `is_container<A>`, where `A` is the attribute exposed by the rule (Spirit.Qi and Spirit.Karma).
`grammar<Iterator, T1, T2, T3, T4>`, `Attribute`	Returns `is_container<A>`, where `A` is the attribute exposed by the grammar (Spirit.Qi and Spirit.Karma).

When to implement

The customization point handles_container needs to be implemented for a specific type whenever this type directly handles container attributes. It is applicable for parsers (Spirit.Qi) and generators (Spirit.Karma). It will have to be implemented under rare circumstances only.