The Context Object

Boost , ,

The Context Object

Введение
Заголовок «wave/context.hpp»
Общественные типы
Параметры шаблона
Функции члена

Introduction

boost::wave::context<>object — основной видимый пользователем объект. Библиотека. Он существует для генерации пары итераторов, которые, будучи исключены, возвращают предварительно обработанные токены. Кроме того, он используется для управления другими аспектами предварительной обработки, такими как:

 включают пути поиска, которые определяют, где искать файлы, которые должны быть включены с#include <...>и#include ..директивы
 which macros to predefine and which of the predefined macros to undefine
 several other options as for instance to control, whether to enable several extensions to the C++ Standard (as for instance variadics and placemarkers) or not.[ORIG_END] -->

Header wave/cpp_context.hpp synopsis

namespace boost {
namespace wave { 
 
    struct this_type {};

    template <
        typename Iterator, typename LexIterator, 
        typename InputPolicy, typename ContextPolicy,
        typename Derived = this_type
    > 
    class context : public InputPolicy 
    {
        typedef <unspecified> token_sequence_type;

    public: 

        typedef pp_iterator<context> iterator_type; 
        typedef Token token_type;
        typedef typename token_type::position_type position_type;
        typedef std::list<token_type> token_sequence_type;

    // constructor
        context(Iterator const &first_, 
            Iterator const &last_, 
            char const *fname = "<Unknown>",
            ContextPolicy const& ctx_policy = ContextPolicy())

    // iterator interface
        iterator_type begin() const;
        iterator_type begin(Iterator const &first, 
            Iterator const &last) const;
        iterator_type end() const;

    // maintain include paths
        bool add_include_path(char const *path_);
        bool add_sysinclude_path(char const *path_);
        void set_sysinclude_delimiter();
 
        size_t get_iteration_depth() const;

    // maintain defined macros
        template <typename String>
        bool add_macro_definition(String macrostring, 
            bool is_predefined = false);
        template <typename String>
        bool add_macro_definition(StringT const &name, 
            position_type const& pos, bool has_params, 
            std::vector<token_type> &parameters, 
            token_sequence_type &definition, 
            bool is_predefined = false)

        template <typename String>
        bool is_defined_macro(String const &name) const;
        template <typename String>
        bool remove_macro_definition(String const &name, 
            bool even_predefined = false);
        void reset_macro_definitions();
        template <typename String>
        bool get_macro_definition(
            String const &name, bool &is_function_style, 
            bool &is_predefined, position_type &pos, 
            std::vector<token_type> &parameters, 
            token_sequence_type &definition) const; 

        typedef <unspecified> macromap_type;
        typedef typename macromap_type::name_iterator name_iterator;
        typedef typename macromap_type::const_name_iterator const_name_iterator;

        name_iterator macro_names_begin();
        name_iterator macro_names_end();
        const_name_iterator macro_names_begin() const;
        const_name_iterator macro_names_end() const;

    // other options
        void set_language(language_support enable);
        language_support get_language() const;

        void set_max_include_nesting_depth(std::size_t new_depth);
        size_t get_max_include_nesting_depth() const;

    // get the Wave version information 
        static std::string get_version();
        static std::string get_version_string();
    };

} // namespace wave
} // namespace boost

Template parameters

Объектboost::wave::contextимеет три шаблонных параметра для определения конкретного поведения его работы. Следующая таблица описывает их более подробно.

Для получения дополнительной информации о типе лексера, пожалуйста, обратитесь кИнтерфейс Лексера.

Если параметр шаблонаInputPolicyопущен, то используется шаблонboost::wave::iteration_context_policies::load_file_to_string. Для получения дополнительной информации о политике ввода, пожалуйста, обратитесь к темеПолитика ввода.

Если параметр шаблона ContextPolicy опущен, используется усилитель::wave::context_policies::eat_whitespace, реализующий определенные базовые крючки предварительной обработки, необходимые для нормального (по умолчанию) исполнения. Для получения дополнительной информации о политике контекста, пожалуйста, обратитесь к темеКонтекстная политика.

Public Typedefs

