Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -183,7 +183,7 @@ https://%D0%BF%D1%80%D0%B8%D0%BC%D0%B5%D1%80.%D1%80%D1%84/%D0%BF%D1%83%D1%82%D1%

- [Справочник API](docs/README.md)
- [URL](docs/URL.md) - единая изменяемая абсолютная или относительная URI-ссылка
- [РазборURL](docs/РазборURL.md) - разбор без передачи исключений
- [РазборURL](docs/РазборURL.md) - разбор URI-ссылок и серверных адресов
- [ВидыХостаURL](docs/ВидыХостаURL.md) - классификация хоста
- [ПараметрыЗапросаURL](docs/ПараметрыЗапросаURL.md) - коллекция параметров запроса
- [ФорматыПараметровЗапросаURL](docs/ФорматыПараметровЗапросаURL.md) - форматы параметров запроса
Expand Down
3 changes: 2 additions & 1 deletion docs/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,7 @@

- [Установка](../README.md#установка) и [быстрый старт](../README.md#быстрый-старт)
- [Работа с относительными ссылками](../README.md#относительные-ссылки)
- [Разбор серверного адреса со схемой по умолчанию](РазборURL.md#разобратьсосхемойпоумолчанию)
- [Разбор ввода без передачи исключений](РазборURL.md)
- Изменение [пути](URL.md#путь-url), [запроса](URL.md#строка-запроса-url) и [фрагмента](URL.md#фрагмент-url)
- [Работа с параметрами запроса](ПараметрыЗапросаURL.md)
Expand All @@ -32,6 +33,6 @@

- [КодированиеURL](КодированиеURL.md) - кодирование компонентов и параметров формы
- [КодыОшибокURL](КодыОшибокURL.md) - машинные коды ошибок
- [РазборURL](РазборURL.md) - разбор с результатом `URL` или `Неопределено`
- [РазборURL](РазборURL.md) - разбор URI-ссылок и серверных адресов
- [ВидыХостаURL](ВидыХостаURL.md) - значения классификации хоста
- [ФорматыПараметровЗапросаURL](ФорматыПараметровЗапросаURL.md) - форматы разбора и сериализации параметров
1 change: 1 addition & 0 deletions docs/КодыОшибокURL.md
Original file line number Diff line number Diff line change
Expand Up @@ -54,6 +54,7 @@
| --- | --- | --- |
| `НедопустимыйСинтаксис()` | `url.invalid_syntax` | Нарушена общая грамматика URI |
| `НедопустимаяСхема()` | `url.invalid_scheme` | Нарушена грамматика схемы |
| `ТребуетсяСерверныйАдрес()` | `url.server_address_required` | Требуется серверный адрес |
| `НедопустимоеПроцентноеКодирование()` | `url.invalid_percent_encoding` | Нарушена форма `%HH` |
| `НедопустимаяСервернаяЧасть()` | `url.invalid_authority` | Нарушена структура серверной части |
| `НедопустимыйХост()` | `url.invalid_host` | Хост не соответствует допустимой форме |
Expand Down
96 changes: 91 additions & 5 deletions docs/РазборURL.md
Original file line number Diff line number Diff line change
@@ -1,16 +1,19 @@
# РазборURL

Публичный модуль разбирает URI-ссылки без передачи исключений вызывающему коду. Использует ту же
общую грамматику, что и конструктор [`URL`](URL.md), по
Публичный модуль разбирает URI-ссылки и серверные адреса. Использует ту же общую грамматику, что и конструктор
[`URL`](URL.md), по
[RFC 3986](https://www.rfc-editor.org/rfc/rfc3986.html) и [RFC 3987](https://www.rfc-editor.org/rfc/rfc3987.html).

Успешный разбор не проверяет ограничения конкретной схемы, доверие к узлу или его сетевую доступность.
Для `http`, `https`, `ws`, `wss` и `ftp` дополнительно вызывайте
[`URL.СоответствуетСхеме()`](URL.md#соответствуетсхеме).
`ПопытатьсяРазобрать()` и `ЭтоКорректнаяСсылка()` не проверяют ограничения конкретной схемы. Для `http`, `https`,
`ws`, `wss` и `ftp` после них дополнительно вызывайте [`URL.СоответствуетСхеме()`](URL.md#соответствуетсхеме).
`РазобратьСоСхемойПоУмолчанию()` и `ПопытатьсяРазобратьСоСхемойПоУмолчанию()` выполняют проверку автоматически.
Ни одна операция модуля не проверяет доверие к узлу или его сетевую доступность.

## Оглавление

- [ПопытатьсяРазобрать](#попытатьсяразобрать)
- [РазобратьСоСхемойПоУмолчанию](#разобратьсосхемойпоумолчанию)
- [ПопытатьсяРазобратьСоСхемойПоУмолчанию](#попытатьсяразобратьсосхемойпоумолчанию)
- [ЭтоКорректнаяСсылка](#этокорректнаяссылка)
- [Связанные сущности](#связанные-сущности)

Expand Down Expand Up @@ -44,6 +47,89 @@

Модуль перехватывает любое исключение конструктора, поэтому причину следует определять по параметру `Ошибка`.

## РазобратьСоСхемойПоУмолчанию

```bsl
РазборURL.РазобратьСоСхемойПоУмолчанию(<Значение>, <СхемаПоУмолчанию>)
```

Разбирает серверный адрес с необязательной схемой. Если схема в адресе отсутствует, добавляет переданную схему.
Явно заданную схему сохраняет. Операция предназначена для серверных адресов, а не для произвольных относительных
URI-ссылок.

### Параметры

| Параметр | Тип | Описание |
| --- | --- | --- |
| Значение | `Строка` | Серверный адрес или абсолютный иерархический URL |
| СхемаПоУмолчанию | `Строка` | Схема без завершающего двоеточия, применяемая при отсутствии явной |

### Возвращаемое значение

Новый независимый [`URL`](URL.md) с определённой серверной частью и непустым хостом.

### Исключения

| Код | Условие |
| --- | --- |
| `argument.invalid_type` | Значение или схема по умолчанию имеют тип, отличный от `Строка` |
| `argument.required` | Значение или схема по умолчанию не заполнены |
| `url.invalid_scheme` | Схема не соответствует грамматике RFC 3986 |
| `url.server_address_required` | Значение не имеет поддерживаемой формы серверного адреса |
| Коды разбора URI | Сформированный URL нарушает общую грамматику |
| `url.invalid_for_scheme` | URL нарушает ограничения известной сетевой схемы |

Грамматика схемы определена в
[RFC 3986, раздел 3.1](https://www.rfc-editor.org/rfc/rfc3986.html#section-3.1).

Для `url.server_address_required` исходная строка не включается в текст и данные ошибки. Это защищает пароль из
данных пользователя от случайного вывода в журнал.

### Пример

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

Адрес = РазборURL.РазобратьСоСхемойПоУмолчанию("hub.example/private", "https");
Сообщить(Адрес.ВСтроку()); // https://hub.example/private
```

Сетевые ссылки вида `//hub.example/private` и абсолютные иерархические URL также поддерживаются. Согласно
[RFC 3986, раздел 4.2](https://www.rfc-editor.org/rfc/rfc3986.html#section-4.2), строка
`hub.example/private` сама по себе является относительным путём. Именно поэтому для неё нужна отдельная операция.

## ПопытатьсяРазобратьСоСхемойПоУмолчанию

```bsl
РазборURL.ПопытатьсяРазобратьСоСхемойПоУмолчанию(<Значение>, <СхемаПоУмолчанию>, <Ошибка> = Неопределено)
```

Разбирает те же формы серверного адреса, что и `РазобратьСоСхемойПоУмолчанию()`, но не выбрасывает исключения.

### Параметры

| Параметр | Тип | Описание |
| --- | --- | --- |
| Значение | `Строка` | Серверный адрес или абсолютный иерархический URL |
| СхемаПоУмолчанию | `Строка` | Схема без завершающего двоеточия, применяемая при отсутствии явной |
| Ошибка | `ИнформацияОбОшибке`, `Неопределено` | Выходной параметр с ошибкой |

### Возвращаемое значение

Новый независимый [`URL`](URL.md) или `Неопределено` при ошибке. При успехе параметр `Ошибка` получает значение
`Неопределено`. При ошибке он содержит её причину с тем же предметным кодом, который выбрасывает
`РазобратьСоСхемойПоУмолчанию()`.

### Пример

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

Ошибка = Неопределено;
Адрес = РазборURL.ПопытатьсяРазобратьСоСхемойПоУмолчанию("hub.example/private", "https", Ошибка);
```


## ЭтоКорректнаяСсылка

```bsl
Expand Down
Loading
Loading