diff --git a/README.md b/README.md index 457d6633..c067e43f 100644 --- a/README.md +++ b/README.md @@ -8,7 +8,7 @@ tools, automation and application code. Agent-friendly should also mean review-friendly: inspectable source, explicit signatures, compiler queries and structured diagnostics help people verify what changed. -The latest published SDK is [v0.7.1-beta.1](https://github.com/ColinHouse/Sprig/releases/tag/v0.7.1-beta.1); it requires a separate JDK (17 or newer for that release; the source on `main` and the next release require JDK 21+). Linux and macOS are release-supported. Windows is an experimental preview. Sprig uses a Java stage-0 compiler and is not self-hosted. Check the [release status](docs/releases/validation.md) and installed `sprig capabilities --json` for the exact implemented feature set. +The latest published SDK is [v0.8.0-beta.1](https://github.com/ColinHouse/Sprig/releases/tag/v0.8.0-beta.1); it requires a separate JDK 21 or newer. Linux and macOS are release-supported. Windows is an experimental preview. Sprig uses a Java stage-0 compiler and is not self-hosted. Check the [release status](docs/releases/validation.md) and installed `sprig capabilities --json` for the exact implemented feature set. ## A first look @@ -56,6 +56,7 @@ SPR-TYPE-NULLABLE [TYPE] unchecked.spr:4:12: Cannot access 'getDayOfWeek' on a v ## Start here +- [Install the SDK](https://colinhouse.github.io/Sprig/en/guide/getting-started) and the [VS Code extension](https://marketplace.visualstudio.com/items?itemName=ColinHouse.sprig-language) - [Beginner tutorial](https://colinhouse.github.io/Sprig/en/tutorial/) - [中文教程](https://colinhouse.github.io/Sprig/tutorial) - [Try the local Task Tracker](examples/task-tracker/README.md) diff --git a/compiler/src/main/resources/sprig/compiler/tooling/catalog.properties b/compiler/src/main/resources/sprig/compiler/tooling/catalog.properties index 0d015b14..f204a13d 100644 --- a/compiler/src/main/resources/sprig/compiler/tooling/catalog.properties +++ b/compiler/src/main/resources/sprig/compiler/tooling/catalog.properties @@ -3,7 +3,7 @@ compilerVersion=0.8.0-beta.1 languageVersion=0.8-dev jdkMinimum=21 license=Apache-2.0 -releaseStatus=development; based on v0.8.0-beta.1; latest published v0.7.1-beta.1 +releaseStatus=development; based on v0.8.0-beta.1; latest published v0.8.0-beta.1 commands=help,version,check,build,run,test,codes,explain,capabilities,api,wrap,doctor,init,resolve,add,remove,search,publish,project,deps,upgrade,fmt,lsp nativeTypes=Int,Int32,BigInt,Float,Float32,Decimal,Bool,String,Unit collectionTypes=List[T];MutableList[T];Map[K,V];MutableMap[K,V] diff --git a/docs/projects/install.md b/docs/projects/install.md index 86251022..fbc476e4 100644 --- a/docs/projects/install.md +++ b/docs/projects/install.md @@ -1,5 +1,7 @@ # Sprig SDK install and upgrade +The current published SDK is [v0.8.0-beta.1](https://github.com/ColinHouse/Sprig/releases/tag/v0.8.0-beta.1). It includes the 0.8 tutorial features and requires a separate JDK 21+; building from source is optional. The language version remains `0.8-dev`, independently of the SDK release version. + The managed SDK installer supports Linux and macOS with JDK 21+ (`java` and `javac`), `curl`, `unzip`, and `shasum` or `sha256sum`. Windows remains an experimental preview. The installer does not require Maven. diff --git a/docs/releases/v0.8.0-beta.1.md b/docs/releases/v0.8.0-beta.1.md index bda6d8df..e66a52db 100644 --- a/docs/releases/v0.8.0-beta.1.md +++ b/docs/releases/v0.8.0-beta.1.md @@ -1,7 +1,7 @@ # Sprig v0.8.0-beta.1 -> The release body is this file as of the tag. The latest published SDK is -> [v0.7.1-beta.1](https://github.com/ColinHouse/Sprig/releases/tag/v0.7.1-beta.1); the version number follows the +> Published SDK: [v0.8.0-beta.1](https://github.com/ColinHouse/Sprig/releases/tag/v0.8.0-beta.1). +> The GitHub release body preserves this file as of the tag; the version number follows the > [release and versioning policy](https://github.com/ColinHouse/Sprig/blob/main/docs/releases/release-policy.md): a new MINOR, because the > release requires JDK 21 and ships a large feature set. diff --git a/docs/releases/validation-v0.7.1-beta.1.md b/docs/releases/validation-v0.7.1-beta.1.md new file mode 100644 index 00000000..1b4f51ee --- /dev/null +++ b/docs/releases/validation-v0.7.1-beta.1.md @@ -0,0 +1,65 @@ +# Release validation — Sprig v0.7.1-beta.1 + +This is the validation authority for the published `v0.7.1-beta.1` snapshot. +Published experimental Beta: compiler **0.7.1-beta.1**, language version +**0.8-dev**, JDK 17+, Apache-2.0. Linux and macOS are release-supported; +Windows is an experimental, non-blocking preview. This is not a production +stability or API compatibility promise. It is the first release under the +[release and versioning policy](release-policy.md), as a PATCH release. + +## Published artifact + +- [GitHub prerelease](https://github.com/ColinHouse/Sprig/releases/tag/v0.7.1-beta.1), + published **2026-10-07 03:52:22 UTC**. +- Annotated tag `v0.7.1-beta.1` targets + `b7fe68eb1cc98cb018f1d07e472d69d73acf4328`, the merge commit of #119. +- ZIP: [`sprig-v0.7.1-beta.1-jdk.zip`](https://github.com/ColinHouse/Sprig/releases/download/v0.7.1-beta.1/sprig-v0.7.1-beta.1-jdk.zip), + **6,189,534 bytes**. +- SHA-256: `be8b43520750870f4fdf080b119ac5fe3159e6a1adf8f0d8abd5e61bc334b81f`; + this matches the GitHub asset digest and the published + [`.sha256` file](https://github.com/ColinHouse/Sprig/releases/download/v0.7.1-beta.1/sprig-v0.7.1-beta.1-jdk.zip.sha256). +- Release workflow [run 37564884616](https://github.com/ColinHouse/Sprig/actions/runs/37564884616) + completed successfully. It built the exact tagged source, ran the tagged test + suite, then downloaded and smoke-tested the same release ZIP on four Linux/ + macOS × JDK 17/26 jobs before publishing the prerelease. + +## Verification evidence + +| Evidence | Result | +|---|---| +| Release-preparation archive and integration checks | On the #119 branch, `package-alpha.py --skip-build` followed by `check-sdk-archive.py` passed (offline help, api, doctor, check, run, probe, init, resolve and project commands and the showcases; 53 Markdown files, 59 local links), and `tests/fabric/check_template.py` reported "Fabric/Loom starter integration: passed". | +| Full contributor gate | Not rerun locally on #119. An independent review ran the full `./scripts/verify.sh` on the head of #112, which carries the release's main changes, with every stage green; its findings were fixed in #116. The required CI matrix ran the full gate on #119. | +| Required CI | #119 passed every check, including the non-blocking Windows preview (11 checks). | +| Tagged-source preflight | Before the tag was pushed, a clean checkout of `b7fe68e` reported `releaseStatus` `prerelease; v0.7.1-beta.1`; `package-alpha.py` with `SPRIG_PACKAGE_VERSION=v0.7.1-beta.1` accepted it, and `check-sdk-archive.py --archive` passed on the resulting ZIP. | +| Tagged-source release workflow | Build and full `scripts/test.py` completed successfully on the tag before packaging was handed to validation (package job 03:03:57–03:21:54 UTC). | +| Downloaded ZIP smoke matrix | Passed on Ubuntu and macOS with JDK 17 and JDK 26 (03:28–03:45 UTC); each job tested the actual release ZIP outside the source checkout. | +| Release notes | The GitHub release body is `docs/releases/v0.7.1-beta.1.md` as of the tag. | +| Public asset checksum | Passed after downloading the published ZIP (6,189,534 bytes): `shasum -a 256 -c sprig-v0.7.1-beta.1-jdk.zip.sha256`. The value equals the GitHub asset digest. | +| Managed SDK upgrade | In an isolated `HOME`, `install-sprig.sh --version v0.7.0-beta.1` installed the previous Beta; `sprig upgrade --check` reported v0.7.1-beta.1 as available; `sprig upgrade` switched to it and retained the previous SDK directory; `sprig capabilities --json` then reported compiler `0.7.1-beta.1`, language `0.8-dev` and `releaseStatus` `prerelease; v0.7.1-beta.1`, and a second check reported it as the latest published SDK. The upgraded SDK rejected a nullable join with `SPR-TYPE-NULLABLE`, printed an `Error`'s message from `toString()`, returned `1` from `"b".compareTo("a")` and ran a 3,000,000-iteration `for` over `range`. | + +#118 (quick fixes in `sprig lsp`) merged into `main` 34 seconds after #119. +The tag was created on the #119 merge commit, so #118 is not part of this +release, and the tag was not moved. + +## Scope and limits + +The Beta SDK packages the compiler and runtime, the `sprig lsp` language +server, the bundled `@std` modules, schema-5 dependency locks, the project test +runner, the Java wrapper generator, explicit Java interoperability including +functional interfaces, varargs, `Int` arguments for `int` parameters and +wildcard bounds, the first-party CLI, HTTP, JSON, SQLite and Web packages, and +the `dev.sprig` Gradle plugin with its Fabric/Loom starter, as described in the +release notes. Query an installed SDK with `sprig capabilities --json` and +inspect the asset contents for the exact shipped surface. + +Windows remains experimental and non-blocking; no Windows support claim is +made. Sprig has no central package registry and is not self-hosted. The VS Code +extension is built from `editors/vscode` and is not part of the SDK archive. +Java interop is intentionally bounded. Types and checked integer operations do +not prove numerical stability, algorithmic correctness, or production +readiness. See [`v0.7.1-beta.1.md`](v0.7.1-beta.1.md) and +[`known limitations`](../language/known-limitations.md). + +The previous published Beta validation record is preserved at +[`validation-v0.7.0-beta.1.md`](validation-v0.7.0-beta.1.md); the versioned +release history remains in [`v0.7.0-beta.1.md`](v0.7.0-beta.1.md). diff --git a/docs/releases/validation.md b/docs/releases/validation.md index 1b4f51ee..b6cf0e7b 100644 --- a/docs/releases/validation.md +++ b/docs/releases/validation.md @@ -1,65 +1,59 @@ -# Release validation — Sprig v0.7.1-beta.1 +# Release validation — Sprig v0.8.0-beta.1 -This is the validation authority for the published `v0.7.1-beta.1` snapshot. -Published experimental Beta: compiler **0.7.1-beta.1**, language version -**0.8-dev**, JDK 17+, Apache-2.0. Linux and macOS are release-supported; -Windows is an experimental, non-blocking preview. This is not a production -stability or API compatibility promise. It is the first release under the -[release and versioning policy](release-policy.md), as a PATCH release. +This is the validation authority for the published `v0.8.0-beta.1` snapshot. +Published experimental Beta: compiler **0.8.0-beta.1**, language version +**0.8-dev**, separate JDK **21+**, Apache-2.0. Linux and macOS are +release-supported; Windows remains an experimental, non-blocking preview. +This is not a production-stability or frozen-language promise. ## Published artifact -- [GitHub prerelease](https://github.com/ColinHouse/Sprig/releases/tag/v0.7.1-beta.1), - published **2026-10-07 03:52:22 UTC**. -- Annotated tag `v0.7.1-beta.1` targets - `b7fe68eb1cc98cb018f1d07e472d69d73acf4328`, the merge commit of #119. -- ZIP: [`sprig-v0.7.1-beta.1-jdk.zip`](https://github.com/ColinHouse/Sprig/releases/download/v0.7.1-beta.1/sprig-v0.7.1-beta.1-jdk.zip), - **6,189,534 bytes**. -- SHA-256: `be8b43520750870f4fdf080b119ac5fe3159e6a1adf8f0d8abd5e61bc334b81f`; - this matches the GitHub asset digest and the published - [`.sha256` file](https://github.com/ColinHouse/Sprig/releases/download/v0.7.1-beta.1/sprig-v0.7.1-beta.1-jdk.zip.sha256). -- Release workflow [run 37564884616](https://github.com/ColinHouse/Sprig/actions/runs/37564884616) - completed successfully. It built the exact tagged source, ran the tagged test - suite, then downloaded and smoke-tested the same release ZIP on four Linux/ - macOS × JDK 17/26 jobs before publishing the prerelease. +- [GitHub prerelease](https://github.com/ColinHouse/Sprig/releases/tag/v0.8.0-beta.1), + published **2026-10-08 16:25:30 UTC**. +- Tag `v0.8.0-beta.1` targets `13526327975e8ec8adf02a1cdf35419d235f1dd0`, + the merge commit of #230. The published tag has not been moved. +- ZIP: [`sprig-v0.8.0-beta.1-jdk.zip`](https://github.com/ColinHouse/Sprig/releases/download/v0.8.0-beta.1/sprig-v0.8.0-beta.1-jdk.zip), + **6,925,087 bytes**. +- SHA-256: `9c926aa10c7ec915deb76f5782be11137988a29a68d379bc194a11f8e3c08bab`. + A fresh download matched both the GitHub asset digest and the published + [`.sha256` file](https://github.com/ColinHouse/Sprig/releases/download/v0.8.0-beta.1/sprig-v0.8.0-beta.1-jdk.zip.sha256). +- Release workflow [run 37806498884](https://github.com/ColinHouse/Sprig/actions/runs/37806498884) + completed successfully on the tagged commit. ## Verification evidence | Evidence | Result | |---|---| -| Release-preparation archive and integration checks | On the #119 branch, `package-alpha.py --skip-build` followed by `check-sdk-archive.py` passed (offline help, api, doctor, check, run, probe, init, resolve and project commands and the showcases; 53 Markdown files, 59 local links), and `tests/fabric/check_template.py` reported "Fabric/Loom starter integration: passed". | -| Full contributor gate | Not rerun locally on #119. An independent review ran the full `./scripts/verify.sh` on the head of #112, which carries the release's main changes, with every stage green; its findings were fixed in #116. The required CI matrix ran the full gate on #119. | -| Required CI | #119 passed every check, including the non-blocking Windows preview (11 checks). | -| Tagged-source preflight | Before the tag was pushed, a clean checkout of `b7fe68e` reported `releaseStatus` `prerelease; v0.7.1-beta.1`; `package-alpha.py` with `SPRIG_PACKAGE_VERSION=v0.7.1-beta.1` accepted it, and `check-sdk-archive.py --archive` passed on the resulting ZIP. | -| Tagged-source release workflow | Build and full `scripts/test.py` completed successfully on the tag before packaging was handed to validation (package job 03:03:57–03:21:54 UTC). | -| Downloaded ZIP smoke matrix | Passed on Ubuntu and macOS with JDK 17 and JDK 26 (03:28–03:45 UTC); each job tested the actual release ZIP outside the source checkout. | -| Release notes | The GitHub release body is `docs/releases/v0.7.1-beta.1.md` as of the tag. | -| Public asset checksum | Passed after downloading the published ZIP (6,189,534 bytes): `shasum -a 256 -c sprig-v0.7.1-beta.1-jdk.zip.sha256`. The value equals the GitHub asset digest. | -| Managed SDK upgrade | In an isolated `HOME`, `install-sprig.sh --version v0.7.0-beta.1` installed the previous Beta; `sprig upgrade --check` reported v0.7.1-beta.1 as available; `sprig upgrade` switched to it and retained the previous SDK directory; `sprig capabilities --json` then reported compiler `0.7.1-beta.1`, language `0.8-dev` and `releaseStatus` `prerelease; v0.7.1-beta.1`, and a second check reported it as the latest published SDK. The upgraded SDK rejected a nullable join with `SPR-TYPE-NULLABLE`, printed an `Error`'s message from `toString()`, returned `1` from `"b".compareTo("a")` and ran a 3,000,000-iteration `for` over `range`. | +| Tagged-source packaging | The release workflow's `package` job completed successfully. See the workflow run for its individual build, test and archive steps. | +| Downloaded ZIP smoke matrix | All four release jobs passed: Ubuntu and macOS, each with JDK 21 and JDK 26. These jobs test the downloaded SDK, not only the source checkout. | +| Publication | The release job passed; the public prerelease contains the ZIP and its checksum asset. | +| Local onboarding, 2026-10-09 | A fresh official ZIP was downloaded, its SHA-256 verified, and extracted in a temporary directory on macOS with JDK 26.0.1. `sprig version` printed `sprig-compiler 0.8.0-beta.1`; `sprig doctor --json` reported `jdkMinimum: 21` and `javacAvailable: true`. `sprig init hello`, `sprig resolve` and `sprig run` each exited 0; the program printed `Hello, Sprig!`. | +| Installed identity | The same extracted SDK's `sprig capabilities --json` reported compiler `0.8.0-beta.1`, language `0.8-dev` and `releaseStatus` `prerelease; v0.8.0-beta.1`. | -#118 (quick fixes in `sprig lsp`) merged into `main` 34 seconds after #119. -The tag was created on the #119 merge commit, so #118 is not part of this -release, and the tag was not moved. +The local check used the manually extracted ZIP, not the managed installer or +an upgrade from an older SDK. It did not run Windows or manually exercise every +editor command. Those results are not inferred from the onboarding smoke check. ## Scope and limits -The Beta SDK packages the compiler and runtime, the `sprig lsp` language -server, the bundled `@std` modules, schema-5 dependency locks, the project test -runner, the Java wrapper generator, explicit Java interoperability including -functional interfaces, varargs, `Int` arguments for `int` parameters and -wildcard bounds, the first-party CLI, HTTP, JSON, SQLite and Web packages, and -the `dev.sprig` Gradle plugin with its Fabric/Loom starter, as described in the -release notes. Query an installed SDK with `sprig capabilities --json` and -inspect the asset contents for the exact shipped surface. +The SDK includes the tutorial's 0.8 syntax and standard modules, Java +interoperability, the language server, project/dependency tools, Gradle/JVM +integration and the Fabric starter. See the [release notes](v0.8.0-beta.1.md) +for additions, incompatible changes and library limits; query an installed SDK +with `sprig capabilities --json` for its actual surface. -Windows remains experimental and non-blocking; no Windows support claim is -made. Sprig has no central package registry and is not self-hosted. The VS Code -extension is built from `editors/vscode` and is not part of the SDK archive. -Java interop is intentionally bounded. Types and checked integer operations do -not prove numerical stability, algorithmic correctness, or production -readiness. See [`v0.7.1-beta.1.md`](v0.7.1-beta.1.md) and -[`known limitations`](../language/known-limitations.md). +The [VS Code extension](https://marketplace.visualstudio.com/items?itemName=ColinHouse.sprig-language) +is published separately as `ColinHouse.sprig-language`; its current version is +**0.3.1**, independent of the SDK and language versions. The Marketplace listing +was checked on 2026-10-09. The SDK ZIP does not install the extension or a JDK. -The previous published Beta validation record is preserved at -[`validation-v0.7.0-beta.1.md`](validation-v0.7.0-beta.1.md); the versioned -release history remains in [`v0.7.0-beta.1.md`](v0.7.0-beta.1.md). +Windows remains experimental. Java interoperability is bounded, the compiler +is not self-hosted, and type checking does not prove numerical stability or +application correctness. See [known limitations](../language/known-limitations.md). + +## Previous releases + +The preceding published SDK's evidence is preserved unchanged in +[validation-v0.7.1-beta.1.md](validation-v0.7.1-beta.1.md); its release notes +are [v0.7.1-beta.1.md](v0.7.1-beta.1.md). Earlier evidence remains in +[validation-v0.7.0-beta.1.md](validation-v0.7.0-beta.1.md). diff --git a/editors/vscode/README.md b/editors/vscode/README.md index f08314c8..f13f90ac 100644 --- a/editors/vscode/README.md +++ b/editors/vscode/README.md @@ -12,15 +12,20 @@ Extension version **0.3.1** is independent of the compiler version. ## Install / 安装 -Install **Sprig** (`ColinHouse.sprig-language`) from the Extensions view. The -Visual Studio Marketplace serves VS Code; Open VSX serves VSCodium and other -compatible editors. To build the extension yourself, see -[Development](#development--开发). +Install **Sprig** (`ColinHouse.sprig-language`, publisher **ColinHouse**) from the +[Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=ColinHouse.sprig-language), or run: + +```sh +code --install-extension ColinHouse.sprig-language +``` + +The extension and SDK are installed separately. To build a local VSIX for +extension development or compatible editors, see [Development](#development--开发). Highlighting, the outline and snippets work immediately, without Java or the compiler. Everything else needs JDK 21+ and the [Sprig SDK](https://colinhouse.github.io/Sprig/en/guide/getting-started). Set -**Sprig: Compiler Path** to the SDK's `bin/sprig` launcher, or put the SDK's +**Sprig: Compiler Path** to the SDK's `bin/sprig` launcher (`bin\sprig.cmd` on Windows), or put the SDK's `bin` on PATH. A built Sprig source checkout is found by searching parent directories for `bin/sprig` after PATH. diff --git a/scripts/internal/check-tooling-consistency.py b/scripts/internal/check-tooling-consistency.py index d9e5563a..ed9ba63b 100644 --- a/scripts/internal/check-tooling-consistency.py +++ b/scripts/internal/check-tooling-consistency.py @@ -70,6 +70,18 @@ def invoke(*args): "website/en/project/release-status.md": [published_version, published_tag], "website/project/release-status.md": [published_version, published_tag], } +# Onboarding pages must identify the published SDK, rather than a pre-release +# preparation snapshot. Historical release notes are deliberately excluded. +for name in ("website/index.md", "website/en/index.md", + "website/guide/getting-started.md", "website/en/guide/getting-started.md", + "website/tutorial/index.md", "website/en/tutorial/index.md", + "website/tutorial/ch01-tools.md", "website/en/tutorial/ch01-tools.md"): + required[name] = [published_tag] +for name in ("website/guide/editor.md", "website/en/guide/editor.md", "editors/vscode/README.md"): + required[name] = ["https://marketplace.visualstudio.com/items?itemName=ColinHouse.sprig-language", + "code --install-extension ColinHouse.sprig-language"] +for name in ("website/tutorial/ch23-tooling.md", "website/en/tutorial/ch23-tooling.md"): + required[name] = ["sprig-compiler " + version, "compilerVersion: " + version] for name, markers in required.items(): text = (ROOT / name).read_text() for marker in markers: diff --git a/website/en/guide/editor.md b/website/en/guide/editor.md index d371abf0..74955eed 100644 --- a/website/en/guide/editor.md +++ b/website/en/guide/editor.md @@ -9,7 +9,7 @@ The extension helps you write Sprig in VS Code with: - an outline - hover information - completion -- parameter hints and semantic highlighting (with a compiler that provides them) +- parameter hints and semantic highlighting (supported by compiler v0.8.0-beta.1) - go-to-definition, find references and rename - snippets - a Testing view @@ -17,26 +17,33 @@ The extension helps you write Sprig in VS Code with: Types, signatures and errors all come from the `sprig` command you installed; the extension doesn't do any type checking of its own. When that compiler has the [language server](/en/guide/tooling#language-server), `sprig lsp`, the extension starts it and gets everything above from it. -The extension isn't on the VS Code Marketplace yet and isn't part of the SDK archive, so you package and install it yourself from source. +The extension is available on the [Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=ColinHouse.sprig-language) as `ColinHouse.sprig-language`. It does not include the Sprig SDK; install that separately. ## Installing -In the Sprig repository, in `editors/vscode/`, run: +Search for **Sprig** in VS Code's Extensions view, check that the publisher is **ColinHouse**, and install it. Or run: ```sh -npm ci -npm run package +code --install-extension ColinHouse.sprig-language ``` -That creates `dist/sprig-language-0.3.1.vsix`. In VS Code's Extensions view, choose `…` → **Install from VSIX…** and pick it, or run: +### Package from source (optional) + +Packaging is needed only for extension development or local modifications. In the repository's `editors/vscode/` directory, run: ```sh +npm ci +npm run package code --install-extension dist/sprig-language-0.3.1.vsix ``` +Alternatively, choose `…` → **Install from VSIX…** in the Extensions view and select the generated VSIX. + +### Configure the compiler + Highlighting, the outline and snippets work right away, without Java or the compiler. -Everything else needs JDK 21+ and the [Sprig SDK](/en/guide/getting-started). Then set **Sprig: Compiler Path** (`sprig.compilerPath`) to the SDK's `bin/sprig`. If you don't set it, the extension looks for `sprig` on your `PATH` first, then searches parent directories for a `bin/sprig` built from source. The Testing view needs compiler v0.5.0-beta.1 or newer. +Everything else needs JDK 21+ and the [Sprig SDK](/en/guide/getting-started). Then set **Sprig: Compiler Path** (`sprig.compilerPath`) to the SDK's `bin/sprig` (`bin\sprig.cmd` on Windows). If you don't set it, the extension looks for `sprig` on your `PATH` first, then searches parent directories for a `bin/sprig` built from source. The Testing view needs compiler v0.5.0-beta.1 or newer. The language server is new in v0.6.0-beta.1. With v0.6.0-beta.1 or newer, the extension uses it automatically; with v0.5.0-beta.1, it falls back to running separate compiler commands, as the table below shows. To turn the server off, set `sprig.languageServer.enabled` to `false`. @@ -45,7 +52,7 @@ The language server is new in v0.6.0-beta.1. With v0.6.0-beta.1 or newer, the ex | Feature | With the language server | With v0.5.0-beta.1 | |---|---|---| | Errors | Shown as you type, in the Problems panel. An error inside an imported file shows on its `import` line | Shown when you save | -| Quick fixes | When an error's fix is one mechanical rewrite, such as `else if` to `elif` or a missing `@std` import, the lightbulb next to it offers that change, and one click applies it. Needs a compiler newer than v0.7.1-beta.1 | Not available | +| Quick fixes | When an error's fix is one mechanical rewrite, such as `else if` to `elif` or a missing `@std` import, the lightbulb next to it offers that change, and one click applies it. Included in compiler v0.8.0-beta.1 | Not available | | Hover | Any name: its declaration and type, including local variables and parameters, plus the comment above it | Keywords, `JavaClass.method`, `module.function` and your top-level declarations, from the saved file | | Completion | After a dot, the members of any value, including local variables; elsewhere, the names in scope and keywords | Keywords, the file's declarations and imported names; members after `JavaClass.`, `module.`, an enum name or a top-level variable | | Go to Definition (F12) | Any name, across files | Import paths, `module.member` and declarations in the same file | @@ -58,7 +65,7 @@ The language server is new in v0.6.0-beta.1. With v0.6.0-beta.1 or newer, the ex In both cases, hovering over a keyword shows its `sprig help` text, **Go to Symbol in Workspace** searches all your files, and clicking an error code opens the diagnostic code reference. For snippets, type a prefix such as `func`, `class`, `variant`, `match`, `ifnn`, `try` or `importj` and press Tab. -These new capabilities come from the updated compiler; extension 0.3.1 ships with it and registers them automatically. Nested calls and commas inside strings do not advance the outer call's active parameter; named constructor fields can be written out of order. Java parameter names missing from bytecode use `arg0`, `arg1`, etc. Java candidates are not ranked by argument types, and Sprig generics display their written type parameters; built-in functions and native string/collection methods have no parameter signatures yet. Unrelated syntax errors can still prevent a hint. Syntax or name-resolution failures clear semantic tokens and leave lexical highlighting available. +Compiler v0.8.0-beta.1 provides these capabilities; extension 0.3.1 supports them and registers them automatically. Nested calls and commas inside strings do not advance the outer call's active parameter; named constructor fields can be written out of order. Java parameter names missing from bytecode use `arg0`, `arg1`, etc. Java candidates are not ranked by argument types, and Sprig generics display their written type parameters; built-in functions and native string/collection methods have no parameter signatures yet. Unrelated syntax errors can still prevent a hint. Syntax or name-resolution failures clear semantic tokens and leave lexical highlighting available. ## Commands diff --git a/website/en/guide/getting-started.md b/website/en/guide/getting-started.md index d12b8692..4f6bfa11 100644 --- a/website/en/guide/getting-started.md +++ b/website/en/guide/getting-started.md @@ -25,19 +25,19 @@ sprig version To upgrade later, run `sprig upgrade --check` to see whether there's a new version, then `sprig upgrade`. -::: tip You get v0.7.1-beta.1 -The install script installs the newest published release, v0.7.1-beta.1 today. This site follows the `main` branch, and some of what it shows (`if` expressions, contract classes, `@std/concurrent`, `sprig build --bundle`) is newer. To use those, build from source as described [below](#windows-and-building-from-source); [release status](/en/project/release-status) lists the differences. +::: tip Current published release: v0.8.0-beta.1 +The installer selects the newest published release, including Betas. The current v0.8.0-beta.1 includes the tutorial's `if` expressions, contract classes, function references and `@std/concurrent`; building from source is optional. SDK, language and extension versions are independent. Query `sprig capabilities --json` for exact capabilities and see [release status](/en/project/release-status). ::: ### Manual download -You can also download the ZIP from the [release page](https://github.com/ColinHouse/Sprig/releases/tag/v0.7.1-beta.1), verify it and unpack it yourself: +You can also download the ZIP from the [release page](https://github.com/ColinHouse/Sprig/releases/tag/v0.8.0-beta.1), verify it and unpack it yourself: ```bash -curl -LO https://github.com/ColinHouse/Sprig/releases/download/v0.7.1-beta.1/sprig-v0.7.1-beta.1-jdk.zip -curl -LO https://github.com/ColinHouse/Sprig/releases/download/v0.7.1-beta.1/sprig-v0.7.1-beta.1-jdk.zip.sha256 -shasum -a 256 -c sprig-v0.7.1-beta.1-jdk.zip.sha256 -unzip sprig-v0.7.1-beta.1-jdk.zip +curl -LO https://github.com/ColinHouse/Sprig/releases/download/v0.8.0-beta.1/sprig-v0.8.0-beta.1-jdk.zip +curl -LO https://github.com/ColinHouse/Sprig/releases/download/v0.8.0-beta.1/sprig-v0.8.0-beta.1-jdk.zip.sha256 +shasum -a 256 -c sprig-v0.8.0-beta.1-jdk.zip.sha256 +unzip sprig-v0.8.0-beta.1-jdk.zip ``` On Linux, `sha256sum -c` works too. If the checksum doesn't match, download the file again; don't skip the check. Then add the unpacked directory's `bin` to your `PATH`. @@ -71,7 +71,7 @@ You should see `Hello, Sprig!`. Here's what each command did: Almost all of them accept `--json` and return structured output that editors, scripts and AI coding assistants can read. See [tools and JSON](/en/guide/tooling). -For editing, there's a [VS Code extension](/en/guide/editor) (a local preview for now) with syntax highlighting, checks on save and one-click run. +The [Sprig VS Code extension](https://marketplace.visualstudio.com/items?itemName=ColinHouse.sprig-language) is available on the Marketplace, with highlighting, live diagnostics, parameter hints and one-command runs. See the [extension guide](/en/guide/editor) for installation and compiler path settings. ## Windows and building from source diff --git a/website/en/guide/tooling.md b/website/en/guide/tooling.md index fceb0c2a..b6210418 100644 --- a/website/en/guide/tooling.md +++ b/website/en/guide/tooling.md @@ -2,7 +2,7 @@ Sprig comes as one command-line program, `sprig`, and everything it does is a subcommand. There's no background process: even the language server is a subcommand, `sprig lsp`, which your editor starts itself. For VS Code, see the [VS Code extension](/en/guide/editor). -This page follows the `main` branch. `sprig build --bundle`, `sprig search`, `sprig publish` and `run --no-cache` are newer than the published v0.7.1-beta.1; every other command is in it. For exactly what your installed SDK supports, run `sprig capabilities --json`. +This page follows `main`. The current published v0.8.0-beta.1 includes the commands below, including `sprig build --bundle`, `sprig search`, `sprig publish` and `run --no-cache`. Query `sprig capabilities --json` for your installed SDK's exact capabilities. ## The commands @@ -75,7 +75,7 @@ A small greeting program that runs successfully: ```json { "schemaVersion": 1, - "toolVersion": "sprig-compiler 0.7.1-beta.1", + "toolVersion": "sprig-compiler 0.8.0-beta.1", "command": "run", "exitCode": 0, "programOutput": "Hello, Ada!\n", @@ -101,7 +101,7 @@ And with `--json` (the real `uri` is a full `file:` path, shortened here): ```json { "schemaVersion": 1, - "toolVersion": "sprig-compiler 0.7.1-beta.1", + "toolVersion": "sprig-compiler 0.8.0-beta.1", "command": "check", "exitCode": 1, "environment": {"classpath": []}, @@ -153,7 +153,7 @@ The full approach is in [working with AI assistants](/en/guide/agent-workflow). `sprig lsp` speaks the Language Server Protocol over standard input and output, so editors such as Neovim and Helix can use it directly, and the [VS Code extension](/en/guide/editor) starts it for you. It's new in v0.6.0-beta.1. -It gives you errors as you type, hover, go to definition, references, an outline, completion, formatting, rename for local variables and parameters, and quick fixes: when an error's fix is one mechanical rewrite, your editor applies it in one click. All of it comes from the same compiler as `sprig check`, so your editor and the command line never disagree. While your code doesn't parse, the server answers with nothing rather than a guess. Quick fixes are newer than v0.7.1-beta.1 and come with the next release. +It gives you errors as you type, hover, go to definition, references, an outline, completion, formatting, rename for local variables and parameters, and quick fixes: when an error's fix is one mechanical rewrite, your editor applies it in one click. All of it comes from the same compiler as `sprig check`, so your editor and the command line never disagree. Most semantic queries need parseable source; parameter hints can handle calls whose closing parenthesis is still missing. Quick fixes, parameter hints and semantic tokens are included in v0.8.0-beta.1. Parameter hints can handle unfinished calls, but other syntax errors may still disable semantic features. Editor setup and the details of each feature are in the [language server reference](/en/reference/tooling/lsp). diff --git a/website/en/index.md b/website/en/index.md index 10dde102..842f3dcf 100644 --- a/website/en/index.md +++ b/website/en/index.md @@ -55,7 +55,7 @@ SPR-MATCH-NONEXHAUSTIVE [FLOW] main.spr:9:12: Missing case: Shape.Triangle ## Can I use it yet? -Sprig is young. The current release is the experimental v0.7.1-beta.1. Everything listed above works today, and each item has an example you can run. It has no inheritance and no variance, and it isn't meant for production use yet. This site follows the `main` branch, so some of what it shows, such as contract classes, `if` expressions, function references and `@std/concurrent`, is newer than v0.7.1-beta.1; [release status](/en/project/release-status) has the full list. The limits are listed in [known limitations](/en/reference/language/known-limitations). +Sprig is young. The current release is the experimental [v0.8.0-beta.1](https://github.com/ColinHouse/Sprig/releases/tag/v0.8.0-beta.1), requiring JDK 21+. The features above and the syntax used by the tutorial are included in this SDK. It has no Sprig class inheritance or variance and is not meant for production use yet. This site follows `main`; consult [release status](/en/project/release-status) and your installed compiler for later changes. See [known limitations](/en/reference/language/known-limitations) for the full list. ## Up and running in five minutes diff --git a/website/en/project/release-status.md b/website/en/project/release-status.md index 80876b1c..24cf851d 100644 --- a/website/en/project/release-status.md +++ b/website/en/project/release-status.md @@ -1,69 +1,56 @@ # Release status -The current release is [v0.7.1-beta.1](https://github.com/ColinHouse/Sprig/releases/tag/v0.7.1-beta.1). +The current published SDK is [v0.8.0-beta.1](https://github.com/ColinHouse/Sprig/releases/tag/v0.8.0-beta.1). -| | | +| Item | Current status | |---|---| -| Compiler | `0.7.1-beta.1` | -| Language version | `0.8-dev` | -| Requires | JDK 21 or newer for the install script and for the source on `main` (the SDK doesn't include a JDK). The published v0.7.1-beta.1 itself still runs on JDK 17 if you install its ZIP by hand | +| SDK / compiler | `0.8.0-beta.1` | +| Language | `0.8-dev`, not frozen yet | +| Runtime requirement | Separate JDK 21+; the SDK does not bundle a JDK | +| VS Code extension | `ColinHouse.sprig-language` on the Marketplace, version `0.3.1`; install the SDK separately | | License | Apache-2.0 | -| Platforms | Linux and macOS are supported; Windows is an experimental preview | +| Platforms | Linux and macOS are release-supported; Windows is an experimental preview | -This is an experimental Beta. It's for trying Sprig out and reporting problems; don't move production projects to it yet. +This is an experimental Beta for trying Sprig and reporting problems, not for migrating production projects. The published SDK can run the current tutorial; building from source is optional. See [installation](/en/guide/getting-started) and the [extension guide](/en/guide/editor). -## What's new in this release +## What this release adds -v0.7.1-beta.1 fixes what an evaluation of v0.7.0-beta.1 found with real programs and Java baselines, and makes Java calls easier: +These changes from v0.7.1-beta.1 are included in the v0.8.0-beta.1 SDK: -- `for i in range(n)` counts instead of building a list, so a loop of any length runs in constant memory -- top-level code with several hot loops runs as fast as the same Java -- joining a value that may be `null` into text is an error, instead of printing `null` -- an `Error` shows its message wherever it becomes text, `toString()` included -- `a.compareTo(b)` on Strings, which is what a Java `Comparator` wants -- an `Int` goes into an `int` Java parameter with a run-time range check, and wildcard types in Java signatures, such as `List`, are read at their bounds -- `sprig api` shows the comment written above each declaration -- help and `sprig capabilities` say what the compiler actually does, including that `==` compares two class objects by identity +- Language: `if` expressions, type arguments inferred from arguments, contract classes and `conform`, one-line classes, named function references, error classes, read-only views of mutable collections, and more complete nullability narrowing across conditional branches. +- Java: extending a Java class with `conform`, nullability annotations, argument-based type inference for Java generic methods, and `--classpath-file`. +- Libraries and packages: structured scopes and virtual threads in `@std/concurrent`, and improvements to collections, text, regex, Web and SQLite. Registry packages are published through PRs to `registry/`, validated by CI; there is no central account-based upload service. +- Tools: `sprig build --bundle`, the `run`/`test` compilation cache, `sprig search` and `sprig publish`. +- Editor: quick fixes, parameter hints, semantic highlighting, and a warning when the references scan omits results at its limit. Rename remains limited to locals and parameters; there is no debugger. Other syntax errors may still affect semantic features. +- The minimum JDK rises from 17 to 21. -It's a patch release: everything from v0.7.0-beta.1 is still there, and so is everything from v0.6. There's no central package registry yet, and the compiler isn't written in Sprig itself (it isn't self-hosted). For exactly what your installed SDK supports, run `sprig capabilities --json`. The full story is in the [v0.7.1-beta.1 release notes](https://github.com/ColinHouse/Sprig/blob/main/docs/releases/v0.7.1-beta.1.md). +See the [v0.8.0-beta.1 notes](https://github.com/ColinHouse/Sprig/blob/main/docs/releases/v0.8.0-beta.1.md) for the complete changes and limits. Query `sprig capabilities --json` for your installed SDK's actual features. -## Upgrading from v0.7.0 +## Upgrade from v0.7.1 -Run `sprig upgrade`, then run `sprig resolve` once in each project, because a lock file records the compiler that wrote it. +Install JDK 21+ first. For a managed Linux/macOS installation, run `sprig upgrade`. Manually extracted SDKs, including Windows, need a new verified ZIP. Run `sprig resolve` inside projects after upgrading to update the lock's compiler identity. -Two kinds of programs that v0.7.0 accepted are now rejected, because they could print `null` or fail at run time. The error tells you what to change: +This MINOR upgrade includes changes that may require source edits: -- joining a value that may be `null` into a `String`: check it first, or give it a fallback with `or_else` from `@std/nulls.spr`. A value a Java method returns counts as possibly `null` too; a `toString()` result doesn't -- using a Java exception's `message` as a `String`: Java may leave it `null`, so it's a `String?` now. Join the exception itself, or check the message first +- Number conversions now have one spelling: replace `n.toFloat()`, `x.toInt()`, `Decimal.fromInt(n)` and `Int.parse(text)` with `n.toFloatExact()`, `x.toIntExact()`, `n.toDecimal()` and `text.toInt()` respectively. +- More complete narrowing in `elif` and `else` rejects some older patterns in branches already known to be non-null. +- Some library functions now declare `throws Error`; callers need to handle errors as their signatures require. +- See the release notes' [upgrade section](https://github.com/ColinHouse/Sprig/blob/main/docs/releases/v0.8.0-beta.1.md#upgrade-from-v071-beta1) for the remaining collection, numeric and interop changes. -One program that still compiles prints something else: `toString()` on an `Error` now gives its message, without the `sprig.runtime.SprigError: ` prefix. +## Website, source and released SDK -Coming from v0.6? Read the upgrade section of the [v0.7.0-beta.1 release notes](https://github.com/ColinHouse/Sprig/blob/main/docs/releases/v0.7.0-beta.1.md) as well. - -## Changes since the release - -This website follows the source on the repository's `main` branch, which is ahead of v0.7.1-beta.1. Not every page marks what's new, so go by this list: - -- Language: `if` expressions; `elif` and `else` knowing the earlier conditions are false; generic calls that work out their type arguments from the arguments you pass; contract classes (`conform C to Contract`); one-line classes `class Pair(first: Int, second: Int)`; named functions, module functions and methods used as values without parentheses; error classes (`conform E to Error(message)`); a `MutableList` accepted where a `List` is expected; `compareTo` on the number types, `String.lastIndexOf`, and comparisons with a literal such as `xs == []`. -- Java: extending a Java class with `conform C to J(fields) as NAME`; nullability annotations; Java generic methods inferring their type arguments from the arguments; the `--classpath-file` option. -- Libraries: structured scopes over virtual threads in `@std/concurrent`; `find_groups` in `@std/regex`, `max`, `min`, `max_by` and `min_by` in `@std/lists`, `escape_html` in `@std/text`; `app.put`, `app.patch` and `app.run_on` in sprig-web; one statement per SQL string in sprig-sqlite, and migrations checked as a whole before any runs. -- Tools: quick fixes in the language server; `sprig build --bundle`; the compiled-class cache of `run` and `test` (`run --no-cache`); `sprig search`, `sprig publish` and packages published to `registry/` by pull request; a runtime failure inside an `@std` function reported at your line that called it. -- A JDK 21 minimum. - -A few changes reject code that v0.7.1-beta.1 accepts. The one you'll meet first is the number conversions: each now has one spelling. `n.toFloat()`, `x.toInt()`, `Decimal.fromInt(n)` and `Int.parse(text)` are gone; write `n.toFloatExact()`, `x.toIntExact()`, `n.toDecimal()` and `text.toInt()`. The others (a narrower type in `elif` and `else`, library functions that now declare `throws Error`, a Float map key reached through generic code) and the full upgrade list are in the draft notes for the next release, [v0.8.0-beta.1](https://github.com/ColinHouse/Sprig/blob/main/docs/releases/v0.8.0-beta.1.md). +The site follows `main`. The current tutorial's features are published; later source changes may precede the next SDK. `sprig version` identifies the SDK/compiler release, and `sprig capabilities --json` reports its language version and features. `languageVersion: 0.8-dev` does not mean that the SDK is unpublished. ## How it was verified -The release's SDK archive passed acceptance checks on Linux and macOS with JDK 17 and 26, including checksum verification and the publishing workflow. The [release validation record](https://github.com/ColinHouse/Sprig/blob/main/docs/releases/validation.md) lists the source revision, the archive's SHA-256, the commands run and links to the CI runs. - -A build from source without a tag reports itself as development; a build that exactly matches a clean tag reports prerelease. +The release workflow passed the downloaded-SDK checks on Linux/macOS × JDK 21/26. A fresh local ZIP download on macOS/JDK 26.0.1 also passed SHA-256 verification and `init → resolve → run`. See the [release validation record](https://github.com/ColinHouse/Sprig/blob/main/docs/releases/validation.md) for the source commit, digest, CI links and limits. The local smoke check does not imply manual Windows or complete editor-interaction coverage. ## Still planned -- Java arrays as values you can index, and full Java generics +- Java arrays as indexable values, and full Java generics - a compiler written in Sprig itself (self-hosting) -Also note that type checking doesn't prove numerical stability. +Type checking does not prove numerical stability or application correctness either. ## Earlier releases diff --git a/website/en/tutorial/ch01-tools.md b/website/en/tutorial/ch01-tools.md index 0529da47..a0d64530 100644 --- a/website/en/tutorial/ch01-tools.md +++ b/website/en/tutorial/ch01-tools.md @@ -65,96 +65,70 @@ Common problems: ## 1.3 Install Sprig, and check the version -This part matters most: **this book follows the 0.8 language on the `main` branch**. The official release and the install script currently give you `v0.7.1-beta.1`, which does not have some of the syntax the book uses, so later programs won't run on it. Until 0.8 is released, build from source. +The syntax and standard modules used by this book are included in the published [v0.8.0-beta.1 SDK](https://github.com/ColinHouse/Sprig/releases/tag/v0.8.0-beta.1). Install the SDK to begin; you do not need to build the compiler first. -### Build from source (Linux, macOS, Windows) +### Linux / macOS: install the SDK -You need Git, JDK 21+, and Python 3.12+. In a terminal: +After installing JDK 21+, run: ```bash -git clone https://github.com/ColinHouse/Sprig.git -cd Sprig -python3 scripts/build.py +curl -fsSL https://raw.githubusercontent.com/ColinHouse/Sprig/main/scripts/install-sprig.sh | sh +export PATH="$HOME/.local/bin:$PATH" +sprig version ``` -On Windows, use this for the last line: +The installer selects the newest published release, including Betas, checks the ZIP's SHA-256, installs the SDK under `~/.sprig/versions/` and places its launcher at `~/.local/bin/sprig`. It does not edit your shell configuration. The `export` above affects this terminal only; add it to `~/.zshrc` for zsh or `~/.bashrc` for bash if new terminals should find `sprig` too. -```powershell -py -3 scripts/build.py -``` +You can also download, verify and unpack the ZIP manually; see [installation](/en/guide/getting-started). Using the SDK does not require Python or Git. The first Maven dependency resolution may still need a network connection. -The first build downloads pinned build tools, so it needs a network connection and a few minutes. When it finishes, `bin/sprig` (on Windows, `bin\sprig.cmd`) in that checkout is the compiler. +### Windows: unpack the SDK -### Make `sprig` typeable (optional) +Windows is an experimental preview and has no managed installer. Download the release ZIP and its matching `.sha256` file, verify the checksum, then unpack and use `bin\sprig.cmd`. Add the extracted SDK's `bin` directory to `Path` to type `sprig ...` directly. See [installing on Windows](/en/reference/projects/install#windows) for the full steps. -The rest of the book writes commands as `sprig`. To avoid typing the full path, add the checkout's `bin` directory to `PATH`. The default macOS terminal is zsh: - -```bash -echo 'export PATH="/replace/this/with/the/checkout/Sprig/bin:$PATH"' >> ~/.zshrc -``` - -Then open a new terminal. For bash use `~/.bashrc`; Linux is the same idea. On Windows, search Settings for "environment variables" and add `...\Sprig\bin` to Path. - -You can also skip this: every `sprig ...` in the book can be `/path/to/Sprig/bin/sprig ...`, or `...\Sprig\bin\sprig.cmd ...` on Windows. - -### Checking the version: `sprig version` is not enough - -Look at the version command first: +### Check the version ```bash sprig version ``` +The current SDK prints: + ```text -sprig-compiler 0.7.1-beta.1 +sprig-compiler 0.8.0-beta.1 ``` -**This does not tell the new compiler from the old one.** The published SDK also calls itself `0.7.1-beta.1`, and so does the 0.8 compiler built from `main`. The first line of `sprig capabilities` is no help either: both say "language 0.8-dev". Don't trust version strings; trust the feature list: +This is the **SDK/compiler release version**. If it shows an older version, run `sprig upgrade` for a managed installation, or download a new ZIP for a manual installation. If the old version persists, check that `PATH` and **Sprig: Compiler Path** do not point to another compiler. + +Then run: ```bash sprig capabilities ``` -```text -Sprig compiler 0.7.1-beta.1 / language 0.8-dev -JDK minimum: 21 -Commands: help, version, check, build, run, test, codes, explain, capabilities, api, wrap, doctor, init, resolve, add, remove, search, publish, project, deps, upgrade, fmt, lsp -Types: Int, Int32, BigInt, Float, Float32, Decimal, Bool, String, Unit -Implemented: typed functions, one-line class declarations, contract classes (methods without bodies) with conform, function references (named, module and method functions, and print, as values), source function types fn(A) -> R, function types that throw Error, rethrows functions, classes, enums, variants, match statements, match expressions, if expressions, explicit declaration reexports, nullable types, typed catch, local modules, lambdas up to three parameters, generic blocks with one or more type parameters, explicit Type[Arg] generic uses, type arguments inferred from call arguments, Equatable capability, Comparable capability, Sprig function values passed as Java functional interfaces with up to three parameters, Java varargs calls, declared foreign JVM conformance (conform Class to ImportedInterface), Java class conformance with a parent view, error classes (conform C to Error(message)) -Unsupported: inference from the expected type, variance, inheritance, Java functional interfaces with more than three parameters, Java type-variable varargs (T...), varargs declarations in Sprig, annotations, decorators, macros, reflection-based schemas, block lambdas, tuples, destructuring, string interpolation, Char type, async/await, wildcard match, pipeline, operator overloading, arrays -Use 'sprig help ' for syntax and rules. -``` - -The long `Implemented:` line must contain **`if expressions`**. The old SDK's list doesn't have it. To check just that one item: +It lists the compiler version, `language 0.8-dev`, the minimum JDK, commands, types and implemented features. `0.8-dev` is the **language version**: the language is not frozen yet. It does not mean you lack a published SDK. Use `sprig capabilities --json` for a complete, machine-readable list for editors or coding agents. -```bash -sprig capabilities | grep -o "if expressions" -``` +::: tip What are the two versions for? +`sprig version` identifies the SDK you installed; `sprig capabilities` describes its features. This site follows `main` and may gain new features later. Include both version and capability information when reporting a problem; see [release status](/en/project/release-status). +::: -```text -if expressions -``` +### Build from source (optional) -On Windows PowerShell: +To modify the compiler or try unpublished changes, you need Git, JDK 21+ and Python 3.12+: -```powershell -sprig capabilities | Select-String "if expressions" +```bash +git clone https://github.com/ColinHouse/Sprig.git +cd Sprig +python3 scripts/build.py ``` -If you see `if expressions`, you have the right compiler. If you don't, you have the published SDK; build from source as above. - -One more confirmation: `sprig doctor`, which you'll run below, prints `jdkMinimum: 21` on the right compiler. On the old SDK it is `jdkMinimum: 17`. - -::: tip Coming from another language? -Static typing and compilers may be familiar already. The one counterintuitive thing here: **version strings lie, feature lists don't**. This is how the Sprig toolchain works everywhere. `sprig capabilities --json` and `sprig doctor --json` report machine-readable facts, and the editor extension and AI assistants read them instead of guessing from a version number. -::: +On Windows replace the last line with `py -3 scripts/build.py`. The first build downloads pinned build tools. Use the repository's `bin/sprig` (`bin\sprig.cmd` on Windows), or add its `bin` directory to `PATH`. You can also replace every `sprig ...` command in this book with that launcher's full path. ## 1.4 Editor: VS Code You can write Sprig in any text editor, but a good one saves you work. Use [VS Code](https://code.visualstudio.com/): 1. Install VS Code. -2. Install the Sprig extension. It isn't on the Marketplace yet, so package it from source; see the [extension page](/en/guide/editor). Syntax highlighting, check-on-save and one-click run all use the compiler you just built. If the extension can't find it, set **Sprig: Compiler Path** to `bin/sprig`. +2. Install [Sprig from the Marketplace](https://marketplace.visualstudio.com/items?itemName=ColinHouse.sprig-language), checking that the publisher is **ColinHouse**. It uses the SDK you installed for diagnostics, parameter hints and runs. If it cannot find the compiler, set **Sprig: Compiler Path** to the SDK launcher (`bin/sprig`, or `bin\sprig.cmd` on Windows); see the [extension guide](/en/guide/editor). 3. Save your files with the `.spr` extension, for example `hello.spr`. ### Deliberate mistake: indenting with a tab @@ -180,7 +154,7 @@ The first few lines on this machine are: ```text schemaVersion: 1 -compilerVersion: 0.7.1-beta.1 +compilerVersion: 0.8.0-beta.1 languageVersion: 0.8-dev jdkMinimum: 21 javaVersion: 26.0.1 @@ -196,8 +170,8 @@ Many lines follow, listing `javaHome`, class paths, cache locations and more. Th - The terminal is where you type commands; `cd`, `pwd` and `ls` get you around. - You need JDK 21+; both `java -version` and `javac -version` must produce output. -- This book needs the 0.8 compiler from `main`. The official `v0.7.1-beta.1` SDK is not enough; until 0.8 is released, build from source with `python3 scripts/build.py` and use `bin/sprig`. -- `sprig version` and the first line of `capabilities` cannot tell the versions apart; look for `if expressions` in the `Implemented:` line of `sprig capabilities`. +- Install the published v0.8.0-beta.1 SDK; building from source is optional. +- `sprig version` identifies the SDK release; `sprig capabilities` lists features and the separate language version. - `sprig doctor` is the check-up; `jdkMinimum` should be 21. - Indent with spaces, never tabs. @@ -218,17 +192,17 @@ javac 26.0.1 Your numbers will differ (21, 22, 23, ... are all fine), as long as both major versions are ≥ 21. If `javac` isn't found, go back to 1.2. ::: -2. Run `sprig capabilities | grep -o "if expressions"` (on Windows use `Select-String`) and confirm you see `if expressions`. - Hint: `grep -o` keeps only the matching text; on Windows use `sprig capabilities | Select-String "if expressions"`. +2. Run `sprig version`, then `sprig capabilities`. Find the compiler and language versions. + Hint: the SDK release version and the language version describe different things. ::: details Answer -The right compiler prints exactly: +For the current published SDK: ```text -if expressions +sprig-compiler 0.8.0-beta.1 ``` -No output means you have the old release; build from source as in 1.3. +The capability list reports compiler `0.8.0-beta.1` and language `0.8-dev`. A newer SDK may have a different version; an older SDK should be upgraded as in 1.3. ::: 3. Run `sprig doctor`, find the `jdkMinimum` and `javacAvailable` lines, and say what they should be. diff --git a/website/en/tutorial/ch23-tooling.md b/website/en/tutorial/ch23-tooling.md index ad4acd5d..ab69aa0f 100644 --- a/website/en/tutorial/ch23-tooling.md +++ b/website/en/tutorial/ch23-tooling.md @@ -120,7 +120,7 @@ declarations: ```json { "schemaVersion": 1, - "toolVersion": "sprig-compiler 0.7.1-beta.1", + "toolVersion": "sprig-compiler 0.8.0-beta.1", "command": "check", "exitCode": 1, "environment": {"classpath": []}, @@ -150,7 +150,7 @@ The other everyday command is `sprig capabilities`, which states once and for al ```text $ sprig capabilities -Sprig compiler 0.7.1-beta.1 / language 0.8-dev +Sprig compiler 0.8.0-beta.1 / language 0.8-dev JDK minimum: 21 Commands: help, version, check, build, run, test, codes, explain, capabilities, api, wrap, doctor, init, resolve, add, remove, search, publish, project, deps, upgrade, fmt, lsp Types: Int, Int32, BigInt, Float, Float32, Decimal, Bool, String, Unit @@ -177,7 +177,7 @@ Two more commands inspect the environment: ```text $ sprig doctor schemaVersion: 1 -compilerVersion: 0.7.1-beta.1 +compilerVersion: 0.8.0-beta.1 languageVersion: 0.8-dev jdkMinimum: 21 javaVersion: 26.0.1 diff --git a/website/en/tutorial/index.md b/website/en/tutorial/index.md index 0e92a596..a05428b8 100644 --- a/website/en/tutorial/index.md +++ b/website/en/tutorial/index.md @@ -46,9 +46,9 @@ Each chapter starts with what you will learn and ends with a summary and exercis ## Which compiler version you need -This book follows the 0.8 language, the compiler on the repository's `main` branch. `sprig capabilities` reports it as `language 0.8-dev`. +This book uses the 0.8 language, reported as `language 0.8-dev` by `sprig capabilities`. The SDK release version and the language version describe different things. -The published SDK is v0.7.1-beta.1, which is older than this book: if expressions, one-line classes, contract classes, error classes, function references, type-argument inference and `@std/concurrent` all arrived after v0.7.1-beta.1. Until 0.8 is released, [build from source](/en/tutorial/ch01-tools) and use the repository's `bin/sprig` (`bin\sprig.cmd` on Windows). Chapter 1 walks through the environment, the version check and your first program. +The published [v0.8.0-beta.1 SDK](https://github.com/ColinHouse/Sprig/releases/tag/v0.8.0-beta.1) includes the syntax and standard modules used in this book and requires JDK 21+. Install the SDK directly; you do not need to build the compiler first. Chapter 1 explains [installation and version checks](/en/tutorial/ch01-tools). This site follows `main`; see [release status](/en/project/release-status) for later differences and `sprig capabilities --json` for your installed compiler's capabilities. ## Chapter map diff --git a/website/guide/editor.md b/website/guide/editor.md index 9dc9a268..cb43049a 100644 --- a/website/guide/editor.md +++ b/website/guide/editor.md @@ -9,7 +9,7 @@ - 文件大纲 - 悬停提示 - 自动补全 -- 函数参数提示和语义着色（需要提供这两项能力的新编译器） +- 函数参数提示和语义着色（v0.8.0-beta.1 编译器支持） - 跳转到定义、查找引用和重命名 - 代码片段 - 测试面板 @@ -17,26 +17,33 @@ 类型、签名和报错都来自你装好的 `sprig` 命令，插件自己不做类型检查。如果这个编译器带有[语言服务器](/guide/tooling#语言服务器) `sprig lsp`，插件会自动启动它，上面这些功能都由它提供。 -插件还没有发布到 VS Code 插件市场，也没有放进 SDK 的压缩包，需要自己从源码打包安装。 +插件已上架 [Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=ColinHouse.sprig-language)，扩展标识是 `ColinHouse.sprig-language`。插件不包含 Sprig SDK，需要分别安装。 ## 安装 -在 Sprig 仓库的 `editors/vscode/` 目录里运行： +在 VS Code 扩展面板搜索 **Sprig**，确认发布者是 **ColinHouse**，然后安装；也可以运行： ```sh -npm ci -npm run package +code --install-extension ColinHouse.sprig-language ``` -会生成 `dist/sprig-language-0.3.1.vsix`。在 VS Code 的扩展面板里点 `…` → **Install from VSIX…** 选中它，或者在命令行运行： +### 从源码打包（可选） + +只有开发插件或安装本地修改时才需要打包。在 Sprig 仓库的 `editors/vscode/` 目录运行： ```sh +npm ci +npm run package code --install-extension dist/sprig-language-0.3.1.vsix ``` +也可以在扩展面板里点 `…` → **Install from VSIX…**，选择生成的 VSIX。 + +### 配置编译器 + 装好以后，语法高亮、大纲和代码片段马上就能用，不需要 Java 和编译器。 -其他功能还需要装好 JDK 21+ 和 [Sprig SDK](/guide/getting-started)，然后在设置里把 **Sprig: Compiler Path**（`sprig.compilerPath`）设成 SDK 里的 `bin/sprig`。不设置的话，插件会先在 `PATH` 里找 `sprig`，再沿着上级目录查找源码构建出来的 `bin/sprig`。测试面板需要 v0.5.0-beta.1 或更新的编译器。 +其他功能还需要装好 JDK 21+ 和 [Sprig SDK](/guide/getting-started)，然后在设置里把 **Sprig: Compiler Path**（`sprig.compilerPath`）设成 SDK 里的 `bin/sprig`（Windows 为 `bin\sprig.cmd`）。不设置的话，插件会先在 `PATH` 里找 `sprig`，再沿着上级目录查找源码构建出来的 `bin/sprig`。测试面板需要 v0.5.0-beta.1 或更新的编译器。 语言服务器是 v0.6.0-beta.1 新加的。用 v0.6.0-beta.1 或更新的编译器时，插件会自动用上它；用 v0.5.0-beta.1 时，插件改为每次单独调用编译器命令，区别见下表。想关掉语言服务器，把 `sprig.languageServer.enabled` 设成 `false`。 @@ -45,7 +52,7 @@ code --install-extension dist/sprig-language-0.3.1.vsix | 功能 | 有语言服务器时 | 用 v0.5.0-beta.1 时 | |---|---|---| | 报错 | 边写边报，显示在「问题」面板里。被导入的文件里有错，会标在对应的 `import` 那一行 | 保存时才报 | -| 快速修复 | 错误的改法是一处机械改写时，比如把 `else if` 改成 `elif`、补上漏写的 `@std` 导入，错误旁边的灯泡里就有这处修改，点一下就改好。需要比 v0.7.1-beta.1 新的编译器 | 没有 | +| 快速修复 | 错误的改法是一处机械改写时，比如把 `else if` 改成 `elif`、补上漏写的 `@std` 导入，错误旁边的灯泡里就有这处修改，点一下就改好。已包含在 v0.8.0-beta.1 编译器中 | 没有 | | 悬停提示 | 任何名字都能显示声明和类型，包括局部变量和参数，还有写在声明上方的注释 | 关键字、`Java类.方法`、`模块.函数` 和你写的顶层声明，用的是已保存文件的信息 | | 自动补全 | 输入点号后补全任何值的成员，包括局部变量；其他位置补全作用域里的名字和关键字 | 关键字、本文件的声明和导入的名字；输入 `Java类.`、`模块.`、enum 名加点或顶层变量加点之后，补全它的成员 | | 跳转到定义（F12） | 任何名字，可以跨文件 | import 的路径、`模块.成员` 和本文件的声明 | @@ -58,7 +65,7 @@ code --install-extension dist/sprig-language-0.3.1.vsix 两种情况下，停在关键字上都会显示 `sprig help` 的说明，**Go to Symbol in Workspace** 可以在整个工作区里搜，点错误码可以打开错误码文档。代码片段：输入 `func`、`class`、`variant`、`match`、`ifnn`、`try`、`importj` 等前缀，按 Tab 展开。 -参数提示和语义着色由更新后的编译器提供，插件 0.3.1 随它一起发布，会自动注册这两项功能。嵌套调用和字符串里的逗号不会弄错当前参数；命名构造参数可以按任意顺序填写。Java 没保留参数名时显示 `arg0`、`arg1` 等占位名。Java 重载暂不按实参类型排序，Sprig 泛型显示声明里的类型参数；内置函数和原生字符串、集合方法暂不提供参数签名。调用之外的语法错误仍可能让提示失效。语法或名字解析失败时会清空语义着色，保留词法高亮。 +参数提示和语义着色由 v0.8.0-beta.1 编译器提供，插件 0.3.1 支持这两项能力，会自动注册这两项功能。嵌套调用和字符串里的逗号不会弄错当前参数；命名构造参数可以按任意顺序填写。Java 没保留参数名时显示 `arg0`、`arg1` 等占位名。Java 重载暂不按实参类型排序，Sprig 泛型显示声明里的类型参数；内置函数和原生字符串、集合方法暂不提供参数签名。调用之外的语法错误仍可能让提示失效。语法或名字解析失败时会清空语义着色，保留词法高亮。 ## 命令 diff --git a/website/guide/getting-started.md b/website/guide/getting-started.md index d8143a3c..bccb18ca 100644 --- a/website/guide/getting-started.md +++ b/website/guide/getting-started.md @@ -25,19 +25,19 @@ sprig version 以后想升级，运行 `sprig upgrade --check` 看看有没有新版本，再用 `sprig upgrade` 升级。 -::: tip 装好的是 v0.7.1-beta.1 -安装脚本装的是最新发布的版本，现在是 v0.7.1-beta.1。这个网站按 `main` 分支来写，有些功能（比如 `if` 表达式、契约类、`@std/concurrent`、`sprig build --bundle`）比它新。想用这些功能，就按下面[从源码构建](#windows-和从源码构建)的步骤来；具体差别见[发布状态](/project/release-status)。 +::: tip 当前发布版本：v0.8.0-beta.1 +安装脚本选择最新已发布的版本（包括 Beta）。当前的 v0.8.0-beta.1 已包含教程使用的 `if` 表达式、契约类、函数引用和 `@std/concurrent` 等功能，无需从源码构建。SDK、语言和插件各有独立版本；具体能力可用 `sprig capabilities --json` 查询，见[发布状态](/project/release-status)。 ::: ### 手动下载 -也可以从[发布页](https://github.com/ColinHouse/Sprig/releases/tag/v0.7.1-beta.1)下载 ZIP，自己校验后解压： +也可以从[发布页](https://github.com/ColinHouse/Sprig/releases/tag/v0.8.0-beta.1)下载 ZIP，自己校验后解压： ```bash -curl -LO https://github.com/ColinHouse/Sprig/releases/download/v0.7.1-beta.1/sprig-v0.7.1-beta.1-jdk.zip -curl -LO https://github.com/ColinHouse/Sprig/releases/download/v0.7.1-beta.1/sprig-v0.7.1-beta.1-jdk.zip.sha256 -shasum -a 256 -c sprig-v0.7.1-beta.1-jdk.zip.sha256 -unzip sprig-v0.7.1-beta.1-jdk.zip +curl -LO https://github.com/ColinHouse/Sprig/releases/download/v0.8.0-beta.1/sprig-v0.8.0-beta.1-jdk.zip +curl -LO https://github.com/ColinHouse/Sprig/releases/download/v0.8.0-beta.1/sprig-v0.8.0-beta.1-jdk.zip.sha256 +shasum -a 256 -c sprig-v0.8.0-beta.1-jdk.zip.sha256 +unzip sprig-v0.8.0-beta.1-jdk.zip ``` Linux 上也可以用 `sha256sum -c`。如果校验没通过，请重新下载，不要跳过校验。解压后把目录里的 `bin` 加进 `PATH`。 @@ -71,7 +71,7 @@ sprig run 这些命令几乎都能加 `--json`，输出结构化的结果，方便编辑器、脚本或 AI 编程助手读取。详见[工具与 JSON](/guide/tooling)。 -编辑器方面，有一个 [VS Code 插件](/guide/editor)（目前是本地预览版），支持语法高亮、保存时检查和一键运行。 +编辑器方面，[Sprig VS Code 插件](https://marketplace.visualstudio.com/items?itemName=ColinHouse.sprig-language)已上架 Marketplace，支持语法高亮、边写边检查、参数提示和一键运行。安装和编译器路径配置见[插件说明](/guide/editor)。 ## Windows 和从源码构建 diff --git a/website/guide/tooling.md b/website/guide/tooling.md index cadc0ba5..0bc75c23 100644 --- a/website/guide/tooling.md +++ b/website/guide/tooling.md @@ -2,7 +2,7 @@ Sprig 只有一个命令行程序 `sprig`，所有功能都是它的子命令。它没有常驻后台的进程，连语言服务器也是一个子命令 `sprig lsp`，由编辑器自己启动。VS Code 里的支持见 [VS Code 插件](/guide/editor)。 -这页按 `main` 分支来写。`sprig build --bundle`、`sprig search`、`sprig publish` 和 `run --no-cache` 比已发布的 v0.7.1-beta.1 新，其他命令在 v0.7.1-beta.1 里都有。你装的 SDK 具体支持哪些功能，以 `sprig capabilities --json` 的输出为准。 +这页按 `main` 分支维护。当前发布的 v0.8.0-beta.1 包含这里列出的命令，包括 `sprig build --bundle`、`sprig search`、`sprig publish` 和 `run --no-cache`。安装版本的具体能力以 `sprig capabilities --json` 为准。 ## 命令一览 @@ -75,7 +75,7 @@ Sprig 只有一个命令行程序 `sprig`，所有功能都是它的子命令。 ```json { "schemaVersion": 1, - "toolVersion": "sprig-compiler 0.7.1-beta.1", + "toolVersion": "sprig-compiler 0.8.0-beta.1", "command": "run", "exitCode": 0, "programOutput": "Hello, Ada!\n", @@ -101,7 +101,7 @@ SPR-MATCH-NONEXHAUSTIVE [FLOW] main.spr:6:12: Missing case: Shape.Square ```json { "schemaVersion": 1, - "toolVersion": "sprig-compiler 0.7.1-beta.1", + "toolVersion": "sprig-compiler 0.8.0-beta.1", "command": "check", "exitCode": 1, "environment": {"classpath": []}, @@ -153,7 +153,7 @@ SPR-MATCH-NONEXHAUSTIVE [FLOW] main.spr:6:12: Missing case: Shape.Square `sprig lsp` 通过标准输入输出说 Language Server Protocol（LSP），Neovim、Helix 这类编辑器可以直接用它，[VS Code 插件](/guide/editor)也会自动启动它。它是 v0.6.0-beta.1 新加的。 -它提供边写边报错、悬停提示、跳转到定义、查找引用、大纲、补全、格式化、局部变量和参数的重命名，以及快速修复：错误的改法是一处机械改写时，在编辑器里点一下就能改好。这些都来自和 `sprig check` 同一个编译器，所以编辑器里看到的和命令行永远一致。代码还解析不了的时候，服务器宁可什么都不返回，也不去猜。快速修复比 v0.7.1-beta.1 新。 +它提供边写边报错、悬停提示、跳转到定义、查找引用、大纲、补全、格式化、局部变量和参数的重命名，以及快速修复：错误的改法是一处机械改写时，在编辑器里点一下就能改好。这些都来自和 `sprig check` 同一个编译器，所以编辑器里看到的和命令行永远一致。大多数语义查询需要能解析的源码；参数提示能处理暂时缺少右括号的调用。快速修复、参数提示和语义着色已包含在 v0.8.0-beta.1 中；未完成的调用可以获得参数提示，但其他语法错误仍可能让语义功能失效。 编辑器怎么配置、每项功能的细节，见[语言服务器参考（英文）](/en/reference/tooling/lsp)。 diff --git a/website/index.md b/website/index.md index e83191b2..83acb0e6 100644 --- a/website/index.md +++ b/website/index.md @@ -55,7 +55,7 @@ SPR-MATCH-NONEXHAUSTIVE [FLOW] main.spr:9:12: Missing case: Shape.Triangle ## 现在能用吗？ -Sprig 还在早期。当前发布的版本是实验性的 v0.7.1-beta.1：上面列的事情都已经能做，每一项都有能直接运行的例子。不过它没有继承，泛型没有协变和逆变，也不建议用在生产环境。网站按 `main` 分支来写，契约类、`if` 表达式、函数引用、`@std/concurrent` 这些功能比 v0.7.1-beta.1 新，完整清单见[发布状态](/project/release-status)。限制的完整清单见[已知限制](/en/reference/language/known-limitations)（英文）。 +Sprig 还在早期。当前发布的版本是实验性的 [v0.8.0-beta.1](https://github.com/ColinHouse/Sprig/releases/tag/v0.8.0-beta.1)，需要 JDK 21+；上面列出的功能和教程使用的语法已包含在这个 SDK 里。它没有 Sprig 类继承，泛型没有协变和逆变，也不建议用在生产环境。网站随 `main` 分支维护，后续改动以[发布状态](/project/release-status)和你安装的编译器输出为准。完整限制见[已知限制](/en/reference/language/known-limitations)（英文）。 ## 五分钟跑起来 diff --git a/website/project/release-status.md b/website/project/release-status.md index 589cfa64..9fcc5e4c 100644 --- a/website/project/release-status.md +++ b/website/project/release-status.md @@ -1,69 +1,56 @@ # 发布状态 -当前发布的版本是 [v0.7.1-beta.1](https://github.com/ColinHouse/Sprig/releases/tag/v0.7.1-beta.1)。 +当前发布的 SDK 是 [v0.8.0-beta.1](https://github.com/ColinHouse/Sprig/releases/tag/v0.8.0-beta.1)。 -| | | +| 项目 | 当前状态 | |---|---| -| 编译器 | `0.7.1-beta.1` | -| 语言版本 | `0.8-dev` | -| 运行环境 | 安装脚本和 `main` 上的源码要求 JDK 21 或更新的版本（SDK 不附带 JDK）。已发布的 v0.7.1-beta.1 本身在 JDK 17 上也能运行，但要手动下载它的 ZIP 来安装 | +| SDK / 编译器 | `0.8.0-beta.1` | +| 语言版本 | `0.8-dev`，尚未冻结 | +| 运行环境 | JDK 21+；SDK 不附带 JDK | +| VS Code 插件 | Marketplace 上的 `ColinHouse.sprig-language`，版本 `0.3.1`；需单独安装 SDK | | 许可证 | Apache-2.0 | -| 平台 | 正式支持 Linux 和 macOS；Windows 是实验性预览 | +| 平台 | Linux 和 macOS 为发布支持平台；Windows 是实验性预览 | -这是一个实验性的 Beta 版，适合拿来试用和反馈问题，还不建议迁移生产项目。 +这是实验性 Beta，适合试用和反馈问题，还不建议迁移生产项目。安装发布的 SDK 即可学习当前教程，无需先从源码构建；见[安装说明](/guide/getting-started)和[插件说明](/guide/editor)。 ## 这个版本新增了什么 -v0.7.1-beta.1 修好了一次评测用真实程序和 Java 对照在 v0.7.0-beta.1 里发现的问题，也让调用 Java 更顺手： +以下变化相对于 v0.7.1-beta.1，已包含在 v0.8.0-beta.1 SDK 中： -- `for i in range(n)` 改成计数，不再先建出整个列表，循环多长都只占固定的内存 -- 顶层代码里有好几个热循环时，跑得和同样的 Java 一样快 -- 把可能为 `null` 的值拼进文本会报错，不再打印出 `null` -- `Error` 不管怎么变成文本，显示的都是它的消息，`toString()` 也一样 -- 字符串有了 `a.compareTo(b)`，正好是 Java `Comparator` 要的 -- `Int` 可以直接传给 Java 的 `int` 参数，运行时检查范围；Java 签名里的通配符类型，比如 `List`，按它的上下界来读 -- `sprig api` 会显示写在每个声明上方的注释 -- 帮助和 `sprig capabilities` 说的就是编译器实际的行为，包括 `==` 比较两个类对象时看的是不是同一个对象 +- 语言：`if` 表达式、根据实参推断泛型类型参数、契约类和 `conform`、单行类、具名函数引用、错误类、可变集合的只读视图，以及更完整的条件分支可空性收窄。 +- Java：用 `conform` 扩展 Java 类、读取可空性注解、Java 泛型方法根据实参推断类型参数，以及 `--classpath-file`。 +- 标准库和包：`@std/concurrent` 的结构化 scope 和虚拟线程，以及集合、文本、正则、Web 和 SQLite 的改进。注册表包通过向 `registry/` 提交 PR 发布，并由 CI 验证；目前没有带账号和上传服务的中央包仓库。 +- 工具：`sprig build --bundle`、`run`/`test` 编译缓存、`sprig search` 和 `sprig publish`。 +- 编辑器：快速修复、参数提示、语义着色，以及引用扫描达到上限时的结果不完整提示。重命名仍限于局部变量和参数，没有调试器；其他语法错误仍可能影响语义功能。 +- 最低 JDK 从 17 提升到 21。 -这是一个补丁版本：v0.7.0-beta.1 和 v0.6 里有的功能都还在。还没有中央的包仓库，编译器也还不是用 Sprig 自己写的（没有自举）。你装的 SDK 具体支持什么，以 `sprig capabilities --json` 为准。完整的说明见 [v0.7.1-beta.1 发布说明（英文）](https://github.com/ColinHouse/Sprig/blob/main/docs/releases/v0.7.1-beta.1.md)。 +完整变化和限制见 [v0.8.0-beta.1 发布说明（英文）](https://github.com/ColinHouse/Sprig/blob/main/docs/releases/v0.8.0-beta.1.md)。安装版本的具体功能以 `sprig capabilities --json` 为准。 -## 从 v0.7.0 升级 +## 从 v0.7.1 升级 -运行 `sprig upgrade`，然后在每个项目里运行一次 `sprig resolve`，因为锁文件里记着写它的编译器版本。 +先安装 JDK 21+。Linux/macOS 的托管安装运行 `sprig upgrade`；手动解压的 SDK（包括 Windows）需要下载并校验新 ZIP。升级后在项目中运行 `sprig resolve`，更新记录编译器身份的锁文件。 -有两类 v0.7.0 能通过的写法现在会报错，因为它们可能打印出 `null`，或者运行时才出错。报错里会告诉你怎么改： +这次 MINOR 升级包含需要修改代码的变化： -- 把可能为 `null` 的值拼进 `String`：先检查，或者用 `@std/nulls.spr` 里的 `or_else` 给个默认值。Java 方法返回的值也算可能为 `null`，`toString()` 的结果不算 -- 把 Java 异常的 `message` 当 `String` 用：Java 可能让它是 `null`，所以它现在是 `String?`。直接拼接异常本身，或者先检查消息 +- 数字转换统一写法：`n.toFloat()`、`x.toInt()`、`Decimal.fromInt(n)` 和 `Int.parse(text)` 分别改成 `n.toFloatExact()`、`x.toIntExact()`、`n.toDecimal()` 和 `text.toInt()`。 +- `elif` 和 `else` 的类型收窄更完整；在已经确定非空的分支中，一些旧写法会被拒绝。 +- 部分库函数现在声明 `throws Error`；调用代码需要按其签名处理错误。 +- 其他集合、数值及互操作变化见发布说明的[升级部分（英文）](https://github.com/ColinHouse/Sprig/blob/main/docs/releases/v0.8.0-beta.1.md#upgrade-from-v071-beta1)。 -还有一处写法照样能编译，但打印出来的不一样了：`Error` 的 `toString()` 现在返回它的消息，不再带 `sprig.runtime.SprigError: ` 前缀。 +## 网站、源码和发布版 -从 v0.6 升级的话，还要看一下 [v0.7.0-beta.1 发布说明（英文）](https://github.com/ColinHouse/Sprig/blob/main/docs/releases/v0.7.0-beta.1.md)里的升级部分。 - -## 发布之后的改动 - -网站按仓库 `main` 分支上的源码来写，比 v0.7.1-beta.1 新。不是每一页都会注明哪些内容是新的，所以请以这份清单为准： - -- 语言：`if` 表达式；`elif` 和 `else` 知道前面的条件为假；泛型调用根据你传的参数算出类型参数；契约类（`conform C to Contract`）；单行类 `class Pair(first: Int, second: Int)`；不加括号就是函数值的具名函数、模块函数和方法；错误类（`conform E to Error(message)`）；`MutableList` 可以直接当 `List` 用；数字类型上的 `compareTo`、`String.lastIndexOf`，以及 `xs == []` 这样直接和字面量比较。 -- Java：用 `conform C to J(字段) as 名字` 继承 Java 类；读取可空性注解；Java 泛型方法按实参推断类型参数；`--classpath-file` 选项。 -- 库：`@std/concurrent` 的结构化 scope 和虚拟线程；`@std/regex` 的 `find_groups`，`@std/lists` 的 `max`、`min`、`max_by`、`min_by`，`@std/text` 的 `escape_html`；sprig-web 的 `app.put`、`app.patch` 和 `app.run_on`；sprig-sqlite 的每个 SQL 字符串只能有一条语句，迁移在运行前先整体检查。 -- 工具：语言服务器的快速修复；`sprig build --bundle`；`run` 和 `test` 的编译缓存（`run --no-cache`）；`sprig search`、`sprig publish`，以及经 pull request 发布到 `registry/` 的包；`@std` 函数里的运行时错误指向你调用它的那一行。 -- 最低 JDK 21。 - -有几处改动会让 v0.7.1-beta.1 能通过的代码报错。最先碰到的会是数字转换：每种只留一种写法。`n.toFloat()`、`x.toInt()`、`Decimal.fromInt(n)` 和 `Int.parse(text)` 都没有了，分别改成 `n.toFloatExact()`、`x.toIntExact()`、`n.toDecimal()` 和 `text.toInt()`。其余几处（`elif` 和 `else` 里更窄的类型、改为声明 `throws Error` 的库函数、经泛型代码传入的 Float map 键）和完整的升级说明，见下一个版本的说明草稿 [v0.8.0-beta.1（英文）](https://github.com/ColinHouse/Sprig/blob/main/docs/releases/v0.8.0-beta.1.md)。 +网站随 `main` 分支维护。当前教程使用的功能已经发布；后续源码可能先于下次 SDK 发布增加改动。`sprig version` 确认 SDK/编译器版本，`sprig capabilities --json` 确认语言版本和实际功能。`languageVersion: 0.8-dev` 不代表 SDK 没有发布。 ## 怎么验证的 -这个版本的 SDK 压缩包在 Linux 和 macOS 上，分别用 JDK 17 和 26 做过验收，也核对了校验值和发布流程。具体的源码版本、压缩包的 SHA-256、运行的命令和 CI 链接，见[发布验证记录（英文）](https://github.com/ColinHouse/Sprig/blob/main/docs/releases/validation.md)。 - -从源码构建、没有打 tag 的版本，版本信息会标成 development；和某个干净的 tag 完全一致的构建，会标成 prerelease。 +发布流程已通过 Linux/macOS × JDK 21/26 的下载 SDK 验证。另在 macOS/JDK 26.0.1 上重新下载官方 ZIP、核对 SHA-256，并跑通 `init → resolve → run`。源码提交、校验值、CI 链接及验证范围见[发布验证记录（英文）](https://github.com/ColinHouse/Sprig/blob/main/docs/releases/validation.md)。本地冒烟检查不代表 Windows 或全部编辑器交互都经过人工验证。 ## 还在计划中 - 能像值一样索引的 Java 数组，以及完整的 Java 泛型 - 用 Sprig 自己来写编译器（自举） -另外，类型检查保证不了数值计算是否稳定。 +类型检查也不能保证数值稳定性或应用逻辑正确。 ## 更早的版本 diff --git a/website/tutorial/ch01-tools.md b/website/tutorial/ch01-tools.md index 231cd080..67154e99 100644 --- a/website/tutorial/ch01-tools.md +++ b/website/tutorial/ch01-tools.md @@ -65,96 +65,70 @@ javac 26.0.1 ## 1.3 装 Sprig，并且确认版本 -这一节最重要：**这本书跟着 Sprig 源码 `main` 分支上的 0.8 语言写**，书里的例子用到了 0.8 才有的一些语法。官方发布页和安装脚本现在给你的是 `v0.7.1-beta.1`，它没有这些语法，后面几章的程序在它上面跑不起来。0.8 正式发布之前，请从源码构建。 +本书使用的语法和标准模块已包含在 [v0.8.0-beta.1 SDK](https://github.com/ColinHouse/Sprig/releases/tag/v0.8.0-beta.1) 中。安装发布的 SDK 就能开始，不需要先构建编译器。 -### 从源码构建（Linux、macOS、Windows 都可以） +### Linux / macOS：安装 SDK -需要 Git、JDK 21+ 和 Python 3.12+。在终端里： +装好 JDK 21+ 后，在终端运行： ```bash -git clone https://github.com/ColinHouse/Sprig.git -cd Sprig -python3 scripts/build.py +curl -fsSL https://raw.githubusercontent.com/ColinHouse/Sprig/main/scripts/install-sprig.sh | sh +export PATH="$HOME/.local/bin:$PATH" +sprig version ``` -Windows 上把最后一条换成： +安装脚本选择最新已发布的版本（包括 Beta），核对 ZIP 的 SHA-256，并将 SDK 安装到 `~/.sprig/versions/`，启动器放到 `~/.local/bin/sprig`。它不修改终端配置；上面的 `export` 只在当前终端生效。想让新终端也能找到 `sprig`，可以把这行 `export` 加到 zsh 的 `~/.zshrc` 或 bash 的 `~/.bashrc`。 -```powershell -py -3 scripts/build.py -``` +也可以手动下载、校验和解压 ZIP，详见[安装说明](/guide/getting-started)。使用 SDK 不需要 Python 或 Git；第一次解析 Maven 依赖仍可能需要联网。 -第一次构建会下载固定版本的构建工具，需要联网，也要等几分钟。构建完成后，仓库里的 `bin/sprig`（Windows 是 `bin\sprig.cmd`）就是编译器。 +### Windows：解压 SDK -### 让 `sprig` 可以直接输入（可选） +Windows 目前是实验性预览，没有上述安装脚本。下载发布页的 ZIP 和同名 `.sha256` 文件，核对校验值后解压，使用其中的 `bin\sprig.cmd`。把解压目录的 `bin` 加到 `Path` 后，本书的 `sprig ...` 命令就能直接运行。详细步骤见 [Windows 安装说明（英文）](/en/reference/projects/install#windows)。 -本书后面的命令都写作 `sprig`。如果不想每次都写完整路径，可以把仓库的 `bin` 目录加进 `PATH`。macOS 默认终端是 zsh，在终端里运行： - -```bash -echo 'export PATH="/把这里换成仓库的完整路径/Sprig/bin:$PATH"' >> ~/.zshrc -``` - -然后重开终端。用 bash 的话改成 `~/.bashrc`；Linux 同理。Windows 可以在“设置”里搜索“环境变量”，把 `...\Sprig\bin` 加到 Path 里。 - -不配置也行：书里每条 `sprig ...` 都可以换成 `/完整路径/Sprig/bin/sprig ...`，Windows 上换成 `...\Sprig\bin\sprig.cmd ...`。 - -### 确认版本：`sprig version` 不够用 - -先看版本命令的输出： +### 确认版本 ```bash sprig version ``` +当前 SDK 的输出是： + ```text -sprig-compiler 0.7.1-beta.1 +sprig-compiler 0.8.0-beta.1 ``` -**这条信息区分不了新旧编译器**：官方发布的旧 SDK 也自称 `0.7.1-beta.1`，`main` 上构建出来的 0.8 编译器同样如此。`sprig capabilities` 的第一行也一样，两边都写“language 0.8-dev”。所以不要靠版本号，靠功能清单： +这表示 **SDK/编译器发布版本**。如果显示旧版本，在托管安装中运行 `sprig upgrade`；手动解压的 SDK 则重新下载。若仍显示旧版本，检查 `PATH` 和编辑器的 **Sprig: Compiler Path** 是否指向另一份编译器。 + +再运行： ```bash sprig capabilities ``` -```text -Sprig compiler 0.7.1-beta.1 / language 0.8-dev -JDK minimum: 21 -Commands: help, version, check, build, run, test, codes, explain, capabilities, api, wrap, doctor, init, resolve, add, remove, search, publish, project, deps, upgrade, fmt, lsp -Types: Int, Int32, BigInt, Float, Float32, Decimal, Bool, String, Unit -Implemented: typed functions, one-line class declarations, contract classes (methods without bodies) with conform, function references (named, module and method functions, and print, as values), source function types fn(A) -> R, function types that throw Error, rethrows functions, classes, enums, variants, match statements, match expressions, if expressions, explicit declaration reexports, nullable types, typed catch, local modules, lambdas up to three parameters, generic blocks with one or more type parameters, explicit Type[Arg] generic uses, type arguments inferred from call arguments, Equatable capability, Comparable capability, Sprig function values passed as Java functional interfaces with up to three parameters, Java varargs calls, declared foreign JVM conformance (conform Class to ImportedInterface), Java class conformance with a parent view, error classes (conform C to Error(message)) -Unsupported: inference from the expected type, variance, inheritance, Java functional interfaces with more than three parameters, Java type-variable varargs (T...), varargs declarations in Sprig, annotations, decorators, macros, reflection-based schemas, block lambdas, tuples, destructuring, string interpolation, Char type, async/await, wildcard match, pipeline, operator overloading, arrays -Use 'sprig help ' for syntax and rules. -``` - -`Implemented:` 这一行很长，里面必须出现 **`if expressions`**。旧 SDK 的清单里没有这一项。可以只筛选这一项来检查： +它会列出编译器版本、`language 0.8-dev`、最低 JDK、命令、类型和已实现功能。`0.8-dev` 是**语言版本**，表示语言尚未冻结；它不表示你没有安装发布的 SDK。需要完整、可供编辑器或 AI 助手读取的清单时，用 `sprig capabilities --json`。 -```bash -sprig capabilities | grep -o "if expressions" -``` +::: tip 两种版本各有什么用？ +`sprig version` 帮你确认安装的是哪一版 SDK；`sprig capabilities` 帮你确认它有哪些功能。网站随 `main` 分支维护，后续可能增加功能，因此排查问题时应同时提供版本和功能信息，见[发布状态](/project/release-status)。 +::: -```text -if expressions -``` +### 从源码构建（可选） -Windows PowerShell 上： +想修改编译器或试用尚未发布的改动时，需要 Git、JDK 21+ 和 Python 3.12+： -```powershell -sprig capabilities | Select-String "if expressions" +```bash +git clone https://github.com/ColinHouse/Sprig.git +cd Sprig +python3 scripts/build.py ``` -有 `if expressions` 输出，编译器就对。没有输出，说明你手里的是旧发布版，回到上面“从源码构建”。 - -还有一个佐证：等会儿要运行的 `sprig doctor`，在正确的编译器上会打印 `jdkMinimum: 21`；旧发布版是 `jdkMinimum: 17`。 - -::: tip 学过其他语言？ -静态类型语言、编译器等概念你可能都熟。这一章唯一反直觉的点是：**版本号不可信，功能清单才可信**。这也是 Sprig 工具链的一贯风格——`sprig capabilities --json`、`sprig doctor --json` 给的是机器可读的当前事实，编辑器插件和 AI 助手都读它们，不猜版本。 -::: +Windows 把最后一条换成 `py -3 scripts/build.py`。第一次构建会下载固定版本的构建工具。构建完成后使用仓库里的 `bin/sprig`（Windows 是 `bin\sprig.cmd`），或将仓库的 `bin` 加到 `PATH`。本书的 `sprig ...` 也可以直接替换为该启动器的完整路径。 ## 1.4 编辑器：VS Code 虽然用记事本也能写，但编辑器能帮你省很多事。推荐 [VS Code](https://code.visualstudio.com/)： 1. 安装 VS Code。 -2. 安装 Sprig 插件。插件目前没有发布到插件市场，需要从源码打包，步骤见[插件页面](/guide/editor)。装好以后，语法高亮、保存时检查、一键运行这些功能都会用上你刚构建的编译器。如果插件找不到编译器，在设置里把 **Sprig: Compiler Path** 指向 `bin/sprig`。 +2. 安装 [Marketplace 上的 Sprig 插件](https://marketplace.visualstudio.com/items?itemName=ColinHouse.sprig-language)，确认发布者是 **ColinHouse**。插件使用已安装的 SDK 提供报错、参数提示和运行功能。如果找不到编译器，将 **Sprig: Compiler Path** 指向 SDK 启动器（`bin/sprig`，Windows 为 `bin\sprig.cmd`），详见[插件说明](/guide/editor)。 3. 把代码文件保存成 `.spr` 后缀，例如 `hello.spr`。 ### 故意写错：用 Tab 缩进 @@ -180,7 +154,7 @@ sprig doctor ```text schemaVersion: 1 -compilerVersion: 0.7.1-beta.1 +compilerVersion: 0.8.0-beta.1 languageVersion: 0.8-dev jdkMinimum: 21 javaVersion: 26.0.1 @@ -196,8 +170,8 @@ javaVersion: 26.0.1 - 终端是输入命令的地方；`cd`、`pwd`、`ls` 是三个最常用的导航命令。 - 需要 JDK 21+，`java -version` 和 `javac -version` 都要有输出。 -- 这本书需要 `main` 上的 0.8 编译器；官方 SDK 的 `v0.7.1-beta.1` 不够，0.8 发布前从源码构建：`python3 scripts/build.py`，然后使用 `bin/sprig`。 -- `sprig version` 和 `capabilities` 的第一行区分不了新旧版本；用 `sprig capabilities` 的 `Implemented:` 行里有没有 `if expressions` 来判断。 +- 安装已发布的 v0.8.0-beta.1 SDK 即可；从源码构建是可选步骤。 +- `sprig version` 确认 SDK 发布版本；`sprig capabilities` 列出功能和独立的语言版本。 - `sprig doctor` 做环境体检，`jdkMinimum` 应为 21。 - 缩进只用空格，不用 Tab。 @@ -217,16 +191,16 @@ javaVersion: 26.0.1 你的数字可能不同（21、22、23……都行），只要两个大版本都 ≥ 21。如果 `javac` 找不到，回到 1.2。 ::: -2. 运行 `sprig capabilities | grep -o "if expressions"`（Windows 用 `Select-String`），确认屏幕上有 `if expressions`。 - 提示：`grep -o` 只留下匹配到的那一小段文字；Windows 上换成 `sprig capabilities | Select-String "if expressions"`。 +2. 运行 `sprig version`，再运行 `sprig capabilities`，找出编译器版本和语言版本。 + 提示：SDK 发布版本和语言版本描述的是两件事。 ::: details 参考答案 - 正确编译器的输出就是： + 当前发布的 SDK 输出： ```text - if expressions + sprig-compiler 0.8.0-beta.1 ``` - 没有输出说明编译器是旧发布版，回到 1.3 从源码构建。 + 功能清单显示编译器 `0.8.0-beta.1`、语言 `0.8-dev`。新 SDK 的数字可能不同；若版本较旧，按 1.3 升级。 ::: 3. 运行 `sprig doctor`，找出 `jdkMinimum` 和 `javacAvailable` 两行，说出它们应该是什么。 diff --git a/website/tutorial/ch23-tooling.md b/website/tutorial/ch23-tooling.md index 49e985ab..f4ff29b7 100644 --- a/website/tutorial/ch23-tooling.md +++ b/website/tutorial/ch23-tooling.md @@ -120,7 +120,7 @@ declarations: ```json { "schemaVersion": 1, - "toolVersion": "sprig-compiler 0.7.1-beta.1", + "toolVersion": "sprig-compiler 0.8.0-beta.1", "command": "check", "exitCode": 1, "environment": {"classpath": []}, @@ -150,7 +150,7 @@ declarations: ```text $ sprig capabilities -Sprig compiler 0.7.1-beta.1 / language 0.8-dev +Sprig compiler 0.8.0-beta.1 / language 0.8-dev JDK minimum: 21 Commands: help, version, check, build, run, test, codes, explain, capabilities, api, wrap, doctor, init, resolve, add, remove, search, publish, project, deps, upgrade, fmt, lsp Types: Int, Int32, BigInt, Float, Float32, Decimal, Bool, String, Unit @@ -177,7 +177,7 @@ Use 'sprig help ' for syntax and rules. ```text $ sprig doctor schemaVersion: 1 -compilerVersion: 0.7.1-beta.1 +compilerVersion: 0.8.0-beta.1 languageVersion: 0.8-dev jdkMinimum: 21 javaVersion: 26.0.1 diff --git a/website/tutorial/index.md b/website/tutorial/index.md index 65e31363..033409f2 100644 --- a/website/tutorial/index.md +++ b/website/tutorial/index.md @@ -46,9 +46,9 @@ done ## 需要哪个版本的编译器 -这本书跟的是 0.8 语言，也就是仓库 main 分支上的编译器。`sprig capabilities` 会把它写成 `language 0.8-dev`。 +这本书使用 0.8 语言，编译器在 `sprig capabilities` 中将它写成 `language 0.8-dev`。SDK 的发布版本与语言版本是两回事。 -已经发布的 SDK 是 v0.7.1-beta.1，比这本书旧：书里用到的 if 表达式、单行类、契约类、错误类、函数引用、类型参数推断和 `@std/concurrent` 都是 v0.7.1-beta.1 之后才加入的。在 0.8 正式发布之前，请先[从源码构建](/tutorial/ch01-tools)，用仓库里的 `bin/sprig`（Windows 上是 `bin\sprig.cmd`）。第 1 章会把环境、版本检查和第一个程序一步步讲完。 +当前已发布的 [v0.8.0-beta.1 SDK](https://github.com/ColinHouse/Sprig/releases/tag/v0.8.0-beta.1)包含本书使用的语法和标准模块，需要 JDK 21+。直接安装 SDK 即可开始，不需要先构建编译器。第 1 章会一步步说明[安装和版本检查](/tutorial/ch01-tools)。网站随 `main` 分支维护；后续版本差异见[发布状态](/project/release-status)，实际功能以 `sprig capabilities --json` 为准。 ## 章节地图