Ordfoss

PropertyPath.h header

#include <ew/app/PropertyPath.h>

Namespace ew::app

PathOutcome struct

struct ew::app::PathOutcome

What a path lookup found.

Members

std::vector<ew::core::expression::Value> ew::app::expression::PathOutcome::values

The values the path named: one for a scalar, one per element for a list, none for an empty collection.

bool ew::app::expression::PathOutcome::resolved = false

Whether the path named anything at all. False means a segment matches no field, alias or member – a typo, which must be reported rather than read as an empty value.

QString ew::app::expression::PathOutcome::error

Why the lookup was refused, when it was: a hidden object, a path that fans out past the limit, an unknown moment. Empty when resolved answers on its own.

Viewer struct

struct ew::app::Viewer

Who an expression is being evaluated for.

An expression must not become a way around the audience gate. A rule, a formula or a condition that could read a field its reader may not see would leak the value through its result – "the heir's true parent is Rhys" is disclosed by heir.parent = "Rhys" answering 1 just as surely as by showing the field. So the reader travels with the resolution, and a hidden object resolves to a refusal rather than to a value.

Members

QString ew::app::expression::Viewer::audience

The audience the expression is read as. Empty is the author's own view, which sees everything – the ordinary editing case, and the default every existing caller wants.

bool ew::app::expression::Viewer::isAi = false

Whether the reader is the AI, which additionally may not read AI-excluded content.

bool operator==(const Viewer &, const Viewer &)=default

Two viewers are the same reader when both halves match.

Functions

bool ew::app::expression::isPathCharacter(QChar character)

Whether character may appear inside a property path beyond letters, digits and '_': the '.' between segments and the '[' ']' of an element selector.

bool ew::app::expression::mayRead(const ew::core::project::Project &project, const Viewer &viewer, const ew::core::content::ContentObject &object)

Whether viewer may read object at all: visible to their audience, and not withheld from the AI when the reader is the AI.

QStringList ew::app::expression::pathNamesFor(const ew::core::project::Project &project, const ew::core::entity::Entity &entity)

The names entity offers at the head of a path: its fields, name, and one reference hop.

QStringList ew::app::expression::pathSegments(const QString &name)

Splits name into its dotted segments, or an empty list when it is not a well-formed path (an empty segment, a bracket that does not close).

PathOutcome ew::app::expression::valuesAtPath(const ew::core::project::Project &project, const Viewer &viewer, const ew::core::entity::Entity &from, const QStringList &segments, qsizetype index, std::optional< qint64 > instant)

The values the dotted path segments (from index) names, walking out from from.

The one walk. A validation rule, a computed field, a spreadsheet formula and a branching condition all ask the same question – what is this object's property – and four implementations of it would answer differently the first time any one of them was corrected. Everything the path can cross is here:

  • a plain field (price);
  • a member inside a property block or map (stats.strength);
  • a reference to another object, traversed (homeland.climate), with the reader's visibility checked at every hop;
  • a list, which contributes one value per element, optionally written [] to say so, or [2] to take one element by its 1-based position.

instant pins every value to a moment on the timeline (Entity::valueAt); std::nullopt reads base values. A field that is declared but unset is a blank, not a failure – a rule has to be able to say ISEMPTY(motto).