FileWatcher

Библиотека для отслеживания изменений в файловой системе на языке OneScript.

Описание

FileWatcher позволяет отслеживать изменения файлов в указанном каталоге, включая:

• Изменение содержимого файлов (через сравнение MD5 хешей)
• Добавление новых файлов
• Удаление файлов
• Изменение структуры каталогов

Библиотека работает только в асинхронном (фоновом) режиме через фоновые задания OneScript.

Доступны два режима работы с изменениями:

• Обычный режим (по умолчанию): все изменения передаются единым массивом
• Режим детализации: изменения группируются по типам (создание, изменение, удаление)

Установка

opm install filewatcher

Использование

Базовый пример

#Использовать filewatcher

// Обработчик изменений
Процедура ОбработатьИзменения(СтруктураИзменена, ИзмененныеФайлы, ТекущаяСтруктура)
    
    Если СтруктураИзменена Тогда
        Сообщить("Структура каталога изменена");
    КонецЕсли;
    
    Для Каждого Файл Из ИзмененныеФайлы Цикл
        Сообщить("Файл изменен: " + Файл.ПолноеИмя);
    КонецЦикла;

КонецПроцедуры

// Создаем экземпляр сканера
Сканер = Новый СканерИзмененийФайлов("/путь/к/каталогу", 1000);

// Настраиваем фильтры
Сканер.УстановитьМаску("*.os")
    .ДобавитьКаталогИсключения("/подкаталог");

// Запускаем мониторинг в фоновом режиме
Сканер.Запустить(Новый Действие(ЭтотОбъект, "ОбработатьИзменения"));

Режим мониторинга производительности

#Использовать filewatcher

Сканер = Новый СканерИзмененийФайлов("/путь/к/каталогу", 1000);
Сканер.РежимМониторингаСканирования(); // Включает вывод времени сканирования
Сканер.Запустить(Обработчик);

Режим детализации изменений

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

#Использовать filewatcher

// Обработчик для режима детализации
Процедура ОбработатьДетализированныеИзменения(СтруктураИзменена, ДетализацияИзменений, ТекущаяСтруктура)
    
    Если СтруктураИзменена Тогда
        Сообщить("Структура каталога изменена");
    КонецЕсли;
    
    // ДетализацияИзменений - это структура с ключами: Создано, Изменено, Удалено
    
    Для Каждого Файл Из ДетализацияИзменений.Создано Цикл
        Сообщить("Файл создан: " + Файл.ПолноеИмя);
    КонецЦикла;
    
    Для Каждого Файл Из ДетализацияИзменений.Изменено Цикл
        Сообщить("Файл изменен: " + Файл.ПолноеИмя);
    КонецЦикла;
    
    Для Каждого Файл Из ДетализацияИзменений.Удалено Цикл
        Сообщить("Файл удален: " + Файл.ПолноеИмя);
    КонецЦикла;

КонецПроцедуры

// Создаем экземпляр сканера с режимом детализации
Сканер = Новый СканерИзмененийФайлов("/путь/к/каталогу", 1000);
Сканер.РежимДетализацииИзменений() // Включаем режим детализации
    .УстановитьМаску("*.os");

Сканер.Запустить(Новый Действие(ЭтотОбъект, "ОбработатьДетализированныеИзменения"));

API

Конструктор

Новый СканерИзмененийФайлов(ПутьККаталогу, ИнтервалСканирования = 1000)

Параметры:

• ПутьККаталогу (Строка) - путь к каталогу для отслеживания
• ИнтервалСканирования (Число) - интервал между сканированиями в миллисекундах (по умолчанию 1000)

Методы

УстановитьМаску(Маска) → СканерИзмененийФайлов

Устанавливает маску для фильтрации файлов.

Параметры:

• Маска (Строка) - маска файлов (например, ".txt", ".os")

Пример:

Сканер.УстановитьМаску("*.os");

ДобавитьКаталогИсключения(ПутьККаталогу) → СканерИзмененийФайлов

Добавляет каталог в список исключений. Путь указывается относительно основного каталога.

Параметры:

• ПутьККаталогу (Строка) - относительный путь к каталогу (например, "/подкаталог")

Пример:

Сканер.ДобавитьКаталогИсключения("/node_modules");

РежимМониторингаСканирования() → СканерИзмененийФайлов

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

РежимДетализацииИзменений() → СканерИзмененийФайлов

Включает режим детализации изменений. В этом режиме второй параметр обработчика будет содержать структуру с ключами:

• Создано (Массив из Файл) - созданные файлы
• Изменено (Массив из Файл) - измененные файлы
• Удалено (Массив из Файл) - удаленные файлы

