Action Reference

June 2, 2026 · View on GitHub

The reference documentation for all included actions. The actions related to stream parsing are documented here.

Preamble
Actions
Index

Preamble

By default all actions reside in namespace tao::pegtl.

Only include/tao/pegtl/nothing.hpp, which defines nothing and maybe_nothing, is automatically included with <tao/pegtl.hpp>. For all other actions the appropriate headers from include/tao/pegtl/action/ need to be included manually.

The action classes shown below are selectively attached in the usual way. For example we can invoke change_action to switch the parsing run from my_action to other_action while parsing some_rule as follows.

template< typename Rule >
struct other_action;

template< typename Rule >
struct my_action
   : tao::pegtl::nothing< Rule >
{};

template<>
struct my_action< some_rule >
   : tao::pegtl::change_action< other_action >
{};

Important

Please remember that the current apply_mode enables or disables only the apply() and apply0() action functions. When an action has a match() function it will be called regardless of apply_mode.

Some actions have a success() function that is called when the rule the action was attached to succeeds. In some cases there is a default implementation that can be replaced with a user-defined function, in other cases there is no default and a user-defined function has to be supplied.

In either case, the procedure to supply a user-defined success() is the same.

template< typename Rule >
struct my_action
   : tao::pegtl::nothing< Rule >
{ /* base definition */ }

struct action_that_calls_success;

template<>
struct my_action< some_rule >
   : action_that_calls_success
{
   template< typename ParseInput,
             typename... States >
   static void success( const ParseInput&, States&&... )
   {
      ...
   }
};

Alternatively an intermediate class can be created that inherits from action_that_calls_success and implements success(), but is not itself attached to a rule. Then specializations of my_action would inherit from that intermediate class. This approach requires more code but is more modular.

Note that the correct success() function will be called by action_that_calls_success::match() even though the function is not virtual because action_that_calls_success::match() does not call action_that_calls_success::success(). Instead, assuming the currently matched rule is Rule and the current action class template is Action, it calls Action< Rule >::success().

This pattern is used throughout the PEGTL and is the reason for all action and control functions being passed the current action and control classes as template parameters, to make functions in derived classes visible and callable.

Actions

By default all action classes and class templates reside in namespace tao::pegtl.

`add_guard< G >`

Creates an object of type G before parsing the rule R it is attached to.
If G can be default-constructed it will be, or
it will be constructed with the input and all previous states as arguments.
If actions are enabled and G has a success() method it will be called with the input and all states if R succeeds.
Included via include/tao/pegtl/action/add_guard.hpp.
This action implements only a match() function and therefore:
Publicly derives from maybe_nothing.

The difference between add_guard and add_state is that add_guard does not add the newly constructed object to the states while parsing the rule it is attached to.

template< typename AddGuard >
struct add_guard
   : maybe_nothing
{
   template< typename Rule,
             apply_mode A,
             rewind_mode M,
             template< typename... >
             class Action,
             template< typename... >
             class Control,
             typename ParseInput,
             typename... States >
   [[nodiscard]] static bool match( ParseInput& in, States&&... st );

   template< typename ParseInput,
             typename... States >
   static void success( const ParseInput& in, AddGuard& g, States&&... st );
};

`add_state< S >`

Creates an object of type S before parsing the rule R it is attached to.
Adds this new object of type S as first state object while parsing R.
If S can be default-constructed it will be, or
it will be constructed with the input and all previous states as arguments.
If actions are enabled and S has a success() method it will be called with the input and all states if R succeeds.
Included via include/tao/pegtl/action/add_state.hpp.
This action implements only a match() function and therefore:
Publicly derives from maybe_nothing.

The difference between add_guard and add_state is that add_state adds the newly constructed object as first state while parsing the rule it is attached to.

template< typename AddState >
struct add_state
   : maybe_nothing
{ ... };

`change_action< A >`

Parses the rule it is attached to substituting A as current action.
Does not change the current apply_mode.
Non-intrusive action equivalent of the action rule.
Included via include/tao/pegtl/action/change_action.hpp.
This action implements only a match() function and therefore:
Publicly derives from maybe_nothing.

template< template< typename... > class NewAction >
struct change_action
   : maybe_nothing
{ ... };

`change_action_and_state< A, S >`

