koskript 1.2.0__py3-none-any.whl

koskript/lang/interpreter.py

@@ -0,0 +1,332 @@
+from .emtypes import *
+
+class KoskripInterpreter(object):
+    def __init__(self):
+        self.globals = {"_": {}}
+        self.scopes = []
+        self._scope_counter = 0
+        self._handlers = {
+            LocalDecl:   self._local_decl,
+            DeclStmt: self._decl,
+            FnDef:       self._fn_def,
+            FnCall:      self._fn_call,
+            ReturnStmt:  self._return_stmt,
+            WhileStmt:   self._while_stmt,
+            ForStmt:     self._for_stmt,
+            ForItemStmt: self._foritem_stmt,
+            BreakStmt:    self._break_stmt,
+            ContinueStmt: self._continue_stmt,
+            IfStmt: self._if_stmt,
+            ElseIfStmt: self._else_if_stmt,
+            ElseStmt: self._else_stmt
+        }
+    
+    def execute(self, ast: list):
+        result = None
+        for node in ast:
+            result = self.visit(node)
+        return result
+
+    def run(self, ast: list):
+        # Entry point: a top-level `return` stops execution and yields its value.
+        try:
+            return self.execute(ast)
+        except ReturnSignal as signal:
+            return signal.value
+        except (BreakSignal, ContinueSignal) as signal:
+            raise Errors.RuntimeError(f"'{signal}' outside of a loop")
+
+    def execute_block(self, body: list):
+        self._push_scope("block")
+        try:
+            self.execute(body)
+        finally:
+            self.scopes.pop()
+
+    def _push_scope(self, prefix: str) -> str:
+        self._scope_counter += 1
+        scope = f"{prefix}_{self._scope_counter}"
+        self.scopes.append(scope)
+        return scope
+
+    def get_global(self, name: str) -> KoskriptObject:
+        for scope in reversed(self.scopes):
+            if scope in self.globals and name in self.globals[scope]:
+                return self.globals[scope][name]
+        
+        if name in self.globals["_"]:
+            return self.globals["_"][name]
+        
+        raise NameError(f"'{name}' is not defined")
+
+    def set_global(self, name: str, value: KoskriptObject) -> None:
+        if self.scopes:
+            scope = self.scopes[-1]
+            if scope not in self.globals:
+                self.globals[scope] = {}
+            self.globals[scope][name] = value
+            return
+        
+        self.globals["_"][name] = value
+
+    def visit(self, node):
+        handler = self._handlers.get(type(node))
+        if handler is None:
+            # Statements can also be bare expressions (e.g. `f(x)`, `1 + 2`).
+            return self.expr_eval(node)
+        return handler(node)
+
+    # EVALUATORS ####################################################################
+
+    def expr_eval(self, expr):
+        match expr:
+            case IntLit(value):  return value
+            case FloatLit(value): return value
+            case StrLit(value):  return value
+            case BoolLit(value): return value
+            case NullLit(value): return value
+            case NameRef(name):  return self.get_global(name).value
+            case AddStmt(l, r):  return self.expr_eval(l) + self.expr_eval(r)
+            case SubStmt(l, r):  return self.expr_eval(l) - self.expr_eval(r)
+            case MulStmt(l, r):  return self.expr_eval(l) * self.expr_eval(r)
+            case DivStmt(l, r):  return self.expr_eval(l) / self.expr_eval(r)
+            case ModStmt(l, r):  return self.expr_eval(l) % self.expr_eval(r)
+            case NegStmt(v):     return -self.expr_eval(v)
+            case ArrayLit(array): return [self.expr_eval(i) for i in array]
+
+            case MapValue(key, value): return key, value
+            case MapLit(values):
+                res = {}
+                for val in values:
+                    res[self.expr_eval(val.key)] = self.expr_eval(val.value)
+                return res
+
+            case MemberAccess(name, attrs):
+                value = self.expr_eval(name)
+
+                if not isinstance(value, dict):
+                    raise Errors.MismatchType(f"member access only supported on map, got {value}")
+                
+                for attr in attrs:
+                    try:
+                        value = value[attr.name]
+                    except:
+                        raise Errors.RuntimeError(f"no member with the value {attr} is defined on {value}")
+
+                return value
+
+            case IndexAccess(value, index):
+                container = self.expr_eval(value)
+                key = self.expr_eval(index)
+
+                try:
+                    return container[key]
+                except (KeyError, IndexError, TypeError):
+                    raise Errors.RuntimeError(
+                        f"cannot index {type(container).__name__} with {key!r}")
+
+            case FnCall(n, arg): return self.fn_eval(n, arg)
+            case LambdaFnDef(p, body): return Function(params=p, body=body)
+            case EquComp() | NequComp() | LteComp() | GteComp() | GtComp() | LtComp() \
+               | AndCond() | OrCond() | NotCond():
+                return self.cond_eval(expr)
+            case _: raise RuntimeError(f"Unknown expr: {type(expr).__name__}")
+
+    def fn_eval(self, callee, args):
+        if isinstance(callee, NameRef):
+            func: KoskriptObject = self.get_global(callee.name)
+        else:
+            func = self.expr_eval(callee)
+            if not isinstance(func, KoskriptObject):
+                func = KoskriptObject(value=func)
+
+        if not func:
+            raise NameError(f"no define with the name {callee} exists.")
+        
+        if callable(func.value):
+            return func.value(*[self.expr_eval(arg) for arg in args])
+
+        if type(func.value) != Function:
+            raise ValueError(f"{callee} is not callable.")
+        
+        func_params = func.value.params
+        func_body = func.value.body
+        if type(func_body) != list: func_body = [func_body]
+
+        self._push_scope(f"func_{callee}")
+        try:
+            for index_param, param in enumerate(func_params):
+                try:
+                    self.set_global(
+                        name=param, 
+                        value=KoskriptObject(
+                            self.expr_eval(args[index_param]), 
+                            read_only=True)
+                    )
+                except IndexError:
+                    break
+            
+            self.execute(func_body)
+        except (BreakSignal, ContinueSignal) as signal:
+            raise Errors.RuntimeError(f"'{signal}' outside of a loop")
+        except ReturnSignal as signal:
+            return signal.value
+        finally:
+            self.scopes.pop()
+        return None
+
+
+    def cond_eval(self, condition):
+        match condition:
+            case EquComp(l, r): return self.expr_eval(l) == self.expr_eval(r)
+            case NequComp(l, r): return self.expr_eval(l) != self.expr_eval(r)
+            case LteComp(l, r): return self.expr_eval(l) <= self.expr_eval(r)
+            case GteComp(l, r): return self.expr_eval(l) >= self.expr_eval(r)
+            case GtComp(l, r): return self.expr_eval(l) > self.expr_eval(r)
+            case LtComp(l, r): return self.expr_eval(l) < self.expr_eval(r)
+
+            case AndCond(l, r): return self.cond_eval(l) and self.cond_eval(r)
+            case OrCond(l, r): return self.cond_eval(l) or self.cond_eval(r)
+
+            case NotCond(com): return not self.cond_eval(com[0])
+
+            case _: return bool(self.expr_eval(condition))
+    
+
+    # HANDLERS ######################################################################
+    
+    def _local_decl(self, node: LocalDecl):
+        value = self.expr_eval(node.value)
+        name = node.name
+
+        self.set_global(
+            name,
+            KoskriptObject(
+                value=value
+            )
+        )
+
+
+    def _decl(self, node: DeclStmt):
+        variable = self.get_global(node.name)
+
+        if not variable:
+            raise NameError(f"{node.name} is not declared.")
+
+        variable.set_value(self.expr_eval(node.value))
+
+    def _fn_def(self, node: FnDef):
+        self.set_global(
+            name=node.name,
+            value=KoskriptObject(
+                value=Function(
+                params=node.params,
+                body=node.body
+            ))
+        )
+
+    def _fn_call(self, node: FnCall):
+        #print(node)
+        return self.fn_eval(node.name, args=node.args)
+
+    def _return_stmt(self, node: ReturnStmt):
+        value = self.expr_eval(node.value) if node.value is not None else None
+        raise ReturnSignal(value)
+
+    def _while_stmt(self, node: WhileStmt):
+        while self.cond_eval(node.condition):
+            try:
+                self.execute_block(node.body)
+            except ContinueSignal:
+                continue
+            except BreakSignal:
+                break
+
+    def _for_stmt(self, node: ForStmt):
+        array_value = self.expr_eval(node.iterable)
+
+        if type(array_value) != list and type(array_value) != dict:
+            raise NameError(f"for statement only supports maps or arrays.")
+
+        self._push_scope(f"for")
+        try:
+            var = KoskriptObject(None)
+            var.read_only = True
+            self.set_global(node.var, var)
+
+            variable = self.get_global(node.var)
+            for value in array_value:
+                variable.value = value
+                try:
+                    self.execute_block(node.body)
+                except ContinueSignal:
+                    continue
+                except BreakSignal:
+                    break
+        finally:
+            self.scopes.pop()
+        
+    def _foritem_stmt(self, node: ForItemStmt):
+        map_value = self.expr_eval(node.iterable)
+
+        if type(map_value) != dict:
+            raise ValueError(f"foreach statement only supports maps.")
+
+        self._push_scope(f"foreach")
+        try:
+            keyvalue = KoskriptObject(None)
+            varvalue = KoskriptObject(None)
+
+            keyvalue.read_only = True
+            varvalue.read_only = True
+
+            self.set_global(node.key, keyvalue)
+            self.set_global(node.var, varvalue)
+
+            kval = self.get_global(node.key)
+            vval = self.get_global(node.var)
+            for key, value in map_value.items():
+                kval.value = key
+                vval.value = value
+                try:
+                    self.execute_block(node.body)
+                except ContinueSignal:
+                    continue
+                except BreakSignal:
+                    break
+        finally:
+            self.scopes.pop()
+
+    def _break_stmt(self, node: BreakStmt):
+        raise BreakSignal()
+
+    def _continue_stmt(self, node: ContinueStmt):
+        raise ContinueSignal()
+    
+    def _if_stmt(self, node: IfStmt):
+        condition = self.cond_eval(node.condition)
+
+        if condition:
+            self.execute_block(node.body)
+            return   
+
+        for obj in node.if_tree:
+            if type(obj) == ElseIfStmt:
+                res = self._else_if_stmt(obj)
+                if res:
+                    break
+            else:
+                self._else_stmt(obj)
+                break
+
+    def _else_if_stmt(self, node: ElseIfStmt):
+        condition = self.cond_eval(node.condition)
+        
+        if not condition:
+            return False
+    
+        self.execute_block(node.body)
+        return True
+    
+    def _else_stmt(self, node: ElseStmt):
+        self.execute_block(node.body)

