joyfl 0.4__py3-none-any.whl

joyfl/__init__.py

@@ -0,0 +1,3 @@
+## Copyright © 2025, Alex J. Champandard.  Licensed under AGPLv3; see LICENSE! ⚘
+
+__version__ = "0.4"

joyfl/__main__.py

@@ -0,0 +1,124 @@
+## Copyright © 2025, Alex J. Champandard.  Licensed under AGPLv3; see LICENSE! ⚘
+#
+# joyfl — A minimal but elegant dialect of Joy, functional / concatenative stack language.
+#
+
+import sys
+import time
+import traceback
+from pathlib import Path
+
+import click
+
+from .types import nil
+from .errors import JoyError, JoyParseError, JoyNameError, JoyIncompleteParse, JoyAssertionError, JoyImportError
+from .parser import format_parse_error_context, print_source_lines, format_source_lines
+from .formatting import write_without_ansi, format_item, show_stack
+
+from . import api as J
+
+
+@click.command()
+@click.argument('files', nargs=-1, type=click.File('r'))
+@click.option('--command', '-c', 'commands', multiple=True, type=str, help='Execute Joy code from command line.')
+@click.option('--repl', is_flag=True, help='Start REPL after executing commands and files.')
+@click.option('--verbose', '-v', default=0, count=True, help='Enable verbose interpreter execution.')
+@click.option('--validate', is_flag=True, help='Enable type and stack validation before each operation.')
+@click.option('--ignore', '-i', is_flag=True, help='Ignore errors and continue executing.')
+@click.option('--stats', is_flag=True, help='Display execution statistics (e.g., number of steps).')
+@click.option('--plain', '-p', is_flag=True, help='Strip ANSI color codes and redirect stderr to stdout.')
+def main(files: tuple, commands: tuple, repl: bool, verbose: int, validate: bool, ignore: bool, stats: bool, plain: bool):
+
+    if plain is True:
+        writer = write_without_ansi(sys.stdout.write)
+        sys.stdout.write, sys.stderr.write = writer, writer
+    failure = False
+
+    def _maybe_fatal_error(message: str, detail: str, exc_type: str = None, context: str = '', is_repl=False):
+        header = detail if not exc_type else f"{detail} (Exception: \033[33m{exc_type}\033[0m)"
+        print(f'\033[30;43m {message} \033[0m {header}\n{context}', file=sys.stderr)
+        if not is_repl and not ignore: sys.exit(1)
+
+    def _handle_exception(exc, filename, source, is_repl=False):
+        if isinstance(exc, JoyParseError):
+            if is_repl and isinstance(exc, JoyIncompleteParse): return True
+            context = format_parse_error_context(filename, exc.line, exc.column, exc.token, source=source)
+            context += f"\n\033[90m{str(exc).replace(chr(10), ' ').replace(chr(9), ' ')}\033[0m\n"
+            _maybe_fatal_error("SYNTAX ERROR.", f"Parsing `\033[97m{filename}\033[0m` caused a problem!", type(exc).__name__, context, is_repl)
+        elif isinstance(exc, JoyNameError):
+            detail = f"Term `\033[1;97m{exc.joy_op}\033[0m` from `\033[97m{filename}\033[0m` was not found in library!"
+            context = '\n' + format_source_lines(exc.joy_meta, exc.joy_op)
+            _maybe_fatal_error("LINKER ERROR.", detail, type(exc).__name__, context, is_repl)
+        elif isinstance(exc, JoyAssertionError):
+            print(f'\033[30;43m ASSERTION FAILED. \033[0m Function \033[1;97m`{exc.joy_op}`\033[0m raised an error.\n', file=sys.stderr)
+            print_source_lines(exc.joy_op, J.library.quotations, file=sys.stderr)
+            print(f'\033[1;33m  Stack content is\033[0;33m\n    ', end='', file=sys.stderr)
+            show_stack(exc.joy_stack, width=None, file=sys.stderr); print('\033[0m', file=sys.stderr)
+            if not is_repl and not ignore: sys.exit(1)
+        elif isinstance(exc, JoyImportError):
+            detail = f"Importing library module failed while resolving `{exc.joy_op}`: \033[97m{exc.filename}\033[0m"
+            context = '\n' + format_source_lines(exc.joy_meta, exc.joy_op)
+            _maybe_fatal_error("IMPORT ERROR.", detail, type(exc).__name__, context, is_repl)
+        elif isinstance(exc, Exception):
+            print(f'\033[30;43m RUNTIME ERROR. \033[0m Function \033[1;97m`{exc.joy_op}`\033[0m caused an error in interpret! (Exception: \033[33m{type(exc).__name__}\033[0m)\n', file=sys.stderr)
+            tb_lines = traceback.format_exc().split('\n')
+            print(*[line for line in tb_lines if 'lambda' in line], sep='\n', end='\n', file=sys.stderr)
+            print_source_lines(exc.joy_op, J.library.quotations, file=sys.stderr)
+            traceback.print_exc()
+            if not is_repl and not ignore: sys.exit(1)
+        return False
+
+    base = Path(__file__).resolve().parent
+    candidates = (d / 'libs' / 'stdlib.joy' for d in (base, *base.parents[:2]))
+    stdlib_path = next((p for p in candidates if p.exists()), Path('libs/stdlib.joy'))
+    J.load(stdlib_path.read_text(encoding='utf-8'), filename='libs/stdlib.joy', validate=validate)
+
+    # Build execution list: files first, then commands.
+    items = [(f.read(), f.name) for f in files]
+    items += [(cmd, f'<INPUT_{i+1}>') for i, cmd in enumerate(commands)]
+
+    total_stats = {'steps': 0, 'start': time.time()} if stats else None
+    for source, filename in items:
+        try:
+            r = J.run(source, filename=filename, verbosity=verbose, validate=validate, stats=total_stats)
+            (r is None and ((failure := True) or (not ignore and sys.exit(1))))
+        except (JoyError, Exception) as exc:
+            _handle_exception(exc, filename, source, is_repl=False)
+
+    if total_stats and len(items) > 0:
+        elapsed_time = time.time() - total_stats['start']
+        print(f"\n\033[97m\033[48;5;30m STATISTICS. \033[0m")
+        print(f"step\t\033[97m{total_stats['steps']:,}\033[0m")
+        print(f"time\t\033[97m{elapsed_time:.3f}s\033[0m")
+
+    # Start REPL if no items were provided or --repl flag was set
+    if len(items) == 0 or repl:
+        if sys.platform != "win32": import readline
+
+        print('joyfl - Functional stack language REPL; type Ctrl+C to exit.')
+        source = ""
+
+        while True:
+            try:
+                prompt = "\033[36m<<< \033[0m" if not source.strip() else "\033[36m... \033[0m"
+                line = input(prompt)
+                if len(line.strip()) == 0: continue
+                if line.strip() in ('quit', 'exit'): break
+                source += line + " "
+
+                try:
+                    stack = J.run(source, filename='<REPL>', verbosity=verbose, validate=validate)
+                    if stack is not nil: print("\033[90m>>>\033[0m", format_item(stack[-1]))
+                    source = ""
+                except (JoyError, Exception) as exc:
+                    if not _handle_exception(exc, '<REPL>', source, is_repl=True):
+                        source = ""
+
+            except (KeyboardInterrupt, EOFError):
+                print(""); break
+
+    sys.exit(failure)
+
+
+if __name__ == "__main__":
+    main()

