This is an automated email from the ASF dual-hosted git repository.

tqchen pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/tvm-tirx.git


The following commit(s) were added to refs/heads/main by this push:
     new b2a992e0d [DOCS][IR] Rewrite Printing and Parsing around why, the 
parser, and the builder (#143)
b2a992e0d is described below

commit b2a992e0dd624f13b86b1ff6f9887f737e689496
Author: Tianqi Chen <[email protected]>
AuthorDate: Sat Oct 31 10:51:08 2026 -0400

    [DOCS][IR] Rewrite Printing and Parsing around why, the parser, and the 
builder (#143)
    
    Rewrite the IR Walkthrough's Printing and Parsing chapter around why
    TVMScript exists and how the parser works.
    
    - Open with why: every program at any stage can be written as TVMScript,
    which serves as the DSL frontend, the IR constructor for tests, and the
    diagnostic printer.
    - Printing and parsing `add_one` and a module, including the Python 3.12
    `[n]` symbol syntax.
    - How the parser works: transpilation onto the IR builder with the real
    generated builder program, metaprogramming, direct builder construction,
    region syntax, and predictability over sugar.
    - Extending the syntax, and the parser protocol as an advanced topic.
    - Diagnostics: printing at a stage and highlighting objects.
    - Code comes from a new runnable `examples/ir_walkthrough`, added to the
    CPU minimal-examples run.
    - New reference page for `script.ir_builder.parser_protocol`.
    - Writing Passes now compares against an inline expected module and no
    longer saves IR as TVMScript, which is not a serialization format.
---
 docs/compiler/writing_passes.rst                   |  70 +--
 docs/ir/printing_and_parsing.rst                   | 509 +++++++++------------
 docs/programming_guides/language_basics.rst        |   2 +-
 .../python/script.ir_builder.parser_protocol.rst   |  88 ++++
 docs/reference/python/script.ir_builder.rst        |   1 +
 .../ir_walkthrough/add_one_printed.py              |  18 +-
 examples/ir_walkthrough/printing_and_parsing.py    |  93 ++++
 .../ir_walkthrough/run_all_cpu.sh                  |  13 +-
 pyproject.toml                                     |   2 +
 tests/scripts/task_minimal_examples_cpu.sh         |   2 +-
 10 files changed, 417 insertions(+), 381 deletions(-)

diff --git a/docs/compiler/writing_passes.rst b/docs/compiler/writing_passes.rst
index aa0528257..b649ecc87 100644
--- a/docs/compiler/writing_passes.rst
+++ b/docs/compiler/writing_passes.rst
@@ -22,8 +22,7 @@ Suppose we want a version of an add-one function for tensors 
of length 128.
 We will write a pass that fixes its symbolic length, then combine it with
 statement simplification. A compiler pass packages an IR transformation so
 the pass manager can run it as part of a pipeline. As we build this pipeline,
-we will check its result, inspect the intermediate programs, and save one
-to reproduce a single transformation.
+we will check its result and inspect the intermediate programs.
 
 Starting Program
 ----------------
@@ -147,24 +146,19 @@ type must agree with its source and indices:
 
    assert tirx.analysis.check_well_formed(after)
 
-We also want to check that it has the structure we intended. We can parse
-an independently written version of the expected function, then compare it
-with the result:
+We also want to check that it has the structure we intended. We can write
+the expected module directly in TVMScript, then compare it with the result:
 
 .. code-block:: python
 
-   from tvm_tirx.script import from_source
+   @T.ir_module
+   class Expected:
+       @T.function
+       def guarded_add_one(A: T.Tensor((128,), T.float32), B: T.Tensor((128,), 
T.float32)):
+           for i in range(128):
+               B[i] = A[i] + 1
 
-   expected = from_source(
-       """
-   @T.function
-   def guarded_add_one(A: T.Tensor((128,), T.float32), B: T.Tensor((128,), 
T.float32)):
-       for i in range(128):
-           B[i] = A[i] + 1
-   """,
-       extra_vars={"T": T},
-   )
-   ir.assert_structural_equal(after["guarded_add_one"], expected)
+   ir.assert_structural_equal(after, Expected)
 
 This comparison checks both fixed tensor shapes and the loop with a direct
 store in its body. Neither well-formedness nor structural comparison proves
@@ -200,50 +194,6 @@ already fixed the length when the simplifier receives the 
module.
 The instrument observes the pipeline without changing it. To inspect our
 own pass instead, use ``specialize.info.name`` in the lists.
 
-Saving and Reproducing a Stage
-------------------------------
-
-Once we have identified a stage to investigate, we can save its input and
-run that pass on its own. ``specialized`` is the module produced earlier by
-our pass, before statement simplification. Save it as TVMScript with imports
-included so it can be parsed independently:
-
-.. code-block:: python
-
-   from pathlib import Path
-
-   stage_file = Path("before_simplify.py")
-   stage_file.write_text(
-       specialized.script(extra_config={"ir.comment_imports": False}),
-       encoding="utf-8",
-   )
-
-In a separate experiment, load this file and apply only ``StmtSimplify``.
-There is no need to recreate the original symbolic dimension or rerun the
-specialization pass:
-
-.. code-block:: python
-
-   from pathlib import Path
-
-   from tvm_tirx import tirx
-   from tvm_tirx.script import from_source
-
-   restored = 
from_source(Path("before_simplify.py").read_text(encoding="utf-8"))
-   reproduced = tirx.transform.StmtSimplify()(restored)
-   print(reproduced["guarded_add_one"].script())
-
-The printed function has the same fixed shapes and direct store as before.
-If we run this loading code in the original Python session, we can also
-compare ``reproduced`` with the full pipeline's result, ``after``:
-
-.. code-block:: python
-
-   ir.assert_structural_equal(reproduced, after)
-
-The saved input can now serve as a small reproducer when investigating a
-simplifier change.
-
 The :doc:`pass API </reference/python/ir.transform>` and
 :doc:`TIRx transformation API </reference/python/tirx.transform>` cover
 other pass forms and built-in transformations. The
diff --git a/docs/ir/printing_and_parsing.rst b/docs/ir/printing_and_parsing.rst
index 75ad0e3c7..03192fc43 100644
--- a/docs/ir/printing_and_parsing.rst
+++ b/docs/ir/printing_and_parsing.rst
@@ -20,85 +20,46 @@
 Printing and Parsing
 ====================
 
-In this chapter, we will introduce printing and parsing with TVMScript,
-TIRx's Python-based syntax for tensor programs.
-The printer turns IR objects into readable TVMScript code, and the parser
-constructs IR objects from that code. We will use these interfaces to
-inspect the add-one function, save and load programs, and examine a
-compiler pass's changes.
-
-Printing IR
------------
-
-We will use a CPU function that adds one to each tensor element. The
-TVMScript decorator ``@T.function`` parses its definition into a
-``tirx.Function`` IR object:
-
-.. literalinclude:: ../../examples/quick_start/add_one_cpu.py
-   :language: python
-   :start-at: from tvm_tirx.script import tirx as T
-   :end-at:         B[i] = A[i] + 1
-
-The ``script()`` method returns the function's TVMScript source:
-
-.. code-block:: python
-
-   source = add_one.script()
-   print(source)
-
-The output makes the symbolic dimension and constant's type explicit:
-
-.. code-block:: python
-
-   from __future__ import annotations
-
-   # from tvm_tirx.script import tirx as T
-
-   @T.function
-   def add_one[n](A: T.Tensor((n,), T.float32), B: T.Tensor((n,), T.float32)):
-       for i in range(n):
-           B[i] = A[i] + T.float32(1.0)
-
-The original code declares ``n`` with ``T.dynamic``. The printer places
-that declaration in ``[n]`` after the function name, so the printed
-definition includes the symbol needed by its tensor shapes and loop
-bound. ``T.float32(1.0)`` records the float32 constant used by the addition.
-The printed form represents the same IR as the original definition.
+Every TIRx program, at any stage of compilation, can be written in
+TVMScript, an embedded Python syntax. The printer turns IR into TVMScript,
+and the parser turns TVMScript back into IR. This lets one syntax serve
+three roles:
 
-The same method works on modules and smaller IR objects. For example,
-``add_one.params[0].ty.script()`` returns ``T.Tensor((n,), T.float32)``
-for the input tensor type.
+- **DSL frontend**: developers and agents write tensor programs directly
+  in TVMScript.
+- **IR constructor for tests**: a test writes its input and expected
+  output as TVMScript, then compares them structurally with the result of
+  a pass.
+- **Diagnostic printer**: when compilation fails, the printer shows the
+  program as it stands at that stage, in the same syntax the user wrote.
 
-.. _parsing-source:
+.. note::
 
-Parsing TVMScript
------------------
+   The runnable code in this chapter is under
+   `examples/ir_walkthrough 
<https://github.com/apache/tvm-tirx/tree/main/examples/ir_walkthrough>`_
+   in the repository.
 
-The :doc:`TVMScript parser </reference/python/script.parser>` provides
-``from_source`` to construct IR from a string containing TVMScript code.
-We can use it with the add-one definition:
+Printing and Parsing
+--------------------
 
-.. code-block:: python
+We will use a CPU function that adds one to each tensor element:
 
-   from tvm_tirx.script import from_source
+.. literalinclude:: ../../examples/ir_walkthrough/printing_and_parsing.py
+   :language: python
+   :start-after: # [function.begin]
+   :end-before: # [function.end]
 
-   source_text = """
-   from tvm_tirx.script import tirx as T
+The ``script()`` method prints any IR object as TVMScript:
 
-   @T.function
-   def add_one[n](A: T.Tensor((n,), T.float32), B: T.Tensor((n,), T.float32)):
-       for i in range(n):
-           B[i] = A[i] + T.float32(1.0)
-   """
-   parsed_function = from_source(source_text)
-   print(type(parsed_function).__name__)
-   print(parsed_function.script())
+.. literalinclude:: ../../examples/ir_walkthrough/printing_and_parsing.py
+   :language: python
+   :start-after: # [print.begin]
+   :end-before: # [print.end]
 
 The output is:
 
-.. code-block:: text
+.. code-block:: python
 
-   Function
    from __future__ import annotations
 
    # from tvm_tirx.script import tirx as T
@@ -108,276 +69,216 @@ The output is:
        for i in range(n):
            B[i] = A[i] + T.float32(1.0)
 
-``parsed_function`` is a ``tirx.Function`` containing the parameter
-variables, loop, and tensor store. It can be inspected or compiled
-through the same interfaces as ``add_one``.
-
-The import inside ``source_text`` tells the parser what ``T`` refers to.
-Our first call to ``add_one.script()`` returned ``source`` with that
-import commented out. To parse this string, we can bind the name ``T``
-to the existing namespace through ``extra_vars``:
-
-.. code-block:: python
-
-   from tvm_tirx import ir
-   from tvm_tirx.script import tirx as T
-
-   restored_function = from_source(source, extra_vars={"T": T})
-   ir.assert_structural_equal(add_one, restored_function)
-
-The printed ``[n]`` declares the symbolic dimension, so it needs no
-external binding.
-
-Saving and Loading a Module
----------------------------
-
-An IR module can be saved as TVMScript for later inspection or reuse.
-We can store the CPU function in a module and write its source to a file.
-The file can include its own imports, so a parser can read it in another
-process. ``ir.comment_imports=False`` enables those imports:
-
-.. code-block:: python
-
-   from pathlib import Path
-
-   module = ir.IRModule({"add_one": add_one})
-   module_source = module.script(extra_config={"ir.comment_imports": False})
-   output_path = Path("add_one_module.py")
-   output_path.write_text(module_source)
-
-We can read the saved source and reconstruct the module:
-
-.. code-block:: python
-
-   restored_module = from_source(output_path.read_text())
-   ir.assert_structural_equal(module, restored_module)
-
-The parser resolves the namespace names from the imports, so this call
-needs no ``extra_vars``. ``restored_module`` is an ``ir.IRModule``
-with the same function definitions as ``module``.
-
-Inspecting IR
--------------
-
-The printer can also help us locate a selected computation in the source
-or see how a compiler pass changes the program.
-
-.. _highlighting-nodes:
-
-Highlighting IR Objects
-~~~~~~~~~~~~~~~~~~~~~~~
-
-An analysis may need to identify an expression in a diagnostic. We can
-reach the addition in ``B[i] = A[i] + 1`` through the function's body,
-then ask the printer to underline it and attach a message about its type:
-
-.. code-block:: python
-
-   loop = add_one.body[0]
-   store = loop.body[0]
-   addition = store.value
-   marked_source = add_one.script(
-       obj_to_underline=[addition],
-       obj_to_annotate={addition: "result dtype: float32"},
-       print_line_numbers=True,
-       num_context_lines=1,
-   )
-   print(marked_source)
-
-The marked lines include:
-
-.. code-block:: text
-
-   7     for i in range(n):
-   8         B[i] = A[i] + T.float32(1.0)  # result dtype: float32
-                    ^^^^^^^^^^^^^^^^^^^^^
-
-``obj_to_underline`` selects the expression to mark, and ``obj_to_annotate``
-attaches the message. The line numbers refer to this printed source.
-``num_context_lines=1`` keeps one surrounding line, so the diagnostic
-shows the loop containing the addition.
-
-For interactive inspection,
-:meth:`add_one.show() <tvm_tirx.tirx.Function.show>` displays highlighted
-source directly and accepts the same options.
-
-Inspecting a Transformation
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The printer also helps us check what a compiler pass changes. Consider
-this version of add-one with a bounds check inside the loop:
-
-.. code-block:: python
-
-   @T.function
-   def guarded_add_one(A: T.Tensor((n,), T.float32), B: T.Tensor((n,), 
T.float32)):
-       for i in range(n):
-           if i < n:
-               B[i] = A[i] + 1
-
-The loop already guarantees ``i < n``, so this extra branch is redundant.
-The ``StmtSimplify`` pass can remove it. We can print the module before
-and after applying that pass:
-
-.. code-block:: python
-
-   from tvm_tirx import ir, tirx
-
-   before_simplify = ir.IRModule({"guarded_add_one": guarded_add_one})
-   print(before_simplify.script())
-   after_simplify = tirx.transform.StmtSimplify()(before_simplify)
-   print(after_simplify.script())
+The printer writes out everything the IR records. The constant ``1``
+becomes ``T.float32(1.0)``, its value with the type the addition uses. The
+symbolic dimension ``n`` is declared in ``[n]`` after the function name,
+using the type-parameter syntax introduced in Python 3.12. Each name in
+the brackets declares a symbolic variable as if by ``T.dynamic``, but
+scoped to this function, so the printed function is self-contained. On
+Python 3.12 and newer, we can also write this form ourselves. A symbol with a 
dtype other than ``int32`` carries an
+annotation, as in ``[m: T.int64]``. The same method works on smaller
+objects. For example, ``add_one.params[0].ty.script()`` returns
+``T.Tensor((n,), T.float32)``.
+
+A module prints the same way, as a class marked with ``@T.ir_module`` with
+one ``@T.function`` per member:
+
+.. literalinclude:: ../../examples/ir_walkthrough/printing_and_parsing.py
+   :language: python
+   :start-after: # [print_module.begin]
+   :end-before: # [print_module.end]
 
-The second output contains the simplified loop:
+The output is:
 
 .. code-block:: python
 
-   for i in range(n):
-       B[i] = A[i] + T.float32(1.0)
-
-Building Program Variants
--------------------------
+   from __future__ import annotations
 
-A source generator may produce functions with the same structure but
-different constants. ``from_source`` can parse the same template with
-different ``extra_vars`` to build these variants. This template replaces
-the add-one constant with ``increment``:
+   # from tvm_tirx.script import tirx as T
 
-.. code-block:: python
+   n = T.dynamic("n", dtype="int32")
+   @T.ir_module
+   class Module:
+       @T.function
+       def add_one(A: T.Tensor((n,), T.float32), B: T.Tensor((n,), T.float32)):
+           for i in range(n):
+               B[i] = A[i] + T.float32(1.0)
 
-   variant_source = """
-   @T.function
-   def add_constant[n](A: T.Tensor((n,), T.float32), B: T.Tensor((n,), 
T.float32)):
-       for i in range(n):
-           B[i] = A[i] + increment
-   """
-
-The same text can produce versions that add one or two:
+Functions in a module can share symbols, so ``n`` is declared once before
+the class instead of in ``[n]``.
 
-.. code-block:: python
+The printed output is TVMScript that ``@T.function`` and ``@T.ir_module``
+accept. On Python 3.12 and newer, a printed function placed in a Python
+file, here ``add_one_printed.py`` with its import enabled, builds the same
+IR again:
 
-   add_one_variant = from_source(
-       variant_source, extra_vars={"T": T, "increment": 1.0}
-   )
-   add_two_variant = from_source(
-       variant_source, extra_vars={"T": T, "increment": 2.0}
-   )
-   print(add_two_variant.script())
+.. literalinclude:: ../../examples/ir_walkthrough/add_one_printed.py
+   :language: python
+   :start-after: # [printed.begin]
+   :end-before: # [printed.end]
 
-The parser turns the ``increment`` value passed through ``extra_vars``
-into a constant. The addition in ``add_two_variant`` is therefore
-``A[i] + T.float32(2.0)``; both functions still take only ``A`` and ``B``
-as parameters.
+.. literalinclude:: ../../examples/ir_walkthrough/printing_and_parsing.py
+   :language: python
+   :start-after: # [parse.begin]
+   :end-before: # [parse.end]
 
-.. _user-ir-source-locations:
+Printing and then parsing gives back the same IR. This is what lets a test
+write its expected IR as TVMScript and compare it with the output of a
+pass. To store or transfer IR, use ``ir.save_json`` and ``ir.load_json``,
+which serialize the IR objects directly.
 
-Source Locations
-----------------
+How the Parser Works
+--------------------
 
-IR nodes can carry source locations to help diagnostics point back to
-the original code. The ``loc`` field stores this information, and
-:class:`ir.SourceLoc <tvm_tirx.ir.SourceLoc>` records the source file
-and range.
+The parser is a thin layer over an IR builder, the Python API that
+constructs IR. The builder works with frames: entering a function, loop,
+or region opens a frame, and the statements built inside it become its
+body. Parsing is transpilation: the parser reads the Python syntax tree of
+a TVMScript definition, rewrites each syntax form into the matching
+builder call, then compiles and runs the result as an ordinary Python
+function in the definition's original scope.
 
-The parameter ``A`` is declared on this line of the CPU program:
+For example, this definition:
 
-.. literalinclude:: ../../examples/quick_start/add_one_cpu.py
+.. literalinclude:: ../../examples/ir_walkthrough/printing_and_parsing.py
    :language: python
-   :start-at: def add_one(
-   :end-at: def add_one(
-   :lineno-match:
+   :start-at: @T.function
+   :end-at: B[i] = A[i] + 1
 
-The parameter's ``loc`` points back to this declaration. We can read
-``start_line`` to report its line number:
+becomes this builder program:
 
 .. code-block:: python
 
-   parameter = add_one.params[0]
-   location = parameter.loc
-   line = location.start_line
-   print(f"Parameter {parameter.name} is declared on line {line}.")
-
-For the CPU source file shown above, the output is:
-
-.. code-block:: text
-
-   Parameter A is declared on line 29.
-
-The number follows the definition's position in its source file; it can
-change if you save the definition elsewhere.
+   with _I0.IRBuilder() as _builder0:
+       with T.function_() as _fn0:
+
+           def _declare0():
+               T.func_name_('add_one')
+               A = T.arg_('A', T.Tensor((n,), T.float32))
+               B = T.arg_('B', T.Tensor((n,), T.float32))
+           _declare0()
+
+           def _build0():
+               A, B = _fn0.params
+               with T.for_(T.range_(n), names='i') as i:
+                   T.setitem_(value=A[i] + 1, target=B, key=i)
+           _build0()
+   _result0 = _fn0.function
+   _result0.__name__ = 'add_one'
+   T.check_well_formed_(_result0)
+
+Each syntax form maps to builder calls: the definition becomes a
+``function_`` frame, parameter annotations become ``arg_`` calls with
+their types, the loop becomes a ``for_`` frame,
+and the store becomes ``setitem_``. The signature is declared before the
+body is built, and the finished function is checked for well-formedness.
+Expressions such as ``A[i] + 1`` stay as written: ``A`` is the IR
+variable returned by ``arg_``, so Python's ``[]`` and ``+`` build the IR
+expression directly.
+Because the program runs as normal Python, ``n`` and other names come from
+the surrounding scope. The real output also passes source positions to
+each call, which is how parsed IR gets its ``loc``.
+
+Because the builder program runs as ordinary Python, the parser supports
+metaprogramming out of the box. A TVMScript function can read any Python
+value from its enclosing scope, and a Python function can build a new
+TVMScript function on each call:
+
+.. literalinclude:: ../../examples/ir_walkthrough/printing_and_parsing.py
+   :language: python
+   :start-after: # [metaprogramming.begin]
+   :end-before: # [metaprogramming.end]
 
-We can also retrieve the source filename through
-``location.source_name.name``. To inspect which fields a source location
-records without displaying its file path, we can print the location
-with ``source_name`` hidden:
+``add_two`` adds ``2`` to ``int32`` tensors, and ``add_three`` adds
+``T.float32(3.0)`` to ``float32`` tensors. The parser needs no template
+language for this: ``value`` and ``dtype`` are evaluated like any other
+Python name when the builder program runs.
 
-.. code-block:: python
+The builder is also a public API, so we can construct the same function
+directly, without the parser:
 
-   print(ir.format_tree(location, hide=["source_name"]))
+.. literalinclude:: ../../examples/ir_walkthrough/printing_and_parsing.py
+   :language: python
+   :start-after: # [builder.begin]
+   :end-before: # [builder.end]
+
+``builder.get()`` returns a ``tirx.Function`` that is structurally equal
+to ``add_one``. Hand-written builder code uses the user-facing API, such as
+``T.serial`` and ``T.assign``, rather than the protocol hooks the parser
+emits. Writing builder code directly is sometimes helpful because
+it stays unambiguously in the Python domain. A plain Python ``for`` or
+``if`` runs while the IR is built, and IR control flow comes only from
+explicit frames such as ``T.serial`` and ``T.if_`` with ``T.then_``. 
Developers and agents
+therefore know exactly what each line executes. To record source
+locations, wrap the construction in ``builder.line_trace_scope()``, and
+each statement then records its source line in ``loc``.
 
-The fields include ``start_line``, ``end_line``, ``start_column``, and
-``end_column``, which identify the declaration's range in the source.
+.. _tvmscript-region-syntax:
 
-Source locations are also useful when parsing fails. The following
-source is missing the type annotation for parameter ``A``. We give the
-text a filename so the diagnostic can identify it:
+Regions are built with frames in the same way. A region operator such as
+``T.device_entry`` opens a frame, and the statements inside its ``with``
+block become the region's body:
 
 .. code-block:: python
 
-   invalid_source = """@T.function
-   def invalid_add_one(A):
-       T.evaluate(0)
-   """
-   try:
-       from_source(
-           invalid_source,
-           extra_vars={"T": T},
-           filename="generated_add_one.py",
-       )
-   except SyntaxError as error:
-       print(error)
-
-The output is:
-
-.. code-block:: text
-
-   Parameter 'A' requires an annotation (generated_add_one.py, line 2)
-
-The message identifies the supplied source text and the line with the
-invalid parameter. Successfully parsed nodes record the filename and
-their positions in ``loc``.
-
-.. _tvmscript-region-syntax:
+   with T.device_entry(launch=T.cuda.LaunchConfig(grid=T.ceildiv(n, 256), 
block=256)):
+       i = T.cuda.block_idx("x") * 256 + T.cuda.thread_idx("x")
+       if i < n:
+           B[i] = A[i] + 1
+
+As a shorthand, a region call written as a plain statement opens the same
+frame for the rest of its enclosing block, so ``T.device_entry(...)``
+followed by the same statements at the same indentation produces the same
+``ir.RegionStmt``.
+
+We value **predictability** over syntactic sugar. Each syntax form has one
+fixed meaning: an annotation is a type, an assignment binds a variable, a
+subscript store writes a tensor, and a call is an ordinary Python call.
+Types such as ``T.Tensor`` and operators such as ``T.cuda.thread_idx`` are
+plain functions that return IR, so the parser has no rules specific to
+them.
+
+Extending the Syntax
+--------------------
+
+Because the parser only rewrites syntax into builder calls, extending
+TVMScript rarely touches the parser. Operators and types registered by an
+extension package are plain functions that return IR, so they work in
+TVMScript as soon as the package is imported. For example, an operator
+registered under an extension namespace ``my_ext`` is written
+``my_ext.cmul(a, b)``, like any built-in operator.
+
+As an advanced topic, a new language variant can also be added if
+necessary. The builder hooks that the parser emits for each syntax form,
+such as ``bind_``, ``setitem_``, and ``for_``, form the *parser protocol*,
+defined in ``tvm_tirx.script.ir_builder.parser_protocol``. A variant
+implements these hooks on its own namespace and registers it with the
+parser, and the same parser then builds its IR.
+
+Diagnostics
+-----------
 
-Region Syntax
--------------
+When compilation fails, the most useful view is usually the program as it
+stands at that stage. Calling ``script()`` on the module at that point
+shows it in the same syntax used to write it.
 
-The parser also determines which statements belong to a region. A CUDA
-function uses ``T.device_entry`` to mark the statements that execute on
-the GPU. In the following function, the region starts at that line:
+The printer can also point at specific objects. ``obj_to_underline`` marks
+objects in the output, and ``obj_to_annotate`` attaches a message to them:
 
-.. literalinclude:: ../../examples/quick_start/add_one_cuda.py
+.. literalinclude:: ../../examples/ir_walkthrough/printing_and_parsing.py
    :language: python
-   :start-at: @T.function
-   :end-at:         B[i] = A[i] + 1
-
-For this form, TVMScript takes all following statements in the same
-enclosing block as the region's body. The enclosing block here is the
-function body: the region extends from ``T.device_entry(...)`` to the
-end of the function. It contains the assignment to ``i`` and the entire
-``if`` branch, even though those statements have the same indentation
-as ``T.device_entry(...)``.
+   :start-after: # [highlight.begin]
+   :end-before: # [highlight.end]
 
-An explicit ``with`` block shows the same region through indentation:
+The output ends with:
 
-.. code-block:: python
+.. code-block:: text
 
    @T.function
-   def add_one(A: T.Tensor((n,), T.float32), B: T.Tensor((n,), T.float32)):
-       with T.device_entry(launch=T.cuda.LaunchConfig(grid=T.ceildiv(n, 256), 
block=256)):
-           i = T.cuda.block_idx("x") * 256 + T.cuda.thread_idx("x")
-           if i < n:
-               B[i] = A[i] + 1
-
-Both forms produce the same ``ir.RegionStmt``. The :doc:`statements`
-chapter explains the IR structure inside that region.
+   def add_one[n](A: T.Tensor((n,), T.float32), B: T.Tensor((n,), T.float32)):
+       for i in range(n):
+           B[i] = A[i] + T.float32(1.0)  # result dtype: float32
+                  ^^^^^^^^^^^^^^^^^^^^^
+
+``show()`` accepts the same options and displays the result with syntax
+highlighting.
diff --git a/docs/programming_guides/language_basics.rst 
b/docs/programming_guides/language_basics.rst
index 87a03ddfa..23ac987f5 100644
--- a/docs/programming_guides/language_basics.rst
+++ b/docs/programming_guides/language_basics.rst
@@ -172,7 +172,7 @@ skips the remaining threads in this example.
 
 In ``add_one``, the statements after ``T.device_entry(...)`` form the GPU
 computation. The same section can also be written inside a
-``with T.device_entry(...):`` block. :ref:`tvmscript-region-syntax`
+``with T.device_entry(...):`` block. :ref:`Region syntax 
<tvmscript-region-syntax>`
 explains both forms.
 
 ``grid`` and ``block`` accept an integer or up to three dimensions.
diff --git a/docs/reference/python/script.ir_builder.parser_protocol.rst 
b/docs/reference/python/script.ir_builder.parser_protocol.rst
new file mode 100644
index 000000000..3422cd90a
--- /dev/null
+++ b/docs/reference/python/script.ir_builder.parser_protocol.rst
@@ -0,0 +1,88 @@
+..  Licensed to the Apache Software Foundation (ASF) under one
+    or more contributor license agreements.  See the NOTICE file
+    distributed with this work for additional information
+    regarding copyright ownership.  The ASF licenses this file
+    to you under the Apache License, Version 2.0 (the
+    "License"); you may not use this file except in compliance
+    with the License.  You may obtain a copy of the License at
+
+..    http://www.apache.org/licenses/LICENSE-2.0
+
+..  Unless required by applicable law or agreed to in writing,
+    software distributed under the License is distributed on an
+    "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+    KIND, either express or implied.  See the License for the
+    specific language governing permissions and limitations
+    under the License.
+
+tvm_tirx.script.ir_builder.parser_protocol
+==========================================
+
+.. automodule:: tvm_tirx.script.ir_builder.parser_protocol
+   :no-members:
+
+.. currentmodule:: tvm_tirx.script.ir_builder.parser_protocol
+
+Functions and Modules
+---------------------
+
+.. autosummary::
+   :toctree: generated/
+
+   ir_module
+   decl_function
+   function_
+   arg_
+   func_name_
+   func_ret_type_
+
+Bindings and Statements
+-----------------------
+
+.. autosummary::
+   :toctree: generated/
+
+   resolve_global_info_
+   call_global_var_
+   module_member_
+   bind_
+   decl_mutable_cell_
+   set_mutable_cell_
+   unpack_
+   emit_
+   setitem_
+   setattr_
+
+Control Flow
+------------
+
+.. autosummary::
+   :toctree: generated/
+
+   if_
+   then_
+   else_
+   for_
+   while_
+   range_
+   break_
+   continue_
+   return_
+   assert_
+
+Operators
+---------
+
+.. autosummary::
+   :toctree: generated/
+
+   if_then_else_
+   and_
+   or_
+   not_
+   lt_
+   le_
+   gt_
+   ge_
+   eq_
+   ne_
diff --git a/docs/reference/python/script.ir_builder.rst 
b/docs/reference/python/script.ir_builder.rst
index f70af55fc..74f25c8ce 100644
--- a/docs/reference/python/script.ir_builder.rst
+++ b/docs/reference/python/script.ir_builder.rst
@@ -127,5 +127,6 @@ Namespaces
    :maxdepth: 1
 
    script.ir_builder.frame
+   script.ir_builder.parser_protocol
    script.ir_builder.stmt
    script.ir_builder.tracing
diff --git a/tests/scripts/task_minimal_examples_cpu.sh 
b/examples/ir_walkthrough/add_one_printed.py
old mode 100755
new mode 100644
similarity index 73%
copy from tests/scripts/task_minimal_examples_cpu.sh
copy to examples/ir_walkthrough/add_one_printed.py
index 42c7fa376..6fa8c1848
--- a/tests/scripts/task_minimal_examples_cpu.sh
+++ b/examples/ir_walkthrough/add_one_printed.py
@@ -1,4 +1,3 @@
-#!/usr/bin/env bash
 # Licensed to the Apache Software Foundation (ASF) under one
 # or more contributor license agreements.  See the NOTICE file
 # distributed with this work for additional information
@@ -15,11 +14,16 @@
 # KIND, either express or implied.  See the License for the
 # specific language governing permissions and limitations
 # under the License.
+"""The printed form of add_one, as produced by add_one.script()."""
 
-set -euxo pipefail
+# [printed.begin]
+from tvm_tirx.script import tirx as T
 
-# Keep this explicit list limited to examples that run in a few seconds.
-examples=(examples/quick_start)
-for example in "${examples[@]}"; do
-    uv run --no-sync bash "${example}/run_all_cpu.sh"
-done
+
[email protected]
+def add_one[n](A: T.Tensor((n,), T.float32), B: T.Tensor((n,), T.float32)):
+    for i in range(n):
+        B[i] = A[i] + T.float32(1.0)
+
+
+# [printed.end]
diff --git a/examples/ir_walkthrough/printing_and_parsing.py 
b/examples/ir_walkthrough/printing_and_parsing.py
new file mode 100644
index 000000000..866768c1d
--- /dev/null
+++ b/examples/ir_walkthrough/printing_and_parsing.py
@@ -0,0 +1,93 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+"""Print, parse, and build add_one."""
+
+# Imports stay next to the snippets that use them in the docs.
+# ruff: noqa: E402
+
+# [function.begin]
+from tvm_tirx import ir
+from tvm_tirx.script import tirx as T
+
+n = T.dynamic("n")
+
+
[email protected]
+def add_one(A: T.Tensor((n,), T.float32), B: T.Tensor((n,), T.float32)):
+    for i in range(n):
+        B[i] = A[i] + 1
+
+
+# [function.end]
+
+# [print.begin]
+print(add_one.script())
+# [print.end]
+
+# [print_module.begin]
+module = ir.IRModule({"add_one": add_one})
+print(module.script())
+# [print_module.end]
+
+# [parse.begin]
+from add_one_printed import add_one as printed_add_one
+
+ir.assert_structural_equal(add_one, printed_add_one)
+# [parse.end]
+
+
+# [metaprogramming.begin]
+def make_add(value, dtype):
+    @T.function
+    def add(A: T.Tensor((n,), dtype), B: T.Tensor((n,), dtype)):
+        for i in range(n):
+            B[i] = A[i] + value
+
+    return add
+
+
+add_two = make_add(2, T.int32)
+add_three = make_add(3, T.float32)
+# [metaprogramming.end]
+print(add_two.script())
+print(add_three.script())
+
+# [builder.begin]
+from tvm_tirx.script.ir_builder import IRBuilder
+
+with IRBuilder() as builder:
+    with T.function_():
+        T.func_name_("add_one")
+        A = T.arg_("A", T.Tensor((n,), T.float32))
+        B = T.arg_("B", T.Tensor((n,), T.float32))
+        with T.serial(n) as i:
+            T.assign(B[i], A[i] + 1)
+built = builder.get()
+
+ir.assert_structural_equal(built, add_one)
+# [builder.end]
+
+# [highlight.begin]
+loop = add_one.body.seq[0]
+addition = loop.body.seq[0].value
+print(
+    add_one.script(
+        obj_to_underline=[addition],
+        obj_to_annotate={addition: "result dtype: float32"},
+    )
+)
+# [highlight.end]
diff --git a/tests/scripts/task_minimal_examples_cpu.sh 
b/examples/ir_walkthrough/run_all_cpu.sh
similarity index 76%
copy from tests/scripts/task_minimal_examples_cpu.sh
copy to examples/ir_walkthrough/run_all_cpu.sh
index 42c7fa376..03fa00cb2 100755
--- a/tests/scripts/task_minimal_examples_cpu.sh
+++ b/examples/ir_walkthrough/run_all_cpu.sh
@@ -1,4 +1,4 @@
-#!/usr/bin/env bash
+#!/bin/bash
 # Licensed to the Apache Software Foundation (ASF) under one
 # or more contributor license agreements.  See the NOTICE file
 # distributed with this work for additional information
@@ -15,11 +15,8 @@
 # KIND, either express or implied.  See the License for the
 # specific language governing permissions and limitations
 # under the License.
+set -ex
+cd "$(dirname "$0")"
 
-set -euxo pipefail
-
-# Keep this explicit list limited to examples that run in a few seconds.
-examples=(examples/quick_start)
-for example in "${examples[@]}"; do
-    uv run --no-sync bash "${example}/run_all_cpu.sh"
-done
+# Print, parse, and build add_one
+python printing_and_parsing.py
diff --git a/pyproject.toml b/pyproject.toml
index eadb693e5..3bedf54e9 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -204,6 +204,8 @@ include = [
 line-length = 100
 indent-width = 4
 target-version = "py310"
+# The printed form of a function declares symbols with Python 3.12 type 
parameters.
+per-file-target-version = { "examples/ir_walkthrough/add_one_printed.py" = 
"py312" }
 exclude = ["3rdparty", "build", "dist", ".venv", ".ruff_cache", "node_modules"]
 
 [tool.ruff.lint]
diff --git a/tests/scripts/task_minimal_examples_cpu.sh 
b/tests/scripts/task_minimal_examples_cpu.sh
index 42c7fa376..4f9551a23 100755
--- a/tests/scripts/task_minimal_examples_cpu.sh
+++ b/tests/scripts/task_minimal_examples_cpu.sh
@@ -19,7 +19,7 @@
 set -euxo pipefail
 
 # Keep this explicit list limited to examples that run in a few seconds.
-examples=(examples/quick_start)
+examples=(examples/quick_start examples/ir_walkthrough)
 for example in "${examples[@]}"; do
     uv run --no-sync bash "${example}/run_all_cpu.sh"
 done

Reply via email to