TCLpy Tutorial & Guide 🚀

1. Installation

Install the package from PyPI or set it up locally for development:

# Standard PyPI Installation
pip install ASTpytcl

# Or editable local development install
git clone https://github.com/TCLpy/TCLpy.git
cd TCLpy
pip install -e .

2. Using the Interactive REPL

Once installed, launch the interactive shell directly from your terminal (featuring full readline history navigation and multi-line brace balancing):

tclpy

Inside the shell, write Tcl commands naturally:

tclpy> set message "Hello from TCLpy!"
tclpy> puts $message
Hello from TCLpy!

3. Embedding TCLpy in Python Scripts

tclpy provides a clean top-level API allowing Python programs to evaluate Tcl code and share state dictionaries seamlessly.

Evaluating Tcl Strings

import tclpy

env = {"x": 10, "y": 20}
tclpy.eval('set total [expr {$x + $y}]', env)
print("Total:", env["total"])  # Output: 30

Sourcing Tcl Files

import tclpy

env = {}
tclpy.source("workflow.tcl", env)
print("Result from sourced file:", env.get("result"))

4. Python FFI & Advanced Operations

You can import any Python module and invoke its functions directly using Tcl's double-colon namespace syntax:

# Import the math module and compute square root
    py::import math
    set root [math::sqrt 144]
    puts "Square root: $root"