joyfl/api.py

@@ -0,0 +1,10 @@
+## joyfl — Copyright © 2025, Alex J. Champandard.  Licensed under AGPLv3; see LICENSE! ⚘
+
+from .types import Operation, Stack, nil
+from .errors import *
+from .runtime import Runtime
+
+_RUNTIME = Runtime()
+
+def __getattr__(name):
+    return getattr(_RUNTIME, name)

joyfl/builtins.py

@@ -0,0 +1,44 @@
+## Copyright © 2025, Alex J. Champandard.  Licensed under AGPLv3; see LICENSE! ⚘
+
+from .library import Library
+from . import operators
+from .combinators import comb_i, comb_dip, comb_step, comb_cont
+
+
+def _joy_name_from_python(py_name: str) -> str:
+    # py_name like 'op_equal_q' -> 'equal?'; 'op_put_b' -> 'put!'; underscores -> dashes
+    base = py_name[3:]
+    base = base.replace('_q', '?').replace('_b', '!')
+    return base.replace('_', '-')
+
+
+def load_builtins_library():
+    # Combinators
+    combinators = {
+        'i': comb_i,
+        'dip': comb_dip,
+        'step': comb_step,
+        ',,,': comb_cont,
+    }
+    quotations = {}
+    constants = {'true': True, 'false': False}
+    factories = {}
+    aliases = {
+        '+': 'add', '-': 'sub', '*': 'mul', '/': 'div', '%': 'rem',
+        '>': 'gt', '>=': 'gte', '<': 'lt', '<=': 'lte',
+        '=': 'equal?', '!=': 'differ?', 'size': 'length',
+    }
+
+    lib = Library(functions={}, combinators=combinators, quotations=quotations, constants=constants, factories=factories, aliases=aliases)
+
+    # Functions (wrapped via Library helper)
+    for k in dir(operators):
+        if not k.startswith('op_'):
+            continue
+        joy = _joy_name_from_python(k)
+        lib.add_function(joy, getattr(operators, k))
+
+    lib.ensure_consistent()
+    return lib
+
+

