Ada 2.9.2
Fast spec-compliant URL parser
|
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 common use of a URL parser is to take a URL string and normalize it. The WHATWG URL specification has been adopted by most browsers. Other tools, such as curl and many standard libraries, follow the RFC 3986. The following table illustrates possible differences in practice (encoding of the host, encoding of the path):
string source | string value |
---|---|
input string | https://www.7‑Eleven.com/Home/Privacy/Montréal |
ada's normalized string | https://www.xn–7eleven-506c.com/Home/Privacy/Montr%C3%A9al |
curl 7.87 | (returns the original unchanged) |
The project is otherwise self-contained and it has no dependency. A recent C++ compiler supporting C++20. We test GCC 12 or better, LLVM 12 or better and Microsoft Visual Studio 2022.
On a benchmark where we need to validate and normalize thousands URLs found on popular websites, we find that ada can be several times faster than popular competitors (system: Apple MacBook 2022 with LLVM 14).
Ada has improved the performance of the popular JavaScript environment Node.js:
Since Node.js 18, a new URL parser dependency was added to Node.js — Ada. This addition bumped the Node.js performance when parsing URLs to a new level. Some results could reach up to an improvement of 400%. (State of Node.js Performance 2023)
The Ada library is used by important systems besides Node.js such as Redpanda, Kong, Telegram and Cloudflare Workers.
Linux or macOS users might follow the following instructions if they have a recent C++ compiler installed and a standard utility (wget
)
demo.cpp
with this content: ./demo
We provide clients for different programming languages through our C API.
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).
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:
You should do...
For simplicity, in the examples below, we skip the check because we know that parsing succeeds. All strings are assumed to be valid UTF-8 strings.
For more information about command-line options, please refer to the CLI documentation.
See the file include/ada_c.h
for our C interface. We expect ASCII or UTF-8 strings.
When linking against the ada library from C++, be minding that ada requires access to the standard C++ library. E.g., you may link with the C++ compiler.
E.g., if you grab our single-header C++ files (ada.cpp
and ada.h
), as well as the C header (ada_c.h
), you can often compile a C program (demo.c
) as follows under Linux/macOS systems:
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 is available through Homebrew. You can install Ada using brew install ada-url
.
Ada uses cmake as a build system. It's recommended you to run the following commands to build it locally.
cmake -B build && cmake --build build
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.
This code is made available under the Apache License 2.0 as well as the MIT license.
Our tests include third-party code and data. The benchmarking code includes third-party code: it is provided for research purposes only and not part of the library.