iversonnb 0.2.0__py3-none-any.whl

iversonnb/__init__.py

@@ -0,0 +1,9 @@
+__version__ = "0.2.0"
+
+from .core import *
+from .j import create_j_magic
+
+def load_ipython_extension(ipython):
+    "Register both the `apl` and `j` magics"
+    create_magic(shell=ipython)
+    create_j_magic(shell=ipython)

iversonnb/_modidx.py

@@ -0,0 +1,67 @@
+# Autogenerated by nbdev
+
+d = { 'settings': { 'branch': 'main',
+                'doc_baseurl': '/iversonnb',
+                'doc_host': 'https://answerdotai.github.io',
+                'git_url': 'https://github.com/answerdotai/iversonnb',
+                'lib_path': 'iversonnb'},
+  'syms': { 'iversonnb.core': { 'iversonnb.core.APLMagic': ('core.html#aplmagic', 'iversonnb/core.py'),
+                                'iversonnb.core.APLMagic.__init__': ('core.html#aplmagic.__init__', 'iversonnb/core.py'),
+                                'iversonnb.core.APLMagic.apl': ('core.html#aplmagic.apl', 'iversonnb/core.py'),
+                                'iversonnb.core.Apl': ('core.html#apl', 'iversonnb/core.py'),
+                                'iversonnb.core.Apl.__call__': ('core.html#apl.__call__', 'iversonnb/core.py'),
+                                'iversonnb.core.Apl.__enter__': ('core.html#apl.__enter__', 'iversonnb/core.py'),
+                                'iversonnb.core.Apl.__exit__': ('core.html#apl.__exit__', 'iversonnb/core.py'),
+                                'iversonnb.core.Apl.__getitem__': ('core.html#apl.__getitem__', 'iversonnb/core.py'),
+                                'iversonnb.core.Apl.__init__': ('core.html#apl.__init__', 'iversonnb/core.py'),
+                                'iversonnb.core.Apl.__setitem__': ('core.html#apl.__setitem__', 'iversonnb/core.py'),
+                                'iversonnb.core.Apl._connect': ('core.html#apl._connect', 'iversonnb/core.py'),
+                                'iversonnb.core.Apl.close': ('core.html#apl.close', 'iversonnb/core.py'),
+                                'iversonnb.core.Apl.fn': ('core.html#apl.fn', 'iversonnb/core.py'),
+                                'iversonnb.core.Apl.pyval': ('core.html#apl.pyval', 'iversonnb/core.py'),
+                                'iversonnb.core.Apl.run': ('core.html#apl.run', 'iversonnb/core.py'),
+                                'iversonnb.core.AplError': ('core.html#aplerror', 'iversonnb/core.py'),
+                                'iversonnb.core.AplError.__init__': ('core.html#aplerror.__init__', 'iversonnb/core.py'),
+                                'iversonnb.core.AplOut': ('core.html#aplout', 'iversonnb/core.py'),
+                                'iversonnb.core.AplOut.__repr__': ('core.html#aplout.__repr__', 'iversonnb/core.py'),
+                                'iversonnb.core.AplOut._repr_html_': ('core.html#aplout._repr_html_', 'iversonnb/core.py'),
+                                'iversonnb.core.AplPrompt': ('core.html#aplprompt', 'iversonnb/core.py'),
+                                'iversonnb.core.AplPrompt.__init__': ('core.html#aplprompt.__init__', 'iversonnb/core.py'),
+                                'iversonnb.core._apljson': ('core.html#_apljson', 'iversonnb/core.py'),
+                                'iversonnb.core._recvall': ('core.html#_recvall', 'iversonnb/core.py'),
+                                'iversonnb.core.create_ipython_config': ('core.html#create_ipython_config', 'iversonnb/core.py'),
+                                'iversonnb.core.create_magic': ('core.html#create_magic', 'iversonnb/core.py'),
+                                'iversonnb.core.find_dyalog': ('core.html#find_dyalog', 'iversonnb/core.py'),
+                                'iversonnb.core.load_ipython_extension': ('core.html#load_ipython_extension', 'iversonnb/core.py'),
+                                'iversonnb.core.ride_recv': ('core.html#ride_recv', 'iversonnb/core.py'),
+                                'iversonnb.core.ride_run': ('core.html#ride_run', 'iversonnb/core.py'),
+                                'iversonnb.core.ride_send': ('core.html#ride_send', 'iversonnb/core.py'),
+                                'iversonnb.core.start_dyalog': ('core.html#start_dyalog', 'iversonnb/core.py')},
+            'iversonnb.j': { 'iversonnb.j.J': ('j.html#j', 'iversonnb/j.py'),
+                             'iversonnb.j.J.__call__': ('j.html#j.__call__', 'iversonnb/j.py'),
+                             'iversonnb.j.J.__enter__': ('j.html#j.__enter__', 'iversonnb/j.py'),
+                             'iversonnb.j.J.__exit__': ('j.html#j.__exit__', 'iversonnb/j.py'),
+                             'iversonnb.j.J.__getitem__': ('j.html#j.__getitem__', 'iversonnb/j.py'),
+                             'iversonnb.j.J.__init__': ('j.html#j.__init__', 'iversonnb/j.py'),
+                             'iversonnb.j.J.__setitem__': ('j.html#j.__setitem__', 'iversonnb/j.py'),
+                             'iversonnb.j.J.close': ('j.html#j.close', 'iversonnb/j.py'),
+                             'iversonnb.j.J.fn': ('j.html#j.fn', 'iversonnb/j.py'),
+                             'iversonnb.j.J.getm': ('j.html#j.getm', 'iversonnb/j.py'),
+                             'iversonnb.j.J.interrupt': ('j.html#j.interrupt', 'iversonnb/j.py'),
+                             'iversonnb.j.J.pyval': ('j.html#j.pyval', 'iversonnb/j.py'),
+                             'iversonnb.j.J.run': ('j.html#j.run', 'iversonnb/j.py'),
+                             'iversonnb.j.JError': ('j.html#jerror', 'iversonnb/j.py'),
+                             'iversonnb.j.JMagic': ('j.html#jmagic', 'iversonnb/j.py'),
+                             'iversonnb.j.JMagic.__init__': ('j.html#jmagic.__init__', 'iversonnb/j.py'),
+                             'iversonnb.j.JMagic.j': ('j.html#jmagic.j', 'iversonnb/j.py'),
+                             'iversonnb.j.JOut': ('j.html#jout', 'iversonnb/j.py'),
+                             'iversonnb.j.JOut.__repr__': ('j.html#jout.__repr__', 'iversonnb/j.py'),
+                             'iversonnb.j._flat': ('j.html#_flat', 'iversonnb/j.py'),
+                             'iversonnb.j._jdat': ('j.html#_jdat', 'iversonnb/j.py'),
+                             'iversonnb.j._nest': ('j.html#_nest', 'iversonnb/j.py'),
+                             'iversonnb.j.create_j_magic': ('j.html#create_j_magic', 'iversonnb/j.py'),
+                             'iversonnb.j.find_j': ('j.html#find_j', 'iversonnb/j.py'),
+                             'iversonnb.j.load_ipython_extension': ('j.html#load_ipython_extension', 'iversonnb/j.py'),
+                             'iversonnb.j.load_j': ('j.html#load_j', 'iversonnb/j.py')},
+            'iversonnb.jkernel': {},
+            'iversonnb.kernel': {}}}