joyfl/combinators.py

@@ -0,0 +1,58 @@
+## Copyright © 2025, Alex J. Champandard.  Licensed under AGPLv3; see LICENSE! ⚘
+#
+# joyfl — A minimal but elegant dialect of Joy, functional / concatenative stack language.
+#
+
+from .types import Operation
+from .parser import parse
+from .formatting import show_stack
+
+
+def comb_i(_, queue, tail, head, lib):
+    """Takes a program as quotation on the top of the stack, and puts it into the queue for execution."""
+    assert isinstance(head, (list, tuple))
+    queue.extendleft(reversed(head))
+    return tail
+
+def comb_dip(_, queue, *stack, lib):
+    """Schedules a program for execution like `i`, but removes the second top-most item from the stack too
+    and then restores it after the program is done.  This is like running `i` one level lower in the stack.
+    """
+    ((tail, item), head) = stack
+    assert isinstance(head, list)
+    queue.appendleft(item)
+    queue.extendleft(reversed(head))
+
+    return tail
+
+def comb_step(this: Operation, queue, *stack, lib):
+    """Applies a program to every item in a list in a recursive fashion.  `step` expands into another
+    quotation that includes itself to run on the rest of the list, after the program was applied to the
+    head of the list.
+    """
+    (tail, values), program = stack
+    assert isinstance(program, list) and isinstance(values, list)
+    if len(values) == 0: return tail
+    queue.extendleft(reversed([values[0]] + program + [values[1:], program, this]))
+    return tail
+
+def comb_cont(this: Operation, queue, *stack, lib):
+    from .linker import link_body
+
+    print(f"\033[97m  ~ :\033[0m  ", end=''); show_stack(stack, width=72, end='')
+    try:
+        program = []
+        value = input("\033[4 q\033[36m  ...  \033[0m")
+        if value.strip():
+            for typ, data in parse(value, start='term'):
+                program, _ = link_body(data, meta={'filename': '<REPL>', 'lines': (1, 1)}, globals_=lib)
+    except Exception as e:
+        print('EXCEPTION: comb_cont could not parse or compile the text.', e)
+        import traceback; traceback.print_exc(limit=2)
+    finally:
+        print("\033[0 q", end='')
+
+    if program:
+        queue.extendleft(reversed(program + [this]))
+    return stack
+

joyfl/errors.py

