The UI document interpreter: Interpreter::mount turns a loaded Document into reactive state and a view tree, mounts it through Mounted on any IViewBackend, and runs its queries, mutations, relations and commands. Model calls go through a Dispatcher (the bridge's model-free seams in an application, a scripted fake in a test); what only the application can do goes through an InterpreterHost; what screens share — the query cache, the principal's permissions, the formatting facts — is a Session. More...

#include <algorithm>
#include <charconv>
#include <chrono>
#include <cstddef>
#include <cstdint>
#include <deque>
#include <exception>
#include <expected>
#include <format>
#include <functional>
#include <limits>
#include <map>
#include <memory>
#include <optional>
#include <ranges>
#include <set>
#include <span>
#include <stdexcept>
#include <string>
#include <string_view>
#include <utility>
#include <variant>
#include <vector>
#include "../core/backend.hpp"
#include "../core/bridge.hpp"
#include "../core/completion.hpp"
#include "../core/wire.hpp"
#include "../forms/engine/collection.hpp"
#include "../forms/engine/collection_view.hpp"
#include "../forms/engine/field_model.hpp"
#include "../forms/engine/form_session.hpp"
#include "../forms/engine/form_view.hpp"
#include "../forms/engine/wizard.hpp"
#include "../forms/engine/wizard_view.hpp"
#include "../reactive/runtime.hpp"
#include "../reactive/scheduler.hpp"
#include "../reactive/scope.hpp"
#include "../reactive/signal.hpp"
#include "../ui/backend.hpp"
#include "dev_tools.hpp"
#include "document.hpp"
#include "expression.hpp"
#include "message.hpp"
#include "mount.hpp"
#include "value.hpp"
#include "view.hpp"

Classes
struct	morph::ui::CallOptions
	How one model call is sent. More...
class	morph::ui::ModelChannel
	One bound model alias: the instance a document's alias names, and the calls made through it. More...
class	morph::ui::Dispatcher
	The interpreter's view of the bridge: binds a model by its type id, privately or to a shared instance. More...
class	morph::ui::BridgeDispatcher
	A Dispatcher over the bridge's model-free seams: bindByType, executeRaw and the string-keyed attach, through RawHandler. More...
struct	morph::ui::NavigateRequest
	What navigate asks the host to open (spec 6 §16, §20). More...
struct	morph::ui::UploadRequest
	What an upload command asks the host to send, and the mutation that will reference the file, which is what the server authorises the upload as (spec 6 §18). More...
struct	morph::ui::InlineFile
	A file whose bytes a document moves inline: download from bytes, upload into bytes. More...
class	morph::ui::InterpreterHost
	What the application answers for the commands a document cannot carry out alone (spec 6). Every default answers "not supported", which the interpreter reports as a diagnostic. More...
struct	morph::ui::SessionOptions
	What a Session is built with. More...
struct	morph::ui::detail::OptimisticLayer
	One optimistic write still waiting for its reply. More...
struct	morph::ui::detail::CacheEntry
	One entry of the session's query cache (spec 5 §5): one request in flight, one value, one error. More...
struct	morph::ui::detail::Marks
	The entries one change marks stale, each once, in the order they were found. More...
struct	morph::ui::HostCommandResult
	What running a host command (host/1) did. More...
struct	morph::ui::HostCommands
	The client's host commands, as a session runs them (spec 6 §14). More...
class	morph::ui::Session
	What screens of one client session share (spec 5 §5, §12b): the query cache, the mounted queries, the principal's permitted actions, the formatting facts and the client's env, session and host values. More...
struct	morph::ui::BorrowedModel
	A model the opener lends to a screen whose alias says {"from": alias} (spec 6 §16). More...
struct	morph::ui::LoggedCommand
	One command of a command list the inspector's log shows (spec 6 §21). More...
struct	morph::ui::CommandLogEntry
	One command list as it ran: the event that ran it, its commands, and the reactive batch they ran in. More...
struct	morph::ui::MountOptions
	What Interpreter::mount is given beside the document. More...
struct	morph::ui::detail::Binding
	A name bound for the expressions of one place: a command's event, a step's as, result in a patch, body in an optimistic, props in a fallback, boundary in a boundary's error. More...
struct	morph::ui::detail::StateSlot
	One state declaration at run time. More...
struct	morph::ui::detail::ModelAlias
	One model alias at run time: the instance it names, and the channel bound to it. More...
struct	morph::ui::detail::TransferState
	The values of an upload transfer id (spec 6 §18). More...
struct	morph::ui::detail::ElementState
	An element's live values (spec 5 §6). More...
struct	morph::ui::detail::CheckRuntime
	One check at run time. More...
struct	morph::ui::detail::NameRef
	One declared name of a run-time scope. More...
struct	morph::ui::detail::BoundaryRuntime
	A boundary at run time: the queries it owns (spec 5 §9). More...
class	morph::ui::detail::RtScope
	One document scope at run time: the screen, a dialog's or drawer's content, a switch case or a row. More...
class	morph::ui::detail::ScopeEnv
	The Environment the evaluator reads through: a scope chain and the names bound at one place. More...
class	morph::ui::detail::QueryRuntime
	A query at run time (spec 5 §5): a key over the scope, an entry of the session's cache, latest wins. More...
class	morph::ui::detail::MutationRuntime
	A mutation at run time (spec 5 §5): concurrency, optimistic writes and the reply's effects. More...
struct	morph::ui::InterpreterOptions
	What an Interpreter is built with. More...
struct	morph::ui::detail::CommandCtx
	Where a command list runs: its scope, the names bound there, and what it may answer. More...
struct	morph::ui::detail::LowerCtx
	Where a node is lowered: its scope, the names bound there and the boundary that owns its queries. More...
struct	morph::ui::detail::ActionModel
	An actionButton part, lowered in the scope of the list it belongs to: what a screen's head shows and an overlay's footer draws as buttons. More...
struct	morph::ui::detail::BadgeModel
	A headBadge part, lowered in the screen scope. More...
class	morph::ui::detail::ScreenCore
	One mounted screen's interpreter: its document, diagnostics, slots and preferences, and the code that declares scopes, lowers nodes and runs commands. More...
struct	morph::ui::detail::ScreenCore::KeptState
	A state of the screen this one replaces: its declared type's name and its value. More...
struct	morph::ui::detail::ScreenCore::LoweredNode
	A node as it was lowered, which the inspector lists while its scope lives. More...
struct	morph::ui::HeadBadge
	A status badge of a screen's head, as its handle answers it. More...
struct	morph::ui::HeadAction
	An action of a screen's head, as its handle answers it. More...
class	morph::ui::Screen
	A mounted screen: its scopes, its view mounted through Mounted, and what its host asks of it. More...
class	morph::ui::AppRoot
	The app document mounted as the root scope every screen of the session shares (spec 6 §5). More...
class	morph::ui::Interpreter
	Mounts UI documents (spec 5): one per client process or window, over a session and a dispatcher. More...
struct	morph::ui::detail::DateReading
	What a date input reads from a value: the instant it shows, and whether the value names one at all. More...
class	morph::ui::detail::TransferHold
	A transfer's share of its screen's pending count. More...
struct	morph::ui::detail::DetachedLower
	A lowering context whose scope is held weakly: what an Effect the scope itself owns may keep, so the scope does not keep itself alive. More...
struct	morph::ui::detail::ArrangedChild
	One child of an arranged container, as the user's choice places it. More...

Typedefs
using	morph::ui::Evaluator
	Evaluates an action body without running it: the model's type id, the action id and the JSON body in, the query's value out (spec 5 §7). ui::evaluatorOver builds one over the UI service's ui-evaluate.
using	morph::ui::Watcher = std::function<async::Completion<std::string>(std::string const& kind, std::string const& bodyJson)>
	Sends a watch or unwatch request for a session's cache (spec 8 §7): the kind, and the WatchBody as JSON. ui::watcherOver builds one over a remote source's exchange.
using	morph::ui::detail::RowsByKey = std::map<std::string, Value const*, std::less<>>
	New rows by the canonical text of their key.
using	morph::ui::detail::Bindings = std::vector<Binding>
	The names bound at one place, innermost last.
using	morph::ui::detail::RunDone = std::function<void(bool succeeded, Value const& reply)>
	One run of a mutation, as a command sees it: whether it succeeded, and the reply.
using	morph::ui::detail::Done = std::function<void(bool)>
	Called once when a command finishes: whether it succeeded.
using	morph::ui::detail::ActionModels = std::vector<ActionModel>
	A list of lowered actionButton parts, in document order.

Enumerations
enum class	morph::ui::detail::PatchMiss : std::uint8_t { NoList , NoRow }
	Why a patch left a query's value as it was. More...
enum class	morph::ui::ReplyUse : std::uint8_t { Applied , Discarded }
	How a mutation's reply was used. More...

Functions
std::string	morph::ui::detail::failureText (std::exception_ptr const &error)
	The text of a failure.
std::string	morph::ui::detail::defaultErrorKind (std::exception_ptr const &error)
	The default error kinds: the bridge's own failures, and error for the rest.
std::string	morph::ui::detail::canonicalJson (Value const &value)
	A value's JSON text, with record fields in name order: a cache key's canonical body.
Value	morph::ui::detail::withPath (Value const &base, std::span< std::string const > path, Value value)
	A value with the field at `path` replaced, creating records along the way.
Value	morph::ui::detail::rowId (Value const &row)
	A row's identity for patch and optimistic: its id field.
Value	morph::ui::detail::mergeRow (Value const &row, Value const &with)
	Writes `with` over a row: the fields of a record over a record's, otherwise the whole row.
std::expected< Value, PatchMiss >	morph::ui::detail::patchRows (Value const &value, std::string_view listMember, Value const &key, Value const &with)
	Replaces the row whose id equals `key` in a query's list of rows.
std::string	morph::ui::detail::patchMissReason (std::string_view query, std::string_view listMember)
	What a patch that found no list reports.
Value	morph::ui::detail::withoutFields (Value const &value, std::vector< std::string > const &fields)
	Removes the named fields from a record, and from each record of a list.
std::vector< std::string >	morph::ui::detail::pathMembers (std::string_view path)
	The members of a catalog record path: "header.rows" is header, then rows; "" is none.
void	morph::ui::detail::keyedRowsAt (Value const &value, std::span< std::string const > path, std::string_view keyField, std::vector< Value const * > &out)
	The rows of a keyed record that a value holds at a path.
std::optional< Value >	morph::ui::detail::patchKeyedRows (Value const &value, std::span< std::string const > path, std::string_view keyField, RowsByKey const &rows)
	Merges new rows over the rows with the same key that a value holds at a path.
std::vector< Value const * >	morph::ui::detail::keyedRowsOf (Value const &value, std::vector< std::string > const &paths, std::string_view keyField)
	The rows of a keyed record a value holds, at each of the record's paths.
std::optional< Value >	morph::ui::detail::patchHeldRows (Value const &value, std::vector< std::string > const &paths, std::string_view keyField, RowsByKey const &rows)
	Merges new rows into a value at each of the record's paths.
Value	morph::ui::detail::evalIn (RtScope const &scope, Bindings const *bindings, ExprPtr const &expr)
	Evaluates an expression in a scope.
bool	morph::ui::detail::engaged (Value const &value)
	Whether a value counts as given for required: not null, not an empty string or list.
std::string	morph::ui::detail::textOf (Value const &value, FormatContext const &format)
	A value as text for a widget: a string as itself, a number in the locale, a timestamp in ISO 8601, null as nothing, anything else as JSON.
Key	morph::ui::detail::keyOf (Value const &value)
	A value as a view key: an int or a string as itself, anything else as its JSON text.
Value	morph::ui::detail::valueOfKey (Key const &key)
	A view key as a value.
std::vector< std::string >	morph::ui::detail::stringsOf (Value const &value)
	A list of strings out of a value: a string, a list of strings, or nothing.
Value	morph::ui::detail::listOfStrings (std::vector< std::string > const &texts)
	A list of strings as a value.
CommandCtx	morph::ui::detail::detached (CommandCtx const &ctx)
	A command context without its scope: what a callback the host keeps may hold, so that the host never keeps a scope alive past its screen. The callback holds the scope weakly and puts it back.
KeySpec const *	morph::ui::detail::keySpec (KindSpec const &kind, std::string_view key)
	A kind's key spec, from the kind table.
bool	morph::ui::detail::statefulKind (std::string_view kind)
	Whether a node kind keeps per-element state even without an id: the inputs, dialogs, tables and the forms engine's screens.
std::string	morph::ui::detail::commandKey (CommandKind kind)
	The key a command is written with.
std::string	morph::ui::detail::instanceKeyText (Value const &key)
	The text of an instance key, as the bridge's string-keyed attach takes it.
std::shared_ptr< ModelChannel >	morph::ui::detail::channelOf (ModelAlias &alias, ScreenCore &core)
	The channel an alias is bound to for its current token, binding it when the token changed.
ElementState *	morph::ui::detail::elementFor (RtScope const &scope, DocNode const &node)
	The element a node of a scope keeps its state in.
void	morph::ui::detail::transfersOf (Commands const &commands, std::vector< std::string > &out)
	The transfers of the upload commands in a list, nested lists included.
DateReading	morph::ui::detail::dateInstantOf (Value const &value, std::int32_t offsetMinutes)
	Reads what a date input shows for `value`, in a display zone `offsetMinutes` from UTC.
std::string	morph::ui::detail::dateTextOf (time::DateTime const &instant, std::int32_t offsetMinutes)
	A date input's date text for `instant` in a display zone `offsetMinutes` from UTC.
bool	morph::ui::detail::sameShown (std::string_view kind, Value const &lhs, Value const &rhs, FormatContext const &format)
	Whether two values show the same in an input: by text for a text input, by instant for a date input, by value otherwise.
Value	morph::ui::detail::optionKey (Value const &option)
	The key of a select option: a record's key, id or value field, or the option itself.
Value	morph::ui::detail::jsonTextValue (std::string_view text)
	A JSON text as a document value; null when it is not JSON or holds what a value cannot (a fraction).
Value	morph::ui::detail::formFieldValue (forms::FieldState const &field)
	One field of a form as a record: value (the encoded value, null while blank or invalid), draft (the text), valid, required, visible, readonly and errors. Tracked.
Value	morph::ui::detail::formValue (ElementState const &element, std::string_view name)
	A form's element values (spec 5 §6): ready, body (the record the form would submit, null while not ready), submitted (whether a submission was sent), pending, and each field by its wire name. Tracked.
std::string	morph::ui::detail::base64Encode (std::string_view bytes)
	Bytes as base64 (RFC 4648, with padding): how a document carries an inline file.
std::optional< std::string >	morph::ui::detail::base64Decode (std::string_view text)
	Base64 text as bytes (RFC 4648, with or without padding).
std::size_t	morph::ui::detail::base64Size (std::string_view text)
	How many bytes base64 text decodes to, read from its length alone.
std::string	morph::ui::detail::sizeText (std::size_t bytes)
	A byte count as a person reads it: 512 bytes, 2.4 KiB, 1 MiB.
std::expected< std::string, std::string >	morph::ui::detail::inlineBytes (Value const &value)
	A document's inline file content as bytes: base64 text, or a list of integers 0 to 255.
bool	morph::ui::detail::boolOf (Value const &value, FormatContext const &format)
	A value as a bool property: true only for true.
std::string	morph::ui::detail::stringOf (Value const &value, FormatContext const &format)
	A value as a text property.
std::string	morph::ui::detail::componentText (Value const &value, std::string_view type, FormatContext const &format)
	A value as a custom component's text prop (spec 5 §10): an int or exact as plain decimal text, so no id or amount loses precision; json as its JSON text; string as the formatted text.
double	morph::ui::detail::componentNumber (Value const &value)
	A value as a custom component's number prop: the one kind that crosses as a double.
Value	morph::ui::detail::componentPayload (std::string const &payload, Type const *type)
	A custom component's event payload as a value: i:<int64> an int, s:<text> a string, anything else JSON text read as the event's declared type, and text that is none of those a string.
std::int64_t	morph::ui::detail::intOf (Value const &value, std::int64_t fallback)
	A value as an integer: an int, or a decimal truncated toward zero.
std::optional< TextRole >	morph::ui::detail::roleNamed (std::string_view name)
	A text role by name.
TextRole	morph::ui::detail::roleOf (Value const &value, FormatContext const &format)
	A text role by name, as roleNamed reads it.
Tone	morph::ui::detail::toneOf (Value const &value, FormatContext const &format)
	A tone by name.
Sizing	morph::ui::detail::sizingOf (Value const &value)
	A sizing by its document form: "content", {"fixed": n} or {"stretch": w}.
bool	morph::ui::detail::isSizing (Value const &value)
	Whether a value is a sizing of one dimension: "content", {"fixed": n} or {"stretch": w}.
Align	morph::ui::detail::alignOf (std::string_view name)
	An alignment by name, as the loader checked it: start, center, end, or stretch for none.
Justify	morph::ui::detail::justifyOf (std::string_view name)
	A justification by name, as the loader checked it: center, end, between, or start for none.
Axis	morph::ui::detail::axisOf (Value const &value)
	An axis by name: horizontal, or vertical for anything else.
StepState	morph::ui::detail::stepStateOf (std::string_view name)
	A step's state by name: active, done, failed, or pending for anything else.
std::vector< SelectOption >	morph::ui::detail::selectOptions (Value const &options, FormatContext const &format)
	The options of a select, from a list of scalars or of records with a key and a label.
Node	morph::ui::detail::lazy (std::function< Node()> build)
	Content whose scope is made when it mounts and released when it unmounts: a one-row forEach whose row view builds it.
Node	morph::ui::detail::holding (std::vector< Node > children, std::shared_ptr< RtScope > scope, std::vector< KeyBinding > keys={})
	A column of content that holds its scope for as long as it is mounted: its visible is a binding that keeps the scope alive and reads nothing.
forms::FieldOverlay	morph::ui::detail::overlayOf (RtScope const &scope, DocNode const &part, FormatContext const &format)
	A document field overlay's expressions, evaluated once, as the engine's overlay.
DetachedLower	morph::ui::detail::detachedLower (LowerCtx const &ctx)
	Detaches a lowering context's scope.
LowerCtx	morph::ui::detail::attached (DetachedLower const &held)
	Puts a detached context's scope back.
std::expected< forms::detail::engine::Json, std::string >	morph::ui::detail::changeWire (std::string const &payload, std::string_view type)
	A component's change payload as the wire value of the field it draws, read as the value prop's declared type.
std::function< Value()>	morph::ui::detail::formFilled (std::string const &prop, forms::FieldState *state)
	What a form fills of a field component's props: the field's value, errors, read-only and required state, and label, each a tracked read of the field.
std::vector< ArrangedChild >	morph::ui::detail::arrangedChildren (Value const &stored, std::span< DocNode const *const > declared)
	A container's children in the order a stored arrange choice gives, each marked shown or hidden.
std::vector< Value >	morph::ui::detail::arrangedOrder (Value const &stored, std::span< DocNode const *const > declared)
	The ids of the children an arrange choice shows, in its order (arrangedChildren, without the hidden).
Value	morph::ui::detail::arrangementValue (std::vector< ArrangedChild > const &children)
	An arrangement as the choice an arrange point stores.
DocNode const *	morph::ui::detail::elementNode (DocNode const &node, std::string_view elementId)
	The element of a document tree with `elementId`.

Variables
constexpr std::size_t	morph::ui::kDefaultInlineFileBytes = std::size_t{1024} * 1024
	The inline cap a session has unless it is given another: 1 MiB.
constexpr std::size_t	morph::ui::kMaxInlineFileBytes = (wire::kMaxEnvelopeBytes - (std::size_t{64} * 1024)) * 3 / 4
	The largest inline cap a session takes: base64 grows bytes by 4/3, and 64 KiB of an envelope are left for the rest of the body, so the encoded file still fits wire::kMaxEnvelopeBytes.
constexpr std::size_t	morph::ui::detail::kCommandLogSize = 256
	How many command lists the inspector's log keeps.
constexpr std::size_t	morph::ui::detail::kPruneLoweredAt = 256
	How often, in lowered nodes, the inspector's node list drops the nodes whose scope is gone.

Detailed Description

The UI document interpreter: Interpreter::mount turns a loaded Document into reactive state and a view tree, mounts it through Mounted on any IViewBackend, and runs its queries, mutations, relations and commands. Model calls go through a Dispatcher (the bridge's model-free seams in an application, a scripted fake in a test); what only the application can do goes through an InterpreterHost; what screens share — the query cache, the principal's permissions, the formatting facts — is a Session.

Definition in file interpreter.hpp.

Typedef Documentation

◆ Evaluator

using morph::ui::Evaluator

Initial value:

std::function<async::Completion<std::string>(std::string const& typeId, std::string const& actionId,

std::string const& bodyJson)>

Evaluates an action body without running it: the model's type id, the action id and the JSON body in, the query's value out (spec 5 §7). ui::evaluatorOver builds one over the UI service's ui-evaluate.

Definition at line 114 of file interpreter.hpp.

◆ Watcher

using morph::ui::Watcher = std::function<async::Completion<std::string>(std::string const& kind, std::string const& bodyJson)>

Sends a watch or unwatch request for a session's cache (spec 8 §7): the kind, and the WatchBody as JSON. ui::watcherOver builds one over a remote source's exchange.

Definition at line 418 of file interpreter.hpp.

◆ RowsByKey

using morph::ui::detail::RowsByKey = std::map<std::string, Value const*, std::less<>>

New rows by the canonical text of their key.

Definition at line 670 of file interpreter.hpp.

◆ Bindings

using morph::ui::detail::Bindings = std::vector<Binding>

The names bound at one place, innermost last.

Definition at line 1472 of file interpreter.hpp.

◆ RunDone

using morph::ui::detail::RunDone = std::function<void(bool succeeded, Value const& reply)>

One run of a mutation, as a command sees it: whether it succeeded, and the reply.

Definition at line 2013 of file interpreter.hpp.

◆ Done

using morph::ui::detail::Done = std::function<void(bool)>

Called once when a command finishes: whether it succeeded.

Definition at line 2130 of file interpreter.hpp.

◆ ActionModels

using morph::ui::detail::ActionModels = std::vector<ActionModel>

A list of lowered actionButton parts, in document order.

Definition at line 2164 of file interpreter.hpp.

Enumeration Type Documentation

◆ PatchMiss

enum class morph::ui::detail::PatchMiss : std::uint8_t

strong

Why a patch left a query's value as it was.

Enumerator
NoList	The value, or its at member, is not a list: the patch can never apply, and is reported.
NoRow	No row's id equals the key: the row is not loaded, which is not a fault.

Definition at line 531 of file interpreter.hpp.

◆ ReplyUse

enum class morph::ui::ReplyUse : std::uint8_t

strong

How a mutation's reply was used.

Enumerator
Applied	The reply is the latest: its values may patch the cache.
Discarded	A newer run's reply was applied first, so its values are older and only mark.

Definition at line 856 of file interpreter.hpp.

Function Documentation

◆ failureText()

std::string morph::ui::detail::failureText ( std::exception_ptr const & error )

inlinenodiscard

The text of a failure.

Parameters

error The failure.

Returns: what(), or unknown error.

Definition at line 450 of file interpreter.hpp.

◆ defaultErrorKind()

std::string morph::ui::detail::defaultErrorKind ( std::exception_ptr const & error )

inlinenodiscard

The default error kinds: the bridge's own failures, and error for the rest.

Parameters

error The failure.

Returns: The kind.

Definition at line 463 of file interpreter.hpp.

◆ canonicalJson()

std::string morph::ui::detail::canonicalJson ( Value const & value )

inlinenodiscard

A value's JSON text, with record fields in name order: a cache key's canonical body.

Parameters

value The value.

Returns: The text.

Definition at line 482 of file interpreter.hpp.

◆ withPath()

Value morph::ui::detail::withPath	(	Value const &	base,
		std::span< std::string const >	path,
		Value	value )

inlinenodiscard

A value with the field at path replaced, creating records along the way.

Parameters

base	The value written into.
path	The field path.
value	The new value at the path.

Returns: The new value.

Definition at line 492 of file interpreter.hpp.

◆ rowId()

Value morph::ui::detail::rowId ( Value const & row )

inlinenodiscard

A row's identity for patch and optimistic: its id field.

Parameters

row The row.

Returns: The id field, or null.

Definition at line 508 of file interpreter.hpp.

◆ mergeRow()

Value morph::ui::detail::mergeRow	(	Value const &	row,
		Value const &	with )

inlinenodiscard

Writes with over a row: the fields of a record over a record's, otherwise the whole row.

Parameters

row	The row.
with	The new content.

Returns: The new row.

Definition at line 517 of file interpreter.hpp.

◆ patchRows()

std::expected< Value, PatchMiss > morph::ui::detail::patchRows	(	Value const &	value,
		std::string_view	listMember,
		Value const &	key,
		Value const &	with )

inlinenodiscard

Replaces the row whose id equals key in a query's list of rows.

Parameters

value	The query's value: the list itself, or a record holding it in member `listMember`.
listMember	The record member holding the list; empty when `value` is the list.
key	The row's id.
with	The new content, merged over the row.

Returns: The new value, or why it is unchanged.

Definition at line 543 of file interpreter.hpp.

◆ patchMissReason()

std::string morph::ui::detail::patchMissReason	(	std::string_view	query,
		std::string_view	listMember )

inlinenodiscard

What a patch that found no list reports.

Parameters

query	The query it patches.
listMember	The record member it names; empty when none.

Returns: The diagnostic's reason.

Definition at line 581 of file interpreter.hpp.

◆ withoutFields()

Value morph::ui::detail::withoutFields	(	Value const &	value,
		std::vector< std::string > const &	fields )

inlinenodiscard

Removes the named fields from a record, and from each record of a list.

Parameters

value	The value.
fields	The field names.

Returns: The value without them.

Definition at line 595 of file interpreter.hpp.

◆ pathMembers()

std::vector< std::string > morph::ui::detail::pathMembers ( std::string_view path )

inlinenodiscard

The members of a catalog record path: "header.rows" is header, then rows; "" is none.

Parameters

path The path.

Returns: Its members in order.

Definition at line 620 of file interpreter.hpp.

◆ keyedRowsAt()

void morph::ui::detail::keyedRowsAt	(	Value const &	value,
		std::span< std::string const >	path,
		std::string_view	keyField,
		std::vector< Value const * > &	out )

inline

The rows of a keyed record that a value holds at a path.

A list on the way is looked through, as the result walker looks through a std::vector. At the path's end a record with the key field is a row, and a record without it is a map whose values are the rows.

Parameters

value	The value.
path	The members still to follow.
keyField	The record's key field.
out	Where the rows go.

Definition at line 639 of file interpreter.hpp.

◆ patchKeyedRows()

std::optional< Value > morph::ui::detail::patchKeyedRows	(	Value const &	value,
		std::span< std::string const >	path,
		std::string_view	keyField,
		RowsByKey const &	rows )

inlinenodiscard

Merges new rows over the rows with the same key that a value holds at a path.

Parameters

value	The value.
path	The members still to follow.
keyField	The record's key field.
rows	The new rows.

Returns: The new value, or nothing when no row matched.

Definition at line 679 of file interpreter.hpp.

◆ keyedRowsOf()

std::vector< Value const * > morph::ui::detail::keyedRowsOf	(	Value const &	value,
		std::vector< std::string > const &	paths,
		std::string_view	keyField )

inlinenodiscard

The rows of a keyed record a value holds, at each of the record's paths.

Parameters

value	The value.
paths	The record's paths.
keyField	The record's key field.

Returns: The rows.

Definition at line 805 of file interpreter.hpp.

◆ patchHeldRows()

std::optional< Value > morph::ui::detail::patchHeldRows	(	Value const &	value,
		std::vector< std::string > const &	paths,
		std::string_view	keyField,
		RowsByKey const &	rows )

inlinenodiscard

Merges new rows into a value at each of the record's paths.

Parameters

value	The value.
paths	The record's paths.
keyField	The record's key field.
rows	The new rows by key.

Returns: The new value, or nothing when no row matched.

Definition at line 821 of file interpreter.hpp.

◆ evalIn()

Value morph::ui::detail::evalIn	(	RtScope const &	scope,
		Bindings const *	bindings,
		ExprPtr const &	expr )

inlinenodiscard

Evaluates an expression in a scope.

Parameters

scope	The scope.
bindings	The names bound here; may be nullptr.
expr	The expression; nullptr evaluates to null.

Returns: The value.

Definition at line 1797 of file interpreter.hpp.

◆ engaged()

bool morph::ui::detail::engaged ( Value const & value )

inlinenodiscard

Whether a value counts as given for required: not null, not an empty string or list.

Parameters

value The value.

Returns: It.

Definition at line 1808 of file interpreter.hpp.

◆ textOf()

std::string morph::ui::detail::textOf	(	Value const &	value,
		FormatContext const &	format )

inlinenodiscard

A value as text for a widget: a string as itself, a number in the locale, a timestamp in ISO 8601, null as nothing, anything else as JSON.

Parameters

value	The value.
format	The formatting facts.

Returns: The text.

Definition at line 1826 of file interpreter.hpp.

◆ keyOf()

Key morph::ui::detail::keyOf ( Value const & value )

inlinenodiscard

A value as a view key: an int or a string as itself, anything else as its JSON text.

Parameters

value The value.

Returns: The key.

Definition at line 1852 of file interpreter.hpp.

◆ valueOfKey()

Value morph::ui::detail::valueOfKey ( Key const & key )

inlinenodiscard

A view key as a value.

Parameters

key The key.

Returns: An int or a string.

Definition at line 1865 of file interpreter.hpp.

◆ stringsOf()

std::vector< std::string > morph::ui::detail::stringsOf ( Value const & value )

inlinenodiscard

A list of strings out of a value: a string, a list of strings, or nothing.

Parameters

value The value.

Returns: The strings.

Definition at line 1875 of file interpreter.hpp.

◆ listOfStrings()

Value morph::ui::detail::listOfStrings ( std::vector< std::string > const & texts )

inlinenodiscard

A list of strings as a value.

Parameters

texts The strings.

Returns: The list.

Definition at line 1892 of file interpreter.hpp.

◆ detached()

CommandCtx morph::ui::detail::detached ( CommandCtx const & ctx )

inlinenodiscard

A command context without its scope: what a callback the host keeps may hold, so that the host never keeps a scope alive past its screen. The callback holds the scope weakly and puts it back.

Parameters

ctx	The context.

Returns: The context, its scope dropped.

Definition at line 2123 of file interpreter.hpp.

◆ keySpec()

KeySpec const * morph::ui::detail::keySpec	(	KindSpec const &	kind,
		std::string_view	key )

inlinenodiscard

A kind's key spec, from the kind table.

Parameters

kind	The kind spec.
key	The key.

Returns: The spec, or nullptr when the kind has no such key of its own.

Definition at line 2182 of file interpreter.hpp.

◆ statefulKind()

bool morph::ui::detail::statefulKind ( std::string_view kind )

inlinenodiscard

Whether a node kind keeps per-element state even without an id: the inputs, dialogs, tables and the forms engine's screens.

Parameters

kind The kind.

Returns: It.

Definition at line 2195 of file interpreter.hpp.

◆ commandKey()

std::string morph::ui::detail::commandKey ( CommandKind kind )

inlinenodiscard

The key a command is written with.

Parameters

kind	The command's kind.

Returns: Its key, such as refetch.

Definition at line 2211 of file interpreter.hpp.

◆ instanceKeyText()

std::string morph::ui::detail::instanceKeyText ( Value const & key )

inlinenodiscard

The text of an instance key, as the bridge's string-keyed attach takes it.

Parameters

key	The key's value.

Returns: The text; empty for null.

Definition at line 3332 of file interpreter.hpp.

◆ channelOf()

std::shared_ptr< ModelChannel > morph::ui::detail::channelOf	(	ModelAlias &	alias,
		ScreenCore &	core )

inlinenodiscard

The channel an alias is bound to for its current token, binding it when the token changed.

Parameters

alias	The alias.
core	The screen.

Returns: The channel, or nullptr while the alias is unbound.

Definition at line 3349 of file interpreter.hpp.

◆ elementFor()

ElementState * morph::ui::detail::elementFor	(	RtScope const &	scope,
		DocNode const &	node )

inlinenodiscard

The element a node of a scope keeps its state in.

Parameters

scope	The scope that declares it.
node	The node.

Returns: The element, or nullptr for a node that keeps none.

Definition at line 3954 of file interpreter.hpp.

◆ transfersOf()

void morph::ui::detail::transfersOf	(	Commands const &	commands,
		std::vector< std::string > &	out )

inline

The transfers of the upload commands in a list, nested lists included.

Parameters

commands	The list.
out	Where the transfer ids go.

Definition at line 3967 of file interpreter.hpp.

◆ dateInstantOf()

DateReading morph::ui::detail::dateInstantOf	(	Value const &	value,
		std::int32_t	offsetMinutes )

inlinenodiscard

Reads what a date input shows for value, in a display zone offsetMinutes from UTC.

A timestamp is its instant; a yyyy-MM-dd string is midnight of that date in the display zone; a string DateTime::fromIso8601 reads is its instant; null and "" are empty. Any other value is empty and unreadable.

Parameters

value	The value.
offsetMinutes	The display zone's offset from UTC, in minutes.

Returns: The instant, or nothing, and whether the value was readable.

Definition at line 4213 of file interpreter.hpp.

◆ dateTextOf()

std::string morph::ui::detail::dateTextOf	(	time::DateTime const &	instant,
		std::int32_t	offsetMinutes )

inlinenodiscard

A date input's date text for instant in a display zone offsetMinutes from UTC.

Parameters

instant	The instant.
offsetMinutes	The display zone's offset from UTC, in minutes.

Returns: yyyy-MM-dd.

Definition at line 4245 of file interpreter.hpp.

◆ sameShown()

bool morph::ui::detail::sameShown	(	std::string_view	kind,
		Value const &	lhs,
		Value const &	rhs,
		FormatContext const &	format )

inlinenodiscard

Whether two values show the same in an input: by text for a text input, by instant for a date input, by value otherwise.

Parameters

kind	The input's kind.
lhs	One value.
rhs	The other.
format	The formatting facts.

Returns: It.

Definition at line 4259 of file interpreter.hpp.

◆ optionKey()

Value morph::ui::detail::optionKey ( Value const & option )

inlinenodiscard

The key of a select option: a record's key, id or value field, or the option itself.

Parameters

option The option.

Returns: The key.

Definition at line 4274 of file interpreter.hpp.

◆ jsonTextValue()

Value morph::ui::detail::jsonTextValue ( std::string_view text )

inlinenodiscard

A JSON text as a document value; null when it is not JSON or holds what a value cannot (a fraction).

Parameters

text	The JSON text.

Returns: The value.

Definition at line 4399 of file interpreter.hpp.

◆ formFieldValue()

Value morph::ui::detail::formFieldValue ( forms::FieldState const & field )

inlinenodiscard

One field of a form as a record: value (the encoded value, null while blank or invalid), draft (the text), valid, required, visible, readonly and errors. Tracked.

Parameters

field The field.

Returns: The record.

Definition at line 4412 of file interpreter.hpp.

◆ formValue()

Value morph::ui::detail::formValue	(	ElementState const &	element,
		std::string_view	name )

inlinenodiscard

A form's element values (spec 5 §6): ready, body (the record the form would submit, null while not ready), submitted (whether a submission was sent), pending, and each field by its wire name. Tracked.

Parameters

element	The form's element.
name	The value's name.

Returns: The value; null for a name the form does not have, or a form without a session.

Definition at line 4439 of file interpreter.hpp.

◆ base64Encode()

std::string morph::ui::detail::base64Encode ( std::string_view bytes )

inlinenodiscard

Bytes as base64 (RFC 4648, with padding): how a document carries an inline file.

Parameters

bytes The bytes.

Returns: The text.

Definition at line 5109 of file interpreter.hpp.

◆ base64Decode()

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

inlinenodiscard

Base64 text as bytes (RFC 4648, with or without padding).

Parameters

text The text.

Returns: The bytes, or std::nullopt for text that is not base64.

Definition at line 5132 of file interpreter.hpp.

◆ base64Size()

std::size_t morph::ui::detail::base64Size ( std::string_view text )

inlinenodiscard

How many bytes base64 text decodes to, read from its length alone.

Parameters

text The text.

Returns: The byte count.

Definition at line 5176 of file interpreter.hpp.

◆ sizeText()

std::string morph::ui::detail::sizeText ( std::size_t bytes )

inlinenodiscard

A byte count as a person reads it: 512 bytes, 2.4 KiB, 1 MiB.

Parameters

bytes The count.

Returns: The text.

Definition at line 5186 of file interpreter.hpp.

◆ inlineBytes()

std::expected< std::string, std::string > morph::ui::detail::inlineBytes ( Value const & value )

inlinenodiscard

A document's inline file content as bytes: base64 text, or a list of integers 0 to 255.

Parameters

value The value.

Returns: The bytes, or why the value is neither.

Definition at line 5205 of file interpreter.hpp.

◆ boolOf()

bool morph::ui::detail::boolOf	(	Value const &	value,
		FormatContext const &	format )

inlinenodiscard

A value as a bool property: true only for true.

Parameters

value	The value.
format	Unused.

Returns: It.

Definition at line 5437 of file interpreter.hpp.

◆ stringOf()

std::string morph::ui::detail::stringOf	(	Value const &	value,
		FormatContext const &	format )

inlinenodiscard

A value as a text property.

Parameters

value	The value.
format	The formatting facts.

Returns: Its text.

Definition at line 5447 of file interpreter.hpp.

◆ componentText()

std::string morph::ui::detail::componentText	(	Value const &	value,
		std::string_view	type,
		FormatContext const &	format )

inlinenodiscard

A value as a custom component's text prop (spec 5 §10): an int or exact as plain decimal text, so no id or amount loses precision; json as its JSON text; string as the formatted text.

Parameters

value	The value.
type	The prop type the component declares.
format	The formatting facts, for string.

Returns: The text.

Definition at line 5457 of file interpreter.hpp.

◆ componentNumber()

double morph::ui::detail::componentNumber ( Value const & value )

inlinenodiscard

A value as a custom component's number prop: the one kind that crosses as a double.

Parameters

value The value.

Returns: It; zero for anything that is not a number.

Definition at line 5481 of file interpreter.hpp.

◆ componentPayload()

Value morph::ui::detail::componentPayload	(	std::string const &	payload,
		Type const *	type )

inlinenodiscard

A custom component's event payload as a value: i:<int64> an int, s:<text> a string, anything else JSON text read as the event's declared type, and text that is none of those a string.

Parameters

payload	The payload, as the backend reports it.
type	The payload type the component declares; null for an undeclared event.

Returns: The value.

Definition at line 5499 of file interpreter.hpp.

◆ intOf()

std::int64_t morph::ui::detail::intOf	(	Value const &	value,
		std::int64_t	fallback )

inlinenodiscard

A value as an integer: an int, or a decimal truncated toward zero.

Parameters

value	The value.
fallback	What anything else gives.

Returns: It.

Definition at line 5525 of file interpreter.hpp.

◆ roleNamed()

std::optional< TextRole > morph::ui::detail::roleNamed ( std::string_view name )

inlinenodiscard

A text role by name.

Parameters

name	normal, muted, heading (or title), section, error, success.

Returns: The role; nullopt for any other name.

Definition at line 5538 of file interpreter.hpp.

◆ roleOf()

TextRole morph::ui::detail::roleOf	(	Value const &	value,
		FormatContext const &	format )

inlinenodiscard

A text role by name, as roleNamed reads it.

Parameters

value	The name.
format	Unused.

Returns: The role; Normal for any other name.

Definition at line 5564 of file interpreter.hpp.

◆ toneOf()

Tone morph::ui::detail::toneOf	(	Value const &	value,
		FormatContext const &	format )

inlinenodiscard

A tone by name.

Parameters

value	neutral, info, ok (or success), warn (or warning), err (or error).
format	Unused.

Returns: The tone; Neutral for anything else.

Definition at line 5572 of file interpreter.hpp.

◆ sizingOf()

Sizing morph::ui::detail::sizingOf ( Value const & value )

inlinenodiscard

A sizing by its document form: "content", {"fixed": n} or {"stretch": w}.

Parameters

value The value.

Returns: The sizing.

Definition at line 5592 of file interpreter.hpp.

◆ isSizing()

bool morph::ui::detail::isSizing ( Value const & value )

inlinenodiscard

Whether a value is a sizing of one dimension: "content", {"fixed": n} or {"stretch": w}.

Parameters

value The value.

Returns: Whether sizingOf reads it as written rather than as content by default.

Definition at line 5605 of file interpreter.hpp.

◆ alignOf()

Align morph::ui::detail::alignOf ( std::string_view name )

inlinenodiscard

An alignment by name, as the loader checked it: start, center, end, or stretch for none.

Parameters

name	The name; empty for none.

Returns: The alignment.

Definition at line 5617 of file interpreter.hpp.

◆ justifyOf()

Justify morph::ui::detail::justifyOf ( std::string_view name )

inlinenodiscard

A justification by name, as the loader checked it: center, end, between, or start for none.

Parameters

name	The name; empty for none.

Returns: The justification.

Definition at line 5633 of file interpreter.hpp.

◆ axisOf()

Axis morph::ui::detail::axisOf ( Value const & value )

inlinenodiscard

An axis by name: horizontal, or vertical for anything else.

Parameters

value The value.

Returns: The axis.

Definition at line 5649 of file interpreter.hpp.

◆ stepStateOf()

StepState morph::ui::detail::stepStateOf ( std::string_view name )

inlinenodiscard

A step's state by name: active, done, failed, or pending for anything else.

Parameters

name The name.

Returns: The state.

Definition at line 5657 of file interpreter.hpp.

◆ selectOptions()

std::vector< SelectOption > morph::ui::detail::selectOptions	(	Value const &	options,
		FormatContext const &	format )

inlinenodiscard

The options of a select, from a list of scalars or of records with a key and a label.

Parameters

options	The list.
format	The formatting facts.

Returns: The options.

Definition at line 5671 of file interpreter.hpp.

◆ lazy()

Node morph::ui::detail::lazy ( std::function< Node()> build )

inlinenodiscard

Content whose scope is made when it mounts and released when it unmounts: a one-row forEach whose row view builds it.

Parameters

build Builds the content, its scope included.

Returns: The node.

Definition at line 5687 of file interpreter.hpp.

◆ holding()

Node morph::ui::detail::holding	(	std::vector< Node >	children,
		std::shared_ptr< RtScope >	scope,
		std::vector< KeyBinding >	keys = {} )

inlinenodiscard

A column of content that holds its scope for as long as it is mounted: its visible is a binding that keeps the scope alive and reads nothing.

Parameters

children	The content.
scope	The scope.
keys	The chords of the content.

Returns: The node.

Definition at line 5698 of file interpreter.hpp.

◆ overlayOf()

forms::FieldOverlay morph::ui::detail::overlayOf	(	RtScope const &	scope,
		DocNode const &	part,
		FormatContext const &	format )

inlinenodiscard

A document field overlay's expressions, evaluated once, as the engine's overlay.

Parameters

scope	The scope the form is declared in.
part	The fields entry.
format	How values read as text and numbers.

Returns: The overlay.

Definition at line 6435 of file interpreter.hpp.

◆ detachedLower()

DetachedLower morph::ui::detail::detachedLower ( LowerCtx const & ctx )

inlinenodiscard

Detaches a lowering context's scope.

Parameters

ctx	The context.

Returns: The context, its scope held weakly.

Definition at line 6482 of file interpreter.hpp.

◆ attached()

LowerCtx morph::ui::detail::attached ( DetachedLower const & held )

inlinenodiscard

Puts a detached context's scope back.

Parameters

held	The detached context.

Returns: The context; its scope is null once the scope is gone.

Definition at line 6489 of file interpreter.hpp.

◆ changeWire()

std::expected< forms::detail::engine::Json, std::string > morph::ui::detail::changeWire	(	std::string const &	payload,
		std::string_view	type )

inlinenodiscard

A component's change payload as the wire value of the field it draws, read as the value prop's declared type.

Parameters

payload	The payload, as the backend reports it.
type	The value prop's type.

Returns: The wire value, or why the payload is not one.

Definition at line 6629 of file interpreter.hpp.

◆ formFilled()

std::function< Value()> morph::ui::detail::formFilled	(	std::string const &	prop,
		forms::FieldState *	state )

inlinenodiscard

What a form fills of a field component's props: the field's value, errors, read-only and required state, and label, each a tracked read of the field.

Parameters

prop	The prop's name.
state	The field.

Returns: The read, or empty for a prop the form does not fill.

Definition at line 6661 of file interpreter.hpp.

◆ arrangedChildren()

std::vector< ArrangedChild > morph::ui::detail::arrangedChildren	(	Value const &	stored,
		std::span< DocNode const *const >	declared )

inlinenodiscard

A container's children in the order a stored arrange choice gives, each marked shown or hidden.

A child the choice does not name keeps its declared place after the named ones, shown, and an entry that names no child, names one twice or is not a {"id", "hidden"} record is skipped, so a new document version survives an old choice (spec 5 §12b). A choice that is not a list leaves the declared order. Only "hidden": true hides.

Parameters

stored	The point's current choice.
declared	The container's children, in document order.

Returns: Every child, in order.

Definition at line 7435 of file interpreter.hpp.

◆ arrangedOrder()

std::vector< Value > morph::ui::detail::arrangedOrder	(	Value const &	stored,
		std::span< DocNode const *const >	declared )

inlinenodiscard

The ids of the children an arrange choice shows, in its order (arrangedChildren, without the hidden).

Parameters

stored	The point's current choice.
declared	The container's children, in document order.

Returns: The ids to show, in order.

Definition at line 7466 of file interpreter.hpp.

◆ arrangementValue()

Value morph::ui::detail::arrangementValue ( std::vector< ArrangedChild > const & children )

inlinenodiscard

An arrangement as the choice an arrange point stores.

Parameters

children Every child, in order.

Returns: [{"id", "hidden"}, …].

Definition at line 7479 of file interpreter.hpp.

◆ elementNode()

DocNode const * morph::ui::detail::elementNode	(	DocNode const &	node,
		std::string_view	elementId )

inlinenodiscard

The element of a document tree with elementId.

Parameters

node	The subtree.
elementId	The element's id.

Returns: The element, or nullptr when the subtree has none with that id.

Definition at line 7493 of file interpreter.hpp.

Variable Documentation

◆ kDefaultInlineFileBytes

std::size_t morph::ui::kDefaultInlineFileBytes = std::size_t{1024} * 1024

inlineconstexpr

The inline cap a session has unless it is given another: 1 MiB.

Definition at line 219 of file interpreter.hpp.

◆ kMaxInlineFileBytes

std::size_t morph::ui::kMaxInlineFileBytes = (wire::kMaxEnvelopeBytes - (std::size_t{64} * 1024)) * 3 / 4

inlineconstexpr

The largest inline cap a session takes: base64 grows bytes by 4/3, and 64 KiB of an envelope are left for the rest of the body, so the encoded file still fits wire::kMaxEnvelopeBytes.

Definition at line 223 of file interpreter.hpp.

◆ kCommandLogSize

std::size_t morph::ui::detail::kCommandLogSize = 256

inlineconstexpr

How many command lists the inspector's log keeps.

Definition at line 2203 of file interpreter.hpp.

◆ kPruneLoweredAt

std::size_t morph::ui::detail::kPruneLoweredAt = 256

inlineconstexpr

How often, in lowered nodes, the inspector's node list drops the nodes whose scope is gone.

Definition at line 2206 of file interpreter.hpp.

Classes

Typedefs

Enumerations

Functions

Variables

Detailed Description

Typedef Documentation

◆ Evaluator

◆ Watcher

◆ RowsByKey

◆ Bindings

◆ RunDone

◆ Done

◆ ActionModels

Enumeration Type Documentation

◆ PatchMiss

◆ ReplyUse

Function Documentation

◆ failureText()

◆ defaultErrorKind()

◆ canonicalJson()

◆ withPath()

◆ rowId()

◆ mergeRow()

◆ patchRows()

◆ patchMissReason()

◆ withoutFields()

◆ pathMembers()

◆ keyedRowsAt()

◆ patchKeyedRows()

◆ keyedRowsOf()

◆ patchHeldRows()

◆ evalIn()

◆ engaged()

◆ textOf()

◆ keyOf()

◆ valueOfKey()

◆ stringsOf()

◆ listOfStrings()

◆ detached()

◆ keySpec()

◆ statefulKind()

◆ commandKey()

◆ instanceKeyText()

◆ channelOf()

◆ elementFor()

◆ transfersOf()

◆ dateInstantOf()

◆ dateTextOf()

◆ sameShown()

◆ optionKey()

◆ jsonTextValue()

◆ formFieldValue()

◆ formValue()

◆ base64Encode()

◆ base64Decode()

◆ base64Size()

◆ sizeText()

◆ inlineBytes()

◆ boolOf()

◆ stringOf()

◆ componentText()

◆ componentNumber()

◆ componentPayload()

◆ intOf()

◆ roleNamed()

◆ roleOf()

◆ toneOf()

◆ sizingOf()

◆ isSizing()

◆ alignOf()

◆ justifyOf()

◆ axisOf()

◆ stepStateOf()

◆ selectOptions()

◆ lazy()

◆ holding()

◆ overlayOf()

◆ detachedLower()

◆ attached()