iversonnb/core.py

@@ -0,0 +1,253 @@
+"""Driving Dyalog APL over the RIDE protocol, and `apl` magics for Jupyter and IPython
+
+Docs: https://answerdotai.github.io/iversonnb/core.html.md"""
+
+# AUTOGENERATED! DO NOT EDIT! File to edit: ../00_core.ipynb.
+
+# %% auto #0
+__all__ = ['find_dyalog', 'start_dyalog', 'ride_send', 'ride_recv', 'AplError', 'AplPrompt', 'ride_run', 'Apl', 'AplOut',
+           'APLMagic', 'create_magic', 'load_ipython_extension', 'create_ipython_config']
+
+# %% ../00_core.ipynb #fe6dcafd
+import atexit,html,json,socket,subprocess
+from shutil import which
+from importlib.resources import files
+from fastcore.utils import *
+from fastcore.test import *
+from IPython.display import display, Javascript, HTML
+from IPython.paths import get_ipython_dir
+from IPython.utils.capture import capture_output
+
+
+# %% ../00_core.ipynb #0c05a3cc
+def find_dyalog():
+    "Locate the Dyalog interpreter binary"
+    if p:=which('mapl') or which('dyalog'): return p
+    apps = sorted(Path('/Applications').glob('Dyalog-*.app'))
+    if apps: return str(apps[-1]/'Contents/Resources/Dyalog/mapl')
+    vers = sorted(Path('/opt/mdyalog').glob('*/*/*/mapl'))
+    if vers: return str(vers[-1])
+    raise FileNotFoundError('Dyalog APL not found: install it from dyalog.com')
+
+# %% ../00_core.ipynb #ece90862
+def start_dyalog(
+    dyalog=None,  # Path to the interpreter binary; `find_dyalog()` result if None
+    timeout=10,   # Socket timeout (secs), so a client bug can never hang the caller
+):
+    "Spawn a Dyalog interpreter that connects back to us over RIDE; return `(socket,Popen)`"
+    if not dyalog: dyalog = find_dyalog()
+    lsn = socket.create_server(('127.0.0.1', 0))
+    port = lsn.getsockname()[1]
+    env = os.environ | dict(RIDE_INIT=f'CONNECT:127.0.0.1:{port}', RIDE_SPAWNED='1',
+        MAXAPLCORES=os.environ.get('MAXAPLCORES','0'),
+        DYALOGQUIETUCMDBUILD='1', DYALOG_LINEEDITOR_MODE='1', ENABLE_CEF='0', LOG_FILE_INUSE='0')
+    dn = subprocess.DEVNULL
+    proc = subprocess.Popen([dyalog], env=env, stdin=dn, stdout=dn, stderr=dn)
+    lsn.settimeout(10)
+    sock,_ = lsn.accept()
+    lsn.close()
+    sock.settimeout(timeout)
+    return sock,proc
+
+# %% ../00_core.ipynb #3ede6ea9
+def ride_send(sock, msg):
+    "Send one RIDE message: a handshake `str`, or a `[cmd,args]` list sent as JSON"
+    if not isinstance(msg,str): msg = json.dumps(msg, separators=(',',':'))
+    b = ('RIDE'+msg).encode()
+    sock.sendall((len(b)+4).to_bytes(4,'big')+b)
+
+def _recvall(sock, n):
+    parts = []
+    while n:
+        b = sock.recv(n)
+        if not b: raise ConnectionError('Dyalog closed the connection')
+        parts.append(b)
+        n -= len(b)
+    return b''.join(parts)
+
+def ride_recv(sock):
+    "Receive one RIDE message, JSON-decoded unless it's a handshake string"
+    hdr = _recvall(sock, 8)
+    assert hdr[4:8]==b'RIDE', f"Bad RIDE header: {hdr}"
+    msg = _recvall(sock, int.from_bytes(hdr[:4],'big')-8).decode()
+    msg = re.sub(r'[\x00-\x1f]', lambda m: f'\\u{ord(m[0]):04x}', msg)
+    return json.loads(msg) if msg[0]=='[' else msg
+
+
+# %% ../00_core.ipynb #8b0cdcfc
+class AplError(Exception):
+    "An APL error, carrying the session's error display as its message; `reset` means the interpreter was replaced and workspace state lost"
+    def __init__(self, msg, reset=False):
+        super().__init__(msg)
+        self.reset = reset
+
+class AplPrompt(Exception):
+    "The session stopped at a non-ready prompt: 2=⎕ input, 3=incomplete input, 4=⍞ input"
+    def __init__(self, ptype):
+        super().__init__(f'prompt type {ptype}')
+        self.ptype = ptype
+
+
+# %% ../00_core.ipynb #538b5ad9
+def ride_run(sock, code):
+    "Run one or more lines of APL in the session; return `(output,errno)` once the session is ready again"
+    lines = [l for l in code.splitlines() if l.strip()]
+    ride_send(sock, ['Execute',{'text':'\n'.join(lines)+'\n','trace':0}])
+    out,err,pending = '',0,len(lines)
+    while True:
+        m,a = ride_recv(sock)
+        if m=='AppendSessionOutput':
+            if a['type']==14: pending -= 1
+            elif a['type']!=1: out += a['result']
+        elif m=='HadError': err = a['error']
+        elif m=='SetPromptType' and a['type']!=0 and not pending:
+            if a['type']!=1: raise AplPrompt(a['type'])
+            return out,err
+
+
+# %% ../00_core.ipynb #23638f61
+class Apl:
+    "A Dyalog APL session over the RIDE protocol"
+    def __init__(self, dyalog=None, timeout=10):
+        store_attr()
+        self._connect()
+
+    def _connect(self):
+        self.sock,self.proc = start_dyalog(self.dyalog, self.timeout)
+        assert ride_recv(self.sock)=='SupportedProtocols=2'
+        ride_send(self.sock, 'SupportedProtocols=2')
+        ride_send(self.sock, 'UsingProtocol=2')
+        assert ride_recv(self.sock)=='UsingProtocol=2'
+        ride_send(self.sock, ['Identify',{'apiVersion':1,'identity':1}])
+        self.info = ride_recv(self.sock)[1]
+        ride_send(self.sock, ['SetPW',{'pw':32767}])
+        atexit.register(self.close)
+        while True:
+            m,a = ride_recv(self.sock)
+            if m=='SetPromptType' and a['type']==1: break
+        self.sock.settimeout(None)  # timeout guards startup only; run() waits as long as the code takes
+
+
+# %% ../00_core.ipynb #32eb4980
+@patch
+def close(self:Apl):
+    "Shut down the interpreter and close the connection"
+    atexit.unregister(self.close)
+    try: ride_send(self.sock, ['Exit',{'code':0}])
+    except OSError: pass
+    self.sock.close()
+    try: self.proc.wait(3)
+    except subprocess.TimeoutExpired:
+        self.proc.kill()
+        self.proc.wait()
+
+# %% ../00_core.ipynb #cc30073d
+@patch
+def run(self:Apl, code):
+    "Run `code` in the session, returning its output; raises `AplError` on APL errors"
+    try: out,err = ride_run(self.sock, code)
+    except AplPrompt as e:
+        if e.ptype in (2,4):
+            ride_run(self.sock, '→' if e.ptype==2 else '')
+            raise AplError('Input via ⎕ or ⍞ is not supported in iversonnb') from None
+        self.close()
+        self._connect()
+        raise AplError('Incomplete input wedged the Dyalog interpreter; started a fresh session (workspace lost). See Dyalog/ride#1401',
+            reset=True) from None
+    if err: raise AplError(out)
+    return out
+
+
+# %% ../00_core.ipynb #07eae6b5
+class AplOut(str):
+    "Output text from an `Apl` call; displays verbatim, in the SAX2 APL font where HTML is available"
+    def __repr__(self): return str(self)
+    def _repr_html_(self): return f'<pre class="iversonnb_out sax2">{html.escape(self.rstrip(chr(10)))}</pre>'
+
+@patch
+def __call__(self:Apl, code):
+    "Run `code`, returning session output (or None if there is none)"
+    return AplOut(self.run(code)) or None
+
+
+# %% ../00_core.ipynb #a82d16ca
+@patch
+def pyval(self:Apl, expr):
+    "Evaluate `expr` and return the result as a Python value"
+    return json.loads(self.run(f"1(⎕JSON⍠'HighRank' 'Split')({expr})"))
+
+# %% ../00_core.ipynb #4a0c3e58
+def _apljson(v):
+    "An APL expression that evaluates to the Python value `v`"
+    return "⎕JSON'" + json.dumps(v).replace("'", "''") + "'"
+
+@patch
+def __getitem__(self:Apl, expr): return self.pyval(expr)
+
+@patch
+def __setitem__(self:Apl, nm, v): self.run(f'{nm}←{_apljson(v)}')
+
+# %% ../00_core.ipynb #8a0bb0fe
+@patch
+def fn(self:Apl, code):
+    "A Python callable applying APL function `code` monadically or dyadically"
+    def f(*args):
+        if len(args)==1: return self.pyval(f'({code}){_apljson(args[0])}')
+        a,w = args
+        return self.pyval(f'({_apljson(a)})({code}){_apljson(w)}')
+    return f
+
+# %% ../00_core.ipynb #9bd19790
+@patch
+def __enter__(self:Apl): return self
+
+@patch
+def __exit__(self:Apl, *args): self.close()
+
+# %% ../00_core.ipynb #04f56c87
+_css = """<style>
+@font-face { font-family:'SAX2'; src: local('SAX2'), url('https://cdn.jsdelivr.net/gh/abrudz/SAX2@master/SAX2.ttf') format('truetype') }
+.sax2 { font-family:'SAX2',monospace !important; line-height:1.05 !important }
+</style>"""
+
+class APLMagic:
+    "IPython `%apl`/`%%apl` magics, driving a lazily-started `Apl` session"
+    def __init__(self, dyalog=None): self.dyalog,self.o,self._loaded = dyalog,None,False
+
+    def apl(self, line, cell=None):
+        "Run APL: a cell magic displays the session output; a line magic returns the expression's Python value"
+        if not self.o: self.o = Apl(self.dyalog)
+        if not self._loaded:
+            display(Javascript((files('iversonnb')/'lb.js').read_text()))
+            display(HTML(_css))
+            self._loaded = True
+        if cell is None: return self.o[line.split('⍝')[0].strip()]
+        disp,cell = True,cell.rstrip()
+        if cell.endswith(';'): disp,cell = False,cell[:-1]
+        out = self.o(cell)
+        if disp and out: display(out)
+
+
+# %% ../00_core.ipynb #953c6348
+def create_magic(shell=None):
+    "Create an `APLMagic` and register its `apl` line/cell magic with `shell`, returning it"
+    if not shell: shell = get_ipython()
+    apl_magic = APLMagic()
+    shell.register_magic_function(apl_magic.apl, 'line_cell', 'apl')
+    return apl_magic
+
+
+# %% ../00_core.ipynb #3e0cb6bc
+def load_ipython_extension(ipython):
+    "Required function for creating magic"
+    create_magic(shell=ipython)
+
+# %% ../00_core.ipynb #66869255
+def create_ipython_config():
+    "Called by `iversonnb_install` to install magic"
+    ipython_dir = Path(get_ipython_dir())
+    cf = ipython_dir/'profile_default'/'ipython_config.py'
+    cf.parent.mkdir(parents=True, exist_ok=True)
+    if cf.exists() and 'iversonnb' in cf.read_text(): return print('iversonnb already installed!')
+    with cf.open(mode='a') as f: f.write("\nc.InteractiveShellApp.extensions.append('iversonnb')\n\n")
+    print(f"Jupyter config updated at {cf}")

