Skip to content

State

State dataclass

State(
    parent: LoweringABC[ASTNodeType],
    *,
    source: SourceInfo | None = None,
    lines: list[str] = list(),
    file: str | None = None,
    lineno_offset: int = 0,
    col_offset: int = 0
)

Bases: Generic[ASTNodeType]

State of the lowering process.

This class is used to store the state of the lowering process. It contains the current frame, the current block, and the current source.

code property

code

Obtain the code generated by the lowering process.

col_offset class-attribute instance-attribute

col_offset: int = field(default=0, kw_only=True)

column offset at the beginning of the source

current_frame property

current_frame: Frame[ASTNodeType]

current frame being lowered

file class-attribute instance-attribute

file: str | None = field(default=None, kw_only=True)

file name of the current node

lineno_offset class-attribute instance-attribute

lineno_offset: int = field(default=0, kw_only=True)

lineno offset at the beginning of the source

lines class-attribute instance-attribute

lines: list[str] = field(default_factory=list, kw_only=True)

source lines of the code being lowered

parent instance-attribute

parent: LoweringABC[ASTNodeType]

the parent lowering transform

root_frame property

root_frame: Frame[ASTNodeType]

root frame of the lowering process

source class-attribute instance-attribute

source: SourceInfo | None = field(
    default=None, kw_only=True
)

source info of the current node

Result dataclass

Result(data: tuple[SSAValue, ...])

A proxy object to the result of the lowering process.

Use .data to access the result of the lowering process. Use .expect_one() to assert that the result is a single value.

frame

frame(
    stmts: Sequence[ASTNodeType] | StmtStream[ASTNodeType],
    region: Optional[Region] = None,
    entr_block: Optional[Block] = None,
    next_block: Optional[Block] = None,
    globals: dict[str, Any] | None = None,
    capture_callback: Optional[CallbackFn] = None,
    finalize_next: bool = True,
) -> Generator[Frame[ASTNodeType], Any, None]

Context manager to push a new frame and pop it after the block.

Source code in src/kirin/lowering/state.py
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
@contextmanager
def frame(
    self,
    stmts: Sequence[ASTNodeType] | StmtStream[ASTNodeType],
    region: Optional[Region] = None,
    entr_block: Optional[Block] = None,
    next_block: Optional[Block] = None,
    globals: dict[str, Any] | None = None,
    capture_callback: Optional[CallbackFn] = None,
    finalize_next: bool = True,
) -> Generator[Frame[ASTNodeType], Any, None]:
    """Context manager to push a new frame and pop it after the block."""

    if not isinstance(stmts, StmtStream):
        stmts = StmtStream(stmts)

    region = region or Region()
    region.source = self.source

    entr_block = entr_block or Block()
    region.blocks.append(entr_block)

    if self._current_frame is not None:
        globals = globals or self.current_frame.globals
    else:
        globals = globals or {}

    frame = Frame(
        state=self,
        stream=stmts,
        curr_region=region or Region(entr_block),
        entr_block=entr_block,
        curr_block=entr_block,
        next_block=next_block or Block(),
        globals=globals,
        capture_callback=capture_callback,
    )
    self.push_frame(frame)
    try:
        yield frame
    finally:
        self.pop_frame(finalize_next)

get_global

get_global(
    node: ASTNodeType, *, no_raise: Literal[True] | bool
) -> LoweringABC.Result | None
get_global(
    node: ASTNodeType, *, no_raise: Literal[False] = False
) -> LoweringABC.Result
get_global(node: ASTNodeType, *, no_raise: bool = False)

Get the global value of a node. Args: node (ASTNodeType): the node to get the global value of. no_raise (bool): if True, do not raise an exception if the value is not found. Returns: LoweringABC.Result: a proxy object to the global value. .data is the value, and .expect(type) will raise an exception if the value is the expected type.

Source code in src/kirin/lowering/state.py
122
123
124
125
126
127
128
129
130
131
132
133
def get_global(self, node: ASTNodeType, *, no_raise: bool = False):
    """Get the global value of a node.
    Args:
        node (ASTNodeType): the node to get the global value of.
        no_raise (bool): if True, do not raise an exception if the value is not found.
    Returns:
        `LoweringABC.Result`: a proxy object to the global value. `.data` is the
            value, and `.expect(type)` will raise an exception if the value is the expected type.
    """
    if no_raise:
        return self.parent.lower_global_no_raise(self, node)
    return self.parent.lower_global(self, node)

pop_frame

pop_frame(finalize_next: bool = True)

Pop the current frame and return it.

Parameters:

Name Type Description Default
finalize_next(bool)

If True, append the next block of the current frame.

required

Returns:

Name Type Description
Frame

The popped frame.

Source code in src/kirin/lowering/state.py
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
def pop_frame(self, finalize_next: bool = True):
    """Pop the current frame and return it.

    Args:
        finalize_next(bool): If True, append the next block of the current frame.

    Returns:
        Frame: The popped frame.
    """
    if self._current_frame is None:
        raise ValueError("No frame to pop")
    frame = self._current_frame

    if finalize_next and frame.next_block.parent is None:
        frame.push(frame.next_block)
    self._current_frame = frame.parent
    return frame