@@ -0,0 +1,40 @@
+## Copyright © 2025, Alex J. Champandard.  Licensed under AGPLv3; see LICENSE! ⚘
+
+import lark
+
+
+class JoyError(Exception):
+    def __init__(self, message: str = "", *, joy_op=None, joy_meta=None):
+        super().__init__(message)
+        self.joy_op = joy_op
+        self.joy_meta = joy_meta
+
+class JoyParseError(JoyError):
+    def __init__(self, message, *, filename=None, line=None, column=None, token=None):
+        super().__init__(message)
+        self.filename = filename
+        self.line = line
+        self.column = column
+        self.token = token
+
+class JoyIncompleteParse(JoyParseError, lark.exceptions.ParseError):
+    def __init__(self, message, *, filename=None, line=None, column=None, token=None):
+        super().__init__(message, filename=filename, line=line, column=column, token=token)
+
+class JoyNameError(JoyError, NameError):
+    pass
+
+class JoyRuntimeError(JoyError, RuntimeError):
+    pass
+
+class JoyAssertionError(JoyError, AssertionError):
+    pass
+
+
+class JoyImportError(JoyError, ImportError):
+    def __init__(self, message, *, joy_op=None, filename=None, joy_meta=None):
+        super().__init__(message, joy_op=joy_op, joy_meta=joy_meta)
+        self.filename = filename
+
+class JoyModuleError(JoyImportError):
+    pass

joyfl/formatting.py

@@ -0,0 +1,62 @@
+## Copyright © 2025, Alex J. Champandard.  Licensed under AGPLv3; see LICENSE! ⚘
+#
+# joyfl — A minimal but elegant dialect of Joy, functional / concatenative stack language.
+#
+
+import re
+import sys
+
+from .types import stack_list, Stack, nil
+
+
+def stack_to_list(stk: Stack) -> stack_list:
+    result = []
+    while stk is not nil:
+        stk, head = stk
+        result.append(head)
+    return stack_list(result)
+
+def list_to_stack(values: list, base=None) -> Stack:
+    stack = nil if base is None else base
+    for value in reversed(values):
+        stack = Stack(stack, value)
+    return stack
+
+
+def write_without_ansi(write_fn):
+    """Wrapper function that strips ANSI codes before calling the original writer."""
+    ansi_re = re.compile(r'\033\[[0-9;]*m')
+    return lambda text: write_fn(ansi_re.sub('', text))
+
+def format_item(it, width=None, indent=0):
+    if (is_stack := isinstance(it, stack_list)) or isinstance(it, list):
+        items = reversed(it) if is_stack else it
+        lhs, rhs = ('<', '>') if is_stack else ('[', ']')
+        formatted_items = [format_item(i, width, indent + 4) for i in items]
+        single_line = lhs + ' '.join(formatted_items) + rhs
+        # If it fits on one line, use single line format.
+        if width is None or len(single_line) + indent <= width: return single_line
+        # Otherwise use multi-line format...
+        result = lhs + '   '
+        for i, item in enumerate(formatted_items):
+            if i > 0: result += '\n' + (' ' * (indent + 4))
+            result += item
+        result += '\n' + (' ' * indent) + rhs
+        return result
+    if isinstance(it, str) and indent > 0: return f'"{it.replace(chr(34), chr(92)+chr(34))}"'
+    if isinstance(it, bool): return str(it).lower()
+    if isinstance(it, bytes): return str(it)[1:-1]
+    return str(it)
+
+def show_stack(stack, width=72, end='\n', file=None):
+    stack_str = ' '.join(format_item(s) for s in reversed(stack_to_list(stack))) if stack is not nil else '∅'
+    if len(stack_str) > (width or sys.maxsize):
+        stack_str = '… ' + stack_str[-width+2:]
+    print(f"{stack_str:>{width}}" if width else stack_str, end=end, file=file)
+
+def show_program_and_stack(program, stack, width=72):
+    prog_str = ' '.join(format_item(p) for p in program) if program else '∅'
+    if len(prog_str) > width:
+        prog_str = prog_str[:+width-2] + ' …'
+    show_stack(stack, end='')
+    print(f" \033[36m <=> \033[0m {prog_str:<{width}}")

joyfl/interpreter.py

