semver

Библиотека для работы с версиями

Библиотека позволяет читать из строк и сравнивать версии, а так же диапазоны версий семантического версионирования (semver) аннотация v2.0.0 (например, npmjs.org, pypi.org и другие)

Данная библиотека не использует регулярные выражения.

Пример работы:

• Чтение версии из файла

Версия = Версии.ВерсияИзФайла("Путь/К/Файлу");

Сообщить(Версия.ВСтроку());

• Версия из строки

Версия = Версии.ВерсияИзСтроки("1.0.0");

Сообщить(Версия.ВСтроку());

• Максимальная версия из массива версий

МассивВерсий = Новый Массив();
МассивВерсий.Добавить(ВерсияИзСтроки("1.0.2"));
МассивВерсий.Добавить(ВерсияИзСтроки("1.0.3"));
МассивВерсий.Добавить(ВерсияИзСтроки("1.0.4"));

МаксимальнаяВерсия = Версии.МаксимальнаяИзМассива(МассивВерсий);

Сообщить(МаксимальнаяВерсия.ВСтроку());

• Сравнение версий

ЗнакСравнения = Версии.СравнитьВерсии("1.0.0", "2.0");
// Пример,
//  (-1) - СтрокаВерсия1 меньше (<) СтрокаВерсия2
//  (1) - СтрокаВерсия1 больше (>) СтрокаВерсия2
//  (0) - СтрокаВерсия1 равна (=) СтрокаВерсия2

Версия1Меньше = Версии.ВерсияМеньше("1.0.0", "2.0");

Версия1Больше = Версии.ВерсияБольше("1.0.0", "2.0");

• Соответсвие версии диапазону

Сравнение = Версии.Сравнение(">=1.0.0");
Результат = Сравнение.ПроверяемаяВерсия("1.0.2")
                     .ВДиапазоне();
// ИЛИ

Результат = Версии.ВерсияВДиапазоне("1.0.2", ">=1.0.0")

• Соответсвие массива версий диапазону

МассивВерсий = Новый Массив();
МассивВерсий.Добавить("1.0.2");
МассивВерсий.Добавить("1.0.3");
МассивВерсий.Добавить("1.0.4");

Сравнение = Версии.Сравнение(">=1.0.0");
Результат = Сравнение.ПроверяемыеВерсии(МассивВерсий)
                     .ВДиапазоне();

• Масимальная версия массива версий соотвествующая диапазону

МассивВерсий = Новый Массив();
МассивВерсий.Добавить("1.0.2");
МассивВерсий.Добавить("1.0.3");
МассивВерсий.Добавить("1.0.4");

МаксимальнаяВерсия = Версии.Сравнение(">=1.0.0")
                     .ПроверяемыеВерсии(МассивВерсий)
                     .Максимальная();

Сообщить(МаксимальнаяВерсия.ВСтроку());

• Масимальная версия массива версий между диапазонами нижний и верхний

МассивВерсий = Новый Массив();
МассивВерсий.Добавить("1.0.2");
МассивВерсий.Добавить("1.0.3");
МассивВерсий.Добавить("1.0.4");

МаксимальнаяВерсия = Версии.МаксимальнаяВерсияМежду(МассивВерсий, ">=1.0.0", "<2.0.0");

// ИЛИ
МаксимальнаяВерсия = Версии.Сравнение(">=1.0.0")
                .ДобавитьДиапазон("<2.0.0")
                .ПроверяемыеВерсии(МассивВерсий)
                .Максимальная();

Сообщить(МаксимальнаяВерсия.ВСтроку());

Так же описание функциональности содержится в папке tests. В прилагающихся *.os можно подсмотреть больше примеров из тестов.

Установка

Для установки необходимо:

• Скачать файл semver.ospx из раздела releases
• Воспользоваться командой:

opm install -f <ПутьКФайлу>

или

opm install semver

Базовые принципы работы с классами библиотеки

Работа с версией

Для чтения версии из строки и оперирования версиями реализован класс Версия.

При чтении версии из строки, в случае возникновения ошибки всегда возвращается нулевая версия (0.0.0)

• Создание класса версия

    НоваяВерсия = Новый Версия("1.0.0");

• Строковое представление класса версия

    НоваяВерсия = Новый Версия("1.0.0");
    Сообщить(НоваяВерсия.ВСтроку());

• Сравнение версии с другими версиями

    НоваяВерсия = Новый Версия("1.0.0");
    ВтораяВерсия = Новый Версия("2.0.0");

    Больше = НоваяВерсия.Больше(ВтораяВерсия);
    БольшеИлиРавны = НоваяВерсия.БольшеИлиРавны(ВтораяВерсия);
    Меньше = НоваяВерсия.Меньше(ВтораяВерсия);
    МеньшеИлиРавны = НоваяВерсия.МеньшеИлиРавны(ВтораяВерсия);

• Получение ошибки при чтении версии из строки

    НоваяВерсия = Новый Версия("1.0.0");
    Если НоваяВерсия.Ошибка() Тогда
        Сообщить(НоваяВерсия.ПолучитьОписаниеОшибки());
    КонецЕсли;

Более подробно смотри в описании публичного интерфейса

Работа с версиями

Для работы с несколькими версиями реализован модуль Версии

Более подробно смотри в описании публичного интерфейса

Работа с диапазоном версий

Для работы с диапазонами версий реализован класс ДиапазонВерсий.

Данный класс реализовывает вычисление вхождения версии (или массива версии) в переданный диапазон. А так же обеспечивает чтение простых диапазонов (>=1.2), с тильдой (~), с кареткой (^) и X - диапазоны (x, X или *)

