References

Home ▸ API Reference ▸ References

Xigt's relatively flat structure makes references an important way of showing the structure in IGT data. There are three types of references: a simple IdRef which refers to a single id, an IdRefs which refers to a space-separated list of ids, and alignment expressions which can handle more complex references. Various functions are provided by the API for interpreting and resolving references.

Reference Types

IdRef

Refers to a single id.

See also the format definition in the data model.

IdRefs

Refers to one or more space-delimited ids.

See also the format definition in the data model.

Alignment Expression

An alignment expression refers to one or more Items by their ids and can select sub-spans of content from the items. Items are the only data structure that may use or be a referent of an alignment expression.

See also the format definition in the data model.

Functions

Interpretive functions

# ref.resolve(container, expression)

Resolve and return the content referenced by expression. Ids in expression must be contained in container. Resolution gets content, not data structures, implying that the referents must be Items.

# ref.referents(igt, id)

Get ids referred by the object denoted by id.

# ref.referrers(igt, id)

Get ids denoting objects that refer to id.

# ref.dereference(obj, refattr)

Return the object referred by the first (possibly only) Id in refattr, where refattr exists on obj and the referred object is contained by the Igt of obj. Raises a XigtLookupError if obj has no Igt.

# ref.dereference_all(obj, refattr)

Return all objects referred by the Ids in refattr, where refattr exists on obj and the referred objects are contained by the Igt of obj. Raises a XigtLookupError if obj has no Igt.

String functions

# ref.expand(expression)

Return an expanded expression that lists each span separately.

>>> ref.expand('a1[3:5+6:7]')
'a1[3:5]+a1[6:7]'

# ref.compress(expression)

Return a compressed expression that groups adjacent spans with the same id.

>>> ref.compress('a1[3:5]+a1[6:7]')
'a1[3:5+6:7]'

# ref.selections(expression, keep_delimiters=True)

Return the list of selections in expression. When keep_delimiters is True, the delimiters between selections remain as list items.

>>> ref.selections('a1[3:5]+a2[1:2+3:4]')
['a1[3:5]', '+', 'a2[1:2+3:4]']
>>> ref.selections('a1[3:5]+a2[1:2+3:4]', keep_delimiters=False)
['a1[3:5]', 'a2[1:2+3:4]']

When the delimiters are kept, an equivalent expression can be formed by joining the result: ''.join(ref.selections(expr)).

# ref.spans(expression, keep_delimiters=True)

Return the list of spans in expression. When keep_delimiters is True, the delimiters between spans remain as list items.

>>> ref.spans('a1[3:5]+a2[1:2+3:4]')
['a1[3:5]', '+', 'a2[1:2]', '+', 'a2[3:4]']
>>> ref.spans('a1[3:5]+a2[1:2+3:4]', keep_delimiters=False)
['a1[3:5]', 'a2[1:2]', 'a2[3:4]']

When the delimiters are kept, an equivalent expression can be formed by joining the result: ''.join(ref.spans(expr)).

# ref.ids(expression)

Return the list of Ids within expression. One id will be returned for every selection, even if the same id is used sequentially.

>>> ref.ids('a1[3:5]+a2[1:2+3:4],a2[5:6],a3')
['a1', 'a2', 'a2', 'a3']
>>> ref.ids('a1 a2  a3')
['a1', 'a2', 'a3']