iversonnb/j.py

@@ -0,0 +1,204 @@
+"""Running J in-process through libj, and `j` magics for Jupyter and IPython
+
+Docs: https://answerdotai.github.io/iversonnb/j.html.md"""
+
+# AUTOGENERATED! DO NOT EDIT! File to edit: ../01_j.ipynb.
+
+# %% auto #0
+__all__ = ['find_j', 'load_j', 'JError', 'J', 'JOut', 'JMagic', 'create_j_magic', 'load_ipython_extension']
+
+# %% ../01_j.ipynb #7e555789
+import ctypes
+from ctypes import c_void_p,c_char_p,c_int,c_longlong,c_double,c_byte,POINTER,byref,cast,create_string_buffer
+from shutil import which
+from IPython.display import display
+from IPython.utils.capture import capture_output
+from fastcore.utils import *
+from fastcore.test import *
+
+# %% ../01_j.ipynb #4f9e0882
+_LIBJ = 'j.dll' if sys.platform=='win32' else 'libj.dylib' if sys.platform=='darwin' else 'libj.so'
+
+def find_j():
+    "Locate the J binary directory: the one containing libj and profile.ijs"
+    if (p:=which('jconsole')) and (d:=Path(p).resolve().parent/_LIBJ).exists(): return d.parent
+    try:
+        import jlang
+        return Path(jlang.path())/'bin'
+    except ImportError: pass
+    roots = [Path.home(), Path('/Applications'), Path('/opt'), Path('/usr/share')]
+    cands = sorted(c for r in roots if r.exists() for c in r.glob('j9*') if (c/'bin'/_LIBJ).exists())
+    if cands: return cands[-1]/'bin'
+    raise FileNotFoundError('J not found: pip install jlanguage, or install it from jsoftware.com')
+
+# %% ../01_j.ipynb #ee362390
+_OUTCB = ctypes.CFUNCTYPE(None, c_void_p, c_int, c_void_p)   # Joutput(jt, type, text)
+_INCB  = ctypes.CFUNCTYPE(c_void_p, c_void_p, c_char_p)      # Jinput(jt, prompt) -> line
+_SMCON = 3   # smoptions: identify as a console front end
+
+def load_j(jbin=None):
+    "Load libj from `jbin` (or `find_j()`), declare its C signatures, and return `(jbin,lib)`"
+    jbin = Path(jbin or find_j())
+    lib = ctypes.CDLL(str(jbin/_LIBJ))
+    lib.JInit2.restype = c_void_p
+    lib.JInit2.argtypes = [c_char_p]
+    lib.JDo.argtypes = [c_void_p,c_char_p]
+    lib.JSM.argtypes = [c_void_p,c_void_p]
+    lib.JInterrupt.argtypes = lib.JFree.argtypes = [c_void_p]
+    lib.JGetM.argtypes = lib.JSetM.argtypes = [c_void_p,c_char_p]+[POINTER(c_longlong)]*4
+    return jbin,lib
+
+# %% ../01_j.ipynb #e8a80100
+class JError(Exception):
+    "A J error, carrying the session's output (including the error display) as its message"
+
+# %% ../01_j.ipynb #30e60cf7
+class J:
+    "A J session: the libj engine loaded in-process, with the stdlib profile booted"
+    def __init__(self, jbin=None):
+        self.jbin,self._lib = load_j(jbin)
+        self.jt = self._lib.JInit2(str(self.jbin).encode())
+        self._out,self._inq,self.exited = [],[],None
+        @_OUTCB
+        def _o(j,typ,p):
+            if typ==5: self.exited = p or 0
+            else: self._out.append((typ, ctypes.string_at(p).decode('utf-8','replace') if p else ''))
+        @_INCB
+        def _i(j,prompt):
+            self._inbuf = create_string_buffer((self._inq.pop(0) if self._inq else ')').encode())
+            return ctypes.addressof(self._inbuf)
+        self._cbs = (c_void_p*5)(cast(_o,c_void_p), None, cast(_i,c_void_p), None, _SMCON)
+        self._lib.JSM(self.jt, self._cbs)
+        boot = f"(3 : '0!:0 y')<BINPATH,'/profile.ijs'[ARGV_z_=:<'jconsole'[BINPATH_z_=:'{self.jbin}'"
+        if self._lib.JDo(self.jt, boot.encode()): raise JError(''.join(t for _,t in self._out))
+
+# %% ../01_j.ipynb #db9dc5bf
+@patch
+def run(self:J, code):
+    "Run `code` (one or more lines of J) in the session, returning its output; raises `JError` on J errors"
+    self._out.clear()
+    self._inq[:] = code.strip().splitlines()
+    while self._inq and self.exited is None:
+        rc = self._lib.JDo(self.jt, self._inq.pop(0).encode())
+        if rc and self.exited is None: raise JError(''.join(t for _,t in self._out))
+    if self.exited is not None: return ''.join(t for ty,t in self._out if ty!=2)   # drop the exit unwind noise
+    return ''.join(t for _,t in self._out)
+
+# %% ../01_j.ipynb #8d7be472
+class JOut(str):
+    "Output text from a `J` call; displays verbatim"
+    def __repr__(self): return str(self)
+
+@patch
+def __call__(self:J, code):
+    "Run `code`, returning session output (or None if there is none)"
+    return JOut(self.run(code)) or None
+
+# %% ../01_j.ipynb #b4ba14ce
+def _nest(x, shape):
+    "Nest flat sequence `x` (row-major ravel) into `shape`"
+    if len(shape)<2: return x
+    n = len(x)//shape[0]
+    return [_nest(x[i*n:(i+1)*n], shape[1:]) for i in range(shape[0])]
+
+@patch
+def getm(self:J, name):
+    "Read noun `name` into Python: str for characters; int/float scalars and (nested) lists otherwise"
+    t,r,s,d = c_longlong(),c_longlong(),c_longlong(),c_longlong()
+    if self._lib.JGetM(self.jt, name.encode(), byref(t),byref(r),byref(s),byref(d)): raise JError(f'no noun: {name}')
+    shape = cast(s.value, POINTER(c_longlong))[:r.value]
+    n = math.prod(shape)
+    if t.value==2: return _nest(ctypes.string_at(d.value, n).decode('utf-8','replace'), shape)
+    if t.value not in (1,4,8): raise JError(f'unsupported J type {t.value} for: {name}')
+    x = cast(d.value, POINTER({1:c_byte,4:c_longlong,8:c_double}[t.value]))[:n]
+    return _nest(x, shape) if r.value else x[0]
+
+# %% ../01_j.ipynb #86f8fb28
+@patch
+def pyval(self:J, expr):
+    "Evaluate `expr` and return the result as a Python value"
+    self.run(f'jnbtmp =: {expr}')
+    try: return self.getm('jnbtmp')
+    finally: self.run("4!:55 <'jnbtmp'")
+
+@patch
+def __getitem__(self:J, expr): return self.pyval(expr)
+
+# %% ../01_j.ipynb #89f0e80f
+def _flat(o): return [a for x in o for a in _flat(x)] if isinstance(o,(list,tuple)) else [o]
+
+def _jdat(v):
+    "ctypes `(type,shape,buf)` for a Python scalar, string, or uniformly nested list"
+    if isinstance(v,str):
+        b = v.encode()
+        return 2, [len(b)], create_string_buffer(b, len(b))
+    shape,x = [],v
+    while isinstance(x,(list,tuple)): shape,x = shape+[len(x)],x[0]
+    flat = _flat(v)
+    if any(isinstance(a,float) for a in flat): return 8, shape, (c_double*len(flat))(*flat)
+    return 4, shape, (c_longlong*len(flat))(*flat)
+
+@patch
+def __setitem__(self:J, nm, v):
+    "Assign Python value `v` (scalar, string, or nested list) to noun `nm`"
+    t,shape,buf = _jdat(v)
+    sh = (c_longlong*len(shape))(*shape)
+    a = [c_longlong(t), c_longlong(len(shape)), c_longlong(ctypes.addressof(sh)), c_longlong(ctypes.addressof(buf))]
+    if self._lib.JSetM(self.jt, nm.encode(), *map(byref,a)): raise JError(f'JSetM failed: {nm}')
+
+# %% ../01_j.ipynb #b3270978
+@patch
+def fn(self:J, code):
+    "A Python callable applying J verb `code` monadically or dyadically (left argument first)"
+    def f(*args):
+        if len(args)==1:
+            self['jnby'] = args[0]
+            return self.pyval(f'({code}) jnby')
+        self['jnbx'],self['jnby'] = args
+        return self.pyval(f'jnbx ({code}) jnby')
+    return f
+
+# %% ../01_j.ipynb #79911134
+@patch
+def interrupt(self:J):
+    "Stop the currently running sentence with an attention interrupt; safe to call from another thread"
+    self._lib.JInterrupt(self.jt)
+
+# %% ../01_j.ipynb #af540693
+@patch
+def close(self:J):
+    "Free the engine instance; the session is unusable afterwards"
+    self._lib.JFree(self.jt)
+    self.jt = None
+
+@patch
+def __enter__(self:J): return self
+
+@patch
+def __exit__(self:J, *args): self.close()
+
+# %% ../01_j.ipynb #12c1ebee
+class JMagic:
+    "IPython `%j`/`%%j` magics, driving a lazily-started `J` session"
+    def __init__(self, jbin=None): self.jbin,self.o = jbin,None
+
+    def j(self, line, cell=None):
+        "Run J: a cell magic displays the session output; a line magic returns the expression's Python value"
+        if not self.o: self.o = J(self.jbin)
+        if cell is None: return self.o[line.strip()]
+        disp,cell = True,cell.rstrip()
+        if cell.endswith(';'): disp,cell = False,cell[:-1]
+        out = self.o(cell)
+        if disp and out: display(out)
+
+# %% ../01_j.ipynb #00b65478
+def create_j_magic(shell=None):
+    "Create a `JMagic` and register its `j` line/cell magic with `shell`, returning it"
+    if not shell: shell = get_ipython()
+    jm = JMagic()
+    shell.register_magic_function(jm.j, 'line_cell', 'j')
+    return jm
+
+def load_ipython_extension(ipython):
+    "Required function for creating magic"
+    create_j_magic(shell=ipython)

