Включи как — функция включения файлов в конфигурации¶

Включи как (англ. include as) — конструкция в языках разметки и конфигурационных форматах, предназначенная для включения содержимого одного файла в другой с указанием альтернативного имени, типа или обработки подключаемого фрагмента. Синтаксис «include as» встречается в системах сборки, шаблонизаторах, форматах конфигураций и системах документации, где требуется не просто подставить текст, а пометить его происхождение или назначение.

¶Общие принципы

Конструкции включения в конфигурациях принято делить на две группы:

• Простое включение (include, import) — подстановка содержимого файла без дополнительных указаний.
• Включение с указанием (include as, import as) — подстановка с присвоением имени, пространства имён, типа или иной метки.

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

¶Синтаксис в разных системах

¶Языки разметки и документация

В формате reStructuredText (используется в Sphinx и документации Python) директива .. include:: допускает параметр :name: и :encoding:, а также :parser: — указание парсера для подключаемого файла. В Markdown расширения (например, markdown-include) поддерживают синтаксис вида <!-- include: файл.md -->, иногда с указанием заголовка уровня.

В DocBook и DocBook-подобных форматах включение реализовано через xi:include (XInclude) с атрибутами parse, href и xpointer, что позволяет подключать фрагменты XML-документов с указанием обработки.

¶Языки программирования и конфигурации

В языке Rust директива include! позволяет включить файл на этапе компиляции; аналог include_str! и include_bytes! подключает содержимое как строку или массив байтов — здесь «as» реализовано через присваивание результата переменной.

В конфигурациях Ansible директива include_tasks и import_tasks подключают файлы задач; в YAML-конфигурациях Kubernetes конструкция import в Kustomize позволяет подключать базовые манифесты с переопределением имён ресурсов.

В системе сборки Bazel директива load загружает символы из .bzl-файлов с указанием имён, что по смыслу соответствует «include as».

¶Шаблонизаторы

В Jinja2 (Python) конструкция {% include 'файл.html' with context %} подключает шаблон с передачей контекста; в Twig (PHP) — {% include 'шаблон.html' with { 'переменная': значение } %}. В обоих случаях содержимое подключается под именем шаблона, а не как безымянный фрагмент.

¶Примеры использования

Типичный пример в reStructuredText:

`` .. include:: common/header.rst :parser: myst_parser.sphinx_ :encoding: utf-8 ``

Пример в Ansible (YAML):

```yaml

• name: Подключить общие задачи

ansible.builtin.include_tasks: file: common/setup.yml name: common_setup ```

Пример в Rust:

``rust let шаблон = include_str!("шаблон.txt"); ``

¶Области применения

• Документация Sphinx — подключение общих разделов (лицензии, предупреждения) в несколько документов.
• Сборка программного обеспечения — включение общих правил, макросов, заголовочных файлов.
• Конфигурации инфраструктуры — переиспользование общих манифестов и задач.
• Шаблоны веб-страниц — подключение общих фрагментов (шапка, подвал) с указанием контекста.

¶Отличие от простого включения

Простое включение (include) подразумевает, что содержимое подключается «как есть», без дополнительной обработки. Включение с указанием (include as) добавляет слой идентификации: файл может быть подключён под разными именами, с разной кодировкой, разным парсером или в разном контексте. Это критично при многократном использовании одного источника в разных проектах или разделах документации.

¶См. также

• Include (программирование)
• XInclude
• Jinja2
• Ansible
• reStructuredText

¶Источники

• Документация Sphinx по директиве include
• Документация Ansible по include_tasks и import_tasks
• Документация Rust по макросам include!, include_str!
• Спецификация XInclude (W3C)
• Документация Kustomize по конструкции import