Merge branch 'cli-docs' of https://github.com/JeffersGlass/spy into cli-docs

Author: JeffersGlass

.github/workflows/docs-preview-build.yml

@@ -16,6 +16,7 @@ on:
   pull_request:
     paths:
       - 'docs/**'
+      - 'spy/cli/**' # Rebuild cli docs when cli changes
       - '.github/workflows/docs**'
     types:
       - opened

.github/workflows/docs.yml

@@ -9,6 +9,7 @@ on:
       - 'docs/**'
     paths:
       - 'docs/**'
+      - 'spy/cli/**' # Rebuild cli docs when cli changes
   workflow_dispatch:  # Allows manual triggering
 
 # Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages

docs/mkdocs.yml

@@ -44,19 +44,23 @@ markdown_extensions:
       alternate_style: true
   - toc:
       permalink: true
+      toc_depth: 3
   - def_list
-  - mkdocs-typer
+
+plugins:
+  - mkdocs-typer2
 
 nav:
   - Home: index.md
   - contributing.md
   - Language features:
     - howto/main_function.md
-    - howto/cli.md
-  - API Reference:
+    - howto/generics.md
+  - Reference:
     - api_reference/python_builtins.md
     - api_reference/spy_builtins.md
     - api_reference/spy_module.md
+    - api_reference/cli.md
   - Unsorted notes:
       - Low-level memory model: llmem.md
 

docs/src/api_reference/cli.md

@@ -0,0 +1,8 @@
+title: SPy CLI
+____
+
+::: mkdocs-typer2
+    :module: spy.cli.cli
+    :name: spy
+    :engine: legacy
+    :pretty: false

docs/src/howto/cli.md