iversonnb/jkernel.py

@@ -0,0 +1,49 @@
+"J clikernel: a stream-protocol worker and MCP supervisor driving J in-process via `J` (libj). Hand-written (not nbdev-exported); see `clikernel.base` for the protocol."
+import signal,sys,threading,traceback
+from fastcore.xdg import xdg_config_home
+from clikernel.base import fmt_error,init_worker,run_mcp,run_startup,serve_stream
+from iversonnb.j import J,JError
+
+INSTRUCTIONS = "jkernel is a persistent J session: `execute` runs J code and keeps workspace state (nouns, verbs) across calls; `restart` gives a clear workspace. If a response starts with a NOTE saying the session was replaced, all workspace state is gone."
+
+_DOCS = dict(
+    execute="Run J `code` in the persistent J session, keeping workspace state (nouns, verbs) across calls.",
+    restart="Kill the worker and start a fresh J session with a clear workspace; all state is discarded. Also works when `execute` is stuck: the stuck call returns an error and the session comes back fresh.",
+    interrupt="Interrupt the J code the kernel is currently running (a J attention interrupt): the in-flight `execute` call returns with an attention interrupt error, and workspace state survives. Prefer this over `restart` when a call is merely taking too long. Only meaningful while an `execute` call is running.",
+    died="NOTE: the kernel process had died; a fresh one was started, and all previous workspace state (nouns, verbs) is gone.\n")
+
+
+def _execute(j, code):
+    try: return j.run(code)
+    except JError as e: return fmt_error("error", str(e))
+    except Exception: return fmt_error("error", traceback.format_exc())
+
+
+def main():
+    init_worker()
+    signal.signal(signal.SIGTERM, lambda s,f: sys.exit(0))
+    j = J()
+    state = dict(busy=False)
+    # JDo blocks its calling thread at the C level, so each request runs on a worker thread and the main
+    # thread joins in slices, staying free to run the SIGINT handler: JInterrupt is just a break-flag
+    # write (safe cross-thread), and the engine polls it between sentences, ending the in-flight JDo.
+    def _sigint(s,f):
+        if state['busy']: j.interrupt()
+    signal.signal(signal.SIGINT, _sigint)
+    def execute(code):
+        res = {}
+        th = threading.Thread(target=lambda: res.update(out=_execute(j, code)), daemon=True)
+        state['busy'] = True
+        try:
+            th.start()
+            while th.is_alive(): th.join(0.1)
+        finally: state['busy'] = False
+        return res['out']
+    block = run_startup(xdg_config_home()/"iversonnb"/"startup.ijs", lambda src: (j.run(src), None))
+    serve_stream(execute, INSTRUCTIONS + ("\n\n" + block if block else ""), should_exit=lambda: j.exited is not None)
+
+
+def main_mcp(): run_mcp([sys.executable, "-m", "iversonnb.jkernel"], name="jkernel", docs=_DOCS, instructions=INSTRUCTIONS)
+
+
+if __name__ == "__main__": main()

