Модуль «фс»

🔌 Подключение модуля

Для использования функций модуля необходимо получить ссылку на глобальный объект фс:

₽фс = фс;

После этого все методы доступны через переменную ₽фс.

🛡️ Настройка безопасности

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

установитьКорень(путь)

Устанавливает корневую директорию для безопасного режима.

Возвращает: ничего.

режимБезопасности(включить)

Включает или выключает безопасный режим.

Возвращает: ничего.

корневаяПапка()

Возвращает текущую корневую директорию (пустую строку, если не установлена).

Возвращает: строка — путь к корневой папке.

безопасность()

Возвращает текущее состояние безопасного режима.

Возвращает: логическое значение — истина, если безопасный режим включён.

🧭 Утилиты для работы с путями

текущийФайл()

Возвращает путь к текущему исполняемому скрипту (устанавливается интерпретатором).

Возвращает: строка — путь к файлу скрипта.

текущаяПапка()

Возвращает директорию, в которой находится текущий скрипт.

Возвращает: строка — путь к папке скрипта.

путь(часть1, часть2, ...)

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

Параметры: произвольное количество строк.

Возвращает: строка — объединённый путь.

₽полныйПуть = ₽фс.путь(₽фс.текущаяПапка(), "data", "file.txt");

📖 Чтение файлов

прочитатьФайл(путь, кодировка, callback) асинхронный

Читает содержимое файла асинхронно. Результат передаётся в колбэк.

Возвращает: ничего.

прочитатьФайлСинх(путь, кодировка) синхронный

Блокирует выполнение до завершения чтения.

Возвращает: строка — содержимое файла; при ошибке — null.

✍️ Запись файлов

записатьФайл(путь, данные, callback) асинхронный

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

Возвращает: ничего.

записатьФайлСинх(путь, данные) синхронный

Блокирует выполнение до завершения записи.

Возвращает: логическое значение — истина при успехе, ложь при ошибке.

📂 Работа с директориями

прочитатьПапку(путь, callback) асинхронный

Получает список содержимого директории асинхронно.

Возвращает: ничего.

прочитатьПапкуСинх(путь) синхронный

Блокирующий вариант.

Возвращает: массив строк — имена элементов в папке; при ошибке — null.

создатьПапку(путь, callback) асинхронный

Создаёт директорию (включая все промежуточные) асинхронно.

Возвращает: ничего.

создатьПапкуСинх(путь) синхронный

Блокирующий вариант.

Возвращает: логическое значение — истина при успехе, ложь при ошибке.

удалитьПапку(путь, callback) асинхронный

Удаляет пустую директорию асинхронно.

Возвращает: ничего.

удалитьПапкуСинх(путь) синхронный

Блокирующий вариант.

Возвращает: логическое значение — истина при успехе, ложь при ошибке.

🔍 Проверка существования

существует(путь, callback) асинхронный

Проверяет, существует ли файл или папка по указанному пути.

Возвращает: ничего.

существуетСинх(путь) синхронный

Блокирующий вариант.

Возвращает: логическое значение.

🗑️ Удаление файлов

удалить(путь, callback) асинхронный

Удаляет файл асинхронно.

Возвращает: ничего.

удалитьСинх(путь) синхронный

Блокирующий вариант.

Возвращает: логическое значение — истина при успехе, ложь при ошибке.

📊 Статистика файла

статистика(путь, callback) асинхронный

Возвращает информацию о файле или папке.

Возвращает: ничего.

статистикаСинх(путь) синхронный

Блокирующий вариант.

Возвращает: объект с теми же полями, что и в асинхронном варианте, или null при ошибке.

Объект статистики содержит следующие поля:

• size (число) — размер в байтах
• isFile (логическое) — является ли файлом
• isDir (логическое) — является ли папкой
• isSymLink (логическое) — является ли символической ссылкой
• mtime (число) — время последней модификации (timestamp)
• ctime (число) — время создания (timestamp)
• atime (число) — время последнего доступа (timestamp)

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

Синхронное чтение и запись

₽фс = фс;

// Запись
₽результат = ₽фс.записатьФайлСинх("example.txt", "Hello, world!");
если (₽результат) {
    вывод("Файл записан");
} иначе {
    вывод("Ошибка записи");
}

// Чтение
₽содержимое = ₽фс.прочитатьФайлСинх("example.txt", "utf8");
если (₽содержимое != 0) {
    вывод("Содержимое: " + ₽содержимое);
} иначе {
    вывод("Файл не найден");
}

Асинхронное чтение с колбэком

₽фс.прочитатьФайл("data.txt", "utf8", функция(₽текст) {
    если (₽текст != 0) {
        вывод("Прочитано: " + ₽текст);
    } иначе {
        вывод("Ошибка чтения");
    }
});

Работа с папками

// Создать папку
₽фс.создатьПапкуСинх("./backup");

// Получить список файлов
₽список = ₽фс.прочитатьПапкуСинх(".");
для каждого (₽элемент из ₽список) {
    вывод(₽элемент);
}

Использование безопасного режима

// Устанавливаем корень
₽фс.установитьКорень("/home/user/sandbox");
₽фс.режимБезопасности(истина);

// Теперь все операции ограничены этой папкой
₽данные = ₽фс.прочитатьФайлСинх("config.txt", "utf8"); // разрешено
₽данные = ₽фс.прочитатьФайлСинх("/etc/passwd", "utf8"); // будет ошибка доступа

⚠️ Особенности

• Асинхронные методы используют внутренний пул потоков (QtConcurrent) и не блокируют выполнение скрипта. Результат возвращается через колбэк. При использовании с волокнами (fiber) колбэки вызываются в контексте волокна.
• Синхронные методы блокируют выполнение до завершения операции, что может быть удобно для простых сценариев.
• Кодировка по умолчанию — utf8. Для системной кодировки используйте "local".
• Безопасный режим проверяет, что все пути находятся внутри корневой директории, используя канонические пути. Если корень не установлен, ограничения не применяются.
• Ошибки в синхронных методах обычно возвращают null или ложь. В асинхронных — колбэк получает null или ложь в случае ошибки. Исключения могут быть выброшены при нарушении безопасности или при неверных аргументах.