Ada

Ada is a fast and spec-compliant URL parser written in C++. Specification for URL parser can be found from the WHATWG website.

Requirements

• A recent C++ compiler supporting C++17. We test GCC 9 or better, LLVM 10 or better and Microsoft Visual Studio 2022.
• We use ICU when it is available.

Usage

Examples

• Parse and validate a URL

ada::result url = ada::parse("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 url = ada::parse("some bad url");
url->get_href();

You should do...

ada::result url = ada::parse("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 url = ada::parse("https://www.google.com");
url->set_username("username");
url->set_password("password");
// ada->get_href() will return "https://username:password@www.google.com/"

• Get/Update Protocol

ada::result url = ada::parse("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 url = ada::parse("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 url = ada::parse("https://www.google.com");
url->set_port("8080");
// url->get_port() will return "8080"

• Get/Update pathname

ada::result url = ada::parse("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 url = ada::parse("https://www.google.com");
url->set_search("target=self");
// url->get_search() will return "?target=self"

• Get/Update hash/fragment

ada::result url = ada::parse("https://www.google.com");
url->set_hash("is-this-the-real-life");
// url->get_hash() will return "#is-this-the-real-life"

CMake dependency

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.

Contributing

Building

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.

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

Installing ICU

For macOS, you may install it with brew using brew install icu4c. Linux users may install ICU according to the their distribution: under Ubuntu, the command is apt-get install -y libicu-dev.

Amalgamation

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.