url

url - библиотека OneScript для работы с URI-ссылками и URL по стандартам RFC 3986 и RFC 3987.

Библиотека разбирает абсолютные и относительные ссылки, поддерживает Unicode и позволяет безопасно изменять компоненты URL без сетевых запросов и скрытых преобразований.

Возможности

• строгий и безопасный разбор абсолютных и относительных URI-ссылок;
• разрешение, релятивизация, нормализация, сравнение и сортировка URI;
• проверка ограничений схем http, https, ws, wss и ftp;
• работа с Unicode, IDN и Punycode по UTS #46;
• атомарное изменение компонентов URL;
• параметры запроса с дубликатами, сохранением порядка и кодированием application/x-www-form-urlencoded.

Требования

• OneScript 2.0.0 или новее;
• OPM для установки зависимостей и сборки пакета.

Установка

opm install url

Подключение библиотеки:

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

Для проекта с packagedef:

Описание.ЗависитОт("url");

Быстрый старт

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

Адрес = Новый URL("https://example.com/users");

Адрес.ДобавитьСегментПути("42");
Адрес.ПараметрыЗапроса()
    .Установить("q", "hello world")
    .Добавить("include", "orders")
    .Добавить("include", "contacts");

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

Результат:

https://example.com/users/42?q=hello+world&include=orders&include=contacts

Параметры сохраняют порядок добавления и повторяющиеся имена.

Относительные ссылки

Вторым параметром конструктора URL можно передать абсолютный базовый адрес:

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

Адрес = Новый URL("../users", "https://example.com/api/v1/");
Сообщить(Адрес.ВСтроку());

Результат:

https://example.com/api/users

Относительная ссылка разрешается по алгоритму RFC 3986 § 5.2.

Безопасный разбор

Конструктор URI выбрасывает исключение для некорректной ссылки. Если ошибка разбора является ожидаемой, используйте модуль РазборURI:

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

ВходнаяСтрока = "https://пример.рф/путь";
Ссылка = РазборURI.ПопытатьсяРазобрать(ВходнаяСтрока);
Если Ссылка = Неопределено Тогда
    Сообщить("Некорректная URI-ссылка");
Иначе
    Сообщить(Ссылка.ВСтроку());
КонецЕсли;

ПопытатьсяРазобрать() возвращает объект URI или Неопределено. Для простой проверки без получения объекта используйте РазборURI.ЭтоКорректнаяСсылка().

Сравнение и проверка схемы

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

Первая = Новый URI("HTTP://Example.COM/a%2f");
Вторая = Новый URI("http://example.com/a%2F");

Сообщить(Первая.РавенПоКомпонентам(Вторая));  // Истина
Сообщить(Первая.Сравнить(Вторая));            // 0

Адрес = Новый URI("http:/path");
Сообщить(Адрес.СоответствуетСхеме()); // Ложь: для HTTP нужен хост

Подробнее о лексическом, компонентном и нормализованном сравнении смотрите в документации URI.

Unicode и IDN

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

Адрес = Новый URL("https://пример.рф/путь?q=я");

Сообщить(Адрес.ВСтроку());
Сообщить(Адрес.IDNХост());
Сообщить(Адрес.КодированноеПредставление());

Результат:

https://пример.рф/путь?q=я
xn--e1afmkfd.xn--p1ai
https://%D0%BF%D1%80%D0%B8%D0%BC%D0%B5%D1%80.%D1%80%D1%84/%D0%BF%D1%83%D1%82%D1%8C?q=%D1%8F

ВСтроку() сохраняет символы Unicode, IDNХост() преобразует доменное имя в Punycode, а КодированноеПредставление() возвращает URI из символов ASCII с процентным кодированием UTF-8.

Ошибки и границы ответственности

Некорректный синтаксис, процентное кодирование, хосты и несовместимые компоненты приводят к исключениям со стабильными кодами, например uri.invalid_syntax и url.incompatible_components. Получить и сопоставить коды можно через модули КодыОшибокURL и ДиагностикаОшибок.

url работает только с текстовым представлением адресов: не выполняет DNS-запросы, HTTP-запросы и другие сетевые операции. Библиотека не реализует браузерный алгоритм разбора WHATWG URL; из этого стандарта используется только формат application/x-www-form-urlencoded для параметров запроса.

Документация

• Справочник API
• URI - неизменяемая URI-ссылка
• URL - изменяемый абсолютный адрес
• РазборURI - безопасный разбор
• ВидыХостаURI - классификация хоста
• ПараметрыЗапросаURL - коллекция параметров запроса
• КодированиеURL - кодирование компонентов
• КодыОшибокURL - машинные коды ошибок

Разработка

Установить зависимости:

opm install -l --dev

Запустить тесты:

oneunit execute --recursive

Собрать пакет:

opm build .