Capture¶
Dealing with capturing inside variable assignment, references to it, and constraints inside capture expressions.
This includes the label:body capture operator, annotation references like A.word, and constraint expressions like A.word = "over".
module-attribute
¶
CaptureConstraintExpr = Union[
AnnotationRef,
ConstraintLiteral,
ConstraintInteger,
ConstraintBoolLiteral,
ConstraintIntegerRange,
ConstraintComparison,
ConstraintBoolean,
ConstraintNot,
ConstraintFunctionCall,
]
Discriminated union of capture-level constraint expressions.
Represents any constraint that can appear inside a capture group ([...]).
The actual constraint type is determined by the node_type discriminator.
Members include annotation references, literals, integers, comparisons, boolean combinations, and negations specific to capture-level validation.
Bases: BCQLNode
A capture label applied to a sub-query: label:body, e.g. A:[word="hello"].
Everything matched by body is captured under label in the match info.
Attributes:
| Name | Type | Description |
|---|---|---|
label |
str
|
The capture group name (e.g. |
body |
BCQLNodeUnion
|
The sub-query whose match is captured |
Return this capture expression in BCQL syntax.
View source on GitHub: src/bcql_py/models/capture.py lines 48–50
Bases: BCQLNode
Reference to a captured token's annotation: label.annotation, or a bare capture label.
Examples:
- A.word refers to the word annotation of capture A.
- A as a bare label (typically used as a function argument, e.g. start(A)).
Attributes:
| Name | Type | Description |
|---|---|---|
label |
str
|
Capture group name. |
annotation |
str
|
Annotation name, or empty string for a bare label reference. |
Return this annotation reference in BCQL syntax.
View source on GitHub: src/bcql_py/models/capture.py lines 71–75
Bases: BCQLNode
A literal string value in a capture constraint.
Example: the "over" in A.word = "over".
Attributes:
| Name | Type | Description |
|---|---|---|
value |
str
|
The literal string (without quotes) |
quote_char |
Literal['"', "'"]
|
The quote character used in the original query, either |
Return this literal value in BCQL syntax.
View source on GitHub: src/bcql_py/models/capture.py lines 94–96
Bases: BCQLNode
A comparison in a capture constraint: left op right.
Supported operators: =, !=, <, <=, >, >=.
Operators here do not get their own class; should not be needed here.
Attributes:
| Name | Type | Description |
|---|---|---|
operator |
Literal['=', '!=', '<', '<=', '>', '>=']
|
The comparison operator. |
left |
CaptureConstraintExpr
|
Left-hand operand (usually an AnnotationRef]. |
right |
CaptureConstraintExpr
|
Right-hand operand (annotation ref, literal, or function call). |
Return this comparison expression in BCQL syntax.
View source on GitHub: src/bcql_py/models/capture.py lines 118–120
Bases: BCQLNode
Boolean combination of capture constraints: left op right.
Operators: & (AND), | (OR), -> (implication). All three share the same precedence
per Bcql.g4's booleanOperator rule. The -> implication operator is most commonly
seen in capture constraints (e.g. A.word = "cat" -> B.word = "dog") but the grammar
allows it at every level.
Attributes:
| Name | Type | Description |
|---|---|---|
operator |
Literal['&', '|', '->']
|
|
left |
CaptureConstraintExpr
|
Left operand. |
right |
CaptureConstraintExpr
|
Right operand. |
Return this boolean expression in BCQL syntax.
View source on GitHub: src/bcql_py/models/capture.py lines 142–144
Bases: BCQLNode
Logical NOT in a capture constraint
Attributes:
| Name | Type | Description |
|---|---|---|
operand |
CaptureConstraintExpr
|
The constraint being negated. |
Return this negated expression in BCQL syntax.
View source on GitHub: src/bcql_py/models/capture.py lines 157–159
Bases: BCQLNode
An integer literal in a capture constraint.
Example: the 5 in focus.pos > 5.
Attributes:
| Name | Type | Description |
|---|---|---|
value |
int
|
The integer value. |
Return this integer literal in BCQL syntax.
View source on GitHub: src/bcql_py/models/capture.py lines 174–176
Bases: BCQLNode
A boolean literal value in a capture constraint.
Example: the true in A.property = true.
Attributes:
| Name | Type | Description |
|---|---|---|
value |
bool
|
The boolean value. |
Return this boolean literal in BCQL syntax.
View source on GitHub: src/bcql_py/models/capture.py lines 191–193
Bases: BCQLNode
A standalone integer range value in a capture constraint.
Example: the in[2,5] in A.depth = in[2,5].
This is distinct from IntegerRangeConstraint,
which bundles an annotation name with the range inside a token query, e.g.
pos_confidence=in[min,max].
Attributes:
| Name | Type | Description |
|---|---|---|
min_val |
int
|
Lower bound of the range (inclusive). |
max_val |
int
|
Upper bound of the range (inclusive). |
Return this integer range in BCQL syntax.
View source on GitHub: src/bcql_py/models/capture.py lines 213–215
Bases: BCQLNode
A function call in a capture constraint.
Examples: start(A) or end(B) used in expressions like
start(B) < start(A).
Attributes:
| Name | Type | Description |
|---|---|---|
name |
str
|
Function name (e.g. |
args |
list[CaptureConstraintExpr]
|
Function arguments (annotation refs, literals, etc.). |
Return this function call in BCQL syntax.
View source on GitHub: src/bcql_py/models/capture.py lines 235–238
Bases: BCQLNode
A query with a global capture constraint.
The constraint expression follows the :: operator and relates captures defined in body.
Example: A:[] "by" B:[] :: A.word = B.word where A:[] "by" B:[] is the body and A.word = B.word is the constraint expression.
Attributes:
| Name | Type | Description |
|---|---|---|
body |
BCQLNodeUnion
|
The main query containing captures. |
constraint |
CaptureConstraintExpr
|
The constraint expression relating captures. |
Return this global-constraint query in BCQL syntax.
View source on GitHub: src/bcql_py/models/capture.py lines 289–291