Ordfoss

JournalEntry.h header

#include <ew/core/JournalEntry.h>

Namespace ew::core

JournalEntry struct

struct ew::core::JournalEntry

One recorded change: what was done, to what, by whom, and when.

Entries are written as mutations apply and are never rewritten, so the journal is an append-only account of the project's history. It sits alongside undo rather than replacing it: undoing a change is itself a change, and the journal records that too.

The journal is purely local. Nothing in the app requires a consumer for it, and no consumer may be required for the app to run.

Members

JournalEntryId ew::core::journal::JournalEntry::id

Identity of this entry.

QDateTime ew::core::journal::JournalEntry::timestamp

When the change was applied, in UTC.

QString ew::core::journal::JournalEntry::author

Who made the change. Free text rather than an account id, because the product has no accounts and must keep working without any: it is whatever the local user is called.

ew::core::foundation::OperationSubject ew::core::journal::JournalEntry::subject

What the change was about. See OperationSubject – a content object, a taxonomy category, or a piece of project-level state.

OperationKind ew::core::journal::JournalEntry::kind =

Whether this records the change being made, reversed, or re-applied.

QString ew::core::journal::JournalEntry::description

Human-readable summary of the change, taken from the command's own description.

OperationGroupId ew::core::journal::JournalEntry::group

The group this entry belongs to, when several mutations were applied as one undoable step. Null for a change that stands alone. Entries sharing a group were one user action.

Types

using ew::core::journal::JournalEntryId = ew::core::foundation::Id<JournalEntryIdTag>

Stable, globally-unique identity for one journal entry. See Id for the shared semantics.

using ew::core::journal::OperationGroupId = ew::core::foundation::Id<OperationGroupIdTag>

Identity of a group of entries that were applied as one undoable step.

A DISTINCT KIND from JournalEntryId on purpose, though it would be tempting to reuse it: a group id does not name an entry, and nothing guarantees an entry exists with that id. Giving it its own kind is what stops the two being passed for one another – which is the entire reason ids carry a phantom tag in this codebase.

Functions

std::optional< JournalEntry > ew::core::journal::journalEntryFromJson(const QJsonObject &json)

Parses a journal entry from json. Returns std::nullopt when a required field is missing or malformed – a damaged entry is refused rather than read back with holes silently filled in, because an audit trail that quietly invents values is worse than one that admits a gap.

QJsonObject ew::core::journal::toJson(const JournalEntry &entry)

Serializes entry to a JSON object.