Модули

В разработке больших программных систем грамотная организация кода — это не просто рекомендация, а необходимость. По мере роста проекта навигация по нему неизбежно усложняется, и без продуманной структуры вы быстро столкнётесь с трудностями.

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

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

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

Практически любой нетривиальный проект требует разбиения на модули. По мере расширения функциональности логично выделять отдельные компоненты в самостоятельные модули. Со временем некоторые из них могут превратиться во внешние зависимости.

Главное преимущество модульного подхода — чёткое разделение интерфейса и реализации. Когда код организован в модули, другие части программы взаимодействуют с ними только через публичный интерфейс, не вникая во внутренние детали работы. Такой принцип инкапсуляции позволяет разработчикам:

• Упростить мыслительную нагрузку, фокусируясь только на текущей задаче
• Уменьшить связность между компонентами системы
• Повысить надёжность за счёт чётких контрактов между модулями

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

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

В языке Zig концепция модулей предельно проста, что соответствует основным принципам, которым следует сообщество разработчиков при его создании.

Модули в Zig

Любой файл с расширение .zig является модулем в языке Zig. В языке нет каких то специальных механизмов или ключевых слов для объявления модулей. Вся работа с модулями строится всего на трех ключевых словах - pub, import и usingnamespace. При этом для создания иерархии модулей используется иерархия папок и файлов на уровне файловой системы. Каждый файл на диске с расширением .zig может быть импортирован в другой файл с помощью ключевого слова import. При этом, при импорте файла компилятор превратит содержимое импортируемого файла в структуру с именем, равным имени файла без расширения. Например, если вы импортируете файл math.zig, то компилятор создаст структуру с содержимым модуля. Давайте расмотрим пример простого импорта:

// Файл math.zig

const MAX = 100;

pub fn add(a: i32, b: i32) i32 {
    return a + b;
}

// Файл main.zig
const math = @import("math.zig");

pub fn main() void {
    math.add(2, 3);
}

В этом примере мы импортируем модуль math.zig в файл main.zig. Компилятор создаст структуру с именем math, которая будет содержать все публичные функции и константы из файла math.zig. Мы можем использовать эти функции и константы в файле main.zig с помощью синтаксиса math.add(2, 3). Функция @import принимает всего один параметр, который может быть либо относительным или абсолютным путем к импортированному файлу, либо именем модуля. На текущий момент в Zig поддерживается три модуля, которые вы можете импортировать по имени - std, builtin и root:

• std: Данный модуль представляет из себе стандартную библиотеку языка Zig, которая содержит множество полезных функций и структур данных. Она включает в себя модули для работы с файлами, сетью, потоками, а также содержит множество полезных функций для работы с числами, строками и массивами. Мы неоднократно уже импортировали различные части стандартной библиотеки, например, модуль std.debug для вывода отладочной информации в консоль, модуль std.io для работы с файлами и потоками и модуль std.mem для работы с памятью.
• builtin: Данный модуль содержит различные переменные, которые могут быть полезны при компиляции вашего кода, такие как архитектура платформы, информация о процессоре, версия Zig и т.д.
• root: Данный модуль представляет из себе корневой модуль языка Zig, например если мы разрабатываем библиотеку, то импорт root вернет нам корневой модуль нашей библиотеки, если мы разрабатываем приложение, то импорт root вернет нам корневой модуль нашего приложения.

При импортировании нашего модуля мы задаем имя, которое будет использоваться для доступа к функциям и переменным в этом модуле. Например, если мы импортируем модуль math.zig и задаем имя math, то мы можем использовать функции и переменные из этого модуля с помощью синтаксиса math.add(2, 3).

Если имя файла импортируемого модуля состоит из нескольких слов, то принято разделять слова символом _, например my_module.zig.

Доступ к элементам модуля

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

// Файл user.zig

const Animal = struct {
    name: []u8,
};

// Фалй main.zig
const std = @import("std");
const user_module = @import("user.zig");

pub fn main() !void {
    const user = user_module.User{
        .name = "John Doe",
    };
    std.debug.print("User: {s}\n", .{user.name});

    const animal = user_module.Animal{
        .name = "Dog",
    };
    std.debug.print("Animal: {s}\n", .{animal.name});
}

Если мы попробуем скомпилировать нашу программу, то получим ошибку:

