Ada is a fast and spec-compliant URL parser written in C++. Specification for URL parser can be found from the WHATWG website.
The Ada library passes the full range of tests from the specification, across a wide range of platforms (e.g., Windows, Linux, macOS). It fully supports the relevant Unicode Technical Standard.
- A recent C++ compiler supporting C++17. We test GCC 9 or better, LLVM 10 or better and Microsoft Visual Studio 2022.
The project is otherwise self-contained and it has no dependency.
Ada supports two types of URL instances, ada:url
and ada:url_aggregator
. The usage is
the same in either case: we have an parsing function template ada::parse
which can return
either a result of type ada::result<ada:url>
or of type ada::result<ada:url_aggregator>
depending on your needs. The ada:url_aggregator
class is smaller and it is backed by a precomputed
serialized URL string. The ada:url
class is made of several separate strings for the various
components (path, host, and so forth).
- Parse and validate a URL
ada::result<ada::url_aggregator> url = ada::parse<ada:url_aggregator>("https://www.google.com");
if (url) { /* URL is valid */ }
After calling 'parse', you must check that the result is valid before accessing it when you are not sure that it will succeed. The following code is unsafe:
ada::result<ada:url_aggregator> url = ada::parse<ada:url_aggregator>("some bad url");
url->get_href();
You should do...
ada::result<ada:url_aggregator> url = ada::parse<ada:url_aggregator>("some bad url");
if(url) {
// next line is now safe:
url->get_href();
} else {
// report a parsing failure
}
For simplicity, in the examples below, we skip the check because we know that parsing succeeds.
- Get/Update credentials
ada::result<ada:url_aggregator> url = ada::parse<ada:url_aggregator>("https://www.google.com");
url->set_username("username");
url->set_password("password");
// ada->get_href() will return "https://username:[email protected]/"
- Get/Update Protocol
ada::result<ada:url_aggregator> url = ada::parse<ada:url_aggregator>("https://www.google.com");
url->set_protocol("wss");
// url->get_protocol() will return "wss:"
// url->get_href() will return "wss://www.google.com/"
- Get/Update host
ada::result<ada:url_aggregator> url = ada::parse<ada:url_aggregator>("https://www.google.com");
url->set_host("github.com");
// url->get_host() will return "github.com"
// you can use `url.set_hostname` depending on your usage.
- Get/Update port
ada::result<ada:url_aggregator> url = ada::parse<ada:url_aggregator>("https://www.google.com");
url->set_port("8080");
// url->get_port() will return "8080"
- Get/Update pathname
ada::result<ada:url_aggregator> url = ada::parse<ada:url_aggregator>("https://www.google.com");
url->set_pathname("/my-super-long-path")
// url->get_pathname() will return "/my-super-long-path"
- Get/Update search/query
ada::result<ada:url_aggregator> url = ada::parse<ada:url_aggregator>("https://www.google.com");
url->set_search("target=self");
// url->get_search() will return "?target=self"
- Get/Update hash/fragment
ada::result<ada:url_aggregator> url = ada::parse<ada:url_aggregator>("https://www.google.com");
url->set_hash("is-this-the-real-life");
// url->get_hash() will return "#is-this-the-real-life"
See the file tests/installation/CMakeLists.txt
for an example of how you might use ada from your own
CMake project, after having installed ada on your system.
Ada uses cmake as a build system. It's recommended you to run the following commands to build it locally.
- Build:
cmake -B build && cmake --build build
- Test:
ctest --output-on-failure --test-dir build
Windows users need additional flags to specify the build configuration, e.g. --config Release
.
The project can also be built via docker using default docker file of repository with following commands.
docker build -t ada-builder . && docker run --rm -it -v ${PWD}:/repo ada-builder
You may amalgamate all source files into only two files (ada.h
and ada.cpp
) by typing executing the Python
3 script singleheader/amalgamate.py
. By default, the files are created in the singleheader
directory.