iversonnb/kernel.py

@@ -0,0 +1,56 @@
+"APL clikernel: a stream-protocol worker and MCP supervisor driving Dyalog over RIDE via `Apl`. Hand-written (not nbdev-exported); see `clikernel.base` for the protocol."
+import signal,sys,traceback
+from fastcore.xdg import xdg_config_home
+from clikernel.base import fmt_error,init_worker,run_mcp,run_startup,serve_stream
+from iversonnb.core import Apl,AplError,ride_send
+
+INSTRUCTIONS = "aplkernel is a persistent Dyalog APL session: `execute` runs APL code and keeps workspace state (variables, functions) across calls; `restart` gives a clear workspace. If a response starts with a NOTE saying the session was replaced, all workspace state is gone."
+
+_RESET = "NOTE: the Dyalog interpreter was replaced with a fresh session; all previous workspace state (variables, functions) is gone.\n"
+
+_DOCS = dict(
+    execute="Run APL `code` in the persistent Dyalog session, keeping workspace state (variables, functions) across calls. If the session had to be replaced (the interpreter died, or incomplete input hit Dyalog/ride#1401), the response starts with a NOTE saying workspace state was lost.",
+    restart="Kill the worker and start a fresh Dyalog session with a clear workspace; all state is discarded. Also works when `execute` is stuck: the stuck call returns an error and the session comes back fresh.",
+    interrupt="Interrupt the APL code the kernel is currently running (a RIDE StrongInterrupt): the in-flight `execute` call returns with an INTERRUPT error, and workspace state survives. Prefer this over `restart` when a call is merely taking too long. Only meaningful while an `execute` call is running.",
+    died="NOTE: the kernel process had died; a fresh one was started, and all previous workspace state (variables, functions) is gone.\n")
+
+
+def _execute(apl, code):
+    try: return apl.run(code)
+    except AplError as e:
+        body = fmt_error("error", str(e))
+        return _RESET + body if e.reset else body
+    except Exception:
+        apl.close()
+        apl._connect()
+        return _RESET + fmt_error("error",
+            f"the Dyalog session died while executing this request; a fresh session was started\n{traceback.format_exc()}")
+
+
+def main():
+    init_worker()
+    # SIGTERM (the supervisor's graceful kill) becomes SystemExit, so atexit shuts Dyalog down.
+    # SIGINT becomes a RIDE StrongInterrupt when a request is running (see the probe notes in tests):
+    # the interpreter answers with an INTERRUPT error and the session survives; when idle it's a no-op,
+    # since an idle StrongInterrupt is silent but a stray KeyboardInterrupt would desync the stream.
+    signal.signal(signal.SIGTERM, lambda s,f: sys.exit(0))
+    apl = Apl()
+    state = dict(exit=False, busy=False)
+    def _sigint(s,f):
+        if state['busy']: ride_send(apl.sock, ['StrongInterrupt',{}])
+    signal.signal(signal.SIGINT, _sigint)
+    def execute(code):
+        if code.strip().upper() == ')OFF':
+            state['exit'] = True
+            return ""
+        state['busy'] = True
+        try: return _execute(apl, code)
+        finally: state['busy'] = False
+    block = run_startup(xdg_config_home()/"iversonnb"/"startup.apl", lambda src: (apl.run(src), None))
+    serve_stream(execute, INSTRUCTIONS + ("\n\n" + block if block else ""), should_exit=lambda: state['exit'])
+
+
+def main_mcp(): run_mcp([sys.executable, "-m", "iversonnb.kernel"], name="aplkernel", docs=_DOCS, instructions=INSTRUCTIONS)
+
+
+if __name__ == "__main__": main()