run
└─ run simple
   └─ install
      └─ install simple
         └─ zig build-exe simple Debug native 1 errors
src/main.zig:10:31: error: 'Animal' is not marked 'pub'
    const animal = user_module.Animal{
                   ~~~~~~~~~~~^~~~~~~

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

Публичное API библиотеки

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

Чтобы предоставить пользователям удобный и понятный публичный интерфейс, важно сгруппировать все экспортируемые элементы под одним именем. Это позволит использовать библиотеку максимально просто и удобно. Но как это сделать, если код разбит на несколько модулей?

В этом случае на помощь приходит функция usingnamespace, которая позволяет «включать» все объявления из одного пространства имен в другое. Это упрощает доступ к функциям, типам и другим сущностям, делая использование библиотеки более удобным. Синтаксис usingnamespace прост:

usingnamespace @import("std"); // Теперь все из std доступно в текущей области

Этот код делает все публичные объявления из стандартной библиотеки Zig доступными в текущей области видимости. Как же мы можем использовать эту функцию для создания собственного публичного интерфейса? Давайте рассмотрим пример простой библиотеки:

// Файл user.zig
const address = @import("address.zig");

pub const User = struct {
    name: []const u8,
    email: []const u8,
    age: u8,
    address: address.Address,
};

// Файл address.zig
pub const Address = struct {
    street: []const u8,
    city: []const u8,
    state: []const u8,
    zip: []const u8,
};

// Файл validation.zig
const std = @import("std");

const checks = struct {
    fn _isEmail(str: []const u8) bool {
        return std.mem.indexOf(u8, str, "@") != null;
    }
};

pub const Validation = struct {
    pub usingnamespace struct {
        pub const isEmail = checks._isEmail;
        pub const isNumber = std.ascii.isDigit;
    };
};

// Файл root.zig
const address = @import("address.zig");
const user = @import("user.zig");
const validation = @import("validation.zig");

pub usingnamespace address;
pub usingnamespace user;
pub usingnamespace validation.Validation;

Наша библиотека состоит из трёх файлов с различными функциями и структурами, а также корневого файла, через который экспортируется публичный интерфейс. В коде мы применили usingnamespace в двух местах: сначала в файле validation.zig, чтобы продемонстрировать разделение между приватной и публичной частями модуля, затем в файле root.zig для объединения и экспорта всего публичного API библиотеки. Такой подход к организации кода даёт несколько существенных преимуществ:

• Единая точка входа - весь API доступен через root.zig
• Изолированные модули - каждый файл отвечает за свою область
• Контролируемый экспорт - только нужные функции становятся публичными
• Прозрачное использование - клиенты работают с единым неймспейсом

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

Еще один из вариантов использования usingnamespace - это возможность расширения структур, используя “примеси”. Давайте предположим что у нас есть библиотека работы с векторами:

const Vector2 = struct {
    x: f32,
    y: f32,
};

const Vector3 = struct {
    usingnamespace Vector2;
    z: f32,
};

В данном примере мы пасширяем структуру Vector3 полями из нашего Vector2 и добавляем новое поле z. Это позволяет не дублировать код и упростить поддержку и расширение кода. Еще один из примеров использования usingnamespace - это использования его с возможностями генерации кода через comptime. Давайте рассмотрим пример условного расширения структуры:

const std = @import("std");

pub fn Builder(comptime extend: bool) type {
    return struct {
        pub fn simple() void {
            std.debug.print("Simple api\n", .{});
        }

        pub usingnamespace if (extend)
            struct {
                pub fn extended() void {
                    std.debug.print("Extended api\n", .{});
                }
            }
        else
            struct {};
    };
}

pub fn main() !void {
    const builder = Builder(true);

    builder.simple();
    if (@hasDecl(builder, "extended")) {
        builder.extended();
    }
}

Если мы запустим наш пример, то он выведет:

Simple api
Extended api

Но если мы изменим создание экземпляра Builder на Builder(false), то наш код уже выведет только Simple api. Таким образом используя usingnamespace и возможности генерации кода через comptime, мы можем условно расширять структуры и функциональность в зависимости от условий компиляции.

Использование usingnamespace — это мощный инструмент в Zig для управления областью видимости и создания выразительных API. При правильном использовании он помогает уменьшить шаблонный код и улучшить организацию кода. Однако важно применять его осознанно, чтобы не допустить неясностей в происхождении идентификаторов.