@@ -0,0 +1,123 @@
+## Copyright © 2025, Alex J. Champandard.  Licensed under AGPLv3; see LICENSE! ⚘
+#
+# joyfl — A minimal but elegant dialect of Joy, functional / concatenative stack language.
+#
+
+import sys
+import traceback
+import collections
+
+from typing import Any, TypeVar
+
+from .types import Operation, Stack, nil
+from .parser import print_source_lines
+from .library import Library
+from .formatting import show_stack, show_program_and_stack, stack_to_list
+
+
+def can_execute(op: Operation, stack: Stack) -> tuple[bool, str]:
+    """Check if operation can execute on stack using inferred stack effects."""
+    # Special cases for combinators and runtime hazards that don't come from signature
+    if op.type == Operation.COMBINATOR and op.name in ("i", "dip"):
+        if stack is nil:
+            return False, f"`{op.name}` needs at least 1 item on the stack, but stack is empty."
+        _, head = stack
+        if not isinstance(head, (list, tuple)):
+            return False, f"`{op.name}` requires a quotation as list as top item on the stack."
+        return True, ""
+
+    # Division by zero guard for division, as binary int/float op.
+    if op.name in ('div', '/') and stack is not nil:
+        _, head = stack
+        if head == 0:
+            return False, f"`{op.name}` would divide by zero and cause a runtime exception."
+
+    if op.type != Operation.FUNCTION: return True, ""
+
+    eff = getattr(op.ptr, '__joy_meta__')
+    inputs = eff['inputs']
+    items = stack_to_list(stack)
+    depth = len(items)
+    if depth < len(inputs):
+        need = len(inputs)
+        return False, f"`{op.name}` needs at least {need} item(s) on the stack, but {depth} available."
+
+    # Type checks from top downward
+    for i, expected_type in enumerate(inputs):
+        if isinstance(expected_type, TypeVar): expected_type = expected_type.__bound__
+        if expected_type in (Any, None): continue
+        actual = items[i]
+        if not isinstance(actual, expected_type):
+            type_name = expected_type.__name__ if hasattr(expected_type, '__name__') else str(expected_type)
+            return False, f"`{op.name}` expects {type_name} at position {i+1} from top, got {type(actual).__name__}."
+
+    # Extra semantic guard for 'index' bounds when types look correct
+    if op.name == 'index' and len(items) >= 2 and isinstance(items[0], (list, str)) and isinstance(items[1], int):
+        idx, seq = items[1], items[0]
+        if not (0 <= int(idx) < len(seq)):
+            return False, f"`{op.name}` would index a list out ouf bounds."
+
+    return True, ""
+
+
+def interpret_step(program, stack, lib: Library):
+    op = program.popleft()
+    if isinstance(op, bytes) and op in (b'ABORT', b'BREAK'):
+        print(f"\033[97m  ~ :\033[0m  ", end=''); show_program_and_stack(program, stack)
+        if op == b'ABORT': sys.exit(-1)
+        if op == b'BREAK': input()
+
+    if not isinstance(op, Operation):
+        stack = Stack(stack, op)
+        return stack, program
+
+    match op.type:
+        case Operation.FUNCTION:
+            stack = op.ptr(stack)
+        case Operation.COMBINATOR:
+            stack = op.ptr(op, program, *stack, lib=lib)
+        case Operation.EXECUTE:
+            program.extendleft(reversed(op.ptr))
+
+    return stack, program
+
+
+def interpret(program: list, stack=None, lib: Library = None, verbosity=0, validate=False, stats=None):
+    stack = nil if stack is None else stack
+    program = collections.deque(program)
+
+    def is_notable(op):
+        if not isinstance(op, Operation): return False
+        return isinstance(op.ptr, list) or op.type == Operation.COMBINATOR
+
+    step = 0
+    while program:
+        if validate and isinstance(program[0], Operation):
+            if (check := can_execute(program[0], stack)) and not check[0]:
+                print(f'\033[30;43m TYPE ERROR. \033[0m {check[1]}\n', file=sys.stderr)
+                print(f'\033[1;33m  Stack content is\033[0;33m\n    ', end='', file=sys.stderr)
+                show_stack(stack, width=None, file=sys.stderr)
+                print('\033[0m', file=sys.stderr)
+                print_source_lines(program[0], lib.quotations, file=sys.stderr)
+                break
+        
+        if verbosity == 2 or (verbosity == 1 and (is_notable(program[0]) or step == 0)):
+            print(f"\033[90m{step:>3} :\033[0m  ", end='')
+            show_program_and_stack(program, stack)
+
+        step += 1
+        try:
+            op = program[0]
+            stack, program = interpret_step(program, stack, lib)
+        except Exception as exc:
+            exc.joy_op = op
+            exc.joy_stack = stack
+            raise
+
+    if verbosity > 0:
+        print(f"\033[90m{step:>3} :\033[0m  ", end='')
+        show_program_and_stack(program, stack)
+    if stats is not None:
+        stats['steps'] = stats.get('steps', 0) + step
+
+    return stack

