Token¶

bcql_py.models.token ¶

Token-level annotations

StringValue ¶

Bases: BCQLNode

A quoted string value inside a BCQL query.

Handles regular strings, literal strings (prefixed with l), and sensitivity flags ((?-i) for sensitive, (?i) for insensitive).

Attributes:

Name	Type	Description
`value`	`str`	The raw string content (without surrounding quotes).
`is_literal`	`bool`	`True` when prefixed with `l` (e.g. `l"e.g."`).
`sensitivity`	`Literal['default', 'sensitive', 'insensitive']`	`"default"` follows the default value (unspecified), `"sensitive"` for `(?-i)`, `"insensitive"` for `(?i)`.

Example::

StringValue(value="(?-i)Panama").to_bcql()
# '"(?-i)Panama"'

AnnotationConstraint ¶

Bases: BCQLNode

A single annotation comparison: annotation op "value". Typically between an identifier, an operator, and a string value. Note that the identifier is not semantically specified here! It fully depends on the corpus which attributes (like word, lemma, pos) are available. So here annotation is underspecified as just a string.

Example: word="man" or pos != "noun".

Attributes:

Name	Type	Description
`annotation`	`str`	The annotation name (e.g. `"word"`, `"lemma"`).
`operator`	`Literal['=', '!=', '<', '<=', '>', '>=']`	`"="` or `"!="`.
`value`	`StringValue`	The value being compared against.

IntegerRangeConstraint ¶

Bases: BCQLNode

An integer range constraint, such as a parser's confidence: annotation=in[min,max].

Example: pos_confidence=in[50,100].

Note that we require both min and max vals to be given. No implicit "infinite" or "zero" bounds.

Attributes:

Name	Type	Description
`annotation`	`str`	The annotation name.
`min_val`	`int`	Inclusive lower bound.
`max_val`	`int`	Inclusive upper bound.

FunctionConstraint ¶

Bases: BCQLNode

A function-call constraint inside token brackets.

TODO: check for predefined functions in blacklab?

Attributes:

Name	Type	Description
`name`	`str`	The function / pseudo-annotation name.
`args`	`list[StringValue]`	The string arguments to the function.

NotConstraint ¶

Bases: BCQLNode

Logical NOT on a token-level constraint: !expr.

Typically for a capture group: !(pos="noun" | pos="verb").

Attributes:

Name	Type	Description
`operand`	`ConstraintExpr`	The constraint being negated.

BoolConstraint ¶

Bases: BCQLNode

Boolean combination of token-level constraints: left op right.

The operator is & (AND), | (OR), or -> (implication). Per the BCQL spec / Bcql.g4, all three share identical precedence and are left-associative. See the booleanOperator rule in Bcql.g4. Naming-wise calling it "boolean" might be somewhat confusing for the implication case though

Not to be confused with sequence-level boolean operators (also &, |, and ->) which combine whole sub-queries instead of token constraints. See sequence.SequenceBoolNode for those.

Attributes:

Name	Type	Description
`operator`	`Literal['&', '\|', '->']`	`"&"`, `"\|"`, or `"->"`.
`left`	`ConstraintExpr`	Left operand.
`right`	`ConstraintExpr`	Right operand.

TokenQuery ¶

Bases: BCQLNode

A single token query: [...], "string" shorthand, or [].

Attributes:

Name	Type	Description
`constraint`	`ConstraintExpr \| None`	The constraint expression inside the brackets, or `None` for match-all (`[]`).
`negated`	`bool`	`True` for the negated form `![...]`.
`shorthand`	`StringValue \| None`	When the query was written as a bare string like `"man"` (shorthand for `[word="man"]`), this stores the StringValue]. If set, `constraint` is `None`.