Написана справка на 80%

Author: khorevaa

README.md

@@ -6,6 +6,342 @@
 [![Build Status](https://travis-ci.org/khorevaa/semver.svg?branch=master)](https://travis-ci.org/khorevaa/semver)
 [![Coverage Status](https://coveralls.io/repos/github/khorevaa/semver/badge.svg?branch=master)](https://coveralls.io/github/khorevaa/semver?branch=master)
 
+# Библиотека для работы с версиями
 
+Библиотека позволяет читать из строк и сравнивать версии, а так же диапазоны версий семантического версионирования (semver) аннотация v2.0.0 (например, npmjs.org, pypi.org и другие)
 
-Библиотека для работы с версиями
+Данная библиотека не использует регулярные выражения.
+
+
+Пример работы:
+
+* Чтение версии из файла
+```bsl
+
+Версия = Версии.ВерсияИзФайла("Путь/К/Файлу");
+
+Сообщить(Версия.ВСтроку());
+
+```
+
+* Версия из строки
+```bsl
+
+Версия = Версии.ВерсияИзСтроки("1.0.0");
+
+Сообщить(Версия.ВСтроку());
+
+```
+* Максимальная версия из массива версий
+```bsl
+
+МассивВерсий = Новый Массив();
+МассивВерсий.Добавить(ВерсияИзСтроки("1.0.2"));
+МассивВерсий.Добавить(ВерсияИзСтроки("1.0.3"));
+МассивВерсий.Добавить(ВерсияИзСтроки("1.0.4"));
+
+МаксимальнаяВерсия = Версии.МаксимальнаяИзМассива(МассивВерсий);
+
+Сообщить(МаксимальнаяВерсия.ВСтроку());
+
+```
+
+
+* Сравнение версий
+```bsl
+
+ЗнакСравнения = Версии.СравнитьВерсии("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");
+
+```
+
+* Соответсвие версии диапазону
+```bsl
+
+Сравнение = Версии.Сравнение(">=1.0.0");
+Результат = Сравнение.ПроверяемаяВерсия("1.0.2")
+                     .ВДиапазоне();
+// ИЛИ
+
+Результат = Версии.ВерсияВДиапазоне("1.0.2", ">=1.0.0")
+
+```
+
+* Соответсвие массива версий диапазону
+```bsl
+
+МассивВерсий = Новый Массив();
+МассивВерсий.Добавить("1.0.2");
+МассивВерсий.Добавить("1.0.3");
+МассивВерсий.Добавить("1.0.4");
+
+Сравнение = Версии.Сравнение(">=1.0.0");
+Результат = Сравнение.ПроверяемыеВерсии(МассивВерсий)
+                     .ВДиапазоне();
+
+```
+
+* Масимальная версия массива версий соотвествующая диапазону
+```bsl
+
+МассивВерсий = Новый Массив();
+МассивВерсий.Добавить("1.0.2");
+МассивВерсий.Добавить("1.0.3");
+МассивВерсий.Добавить("1.0.4");
+
+МаксимальнаяВерсия = Версии.Сравнение(">=1.0.0")
+                     .ПроверяемыеВерсии(МассивВерсий)
+                     .Максимальная();
+
+Сообщить(МаксимальнаяВерсия.ВСтроку());
+
+```
+
+* Масимальная версия массива версий между диапазонами нижний и верхний
+```bsl
+
+МассивВерсий = Новый Массив();
+МассивВерсий.Добавить("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](https://github.com/khorevaa/semver/releases)
+* Воспользоваться командой:
+
+```
+opm install -f <ПутьКФайлу>
+```
+или
+
+```
+opm install semver
+```
+## Базовые принципы работы с классами библиотеки
+
+### Работа с версией
+
+Для чтения версии из строки и оперирования версиями реализован класс `Версия`.
+> При чтении версии из строки, в случае возникновения ошибки всегда возвращается нулевая версия (`0.0.0`)
+
+* Создание класса версия
+```bsl
+
+    НоваяВерсия = Новый Версия("1.0.0");
+
+```
+
+* Строковое представление класса версия
+```bsl
+
+    НоваяВерсия = Новый Версия("1.0.0");
+    Сообщить(НоваяВерсия.ВСтроку());
+```
+
+* Сравнение версии с другими версиями
+```bsl
+
+    НоваяВерсия = Новый Версия("1.0.0");
+    ВтораяВерсия = Новый Версия("2.0.0");
+
+    Больше = НоваяВерсия.Больше(ВтораяВерсия);
+    БольшеИлиРавны = НоваяВерсия.БольшеИлиРавны(ВтораяВерсия);
+    Меньше = НоваяВерсия.Меньше(ВтораяВерсия);
+    МеньшеИлиРавны = НоваяВерсия.МеньшеИлиРавны(ВтораяВерсия);
+
+```
+
+* Получение ошибки при чтении версии из строки
+```bsl
+
+    НоваяВерсия = Новый Версия("1.0.0");
+    Если НоваяВерсия.Ошибка() Тогда
+        Сообщить(НоваяВерсия.ПолучитьОписаниеОшибки());
+    КонецЕсли;
+
+```
+
+Более подробно смотри в описании [публичного интерфейса](docs/README.md#класс-версия)
+
+### Работа с версиями
+
+Для работы с несколькими версиями реализован модель `Версии`
+
+Более подробно смотри в описании [публичного интерфейса](docs/README.md#модуль-версии)
+### Работа с диапазоном версий
+
+Для работы с диапазонами версий реализован класс `ДиапазонВерсий`.
+
+
+Данный класс реализовывает вычисление вхождения версии (или массива версии)  в переданный диапазон. А так же обеспечивает чтение простых диапазонов (`>=1.2`), с тильдой (`~`), с кареткой (`^`) и X - диапазоны (`x, X или *`)
+
+
+Более подробно смотри в описании [публичного интерфейса](docs/README.md#класс-диапазонверсий)
+### Работа с сравнением версий
+
+Для работы с сравнениями версий реализован класс СравнениеВерсий
+
+Класс реализовывает ряд терминальных методов:
+
+* `ВМассив()` - выполняет сравнение и выгружает результат (подходящие версии) в массив (элементы класса Версия)
+* `ВМассивСтрок()` - тоже самое, что и `ВМассив()`, только элементы массива равны строковым представлениям версий
+* `Максимальная()` - выполняет сравнение и возвращает максимальный из подходящих версий
+* `ВДиапазоне()` - выполняет сравнение и возвращает истина или ложь, если все проверяемые элементы подошли под диапазоны сравнения
+
+Все остальные методы возвращают этот же класс, что позволяет работать в `текучем` виде.
+
+Примеры использования:
+
+* Создание объекта сравнения версий
+```bsl
+
+СравнениеВсеВерсии = Новый СравнениеВерсий(); // Диапазон по умолчанию "*"
+СравнениеБольшеРавно = Новый СравнениеВерсий(">=1.0.0");
+
+// Или через модуль Версии
+СравнениеВсеВерсии = Версии.Сравнение(); // Диапазон по умолчанию "*"
+СравнениеБольшеРавно = Версии.Сравнение(">=1.0.0");
+
+```
+
+* Добавление еще одного диапазона в сравнение
+```bsl
+
+Сравнение = Новый СравнениеВерсий(">=1.0.0");
+Сравнение.ДобавитьДиапазон("<2.0.0");
+
+// Или через модуль Версии
+Сравнение = Версии.Сравнение(">=1.0.0")
+                .ДобавитьДиапазон("<2.0.0");
+
+```
+
+* Добавление версии для сравнения
+```bsl
+
+Сравнение = Новый СравнениеВерсий(">=1.0.0");
+Сравнение.ДобавитьДиапазон("<2.0.0");
+Сравнение.ПроверяемаяВерсия("1.0.0");
+
+// Или через модуль Версии
+Сравнение = Версии.Сравнение(">=1.0.0")
+                .ДобавитьДиапазон("<2.0.0")
+                .ПроверяемаяВерсия("1.0.0");
+
+```
+
+* Добавление массива версий для сравнения
+```bsl
+
+МассивВерсий = Новый Массив();
+МассивВерсий.Добавить("1.0.2");
+МассивВерсий.Добавить("1.0.3");
+МассивВерсий.Добавить("1.0.4");
+
+Сравнение = Новый СравнениеВерсий(">=1.0.0");
+Сравнение.ДобавитьДиапазон("<2.0.0");
+Сравнение.ПроверяемыеВерсии(МассивВерсий);
+
+// Или через модуль Версии
+Сравнение = Версии.Сравнение(">=1.0.0")
+                .ДобавитьДиапазон("<2.0.0")
+                .ПроверяемыеВерсии(МассивВерсий);
+
+```
+
+Более подробно смотри в описании [публичного интерфейса](docs/README.md#класс-сравнениеверсий)
+## Диапазоны
+
+Поддерживаются, как простые диапазоны версий `>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`
+
+## Публичный интерфейс
+
+[Документация публичного интерфейса](docs/README.md)
+## Доработка
+
+Доработка проводится по git-flow. Жду ваших PR.
+
+## Лицензия
+
+Смотри файл `LICENSE`.