Шаблонboost::wave::contextопределяет следующие публичные типдефы, которые могут быть полезны при использовании этого класса:

Member functions

Конструктор

    context(Iterator const &first, 
        Iterator const &last, char const *filename, 
        ContextPolicy const& ctx_policy);

Конструирует объект контекста поверх входного потока, заданного парой вспомогательных итераторов[первый,  последний]. Итераторы должны быть как минимумforward_iteratorтипа итераторов. Параметр имени файла предоставляется только в информационных целях. Эта строка используется для указания позиций токенов внутри входного потока, она не проверяется против файловой системы. Если параметр имени файла не указан, он по умолчанию соответствует"". Если параметр ctx_policy не поставляется, он по умолчанию подается на объект ContextPolicy.

Кроме того, таблица макросимволов заполнена предопределенными макросами, и текущий справочный каталог настроен на путь заданного имени файла. Если это имя файла не ссылается на действительный элемент файловой системы, текущий справочный каталог устанавливается в текущий системный каталог. (Текущий справочный каталог — это путь файловой системы, который используется в качестве целевого каталога при обработке директив#include ..»).

Iterator interface

Пара итераторов, возвращаемых контекстом::beginи контекстом::end, является основным интерфейсом для доступа к предварительно обработанным токенам из движка препроцессора. При итерации по заданному диапазону итераторов[начало,  конец]возвращаются предварительно обработанные токены C++, которые генерируются на лету из основного входного потока. Возвращенные итераторы концептуально относятся к типуforward_iterator.

начать

    iterator_type begin();
    iterator_type begin(Iterator const &first,
         Iterator const &last, );

Инициализирует и возвращает стартовый итератор для предварительно обработанного потока токенов. Пара итераторов, задаваемая парами [первый, последний], определяет входную последовательность для предварительного процесса. Первая версия этой функции использует поток ввода, указанный конструктором.  

конец

    iterator_type end() const;

Инициализирует и возвращает конец итератора потока для сравнения с для обнаружения конца предварительно обработанного потока токенов.

Maintain include paths

БиблиотекаWaveподдерживает два отдельных пути поиска для включения файлов. Путь поиска для пользователя включает файлы, а путь поиска для системы включает файлы. Любые каталоги, указанные с функциейadd_include_path()перед функциейset_sysinclude_delimiter()называется поиском только для случая#include ..»директив, они не ищутся#include директив. Т.е. эти каталоги добавляются к пользователю и включают в себя путь поиска.

Если дополнительные каталоги указаны с функциейadd_include_path()после вызова функцииset_sysinclude_delimiter(), эти каталоги ищутся для всех директив#include. То есть эти каталоги добавляются в систему и включают в себя путь поиска.

Кроме того, вызов функцииset_sysinclude_delimiter()препятствует использованию текущего справочного каталога в качестве первого каталога поиска для#include ..»директив. Поэтому текущий справочник ищется только в том случае, если он запрашивается явно с вызовом функцииadd_include_path(".) 131.

Каллиг обе функции,set_sysinclude_delimiter()иadd_include_path().позволяет точно контролировать, какие каталоги ищутся до текущего и какие после.

Эти функции моделируются после поведения командной строки, реализованного популярным компилятором gcc.

add_include_path

    bool add_include_path(char const *path);

Добавление данного пути файловой системы к пользователю включает в себя пути поиска. После вызоваset_sysinclude_delimiter()эта функция добавляет заданный путь файловой системы к системе, включающей в себя пути поиска. Обратите внимание, что данный путь проверяется против файловой системы.

Если данная строка пути не образует имя действительного элемента каталога файловой системы, функция возвращаетложное. Если указанный путь был успешно добавлен к рассматриваемым путям поиска, функция возвращаетистинное.

add_sysinclude_path

    bool add_sysinclude_path(char const *path);

Добавление данного пути файловой системы к системе включает в себя пути поиска. Эта функция, работающая в системе, включает в себя путь поиска независимо от режима работыadd_include_path(). Обратите внимание, что данный путь проверяется против файловой системы.

Если данная строка пути не образует имя действительного элемента каталога файловой системы, функция возвращаетложное. Если данный путь был успешно добавлен в систему, включающую в себя пути поиска, функция возвращаетистинное.

set_sysinclude_delimiter

    void set_sysinclude_delimiter();

Переключает режим, как работает функцияadd_include_path(). По умолчанию данный путь файловой системы добавляется к пользователю, включая пути поиска. После вызова этой функции последующий вызов вadd_include_path()добавляет заданный путь файловой системы к системе, включающей в себя пути поиска. Кроме того, он препятствует использованию текущего справочного каталога в качестве первого каталога поиска для#include ..»директив.

get_iteration_depth

    size_t get_iteration_depth() const;

Возвращает фактическую глубину итерации, т.е. текущее количество уровней, которые должны быть выведены из контекста итерации, прежде чем будет достигнут основной (самый верхний) контекст итерации.

Maintain defined macros

add_macro_definition

    bool add_macro_definition(
        std::string macrostring, bool is_predefined); 

В таблицу макросимволов добавлено новое макроопределение. Параметрмакрострундолжен содержать макрос для определения в формате командной строки, то есть что-то вродеMACRO(x)=определение. В следующей таблице этот формат описан более подробно. Параметрявляется_предопределеннымдолжен быть истинным при определении предопределенных макросов, то есть макросов, которые не являются неопределяемыми с помощью директивы#undefизнутри предварительно обработанного входного потока. Если этот параметр не указан, он по умолчаниюложный.

Summary of possible formats for defining macros
MACRO	define MACRO as 1
MACRO=	define MACRO as nothing (empty)
MACRO=definition	define MACRO as definition
MACRO(x)	define MACRO(x) as 1
MACRO(x)=	define MACRO(x) as nothing (empty)
MACRO(x)=definition	define MACRO(x) as definition

Функция возвращаетложную, если макроопределение уже определено и новое определение эквивалентно существующему, оно возвращается истинное, если новый макроопределение было успешно добавлено в таблицу макросимволов.

Если данное макроопределение напоминает переопределение и новый макрос не идентичен уже определенному макросу (в смысле, определенном стандартом C++), функция бросает соответствующеепрепроцесс_исключение.

is_defined_macro

    template <typename String>
    bool is_defined_macro(String const &name) const; 

Возвращается, если определен макрос с заданнымименем, т.е. если он содержится в таблице макросимволов.

get_macro_definition

    template <typename String>
    bool get_macro_definition(
        String const &name, bool &is_function_style, 
        bool &is_predefined, position_type &pos, 
        std::vector<token_type> &parameters, 
        token_sequence_type &definition) const; 

Позволяет получить всю информацию, известную в отношении макроопределения. В имениуказывается имя макроса, для которого информация должна быть возвращена. Параметры— это_function_styleи— это_predefinedreturn, независимо от того, был ли макрос определен как макрос стиля функции или как предварительно заданный макрос resp. Параметрposбудет содержать положение, в котором был определен макрос. Параметрпараметровбудет содержать имена параметров, с которыми был определен макрос, а определение параметрабудет содержать последовательность токенов для определения (макротело).

Функция возвращаетистинноето, что макрос был определен, и запрашиваемая информация была успешно извлечена,ложноев противном случае.

удалить_macro_definition

    template <typename String>
    bool remove_macro_definition(
        String const &name, bool even_predefined); 

Удаляет определение макроса с заданнымименемиз таблицы макросимволов. Эта операция эквивалентна директиве#undefс этимименем, выполненным из входного потока. Если параметрeven_predefinedявляетсяистинным, то макрос удаляется из таблицы макросимволов даже, если он определен как предопределенный макрос.

Обратите внимание, что следующие макросыненеопределимы в любом случае:__FILE__,__LINE__,__DATE__,__TIME__,__cplusplus,__STDC__. Если параметрдаже_предопределенныйне указан, он по умолчанию не соответствуетложному.

Функция возвращаетложную, если макрос не был определен и возвращаетистиннуюиначе.

Если макрос для удаления не может быть неопределенным (это предопределенный макрос и параметрeven_predefinedустановлен наfalseили это один из упомянутых не неопределяемых макросов выше), функция бросаетpreprocess_ Exception.

reset_macro_definitions

    void reset_macro_definitions(); 

Сбрасывает таблицу макросимволов в исходное состояние, т.е. не определяет все определяемые пользователем макросы и вставляет внутренние предопределенные макросы, как описаноздесь.

macro_names_begin, macro_names_end

    name_iterator macro_names_begin();
    name_iterator macro_names_end();
    const_name_iterator macro_names_begin() const;
    const_name_iterator macro_names_end() const;

Функцииmacro_names_beginиmacro_names_endвозвращают итераторы, позволяющие повторять имена всех определенных макросов.

Get Version information

get_version

    static std::string get_version(); 

возвращает строку, содержащую ток Волновая версия, отформатированная как0xvvrsbbbb(это струнное представление эквивалентного шестнадцатеричного числа), где'vv'является номером версии,'r'номером выпуска,'s'номером субрелиза и'bbbb'номером сборки. Возможное значение возврата выглядит как0x00910454. Возвращенное значение является таким же, как вставлено в предварительно обработанный поток токенов, когда задан макрос. __WAVE_VERSION__расширяется.

get_version_str

    static std::string get_version_str(); 

возвращает строку, содержащую ток Волновая версия отформатирована как«v.rr.ss.bbbb», где«v»является номером версии,«rr»номером выпуска,«ss»номером субрелиза и«bbbb»номером сборки. Возможное значение возврата выглядит как"0.9.1.454". Возвращенное значение такое же, как оно будет вставлено в предварительно обработанный поток токенов, когда предопределенный макрос__WAVE_VERSION_STR__расширяется.

Control extended options

set_language
get_language

    void set_language(language_support language, 
        bool reset_macros = true);
    language_support get_language() const;

Эта функция позволяет задать языковой режим, в которомБиблиотекадолжна работать. Возможные языковые режимы определяются перечисленным типомlanguage_support:

    enum language_support {
    // support flags for C++98
        support_normal = 0x01,
        support_cpp = support_normal,

    // support flags for C99
        support_option_long_long = 0x02,
        support_option_variadics = 0x04,
        support_c99 = support_option_variadics | support_option_long_long | 0x08,

    // the mask for the main language settings
        support_option_mask = 0xFFB0,

    // additional fine tuning of the general behavior
        support_option_emit_contline = 0x0040,
        support_option_insert_whitespace = 0x0080,
        support_option_preserve_comments = 0x0100,
        support_option_no_character_validation = 0x0200,
        support_option_convert_trigraphs = 0x0400,
        support_option_single_line = 0x0800,
        support_option_prefer_pp_numbers = 0x1000,
        support_option_emit_line_directives = 0x2000,
        support_option_include_guard_detection = 0x4000,
        support_option_emit_pragma_directives = 0x8000
    };

При использовании сsupport_option_variadicsподдержка вариадиков, маркеров места и оператора _Pragma()включена в обычном режиме C++. При использовании сsupport_option_long_longподдержка длинных суффиксов включена в режиме C++.

support_c99включает поддержку языка C99, которая по умолчанию позволяет использовать вариадики, маркеры места, оператор _Pragmaи длинные длинные суффиксы. Кроме того, он отключает специфические токены C++, такие как'->*','.*','::'и т.д.

Значенияsupport_option_...должны использоваться в сочетании с основными языковыми настройкамиsupport_normalиsupport_c99.

• Еслиsupport_option_insert_whitespaceФлаг установлен, theВолнабиблиотека  вставляет дополнительное белое пространство между токенами, где сцепленное представление строк двух токенов образует другой действительный токен C++. Это очень важно, чтобы избежать неправильной интерпретации сгенерированного вывода, если он будет обработан компилятором C++.  
• Еслиsupport_option_preserve_commentsустановлен флаг, библиотекаWaveсохраняет почти все комментарии в исходном коде. Не сохранились только те комментарии, которые содержатся внутри макроопределений. Если этот флаг не установлен, все комментарии заменяются одним пространством.
• Еслиsupport_option_no_character_validationфлаг установлен,волнабиблиотека не валидирует универсальные буквы символов (данные в виде'u1234'или'U12345678'), чтобы быть в допустимом диапазоне значений. Этот флаг используется только для внутренних целей в рамках тестирования и редко используется пользователем библиотеки.
• Если флагsupport_option_convert_trigraphsустановлен,Библиотека волнзаменяет все события символов триграфа их нетриграфической последовательностью символов (т.е.'??=').заменяется'#'и т.д. По умолчанию замена не производится.
• Если флагsupport_option_single_lineустановлен,Волноваябиблиотека теперь будет повторять ошибку, если последняя строка обработанного ввода не будет завершена новой строкой. Этот флаг используется только для внутренних целей в рамках тестирования и редко используется пользователем библиотеки.
• Если флагsupport_option_prefer_pp_numbersустановлен, тоВолновойбиблиотеке предписывается правильно идентифицировать pp-числа во входном потоке. Они распознаются в «нормальных» токенах, прежде чем они вернутся в приложение вызова. Флаг устанавливается по умолчанию и используется только для внутренних целей и редко сбрасывается пользователем библиотеки.
• Если флагsupport_option_emit_line_directivesустановлен, тоВолноваябиблиотека будет издаватьдирективы #lineв генерируемом потоке токенов, если это необходимо. Этот флаг устанавливается по умолчанию, чтобы библиотека не могла генерировать директивы#line.
• Если флагsupport_option_include_guard_detectionустановлен,В библиотеке Waveбудет предпринята попытка автоматической идентификации включающих в себя стражи при обработке включенного файла. Файлы, содержащие охрану, обрабатываются так, как если бы они содержали #прагму один раз, то есть эти файлы не будут открываться дважды, даже если они указаны во втором#включаютзаявлении.

В ходе этого процесса библиотека распознает две формы охранников:

 #ifndef INCLUDE_GUARD_MACRO
 #define INCLUDE_GUARD_MACRO
 ...
 #endif
or
 #if !defined(INCLUDE_GUARD_MACRO)
 #define INCLUDE_GUARD_MACRO
 ...
 #endif

Обратите внимание, что скобки во второй форме являются необязательными (т.е.). Определение INCLUDE_GUARD_MACROтакже будет работать. Код позволяет распознавать любые токены whitespace, newline и single '#' до#if/#ifndefи после финального#endifдля включения сторожа.

Этот флаг включен по умолчанию, поэтому, если вы не хотите, чтобы библиотека автоматически переконфигурировалась, вам нужно будет явно сбросить его.

• Если флагsupport_option_emit_pragma_directivesустановлен, тоВолноваябиблиотека издаст на выход все неизвестные#прагмадирективы. Этот вариант порта будет признан только в том случае, еслиBOOST_WAVE_EMIT_PRAGMA_DIRECTIVESопределяется во время компиляции до значения, не равного нулю (см.здесьдля получения дополнительной информации).
• Если флагsupport_option_emit_contlinesустановлен, тоВолноваябиблиотека будет излучать все обратные линии, встречающиеся во входе. Он будет генерировать токенT_CONTLINEдля каждой из этих последовательностей символов. Обратите внимание, что эта опция поддерживается только пользовательским модулем SLex lexer. См. пример cpp_tokens для рабочего примера.

Если параметрreset_macrosсоответствует действительности, функцияset_languageвнутренне сбрасывает список определенных макросов, поэтому, пожалуйста, будьте осторожны, чтобы не называть его после того, как вы уже определили свои собственные макросы.

set_max_include_nesting_depth
get_max_include_nesting_depth

    void set_max_include_nesting_depth(size_t new_depth); 
    size_t get_max_include_nesting_depth() const;

Эти функции позволяют установить или получить максимально возможную глубину вложения файлов, поддерживаемую. Библиотека. Начальное значение для этого определяется константой предварительной обработкиWAVE_MAX_INCLUDE_LEVEL_DEPTH(см.здесь).

Copyright © 2003-2011 Hartmut Kaiser

Distributed under the Boost Software License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)

Last updated: Saturday, August 6, 2011 20:22

Статья The Context Object раздела может быть полезна для разработчиков на c++ и boost.

:: Главная :: ::