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
9 changes: 5 additions & 4 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@ Unicode, разрешение ссылок относительно базово
- работа с Unicode, IDN и Punycode по UTS #46;
- получение кодированного URI-представления;
- работа с параметрами запроса с сохранением порядка и повторяющихся имён;
- кодирование параметров в формате `application/x-www-form-urlencoded`.
- процентное кодирование параметров по RFC 3986 и кодирование `application/x-www-form-urlencoded`.

## Требования

Expand Down Expand Up @@ -68,7 +68,7 @@ opm install url
Результат:

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

Параметры сохраняют порядок добавления и повторяющиеся имена.
Expand Down Expand Up @@ -176,8 +176,8 @@ https://%D0%BF%D1%80%D0%B8%D0%BC%D0%B5%D1%80.%D1%80%D1%84/%D0%BF%D1%83%D1%82%D1%
[`ДиагностикаОшибок`](https://github.com/Stivo182/oscript-errors/blob/main/docs/ДиагностикаОшибок.md).

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

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

Expand All @@ -186,6 +186,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%
- [РазборURL](docs/РазборURL.md) - разбор без передачи исключений
- [ВидыХостаURL](docs/ВидыХостаURL.md) - классификация хоста
- [ПараметрыЗапросаURL](docs/ПараметрыЗапросаURL.md) - коллекция параметров запроса
- [ФорматыПараметровЗапросаURL](docs/ФорматыПараметровЗапросаURL.md) - форматы параметров запроса
- [КодированиеURL](docs/КодированиеURL.md) - кодирование компонентов
- [КодыОшибокURL](docs/КодыОшибокURL.md) - машинные коды ошибок

Expand Down
6 changes: 4 additions & 2 deletions docs/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,8 +3,9 @@
Публичный программный интерфейс пакета `url` предназначен для работы с абсолютными и относительными URI-ссылками,
в том числе содержащими символы Unicode. Сетевой ввод-вывод не выполняется. Синтаксис основан на
[RFC 3986](https://www.rfc-editor.org/rfc/rfc3986.html) и
[RFC 3987](https://www.rfc-editor.org/rfc/rfc3987.html), а обработка параметров формы - на
[WHATWG URL §5](https://url.spec.whatwg.org/#application-x-www-form-urlencoded).
[RFC 3987](https://www.rfc-editor.org/rfc/rfc3987.html). Параметры запроса поддерживают профиль процентного
кодирования RFC 3986 и формат веб-формы из
[WHATWG URL, §5](https://url.spec.whatwg.org/#application-x-www-form-urlencoded).

## По задачам

Expand Down Expand Up @@ -33,3 +34,4 @@
- [КодыОшибокURL](КодыОшибокURL.md) - машинные коды ошибок
- [РазборURL](РазборURL.md) - разбор с результатом `URL` или `Неопределено`
- [ВидыХостаURL](ВидыХостаURL.md) - значения классификации хоста
- [ФорматыПараметровЗапросаURL](ФорматыПараметровЗапросаURL.md) - форматы разбора и сериализации параметров
43 changes: 20 additions & 23 deletions docs/URL.md
Original file line number Diff line number Diff line change
Expand Up @@ -129,10 +129,10 @@
Конструктор и методы изменения проверяют общую грамматику URI, но не ограничения конкретной схемы. Например,
`http:/path` синтаксически корректен, однако `СоответствуетСхеме()` вернёт `Ложь`, потому что у `http` нет хоста.

Конструктор проверяет форму процентных последовательностей, но декодирование UTF-8 выполняется при вызове
декодирующих методов. Поэтому успешно созданный объект всё ещё может вызвать `encoding.invalid` при обращении к
`Путь()`, `СтрокаЗапроса()`, `Фрагмент()` или другому декодированному представлению. Единой операции строгого
декодирования всех компонентов нет: проверяйте только те декодированные компоненты, которые использует приложение.
Конструктор проверяет форму процентных последовательностей в пути, данных пользователя, хосте и фрагменте.
В строке запроса допускается литеральный `%`. Подробнее это поведение описано в
[`ПараметрыЗапросаURL`](ПараметрыЗапросаURL.md#создание). Декодирование UTF-8 выполняется при вызове декодирующих
методов, поэтому они могут вызвать `encoding.invalid`.

## Создание

Expand Down Expand Up @@ -959,13 +959,13 @@ ASCII, но не заменяет доменное имя на Punycode.
## Строка запроса URL

`СтрокаЗапроса()` работает со всем запросом как с компонентом URI и оставляет `+` без изменений.
`ПараметрыЗапроса()` разбирает запрос как форму `application/x-www-form-urlencoded`, где `+` означает пробел.
Сохранённая коллекция параметров является живым представлением запроса, а не снимком. Она увидит последующие
изменения URL и изменения через другую связанную коллекцию при следующем вызове своего метода.
`ПараметрыЗапроса()` по умолчанию разбирает пары в формате
[`RFC3986()`](ФорматыПараметровЗапросаURL.md#rfc3986), где `+` является обычным символом. Для интерпретации
`application/x-www-form-urlencoded` вызовите `РазобратьКак(ФорматыПараметровЗапросаURL.ВебФорма())`.

Чтение параметров сохраняет исходную строку запроса. Любой изменяющий метод коллекции кодирует имена и заданные
значения заново по правилам формы, сохраняя параметры без значения без знака `=`. При этом, например, `%20`
станет `+`.
Повторные вызовы `ПараметрыЗапроса()` возвращают одну и ту же коллекцию. Ранее полученная ссылка на неё остаётся
актуальной после изменения строки запроса через методы URL. Чтение параметров сохраняет исходное написание,
а изменение пар влияет на последующее представление URL в соответствии с текущим форматом.

### СтрокаЗапроса

Expand Down Expand Up @@ -999,19 +999,15 @@ ASCII, но не заменяет доменное имя на Punycode.

### ПараметрыЗапроса

Возвращает связанную с URL коллекцию параметров формы. Чтение коллекции не изменяет исходное написание запроса;
при изменении коллекции запрос сериализуется по алгоритму
[WHATWG `application/x-www-form-urlencoded`](https://url.spec.whatwg.org/#application-x-www-form-urlencoded).
Возвращает связанную с URL коллекцию параметров запроса.

```bsl
.ПараметрыЗапроса()
```

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

Новый объект [`ПараметрыЗапросаURL`](ПараметрыЗапросаURL.md), связанный с текущим URL.

Каждый вызов возвращает новый объект коллекции, но все такие объекты читают и изменяют запрос одного владельца.
Тот же объект [`ПараметрыЗапросаURL`](ПараметрыЗапросаURL.md) на протяжении жизни URL.

### УстановитьСтрокуЗапроса

Expand Down Expand Up @@ -1066,18 +1062,16 @@ ASCII, но не заменяет доменное имя на Punycode.
| --- | --- |
| `argument.invalid_type` | Передан неподдерживаемый тип |
| `url.invalid_syntax` | Значение содержит недопустимый символ |
| `url.invalid_percent_encoding` | Нарушена форма `%HH` |

#### Поведение

Пустая строка создаёт определённый пустой запрос `?`. `Неопределено` полностью удаляет запрос.
Пустая строка создаёт определённый пустой запрос `?`. `Неопределено` полностью удаляет запрос. Процент, не
образующий последовательность `%HH`, в кодированном представлении заменяется на `%25`.

### УстановитьПараметрыЗапроса

Копирует текущие параметры в запрос URL. Пустая коллекция удаляет компонент запроса.
Самостоятельная или связанная с другим URL коллекция после этого не влияет на целевой URL. Коллекция,
уже связанная с целевым URL, сохраняет связь, и её
следующее изменение снова изменит этот URL.
Копирует пары и текущий формат. Если в пустой коллекции строка запроса отсутствует, компонент запроса удаляется.
Переданная коллекция остаётся независимой, а ранее полученная ссылка на параметры целевого URL остаётся актуальной.

```bsl
.УстановитьПараметрыЗапроса(<Значение>)
Expand Down Expand Up @@ -1455,7 +1449,7 @@ ASCII, но не заменяет доменное имя на Punycode.
// https://example.com/files/reports%2F2025.pdf
```

Строка запроса и параметры формы:
Строка запроса и параметры веб-формы:

```bsl
#Использовать url
Expand All @@ -1465,6 +1459,9 @@ ASCII, но не заменяет доменное имя на Punycode.
Сообщить(Адрес.СтрокаЗапроса());
// q=hello+world

Адрес.ПараметрыЗапроса().РазобратьКак(
ФорматыПараметровЗапросаURL.ВебФорма()
);
Сообщить(Адрес.ПараметрыЗапроса().Получить("q"));
// hello world
```
Expand Down
5 changes: 3 additions & 2 deletions docs/КодированиеURL.md
Original file line number Diff line number Diff line change
Expand Up @@ -54,8 +54,9 @@
```

`КодироватьСтрокуЗапроса()` не разбирает пары параметров и не защищает `&` и `=` как данные. Для построения
параметров используйте [`ПараметрыЗапросаURL`](ПараметрыЗапросаURL.md) либо кодируйте имя и значение отдельно
через `КодироватьПараметрФормы()`.
параметров используйте [`ПараметрыЗапросаURL`](ПараметрыЗапросаURL.md). Для совместимости с веб-формой можно
явно выбрать [`ВебФорма()`](ФорматыПараметровЗапросаURL.md#вебформа) или кодировать каждое имя и значение через
`КодироватьПараметрФормы()`.

## Функции

Expand Down
Loading
Loading