gwbasickernel 0.1.0__py3-none-any.whl

gwbasickernel/README.md

@@ -0,0 +1,80 @@
+# GW-BASIC Jupyter kernel
+
+Run GW-BASIC programs in JupyterLab or Notebook. Variables and program lines
+persist between cells. The kernel converts the interpreter's Sixel output to
+inline PNG images, so the notebook browser does not need Sixel support.
+
+Requires Python 3.10 or later and the native
+[GW-BASIC 2026 interpreter](https://github.com/evvaletov/gw-basic-2026)
+on Linux or macOS. The Python package does not include that interpreter.
+The DOS executables cannot be used as the notebook backend.
+
+## Install the interpreter
+
+With Homebrew on Linux or macOS:
+
+```sh
+brew tap evvaletov/gwbasic https://github.com/evvaletov/gw-basic-2026.git
+brew install evvaletov/gwbasic/gwbasic
+```
+
+The Homebrew formula builds from a pinned source revision. It includes the
+interpreter and native compiler, with PulseAudio disabled.
+
+Alternatively, build from source with a C11 compiler and CMake:
+
+```sh
+git clone https://github.com/evvaletov/gw-basic-2026.git
+cd gw-basic-2026
+cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
+cmake --build build --parallel 2
+export GWBASIC="$PWD/build/gwbasic"
+```
+
+## Install the kernel
+
+Create a Python environment for the kernel and JupyterLab:
+
+```sh
+python3 -m venv .venv
+. .venv/bin/activate
+python -m pip install gwbasickernel jupyterlab
+gwbasickernel-install --sys-prefix
+jupyter lab
+```
+
+Choose **GW-BASIC 2026** when creating a notebook. The kernel looks for the
+interpreter in `GWBASIC`, then on `PATH`. To save its location in the kernelspec,
+use this command instead of the installer command above:
+
+```sh
+gwbasickernel-install --sys-prefix --gwbasic /absolute/path/to/gwbasic
+```
+
+If Jupyter runs in another Python environment, use `--user` to register the
+kernel for your account. Keep the kernel's Python environment in place:
+the kernelspec records its Python executable.
+
+## Try it
+
+```basic
+10 FOR N=1 TO 8
+20 PRINT N;N*N
+30 NEXT N
+RUN
+```
+
+For graphics, clear the previous program first:
+
+```basic
+NEW
+10 SCREEN 1
+20 CIRCLE (160,100),80,2
+RUN
+```
+
+See the [executed graphics notebook](https://github.com/evvaletov/gw-basic-2026/blob/main/examples/graphics.ipynb)
+and [demo guide](https://github.com/evvaletov/gw-basic-2026/blob/main/docs/demos.md).
+
+`%new` clears the BASIC program; `%reset` starts a fresh interpreter process.
+`%timeout 60` changes the output wait timeout from its default of 30 seconds.

gwbasickernel/__init__.py

@@ -0,0 +1,3 @@
+"""Jupyter kernel for GW-BASIC 2026."""
+
+__version__ = '0.1.0'

gwbasickernel/__main__.py

@@ -0,0 +1,4 @@
+from ipykernel.kernelapp import IPKernelApp
+from .kernel import GWBasicKernel
+
+IPKernelApp.launch_instance(kernel_class=GWBasicKernel)

gwbasickernel/basic_lexer.py

@@ -0,0 +1,79 @@
+"""Pygments lexer for GW-BASIC."""
+
+from pygments.lexer import RegexLexer
+from pygments.token import (
+    Comment, Keyword, Name, Number, Operator, Punctuation, String, Text,
+)
+
+
+class GWBasicLexer(RegexLexer):
+    name = 'GW-BASIC'
+    aliases = ['gwbasic', 'basic']
+    filenames = ['*.bas', '*.BAS']
+    mimetypes = ['text/x-basic']
+
+    tokens = {
+        'root': [
+            # REM comments (to end of line)
+            (r"(?i)\bREM\b.*$", Comment.Single),
+            # Single-quote comments
+            (r"'.*$", Comment.Single),
+
+            # String literals
+            (r'"[^"]*"', String.Double),
+
+            # Line numbers at start of line
+            (r'^\s*\d+', Name.Label),
+
+            # Hex and octal literals
+            (r'&[Hh][0-9A-Fa-f]+', Number.Hex),
+            (r'&[Oo]?[0-7]+', Number.Oct),
+
+            # Floating point
+            (r'\d+\.\d*([eEdD][+-]?\d+)?[!#]?', Number.Float),
+            (r'\d+[eEdD][+-]?\d+[!#]?', Number.Float),
+
+            # Integer
+            (r'\d+[%!#]?', Number.Integer),
+
+            # Statements / keywords
+            (r'(?i)\b(AUTO|BEEP|BLOAD|BSAVE|CALL|CALLS|CHAIN|CHDIR|CIRCLE'
+             r'|CLEAR|CLOSE|CLS|COLOR|COM|COMMON|CONT|DATA|DEF\s+SEG'
+             r'|DEF\s+FN|DEFDBL|DEFINT|DEFSNG|DEFSTR|DELETE|DIM|DRAW'
+             r'|EDIT|ELSE|END|ENVIRON|ERASE|ERROR|FIELD|FILES|FOR|GET'
+             r'|GOSUB|GOTO|IF|INPUT|KEY|KILL|LCOPY|LET|LINE\s+INPUT'
+             r'|LINE|LIST|LLIST|LOAD|LOCATE|LPRINT|LSET|MERGE|MKDIR'
+             r'|MOTOR|NAME|NEW|NEXT|ON|OPEN|OPTION\s+BASE|OUT|PAINT'
+             r'|PALETTE|PLAY|POKE|PRESET|PRINT|PSET|PUT|RANDOMIZE'
+             r'|READ|REM|RENUM|RESET|RESTORE|RESUME|RETURN|RMDIR|RSET'
+             r'|RUN|SAVE|SCREEN|SHELL|SOUND|STOP|SWAP|SYSTEM|THEN|TIMER'
+             r'|TO|TRON|TROFF|USING|VIEW|WAIT|WEND|WHILE|WIDTH|WINDOW'
+             r'|WRITE)\b', Keyword),
+
+            # Built-in functions
+            (r'(?i)\b(ABS|ASC|ATN|CDBL|CHR\$|CINT|COS|CSNG|CSRLIN'
+             r'|CVD|CVI|CVS|DATE\$|EOF|ENVIRON\$|ERDEV\$?|ERL|ERR'
+             r'|EXP|FIX|FN|FRE|HEX\$|INKEY\$|INP|INPUT\$|INSTR|INT'
+             r'|IOCTL\$|LEFT\$|LEN|LOC|LOF|LOG|LPOS|MID\$|MKD\$'
+             r'|MKI\$|MKS\$|OCT\$|PEEK|PEN|PMAP|POINT|POS|RIGHT\$'
+             r'|RND|SGN|SIN|SPACE\$|SPC|SQR|STICK|STR\$|STRIG'
+             r'|STRING\$|TAB|TAN|TIME\$|TIMER|USR|VAL|VARPTR\$?)\b',
+             Name.Builtin),
+
+            # Logical / arithmetic operators as keywords
+            (r'(?i)\b(AND|EQV|IMP|MOD|NOT|OR|XOR|STEP)\b', Operator.Word),
+
+            # Operators
+            (r'[+\-*/\\^<>=]', Operator),
+            (r'<>|<=|>=', Operator),
+
+            # Punctuation
+            (r'[(),;:#]', Punctuation),
+
+            # Identifiers (variable names)
+            (r'[A-Za-z][A-Za-z0-9]*[%!#$]?', Name),
+
+            # Whitespace
+            (r'\s+', Text),
+        ],
+    }

gwbasickernel/install.py

@@ -0,0 +1,60 @@
+"""Install the GW-BASIC kernel into Jupyter."""
+
+import argparse
+import json
+import shutil
+import sys
+import tempfile
+from pathlib import Path
+
+
+def install_kernel(user=True, prefix=None, gwbasic=None):
+    from jupyter_client.kernelspec import KernelSpecManager
+
+    spec = json.loads((Path(__file__).parent / 'kernel.json').read_text())
+    spec['argv'][0] = sys.executable
+    if gwbasic is not None:
+        binary = shutil.which(str(gwbasic))
+        if binary is None:
+            raise ValueError(f'GW-BASIC executable not found: {gwbasic}')
+        spec['env'] = {'GWBASIC': str(Path(binary).absolute())}
+
+    with tempfile.TemporaryDirectory() as td:
+        dest = Path(td) / 'gwbasic'
+        dest.mkdir()
+        (dest / 'kernel.json').write_text(json.dumps(spec, indent=2) + '\n')
+
+        ksm = KernelSpecManager()
+        ksm.install_kernel_spec(
+            str(dest), kernel_name='gwbasic', user=user, prefix=prefix,
+        )
+
+    print('GW-BASIC kernel installed successfully.')
+    print('Run "jupyter kernelspec list" to verify.')
+
+
+def main():
+    parser = argparse.ArgumentParser(description='Install the GW-BASIC Jupyter kernel')
+    location = parser.add_mutually_exclusive_group()
+    location.add_argument('--user', action='store_true',
+                        help='Install for the current user (default)')
+    location.add_argument('--sys-prefix', action='store_true',
+                        help='Install into sys.prefix (for virtualenvs)')
+    location.add_argument('--prefix', type=str, default=None,
+                        help='Install into a specific prefix')
+    parser.add_argument('--gwbasic', help='Interpreter executable to save in the kernelspec')
+    args = parser.parse_args()
+
+    try:
+        if args.sys_prefix:
+            install_kernel(user=False, prefix=sys.prefix, gwbasic=args.gwbasic)
+        elif args.prefix:
+            install_kernel(user=False, prefix=args.prefix, gwbasic=args.gwbasic)
+        else:
+            install_kernel(gwbasic=args.gwbasic)
+    except ValueError as exc:
+        parser.error(str(exc))
+
+
+if __name__ == '__main__':
+    main()

gwbasickernel/kernel.json

@@ -0,0 +1,8 @@
+{
+  "argv": ["python", "-m", "gwbasickernel", "-f", "{connection_file}"],
+  "display_name": "GW-BASIC 2026",
+  "language": "basic",
+  "metadata": {
+    "debugger": false
+  }
+}

gwbasickernel/kernel.py

@@ -0,0 +1,575 @@
+"""Jupyter kernel for GW-BASIC 2026.
+
+Persistent process model: a long-running gwbasic subprocess reads BASIC
+commands from stdin and writes output to stdout.  The kernel sends each
+notebook cell as one or more lines of BASIC, followed by a sentinel
+PRINT that emits a known delimiter.  Output is captured until the
+delimiter appears, then forwarded to the notebook.
+
+GW-BASIC's piped mode suppresses the banner and "Ok" prompt automatically,
+and stdout is unbuffered, making it ideal for subprocess communication.
+
+Features beyond basic execution:
+  - Inline Sixel graphics: ESC P ... ESC \\ sequences are extracted from
+    the output stream, decoded into PNG images, and displayed inline.
+  - INPUT statement support: when gwbasic prints "? " (the INPUT prompt),
+    the kernel requests input from the notebook front-end via the Jupyter
+    stdin protocol.
+  - Pygments lexer: GW-BASIC syntax highlighting in notebooks.
+  - Tab completion for all GW-BASIC keywords.
+"""
+
+import base64
+import io
+import os
+import re
+import select
+import shutil
+import signal
+import struct
+import subprocess
+import zlib
+
+from ipykernel.kernelbase import Kernel
+
+from . import __version__
+
+_SENTINEL = '\x01GWDONE\x01'
+_SENTINEL_CMD = 'PRINT CHR$(1)+"GWDONE"+CHR$(1)\n'
+
+_ERROR_RE = re.compile(
+    r'(?:Syntax error|Illegal function call|Type mismatch|Out of |'
+    r'Division by zero|Overflow|RETURN without GOSUB|'
+    r'NEXT without FOR|Undefined |Subscript out of range|'
+    r'Redo from start|String too long|'
+    r'WHILE without WEND|WEND without WHILE|'
+    r'File not found|File already open|Bad file |'
+    r'Direct statement in file|Missing operand|'
+    r'Duplicate Definition|Formula too complex|'
+    r'Internal error|Unprintable error)',
+    re.IGNORECASE,
+)
+
+# DCS (ESC P) starts Sixel, ST (ESC \) ends it — both as bytes
+_DCS = b'\x1bP'
+_ST = b'\x1b\\'
+
+GW_KEYWORDS = [
+    'AUTO', 'BEEP', 'BLOAD', 'BSAVE', 'CALL', 'CHAIN', 'CHDIR',
+    'CIRCLE', 'CLEAR', 'CLOSE', 'CLS', 'COLOR', 'COM', 'COMMON',
+    'CONT', 'DATA', 'DATE$', 'DEF', 'DEFDBL', 'DEFINT', 'DEFSNG',
+    'DEFSTR', 'DELETE', 'DIM', 'DRAW', 'EDIT', 'ELSE', 'END',
+    'ENVIRON', 'ENVIRON$', 'ERASE', 'ERDEV', 'ERDEV$', 'ERR', 'ERL',
+    'ERROR', 'FIELD', 'FILES', 'FN', 'FOR', 'GET', 'GOSUB', 'GOTO',
+    'IF', 'INPUT', 'IOCTL', 'IOCTL$', 'KEY', 'KILL', 'LCOPY',
+    'LET', 'LINE', 'LIST', 'LLIST', 'LOAD', 'LOCATE', 'LPRINT',
+    'LSET', 'MERGE', 'MKDIR', 'MOTOR', 'NAME', 'NEW', 'NEXT',
+    'NOISE', 'ON', 'OPEN', 'OPTION', 'OUT', 'PAINT', 'PALETTE',
+    'PLAY', 'POKE', 'PRESET', 'PRINT', 'PSET', 'PUT', 'RANDOMIZE',
+    'READ', 'REM', 'RENUM', 'RESET', 'RESTORE', 'RESUME', 'RETURN',
+    'RMDIR', 'RSET', 'RUN', 'SAVE', 'SCREEN', 'SHELL', 'SOUND',
+    'STOP', 'SWAP', 'SYSTEM', 'THEN', 'TIME$', 'TIMER', 'TO',
+    'TRON', 'TROFF', 'VIEW', 'WAIT', 'WEND', 'WHILE', 'WIDTH',
+    'WINDOW', 'WRITE',
+    'ABS', 'ASC', 'ATN', 'CDBL', 'CHR$', 'CINT', 'COS', 'CSNG',
+    'CSRLIN', 'CVD', 'CVI', 'CVS', 'EOF', 'EXP', 'FIX', 'FRE',
+    'HEX$', 'INKEY$', 'INP', 'INPUT$', 'INSTR', 'INT', 'LEFT$',
+    'LEN', 'LOC', 'LOF', 'LOG', 'LPOS', 'MID$', 'MKD$', 'MKI$',
+    'MKS$', 'OCT$', 'PEEK', 'PEN', 'PMAP', 'POINT', 'POS',
+    'RIGHT$', 'RND', 'SGN', 'SIN', 'SPACE$', 'SPC', 'SQR',
+    'STICK', 'STR$', 'STRIG', 'STRING$', 'TAB', 'TAN', 'USR',
+    'VAL', 'VARPTR', 'VARPTR$',
+    'AND', 'EQV', 'IMP', 'MOD', 'NOT', 'OR', 'XOR', 'STEP',
+]
+
+
+# ---------- Sixel decoder (pure Python, no PIL dependency) ----------
+
+def _parse_sixel_palette(data):
+    """Parse #n;2;r;g;b palette definitions from Sixel data."""
+    palette = {}
+    for m in re.finditer(rb'#(\d+);2;(\d+);(\d+);(\d+)', data):
+        idx = int(m.group(1))
+        r = int(m.group(2)) * 255 // 100
+        g = int(m.group(3)) * 255 // 100
+        b = int(m.group(4)) * 255 // 100
+        palette[idx] = (r, g, b)
+    return palette
+
+
+def _decode_sixel(data):
+    """Decode Sixel data into an RGBA image. Returns (width, height, rgba_bytes)."""
+    # Strip DCS/ST wrappers if present
+    if data.startswith(_DCS):
+        data = data[len(_DCS):]
+    if data.endswith(_ST):
+        data = data[:-len(_ST)]
+
+    # Skip mode char (usually 'q')
+    if data and data[0:1] == b'q':
+        data = data[1:]
+
+    palette = _parse_sixel_palette(data)
+    if not palette:
+        palette = {0: (0, 0, 0)}
+
+    # First pass: determine image dimensions
+    x = 0
+    y = 0
+    max_x = 0
+    max_y = 0
+    color = 0
+    i = 0
+    while i < len(data):
+        ch = data[i]
+        if ch == ord('#'):
+            # Color selector or palette def — skip palette defs
+            j = i + 1
+            num = b''
+            while j < len(data) and (data[j] in b'0123456789'):
+                num += bytes([data[j]])
+                j += 1
+            if j < len(data) and data[j] == ord(';'):
+                # Palette definition — skip to end
+                while j < len(data) and data[j] not in b'#$-\x1b' and not (63 <= data[j] <= 126):
+                    j += 1
+                i = j
+                continue
+            color = int(num) if num else 0
+            i = j
+        elif ch == ord('$'):
+            x = 0
+            i += 1
+        elif ch == ord('-'):
+            x = 0
+            y += 6
+            i += 1
+        elif ch == ord('!'):
+            # RLE: !count<char>
+            j = i + 1
+            num = b''
+            while j < len(data) and data[j] in b'0123456789':
+                num += bytes([data[j]])
+                j += 1
+            count = int(num) if num else 1
+            if j < len(data) and 63 <= data[j] <= 126:
+                x += count
+                j += 1
+            max_x = max(max_x, x)
+            max_y = max(max_y, y + 6)
+            i = j
+        elif 63 <= ch <= 126:
+            x += 1
+            max_x = max(max_x, x)
+            max_y = max(max_y, y + 6)
+            i += 1
+        else:
+            i += 1
+
+    if max_x == 0 or max_y == 0:
+        return 0, 0, b''
+
+    width, height = max_x, max_y
+    # RGBA buffer (transparent background)
+    pixels = bytearray(width * height * 4)
+
+    # Second pass: render pixels
+    x = 0
+    y = 0
+    color = 0
+    i = 0
+    while i < len(data):
+        ch = data[i]
+        if ch == ord('#'):
+            j = i + 1
+            num = b''
+            while j < len(data) and data[j] in b'0123456789':
+                num += bytes([data[j]])
+                j += 1
+            if j < len(data) and data[j] == ord(';'):
+                while j < len(data) and data[j] not in b'#$-\x1b' and not (63 <= data[j] <= 126):
+                    j += 1
+                i = j
+                continue
+            color = int(num) if num else 0
+            i = j
+        elif ch == ord('$'):
+            x = 0
+            i += 1
+        elif ch == ord('-'):
+            x = 0
+            y += 6
+            i += 1
+        elif ch == ord('!'):
+            j = i + 1
+            num = b''
+            while j < len(data) and data[j] in b'0123456789':
+                num += bytes([data[j]])
+                j += 1
+            count = int(num) if num else 1
+            if j < len(data) and 63 <= data[j] <= 126:
+                sixel = data[j] - 63
+                j += 1
+                r, g, b = palette.get(color, (0, 0, 0))
+                for dx in range(count):
+                    cx = x + dx
+                    if cx >= width:
+                        break
+                    for bit in range(6):
+                        if sixel & (1 << bit):
+                            cy = y + bit
+                            if cy < height:
+                                off = (cy * width + cx) * 4
+                                pixels[off] = r
+                                pixels[off + 1] = g
+                                pixels[off + 2] = b
+                                pixels[off + 3] = 255
+                x += count
+            i = j
+        elif 63 <= ch <= 126:
+            sixel = ch - 63
+            r, g, b = palette.get(color, (0, 0, 0))
+            if x < width:
+                for bit in range(6):
+                    if sixel & (1 << bit):
+                        cy = y + bit
+                        if cy < height:
+                            off = (cy * width + x) * 4
+                            pixels[off] = r
+                            pixels[off + 1] = g
+                            pixels[off + 2] = b
+                            pixels[off + 3] = 255
+            x += 1
+            i += 1
+        else:
+            i += 1
+
+    return width, height, bytes(pixels)
+
+
+def _rgba_to_png(width, height, rgba):
+    """Encode raw RGBA pixels as PNG (pure Python, no dependencies)."""
+    def _chunk(tag, data):
+        c = tag + data
+        return struct.pack('>I', len(data)) + c + struct.pack('>I', zlib.crc32(c) & 0xFFFFFFFF)
+
+    ihdr = struct.pack('>IIBBBBB', width, height, 8, 6, 0, 0, 0)
+    raw = b''
+    stride = width * 4
+    for y in range(height):
+        raw += b'\x00' + rgba[y * stride:(y + 1) * stride]
+    idat = zlib.compress(raw)
+
+    out = b'\x89PNG\r\n\x1a\n'
+    out += _chunk(b'IHDR', ihdr)
+    out += _chunk(b'IDAT', idat)
+    out += _chunk(b'IEND', b'')
+    return out
+
+
+# ---------- Kernel class ----------
+
+class GWBasicKernel(Kernel):
+    implementation = 'gwbasickernel'
+    implementation_version = __version__
+    language = 'basic'
+    language_version = '2026'
+    language_info = {
+        'name': 'basic',
+        'mimetype': 'text/x-basic',
+        'file_extension': '.bas',
+        'codemirror_mode': 'vb',
+        'pygments_lexer': 'gwbasickernel.basic_lexer.GWBasicLexer',
+    }
+    banner = 'GW-BASIC 2026 Jupyter Kernel'
+
+    def __init__(self, **kwargs):
+        super().__init__(**kwargs)
+        self._proc = None
+        self._timeout = int(os.environ.get('GWBASIC_TIMEOUT', '30'))
+
+    def _find_binary(self):
+        env = os.environ.get('GWBASIC')
+        if env and os.path.isfile(env) and os.access(env, os.X_OK):
+            return env
+        for candidate in ['gwbasic', './build/gwbasic', './gwbasic']:
+            found = shutil.which(candidate)
+            if found:
+                return found
+        return None
+
+    def _start_process(self):
+        self._kill_process()
+        binary = self._find_binary()
+        if not binary:
+            return False
+        self._proc = subprocess.Popen(
+            [binary],
+            stdin=subprocess.PIPE,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.STDOUT,
+            bufsize=0,
+        )
+        return True
+
+    def _kill_process(self):
+        if self._proc is not None:
+            try:
+                self._proc.kill()
+                self._proc.wait(timeout=5)
+            except (ProcessLookupError, subprocess.TimeoutExpired):
+                pass
+            self._proc = None
+
+    def _is_alive(self):
+        return self._proc is not None and self._proc.poll() is None
+
+    def _send_interrupt_children(self):
+        if self._is_alive():
+            self._proc.send_signal(signal.SIGINT)
+        else:
+            super()._send_interrupt_children()
+
+    def _read_until_sentinel(self, allow_stdin=False):
+        """Read raw bytes from stdout until sentinel or timeout.
+
+        When allow_stdin is True and the output ends with "? " (INPUT prompt),
+        the kernel requests input from the notebook front-end and writes the
+        response to the subprocess's stdin.
+
+        Returns (raw_bytes, status).
+        """
+        fd = self._proc.stdout.fileno()
+        buf = b''
+        sentinel_bytes = _SENTINEL.encode()
+
+        while True:
+            try:
+                ready, _, _ = select.select([fd], [], [], self._timeout)
+            except (KeyboardInterrupt, InterruptedError):
+                if self._is_alive():
+                    self._proc.send_signal(signal.SIGINT)
+                return buf, 'interrupted'
+
+            if not ready:
+                # Check for INPUT prompt before declaring timeout
+                if allow_stdin and buf.endswith(b'? '):
+                    reply = self.raw_input('? ')
+                    self._proc.stdin.write((reply + '\n').encode())
+                    self._proc.stdin.flush()
+                    continue
+                return buf, 'timeout'
+
+            chunk = os.read(fd, 8192)
+            if not chunk:
+                return buf, 'died'
+
+            buf += chunk
+
+            # Check for sentinel in the buffer
+            if sentinel_bytes in buf:
+                idx = buf.index(sentinel_bytes)
+                # Keep everything before the sentinel, stripping the
+                # PRINT output that contains it (newline + sentinel + newline)
+                before = buf[:idx]
+                # Remove trailing newline left by PRINT before sentinel
+                if before.endswith(b'\n'):
+                    before = before[:-1]
+                return before, 'done'
+
+            # Check for INPUT prompt: "? " at end of buffer (no newline after)
+            if allow_stdin and buf.endswith(b'? '):
+                last_nl = buf.rfind(b'\n')
+                tail = buf[last_nl + 1:] if last_nl >= 0 else buf
+                if b'\n' not in tail[:-2]:  # no embedded newline before "? "
+                    prompt_line = tail.decode('utf-8', errors='replace')
+                    reply = self.raw_input(prompt_line)
+                    self._proc.stdin.write((reply + '\n').encode())
+                    self._proc.stdin.flush()
+
+    def _split_sixel(self, raw):
+        """Split raw output into (text_parts, sixel_blobs) interleaved."""
+        parts = []
+        pos = 0
+        while True:
+            dcs_idx = raw.find(_DCS, pos)
+            if dcs_idx == -1:
+                parts.append(('text', raw[pos:]))
+                break
+            if dcs_idx > pos:
+                parts.append(('text', raw[pos:dcs_idx]))
+            st_idx = raw.find(_ST, dcs_idx)
+            if st_idx == -1:
+                parts.append(('text', raw[pos:]))
+                break
+            end = st_idx + len(_ST)
+            parts.append(('sixel', raw[dcs_idx:end]))
+            pos = end
+        return parts
+
+    def _has_error(self, text):
+        return bool(_ERROR_RE.search(text))
+
+    def _handle_magic(self, code):
+        stripped = code.strip()
+        if stripped == '%reset':
+            self._kill_process()
+            return True, 'Session reset.'
+        if stripped.startswith('%timeout'):
+            parts = stripped.split()
+            if len(parts) == 2:
+                try:
+                    self._timeout = int(parts[1])
+                    return True, f'Timeout set to {self._timeout}s.'
+                except ValueError:
+                    return True, 'Usage: %timeout <seconds>'
+            return True, f'Current timeout: {self._timeout}s. Usage: %timeout <seconds>'
+        if stripped == '%new':
+            if self._is_alive():
+                self._proc.stdin.write(b'NEW\n')
+                self._proc.stdin.write(_SENTINEL_CMD.encode())
+                self._proc.stdin.flush()
+                self._read_until_sentinel()
+            return True, 'Program cleared.'
+        return False, None
+
+    def do_execute(self, code, silent, store_history=True,
+                   user_expressions=None, allow_stdin=False):
+        handled, response = self._handle_magic(code)
+        if handled:
+            if not silent and response:
+                self.send_response(self.iopub_socket, 'stream',
+                                   {'name': 'stdout', 'text': response + '\n'})
+            return {
+                'status': 'ok', 'execution_count': self.execution_count,
+                'payload': [], 'user_expressions': {},
+            }
+
+        if not code.strip():
+            return {
+                'status': 'ok', 'execution_count': self.execution_count,
+                'payload': [], 'user_expressions': {},
+            }
+
+        if not self._is_alive():
+            if not self._start_process():
+                if not silent:
+                    self.send_response(self.iopub_socket, 'stream', {
+                        'name': 'stderr',
+                        'text': 'gwbasic binary not found.\n'
+                                'Set GWBASIC env var or install gwbasic on PATH.\n',
+                    })
+                return {
+                    'status': 'error', 'execution_count': self.execution_count,
+                    'ename': 'FileNotFoundError', 'evalue': 'gwbasic not found',
+                    'traceback': [],
+                }
+
+        for line in code.split('\n'):
+            line = line.rstrip()
+            if line:
+                self._proc.stdin.write((line + '\n').encode())
+
+        self._proc.stdin.write(_SENTINEL_CMD.encode())
+        self._proc.stdin.flush()
+
+        raw, status = self._read_until_sentinel(allow_stdin=allow_stdin)
+
+        if status == 'interrupted':
+            if not silent:
+                self.send_response(self.iopub_socket, 'stream', {
+                    'name': 'stderr', 'text': 'Execution interrupted.\n',
+                })
+            return {'status': 'abort', 'execution_count': self.execution_count}
+
+        if status == 'timeout':
+            self._kill_process()
+            if not silent:
+                self.send_response(self.iopub_socket, 'stream', {
+                    'name': 'stderr',
+                    'text': f'Execution timed out after {self._timeout}s. '
+                            f'Use %timeout to increase.\n',
+                })
+            return {
+                'status': 'error', 'execution_count': self.execution_count,
+                'ename': 'TimeoutError',
+                'evalue': f'Timed out after {self._timeout}s',
+                'traceback': [],
+            }
+
+        if status == 'died':
+            self._proc = None
+            text = raw.decode('utf-8', errors='replace').strip()
+            if not silent and text:
+                self.send_response(self.iopub_socket, 'stream', {
+                    'name': 'stderr',
+                    'text': f'GW-BASIC process exited.\n{text}\n',
+                })
+            return {
+                'status': 'error', 'execution_count': self.execution_count,
+                'ename': 'RuntimeError', 'evalue': 'Process exited',
+                'traceback': [],
+            }
+
+        # Split output into text and Sixel graphics
+        parts = self._split_sixel(raw)
+
+        is_error = False
+        for kind, data in parts:
+            if kind == 'text':
+                text = data.decode('utf-8', errors='replace').strip()
+                if not text:
+                    continue
+                if self._has_error(text):
+                    is_error = True
+                if not silent:
+                    self.send_response(self.iopub_socket, 'stream', {
+                        'name': 'stderr' if is_error else 'stdout',
+                        'text': text + '\n',
+                    })
+            elif kind == 'sixel' and not silent:
+                w, h, rgba = _decode_sixel(data)
+                if w > 0 and h > 0:
+                    png = _rgba_to_png(w, h, rgba)
+                    b64 = base64.b64encode(png).decode('ascii')
+                    self.send_response(self.iopub_socket, 'display_data', {
+                        'data': {'image/png': b64},
+                        'metadata': {'image/png': {'width': w, 'height': h}},
+                    })
+
+        if is_error:
+            err_text = raw.decode('utf-8', errors='replace').strip()
+            return {
+                'status': 'error', 'execution_count': self.execution_count,
+                'ename': 'BASICError', 'evalue': err_text.split('\n')[0],
+                'traceback': err_text.split('\n'),
+            }
+
+        return {
+            'status': 'ok', 'execution_count': self.execution_count,
+            'payload': [], 'user_expressions': {},
+        }
+
+    def do_complete(self, code, cursor_pos):
+        text = code[:cursor_pos]
+        match = re.search(r'([A-Za-z_]\w*\$?)$', text)
+        if not match:
+            return {'matches': [], 'cursor_start': cursor_pos,
+                    'cursor_end': cursor_pos, 'status': 'ok'}
+
+        token = match.group(1).upper()
+        start = cursor_pos - len(token)
+        matches = [kw for kw in GW_KEYWORDS if kw.startswith(token)]
+        return {
+            'matches': matches, 'cursor_start': start,
+            'cursor_end': cursor_pos, 'status': 'ok',
+        }
+
+    def do_is_complete(self, code):
+        if not code.strip():
+            return {'status': 'incomplete', 'indent': ''}
+        return {'status': 'complete'}
+
+    def do_shutdown(self, restart):
+        self._kill_process()
+        return {'status': 'ok', 'restart': restart}

gwbasickernel/test_kernel.py

@@ -0,0 +1,140 @@
+"""Smoke test for the GW-BASIC Jupyter kernel.
+
+Spawns the kernel class directly and exercises the do_execute path
+via the subprocess protocol. No running Jupyter instance required.
+"""
+
+import os
+import sys
+
+# Ensure gwbasic binary is found
+os.environ['GWBASIC'] = os.path.join(os.path.dirname(__file__), '..', 'build', 'gwbasic')
+
+
+def test_kernel():
+    from .kernel import GWBasicKernel, _decode_sixel, _rgba_to_png
+
+    # Minimal mock — we only need the subprocess communication, not ZMQ
+    class MockKernel(GWBasicKernel):
+        execution_count = 1
+        iopub_socket = None
+        _captured = []
+
+        def __init__(self):
+            self._proc = None
+            self._timeout = 10
+
+        def send_response(self, socket, msg_type, content):
+            self._captured.append((msg_type, content))
+
+    k = MockKernel()
+
+    def run(code):
+        k._captured = []
+        result = k.do_execute(code, silent=False)
+        text = ''
+        has_image = False
+        for msg_type, content in k._captured:
+            if msg_type == 'stream':
+                text += content.get('text', '')
+            elif msg_type == 'display_data':
+                has_image = True
+        return result, text.strip(), has_image
+
+    # Test 1: Simple PRINT
+    r, out, _ = run('PRINT "Hello Jupyter"')
+    assert r['status'] == 'ok', f'Expected ok, got {r}'
+    assert 'Hello Jupyter' in out, f'Expected Hello Jupyter, got: {out}'
+    print(f'  PASS  PRINT: {out}')
+
+    # Test 2: Arithmetic
+    r, out, _ = run('PRINT 6*7')
+    assert r['status'] == 'ok'
+    assert '42' in out, f'Expected 42, got: {out}'
+    print(f'  PASS  Arithmetic: {out}')
+
+    # Test 3: State persistence across cells
+    r, _, _ = run('X = 42')
+    assert r['status'] == 'ok'
+    r, out, _ = run('PRINT X')
+    assert '42' in out, f'Expected 42, got: {out}'
+    print(f'  PASS  State persistence: {out}')
+
+    # Test 4: Error handling
+    r, out, _ = run('PRINT 1/0')
+    assert r['status'] == 'error', f'Expected error, got {r}'
+    assert 'Division by zero' in out, f'Expected Division by zero, got: {out}'
+    print(f'  PASS  Error: {out}')
+
+    # Test 5: Recovery after error
+    r, out, _ = run('PRINT "OK after error"')
+    assert r['status'] == 'ok'
+    assert 'OK after error' in out
+    print(f'  PASS  Recovery: {out}')
+
+    # Test 6: Program RUN
+    r, _, _ = run('10 PRINT "Alpha"\n20 PRINT "Beta"')
+    assert r['status'] == 'ok'
+    r, out, _ = run('RUN')
+    assert 'Alpha' in out and 'Beta' in out, f'Expected Alpha+Beta, got: {out}'
+    print(f'  PASS  RUN: {repr(out)}')
+
+    # Test 7: Magic %reset
+    r, out, _ = run('%reset')
+    assert r['status'] == 'ok'
+    assert 'reset' in out.lower()
+    print(f'  PASS  %reset: {out}')
+
+    # Test 8: String functions
+    r, out, _ = run('PRINT LEFT$("HELLO", 3)')
+    assert 'HEL' in out, f'Expected HEL, got: {out}'
+    print(f'  PASS  String functions: {out}')
+
+    # Test 9: Multi-statement line
+    r, out, _ = run('A=10:B=20:PRINT A+B')
+    assert '30' in out, f'Expected 30, got: {out}'
+    print(f'  PASS  Multi-statement: {out}')
+
+    # Test 10: FRE returns real value
+    r, out, _ = run('PRINT FRE(0)')
+    assert r['status'] == 'ok'
+    print(f'  PASS  FRE: {out}')
+
+    # Test 11: Sixel decoder (unit test)
+    # Minimal Sixel: single red pixel at position (0,0)
+    # '@' = ASCII 64 = sixel value 1 = bit 0 set = row 0 pixel
+    sixel_data = b'\x1bPq#1;2;100;0;0#1@\x1b\\'
+    w, h, rgba = _decode_sixel(sixel_data)
+    assert w == 1 and h == 6, f'Expected 1x6, got {w}x{h}'
+    # Pixel (0,0) should be red (255,0,0,255)
+    assert rgba[0] == 255 and rgba[1] == 0 and rgba[2] == 0 and rgba[3] == 255, \
+        f'Expected red pixel, got {list(rgba[:4])}'
+    print(f'  PASS  Sixel decode: {w}x{h} pixel')
+
+    # Test 12: PNG encoder (unit test)
+    png = _rgba_to_png(1, 1, bytes([255, 0, 0, 255]))
+    assert png[:8] == b'\x89PNG\r\n\x1a\n', 'Invalid PNG header'
+    print(f'  PASS  PNG encode: {len(png)} bytes')
+
+    # Test 13: Sixel graphics via SCREEN (integration)
+    r, out, has_img = run('SCREEN 1\nPSET (10,10), 1\nSCREEN 0')
+    # The Sixel output should be detected and rendered as an image
+    assert r['status'] == 'ok', f'Expected ok, got {r}'
+    if has_img:
+        print('  PASS  Sixel graphics: inline image rendered')
+    else:
+        print('  PASS  Sixel graphics: no image (Sixel may not be emitted in piped mode)')
+
+    # Test 14: Pygments lexer loads
+    from .basic_lexer import GWBasicLexer
+    lexer = GWBasicLexer()
+    tokens = list(lexer.get_tokens('10 PRINT "Hello"'))
+    assert len(tokens) > 0, 'Lexer produced no tokens'
+    print(f'  PASS  Pygments lexer: {len(tokens)} tokens')
+
+    k.do_shutdown(False)
+    print(f'\n14 tests passed.')
+
+
+if __name__ == '__main__':
+    test_kernel()

gwbasickernel-0.1.0.dist-info/METADATA

@@ -0,0 +1,101 @@
+Metadata-Version: 2.4
+Name: gwbasickernel
+Version: 0.1.0
+Summary: Jupyter kernel for GW-BASIC 2026 with inline graphics
+Author: Eremey Valetov
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/evvaletov/gw-basic-2026
+Project-URL: Documentation, https://evvaletov.github.io/gw-basic-2026/
+Project-URL: Issues, https://github.com/evvaletov/gw-basic-2026/issues
+Classifier: Framework :: Jupyter
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: MacOS
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: ipykernel>=6
+Requires-Dist: jupyter_client>=8
+Requires-Dist: pygments>=2
+Dynamic: license-file
+
+# GW-BASIC Jupyter kernel
+
+Run GW-BASIC programs in JupyterLab or Notebook. Variables and program lines
+persist between cells. The kernel converts the interpreter's Sixel output to
+inline PNG images, so the notebook browser does not need Sixel support.
+
+Requires Python 3.10 or later and the native
+[GW-BASIC 2026 interpreter](https://github.com/evvaletov/gw-basic-2026)
+on Linux or macOS. The Python package does not include that interpreter.
+The DOS executables cannot be used as the notebook backend.
+
+## Install the interpreter
+
+With Homebrew on Linux or macOS:
+
+```sh
+brew tap evvaletov/gwbasic https://github.com/evvaletov/gw-basic-2026.git
+brew install evvaletov/gwbasic/gwbasic
+```
+
+The Homebrew formula builds from a pinned source revision. It includes the
+interpreter and native compiler, with PulseAudio disabled.
+
+Alternatively, build from source with a C11 compiler and CMake:
+
+```sh
+git clone https://github.com/evvaletov/gw-basic-2026.git
+cd gw-basic-2026
+cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
+cmake --build build --parallel 2
+export GWBASIC="$PWD/build/gwbasic"
+```
+
+## Install the kernel
+
+Create a Python environment for the kernel and JupyterLab:
+
+```sh
+python3 -m venv .venv
+. .venv/bin/activate
+python -m pip install gwbasickernel jupyterlab
+gwbasickernel-install --sys-prefix
+jupyter lab
+```
+
+Choose **GW-BASIC 2026** when creating a notebook. The kernel looks for the
+interpreter in `GWBASIC`, then on `PATH`. To save its location in the kernelspec,
+use this command instead of the installer command above:
+
+```sh
+gwbasickernel-install --sys-prefix --gwbasic /absolute/path/to/gwbasic
+```
+
+If Jupyter runs in another Python environment, use `--user` to register the
+kernel for your account. Keep the kernel's Python environment in place:
+the kernelspec records its Python executable.
+
+## Try it
+
+```basic
+10 FOR N=1 TO 8
+20 PRINT N;N*N
+30 NEXT N
+RUN
+```
+
+For graphics, clear the previous program first:
+
+```basic
+NEW
+10 SCREEN 1
+20 CIRCLE (160,100),80,2
+RUN
+```
+
+See the [executed graphics notebook](https://github.com/evvaletov/gw-basic-2026/blob/main/examples/graphics.ipynb)
+and [demo guide](https://github.com/evvaletov/gw-basic-2026/blob/main/docs/demos.md).
+
+`%new` clears the BASIC program; `%reset` starts a fresh interpreter process.
+`%timeout 60` changes the output wait timeout from its default of 30 seconds.

gwbasickernel-0.1.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+gwbasickernel/README.md,sha256=UxKKuCooAfd_9mC9ZIvUGLOtNtKXaWN_diTv3YwWS9Q,2352
+gwbasickernel/__init__.py,sha256=V0pJTh8MU9tJ7d0ZKK0VD3P36ZwG2IUduwhRXYGBScw,63
+gwbasickernel/__main__.py,sha256=ZRyXUypbCWf-wDm7fuZlFKzRbFxwHNB6F0Nuj4_9Ykc,135
+gwbasickernel/basic_lexer.py,sha256=ealwhWBtOMap0N0FrbddSyeRE1Dac-iyKcNv44DeHCc,2886
+gwbasickernel/install.py,sha256=KO9lclfYmoK4NCtc6s9aLB3IhtcwCIQLxXGiyIr2-o0,2111
+gwbasickernel/kernel.json,sha256=zTKt3s2oGWK0SEyj75O20pWTwDUzQMhs7gpIG51afvk,176
+gwbasickernel/kernel.py,sha256=xI7KCg_8l6XqwX_FNPp-TL9uocw4jUPTgRleNAqTxXA,20644
+gwbasickernel/test_kernel.py,sha256=5cmIHPkavIbN9VIPKB74EpnJM84uLWzev1SeoxZnK6c,4778
+gwbasickernel-0.1.0.dist-info/licenses/LICENSE,sha256=-mIPUvK6wSxeUkO82LHW_GbhCgP23AFZPoTJyS8AMY0,1071
+gwbasickernel-0.1.0.dist-info/METADATA,sha256=RTI5PmUHtG1Xj_goD8PXrIzLlAumyF8loyaWD89Gvc8,3090
+gwbasickernel-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+gwbasickernel-0.1.0.dist-info/entry_points.txt,sha256=u52KcGl979bG_JYZgBMIio8Y5NhVai_KB3HNY6vA7iE,137
+gwbasickernel-0.1.0.dist-info/top_level.txt,sha256=Zew3LBNrkia0PskUaC9Hvz1LeCp_Acoypcr21v9MoTs,14
+gwbasickernel-0.1.0.dist-info/RECORD,,

gwbasickernel-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

gwbasickernel-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,5 @@
+[console_scripts]
+gwbasickernel-install = gwbasickernel.install:main
+
+[pygments.lexers]
+gwbasic = gwbasickernel.basic_lexer:GWBasicLexer

gwbasickernel-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Eremey Valetov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

gwbasickernel-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+gwbasickernel