Skyr URL

Status

Introduction

This library provides:

• A skyr::url class that implements a generic URL parser, conforming with the WhatWG URL specification
• URL serialization and comparison
• Percent encoding and decoding functions
• IDNA and Punycode functions for domain name parsing
• Basic Unicode conversion functions

Building the project

This project requires the availability of a C++17 compliant compiler and standard library.

Installing dependencies using vcpkg

Using vcpkg, install the library dependencies:

> cd ${VCPKG_ROOT}
> git init
> git remote add origin https://github.com/Microsoft/vcpkg.git
> git fetch origin master
> git checkout -b master origin/master
> ./bootstrap-vcpkg.sh
> ./vcpkg install tl-expected catch2 nlohmann-json

Building with CMake and Ninja

From a terminal, execute the following sequence of commands:

> mkdir _build
> cd _build
> cmake .. \
    -G "Ninja" \
    -DCMAKE_TOOLCHAIN_FILE=${VCPKG_ROOT}/vcpkg/scripts/buildsystems/vcpkg.cmake
> ninja

To run the tests, run ninja test from the terminal while in the _build directory:

> ninja test

Building with CMake and Visual Studio 2017

Open Visual Studio 2017, and click on File->Open->Folder, or use the shortcut Ctrl+Shift+Alt+O. Open the root folder of this project. This will load the project in the explorer. To build, simply open the CMake menu and click Build All.

To run the tests, open the CMake menu, click Tests and then run Run Skyr CTests.

Examples

These examples are based on the WhatWG API specification

To build the examples, run cmake as follows:

> cmake .. \
    -G "Ninja" \
    -DSkyr_BUILD_EXAMPLES=ON \
    -DCMAKE_TOOLCHAIN_FILE=${VCPKG_ROOT}/vcpkg/scripts/buildsystems/vcpkg.cmake

Creating a URL without a base URL

This example parses a string, "https://example.org/💩", without using a base URL:

#include <skyr/url.hpp>
#include <iostream>

int main(int argc, char *argv[]) {
  auto url = skyr::url("http://example.org/\xf0\x9f\x92\xa9");
  std::cout << url.pathname() << std::endl;
}

Gives the output: /%F0%9F%92%A9

Creating a non-absolute URL without a base URL

This gives an error if the input, "/🍣🍺", is not an absolute-URL-with-fragment-string:

#include <skyr/url.hpp>
#include <iostream>

int main(int argc, char *argv[]) {
  auto url = skyr::make_url("\xf0\x9f\x8d\xa3\xf0\x9f\x8d\xba");
  if (!url) {
    std::cerr << "Parsing failed: " << url.error().message() << std::endl;
  }
}

This gives the output: Parsing failed: Not an absolute URL with fragment

Creating a non-absolute URL with a base URL

This example parses a string, "🏳️‍🌈", using a base URL, "https://example.org/":

#include <skyr/url.hpp>
#include <iostream>

int main(int argc, char *argv[]) {
  auto base = skyr::url("https://example.org/");
  auto url = skyr::url(
    "\xf0\x9f\x8f\xb3\xef\xb8\x8f\xe2\x80\x8d\xf0\x9f\x8c\x88", base);
  std::cout << url.href() << std::endl;
}

This gives the output: https://example.org/%F0%9F%8F%B3%EF%B8%8F%E2%80%8D%F0%9F%8C%88

Installation

Installing with CMake and Ninja

> cmake .. \
    -G "Ninja" \
    -DCMAKE_TOOLCHAIN_FILE=${VCPKG_ROOT}/vcpkg/scripts/buildsystems/vcpkg.cmake \
    -DCMAKE_INSTALL_PREFIX=$PREFIX
> ninja
> ninja test      # optional
> ninja install

Where $PREFIX is the location where you want to install the library. Depending on the location of $PREFIX, you may need to run the install command as an administrator (e.g. on Linux as sudo).

Installing with CMake and Visual Studio 2017

Open the CMake menu, click Install, then Skyr.

Dependencies

This library uses expected and a modified implementation of utfcpp.

The tests use Catch2 and nlohmann-json.

Requirements

This library has been tested using the following platforms and compilers:

Linux:

• GCC 8
• GCC 9
• Clang 7
• Clang 8

MacOS:

• Clang 7

Windows:

• Microsoft Visual C++ 2017

License

This library is released under the Boost Software License (please see http://boost.org/LICENSE_1_0.txt or the accompanying LICENSE_1_0.txt file for the full text).

Why skyr?

This name was chosen by a random project name generator, which itself was randomly chosen.

Contact

Any questions about this library can be addressed to the cpp-netlib developers mailing list. Issues can be filed using Github at http://github.com/cpp-netlib/url/issues.