Class: File_Therion_Reference

File_Therion_Reference __construct( string|object $refObj, File_Therion_Survey $ctx)

Create a new therion reference object.

This generates a new reference object. The following invocations exist:

• (obj, survey): Create obj reference (to generate string-reference).
• (string, survey): Create resolvable string-reference.

More special invocations are:

• (string, null): Create a contextless static ref (returns string as is)
• (obj, null): Create fake obj reference (generates entire pathref).

Parameters:

File_Therion_IReferenceable getObject( )

Return referenced object by string reference.

In case the string reference was not resolved yet, it will be looked up. You usually dont need to call this yourself ({@see getObject()}).

This will throw an UnexpectedValueException when the view context is invalid. A File_Therion_InvalidReferenceException will be thrown, when the referenced object cannot be found in the data model.

array getSurveyPath( )

Retrieves the path leading to the objects survey context.

Objects must be associated to a survey. The surveys of the Object must be reachable from the survey context of the reference (viewing ctx), which is usually the parent survey referencing station of subsurveys.

When the references viewing context is not set (null), the topmost Object context will be used as top parent. This will result in the maximum possible path being resolved. When the Objects context is null, an UnexpectedValueException is thrown. When the Objects context is not reachable from the reference context, a File_Therion_InvalidReferenceException will be thrown.

Technically the search is done by walking the objects survey context structure upwards until the viewing survey context is reached.

The array returned is one of the following:

• array containing no elements: Object is local to viewing context
• array containing n elements: top-down path of surveys

File_Therion_Reference parse( $string $string)

Parse string reference into static reference object.

This will create a basic string reference object without context. As such, it is just a kind of alias to the constructor for static string references.

Overrides File_Therion_DataType::parse() (Parse string content into this datatype)

Parameters:

Therion toString( )

Get string representation.

The string reference will be generated in case it was not already present. To be sure you always have an up-to-date reference, you may call updateStringReference() manually beforehand.

Overrides File_Therion_DataType::toString() (Get string representation)

void updateObjectReference( )

Parse string reference and resolve referenced object.

This will take the current string reference and uses the view-context to lookup the referenced object.

void updateStringReference( )

Update string representation of this reference.

This will generate a string reference that will be returned by toString(). The reference addresses the current referenced object viewed from the reference view-context. You usually don't need to call this yourself ({@see toString()}).

As of therion 5.3.16 and Survex 1.2.16 the reference syntax looks like with deep nested structures the path syntax is resolved right-to-left as top-down, with the dot just beeing an alternate @-sign. eg.: "1.1@deepest.notSoDeep.topSurvey": saying"1.1 at deepest@notSoDeep@topSurvey", while topSurvey is the next reachable level from the current viewed one.