Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
31 changes: 31 additions & 0 deletions .github/workflows/studio.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,31 @@
name: Tell Studio (Rust / GPUI)

on:
workflow_dispatch:
schedule:
- cron: "41 3 * * 1"

permissions:
contents: read

concurrency:
group: tell-studio-${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: true

jobs:
cargo-test:
runs-on: ubuntu-24.04
steps:
- uses: actions/checkout@v4
- uses: dtolnay/rust-toolchain@stable
- name: Install GPUI Linux dependencies
run: |
sudo apt-get update
sudo apt-get install -y \
libasound2-dev libfontconfig1-dev libfreetype6-dev \
libx11-dev libx11-xcb-dev libxkbcommon-dev libxkbcommon-x11-dev \
libxcb-render0-dev libxcb-shape0-dev libxcb-xfixes0-dev \
libxcb-xkb-dev libxrandr-dev libxi-dev libxcursor-dev \
libwayland-dev libvulkan-dev pkg-config
- name: Check the GPUI application and run buffer tests
run: cargo test --manifest-path studio/Cargo.toml
10 changes: 4 additions & 6 deletions .github/workflows/tellc.yml
Original file line number Diff line number Diff line change
@@ -1,12 +1,10 @@
name: TellC LLVM compiler

on:
pull_request:
paths:
- "TellC/**"
- "scripts/build-tellc-macos.sh"
- "README.md"
- ".github/workflows/tellc.yml"
# The embedded LLVM/LLD build is intentionally excluded from normal PRs:
# upstream builds are expensive and the native Go/runtime suites run on PRs.
schedule:
- cron: "17 2 * * 1"
workflow_dispatch:

permissions:
Expand Down
49 changes: 36 additions & 13 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,10 +2,7 @@

**Tell is a sentence-first programming language.** Its goal is to make code read like clear instructions written in ordinary language, while keeping familiar programming capabilities underneath.

Tell has two runtimes:

- **Native runtime:** a standalone executable written in Go. It runs `.tell` programs directly and does not need Python or Go installed on the user's machine.
- **Python runtime:** the original interpreter, kept for compatibility, experimentation, and people who want to embed or extend Tell from Python.
Tell's primary runtime is the standalone Go executable. The Python interpreter is deprecated and remains available only as a compatibility bridge while existing projects migrate. New language features target Go; new desktop editor work targets Rust/GPUI Studio.

Current version: **0.3.7**.

Expand Down Expand Up @@ -81,6 +78,30 @@ tell run examples/hello.tbc

Use `tell build source.tell --output output.tbc` to choose the artifact path. The compiler supports functions, recursion, closures, core control flow, local modules embedded in the artifact, `Try`/`Raise`, and the initial class model with constructors, fields, methods, single inheritance, and overrides. `Finally` and other language features remain unsupported in bytecode; see the [CLI reference](docs/CLI_REFERENCE.md) for its exact subset and limits. [examples/compiled-objects.tell](examples/compiled-objects.tell) demonstrates an object program that can be run by either interpreter or compiled to bytecode by the native runtime.

## Typed Tell on the native Go runtime

The Go runtime supports an opt-in typed dialect with type-first declarations
and explicit function signatures:

~~~tell
to factorial(number: n) out number:
if n <= 1:
give back 1
end if
give back n * factorial(n - 1)
end function

let number answer be factorial(5)
say answer
~~~

Use `tell --typed native/examples/native-typed.tell` to require explicit
types for variables, function parameters, and return values. The same strict
validation is available through `tell check --typed` and `tell build --typed`.
Typed parameter and return contracts are enforced during normal execution
and preserved in bytecode. Existing dynamic Tell programs remain supported
without `--typed`; see the [typed Go dialect guide](docs/TYPED_TELL.md).

## Compile native executables with TellC

TellC is an experimental C++ compiler that translates its typed dialect through LLVM into a native executable. Its dialect is separate from the dynamically typed language used by the Go and Python runtimes; programs are not necessarily interchangeable. For example:
Expand Down Expand Up @@ -111,9 +132,9 @@ build/tellc-macos-arm64/tellc/tellc TellC/examples/factorial.tell -o factorial

The example prints `120`. The standalone compiler embeds LLVM code generation and the Mach-O linker; it and its output target macOS 11 or later. A Linux build uses a compatible LLVM installation, `llc`, and Clang. Build details, dependencies, and tests are in the [TellC guide](TellC/README.md), [build guide](TellC/docs/BUILDING.md), and [test guide](TellC/docs/TESTING.md). `tellc source.tell` defaults to `a.out`; use `-o` to choose the output and `tellc --llvm-version` to inspect its LLVM version.

## Run the Python version
## Legacy Python runtime (deprecated)

Python 3.10 or newer is required for this runtime only.
Python 3.10 or newer is required only for this legacy compatibility runtime. New development should target the native Go runtime.

```bash
python tell.py examples/hello.tell
Expand All @@ -132,15 +153,17 @@ python -m pip install .
tell examples/hello.tell
```

## Desktop IDE
## Native desktop editor

Tell includes a Python Tk desktop IDE with a tabbed `.tell` editor, line numbers, syntax colours, block-aware indentation, file open/save, Find, and a persistent interactive shell. Run, syntax check, bytecode build, and project tests invoke the native Go runtime when it is available. The Python runtime is the fallback. The IDE is optional and does not change the standalone native runtime.
The replacement editor is the early Rust/GPUI application in [studio/](studio/README.md). It opens one Tell source file, supports basic editing and saving, and runs the native Go executable. Build it from the repository root:

```powershell
python -m tell ide
```
~~~sh
cargo run --manifest-path studio/Cargo.toml -- path/to/program.tell
~~~

Set TELL_NATIVE_EXECUTABLE to the Go executable path when it is not available as tell on PATH. This is an initial editor foundation, not yet a full Zed-style IDE; tabs, diagnostics, language-server integration, undo/redo, and project navigation remain future work.

After installing Tell with `python -m pip install .`, launch it with `tell-ide` (or `tell ide`). Tkinter is included with the standard Windows Python installer; on some Linux distributions install `python3-tk`. See the [IDE guide](docs/IDE.md) for shortcuts and runtime selection.
The Python/Tk IDE is deprecated and remains temporarily available as a compatibility fallback through python -m tell ide, which prints a deprecation warning. New installations no longer include the separate tell-ide console command. See the [migration guide](docs/IDE.md).

## Language features

Expand Down Expand Up @@ -169,7 +192,7 @@ After installing Tell with `python -m pip install .`, launch it with `tell-ide`
| Static methods, access modifiers, multiple inheritance | Planned | Planned |
| Async, package manager | Planned | Planned |

The native and Python runtimes aim to share the same core syntax. The Python runtime currently has a broader set of built-ins and standard-library behavior. This is an evolving language, not a claim of complete Python compatibility.
The Go runtime is the primary implementation and the Python runtime is maintained only for compatibility during migration. Cross-runtime differences remain; use the Go executable for new projects. This is an evolving language, not a claim of complete Python compatibility.

## Syntax guide

Expand Down
10 changes: 10 additions & 0 deletions TellC/docs/CI.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
# LLVM compiler workflow

TellC's full LLVM/LLD jobs are resource-intensive. They run on a weekly
schedule and through manual workflow dispatch, not on ordinary pull requests.
Fast Go/runtime checks remain part of normal PR validation.

To run the full matrix manually, open **Actions → TellC LLVM compiler →
Run workflow**. The workflow validates Linux with the external LLVM toolchain,
Apple silicon with embedded LLVM + LLD, and Intel macOS with the external
toolchain.
12 changes: 7 additions & 5 deletions docs/ARCHITECTURE.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,14 +4,14 @@

Both runtimes parse block headers with explicit prefix and delimiter routines, including nested otherwise-if chains. The parser now builds expression ASTs for common `Let`, `Set`, instance member assignment, output, assertion, return, raise, loop-control, bare expression, and `Tell object to method` statements. The expression AST includes tuple literals with shared runtime semantics. Other statements still use the line-oriented compatibility recognizers.

Tell has two independent runtimes:
Tell is moving toward one primary native runtime. The Python implementation is deprecated and remains only as a compatibility runtime during migration. New language features should target Go; new desktop editor features should target Rust/GPUI Studio.

- `native/internal/tell` is a Go interpreter compiled into standalone binaries. Its block parser retains source line/column information and represents migrated statements with a `simpleStatement` containing a parsed expression AST. The runtime evaluates that AST directly; the bytecode compiler also lowers it directly rather than reparsing the statement text. Remaining statement families still use compatibility recognizers. Its expression lexer recognizes human-language operators directly, supports Unicode expression identifiers, and records offsets and Unicode-aware line/column coordinates. A few prefix and object-construction phrases remain syntax rewrites.
- `tell/interpreter.py` parses line-oriented blocks into nodes with typed dictionaries for migrated statements, and uses its own Tell lexer, Pratt parser, and expression nodes for the shared expression grammar. Python expression evaluation now uses Tell ASTs exclusively; host-only Python expression forms fail Tell parsing rather than falling through to a second expression language. Control-flow conditions are parsed into cached ASTs before execution.
- `tell/interpreter.py` is the deprecated Python compatibility interpreter. It parses line-oriented blocks into nodes with typed dictionaries for migrated statements, and uses its own Tell lexer, Pratt parser, and expression nodes for the shared expression grammar. Python expression evaluation now uses Tell ASTs exclusively; host-only Python expression forms fail Tell parsing rather than falling through to a second expression language. Control-flow conditions are parsed into cached ASTs before execution.

Both runtimes own separate environments, built-ins, class/instance implementations, module loaders, and standard-library adapters. Local modules execute in an environment parented by the runtime globals, export public top-level bindings, and are cached by resolved file path per interpreter. `conformance/core.json` is the shared executable corpus. Each runtime test runner executes those same programs and compares output against the declared expected output.

The optional Python adapter is deliberately outside ordinary runtime startup. The Python implementation imports requested modules in its current process. The native Go runtime invokes a configured Python executable per foreign function call and exchanges JSON values over stdin/stdout. Named and positional arguments work; opaque Python objects and persistent Python-side module state do not cross calls. This keeps the default Go runtime independent of Python while making the dependency explicit for programs that choose the adapter.
The optional Python adapter is deliberately outside ordinary Go runtime startup. The Python runtime is deprecated and should not be used as the target for new features. The Python implementation imports requested modules in its current process. The native Go runtime invokes a configured Python executable per foreign function call and exchanges JSON values over stdin/stdout. Named and positional arguments work; opaque Python objects and persistent Python-side module state do not cross calls. This keeps the default Go runtime independent of Python while making the dependency explicit for programs that choose the adapter.

## Current execution path

Expand All @@ -36,14 +36,16 @@ It supports `Let`, `Set`, `Remember` field initialization, output statements, ba

## Persistent sessions

The Python `Interpreter` retains its global environment between `run` calls. The native `Session` API provides the same behavior with `NewSession` or `NewSessionWithLimits` and `Exec`. Both REPLs rely on this persistence and pass the same execution-limit settings used by command-line program runs.
The deprecated Python `Interpreter` retains its global environment between `run` calls. The native `Session` API provides the same behavior with `NewSession` or `NewSessionWithLimits` and `Exec`. Both REPLs rely on this persistence and pass the same execution-limit settings used by command-line program runs.

## Architectural priorities

1. Continue migrating I/O, module, collection-mutation, object, and library statements from raw text recognizers into typed statement nodes; add full source spans and parser recovery.
2. Replace expression phrase rewriting with explicit tokens in both runtimes while retaining the English operator grammar.
3. Separate parser, AST, diagnostics, runtime, standard library, and CLI code into focused modules/packages.
4. Build shared semantic analysis and a stable IR, then expand bytecode lowering from the current syntax-limited subset.
5. Align numeric, collection, error, and library behavior with cross-runtime conformance cases as each statement family moves to the AST.
5. Continue migrating the supported typed dialect into the Go parser, semantic checker, runtime, and bytecode format.
6. Keep the Python runtime in compatibility-only mode until native feature coverage and migration guidance are sufficient.
7. Build the Rust/GPUI Studio editor around the Go CLI and the existing Tell language server.

See [ENGINEERING_AUDIT.md](ENGINEERING_AUDIT.md) for measured gaps and current validation evidence.
57 changes: 34 additions & 23 deletions docs/IDE.md
Original file line number Diff line number Diff line change
@@ -1,35 +1,46 @@
# Tell IDE
# Tell Studio and IDE migration

Tell IDE is an optional desktop editor and interactive shell built with Python's Tk interface. It follows the editing and run loop of Python IDLE while executing programs with Tell itself.
The Python/Tk desktop IDE is deprecated. It remains available temporarily as a
compatibility fallback, but new editor work belongs in the Rust/GPUI
application under [studio/](../studio/README.md).

## Start
## Current replacement: Tell Studio

From a Tell source checkout:
Tell Studio is an early native desktop shell built on GPUI, the Rust UI
framework used by Zed. It provides a single-file source workspace, basic
keyboard editing, save, and execution through the native Go runtime.

```console
python -m tell ide
```
Build and launch it from the repository root:

~~~sh
cargo run --manifest-path studio/Cargo.toml -- path/to/program.tell
~~~

After installing the Python package, use either command:
The native Go executable must be available as tell on PATH, or set
TELL_NATIVE_EXECUTABLE to its absolute path. Studio is an early foundation,
not a full Zed-style IDE yet: multi-tab editing, diagnostics, language-server
integration, debugger tooling, and project navigation are future work.

```console
tell ide
tell-ide
```
## Legacy Python/Tk editor

The UI requires Python 3.10 or newer and Tkinter. Windows Python installers normally include Tkinter. On Linux, install the distribution's `python3-tk` package if needed. The Go runtime is preferred for execution. Set `TELL_NATIVE_EXECUTABLE` to a native Tell executable to select one explicitly. If no native executable is found, the editor falls back to the Python Tell runtime. A Python fallback requires the Tell Python package to be importable by the child process.
For compatibility during the transition only:

## Editor and shell
~~~sh
python -m tell ide
~~~

- Open multiple `.tell` files in tabs; create, save, and close files with unsaved-change prompts.
- Use syntax colours, line numbers, block-aware indentation, horizontal and vertical scrolling, and Find.
- The bottom shell is persistent: variables and functions survive between entries. Use Shift+Enter to write a multi-line shell entry, or enter a block one line at a time.
- Shell input is routed to a running program while it is waiting for `Ask`; otherwise, it goes to the persistent Tell REPL.
- Run a module with F5, check syntax with F7, build native bytecode with Ctrl+B, and run project tests with Ctrl+T.
- Build output is written beside the source as `.tbc`. The IDE asks before replacing an existing bytecode file.
- Run and check can execute the current unsaved buffer as a temporary source file in the same directory, preserving relative module lookup. Temporary files are removed when the command exits.
This command prints a deprecation warning. The standalone tell-ide Python
console entry point is no longer installed by new package builds.

The IDE is an editor and runtime console, not a debugger or language server. Highlighting is lexical and provides no static diagnostics while typing. Bytecode building requires the native Go runtime; ordinary run/check operations can use either runtime.
The legacy UI requires Python 3.10 or newer and Tkinter. Existing projects may
continue using it while migrating, but new features should be added to
studio/ and the native Go toolchain instead.

## Migration policy

For editor integration with the typed TellC language, see the separate [language server](../lsp/README.md).
The Python interpreter and IDE are not deleted in this change. They remain
compatibility components until supported Go runtime features and the Rust
editor reach sufficient parity. The Python runtime should receive only
security, compatibility, and migration fixes; new runtime features belong in
Go. The IDE should receive only critical compatibility fixes; new editor
features belong in GPUI Studio.
Loading
Loading