Более подробно смотри в описании публичного интерфейса

Работа с сравнением версий

Для работы с сравнениями версий реализован класс СравнениеВерсий

Класс реализовывает ряд терминальных методов:

• ВМассив() - выполняет сравнение и выгружает результат (подходящие версии) в массив (элементы класса Версия)
• ВМассивСтрок() - тоже самое, что и ВМассив(), только элементы массива равны строковым представлениям версий
• Максимальная() - выполняет сравнение и возвращает максимальный из подходящих версий
• ВДиапазоне() - выполняет сравнение и возвращает истина или ложь, если все проверяемые элементы подошли под диапазоны сравнения

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

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

• Создание объекта сравнения версий

СравнениеВсеВерсии = Новый СравнениеВерсий(); // Диапазон по умолчанию "*"
СравнениеБольшеРавно = Новый СравнениеВерсий(">=1.0.0");

// Или через модуль Версии
СравнениеВсеВерсии = Версии.Сравнение(); // Диапазон по умолчанию "*"
СравнениеБольшеРавно = Версии.Сравнение(">=1.0.0");

• Добавление еще одного диапазона в сравнение

Сравнение = Новый СравнениеВерсий(">=1.0.0");
Сравнение.ДобавитьДиапазон("<2.0.0");

// Или через модуль Версии
Сравнение = Версии.Сравнение(">=1.0.0")
                .ДобавитьДиапазон("<2.0.0");

• Добавление версии для сравнения

Сравнение = Новый СравнениеВерсий(">=1.0.0");
Сравнение.ДобавитьДиапазон("<2.0.0");
Сравнение.ПроверяемаяВерсия("1.0.0");

// Или через модуль Версии
Сравнение = Версии.Сравнение(">=1.0.0")
                .ДобавитьДиапазон("<2.0.0")
                .ПроверяемаяВерсия("1.0.0");

• Добавление массива версий для сравнения

МассивВерсий = Новый Массив();
МассивВерсий.Добавить("1.0.2");
МассивВерсий.Добавить("1.0.3");
МассивВерсий.Добавить("1.0.4");

Сравнение = Новый СравнениеВерсий(">=1.0.0");
Сравнение.ДобавитьДиапазон("<2.0.0");
Сравнение.ПроверяемыеВерсии(МассивВерсий);

// Или через модуль Версии
Сравнение = Версии.Сравнение(">=1.0.0")
                .ДобавитьДиапазон("<2.0.0")
                .ПроверяемыеВерсии(МассивВерсий);

Более подробно смотри в описании публичного интерфейса

Диапазоны

Поддерживаются, как простые диапазоны версий >1.2.3, >=1.2, <1. так и сложные с использованием символов тильда (~), каретка(^) и X (x, X или *)

Простые диапазоны (>1.2.3, >=1.2, <1)

Они состоят из знака операции и строкового представления версии. Возможные знаки операции:

• < Меньше
• <= Меньше или равно
• > Больше
• >= Больше или рано
• = Равно. (по умолчанию) используется, если знак операции не задан

Примеры,

• >=1.2.3
• <1.3.0

Поддержка диапазонов тильда (~1.2.3, ~1.2, ~1)

Примеры, диапазонов с тильдой.

• ~1.2.3 = >=1.2.3 <1.(2+1).0 = >=1.2.3 <1.3.0
• ~1.2 = >=1.2.0 <1.(2+1).0 = >=1.2.0 <1.3.0 (Или 1.2.x)
• ~1 = >=1.0.0 <(1+1).0.0 = >=1.0.0 <2.0.0 (Или 1.x)
• ~0.2.3 = >=0.2.3 <0.(2+1).0 = >=0.2.3 <0.3.0
• ~0.2 = >=0.2.0 <0.(2+1).0 = >=0.2.0 <0.3.0 (Или 0.2.x)
• ~0 = >=0.0.0 <(0+1).0.0 = >=0.0.0 <1.0.0 (Или 0.x)

Поддержка диапазонов каретка (^1.2.3, ^0.2.5, ^0.0.4)

Диапазон каретки используется, если совместимость API не сохраняется между версиями0.2.4 и 0.3.0

Примеры:

• ^1.2.3 = >=1.2.3 <2.0.0
• ^0.2.3 = >=0.2.3 <0.3.0
• ^0.0.3 = >=0.0.3 <0.0.4

Совместно с X:

• ^1.2.x = >=1.2.0 <2.0.0
• ^0.0.x = >=0.0.0 <0.1.0
• ^0.0 = >=0.0.0 <0.1.0
• ^1.x = >=1.0.0 <2.0.0
• ^0.x = >=0.0.0 <1.0.0

Поддержка диапазонов X 1.2.x, 1.X, 1.2.*, *

Любой из символов X, x, или * может быть использовать в диапазоне на месте номера [основной, вспомогательной, патча], например:

• * = >=0.0.0 (Любая версия)
• 1.x = >=1.0.0 <2.0.0 (Между основными версиями)
• 1.2.x = >=1.2.0 <1.3.0 (Mежду вспомогательными версиями)

Или без них совсем.

• "" (Пустая строка) = * = >=0.0.0
• 1 = 1.x.x = >=1.0.0 <2.0.0
• 1.2 = 1.2.x = >=1.2.0 <1.3.0

Публичный интерфейс

Документация публичного интерфейса

Доработка

Доработка проводится по git-flow. Жду ваших PR.

Лицензия

Смотри файл LICENSE.