From 8f3462669e8d536c841d3ce07bfed5432cb379bc Mon Sep 17 00:00:00 2001 From: Li Jin Date: Tue, 24 Feb 2026 17:03:14 +0800 Subject: Updated README.md and CHANGELOG.md. [skip CI] --- CHANGELOG.md | 299 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 85 +++++++++-------- 2 files changed, 346 insertions(+), 38 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index d22e644..ba91bbb 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,305 @@ The implementation for the original Moonscript language 0.5.0 can be found in the `0.5.0` branch of Yuescript. The Moonscript with fixes and new features is in the main branch of Yuescript. Here are the changelogs for each Yuescript version. +## v0.33.x + +### Added Features + +* Expanded documentation deliverables with an all-in-one documentation output. +* Improved `break` feature set by supporting multiple break values (extends the `break with value` work introduced in `v0.28.x`). +* Further improved reserved-comment preservation behavior for table/class blocks (parser, AST and code generation), with dedicated test coverage. + +### Fixed Issues + +* Fixed formatter issues and improved formatting stability. +* Fixed comma placement/insertion issues when line-number comments are enabled (including class-member cases, issue #240). +* Fixed more comment-preserving code paths and issue #245. +* Improved documentation site rendering/highlighting and updated documentation content/assets. + +## v0.32.x + +### Added Features + +* Added `;` as a statement separator. + ```moonscript + a = 1; b = 2; result = a + b + ``` +* Migrated the documentation site to VitePress and added/expanded localized docs (including German and Portuguese-Brazil). +* Added substantial compiler test coverage (including large regression/spec batches). + +### Fixed Issues + +* Fixed `import global` related issues after the `v0.31.x` syntax addition. +* Fixed global-variable lint behavior. +* Improved cross-platform build support (LuaJIT, MSVC/Windows, CMake, rockspec updates). +* Added Lua 5.5 support in CMake configuration and fixed CI/build workflow issues. +* Fixed issue #227 and multiple documentation/site regressions. + +## v0.31.x + +### Added Features + +* Added const attributes. + ```moonscript + const a = 123 + const {:x, :y} = point + ``` +* Added `import global` syntax. + ```moonscript + import global + print "hello" + math.random 10 + ``` +* These are the primary language-level additions in `v0.31.x` (with follow-up fixes landing in `v0.32.x`). + +### Fixed Issues + +* Fixed global import ordering. +* Fixed a crash issue in `v0.31.1`. +* Updated Windows workflow/build-related integration. + +## v0.30.x + +### Added Features + +* Added named vararg support. + ```moonscript + f = (...t) -> + for i = 1, t.n + print t[i] + ``` +* Improved syntax error messages with more contextual details (not syntax-changing, but a meaningful compiler UX improvement). + +### Fixed Issues + +* Fixed empty-line-as-block parsing issue. +* Fixed formatter crash and other formatting-related issues. +* Refactored `FnArgsDef` rules and fixed issue #224. +* Updated reserved-comments behavior/functionality. + +## v0.29.x + +### Added Features + +* Introduced/iterated new syntax around `try` flow, including `try!` / `try?` related changes. + ```moonscript + a, b, c = try? func! + a = (try? func!) ?? "default" + + f try? + print 123 + func! + catch e + print e + e + ``` +* Added more reversed-index support for slice expressions and later fixed reversed-index edge cases. + ```moonscript + tab = [1, 2, 3, 4, 5] + print tab[#], tab[#-1] + ``` +* Added function argument destructuring. + ```moonscript + f = ({:x, :y}) -> x + y + print f x: 1, y: 2 + ``` +* Added YAML multiline string support and macro argument checking. + ```moonscript + config = | + database: + host: localhost + port: 5432 + ``` + +### Fixed Issues + +* Fixed a crash in `yue.to_ast()` and additional reference/crash issues. +* Stopped linting explicitly defined global variables. +* Fixed issue #222 and #223. +* Improved platform/build compatibility: Windows x64, Lua 5.1, Termux, WASM/build pipeline issues. +* Renamed builtin JSON library to `cojson`, included a minimal JSON lib in the compiler tool, and removed `codecvt` usage for C++26 compatibility. + +## v0.28.x + +### Added Features + +* Allowed backcall without parentheses. + ```moonscript + results = do + data <- readAsync "data.txt" + process data + ``` +* Added global `const` declaration support, including declaration without initializer. + ```moonscript + import global + global const Flag = 1 + global const math, table + ``` +* Added `break with value` syntax. + ```moonscript + x, y = for i = 1, 10 + if i > 5 + break i, i * 2 + ``` +* Added `-` for implicit object. + ```moonscript + items = + - "a" + - "b" + - "c" + ``` + +### Fixed Issues + +* Added/expanded related tests/docs and table-matching support around the new syntax behaviors. + +## v0.27.x + +### Added Features + +* Adjusted macro behavior by aligning Lua inserter macro behavior with common Yue macro behavior (semantic behavior alignment rather than new syntax). + +### Fixed Issues + +* Fixed issues #194, #195, #198, #201, #204, #206 and #209. +* Updated `efsw` and fixed build-related issues. +* Added/updated tests and documentation examples. + +## v0.26.x + +### Added Features + +* Added WASM distribution support for ESM/CommonJS modules and TypeScript integration (#176). + +### Fixed Issues + +* Fixed WASM build issues and updated WASM build pipeline. +* Fixed issues #174, #175, #177, #178, #183, #185 and #188. +* Fixed MoonScript issue #459. +* Fixed build flags and related release/build issues; refreshed specs/docs/readme. + +## v0.25.x + +### Added Features + +* This series mainly improves semantic correctness and code generation consistency. + +### Fixed Issues + +* Fixed multi-value assignment evaluation order (including more edge cases in `v0.25.1`). +* Disallowed some semantically incorrect syntax to improve code consistency. +* Removed redundant/useless `do` blocks in generated code (`with` and related cases). +* Fixed indentation/missed-indent issue and a few additional regressions. + +## v0.24.x + +### Added Features + +* Added reusable macro environment support. +* Added builtin macros `$to_ast()` and `$is_ast()`. +* Added `yue.is_ast()`. + ```moonscript + import "yue" + formated = yue.format code, 0, true + ``` + +### Fixed Issues + +* Fixed macro function line-number handling. +* Fixed Lua 5.1 build. +* Fixed Lua stack size insufficiency issue. + +## v0.23.x + +### Added Features + +* Added macros-generating-macros feature (`v0.23.9`), expanding macro metaprogramming capability. + ```moonscript + macro Enum = (...) -> + items = {...} + itemSet = {item, true for item in *items} + (item) -> + error "got \"#{item}\", expecting one of #{table.concat items, ', '}" unless itemSet[item] + "\"#{item}\"" + + macro BodyType = $Enum( + Static + Dynamic + Kinematic + ) + + print "Valid enum type:", $BodyType Static + ``` +* Most other `v0.23.x` changes focus on try-catch/code-generation correctness rather than new syntax forms. +* Added more tests/spec cases and documentation updates (including object literal docs in README, #165). + +### Fixed Issues + +* Fixed multiple try-catch syntax ambiguity/corner cases and removed redundant generated `do` blocks. +* Fixed spread expression list issue in up-value functions. +* Prevented extra anonymous function generation from `const`/`close` declarations. +* Fixed nil-coalescing/anonymous-function movement issue and anonymous-function argument ordering. +* Fixed a for-each key variable const-marking issue and traceback rewrite/codegen checks. + +## v0.22.x + +### Added Features + +* Added default return declaration for function literals. + ```moonscript + findValue = (items): "not found" -> + for item in *items + if item.name == "target" + return item.name + ``` +* Added option to stop implicit returns on the root (#164). +* `v0.22.x` also adjusts `for`-loop const behavior to align with Lua 5.5 changes, then refines the rule in `v0.22.1` (only index/key variable is const). + +### Fixed Issues + +* Fixed undeclared specifier in `yue_compiler.cpp` (#163). +* Removed an unnecessary const declaration. +* Corrected/refined `for`-loop const default behavior introduced in `v0.22.0`. + +## v0.21.x + +### Added Features + +* Changed the if-assignment syntax to prevent error-prone cases (syntax/grammar behavior change). + ```moonscript + if user := obj\find_user "valid" + print user.name + elseif other := obj\find_user "fallback" + print other.name + ``` +* Added `yue.format()` and fixed `yue` AST-to-code conversion related functionality. + ```moonscript + import "yue" + formated = yue.format code, 0, true + ``` + +### Fixed Issues + +* Fixed issues #157 and #158 (including a web compiler issue). +* Fixed invalid formatting/formation cases and in-expression formatting issues. +* Fixed more invalid in-expression use cases. +* Fixed const list destructuring, empty-check/empty-block-at-EOF cases, and crash/format edge cases. +* Fixed `luaminify` related issue and updated Lua 5.4 integration/tooling. + +## v0.20.x (after v0.20.2) + +### Added Features + +* This interval mainly contains follow-up fixes for newly introduced `v0.20.2` features (chaining conditions, list/switch matching, import handling) plus release pipeline improvements. + +### Fixed Issues + +* Fixed table-matching syntax in `switch` statements with list tables. +* Fixed a missing condition-chaining case. +* Fixed a crash case for `import` statements. +* Made function-call argument behavior consistent with table-list behavior. +* Improved release/build pipeline setup (CI workflows, LuaRocks upload, docs code checks, test workflow setup). + ## v0.20.2 ### Added Features diff --git a/README.md b/README.md index 73fadf7..caff885 100644 --- a/README.md +++ b/README.md @@ -1,55 +1,58 @@ # YueScript -logo +YueScript logo [![IppClub](https://img.shields.io/badge/IppClub-Certified-11A7E2?logo=data%3Aimage%2Fsvg%2Bxml%3Bcharset%3Dutf-8%3Bbase64%2CPHN2ZyB2aWV3Qm94PSIwIDAgMjg4IDI3NCIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIiB4bWw6c3BhY2U9InByZXNlcnZlIiBzdHlsZT0iZmlsbC1ydWxlOmV2ZW5vZGQ7Y2xpcC1ydWxlOmV2ZW5vZGQ7c3Ryb2tlLWxpbmVqb2luOnJvdW5kO3N0cm9rZS1taXRlcmxpbWl0OjIiPjxwYXRoIGQ9Im0xNDYgMzEgNzIgNTVWMzFoLTcyWiIgc3R5bGU9ImZpbGw6I2Y2YTgwNjtmaWxsLXJ1bGU6bm9uemVybyIvPjxwYXRoIGQ9Im0xNjkgODYtMjMtNTUgNzIgNTVoLTQ5WiIgc3R5bGU9ImZpbGw6I2VmN2EwMDtmaWxsLXJ1bGU6bm9uemVybyIvPjxwYXRoIGQ9Ik0yNiAzMXY1NWg4MEw4MSAzMUgyNloiIHN0eWxlPSJmaWxsOiMwN2ExN2M7ZmlsbC1ydWxlOm5vbnplcm8iLz48cGF0aCBkPSJNMTA4IDkydjExMmwzMS00OC0zMS02NFoiIHN0eWxlPSJmaWxsOiNkZTAwNWQ7ZmlsbC1ydWxlOm5vbnplcm8iLz48cGF0aCBkPSJNMCAyNzR2LTUyaDk3bC0zMyA1MkgwWiIgc3R5bGU9ImZpbGw6I2Y2YTgwNjtmaWxsLXJ1bGU6bm9uemVybyIvPjxwYXRoIGQ9Im03NyAyNzQgNjctMTA3djEwN0g3N1oiIHN0eWxlPSJmaWxsOiNkZjI0MzM7ZmlsbC1ydWxlOm5vbnplcm8iLz48cGF0aCBkPSJNMTUyIDI3NGgyOWwtMjktNTN2NTNaIiBzdHlsZT0iZmlsbDojMzM0ODVkO2ZpbGwtcnVsZTpub256ZXJvIi8%2BPHBhdGggZD0iTTE5MSAyNzRoNzl2LTUySDE2N2wyNCA1MloiIHN0eWxlPSJmaWxsOiM0ZTI3NWE7ZmlsbC1ydWxlOm5vbnplcm8iLz48cGF0aCBkPSJNMjg4IDEwMGgtMTdWODVoLTEzdjE1aC0xN3YxM2gxN3YxNmgxM3YtMTZoMTd2LTEzWiIgc3R5bGU9ImZpbGw6I2M1MTgxZjtmaWxsLXJ1bGU6bm9uemVybyIvPjxwYXRoIGQ9Im0yNiA4NiA1Ni01NUgyNnY1NVoiIHN0eWxlPSJmaWxsOiMzMzQ4NWQ7ZmlsbC1ydWxlOm5vbnplcm8iLz48cGF0aCBkPSJNOTMgMzFoNDJsLTMwIDI5LTEyLTI5WiIgc3R5bGU9ImZpbGw6IzExYTdlMjtmaWxsLXJ1bGU6bm9uemVybyIvPjxwYXRoIGQ9Ik0xNTggMTc2Vjg2bC0zNCAxNCAzNCA3NloiIHN0eWxlPSJmaWxsOiMwMDU5OGU7ZmlsbC1ydWxlOm5vbnplcm8iLz48cGF0aCBkPSJtMTA2IDU5IDQxLTEtMTItMjgtMjkgMjlaIiBzdHlsZT0iZmlsbDojMDU3Y2I3O2ZpbGwtcnVsZTpub256ZXJvIi8%2BPHBhdGggZD0ibTEyNCAxMDAgMjItNDEgMTIgMjctMzQgMTRaIiBzdHlsZT0iZmlsbDojNGUyNzVhO2ZpbGwtcnVsZTpub256ZXJvIi8%2BPHBhdGggZD0ibTEwNiA2MCA0MS0xLTIzIDQxLTE4LTQwWiIgc3R5bGU9ImZpbGw6IzdiMTI4NTtmaWxsLXJ1bGU6bm9uemVybyIvPjxwYXRoIGQ9Im0xMDggMjA0IDMxLTQ4aC0zMXY0OFoiIHN0eWxlPSJmaWxsOiNiYTAwNzc7ZmlsbC1ydWxlOm5vbnplcm8iLz48cGF0aCBkPSJtNjUgMjc0IDMzLTUySDBsNjUgNTJaIiBzdHlsZT0iZmlsbDojZWY3YTAwO2ZpbGwtcnVsZTpub256ZXJvIi8%2BPHBhdGggZD0iTTc3IDI3NGg2N2wtNDAtNDUtMjcgNDVaIiBzdHlsZT0iZmlsbDojYTgxZTI0O2ZpbGwtcnVsZTpub256ZXJvIi8%2BPHBhdGggZD0iTTE2NyAyMjJoNThsLTM0IDUyLTI0LTUyWiIgc3R5bGU9ImZpbGw6IzExYTdlMjtmaWxsLXJ1bGU6bm9uemVybyIvPjxwYXRoIGQ9Im0yNzAgMjc0LTQ0LTUyLTM1IDUyaDc5WiIgc3R5bGU9ImZpbGw6IzA1N2NiNztmaWxsLXJ1bGU6bm9uemVybyIvPjxwYXRoIGQ9Ik0yNzUgNTVoLTU3VjBoMjV2MzFoMzJ2MjRaIiBzdHlsZT0iZmlsbDojZGUwMDVkO2ZpbGwtcnVsZTpub256ZXJvIi8%2BPHBhdGggZD0iTTE4NSAzMWg1N3Y1NWgtMjVWNTVoLTMyVjMxWiIgc3R5bGU9ImZpbGw6I2M1MTgxZjtmaWxsLXJ1bGU6bm9uemVybyIvPjwvc3ZnPg%3D%3D&labelColor=fff)](https://ippclub.org) [![Ubuntu](https://github.com/pigpigyyy/Yuescript/actions/workflows/ubuntu.yml/badge.svg)](https://github.com/pigpigyyy/Yuescript/actions/workflows/ubuntu.yml) [![Windows](https://github.com/pigpigyyy/Yuescript/actions/workflows/windows.yml/badge.svg)](https://github.com/pigpigyyy/Yuescript/actions/workflows/windows.yml) [![macOS](https://github.com/pigpigyyy/Yuescript/actions/workflows/macos.yml/badge.svg)](https://github.com/pigpigyyy/Yuescript/actions/workflows/macos.yml) [![Discord Badge](https://img.shields.io/discord/844031511208001577?color=5865F2&label=Discord&logo=discord&logoColor=white&style=flat-square)](https://discord.gg/cRJ2VAm2NV) -YueScript is a MoonScript dialect. It is derived from [MoonScript language](https://github.com/leafo/moonscript) 0.5.0 and continuously adopting new features to be more up to date. +YueScript is a MoonScript dialect that compiles to Lua. It is derived from [MoonScript](https://github.com/leafo/moonscript) `0.5.0` and continues to adopt new features to stay up to date. -MoonScript is a language that compiles to Lua. Since original MoonScript has been used to write web framework [lapis](https://github.com/leafo/lapis) and run a few business web sites like [itch.io](https://itch.io) and [streak.club](https://streak.club) with some large code bases. The original language is getting too hard to adopt new features for those may break the stablility for existing applications. +## Quick Links -So YueScript is a new code base for pushing the language to go forward and being a playground to try introducing new language syntax or programing paradigms to make MoonScript language more expressive and productive. +- Website: +- Documentation: +- Changelog: [`CHANGELOG.md`](./CHANGELOG.md) +- Discord: -Yue (月) is the name of moon in Chinese and it's pronounced as [jyɛ]. +## Overview +MoonScript has been used to build real-world projects such as [Lapis](https://github.com/leafo/lapis), [itch.io](https://itch.io), and [streak.club](https://streak.club). As the original implementation became harder to evolve without risking compatibility, YueScript was created as a modernized code base for pushing the language forward. +YueScript is both a production-ready compiler and a playground for exploring new syntax and programming paradigms that make MoonScript-style development more expressive and productive. + +Yue (月) is the Chinese word for moon and is pronounced [jyɛ]. ## About Dora SSR YueScript is being developed and maintained alongside the open-source game engine [Dora SSR](https://github.com/ippclub/Dora-SSR). It has been used to create engine tools, game demos and prototypes, validating its capabilities in real-world scenarios while enhancing the Dora SSR development experience. - - ## Features -* Based on modified [parserlib](https://github.com/axilmar/parserlib) library from Achilleas Margaritis with some performance enhancement. **lpeg** library is no longer needed. -* Written in C++17. -* Support most of the features from MoonScript language. Generate Lua codes in the same way like the original compiler. -* Reserve line numbers from source file in the compiled Lua codes to help debugging. -* More features like macro, existential operator, pipe operator, Javascript-like export syntax and etc. -* See other details in the [changelog](./CHANGELOG.md). Find document [here](http://yuescript.org). - - +- Based on a modified [parserlib](https://github.com/axilmar/parserlib) with performance enhancements. `lpeg` is no longer required. +- Written in C++17. +- Supports most MoonScript features and generates Lua code in a style compatible with the original compiler. +- Preserves source line numbers in generated Lua to improve debugging. +- Adds features like macros, existential operator, pipe operator, JavaScript-like export syntax, and more. +- See [`CHANGELOG.md`](./CHANGELOG.md) for more details. -## Installation & Usage +## Installation -* **Lua Module** +### Lua Module -  Build `yue.so` file with +Build `yue.so` with: ```sh > make shared LUAI=/usr/local/include/lua LUAL=/usr/local/lib/lua ``` -  Then get the binary file from path `bin/shared/yue.so`. +Then get the binary file from `bin/shared/yue.so`. -  Or you can install [luarocks](https://luarocks.org), a package manager for Lua modules. Then install it as a Lua module with +Or install via [LuaRocks](https://luarocks.org): ```sh > luarocks install yuescript ``` -  Then require the YueScript module in Lua: +Then require the YueScript module in Lua: ```lua require("yue")("main") -- require `main.yue` @@ -65,26 +68,27 @@ f! }) ``` +### Binary Tool (CLI) +Clone this repo, then build and install executable with: -* **Binary Tool** - -  Clone this repo, then build and install executable with: ```sh > make install ``` -  Build YueScript tool without macro feature: +Build YueScript tool without macro feature: + ```sh > make install NO_MACRO=true ``` -  Build YueScript tool without built-in Lua binary: +Build YueScript tool without built-in Lua binary: + ```sh > make install NO_LUA=true ``` -  Use YueScript tool with: +Use YueScript tool with: ```sh > yue -h @@ -131,24 +135,29 @@ Options: in a single line to start/stop multi-line mode ``` -Use cases: +### Common Usage -* Recursively compile every YueScript file with extension `.yue` under current path: `yue .` -* Compile and save results to a target path: `yue -t /target/path/ .` -* Compile and reserve debug info: `yue -l .` -* Compile and generate minified codes: `yue -m .` -* Execute raw codes: `yue -e 'print 123'` -* Execute a YueScript file: `yue -e main.yue` +- Recursively compile every YueScript file with extension `.yue` under current path: `yue .` +- Compile and save results to a target path: `yue -t /target/path/ .` +- Compile and reserve debug info: `yue -l .` +- Compile and generate minified codes: `yue -m .` +- Execute raw codes: `yue -e 'print 123'` +- Execute a YueScript file: `yue -e main.yue` +## Mascot (Xiaoyu / 小玉) +Xiaoyu, the YueScript mascot -## Editor Support +Xiaoyu (小玉) is YueScript's official mascot, a cyber rabbit often seen perched on a crescent moon and coding on a laptop. -* [Vim](https://github.com/pigpigyyy/YueScript-vim) -* [ZeroBraneStudio](https://github.com/pkulchenko/ZeroBraneStudio/issues/1134) (Syntax highlighting) -* [Visual Studio Code](https://github.com/pigpigyyy/yuescript-vscode) +- English page: [here](https://yuescript.org/doc/extras/mascot.html) +- Artwork by [Tyson Tan](https://tysontan.com) +## Editor Support +- [Vim](https://github.com/pigpigyyy/YueScript-vim) +- [ZeroBraneStudio](https://github.com/pkulchenko/ZeroBraneStudio/issues/1134) (Syntax highlighting) +- [Visual Studio Code](https://github.com/pigpigyyy/yuescript-vscode) ## License -- cgit v1.2.3-55-g6feb