route.hpp File Reference

Routes (spec 6 §20): the string form of a screen instance, <screen id>?<param>=<value>&…, written from a screen's declared params and read back against them. More...

#include <algorithm>
#include <charconv>
#include <cstddef>
#include <cstdint>
#include <expected>
#include <functional>
#include <limits>
#include <memory>
#include <optional>
#include <string>
#include <string_view>
#include <system_error>
#include <utility>
#include <vector>
#include "../util/rational.hpp"
#include "document.hpp"
#include "value.hpp"

Go to the source code of this file.

Classes
struct	morph::ui::Route
	A route read back: the screen and its params. More...

Functions
constexpr bool	morph::ui::detail::route::unreserved (char byte) noexcept
	Whether a byte is an RFC 3986 unreserved character, written as is in a route.
std::string	morph::ui::detail::route::encode (std::string_view text)
	Percent-encodes every byte that is not an RFC 3986 unreserved character.
constexpr int	morph::ui::detail::route::hexDigit (char digit) noexcept
	The value of a hexadecimal digit.
std::optional< std::string >	morph::ui::detail::route::decode (std::string_view text)
	Decodes XX escapes.
std::optional< std::int64_t >	morph::ui::detail::route::integer (std::string_view text)
	Reads a whole decimal integer.
std::optional< std::string >	morph::ui::detail::route::textOf (Type const &type, Value const &value)
	The canonical text of a param's value.
std::optional< Value >	morph::ui::detail::route::valueOf (Type const &type, std::string_view text)
	Reads a param's text.
std::expected< std::string, std::string >	morph::ui::routeOf (std::string_view screen, std::vector< std::pair< std::string, Type > > const &declared, ValueRecord const &params)
	Writes the route of a screen instance: its id, then each param the screen declares that params gives, in declaration order, as name=value joined by & after a ?.
std::expected< std::string, std::string >	morph::ui::routeOf (Document const &document, ValueRecord const &params)
	Writes the route of a mounted document's instance: routeOf with the document's id and declared params.
std::expected< Route, std::string >	morph::ui::parseRoute (std::string_view route, std::function< std::shared_ptr< Document const >(std::string_view)> const &lookup)
	Reads a route back against the screen it names.

Detailed Description

Routes (spec 6 §20): the string form of a screen instance, <screen id>?<param>=<value>&…, written from a screen's declared params and read back against them.

Specified in docs/spec/ui/host.md.

Definition in file route.hpp.

Function Documentation

unreserved()

bool morph::ui::detail::route::unreserved ( char byte )

nodiscardconstexprnoexcept

Whether a byte is an RFC 3986 unreserved character, written as is in a route.

Parameters

byte

The byte.

Returns

It.

Definition at line 49 of file route.hpp.

encode()

std::string morph::ui::detail::route::encode ( std::string_view text )

inlinenodiscard

Percent-encodes every byte that is not an RFC 3986 unreserved character.

Parameters

text

The text.

Returns

It, encoded.

Definition at line 57 of file route.hpp.

hexDigit()

int morph::ui::detail::route::hexDigit ( char digit )

nodiscardconstexprnoexcept

The value of a hexadecimal digit.

Parameters

digit

The digit.

Returns

0 to 15, or -1 for a byte that is not one.

Definition at line 77 of file route.hpp.

decode()

std::optional< std::string > morph::ui::detail::route::decode ( std::string_view text )

inlinenodiscard

Decodes XX escapes.

Parameters

text

The text.

Returns

It, decoded; nothing for a truncated or non-hexadecimal escape.

Definition at line 93 of file route.hpp.

integer()

std::optional< std::int64_t > morph::ui::detail::route::integer ( std::string_view text )

inlinenodiscard

Reads a whole decimal integer.

Parameters

text

The text.

Returns

The integer; nothing for anything else, an empty text and a + sign included.

Definition at line 119 of file route.hpp.

textOf()

std::optional< std::string > morph::ui::detail::route::textOf ( Type const & type, Value const & value )

inlinenodiscard

The canonical text of a param's value.

Parameters

type	The param's declared type.
value	The value.

Returns

The text; nothing for a type with no route form, or a value not of the type.

Definition at line 133 of file route.hpp.

valueOf()

std::optional< Value > morph::ui::detail::route::valueOf ( Type const & type, std::string_view text )

inlinenodiscard

Reads a param's text.

Parameters

type	The param's declared type.
text	The text.

Returns

The value; nothing when the text does not parse as the type.

Definition at line 178 of file route.hpp.

routeOf() [1/2]

std::expected< std::string, std::string > morph::ui::routeOf ( std::string_view screen, std::vector< std::pair< std::string, Type > > const & declared, ValueRecord const & params )

inlinenodiscard

Writes the route of a screen instance: its id, then each param the screen declares that params gives, in declaration order, as name=value joined by & after a ?.

A param's value is the canonical text of its declared type: an int in decimal, a bool as true or false, a decimal as num/den@dp (the canonical fraction and the places), a key as i:<int64> or s:<text>, and a string percent-encoded (every byte but RFC 3986's unreserved characters). A null or absent optional is left out. quantity, timestamp, list and record params have no route form.

Parameters

screen	The screen id.
declared	The screen's declared params (Document::params), in order.
params	The params of this instance.

Returns

The route, or why the instance has none: a param of a type with no route form, a required param that is missing or null, or a value that does not have its declared type.

Definition at line 248 of file route.hpp.

routeOf() [2/2]

std::expected< std::string, std::string > morph::ui::routeOf ( Document const & document, ValueRecord const & params )

inlinenodiscard

Writes the route of a mounted document's instance: routeOf with the document's id and declared params.

Parameters

document	The document.
params	The params of this instance.

Returns

The route, or why it has none.

Definition at line 277 of file route.hpp.

parseRoute()

std::expected< Route, std::string > morph::ui::parseRoute ( std::string_view route, std::function< std::shared_ptr< Document const >(std::string_view)> const & lookup )

inlinenodiscard

Reads a route back against the screen it names.

Refused, with the route and the reason: a screen lookup does not know, a param the screen does not declare or gives twice, a value that does not parse as its declared type, and a required param that is missing.

Parameters

route	The route text.
lookup	The document of a screen id, or null for an unknown one.

Returns

The screen and its params, or why the route is refused.

Definition at line 289 of file route.hpp.