joyfl/library.py

@@ -0,0 +1,84 @@
+## Copyright © 2025, Alex J. Champandard.  Licensed under AGPLv3; see LICENSE! ⚘
+
+from dataclasses import dataclass, field
+from typing import Any, Callable
+
+from .types import Stack
+from .errors import JoyNameError
+from .loader import get_stack_effects, resolve_module_op
+
+
+@dataclass
+class Library:
+    functions: dict[str, Callable[..., Any]]
+    combinators: dict[str, Callable[..., Any]]
+    quotations: dict[str, tuple[list, dict]]  # name -> (program, meta)
+    constants: dict[str, Any]
+    factories: dict[str, Callable[[], Any]]
+    aliases: dict[str, str] = field(default_factory=dict)
+
+    # Registration helpers
+    def add_function(self, name: str, fn: Callable[..., Any]) -> None:
+        fn, meta = _make_wrapper(fn, name)
+        fn.__joy_meta__ = meta
+        self.functions[name] = fn
+
+    def add_quotation(self, name: str, program: list, meta: dict) -> None:
+        self.quotations[name] = (program, meta)
+
+    def ensure_consistent(self) -> None:
+        for _, fn in list(self.functions.items()):
+            assert hasattr(fn, '__joy_meta__')
+
+    def get_function(self, name: str, *, meta: dict | None = None) -> Callable[..., Any]:
+        resolved_name = self.aliases.get(name, name)
+        if (fn := self.functions.get(resolved_name)) is not None:
+            return fn
+        if '.' in resolved_name:
+            ns, op = resolved_name.split('.', 1)
+            py_fn = resolve_module_op(ns, op, meta=meta)
+            fn, meta = _make_wrapper(py_fn, resolved_name)
+            fn.__joy_meta__ = meta
+            self.functions[resolved_name] = fn
+            return fn
+        raise JoyNameError(f"Operation `{name}` not found in library.", joy_op=name, joy_meta=meta)
+
+
+def _make_wrapper(fn: Callable[..., Any], name: str) -> Callable[..., Any]:
+    meta = get_stack_effects(fn=fn, name=name)
+    
+    match meta['valency']:
+        case -1:
+            def push(_, res): return res
+        case 0:
+            def push(base, _): return base
+        case 1:
+            def push(base, res): return Stack(base, res)
+        case _:
+            def push(base, res):
+                for v in res: base = Stack(base, v)
+                return base
+
+    match meta['arity']:
+        case -1:
+            def w_n(stk: Stack):
+                return push(stk, fn(*stk))
+            return w_n, meta
+        case 1:
+            def w_1(stk: Stack):
+                base, a = stk
+                return push(base, fn(a))
+            return w_1, meta
+        case 2:
+            def w_2(stk: Stack):
+                (base, b), a = stk
+                return push(base, fn(b, a))
+            return w_2, meta
+        case _:
+            def w_x(stk: Stack):
+                args, base = (), stk
+                for _ in range(meta['arity']):
+                    base, h = base
+                    args = (h,) + args
+                return push(base, fn(*args))
+            return w_x, meta