xnano.expressions

Bases: ExpressionScope

A buffer's own position and size, as expressions.

Attributes:

• x (NumericValue[int | float]) –

  The column in the parent.

• y (NumericValue[int | float]) –

  The row in the parent.

• position (Value[Point]) –

  The position in the parent.

• width (NumericValue[int | float]) –

  The width in cells.

• height (NumericValue[int | float]) –

  The height in cells.

• size (Value[Size]) –

  The size in cells.

• region (Value[Rectangle]) –

  The rectangle on the screen, counting every parent offset.

Examples:

assert BufferScope.width is Width
assert BufferScope.region is BufferRegion

x: NumericValue[int | float]

y: NumericValue[int | float]

position: Value[Point]

width: NumericValue[int | float]

height: NumericValue[int | float]

size: Value[Size]

region: Value[Rectangle]

Bases: Generic[ValueType_co]

A value or action described now and evaluated later against a buffer or runtime.

Evaluation is explicit. Using an expression where Python wants a truth value raises TypeError; combine conditions with &, | and ~ instead.

Examples:

from xnano_core._xnano_core import _reference

width = _reference('Width', 'numeric_property')
buffer = Buffer(width=8, height=1)
assert buffer.inspect(width + 2) == 10
assert (width + 2).evaluate(EvaluationContext(buffer=buffer)) == 10

Methods:

• evaluate –

  Compute the expression's value.

evaluate(context: EvaluationContext) -> ValueType_co

from xnano_core._xnano_core import _reference

width = _reference('Width', 'numeric_property')
context = EvaluationContext(buffer=Buffer(width=5, height=1))
assert (width * 2).evaluate(context) == 10

2984
2985
2986
2987
2988
2989
2990
2991
2992
2993
2994
2995
2996

def evaluate(self, context: EvaluationContext) -> ValueType_co:
    """
    Compute the expression's value.

    Examples:
        ```python
        from xnano_core._xnano_core import _reference

        width = _reference('Width', 'numeric_property')
        context = EvaluationContext(buffer=Buffer(width=5, height=1))
        assert (width * 2).evaluate(context) == 10
        ```
    """

Bases: ExpressionScope

The latest key event, as expressions.

Every member has no value while the latest input was not a key event, so a condition on a key is false for mouse, wheel and paste events. Comparing a member with None raises TypeError; compare it with the key you wait for, such as KeyboardScope.key == 'q'.

Attributes:

• key (Value[str | None]) –

  The key name, such as 'q' or 'enter'.

• kind (Value[Literal['press', 'repeat', 'release'] | None]) –

  'press', 'repeat' or 'release'.

• chord (Value[str | None]) –

  The key with its modifiers, such as 'ctrl+s'.

Examples:

with Runtime.offscreen(width=10, height=3) as runtime:
    buffer = Buffer(width=10, height=3)
    runtime.mount(buffer)
    seen = []
    buffer.add_hook(
        lambda context: seen.append('quit'),
        events=('key',),
        condition=KeyboardScope.key == 'q',
    )
    for key in ('w', 'q'):
        runtime.inject(Event.key_press(key))
        runtime.step()
    assert seen == ['quit']
    assert buffer.inspect(KeyboardScope.chord) == 'q'

key: Value[str | None]

kind: Value[Literal['press', 'repeat', 'release'] | None]

chord: Value[str | None]

Bases: ExpressionScope

The latest mouse button or motion report, as expressions.

position, button and kind describe the event being handled and have no value while the latest input was a key, a paste or a wheel report, so a condition on them is false (comparing with None raises TypeError); is_down is the held state and stays true between events while a button is held. Wheel reports belong to ScrollScope.

Attributes:

• position (Value[Point | None]) –

  The cell of the event.

• button (Value[MouseButton | None]) –

  'left', 'right' or 'middle'.

• kind (Value[Literal['press', 'release', 'drag', 'move'] | None]) –

  'press', 'release', 'drag' or 'move'.

• is_down (Predicate) –

  Whether any button is held.

Examples:

with Runtime.offscreen(width=10, height=3) as runtime:
    buffer = Buffer(width=4, height=2, x=1, y=1)
    runtime.mount(buffer)
    clicks = []
    buffer.add_hook(
        lambda context: clicks.append('inside'),
        events=('mouse',),
        condition=BufferScope.region.contains(MouseScope.position),
    )
    runtime.inject(Event.mouse_event(column=2, row=2, kind='move'))
    runtime.inject(Event.mouse_event(column=8, row=2, kind='move'))
    runtime.step()
    assert clicks == ['inside']
    assert buffer.inspect(MouseScope.position.x) == 8

position: Value[Point | None]

button: Value[MouseButton | None]

kind: Value[Literal['press', 'release', 'drag', 'move'] | None]

is_down: Predicate

Bases: Value[NumberType]

A numeric expression that supports comparisons and arithmetic.

Arithmetic and comparisons build new expressions instead of computing right away.

Examples:

from xnano_core._xnano_core import _reference

width = _reference('Width', 'numeric_property')
buffer = Buffer(width=8, height=3)
assert buffer.inspect(width + 2) == 10
assert buffer.inspect(10 - width) == 2
assert buffer.inspect(width > 4)
assert buffer.inspect(-width) == -8

Methods:

• evaluate –

  Compute the expression's value.

• equals –

  A predicate that is true when the value equals other.

• not_equals –

  A predicate that is true when the value differs from other.

• contains –

  A condition that is true while this rectangle contains the point other.

• __eq__ –

  A predicate that is true when the value equals other; the same as equals.

• __ne__ –

  A predicate that is true when the value differs from other; the same as not_equals.

• __hash__ –

  The identity hash, which keeps expressions usable in sets and dictionaries.

• __lt__ –

  A predicate that is true when the value is less than other.

• __le__ –

  A predicate that is true when the value is at most other.

• __gt__ –

  A predicate that is true when the value is greater than other.

• __ge__ –

  A predicate that is true when the value is at least other.

• __add__ –

  The sum of the value and other.

• __sub__ –

  The value minus other.

• __mul__ –

  The product of the value and other.

• __truediv__ –

  The value divided by other.

• __mod__ –

  The remainder of dividing the value by other.

• __neg__ –

  The value with its sign flipped.

• __rtruediv__ –

  other divided by the value.

• __rmod__ –

  The remainder of dividing other by the value.

• __floordiv__ –

  The value divided by other, rounded toward negative infinity like Python's //.

• __rfloordiv__ –

  other divided by the value, rounded toward negative infinity.

• __pow__ –

  The value raised to the power other.

• __rpow__ –

  other raised to the power of the value.

• __abs__ –

  The absolute value.

• __floor__ –

  The value rounded down to a whole number, used by math.floor.

• __ceil__ –

  The value rounded up to a whole number, used by math.ceil.

• __round__ –

  The value rounded to the nearest whole number, halves away from zero.

• minimum –

  The smaller of the value and other.

• maximum –

  The larger of the value and other.

• clamp –

  The value limited to the range from lowest to highest.

Attributes:

• x (NumericValue[int]) –

  The column of a Point or the left edge of a Rectangle.

• y (NumericValue[int]) –

  The row of a Point or the top edge of a Rectangle.

• width (NumericValue[int]) –

  The width of a Size or a Rectangle.

• height (NumericValue[int]) –

  The height of a Size or a Rectangle.

• right (NumericValue[int]) –

  The first column after a Rectangle.

• bottom (NumericValue[int]) –

  The first row after a Rectangle.

x: NumericValue[int]

from xnano_core._xnano_core import Position

assert Buffer(width=4, height=1, x=3, y=2).inspect(Position.x) == 3

y: NumericValue[int]

from xnano_core._xnano_core import Position

assert Buffer(width=4, height=1, x=3, y=2).inspect(Position.y) == 2

width: NumericValue[int]

from xnano_core._xnano_core import BufferSize

assert Buffer(width=6, height=2).inspect(BufferSize.width) == 6

height: NumericValue[int]

from xnano_core._xnano_core import BufferSize

assert Buffer(width=6, height=2).inspect(BufferSize.height) == 2

right: NumericValue[int]

from xnano_core._xnano_core import Bounds

assert Buffer(width=6, height=2, x=1).inspect(Bounds.right) == 7

bottom: NumericValue[int]

from xnano_core._xnano_core import Bounds

assert Buffer(width=6, height=2, y=1).inspect(Bounds.bottom) == 3

evaluate(context: EvaluationContext) -> ValueType_co