Parses the rule it is attached to substituting A as current action.
Does not change the current apply_mode.
Creates an object of type S before parsing the rule R it is attached to.
Uses the new object of type S as only state object while parsing R.
If S can be default-constructed it will be, or
it will be constructed with the input and all previous states as arguments.
If actions are enabled and S has a success() method it will be called with the input and all states if R succeeds.
Combines change_action and change_state into a single action.
Included via include/tao/pegtl/action/change_action_and_state.hpp.
This action implements only a match() function and therefore:
Publicly derives from maybe_nothing.

template< template< typename... > class NewAction, typename NewState >
struct change_action_and_state
   : maybe_nothing
{ ... };

`change_action_and_states< A, S... >`

Combines change_action and change_states into a single action.
Parses the rule it is attached to substituting A as current action.
Does not change the current apply_mode.
Creates objects of types S... before parsing the rule R it is attached to.
Uses the new objects of types S... as state objects while parsing R.
The new states are all default-constructed.
If actions are enabled it calls A< R >::success() with the new and old states as arguments in that order.
There is no default implementation for success(), it must be user defined.
Included via include/tao/pegtl/action/change_action_and_states.hpp.
This action implements only a match() function and therefore:
Publicly derives from maybe_nothing.

template< template< typename... > class NewAction, typename... NewStates >
struct change_action_and_states
   : maybe_nothing
{ ... };

`change_control< C >`

Parses the rule it is attached to substituting C as current control.
Non-intrusive action equivalent of the control rule.
Included via include/tao/pegtl/action/change_control.hpp.
This action implements only a match() function and therefore:
Publicly derives from maybe_nothing.

template< template< typename... > class NewControl >
struct change_control
   : maybe_nothing
{ ... };

`change_rule< R >`

Parses this action's template parameter instead of the rule this action is attached to.
Included via include/tao/pegtl/action/change_rule.hpp.
This action implements only a match() function and therefore:
Publicly derives from maybe_nothing.

template< typename NewRule >
struct change_rule
   : maybe_nothing
{ ... };

Caution

The change made by this action is invisible to the grammar analysis.

`change_state< S >`

Creates an object of type S before parsing the rule R it is attached to.
Uses the new object of type S as only state object while parsing R.
If S can be default-constructed it will be, or
it will be constructed with the input and all previous states as arguments.
If actions are enabled and S has a success() method it will be called with the input and all states if R succeeds.
Included via include/tao/pegtl/action/change_state.hpp.
This action implements only a match() function and therefore:
Publicly derives from maybe_nothing.

template< typename NewState >
struct change_state
   : maybe_nothing
{ ... };

`change_states< S... >`

Creates objects of types S... before parsing the rule R it is attached to.
Uses the new objects of types S... as state objects while parsing R.
The new states are all default-constructed.
If actions are enabled it calls A< R >::success() with the new and old states as arguments in that order.
There is no default implementation for success(), it must be user defined.
Included via include/tao/pegtl/action/change_states.hpp.
This action implements only a match() function and therefore:
Publicly derives from maybe_nothing.

template< typename... NewStates >
struct change_states
   : maybe_nothing
{ ... };

`check_consume< N >`

Checks how many input objects the rule it is attached to consumed.
Throws an exception when it consumed more than N input objects.
Included via include/tao/pegtl/action/check_consume.hpp.
This action implements only a match() function and therefore:
Publicly derives from maybe_nothing.
Similar to limit_consume, but check_consume checks the consumption after matching.

 template< std::size_t Maximum >
 struct check_consume
    : maybe_nothing
 { ... };

`check_depth< N >`

Limits the rule nesting depth for the rule(s) it is attached to.
Throws an exception when the nesting depth exceeds the limit.
Does not count rules when control is disabled.
Requires an input with make_depth_guard() function like input_with_depth.
Publicly derives from maybe_nothing.

 template< std::size_t Maximum >
 struct check_depth
    : maybe_nothing
 { ... };

`control_action`

Adds the start(), success() and failure() control functions to the action.
Implements do-nothing default versions of these functions.
Optionally adds the unwind() control function to the action.
Included via include/tao/pegtl/action/control_action.hpp.
This action implements only a match() function and therefore:
Publicly derives from maybe_nothing.

struct control_action
   : maybe_nothing
{ ... };

When using this action, all specializations my_control< Rule > that use control_action as base class have to implement the following member functions.

   template< typename ParseInput, typename... States >
   static void start( const ParseInput&, States&&... );

   template< typename ParseInput, typename... States >
   static void success( const ParseInput&, States&&... );

   template< typename ParseInput, typename... States >
   static void failure( const ParseInput&, States&&... );

