Skip to content

Latest commit

 

History

History
123 lines (95 loc) · 4.75 KB

README.md

File metadata and controls

123 lines (95 loc) · 4.75 KB

http-link-header-cpp

Minimal HTTP "Link:" header parser.

RFC 8288 describes a model for the relationships between resources on the Web ("links") and the type of those relationships ("link relation types"). It also defines the serialization of such links in HTTP headers with the "Link:" header field.

http-link-header-cpp is a "header-only" C++ library for parsing HTTP "Link:" headers.

Usage Examples

Parse a simple header

    std::vector<http_link_header::Link> links =
        http_link_header::parse(R"(<https://example.com/book/chap2>; rel="previous"; title="previous chapter")");

    std::cout << links[0].linkRelation << std::endl; // previous
    std::cout << links[0].linkTarget << std::endl; // https://example.com/book/chap2

    std::cout << links[0].targetAttributes[0].name << std::endl; // title
    std::cout << links[0].targetAttributes[0].value << std::endl; // previous chapter

Parse a header with multiple links

    std::vector<http_link_header::Link> links =
        http_link_header::parse(R"(<https://example.com/book/chap2>; rel="previous"; title="previous chapter", <https://example.com/book/chap4>; rel="next"; title="next chapter")");

    std::cout << links.size() << std::endl; // 2

Parse a header with relative links and specific base URI

    std::vector<http_link_header::Link> links =
        http_link_header::parse(R"(<terms>; rel="copyright", <../privacy>; rel="policy")", "https://example.org/a/b");

    std::cout << links[0].linkContext << std::endl; // https://example.org/a/b
    std::cout << links[0].linkTarget << std::endl; // https://example.org/a/terms
    std::cout << links[1].linkContext << std::endl; // https://example.org/a/b
    std::cout << links[1].linkTarget << std::endl; // https://example.org/privacy

Parse a header with relative links, specific base URI, and "anchor" overrides

    std::vector<http_link_header::Link> links =
        http_link_header::parse(R"(<terms>; rel="copyright"; anchor="#legal", <other>; rel="other"; anchor="https://corporate.example.org")", "https://example.org/a/b");

    std::cout << links[0].linkContext << std::endl; // https://example.org/a/b#legal
    std::cout << links[0].linkTarget << std::endl; // https://example.org/a/terms
    std::cout << links[1].linkContext << std::endl; // https://corporate.example.org
    std::cout << links[1].linkTarget << std::endl; // https://example.org/a/other

Dependencies

Build dependencies / runtime dependencies

  • uriparser: used when resolving URI references.

Test dependencies

Development pre-requisites

  1. Install a toolchain. http-link-header-cpp is a header-only C++11 library. You will need a recent GCC or Clang compiler supporting fully C++17 at least.
  2. Install CMake.
  3. Install Python.
  4. Install conan: python3 -m pip install -U conan (more details at docs.conan.io)
  • run conan once to initialize conan home (~/.conan)
  • create a conan profile for the default system compiler

Development workflow

After cloning the repository, create a build directory at the root of the package.

mkdir build-dir && cd build-dir

Pull the dependencies with Conan.

conan install --build=missing ..

Generate the build scripts with cmake.

cmake -DUSE_CONAN=ON \
      -GNinja \
      -DCMAKE_PREFIX_PATH=$(pwd) \
      -DCMAKE_BUILD_TYPE=Release \
      -DCMAKE_INSTALL_PREFIX=$(pwd)/sysroot \
      .. # the directory containing the conanfile.txt

Explanations:

  • -DUSE_CONAN=ON: tell CMakeLists.txt to load conanbuildinfo.cmake generated by the conan install command.
  • -GNinja: Use Ninja instead of GNU Make. Remove this if you prefer using GNU Make as it is the default CMake generator.
  • -DCMAKE_PREFIX_PATH=$(pwd): Variable telling CMake where to find the generated config files for dependencies (i.e. <lowercasePackageName>-config.cmake)
  • -DCMAKE_BUILD_TYPE=Release: Change it to Debug if you want to build the project with -O0 -g
  • -DCMAKE_INSTALL_PREFIX=$(pwd)/sysroot: If CMAKE_INSTALL_PREFIX is not set, the default installation locations for http-link-header-cpp are /usr/local/include and /usr/local/share.

Build the project.

ninja

Run the unit tests.

ninja test

Install the build artifacts.

ninja install

Exporting the package into Conan cache

At the root of the package:

conan create . http-link-header-cpp/0.9.0@conan/testing --build=missing

The package can be pulled in others packages depending on it by adding http-link-header-cpp/0.9.0@conan/testing as a build dependency.