[/
    Copyright (c) 2019 Vinnie Falco (vinnie.falco@gmail.com)

    Distributed under the Boost Software License, Version 1.0. (See accompanying
    file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)

    Official repository: https://github.com/cppalliance/json
]

[/-----------------------------------------------------------------------------]

[section Examples]

[section QR Code]

A QR code is a machine-readable two-dimensional barcode. They might contain data
for a identifier or a URL to a website.

This example shows how to construct and modify URLs to consume a third party API to
generate QR Codes.

[example_qrcode]
[endsect]

[section Finicky]

This example shows how to classify URLs according to a set of rules. It is
inspired by [@https://github.com/johnste/finicky Finicky] application.

The URLs are classified and redirected to a browser according to their
category. See the example `config.json` file.

[example_finicky]
[endsect]

[section mailto URLs]

`mailto` is a URL scheme for email addresses. `mailto` URL are used on websites
to allow users to send an email to a specific address directly from an HTML document.

This example parses a mailto URL into a new view type and prints its components to
standard output.

[example_mailto]
[endsect]

[section Magnet Link]

`magnet` is a URL scheme for identifying files by their content. These files are
usually identified by cryptographic hash value.

Magnet links are useful in peer-to-peer file sharing networks because they allow
resources to be referred to without the need for a continuously available host..

This example parses a magnet link into a new view type and prints its components to
standard output.

[example_magnet]
[endsect]

[section File Router]

This example defines a router that associates URL paths to a directory in the filesystem. If
the specified route matches and the file exists, the example prints its contents to standard output.

[example_file_router]
[endsect]

[section Router]

This example defines a router for URL paths. If the specified route matches one of the existing
routes, the example executes the underlying callback function.

[example_router]
[endsect]

[section Sanitizing URLs]

This example parses a non-strict or invalid URL
into path components according to its delimiters.
This pattern can be adapted to the requirements of other
applications.

Once the non-strict components are determined, a new URL is
created and its parts are set with the `set_encoded_X`
functions, which will encode any invalid chars accordingly.

This sort of transformation is useful in applications that are
extremely loose in what kinds of URLs they accept, such as
browsers. The sanitized URL can later be used for machine-to-machine
communication.

Using non-strict URLs directly is a security concern in
machine-to-machine communication, is ambiguous, and also
involve an extra cost for the transformations.

Different transformations are required by different applications to
construct a valid URL appropriate for machine-to-machine communication.
For instance, if an invalid relative reference includes something that
looks like a host in the first path segment, browsers usually interpret
that as the host with an implicit "https" scheme. Other applications
also have other implicit schemes.

The example also identifies whether the input url is already valid.
It includes diagnostics that can be used to help the user determine
if a URL is invalid and why it's invalid.

Once all transformations are applied, the result is a URL
appropriate for machine-to-machine communication.

[example_sanitize_url]
[endsect]

[endsect]