@@ -0,0 +1,118 @@
+title: Generic Functions and Types
+---
+<!-- See https://github.com/spylang/spy/pull/519 and https://github.com/spylang/spy/pull/448-->
+
+### Generic Functions
+
+Functions decorated with [@blue.generic](../api_reference/spy_builtins.md#bluegeneric) are called with `[]` brackets instead of parentheses. These *may* be used anywhere, but they are intended to help create functions that look like [PEP 695](https://peps.python.org/pep-0695/) functions with type parameters:
+
+```python
+@blue.generic
+def add(T):
+    def impl(x:T, y: T) -> T:
+        return x + y
+    return impl
+
+def main() -> None:
+    print(add[i32](1, 2))
+    print(add[str]('hello ', 'world'))
+```
+
+Like all functions marked `@blue`, the generic function is guaranteed to be executed at compile-time. We can see in the redshifted version of the above code that `add()` no longer appears, but the two specialized versions of it remain:
+
+<!-- Colorful code formatted by ansi2html -->
+<style type="text/css">
+.ansi2html-content { display: block; white-space: pre-wrap; word-wrap: break-word; font-size: .85em; padding:1.1em; corner-radius: 0.1em}
+.ansi32 { color: #00aa00; }
+.ansi33 { color: #aa5500; }
+.ansi34 { color: #0000aa; }
+.ansi35 { color: #E850A8; }
+</style>
+<div class="body_background" style="background-color:rgb(245, 245, 245);">
+<pre class="ansi2html-content">
+<span class="ansi34">def</span> main() -&gt; <span class="ansi34">None</span>:
+    <span class="ansi35">`_print::println[i32]::p`</span>(<span class="ansi35">`t::add[i32]::impl`</span>(<span class="ansi33">1</span>, <span class="ansi33">2</span>))
+    <span class="ansi35">`_print::println[str]::p`</span>(<span class="ansi35">`t::add[str]::impl`</span>(<span class="ansi32">'hello '</span>, <span class="ansi32">'world'</span>))
+
+<span class="ansi34">def</span> <span class="ansi35">`t::add[i32]::impl`</span>(x: <span class="ansi35">i32</span>, y: <span class="ansi35">i32</span>) -&gt; <span class="ansi35">i32</span>:
+    <span class="ansi34">return</span> x + y
+
+<span class="ansi34">def</span> <span class="ansi35">`t::add[str]::impl`</span>(x: <span class="ansi35">str</span>, y: <span class="ansi35">str</span>) -&gt; <span class="ansi35">str</span>:
+    <span class="ansi34">return</span> <span class="ansi35">`operator::str_add`</span>(x, y)
+</pre>
+</div>
+
+### Generic Class Syntax
+
+`@struct` classes may also be created with one or more parameters in `[]` brackets. This is different from passing superclasses inside of `()` parentheses; rather, this is syntactic sugar for a generic function with an inner `@struct` class than can make use of those parameters:
+
+```py
+@struct
+class MyList[T]:
+    inner: list[T]
+    other_param_1: ...
+    other_param_2: ...
+
+# ↑ is syntactic sugar for ↓
+
+@blue.generic
+def MyList(T):
+    @struct
+    class Self:
+        inner: list[T]
+        other_param_1: ...
+        other_param_2: ...
+
+    return Self
+```
+
+In use, this looks like:
+
+```py
+@struct
+class MyNamedList[T]:
+    name: str
+    data: list[T]
+
+def main() -> None:
+    my_int_list = MyNamedList[i32]("profits", [])
+    my_int_list.data.append(1_000_000)
+
+    my_str_list = MyNamedList[str]("words", ["hello", "world"])
+    my_str_list.data.extend(["and", "goodbye"])
+```
+
+For a larger example, see the `myarray` example [on GitHub](https://github.com/spylang/spy/blob/main/examples/myarray.spy) or [run it in the SPy Playground](https://spylang.github.io/spy/#code=eJydVcFO40AMvecrrHBpdiGiwHKoFsRKcOCCkOCyQlVkEqed3XQmmplQytevJ5OmkzZIK6oeEnv8bL9nT-I4jp6XwgD_lSRQJdglwUoZC1i8ocypAHrHVV2Rcd6nxw0YBSXqNIruLQjnWZG0pg18RSPy9iDCgiRpkQNqjRuwm5qi6EFZ4oNowVjd5JxEE9RoDKd53cAbVg3nmYiUUshVLahI0ijmIqNSqxU00mBJLqnSFhZ5hlWl8mP3VFsdRdGNh43yijHhl8t8ixZfbp9_P97NZxHwryK5sMsZiPOz9j3HGnNhNzuLsLQysw61i2XweEvWtjOfhQ1_GubLbKTF3LLdNAvUUCqu6OaVO0q7gKigclfUpAVOfFHbwtuCWtgnqkrvGyt6vPDPi3ceTbbRsgUOlXC6SVz14udK5nyUWslcd1itcWMgdoFxJ8cY09NiwPMRo3F0J7TDcQYJH6TVSe4mbK2xrknzEKhGFm3yOMuqKstiqJWQlnQKz2xlWhusoGDWHNCSsD5ppUdLRdpm83F93_vSdxQcgeS-Z4yg6bhlgtvVmkytZMEjrEYYGPaWeiCnZJZJWmfZJNAmgZPrPeWOuO-uGcZfoy78qvi1cC3tRK7gqp_qwxYm0yQ4mvq0HOEfQtd2Mkad7YCEiTx818YuheAzp_3beikqngb4uR3F3hPCvoj5IGqLI-A7THtrMIhplq3wLzkWq2RHrZsLWUwMnzj2t8IM_Lo4gh_4qpoNWTMey83AroEyoOn6KiRmWP0RV2TEB68BUcE30QkUqnmtyA9DFzKIcMKHJAeUf4OzYfvl3mnmZ5h-BHB6kO0z1cLAZK8rvkE3fHsLY4Vc-IvhQJmhVoHKW-bGaw3UDrQ_OHqovVesH8Iea_9AQEbYYnQwyS99pa6YdlbGt6R_duUES7wg64B4BP24id0mtxz_36SJbsLGSNMoDMG9LOj9Tmv-LPQOvwghg0FhZrQw3oev7cKXKhwu9htf_K62FQo52UuPWVkptE7U7Y1ZXl7wpXWadH4hB17uZT65CJ0vp_N-9jvL1FnOQsuZs5yHlnNnuQgsaXd9_EhGjJfeyF9nZoQ_Rxrlgti6I6TWfH7SgYt5Ev0DKx6k_A==)
+
+### `__origin__`
+
+The `__origin__` attribute of SPy objects carries information about the generic function which created them, if any. When `blue.generic` defines a `type` or `function` and returns it, the returned object has it's `__origin__` is set to the generic function:
+
+```py
+@blue.generic
+def adder(T):
+    @struct
+    class impl:
+         ...
+
+    return impl
+
+
+def main() -> None:
+    assert adder[T].__origin__ is adder
+```
+
+This is a straightforward way to identify that, for example, `MyList[T]` is a 'specialised' version of `MyList` on the type `T`.
+
+(The default value for `__origin__` is `None`. If the object returned by a generic function already has a non-`None` origin, that origin will *not* be overwritten.)
+
+The `__origin__` functions identically with the Generic Class syntax described above:
+
+```py
+@struct
+class MyList[T]:
+    inner: list[T]
+
+def main() -> None:
+    assert MyList[i32].__origin__ is MyList
+```

docs/src/howto/generics.md

@@ -17,6 +17,7 @@ dependencies = [
     "wasmtime==8.0.1; sys_platform != 'emscripten'",
     "ziglang==0.13.0; sys_platform != 'emscripten'",
     "mkdocs-typer>=0.0.3",
+    "mkdocs-typer2[mkdocs]>=0.3.0",
 ]
 
 [project.optional-dependencies]

pyproject.toml

@@ -172,8 +172,8 @@ def init_c(self) -> None:
                         spy_list_str lst = spy_list_str_new();
                         for (int i = 0; i < argc; i++) {
                             size_t length = strlen(argv[i]);
-                            spy_Str *s = spy_str_alloc(length);
-                            char *buf = (char *)s->utf8;
+                            spy_StrObject *s = spy_str_alloc(length);
+                            char *buf = (char *)spy_StrObject_UTF8(s);
                             memcpy(buf, argv[i], length);
                             lst = spy_list_str_push(lst, s);
                         }

spy/backend/c/cmodwriter.py

@@ -136,7 +136,7 @@ def __init__(self, vm: SPyVM) -> None:
         self._d[B.w_f32] = C_Type("float")
         self._d[B.w_complex128] = C_Type("spy_Complex128")
         self._d[B.w_bool] = C_Type("bool")
-        self._d[B.w_str] = C_Type("spy_Str *")
+        self._d[B.w_str] = C_Type("spy_StrObject *")
         self._d[RB.w_RawBuffer] = C_Type("spy_RawBuffer *")
         self._d[JSFFI.w_JsRef] = C_Type("JsRef")
         self._d[POSIX.w__FILE] = C_Type("FILE *")

spy/backend/c/context.py

@@ -124,6 +124,14 @@ def emit_StructType(self, fqn: FQN, w_st: W_StructType) -> None:
             )
             return
 
+        # _str::StrObject is already declared in str.h as spy_StrObject. Just emit a
+        # typedef.
+        if str(w_st.fqn) == "_str::StrObject":
+            self.tbh_fwdecl.wl(
+                f"typedef spy_StrObject {c_st}; /* alias of spy_StrObject */"
+            )
+            return
+
         human_fqn = w_st.fqn.human_name(self.ctx.vm)
         self.tbh_fwdecl.wl(f"typedef struct {c_st} {c_st}; /* {human_fqn} */")
 
@@ -144,6 +152,18 @@ def emit_PtrType(self, fqn: FQN, w_ptrtype: W_PtrType) -> None:
         c_ptrtype = C_Type(w_ptrtype.fqn.c_name)
         w_itemT = w_ptrtype.w_itemT
         c_itemT = self.ctx.w2c(w_itemT)
+
+        # some ptr types are predeclared manually in libspy. Make sure to keep the code
+        # generated here and the code manually written there always in sync.
+        if str(w_ptrtype.fqn) in (
+            "unsafe::gc_ptr[u8]",
+            "unsafe::gc_ptr[_str::StrObject]",
+        ):
+            self.tbh_fwdecl.wl(
+                f"// {c_ptrtype}: skip as it's already pre-declared by libspy"
+            )
+            return
+
         self.tbh_fwdecl.wb(f"""
         typedef struct {c_ptrtype} {{
             {c_itemT} *p;