The unwind() function is optional. As in other cases where the PEGTL auto-detects the presence of unwind() its absence will lead to a micro-optimization (by omitting a guard object or a try-catch block).

   template< typename ParseInput, typename... States >
   static void unwind( const ParseInput&, States&&... );

`disable_action`

Parses the rule it is attached to with actions disabled:
Changes the current apply_mode to apply_mode::disabled.
Non-intrusive action equivalent of the disable rule.
Included via include/tao/pegtl/action/disable_action.hpp.
This action implements only a match() function and therefore:
Publicly derives from maybe_nothing.

struct disable_action
   : maybe_nothing
{ ... };

`enable_action`

Parses the rule it is attached to with actions enabled:
Changes the current apply_mode to apply_mode::enabled.
Non-intrusive action equivalent of the enable rule.
Included via include/tao/pegtl/action/enable_action.hpp.
This action implements only a match() function and therefore:
Publicly derives from maybe_nothing.

struct enable_action
   : maybe_nothing
{ ... };

`limit_consume< N >`

Parses the rule it is attached to with the input limited to contain at most the next N objects.
Throws an exception when the rule consumes all N input objects (unless there are no more input objects).
Requires an input that implements private_set_end() like the view_input.
Included via include/tao/pegtl/action/limit_consume.hpp.
This action implements only a match() function and therefore:
Publicly derives from maybe_nothing.
Similar to check_consume, but limit_consume limits by modifying the input before matching.

 template< std::size_t Maximum >
 struct limit_consume
    : maybe_nothing
 { ... };

`match_typed_state< T >`

Parses the rule it is attached to with only the state of type T.
Included via include/tao/pegtl/action/match_typed_state.hpp.
This action implements only a match() function and therefore:
Publicly derives from maybe_nothing.
Related to the control class apply_typed_state.

template< typename T >
struct match_typed_state
   : maybe_nothing
{ ... };

`maybe_nothing`

A type alias for tao::pegtl::nothing< void >.
Included via include/tao/pegtl/nothing.hpp or include/tao/pegtl.hpp.

This type (alias) serves as a tag type in two strongly related roles. When my_action< void > has tao::pegtl::nothing< void > aka. maybe_nothing as public base class then the PEGTL will static_assert the presence of a callable apply() or apply0() function for all action class template specializations that do not also have maybe_nothing as public base class.

using maybe_nothing = nothing< void >;

`nothing< R >`

A "do nothing" action, defined as an empty class template.
Included via include/tao/pegtl/nothing.hpp or include/tao/pegtl.hpp.
The default action for parse() and parse_nested().

template< typename Rule >
struct nothing
{};

It is recommended, though not required, to use nothing as base class for the default case of custom action templates. This enables the static assert explained with maybe_nothing.

template< typename Rule >
struct my_action
   : nothing< Rule >
{};

// ... (partial) specialisations of my_action ...

`require_apply`

An empty tag class related to actions, not an action itself.
Included via include/tao/pegtl/action/require_apply.hpp.

When an action (specialization for a rule) has require_apply as public base class the PEGTL statically asserts the presence of a callable apply() function in the action. This check is performed independent of any presence or absence of maybe_nothing.

struct require_apply
{};

`require_apply0`

An empty tag class related to actions, not an action itself.
Included via include/tao/pegtl/action/require_apply0.hpp.

When an action (specialization for a rule) has require_apply0 as public base class the PEGTL statically asserts the presence of a callable apply0() function in the action. This check is performed independent of any presence or absence of maybe_nothing.

struct require_apply0
{};

Index

add_guard ^(actions)
add_state ^(actions)
change_action ^(actions)
change_action_and_state ^(actions)
change_action_and_states ^(actions)
change_control ^(actions)
change_rule ^(actions)
change_state ^(actions)
change_states ^(actions)
check_consume ^(actions)
check_depth ^(actions)
control_action ^(actions)
disable_action ^(actions)
enable_action ^(actions)
limit_consume ^(actions)
match_typed_state ^(actions)
maybe_nothing ^(actions)
nothing ^(actions)
require_apply ^(actions)
require_apply0 ^(actions)

This page is part of the PEGTL and its documentation.

Copyright (c) 2014-2026 Dr. Colin Hirsch and Daniel Frey
Distributed under the Boost Software License, Version 1.0
See accompanying file LICENSE_1_0.txt or copy at https://www.boost.org/LICENSE_1_0.txt