mirror of
https://github.com/boostorg/url.git
synced 2025-05-09 17:33:52 +00:00
145 lines
5.0 KiB
Plaintext
145 lines
5.0 KiB
Plaintext
[/
|
|
Copyright (c) 2021 Vinnie Falco (vinnie.falco@gmail.com)
|
|
Copyright (c) 2022 Alan de Freitas (alandefreitas@gmail.com)
|
|
|
|
Distributed under the Boost Software License, Version 1.0. (See accompanying
|
|
file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
|
|
|
|
Official repository: https://github.com/boostorg/url
|
|
]
|
|
|
|
[section Overview]
|
|
[block'''<?dbhtml stop-chunking?>''']
|
|
|
|
[/-----------------------------------------------------------------------------]
|
|
|
|
Boost.URL is a portable C++ library which provides containers and algorithms
|
|
which model a "URL," more formally described using the
|
|
[@https://datatracker.ietf.org/doc/html/rfc3986 Uniform Resource Identifier (URI)]
|
|
specification (henceforth referred to as __rfc3986__). A URL is a compact sequence
|
|
of characters that identifies an abstract or physical resource. For example,
|
|
this is a valid URL:
|
|
|
|
[teletype]
|
|
```
|
|
https://www.example.com/path/to/file.txt?userid=1001&pages=3&results=full#page1
|
|
```
|
|
|
|
This library understands the grammars related to URLs and provides
|
|
functionality to validate, parse, examine, and modify urls, and apply
|
|
normalization or resolution algorithms.
|
|
|
|
[heading Features]
|
|
|
|
While the library is general purpose, special care has been taken to ensure
|
|
that the implementation and data representation are friendly to network
|
|
programs which need to handle URLs efficiently and securely, including the
|
|
case where the inputs come from untrusted sources.
|
|
Interfaces are provided for using error codes instead of exceptions as
|
|
needed, and most algorithms have the means to opt-out of dynamic memory
|
|
allocation. Another feature of the library is that all modifications
|
|
leave the URL in a valid state. Code which uses this library is easy
|
|
to read, flexible, and performant.
|
|
|
|
Boost.URL offers these features:
|
|
|
|
* C++11 as only requirement
|
|
* Fast compilation, few templates
|
|
* Strict compliance with __rfc3986__
|
|
* Containers that maintain valid URLs
|
|
* Parsing algorithms that work without exceptions
|
|
* Control over storage and allocation for URLs
|
|
* Support for `-fno-exceptions`, detected automatically
|
|
* Features that work well on embedded devices
|
|
|
|
[note
|
|
Currently the library does not handle
|
|
[@https://www.rfc-editor.org/rfc/rfc3987.html Internationalized Resource Identifiers] (IRIs).
|
|
These are different from URLs, come from Unicode strings instead of
|
|
low-ASCII strings, and are covered by a separate specification.
|
|
]
|
|
|
|
[/-----------------------------------------------------------------------------]
|
|
|
|
[section Requirements]
|
|
|
|
The library requires a compiler supporting at least C++11.
|
|
|
|
Aliases for standard types, such as __error_code__ or __string_view__,
|
|
use their Boost equivalents.
|
|
|
|
Boost.URL works great on embedded devices. It can be used in a
|
|
way that avoids all dynamic memory allocations. Furthermore it
|
|
offers alternative interfaces that work without exceptions if
|
|
desired.
|
|
|
|
[endsect]
|
|
|
|
[/-----------------------------------------------------------------------------]
|
|
|
|
[heading Tested Compilers]
|
|
|
|
Boost.URL has been tested with the following compilers:
|
|
|
|
* clang: 3.8, 4, 5, 6, 7, 8, 9, 10, 11, 12
|
|
* gcc: 4.8, 4.9, 5, 6, 7, 8, 9, 10, 11
|
|
* msvc: 14.1, 14.2, 14.3
|
|
|
|
and these architectures: x86, x64, ARM64, S390x.
|
|
|
|
[heading Quality Assurance]
|
|
|
|
The development infrastructure for the library includes
|
|
these per-commit analyses:
|
|
|
|
* Coverage reports
|
|
* Compilation and tests on Drone.io and GitHub Actions
|
|
* Regular code audits for security
|
|
|
|
[/-----------------------------------------------------------------------------]
|
|
|
|
[section Nomenclature]
|
|
|
|
Various names have been used historically to refer to different
|
|
flavors of resource identifiers, including ['URI], ['URL], ['URN],
|
|
and even ['IRI]. Over time, the distinction between URIs and URLs
|
|
has disappeared when discussed in technical documents and
|
|
informal works. In this library we use the term [*URL] to
|
|
refer to all strings which are valid according to the
|
|
top-level grammar rules found in __rfc3986__.
|
|
|
|
[endsect]
|
|
|
|
[/-----------------------------------------------------------------------------]
|
|
|
|
[heading ABNF]
|
|
|
|
This documentation uses the Augmented
|
|
[@https://en.wikipedia.org/wiki/Backus%E2%80%93Naur_form Backus-Naur Form]
|
|
(ABNF) notation of
|
|
[@https://datatracker.ietf.org/doc/html/rfc5234 rfc5234]
|
|
to specify particular grammars used by algorithms and containers. While
|
|
a complete understanding of the notation is not a requirement for using
|
|
the library, it may help for an understanding of how valid components of
|
|
URLs are defined. In particular, this is of interest to users who
|
|
wish to compose parsing algorithms using the combinators provided by
|
|
the library.
|
|
|
|
[/-----------------------------------------------------------------------------]
|
|
|
|
[section:security_review Security Review (Bishop Fox)]
|
|
To be announced
|
|
[endsect]
|
|
|
|
[heading Acknowledgments]
|
|
|
|
This library wouldn't be where it is today without the help of
|
|
[@https://github.com/pdimov Peter Dimov]
|
|
for design advice and general assistance.
|
|
|
|
[/-----------------------------------------------------------------------------]
|
|
|
|
[include 2.0.quicklook.qbk]
|
|
|
|
[endsect]
|