Transform an Attribute to a Different Type (Qi and Karma)

transform_attribute

The template transform_attribute is a type used as an attribute customization point. It is invoked by Qi rule, semantic action and attr_cast, and Karma rule, semantic action and attr_cast. It is used to automatically transform the user provided attribute to the attribute type expected by the right hand side component (for rule), the semantic action, or the embedded component (for attr_cast).

	Note
	The interface of this customization point has been changed with Boost V1.44. We added the `Domain` template parameter to allow for more fine grained specializations for Spirit.Qi and Spirit.Karma.

Module Headers

#include <boost/spirit/home/support/attributes.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 Exposed, typename Transformed, typename Domain, typename Enable>
struct transform_attribute
{
    typedef <unspecified> type;

    static type pre(Exposed& val);
    static void post(Exposed& val, type attr);    // Qi only
    static void fail(Exposed&);                   // Qi only
};

Template parameters

Parameter	Description	Default
`Exposed`	The attribute type supplied to the component which needs to be transformed.	none
`Transformed`	The attribute type expected by the component to be provided as the result of the transformation.	none
`Domain`	The domain of the sub library the template is instantiated in. Typically this is either `qi::domain` or `karma::domain`.	none
`Enable`	Helper template parameter usable to selectively enable or disable certain specializations of `transform_attribute` utilizing SFINAE (i.e. `boost::enable_if` or `boost::disable_if`).	`void`

Notation

Exposed: The type, Exposed is the type of the attribute as passed in by the user.
Transformed: The type, Transformed is the type of the attribute as passed along to the right hand side of the rule (embedded component of attr_cast).
Domain: The domain of the sub library the template is instantiated in. Typically this is either qi::domain or karma::domain.
exposed: An instance of type Exposed.
transformed: An instance of type Transformed.

Expression Semantics

Expression	Semantics
`transform_attribute<Exposed, Transformed, Domain>::type`	Evaluates to the type to be used as the result of the transformation (to be passed to the right hand side of the `rule` or to the embedded component of the `attr_cast`. Most of the time this is equal to `Transformed`, but in other cases this might evaluate to `Transformed&` instead avoiding superfluous object creation.
type transform_attribute<Exposed, Transformed, Domain>::pre(exposed)	Do `pre`-transformation before invoking the right hand side component for `rule` (or the embedded component for `attr_cast`). This takes the attribute supplied as by the user (of type `Exposed`) and returns the attribute to be passed down the component hierarchy (of the type as exposed by the metafunction `type`). This function will be called in Qi and for Karma.
void transform_attribute<Exposed, Transformed, Domain>::post(exposed, transformed)	Do `post`-transformation after the invocation of the right hand side component for `rule` (or the embedded component for `attr_cast`). This takes the original attribute as supplied by the user and the attribute as returned from the right hand side (embedded) component and is expected to propagate the result back into the supplied attribute instance. This function will be called in Qi only.
void transform_attribute<Exposed, Transformed, Domain>::fail(exposed)	Handling failing parse operations of the right hand side component for `rule` (or the embedded component for `attr_cast`). This function will be called in Qi only.

Predefined Specializations

Template parameters	Semantics
`Exposed`, `Transformed`	`type` evaluates to `Transformed`, `pre()` returns a new instance of `Transformed` constructed from the argument of type `Exposed`, `post()` assigns `transformed` to `exposed`.
`optional<Exposed>`, `Transformed`, `typename disable_if<is_same<optional<Exposed>, Transformed> >::type`	`type` evaluates to `Transformed&`, `pre()` returns a reference to the instance of `Transformed` stored in the passed optional (the argument of type `optional<Exposed>`), the optional instance is initialized, if needed. `post()` does nothing, `fail()` resets the optional (its parameter) instance to the non-initialized state.
`Exposed&`, `Transformed`	`type` evaluates to `Transformed`, `pre()` returns a new instance of `Transformed` constructed from the argument of type `Exposed`, `post()` assigns `transformed` to `exposed`.
`Attrib&`, `Attrib`	`type` evaluates to `Attrib&`, `pre()` returns it's argument, `post()` does nothing.
`Exposed const`, `Transformed`	(usind in Karma only) `type` evaluates to `Transformed`, `pre()` returns it's argument, `post()` is not implemented.
`Attrib const&`, `Attrib`	(usind in Karma only) `type` evaluates to `Attrib const&`, `pre()` returns it's argument, `post()` is not implemented.
`Attrib const`, `Attrib`	(usind in Karma only) `type` evaluates to `Attrib const&`, `pre()` returns it's argument, `post()` is not implemented.
`unused_type`, `Attrib`	`type` evaluates to `unused_type`, `pre()` and `post()` do nothing.
`Attrib`, `unused_type`	`type` evaluates to `unused_type`, `pre()` and `post()` do nothing.

When to implement

The customization point transform_attribute needs to be implemented for a specific pair of types whenever the attribute type supplied to a rule or attr_cast cannot automatically transformed to the attribute type expected by the right hand side of the rule (embedded component of the attr_cast) because the default implementation as shown above is not applicable. Examples for this could be that the type Transformed is not constructible from the type Exposed.