scope-path.hpp File Reference

Go to the source code of this file.

Description

An Object representing a sequence of nested scopes within the Session.

MObjects are being attached to the model by Placements, and each Placement is added as belonging into another Placement, which defines the Scope of the addition. There is one (formal) root element, containing the timelines; from there a nested sequence of scopes leads down to each Placement. Ascending this path yields all the scopes to search or query in proper order to be used when resolving some attribute of placement. Placements use visibility rules comparable to visibility of scoped definitions in common programming languages or in cascading style sheets, where a local definition can shadow a global one. In a similar way, properties not defined locally may be resolved by querying up the sequence of nested scopes.

A scope path is represented as sequence of scopes, where each Scope is implemented by a PlacementRef pointing to the »scope top«, i.e. the placement in the session constituting this scope. The leaf of this path can be considered the current scope. ScopePath is intended to be used for remembering a current location within the model, usable for resolving queries and discovering contents.

operations and behaviour

In addition to some search and query functions, a scope path has the ability to navigate to a given target scope, which must be reachable by ascending and descending into the branches of the overall tree or DAG (in the general case). Navigating is a mutating operation which usually happens when the current "focus" shifts while operating on the model.

• ScopePath can be default constructed, yielding an invalid path.
• When created with a given target Scope, a connection to the current Session is created behind the scenes to discover the path starting from this target Scope up to model root. This is the core "locating" operation. It may fail.
• There is a pre defined ScopePath::INVALID token
• ScopePaths are intended to be handled by value (as are Scopes and PlacementRefs). They are equality comparable and provide several specialised relation predicates.
• while generally copying is permitted, you may not overwrite an ScopePath which is attached (referred by a QueryFocus, see below)
• all implementations are focused on clarity, not uttermost performance, as the assumption is for paths to be relatively short and path operations to be executed rather in a GUI action triggered context.
• the iteration (Lumiera Forward Iterator) yields the path elements in ascending order, starting with the leaf element
• a path containing just the root element evaluates to bool(false) (rationale is that any valid, usable path is below just root).
• an empty (nil) path doesn't even contain the root element and may throw on many operations.

relation to ScopeLocator

ScopeLocator holds the QueryFocusStack, which contains ScopePath objects. Each of these stack frames represents the current location for some evaluation context; it is organised as stack to allow intermediate evaluations. Management of these stack frames is automated, with the assistance of ScopePath by incorporating a ref-count. Client code usually accesses this mechanism through QueryFocus objects as frontend, which is reflected in the mentioned embedded refcount

See also

scope-path-test.cpp

Scope

ScopeLocator

Definition in file scope-path.hpp.

#include "steam/mobject/session/scope.hpp"
#include "lib/iter-adapter.hpp"
#include "lib/error.hpp"
#include <vector>
#include <string>

Classes
class	ScopePath
	Sequence of nested scopes within the high-level model. More...
struct	ValueTypeBinding< vector< Scope >::const_reverse_iterator >
	this explicit specialisation allows to build a RangeIter to yield const Scope elements, based on the const_reverse_iterator used internally within ScopePath. More...

Functions
void	intrusive_ptr_add_ref (ScopePath *pathFrame)
	management function for boost::intrusive_ptr to be picked up by ADL
void	intrusive_ptr_release (ScopePath *pathFrame)
bool	operator!= (ScopePath const &path1, ScopePath const &path2)
bool	operator== (ScopePath const &path1, ScopePath const &path2)

Namespaces
	lib
	Implementation namespace for support and library code.
	steam
	Steam-Layer implementation namespace root.
	steam::mobject
	Media-Objects, edit operations and high-level session.
	steam::mobject::session
	Namespace of Session and user visible high-level objects.