Represents an immutable JsonPath like path in the Qml code model (from a DomItem to another DomItem) More...

Collaboration diagram for Path:

Detailed Description

Represents an immutable JsonPath like path in the Qml code model (from a DomItem to another DomItem)

The Path class is implemented as a linked list tree where components of the path can be shared between multiple paths.

We will represent a list of components with \badcode [a] // one element "a" in the list [a,b,c] // three elements in the list and the linked list tree structure with arrows: \badcode [a,b,c] <- [y,z] // one linked list made up of two nodes consisting of a, b, c, y and z ^ |______ [q] <- [w] // one linked list made up of three nodes consisting of a, b, c, q and w, sharing the a,b and c part with the above list

Appending components to the path will create a new linked list node, for example when appending d to {[a,b,c]}: \badcode [a,b,c] <- [d] This allows to share the path prefix when constructing paths recursively, for example.

Each node of the linked list tree is stored as PathData. It contains a vector of PathComponents, a pointer to the previous element in the path (called parent), and a QStringList to extend the lifetime of QStringViews used inside of PathComponent.

The path can also be "compressed", as the linked list structure contains vectors of components: {a.b.c.d} could be represented by \badcode [a] <- [b] <- [c] <- [d] (which is the default) or also \badcode [a, b] <- [c, d] when {[c,d]} got appended to {[a, b]} via withPath, for example.

The PathData is responsible to own the string data used by the PathComponents it contains. PathComponents do not contain any owning QStrings, they only hold QStringViews. To construct a PathData, store the string data in the QStringList such that it can be referenced by the QStringViews of PathData's PathComponents. PathData are assumed to be immutable after construction to avoid any dangling references due to a QStringList reallocation, for example.

Appending one component to the Path allows to share the "parent" path in the memory and should be the preferred way of constructing paths for DomItems.

To iterate through the path, you need two iterators. One for the current data (that contains the vector of components and the pointer to the "parent") and one for the current idx in the vector of components.

To access d in that path: \badcode [a, b] <- [c, d] you need to do \badcode path.m_data->components[1]. to access b instead, you need to do: \badcode path.m_data->parent->components[1]

Note that all kind of forward iterations (getting the components a, b, c, and d in this order from a.b.c.d) is a bit more involved, and backward iteration is much faster/easier.

The path also supports slicing via the m_length and m_endOffset members. m_endOffset ignores the n last components, for example {a.b.c.d} can be stored as

\badcode [root] <- [a] <- [b] <- [c] <- [d] <- [e] <- [f] <- [g] with m_endOffset = 3 and m_length = 4.

Paths are usually created during the Dom construction, and destroyed when the DomItem or Dom element holding it is destroyed.

The underlying PathData, on the other hand, is managed by a std::shared_ptr. It is destroyed when all Paths referencing it are destroyed. PathData can be referenced either directly through Path's m_data member, or indirectly through another PathData's m_parent member.

It can be created either from a string, with the path static functions or by modifying an existing path

Path qmlFilePath =
    Path::fromString(u"$env.qmlFilesByPath[\"/path/to/file\"]");
Path imports = qmlFilePath.withField(u"imports")
Path currentComponentImports = Path::fromCurrent(u"component").withField(u"imports");

This is a way to refer to elements in the Dom models that is not dependent from the source location, and thus can also be used in visual tools. A Path is quite stable toward reallocations or changes in the Dom model, and accessing it is safe even when "dangling", thus it is a good long term reference to an element in the Dom model.

Path objects are a value type that have a shared pointer to extra data if needed, thus one should use them as value objects. The implementation has still optimization potential, but the behavior for the user should be already the final one.

Path is both a range, and a single element (a bit like strings and characters in python).

The root contexts are: \list

\l{$modules} All the known modules (even not imported), this is a global, rename independent reference
\l{$cpp} The Cpp names (namespaces, and Cpp types) visible in the current component
\l{$libs} The plugins/libraries and their contents
\l{$top} A top level entry in the DOM model, either $env or $universe (stepping in the universe one looses the reference to its environment)
\l{$env} The environment containing the currently available modules, i.e. the top level entry in the DOM model
\l{$universe} The dom unverse used by ths environment, and potentially shared with others that contains all the known parse entries, and also the latest, potentially invalid entries
\l{$} ? undecided, one the previous ones? \endlist

The current contexts are: \list

\l{@obj} The current object (if in a map or list goes up until it is in the current object) .
\l{@component} The root object of the current component.
\l{@module} The current module instantiation.
\l{@ids} The ids in the current component.
\l{@types} All the types in the current component (reachable through imports, respecting renames)
\l{@lookupStrict} The strict lookup inside the current object: localJS, ids, properties, proto properties, component, its properties, global context, oterwise error
\l{@lookupDynamic} The default lookup inside the current object: localJS, ids, properties, proto properties, component, its properties, global context, ..
\l{@lookup} Either lookupStrict or lookupDynamic depending on the current component and context.
\l{@} ? undecided, one the previous ones \endlist

The documentation for this class was generated from the following file:

qtdeclarative/src/qmldom/qqmldompath.cpp (1237c2e07c63b4cdc92446c668b0417200e8c93b)