koskript-1.2.0.dist-info/METADATA

@@ -0,0 +1,352 @@
+Metadata-Version: 2.4
+Name: koskript
+Version: 1.2.0
+Summary: A simple embedded scripting language written in Python
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: lark>=1.3.1
+Dynamic: license-file
+
+![Koskript](https://raw.githubusercontent.com/alesisce/koskript/refs/heads/main/banner.png)
+
+# Koskript
+
+Koskript is a simple, embeddable, and lightweight scripting language designed to be used as a DSL inside Python applications. It features dynamic typing, lexical scoping, and native Python interop — letting you expose any Python function or object directly to your scripts.
+
+> **NOTE:** Koskript is currently in early development. Features like module imports, more types, and performance improvements are on the way.
+
+---
+
+## Features
+
+- Dynamic typing.
+- Block-level lexical scoping with `local` declarations
+- Native Python interop via `KoskriptObject`
+- `if`, `elseif`, `else`
+- `while`, `for`, `foreach` loops with `break` / `continue`
+- Member access — `map.key.subkey`
+- Index access — `array[0]`, `map["key"]`
+- First-class functions and lambda expressions
+- Arithmetic (`+`, `-`, `*`, `/`, `%`), comparison and logical operators
+- Embeddable in any Python application
+
+---
+
+## Installation
+
+Clone the repository and import it directly into your project:
+
+```bash
+git clone https://github.com/alesisce/koskript.git
+```
+
+> PyPI package coming soon.
+
+---
+
+## Quick Start
+
+```python
+from koskript import KoskriptRuntime
+
+runtime = KoskriptRuntime({
+    "print": print
+})
+runtime.execute("""
+local x = 10
+local y = 26
+
+print(x+y)
+""")
+```
+
+Any Python value or callable you pass in is wrapped automatically — no need to build `KoskriptObject` yourself.
+
+---
+
+## Example
+
+```koskript
+// Student grade checker
+local students = {
+    "Aleix": {
+        "age": 17,
+        "grade": 95
+    },
+    "Maria": {
+        "age": 15,
+        "grade": 72
+    },
+    "Juan": {
+        "age": 18,
+        "grade": 88
+    }
+}
+
+local passing_grade = 75
+                   
+foreach (name, data in students) {
+    local grade = data.grade
+
+    if (grade >= passing_grade) {
+        print("PASS:", name, "->", grade) // Depends on how you implement it.
+    } elseif (grade >= 60) {
+        print("NEAR PASS:", name, "->", grade)
+    } else {
+        print("FAIL:", name, "->", grade)
+    }
+}
+```
+
+Output:
+```
+PASS: Aleix -> 95
+NEAR PASS: Maria -> 72
+PASS: Juan -> 88
+```
+
+---
+
+## Language Reference
+
+### Types
+
+| Type | Description |
+|------|-------------|
+| `int` | Integer number |
+| `float` | Floating-point number |
+| `string` | Text string |
+| `bool` | `true` or `false` |
+| `null` | The absence of a value |
+| `array` | Ordered list |
+| `map` | Key-value store |
+
+### Variables
+
+```koskript
+local x = 10
+local pi = 3.14
+local name = "Koskript"
+local active = true
+local missing = null
+local items = [1, 2, 3]
+local empty = []
+local config = { "debug": true, "version": 1 }
+```
+
+Variables declared with `local` are scoped to the block they are declared in — including `if`, `while`, `for` and `foreach` bodies.
+
+### Functions
+
+```koskript
+fn add(a, b) {
+    return a + b
+}
+
+local result = add(10, 20)
+```
+
+### Operators
+
+```koskript
+local a = 2 + 3 * 4      // 14  (precedence: * / % before + -)
+local b = 10 % 3         // 1
+local c = -a             // unary minus
+local d = (a + b) * 2    // grouping with parentheses
+
+if (x >= 10 and not done or retry) {
+    // ...
+}
+```
+
+| Operators | Description |
+|-----------|-------------|
+| `+` `-` `*` `/` `%` | Arithmetic |
+| `-x` | Unary minus |
+| `==` `!=` `>` `<` `>=` `<=` | Comparison |
+| `and` `or` `not` | Logical (short-circuiting) |
+| `( )` | Grouping |
+
+### Control Flow
+
+```koskript
+if (x > 10) {
+    print("big")
+} elseif (x == 10) {
+    print("exact")
+} else {
+    print("small")
+}
+```
+
+### Lambda Functions
+
+```koskript
+local greet = () {
+    print("Hello world")
+}
+
+greet()
+
+// lambdas can take parameters and return values
+local add = (a, b) {
+    return a + b
+}
+
+print(add(1, 2))
+
+// invoke a lambda literal directly
+print((() { return 42 })())
+```
+
+### Loops
+
+```koskript
+// while
+while (x > 0) {
+    x = x - 1
+}
+
+// for — iterate array
+for (item in items) {
+    print(item)
+}
+
+// foreach — iterate map
+foreach (key, value in config) {
+    print(key, value)
+}
+```
+
+`break` exits the nearest loop and `continue` skips to the next iteration:
+
+```koskript
+for (item in items) {
+    if (item == 2) {
+        continue   // skip this item
+    }
+    if (item == 5) {
+        break      // stop looping
+    }
+    print(item)
+}
+```
+
+### Member Access
+
+```koskript
+local user = { "name": "Aleix", "age": 17 }
+print(user.name)
+print(user.age)
+```
+
+### Index Access
+
+```koskript
+local items = [10, 20, 30]
+print(items[0])        // 10
+print(items[-1])       // 30
+
+local config = { "debug": true }
+print(config["debug"]) // true
+
+// member access and indexing can be chained
+local data = { "nums": [1, 2, 3] }
+print(data.nums[1])    // 2
+```
+
+### Strings
+
+Strings support single or double quotes and the escapes `\n`, `\t`, `\r`, `\0`, `\\`, `\"` and `\'`:
+
+```koskript
+print("line one\nline two")
+```
+
+### Comments
+
+```koskript
+// line comments start with two slashes
+```
+
+### Reserved Keywords
+
+The following words cannot be used as identifiers:
+
+`if` `elseif` `else` `while` `for` `foreach` `fn` `return` `local` `true` `false` `null` `and` `or` `not` `in` `break` `continue`
+
+### Python Interop
+
+Any Python value or callable can be exposed to Koskript. They are wrapped in a `KoskriptObject` automatically:
+
+```python
+from koskript import KoskriptRuntime
+
+runtime = KoskriptRuntime({
+    "print": print,
+    "len": len,
+})
+
+# add more later — register() is chainable
+runtime.register("sqrt", math.sqrt)
+runtime["now"] = time.time
+```
+
+### Embedding API
+
+`execute()` returns the value of the last evaluated expression, or the value of a top-level `return`:
+
+```python
+runtime = KoskriptRuntime({"print": print})
+result = runtime.execute("local x = 10\nx * 2")   # 20
+result = runtime.execute("return 1 + 2")           # 3
+```
+
+For a quick one-off script, use the `run()` helper:
+
+```python
+from koskript import run
+
+run("print(1 + 2)", print=print)   # 3
+```
+
+Errors raised by scripts are available under `koskript.Errors`:
+
+```python
+from koskript import Errors
+
+try:
+    runtime.execute("local a = [1]\nprint(a[5])")
+except Errors.RuntimeError as e:
+    print(e)
+```
+
+---
+
+## Roadmap
+
+- [x] Index access (`array[0]`, `map["key"]`)
+- [x] `float` type
+- [x] `null` type
+- [x] `break` / `continue` statements
+- [ ] Module imports (`import "mymodule"`)
+- [ ] Performance improvements
+- [ ] Standard library
+- [ ] PyPI package
+- [ ] Custom parser (remove Lark dependency)
+- [ ] VM-based execution
+
+---
+
+## License
+
+Koskript is licensed under the Mozilla Public License 2.0 (MPL-2.0).
+
+You are free to use, modify, and redistribute Koskript. However, you may not redistribute this project under a different name or claim authorship of the Koskript language.
+
+**Koskript is a trademark of Alesis.**
+
+---
+
+*Built with ❤️ by Alesis*

koskript-1.2.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+koskript/__init__.py,sha256=15DmS6nvri29BNpXwZRnsTWcE0A0xE6tJJz2TnynoYI,2622
+koskript/lang/astgen.py,sha256=_GCX8gnX0vMFYg_vH5G-7T-qVB8FAcYndjZSeZPli3I,5709
+koskript/lang/emtypes.py,sha256=bfc9-k9zjv_haA4a_EzFWoqRj2GUDbI_JT9ltrEINpo,3296
+koskript/lang/errors.py,sha256=LtCDLXFsV-ZYqAJTbmQvzgXgl-xO7BcHbZTQ0JerUBw,351
+koskript/lang/interpreter.py,sha256=TDYojeSTMSryBit32sjd0zwRd2xuhBvNbm_761bMsPY,11752
+koskript-1.2.0.dist-info/licenses/LICENSE,sha256=kiHC-TYVm4RG0ykkn7TA8lvlEPRHODoPEzNqx5hWaKM,17099
+koskript-1.2.0.dist-info/METADATA,sha256=kr1_9khWeCheCQTxf626pUuCX6-6ZujX3CwqPfu_XIs,7397
+koskript-1.2.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+koskript-1.2.0.dist-info/top_level.txt,sha256=cls7RsuQwlrfwJUYwcSkzqQcdE-KfdLlFu-6vuae6gQ,9
+koskript-1.2.0.dist-info/RECORD,,

koskript-1.2.0.dist-info/WHEEL

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