Compare commits

..
5 Commits
Author SHA1 Message Date
cflmy 111849d92a 添加readme 2026-08-11 17:38:49 +08:00
cflmy 235384fb85 开发基本的骨架,错误处理的结构体和框架 2026-08-11 17:29:43 +08:00
cflmy a9b59b361e 初始化项目的基本框架 2026-08-11 16:37:13 +08:00
cflmy c4501a17f2 master分支 init 2026-08-11 15:26:16 +08:00
cflmyandCursor 5f00572e24 Empty master branch.
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-11 15:09:22 +08:00
69 changed files with 240 additions and 7416 deletions

No files matched your search

+1 -13
View File
@@ -1,13 +1 @@
/target/
**/*.rs.bk
.idea/
.vscode/
*.pdb
.DS_Store
# Python spike venv (local)
spike/.venv/
spike/__pycache__/
spike/.pytest_cache/
**/__pycache__/
*.pyc
/target
Generated
+1 -441
View File
@@ -1,447 +1,7 @@
# This file is automatically @generated by Cargo.
# It is not intended for manual editing.
version = 3
[[package]]
name = "aho-corasick"
version = "1.1.5"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "c982642fa9e8606056828ee9a8505737230110bb1099153c79efe865c59d12ba"
dependencies = [
"memchr",
]
[[package]]
name = "anstream"
version = "0.6.21"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "43d5b281e737544384e969a5ccad3f1cdd24b48086a0fc1b2a5262a26b8f4f4a"
dependencies = [
"anstyle",
"anstyle-parse",
"anstyle-query",
"anstyle-wincon",
"colorchoice",
"is_terminal_polyfill",
"utf8parse",
]
[[package]]
name = "anstyle"
version = "1.0.14"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "940b3a0ca603d1eade50a4846a2afffd5ef57a9feac2c0e2ec2e14f9ead76000"
[[package]]
name = "anstyle-parse"
version = "0.2.7"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "4e7644824f0aa2c7b9384579234ef10eb7efb6a0deb83f9630a49594dd9c15c2"
dependencies = [
"utf8parse",
]
[[package]]
name = "anstyle-query"
version = "1.1.5"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "40c48f72fd53cd289104fc64099abca73db4166ad86ea0b4341abe65af83dadc"
dependencies = [
"windows-sys",
]
[[package]]
name = "anstyle-wincon"
version = "3.0.11"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "291e6a250ff86cd4a820112fb8898808a366d8f9f58ce16d1f538353ad55747d"
dependencies = [
"anstyle",
"once_cell_polyfill",
"windows-sys",
]
[[package]]
name = "anyhow"
version = "1.0.104"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "330a5ed07fa54e4702c9d6c4174f74427fc0ef6e214bbd677ae50a5099946470"
[[package]]
name = "ascii"
version = "1.1.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "d92bec98840b8f03a5ff5413de5293bfcd8bf96467cf5452609f939ec6f5de16"
[[package]]
name = "assert_cmd"
version = "2.0.14"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "ed72493ac66d5804837f480ab3766c72bdfab91a65e565fc54fa9e42db0073a8"
dependencies = [
"anstyle",
"bstr",
"doc-comment",
"predicates",
"predicates-core",
"predicates-tree",
"wait-timeout",
]
[[package]]
name = "autocfg"
version = "1.5.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "f2032f911046de80f0a198e0901378627c33f59ea0ac00e363d481118bd70a53"
[[package]]
name = "bstr"
version = "1.13.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "1f7dc094d718f2e1c1559ad110e27eeaae14a5465d3d56dd6dbd793079fbd530"
dependencies = [
"memchr",
"regex-automata",
"serde_core",
]
[[package]]
name = "chunked_transfer"
version = "1.5.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "6e4de3bc4ea267985becf712dc6d9eed8b04c953b3fcfb339ebc87acd9804901"
[[package]]
name = "clap"
version = "4.4.18"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "1e578d6ec4194633722ccf9544794b71b1385c3c027efe0c55db226fc880865c"
dependencies = [
"clap_builder",
"clap_derive",
]
[[package]]
name = "clap_builder"
version = "4.4.18"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "4df4df40ec50c46000231c914968278b1eb05098cf8f1b3a518a95030e71d1c7"
dependencies = [
"anstream",
"anstyle",
"clap_lex",
"strsim",
]
[[package]]
name = "clap_derive"
version = "4.4.7"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "cf9804afaaf59a91e75b022a30fb7229a7901f60c755489cc61c9b423b836442"
dependencies = [
"heck",
"proc-macro2",
"quote",
"syn 2.0.119",
]
[[package]]
name = "clap_lex"
version = "0.6.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "702fc72eb24e5a1e48ce58027a675bc24edd52096d5397d4aea7c6dd9eca0bd1"
[[package]]
name = "colorchoice"
version = "1.0.5"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "1d07550c9036bf2ae0c684c4297d503f838287c83c53686d05370d0e139ae570"
[[package]]
name = "difflib"
version = "0.4.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "6184e33543162437515c2e2b48714794e37845ec9851711914eec9d308f6ebe8"
[[package]]
name = "doc-comment"
version = "0.3.4"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "780955b8b195a21ab8e4ac6b60dd1dbdcec1dc6c51c0617964b08c81785e12c9"
[[package]]
name = "float-cmp"
version = "0.9.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "98de4bbd547a563b716d8dfa9aad1cb19bfab00f4fa09a6a4ed21dbcf44ce9c4"
dependencies = [
"num-traits",
]
[[package]]
name = "heck"
version = "0.4.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "95505c38b4572b2d910cecb0281560f54b440a19336cbbcb27bf6ce6adc6f5a8"
[[package]]
name = "httpdate"
version = "1.0.3"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "df3b46402a9d5adb4c86a0cf463f42e19994e3ee891101b1841f30a545cb49a9"
[[package]]
name = "is_terminal_polyfill"
version = "1.70.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "a6cb138bb79a146c1bd460005623e142ef0181e3d0219cb493e02f7d08a35695"
[[package]]
name = "libc"
version = "0.2.189"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "3eaf3ede3fee6db1a4c2ee091bf8a8b4dccdc6d17f656fb07896ee72867612f2"
[[package]]
name = "log"
version = "0.4.33"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "0ceec5bc11778974d1bcb055b18002eba7f4b3518b6a0081b3af5f21666da9ad"
version = 4
[[package]]
name = "marqdo"
version = "0.1.0"
dependencies = [
"anyhow",
"assert_cmd",
"clap",
"predicates",
"thiserror",
"tiny_http",
]
[[package]]
name = "memchr"
version = "2.8.3"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "cf8baf1c55e62ffcace7a9f06f4bd9cd3f0c4beb022d3b367256b91b87513d98"
[[package]]
name = "normalize-line-endings"
version = "0.3.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "61807f77802ff30975e01f4f071c8ba10c022052f98b3294119f3e615d13e5be"
[[package]]
name = "num-traits"
version = "0.2.19"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "071dfc062690e90b734c0b2273ce72ad0ffa95f0c74596bc250dcfd960262841"
dependencies = [
"autocfg",
]
[[package]]
name = "once_cell_polyfill"
version = "1.70.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "384b8ab6d37215f3c5301a95a4accb5d64aa607f1fcb26a11b5303878451b4fe"
[[package]]
name = "predicates"
version = "3.1.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "68b87bfd4605926cdfefc1c3b5f8fe560e3feca9d5552cf68c466d3d8236c7e8"
dependencies = [
"anstyle",
"difflib",
"float-cmp",
"normalize-line-endings",
"predicates-core",
"regex",
]
[[package]]
name = "predicates-core"
version = "1.0.10"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "cad38746f3166b4031b1a0d39ad9f954dd291e7854fcc0eed52ee41a0b50d144"
[[package]]
name = "predicates-tree"
version = "1.0.13"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "d0de1b847b39c8131db0467e9df1ff60e6d0562ab8e9a16e568ad0fdb372e2f2"
dependencies = [
"predicates-core",
"termtree",
]
[[package]]
name = "proc-macro2"
version = "1.0.107"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "985e7ec9bb745e6ce6535b544d84d6cd6f7ad8bd711c398938ae983b91a766d9"
dependencies = [
"unicode-ident",
]
[[package]]
name = "quote"
version = "1.0.47"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "1fbf4db142a473a8d80c26bbf18454ed458bf8d26c8219c331daecfdbd079001"
dependencies = [
"proc-macro2",
]
[[package]]
name = "regex"
version = "1.13.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "f020237b6c8eed93db2e2cb53c00c60a8e1bc73da7d073199a1180401450218d"
dependencies = [
"aho-corasick",
"memchr",
"regex-automata",
"regex-syntax",
]
[[package]]
name = "regex-automata"
version = "0.4.16"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "8fcfdb36bda0c880c5931cdc7a2bcdc8ba4556847b9d912bca70bc94708711ad"
dependencies = [
"aho-corasick",
"memchr",
"regex-syntax",
]
[[package]]
name = "regex-syntax"
version = "0.8.11"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "d6f6ff9a378485b298a5286656da665ba74413d36db0979633275d2e708145d4"
[[package]]
name = "serde_core"
version = "1.0.229"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "67dca2c9c51e58a4791a4b1ed58308b39c64224d349a935ab5039aa360942a48"
dependencies = [
"serde_derive",
]
[[package]]
name = "serde_derive"
version = "1.0.229"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "e7a5d71263a5a7d47b41f6b3f06ba276f10cc18b0931f1799f710578e2309348"
dependencies = [
"proc-macro2",
"quote",
"syn 3.0.3",
]
[[package]]
name = "strsim"
version = "0.10.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "73473c0e59e6d5812c5dfe2a064a6444949f089e20eec9a2e5506596494e4623"
[[package]]
name = "syn"
version = "2.0.119"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "872831b642d1a07999a962a351ed35b955ea2cfc8f3862091e2a240a84f17297"
dependencies = [
"proc-macro2",
"quote",
"unicode-ident",
]
[[package]]
name = "syn"
version = "3.0.3"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "53e9bae58849f64dfa4f5d5ae372c8341f7305f82a3868709269343628b659a3"
dependencies = [
"proc-macro2",
"quote",
"unicode-ident",
]
[[package]]
name = "termtree"
version = "0.5.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "8f50febec83f5ee1df3015341d8bd429f2d1cc62bcba7ea2076759d315084683"
[[package]]
name = "thiserror"
version = "1.0.69"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "b6aaf5339b578ea85b50e080feb250a3e8ae8cfcdff9a461c9ec2904bc923f52"
dependencies = [
"thiserror-impl",
]
[[package]]
name = "thiserror-impl"
version = "1.0.69"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "4fee6c4efc90059e10f81e6d42c60a18f76588c3d74cb83a0b242a2b6c7504c1"
dependencies = [
"proc-macro2",
"quote",
"syn 2.0.119",
]
[[package]]
name = "tiny_http"
version = "0.12.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "389915df6413a2e74fb181895f933386023c71110878cd0825588928e64cdc82"
dependencies = [
"ascii",
"chunked_transfer",
"httpdate",
"log",
]
[[package]]
name = "unicode-ident"
version = "1.0.24"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "e6e4313cd5fcd3dad5cafa179702e2b244f760991f45397d14d4ebf38247da75"
[[package]]
name = "utf8parse"
version = "0.2.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "06abde3611657adf66d383f00b093d7faecc7fa57071cce2578660c9f1010821"
[[package]]
name = "wait-timeout"
version = "0.2.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "09ac3b126d3914f9849036f826e054cbabdc8519970b8998ddaf3b5bd3c65f11"
dependencies = [
"libc",
]
[[package]]
name = "windows-link"
version = "0.2.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "f0805222e57f7521d6a62e36fa9163bc891acd422f971defe97d64e70d0a4fe5"
[[package]]
name = "windows-sys"
version = "0.61.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "ae137229bcbd6cdf0f7b80a31df61766145077ddf49416a728b02cb3921ff3fc"
dependencies = [
"windows-link",
]
+5 -17
View File
@@ -1,22 +1,10 @@
[package]
name = "marqdo"
version = "0.0.1"
edition = "2021"
license = "Apache-2.0"
description = "Marqdo — Markdown markers as an interpreted programming language"
readme = "README.md"
repository = "https://github.com/cflmy/marqdo"
version = "0.1.0"
edition = "2024"
[dependencies]
[[bin]]
name = "marqdo"
path = "src/main.rs"
[dependencies]
anyhow = "1"
clap = { version = "=4.4.18", features = ["derive"] }
thiserror = "1"
tiny_http = "0.12"
[dev-dependencies]
assert_cmd = "=2.0.14"
predicates = "=3.1.0"
path = "src/marqdo.rs"
-201
View File
@@ -1,201 +0,0 @@
Apache License
Version 2.0, January 2004
http://www.apache.org/licenses/
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
1. Definitions.
"License" shall mean the terms and conditions for use, reproduction,
and distribution as defined by Sections 1 through 9 of this document.
"Licensor" shall mean the copyright owner or entity authorized by
the copyright owner that is granting the License.
"Legal Entity" shall mean the union of the acting entity and all
other entities that control, are controlled by, or are under common
control with that entity. For the purposes of this definition,
"control" means (i) the power, direct or indirect, to cause the
direction or management of such entity, whether by contract or
otherwise, or (ii) ownership of fifty percent (50%) or more of the
outstanding shares, or (iii) beneficial ownership of such entity.
"You" (or "Your") shall mean an individual or Legal Entity
exercising permissions granted by this License.
"Source" form shall mean the preferred form for making modifications,
including but not limited to software source code, documentation
source, and configuration files.
"Object" form shall mean any form resulting from mechanical
transformation or translation of a Source form, including but
not limited to compiled object code, generated documentation,
and conversions to other media types.
"Work" shall mean the work of authorship, whether in Source or
Object form, made available under the License, as indicated by a
copyright notice that is included in or attached to the work
(an example is provided in the Appendix below).
"Derivative Works" shall mean any work, whether in Source or Object
form, that is based on (or derived from) the Work and for which the
editorial revisions, annotations, elaborations, or other modifications
represent, as a whole, an original work of authorship. For the purposes
of this License, Derivative Works shall not include works that remain
separable from, or merely link (or bind by name) to the interfaces of,
the Work and Derivative Works thereof.
"Contribution" shall mean any work of authorship, including
the original version of the Work and any modifications or additions
to that Work or Derivative Works thereof, that is intentionally
submitted to Licensor for inclusion in the Work by the copyright owner
or by an individual or Legal Entity authorized to submit on behalf of
the copyright owner. For the purposes of this definition, "submitted"
means any form of electronic, verbal, or written communication sent
to the Licensor or its representatives, including but not limited to
communication on electronic mailing lists, source code control systems,
and issue tracking systems that are managed by, or on behalf of, the
Licensor for the purpose of discussing and improving the Work, but
excluding communication that is conspicuously marked or otherwise
designated in writing by the copyright owner as "Not a Contribution."
"Contributor" shall mean Licensor and any individual or Legal Entity
on behalf of whom a Contribution has been received by Licensor and
subsequently incorporated within the Work.
2. Grant of Copyright License. Subject to the terms and conditions of
this License, each Contributor hereby grants to You a perpetual,
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
copyright license to reproduce, prepare Derivative Works of,
publicly display, publicly perform, sublicense, and distribute the
Work and such Derivative Works in Source or Object form.
3. Grant of Patent License. Subject to the terms and conditions of
this License, each Contributor hereby grants to You a perpetual,
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
(except as stated in this section) patent license to make, have made,
use, offer to sell, sell, import, and otherwise transfer the Work,
where such license applies only to those patent claims licensable
by such Contributor that are necessarily infringed by their
Contribution(s) alone or by combination of their Contribution(s)
with the Work to which such Contribution(s) was submitted. If You
institute patent litigation against any entity (including a
cross-claim or counterclaim in a lawsuit) alleging that the Work
or a Contribution incorporated within the Work constitutes direct
or contributory patent infringement, then any patent licenses
granted to You under this License for that Work shall terminate
as of the date such litigation is filed.
4. Redistribution. You may reproduce and distribute copies of the
Work or Derivative Works thereof in any medium, with or without
modifications, and in Source or Object form, provided that You
meet the following conditions:
(a) You must give any other recipients of the Work or
Derivative Works a copy of this License; and
(b) You must cause any modified files to carry prominent notices
stating that You changed the files; and
(c) You must retain, in the Source form of any Derivative Works
that You distribute, all copyright, patent, trademark, and
attribution notices from the Source form of the Work,
excluding those notices that do not pertain to any part of
the Derivative Works; and
(d) If the Work includes a "NOTICE" text file as part of its
distribution, then any Derivative Works that You distribute must
include a readable copy of the attribution notices contained
within such NOTICE file, excluding those notices that do not
pertain to any part of the Derivative Works, in at least one
of the following places: within a NOTICE text file distributed
as part of the Derivative Works; within the Source form or
documentation, if provided along with the Derivative Works; or,
within a display generated by the Derivative Works, if and
wherever such third-party notices normally appear. The contents
of the NOTICE file are for informational purposes only and
do not modify the License. You may add Your own attribution
notices within Derivative Works that You distribute, alongside
or as an addendum to the NOTICE text from the Work, provided
that such additional attribution notices cannot be construed
as modifying the License.
You may add Your own copyright statement to Your modifications and
may provide additional or different license terms and conditions
for use, reproduction, or distribution of Your modifications, or
for any such Derivative Works as a whole, provided Your use,
reproduction, and distribution of the Work otherwise complies with
the conditions stated in this License.
5. Submission of Contributions. Unless You explicitly state otherwise,
any Contribution intentionally submitted for inclusion in the Work
by You to the Licensor shall be under the terms and conditions of
this License, without any additional terms or conditions.
Notwithstanding the above, nothing herein shall supersede or modify
the terms of any separate license agreement you may have executed
with Licensor regarding such Contributions.
6. Trademarks. This License does not grant permission to use the trade
names, trademarks, service marks, or product names of the Licensor,
except as required for reasonable and customary use in describing the
origin of the Work and reproducing the content of the NOTICE file.
7. Disclaimer of Warranty. Unless required by applicable law or
agreed to in writing, Licensor provides the Work (and each
Contributor provides its Contributions) on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
implied, including, without limitation, any warranties or conditions
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
PARTICULAR PURPOSE. You are solely responsible for determining the
appropriateness of using or redistributing the Work and assume any
risks associated with Your exercise of permissions under this License.
8. Limitation of Liability. In no event and under no legal theory,
whether in tort (including negligence), contract, or otherwise,
unless required by applicable law (such as deliberate and grossly
negligent acts) or agreed to in writing, shall any Contributor be
liable to You for damages, including any direct, indirect, special,
incidental, or consequential damages of any character arising as a
result of this License or out of the use or inability to use the
Work (including but not limited to damages for loss of goodwill,
work stoppage, computer failure or malfunction, or any and all
other commercial damages or losses), even if such Contributor
has been advised of the possibility of such damages.
9. Accepting Warranty or Additional Liability. While redistributing
the Work or Derivative Works thereof, You may choose to offer,
and charge a fee for, acceptance of support, warranty, indemnity,
or other liability obligations and/or rights consistent with this
License. However, in accepting such obligations, You may act only
on Your own behalf and on Your sole responsibility, not on behalf
of any other Contributor, and only if You agree to indemnify,
defend, and hold each Contributor harmless for any liability
incurred by, or claims asserted against, such Contributor by reason
of your accepting any such warranty or additional liability.
END OF TERMS AND CONDITIONS
APPENDIX: How to apply the Apache License to your work.
To apply the Apache License to your work, attach the following
boilerplate notice, with the fields enclosed by brackets "[]"
replaced with your own identifying information. (Don't include
the brackets!) The text should be enclosed in the appropriate
comment syntax for the file format. We also recommend that a
file or class name and description of purpose be included on the
same "printed page" as the copyright notice for easier
identification within third-party archives.
Copyright [yyyy] [name of copyright owner]
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-73
View File
@@ -1,73 +0,0 @@
# Marqdo
**代码即文档。文档即代码。**
Marqdo:Markdown **标记即语法**。源文件 `.mq.md` 既是文稿也是程序。
语法宪法:[doc/design/markdown-mapping.md](doc/design/markdown-mapping.md) · 调用实参:[call-arguments.md](doc/design/call-arguments.md) · 示例布局:[examples-and-tests.md](doc/design/examples-and-tests.md) · 浏览:[view.md](doc/design/view.md) · 示例:[examples/](examples/)
---
## 语法速览(v0.1)
| 标记 | 含义 |
|------|------|
| 无标记行 | 注释 |
| `*…*` | 程序语句 |
| `**…**` | **返回值**(架构) |
| `> print …` 等 | 输出等副作用 = **普通函数**,非架构标记 |
| `#` / `##` | 函数与作用域 |
| `+` / `1.` | 分支(臂头单独 `*` = else) |
| `-` | 循环(头下纯名则为形参) |
| 表格 | 集合 |
| `---` / `***` | 可选:框住分支/循环(不强制) |
```markdown
# main
> print text=Hello World!
## 加一
- n
**`n` + 1**
```
---
## 理念
1. 叙述默认安全(无标记 = 注释)。
2. 返回是架构;打印只是函数。
3. 依赖清单由工具生成(OKF 风格),不是手填配置。
4. **正经解释器(Rust)**:词法/行分类 → 递归下降语法 → 语义 → 树遍历 → 日后字节码;**不用 Flex/Bison**。见 [路线图](doc/roadmap/interpreter.md) 与 [依赖说明](doc/design/dependencies.md)。
---
## 现状
- 映射 v0.1:[markdown-mapping.md](doc/design/markdown-mapping.md)
- 解释器路线图:[interpreter.md](doc/roadmap/interpreter.md)
- **Phase I(树遍历)已通**:`examples/structure/` 与 `examples/keywords/` 金样例均可 `marqdo run`
- **view**:`marqdo view examples` 按 AST 浏览结构与输出
- 依赖(Rust,无 Flex/Bison):[dependencies.md](doc/design/dependencies.md)
- 选型:[ADR 0001 — Rust](doc/adr/0001-implementation-language.md)
```bash
cargo run -- run examples/structure/hello.mq.md
cargo run -- run examples/structure/hello.mq.md --backend bytecode
cargo run -- view examples --no-open
```
当前发布:**v0.0.1**(Phase I 树遍历 + `view` + M5 字节码原型)。M5 见 [bytecode.md](doc/design/bytecode.md);errors 见 `examples/errors/`。
---
## 命名
**Marqdo** = Marq(Markdown)+ do(执行)
## 许可
[Apache License 2.0](LICENSE)
+91
View File
@@ -0,0 +1,91 @@
---
title: Marqdo主分支开发记录
date: 2026-08-11
author: pingan
---
## 前言
在经过一周多的ai疯狂开发之后,尽管marqdo已经做出了并拥有了许多非常良好的特性,作者确逐渐感到非常的不安,
这种不安来自于崩塌感,作者不知道什么时候,ai就会更改关键的定义,导致突然的崩塌,在开发智能体拓展库的时候作者还尚未有这种感觉,但是在网络拓展库,这种不安定感几乎席卷了作者的全部身心。
必须承认,ai在没有经过大量训练就撰写一门崭新的语法,定义一些它完全没有接触过的东西对于ai还是太困难了,ai并不能通过我的监督,真正的理解marqdo代码即文档的设计思路,所以,尽管非常的遗憾,作者还是决定回归古法编程,还是手搓代码吧,尽管这意味着marqdo很难赶上ai的浪潮了。
marqdo的设计初衷很是简单,这就不是一门设计给程序员的语言,哪个程序员会用markdown表格来表示集合呢?不会的,这太过繁复了,但是ai可以,这就使得过去编程语言的范式变得不是那么重要了。
自然如果只是为了易读性,marqdo并没有完全的开发必要,重点在于对md的支持,作者必须承认谷歌提出的OKF规范,把markdown这种文件格式放到了一个极高的位置,这意味着,可执行的知识体系,如果能做到,为什么不试试?
此外,jupyter notebook笔记本体积太大不利于管理的问题也是存在的,作者就在想,markdown支持代码块的插入,这个代码如果可以直接执行并放回,这不就是最好的jupyter替代品吗?事实上,在main分支的marqdo已经实现了这个功能,但是还不够好,作者要把marqdo真正做成一门科学计算的顶级语言。
最后是数学公式的支持,公式库需要能够自动的渲染,高可读,还要能够自动的画图,自动的完成诸多内容,让可执行=正确,让ai支持数学推理不再困难。
最后,2026年8月11日,我预祝未来的自己,开发成功。
## 开发
### Marqdo上下文无关文法
file -> "---" metadata "---" content ;
metadata -> file_information |
import_lib_name ;
content -> comment |
code_body ;
comment -> comment_content ;
code_body -> class |
function|
code|
$formula$|$$formula$$|\[formula\]|
```code_block_type
code_block
```;
class -> # class_name code_body |
# class_name => parent_class_name code_body ;
function -> function_header param_list body return_stmt ;
function_header -> ## identifier |
### identifier |
#### identifier ;
param_list -> + identifier ;
body -> statement |
branch |
loop ;
return_stmt -> ** statement ** ;
<!--the number of # stand for the level of function -->
code -> 1. branch |
- loop |
statement ;
<!--Ordered lists represent branch, unordered lists represent loop-->
branch -> statement ;
loop -> statement ;
statement -> > call |
literal|
`var_value_name`|
list and dict|
"str"|
*statement_without_any_marker*;
<!--here we use markdown table to stand for list and dict-->
call -> function_name args;
literal -> literal_code as other code;
formula -> latex math code;
code_block_type -> code_block's code type;
code_block -> code of a code_block;
-41
View File
@@ -1,41 +0,0 @@
# Marqdo 开发文档
本目录存放各阶段设计、选型与路线图。
## 目录约定
| 路径 | 用途 |
|------|------|
| [`research/`](research/) | 外部标准与调研 |
| [`design/`](design/) | 语言设计(语法映射等) |
| [`adr/`](adr/) | 架构决策记录 |
| [`roadmap/`](roadmap/) | 实现路线与里程碑 |
## 当前文档
| 文档 | 摘要 |
|------|------|
| [design/markdown-mapping.md](design/markdown-mapping.md) | **v0.1 语法宪法** |
| [design/code-vs-comment.md](design/code-vs-comment.md) | 叙述 / 可执行 / 外联 |
| [design/return-hr-and-code-surface.md](design/return-hr-and-code-surface.md) | 语句/返回/输出决议 |
| [design/generated-yaml-manifest.md](design/generated-yaml-manifest.md) | 生成式 OKF 清单 |
| [design/tech-stack.md](design/tech-stack.md) | 实现栈对比 |
| [adr/0001-implementation-language.md](adr/0001-implementation-language.md) | **Accepted:Rust 参考解释器;不用 Flex/Bison** |
| [design/dependencies.md](design/dependencies.md) | 依赖详单(无 Flex/Bison) |
| [design/keywords.md](design/keywords.md) | **英文最小关键字 / 内置 `print` `input`** |
| [design/call-arguments.md](design/call-arguments.md) | **调用:具名 + 位置实参** |
| [design/examples-and-tests.md](design/examples-and-tests.md) | **示例即金样例目录布局** |
| [design/view.md](design/view.md) | **`marqdo view` 源结构浏览器** |
| [design/bytecode.md](design/bytecode.md) | **M5 字节码 / 双后端** |
| [design/pipeline-debug.md](design/pipeline-debug.md) | **流水线 `--dump-*` 可视调试** |
| [dev-setup.md](dev-setup.md) | 开发环境配置(Rust M0) |
| [roadmap/interpreter.md](roadmap/interpreter.md) | 正经解释器路线图 |
| [research/okf-and-marqdo.md](research/okf-and-marqdo.md) | OKF 调研 |
示例与验收集:[`examples/`](../examples/)。Spike 存档:[`spike/`](../spike/)。
## 写作原则
1. 先宪法与路线图,再实现。
2. 金样例不过 = 未完成。
3. 示例统一 `.mq.md`。
-53
View File
@@ -1,53 +0,0 @@
# ADR 0001:参考实现语言与前端工具
| | |
|---|---|
| 状态 | **Accepted**(修订:实现语言 = Rust) |
| 日期 | 2026-08-04 |
| 决策者 | chaungming + 协作 |
| 相关 | [dependencies.md](../design/dependencies.md) · [interpreter 路线图](../roadmap/interpreter.md) · [spike/REPORT.md](../../spike/REPORT.md) |
---
## 背景
语法宪法 v0.1 已定;Python Spike 已验证 GFM/行扫描风险。产品目标是正经**解释器**(`marqdo run index.mq.md`),实现语言需兼顾安全与可维护性。
---
## 决策
1. **参考解释器实现语言:Rust(stable)**
- 内存安全、单静态二进制、适合长期演进到字节码 VM。
- Python Spike **保留为算法原型/对照**,不是运行时依赖。
2. **词法 / 语法:不使用 Flex、Bison**
- **主因是 Marqdo 的 Markdown 语法形态**,不是「因为选了 Rust」。换成 C++ 同样不建议用 Flex/Bison 做整语言前端。
- 解释器需要词法·语法**阶段**;采用自研行分类 + GFM 库 + **手写递归下降** → AST。
- 详见 [dependencies.md](../design/dependencies.md)。
3. **架构分期不变**
- Phase I:树遍历解释器
- Phase II:字节码 + VM
- 见 [interpreter.md](../roadmap/interpreter.md)
4. **Markdown 库**
- `pulldown-cmark` 或 `comrak` 二选一(建包前短 Spike 钉死)。
---
## 后果
- 正式代码以 Cargo 工程生长;不把 Flex/Bison/LLVM 列入 v1 依赖。
- 金样例仍为 `examples/`;行为与宪法一致。
- 此前「Python 作参考实现」的倾向由本修订取代;Spike 结论(行扫描等)仍然有效并迁入 Rust。
---
## 否决
| 方案 | 原因 |
|------|------|
| Flex + Bison 作主前端 | 与 Markup-as-Syntax / Rust 栈错配;解释器非必需 |
| v1 上 LLVM | 产品是解释执行文档,不是机器后端 |
| 仅 Python 正则玩具 | 达不到安全与长期目标 |
-89
View File
@@ -1,89 +0,0 @@
# Marqdo 字节码(M5 原型)
| | |
|---|---|
| 状态 | 进行中(原型) |
| 日期 | 2026-08-04 |
| 相关 | [roadmap/interpreter.md](../roadmap/interpreter.md) · Phase I 树遍历 |
---
## 1. 目标
在保留树遍历后端(`--backend tree`,默认)的同时,提供栈式字节码 VM(`--backend bytecode`),使**核心金样例** stdout 与树遍历 bit 一致。
```
.mq.md → load/parse → Module AST
├─ tree-walk
└─ compile → Chunk → VM
```
---
## 2. 指令集(草案 / 原型已实现子集)
| Op | 栈效应 | 说明 |
|----|--------|------|
| `Constant i` | → v | 常量池 |
| `True` / `False` / `None` | → b | |
| `Pop` | v → | |
| `GetLocal i` / `SetLocal i` | | 当前帧槽 |
| `GetGlobal i` / `SetGlobal i` | | 名字在常量池(文本) |
| `Add` `Sub` `Mul` `Div` `Negate` `Not` | | |
| `Equal` `NotEqual` `Greater` `GreaterEqual` `Less` `LessEqual` | | |
| `Jump a` / `JumpIfFalse a` / `JumpBack a` | | 相对/绝对跳转(原型用绝对 u16) |
| `Print` | v → | 弹出并写 stdout |
| `BuildList n` | v… → list | |
| `GetIndex` | list, i → v | foreach 用 |
| `Call f argc` | args… → ret | 用户函数(按形参序压栈) |
| `Return` | | 返回 / 结束帧 |
| `Interp n` | parts… → text | n 个交错 Lit/Var 标记后的拼接(简化:编译期展开为常量+拼接) |
原型实现以 `src/bytecode/` 为准;未列出的 Op 不存在于当前构建。
---
## 3. 编译约定
- 每个 Marqdo `Function` → 一个 `FnChunk`(含 `name`、`params`、`code`、`constants`)。
- 模块级 `Program`:函数表 + 入口名(`main` 或唯一无参 level-1)。
- 局部变量:函数体内首次赋值/形参分配槽位。
- 嵌套 `##`:编入同一 `Program`,按名 `Call`;查找规则对齐树遍历(子树优先,再顶层)。
- `and` / `or`:短接跳转。
- 分支 / while:`JumpIfFalse` + `Jump` / `JumpBack`。
- foreach:`BuildList` 或已有 list 全局/局部 → 索引循环。
---
## 4. 覆盖表(M5 原型)
| 金样例 | tree | bytecode |
|--------|------|----------|
| `structure/hello` | ✅ | ✅ |
| `structure/branch` | ✅ | ✅ |
| `structure/loop` | ✅ | ✅ |
| `structure/collection` | ✅ | ✅ |
| `keywords/print` | ✅ | ✅ |
| `keywords/bool-logic` | ✅ | ✅ |
| `structure/nested-call` | ✅ | ✅ |
| `structure/positional-call` | ✅ | ✅ |
| `structure/import/*` | ✅ | ✅(load 合并 AST 后编译) |
| `examples/errors/*` | ✅(非零退出) | 同 tree 语义(编译期/运行期诊断) |
核心金样例双后端已对齐;后续可扩展 Op、优化与更好的调试信息。
---
## 5. CLI
```bash
marqdo run FILE --backend tree # 默认
marqdo run FILE --backend bytecode
marqdo run FILE --dump-bytecode # 反汇编后仍可按 backend 执行
```
---
## 6. 非目标(本原型)
优化、寄存器分配、GC、与树遍历指令级调试对齐、独立 sema IR。
-50
View File
@@ -1,50 +0,0 @@
# 调用实参:具名与位置
| | |
|---|---|
| 状态 | 已定(v0.1 增补) |
| 日期 | 2026-08-04 |
| 相关 | [markdown-mapping.md](markdown-mapping.md) · [keywords.md](keywords.md) |
---
## 1. 目标
`>` 调用同时支持:
| 形式 | 示例 | 说明 |
|------|------|------|
| **具名**(保留) | `> 问候 谁=Marqdo` | `名=值`;值可含空格(至下一 `名=`) |
| **位置**(新增) | `> 问候 Marqdo` | 按形参声明顺序绑定 |
二者可混用:位置实参按「尚未被具名绑定的形参」从左到右填充。具名不可绑定同一形参两次;位置实参不得出现在「已出现具名实参」之后(对齐常见「位置在前、关键字在后」习惯)。
---
## 2. 文法(调用尾部)
```
call_tail ::= callee arg*
arg ::= named | positional
named ::= ident '=' value
positional ::= value_token
```
- `value`(具名右侧):可含空格与 `` `var` `` 插值,直到下一个 `ident=` 边界。
- `value_token`(位置):空白分隔的一个词法单元——数字、`` `名` ``、标识/文本词;**不含空格**。多词字符串请用具名,例如 `> print text=Hello World!`。
- 内置 `print` 形参名为 `text`:`> print Hi` 与 `> print text=Hi` 等价。
---
## 3. 绑定算法
1. 收集具名 → 映射;冲突则报错。
2. 按函数形参表顺序:若具名已提供则用之,否则取下一个位置实参。
3. 位置实参有余、或必填形参仍缺 → 报错(内置 `input` 的 `prompt` 可缺省)。
4. 用户函数:额外具名键仍写入调用环境(便于扩展);位置实参不可超过形参数目。
---
## 4. 金样例
见 `examples/structure/positional-call.mq.md` 与更新后的 `examples/structure/import/`。
-28
View File
@@ -1,28 +0,0 @@
# 可执行面与叙述面
| | |
|---|---|
| 状态 | 与 mapping v0.1 / keywords 对齐 |
| 日期 | 2026-08-04 |
---
## 三层
| 层 | 形态 | 角色 |
|----|------|------|
| **叙述面** | 无标记行 | 注释;内部标记无语义 |
| **Marqdo 可执行面** | 结构标记 + `*语句*` + `**返回**` | 本语言程序 |
| **外联面** | ` ```lang ` | 其它语言(FFI) |
输出属于可执行面里的**函数调用**(`> print …`),见 [keywords.md](keywords.md)。
---
## 语句 vs 返回 vs 输出
| 标记/形式 | 角色 | 是否架构级 |
|-----------|------|------------|
| `*…*` | 程序语句 | 是 |
| `**…**` | 返回值 | 是 |
| `> print …` | 打印副作用 | 否(内置函数) |
-174
View File
@@ -1,174 +0,0 @@
# Marqdo 实现依赖说明(Rust 参考解释器)
| | |
|---|---|
| 状态 | 已定 |
| 日期 | 2026-08-04 |
| 相关 | [ADR 0001](../adr/0001-implementation-language.md) · [interpreter 路线图](../roadmap/interpreter.md) |
---
## 1. 要不要 Flex / Bison?
### 结论:**不需要。** 主因不是「用了 Rust」,而是 **Marqdo 的语法形态 + 解释器并不绑定生成器。**
把两件事分开:
| 问题 | 答案 |
|------|------|
| 因为 Rust 才不用 Flex/Bison? | **否。** Flex/Bison 生成的是 C(也可接 C++)。若实现改成 **C++**,**仍然不建议**用它们做 Marqdo 主前端。 |
| 因为是解释器才不用? | **部分相关,但不是全部。** 解释器**需要**词法/语法阶段,但**不规定**必须用 Flex/Bison;手写递归下降是主流。即便将来做「编译到字节码/原生」,Marqdo 也因 Markdown 外壳而不适合整语言 Bison 化。 |
| 真正主因 | **Markup-as-Syntax**:源是 GFM 文档结构(标题/列表/强调/表格/行分类),不是 Cminusf 那种纯字符流文法。 |
| 工具 | 典型用途 | Marqdo 为何不用(与宿主语言无关) |
|------|----------|----------------------------------|
| **Flex** | 正则 → C 词法分析器 | 「词法」是 **行分类 + Markdown 标记**,不是经典 `id\|num\|op` 字符流 |
| **Bison** | Yacc 文法 → C LR 分析器 | 整体语法绑在 **GFM 块结构**上,硬写成单一 Bison 文法别扭且难与预览器对齐 |
[USTC 编译课 Lab1](https://ustc-compiler-2025.github.io/homepage/) 用 Flex/Bison,是因为对象语言是 **C 式源码的编译器**;换 C++ 写那个编译器也合理。
Marqdo 换 **Rust 或 C++** 都不改变「主前端不该是 Flex/Bison」这一判断。
**解释型语言同样需要词法与语法分析**,要的是阶段,不是这两个具体程序。
---
## 2. Marqdo 前端应怎样做(替代 Flex/Bison)
拆成三层,比「一个大 lexer/parser」更贴合宪法:
```
.mq.md 文本
│
├─① 行分类(自研) 无标记 → 注释;有标记 → 代码行
├─② GFM 块/行内(库) 标题、表、强调、列表结构
├─③ 行扫描补强(自研) 保留 '-' / '+';frontmatter `> file.mq.md`
└─④ Marqdo 语法(自研) 递归下降:Module/Fun/Stmt/Expr → AST
└─ 表达式子语言 可手写,或仅对 Expr 用 pest/nom
```
| 阶段 | 做法 | 对应编译学 |
|------|------|------------|
| ①③ | Rust 手写扫描 | 词法 / 扫描器 |
| ② | `pulldown-cmark` 或 `comrak` | 复用 GFM,避免自研表格/强调 |
| ④ | **手写递归下降**(推荐主路径) | 语法分析 |
| Expr(可选) | `pest`(PEG)或 `nom`(组合子) | 仅迷你表达式,不是整门语言 |
**不推荐**整门语言上 LALRPOP / rusty_lr / Bison 等价物作为 v1 主前端:Markdown 外壳 + 行语义会让文法极度别扭。若将来有「纯文本 Marqdo 方言」,再另议生成器。
---
## 3. 详细依赖清单(Rust)
### 3.1 工具链(开发机)
| 依赖 | 用途 | 安装 |
|------|------|------|
| **Rust**(stable,建议 ≥ 1.75) | 编译实现 | [rustup](https://rustup.rs/):`rustup default stable` |
| **Cargo** | 包与构建 | 随 rustup |
| **rustfmt / clippy** | 格式与静态检查 | `rustup component add rustfmt clippy` |
| **Git** | 版本管理 | 已有 |
**不要安装:** Flex、Bison、LLVM(v1 解释器不需要)。
(日后若做原生后端再开 ADR;与当前解释器无关。)
### 3.2 Cargo crate(建议写入根 `Cargo.toml` / workspace)
#### 必选(Phase I 树遍历解释器)
| Crate | 角色 | 说明 |
|-------|------|------|
| **pulldown-cmark** *或* **comrak** | GFM 事件/AST | 标题、列表、表格、emphasis/strong;Spike 已证明「库 + 行扫描」可行。二选一做 Spike 对比后钉死 |
| **thiserror** / **anyhow** | 错误类型 | 诊断与 CLI 报错 |
| **clap** | CLI | `marqdo run [path]` |
| **serde** + **serde_yaml** | 元信息 | 仅解析 frontmatter 中的 YAML **键值**;`> x.mq.md` 仍按**行**抽取(见 Spike) |
#### 强烈建议
| Crate | 角色 |
|-------|------|
| **camino** 或标准 `PathBuf` | 路径 |
| **indexmap** | 保序 map(模块导出等) |
#### 测试
| Crate | 角色 |
|-------|------|
| **rust 自带** `#[test]` | 单元测试 |
| **insta** 或手写金文件 | examples 期望 stdout 快照(可选) |
| **assert_cmd** / **predicates** | CLI 集成测试(可选) |
#### Phase II(字节码 VM,后加)
无强制新依赖;VM 以自研为主。可选:
| Crate | 角色 |
|-------|------|
| **num_enum** 等 | opcode 枚举(可选) |
#### 明确不引入(v1)
| 东西 | 原因 |
|------|------|
| flex / bison / lemon | 见 §1 |
| lalrpop / rusty_lr 作**整语言**前端 | 与 MD 外壳冲突;递归下降更合适 |
| llvm-sys / inkwell | 非解释器 v1 |
| 完整 Python 运行时嵌入 | 参考实现已定为 Rust,避免双运行时 |
### 3.3 表达式子语言(可选增强)
若手写 Expr 递归下降过痛,**仅**对 `` `a` + 1 == `b` `` 这类表达式引入其一:
| 选项 | 类型 | 何时用 |
|------|------|--------|
| **手写递归下降** | 无新依赖 | 默认;与全书一致、错误信息最好控 |
| **pest** | PEG 生成器 | 文法清晰、想要 `.pest` 文件时 |
| **nom** | 解析组合子 | 要零拷贝/细控时 |
整文件 `.mq.md` **不要**整份丢给 pest/nom。
---
## 4. 仓库布局(与依赖对应)
```
Cargo.toml # workspace 或单包
crates/marqdo/ # 或根包 marqdo
src/
main.rs / lib.rs
lex/ # 行分类、Token(自研,无 flex)
parse/ # 递归下降(自研,无 bison)
ast/
sema/
interp/ # Phase I
bytecode/ # Phase II
runtime/
tests/
examples/ # 金样例(已有)
spike/ # Python 风险探测存档(可保留,非运行时依赖)
```
开发命令示例:
```bash
cargo build
cargo test
cargo run -- run examples/structure/nested-call.mq.md
```
---
## 5. 与 Python Spike 的关系
| | Python `spike/` | Rust 参考实现 |
|--|-----------------|---------------|
| 角色 | 已验证 S1–S5 风险 | **正式**词法/语法/语义/解释器 |
| 是否运行时依赖 | 否 | 是 |
| 算法可迁移 | 行扫描、`split_front_matter`、导入正则 | 用 Rust 重写同算法 |
---
## 6. 一句话对照
- **需要:** 词法(行分类+标记)、语法(递归下降→AST)、语义、解释器/日后 VM。
- **不需要:** Flex、Bison、LLVM(v1)。
- **外部库只需:** Rust 工具链 + GFM crate(pulldown-cmark/comrak)+ CLI/错误/测试若干;表达式可选 pest/nom。
-76
View File
@@ -1,76 +0,0 @@
# 示例与测试布局
| | |
|---|---|
| 状态 | 已定 |
| 日期 | 2026-08-04 |
| 原则 | **示例即金样例**:`examples/**/*.mq.md` 由 `cargo test` / CI 跑通;`marqdo view` 也可直接浏览 |
---
## 1. 目录
```
examples/
README.md # 本树说明
structure/ # 代码基础结构(Markup 架构)
hello.mq.md
nested-call.mq.md # 原 index:嵌套函数 + 调用
positional-call.mq.md # 位置实参
branch.mq.md
loop.mq.md
collection.mq.md
import/
main.mq.md # 原 with-import
utils.mq.md
keywords/ # 关键字与内置名
print.mq.md
bool-logic.mq.md # True/False/None、and/or/not
errors/ # 期望失败(诊断文案稳定后再加金样例)
.gitkeep
```
Rust 集成测试:`tests/gold.rs` 扫描约定路径,比对 stdout。
---
## 2. 分类职责
| 类别 | 测什么 | 不测什么 |
|------|--------|----------|
| **structure** | `#`/`##`、形参、`>` 调用、`*`/`**`、`+`/`-`、表、导入、位置/具名实参 | 关键字边角 |
| **keywords** | `True`/`False`/`None`、`and`/`or`/`not`、`print`/`input` 约定 | 复杂控制流(可极简) |
| **errors** | 未定义名、实参错误、语法错误的诊断 | 成功路径 |
未单独建夹、但应覆盖的其它测试(放 `tests/` 单测或日后 `examples/runtime/`):
- **流水线调试**:`--dump-lines` / `--dump-ast` / `--trace-eval`
- **CLI**:默认 `index.mq.md`、退出码
- **view**:目录扫描、单文件页、执行区(见 [view.md](view.md))
- **模块图**:循环导入拒绝
---
## 3. 金样例约定
每个可执行 `.mq.md` 在 `tests/gold.rs`(或旁路 `.out` 文件)登记期望 stdout。
`errors/` 内文件登记期望 stderr 子串与非零退出码。
Frontmatter 可写:
```yaml
---
title: …
expect_stdout: |
line1
line2
---
```
(可选;v0 先以测试代码内嵌期望为主。)
---
## 4. 与 `view` 的关系
`marqdo view examples` 按上述文件夹生成侧栏索引;`structure` / `keywords` 为一级分组。
-163
View File
@@ -1,163 +0,0 @@
# 设计草案:机器生成的 YAML 清单(OKF 风格)
| | |
|---|---|
| 状态 | 草案(已采纳方向;修正「配置文件」误解) |
| 日期 | 2026-08-04 |
| 相关 | [OKF 调研](../research/okf-and-marqdo.md) |
| 取代 | 此前「YAML = 人手写的编译器配置 / frontmatter 契约」的表述 |
---
## 决策
Marqdo 项目中的 **YAML(及由其组成的 OKF 风格知识包)是工具自动生成的产物,不是给人填的配置文件。**
它的角色接近其它语言里由工具维护的**依赖与包元数据**,例如:
| 生态 | 类比(职责相近,不是语法相同) |
|------|--------------------------------|
| Rust | `Cargo.toml` / 解析后的依赖图(由源与清单共同推导,工具可改写) |
| Python | `requirements.txt`(常由解析/冻结生成) |
| Go | `go.mod` + `go.sum`(`go mod tidy` 维护) |
我们选择 **OKF 的形态**(Markdown + YAML frontmatter 的概念目录)来承载这份生成结果,从而一举两得:
1. **给编译器 / 包管理**:依赖图、模块身份、导出符号、版本锁定等可查询元数据
2. **给本项目文档**:同一份生成物可直接渲染为「项目知识目录」——模块说明、依赖关系、API 索引等**自动生成本项目文档内容**
**唯一手写真相**仍是 `.mq.md` 源文件正文。YAML 清单是派生工件;过时则重新生成,禁止当成第二套权威配置去手改(除非工具链明确支持的「生成后微调」流程,且须可复现)。
**与源 frontmatter 的分工**(见 [markdown-mapping.md](markdown-mapping.md)):源文件 `---` 块可含 `title` 等元信息,以及人手声明的跨文件导入行 `> other.mq.md`。那是**源上的导入声明**,不是工程依赖锁。工具仍应据此(及正文 `>` 调用)**生成** OKF 风格依赖/模块目录;不要把生成目录手改成权威。
---
## 纠正:它不是什么
| ❌ 不是 | ✅ 是 |
|--------|------|
| 人手维护的 `run` / `target` / 路径配置 | 从源码 **推导** 出的依赖与模块元数据 |
| 编译器「怎么跑」的 ini/配置替代品 | 解析、链接、文档站共用的 **生成清单** |
| 与正文平行的第二套程序描述 | 正文的 **投影**(projection):结构化、可查询、可渲染 |
执行方式(解释 / 检查 / 编译到某后端)由 **CLI、子命令或工程约定** 决定,不塞进这份 YAML 让人配置。
---
## 数据流
```
手写 .mq.md 源
(叙事 + 类型 + 函数 + 正文中的引用/导入)
│
▼
marqdo 工具链
· 解析正文 AST
· 收集 import / 链接 / 导出
· 解析依赖、锁定版本
│
├──────────────────────────────┐
▼ ▼
生成 OKF 风格清单 编译 / 类型检查 / 运行
(YAML + 概念 Markdown) (消费清单加速解析)
│
▼
自动生成本项目文档
(模块索引、依赖图、API 目录……)
```
- **源 → 清单**:单向派生;清单不得反向成为「唯一写依赖的地方」。
- **清单 → 文档**:OKF 包本身即可浏览;也可再生成站点/目录页。
- **清单 → 编译**:编译器可读生成结果以跳过重复发现,但语义仍以源为准;清单缺失时应能从源重建。
---
## 生成物长什么样(示意)
工程在构建或 `marqdo sync` 类命令后,可得到类似 OKF bundle 的目录(路径未定):
```
.marqdo/ # 或 docs/catalog/ 等 — 待 ADR
index.md # 生成:项目总览
modules/
cart.md # 生成:每个模块一个概念文档
prelude-list.md
deps/
lock.yaml # 生成:依赖锁定(机器向)
```
单个生成的概念文件可呈 OKF 形:
```yaml
---
type: Marqdo Module # 生成
title: cart
description: 购物车:行项目与总额
resource: src/cart.mq.md # 指向源文件
depends:
- prelude/list
- math/sum
exports: [Line, total]
generated:
by: "marqdo/0.1"
at: 2026-08-04T01:00:00Z
---
# cart
> 本页由 Marqdo 工具链根据 [`src/cart.mq.md`](../../src/cart.mq.md) **自动生成**,请勿手改。
## 依赖
- [prelude/list](../modules/prelude-list.md)
- [math/sum](../modules/math-sum.md)
## 导出
| 符号 | 种类 |
|------|------|
| `Line` | type |
| `total` | fn |
```
人要改行为或说明 → 改 `src/cart.mq.md`;再生成,文档与依赖清单一起更新。
---
## 与「代码即文档」的关系
Marqdo 有两层「文档」,不要混为一谈:
| 层 | 谁写 | 是什么 |
|----|------|--------|
| **源文档** | 人(及协助编写的 Agent) | `.mq.md`:程序本身,打开即读、即可跑 |
| **项目目录文档** | 机器 | OKF 风格 YAML/Markdown:从全项目源 **汇总** 的依赖、模块图、索引 |
前者消灭「实现与说明漂移」;后者消灭「仓库级总览靠手维护 README 目录」——总览从源自动长出,格式还对 Agent / 搜索友好(OKF)。
---
## 原则
1. **源为唯一权威** — 依赖与导出以 `.mq.md` 正文中的语言构造为准;YAML 是提取结果。
2. **生成、可复现** — 同一源树 + 同一工具版本 → 同一清单(允许时间戳等字段除外或规范化)。
3. **勿手改生成物** — 生成文件应带头注释或 `generated` 字段;CI 可校验「未提交脏生成」或「提交的生成与源一致」。
4. **OKF 形、Marqdo 义** — 文件形态对齐 OKF(`type`、链接、目录),词汇服务模块/依赖/导出,而不是照搬 BigQuery 概念类型。
5. **清单可删可再生** — 没有清单时,编译器仍须能直接从源工作(可能更慢);清单是缓存与文档面,不是语言语义的一部分。
---
## 待决问题(后续 ADR)
- [ ] 生成物落盘路径(例如 `.marqdo/` vs `docs/catalog/`)及是否提交进 git
- [ ] 单文件是否仍写入「生成型 frontmatter」,还是全部集中在工程级 OKF 包
- [ ] 与 `Cargo.toml` 式「可手写包身份(name/version)」的边界:是否允许极少量非生成的包清单,与全自动 OKF 目录如何分工
- [ ] `marqdo sync` / `marqdo doc` 命令的具体行为
- [ ] 是否沿用 OKF v0.2 的 `generated` / `sources` 字段描述溯源
---
## 结论
**YAML(OKF 风格清单)= 机器从 `.mq.md` 自动生成的依赖与项目元数据,并可据此自动生成本项目文档;不是人手填写的配置文件。**
人写源,工具写清单与目录文档;编译器与文档站共同消费生成物,语义始终回到源。
-84
View File
@@ -1,84 +0,0 @@
# Marqdo 关键字与内置名(v0 最小集)
| | |
|---|---|
| 状态 | 已定(前期够用) |
| 日期 | 2026-08-04 |
| 原则 | **英文**;参考 [Python](https://realpython.com/python-keywords/) 但远更少;控制流仍靠 Markdown 标记,不引入 `if`/`while`/`def` |
| 相关 | [markdown-mapping.md](markdown-mapping.md) |
---
## 1. 设计原则
1. **标记承担架构**:函数=`#`,分支=`+`,循环=`-`,返回=`**…**`,语句=`*…*`。因此 **不**把 `def`/`if`/`else`/`while`/`for`/`return` 做成关键字。
2. **英文标识**:内置与字面量用英文,便于工具高亮与国际协作。
3. **学 Python 的边界**:Python 3 里 [`print` / `input` 是内置函数,不是关键字](https://realpython.com/python-keywords/);布尔与空值是字面量关键字。Marqdo 同样区分 **关键字** vs **内置函数名**。
4. **宁少勿多**:前期只列执行 examples 所需;要加再进 ADR。
---
## 2. 关键字(词法保留,不可作变量名)
| 关键字 | 含义 | 备注 |
|--------|------|------|
| `True` | 布尔真 | 对齐 Python 大小写 |
| `False` | 布尔假 | |
| `None` | 空值 | |
| `and` | 逻辑与 | 表达式内 |
| `or` | 逻辑或 | |
| `not` | 逻辑非 | |
**本期不引入:** `if` `else` `elif` `while` `for` `def` `class` `return` `import` `pass` `break` `continue` `in` `is` `lambda` …
(`else` 分支臂仍用臂头单独的 `*` 标记,不是单词 `else`。)
---
## 3. 内置函数(可调用名,建议勿遮蔽)
| 名称 | 作用 | 调用示例 |
|------|------|----------|
| `print` | 写到 stdout(副作用) | `> print text=Hello` 或 `> print Hello`(位置实参,见 [call-arguments.md](call-arguments.md)) |
| `input` | 从 stdin 读一行(返回文本) | `*`name` = > input prompt=Name: *` |
参数约定(v0):
- `print`:具名实参 `text`(必填);日后可扩展 `end` 等。
- `input`:可选 `prompt`;返回用户输入字符串(不含换行)。
旧文档中的中文 `print` **废弃**,统一为 `print`。
---
## 4. 与 Markup 调用的关系
```markdown
# main
> print text=Hello World!
*`n` = 1*
+ `n` > 0
> print text=positive
+ *
> print text=other
```
- `>` 是**调用标记**(架构)。
- `print` 是**被调名字**(内置库)。
- 用户自定义 `# print` 会遮蔽内置(实现应警告)。
---
## 5. 标识符规则(摘要)
- 变量:行内 `` `name` ``;`name` 不可为上表关键字。
- 函数名:`#` 标题文本;建议 ASCII/英文,中文标题仍允许但内置名保持英文。
- 比较:`==` `>` `<` `>=` `<=`;逻辑:`and` `or` `not`。
---
## 6. 后续可增(未批准)
`len`、`str`、`int`、`float`、`range`;以及 `break`/`continue`(若循环需要)。增加前开短 ADR。
-211
View File
@@ -1,211 +0,0 @@
# Marqdo 语法映射 v0.1(Markup-as-Syntax)
| | |
|---|---|
| 状态 | 已定论(修订:语句 / 返回 / 输出职责分离) |
| 日期 | 2026-08-04 |
| 取代 | v0 中「`**`=输出、`*`=返回」 |
| 相关 | [code-vs-comment.md](code-vs-comment.md) · [return-hr-and-code-surface.md](return-hr-and-code-surface.md) |
Markdown **标记即语法**。输出**不是**语言架构原语,而是内置函数 **`print`**(英文;见 [keywords.md](keywords.md))。
---
## 1. 哲学
1. `.mq.md`:打开即文档,运行即程序。
2. **无标记行 = 叙述注释**(内部任何标记无语义)。
3. **可执行**靠标记:结构标记(`#` `>` `+` `-` 表…)与 **斜体语句** / **粗体返回**。
4. 作用域 = `#` 层数;入口 = `index.mq.md`。
---
## 2. 行首判别
跳过前导空白后:
| 首字符 | 分类 |
|--------|------|
| 普通文字 / 空 | **注释** |
| 标记字符 | **代码** |
标记含:`#` `*` `>` `+` `-` `` ` `` `|`、有序数字、围栏 `` ` ``、以及函数体内的分割线 `---` / `***`(见 §11)。
---
## 3. 映射总表(v0.1)
| 标记 | 语义 |
|------|------|
| `#` … `######` | 函数;层数 = 作用域 |
| 函数头下 `-` 纯名 | 形参 |
| 体内 `-` | 循环 |
| 体内 `+` 或 `1.` | 分支 |
| 分支臂头整行恰为 `*` | else |
| `> 函数 形参=实参` 或 `> 函数 实参` | 调用(具名 / 位置,见 [call-arguments.md](call-arguments.md)) |
| frontmatter `> path.mq.md` | 跨文件导入 |
| `*…*` | **程序语句**(绑定、表达式句、可写的调用句等) |
| `**…**` | **返回值**(架构级;函数结果) |
| 无标记行 | 注释 |
| GFM 表格 | 集合 |
| ` ```lang ` | 外联异种代码 |
| `---` / `***` | **可选**:框住分支/循环块(美化/分组;v0.1 不强制,见 §11) |
### 输出不是架构
| 错误(旧) | 正确(v0.1) |
|------------|--------------|
| `**Hello**` 表示打印 | `> print text=Hello` |
| 中文名 `输出`(已废弃) | 统一英文内置 `print` |
| 输出与返回抢粗体 | 粗体只表示 **返回** |
`print` / `input` 为内置函数,完整表见 [keywords.md](keywords.md)。
---
## 4. 语句、返回、调用
### 程序语句(斜体)
```markdown
*`x` = 1*
*`y` = `x` + 2*
```
行首已是结构标记的构造(`#` `>` `+` `-` `|`)**不必**再包一层斜体;斜体用于「一般语句」槽位。
### 返回值(粗体)
```markdown
# 加一
- n
**`n` + 1**
```
### 输出(内置函数 `print`)
```markdown
# main
> print text=Hello World!
```
### else 与斜体消歧
- 分支臂**第一行整行只有一个** `*` → else。
- `*中间有内容*` → 程序语句。
- `**…**` → 返回(与 else 无关)。
---
## 5. Frontmatter 与跨文件
同 v0:文件头 `---` 对为元信息;其中 `> file.mq.md` 为导入。
**函数体内的** `---` / `***` 不解释为 frontmatter(见 §11)。
---
## 6. 函数、作用域、提升
规则同 v0。推荐:
```markdown
# main
> print text=Hello World!
## 加问候
- 谁
**你好,`谁`**
```
(需要打印时对返回值再 `> print`,或直接 `> print`。)
形参 `- 名` → 体内 `` `名` ``。
---
## 7. 绑定与比较
| 写法 | 含义 |
|------|------|
| `*`x` = 1*` 或行首 `` `x` = 1 `` | 绑定(两种均允许;实现应统一) |
| `` `x` == 1 `` | 相等比较 |
v0.1 **推荐**绑定写在斜体语句内,以保持「语句=斜体」一致;行首 `` ` `` 仍合法以便表格右值绑定。
---
## 8. 分支与循环
分支(`+` / 有序),循环(`-`),语义同 v0。臂体内打印改为调用 `print`:
```markdown
*`x` = 0*
+ `x` > 0
> print text=正数
+ `x` < 0
> print text=负数
+ *
> print text=零
```
```markdown
- [果](篮子)
> print text=今天吃`果`
```
---
## 9. 集合(表格)
同 v0。`` `篮子` = `` 后接 GFM 表。
---
## 10. 求值入口
1. 加载 `index.mq.md` + 导入。
2. Pass1 收集定义。
3. Pass2 执行 `# main`。
4. `*` 语句、`**` 返回、`>` 调用、`+`/`-` 控制流、表绑定按语义执行;`> print` 写 stdout。
---
## 11. 分割线框住分支/循环(可选、非强制)
允许用 `---` 或 `***` 将分支/循环块视觉框起来,便于阅读:
```markdown
---
+ `x` > 0
> print text=正
+ *
> print text=其它
---
```
| 约定 | 说明 |
|------|------|
| v0.1 | **不强制**;无框同样合法 |
| 语义 | 若使用,框内仍是原列表语义;分割线本身不产生控制流 |
| 保留 | 日后若缺「块」类关键语法,可升级分割线为强制块边界 |
| 消歧 | 仅文件开头的 `---` 对 = frontmatter;函数体内成对/成段的 `---`/`***` = 可选框 |
---
## 12. v0.1 非目标
- break/continue、完整错误模型、静态类型、完整 FFI
- 强制分割线框
- 用 `*` 作无序列表符
---
## 13. 示例索引
见 [`examples/`](../../examples/)。
-73
View File
@@ -1,73 +0,0 @@
# 解释器流水线可视调试
| | |
|---|---|
| 状态 | 已定(开发期强制友好) |
| 日期 | 2026-08-04 |
| 参考 | [Crafting Interpreters — Scanning](https://www.craftinginterpreters.com/scanning.html)(先打 token)· [AstPrinter](https://craftinginterpreters.com/representing-code.html) · CLI `--dump-ast` 类实践 |
---
## 1. 目标
开发 `marqdo` 时,对任意 `.mq.md` 应能**分阶段看见**中间结果,避免黑盒;正式 `run` 默认安静,仅输出程序 `print` 的内容。
---
## 2. CLI 开关
```bash
marqdo run FILE [dumps...]
marqdo dump FILE --stage lines|tokens|ast|sema|all
```
| 标志 | 阶段 | 输出内容 |
|------|------|----------|
| `--dump-lines` | 行分类 | 每行:`LINE kind=Comment\|Code\|Blank` + 原文预览 |
| `--dump-tokens` | 词法 | Token 流:`type lexeme line:col` |
| `--dump-ast` | 语法 | S 表达式或缩进树(模块/函数/语句) |
| `--dump-sema` | 语义 | 作用域、导入图、提升后的符号表 |
| `--trace-eval` | 求值 | 进入/离开函数、绑定、分支臂选择、`print` 调用 |
| `--dump-bytecode` | 字节码 | 反汇编 `Program`(见 [bytecode.md](bytecode.md)) |
| `--backend tree\|bytecode` | 执行后端 | 默认 `tree`;`bytecode` 走栈式 VM |
| `--dump-all` | 以上全部 | 按管道顺序打印,段之间用横幅分隔 |
格式约定:
- 人类可读优先;段首统一:`=== marqdo: <stage> ===`
- 可选 `--dump-format=text|json`(json 后置,text 先做)
- 有 dump 时:若求值未实现,仍打印已实现阶段再以非 0 退出(便于 M1 只测 lines)
---
## 3. 横幅示例
```
=== marqdo: lines (examples/hello.mq.md) ===
1 Blank
2 Comment | # Hello World
3 Blank
4 Comment | 本程序调用...
5 Blank
6 Code | > print text=Hello World!
=== marqdo: end lines ===
```
---
## 4. 实现要点
- dump 逻辑放在 `src/debug/`(或各阶段 `fmt`),**不**与安静求值路径搅在一起。
- 每个阶段纯函数:`input → (artifacts, diagnostics)`,CLI 负责打印。
- 单测可断言 dump 字符串包含关键行(稳定子集),避免绑死全文格式。
---
## 5. 与里程碑
| 里程碑 | 必须可用的 dump |
|--------|-----------------|
| M1 | `--dump-lines`(及可选 tokens 雏形) |
| M2 | `--dump-ast` |
| M3–M4 | `--dump-sema`、`--trace-eval` |
| 全程 | `--dump-all` 随阶段增长自动变完整 |
-18
View File
@@ -1,18 +0,0 @@
# 记录:返回 / 语句 / 输出 / 分割线(决议)
| | |
|---|---|
| 状态 | 已决议(并入 mapping v0.1 + keywords) |
| 日期 | 2026-08-04 |
---
## 决议
1. **`*…*` = 程序语句**。
2. **`**…**` = 返回值**(架构级)。
3. **输出**用内置函数 **`print`**(英文),不是粗体,不是中文名。
4. **`---` / `***`**:可选框住分支/循环,不强制。
5. **否决**:无标记行 = 默认代码。
详见 [keywords.md](keywords.md)、[markdown-mapping.md](markdown-mapping.md)。
-152
View File
@@ -1,152 +0,0 @@
# 参考实现:技术选型分析(尚未拍板)
| | |
|---|---|
| 状态 | **分析中 — 未定案** |
| 日期 | 2026-08-04 |
| 说明 | 对比候选与约束;**不在本文直接开写实现仓库脚手架** |
上一版曾草率写「就用 TypeScript」——信息不足,已作废为定论。本文只做选型框架与对比,**最终实现语言须单开 ADR 确认后再动工。**
---
## 1. 我们在选什么
参考实现至少包含:
1. **读入** `.mq.md`(含 frontmatter 混合行)
2. **对齐 GFM** 的结构:标题、列表(`-`/`+`/`1.`)、强调、表格、围栏、链接
3. **Lower**:行首判别、标题树作用域、列表符语义、注释剥离
4. **两遍**:收集定义 + 导入 → 求值
5. **CLI** + **金样例测试**(`examples/`)
可选后期:字节码/编译、LSP、格式化。首版目标是**验证语法宪法**,不是上生产编译器。
---
## 2. 选型准则(按权重)
| 权重 | 准则 | 说明 |
|------|------|------|
| 高 | GFM 忠实度 | 表格、列表符、强调边界与 GitHub 预览一致,减少「能渲染不能跑 / 能跑不能渲染」 |
| 高 | 与宪法同构 | 易于表达「先 mdast/事件流,再 Marqdo AST」 |
| 高 | 测试与迭代速度 | 改语法宪法时能快速改测试 |
| 中 | 静态类型 / 可维护 AST | 长期改解释器不疼 |
| 中 | CLI 与打包 | 单二进制或 `npx`/等价体验 |
| 低 | 极致性能 | v0 样例很小 |
| 低 | 浏览器内运行 | 可后置 |
非准则:跟风、先写再选、与「生成 OKF」强绑某一云厂商。
---
## 3. 架构共性(与语言无关)
无论选哪门实现语言,流水线应一致:
```
.mq.md 文本
→ 前端:GFM 友好解析(或事件扫描)
→ Middle:Marqdo lower(行类、标题树、- / +、表、围栏)
→ Marqdo AST
→ 语义:导入图、提升、作用域
→ 后端:解释器(v0)/日后编译
→ 测试:examples → 期望 stdout
```
**前端可复用成熟 GFM 库,也可自研**;Middle/后端必须自研(这是语言本体)。
---
## 4. 候选对比
### A. TypeScript / Node + remark(mdast)
| 利 | 弊 |
|----|----|
| remark-gfm 与预览器语义接近;mdast 节点齐全 | 运行时依赖 Node;发行 CLI 需打包 |
| 迭代快、Vitest 方便 | 性能与「系统级编译器」形象偏软 |
| 与 Markdown 工具链同生态 | 需纪律:避免把业务写进插件泥潭 |
**适合:** 验证宪法、快速金样例。
**不自动等于最终生产编译器。**
### B. Rust + pulldown-cmark / comrak
| 利 | 弊 |
|----|----|
| 单静态二进制、性能好、适合日后正式编译器 | GFM 表格/细节与 GitHub 仍可能有差异,要对齐测试 |
| 类型与代数数据类型适合 AST | 前期迭代比 TS 慢 |
| 无 GC、可嵌入 | MD 生态碎片,选库要论证 |
**适合:** 中长期「真编译器」或与 TS 原型双轨。
**风险:** 首版就上 Rust 可能拖慢语法验证。
### C. Python + markdown-it-py / mistune
| 利 | 弊 |
|----|----|
| 原型极快 | 类型与工程化偏弱;双实现时易弃 |
| 文本处理友好 | 打包 CLI 体验一般 |
**适合:** 一次性语法实验。
**不推荐**作为唯一长期实现,除非团队强约束。
### D. Go + goldmark
| 利 | 弊 |
|----|----|
| 单二进制、部署简单 | 泛型/AST 表达力一般;MD 库选 goldmark 需 GFM 扩展评估 |
| 并发与工具链成熟 | 与 MD 研究生态联系弱于 JS |
**适合:** 工具型 CLI 优先的团队。
### E. 自研扫描器(任意语言)+ 仅用 GFM 做对照测试
| 利 | 弊 |
|----|----|
| 完全控制行首判别与 `+`/`-` 语义 | 重复实现表格/强调,易与渲染不一致 |
| 可强制「行分类优先于块解析」 | 工作量大 |
**适合:** 证明「行首判别」与 CommonMark 块结构冲突时的研究分支。
可与 A/B 组合:自研 lower,块结构仍喂给现成解析器。
---
## 5. 关键技术风险(与选语言正交)
1. **行首判别 vs 块解析器** — CommonMark 先成块再看内容;Marqdo 先看行类。可能需「行预分类再喂解析器」或「解析后按源位置重分类」。选型时要让候选语言/库能拿到**源行映射**。
2. **frontmatter 非纯 YAML** — `>` 导入行是扩展;不能整块丢给严格 YAML 解析器。
3. **`+` 与 `-` 列表** — 多数解析器都认,但 lower 必须保留**项目符字符**,不能只得「unordered list」。选库时验证 AST 是否保留 bullet type。
4. **`*` else vs `*返回*` vs 强调** — 依赖 inline 解析与「整行恰好一个 `*`」的行级规则并存。
以上 4 点应作为**选型验收用例**,写进 ADR:用最小样例在候选栈上 Spike,再定案。
---
## 6. 建议的决策流程(尚未执行)
1. **Spike(各 ≤0.5–1 日)**
- 候选 A:TS + remark-gfm — 能否区分 `-`/`+` bullet、解析单列表格、读 strong/emphasis。
- 候选 B:Rust + comrak/pulldown — 同上。
- (可选)C 或 D 若团队有偏好再做。
2. **对照验收用例**(固定):`examples/hello.mq.md`、`branch.mq.md`(`+`)、`collection.mq.md`(表)、含 `> x.mq.md` 的 frontmatter 行。
3. **出 ADR**:选定「验证期实现」与(可选)「生产目标实现」是否同一语言。
4. **再**建仓库脚手架与测试——禁止在 ADR 前默认生成 `package.json` / `Cargo.toml` 当既成事实。
---
## 7. 当前态度(非正式投票)
| 阶段 | 倾向(待 Spike 验证) |
|------|------------------------|
| 语法验证期 | 更可能是 **TypeScript + remark**(快、GFM 近) |
| 长期生产编译器 | **开放** Rust / Go,不与验证期绑定 |
**本文不授权开始实现。** 确认 Spike 计划或直接指定语言后,再写 `adr/0001-implementation-language.md`。
---
## 8. 与「无标记 = 注释」的关系
实现必须先做**行分类**(见 [code-vs-comment.md](code-vs-comment.md)),再谈用何种语言写分类器。选型不能假设「整文件都是可执行代码」。
-119
View File
@@ -1,119 +0,0 @@
# `marqdo view` — 源结构浏览器
| | |
|---|---|
| 状态 | 已定(实现中) |
| 日期 | 2026-08-04 |
| 相关 | [examples-and-tests.md](examples-and-tests.md) · [pipeline-debug.md](pipeline-debug.md) · AST(`src/ast.rs`) |
---
## 1. 动机
`.mq.md` 既是文档也是程序。需要一种**可读渲染**,而不仅是纯文本或 `run` 的 stdout:
- 按语法树展示函数、分支、循环、调用、返回;
- 同页展示**执行结果**;
- 支持打开**单个文件**或**文件夹**(扫描全部 `.mq.md` + 结构索引)。
---
## 2. CLI
```bash
marqdo view [PATH] [--port PORT] [--host HOST] [--no-open]
```
| 参数 | 默认 | 说明 |
|------|------|------|
| `PATH` | `.` | `.mq.md` 文件,或目录(递归扫描 `*.mq.md`) |
| `--port` | `7429` | HTTP 端口 |
| `--host` | `127.0.0.1` | 仅本地 |
| `--no-open` | 关 | 不尝试打开系统浏览器 |
示例:
```bash
marqdo view examples/structure/hello.mq.md
marqdo view examples
marqdo view examples/keywords --port 8080
```
启动后打印 `http://127.0.0.1:7429/`,阻塞直至 Ctrl+C。
---
## 3. 信息架构
### 3.1 目录模式
```
┌─────────────┬──────────────────────────────────┐
│ 索引 │ 选中文件 / 欢迎页 │
│ structure/ │ │
│ hello │ [源码结构] [执行结果] [原始文本] │
│ branch │ │
│ keywords/ │ │
└─────────────┴──────────────────────────────────┘
```
- 侧栏:相对 `PATH` 的目录树;只列出 `.mq.md`。
- 点击文件:主区切换为该文件的三栏/三节视图。
### 3.2 单文件模式
无侧栏列表(或仅当前文件);主区同「选中文件」视图。仍提供「执行」结果。
---
## 4. 主区三节
### 4.1 源码结构(AST 渲染)
不依赖浏览器 Markdown 猜测语义,而用服务端已解析的 AST:
| AST 节点 | 视觉 |
|----------|------|
| `Function` | 卡片:标题层级、形参芯片、子函数嵌套;**中间的注释行仍展示**(来自源行分类,不在 AST 内) |
| `Stmt::*` | 绑定 / 返回 / 调用 / 分支 / 循环;表达式用**表面语法**(如 `` `x` > 0 ``),不用 Debug |
样式:清晰分区,避免「通用仪表盘」堆砌;结构层级一眼可读。
### 4.2 执行结果
服务端对该文件跑与 `marqdo run` 相同的管线,**捕获 stdout/stderr** 与退出状态,展示在「输出」区。
含 `input` 的程序:view 中标注「需交互,未在 view 执行」或提供只读说明(v0:跳过/失败信息)。
### 4.3 原始文本
等宽展示源文件;可选行分类着色(Code / Comment / Blank),与 `--dump-lines` 一致。
---
## 5. HTTP API(实现细节)
| 方法 | 路径 | 含义 |
|------|------|------|
| `GET` | `/` | 索引 HTML |
| `GET` | `/file?path=…` | 单文件页(path 相对根,防 `..` 逃逸) |
| `GET` | `/api/tree` | JSON 文件树 |
| `GET` | `/api/file?path=…` | JSON:`{ source, ast_html 或 ast_json, stdout, stderr, ok }` |
v0 可全部服务端渲染 HTML,API 可选。
安全:根目录锁死为 CLI 给定的 `PATH`(若为文件则其父目录为根、仅一文件);拒绝根外路径。
---
## 6. 依赖
本地同步 HTTP 即可(如 `tiny_http`),无强制前端构建;HTML/CSS/少量 JS 内嵌于 Rust。
---
## 7. 验收
1. `marqdo view examples/structure/hello.mq.md` 显示结构 + `Hello World!` 输出。
2. `marqdo view examples` 侧栏含 `structure/` 与 `keywords/` 分组。
3. 分支/循环样例在结构区可区分臂与循环体。
4. 路径逃逸被拒绝。
-86
View File
@@ -1,86 +0,0 @@
# 开发环境配置(Rust 参考解释器)
| | |
|---|---|
| 状态 | M0 |
| 相关 | [dependencies.md](design/dependencies.md) · [interpreter.md](roadmap/interpreter.md) |
---
## 1. 必备软件
| 软件 | 要求 | 检查 |
|------|------|------|
| Rust + Cargo | stable,建议 ≥ 1.81(本机验证过 1.81) | `rustc --version` / `cargo --version` |
| Git | 任意近期版本 | `git --version` |
安装 Rust(若尚未安装):
- 官方:[https://rustup.rs/](https://rustup.rs/)
- Windows:下载 `rustup-init.exe`,按提示安装后**重新打开终端**
本仓库可选 `rust-toolchain.toml`(钉 1.81.0)。若本机无 `rustup`、但已有匹配的 `rustc`/`cargo`,也可直接开发。
**不需要:** Flex、Bison、LLVM、Node/npm(实现栈为 Rust)。
---
## 2. 获取代码与构建
```bash
git clone https://github.com/cflmy/marqdo.git
cd marqdo
cargo build
cargo test
cargo run -- run examples/structure/hello.mq.md
```
当前 M0:`run` 会读入文件并明确报错「evaluation not implemented」(脚手架,非静默假成功)。
> 若 `cargo build` 报 `edition2024` / 过新 crate:仓库已对 `clap` 等做兼容钉扎(见 `Cargo.toml`);请使用附带的 `Cargo.lock`,勿盲目 `cargo update` 到最新 major。
---
## 3. 推荐组件
```bash
rustup component add rustfmt clippy # 若使用 rustup
cargo fmt
cargo clippy --all-targets
```
代理下拉 crate(可选,与 git 推送类似):
```bash
# Windows PowerShell 示例
$env:HTTPS_PROXY="http://127.0.0.1:7897"
$env:HTTP_PROXY="http://127.0.0.1:7897"
cargo build
```
或配置 `%USERPROFILE%\.cargo\config.toml`:
```toml
[http]
proxy = "http://127.0.0.1:7897"
```
---
## 4. 目录约定
| 路径 | 含义 |
|------|------|
| `src/lex` | 行分类 / 词法(自研) |
| `src/parse` | 递归下降语法 |
| `src/diagnostics` | 诊断 |
| `examples/` | 金样例(宪法) |
| `spike/` | 旧 Python 风险探测,非运行时依赖 |
| `doc/` | 设计与路线图 |
---
## 5. 下一里程碑
见 [interpreter.md](roadmap/interpreter.md):M1 词法·行分类与最小 AST。
-215
View File
@@ -1,215 +0,0 @@
# 调研:Google Open Knowledge Format(OKF)与 Marqdo
| | |
|---|---|
| 状态 | 调研笔记 |
| 日期 | 2026-08-04 |
| 对象 | [OKF v0.2](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md) |
| 公告 | [v0.1 介绍](https://cloud.google.com/blog/products/data-analytics/how-the-open-knowledge-format-can-improve-data-sharing) · [v0.2 trust signals](https://cloud.google.com/blog/products/data-analytics/okf-v0-2-adds-trust-signals) |
---
## 1. OKF 是什么
**Open Knowledge Format(开放知识格式)** 是 Google Cloud 于 2026 年 6 月发布的厂商中立开放规范(Apache 2.0)。它把「LLM Wiki」模式形式化为可移植格式:用**目录树中的 Markdown 文件 + YAML frontmatter** 表示组织知识(表结构、指标、API、操作手册等),供人类与 AI Agent 共同阅读、交换与维护。
一句话定位:
> 知识应活在**格式**里,而不是专有服务或散落的非结构化文本里。
### 核心形态
```
bundle/
index.md # 可选:目录索引(渐进披露)
log.md # 可选:变更历史
concepts/.../*.md # 每个概念一个 Markdown 文件
```
每个概念文件:
```yaml
---
type: Metric # 唯一必填
title: Monthly Active Users
description: ...
tags: [product, growth]
sources: [...] # v0.2:出处
generated: {...} # v0.2:谁生成的
verified: {...} # v0.2:谁验证的
status: stable # v0.2:生命周期
stale_after: 2026-12-01 # v0.2:过期日
---
# 正文(自由 Markdown)
指标定义为……
```
- **Concept ID** = 相对路径去掉 `.md`
- **链接** = 普通 Markdown 链接,形成可遍历关系图
- **无中心 schema registry**;未知 `type` 必须被优雅降级处理
### 设计三原则(官方表述)
1. **Minimally opinionated** — 只强制互通所需的最小公约;其余留给生产者。
2. **Producer / consumer independence** — 写知识的人(或 Agent)与读知识的 Agent/工具解耦;格式即契约。
3. **Format, not platform** — 不绑定云、数据库、模型或 Agent 框架;`cat` 能读,`git clone` 能分发。
### v0.2 新增:五类信任信号
当知识主要由 Agent **持续生成**时,纯 Markdown 不够。v0.2 把下列问题变成 frontmatter 一等字段:
| 问题 | 机制 |
|------|------|
| 从何而来? | `sources`(出处 + 可信度信号,不作统一打分) |
| 该信多少? | `generated` / `verified` → 推导 trust tier(未验证 / 机器确认 / 人工审核) |
| 是否仍真? | `stale_after`(绝对日期,非相对 TTL) |
| 是否现行? | `status`: `draft` → `stable` → `deprecated` |
| 数字是否按约定算出? | 概念类型 `Attested Computation`:executor 跑计算出 receipt,**非 LLM** 的 attester 核验 |
---
## 2. OKF 与 Marqdo:相邻,但不等同
| 维度 | OKF | Marqdo |
|------|-----|--------|
| 本质 | **知识交换格式** | **编程语言** |
| 文件角色 | 描述资产与概念的文档 | 可执行程序 = 可渲染文档 |
| 机器侧 | 解析 metadata、遍历链接、过滤信任 | 解析、类型检查、求值/编译 |
| Markdown 地位 | 载体与呈现层 | **语法表层的一部分**(源即 Markdown) |
| 成功标准 | 跨组织互通、Agent 可策展 | 严肃编程能力 + 阅读体验同时成立 |
OKF 回答:「人和 Agent 如何**共享与信任知识**?」
Marqdo 回答:「程序如何**本身就是知识**,且仍能运行?」
因此借鉴应落在**表示哲学与工程约束**,而不是照搬「知识目录」产品形态。
---
## 3. 值得借鉴的设计点
### 3.1 后缀与生态搭便车 — 已采纳
OKF 坚持「就是 Markdown」:GitHub 渲染、编辑器预览、静态站、搜索索引零摩擦。
**Marqdo 对应决策:源文件后缀为 `.mq.md`。**
- `.md` 确保通用 Markdown 渲染器开箱可用
- `.mq` 前缀声明这是 Marqdo 源,而非普通文档
- 与 OKF「格式优先于平台」一致:可读性不依赖自研 viewer
### 3.2 最小强制面(Minimally opinionated)
OKF 只强制 `type`;其余可选,未知字段保留不拒绝。
**对 Marqdo 的启发:**
- 语言的「文档面」与「程序面」之间,划清**硬语法**与**散文**
- 第一版语法宜小:标题层级、声明、表达式……先钉死互通/可执行最小集
- 扩展用约定或可选 frontmatter,避免一上来造完整注解宇宙
### 3.3 生成式 YAML / OKF 清单 — 已采纳方向(已修正)
OKF 用 YAML frontmatter 承载「可查询元数据」。Marqdo **借鉴其形态**,但职责不同:
**YAML(OKF 风格知识包)由工具从 `.mq.md` 自动生成,不是人手写的配置文件。**
详见 [`design/generated-yaml-manifest.md`](../design/generated-yaml-manifest.md)。
| | |
|--|--|
| 类比 | 其它语言中由工具维护的依赖描述(如 `Cargo.toml` / `requirements.txt` 所承担的那类角色) |
| 形态 | OKF:概念目录 + YAML frontmatter + Markdown 正文 |
| 用途 | ① 编译器/包管理消费依赖图与导出 ② **自动生成本项目文档**(模块索引、依赖关系等) |
| 权威 | 始终是手写 `.mq.md`;清单可删、可重建 |
```
.mq.md 源(人写)
→ marqdo 工具链
→ 生成 OKF 风格清单(YAML + 概念页)
→ 供编译解析,并渲染为项目目录文档
```
执行方式等运行参数不放进该 YAML 当配置;由 CLI / 子命令决定。
程序本体(类型、函数)只活在源正文里。
### 3.4 路径即身份,链接即关系
Concept ID = 路径;关系 = Markdown 链接;目录 = 渐进披露(`index.md`)。
**对模块系统的启发:**
- 文件路径可成为模块身份的一部分(类比 OKF concept ID)
- `import` / 交叉引用尽量与 Markdown 链接同构,使「读文档跳转」与「解析依赖」共用一种边
- 大型程序按「书的章节」组织目录,而不是扁平包名墙
### 3.5 生产者 / 消费者分离
同一 bundle:人手写、Agent 生成、管道导出,均可被另一 Agent 或 UI 消费。
**对 Marqdo 工具链:**
- 解析器、渲染器、求值器、LSP 都是**消费者**;源格式是唯一契约
- 允许 Agent 协助编写 `.mq.md`,但语言必须对「纯手写」同样友好
- 不把语义锁进某一 IDE 或云服务
### 3.6 信任与 attestation(中长期)
OKF v0.2 的 Attested Computation:批准的算法 + 确定性核验,防止 Agent「随口报数」。
**远期可借鉴(非 v0 范围):**
- 文档中嵌入的「可运行示例」是否经过核验执行?
- 渲染出的结果是否带来源与 receipt?
- Agent 生成的 Marqdo 模块如何标注 `generated` / `verified`?
这强化「文档中的数字/行为与真实执行一致」——与 Marqdo「同一份真相」高度同向。
### 3.7 规范本身的克制
OKF 规范强调:一页纸能讲清 v0.1 的互通面;v0.2 只**加词汇、不加强制规则**。
**对 Marqdo 文档文化:**
- ADR 记录否决项
- 语法草案保持短小、可验证的 conformance 描述
- 版本演进优先加法兼容,避免随意破坏「已是有效程序」的源文件
---
## 4. 不应照搬之处
1. **OKF 不是语言** — 其 body 是自由散文;Marqdo body 必须有严格可执行语义。不能停在「Markdown 知识库」。
2. **无中心 type 注册** 适合知识目录;编程语言的类型系统需要更强的一致性与检查规则。
3. **`Attested Computation` 的 executor/attester** 面向数据平台查询核验;Marqdo 若引入类似机制,应长在「测试 / 示例求值 / 再现构建」上,而不是 BigQuery 收据模型。
4. **保留文件名**(`index.md` / `log.md`)可参考,但是否占用需在模块设计里单独 ADR,避免与源文件约定冲突。
---
## 5. 建议纳入 Marqdo 设计议程的议题
来自本次调研、建议在 `design/` 或 `adr/` 中跟进:
1. **`.mq.md` 的双重解析模型** — Markdown CST 与 Marqdo AST 如何共享同一文本、何处分叉。
2. **生成式 OKF 清单的落盘与命令** — 路径、是否提交 git、`sync`/`doc` 行为(方向已采纳,见 [design/generated-yaml-manifest.md](../design/generated-yaml-manifest.md))。
3. **正文中的依赖声明语法** — import / 链接如何写出,供工具提取进生成清单。
4. **Agent 友好但不 Agent 绑定** — 源格式对 LLM 可写,语义对确定性工具可检。
5. **可渲染结果的 attestation(后期)** — 文档内求值结果的可验证性。
---
## 6. 参考链接
- 规范:[okf/SPEC.md](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md)(v0.2)
- 仓库:[GoogleCloudPlatform/knowledge-catalog](https://github.com/GoogleCloudPlatform/knowledge-catalog/tree/main/okf)
- 博客:[Introducing OKF](https://cloud.google.com/blog/products/data-analytics/how-the-open-knowledge-format-can-improve-data-sharing)
- 博客:[OKF v0.2 trust signals](https://cloud.google.com/blog/products/data-analytics/okf-v0-2-adds-trust-signals)
---
## 7. 结论
OKF 证明了一条与 Marqdo 同向的产业判断:**人类可读的 Markdown 可以成为机器与 Agent 的一等交换面**,前提是约定足够小、足够稳,并把信任做成可查询字段而非口头保证。
Marqdo 比 OKF 多走一步:Markdown 不仅是知识的容器,更是**程序的表面语法**。我们借鉴 OKF 的形态,用作**从源自动生成的依赖清单与项目目录文档**(而非人手配置);同时借鉴「格式而非平台」、路径/链接身份、以及(远期)provenance。语言设计必须单独完成——**可渲染不等于可执行,可执行才是 Marqdo 的终点。**
-178
View File
@@ -1,178 +0,0 @@
# Marqdo 参考实现:正经解释器路线图
| | |
|---|---|
| 状态 | 已采纳方向 |
| 日期 | 2026-08-04 |
| 目标 | `marqdo run path/to/index.mq.md` 得到真实执行结果;非演示玩具 |
| 相关 | [markdown-mapping.md](../design/markdown-mapping.md) · [ADR 0001](../adr/0001-implementation-language.md) · [USTC 编译课 2025](https://ustc-compiler-2025.github.io/homepage/) |
---
## 1. 为何是解释器,而不是 USTC 式「编译到机器码」
[USTC《编译原理与技术》2025](https://ustc-compiler-2025.github.io/homepage/) 的实验链是经典**编译器**路径:
```
源码 → 词法(Flex) → 语法(Bison) → AST
→ 语义 / Light IR → 优化 → 后端(龙芯汇编等)
```
这条路适合 Cminusf 一类「最终变成机器指令」的语言。Marqdo 的产品形态是:
- 源即 Markdown 文档,**打开即读、运行即算**;
- 首要交付是 **从 `index.mq.md` 得到求值结果**(stdout、返回值、模块图),不是龙芯/ x86 二进制;
- 语法表面是 Markup-as-Syntax,前端与传统正则+Bison 不同,但**中后端的编译学知识仍然全部用得上**。
因此:
| USTC / 龙书阶段 | Marqdo 解释器中的对应 |
|-----------------|------------------------|
| 词法分析 | **行分类 + 标记词法**(无标记=注释;`#`/`*`/`**`/`>`/`+`/`-`/表…) |
| 语法分析 | **结构解析 → Marqdo AST**(可递归下降;不必上 Bison,除非日后自研纯文本方言) |
| 语义分析 | 作用域、提升、导入、形参绑定、类型(可后置) |
| 中间代码 | **可选**:先树遍历;第二期再降到**字节码** |
| 优化 / 目标代码 | **非 v1 目标**;日后若要可另开「编译后端」ADR |
**结论:做正经解释器 = 把编译前端做扎实 + 把运行时做完整;不是跳过词法语法,也不是一上来 LLVM。**
权威地图见 [Crafting Interpreters — A Map of the Territory](https://craftinginterpreters.com/a-map-of-the-territory.html):用户眼里的「解释器」内部往往仍含编译到字节码(如 CPython);树遍历是第一期,字节码 VM 是第二期。
---
## 2. 推荐总体架构
```
index.mq.md (+ 导入的 .mq.md)
│
▼
┌───────────────────┐
│ 0. 源加载 / 模块图 │ frontmatter `> a.mq.md` → 依赖图
└─────────┬─────────┘
▼
┌───────────────────┐
│ 1. 词法·行分类 │ 注释行丢弃语义;代码行 → Token 流
│ (+ MD 块辅助) │ pulldown-cmark/comrak;+/- 靠行扫描
└─────────┬─────────┘
▼
┌───────────────────┐
│ 2. 语法分析 │ Token/块 → Marqdo AST
│ (递归下降) │ Module / Fun / Stmt / Expr / Branch / Loop …
│ │ **不用 Flex/Bison**(见 dependencies.md)
└─────────┬─────────┘
▼
┌───────────────────┐
│ 3. 语义·绑定 │ Pass1: 收集函数(提升)+ 导入合并
│ │ 作用域链、形参、未定义名诊断
└─────────┬─────────┘
▼
┌───────────────────┐
│ 4a. 树遍历解释器 │ ← Phase I(必须先完成,跑通全部 examples)
│ 或 │
│ 4b. 字节码编译+VM │ ← Phase II(性能与「更像真语言实现」)
└─────────┬─────────┘
▼
stdout / 返回值 / 退出码
```
Phase I 对齐 Crafting Interpreters 的 **jlox(树遍历)**;Phase II 对齐 **clox(字节码 VM)**(见 [Chunks of Bytecode](https://craftinginterpreters.com/chunks-of-bytecode.html))。这是 Python/Ruby/Lua 主实现走过的正经路径,不是玩具捷径。
---
## 3. 各阶段「做满」的标准(反玩具清单)
### Phase 0 — 工程骨架(正式包,不是 `spike/`)
- 包名:`marqdo`(`src/marqdo/` 或 `marqdo/`)
- CLI:`marqdo run <file.mq.md>`,默认找目录下 `index.mq.md`
- 诊断:带文件名、行号、列号
- 测试:每个 `examples/*.mq.md` 有期望 stdout(金样例);CI 可跑
### Phase I — 可运行的语言核心(树遍历)
必须全部为真实现,禁止「正则特判 hello」:
1. **词法 / 行分类**:注释与代码严格分离。
2. **语法 → AST**:函数、形参、`*` 语句、`**` 返回、`>` 调用、`+` 分支、`-` 循环、表格集合、绑定与 `==`。
3. **语义**:提升、嵌套作用域、`##` 私有、frontmatter 导入公有顶层。
4. **运行时**:环境、调用栈、值(文/数/表/记录)、内置 `print`。
5. **验收**:`examples/structure/*` 与 `examples/keywords/*` 全部 `marqdo run` 通过。
### Phase II — 字节码 VM(正经化)
- AST → 线性字节码(栈式 VM 即可,与 clox / [GoAWK 经验](https://benhoyt.com/writings/goawk-compiler-vm/) 同类)
- 控制流用跳转指令实现分支/循环
- 同一套金样例必须 bit-同结果(回归)
- 性能与可调试性(反汇编、栈跟踪)优于 Phase I
### Phase III — 语言完备(按需)
- 更完整表达式文法、错误模型、外联围栏 FFI
- 生成 OKF 依赖目录
- (可选)另一后端:编译到 Python/WASM——**另开 ADR**,不替代自研语义
---
## 4. 与 USTC Lab 的知识复用(学什么、不搬什么)
| 课程内容(摘要) | Marqdo 用法 |
|------------------|-------------|
| Lab1 词法/语法/AST | **直接对标** Phase I 前端;工具可自研递归下降,不必 Flex/Bison |
| Lab2 IR / 访问者 | Phase II 字节码 ≈ 轻量 IR;访问者可用于 AST→字节码 |
| Lab3 后端汇编 | **v1 不做**;解释器 VM 代替机器后端 |
| Lab4 优化 | Phase II 之后可选;解释器也可做常量折叠等 |
教材仍可读:龙书、陈意云《编译原理》、课主页参考书;解释器专项读 **Crafting Interpreters**(免费:[craftinginterpreters.com](https://craftinginterpreters.com/))。
---
## 5. 实现语言(本路线图默认)
**参考解释器:Rust**([ADR 0001](../adr/0001-implementation-language.md))。
- 词法/语法:**自研 + GFM crate**,不用 Flex/Bison([dependencies.md](../design/dependencies.md))。
- Python `spike/` 仅作风险探测与算法草稿。
- Phase I 树遍历、Phase II 字节码 VM 均在 Rust 中实现。
---
## 6. 目录规划(正式代码,非 spike)
```
Cargo.toml
crates/marqdo/ # 或根包
src/lex/ parse/ ast/ sema/ interp/ bytecode/ runtime/
tests/
examples/
spike/ # Python 存档,非运行时依赖
```
---
## 7. 近期里程碑(可执行顺序)
| 周序 | 交付 | 完成定义 |
|------|------|----------|
| M0 | 正式包 + CLI 空壳 + 金样例框架 | `marqdo run` 可调用;测试发现「未实现」 | ✅ |
| M1 | 词法·行分类 + 最小 AST | 单测覆盖注释/代码行 | ✅ |
| M2 | 解析:函数、输出调用、返回 | `hello` + `index` 金样例绿 | ✅ |
| M3 | 分支、循环、表格、绑定 | `branch`/`loop`/`collection` 绿 | ✅ |
| M4 | 导入与提升 | `with-import` 绿;**宣称 Phase I 达标** | ✅ |
| M5 | 字节码设计文档 + 原型 opcode | 核心金样例双后端一致;覆盖表见 [bytecode.md](../design/bytecode.md) | ✅ 原型 |
**Phase I 完成前,不宣称「语言已实现」。**
**仅 hello 特判通过,不算完成。**
---
## 8. 成功判据(产品级)
在仓库根或任意含 `index.mq.md` 的目录:
```bash
marqdo run examples/structure/nested-call.mq.md
# 或
marqdo run examples/structure/import/main.mq.md
```
输出与金样例一致;错误带位置;新增语法必须加金样例与单测。这才是「一门解释型语言」的最低合格线。
-15
View File
@@ -1,15 +0,0 @@
# Marqdo examples(金样例)
本目录即测试夹具,见 [doc/design/examples-and-tests.md](../doc/design/examples-and-tests.md)。
| 目录 | 内容 |
|------|------|
| [`structure/`](structure/) | 函数、调用、分支、循环、表、导入、位置实参 |
| [`keywords/`](keywords/) | `print`、布尔与 `and`/`or`/`not` |
| [`errors/`](errors/) | 期望失败(未定义名 / 未知函数 / 实参 / 语法) |
```bash
cargo test
marqdo run examples/structure/hello.mq.md
marqdo view examples
```
View File
Whitespace-only changes.
-12
View File
@@ -1,12 +0,0 @@
---
title: bad arity
---
# main
> needs_one
## needs_one
- x
> print text=`x`
-7
View File
@@ -1,7 +0,0 @@
---
title: unrecognized code line
---
# main
~not-valid-syntax
-7
View File
@@ -1,7 +0,0 @@
---
title: undefined variable
---
# main
> print text=`missing`
-7
View File
@@ -1,7 +0,0 @@
---
title: unknown function
---
# main
> no_such_fn x=1
-20
View File
@@ -1,20 +0,0 @@
---
title: 布尔与逻辑关键字
---
# main
*`a` = True*
*`b` = False*
+ `a` and not `b`
> print text=ok
+ *
> print text=fail
*`probe` = 1*
+ None
> print text=none-truthy
+ *
> print text=none-falsy
-9
View File
@@ -1,9 +0,0 @@
---
title: 内置 print
---
# main
> print text=named form
> print positional
-14
View File
@@ -1,14 +0,0 @@
---
title: 分支示例
---
# main
*`x` = 0*
+ `x` > 0
> print text=正数
+ `x` < 0
> print text=负数
+ *
> print text=零
-16
View File
@@ -1,16 +0,0 @@
---
title: 集合(表格)示例
---
# main
`篮子` =
| 果 |
|----|
| 苹果 |
| 梨 |
| 桃 |
- [果](篮子)
> print text=`果`
-5
View File
@@ -1,5 +0,0 @@
# Hello World
本程序调用内置函数 `print` 打印问候。注释里的 **粗体** 与 *斜体* 都不执行。
> print text=Hello World!
-14
View File
@@ -1,14 +0,0 @@
---
title: 跨文件导入示例
> utils.mq.md
---
# main
导入 `utils.mq.md` 后:用返回值绑定,再输出;并直接调用问候。
*`y` = > 加一 n=41*
> print text=`y`
> 问候 谁=Marqdo
-14
View File
@@ -1,14 +0,0 @@
---
title: 工具函数
description: 供 frontmatter > 导入;返回用粗体;副作用用输出函数
---
# 加一
- n
**`n` + 1**
# 问候
- 谁
> print text=你好,`谁`!
-25
View File
@@ -1,25 +0,0 @@
---
title: 循环示例
---
# main
倒数:
*`n` = 3*
- `n` > 0
> print text=`n`
*`n` = `n` - 1*
遍历篮子:
`篮子` =
| 果 |
|----|
| 苹果 |
| 梨 |
- [果](篮子)
> print text=今天吃`果`
-15
View File
@@ -1,15 +0,0 @@
---
title: Hello World
description: Recommended entry — nested fn; print builtin; bold return
---
# main
打印一句问候。`print` 是函数,不是语法架构;粗体只用于返回值。
> 问候 谁=World
## 问候
- 谁
> print text=Hello `谁`!
-19
View File
@@ -1,19 +0,0 @@
---
title: 位置实参
description: `> fn value` binds by parameter order; named form still works
---
# main
位置实参:
> 问候 Marqdo
具名实参(保留):
> 问候 谁=World
## 问候
- 谁
> print text=Hello `谁`!
-4
View File
@@ -1,4 +0,0 @@
.venv/
__pycache__/
*.pyc
.pytest_cache/
-14
View File
@@ -1,14 +0,0 @@
# Marqdo Spike(Python)
快速验收 ADR 0001 中的 S1–S5,**不是**完整解释器。
```bash
cd spike
python -m venv .venv
# Windows:
.\.venv\Scripts\activate
pip install -r requirements.txt
pytest -q
```
若需代理:`pip install -r requirements.txt --proxy http://127.0.0.1:7897`
-35
View File
@@ -1,35 +0,0 @@
# Spike 报告:Python + markdown-it-py(S1–S5)
| | |
|---|---|
| 日期 | 2026-08-04 |
| 状态 | **通过** |
| 命令 | `cd spike && pytest -q` → `6 passed` |
---
## 结果
| ID | 项 | 结果 | 备注 |
|----|----|------|------|
| S1 | `*` vs `**` | 通过 | `em_*` / `strong_*` 在 inline children 中 |
| S2 | `-` vs `+` | 通过 | **行扫描** `scan_bullets` 保留项目符;库只保证有 `bullet_list` |
| S3 | 单列表格 | 通过 | `table` 规则开启后可解析 |
| S4 | FM `---` vs 正文 `---` | 通过 | 自研 `split_front_matter` |
| S5 | FM 内 `> *.mq.md` | 通过 | 行正则抽取,不整块丢给严格 YAML |
---
## 对实现的含义
1. **行扫描是必需层**:`-`/`+` 消歧、frontmatter 导入、注释行分类,不宜只靠 MD 库 AST。
2. **markdown-it-py** 足够做块/inline 结构(标题、表、强调、列表);避免 `gfm-like` 默认 `linkify`(缺可选依赖会炸)。
3. Spike **不**等于选定长期实现语言;仅证明 Python 路径可验证宪法。参考实现可继续 Python,或再评 TS/Rust。
---
## 建议下一步
1. 将 ADR 0001 中 Spike 标为通过。
2. 拍板:参考实现是否 **继续 Python**(推荐,与 Spike 同栈)或换栈。
3. 再搭建正式包(`src/marqdo`)与 `marqdo run`,按 examples 金样例推进。
-78
View File
@@ -1,78 +0,0 @@
"""
Spike helpers: GFM parse via markdown-it-py + line-level bullet probe.
"""
from __future__ import annotations
import re
from dataclasses import dataclass
from markdown_it import MarkdownIt
from mdit_py_plugins.front_matter import front_matter_plugin
def make_md() -> MarkdownIt:
# Avoid gfm-like's linkify (needs optional linkify-it-py).
md = MarkdownIt("commonmark", {"html": False, "linkify": False})
md.enable(["table"])
md.use(front_matter_plugin)
return md
@dataclass
class BulletLine:
line_no: int
marker: str # "-" | "+" | "*" | "1."
text: str
_BULLET = re.compile(
r"^(?P<indent>\s*)(?P<marker>[-+*]|\d+\.)\s+(?P<text>.*)$"
)
def scan_bullets(source: str) -> list[BulletLine]:
"""Line-level scan: preserves '-' vs '+' regardless of MD library."""
out: list[BulletLine] = []
for i, line in enumerate(source.splitlines(), start=1):
m = _BULLET.match(line)
if not m:
continue
out.append(
BulletLine(line_no=i, marker=m.group("marker"), text=m.group("text"))
)
return out
def parse_tokens(source: str):
return make_md().parse(source)
def split_front_matter(source: str) -> tuple[str | None, str]:
"""
Split leading --- ... --- front matter from body.
Body-internal --- is left untouched.
"""
if not source.startswith("---"):
return None, source
lines = source.splitlines(keepends=True)
if not lines or lines[0].strip() != "---":
return None, source
for i in range(1, len(lines)):
if lines[i].strip() == "---":
fm = "".join(lines[1:i])
body = "".join(lines[i + 1 :])
return fm, body
return None, source
_IMPORT = re.compile(r"^>\s*(?P<path>\S+\.mq\.md)\s*$")
def front_matter_imports(fm: str) -> list[str]:
paths: list[str] = []
for line in fm.splitlines():
m = _IMPORT.match(line.strip())
if m:
paths.append(m.group("path"))
return paths
-3
View File
@@ -1,3 +0,0 @@
markdown-it-py>=3.0,<4
mdit-py-plugins>=0.4,<1
pytest>=8.0,<9
-104
View File
@@ -1,104 +0,0 @@
"""ADR 0001 Spike acceptance: S1–S5."""
from __future__ import annotations
from marqdo_spike import (
front_matter_imports,
parse_tokens,
scan_bullets,
split_front_matter,
)
def test_s1_emphasis_vs_strong():
"""S1: *a* vs **a** yield distinct inline marks."""
src = "hello *em* and **strong** end\n"
tokens = parse_tokens(src)
inlines = [t for t in tokens if t.type == "inline"]
assert inlines, "expected inline token"
children = inlines[0].children or []
types = [c.type for c in children]
assert "em_open" in types and "em_close" in types
assert "strong_open" in types and "strong_close" in types
assert any(c.type == "text" and c.content == "em" for c in children)
assert any(c.type == "text" and c.content == "strong" for c in children)
def test_s2_bullet_minus_vs_plus_line_scan():
"""S2: line scan distinguishes '-' (loop) vs '+' (branch)."""
src = """
# main
- loop item
+ branch item
"""
bullets = scan_bullets(src)
markers = [b.marker for b in bullets]
assert "-" in markers
assert "+" in markers
assert bullets[0].marker == "-"
assert bullets[1].marker == "+"
def test_s2_library_list_tokens_exist():
"""S2b: library at least parses both as lists (bullet char may need line scan)."""
src = "- a\n\n+ b\n"
tokens = parse_tokens(src)
assert any(t.type == "bullet_list_open" for t in tokens)
def test_s3_single_column_table():
"""S3: GFM single-column table."""
src = """
| 果 |
|----|
| 苹果 |
| 梨 |
"""
tokens = parse_tokens(src)
assert any(t.type == "table_open" for t in tokens)
texts = [t.content for t in tokens if t.type == "inline"]
flat = " ".join(texts)
assert "果" in flat
assert "苹果" in flat
assert "梨" in flat
def test_s4_front_matter_vs_body_hr():
"""S4: file-level --- front matter vs body --- frame."""
src = """---
title: demo
---
# main
---
+ `x` > 0
> 输出 内容=正
---
"""
fm, body = split_front_matter(src)
assert fm is not None
assert "title: demo" in fm
assert body.lstrip().startswith("# main")
assert "---" in body
assert "+ `x` > 0" in body
# Body still has its own ---; must not be eaten by FM splitter
assert body.count("---") >= 2
def test_s5_front_matter_mq_imports():
"""S5: `> file.mq.md` lines inside front matter."""
src = """---
title: main
> utils.mq.md
> lib/math.mq.md
---
# main
"""
fm, body = split_front_matter(src)
assert fm is not None
imports = front_matter_imports(fm)
assert imports == ["utils.mq.md", "lib/math.mq.md"]
assert "# main" in body
+6
View File
@@ -0,0 +1,6 @@
---
title: 解释器源码的放置位置
date: 2026-08-11
---
## 这里放置解释器源码
-208
View File
@@ -1,208 +0,0 @@
//! Marqdo AST (Phase I).
use crate::diagnostics::Span;
#[derive(Debug, Clone)]
pub struct Module {
pub imports: Vec<String>,
pub functions: Vec<Function>,
}
#[derive(Debug, Clone)]
pub struct Function {
pub name: String,
pub level: u8,
pub span: Span,
pub params: Vec<String>,
pub body: Vec<Stmt>,
pub children: Vec<Function>,
}
#[derive(Debug, Clone)]
pub enum Stmt {
Assign {
name: String,
value: Expr,
span: Span,
},
Return {
value: Expr,
span: Span,
},
/// Statement-form call (`> …`); return value discarded.
Call {
call: CallExpr,
span: Span,
},
Branch {
arms: Vec<BranchArm>,
span: Span,
},
While {
condition: Expr,
body: Vec<Stmt>,
span: Span,
},
ForEach {
item: String,
collection: String,
body: Vec<Stmt>,
span: Span,
},
}
#[derive(Debug, Clone)]
pub struct BranchArm {
pub condition: Option<Expr>, // None = else
pub body: Vec<Stmt>,
}
#[derive(Debug, Clone)]
pub struct CallExpr {
pub callee: String,
pub args: Vec<Arg>,
}
#[derive(Debug, Clone)]
pub enum Arg {
Positional(Expr),
Named { name: String, value: Expr },
}
#[derive(Debug, Clone)]
pub enum Expr {
Literal(Literal),
Var(String),
/// Text with embedded `` `var` `` segments.
Interp(Vec<InterpPart>),
Unary {
op: UnaryOp,
expr: Box<Expr>,
},
Binary {
op: BinaryOp,
left: Box<Expr>,
right: Box<Expr>,
},
Call(CallExpr),
List(Vec<Expr>),
}
#[derive(Debug, Clone)]
pub enum InterpPart {
Lit(String),
Var(String),
}
#[derive(Debug, Clone)]
pub enum Literal {
None,
Bool(bool),
Int(i64),
Text(String),
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum UnaryOp {
Not,
Neg,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum BinaryOp {
Add,
Sub,
Mul,
Div,
Eq,
Ne,
Lt,
Le,
Gt,
Ge,
And,
Or,
}
/// Pretty-print AST for `--dump-ast`.
pub fn format_ast_dump(path: &str, module: &Module) -> String {
let mut out = String::new();
out.push_str(&format!("=== marqdo: ast ({path}) ===\n"));
if !module.imports.is_empty() {
out.push_str(&format!("(imports {:?})\n", module.imports));
}
for fun in &module.functions {
dump_fun(&mut out, fun, 0);
}
out.push_str("=== marqdo: end ast ===\n");
out
}
fn dump_fun(out: &mut String, fun: &Function, depth: usize) {
let pad = " ".repeat(depth);
out.push_str(&format!(
"{pad}(fun level={} {:?} params={:?} @{}\n",
fun.level, fun.name, fun.params, fun.span
));
for stmt in &fun.body {
dump_stmt(out, stmt, depth + 1);
}
for child in &fun.children {
dump_fun(out, child, depth + 1);
}
out.push_str(&format!("{pad})\n"));
}
fn dump_stmt(out: &mut String, stmt: &Stmt, depth: usize) {
let pad = " ".repeat(depth);
match stmt {
Stmt::Assign { name, value, span } => {
out.push_str(&format!("{pad}(assign {name:?} {value:?} @{span})\n"));
}
Stmt::Return { value, span } => {
out.push_str(&format!("{pad}(return {value:?} @{span})\n"));
}
Stmt::Call { call, span } => {
out.push_str(&format!(
"{pad}(call {:?} {:?} @{span})\n",
call.callee, call.args
));
}
Stmt::Branch { arms, span } => {
out.push_str(&format!("{pad}(branch @{span}\n"));
for arm in arms {
out.push_str(&format!("{pad} (arm cond={:?}\n", arm.condition));
for s in &arm.body {
dump_stmt(out, s, depth + 2);
}
out.push_str(&format!("{pad} )\n"));
}
out.push_str(&format!("{pad})\n"));
}
Stmt::While {
condition,
body,
span,
} => {
out.push_str(&format!("{pad}(while {condition:?} @{span}\n"));
for s in body {
dump_stmt(out, s, depth + 1);
}
out.push_str(&format!("{pad})\n"));
}
Stmt::ForEach {
item,
collection,
body,
span,
} => {
out.push_str(&format!(
"{pad}(foreach {item:?} in {collection:?} @{span}\n"
));
for s in body {
dump_stmt(out, s, depth + 1);
}
out.push_str(&format!("{pad})\n"));
}
}
}
-453
View File
@@ -1,453 +0,0 @@
//! AST → bytecode Program.
use anyhow::{bail, Result};
use std::collections::HashMap;
use crate::ast::{
Arg, BinaryOp, CallExpr, Expr, Function, InterpPart, Literal, Module, Stmt, UnaryOp,
};
use crate::bytecode::{FnChunk, Op, Program};
use crate::value::Value;
struct FlatFun {
name: String,
parent: Option<usize>,
params: Vec<String>,
body: Vec<Stmt>,
children: Vec<usize>,
}
pub fn compile_module(module: &Module) -> Result<Program> {
let mut flat = Vec::new();
for fun in &module.functions {
collect_fun(fun, None, &mut flat);
}
if flat.is_empty() {
bail!("bytecode: no functions to compile");
}
let entry = flat
.iter()
.position(|f| f.name == "main" && f.parent.is_none())
.or_else(|| {
flat.iter()
.position(|f| f.parent.is_none() && f.params.is_empty())
})
.ok_or_else(|| anyhow::anyhow!("bytecode: no entry function"))?;
let mut functions = Vec::new();
for i in 0..flat.len() {
functions.push(compile_function(i, &flat)?);
}
Ok(Program { functions, entry })
}
fn collect_fun(fun: &Function, parent: Option<usize>, flat: &mut Vec<FlatFun>) -> usize {
let id = flat.len();
flat.push(FlatFun {
name: fun.name.clone(),
parent,
params: fun.params.clone(),
body: fun.body.clone(),
children: Vec::new(),
});
let mut child_ids = Vec::new();
for child in &fun.children {
child_ids.push(collect_fun(child, Some(id), flat));
}
flat[id].children = child_ids;
id
}
struct FnCompiler<'a> {
flat: &'a [FlatFun],
fn_id: usize,
chunk: FnChunk,
locals: HashMap<String, u8>,
}
fn compile_function(fn_id: usize, flat: &[FlatFun]) -> Result<FnChunk> {
let fun = &flat[fn_id];
let mut locals = HashMap::new();
for (i, p) in fun.params.iter().enumerate() {
locals.insert(p.clone(), i as u8);
}
let mut c = FnCompiler {
flat,
fn_id,
chunk: FnChunk {
name: fun.name.clone(),
params: fun.params.clone(),
code: Vec::new(),
constants: Vec::new(),
locals: fun.params.clone(),
},
locals,
};
for stmt in &fun.body {
c.compile_stmt(stmt)?;
}
c.emit(Op::None_);
c.emit(Op::Return);
let mut names = vec![String::new(); c.locals.len()];
for (name, slot) in &c.locals {
names[*slot as usize] = name.clone();
}
c.chunk.locals = names;
Ok(c.chunk)
}
impl<'a> FnCompiler<'a> {
fn emit(&mut self, op: Op) {
self.chunk.code.push(op);
}
fn here(&self) -> u16 {
self.chunk.code.len() as u16
}
fn patch(&mut self, at: u16, op: Op) {
self.chunk.code[at as usize] = op;
}
fn add_const(&mut self, v: Value) -> u16 {
if let Some(i) = self.chunk.constants.iter().position(|c| c == &v) {
return i as u16;
}
let i = self.chunk.constants.len() as u16;
self.chunk.constants.push(v);
i
}
fn local_slot(&mut self, name: &str) -> u8 {
if let Some(&s) = self.locals.get(name) {
return s;
}
let s = self.locals.len() as u8;
self.locals.insert(name.to_string(), s);
s
}
fn resolve_call(&self, name: &str) -> Result<usize> {
let fun = &self.flat[self.fn_id];
for &cid in &fun.children {
if self.flat[cid].name == name {
return Ok(cid);
}
}
let mut parent = fun.parent;
while let Some(pid) = parent {
for &cid in &self.flat[pid].children {
if self.flat[cid].name == name {
return Ok(cid);
}
}
parent = self.flat[pid].parent;
}
for (i, f) in self.flat.iter().enumerate() {
if f.parent.is_none() && f.name == name {
return Ok(i);
}
}
bail!("bytecode: unknown function `{name}`")
}
fn compile_stmt(&mut self, stmt: &Stmt) -> Result<()> {
match stmt {
Stmt::Assign { name, value, .. } => {
self.compile_expr(value)?;
let slot = self.local_slot(name);
self.emit(Op::SetLocal(slot));
self.emit(Op::Pop);
}
Stmt::Return { value, .. } => {
self.compile_expr(value)?;
self.emit(Op::Return);
}
Stmt::Call { call, .. } => self.compile_call(call, true)?,
Stmt::Branch { arms, .. } => {
let mut end_jumps = Vec::new();
for (i, arm) in arms.iter().enumerate() {
let is_last = i + 1 == arms.len();
let mut else_jump = None;
if let Some(cond) = &arm.condition {
self.compile_expr(cond)?;
let jf = self.here();
self.emit(Op::JumpIfFalse(0));
else_jump = Some(jf);
}
for st in &arm.body {
self.compile_stmt(st)?;
}
if !is_last {
let j = self.here();
self.emit(Op::Jump(0));
end_jumps.push(j);
}
if let Some(jf) = else_jump {
self.patch(jf, Op::JumpIfFalse(self.here()));
}
}
let end = self.here();
for j in end_jumps {
self.patch(j, Op::Jump(end));
}
}
Stmt::While {
condition, body, ..
} => {
let loop_start = self.here();
self.compile_expr(condition)?;
let exit_j = self.here();
self.emit(Op::JumpIfFalse(0));
for st in body {
self.compile_stmt(st)?;
}
self.emit(Op::Jump(loop_start));
self.patch(exit_j, Op::JumpIfFalse(self.here()));
}
Stmt::ForEach {
item,
collection,
body,
..
} => {
self.compile_expr(&Expr::Var(collection.clone()))?;
let coll_slot = self.local_slot(&format!("__coll_{collection}"));
self.emit(Op::SetLocal(coll_slot));
self.emit(Op::Pop);
let i_slot = self.local_slot(&format!("__i_{collection}"));
let zero = self.add_const(Value::Int(0));
self.emit(Op::Constant(zero));
self.emit(Op::SetLocal(i_slot));
self.emit(Op::Pop);
let item_slot = self.local_slot(item);
let loop_start = self.here();
self.emit(Op::GetLocal(i_slot));
self.emit(Op::GetLocal(coll_slot));
self.emit(Op::Len);
self.emit(Op::Less);
let exit_j = self.here();
self.emit(Op::JumpIfFalse(0));
self.emit(Op::GetLocal(coll_slot));
self.emit(Op::GetLocal(i_slot));
self.emit(Op::GetIndex);
self.emit(Op::SetLocal(item_slot));
self.emit(Op::Pop);
for st in body {
self.compile_stmt(st)?;
}
self.emit(Op::GetLocal(i_slot));
let one = self.add_const(Value::Int(1));
self.emit(Op::Constant(one));
self.emit(Op::Add);
self.emit(Op::SetLocal(i_slot));
self.emit(Op::Pop);
self.emit(Op::Jump(loop_start));
self.patch(exit_j, Op::JumpIfFalse(self.here()));
}
}
Ok(())
}
fn compile_call(&mut self, call: &CallExpr, as_stmt: bool) -> Result<()> {
match call.callee.as_str() {
"print" => {
let text_expr = call
.args
.iter()
.find_map(|a| match a {
Arg::Named { name, value } if name == "text" => Some(value),
_ => None,
})
.or_else(|| {
call.args.iter().find_map(|a| match a {
Arg::Positional(e) => Some(e),
_ => None,
})
})
.ok_or_else(|| anyhow::anyhow!("bytecode: print needs text"))?;
self.compile_expr(text_expr)?;
self.emit(Op::Print);
if !as_stmt {
self.emit(Op::None_);
}
return Ok(());
}
"input" => bail!("bytecode: input not supported"),
_ => {}
}
let fid = self.resolve_call(&call.callee)?;
let params = self.flat[fid].params.clone();
let mut named: HashMap<String, &Expr> = HashMap::new();
let mut positionals = Vec::new();
for a in &call.args {
match a {
Arg::Positional(e) => positionals.push(e),
Arg::Named { name, value } => {
named.insert(name.clone(), value);
}
}
}
let mut pos_i = 0;
for p in &params {
if let Some(e) = named.get(p) {
self.compile_expr(e)?;
} else if pos_i < positionals.len() {
self.compile_expr(positionals[pos_i])?;
pos_i += 1;
} else {
bail!("bytecode: missing argument for parameter `{p}`");
}
}
if pos_i < positionals.len() {
bail!("bytecode: too many positional arguments");
}
self.emit(Op::Call(fid as u16, params.len() as u8));
if as_stmt {
self.emit(Op::Pop);
}
Ok(())
}
fn compile_expr(&mut self, expr: &Expr) -> Result<()> {
match expr {
Expr::Literal(lit) => match lit {
Literal::None => self.emit(Op::None_),
Literal::Bool(true) => self.emit(Op::True),
Literal::Bool(false) => self.emit(Op::False),
Literal::Int(n) => {
let i = self.add_const(Value::Int(*n));
self.emit(Op::Constant(i));
}
Literal::Text(t) => {
let i = self.add_const(Value::Text(t.clone()));
self.emit(Op::Constant(i));
}
},
Expr::Var(name) => {
let slot = self
.locals
.get(name)
.copied()
.ok_or_else(|| anyhow::anyhow!("bytecode: undefined variable `{name}`"))?;
self.emit(Op::GetLocal(slot));
}
Expr::Interp(parts) => {
if parts.is_empty() {
let i = self.add_const(Value::Text(String::new()));
self.emit(Op::Constant(i));
return Ok(());
}
for (idx, part) in parts.iter().enumerate() {
match part {
InterpPart::Lit(t) => {
let i = self.add_const(Value::Text(t.clone()));
self.emit(Op::Constant(i));
}
InterpPart::Var(n) => {
let slot = self.locals.get(n).copied().ok_or_else(|| {
anyhow::anyhow!("bytecode: undefined variable `{n}`")
})?;
self.emit(Op::GetLocal(slot));
}
}
if idx > 0 {
self.emit(Op::Add);
}
}
}
Expr::Unary { op, expr } => {
self.compile_expr(expr)?;
match op {
UnaryOp::Not => self.emit(Op::Not),
UnaryOp::Neg => self.emit(Op::Negate),
}
}
Expr::Binary {
op: BinaryOp::And,
left,
right,
} => {
// JumpIfFalse always pops the tested value.
self.compile_expr(left)?;
let j_false = self.here();
self.emit(Op::JumpIfFalse(0));
self.compile_expr(right)?;
let j_false2 = self.here();
self.emit(Op::JumpIfFalse(0));
self.emit(Op::True);
let j_end = self.here();
self.emit(Op::Jump(0));
let f2 = self.here();
self.patch(j_false2, Op::JumpIfFalse(f2));
self.emit(Op::False);
let j_end2 = self.here();
self.emit(Op::Jump(0));
let f1 = self.here();
self.patch(j_false, Op::JumpIfFalse(f1));
self.emit(Op::False);
let end = self.here();
self.patch(j_end, Op::Jump(end));
self.patch(j_end2, Op::Jump(end));
}
Expr::Binary {
op: BinaryOp::Or,
left,
right,
} => {
self.compile_expr(left)?;
let j_else = self.here();
self.emit(Op::JumpIfFalse(0));
self.emit(Op::True);
let j_end = self.here();
self.emit(Op::Jump(0));
let else_ip = self.here();
self.patch(j_else, Op::JumpIfFalse(else_ip));
self.compile_expr(right)?;
let j_f = self.here();
self.emit(Op::JumpIfFalse(0));
self.emit(Op::True);
let j_end2 = self.here();
self.emit(Op::Jump(0));
let f = self.here();
self.patch(j_f, Op::JumpIfFalse(f));
self.emit(Op::False);
let end = self.here();
self.patch(j_end, Op::Jump(end));
self.patch(j_end2, Op::Jump(end));
}
Expr::Binary { op, left, right } => {
self.compile_expr(left)?;
self.compile_expr(right)?;
self.emit(match op {
BinaryOp::Add => Op::Add,
BinaryOp::Sub => Op::Sub,
BinaryOp::Mul => Op::Mul,
BinaryOp::Div => Op::Div,
BinaryOp::Eq => Op::Equal,
BinaryOp::Ne => Op::NotEqual,
BinaryOp::Lt => Op::Less,
BinaryOp::Le => Op::Lessequal,
BinaryOp::Gt => Op::Greater,
BinaryOp::Ge => Op::GreaterEqual,
BinaryOp::And | BinaryOp::Or => unreachable!(),
});
}
Expr::Call(call) => self.compile_call(call, false)?,
Expr::List(items) => {
for it in items {
self.compile_expr(it)?;
}
self.emit(Op::BuildList(items.len() as u16));
}
}
Ok(())
}
}
-80
View File
@@ -1,80 +0,0 @@
//! Bytecode chunk + opcodes (M5 prototype).
mod compile;
mod vm;
pub use compile::compile_module;
pub use vm::Vm;
use crate::value::Value;
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Op {
Constant(u16),
True,
False,
None_,
Pop,
GetLocal(u8),
SetLocal(u8),
Add,
Sub,
Mul,
Div,
Negate,
Not,
Equal,
NotEqual,
Greater,
GreaterEqual,
Less,
Lessequal,
/// Absolute jump to instruction index.
Jump(u16),
JumpIfFalse(u16),
Print,
BuildList(u16),
Len,
GetIndex,
/// Call function by index; argc values are on the stack (param order).
Call(u16, u8),
Return,
}
#[derive(Debug, Clone)]
pub struct FnChunk {
pub name: String,
pub params: Vec<String>,
pub code: Vec<Op>,
pub constants: Vec<Value>,
/// Local slot names (params first).
pub locals: Vec<String>,
}
#[derive(Debug, Clone)]
pub struct Program {
pub functions: Vec<FnChunk>,
pub entry: usize,
}
impl Program {
pub fn disassemble(&self) -> String {
let mut out = String::new();
out.push_str("=== marqdo: bytecode ===\n");
for (fi, fun) in self.functions.iter().enumerate() {
let entry = if fi == self.entry { " <entry>" } else { "" };
out.push_str(&format!(
"fn[{fi}] {} params={:?} locals={:?}{entry}\n",
fun.name, fun.params, fun.locals
));
for (i, c) in fun.constants.iter().enumerate() {
out.push_str(&format!(" const[{i}] = {c:?}\n"));
}
for (ip, op) in fun.code.iter().enumerate() {
out.push_str(&format!(" {ip:04} {op:?}\n"));
}
}
out.push_str("=== marqdo: end bytecode ===\n");
out
}
}
-236
View File
@@ -1,236 +0,0 @@
//! Stack VM for Marqdo bytecode.
use anyhow::{bail, Result};
use crate::bytecode::{Op, Program};
use crate::value::Value;
pub struct Vm {
capture: bool,
pub captured_stdout: String,
}
struct Frame {
fn_idx: usize,
ip: usize,
slots: Vec<Value>,
}
impl Vm {
pub fn new() -> Self {
Self {
capture: false,
captured_stdout: String::new(),
}
}
pub fn with_capture() -> Self {
Self {
capture: true,
captured_stdout: String::new(),
}
}
fn emit_line(&mut self, text: &str) {
if self.capture {
self.captured_stdout.push_str(text);
self.captured_stdout.push('\n');
} else {
println!("{text}");
}
}
pub fn run(&mut self, program: &Program) -> Result<Value> {
let mut stack: Vec<Value> = Vec::new();
let entry = program.entry;
let arity = program.functions[entry].params.len();
if arity != 0 {
bail!("bytecode: entry function needs arguments");
}
let mut frames = vec![Frame {
fn_idx: entry,
ip: 0,
slots: vec![Value::None; program.functions[entry].locals.len().max(1)],
}];
loop {
let frame = frames.last_mut().unwrap();
let fun = &program.functions[frame.fn_idx];
if frame.ip >= fun.code.len() {
bail!("bytecode: ip out of range in {}", fun.name);
}
let op = fun.code[frame.ip];
frame.ip += 1;
match op {
Op::Constant(i) => stack.push(fun.constants[i as usize].clone()),
Op::True => stack.push(Value::Bool(true)),
Op::False => stack.push(Value::Bool(false)),
Op::None_ => stack.push(Value::None),
Op::Pop => {
stack.pop();
}
Op::GetLocal(i) => {
let v = frames.last().unwrap().slots[i as usize].clone();
stack.push(v);
}
Op::SetLocal(i) => {
let v = stack.last().cloned().unwrap_or(Value::None);
let slot = i as usize;
let fr = frames.last_mut().unwrap();
if fr.slots.len() <= slot {
fr.slots.resize(slot + 1, Value::None);
}
fr.slots[slot] = v;
}
Op::Add => {
let b = pop(&mut stack)?;
let a = pop(&mut stack)?;
stack.push(add(a, b)?);
}
Op::Sub => bin_int(&mut stack, |a, b| a - b)?,
Op::Mul => bin_int(&mut stack, |a, b| a * b)?,
Op::Div => {
let b = pop(&mut stack)?;
let a = pop(&mut stack)?;
match (a, b) {
(Value::Int(_), Value::Int(0)) => bail!("division by zero"),
(Value::Int(x), Value::Int(y)) => stack.push(Value::Int(x / y)),
_ => bail!("`/` needs ints"),
}
}
Op::Negate => match pop(&mut stack)? {
Value::Int(n) => stack.push(Value::Int(-n)),
_ => bail!("unary `-` needs int"),
},
Op::Not => {
let v = pop(&mut stack)?;
stack.push(Value::Bool(!v.truthy()));
}
Op::Equal => {
let b = pop(&mut stack)?;
let a = pop(&mut stack)?;
stack.push(Value::Bool(a == b));
}
Op::NotEqual => {
let b = pop(&mut stack)?;
let a = pop(&mut stack)?;
stack.push(Value::Bool(a != b));
}
Op::Greater => cmp(&mut stack, |o| o.is_gt())?,
Op::GreaterEqual => cmp(&mut stack, |o| o.is_ge())?,
Op::Less => cmp(&mut stack, |o| o.is_lt())?,
Op::Lessequal => cmp(&mut stack, |o| o.is_le())?,
Op::Jump(t) => {
frames.last_mut().unwrap().ip = t as usize;
}
Op::JumpIfFalse(t) => {
let v = pop(&mut stack)?;
if !v.truthy() {
frames.last_mut().unwrap().ip = t as usize;
}
}
Op::Print => {
let v = pop(&mut stack)?;
self.emit_line(&v.as_display());
}
Op::BuildList(n) => {
let n = n as usize;
let mut items = Vec::with_capacity(n);
for _ in 0..n {
items.push(pop(&mut stack)?);
}
items.reverse();
stack.push(Value::List(items));
}
Op::Len => match pop(&mut stack)? {
Value::List(xs) => stack.push(Value::Int(xs.len() as i64)),
_ => bail!("len needs list"),
},
Op::GetIndex => {
let idx = pop(&mut stack)?;
let list = pop(&mut stack)?;
match (list, idx) {
(Value::List(xs), Value::Int(i)) if i >= 0 && (i as usize) < xs.len() => {
stack.push(xs[i as usize].clone());
}
(Value::List(_), Value::Int(_)) => stack.push(Value::None),
_ => bail!("GetIndex needs list and int"),
}
}
Op::Call(fid, argc) => {
let fid = fid as usize;
let argc = argc as usize;
let callee = &program.functions[fid];
if callee.params.len() != argc {
bail!("bytecode: call argc mismatch");
}
let mut slots = vec![Value::None; callee.locals.len().max(argc).max(1)];
for i in (0..argc).rev() {
slots[i] = pop(&mut stack)?;
}
// args were pushed in param order; we popped reverse so slots[0] is last param — fix:
// stack had p0, p1, p2 (top). pop → p2, p1, p0. So assign slots[argc-1-i] or pop into reverse.
// Actually we did: for i in (0..argc).rev() { slots[i] = pop() }
// first pop → slots[argc-1] = top = last param. Good if push order was p0..plast.
frames.push(Frame {
fn_idx: fid,
ip: 0,
slots,
});
}
Op::Return => {
let ret = pop(&mut stack).unwrap_or(Value::None);
frames.pop();
if frames.is_empty() {
return Ok(ret);
}
stack.push(ret);
}
}
}
}
}
fn pop(stack: &mut Vec<Value>) -> Result<Value> {
stack
.pop()
.ok_or_else(|| anyhow::anyhow!("bytecode: stack underflow"))
}
fn add(a: Value, b: Value) -> Result<Value> {
match (a, b) {
(Value::Int(x), Value::Int(y)) => Ok(Value::Int(x + y)),
(Value::Text(x), Value::Text(y)) => Ok(Value::Text(format!("{x}{y}"))),
(Value::Text(x), y) => Ok(Value::Text(format!("{x}{}", y.as_display()))),
(x, Value::Text(y)) => Ok(Value::Text(format!("{}{y}", x.as_display()))),
// Int + display for interp GetLocal Int + Lit text
(Value::Int(x), y) => Ok(Value::Text(format!("{}{}", x, y.as_display()))),
(x, Value::Int(y)) => Ok(Value::Text(format!("{}{y}", x.as_display()))),
_ => bail!("`+` needs ints or text"),
}
}
fn bin_int(stack: &mut Vec<Value>, f: impl Fn(i64, i64) -> i64) -> Result<()> {
let b = pop(stack)?;
let a = pop(stack)?;
match (a, b) {
(Value::Int(x), Value::Int(y)) => {
stack.push(Value::Int(f(x, y)));
Ok(())
}
_ => bail!("binary op needs ints"),
}
}
fn cmp(stack: &mut Vec<Value>, pred: impl Fn(std::cmp::Ordering) -> bool) -> Result<()> {
let b = pop(stack)?;
let a = pop(stack)?;
let ord = match (&a, &b) {
(Value::Int(x), Value::Int(y)) => x.cmp(y),
(Value::Text(x), Value::Text(y)) => x.cmp(y),
_ => bail!("comparison needs two ints or two texts"),
};
stack.push(Value::Bool(pred(ord)));
Ok(())
}
-9
View File
@@ -1,9 +0,0 @@
//! Captured program run (for tests and `view`).
use crate::value::Value;
#[derive(Debug, Clone)]
pub struct RunCapture {
pub stdout: String,
pub value: Value,
}
-3
View File
@@ -1,3 +0,0 @@
//! Pipeline dump helpers (see doc/design/pipeline-debug.md).
pub use crate::lex::format_lines_dump;
-59
View File
@@ -1,59 +0,0 @@
//! Diagnostics with file/line/column.
use std::fmt;
use std::path::{Path, PathBuf};
use thiserror::Error;
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct Span {
pub line: u32,
pub col: u32,
}
impl Span {
pub fn new(line: u32, col: u32) -> Self {
Self { line, col }
}
}
impl fmt::Display for Span {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
write!(f, "{}:{}", self.line, self.col)
}
}
/// Unified diagnostic: `path:line:col: message` (path omitted if unknown).
#[derive(Debug, Error, Clone)]
#[error("{}", self.format_message())]
pub struct Diagnostic {
pub path: Option<PathBuf>,
pub span: Span,
pub message: String,
}
impl Diagnostic {
pub fn new(path: Option<&Path>, span: Span, message: impl Into<String>) -> Self {
Self {
path: path.map(|p| p.to_path_buf()),
span,
message: message.into(),
}
}
pub fn at(path: &Path, span: Span, message: impl Into<String>) -> Self {
Self::new(Some(path), span, message)
}
pub fn format_message(&self) -> String {
match &self.path {
Some(p) => format!("{}:{}: {}", p.display(), self.span, self.message),
None => format!("{}: {}", self.span, self.message),
}
}
}
/// Convenience for `anyhow` sites that already have a span.
pub fn bail_at(path: Option<&Path>, span: Span, message: impl Into<String>) -> anyhow::Error {
anyhow::Error::new(Diagnostic::new(path, span, message))
}
+40
View File
@@ -0,0 +1,40 @@
//解释器检测到错误的处理模块
//! 错误报告模块,集中管理解释器所有语法错误输出
// use std::io;
// use std::io::Write;
//建立独立抽象ErrorReport结构体
//错误报告器,保存错误状态并提供错误报告接口
#[derive(Debug, Default)]
pub struct ErrorReport {
had_error: bool,
}
impl ErrorReport {
//创建新的错误报告器
pub fn new() -> Self {
Self { had_error: false }
}
//对外公开的错误接口,指定行号和错误信息
pub fn error(&mut self, line: usize, message: &str) {
self.report(line, "", message);
}
//内部私有函数,输出错误信息,标记错误状态为true
fn report(&mut self, line: usize, location: &str, message: &str) {
eprintln!("[line {}] Error{}: {}", line, location, message);
self.had_error = true;
}
//获取错误状态
pub fn has_error(&self) -> bool {
self.had_error
}
//重置错误状态
pub fn clear(&mut self) {
self.had_error = false;
}
}
-509
View File
@@ -1,509 +0,0 @@
//! Tree-walk interpreter (Phase I).
use anyhow::{bail, Result};
use std::collections::{HashMap, HashSet};
use std::path::{Path, PathBuf};
use crate::ast::{
Arg, BinaryOp, CallExpr, Expr, Function, InterpPart, Literal, Module, Stmt, UnaryOp,
};
use crate::diagnostics::{bail_at, Span};
use crate::value::Value;
pub struct Interpreter {
pub path: Option<PathBuf>,
pub trace: bool,
capture: bool,
pub captured_stdout: String,
current_span: Span,
}
struct Env {
vars: HashMap<String, Value>,
}
impl Env {
fn new() -> Self {
Self {
vars: HashMap::new(),
}
}
fn get(&self, name: &str) -> Option<&Value> {
self.vars.get(name)
}
fn set(&mut self, name: String, value: Value) {
self.vars.insert(name, value);
}
}
enum EvArg {
Positional(Value),
Named(String, Value),
}
impl Interpreter {
pub fn new(path: Option<&Path>, trace: bool) -> Self {
Self {
path: path.map(|p| p.to_path_buf()),
trace,
capture: false,
captured_stdout: String::new(),
current_span: Span::new(1, 1),
}
}
pub fn with_capture(path: Option<&Path>, trace: bool) -> Self {
Self {
path: path.map(|p| p.to_path_buf()),
trace,
capture: true,
captured_stdout: String::new(),
current_span: Span::new(1, 1),
}
}
fn err(&self, message: impl Into<String>) -> anyhow::Error {
bail_at(self.path.as_deref(), self.current_span, message)
}
fn emit_line(&mut self, text: &str) {
if self.capture {
self.captured_stdout.push_str(text);
self.captured_stdout.push('\n');
} else {
println!("{text}");
}
}
pub fn run_module(&mut self, module: &Module) -> Result<Value> {
if let Some(main) = find_top(module, "main") {
return self.run_function(module, main, Env::new(), &[]);
}
let tops: Vec<&Function> = module.functions.iter().filter(|f| f.level == 1).collect();
if tops.is_empty() {
bail!("no `# main` and no level-1 function to run");
}
let mut last = Value::None;
for fun in tops {
if fun.params.is_empty() {
last = self.run_function(module, fun, Env::new(), &[])?;
}
}
Ok(last)
}
fn run_function(
&mut self,
module: &Module,
fun: &Function,
mut env: Env,
args: &[(String, Value)],
) -> Result<Value> {
if self.trace {
eprintln!("enter fun {:?}", fun.name);
}
for (k, v) in args {
env.set(k.clone(), v.clone());
}
for p in &fun.params {
if env.get(p).is_none() {
env.set(p.clone(), Value::None);
}
}
let mut ret = Value::None;
for stmt in &fun.body {
if let Some(v) = self.exec_stmt(module, fun, &mut env, stmt)? {
ret = v;
break;
}
}
if self.trace {
eprintln!("leave fun {:?} => {ret}", fun.name);
}
Ok(ret)
}
fn exec_stmt(
&mut self,
module: &Module,
fun: &Function,
env: &mut Env,
stmt: &Stmt,
) -> Result<Option<Value>> {
match stmt {
Stmt::Assign { name, value, span } => {
self.current_span = *span;
let v = self.eval_expr(module, fun, env, value)?;
if self.trace {
eprintln!(" assign {name} = {v:?} @{span}");
}
env.set(name.clone(), v);
Ok(None)
}
Stmt::Return { value, span } => {
self.current_span = *span;
let v = self.eval_expr(module, fun, env, value)?;
if self.trace {
eprintln!(" return {v:?} @{span}");
}
Ok(Some(v))
}
Stmt::Call { call, span } => {
self.current_span = *span;
if self.trace {
eprintln!(" call-stmt {} @{span}", call.callee);
}
let _ = self.eval_call(module, fun, env, call)?;
Ok(None)
}
Stmt::Branch { arms, span } => {
self.current_span = *span;
if self.trace {
eprintln!(" branch @{span}");
}
for arm in arms {
let take = match &arm.condition {
None => true,
Some(cond) => self.eval_expr(module, fun, env, cond)?.truthy(),
};
if take {
for s in &arm.body {
if let Some(v) = self.exec_stmt(module, fun, env, s)? {
return Ok(Some(v));
}
}
break;
}
}
Ok(None)
}
Stmt::While {
condition,
body,
span,
} => {
self.current_span = *span;
if self.trace {
eprintln!(" while @{span}");
}
let mut guard = 0u32;
while self.eval_expr(module, fun, env, condition)?.truthy() {
guard += 1;
if guard > 1_000_000 {
return Err(self.err("while loop exceeded iteration limit"));
}
for s in body {
if let Some(v) = self.exec_stmt(module, fun, env, s)? {
return Ok(Some(v));
}
}
}
Ok(None)
}
Stmt::ForEach {
item,
collection,
body,
span,
} => {
self.current_span = *span;
if self.trace {
eprintln!(" foreach {item} in {collection} @{span}");
}
let coll = env.get(collection).cloned().ok_or_else(|| {
self.err(format!("undefined collection `{collection}`"))
})?;
let items = match coll {
Value::List(xs) => xs,
other => {
return Err(self.err(format!("foreach needs a list, got {other:?}")));
}
};
for val in items {
env.set(item.clone(), val);
for s in body {
if let Some(v) = self.exec_stmt(module, fun, env, s)? {
return Ok(Some(v));
}
}
}
Ok(None)
}
}
}
fn eval_expr(
&mut self,
module: &Module,
fun: &Function,
env: &mut Env,
expr: &Expr,
) -> Result<Value> {
match expr {
Expr::Literal(lit) => Ok(lit_to_value(lit)),
Expr::Var(name) => env
.get(name)
.cloned()
.ok_or_else(|| self.err(format!("undefined variable `{name}`"))),
Expr::Interp(parts) => {
let mut s = String::new();
for part in parts {
match part {
InterpPart::Lit(t) => s.push_str(t),
InterpPart::Var(n) => {
let v = env
.get(n)
.ok_or_else(|| self.err(format!("undefined variable `{n}`")))?;
s.push_str(&v.as_display());
}
}
}
Ok(Value::Text(s))
}
Expr::Unary { op, expr } => {
let v = self.eval_expr(module, fun, env, expr)?;
match op {
UnaryOp::Not => Ok(Value::Bool(!v.truthy())),
UnaryOp::Neg => match v {
Value::Int(n) => Ok(Value::Int(-n)),
_ => Err(self.err("unary `-` needs int")),
},
}
}
Expr::Binary { op, left, right } => {
let l = self.eval_expr(module, fun, env, left)?;
match op {
BinaryOp::And => {
if !l.truthy() {
return Ok(Value::Bool(false));
}
let r = self.eval_expr(module, fun, env, right)?;
return Ok(Value::Bool(r.truthy()));
}
BinaryOp::Or => {
if l.truthy() {
return Ok(Value::Bool(true));
}
let r = self.eval_expr(module, fun, env, right)?;
return Ok(Value::Bool(r.truthy()));
}
_ => {}
}
let r = self.eval_expr(module, fun, env, right)?;
eval_binary(*op, &l, &r).map_err(|e| self.err(e.to_string()))
}
Expr::Call(call) => self.eval_call(module, fun, env, call),
Expr::List(items) => {
let mut out = Vec::new();
for it in items {
out.push(self.eval_expr(module, fun, env, it)?);
}
Ok(Value::List(out))
}
}
}
fn eval_call(
&mut self,
module: &Module,
fun: &Function,
env: &mut Env,
call: &CallExpr,
) -> Result<Value> {
let mut ev_args = Vec::new();
for arg in &call.args {
match arg {
Arg::Positional(e) => {
ev_args.push(EvArg::Positional(self.eval_expr(module, fun, env, e)?));
}
Arg::Named { name, value } => {
ev_args.push(EvArg::Named(
name.clone(),
self.eval_expr(module, fun, env, value)?,
));
}
}
}
match call.callee.as_str() {
"print" => {
let bound = bind_args(&["text".into()], &ev_args, false)
.map_err(|m| self.err(m))?;
let text = bound
.get("text")
.map(|v| v.as_display())
.ok_or_else(|| self.err("print requires text (named or positional)"))?;
self.emit_line(&text);
return Ok(Value::None);
}
"input" => {
if self.capture {
return Err(self.err("input is not available under capture / view"));
}
let bound = bind_args(&["prompt".into()], &ev_args, true)
.map_err(|m| self.err(m))?;
let prompt = bound
.get("prompt")
.map(|v| v.as_display())
.unwrap_or_default();
if !prompt.is_empty() {
print!("{prompt}");
use std::io::Write;
let _ = std::io::stdout().flush();
}
let mut line = String::new();
std::io::stdin().read_line(&mut line)?;
if line.ends_with('\n') {
line.pop();
if line.ends_with('\r') {
line.pop();
}
}
return Ok(Value::Text(line));
}
_ => {}
}
let target = lookup_function(module, fun, &call.callee)
.ok_or_else(|| self.err(format!("unknown function `{}`", call.callee)))?;
let bound = bind_args(&target.params, &ev_args, false).map_err(|m| self.err(m))?;
let mut call_env = Env::new();
for (k, v) in bound {
call_env.set(k, v);
}
self.run_function(module, target, call_env, &[])
}
}
/// Bind evaluated args onto parameter names. Err is a plain message (caller adds span/path).
fn bind_args(
params: &[String],
args: &[EvArg],
allow_missing: bool,
) -> std::result::Result<HashMap<String, Value>, String> {
let mut named: HashMap<String, Value> = HashMap::new();
let mut positionals = Vec::new();
for a in args {
match a {
EvArg::Positional(v) => positionals.push(v.clone()),
EvArg::Named(k, v) => {
if named.contains_key(k) {
return Err(format!("duplicate named argument `{k}`"));
}
named.insert(k.clone(), v.clone());
}
}
}
let mut out: HashMap<String, Value> = HashMap::new();
let mut used_named = HashSet::new();
let mut pos_i = 0usize;
for p in params {
if let Some(v) = named.get(p) {
out.insert(p.clone(), v.clone());
used_named.insert(p.clone());
} else if pos_i < positionals.len() {
out.insert(p.clone(), positionals[pos_i].clone());
pos_i += 1;
} else if !allow_missing {
return Err(format!("missing argument for parameter `{p}`"));
}
}
if pos_i < positionals.len() {
return Err(format!(
"too many positional arguments ({} extra)",
positionals.len() - pos_i
));
}
for (k, v) in named {
if !used_named.contains(&k) && !out.contains_key(&k) {
out.insert(k, v);
}
}
Ok(out)
}
fn find_top<'a>(module: &'a Module, name: &str) -> Option<&'a Function> {
module.functions.iter().find(|f| f.name == name)
}
fn lookup_function<'a>(
module: &'a Module,
current: &'a Function,
name: &str,
) -> Option<&'a Function> {
if let Some(f) = find_in_tree(current, name) {
return Some(f);
}
module.functions.iter().find(|f| f.name == name)
}
fn find_in_tree<'a>(fun: &'a Function, name: &str) -> Option<&'a Function> {
for child in &fun.children {
if child.name == name {
return Some(child);
}
if let Some(f) = find_in_tree(child, name) {
return Some(f);
}
}
None
}
fn lit_to_value(lit: &Literal) -> Value {
match lit {
Literal::None => Value::None,
Literal::Bool(b) => Value::Bool(*b),
Literal::Int(n) => Value::Int(*n),
Literal::Text(s) => Value::Text(s.clone()),
}
}
fn eval_binary(op: BinaryOp, l: &Value, r: &Value) -> Result<Value> {
match op {
BinaryOp::Add => match (l, r) {
(Value::Int(a), Value::Int(b)) => Ok(Value::Int(a + b)),
(Value::Text(a), Value::Text(b)) => Ok(Value::Text(format!("{a}{b}"))),
(Value::Text(a), b) => Ok(Value::Text(format!("{a}{}", b.as_display()))),
(a, Value::Text(b)) => Ok(Value::Text(format!("{}{b}", a.as_display()))),
_ => bail!("`+` needs ints or text"),
},
BinaryOp::Sub => match (l, r) {
(Value::Int(a), Value::Int(b)) => Ok(Value::Int(a - b)),
_ => bail!("`-` needs ints"),
},
BinaryOp::Mul => match (l, r) {
(Value::Int(a), Value::Int(b)) => Ok(Value::Int(a * b)),
_ => bail!("`*` needs ints"),
},
BinaryOp::Div => match (l, r) {
(Value::Int(_), Value::Int(0)) => bail!("division by zero"),
(Value::Int(a), Value::Int(b)) => Ok(Value::Int(a / b)),
_ => bail!("`/` needs ints"),
},
BinaryOp::Eq => Ok(Value::Bool(l == r)),
BinaryOp::Ne => Ok(Value::Bool(l != r)),
BinaryOp::Lt => cmp_ord(l, r, |o| o.is_lt()),
BinaryOp::Le => cmp_ord(l, r, |o| o.is_le()),
BinaryOp::Gt => cmp_ord(l, r, |o| o.is_gt()),
BinaryOp::Ge => cmp_ord(l, r, |o| o.is_ge()),
BinaryOp::And | BinaryOp::Or => unreachable!("handled above"),
}
}
fn cmp_ord(l: &Value, r: &Value, f: impl Fn(std::cmp::Ordering) -> bool) -> Result<Value> {
match (l, r) {
(Value::Int(a), Value::Int(b)) => Ok(Value::Bool(f(a.cmp(b)))),
(Value::Text(a), Value::Text(b)) => Ok(Value::Bool(f(a.cmp(b)))),
_ => bail!("comparison needs two ints or two texts"),
}
}
-130
View File
@@ -1,130 +0,0 @@
//! Line classification (M1) — no Flex.
//!
//! Unmarked lines are comments; lines whose first non-whitespace character
//! opens a Marqdo/Markdown marker are code.
use std::fmt;
/// Kind of a source line after skipping leading indentation for the test.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum LineKind {
Blank,
Comment,
Code,
}
impl fmt::Display for LineKind {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
match self {
LineKind::Blank => write!(f, "Blank"),
LineKind::Comment => write!(f, "Comment"),
LineKind::Code => write!(f, "Code"),
}
}
}
/// One classified source line (1-based line number).
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ClassifiedLine {
pub line_no: u32,
pub kind: LineKind,
pub text: String,
}
/// Characters that start a code line when they appear as the first non-ws char.
fn is_code_starter(c: char) -> bool {
matches!(
c,
'#' | '*' | '>' | '+' | '-' | '`' | '|' | '~'
) || c.is_ascii_digit()
}
/// Classify a single logical line (no trailing newline required).
pub fn classify_line(text: &str) -> LineKind {
let trimmed = text.trim_end_matches(['\r', '\n']);
if trimmed.chars().all(|c| c.is_whitespace()) {
return LineKind::Blank;
}
let first = trimmed.chars().find(|c| !c.is_whitespace());
match first {
None => LineKind::Blank,
Some(c) if is_code_starter(c) => LineKind::Code,
Some(_) => LineKind::Comment,
}
}
/// Classify every line of a source file.
pub fn classify_source(source: &str) -> Vec<ClassifiedLine> {
let source = source.strip_prefix('\u{feff}').unwrap_or(source);
let lines: Vec<&str> = if source.is_empty() {
Vec::new()
} else {
source.lines().collect()
};
lines
.into_iter()
.enumerate()
.map(|(i, text)| ClassifiedLine {
line_no: (i + 1) as u32,
kind: classify_line(text),
text: text.to_string(),
})
.collect()
}
/// Human-readable dump for `--dump-lines`.
pub fn format_lines_dump(path: &str, lines: &[ClassifiedLine]) -> String {
let mut out = String::new();
out.push_str(&format!("=== marqdo: lines ({path}) ===\n"));
for line in lines {
let preview = if line.text.len() > 80 {
format!("{}…", &line.text.chars().take(80).collect::<String>())
} else {
line.text.clone()
};
match line.kind {
LineKind::Blank => {
out.push_str(&format!("{:4} {:7}\n", line.line_no, line.kind));
}
_ => {
out.push_str(&format!(
"{:4} {:7} | {}\n",
line.line_no, line.kind, preview
));
}
}
}
out.push_str("=== marqdo: end lines ===\n");
out
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn blank_and_comment_and_code() {
assert_eq!(classify_line(""), LineKind::Blank);
assert_eq!(classify_line(" "), LineKind::Blank);
assert_eq!(classify_line("hello world"), LineKind::Comment);
assert_eq!(classify_line(" 中文说明"), LineKind::Comment);
assert_eq!(classify_line("> print text=hi"), LineKind::Code);
assert_eq!(classify_line("# main"), LineKind::Code);
assert_eq!(classify_line("*`x` = 1*"), LineKind::Code);
assert_eq!(classify_line("**ret**"), LineKind::Code);
assert_eq!(classify_line("+ `x` > 0"), LineKind::Code);
assert_eq!(classify_line("- item"), LineKind::Code);
assert_eq!(classify_line("1. arm"), LineKind::Code);
assert_eq!(classify_line("| a |"), LineKind::Code);
assert_eq!(classify_line("`x` = 1"), LineKind::Code);
}
#[test]
fn classify_hello_fixture() {
let src = include_str!("../../examples/structure/hello.mq.md");
let lines = classify_source(src);
assert!(lines.iter().any(|l| l.kind == LineKind::Code && l.text.contains("print")));
assert!(lines.iter().any(|l| l.kind == LineKind::Comment));
}
}
-173
View File
@@ -1,173 +0,0 @@
//! Marqdo reference interpreter (Phase I + M5 bytecode prototype).
//!
//! Pipeline: load → line classify → parse → tree-walk eval | bytecode VM.
//! CLI also offers `view` for AST-backed browsing.
pub mod ast;
pub mod bytecode;
pub mod capture;
pub mod debug;
pub mod diagnostics;
pub mod interp;
pub mod lex;
pub mod load;
pub mod parse;
pub mod value;
pub mod view;
use std::path::Path;
use anyhow::{bail, Result};
use crate::ast::format_ast_dump;
use crate::bytecode::{compile_module, Vm};
use crate::capture::RunCapture;
use crate::interp::Interpreter;
use crate::lex::{classify_source, format_lines_dump};
use crate::load::load_module;
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum Backend {
#[default]
Tree,
Bytecode,
}
impl Backend {
pub fn parse(s: &str) -> Result<Self> {
match s {
"tree" => Ok(Self::Tree),
"bytecode" | "bc" => Ok(Self::Bytecode),
other => bail!("unknown backend `{other}` (expected tree|bytecode)"),
}
}
}
/// Options for a single `run` / dump invocation.
#[derive(Debug, Clone, Default)]
pub struct RunOptions {
pub dump_lines: bool,
pub dump_tokens: bool,
pub dump_ast: bool,
pub dump_sema: bool,
pub dump_bytecode: bool,
pub trace_eval: bool,
pub backend: Backend,
}
impl RunOptions {
pub fn dump_all() -> Self {
Self {
dump_lines: true,
dump_tokens: true,
dump_ast: true,
dump_sema: true,
dump_bytecode: true,
trace_eval: true,
backend: Backend::Tree,
}
}
pub fn any_dump(&self) -> bool {
self.dump_lines
|| self.dump_tokens
|| self.dump_ast
|| self.dump_sema
|| self.dump_bytecode
|| self.trace_eval
}
}
/// Run a `.mq.md` program (prints to real stdout).
pub fn run_file(path: &Path, opts: &RunOptions) -> Result<i32> {
let source = std::fs::read_to_string(path)
.map_err(|e| anyhow::anyhow!("failed to read {}: {e}", path.display()))?;
if source.trim().is_empty() {
bail!("{} is empty", path.display());
}
let path_label = path.display().to_string();
if opts.dump_lines {
let lines = classify_source(&source);
print!("{}", format_lines_dump(&path_label, &lines));
}
if opts.dump_tokens {
println!("=== marqdo: tokens ({path_label}) ===");
println!("(fine-grained tokens not implemented yet — use --dump-lines)");
println!("=== marqdo: end tokens ===");
}
let module = load_module(path)?;
if opts.dump_ast {
print!("{}", format_ast_dump(&path_label, &module));
}
if opts.dump_sema {
println!("=== marqdo: sema ({path_label}) ===");
println!(
"functions: {:?}",
module
.functions
.iter()
.map(|f| f.name.as_str())
.collect::<Vec<_>>()
);
println!("imports: {:?}", module.imports);
println!("=== marqdo: end sema ===");
}
match opts.backend {
Backend::Tree => {
let mut interp = Interpreter::new(Some(path), opts.trace_eval);
if opts.trace_eval {
eprintln!("=== marqdo: trace-eval ({path_label}) ===");
}
interp.run_module(&module)?;
if opts.trace_eval {
eprintln!("=== marqdo: end trace-eval ===");
}
}
Backend::Bytecode => {
let program = compile_module(&module)?;
if opts.dump_bytecode {
print!("{}", program.disassemble());
}
let mut vm = Vm::new();
vm.run(&program)?;
}
}
// dump bytecode even on tree backend if requested
if opts.backend == Backend::Tree && opts.dump_bytecode {
let program = compile_module(&module)?;
print!("{}", program.disassemble());
}
Ok(0)
}
/// Run and capture stdout (used by `view` and tests).
pub fn run_file_capture(path: &Path, opts: &RunOptions) -> Result<RunCapture> {
let module = load_module(path)?;
match opts.backend {
Backend::Tree => {
let mut interp = Interpreter::with_capture(Some(path), false);
let value = interp.run_module(&module)?;
Ok(RunCapture {
stdout: interp.captured_stdout,
value,
})
}
Backend::Bytecode => {
let program = compile_module(&module)?;
let mut vm = Vm::with_capture();
let value = vm.run(&program)?;
Ok(RunCapture {
stdout: vm.captured_stdout,
value,
})
}
}
}
-68
View File
@@ -1,68 +0,0 @@
//! Load `.mq.md` files and merge frontmatter imports.
use std::collections::HashSet;
use std::path::{Path, PathBuf};
use anyhow::{bail, Context, Result};
use crate::ast::{Function, Module};
use crate::diagnostics::Diagnostic;
use crate::parse::parse_source;
/// Load `path` and recursively merge imported modules' top-level functions.
pub fn load_module(path: &Path) -> Result<Module> {
let mut visited = HashSet::new();
load_module_inner(path, &mut visited)
}
fn load_module_inner(path: &Path, visited: &mut HashSet<PathBuf>) -> Result<Module> {
let canon = path
.canonicalize()
.unwrap_or_else(|_| path.to_path_buf());
if !visited.insert(canon.clone()) {
bail!("circular import involving {}", path.display());
}
let source = std::fs::read_to_string(path)
.with_context(|| format!("failed to read {}", path.display()))?;
let mut module = parse_source(&source).map_err(|e| attach_path(path, e))?;
let base = path.parent().unwrap_or_else(|| Path::new("."));
let imports = module.imports.clone();
for rel in imports {
let dep_path = base.join(&rel);
let dep = load_module_inner(&dep_path, visited)?;
for fun in dep.functions {
merge_top_level(&mut module.functions, fun);
}
}
Ok(module)
}
fn attach_path(path: &Path, err: anyhow::Error) -> anyhow::Error {
if let Some(d) = err.downcast_ref::<Diagnostic>() {
if d.path.is_none() {
return Diagnostic::at(path, d.span, d.message.clone()).into();
}
return err;
}
// Legacy `line:col: message` from parse bail!
let msg = err.to_string();
if let Some((loc, rest)) = msg.split_once(": ") {
if let Some((line_s, col_s)) = loc.split_once(':') {
if let (Ok(line), Ok(col)) = (line_s.parse::<u32>(), col_s.parse::<u32>()) {
return Diagnostic::at(path, crate::diagnostics::Span::new(line, col), rest).into();
}
}
}
err.context(format!("in {}", path.display()))
}
fn merge_top_level(into: &mut Vec<Function>, fun: Function) {
if let Some(existing) = into.iter_mut().find(|f| f.name == fun.name) {
*existing = fun;
} else {
into.push(fun);
}
}
-132
View File
@@ -1,132 +0,0 @@
use std::path::PathBuf;
use std::process::ExitCode;
use anyhow::Result;
use clap::{Parser, Subcommand, ValueEnum};
use marqdo::view::{serve, ViewOptions};
use marqdo::{Backend, RunOptions};
#[derive(Parser, Debug)]
#[command(name = "marqdo", version, about = "Marqdo interpreter — run and view .mq.md programs")]
struct Cli {
#[command(subcommand)]
command: Commands,
}
#[derive(Clone, Copy, Debug, ValueEnum)]
enum BackendCli {
Tree,
Bytecode,
}
impl From<BackendCli> for Backend {
fn from(b: BackendCli) -> Self {
match b {
BackendCli::Tree => Backend::Tree,
BackendCli::Bytecode => Backend::Bytecode,
}
}
}
#[derive(Subcommand, Debug)]
enum Commands {
/// Execute a Marqdo source file (defaults to ./index.mq.md)
Run {
#[arg(value_name = "FILE")]
file: Option<PathBuf>,
#[arg(long, value_enum, default_value_t = BackendCli::Tree)]
backend: BackendCli,
#[arg(long)]
dump_lines: bool,
#[arg(long)]
dump_tokens: bool,
#[arg(long)]
dump_ast: bool,
#[arg(long)]
dump_sema: bool,
#[arg(long)]
dump_bytecode: bool,
#[arg(long)]
trace_eval: bool,
#[arg(long)]
dump_all: bool,
},
/// Browse `.mq.md` structure + execution in a local webpage
View {
#[arg(value_name = "PATH")]
path: Option<PathBuf>,
#[arg(long, default_value = "127.0.0.1")]
host: String,
#[arg(long, default_value_t = 7429)]
port: u16,
#[arg(long)]
no_open: bool,
},
}
fn main() -> ExitCode {
match try_main() {
Ok(code) => ExitCode::from(code as u8),
Err(err) => {
eprintln!("error: {err:#}");
ExitCode::from(1)
}
}
}
fn try_main() -> Result<i32> {
let cli = Cli::parse();
match cli.command {
Commands::Run {
file,
backend,
dump_lines,
dump_tokens,
dump_ast,
dump_sema,
dump_bytecode,
trace_eval,
dump_all,
} => {
let path = file.unwrap_or_else(|| PathBuf::from("index.mq.md"));
let mut opts = if dump_all {
RunOptions::dump_all()
} else {
RunOptions {
dump_lines,
dump_tokens,
dump_ast,
dump_sema,
dump_bytecode,
trace_eval,
backend: backend.into(),
}
};
if dump_all {
opts.backend = backend.into();
}
marqdo::run_file(&path, &opts)?;
Ok(0)
}
Commands::View {
path,
host,
port,
no_open,
} => {
serve(ViewOptions {
path: path.unwrap_or_else(|| PathBuf::from(".")),
host,
port,
open_browser: !no_open,
})?;
Ok(0)
}
}
}
+85
View File
@@ -0,0 +1,85 @@
//使用rust开发marqdo语言的解释器
//导入库
use std::env; //用于获取命令行参数
use std::fs; //用于读取文件
// use std::io; //用于读取标准输入和输出
// use std::io::BufReader; //用于读取缓冲区
//导入错误报告模块
mod error;
use error::ErrorReport;
fn main() {
//创建新的错误报告器
let mut error_report = ErrorReport::new();
//获取命令行参数
let args: Vec<String> = env::args().collect();
//解析命令行参数
if args.len() > 3 {
eprintln!("Usage: marqdo <use_mode> <file>");
std::process::exit(1);
}
else if args.len() == 3 {
let use_mode = &args[1];
let file_path = &args[2];
//传入模式选择函数,根据不同的模式选择不同的函数执行
mode_selector(use_mode, file_path, &mut error_report);
}
else if args.len() == 2 {
let file_path = &args[1];
//默认为run模式,自动进行文件执行
run_file(file_path, &mut error_report);
}
else {
//无参数输入,默认进入交互模式
run_prompt(&mut error_report);
}
}
//模式选择函数
fn mode_selector(use_mode: &str, file_path: &str, error_report: &mut ErrorReport) {
//根据不同的模式选择不同的函数执行
match use_mode {
"run" => run_file(file_path, error_report),
_ => {eprintln!("Invalid use mode: {}", use_mode);
std::process::exit(2);
}
}
}
//读取marqdo文件并运行marqdo脚本文件
fn run_file(file_path: &str, error_report: &mut ErrorReport) {
match fs::read_to_string(file_path) {
Ok(source) => {
run(&source, error_report);
}
Err(e) => {
eprintln!("Error reading file: {}", e);
std::process::exit(3);
}
}
}
//交互式模式
fn run_prompt(error_report: &mut ErrorReport) {
//提示交互式模式正在开发中
println!("Interactive mode is not available yet.");
error_report.error(0, "Interactive mode is not available yet.");
//清除错误报告
error_report.clear();
std::process::exit(4);
}
//运行marqdo脚本
fn run(source: &str, error_report: &mut ErrorReport) {
//提示正在开发中
println!("Running script is not available yet.");
//输出source
println!("Source: {}", source);
//输出错误报告
println!("Error report: {}", error_report.has_error());
//退出程序
std::process::exit(5);
}
-492
View File
@@ -1,492 +0,0 @@
//! Expression parser (recursive descent over a single string).
use anyhow::{bail, Result};
use crate::ast::{BinaryOp, CallExpr, Expr, InterpPart, Literal, UnaryOp};
pub fn parse_expr(input: &str) -> Result<Expr> {
let mut p = Parser::new(input.trim());
let e = p.parse_or()?;
p.skip_ws();
if !p.rest().is_empty() {
bail!("trailing input in expression: {:?}", p.rest());
}
Ok(e)
}
/// Argument / template RHS: prefer a full expression; else interpolated text.
/// Hyphenated prose (`none-falsy`) is not parsed as subtraction.
pub fn parse_value_or_interp(input: &str) -> Result<Expr> {
let s = input.trim();
if s.is_empty() {
return Ok(Expr::Literal(Literal::Text(String::new())));
}
if has_hyphenated_prose(s) {
return Ok(parse_interp(s));
}
match parse_expr(s) {
Ok(e) => Ok(e),
Err(_) => Ok(parse_interp(s)),
}
}
fn has_hyphenated_prose(s: &str) -> bool {
let chars: Vec<char> = s.chars().collect();
for i in 1..chars.len().saturating_sub(1) {
if chars[i] != '-' {
continue;
}
let left = chars[i - 1];
let right = chars[i + 1];
if left.is_whitespace() || right.is_whitespace() || left == '`' || right == '`' {
continue;
}
// `none-falsy` / `Hello-World` — not `` `n` - 1 ``
if left.is_alphanumeric() || right.is_alphanumeric() || !left.is_ascii() || !right.is_ascii()
{
return true;
}
}
false
}
pub fn parse_interp(s: &str) -> Expr {
let mut parts = Vec::new();
let mut rest = s;
while !rest.is_empty() {
if let Some(start) = rest.find('`') {
if start > 0 {
parts.push(InterpPart::Lit(rest[..start].to_string()));
}
let after = &rest[start + 1..];
if let Some(end) = after.find('`') {
let name = after[..end].to_string();
parts.push(InterpPart::Var(name));
rest = &after[end + 1..];
} else {
parts.push(InterpPart::Lit(format!("`{after}")));
break;
}
} else {
parts.push(InterpPart::Lit(rest.to_string()));
break;
}
}
if parts.len() == 1 {
match &parts[0] {
InterpPart::Lit(t) => return Expr::Literal(Literal::Text(t.clone())),
InterpPart::Var(n) => return Expr::Var(n.clone()),
}
}
Expr::Interp(parts)
}
struct Parser<'a> {
src: &'a str,
i: usize,
}
impl<'a> Parser<'a> {
fn new(src: &'a str) -> Self {
Self { src, i: 0 }
}
fn rest(&self) -> &str {
&self.src[self.i..]
}
fn skip_ws(&mut self) {
while let Some(c) = self.peek_char() {
if c.is_whitespace() {
self.bump_char();
} else {
break;
}
}
}
fn peek_char(&self) -> Option<char> {
self.rest().chars().next()
}
fn bump_char(&mut self) -> Option<char> {
let mut chars = self.rest().chars();
let c = chars.next()?;
self.i += c.len_utf8();
Some(c)
}
fn starts_with(&self, s: &str) -> bool {
self.rest().starts_with(s)
}
fn eat(&mut self, s: &str) -> bool {
if self.starts_with(s) {
self.i += s.len();
true
} else {
false
}
}
fn parse_or(&mut self) -> Result<Expr> {
let mut left = self.parse_and()?;
loop {
self.skip_ws();
if self.eat("or") {
// ensure word boundary
if self.peek_char().map(|c| c.is_alphanumeric() || c == '_').unwrap_or(false) {
self.i -= 2;
break;
}
let right = self.parse_and()?;
left = Expr::Binary {
op: BinaryOp::Or,
left: Box::new(left),
right: Box::new(right),
};
} else {
break;
}
}
Ok(left)
}
fn parse_and(&mut self) -> Result<Expr> {
let mut left = self.parse_cmp()?;
loop {
self.skip_ws();
if self.eat("and") {
if self.peek_char().map(|c| c.is_alphanumeric() || c == '_').unwrap_or(false) {
self.i -= 3;
break;
}
let right = self.parse_cmp()?;
left = Expr::Binary {
op: BinaryOp::And,
left: Box::new(left),
right: Box::new(right),
};
} else {
break;
}
}
Ok(left)
}
fn parse_cmp(&mut self) -> Result<Expr> {
let mut left = self.parse_add()?;
self.skip_ws();
let op = if self.eat("==") {
Some(BinaryOp::Eq)
} else if self.eat("!=") {
Some(BinaryOp::Ne)
} else if self.eat("<=") {
Some(BinaryOp::Le)
} else if self.eat(">=") {
Some(BinaryOp::Ge)
} else if self.eat("<") {
Some(BinaryOp::Lt)
} else if self.eat(">") {
Some(BinaryOp::Gt)
} else {
None
};
if let Some(op) = op {
let right = self.parse_add()?;
left = Expr::Binary {
op,
left: Box::new(left),
right: Box::new(right),
};
}
Ok(left)
}
fn parse_add(&mut self) -> Result<Expr> {
let mut left = self.parse_mul()?;
loop {
self.skip_ws();
if self.eat("+") {
let right = self.parse_mul()?;
left = Expr::Binary {
op: BinaryOp::Add,
left: Box::new(left),
right: Box::new(right),
};
} else if self.eat("-") {
let right = self.parse_mul()?;
left = Expr::Binary {
op: BinaryOp::Sub,
left: Box::new(left),
right: Box::new(right),
};
} else {
break;
}
}
Ok(left)
}
fn parse_mul(&mut self) -> Result<Expr> {
let mut left = self.parse_unary()?;
loop {
self.skip_ws();
if self.eat("*") {
let right = self.parse_unary()?;
left = Expr::Binary {
op: BinaryOp::Mul,
left: Box::new(left),
right: Box::new(right),
};
} else if self.eat("/") {
let right = self.parse_unary()?;
left = Expr::Binary {
op: BinaryOp::Div,
left: Box::new(left),
right: Box::new(right),
};
} else {
break;
}
}
Ok(left)
}
fn parse_unary(&mut self) -> Result<Expr> {
self.skip_ws();
if self.eat("not") {
if self.peek_char().map(|c| c.is_alphanumeric() || c == '_').unwrap_or(false) {
self.i -= 3;
} else {
let expr = self.parse_unary()?;
return Ok(Expr::Unary {
op: UnaryOp::Not,
expr: Box::new(expr),
});
}
}
if self.eat("-") {
let expr = self.parse_unary()?;
return Ok(Expr::Unary {
op: UnaryOp::Neg,
expr: Box::new(expr),
});
}
self.parse_primary()
}
fn parse_primary(&mut self) -> Result<Expr> {
self.skip_ws();
if self.eat("(") {
let e = self.parse_or()?;
self.skip_ws();
if !self.eat(")") {
bail!("expected ')'");
}
return Ok(e);
}
if self.eat("`") {
let start = self.i;
while let Some(c) = self.peek_char() {
if c == '`' {
break;
}
self.bump_char();
}
let name = self.src[start..self.i].to_string();
if !self.eat("`") {
bail!("unterminated `name`");
}
return Ok(Expr::Var(name));
}
if self.eat(">") {
// Inline call: `> name k=v`
self.skip_ws();
return Ok(Expr::Call(parse_call_tail(self.rest()).map(|(c, consumed)| {
self.i += consumed;
c
})?));
}
if self.starts_with("True") && is_word_end(self.rest(), 4) {
self.i += 4;
return Ok(Expr::Literal(Literal::Bool(true)));
}
if self.starts_with("False") && is_word_end(self.rest(), 5) {
self.i += 5;
return Ok(Expr::Literal(Literal::Bool(false)));
}
if self.starts_with("None") && is_word_end(self.rest(), 4) {
self.i += 4;
return Ok(Expr::Literal(Literal::None));
}
if self.peek_char().map(|c| c.is_ascii_digit()).unwrap_or(false) {
let start = self.i;
while self.peek_char().map(|c| c.is_ascii_digit()).unwrap_or(false) {
self.bump_char();
}
let n: i64 = self.src[start..self.i].parse()?;
return Ok(Expr::Literal(Literal::Int(n)));
}
// Bare identifier / text word
if self.peek_char().map(|c| c.is_alphanumeric() || c == '_' || !c.is_ascii()).unwrap_or(false)
{
let start = self.i;
while let Some(c) = self.peek_char() {
if c.is_whitespace() || matches!(c, '=' | '+' | '-' | '*' | '/' | '<' | '>' | '(' | ')' | '`' | '|' | ',')
{
break;
}
self.bump_char();
}
let word = &self.src[start..self.i];
return Ok(Expr::Literal(Literal::Text(word.to_string())));
}
bail!("unexpected expression input: {:?}", self.rest());
}
}
fn is_word_end(s: &str, len: usize) -> bool {
match s[len..].chars().next() {
None => true,
Some(c) => !(c.is_alphanumeric() || c == '_'),
}
}
/// Parse `name key=val …` / positional args; returns call + bytes consumed.
pub fn parse_call_tail(s: &str) -> Result<(CallExpr, usize)> {
use crate::ast::Arg;
let s = s.trim_start();
let original_len = s.len();
let callee = {
let mut parts = s.split_whitespace();
parts
.next()
.ok_or_else(|| anyhow::anyhow!("missing callee"))?
.to_string()
};
let after_callee_offset = {
let idx = s.find(&callee).unwrap();
idx + callee.len()
};
let mut args_str = s[after_callee_offset..].trim_start();
let mut args = Vec::new();
let mut seen_named = false;
while !args_str.is_empty() {
if let Some((key, after_eq)) = try_named_arg(args_str) {
seen_named = true;
let val_end = find_next_arg_boundary(after_eq);
let val_raw = after_eq[..val_end].trim_end();
args.push(Arg::Named {
name: key,
value: parse_value_or_interp(val_raw)?,
});
args_str = after_eq[val_end..].trim_start();
} else {
if seen_named {
bail!("positional argument after named argument is not allowed");
}
let (tok, rest) = split_first_token(args_str);
if tok.is_empty() {
break;
}
args.push(Arg::Positional(parse_value_or_interp(tok)?));
args_str = rest.trim_start();
}
}
Ok((CallExpr { callee, args }, original_len))
}
/// If `s` begins with `ident=`, return (ident, rest_after_eq).
fn try_named_arg(s: &str) -> Option<(String, &str)> {
let s = s.trim_start();
for (i, c) in s.char_indices() {
if c == '=' {
if i == 0 {
return None;
}
let key = &s[..i];
if key.chars().any(|ch| ch.is_whitespace()) {
return None;
}
return Some((key.to_string(), &s[i + 1..]));
}
if c.is_whitespace() {
return None;
}
}
None
}
fn split_first_token(s: &str) -> (&str, &str) {
let s = s.trim_start();
if s.starts_with('`') {
// `` `name` `` as one token
if let Some(end) = s[1..].find('`') {
let end = end + 2; // include closing `
return (&s[..end], &s[end..]);
}
}
match s.find(char::is_whitespace) {
Some(i) => (&s[..i], &s[i..]),
None => (s, ""),
}
}
fn find_next_arg_boundary(after_eq: &str) -> usize {
// Look for ` <ident>=` pattern not inside backticks (UTF-8 safe).
let mut in_bt = false;
for (i, c) in after_eq.char_indices() {
if c == '`' {
in_bt = !in_bt;
continue;
}
if !in_bt && c.is_whitespace() {
let rest = &after_eq[i..];
let trimmed = rest.trim_start();
let skipped = rest.len() - trimmed.len();
if let Some(eq_at) = trimmed.find('=') {
let key = &trimmed[..eq_at];
if !key.is_empty()
&& !key.contains(char::is_whitespace)
&& key
.chars()
.all(|ch| ch.is_alphanumeric() || ch == '_' || !ch.is_ascii())
{
return i + skipped;
}
}
}
}
after_eq.len()
}
/// Parse `> callee args` call expression/statement text (without leading `>`).
pub fn parse_call_after_gt(after_gt: &str) -> Result<CallExpr> {
let (call, _) = parse_call_tail(after_gt.trim())?;
Ok(call)
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn cmp_and_arith() {
let e = parse_expr("`x` > 0").unwrap();
assert!(matches!(e, Expr::Binary { op: BinaryOp::Gt, .. }));
let e = parse_expr("`n` + 1").unwrap();
assert!(matches!(e, Expr::Binary { op: BinaryOp::Add, .. }));
}
#[test]
fn interp_hello() {
let e = parse_value_or_interp("Hello `谁`!").unwrap();
assert!(matches!(e, Expr::Interp(_)));
}
}
-554
View File
@@ -1,554 +0,0 @@
//! Line-oriented recursive descent → AST (no Bison).
mod expr;
pub use expr::{parse_call_after_gt, parse_expr, parse_value_or_interp};
use anyhow::{bail, Result};
use crate::ast::{
BranchArm, Expr, Function, Literal, Module, Stmt,
};
use crate::diagnostics::{Diagnostic, Span};
use crate::lex::{classify_source, ClassifiedLine, LineKind};
use crate::parse::expr::parse_call_after_gt as call_after_gt;
use crate::parse::expr::parse_expr as parse_expr_str;
/// Parse full source (with optional frontmatter) into a module AST.
pub fn parse_source(source: &str) -> Result<Module> {
let lines = classify_source(source);
parse_classified(&lines)
}
pub fn parse_classified(lines: &[ClassifiedLine]) -> Result<Module> {
let mut cur = Cursor::new(lines);
let imports = cur.parse_frontmatter()?;
let mut functions = Vec::new();
while cur.skip_noise() {
let Some(line) = cur.peek() else { break };
let trimmed = line.text.trim();
if is_heading(trimmed) {
functions.push(cur.parse_function(1)?);
} else {
bail!(
"{}:1: expected function heading `# …`, got: {trimmed}",
line.line_no
);
}
}
Ok(Module { imports, functions })
}
struct Cursor<'a> {
lines: &'a [ClassifiedLine],
i: usize,
}
impl<'a> Cursor<'a> {
fn new(lines: &'a [ClassifiedLine]) -> Self {
Self { lines, i: 0 }
}
fn peek(&self) -> Option<&'a ClassifiedLine> {
self.lines.get(self.i)
}
fn bump(&mut self) -> Option<&'a ClassifiedLine> {
let l = self.lines.get(self.i)?;
self.i += 1;
Some(l)
}
/// Skip blank + comment; return true if a line remains.
fn skip_noise(&mut self) -> bool {
while let Some(l) = self.peek() {
match l.kind {
LineKind::Blank | LineKind::Comment => {
self.i += 1;
}
LineKind::Code => return true,
}
}
false
}
fn parse_frontmatter(&mut self) -> Result<Vec<String>> {
let mut imports = Vec::new();
if !self.skip_noise() {
return Ok(imports);
}
let Some(first) = self.peek() else {
return Ok(imports);
};
if first.text.trim() != "---" {
return Ok(imports);
}
self.bump();
while let Some(line) = self.peek() {
let t = line.text.trim();
if t == "---" {
self.bump();
break;
}
if t.starts_with('>') {
let path = t[1..].trim();
if path.ends_with(".mq.md") {
imports.push(path.to_string());
}
}
self.bump();
}
Ok(imports)
}
fn parse_function(&mut self, min_level: u8) -> Result<Function> {
let line = self.bump().unwrap();
let (level, name) = parse_heading(line.text.trim())
.ok_or_else(|| anyhow::anyhow!("{}:1: expected heading", line.line_no))?;
if level < min_level {
bail!("{}:1: heading level {level} < expected {min_level}", line.line_no);
}
let mut fun = Function {
name: name.to_string(),
level,
span: Span {
line: line.line_no,
col: 1,
},
params: Vec::new(),
body: Vec::new(),
children: Vec::new(),
};
// Parameter zone: indented `- name` pure identifiers.
while self.skip_noise() {
let Some(l) = self.peek() else { break };
let trimmed = l.text.trim();
if is_heading(trimmed) {
let (nl, _) = parse_heading(trimmed).unwrap();
if nl > level {
fun.children.push(self.parse_function(level + 1)?);
continue;
}
break;
}
if let Some(param) = parse_param_line(trimmed) {
// Only accept as param before any body stmt (params first).
if fun.body.is_empty() {
fun.params.push(param);
self.bump();
continue;
}
}
break;
}
// Body until next heading at level <= ours.
while self.skip_noise() {
let Some(l) = self.peek() else { break };
let trimmed = l.text.trim();
if is_frame(trimmed) {
self.bump();
continue;
}
if is_heading(trimmed) {
let (nl, _) = parse_heading(trimmed).unwrap();
if nl > level {
fun.children.push(self.parse_function(level + 1)?);
continue;
}
break;
}
// Nested params mid-body shouldn't happen; treat `-` as control flow.
if trimmed.starts_with('+') || is_ordered_branch(trimmed) {
fun.body.push(self.parse_branch()?);
continue;
}
if trimmed.starts_with('-') {
fun.body.push(self.parse_loop_or_err()?);
continue;
}
fun.body.push(self.parse_simple_stmt()?);
}
Ok(fun)
}
fn parse_simple_stmt(&mut self) -> Result<Stmt> {
let line = self.bump().unwrap();
let span = Span {
line: line.line_no,
col: 1,
};
let trimmed = line.text.trim();
if is_frame(trimmed) {
bail!("{span}: unexpected frame line as statement");
}
// Bold return **…**
if trimmed.starts_with("**") && trimmed.ends_with("**") && trimmed.len() >= 4 {
let inner = &trimmed[2..trimmed.len() - 2];
let value = parse_expr_str(inner)?;
return Ok(Stmt::Return { value, span });
}
// Italic statement *…*
if trimmed.starts_with('*') && trimmed.ends_with('*') && !trimmed.starts_with("**") {
let inner = &trimmed[1..trimmed.len() - 1];
return parse_assign_or_expr_stmt(inner, span);
}
// Call >
if trimmed.starts_with('>') {
let call = call_after_gt(trimmed[1..].trim())?;
return Ok(Stmt::Call { call, span });
}
// Bare assign `` `x` = … `` possibly followed by table
if trimmed.starts_with('`') {
if let Some(stmt) = self.parse_backtick_assign(trimmed, span.clone())? {
return Ok(stmt);
}
}
Err(Diagnostic::new(None, span, format!("unrecognized statement: {trimmed}")).into())
}
fn parse_backtick_assign(&mut self, trimmed: &str, span: Span) -> Result<Option<Stmt>> {
// `name` = [rhs]
let Some(rest) = trimmed.strip_prefix('`') else {
return Ok(None);
};
let Some(end) = rest.find('`') else {
return Ok(None);
};
let name = rest[..end].to_string();
let after = rest[end + 1..].trim_start();
if !after.starts_with('=') {
return Ok(None);
}
let rhs = after[1..].trim();
if rhs.is_empty() {
// Consume following table if present.
let list = self.consume_table()?;
return Ok(Some(Stmt::Assign {
name,
value: Expr::List(list.into_iter().map(Expr::Literal).collect()),
span,
}));
}
Ok(Some(Stmt::Assign {
name,
value: parse_value_or_interp(rhs)?,
span,
}))
}
fn consume_table(&mut self) -> Result<Vec<Literal>> {
self.skip_noise();
let mut rows = Vec::new();
let mut header_done = false;
let mut sep_done = false;
while let Some(l) = self.peek() {
if l.kind != LineKind::Code {
break;
}
let t = l.text.trim();
if !t.starts_with('|') {
break;
}
self.bump();
let cells = split_table_row(t);
if !header_done {
header_done = true;
continue;
}
if !sep_done && cells.iter().all(|c| c.chars().all(|ch| ch == '-' || ch == ':' || ch.is_whitespace() || ch == '|'))
{
// separator row like |----|
sep_done = true;
continue;
}
// data row — single column examples: take first cell
if let Some(cell) = cells.first() {
rows.push(Literal::Text(cell.clone()));
}
sep_done = true;
}
if !header_done {
bail!("expected GFM table after empty assignment");
}
Ok(rows)
}
fn parse_branch(&mut self) -> Result<Stmt> {
let first = self.peek().unwrap();
let span = Span {
line: first.line_no,
col: 1,
};
let base_indent = indent_of(&first.text);
let mut arms = Vec::new();
while self.skip_noise() {
let Some(l) = self.peek() else { break };
let ind = indent_of(&l.text);
if ind < base_indent {
break;
}
let trimmed = l.text.trim();
let cond_src = if let Some(rest) = trimmed.strip_prefix('+') {
rest.trim()
} else if let Some(rest) = strip_ordered(trimmed) {
rest
} else {
break;
};
if ind != base_indent {
break;
}
self.bump();
let condition = if cond_src == "*" || cond_src.is_empty() {
None
} else {
Some(parse_expr_str(cond_src)?)
};
let body = self.parse_indented_body(base_indent)?;
arms.push(BranchArm { condition, body });
}
if arms.is_empty() {
bail!("{span}: empty branch");
}
Ok(Stmt::Branch { arms, span })
}
fn parse_loop_or_err(&mut self) -> Result<Stmt> {
let line = self.bump().unwrap();
let span = Span {
line: line.line_no,
col: 1,
};
let base_indent = indent_of(&line.text);
let trimmed = line.text.trim();
let rest = trimmed.strip_prefix('-').unwrap().trim();
// foreach: [item](collection)
if let Some((item, coll)) = parse_foreach_header(rest) {
let body = self.parse_indented_body(base_indent)?;
return Ok(Stmt::ForEach {
item,
collection: coll,
body,
span,
});
}
// while: expression
let condition = parse_expr_str(rest)?;
let body = self.parse_indented_body(base_indent)?;
Ok(Stmt::While {
condition,
body,
span,
})
}
fn parse_indented_body(&mut self, parent_indent: usize) -> Result<Vec<Stmt>> {
let mut body = Vec::new();
while self.skip_noise() {
let Some(l) = self.peek() else { break };
let ind = indent_of(&l.text);
if ind <= parent_indent {
// Same-indent `+`/`-` ends body (next arm / sibling).
break;
}
let trimmed = l.text.trim();
if is_frame(trimmed) {
self.bump();
continue;
}
if is_heading(trimmed) {
break;
}
if trimmed.starts_with('+') || is_ordered_branch(trimmed) {
// Nested branch inside body
body.push(self.parse_branch()?);
continue;
}
if trimmed.starts_with('-') {
body.push(self.parse_loop_or_err()?);
continue;
}
body.push(self.parse_simple_stmt()?);
}
Ok(body)
}
}
fn parse_assign_or_expr_stmt(inner: &str, span: Span) -> Result<Stmt> {
let inner = inner.trim();
// `` `name` = … ``
if let Some(rest) = inner.strip_prefix('`') {
if let Some(end) = rest.find('`') {
let name = rest[..end].to_string();
let after = rest[end + 1..].trim_start();
if let Some(rhs) = after.strip_prefix('=') {
let rhs = rhs.trim();
// Inline call assign: `> fn …`
let value = if rhs.starts_with('>') {
Expr::Call(call_after_gt(rhs[1..].trim())?)
} else {
parse_value_or_interp(rhs)?
};
return Ok(Stmt::Assign {
name,
value,
span,
});
}
}
}
bail!("{span}: italic statement must be an assignment (`name` = …)")
}
fn parse_param_line(trimmed: &str) -> Option<String> {
let rest = trimmed.strip_prefix('-')?.trim();
if rest.is_empty() || rest.contains('`') || rest.contains('[') || rest.contains('=') {
return None;
}
if rest.split_whitespace().count() != 1 {
return None;
}
// Reject if looks like comparison / operator expr
if rest.contains('>') || rest.contains('<') || rest.contains('+') || rest.contains('*') {
return None;
}
Some(rest.to_string())
}
fn parse_foreach_header(rest: &str) -> Option<(String, String)> {
// [item](collection)
let rest = rest.trim();
if !rest.starts_with('[') {
return None;
}
let end_item = rest.find(']')?;
let item = rest[1..end_item].to_string();
let after = rest[end_item + 1..].trim_start();
if !after.starts_with('(') || !after.ends_with(')') {
return None;
}
let coll = after[1..after.len() - 1].to_string();
Some((item, coll))
}
fn parse_heading(trimmed: &str) -> Option<(u8, &str)> {
if !trimmed.starts_with('#') {
return None;
}
let mut level = 0u8;
for c in trimmed.chars() {
if c == '#' {
level = level.saturating_add(1);
} else {
break;
}
}
if level == 0 || level > 6 {
return None;
}
let name = trimmed[level as usize..].trim();
if name.is_empty() {
return None;
}
Some((level, name))
}
fn is_heading(trimmed: &str) -> bool {
parse_heading(trimmed).is_some()
}
fn is_frame(trimmed: &str) -> bool {
if trimmed.len() < 3 {
return false;
}
trimmed.chars().all(|c| c == '-') || trimmed.chars().all(|c| c == '*')
}
fn is_ordered_branch(trimmed: &str) -> bool {
strip_ordered(trimmed).is_some()
}
fn strip_ordered(trimmed: &str) -> Option<&str> {
let mut chars = trimmed.chars();
let mut saw_digit = false;
while let Some(c) = chars.next() {
if c.is_ascii_digit() {
saw_digit = true;
continue;
}
if c == '.' && saw_digit {
return Some(chars.as_str().trim_start());
}
return None;
}
None
}
fn indent_of(text: &str) -> usize {
text.chars()
.take_while(|c| *c == ' ' || *c == '\t')
.map(|c| if c == '\t' { 4 } else { 1 })
.sum()
}
fn split_table_row(line: &str) -> Vec<String> {
let t = line.trim();
let t = t.strip_prefix('|').unwrap_or(t);
let t = t.strip_suffix('|').unwrap_or(t);
t.split('|').map(|c| c.trim().to_string()).collect()
}
#[cfg(test)]
mod tests {
use super::*;
use crate::ast::Stmt;
#[test]
fn parse_hello() {
let src = include_str!("../../examples/structure/hello.mq.md");
let m = parse_source(src).unwrap();
assert_eq!(m.functions.len(), 1);
assert_eq!(m.functions[0].name, "Hello World");
assert_eq!(m.functions[0].body.len(), 1);
assert!(matches!(m.functions[0].body[0], Stmt::Call { .. }));
}
#[test]
fn parse_index() {
let src = include_str!("../../examples/structure/nested-call.mq.md");
let m = parse_source(src).unwrap();
assert!(m.imports.is_empty());
let main = m.functions.iter().find(|f| f.name == "main").unwrap();
assert_eq!(main.children.len(), 1);
assert_eq!(main.children[0].name, "问候");
assert_eq!(main.children[0].params, vec!["谁".to_string()]);
}
#[test]
fn parse_branch() {
let src = include_str!("../../examples/structure/branch.mq.md");
let m = parse_source(src).unwrap();
let main = &m.functions[0];
assert!(main.body.iter().any(|s| matches!(s, Stmt::Branch { .. })));
}
}
-42
View File
@@ -1,42 +0,0 @@
//! Runtime values (Phase I).
use std::fmt;
#[derive(Debug, Clone, PartialEq)]
pub enum Value {
None,
Bool(bool),
Int(i64),
Text(String),
/// Single-column table rows (v0); multi-column later.
List(Vec<Value>),
}
impl Value {
pub fn truthy(&self) -> bool {
match self {
Value::None => false,
Value::Bool(b) => *b,
Value::Int(n) => *n != 0,
Value::Text(s) => !s.is_empty(),
Value::List(xs) => !xs.is_empty(),
}
}
pub fn as_display(&self) -> String {
match self {
Value::None => "None".into(),
Value::Bool(true) => "True".into(),
Value::Bool(false) => "False".into(),
Value::Int(n) => n.to_string(),
Value::Text(s) => s.clone(),
Value::List(_) => "<list>".into(),
}
}
}
impl fmt::Display for Value {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
write!(f, "{}", self.as_display())
}
}
-339
View File
@@ -1,339 +0,0 @@
//! HTML shell for `marqdo view`.
use std::path::Path;
use crate::view::render::FileViewModel;
pub fn escape(s: &str) -> String {
s.chars()
.map(|c| match c {
'&' => "&amp;".into(),
'<' => "&lt;".into(),
'>' => "&gt;".into(),
'"' => "&quot;".into(),
'\'' => "&#39;".into(),
_ => c.to_string(),
})
.collect()
}
pub fn layout(title: &str, nav: &str, main: &str) -> String {
format!(
r##"<!DOCTYPE html>
<html lang="zh-CN">
<head>
<meta charset="utf-8"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>{title} · marqdo view</title>
<link rel="preconnect" href="https://fonts.googleapis.com"/>
<link href="https://fonts.googleapis.com/css2?family=Fraunces:opsz,wght@9..144,600;9..144,700&family=IBM+Plex+Mono:wght@400;500&family=Sora:wght@400;600&display=swap" rel="stylesheet"/>
<style>
:root {{
--bg0: #0f1c1a;
--bg1: #162824;
--panel: #1c322d;
--ink: #e7f2ee;
--muted: #9bb5ac;
--accent: #3ecf8e;
--accent-dim: #2a9b6a;
--call: #5ec8ff;
--branch: #f0b429;
--loop: #ff7a59;
--ret: #c4a7ff;
--err: #ff6b6b;
--line: rgba(255,255,255,0.08);
}}
* {{ box-sizing: border-box; }}
body {{
margin: 0;
min-height: 100vh;
font-family: "Sora", system-ui, sans-serif;
color: var(--ink);
background:
radial-gradient(1200px 600px at 10% -10%, #1a3d34 0%, transparent 55%),
radial-gradient(900px 500px at 100% 0%, #243528 0%, transparent 50%),
linear-gradient(165deg, var(--bg0), var(--bg1));
}}
a {{ color: var(--accent); text-decoration: none; }}
a:hover {{ text-decoration: underline; }}
.shell {{
display: grid;
grid-template-columns: minmax(220px, 280px) 1fr;
min-height: 100vh;
}}
@media (max-width: 800px) {{
.shell {{ grid-template-columns: 1fr; }}
}}
.nav {{
border-right: 1px solid var(--line);
background: rgba(0,0,0,0.22);
padding: 1.25rem 1rem 2rem;
overflow: auto;
}}
.brand {{
font-family: "Fraunces", Georgia, serif;
font-size: 1.45rem;
font-weight: 700;
letter-spacing: -0.02em;
margin: 0 0 0.25rem;
}}
.brand span {{ color: var(--accent); }}
.tagline {{
color: var(--muted);
font-size: 0.8rem;
margin: 0 0 1.25rem;
}}
.nav h2 {{
font-size: 0.7rem;
text-transform: uppercase;
letter-spacing: 0.12em;
color: var(--muted);
margin: 1rem 0 0.4rem;
}}
.nav ul {{ list-style: none; padding: 0; margin: 0; }}
.nav li {{ margin: 0.15rem 0; }}
.nav a.file {{
display: block;
padding: 0.35rem 0.5rem;
border-radius: 6px;
color: var(--ink);
font-family: "IBM Plex Mono", monospace;
font-size: 0.78rem;
}}
.nav a.file:hover, .nav a.file.active {{
background: rgba(62, 207, 142, 0.12);
text-decoration: none;
}}
.folder {{ color: var(--muted); font-size: 0.75rem; margin-top: 0.75rem; }}
main.panel {{
padding: 1.5rem 1.75rem 3rem;
overflow: auto;
}}
h1.page {{
font-family: "Fraunces", Georgia, serif;
font-size: 1.75rem;
margin: 0 0 0.5rem;
}}
.meta {{ color: var(--muted); font-size: 0.85rem; margin-bottom: 1.5rem; }}
section.block {{
margin: 1.25rem 0 1.75rem;
}}
section.block > h2 {{
font-size: 0.75rem;
text-transform: uppercase;
letter-spacing: 0.1em;
color: var(--muted);
margin: 0 0 0.65rem;
border-bottom: 1px solid var(--line);
padding-bottom: 0.35rem;
}}
.card {{
background: var(--panel);
border: 1px solid var(--line);
border-radius: 10px;
padding: 0.85rem 1rem;
margin: 0.55rem 0;
}}
.fun-card {{ border-left: 3px solid var(--accent); }}
.call-card {{ border-left: 3px solid var(--call); }}
.branch-card {{ border-left: 3px solid var(--branch); }}
.loop-card {{ border-left: 3px solid var(--loop); }}
.ret-card {{ border-left: 3px solid var(--ret); }}
.badge {{
display: inline-block;
font-family: "IBM Plex Mono", monospace;
font-size: 0.7rem;
padding: 0.1rem 0.4rem;
border-radius: 4px;
background: rgba(255,255,255,0.06);
margin-right: 0.35rem;
}}
.params {{ margin: 0.35rem 0; }}
.chip {{
display: inline-block;
font-family: "IBM Plex Mono", monospace;
font-size: 0.75rem;
padding: 0.15rem 0.45rem;
margin: 0.15rem;
border-radius: 999px;
background: rgba(62, 207, 142, 0.15);
color: var(--accent);
}}
.nested {{ margin-left: 0.85rem; padding-left: 0.75rem; border-left: 1px dashed var(--line); }}
.arm {{
margin: 0.4rem 0;
padding: 0.5rem 0.65rem;
background: rgba(0,0,0,0.2);
border-radius: 8px;
}}
.out {{
font-family: "IBM Plex Mono", monospace;
font-size: 0.85rem;
white-space: pre-wrap;
background: #0a1210;
border-radius: 8px;
padding: 0.85rem 1rem;
border: 1px solid var(--line);
}}
.out.ok {{ box-shadow: inset 3px 0 0 var(--accent-dim); }}
.out.fail {{ box-shadow: inset 3px 0 0 var(--err); color: #ffc9c9; }}
.source {{
font-family: "IBM Plex Mono", monospace;
font-size: 0.78rem;
white-space: pre-wrap;
background: #0a1210;
border-radius: 8px;
padding: 0.85rem 1rem;
border: 1px solid var(--line);
line-height: 1.45;
}}
.err {{ color: var(--err); }}
.comment-card {{
border-left: 3px solid var(--muted);
background: rgba(255,255,255,0.03);
}}
.comment-text {{
color: var(--muted);
font-size: 0.9rem;
line-height: 1.45;
}}
code.expr {{
font-family: "IBM Plex Mono", monospace;
font-size: 0.82rem;
color: var(--ink);
}}
.welcome {{ max-width: 36rem; }}
.welcome p {{ color: var(--muted); line-height: 1.55; }}
</style>
</head>
<body>
<div class="shell">
<aside class="nav">
<p class="brand">marq<span>do</span> view</p>
<p class="tagline">Markup structure · live output</p>
{nav}
</aside>
<main class="panel">
{main}
</main>
</div>
</body>
</html>
"##,
title = escape(title),
nav = nav,
main = main
)
}
pub fn nav_html(files: &[std::path::PathBuf], active: Option<&str>) -> String {
let mut out = String::from("<h2>Files</h2><ul>");
let mut last_folder = String::new();
for f in files {
let rel = f.to_string_lossy().replace('\\', "/");
let folder = Path::new(&rel)
.parent()
.map(|p| p.to_string_lossy().to_string())
.unwrap_or_default();
if folder != last_folder {
if !folder.is_empty() {
out.push_str(&format!(
"</ul><div class=\"folder\">{}</div><ul>",
escape(&folder)
));
}
last_folder = folder;
}
let name = Path::new(&rel)
.file_name()
.and_then(|s| s.to_str())
.unwrap_or(&rel);
let active_cls = if active == Some(rel.as_str()) {
" active"
} else {
""
};
let href = format!("/file?path={}", urlencoding_encode(&rel));
out.push_str(&format!(
"<li><a class=\"file{active_cls}\" href=\"{href}\">{}</a></li>",
escape(name)
));
}
out.push_str("</ul>");
out
}
fn urlencoding_encode(s: &str) -> String {
let mut out = String::new();
for b in s.bytes() {
match b {
b'A'..=b'Z' | b'a'..=b'z' | b'0'..=b'9' | b'-' | b'_' | b'.' | b'~' | b'/' => {
out.push(b as char);
}
_ => out.push_str(&format!("%{b:02X}")),
}
}
out
}
pub fn page_index(files: &[std::path::PathBuf], only: Option<&Path>) -> String {
let nav = nav_html(files, None);
let main = if let Some(p) = only {
let rel = p.to_string_lossy().replace('\\', "/");
format!(
"<div class=\"welcome\"><h1 class=\"page\">Single file</h1><p class=\"meta\">Open <a href=\"/file?path={}\">{}</a></p></div>",
urlencoding_encode(&rel),
escape(&rel)
)
} else {
format!(
"<div class=\"welcome\"><h1 class=\"page\">Browse</h1><p>Select a <code>.mq.md</code> file in the index. Structure is rendered from the AST; output comes from the same pipeline as <code>marqdo run</code>.</p><p class=\"meta\">{} file(s)</p></div>",
files.len()
)
};
layout("index", &nav, &main)
}
pub fn page_file(files: &[std::path::PathBuf], rel: &str, vm: &FileViewModel) -> String {
let nav = nav_html(files, Some(rel));
let status = if vm.ok { "ok" } else { "fail" };
let out_text = if vm.ok {
if vm.stdout.is_empty() {
"(no stdout)".to_string()
} else {
escape(&vm.stdout)
}
} else {
escape(&vm.stderr)
};
let main = format!(
r#"
<h1 class="page">{title}</h1>
<p class="meta">{rel}</p>
<section class="block">
<h2>Structure</h2>
{structure}
</section>
<section class="block">
<h2>Execution</h2>
<div class="out {status}">{out}</div>
</section>
<section class="block">
<h2>Source</h2>
<pre class="source">{source}</pre>
</section>
"#,
title = escape(
Path::new(rel)
.file_stem()
.and_then(|s| s.to_str())
.unwrap_or(rel)
),
rel = escape(rel),
structure = vm.structure_html,
status = status,
out = out_text,
source = escape(&vm.source),
);
layout(rel, &nav, &main)
}
-307
View File
@@ -1,307 +0,0 @@
//! `marqdo view` — local HTML browser for `.mq.md` structure + output.
mod html;
mod render;
use std::fs;
use std::net::SocketAddr;
use std::path::{Path, PathBuf};
use std::process::Command;
use anyhow::{bail, Context, Result};
use tiny_http::{Header, Method, Request, Response, Server, StatusCode};
use crate::view::html::{escape, page_file, page_index};
use crate::view::render::{render_module_structure, FileViewModel};
use crate::{run_file_capture, RunOptions};
pub struct ViewOptions {
pub path: PathBuf,
pub host: String,
pub port: u16,
pub open_browser: bool,
}
struct ViewRoot {
/// Directory that paths are resolved against.
root: PathBuf,
/// If Some, only this relative file is in scope (single-file mode).
only_file: Option<PathBuf>,
files: Vec<PathBuf>,
}
/// Block serving until Ctrl+C (process kill).
pub fn serve(opts: ViewOptions) -> Result<()> {
let root_info = build_root(&opts.path)?;
let addr: SocketAddr = format!("{}:{}", opts.host, opts.port)
.parse()
.context("invalid host/port")?;
let server = Server::http(addr).map_err(|e| anyhow::anyhow!("listen {addr}: {e}"))?;
let url = format!("http://{}:{}/", opts.host, opts.port);
eprintln!("marqdo view: {url}");
eprintln!("root: {}", root_info.root.display());
eprintln!("{} .mq.md file(s). Ctrl+C to stop.", root_info.files.len());
if opts.open_browser {
let _ = open_url(&url);
}
for request in server.incoming_requests() {
if let Err(err) = handle(&root_info, request) {
eprintln!("view request error: {err:#}");
}
}
Ok(())
}
fn build_root(path: &Path) -> Result<ViewRoot> {
let path = if path.exists() {
path.canonicalize().unwrap_or_else(|_| path.to_path_buf())
} else {
bail!("path not found: {}", path.display());
};
if path.is_file() {
if !is_mq_md(&path) {
bail!("not a .mq.md file: {}", path.display());
}
let root = path
.parent()
.map(|p| p.to_path_buf())
.unwrap_or_else(|| PathBuf::from("."));
let rel = PathBuf::from(path.file_name().unwrap());
return Ok(ViewRoot {
root,
only_file: Some(rel.clone()),
files: vec![rel],
});
}
if !path.is_dir() {
bail!("not a file or directory: {}", path.display());
}
let mut files = Vec::new();
collect_mq_md(&path, &path, &mut files)?;
files.sort();
Ok(ViewRoot {
root: path,
only_file: None,
files,
})
}
fn collect_mq_md(root: &Path, dir: &Path, out: &mut Vec<PathBuf>) -> Result<()> {
for entry in fs::read_dir(dir).with_context(|| format!("read_dir {}", dir.display()))? {
let entry = entry?;
let p = entry.path();
if p.is_dir() {
collect_mq_md(root, &p, out)?;
} else if is_mq_md(&p) {
let rel = p.strip_prefix(root).unwrap_or(&p).to_path_buf();
out.push(rel);
}
}
Ok(())
}
fn is_mq_md(path: &Path) -> bool {
path.file_name()
.and_then(|s| s.to_str())
.map(|s| s.ends_with(".mq.md"))
.unwrap_or(false)
}
fn handle(root: &ViewRoot, request: Request) -> Result<()> {
let url = request.url().to_string();
let method = request.method().clone();
if method != Method::Get {
let resp = Response::from_string("method not allowed").with_status_code(StatusCode(405));
let _ = request.respond(resp);
return Ok(());
}
let (path_part, query) = split_url(&url);
match path_part {
"/" | "/index.html" => {
let body = page_index(&root.files, root.only_file.as_deref());
respond_html(request, body)
}
"/file" => {
let rel = query_param(query, "path").unwrap_or_default();
let resolved = resolve_rel(root, &rel)?;
let vm = build_file_view(&resolved, &rel)?;
let body = page_file(&root.files, &rel, &vm);
respond_html(request, body)
}
"/api/tree" => {
let json = files_json(&root.files);
respond_json(request, json)
}
_ => {
let resp = Response::from_string("not found").with_status_code(StatusCode(404));
let _ = request.respond(resp);
Ok(())
}
}
}
fn build_file_view(abs: &Path, rel: &str) -> Result<FileViewModel> {
let source = fs::read_to_string(abs).with_context(|| format!("read {}", abs.display()))?;
let structure = match crate::load::load_module(abs) {
Ok(module) => render_module_structure(&module, &source),
Err(e) => format!(
"<div class=\"err\">parse/load error: {}</div>",
escape(&format!("{e:#}"))
),
};
let (stdout, stderr, ok) = match run_file_capture(abs, &RunOptions::default()) {
Ok(cap) => (cap.stdout, String::new(), true),
Err(e) => (String::new(), format!("{e:#}"), false),
};
Ok(FileViewModel {
rel_path: rel.to_string(),
source,
structure_html: structure,
stdout,
stderr,
ok,
})
}
fn resolve_rel(root: &ViewRoot, rel: &str) -> Result<PathBuf> {
if rel.is_empty() {
bail!("missing path");
}
let rel_path = PathBuf::from(rel.replace('\\', "/"));
if rel_path
.components()
.any(|c| matches!(c, std::path::Component::ParentDir))
{
bail!("path escapes root");
}
if let Some(only) = &root.only_file {
if &rel_path != only {
bail!("file not in view scope");
}
} else if !root.files.iter().any(|f| f == &rel_path) {
// also allow forward-slash normalized compare
let norm = rel_path.to_string_lossy().replace('\\', "/");
if !root
.files
.iter()
.any(|f| f.to_string_lossy().replace('\\', "/") == norm)
{
bail!("unknown file: {rel}");
}
}
let abs = root.root.join(&rel_path);
let canon = abs.canonicalize().unwrap_or(abs.clone());
let root_canon = root.root.canonicalize().unwrap_or_else(|_| root.root.clone());
if !canon.starts_with(&root_canon) {
bail!("path escapes root");
}
if !is_mq_md(&canon) {
bail!("not a .mq.md file");
}
Ok(canon)
}
fn split_url(url: &str) -> (&str, &str) {
match url.split_once('?') {
Some((p, q)) => (p, q),
None => (url, ""),
}
}
fn query_param<'a>(query: &'a str, key: &str) -> Option<String> {
for pair in query.split('&') {
let mut kv = pair.splitn(2, '=');
let k = kv.next()?;
let v = kv.next().unwrap_or("");
if k == key {
return Some(urlencoding_decode(v));
}
}
None
}
fn urlencoding_decode(s: &str) -> String {
// Minimal decode for %XX and +
let mut out = String::new();
let bytes = s.as_bytes();
let mut i = 0;
while i < bytes.len() {
match bytes[i] {
b'+' => {
out.push(' ');
i += 1;
}
b'%' if i + 2 < bytes.len() => {
let hex = &s[i + 1..i + 3];
if let Ok(v) = u8::from_str_radix(hex, 16) {
out.push(v as char);
i += 3;
} else {
out.push('%');
i += 1;
}
}
c => {
out.push(c as char);
i += 1;
}
}
}
out
}
fn files_json(files: &[PathBuf]) -> String {
let list: Vec<String> = files
.iter()
.map(|f| format!("\"{}\"", escape_json(&f.to_string_lossy().replace('\\', "/"))))
.collect();
format!("{{\"files\":[{}]}}", list.join(","))
}
fn escape_json(s: &str) -> String {
s.replace('\\', "\\\\").replace('"', "\\\"")
}
fn respond_html(request: Request, body: String) -> Result<()> {
let header = Header::from_bytes(&b"Content-Type"[..], &b"text/html; charset=utf-8"[..])
.map_err(|_| anyhow::anyhow!("header"))?;
let resp = Response::from_string(body).with_header(header);
request.respond(resp).context("respond")?;
Ok(())
}
fn respond_json(request: Request, body: String) -> Result<()> {
let header = Header::from_bytes(&b"Content-Type"[..], &b"application/json; charset=utf-8"[..])
.map_err(|_| anyhow::anyhow!("header"))?;
let resp = Response::from_string(body).with_header(header);
request.respond(resp).context("respond")?;
Ok(())
}
fn open_url(url: &str) -> Result<()> {
#[cfg(target_os = "windows")]
{
Command::new("cmd")
.args(["/C", "start", "", url])
.spawn()
.context("open browser")?;
}
#[cfg(target_os = "macos")]
{
Command::new("open").arg(url).spawn().context("open browser")?;
}
#[cfg(all(unix, not(target_os = "macos")))]
{
Command::new("xdg-open")
.arg(url)
.spawn()
.context("open browser")?;
}
Ok(())
}
-424
View File
@@ -1,424 +0,0 @@
//! Render Marqdo AST as HTML fragments for `view`.
//!
//! Comments are not in the AST; they are interleaved from classified source lines.
//! Expressions are shown in surface syntax, never Rust `Debug`.
use crate::ast::{
Arg, BinaryOp, CallExpr, Expr, Function, InterpPart, Literal, Module, Stmt, UnaryOp,
};
use crate::lex::{classify_source, ClassifiedLine, LineKind};
use crate::view::html::escape;
pub struct FileViewModel {
#[allow(dead_code)]
pub rel_path: String,
pub source: String,
pub structure_html: String,
pub stdout: String,
pub stderr: String,
pub ok: bool,
}
pub fn render_module_structure(module: &Module, source: &str) -> String {
let lines = classify_source(source);
let mut out = String::new();
if !module.imports.is_empty() {
out.push_str("<div class=\"card\"><span class=\"badge\">import</span>");
for imp in &module.imports {
out.push_str(&format!("<span class=\"chip\">{}</span>", escape(imp)));
}
out.push_str("</div>");
}
let body_start = skip_frontmatter_end(&lines).unwrap_or(1);
let mut cursor = body_start;
if module.functions.is_empty() {
out.push_str(&emit_comments(&lines, cursor, u32::MAX));
if out.is_empty() {
out.push_str("<p class=\"meta\">(empty module)</p>");
}
return out;
}
// Leading comments before first function
let first = module.functions[0].span.line;
out.push_str(&emit_comments(&lines, cursor, first));
cursor = first;
for (i, fun) in module.functions.iter().enumerate() {
if i > 0 {
out.push_str(&emit_comments(&lines, cursor, fun.span.line));
}
let (html, next) = render_fun(fun, &lines, 0);
out.push_str(&html);
cursor = next;
}
// Trailing comments after last function tree
out.push_str(&emit_comments(&lines, cursor, u32::MAX));
out
}
/// Line after closing frontmatter `---`, or 1 if none.
fn skip_frontmatter_end(lines: &[ClassifiedLine]) -> Option<u32> {
let first_code = lines.iter().find(|l| l.kind == LineKind::Code)?;
if first_code.text.trim() != "---" {
return Some(1);
}
for l in lines.iter().skip_while(|l| l.line_no <= first_code.line_no) {
if l.kind == LineKind::Code && l.text.trim() == "---" {
return Some(l.line_no + 1);
}
}
Some(1)
}
fn emit_comments(lines: &[ClassifiedLine], from_line: u32, before_line: u32) -> String {
let mut s = String::new();
for l in lines {
if l.line_no < from_line {
continue;
}
if l.line_no >= before_line {
break;
}
if l.kind == LineKind::Comment {
let text = l.text.trim();
if text.is_empty() {
continue;
}
s.push_str(&format!(
"<div class=\"card comment-card\"><span class=\"badge\">comment</span><span class=\"comment-text\">{}</span></div>",
escape(text)
));
}
}
s
}
fn render_fun(fun: &Function, lines: &[ClassifiedLine], depth: usize) -> (String, u32) {
let mut s = String::new();
let nest = if depth > 0 { " nested" } else { "" };
s.push_str(&format!("<div class=\"card fun-card{nest}\">"));
s.push_str(&format!(
"<div><span class=\"badge\">fn · h{}</span><strong>{}</strong></div>",
fun.level,
escape(&fun.name)
));
if !fun.params.is_empty() {
s.push_str("<div class=\"params\">");
for p in &fun.params {
s.push_str(&format!("<span class=\"chip\">{}</span>", escape(p)));
}
s.push_str("</div>");
}
let mut cursor = fun.span.line + 1;
// Comments / gap before first body stmt or child
let first_body = fun.body.first().map(stmt_start);
let first_child = fun.children.first().map(|c| c.span.line);
let first_content = match (first_body, first_child) {
(Some(a), Some(b)) => Some(a.min(b)),
(Some(a), None) => Some(a),
(None, Some(b)) => Some(b),
(None, None) => None,
};
if let Some(fc) = first_content {
s.push_str(&emit_comments(lines, cursor, fc));
cursor = fc;
}
// Interleave body stmts and nested functions by source line
let mut bi = 0usize;
let mut ci = 0usize;
while bi < fun.body.len() || ci < fun.children.len() {
let stmt_line = fun.body.get(bi).map(stmt_start);
let child_line = fun.children.get(ci).map(|c| c.span.line);
let take_stmt = match (stmt_line, child_line) {
(Some(sl), Some(cl)) => sl <= cl,
(Some(_), None) => true,
(None, Some(_)) => false,
(None, None) => break,
};
if take_stmt {
let stmt = &fun.body[bi];
let start = stmt_start(stmt);
s.push_str(&emit_comments(lines, cursor, start));
let (html, end) = render_stmt(stmt, lines);
s.push_str(&html);
cursor = end;
bi += 1;
} else {
let child = &fun.children[ci];
s.push_str(&emit_comments(lines, cursor, child.span.line));
let (html, end) = render_fun(child, lines, depth + 1);
s.push_str(&format!("<div class=\"nested\">{html}</div>"));
cursor = end;
ci += 1;
}
}
s.push_str("</div>");
(s, cursor)
}
fn stmt_start(stmt: &Stmt) -> u32 {
match stmt {
Stmt::Assign { span, .. }
| Stmt::Return { span, .. }
| Stmt::Call { span, .. }
| Stmt::Branch { span, .. }
| Stmt::While { span, .. }
| Stmt::ForEach { span, .. } => span.line,
}
}
fn stmt_end_line(stmt: &Stmt) -> u32 {
match stmt {
Stmt::Assign { span, .. } | Stmt::Return { span, .. } | Stmt::Call { span, .. } => {
span.line + 1
}
Stmt::Branch { arms, span, .. } => {
let mut end = span.line + 1;
for arm in arms {
for st in &arm.body {
end = end.max(stmt_end_line(st));
}
}
end
}
Stmt::While { body, span, .. } | Stmt::ForEach { body, span, .. } => {
let mut end = span.line + 1;
for st in body {
end = end.max(stmt_end_line(st));
}
end
}
}
}
fn render_stmt(stmt: &Stmt, lines: &[ClassifiedLine]) -> (String, u32) {
let end = stmt_end_line(stmt);
let html = match stmt {
Stmt::Assign { name, value, .. } => format!(
"<div class=\"card\"><span class=\"badge\">bind</span><code class=\"expr\">`{}` = {}</code></div>",
escape(name),
escape(&expr_display(value))
),
Stmt::Return { value, .. } => format!(
"<div class=\"card ret-card\"><span class=\"badge\">return</span><code class=\"expr\">{}</code></div>",
escape(&expr_display(value))
),
Stmt::Call { call, .. } => format!(
"<div class=\"card call-card\"><span class=\"badge\">call</span><code class=\"expr\">{}</code></div>",
escape(&call_display(call))
),
Stmt::Branch { arms, .. } => {
let mut inner =
String::from("<div class=\"card branch-card\"><span class=\"badge\">branch</span>");
let mut arm_cursor = stmt_start(stmt) + 1;
for arm in arms {
let label = match &arm.condition {
None => "else".to_string(),
Some(c) => expr_display(c),
};
// comments before first stmt in arm (approx: between arms hard; use body starts)
let arm_first = arm.body.first().map(stmt_start);
inner.push_str(&format!(
"<div class=\"arm\"><span class=\"badge\">arm</span><code class=\"expr\">{}</code>",
escape(&label)
));
if let Some(af) = arm_first {
inner.push_str(&emit_comments(lines, arm_cursor, af));
arm_cursor = af;
}
inner.push_str("<div class=\"nested\">");
for st in &arm.body {
let start = stmt_start(st);
inner.push_str(&emit_comments(lines, arm_cursor, start));
let (h, e) = render_stmt(st, lines);
inner.push_str(&h);
arm_cursor = e;
}
inner.push_str("</div></div>");
}
inner.push_str("</div>");
inner
}
Stmt::While {
condition, body, ..
} => {
let mut inner = format!(
"<div class=\"card loop-card\"><span class=\"badge\">while</span><code class=\"expr\">{}</code><div class=\"nested\">",
escape(&expr_display(condition))
);
let mut cursor = stmt_start(stmt) + 1;
for st in body {
let start = stmt_start(st);
inner.push_str(&emit_comments(lines, cursor, start));
let (h, e) = render_stmt(st, lines);
inner.push_str(&h);
cursor = e;
}
inner.push_str("</div></div>");
inner
}
Stmt::ForEach {
item,
collection,
body,
..
} => {
let mut inner = format!(
"<div class=\"card loop-card\"><span class=\"badge\">foreach</span><code class=\"expr\">[{}]({})</code><div class=\"nested\">",
escape(item),
escape(collection)
);
let mut cursor = stmt_start(stmt) + 1;
for st in body {
let start = stmt_start(st);
inner.push_str(&emit_comments(lines, cursor, start));
let (h, e) = render_stmt(st, lines);
inner.push_str(&h);
cursor = e;
}
inner.push_str("</div></div>");
inner
}
};
(html, end)
}
fn call_display(call: &CallExpr) -> String {
let mut s = format!("> {}", call.callee);
for a in &call.args {
match a {
Arg::Positional(e) => {
s.push(' ');
s.push_str(&expr_display(e));
}
Arg::Named { name, value } => {
s.push(' ');
s.push_str(name);
s.push('=');
s.push_str(&expr_display(value));
}
}
}
s
}
/// Surface-syntax preview for view (not Debug).
pub fn expr_display(expr: &Expr) -> String {
expr_prec(expr, 0)
}
fn expr_prec(expr: &Expr, parent_prec: u8) -> String {
match expr {
Expr::Literal(lit) => lit_display(lit),
Expr::Var(name) => format!("`{name}`"),
Expr::Interp(parts) => {
let mut s = String::new();
for p in parts {
match p {
InterpPart::Lit(t) => s.push_str(t),
InterpPart::Var(n) => {
s.push('`');
s.push_str(n);
s.push('`');
}
}
}
s
}
Expr::Unary { op, expr } => {
let prec = 5;
let inner = match op {
UnaryOp::Not => format!("not {}", expr_prec(expr, prec)),
UnaryOp::Neg => format!("-{}", expr_prec(expr, prec)),
};
wrap(inner, prec, parent_prec)
}
Expr::Binary { op, left, right } => {
let (sym, prec) = bin_sym_prec(*op);
let inner = format!(
"{} {} {}",
expr_prec(left, prec),
sym,
expr_prec(right, prec + 1) // left-assoc bias
);
wrap(inner, prec, parent_prec)
}
Expr::Call(call) => call_display(call),
Expr::List(items) => {
let parts: Vec<String> = items.iter().map(|e| expr_prec(e, 0)).collect();
format!("[{}]", parts.join(", "))
}
}
}
fn wrap(inner: String, prec: u8, parent_prec: u8) -> String {
if prec < parent_prec {
format!("({inner})")
} else {
inner
}
}
fn bin_sym_prec(op: BinaryOp) -> (&'static str, u8) {
match op {
BinaryOp::Or => ("or", 1),
BinaryOp::And => ("and", 2),
BinaryOp::Eq => ("==", 3),
BinaryOp::Ne => ("!=", 3),
BinaryOp::Lt => ("<", 3),
BinaryOp::Le => ("<=", 3),
BinaryOp::Gt => (">", 3),
BinaryOp::Ge => (">=", 3),
BinaryOp::Add => ("+", 4),
BinaryOp::Sub => ("-", 4),
BinaryOp::Mul => ("*", 5),
BinaryOp::Div => ("/", 5),
}
}
fn lit_display(lit: &Literal) -> String {
match lit {
Literal::None => "None".into(),
Literal::Bool(true) => "True".into(),
Literal::Bool(false) => "False".into(),
Literal::Int(n) => n.to_string(),
Literal::Text(t) => t.clone(),
}
}
#[cfg(test)]
mod tests {
use super::*;
use crate::ast::{BinaryOp, Expr, Literal};
#[test]
fn expr_gt_is_surface() {
let e = Expr::Binary {
op: BinaryOp::Gt,
left: Box::new(Expr::Var("x".into())),
right: Box::new(Expr::Literal(Literal::Int(0))),
};
assert_eq!(expr_display(&e), "`x` > 0");
assert!(!expr_display(&e).contains("Binary"));
}
#[test]
fn structure_keeps_comments_and_surface_expr() {
let src = include_str!("../../examples/structure/nested-call.mq.md");
let module = crate::parse::parse_source(src).unwrap();
let html = render_module_structure(&module, src);
assert!(html.contains("comment-card"));
assert!(html.contains("print"));
assert!(!html.contains("Binary {"));
assert!(!html.contains("Literal(Int"));
}
}
+6
View File
@@ -0,0 +1,6 @@
---
title: marqdo语言测试用例的放置位置
date: 2026-08-11
---
## 这里用于放置marqdo语言的测试用例
+5
View File
@@ -0,0 +1,5 @@
---
title: hello marqdo!
---
> print "hello marqdo!"
-206
View File
@@ -1,206 +0,0 @@
use std::process::Command;
fn run(args: &[&str]) -> (i32, String, String) {
let output = Command::new(env!("CARGO_BIN_EXE_marqdo"))
.args(args)
.output()
.expect("failed to run marqdo");
let code = output.status.code().unwrap_or(1);
let stdout = String::from_utf8_lossy(&output.stdout).into_owned();
let stderr = String::from_utf8_lossy(&output.stderr).into_owned();
(code, stdout, stderr)
}
fn assert_out(path: &str, expect: &str) {
let (code, stdout, stderr) = run(&["run", path]);
assert_eq!(code, 0, "{path} stderr={stderr}");
assert_eq!(stdout.trim_end(), expect.trim_end(), "{path}");
}
fn assert_err(path: &str, substr: &str) {
let (code, stdout, stderr) = run(&["run", path]);
assert_ne!(code, 0, "{path} unexpectedly succeeded stdout={stdout}");
assert!(
stderr.contains(substr),
"{path} stderr missing {substr:?}: {stderr}"
);
}
#[test]
fn structure_hello() {
assert_out("examples/structure/hello.mq.md", "Hello World!");
}
#[test]
fn structure_nested_call() {
assert_out("examples/structure/nested-call.mq.md", "Hello World!");
}
#[test]
fn structure_positional_call() {
assert_out(
"examples/structure/positional-call.mq.md",
"Hello Marqdo!\nHello World!",
);
}
#[test]
fn structure_branch() {
assert_out("examples/structure/branch.mq.md", "零");
}
#[test]
fn structure_loop() {
assert_out(
"examples/structure/loop.mq.md",
"3\n2\n1\n今天吃苹果\n今天吃梨",
);
}
#[test]
fn structure_collection() {
assert_out("examples/structure/collection.mq.md", "苹果\n梨\n桃");
}
#[test]
fn structure_import() {
assert_out(
"examples/structure/import/main.mq.md",
"42\n你好,Marqdo!",
);
}
#[test]
fn keywords_print() {
assert_out(
"examples/keywords/print.mq.md",
"named form\npositional",
);
}
#[test]
fn keywords_bool_logic() {
assert_out(
"examples/keywords/bool-logic.mq.md",
"ok\nnone-falsy",
);
}
#[test]
fn error_undefined_var() {
assert_err(
"examples/errors/undefined-var.mq.md",
"undefined variable `missing`",
);
}
#[test]
fn error_unknown_fn() {
assert_err(
"examples/errors/unknown-fn.mq.md",
"unknown function `no_such_fn`",
);
}
#[test]
fn error_bad_arity() {
assert_err(
"examples/errors/bad-arity.mq.md",
"missing argument for parameter `x`",
);
}
#[test]
fn error_syntax_bad_line() {
assert_err(
"examples/errors/syntax-bad-line.mq.md",
"unrecognized statement",
);
}
fn assert_out_backend(path: &str, backend: &str, expect: &str) {
let (code, stdout, stderr) = run(&["run", path, "--backend", backend]);
assert_eq!(code, 0, "{path} backend={backend} stderr={stderr}");
assert_eq!(
stdout.trim_end(),
expect.trim_end(),
"{path} backend={backend}"
);
}
#[test]
fn bytecode_hello() {
assert_out_backend(
"examples/structure/hello.mq.md",
"bytecode",
"Hello World!",
);
}
#[test]
fn bytecode_branch() {
assert_out_backend("examples/structure/branch.mq.md", "bytecode", "零");
}
#[test]
fn bytecode_loop() {
assert_out_backend(
"examples/structure/loop.mq.md",
"bytecode",
"3\n2\n1\n今天吃苹果\n今天吃梨",
);
}
#[test]
fn bytecode_collection() {
assert_out_backend(
"examples/structure/collection.mq.md",
"bytecode",
"苹果\n梨\n桃",
);
}
#[test]
fn bytecode_print_keyword() {
assert_out_backend(
"examples/keywords/print.mq.md",
"bytecode",
"named form\npositional",
);
}
#[test]
fn bytecode_bool_logic() {
assert_out_backend(
"examples/keywords/bool-logic.mq.md",
"bytecode",
"ok\nnone-falsy",
);
}
#[test]
fn bytecode_nested_call() {
assert_out_backend(
"examples/structure/nested-call.mq.md",
"bytecode",
"Hello World!",
);
}
#[test]
fn bytecode_positional_call() {
assert_out_backend(
"examples/structure/positional-call.mq.md",
"bytecode",
"Hello Marqdo!\nHello World!",
);
}
#[test]
fn bytecode_import() {
assert_out_backend(
"examples/structure/import/main.mq.md",
"bytecode",
"42\n你好,Marqdo!",
);
}