Без включения этого режима (по умолчанию) второй параметр содержит общий массив всех изменений без разделения по типам.

Пример:

Сканер.РежимДетализацииИзменений()
    .УстановитьМаску("*.txt");

Запустить(Обработчик) → Процедура

Запускает сканирование каталога в фоновом задании.

Параметры:

• Обработчик (Действие) - обработчик изменений (обязателен)

Обработчик должен иметь следующую сигнатуру:

В обычном режиме (по умолчанию):

Процедура Обработчик(ИзмененаСтруктура, ИзмененныеФайлы, ТекущаяСтруктура)
    // ИзмененаСтруктура - Булево, Истина если была изменена структура каталогов
    // ИзмененныеФайлы - Массив из Файл, список всех измененных файлов (создание + изменение + удаление)
    // ТекущаяСтруктура - Массив из Файл, текущее состояние файлов
КонецПроцедуры

В режиме детализации (после вызова РежимДетализацииИзменений()):

Процедура Обработчик(ИзмененаСтруктура, ДетализацияИзменений, ТекущаяСтруктура)
    // ИзмененаСтруктура - Булево, Истина если была изменена структура каталогов
    // ДетализацияИзменений - Структура с ключами:
    //   - Создано (Массив из Файл) - созданные файлы
    //   - Изменено (Массив из Файл) - измененные файлы
    //   - Удалено (Массив из Файл) - удаленные файлы
    // ТекущаяСтруктура - Массив из Файл, текущее состояние файлов
КонецПроцедуры

ЗавершитьСканирование() → Процедура

Устанавливает флаг завершения сканирования. Циклическое сканирование прервется при следующей итерации.

Особенности

• Быстрое сравнение: Использует MD5 хеши для определения изменений файлов
• Гибкая фильтрация: Поддержка масок файлов и исключения каталогов
• Асинхронность: Работа только в фоновом режиме через фоновые задания OneScript без блокировки основного потока
• Мониторинг производительности: Встроенный режим для отслеживания времени сканирования
• Режим детализации: Разделение изменений по типам (создание, изменение, удаление) для более точного контроля

Требования

• OneScript версии 2.0.0 или выше

Лицензия

См. файл LICENSE

Автор

Андрей Савадеров (Macegor)
Email: [email protected]

Репозиторий

https://github.com/Macegor/filewatcher

История изменений

Версия 1.0.0

Новые возможности:

• Режим детализации изменений: метод РежимДетализацииИзменений() — обработчик получает структуру с ключами Создано, Изменено, Удалено (массивы файлов) вместо общего массива. Обратная совместимость сохранена: без вызова метода второй параметр по-прежнему массив всех изменений.
• Поведение при первом запуске: первое сканирование только инициализирует состояние, обработчик не вызывается — исключены ложные срабатывания при старте.

Версия 0.2.0

⚠️ Breaking Changes - Изменения API:

• Удален синхронный режим работы: Библиотека теперь работает только в асинхронном режиме через фоновые задания OneScript
• Изменен конструктор: Удален параметр ВыполнятьВФоне (теперь всегда работает в фоне)

  // Было (0.1.0):
  Новый СканерИзмененийФайлов(ПутьККаталогу, ВыполнятьВФоне = Ложь, ИнтервалСканирования = 1000)
  
  // Стало (0.2.0):
  Новый СканерИзмененийФайлов(ПутьККаталогу, ИнтервалСканирования = 1000)

• Изменен метод Запустить: Параметр Обработчик теперь обязателен (не может быть Неопределено)

  // Было (0.1.0):
  Сканер.Запустить(Обработчик = Неопределено) // Можно было вызывать без обработчика
  
  // Стало (0.2.0):
  Сканер.Запустить(Обработчик) // Обработчик обязателен

Миграция с версии 0.1.0:

Если вы использовали синхронный режим:

// Старый код (0.1.0):
Сканер = Новый СканерИзмененийФайлов("/путь", Ложь, 1000);
Сканер.Запустить(); // Синхронный режим

// Новый код (0.2.0):
Сканер = Новый СканерИзмененийФайлов("/путь", 1000);
Сканер.Запустить(Новый Действие(ЭтотОбъект, "Обработчик")); // Только фоновый режим

Если вы использовали фоновый режим:

// Старый код (0.1.0):
Сканер = Новый СканерИзмененийФайлов("/путь", Истина, 1000);
Сканер.Запустить(Обработчик);

// Новый код (0.2.0):
Сканер = Новый СканерИзмененийФайлов("/путь", 1000);
Сканер.Запустить(Обработчик);