Compare commits
5
Commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
111849d92a | ||
|
|
235384fb85 | ||
|
|
a9b59b361e | ||
|
|
c4501a17f2 | ||
|
|
5f00572e24 |
No files matched your search
@@ -1,50 +0,0 @@
|
|||||||
# Build public/ with marqdo and publish to the gh-pages branch.
|
|
||||||
name: User docs site
|
|
||||||
|
|
||||||
on:
|
|
||||||
push:
|
|
||||||
branches: [main, master]
|
|
||||||
paths:
|
|
||||||
- "public/**"
|
|
||||||
- "src/**"
|
|
||||||
- "Cargo.toml"
|
|
||||||
- "Cargo.lock"
|
|
||||||
- ".github/workflows/pages.yml"
|
|
||||||
- "scripts/build-public.*"
|
|
||||||
workflow_dispatch:
|
|
||||||
|
|
||||||
permissions:
|
|
||||||
contents: write
|
|
||||||
|
|
||||||
jobs:
|
|
||||||
build-and-deploy:
|
|
||||||
runs-on: ubuntu-latest
|
|
||||||
steps:
|
|
||||||
- uses: actions/checkout@v4
|
|
||||||
|
|
||||||
- name: Install Rust
|
|
||||||
uses: dtolnay/rust-toolchain@stable
|
|
||||||
|
|
||||||
- name: Build & export site
|
|
||||||
run: |
|
|
||||||
cargo build --release
|
|
||||||
find public -name '*.mq.md' ! -name 'utils.mq.md' ! -name '¹¤¾ß.mq.md' -print0 \
|
|
||||||
| xargs -0 -n1 ./target/release/marqdo run
|
|
||||||
./target/release/marqdo view output public -o public
|
|
||||||
|
|
||||||
- name: Verify site shape
|
|
||||||
run: |
|
|
||||||
if grep -R "tests/errors" public --include='*.html' ; then
|
|
||||||
echo "user site must not include tests/errors fixtures" >&2
|
|
||||||
exit 1
|
|
||||||
fi
|
|
||||||
test -f public/index.html
|
|
||||||
test -f public/00-welcome.mq.md
|
|
||||||
|
|
||||||
- name: Deploy to gh-pages
|
|
||||||
uses: peaceiris/actions-gh-pages@v4
|
|
||||||
with:
|
|
||||||
github_token: ${{ secrets.GITHUB_TOKEN }}
|
|
||||||
publish_dir: ./public
|
|
||||||
publish_branch: gh-pages
|
|
||||||
force_orphan: true
|
|
||||||
@@ -1,70 +0,0 @@
|
|||||||
# Build and attach release binaries when a version tag is pushed.
|
|
||||||
name: Release
|
|
||||||
|
|
||||||
on:
|
|
||||||
push:
|
|
||||||
tags:
|
|
||||||
- "v*"
|
|
||||||
|
|
||||||
permissions:
|
|
||||||
contents: write
|
|
||||||
|
|
||||||
jobs:
|
|
||||||
windows:
|
|
||||||
runs-on: windows-latest
|
|
||||||
steps:
|
|
||||||
- uses: actions/checkout@v4
|
|
||||||
|
|
||||||
- name: Install Rust
|
|
||||||
uses: dtolnay/rust-toolchain@stable
|
|
||||||
|
|
||||||
- name: Build release
|
|
||||||
run: cargo build --release
|
|
||||||
|
|
||||||
- name: Package
|
|
||||||
shell: pwsh
|
|
||||||
run: |
|
|
||||||
$ver = "${{ github.ref_name }}".TrimStart("v")
|
|
||||||
$target = "x86_64-pc-windows-msvc"
|
|
||||||
New-Item -ItemType Directory -Force -Path dist | Out-Null
|
|
||||||
$exe = "marqdo-$ver-$target.exe"
|
|
||||||
$zip = "marqdo-$ver-$target.zip"
|
|
||||||
$stdlib = "marqdo-$ver-stdlib.zip"
|
|
||||||
Copy-Item target/release/marqdo.exe "dist/$exe"
|
|
||||||
$stage = "dist/stage-bundle"
|
|
||||||
if (Test-Path $stage) { Remove-Item $stage -Recurse -Force }
|
|
||||||
New-Item -ItemType Directory -Force -Path $stage | Out-Null
|
|
||||||
Copy-Item target/release/marqdo.exe "$stage/marqdo.exe"
|
|
||||||
Copy-Item lib "$stage/lib" -Recurse
|
|
||||||
if (Test-Path "dist/$zip") { Remove-Item "dist/$zip" -Force }
|
|
||||||
Compress-Archive -Path "$stage/*" -DestinationPath "dist/$zip" -Force
|
|
||||||
$stageLib = "dist/stage-stdlib"
|
|
||||||
if (Test-Path $stageLib) { Remove-Item $stageLib -Recurse -Force }
|
|
||||||
New-Item -ItemType Directory -Force -Path $stageLib | Out-Null
|
|
||||||
Copy-Item lib "$stageLib/lib" -Recurse
|
|
||||||
if (Test-Path "dist/$stdlib") { Remove-Item "dist/$stdlib" -Force }
|
|
||||||
Compress-Archive -Path "$stageLib/*" -DestinationPath "dist/$stdlib" -Force
|
|
||||||
echo "EXE=$exe" >> $env:GITHUB_ENV
|
|
||||||
echo "ZIP=$zip" >> $env:GITHUB_ENV
|
|
||||||
echo "STDLIB=$stdlib" >> $env:GITHUB_ENV
|
|
||||||
|
|
||||||
- name: Upload release assets
|
|
||||||
uses: softprops/action-gh-release@v2
|
|
||||||
with:
|
|
||||||
body: |
|
|
||||||
## Downloads
|
|
||||||
|
|
||||||
| Asset | Contents |
|
|
||||||
|-------|----------|
|
|
||||||
| `marqdo-*-windows-msvc.exe` | **Executable only** — does **not** include the standard library |
|
|
||||||
| `marqdo-*-windows-msvc.zip` | **Recommended**: `marqdo.exe` + `lib/` (keep them together) |
|
|
||||||
| `marqdo-*-stdlib.zip` | Standard library only — unpack next to the exe, or set `MARQDO_LIB` |
|
|
||||||
|
|
||||||
> The standalone `.exe` does **not** ship `lib/`. Use the bundle zip or stdlib zip for `lib/…` imports.
|
|
||||||
files: |
|
|
||||||
dist/${{ env.EXE }}
|
|
||||||
dist/${{ env.ZIP }}
|
|
||||||
dist/${{ env.STDLIB }}
|
|
||||||
fail_on_unmatched_files: true
|
|
||||||
env:
|
|
||||||
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
|
|
||||||
+1
-21
@@ -1,21 +1 @@
|
|||||||
/target/
|
/target
|
||||||
/dist/
|
|
||||||
**/*.rs.bk
|
|
||||||
.idea/
|
|
||||||
# Editor settings at repo root only (keep vscode-extension/.vscode for F5)
|
|
||||||
/.vscode/
|
|
||||||
*.pdb
|
|
||||||
.DS_Store
|
|
||||||
.marqdo/
|
|
||||||
|
|
||||||
# Generated HTML beside tracked public/*.mq.md (sources stay in git)
|
|
||||||
/public/index.html
|
|
||||||
/public/pages/
|
|
||||||
|
|
||||||
|
|
||||||
# Python spike venv (local)
|
|
||||||
spike/.venv/
|
|
||||||
spike/__pycache__/
|
|
||||||
spike/.pytest_cache/
|
|
||||||
**/__pycache__/
|
|
||||||
*.pyc
|
|
||||||
Generated
+1
-765
@@ -1,771 +1,7 @@
|
|||||||
# This file is automatically @generated by Cargo.
|
# This file is automatically @generated by Cargo.
|
||||||
# It is not intended for manual editing.
|
# It is not intended for manual editing.
|
||||||
version = 3
|
version = 4
|
||||||
|
|
||||||
[[package]]
|
|
||||||
name = "aho-corasick"
|
|
||||||
version = "1.1.5"
|
|
||||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
|
||||||
checksum = "c982642fa9e8606056828ee9a8505737230110bb1099153c79efe865c59d12ba"
|
|
||||||
dependencies = [
|
|
||||||
"memchr",
|
|
||||||
]
|
|
||||||
|
|
||||||
[[package]]
|
|
||||||
name = "android_system_properties"
|
|
||||||
version = "0.1.5"
|
|
||||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
|
||||||
checksum = "819e7219dbd41043ac279b19830f2efc897156490d7fd6ea916720117ee66311"
|
|
||||||
dependencies = [
|
|
||||||
"libc",
|
|
||||||
]
|
|
||||||
|
|
||||||
[[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 = "bitflags"
|
|
||||||
version = "2.13.1"
|
|
||||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
|
||||||
checksum = "b588b76d00fde79687d7646a9b5bdf3cc0f655e0bbd080335a95d7e96f3587da"
|
|
||||||
|
|
||||||
[[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 = "bumpalo"
|
|
||||||
version = "3.20.3"
|
|
||||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
|
||||||
checksum = "72f5acc6cb2ba439de613abc23857ec3d78374d8ed5ac84e9d11336e87da8649"
|
|
||||||
|
|
||||||
[[package]]
|
|
||||||
name = "cc"
|
|
||||||
version = "1.4.0"
|
|
||||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
|
||||||
checksum = "5add81bb678e6cb321aff7fa0dc7689ad82b112dbc032cea19f91d6b8e3582b9"
|
|
||||||
dependencies = [
|
|
||||||
"find-msvc-tools",
|
|
||||||
"shlex",
|
|
||||||
]
|
|
||||||
|
|
||||||
[[package]]
|
|
||||||
name = "cfg-if"
|
|
||||||
version = "1.0.4"
|
|
||||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
|
||||||
checksum = "9330f8b2ff13f34540b44e946ef35111825727b38d33286ef986142615121801"
|
|
||||||
|
|
||||||
[[package]]
|
|
||||||
name = "chrono"
|
|
||||||
version = "0.4.45"
|
|
||||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
|
||||||
checksum = "1aa79e62e7697b8e29b513a68abacf485adcd1fe8284a4316c5ae868e6633327"
|
|
||||||
dependencies = [
|
|
||||||
"iana-time-zone",
|
|
||||||
"num-traits",
|
|
||||||
"windows-link",
|
|
||||||
]
|
|
||||||
|
|
||||||
[[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 = "core-foundation-sys"
|
|
||||||
version = "0.8.7"
|
|
||||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
|
||||||
checksum = "773648b94d0e5d620f64f280777445740e61fe701025087ec8b57f45c791888b"
|
|
||||||
|
|
||||||
[[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 = "find-msvc-tools"
|
|
||||||
version = "0.1.9"
|
|
||||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
|
||||||
checksum = "5baebc0774151f905a1a2cc41989300b1e6fbb29aff0ceffa1064fdd3088d582"
|
|
||||||
|
|
||||||
[[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 = "futures-core"
|
|
||||||
version = "0.3.33"
|
|
||||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
|
||||||
checksum = "2cd50c473c80f6d7c3670a752354b8e569b1a7cbfdc0419ec88e5edad85e0dc7"
|
|
||||||
|
|
||||||
[[package]]
|
|
||||||
name = "futures-task"
|
|
||||||
version = "0.3.33"
|
|
||||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
|
||||||
checksum = "b231ed28831efb4a61a08580c4bc233ec56bc009f4cd8f52da2c3cb97df0c109"
|
|
||||||
|
|
||||||
[[package]]
|
|
||||||
name = "futures-util"
|
|
||||||
version = "0.3.33"
|
|
||||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
|
||||||
checksum = "a77a90a256fce34da66415271e30f94ee91c57b04b8a2c042d9cf3220179deaa"
|
|
||||||
dependencies = [
|
|
||||||
"futures-core",
|
|
||||||
"futures-task",
|
|
||||||
"pin-project-lite",
|
|
||||||
"slab",
|
|
||||||
]
|
|
||||||
|
|
||||||
[[package]]
|
|
||||||
name = "getopts"
|
|
||||||
version = "0.2.24"
|
|
||||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
|
||||||
checksum = "cfe4fbac503b8d1f88e6676011885f34b7174f46e59956bba534ba83abded4df"
|
|
||||||
dependencies = [
|
|
||||||
"unicode-width",
|
|
||||||
]
|
|
||||||
|
|
||||||
[[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 = "iana-time-zone"
|
|
||||||
version = "0.1.65"
|
|
||||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
|
||||||
checksum = "e31bc9ad994ba00e440a8aa5c9ef0ec67d5cb5e5cb0cc7f8b744a35b389cc470"
|
|
||||||
dependencies = [
|
|
||||||
"android_system_properties",
|
|
||||||
"core-foundation-sys",
|
|
||||||
"iana-time-zone-haiku",
|
|
||||||
"js-sys",
|
|
||||||
"log",
|
|
||||||
"wasm-bindgen",
|
|
||||||
"windows-core",
|
|
||||||
]
|
|
||||||
|
|
||||||
[[package]]
|
|
||||||
name = "iana-time-zone-haiku"
|
|
||||||
version = "0.1.2"
|
|
||||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
|
||||||
checksum = "f31827a206f56af32e590ba56d5d2d085f558508192593743f16b2306495269f"
|
|
||||||
dependencies = [
|
|
||||||
"cc",
|
|
||||||
]
|
|
||||||
|
|
||||||
[[package]]
|
|
||||||
name = "is_terminal_polyfill"
|
|
||||||
version = "1.70.2"
|
|
||||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
|
||||||
checksum = "a6cb138bb79a146c1bd460005623e142ef0181e3d0219cb493e02f7d08a35695"
|
|
||||||
|
|
||||||
[[package]]
|
|
||||||
name = "itoa"
|
|
||||||
version = "1.0.18"
|
|
||||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
|
||||||
checksum = "8f42a60cbdf9a97f5d2305f08a87dc4e09308d1276d28c869c684d7777685682"
|
|
||||||
|
|
||||||
[[package]]
|
|
||||||
name = "js-sys"
|
|
||||||
version = "0.3.103"
|
|
||||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
|
||||||
checksum = "53b44bfcdb3f8d5837a46dae1ca9660a837176eee74a28b229bc626816589102"
|
|
||||||
dependencies = [
|
|
||||||
"cfg-if",
|
|
||||||
"futures-util",
|
|
||||||
"wasm-bindgen",
|
|
||||||
]
|
|
||||||
|
|
||||||
[[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"
|
|
||||||
|
|
||||||
[[package]]
|
[[package]]
|
||||||
name = "marqdo"
|
name = "marqdo"
|
||||||
version = "0.1.0"
|
version = "0.1.0"
|
||||||
dependencies = [
|
|
||||||
"anyhow",
|
|
||||||
"assert_cmd",
|
|
||||||
"chrono",
|
|
||||||
"clap",
|
|
||||||
"predicates",
|
|
||||||
"pulldown-cmark",
|
|
||||||
"serde_json",
|
|
||||||
"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"
|
|
||||||
version = "1.21.4"
|
|
||||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
|
||||||
checksum = "9f7c3e4beb33f85d45ae3e3a1792185706c8e16d043238c593331cc7cd313b50"
|
|
||||||
|
|
||||||
[[package]]
|
|
||||||
name = "once_cell_polyfill"
|
|
||||||
version = "1.70.2"
|
|
||||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
|
||||||
checksum = "384b8ab6d37215f3c5301a95a4accb5d64aa607f1fcb26a11b5303878451b4fe"
|
|
||||||
|
|
||||||
[[package]]
|
|
||||||
name = "pin-project-lite"
|
|
||||||
version = "0.2.17"
|
|
||||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
|
||||||
checksum = "a89322df9ebe1c1578d689c92318e070967d1042b512afbe49518723f4e6d5cd"
|
|
||||||
|
|
||||||
[[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 = "pulldown-cmark"
|
|
||||||
version = "0.12.2"
|
|
||||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
|
||||||
checksum = "f86ba2052aebccc42cbbb3ed234b8b13ce76f75c3551a303cb2bcffcff12bb14"
|
|
||||||
dependencies = [
|
|
||||||
"bitflags",
|
|
||||||
"getopts",
|
|
||||||
"memchr",
|
|
||||||
"pulldown-cmark-escape",
|
|
||||||
"unicase",
|
|
||||||
]
|
|
||||||
|
|
||||||
[[package]]
|
|
||||||
name = "pulldown-cmark-escape"
|
|
||||||
version = "0.11.0"
|
|
||||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
|
||||||
checksum = "007d8adb5ddab6f8e3f491ac63566a7d5002cc7ed73901f72057943fa71ae1ae"
|
|
||||||
|
|
||||||
[[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 = "rustversion"
|
|
||||||
version = "1.0.23"
|
|
||||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
|
||||||
checksum = "cf54715a573b99ac80df0bc206da022bcd442c974952c7b9720069370852e21f"
|
|
||||||
|
|
||||||
[[package]]
|
|
||||||
name = "serde"
|
|
||||||
version = "1.0.229"
|
|
||||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
|
||||||
checksum = "4148590afebada386688f18773da617792bf2ef03ffc1e4cbd2b1d45b023e0ba"
|
|
||||||
dependencies = [
|
|
||||||
"serde_core",
|
|
||||||
]
|
|
||||||
|
|
||||||
[[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 = "serde_json"
|
|
||||||
version = "1.0.151"
|
|
||||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
|
||||||
checksum = "c841b55ecdae098c80dcae9cf767f6f8a0c2cdb3416bbef72181df4d0fe73f14"
|
|
||||||
dependencies = [
|
|
||||||
"itoa",
|
|
||||||
"memchr",
|
|
||||||
"serde",
|
|
||||||
"serde_core",
|
|
||||||
"zmij",
|
|
||||||
]
|
|
||||||
|
|
||||||
[[package]]
|
|
||||||
name = "shlex"
|
|
||||||
version = "2.0.1"
|
|
||||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
|
||||||
checksum = "f8fadd59c855ef2080decdef8ff161eb6661b86933c9d82e5ba29dc602a55aba"
|
|
||||||
|
|
||||||
[[package]]
|
|
||||||
name = "slab"
|
|
||||||
version = "0.4.12"
|
|
||||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
|
||||||
checksum = "0c790de23124f9ab44544d7ac05d60440adc586479ce501c1d6d7da3cd8c9cf5"
|
|
||||||
|
|
||||||
[[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 = "unicase"
|
|
||||||
version = "2.9.0"
|
|
||||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
|
||||||
checksum = "dbc4bc3a9f746d862c45cb89d705aa10f187bb96c76001afab07a0d35ce60142"
|
|
||||||
|
|
||||||
[[package]]
|
|
||||||
name = "unicode-ident"
|
|
||||||
version = "1.0.24"
|
|
||||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
|
||||||
checksum = "e6e4313cd5fcd3dad5cafa179702e2b244f760991f45397d14d4ebf38247da75"
|
|
||||||
|
|
||||||
[[package]]
|
|
||||||
name = "unicode-width"
|
|
||||||
version = "0.2.2"
|
|
||||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
|
||||||
checksum = "b4ac048d71ede7ee76d585517add45da530660ef4390e49b098733c6e897f254"
|
|
||||||
|
|
||||||
[[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 = "wasm-bindgen"
|
|
||||||
version = "0.2.126"
|
|
||||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
|
||||||
checksum = "4b067c0c11094aef6b7a801c1e34a26affafdf3d051dba08456b868789aaf9a4"
|
|
||||||
dependencies = [
|
|
||||||
"cfg-if",
|
|
||||||
"once_cell",
|
|
||||||
"rustversion",
|
|
||||||
"wasm-bindgen-macro",
|
|
||||||
"wasm-bindgen-shared",
|
|
||||||
]
|
|
||||||
|
|
||||||
[[package]]
|
|
||||||
name = "wasm-bindgen-macro"
|
|
||||||
version = "0.2.126"
|
|
||||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
|
||||||
checksum = "167ce5e579f6bcf889c4f7175a8a5a585de84e8ff93976ce393efa5f2837aab1"
|
|
||||||
dependencies = [
|
|
||||||
"quote",
|
|
||||||
"wasm-bindgen-macro-support",
|
|
||||||
]
|
|
||||||
|
|
||||||
[[package]]
|
|
||||||
name = "wasm-bindgen-macro-support"
|
|
||||||
version = "0.2.126"
|
|
||||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
|
||||||
checksum = "f3997c7839262f4ef12cf90b818d6340c18e80f263f1a94bf157d0ec4420380e"
|
|
||||||
dependencies = [
|
|
||||||
"bumpalo",
|
|
||||||
"proc-macro2",
|
|
||||||
"quote",
|
|
||||||
"syn 2.0.119",
|
|
||||||
"wasm-bindgen-shared",
|
|
||||||
]
|
|
||||||
|
|
||||||
[[package]]
|
|
||||||
name = "wasm-bindgen-shared"
|
|
||||||
version = "0.2.126"
|
|
||||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
|
||||||
checksum = "dc1b4cb0cc549fcf58d7dfc081778139b3d283a081644e833e84682ad71cea24"
|
|
||||||
dependencies = [
|
|
||||||
"unicode-ident",
|
|
||||||
]
|
|
||||||
|
|
||||||
[[package]]
|
|
||||||
name = "windows-core"
|
|
||||||
version = "0.62.2"
|
|
||||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
|
||||||
checksum = "b8e83a14d34d0623b51dce9581199302a221863196a1dde71a7663a4c2be9deb"
|
|
||||||
dependencies = [
|
|
||||||
"windows-implement",
|
|
||||||
"windows-interface",
|
|
||||||
"windows-link",
|
|
||||||
"windows-result",
|
|
||||||
"windows-strings",
|
|
||||||
]
|
|
||||||
|
|
||||||
[[package]]
|
|
||||||
name = "windows-implement"
|
|
||||||
version = "0.60.2"
|
|
||||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
|
||||||
checksum = "053e2e040ab57b9dc951b72c264860db7eb3b0200ba345b4e4c3b14f67855ddf"
|
|
||||||
dependencies = [
|
|
||||||
"proc-macro2",
|
|
||||||
"quote",
|
|
||||||
"syn 2.0.119",
|
|
||||||
]
|
|
||||||
|
|
||||||
[[package]]
|
|
||||||
name = "windows-interface"
|
|
||||||
version = "0.59.3"
|
|
||||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
|
||||||
checksum = "3f316c4a2570ba26bbec722032c4099d8c8bc095efccdc15688708623367e358"
|
|
||||||
dependencies = [
|
|
||||||
"proc-macro2",
|
|
||||||
"quote",
|
|
||||||
"syn 2.0.119",
|
|
||||||
]
|
|
||||||
|
|
||||||
[[package]]
|
|
||||||
name = "windows-link"
|
|
||||||
version = "0.2.1"
|
|
||||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
|
||||||
checksum = "f0805222e57f7521d6a62e36fa9163bc891acd422f971defe97d64e70d0a4fe5"
|
|
||||||
|
|
||||||
[[package]]
|
|
||||||
name = "windows-result"
|
|
||||||
version = "0.4.1"
|
|
||||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
|
||||||
checksum = "7781fa89eaf60850ac3d2da7af8e5242a5ea78d1a11c49bf2910bb5a73853eb5"
|
|
||||||
dependencies = [
|
|
||||||
"windows-link",
|
|
||||||
]
|
|
||||||
|
|
||||||
[[package]]
|
|
||||||
name = "windows-strings"
|
|
||||||
version = "0.5.1"
|
|
||||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
|
||||||
checksum = "7837d08f69c77cf6b07689544538e017c1bfcf57e34b4c0ff58e6c2cd3b37091"
|
|
||||||
dependencies = [
|
|
||||||
"windows-link",
|
|
||||||
]
|
|
||||||
|
|
||||||
[[package]]
|
|
||||||
name = "windows-sys"
|
|
||||||
version = "0.61.2"
|
|
||||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
|
||||||
checksum = "ae137229bcbd6cdf0f7b80a31df61766145077ddf49416a728b02cb3921ff3fc"
|
|
||||||
dependencies = [
|
|
||||||
"windows-link",
|
|
||||||
]
|
|
||||||
|
|
||||||
[[package]]
|
|
||||||
name = "zmij"
|
|
||||||
version = "1.0.23"
|
|
||||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
|
||||||
checksum = "29666d0abbfad1e3dc4dcf6144730dd3a3ab225bbbdac83319345b1b44ccfc1b"
|
|
||||||
+4
-19
@@ -1,25 +1,10 @@
|
|||||||
[package]
|
[package]
|
||||||
name = "marqdo"
|
name = "marqdo"
|
||||||
version = "0.1.0"
|
version = "0.1.0"
|
||||||
edition = "2021"
|
edition = "2024"
|
||||||
license = "Apache-2.0"
|
|
||||||
description = "Marqdo — Markdown markers as an interpreted programming language"
|
[dependencies]
|
||||||
readme = "README.md"
|
|
||||||
repository = "https://github.com/cflmy/marqdo"
|
|
||||||
|
|
||||||
[[bin]]
|
[[bin]]
|
||||||
name = "marqdo"
|
name = "marqdo"
|
||||||
path = "src/main.rs"
|
path = "src/marqdo.rs"
|
||||||
|
|
||||||
[dependencies]
|
|
||||||
anyhow = "1"
|
|
||||||
chrono = { version = "0.4", default-features = false, features = ["clock", "std"] }
|
|
||||||
clap = { version = "=4.4.18", features = ["derive"] }
|
|
||||||
pulldown-cmark = "0.12"
|
|
||||||
serde_json = "1"
|
|
||||||
thiserror = "1"
|
|
||||||
tiny_http = "0.12"
|
|
||||||
|
|
||||||
[dev-dependencies]
|
|
||||||
assert_cmd = "=2.0.14"
|
|
||||||
predicates = "=3.1.0"
|
|
||||||
@@ -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.
|
|
||||||
@@ -1,130 +0,0 @@
|
|||||||
# Marqdo
|
|
||||||
|
|
||||||
**代码即文档。文档即代码。文档即知识库。**
|
|
||||||
|
|
||||||
Marqdo 把 Markdown **标记当作编程语法**:同一个 `.mq.md` 文件,既是给人读的文稿,也是给机器跑的程序。写文档的过程就是在写可执行逻辑——大型项目里,说明、示例与实现不再分叉成三份真相。
|
|
||||||
|
|
||||||
欢迎访问 [marqdo 官方网站](https://www.marqdo.com/) 阅读更多特性与可执行文档。
|
|
||||||
|
|
||||||
语法宪法:[doc/design/markdown-mapping.md](doc/design/markdown-mapping.md) · 调用实参:[call-arguments.md](doc/design/call-arguments.md) · 用户站:[user-site.md](doc/design/user-site.md) · 浏览:[view.md](doc/design/view.md) · 调试:[view-debug.md](doc/design/view-debug.md) · OKF 清单:[catalog-cli.md](doc/design/catalog-cli.md) · VS Code 扩展:[vscode-extension.md](doc/design/vscode-extension.md)(分支 `vscode-extension`) · 金样例:[tests/](tests/) · 用户文档:[public/](public/)
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 为什么重要
|
|
||||||
|
|
||||||
| 痛点 | Marqdo 的答案 |
|
|
||||||
|------|----------------|
|
|
||||||
| 文档过期、示例跑不通 | **一份源文件**:叙述、结构与执行结果同源 |
|
|
||||||
| 知识散落在 Wiki / 注释 / 脚本里 | **`.mq.md` 即知识单元**,可浏览、可运行、可检索 |
|
|
||||||
| 人写给人看,AI / 工具另起一套 | **人机同读同写同构**:标记语言对人类友好,对解释器确定 |
|
|
||||||
| 大仓里「文档站」与「代码仓」脱节 | `view` 文档站 + `debug` 调试面 + `catalog` 清单,同一棵树长大 |
|
|
||||||
|
|
||||||
这不是「再做一个 Markdown 渲染器」,而是:**把文档升格为可解释的程序与可生长的知识库**,让协作在大型项目里依然站得住。
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 语法速览(v0.1)
|
|
||||||
|
|
||||||
| 标记 | 含义 |
|
|
||||||
|------|------|
|
|
||||||
| 无标记行 | 注释(空行分段) |
|
|
||||||
| `*…*` | 程序语句 |
|
|
||||||
| `**…**` | **返回值**(架构) |
|
|
||||||
| `****` / `**` + 空白 + `**` | **空返回**(`None`),并结束本函数体 |
|
|
||||||
| `> print …` 等 | 输出等副作用 = **普通函数**,非架构标记 |
|
|
||||||
| `#` / `##` | 函数与作用域 |
|
|
||||||
| `+` / `1.` | 分支(臂头单独 `*` = else) |
|
|
||||||
| `-` | 循环(头下纯名则为形参) |
|
|
||||||
| 表格 | 集合 |
|
|
||||||
| 函数体内单独一行 `---` / `***` | **结束本函数体**(无返回值收束;见 mapping §11) |
|
|
||||||
| 文件开头成对 `---` … `---` | Frontmatter(元信息 / 导入),与函数结束符消歧 |
|
|
||||||
|
|
||||||
```markdown
|
|
||||||
# main
|
|
||||||
|
|
||||||
> 问候 谁=World
|
|
||||||
|
|
||||||
## 问候
|
|
||||||
- 谁
|
|
||||||
|
|
||||||
> print text=Hello `谁`!
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 加一
|
|
||||||
- n
|
|
||||||
|
|
||||||
**`n` + 1**
|
|
||||||
```
|
|
||||||
|
|
||||||
完整约定:[markdown-mapping.md](doc/design/markdown-mapping.md)。
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 理念
|
|
||||||
|
|
||||||
1. **叙述默认安全**(无标记 = 注释)。
|
|
||||||
2. **返回是架构;打印只是函数。**
|
|
||||||
3. **代码即文档即知识库**:文稿可执行,执行可回看结构,结构可导航与调试。
|
|
||||||
4. **对齐 [OKF](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md)(Open Knowledge Format)方向**:清单由工具从 `.mq.md` **自动生成**,不是手填配置——见下节与 [catalog-cli.md](doc/design/catalog-cli.md)。
|
|
||||||
5. **正经解释器(Rust)**:词法/行分类 → 语法 → 语义 → 树遍历(及字节码);**不用 Flex/Bison**。见 [路线图](doc/roadmap/interpreter.md)。
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## OKF 风格清单(自动生成)
|
|
||||||
|
|
||||||
从源码派生 YAML / Markdown 知识包(勿手改生成物):
|
|
||||||
|
|
||||||
```bash
|
|
||||||
marqdo catalog [PATH] -o OUT_DIR
|
|
||||||
marqdo sync [PATH] -o OUT_DIR # catalog 的别名
|
|
||||||
```
|
|
||||||
|
|
||||||
| 参数 | 默认 | 说明 |
|
|
||||||
|------|------|------|
|
|
||||||
| `PATH` | `.` | 工程根或含 `.mq.md` 的目录 |
|
|
||||||
| `-o` / `--out` | `.marqdo` | 输出目录 |
|
|
||||||
|
|
||||||
产物示例:`catalog.yaml`、`index.md`、`modules/*.md`(`type: Marqdo Module` 等)。设计见 [generated-yaml-manifest.md](doc/design/generated-yaml-manifest.md) · 调研 [okf-and-marqdo.md](doc/research/okf-and-marqdo.md)。
|
|
||||||
|
|
||||||
```bash
|
|
||||||
cargo run -- catalog public -o .marqdo
|
|
||||||
# 或已安装二进制时:
|
|
||||||
marqdo catalog public -o .marqdo
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 现状(v0.1.0)
|
|
||||||
|
|
||||||
- 映射与解释器:Phase I 树遍历 + 字节码后端可用;金样例在 `tests/`
|
|
||||||
- **`marqdo view`**:文档浏览器(Structure + 函数大纲/搜索 + Execution + Source)
|
|
||||||
- **`marqdo debug`**:独立调试页(断点 / 单步 / locals;默认端口 7430)
|
|
||||||
- **`marqdo catalog` / `sync`**:OKF 风格 YAML + 模块概念页
|
|
||||||
- 标准库:文本、文件、系统、时间、JSON、网络、数学(公式/绘图)、外联(Python 等)
|
|
||||||
- **用户静态站**:`public/` → `view output` → CI 发布 [gh-pages](https://cflmy.github.io/marqdo/)
|
|
||||||
- 选型:[ADR 0001 — Rust](doc/adr/0001-implementation-language.md)
|
|
||||||
|
|
||||||
```bash
|
|
||||||
cargo run -- run tests/structure/hello.mq.md
|
|
||||||
cargo run -- run tests/structure/hello.mq.md --backend bytecode
|
|
||||||
cargo run -- view public --no-open
|
|
||||||
cargo run -- debug public --no-open
|
|
||||||
cargo run -- catalog public -o .marqdo
|
|
||||||
cargo run -- view output public -o public
|
|
||||||
powershell -File ./scripts/build-public.ps1
|
|
||||||
```
|
|
||||||
|
|
||||||
**发布包(GitHub Releases)**:单独 `.exe` **不含** `lib/`;请下载带 `lib/` 的 zip,或另下 `*-stdlib.zip` 解压到可执行文件旁(亦可设 `MARQDO_LIB`)。
|
|
||||||
|
|
||||||
文档:用户站 [public/](public/) · 设计 [doc/](doc/) · OKF / catalog [catalog-cli.md](doc/design/catalog-cli.md) · 调试 [view-debug.md](doc/design/view-debug.md)
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 命名
|
|
||||||
|
|
||||||
**Marqdo** = Marq(Markdown)+ do(执行)
|
|
||||||
|
|
||||||
## 许可
|
|
||||||
|
|
||||||
[Apache License 2.0](LICENSE)
|
|
||||||
@@ -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;
|
||||||
@@ -1,52 +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) | **英文最小关键字 / 内置函数** |
|
|
||||||
| [design/keywords-i18n.md](design/keywords-i18n.md) | **内核中英双名(无需导入;少而精)** |
|
|
||||||
| [design/stdlib.md](design/stdlib.md) | **P2 标准库:内置 + `lib/` + 错误约定** |
|
|
||||||
| [design/stdlib-i18n.md](design/stdlib-i18n.md) | **标准库中英命名:靠库文件名区分,无 lang 开关** |
|
|
||||||
| [design/stdlib-modules.md](design/stdlib-modules.md) | **本波 L1:文件/系统/时间/JSON/网络(JSON 中英同库)** |
|
|
||||||
| [design/stdlib-math.md](design/stdlib-math.md) | **方案:数学库(数值/随机/作图/轻量求解)** |
|
|
||||||
| [design/stdlib-foreign.md](design/stdlib-foreign.md) | **暂缓:外联胶水(\`\`\`lang 具名块)** |
|
|
||||||
| [design/call-arguments.md](design/call-arguments.md) | **调用:具名 + 位置实参** |
|
|
||||||
| [design/examples-and-tests.md](design/examples-and-tests.md) | **tests/ 金样例目录布局** |
|
|
||||||
| [design/view.md](design/view.md) | **`marqdo view` / `view output` 黑白极简 + 静态文档** |
|
|
||||||
| [design/user-site.md](design/user-site.md) | **用户站:`public/` → `gh-pages`** |
|
|
||||||
| [design/catalog-cli.md](design/catalog-cli.md) | **`marqdo catalog` / `sync` OKF 清单命令** |
|
|
||||||
| [design/view-debug.md](design/view-debug.md) | **`marqdo debug` 独立调试页** |
|
|
||||||
| [design/vscode-extension.md](design/vscode-extension.md) | **VS Code 扩展:分支 `vscode-extension`(main 不跟踪源码)** |
|
|
||||||
| [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) | 正经解释器路线图 |
|
|
||||||
| [roadmap/next-phase.md](roadmap/next-phase.md) | **下一阶段:input / 诊断 / 标准库 / view 调试** |
|
|
||||||
| [research/okf-and-marqdo.md](research/okf-and-marqdo.md) | OKF 调研 |
|
|
||||||
|
|
||||||
金样例与集成测试:[`tests/`](../tests/)。面向访客的可执行文档:[`public/`](../public/)。Spike 存档:[`spike/`](../spike/)。
|
|
||||||
|
|
||||||
## 写作原则
|
|
||||||
|
|
||||||
1. 先宪法与路线图,再实现。
|
|
||||||
2. 金样例不过 = 未完成。
|
|
||||||
3. 示例统一 `.mq.md`。
|
|
||||||
@@ -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 依赖。
|
|
||||||
- 金样例仍为 `tests/`;行为与宪法一致。
|
|
||||||
- 此前「Python 作参考实现」的倾向由本修订取代;Spike 结论(行扫描等)仍然有效并迁入 Rust。
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 否决
|
|
||||||
|
|
||||||
| 方案 | 原因 |
|
|
||||||
|------|------|
|
|
||||||
| Flex + Bison 作主前端 | 与 Markup-as-Syntax / Rust 栈错配;解释器非必需 |
|
|
||||||
| v1 上 LLVM | 产品是解释执行文档,不是机器后端 |
|
|
||||||
| 仅 Python 正则玩具 | 达不到安全与长期目标 |
|
|
||||||
@@ -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 后编译) |
|
|
||||||
| `tests/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。
|
|
||||||
@@ -1,53 +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` ≡ `内容`。
|
|
||||||
- `input` / `输入`:`prompt` ≡ `提示`。
|
|
||||||
- `len` / `长度`、`str` / `文本`、`int` / `整数`:`value` ≡ `值`。
|
|
||||||
- 完整中英双名见 [keywords-i18n.md](keywords-i18n.md)。
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 3. 绑定算法
|
|
||||||
|
|
||||||
1. 收集具名 → 映射;冲突则报错。
|
|
||||||
2. 按函数形参表顺序:若具名已提供则用之,否则取下一个位置实参。
|
|
||||||
3. 位置实参有余、或必填形参仍缺 → 报错(内置 `input` 的 `prompt` 可缺省)。
|
|
||||||
4. 用户函数:额外具名键仍写入调用环境(便于扩展);位置实参不可超过形参数目。
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 4. 金样例
|
|
||||||
|
|
||||||
见 `tests/structure/positional-call.mq.md` 与更新后的 `tests/structure/import/`。
|
|
||||||
@@ -1,128 +0,0 @@
|
|||||||
# OKF 兼容清单:`marqdo catalog`
|
|
||||||
|
|
||||||
| | |
|
|
||||||
|---|---|
|
|
||||||
| 状态 | 已定(v0 命令落地) |
|
|
||||||
| 日期 | 2026-08-04 |
|
|
||||||
| 取代 | [generated-yaml-manifest.md](generated-yaml-manifest.md) 中「待决:sync/doc 命令」的命令名部分 |
|
|
||||||
| 相关 | [generated-yaml-manifest.md](generated-yaml-manifest.md) · [view.md](view.md) · [okf-and-marqdo.md](../research/okf-and-marqdo.md) |
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 1. 决策(重申)
|
|
||||||
|
|
||||||
YAML / OKF 风格清单是**从 `.mq.md` 派生的生成物**,不是手写配置。详见 [generated-yaml-manifest.md](generated-yaml-manifest.md)。
|
|
||||||
|
|
||||||
本文件规定 **CLI 与 v0 落盘格式**。
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 2. CLI
|
|
||||||
|
|
||||||
```bash
|
|
||||||
marqdo catalog [PATH] -o OUT_DIR
|
|
||||||
# 别名(与早期草案一致)
|
|
||||||
marqdo sync [PATH] -o OUT_DIR
|
|
||||||
```
|
|
||||||
|
|
||||||
| 参数 | 默认 | 说明 |
|
|
||||||
|------|------|------|
|
|
||||||
| `PATH` | `.` | 工程根或含 `.mq.md` 的目录(递归扫描) |
|
|
||||||
| `-o` / `--out` | `.marqdo` | 生成目录(写入前创建;**覆盖**同名生成文件) |
|
|
||||||
|
|
||||||
退出码:成功 0;无可扫描文件或 IO/解析失败非 0(单文件解析失败时写入 `diagnostics` 并继续其余文件,最终若有失败则非 0)。
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 3. 生成物(v0)
|
|
||||||
|
|
||||||
```
|
|
||||||
OUT_DIR/
|
|
||||||
catalog.yaml # 机器向总清单(OKF 风格字段)
|
|
||||||
index.md # 人/Agent 可读总览(含 YAML frontmatter)
|
|
||||||
modules/
|
|
||||||
<stem>.md # 每个 .mq.md 一个概念页(frontmatter + 摘要)
|
|
||||||
```
|
|
||||||
|
|
||||||
路径中的目录层级拍扁为文件名时用 `__` 连接,例如:
|
|
||||||
|
|
||||||
`structure/import/main.mq.md` → `modules/structure__import__main.md`
|
|
||||||
|
|
||||||
### 3.1 `catalog.yaml`(示意)
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
# GENERATED by marqdo — do not edit by hand
|
|
||||||
type: Marqdo Catalog
|
|
||||||
title: marqdo-project
|
|
||||||
generated:
|
|
||||||
by: marqdo/0.0.1
|
|
||||||
# at: 可选 ISO8601;CI 比对时可忽略
|
|
||||||
modules:
|
|
||||||
- id: structure/hello
|
|
||||||
resource: structure/hello.mq.md
|
|
||||||
title: Hello World # 来自源 frontmatter title,缺省用文件名
|
|
||||||
imports: []
|
|
||||||
exports:
|
|
||||||
- name: Hello World
|
|
||||||
kind: fn
|
|
||||||
- id: structure/import/main
|
|
||||||
resource: structure/import/main.mq.md
|
|
||||||
imports:
|
|
||||||
- utils.mq.md
|
|
||||||
exports:
|
|
||||||
- name: main
|
|
||||||
kind: fn
|
|
||||||
```
|
|
||||||
|
|
||||||
字段约定(v0 最小集):
|
|
||||||
|
|
||||||
| 字段 | 含义 |
|
|
||||||
|------|------|
|
|
||||||
| `type` | 固定 `Marqdo Catalog`(OKF:未知 type 可降级) |
|
|
||||||
| `modules[].resource` | 相对 `PATH` 的源路径 |
|
|
||||||
| `modules[].imports` | 源 frontmatter 中的 `> *.mq.md` |
|
|
||||||
| `modules[].exports` | 顶层 `#` 函数名(`kind: fn`);嵌套 `##` 列入 `children`(可选,v0 可扁平只列顶层) |
|
|
||||||
| `generated.by` | `marqdo/<crate version>` |
|
|
||||||
|
|
||||||
不在 v0:版本锁定哈希、跨仓 URL、完整符号类型。
|
|
||||||
|
|
||||||
### 3.2 模块概念页 frontmatter
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
---
|
|
||||||
type: Marqdo Module
|
|
||||||
title: …
|
|
||||||
resource: structure/hello.mq.md
|
|
||||||
depends: [] # imports 列表
|
|
||||||
exports: [Hello World]
|
|
||||||
generated:
|
|
||||||
by: marqdo/0.0.1
|
|
||||||
---
|
|
||||||
```
|
|
||||||
|
|
||||||
正文含「请勿手改」提示、依赖列表、导出列表;可链到同包其它模块页。
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 4. 与 `view output` 的分工
|
|
||||||
|
|
||||||
| 命令 | 产物 | 受众 |
|
|
||||||
|------|------|------|
|
|
||||||
| `marqdo view output` | 静态 HTML(结构 + 运行结果) | 人类读程序文档站 |
|
|
||||||
| `marqdo catalog` | OKF 风格 YAML + Markdown 索引 | 工具 / Agent / 依赖总览 |
|
|
||||||
|
|
||||||
二者都从同一源树生成,互不替代。发布用户文档时可同时:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
marqdo view output public -o public
|
|
||||||
marqdo catalog tests -o .marqdo
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 5. 验收
|
|
||||||
|
|
||||||
1. `marqdo catalog tests -o /tmp/mq-cat` 写出 `catalog.yaml` 与 `modules/`。
|
|
||||||
2. `catalog.yaml` 含 `structure/hello` 与 import 模块的 `imports: [utils.mq.md]`。
|
|
||||||
3. 文件头或 `generated` 标明 GENERATED;文档声明勿手改。
|
|
||||||
4. `marqdo sync` 与 `catalog` 行为一致。
|
|
||||||
@@ -1,37 +0,0 @@
|
|||||||
# 可执行面与叙述面
|
|
||||||
|
|
||||||
| | |
|
|
||||||
|---|---|
|
|
||||||
| 状态 | 与 mapping v0.1 / keywords 对齐(成段注释) |
|
|
||||||
| 日期 | 2026-08-04 |
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 三层
|
|
||||||
|
|
||||||
| 层 | 形态 | 角色 |
|
|
||||||
|----|------|------|
|
|
||||||
| **叙述面** | 成段注释(空行分段) | 注释;段内任意标记无语义 |
|
|
||||||
| **Marqdo 可执行面** | 结构标记 + `*语句*` + `**返回**` | 本语言程序 |
|
|
||||||
| **外联面** | ` ```lang ` | 其它语言(FFI) |
|
|
||||||
|
|
||||||
输出属于可执行面里的**函数调用**(`> print …`),见 [keywords.md](keywords.md)。
|
|
||||||
|
|
||||||
### 成段注释
|
|
||||||
|
|
||||||
- 以**空行**划分段落。
|
|
||||||
- 段首行:首字符非标记 → 注释。
|
|
||||||
- 段内续行:一律注释(即使以 `` ` `` / `-` 等开头)。
|
|
||||||
- 叙述段与可执行代码之间**必须空一行**,否则 `> print` 等会被吞进注释段。
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 语句 vs 返回 vs 输出
|
|
||||||
|
|
||||||
| 标记/形式 | 角色 | 是否架构级 |
|
|
||||||
|-----------|------|------------|
|
|
||||||
| `*…*` | 程序语句 | 是 |
|
|
||||||
| `**…**` | 返回值 | 是 |
|
|
||||||
| `****` / 空粗体 | 空返回 + 结束函数体 | 是 |
|
|
||||||
| `> print …` | 打印副作用 | 否(内置函数) |
|
|
||||||
| 函数体 `---` / `***` | 结束函数体 | 是(边界) |
|
|
||||||
@@ -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** 或手写金文件 | tests 期望 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/ # gold.rs + structure|keywords|errors
|
|
||||||
public/ # 用户可执行文档
|
|
||||||
spike/ # Python 风险探测存档(可保留,非运行时依赖)
|
|
||||||
```
|
|
||||||
|
|
||||||
开发命令示例:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
cargo build
|
|
||||||
cargo test
|
|
||||||
cargo run -- run tests/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。
|
|
||||||
@@ -1,68 +0,0 @@
|
|||||||
# 示例与测试布局
|
|
||||||
|
|
||||||
| | |
|
|
||||||
|---|---|
|
|
||||||
| 状态 | 已定 |
|
|
||||||
| 日期 | 2026-08-04 |
|
|
||||||
| 原则 | **夹具即金样例**:`tests/{structure,keywords,errors}/**/*.mq.md` 由 `cargo test` / CI 跑通;`marqdo view tests` 也可浏览 |
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 1. 目录
|
|
||||||
|
|
||||||
只保留 **`tests/`**,用子目录区分类别(不再另设 `examples/`):
|
|
||||||
|
|
||||||
```
|
|
||||||
tests/
|
|
||||||
README.md
|
|
||||||
gold.rs # 集成测试入口
|
|
||||||
structure/ # 代码基础结构(Markup 架构)
|
|
||||||
hello.mq.md
|
|
||||||
nested-call.mq.md
|
|
||||||
positional-call.mq.md
|
|
||||||
branch.mq.md
|
|
||||||
loop.mq.md
|
|
||||||
collection.mq.md
|
|
||||||
import/
|
|
||||||
main.mq.md
|
|
||||||
utils.mq.md
|
|
||||||
keywords/ # 关键字与内置名
|
|
||||||
print.mq.md
|
|
||||||
bool-logic.mq.md
|
|
||||||
errors/ # 期望失败(诊断文案稳定后再加金样例)
|
|
||||||
…
|
|
||||||
```
|
|
||||||
|
|
||||||
面向访客的可执行介绍在 [`public/`](../../public/)(无 `errors/`),见 [user-site.md](user-site.md)。
|
|
||||||
开发设计文稿在 [`doc/`](../)(单数)。
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 2. 分类职责
|
|
||||||
|
|
||||||
| 类别 | 测什么 | 不测什么 |
|
|
||||||
|------|--------|----------|
|
|
||||||
| **structure** | `#`/`##`、形参、`>` 调用、`*`/`**`、`+`/`-`、表、导入、位置/具名实参 | 关键字边角 |
|
|
||||||
| **keywords** | `True`/`False`/`None`、`and`/`or`/`not`、`print`/`input` 约定 | 复杂控制流(可极简) |
|
|
||||||
| **errors** | 未定义名、实参错误、语法错误的诊断 | 成功路径 |
|
|
||||||
|
|
||||||
未单独建夹、但应覆盖的其它测试(`src/**` 单测或日后 `tests/runtime/`):
|
|
||||||
|
|
||||||
- **流水线调试**:`--dump-lines` / `--dump-ast` / `--trace-eval`
|
|
||||||
- **CLI**:默认 `index.mq.md`、退出码
|
|
||||||
- **view**:目录扫描、单文件页、执行区(见 [view.md](view.md))
|
|
||||||
- **模块图**:循环导入拒绝
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 3. 金样例约定
|
|
||||||
|
|
||||||
每个可执行 `.mq.md` 在 `tests/gold.rs` 登记期望 stdout。
|
|
||||||
`errors/` 内文件登记期望 stderr 子串与非零退出码。
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 4. 与 `view` / `public` 的关系
|
|
||||||
|
|
||||||
- `marqdo view tests`:开发者浏览金样例(含 errors)。
|
|
||||||
- `marqdo view public`:用户文档站源;**不要**把 `tests/errors` 编进 `public/`。
|
|
||||||
@@ -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)
|
|
||||||
|
|
||||||
- [x] 生成物默认路径:`.marqdo/`(`-o` 可改)— 见 [catalog-cli.md](catalog-cli.md)
|
|
||||||
- [x] `marqdo catalog` / `sync`;静态用户文档:`marqdo view output` — 见 [view.md](view.md)
|
|
||||||
- [ ] 是否提交生成物进 git(项目自定;CI 可校验干净生成)
|
|
||||||
- [ ] 与「可手写包身份 name/version」的边界
|
|
||||||
- [ ] 是否沿用 OKF v0.2 的 `sources` 等溯源字段
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 结论
|
|
||||||
|
|
||||||
**YAML(OKF 风格清单)= 机器从 `.mq.md` 自动生成的依赖与项目元数据,并可据此自动生成本项目文档;不是人手填写的配置文件。**
|
|
||||||
人写源,工具写清单与目录文档;编译器与文档站共同消费生成物,语义始终回到源。
|
|
||||||
@@ -1,137 +0,0 @@
|
|||||||
# 内置关键字 / 函数:中英双名(草案)
|
|
||||||
|
|
||||||
| | |
|
|
||||||
|---|---|
|
|
||||||
| 状态 | **已定(已实现)** |
|
|
||||||
| 日期 | 2026-08-05 |
|
|
||||||
| 原则 | **无需导入**;中英为**同一语义的别名**,不是语言模式开关 |
|
|
||||||
| 相关 | [keywords.md](keywords.md) · [stdlib-i18n.md](stdlib-i18n.md) · [call-arguments.md](call-arguments.md) |
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 1. 动机
|
|
||||||
|
|
||||||
Marqdo 要中英文都能自然书写。标准库已约定「**库文件名区分语言**」(见 [stdlib-i18n.md](stdlib-i18n.md));对**不必导入**的一层——字面量关键字与极少内置函数——也要对等提供中文名。
|
|
||||||
|
|
||||||
正因为每增加一个内置名,就要同时维护中英(及日后更多语言)别名,所以:
|
|
||||||
|
|
||||||
> **关键字 / 内置必须少而精**——体积在「名字 × 语言」上放大,而不是在功能清单上堆满。
|
|
||||||
|
|
||||||
更多能力进可导入的 `lib/`,用中英**不同库文件、不同函数名**扩展,不膨胀解释器内核。
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 2. 分层(与标准库对齐)
|
|
||||||
|
|
||||||
| 层 | 是否导入 | 中英怎么区分 |
|
|
||||||
|----|----------|--------------|
|
|
||||||
| **L0 内核** | 否 | **同一文件内双名**:`print` ≡ `打印`;`True` ≡ `真` |
|
|
||||||
| **L1 标准库** | 是(`> lib/…`) | **不同文件**:`text.mq.md` vs `文本.mq.md`(见 i18n 草案) |
|
|
||||||
|
|
||||||
L0 **不做** `lang:`、不做「当前语言模式」;写英文名就用英文,写中文名就用中文,可在同一程序里混用。
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 3. 范围:哪些要双名
|
|
||||||
|
|
||||||
### 3.1 字面量 / 逻辑关键字(词法保留)
|
|
||||||
|
|
||||||
控制流仍靠 Markdown(`#` `+` `-` `*` `**`),**不**为 `if`/`while`/`def` 做中英关键字。
|
|
||||||
|
|
||||||
| 英文 | 中文(提案) | 备注 |
|
|
||||||
|------|--------------|------|
|
|
||||||
| `True` | `真` | 布尔真 |
|
|
||||||
| `False` | `假` | 布尔假 |
|
|
||||||
| `None` | `空` | 空值 |
|
|
||||||
| `and` | `且` | 逻辑与 |
|
|
||||||
| `or` | `或` | 逻辑或 |
|
|
||||||
| `not` | `非` | 逻辑非 |
|
|
||||||
|
|
||||||
中英文名均**不可作变量名**(同一保留集)。
|
|
||||||
|
|
||||||
### 3.2 内置函数(可调用、无需导入)
|
|
||||||
|
|
||||||
**仅**下列核心五项做中英双名(与「少而精」一致):
|
|
||||||
|
|
||||||
| 英文 | 中文(提案) | 作用 |
|
|
||||||
|------|--------------|------|
|
|
||||||
| `print` | `打印` | 写 stdout |
|
|
||||||
| `input` | `输入` | 读一行 |
|
|
||||||
| `len` | `长度` | 文本/表长度 |
|
|
||||||
| `str` | `文本` | 转为显示文本 |
|
|
||||||
| `int` | `整数` | 转为整数 |
|
|
||||||
|
|
||||||
形参名也提供中英别名(便于纯中文调用):
|
|
||||||
|
|
||||||
| 英文形参 | 中文形参 | 用于 |
|
|
||||||
|----------|----------|------|
|
|
||||||
| `text` | `内容` | `print` / `打印` |
|
|
||||||
| `prompt` | `提示` | `input` / `输入` |
|
|
||||||
| `value` | `值` | `len`/`str`/`int` 及对应中文名 |
|
|
||||||
|
|
||||||
示例(等价):
|
|
||||||
|
|
||||||
```markdown
|
|
||||||
> print text=Hello
|
|
||||||
> 打印 内容=你好
|
|
||||||
|
|
||||||
*`n` = > len `s`*
|
|
||||||
*`n` = > 长度 值=`s`*
|
|
||||||
```
|
|
||||||
|
|
||||||
### 3.3 明确不进 L0 双名表
|
|
||||||
|
|
||||||
下列若已在解释器中实现,视为**宿主原语 / 过渡 API**,**不**再批中文内核别名;应迁入或仅通过标准库暴露(中英分文件):
|
|
||||||
|
|
||||||
| 英文名 | 去向 |
|
|
||||||
|--------|------|
|
|
||||||
| `type` | L1 或维持实现细节,不进「关键字最少集」宣传 |
|
|
||||||
| `trim` `split` `join` | L1:`lib/text.mq.md` / `lib/文本.mq.md` |
|
|
||||||
| `at` | L1:`lib/table.mq.md` / `lib/表.mq.md` |
|
|
||||||
|
|
||||||
这样 L0 公开面 ≈ **6 个关键字词 ×2 + 5 个函数 ×2**,而不是「每个工具函数都 ×2」。
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 4. 语义规则
|
|
||||||
|
|
||||||
1. **别名等价**:中英文名绑定同一实现;诊断文案可用英文稳定串(金样例已有),用户文档中英均可举例。
|
|
||||||
2. **可混用**:同一文件可同时出现 `print` 与 `打印`、`True` 与 `真`。
|
|
||||||
3. **遮蔽**:用户 `# 打印` 与 `# print` 均会遮蔽对应内置名(实现阶段应警告)。
|
|
||||||
4. **大小写**:英文关键字保持 Python 风格(`True`/`False`/`None`);中文无名感大小写问题。
|
|
||||||
5. **扩语言**:日后日文等 → 再为 L0 增加第三个别名列;仍无「名字表」而非语言开关。标准库继续用**文件名**区分(见 i18n 草案)。
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 5. 与旧决议的关系
|
|
||||||
|
|
||||||
- 旧文「中文 `print` 废弃、统一为 `print`」:**废止**;改为正式双名 `print` / `打印`。
|
|
||||||
- [keywords.md](keywords.md) 原则条「英文标识」改为「**内核双名;标准库分文件**」——实现阶段改正文。
|
|
||||||
- 不引入中文控制流关键字(`如果`/`循环` 等);分支循环仍用 `+` / `-`。
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 6. 文档与金样例义务(实现时)
|
|
||||||
|
|
||||||
| 项 | 要求 |
|
|
||||||
|----|------|
|
|
||||||
| `keywords.md` | L0 表改为中英并列;砍掉对 `trim`/`split`/… 的「内核关键字」宣传 |
|
|
||||||
| `public/` | 英 / 中文件同目录并列(拉丁名 vs 中文名) |
|
|
||||||
| `tests/` | 中文关键字 / `打印`·`长度` 等金样例;与英文样例对等 |
|
|
||||||
| 诊断 | 位置格式不变;message 可暂维持英文,或中英均可接受(另开小节) |
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 7. 实现备忘(暂不开发)
|
|
||||||
|
|
||||||
1. 词法 / 解析:字面量与 `and`/`or`/`not` 识别中文别名。
|
|
||||||
2. 调用解析:内置表按别名归一到同一 `BuiltinId`。
|
|
||||||
3. 形参绑定:`text`≡`内容`,`prompt`≡`提示`,`value`≡`值`。
|
|
||||||
4. **不要**加 `lang:` 或全局「中文模式」。
|
|
||||||
5. 与 [stdlib-i18n.md](stdlib-i18n.md) 一并落地时:先收束 L0 公开面,再铺 `lib/text` ↔ `lib/文本`。
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 8. 一句话
|
|
||||||
|
|
||||||
**内核:中英别名、无需导入、必须少;标准库:中英分文件、靠导入路径选择——这样 Marqdo 才能中英文通用而不把解释器撑爆。**
|
|
||||||
@@ -1,95 +0,0 @@
|
|||||||
# Marqdo 关键字与内置名(v0 最小集)
|
|
||||||
|
|
||||||
| | |
|
|
||||||
|---|---|
|
|
||||||
| 状态 | 已定(中英双名) |
|
|
||||||
| 日期 | 2026-08-05 |
|
|
||||||
| 原则 | **少而精**;控制流靠 Markdown;内核中英**别名等价**(见 [keywords-i18n.md](keywords-i18n.md)) |
|
|
||||||
| 相关 | [markdown-mapping.md](markdown-mapping.md) · [keywords-i18n.md](keywords-i18n.md) · [stdlib-i18n.md](stdlib-i18n.md) |
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 1. 设计原则
|
|
||||||
|
|
||||||
1. **标记承担架构**:函数=`#`,分支=`+`,循环=`-`,返回=`**…**`,语句=`*…*`。因此 **不**把 `def`/`if`/`else`/`while`/`for`/`return` 做成关键字。
|
|
||||||
2. **内核双名**:字面量 / 逻辑词 / 五个核心内置函数均有中英别名,**无需导入**,可混用。
|
|
||||||
3. **学 Python 的边界**:区分 **关键字** vs **内置函数名**。
|
|
||||||
4. **宁少勿多**:扩展能力进可导入标准库(中英分文件,见 [stdlib-i18n.md](stdlib-i18n.md))。
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 2. 关键字(词法保留,不可作变量名)
|
|
||||||
|
|
||||||
| 英文 | 中文 | 含义 |
|
|
||||||
|------|------|------|
|
|
||||||
| `True` | `真` | 布尔真 |
|
|
||||||
| `False` | `假` | 布尔假 |
|
|
||||||
| `None` | `空` | 空值 |
|
|
||||||
| `and` | `且` | 逻辑与 |
|
|
||||||
| `or` | `或` | 逻辑或 |
|
|
||||||
| `not` | `非` | 逻辑非 |
|
|
||||||
|
|
||||||
**不引入:** `if` `else` `while` `for` `def` `return` …(分支臂 `*` 不是单词 `else`。)
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 3. 内置函数(可调用,无需导入)
|
|
||||||
|
|
||||||
| 英文 | 中文 | 作用 |
|
|
||||||
|------|------|------|
|
|
||||||
| `print` | `打印` | 写 stdout |
|
|
||||||
| `input` | `输入` | 读一行;capture / view 用 frontmatter `stdin:` / `输入:`、表单或 `--stdin-file` 预置 |
|
|
||||||
| `len` | `长度` | 文本/表长度 |
|
|
||||||
| `str` | `文本` | 转为显示文本 |
|
|
||||||
| `int` | `整数` | 转为整数 |
|
|
||||||
|
|
||||||
形参别名:
|
|
||||||
|
|
||||||
| 英文 | 中文 | 用于 |
|
|
||||||
|------|------|------|
|
|
||||||
| `text` | `内容` | `print` / `打印` |
|
|
||||||
| `prompt` | `提示` | `input` / `输入` |
|
|
||||||
| `value` | `值` | `len`/`str`/`int` 及其中文名 |
|
|
||||||
|
|
||||||
```markdown
|
|
||||||
> print text=Hello
|
|
||||||
> 打印 内容=你好
|
|
||||||
|
|
||||||
*`n` = > 长度 值=`s`*
|
|
||||||
```
|
|
||||||
|
|
||||||
宿主原语 `type` / `trim` / `split` / `join` / `at` **无**内核中文别名;文本/表扩展走标准库文件(见 [stdlib-i18n.md](stdlib-i18n.md))。转换错误见 [stdlib.md](stdlib.md)。
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 4. 与 Markup 调用的关系
|
|
||||||
|
|
||||||
```markdown
|
|
||||||
# main
|
|
||||||
|
|
||||||
> 打印 内容=Hello World!
|
|
||||||
|
|
||||||
*`n` = 1*
|
|
||||||
|
|
||||||
+ `n` > 0
|
|
||||||
> print text=positive
|
|
||||||
+ *
|
|
||||||
> 打印 内容=other
|
|
||||||
```
|
|
||||||
|
|
||||||
- `>` 是调用标记;`print` / `打印` 是同一内置的别名。
|
|
||||||
- 用户 `# print` 或 `# 打印` 会遮蔽对应名字。
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 5. 标识符规则(摘要)
|
|
||||||
|
|
||||||
- 变量:`` `name` ``;不可为上表任一中英文关键字。
|
|
||||||
- 函数名:`#` 标题;中英文均可。
|
|
||||||
- 比较:`==` `>` `<` `>=` `<=`;逻辑:`and`/`且`、`or`/`或`、`not`/`非`。
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 6. 后续可增(未批准)
|
|
||||||
|
|
||||||
`float`、`range`;以及 `break`/`continue`。增加前开短 ADR,并同步考虑是否值得占用双名配额。
|
|
||||||
@@ -1,221 +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. **叙述注释**以空行分段:段首无标记 → 注释;段内续行一律注释(见 §2)。
|
|
||||||
3. **可执行**靠标记:结构标记(`#` `>` `+` `-` 表…)与 **斜体语句** / **粗体返回**。
|
|
||||||
4. 作用域 = `#` 层数;入口 = `index.mq.md`。函数体可用 `---` / `***` 或空返回收束(见 §11)。
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 2. 行首判别与成段注释
|
|
||||||
|
|
||||||
跳过前导空白后,对**段首行**(空行之后的第一行,或文件起始):
|
|
||||||
|
|
||||||
| 首字符 | 分类 |
|
|
||||||
|--------|------|
|
|
||||||
| 普通文字 / 空 | **注释** |
|
|
||||||
| 标记字符 | **代码** |
|
|
||||||
|
|
||||||
标记含:`#` `*` `>` `+` `-` `` ` `` `|`、有序数字、围栏 `` ` ``、以及函数体内的结束分割线 `---` / `***`(见 §11)。
|
|
||||||
|
|
||||||
**成段注释(空行分段)**:段首一旦判定为注释,则直至下一空行之前的所有非空行一律为注释——即使续行以 `` ` `` / `-` / `*` 等开头也不升级为代码。叙述与可执行代码之间**必须空一行**。例外:单独一行的 `---` / `***` / `****`(函数结束或 frontmatter 闭合)始终为代码,并打断注释段。
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 3. 映射总表(v0.1)
|
|
||||||
|
|
||||||
| 标记 | 语义 |
|
|
||||||
|------|------|
|
|
||||||
| `#` … `######` | 函数;层数 = 作用域 |
|
|
||||||
| 函数头下 `-` 纯名 | 形参 |
|
|
||||||
| 体内 `-` | 循环 |
|
|
||||||
| 体内 `+` 或 `1.` | 分支 |
|
|
||||||
| 分支臂头整行恰为 `*` | else |
|
|
||||||
| `> 函数 形参=实参` 或 `> 函数 实参` | 调用(具名 / 位置,见 [call-arguments.md](call-arguments.md)) |
|
|
||||||
| frontmatter `> path.mq.md` | 跨文件导入 |
|
|
||||||
| `*…*` | **程序语句**(绑定、表达式句、可写的调用句等) |
|
|
||||||
| `**…**` | **返回值**(架构级;函数结果) |
|
|
||||||
| `****` / `**` + 空白 + `**` | **空返回**(`None`),并结束本函数体 |
|
|
||||||
| 无标记行 / 成段续行 | 注释(空行分段,见 §2) |
|
|
||||||
| GFM 表格 | 集合 |
|
|
||||||
| 空 RHS 赋值 + 后随 `$$…$$`(或同行 `$$…$$`) | **公式赋值** → 运行时 `formula`(见 [stdlib-math.md](stdlib-math.md));叙述面无名 `$$` 仅展示 |
|
|
||||||
| ` ```lang ` | 外联异种代码 |
|
|
||||||
| 函数体内 `---` / `***` | **结束本函数体**(无返回值函数的收束;见 §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
|
|
||||||
# main
|
|
||||||
|
|
||||||
> 问候 谁=World
|
|
||||||
|
|
||||||
## 问候
|
|
||||||
- 谁
|
|
||||||
|
|
||||||
> print text=Hello `谁`!
|
|
||||||
|
|
||||||
---
|
|
||||||
```
|
|
||||||
|
|
||||||
| 约定 | 说明 |
|
|
||||||
|------|------|
|
|
||||||
| `---` 或 `***` | 函数体**顶层**单独一行(长度 ≥ 3 且全为 `-` 或全为 `*`)→ **结束本函数**;后续语句属于外层 |
|
|
||||||
| `****` / 空粗体 | 空返回(值为 `None`),并同样结束本函数体 |
|
|
||||||
| 有值 `**expr**` | 普通返回;**不**自动截断后续兄弟句(仍可用分割线或下一同级/更浅标题收束) |
|
|
||||||
| Frontmatter | 仅**文件开头**成对 `---` = 元信息;与函数体内结束符消歧 |
|
|
||||||
| 分支/循环臂内 | 分割线仍可忽略(噪声),不截断外层函数 |
|
|
||||||
|
|
||||||
曾设想的「可选框住分支/循环」废止,分割线专用于函数收束。
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 12. v0.1 非目标
|
|
||||||
|
|
||||||
- break/continue、完整错误模型、静态类型、完整 FFI
|
|
||||||
- 用 `*` 作无序列表符
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 13. 示例索引
|
|
||||||
|
|
||||||
见 [`tests/`](../../tests/)。
|
|
||||||
@@ -1,75 +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` | 求值 | **JSON 行**(stderr):语句级事件,含 `path` / `span`(`line:col`) |
|
|
||||||
| `--dump-bytecode` | 字节码 | 反汇编 `Program`(指令旁带 `@line:col`;见 [bytecode.md](bytecode.md)) |
|
|
||||||
| `--backend tree\|bytecode` | 执行后端 | 默认 `tree`;`bytecode` 走栈式 VM |
|
|
||||||
| `--dump-all` | 以上全部 | 按管道顺序打印,段之间用横幅分隔 |
|
|
||||||
|
|
||||||
格式约定:
|
|
||||||
|
|
||||||
- dump 人类可读优先;段首统一:`=== marqdo: <stage> ===`
|
|
||||||
- `--trace-eval`:每条事件一行 JSON,例如
|
|
||||||
`{"event":"stmt","path":"…","span":"5:1","kind":"call","callee":"print"}`
|
|
||||||
树遍历:`enter_fn` / `stmt` / `leave_fn`;字节码:`op`(`print`/`input`/`call`/`return`)。
|
|
||||||
- 有 dump 时:若求值未实现,仍打印已实现阶段再以非 0 退出(便于 M1 只测 lines)
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 3. 横幅示例
|
|
||||||
|
|
||||||
```
|
|
||||||
=== marqdo: lines (tests/structure/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` 随阶段增长自动变完整 |
|
|
||||||
@@ -1,19 +0,0 @@
|
|||||||
# 记录:返回 / 语句 / 输出 / 分割线(决议)
|
|
||||||
|
|
||||||
| | |
|
|
||||||
|---|---|
|
|
||||||
| 状态 | 已决议(并入 mapping v0.1 + keywords;2026-08-04 修订函数收束) |
|
|
||||||
| 日期 | 2026-08-04 |
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 决议
|
|
||||||
|
|
||||||
1. **`*…*` = 程序语句**。
|
|
||||||
2. **`**…**` = 返回值**(架构级);空粗体 `****` / `** **` = 空返回(`None`)并结束函数体。
|
|
||||||
3. **输出**用内置函数 **`print`**(英文),不是粗体,不是中文名。
|
|
||||||
4. **`---` / `***`(函数体顶层)**:结束本函数体(无返回值函数收束);**不是**分支/循环装饰框。
|
|
||||||
5. **成段注释**:空行分段;段内续行不因首字符升级为代码。
|
|
||||||
6. **否决**:无标记行 = 默认代码。
|
|
||||||
|
|
||||||
详见 [keywords.md](keywords.md)、[markdown-mapping.md](markdown-mapping.md)、[code-vs-comment.md](code-vs-comment.md)。
|
|
||||||
@@ -1,49 +0,0 @@
|
|||||||
# 外联 / 胶水标准库
|
|
||||||
|
|
||||||
| | |
|
|
||||||
|---|---|
|
|
||||||
| 状态 | **已定(v1)** |
|
|
||||||
| 日期 | 2026-08-05 |
|
|
||||||
| 相关 | [stdlib-modules.md](stdlib-modules.md) · [stdlib-math.md](stdlib-math.md)(公式同构绑定) |
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 1. 原则
|
|
||||||
|
|
||||||
**导入即用**:`lib/foreign` / `lib/外联`。解释器来自用户本机(PATH / `set_cmd` / `MARQDO_FOREIGN_*`)。live view 可点 Run;静态导出展示源码,Run 禁用。
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 2. 绑定语法(与公式同构)
|
|
||||||
|
|
||||||
```markdown
|
|
||||||
`hi` =
|
|
||||||
```python
|
|
||||||
print("hello")
|
|
||||||
```
|
|
||||||
|
|
||||||
*`out` = > run code=`hi` *
|
|
||||||
```
|
|
||||||
|
|
||||||
得到运行时类型 **`code`**(`lang` + `source`)。未绑定的 \`\`\` 围栏仍是叙述注释。
|
|
||||||
|
|
||||||
曾用的 \`\`\`python name=hi **已移除**。
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 3. API
|
|
||||||
|
|
||||||
| 英文 | 中文 | 形参 | 结果 |
|
|
||||||
|------|------|------|------|
|
|
||||||
| `set_cmd` | `设置命令` | `lang`, `cmd` | None |
|
|
||||||
| `run` | `运行` | `code`(code 值) | 文本 stdout |
|
|
||||||
| `run_lang` | `按语言运行` | `lang`, `source` | 文本 |
|
|
||||||
| `langs` | `语言表` | | 列表 |
|
|
||||||
|
|
||||||
live view:Structure 中 code 卡片带命令框 + Run → `POST /api/foreign-run`。
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 4. 一句话
|
|
||||||
|
|
||||||
**`name` = + \`\`\`lang 围栏 → code 值;显式 run;本机解释器可配置。**
|
|
||||||
@@ -1,146 +0,0 @@
|
|||||||
# 标准库多语言命名(草案)
|
|
||||||
|
|
||||||
| | |
|
|
||||||
|---|---|
|
|
||||||
| 状态 | **草案(先文档、后实现)** |
|
|
||||||
| 日期 | 2026-08-04 |
|
|
||||||
| 原则 | **不指定语言**;靠**库文件名**区分中英(及日后其它语言) |
|
|
||||||
| 相关 | [stdlib.md](stdlib.md) · [stdlib-modules.md](stdlib-modules.md) · [keywords.md](keywords.md) · [keywords-i18n.md](keywords-i18n.md) · [user-site.md](user-site.md) |
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 1. 要解决什么
|
|
||||||
|
|
||||||
- 内置(解释器里的名字)必须**少而精**;更多能力放进可 `>` 导入的标准库。
|
|
||||||
- 标准库需要**中英两套 API**(函数名不同),并方便以后再加日文、西班牙文等。
|
|
||||||
- **不要**用 frontmatter `lang:`、环境变量默认语言、或「同一导入路径再解析语言」——那是负累,也不符合「文档即代码」的直观性。
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 2. 方案(采用)
|
|
||||||
|
|
||||||
**导入哪个库文件,就用哪套函数名。**
|
|
||||||
文件名本身表达语言;解释器只做路径解析,不做语言推断。
|
|
||||||
|
|
||||||
### 2.1 推荐:库名用目标语言书写
|
|
||||||
|
|
||||||
| 导入 | 库内函数名(示例) |
|
|
||||||
|------|-------------------|
|
|
||||||
| `> lib/text.mq.md` | `trim` · `split` · `join` |
|
|
||||||
| `> lib/文本.mq.md` | `去空白` · `拆分` · `拼接` |
|
|
||||||
| `> lib/table.mq.md` | `rows` · `row_at` |
|
|
||||||
| `> lib/表.mq.md` | `行数` · `取行` |
|
|
||||||
|
|
||||||
示例:
|
|
||||||
|
|
||||||
```markdown
|
|
||||||
---
|
|
||||||
> lib/text.mq.md
|
|
||||||
---
|
|
||||||
|
|
||||||
# main
|
|
||||||
*`xs` = > split value=a,b,c sep=,*
|
|
||||||
```
|
|
||||||
|
|
||||||
```markdown
|
|
||||||
---
|
|
||||||
> lib/文本.mq.md
|
|
||||||
---
|
|
||||||
|
|
||||||
# main
|
|
||||||
*`xs` = > 拆分 s=a,b,c sep=,*
|
|
||||||
```
|
|
||||||
|
|
||||||
读者看到导入路径就能知道后面该用英文还是中文函数名——**无需再声明语言**。
|
|
||||||
|
|
||||||
### 2.2 可选:同概念用后缀区分(同目录、同「概念」)
|
|
||||||
|
|
||||||
若希望「同一概念」在文件名上仍共享拉丁词根,可用:
|
|
||||||
|
|
||||||
| 导入 | 含义 |
|
|
||||||
|------|------|
|
|
||||||
| `> lib/text-en.mq.md` | 英文 API |
|
|
||||||
| `> lib/text-zh.mq.md` | 中文 API |
|
|
||||||
|
|
||||||
这与 §2.1 **等价可选**,不是第二套解析器:仍然是「写哪个路径就加载哪个文件」。
|
|
||||||
**优先推荐 §2.1**(`text` / `文本`),后缀形式留给需要 ASCII-only 路径的环境。
|
|
||||||
|
|
||||||
### 2.3 明确不做
|
|
||||||
|
|
||||||
| 不做 | 原因 |
|
|
||||||
|------|------|
|
|
||||||
| `lang: zh` / `MARQDO_LANG` | 隐式状态,难读、难测 |
|
|
||||||
| `> std/text` 再按语言展开 | 多一次魔法 |
|
|
||||||
| 同一文件内中英函数双份导出 | 遮蔽与文档混乱 |
|
|
||||||
| 强制用户只许用中文或只许用英文 | Marqdo 本就多语言友好 |
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 2.4 特例:JSON
|
|
||||||
|
|
||||||
`JSON` 为专有缩写,**不强求**中文库名或中文 API 翻译。官方只提供:
|
|
||||||
|
|
||||||
```text
|
|
||||||
lib/json.mq.md # 中英文档均 `> lib/json.mq.md`;函数 parse / stringify / get / keys
|
|
||||||
```
|
|
||||||
|
|
||||||
不设 `lib/数据.mq.md` 等平行文件。其余模块仍遵守 §2.1。详见 [stdlib-modules.md](stdlib-modules.md) §3.4。
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 3. 与「少而精内置」的边界
|
|
||||||
|
|
||||||
| 层 | 内容 | 如何获得 |
|
|
||||||
|----|------|----------|
|
|
||||||
| **内置(L0)** | 极少:`print` `input` `len` `str` `int`(及语言字面量关键字) | 直接调用,无需导入 |
|
|
||||||
| **标准库(L1)** | 文本/表等扩展 API;**通常**中英各一套文件、各一套函数名(**JSON 例外**:仅 `lib/json.mq.md`) | frontmatter `> lib/…` |
|
|
||||||
| **宿主原语(实现细节)** | 若 `trim`/`split` 等暂由解释器实现 | 仅供标准库包装调用;**文档与用户站引导走 L1**,不鼓励当「关键字」堆砌 |
|
|
||||||
|
|
||||||
日后若某能力足够「核心」,可再升格为 L0;升格前先留在 L1。
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 4. 目录与扩展约定
|
|
||||||
|
|
||||||
```text
|
|
||||||
lib/
|
|
||||||
text.mq.md / 文本.mq.md
|
|
||||||
table.mq.md / 表.mq.md
|
|
||||||
# 本波:fs/文件 · sys/系统 · time/时间 · json(中英同文件)· net/网络
|
|
||||||
# 暂缓:math/数学 · foreign/外联
|
|
||||||
# 其它语言:texte.mq.md / テキスト.mq.md …
|
|
||||||
```
|
|
||||||
|
|
||||||
扩展新语言时:
|
|
||||||
|
|
||||||
1. **新加一个库文件**(文件名用该语言或 `概念-xx`)。
|
|
||||||
2. 库内函数名用该语言习惯。
|
|
||||||
3. 文档表增加一行映射;**无需改解释器语言开关**。
|
|
||||||
|
|
||||||
导入解析仍沿用现有规则:相对路径 → 官方 `lib/` 根(`MARQDO_LIB` / 工作区 `lib/` 等),**不增加语言分支**。
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 5. 文档与示例义务
|
|
||||||
|
|
||||||
- 用户站:英/中库各一页(或同页两小节),导入路径与调用名并排;**JSON** 可共用一页、同一导入。
|
|
||||||
- 金样例:分文件模块中英导入至少各一条;JSON 测 `lib/json.mq.md` 即可。
|
|
||||||
- [keywords.md](keywords.md) 只列 L0;L1 指向本文 + [stdlib.md](stdlib.md) + [stdlib-modules.md](stdlib-modules.md)。
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 6. 实现备忘(暂不开发)
|
|
||||||
|
|
||||||
实现阶段仅需:
|
|
||||||
|
|
||||||
1. 落地 `lib/text.mq.md` 与 `lib/文本.mq.md`(及 table / 表)两套文件与函数名。
|
|
||||||
2. 更新导入示例与金样例;删除「仅中文库名」的单轨示例。
|
|
||||||
3. **不要**实现 `lang:`、默认语言、或 `std/text` 自动选语言。
|
|
||||||
|
|
||||||
若历史上加过 `Module.lang` / `lang:` 解析,应撤回,与本草案对齐。
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 7. 一句话
|
|
||||||
|
|
||||||
**标准库用文件名区分语言(导入即选择);JSON 为缩写特例,中英共用 `lib/json.mq.md`——无语言开关。**
|
|
||||||
@@ -1,231 +0,0 @@
|
|||||||
# 数学标准库(方案)
|
|
||||||
|
|
||||||
| | |
|
|
||||||
|---|---|
|
|
||||||
| 状态 | **已实现(M1–M4)** |
|
|
||||||
| 日期 | 2026-08-05 |
|
|
||||||
| 相关 | [stdlib-modules.md](stdlib-modules.md) · [stdlib-i18n.md](stdlib-i18n.md) · [markdown-mapping.md](markdown-mapping.md) · [view.md](view.md) |
|
|
||||||
| 导入 | `lib/math.mq.md`(英)· `lib/数学.mq.md`(中) |
|
|
||||||
| 范围 | **高中数学**(初等函数、导数、圆锥曲线、简单方程);非大学 CAS |
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 1. 目标
|
|
||||||
|
|
||||||
1. **公式类型**:解析 `$$…$$`(及行内 `$…$` 的可选支持),得到可绑定、可传递的 **`formula` 值**——语义上像「公式常量 / 公式变量」。
|
|
||||||
2. **数学库对 `formula`(及文本表达式)做操作**:求值、化简、求导、求解、作图等。
|
|
||||||
3. **数值 + 随机**:日常算术与可复现随机。
|
|
||||||
4. **作图**:view / 静态页内嵌 SVG;CLI 写本地文件(可指定 `path`)。
|
|
||||||
|
|
||||||
**难度自觉:** 只覆盖高中知识面,自研小型表达式 AST + 规则即可,**不**追求 Mathematica / SymPy 完备性。
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 2. 核心模型:`formula` 类型
|
|
||||||
|
|
||||||
### 2.1 运行时
|
|
||||||
|
|
||||||
| 类型 | `type` 标签 | 说明 |
|
|
||||||
|------|-------------|------|
|
|
||||||
| `Value::Num(f64)` | `num` | 浮点 |
|
|
||||||
| `Value::Formula(…)` | `formula` | 已解析的表达式树(或等价内部表示) |
|
|
||||||
|
|
||||||
`print` / `str` 对 `formula`:输出规范 ASCII(如 `2*x + 1`)或保留源 LaTeX 的一种(实现时写死并文档化;建议 **ASCII 规范式** 便于测试)。
|
|
||||||
|
|
||||||
### 2.2 文档中的 `$$` = 公式赋值(与表格同构)
|
|
||||||
|
|
||||||
在可执行面用 **空 RHS 赋值** 后跟展示数学块,把公式绑到变量(与 `` `xs` = `` 后跟表格一致):
|
|
||||||
|
|
||||||
````markdown
|
|
||||||
# main
|
|
||||||
|
|
||||||
`f` =
|
|
||||||
$$
|
|
||||||
sin(x) + x
|
|
||||||
$$
|
|
||||||
|
|
||||||
*`df` = > diff formula=`f` var=x *
|
|
||||||
|
|
||||||
> plot formula=`f` var=x min=-3 max=3 path=f.svg
|
|
||||||
````
|
|
||||||
|
|
||||||
也支持:
|
|
||||||
|
|
||||||
- 单行围栏:下一行 `$$x^2 - 2$$`
|
|
||||||
- 同行 compact:`*`f` = $$x^2 - 2$$ *`
|
|
||||||
|
|
||||||
**废除:** `$$:name` / `$$ name=…` 模块级具名块(不再产生绑定)。
|
|
||||||
|
|
||||||
**无名 `$$…$$`:** 仅在成段注释(叙述面)里作展示,**不**进入运行时。可执行区若出现未挂在赋值上的裸 `$$` 围栏 → 报错,提示使用 `` `name` = `` + 围栏。
|
|
||||||
|
|
||||||
**行内 `$…$`:** v1 不做绑定;需要时用 `> formula text=…` 显式构造。
|
|
||||||
|
|
||||||
### 2.3 从文本构造
|
|
||||||
|
|
||||||
| 英文 | 中文 | 说明 |
|
|
||||||
|------|------|------|
|
|
||||||
| `formula` | `公式` | `text=` 解析为 `formula`(ASCII 或简单 LaTeX 子集) |
|
|
||||||
|
|
||||||
数学库函数形参统一接受:**`formula` 值**,或能解析的 **文本**(内部先 `formula` 化)。
|
|
||||||
|
|
||||||
### 2.4 与叙述面的关系
|
|
||||||
|
|
||||||
- `` `f` = `` + `$$…$$`:代码面赋值,得到 `formula` 值。
|
|
||||||
- 成段注释里的 `$$`:仍是注释,不解析为公式。
|
|
||||||
- view:公式赋值在 Structure 中显示为绑定,不是 comment。
|
|
||||||
|
|
||||||
(见 [markdown-mapping.md](markdown-mapping.md):空 RHS + `$$` → 公式赋值。)
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 3. 知识范围(高中)
|
|
||||||
|
|
||||||
### 3.1 表达式与符号(S)
|
|
||||||
|
|
||||||
| 纳入 | 例子 |
|
|
||||||
|------|------|
|
|
||||||
| 多项式 | `x^2 - 3*x + 2` |
|
|
||||||
| 初等函数 | `sin` `cos` `tan` `ln` `exp` `sqrt` `abs` |
|
|
||||||
| 四则、幂 | `+ - * / ^` |
|
|
||||||
| 化简 / 展开 | 合并同类项、基本三角恒等(小集合) |
|
|
||||||
| 求导 | 单变元,初等函数求导法则 |
|
|
||||||
| 代入求值 | `subs` → `num` 或公式 |
|
|
||||||
| 求解 | 一元一次 / 二次闭式;其它用数值求根并标明 |
|
|
||||||
|
|
||||||
**不做(本波):** 多元方程组、极限 ε-δ、级数、积分保证、矩阵、复数完备、任意证明。
|
|
||||||
|
|
||||||
### 3.2 作图(P)
|
|
||||||
|
|
||||||
| 纳入 | 说明 |
|
|
||||||
|------|------|
|
|
||||||
| 显函数 `y=f(x)` | 采样折线 SVG |
|
|
||||||
| 导数曲线 | 对 `formula` 先 `diff` 再画,或 `plot` 选项 `derivative=true` |
|
|
||||||
| 圆锥曲线 | 标准形:圆、椭圆、双曲线、抛物线(参数方程或隐式采样) |
|
|
||||||
| 点列 | `plot_points` |
|
|
||||||
|
|
||||||
**不做:** 三维、隐函数通用求解器、交互缩放(静态 SVG 足够)。
|
|
||||||
|
|
||||||
### 3.3 数值与随机(N)
|
|
||||||
|
|
||||||
常数、四则、三角、对数、取整、`num` 转换、`random` / `random_int` / `seed`(同前稿)。
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 4. API 草图(对 `formula` 操作)
|
|
||||||
|
|
||||||
### 4.1 构造与数值
|
|
||||||
|
|
||||||
| 英文 | 中文 | 要点 |
|
|
||||||
|------|------|------|
|
|
||||||
| `formula` | `公式` | 文本 → formula |
|
|
||||||
| `pi` `e` | `圆周率` `自然底数` | → num |
|
|
||||||
| `add`… / `sin`… | `加`… / `正弦`… | 对 num;若传入 formula 则返回 formula(符号)或报错——**v1 建议:算术函数只接 num;符号用 simplify/diff/subs** |
|
|
||||||
| `eval` | `求值` | `formula` + 变量赋值 → num |
|
|
||||||
| `random` / `random_int` / `seed` | `随机` / `随机整数` / `设种子` | 见前 |
|
|
||||||
|
|
||||||
### 4.2 符号
|
|
||||||
|
|
||||||
| 英文 | 中文 | 形参 | 结果 |
|
|
||||||
|------|------|------|------|
|
|
||||||
| `simplify` | `化简` | `formula` | formula |
|
|
||||||
| `expand` | `展开` | `formula` | formula |
|
|
||||||
| `diff` | `求导` | `formula`, `var` | formula |
|
|
||||||
| `subs` | `代入` | `formula`, `var`, `value` | formula 或 num |
|
|
||||||
| `solve` | `求解` | `formula`, `var`,可选区间 | list(num 或公式根) |
|
|
||||||
|
|
||||||
### 4.3 作图
|
|
||||||
|
|
||||||
| 英文 | 中文 | 形参 |
|
|
||||||
|------|------|------|
|
|
||||||
| `plot` | `绘图` | **`formula`**(或 `expr` 文本), `var`, `min`, `max`;可选 `steps`, `path`, `derivative`, **`grid`**(默认开;`False`/`假` 关) |
|
|
||||||
| `plot_conic` | `绘圆锥` | `kind`(circle/ellipse/hyperbola/parabola)+ 系数;可选 `path`, `grid` |
|
|
||||||
| `plot_points` | `绘点列` | `xs`, `ys`;可选 `path`, `grid` |
|
|
||||||
|
|
||||||
返回 **SVG 文本**;坐标轴带箭头与刻度,默认网格;写文件与 view 嵌入规则同前(§5)。
|
|
||||||
|
|
||||||
`diff` / `simplify` / `expand` / 未完全数值化的 `subs` 返回 **`formula`**,可继续链式调用。
|
|
||||||
|
|
||||||
示例:
|
|
||||||
|
|
||||||
```markdown
|
|
||||||
# main
|
|
||||||
|
|
||||||
`f` =
|
|
||||||
$$
|
|
||||||
x^2 - 2
|
|
||||||
$$
|
|
||||||
|
|
||||||
*`roots` = > solve formula=`f` var=x *
|
|
||||||
|
|
||||||
> print text=`roots`
|
|
||||||
|
|
||||||
*`svg` = > plot formula=`f` var=x min=-3 max=3 path=parabola.svg *
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 5. 作图:CLI / view / 静态(不变精神)
|
|
||||||
|
|
||||||
| 场景 | 行为 |
|
|
||||||
|------|------|
|
|
||||||
| 带 `path=` | 写 SVG 到该路径(沙箱内) |
|
|
||||||
| CLI 无 path | 自动 `{stem}-plot-{n}.svg` + 一行 `plot: …` |
|
|
||||||
| view / 导出无 path | 不强制写盘;加入 **plots 产物列表**,Execution 内嵌 |
|
|
||||||
| view / 导出有 path | 写盘 + 内嵌 |
|
|
||||||
|
|
||||||
不把整段 SVG 默认灌进 CLI stdout。
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 6. 分期
|
|
||||||
|
|
||||||
| 期 | 交付 |
|
|
||||||
|----|------|
|
|
||||||
| **M1** | `Num` + 数值/随机;`Formula` AST + `` `name` = `` + `$$…$$` 赋值绑定 |
|
|
||||||
| **M2** | `simplify` / `diff` / `subs` / `eval` / 二次 `solve`(高中子集) |
|
|
||||||
| **M3** | `plot` / `plot_points` / `plot_conic` + view 内嵌 + path 写盘 |
|
|
||||||
| **M4** | 用户文档 `public/stdlib/math*` · 金样例 · mapping 文档补丁 |
|
|
||||||
|
|
||||||
M1–M3 可在同一发版列车上连续落地;验收以「公式赋值 → 求导 → 作图」一条龙为准。
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 7. 实现要点
|
|
||||||
|
|
||||||
```text
|
|
||||||
src/formula/ # 词法/AST/化简/求导/求值(高中规则表)
|
|
||||||
src/host/math.rs # 数值、随机、对 formula 的 host 入口
|
|
||||||
src/host/plot.rs # SVG
|
|
||||||
lex/parse:空 RHS 赋值 + $$ 围栏 → Expr::Formula
|
|
||||||
Value::Num / Value::Formula
|
|
||||||
Interpreter.plots: Vec<String>
|
|
||||||
lib/math.mq.md · lib/数学.mq.md
|
|
||||||
```
|
|
||||||
|
|
||||||
依赖:纯 Rust;不绑 SymPy。公式复杂度、采样点、SVG 大小设硬上限。
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 8. 刻意不做
|
|
||||||
|
|
||||||
- `$$:name` 模块级具名绑定(已废除)。
|
|
||||||
- 无名 `$$` 自动进运行时。
|
|
||||||
- 大学级数 / 完备积分 / 定理证明。
|
|
||||||
- 通用隐函数作图引擎。
|
|
||||||
- 3D、交互式图表库。
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 9. 验收
|
|
||||||
|
|
||||||
1. `` `f` = `` + `$$…$$` + `diff` / `solve` / `plot` 金样例(中英库)。
|
|
||||||
2. 固定 `seed` 的随机金样例。
|
|
||||||
3. `plot` + `path` 在 CLI 落盘;view HTML 含 `<svg`。
|
|
||||||
4. `type` 对公式为 `formula`,对浮点为 `num`。
|
|
||||||
5. view Structure 将公式赋值显示为绑定,而非 comment。
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 10. 一句话
|
|
||||||
|
|
||||||
**`` `f` = `` + `$$…$$` 产出 `formula` 值;数学库对它做高中范围的符号运算、求解与作图——数值与随机并行,图在 view 内嵌、在 CLI 写文件。**
|
|
||||||
@@ -1,228 +0,0 @@
|
|||||||
# 标准库下一波(L1 扩展模块)
|
|
||||||
|
|
||||||
| | |
|
|
||||||
|---|---|
|
|
||||||
| 状态 | **五库 + 数学已落地**;下一波:**外联**([stdlib-foreign.md](stdlib-foreign.md)) |
|
|
||||||
| 日期 | 2026-08-05 |
|
|
||||||
| 本波范围 | 文件 / 系统 / 时间 / JSON / 网络 / 数学(已完成) |
|
|
||||||
| 下一波 | **外联**(本机解释器 / 具名围栏) |
|
|
||||||
| 暂缓 | — |
|
|
||||||
| 原则 | 全部经 frontmatter **导入**;除 JSON 外中英分文件;内核保持少而精 |
|
|
||||||
| 相关 | [stdlib.md](stdlib.md) · [stdlib-i18n.md](stdlib-i18n.md) · [keywords-i18n.md](keywords-i18n.md) · [view.md](view.md) |
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 1. 目标
|
|
||||||
|
|
||||||
在现有 `lib/text`·`lib/文本`、`lib/table`·`lib/表` 之上,把 Marqdo 推进到可写日常脚本。标准库**必须导入**才可用。
|
|
||||||
|
|
||||||
| 模块族 | 英文库 | 中文库 | 本波 |
|
|
||||||
|--------|--------|--------|------|
|
|
||||||
| 文本(已有) | `lib/text.mq.md` | `lib/文本.mq.md` | 已有 |
|
|
||||||
| 表(已有) | `lib/table.mq.md` | `lib/表.mq.md` | 已有 |
|
|
||||||
| **文件** | `lib/fs.mq.md` | `lib/文件.mq.md` | **做** |
|
|
||||||
| **系统** | `lib/sys.mq.md` | `lib/系统.mq.md` | **做** |
|
|
||||||
| **时间** | `lib/time.mq.md` | `lib/时间.mq.md` | **做** |
|
|
||||||
| **JSON** | `lib/json.mq.md` | **同文件(特例,§3.4)** | **做** |
|
|
||||||
| **网络(简)** | `lib/net.mq.md` | `lib/网络.mq.md` | **做** |
|
|
||||||
| 数学 | `lib/math.mq.md` | `lib/数学.mq.md` | **下一波** |
|
|
||||||
| 外联 | `lib/foreign.mq.md` | `lib/外联.mq.md` | **做** |
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 2. 分层与实现分工
|
|
||||||
|
|
||||||
```text
|
|
||||||
用户 .mq.md
|
|
||||||
│ > lib/fs.mq.md
|
|
||||||
▼
|
|
||||||
L1 官方库(.mq.md)
|
|
||||||
│
|
|
||||||
▼
|
|
||||||
L0.5 宿主原语(Rust,英文蛇形)
|
|
||||||
│
|
|
||||||
▼
|
|
||||||
OS / HTTP / 时钟 / …
|
|
||||||
```
|
|
||||||
|
|
||||||
| 层 | 谁实现 | 用户是否直接调用 |
|
|
||||||
|----|--------|------------------|
|
|
||||||
| **L0** | 解释器内置 | 是(`print`/`len`/…) |
|
|
||||||
| **L0.5 宿主原语** | Rust(`src/builtin` 或 `src/host/`) | **原则上否**;供 L1 包装;金样例可直测 |
|
|
||||||
| **L1 官方库** | `lib/*.mq.md` | **是**(文档与用户站只教这一层) |
|
|
||||||
|
|
||||||
规则:
|
|
||||||
|
|
||||||
1. **导入即选择语言**(JSON 除外):`lib/fs.mq.md` → 英文 API;`lib/文件.mq.md` → 中文 API(见 [stdlib-i18n.md](stdlib-i18n.md))。
|
|
||||||
2. **不设 `lang:`**。
|
|
||||||
3. 宿主原语保持英文;中英差异只存在于 L1 包装层(JSON 无第二套包装)。
|
|
||||||
4. 失败一律 `path:line:col: message`([stdlib.md](stdlib.md) §4)。
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 3. 核心模块 API 草图(L1)
|
|
||||||
|
|
||||||
### 3.1 文件 — `fs` / `文件`
|
|
||||||
|
|
||||||
| 英文 | 中文 | 形参(英 / 中) | 结果 |
|
|
||||||
|------|------|-----------------|------|
|
|
||||||
| `read_text` | `读文本` | `path` / `路径` | 文本 |
|
|
||||||
| `write_text` | `写文本` | `path`, `text` / `路径`, `内容` | `None` |
|
|
||||||
| `append_text` | `追加文本` | 同上 | `None` |
|
|
||||||
| `exists` | `存在` | `path` / `路径` | 布尔 |
|
|
||||||
| `list_dir` | `列目录` | `path` / `路径` | 文本列表 |
|
|
||||||
| `make_dir` | `建目录` | `path` / `路径` | `None` |
|
|
||||||
| `remove` | `删除` | `path` / `路径` | `None` |
|
|
||||||
|
|
||||||
约定:路径相对工作目录或绝对路径;二进制 I/O 本波不做;写/删默认需 `--allow-fs-write`(§6)。
|
|
||||||
|
|
||||||
### 3.2 系统 — `sys` / `系统`
|
|
||||||
|
|
||||||
| 英文 | 中文 | 形参 | 结果 |
|
|
||||||
|------|------|------|------|
|
|
||||||
| `env_get` | `取环境` | `name` / `名` | 文本或 `None` |
|
|
||||||
| `env_set` | `设环境` | `name`, `value` / `名`, `值` | `None` |
|
|
||||||
| `args` | `参数表` | (无) | 文本列表 |
|
|
||||||
| `cwd` | `工作目录` | (无) | 文本 |
|
|
||||||
| `exit` | `退出` | `code` / `码` | 不返回 |
|
|
||||||
| `exec` | `执行` | `cmd`, 可选 `args` | 退出码(实现时写死语义) |
|
|
||||||
|
|
||||||
`exec` 默认关(`--allow-exec`);view / 静态站永不开放。
|
|
||||||
|
|
||||||
### 3.3 时间 — `time` / `时间`
|
|
||||||
|
|
||||||
| 英文 | 中文 | 形参 | 结果 |
|
|
||||||
|------|------|------|------|
|
|
||||||
| `now_unix` | `此刻秒` | (无) | 整数(Unix 秒) |
|
|
||||||
| `now_ms` | `此刻毫秒` | (无) | 整数 |
|
|
||||||
| `format` | `格式化` | `unix`, `pattern` / `秒`, `格式` | 文本 |
|
|
||||||
| `sleep_ms` | `睡眠毫秒` | `ms` / `毫秒` | `None` |
|
|
||||||
| `parse` | `解析时间` | `text`, `pattern` / `内容`, `格式` | 整数秒或诊断失败 |
|
|
||||||
|
|
||||||
view 中 `sleep_ms` 设上限(如 5s)。
|
|
||||||
|
|
||||||
### 3.4 JSON — `json`(**中英同库特例**)
|
|
||||||
|
|
||||||
JSON 是专有缩写,**很难也不必要**做合规中文库名/API 翻译。本波定稿:
|
|
||||||
|
|
||||||
| 项 | 约定 |
|
|
||||||
|----|------|
|
|
||||||
| 唯一路径 | **`lib/json.mq.md`**(中英文档均导入此路径) |
|
|
||||||
| 函数名 | 国际通行英文:`parse` / `stringify` / `get` / `keys` |
|
|
||||||
| 形参 | 英文:`text` / `value` / `key` / `indent` |
|
|
||||||
| 不设 | `lib/数据.mq.md`、音译名、中文函数双份 |
|
|
||||||
|
|
||||||
这是对 [stdlib-i18n.md](stdlib-i18n.md)「一概念两文件」的**显式例外**;其它模块仍中英分文件。
|
|
||||||
|
|
||||||
| 函数 | 形参 | 结果 |
|
|
||||||
|------|------|------|
|
|
||||||
| `parse` | `text` | 值(见下) |
|
|
||||||
| `stringify` | `value`, 可选 `indent` | JSON 文本 |
|
|
||||||
| `get` | `value`, `key` | 值或 `None` |
|
|
||||||
| `keys` | `value` | 文本列表 |
|
|
||||||
|
|
||||||
**类型映射(草案)**:
|
|
||||||
|
|
||||||
| JSON | Marqdo Value |
|
|
||||||
|------|----------------|
|
|
||||||
| `null` | `None` |
|
|
||||||
| bool | bool |
|
|
||||||
| number(整数可表) | int |
|
|
||||||
| number(其余) | 文本(本波不引入 float)或诊断拒绝 |
|
|
||||||
| string | text |
|
|
||||||
| array | list |
|
|
||||||
| object | 倾向新宿主类型 **`map`**(`type` → `map`);否则体验差 |
|
|
||||||
|
|
||||||
`map` 为 L0.5 类型扩展,可与 json 同期或紧随;不阻塞 `fs`/`time` 先行。
|
|
||||||
|
|
||||||
### 3.5 网络(简)— `net` / `网络`
|
|
||||||
|
|
||||||
| 英文 | 中文 | 形参 | 结果 |
|
|
||||||
|------|------|------|------|
|
|
||||||
| `http_get` | `获取` | `url` / `地址` | 响应文本(或 map:status/body) |
|
|
||||||
| `http_post` | `提交` | `url`, `body`, 可选 `content_type` | 同上 |
|
|
||||||
| `url_encode` | `编码地址` | `text` / `内容` | 文本 |
|
|
||||||
|
|
||||||
仅 **HTTP 明文**(HTTPS 本波未做,会诊断提示);短超时、响应体上限;默认需 `--allow-net`;view / 静态站默认关。
|
|
||||||
|
|
||||||
**路径字面量:** 具名实参里 `path=a/b` 会被解析成除法。请用无斜杠文件名,或先赋给变量再传入。
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 4. 中英路径总表(本波)
|
|
||||||
|
|
||||||
```text
|
|
||||||
lib/
|
|
||||||
text.mq.md / 文本.mq.md # 已有
|
|
||||||
table.mq.md / 表.mq.md # 已有
|
|
||||||
fs.mq.md / 文件.mq.md # 本波
|
|
||||||
sys.mq.md / 系统.mq.md
|
|
||||||
time.mq.md / 时间.mq.md
|
|
||||||
json.mq.md # 本波;中英共用,无第二文件
|
|
||||||
net.mq.md / 网络.mq.md
|
|
||||||
# 暂缓:math / 数学 · foreign / 外联
|
|
||||||
```
|
|
||||||
|
|
||||||
别名:`std/…` ≡ `lib/…`。
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 5. 落地分期(本波 = M1–M5)
|
|
||||||
|
|
||||||
| 期 | 内容 | 完成定义 |
|
|
||||||
|----|------|----------|
|
|
||||||
| **M1** | 宿主能力框架:权限旗标、`host` 分发、错误文案 | `--allow-*` 可测 |
|
|
||||||
| **M2** | `fs` + `time`(只读 fs + 时钟) | 中英库 + 金样例 |
|
|
||||||
| **M3** | `sys`(env/cwd/args;`exec` 默认关) | 同上 |
|
|
||||||
| **M4** | `json`(+ 可选 `map`) | 往返金样例;唯 `lib/json.mq.md` |
|
|
||||||
| **M5** | `net`(默认关) | 本地 mock 或录制夹具 |
|
|
||||||
|
|
||||||
**不做 M6/M7**(数学 / 外联):详稿仅存档,待五库稳定后再议。
|
|
||||||
|
|
||||||
文档站:`fs`/`sys`/`time`/`net` 英中各一页;`json` 可一页双语叙述、同一导入路径。
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 6. 安全与 view / 静态导出
|
|
||||||
|
|
||||||
### 6.1 行为一致
|
|
||||||
|
|
||||||
`marqdo run`、live `view`、`view output` 对标准库 **默认同一套能力**(读/写盘、HTTP、exec 均可用)。导入库即表示要用;不再要求 `--allow-*`。
|
|
||||||
|
|
||||||
差异仅在 **软退出**:
|
|
||||||
|
|
||||||
| | CLI `run` | view / capture / 静态导出 |
|
|
||||||
|--|-----------|---------------------------|
|
|
||||||
| `exit` | 结束进程 | 报诊断,不杀 view/构建进程 |
|
|
||||||
| `sleep_ms` | 默认可睡(有上限) | live 有上限;导出通常为 0 |
|
|
||||||
|
|
||||||
沙箱:相对路径落在源文件目录(或 view 根)下,防止 `..` 逃逸。
|
|
||||||
|
|
||||||
### 6.2 静态部署
|
|
||||||
|
|
||||||
访客浏览器 **不再执行** Marqdo;HTML 里是构建时冻结的输出。源码中的路径/URL 访客改不了、也触发不了新的 host 调用。审 PR 时审查写死的目标即可。
|
|
||||||
|
|
||||||
勿在静态页嵌入「用户可改 URL 再请求」的浏览器脚本。
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 7. 与现有库的关系
|
|
||||||
|
|
||||||
- `text` / `table` 继续纯包装、无 IO。
|
|
||||||
- JSON `stringify` ≠ `str`(显示)。
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 8. 刻意不做(本波)
|
|
||||||
|
|
||||||
- 数学库、外联/胶水库(及其依赖、权限旗标实现)。
|
|
||||||
- 数据库、异步事件循环、WebSocket、原始 TCP。
|
|
||||||
- float/复数进 L0。
|
|
||||||
- `lang:` 或按 locale 自动选库。
|
|
||||||
- 为 JSON 强造中文库名或中文 API 双份。
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 9. 一句话
|
|
||||||
|
|
||||||
**本波只落地文件 / 系统 / 时间 / JSON / 网络;JSON 中英共用 `lib/json.mq.md`;数学与外联暂缓。**
|
|
||||||
@@ -1,96 +0,0 @@
|
|||||||
# 标准库(P2)
|
|
||||||
|
|
||||||
| | |
|
|
||||||
|---|---|
|
|
||||||
| 状态 | **S0–S3 落地** |
|
|
||||||
| 日期 | 2026-08-04 |
|
|
||||||
| 相关 | [keywords.md](keywords.md) · [call-arguments.md](call-arguments.md) · [stdlib-i18n.md](stdlib-i18n.md) · [stdlib-modules.md](stdlib-modules.md) · [roadmap/next-phase.md](../roadmap/next-phase.md) |
|
|
||||||
|
|
||||||
> **多语言库命名**:见 [stdlib-i18n.md](stdlib-i18n.md)(不设 `lang:`;中英分文件)。
|
|
||||||
> **下一波模块(本波:文件 / 系统 / 时间 / JSON / 网络;数学·外联暂缓)**:见 [stdlib-modules.md](stdlib-modules.md)。
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 1. 分层
|
|
||||||
|
|
||||||
| 层 | 内容 |
|
|
||||||
|----|------|
|
|
||||||
| **L0 内置** | 解释器内:`print` `input` `len` `str` `int` `type` `trim` `split` `join` `at` |
|
|
||||||
| **L1 官方库** | 仓库根目录 [`lib/`](../../lib/)(`.mq.md`);可用 `lib/…` 或别名 `std/…` 导入 |
|
|
||||||
| **L2** | catalog / 用户站收录(随发版) |
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 2. 内置一览(S0 + S1)
|
|
||||||
|
|
||||||
| 名 | 形参 | 结果 |
|
|
||||||
|----|------|------|
|
|
||||||
| `len` | `value` | 文本标量数或列表长度 |
|
|
||||||
| `str` | `value` | 显示文本 |
|
|
||||||
| `int` | `value` | 整数(失败 → 诊断) |
|
|
||||||
| `type` | `value` | `none`/`bool`/`int`/`text`/`list` |
|
|
||||||
| `trim` | `value` | 去首尾空白 |
|
|
||||||
| `split` | `value`, `sep` | 文本列表 |
|
|
||||||
| `join` | `value`, `sep` | 拼接文本 |
|
|
||||||
| `at` | `value`, `index` | 列表下标(越界 → `None`) |
|
|
||||||
|
|
||||||
表(单列表格)在运行时是 `list`:行数用 `len`,取行用 `at`。
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 3. 官方库导入(S2)
|
|
||||||
|
|
||||||
Frontmatter:
|
|
||||||
|
|
||||||
```markdown
|
|
||||||
---
|
|
||||||
> lib/text.mq.md
|
|
||||||
> lib/table.mq.md
|
|
||||||
---
|
|
||||||
```
|
|
||||||
|
|
||||||
`std/text.mq.md` 等价于 `lib/text.mq.md`。解析顺序:
|
|
||||||
|
|
||||||
1. 相对当前文件
|
|
||||||
2. `MARQDO_LIB`(可指向 `lib` 目录或仓库根)
|
|
||||||
3. 当前工作目录的 `lib/`
|
|
||||||
4. 可执行文件附近的 `lib/`(含 `cargo run` 的相对路径)
|
|
||||||
|
|
||||||
当前模块:
|
|
||||||
|
|
||||||
| 路径 | 导出函数 |
|
|
||||||
|------|----------|
|
|
||||||
| `lib/fs.mq.md` / `lib/文件.mq.md` | `read_text`… / `读文本`… |
|
|
||||||
| `lib/time.mq.md` / `lib/时间.mq.md` | `now_unix`… / `此刻秒`… |
|
|
||||||
| `lib/sys.mq.md` / `lib/系统.mq.md` | `env_get`… / `取环境`… |
|
|
||||||
| `lib/json.mq.md` | `parse` `stringify` `get` `keys`(中英同文件) |
|
|
||||||
| `lib/net.mq.md` / `lib/网络.mq.md` | `http_get`… / `获取`… |
|
|
||||||
| `lib/text.mq.md` | `str_trim` `str_split` `str_join` |
|
|
||||||
| `lib/文本.mq.md` | `去空白` `拆分` `拼接` |
|
|
||||||
| `lib/table.mq.md` | `rows` `row_at` |
|
|
||||||
| `lib/表.mq.md` | `行数` `取行` |
|
|
||||||
|
|
||||||
规划中的 L1 扩展见 [stdlib-modules.md](stdlib-modules.md)。
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 4. 转换错误约定(S3)
|
|
||||||
|
|
||||||
用户可见失败统一为:
|
|
||||||
|
|
||||||
```text
|
|
||||||
path:line:col: message
|
|
||||||
```
|
|
||||||
|
|
||||||
内置转换相关文案(稳定子集,金样例断言):
|
|
||||||
|
|
||||||
| 情况 | message |
|
|
||||||
|------|---------|
|
|
||||||
| 非法整数文本 | `cannot convert to int: "…"` |
|
|
||||||
| `int` 类型不对 | `int needs int, bool, or text` |
|
|
||||||
| `len` 类型不对 | `len needs text or list` |
|
|
||||||
| `trim` 非文本 | `trim needs text` |
|
|
||||||
| `split`/`join` 参数类型 | `split needs text value` 等 |
|
|
||||||
| 空分隔符 | `split sep must not be empty` |
|
|
||||||
|
|
||||||
不引入独立异常类型对象;一律走 `Diagnostic`。
|
|
||||||
@@ -1,152 +0,0 @@
|
|||||||
# 参考实现:技术选型分析(尚未拍板)
|
|
||||||
|
|
||||||
| | |
|
|
||||||
|---|---|
|
|
||||||
| 状态 | **分析中 — 未定案** |
|
|
||||||
| 日期 | 2026-08-04 |
|
|
||||||
| 说明 | 对比候选与约束;**不在本文直接开写实现仓库脚手架** |
|
|
||||||
|
|
||||||
上一版曾草率写「就用 TypeScript」——信息不足,已作废为定论。本文只做选型框架与对比,**最终实现语言须单开 ADR 确认后再动工。**
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 1. 我们在选什么
|
|
||||||
|
|
||||||
参考实现至少包含:
|
|
||||||
|
|
||||||
1. **读入** `.mq.md`(含 frontmatter 混合行)
|
|
||||||
2. **对齐 GFM** 的结构:标题、列表(`-`/`+`/`1.`)、强调、表格、围栏、链接
|
|
||||||
3. **Lower**:行首判别、标题树作用域、列表符语义、注释剥离
|
|
||||||
4. **两遍**:收集定义 + 导入 → 求值
|
|
||||||
5. **CLI** + **金样例测试**(`tests/`)
|
|
||||||
|
|
||||||
可选后期:字节码/编译、LSP、格式化。首版目标是**验证语法宪法**,不是上生产编译器。
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 2. 选型准则(按权重)
|
|
||||||
|
|
||||||
| 权重 | 准则 | 说明 |
|
|
||||||
|------|------|------|
|
|
||||||
| 高 | GFM 忠实度 | 表格、列表符、强调边界与 GitHub 预览一致,减少「能渲染不能跑 / 能跑不能渲染」 |
|
|
||||||
| 高 | 与宪法同构 | 易于表达「先 mdast/事件流,再 Marqdo AST」 |
|
|
||||||
| 高 | 测试与迭代速度 | 改语法宪法时能快速改测试 |
|
|
||||||
| 中 | 静态类型 / 可维护 AST | 长期改解释器不疼 |
|
|
||||||
| 中 | CLI 与打包 | 单二进制或 `npx`/等价体验 |
|
|
||||||
| 低 | 极致性能 | v0 样例很小 |
|
|
||||||
| 低 | 浏览器内运行 | 可后置 |
|
|
||||||
|
|
||||||
非准则:跟风、先写再选、与「生成 OKF」强绑某一云厂商。
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 3. 架构共性(与语言无关)
|
|
||||||
|
|
||||||
无论选哪门实现语言,流水线应一致:
|
|
||||||
|
|
||||||
```
|
|
||||||
.mq.md 文本
|
|
||||||
→ 前端:GFM 友好解析(或事件扫描)
|
|
||||||
→ Middle:Marqdo lower(行类、标题树、- / +、表、围栏)
|
|
||||||
→ Marqdo AST
|
|
||||||
→ 语义:导入图、提升、作用域
|
|
||||||
→ 后端:解释器(v0)/日后编译
|
|
||||||
→ 测试:tests 金样例 → 期望 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. **对照验收用例**(固定):`tests/structure/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)),再谈用何种语言写分类器。选型不能假设「整文件都是可执行代码」。
|
|
||||||
@@ -1,57 +0,0 @@
|
|||||||
# 用户静态文档站(public / gh-pages)
|
|
||||||
|
|
||||||
| | |
|
|
||||||
|---|---|
|
|
||||||
| 状态 | 已定 |
|
|
||||||
| 日期 | 2026-08-04 |
|
|
||||||
| 相关 | [view.md](view.md) · 源目录 [`public/`](../../public/) |
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 1. 分工
|
|
||||||
|
|
||||||
| 路径 | 是否入库 | 职责 |
|
|
||||||
|------|----------|------|
|
|
||||||
| `doc/` | 是 | 开发者设计 / ADR / 路线图(单数 `doc`,勿再造 `docs/`) |
|
|
||||||
| `public/**/*.mq.md` | 是 | 用户可读、可执行、可下载的介绍(结构 / 关键字 / 特性迭代);**双语**:拉丁文件名 = 英文,中文文件名 = 中文编程,同目录并列 |
|
|
||||||
| `public/index.html`、`public/pages/` | **否**(ignore) | `marqdo view output` 生成的 HTML |
|
|
||||||
| `tests/{structure,keywords,errors}/` | 是 | 金样例与失败夹具(含 errors) |
|
|
||||||
| 远程分支 `gh-pages` | 发布产物 | 发布整个 `public/`(源文件 + 生成 HTML) |
|
|
||||||
|
|
||||||
**禁止**把 `tests/errors/` 编进用户站。
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 2. 生成
|
|
||||||
|
|
||||||
```bash
|
|
||||||
cargo run --release -- view output public -o public
|
|
||||||
# 或
|
|
||||||
./scripts/build-public.sh
|
|
||||||
powershell -File ./scripts/build-public.ps1
|
|
||||||
```
|
|
||||||
|
|
||||||
产物写在源旁:
|
|
||||||
|
|
||||||
```
|
|
||||||
public/
|
|
||||||
*.mq.md / structure/ / … # 入库源
|
|
||||||
index.html # 生成(ignore)
|
|
||||||
pages/… # 生成(ignore)
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 3. 发布分支
|
|
||||||
|
|
||||||
将构建后的 `public/` 推到 **`gh-pages`**。CI:`.github/workflows/pages.yml`。
|
|
||||||
|
|
||||||
仓库 Settings → Pages → Source = Deploy from branch → `gh-pages` / root。
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 4. 验收
|
|
||||||
|
|
||||||
1. `public/` 下每个 `.mq.md`(除纯工具模块外)`marqdo run` 退出码 0。
|
|
||||||
2. `view output public -o public` 后首页为欢迎页,侧栏无 errors。
|
|
||||||
3. 主分支跟踪 `public/**/*.mq.md`;不提交 `public/index.html` / `public/pages/`。
|
|
||||||
@@ -1,42 +0,0 @@
|
|||||||
# View 调试(`marqdo debug`)
|
|
||||||
|
|
||||||
| | |
|
|
||||||
|---|---|
|
|
||||||
| 状态 | **v1(独立 debug 页)** |
|
|
||||||
| 日期 | 2026-08-05 |
|
|
||||||
| 相关 | [next-phase.md](../roadmap/next-phase.md) P3 · [view.md](view.md) · [pipeline-debug.md](pipeline-debug.md) |
|
|
||||||
|
|
||||||
## 分工
|
|
||||||
|
|
||||||
| 命令 | 角色 |
|
|
||||||
|------|------|
|
|
||||||
| `marqdo view` | 文档浏览器:Structure + Execution + Source;函数大纲与搜索;**无断点** |
|
|
||||||
| `marqdo debug` | 调试宿主(默认端口 **7430**):IDE 式布局;**仅 live** |
|
|
||||||
|
|
||||||
静态 `gh-pages` / `view output` **不能**真断点。
|
|
||||||
|
|
||||||
## Debug 布局(对齐常见调试器)
|
|
||||||
|
|
||||||
参考 VS Code / Chrome DevTools / Jupyter debugger:
|
|
||||||
|
|
||||||
```
|
|
||||||
┌ Toolbar: Start · Continue (F5) · Step (F10) · Stop · status ─┐
|
|
||||||
├ Files ─┬─ Structure (gutter BP) + outline ─┬─ Variables ┤
|
|
||||||
│ │ ├─ Breakpoints │
|
|
||||||
│ │ └─ Call stack │
|
|
||||||
├────────┴────────────────────────────────────┴────────────────┤
|
|
||||||
│ Debug Console (session stdout) │
|
|
||||||
└──────────────────────────────────────────────────────────────┘
|
|
||||||
```
|
|
||||||
|
|
||||||
- 暂停粒度:语句起点(树遍历)。
|
|
||||||
- 无断点时 Start 停在第一句。
|
|
||||||
- Structure 为断点面(非 Source 行)。
|
|
||||||
|
|
||||||
## API
|
|
||||||
|
|
||||||
与此前相同:`POST /api/debug/start|continue|step|stop|breakpoints`(仅 debug 服务)。
|
|
||||||
|
|
||||||
## View 大纲
|
|
||||||
|
|
||||||
Structure 旁(或窄屏下方)函数树:`#fn-{line}` 锚点 + 搜索框过滤 `data-fn` / `data-fn-path`。
|
|
||||||
@@ -1,116 +0,0 @@
|
|||||||
# `marqdo view` — 源结构浏览器与静态文档导出
|
|
||||||
|
|
||||||
| | |
|
|
||||||
|---|---|
|
|
||||||
| 状态 | 已定(v0.0.2 方向) |
|
|
||||||
| 日期 | 2026-08-04 |
|
|
||||||
| 相关 | [examples-and-tests.md](examples-and-tests.md) · [generated-yaml-manifest.md](generated-yaml-manifest.md) · 视觉参考 [id.cflmy.cn](https://id.cflmy.cn) |
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 1. 动机
|
|
||||||
|
|
||||||
`.mq.md` 既是文档也是程序。需要:
|
|
||||||
|
|
||||||
1. **本地浏览**:按 AST 展示结构 + 执行结果;
|
|
||||||
2. **静态导出**:同一套渲染写成 HTML,作为**用户文档站点**(勿手写第二套站点);
|
|
||||||
3. **启动快**:样式极简,无外链字体/厚主题,避免 view 冷启动慢。
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 2. 视觉(Apple HIG / Docs 极简)
|
|
||||||
|
|
||||||
对齐 [Apple HIG](https://developer.apple.com/design/human-interface-guidelines) 的 **clarity / deference / white space**,并参考常见 docs 布局(sticky 侧栏 + 居中主栏,见 Nextra / Docusaurus 类站点):**系统灰底、白内容面、浅分隔线、系统字体**。作者站 [id.cflmy.cn](https://id.cflmy.cn) 仍作克制感参考,但不强行纯黑描边。
|
|
||||||
|
|
||||||
| 规则 | 要求 |
|
|
||||||
|------|------|
|
|
||||||
| 色板 | 页底 `#f5f5f7`;内容面 `#ffffff`;正文 `#1d1d1f`;次要字 `#6e6e73`;分隔 `#d2d2d7`;选中侧栏项反白 |
|
|
||||||
| 布局 | 壳层 `max-width ≈ 1680px`;侧栏 ≈280px;主内容 `max-width ≈ 76rem`;Structure 旁函数大纲;**≤800px 侧栏收起** |
|
|
||||||
| 默认页 | 打开目录时 **直接展示排序后的第一个 `.mq.md`**(实时 `/` 与静态 `index.html` 同),不要求用户先从欢迎页点选 |
|
|
||||||
| 字体 | 仅系统栈:`-apple-system, BlinkMacSystemFont, "Segoe UI", Helvetica, Arial, sans-serif`;等宽 `ui-monospace, SFMono-Regular, Menlo, Consolas, monospace` |
|
|
||||||
| 外链 | **禁止** Google Fonts / CDN 样式;CSS 全部内联于 HTML |
|
|
||||||
| 装饰 | 无多层阴影、无渐变、无发光;圆角 ≈12px;结构区为分组列表(底部分隔),非堆叠厚卡片 |
|
|
||||||
| 诊断路径 | 展示时去掉 Windows `\\?\` 前缀,并优先用相对 view 根的路径 |
|
|
||||||
|
|
||||||
验收:首屏无外网字体请求;宽屏主栏明显宽于早期 `58rem` 方案(现约 `76rem` / 壳 `1680px`)。
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 3. CLI
|
|
||||||
|
|
||||||
### 3.1 实时浏览
|
|
||||||
|
|
||||||
```bash
|
|
||||||
marqdo view [PATH] [--port PORT] [--host HOST] [--no-open]
|
|
||||||
```
|
|
||||||
|
|
||||||
| 参数 | 默认 | 说明 |
|
|
||||||
|------|------|------|
|
|
||||||
| `PATH` | `.` | `.mq.md` 或目录 |
|
|
||||||
| `--port` | `7429` | |
|
|
||||||
| `--host` | `127.0.0.1` | |
|
|
||||||
| `--no-open` | 关 | 不打开浏览器 |
|
|
||||||
|
|
||||||
### 3.2 静态导出(文档生成)
|
|
||||||
|
|
||||||
```bash
|
|
||||||
marqdo view output [PATH] -o OUT_DIR [--no-exec]
|
|
||||||
```
|
|
||||||
|
|
||||||
| 参数 | 默认 | 说明 |
|
|
||||||
|------|------|------|
|
|
||||||
| `PATH` | `.` | 与 `view` 相同扫描范围 |
|
|
||||||
| `-o` / `--out` | (必填) | 输出目录(不存在则创建) |
|
|
||||||
| `--no-exec` | 关 | 不跑程序,执行区显示「skipped」 |
|
|
||||||
|
|
||||||
**产物布局:**
|
|
||||||
|
|
||||||
```
|
|
||||||
OUT_DIR/
|
|
||||||
index.html # 默认 = 排序后第一个 .mq.md 的完整页(侧栏高亮该项)
|
|
||||||
pages/
|
|
||||||
<相对路径>.html # 每个 .mq.md 一页;路径中的 `/` 保留为子目录
|
|
||||||
# 例:structure/hello.mq.md → pages/structure/hello.mq.md.html
|
|
||||||
```
|
|
||||||
|
|
||||||
- 页内链接一律**相对路径**,可用任意静态服务器或 `file://`(同目录结构下)打开。
|
|
||||||
- 用户文档推荐流程:`marqdo view output public -o public`,将生成物发布到 `gh-pages`(见 [user-site.md](user-site.md))。
|
|
||||||
- **执行权限**:与 `marqdo run` 一致(导入即用);view/导出仅对 `exit`/`sleep` 做软化,避免拖垮进程。详见 [stdlib-modules.md](stdlib-modules.md) §6。
|
|
||||||
- 金样例浏览仍可用:`marqdo view output tests -o /tmp/mq-tests`(含 errors,勿当对外用户站)。
|
|
||||||
- 渲染逻辑与实时 `view` **共用**同一套 HTML 构件(结构 / 执行 / 源码),禁止两套皮肤分叉。
|
|
||||||
|
|
||||||
示例:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
marqdo view output public -o public
|
|
||||||
marqdo view output tests/structure/hello.mq.md -o /tmp/hello-doc
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 4. 信息架构
|
|
||||||
|
|
||||||
侧栏文件索引 + 主区:结构(AST+注释;旁侧函数大纲可搜索)· 执行 · 源码。表达式为表面语法。
|
|
||||||
**断点调试**不在 view 内,见 [`marqdo debug`](view-debug.md)。
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 5. HTTP(实时模式)
|
|
||||||
|
|
||||||
| 方法 | 路径 | 含义 |
|
|
||||||
|------|------|------|
|
|
||||||
| `GET` | `/` | 默认打开第一个 `.mq.md`(无文件时为空提示) |
|
|
||||||
| `GET` | `/file?path=…` | 单文件页 |
|
|
||||||
| `GET` | `/api/tree` | JSON 树(可选) |
|
|
||||||
|
|
||||||
根目录锁死;拒绝 `..` 逃逸。
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 6. 验收
|
|
||||||
|
|
||||||
1. 实时 `view`:HIG 风极简、无外链字体、结构与执行正确;打开目录即见首个文件;函数大纲可搜索跳转。
|
|
||||||
2. `view output public -o public`(或临时目录)生成可点的 `index.html`(首文件)与各 `pages/…`。
|
|
||||||
3. 静态页中执行区与 `marqdo run` 一致(未加 `--no-exec` 时);失败诊断路径无 `\\?\`。
|
|
||||||
4. 冷启动无明显外网依赖。
|
|
||||||
5. 调试用 `marqdo debug`(默认端口 7430),与 view 页面分离。
|
|
||||||
@@ -1,31 +0,0 @@
|
|||||||
# VS Code 扩展(分支指针)
|
|
||||||
|
|
||||||
| | |
|
|
||||||
|---|---|
|
|
||||||
| 状态 | **已定分支模型** |
|
|
||||||
| 日期 | 2026-08-05 |
|
|
||||||
| 代码分支 | **`vscode-extension`**(同仓库) |
|
|
||||||
| 目录 | 工作区 `vscode-extension/`(仅在该分支跟踪;**`main` 忽略**) |
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 分工(类比 `public` / `gh-pages`)
|
|
||||||
|
|
||||||
| 分支 | 内容 |
|
|
||||||
|------|------|
|
|
||||||
| `main` | Marqdo 语言 / CLI / `public/*.mq.md` 源;**不**存放扩展实现 |
|
|
||||||
| `vscode-extension` | VS Code 扩展源码、开发规范、TextMate 语法 |
|
|
||||||
| `gh-pages` | 用户站生成 HTML |
|
|
||||||
|
|
||||||
```bash
|
|
||||||
git checkout vscode-extension
|
|
||||||
cd vscode-extension && npm install
|
|
||||||
```
|
|
||||||
|
|
||||||
规范入口(在该分支上阅读):
|
|
||||||
|
|
||||||
- `vscode-extension/README.md` — 目标与目录
|
|
||||||
- `vscode-extension/DEVELOPMENT.md` — 日常流程
|
|
||||||
- `vscode-extension/ARCHITECTURE.md` — 与 CLI 边界
|
|
||||||
|
|
||||||
扩展是 CLI 的薄宿主;语法真相仍是 [markdown-mapping.md](markdown-mapping.md)。
|
|
||||||
@@ -1,87 +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 tests/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` | 诊断 |
|
|
||||||
| `tests/` | 金样例 + 集成测试(`structure` / `keywords` / `errors`) |
|
|
||||||
| `public/` | 用户可执行文档(无 errors) |
|
|
||||||
| `spike/` | 旧 Python 风险探测,非运行时依赖 |
|
|
||||||
| `doc/` | 设计与路线图 |
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 5. 下一里程碑
|
|
||||||
|
|
||||||
见 [interpreter.md](roadmap/interpreter.md):M1 词法·行分类与最小 AST。
|
|
||||||
@@ -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 的终点。**
|
|
||||||
@@ -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(必须先完成,跑通全部 tests 金样例)
|
|
||||||
│ 或 │
|
|
||||||
│ 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`
|
|
||||||
- 诊断:带文件名、行号、列号
|
|
||||||
- 测试:每个 `tests/{structure,keywords}/*.mq.md` 有期望 stdout(金样例);CI 可跑
|
|
||||||
|
|
||||||
### Phase I — 可运行的语言核心(树遍历)
|
|
||||||
|
|
||||||
必须全部为真实现,禁止「正则特判 hello」:
|
|
||||||
|
|
||||||
1. **词法 / 行分类**:注释与代码严格分离。
|
|
||||||
2. **语法 → AST**:函数、形参、`*` 语句、`**` 返回、`>` 调用、`+` 分支、`-` 循环、表格集合、绑定与 `==`。
|
|
||||||
3. **语义**:提升、嵌套作用域、`##` 私有、frontmatter 导入公有顶层。
|
|
||||||
4. **运行时**:环境、调用栈、值(文/数/表/记录)、内置 `print`。
|
|
||||||
5. **验收**:`tests/structure/*` 与 `tests/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
|
|
||||||
src/lex/ parse/ ast/ sema/ interp/ bytecode/ runtime/
|
|
||||||
tests/ # gold.rs + structure|keywords|errors 夹具
|
|
||||||
public/ # 用户可执行文档
|
|
||||||
doc/ # 设计文稿
|
|
||||||
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 tests/structure/nested-call.mq.md
|
|
||||||
# 或
|
|
||||||
marqdo run tests/structure/import/main.mq.md
|
|
||||||
```
|
|
||||||
|
|
||||||
输出与金样例一致;错误带位置;新增语法必须加金样例与单测。这才是「一门解释型语言」的最低合格线。
|
|
||||||
@@ -1,220 +0,0 @@
|
|||||||
# 下一阶段:从玩具到可用语言
|
|
||||||
|
|
||||||
| | |
|
|
||||||
|---|---|
|
|
||||||
| 状态 | **进行中**(P3-D1–D3 live view 断点 v1) |
|
|
||||||
| 日期 | 2026-08-05 |
|
|
||||||
| 目标 | 交互 I/O、可信诊断、可生长标准库;view 渐进成为调试宿主 |
|
|
||||||
| 相关 | [interpreter.md](interpreter.md) · [keywords.md](../design/keywords.md) · [pipeline-debug.md](../design/pipeline-debug.md) · [view.md](../design/view.md) · [view-debug.md](../design/view-debug.md) |
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 0. 现状快照(决策依据)
|
|
||||||
|
|
||||||
| 能力 | 现状 | 结论 |
|
|
||||||
|------|------|------|
|
|
||||||
| **`print`** | 树遍历 + 字节码均可用 | 够用 |
|
|
||||||
| **`input`** | CLI 双后端 + `--stdin-file`;frontmatter `stdin:`/`输入:`;live view 表单覆盖;无预置时 capture 提示补线 | **P1a + P1b 完成** |
|
|
||||||
| **诊断** | 语句级 `path:line:col: message`;字节码指令带 `spans`;errors 金样例双后端断言位置 | **P0 完成** |
|
|
||||||
| **view** | 结构 + 执行 + 源码 + 函数大纲/搜索;无断点 | 文档浏览器 |
|
|
||||||
| **debug** | 独立 `marqdo debug`:断点 / 单步 / locals(树遍历) | **P3-D3 v1** |
|
|
||||||
| **标准库** | S0–S3 完成;本波扩展 = 文件/系统/时间/JSON/网络([stdlib-modules.md](../design/stdlib-modules.md));数学/外联暂缓 | **P2 完成;五库扩展设计中** |
|
|
||||||
| **模块** | `> file.mq.md` 顶层函数合并,无命名空间 | 短期可继续用 |
|
|
||||||
|
|
||||||
用户点名的三件事都对,但**不能并行硬开**:断点调试依赖「可信位置 + 可暂停执行」;标准库依赖稳定运行时与 I/O;`input` 在 CLI 与 view 是两条路径。
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 1. 轻重缓急(总序)
|
|
||||||
|
|
||||||
```text
|
|
||||||
P0 诊断加固(短、撬动后续一切)
|
|
||||||
P1 输入补完(先 CLI,再 view)
|
|
||||||
P2 最小标准库(内置 + 可选 .mq.md 库)
|
|
||||||
P3 view 调试(断点 / 单步)—— 在 P0 之后分期,勿一上来做 DAP
|
|
||||||
```
|
|
||||||
|
|
||||||
| 优先级 | 主题 | 为何此刻 | 不做的代价 |
|
|
||||||
|--------|------|----------|------------|
|
|
||||||
| **P0** | 诊断完备度 | 便宜;给金样例、字节码、调试打地基 | 断点停错行;双后端错误体验分裂 |
|
|
||||||
| **P1** | `input` | 「真语言」最低交互面;已有半截实现 | 只能写纯计算/打印 demo |
|
|
||||||
| **P2** | 标准库 | 无库则用户无法写稍大程序 | 人人自造轮子、示例膨胀 |
|
|
||||||
| **P3** | 前端调试 | 差异化(文档即调试);成本最高 | view 仍停留在「跑完看 stdout」 |
|
|
||||||
|
|
||||||
**原则:** 先让 **CLI 树遍历**成为完备参考实现;字节码跟进同语义;view 只接「已有事件/钩子」,不单独发明第二套语义。
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 2. P0 — 诊断与错误模型(约 3–7 天)
|
|
||||||
|
|
||||||
### 目标
|
|
||||||
|
|
||||||
所有用户可见失败统一为:
|
|
||||||
|
|
||||||
```text
|
|
||||||
path:line:col: message
|
|
||||||
```
|
|
||||||
|
|
||||||
树遍历与字节码**同文案、同位置粒度(至少语句级)**;金样例断言位置而不只子串。
|
|
||||||
|
|
||||||
### 工作项
|
|
||||||
|
|
||||||
1. **统一出口**
|
|
||||||
- 解析侧尽量只产 `Diagnostic`(减少裸 `bail!("7:1: …")`)。
|
|
||||||
- 字节码编译/VM:错误携带 `Span`(或指令 → 源行映射)。
|
|
||||||
2. **位置粒度**
|
|
||||||
- 短期:保持「语句起点」亦可;中期:为 `Expr`/`CallExpr` 补 `span`,让「未定义名」落在标识符上。
|
|
||||||
3. **金样例**
|
|
||||||
- `tests/errors/*`:断言完整 `path:line:col` 前缀(或相对路径规范化后的形式)。
|
|
||||||
- 补:类型错误、除零、循环条件、capture 下 `input` 等。
|
|
||||||
4. **文档**
|
|
||||||
- 更新 [pipeline-debug.md](../design/pipeline-debug.md):错误码/严重级别可列为 P0.5(可选 `E0001` 一类,不阻塞)。
|
|
||||||
|
|
||||||
### 完成定义
|
|
||||||
|
|
||||||
- `cargo test`:errors 金样例含位置。
|
|
||||||
- 同一 `.mq.md` 在 `--backend tree|bytecode` 下诊断一致(允许实现细节差异写进豁免表)。
|
|
||||||
- view 执行失败区仍可读,路径无 `\\?\`。
|
|
||||||
|
|
||||||
### 刻意不做
|
|
||||||
|
|
||||||
- IDE DAP、完整堆栈 UI、sourcemap 可视化编辑器。
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 3. P1 — 输入(约 1–2 周)
|
|
||||||
|
|
||||||
分两轨:**CLI 必须先绿**;**view 交互后做**。
|
|
||||||
|
|
||||||
### P1a — CLI 完备(高优先级)
|
|
||||||
|
|
||||||
| 项 | 说明 |
|
|
||||||
|----|------|
|
|
||||||
| 树遍历 | 已实现 stdin;补 `tests/keywords/input.mq.md`(用管道喂入) |
|
|
||||||
| 字节码 | 增加 `Op::Input`(或等价 host call);与树同语义;capture 下同样拒绝或改走注入 API |
|
|
||||||
| 文档/用户站 | `public/keywords/input.mq.md`;说明「view 默认无交互 stdin」 |
|
|
||||||
|
|
||||||
完成定义:`echo Alice | marqdo run …` 与字节码后端输出一致;金样例稳定。
|
|
||||||
|
|
||||||
### P1b — view / 静态站中的输入(中优先级,接在 P1a 后)
|
|
||||||
|
|
||||||
当前 `run_file_capture` **不能**接真实 stdin——这是设计,不是偶然 bug。
|
|
||||||
|
|
||||||
推荐路径(由易到难):
|
|
||||||
|
|
||||||
1. **脚本化注入(无 UI)**
|
|
||||||
- `marqdo run --stdin-file answers.txt` 或 frontmatter/`---` 旁测数据。
|
|
||||||
- view:执行前提供「预置输入行」文本框,一次性灌入队列。
|
|
||||||
2. **实时交互(live view)**
|
|
||||||
- 执行到 `input` → 暂停 → HTTP/WS 返回 prompt → 用户提交一行 → 继续。
|
|
||||||
- 依赖 P3 的「可暂停执行」钩子;可与断点共用会话模型。
|
|
||||||
3. **静态 `view output`**
|
|
||||||
- 无服务器则只支持预置输入或跳过并标明 `input skipped`。
|
|
||||||
|
|
||||||
完成定义:live `marqdo view` 下至少一个带 `input` 的示例可点按跑通;静态导出行为有文档。
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 4. P2 — 标准库(约 2–3 周,可与 P1b/P3 前半重叠)
|
|
||||||
|
|
||||||
### 分层
|
|
||||||
|
|
||||||
```text
|
|
||||||
L0 内置函数(解释器内) len / str / int / float? / type?
|
|
||||||
L1 标准库模块(.mq.md) 文本、表/集合小工具;官方路径如 lib/ 或 std/
|
|
||||||
L2 生态约定 catalog 收录;用户站专章
|
|
||||||
```
|
|
||||||
|
|
||||||
### 建议落地顺序
|
|
||||||
|
|
||||||
| 迭代 | 内容 | 依据 |
|
|
||||||
|------|------|------|
|
|
||||||
| **S0** | `len`(文本/表)、`str`、`int` | keywords.md 已列候选;字节码已有闲置 `Op::Len` 可接线 |
|
|
||||||
| **S1** | 表工具:取列、行数;字符串 trim/split(先内置或纯 mq 实现二选一) | 文档型语言高频 |
|
|
||||||
| **S2** | 官方 `lib/` 或 `std/` + 导入约定(仍可用 frontmatter;或日后 `> std/text.mq.md`) | 可生长而不破现有导入 |
|
|
||||||
| **S3** | 错误类型约定(如非法 `int` 文本 → 诊断) | 依赖 P0 |
|
|
||||||
|
|
||||||
### 完成定义(S0)
|
|
||||||
|
|
||||||
- 金样例 + 双后端;`public/` 有对应介绍页。
|
|
||||||
- 不引入 `if`/`while` 英文关键字(控制流仍归 Markdown 标记)。
|
|
||||||
|
|
||||||
### 刻意不做(本阶段)
|
|
||||||
|
|
||||||
- 完整面向对象、包管理器、异步 I/O、HTTP 客户端(可列远期)。
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 5. P3 — 前端成为调试机构(约 3–6 周,分里程碑)
|
|
||||||
|
|
||||||
**不要从 DAP/VS Code 插件开干。** view 已有 Structure / Source / Execution,是天然宿主。
|
|
||||||
|
|
||||||
```mermaid
|
|
||||||
flowchart LR
|
|
||||||
P0loc[P0 可信位置] --> Pause[语句边界暂停钩子]
|
|
||||||
Pause --> Sess[调试会话 API]
|
|
||||||
Sess --> UI[view 断点与单步 UI]
|
|
||||||
UI --> DAP[可选 DAP 适配]
|
|
||||||
```
|
|
||||||
|
|
||||||
| 里程碑 | 交付 | 依赖 |
|
|
||||||
|--------|------|------|
|
|
||||||
| **D0** | 语句级源映射(树优先;字节码指令→行) | P0 |
|
|
||||||
| **D1** | 运行时钩子:进入语句前可 pause;`--trace-eval` 结构化事件(JSON 行) | D0 |
|
|
||||||
| **D2** | 进程内调试会话:设/清断点、continue、step over(先树遍历) | D1 |
|
|
||||||
| **D3** | **view debug 模式**:源码行点击断点;高亮当前行;侧栏 locals/栈;与文档模式切换 | D2 + 少量 JS 或服务端推进 |
|
|
||||||
| **D4** | 与 P1b 合流:`input` 暂停复用同一会话 | P1b |
|
|
||||||
| **D5**(可选) | DAP 薄适配,供外部 IDE | D2 稳定后 |
|
|
||||||
|
|
||||||
### 完成定义(D3 即「可用调试」)
|
|
||||||
|
|
||||||
- 用户能在 `marqdo view` 对某 `.mq.md` 设断点、单步、看变量。
|
|
||||||
- 文档站默认模式不变(一次执行);debug 为显式开关。
|
|
||||||
- 断点命中行与 P0 诊断行一致(允许文档说明「语句起点」语义)。
|
|
||||||
|
|
||||||
### 风险与边界
|
|
||||||
|
|
||||||
- 静态 `gh-pages` **无法**真断点(无常驻 VM);调试仅 **live view**(或未来 WASM 解释器)。
|
|
||||||
- 字节码调试可晚于树遍历一个迭代。
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 6. 推荐排期(可执行流程)
|
|
||||||
|
|
||||||
按「每段都可合并、可演示」切周,避免大爆炸:
|
|
||||||
|
|
||||||
| 周序 | 主题 | 可合并交付 |
|
|
||||||
|------|------|------------|
|
|
||||||
| **W1** | P0 诊断统一 + errors 金样例加固 | 双后端错误位置一致 |
|
|
||||||
| **W2** | P1a `input` 字节码 + 管道金样例 + 用户文档 | CLI 交互闭环 |
|
|
||||||
| **W3** | P2-S0 `len`/`str`/`int` + 样例 | 「有点像语言」的第一批库 |
|
|
||||||
| **W4** | P1b 预置输入(view 文本框 / `--stdin-file`) | view 可跑含 input 的 demo |
|
|
||||||
| **W5–W6** | P3-D0–D2 暂停与会话 | 无 UI 也能用 API/CLI 单步 |
|
|
||||||
| **W7–W8** | P3-D3 view 断点 UI + D4 与 input 暂停 | **调试机构**第一版 |
|
|
||||||
| **并行/随后** | P2-S1/S2 扩库;P3-D5 DAP | 按反馈加 |
|
|
||||||
|
|
||||||
若人力紧:**砍掉顺序为 D5 → S2 花活 → 字节码调试**;**不可砍:P0、P1a、P2-S0、D3 之前的 D0–D2。**
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 7. 验收总表(「真正可用」最低线)
|
|
||||||
|
|
||||||
1. **I/O**:CLI 上 `print`/`input` 双后端一致;view 至少支持预置或交互输入之一。
|
|
||||||
2. **错误**:失败必有稳定位置;常见错误有金样例;用户站不靠「瞎猜 stderr」。
|
|
||||||
3. **库**:至少 `len`/`str`/`int` 可用并有文档。
|
|
||||||
4. **调试**:live view 可断点 + 单步 + 看当前绑定(树遍历即可宣称 v1)。
|
|
||||||
5. **不破坏**:现有 `tests/` 金样例与 `public/` 用户站回归绿。
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 8. 文档与工程动作(开工时)
|
|
||||||
|
|
||||||
1. 本文件定为「下一阶段宪法」;开工后把各 P 拆到 `doc/design/` 子设计(`input-interactive.md`、`stdlib.md`、`view-debug.md`)。
|
|
||||||
2. 每个里程碑:金样例 → 实现 → `public/` 更新 →(若行为用户可见)再发版 / 刷 `gh-pages`。
|
|
||||||
3. 版本建议:P1a+P0 可打 `v0.0.4`;P2-S0 打 `v0.0.5`;P3-D3 打 `v0.1.0`(「可用调试」语义升级)。
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 9. 一句话路线
|
|
||||||
|
|
||||||
**先把错误说准、把输入在 CLI 做完,再长出最小标准库;最后把现有 view 升级成可暂停的调试宿主——而不是先做 IDE 插件或大而全标准库。**
|
|
||||||
@@ -1,25 +0,0 @@
|
|||||||
---
|
|
||||||
title: lib/foreign
|
|
||||||
description: Run bound code fences and inline sources via local interpreters
|
|
||||||
---
|
|
||||||
|
|
||||||
# set_cmd
|
|
||||||
- lang
|
|
||||||
- cmd
|
|
||||||
|
|
||||||
**> host_foreign_set_cmd lang=`lang` cmd=`cmd`**
|
|
||||||
|
|
||||||
# run
|
|
||||||
- code
|
|
||||||
|
|
||||||
**> host_foreign_run code=`code`**
|
|
||||||
|
|
||||||
# run_lang
|
|
||||||
- lang
|
|
||||||
- source
|
|
||||||
|
|
||||||
**> host_foreign_run_lang lang=`lang` source=`source`**
|
|
||||||
|
|
||||||
# langs
|
|
||||||
|
|
||||||
**> host_foreign_langs**
|
|
||||||
@@ -1,41 +0,0 @@
|
|||||||
---
|
|
||||||
title: lib/fs
|
|
||||||
description: English filesystem wrappers
|
|
||||||
---
|
|
||||||
|
|
||||||
# read_text
|
|
||||||
- path
|
|
||||||
|
|
||||||
**> host_read_text path=`path`**
|
|
||||||
|
|
||||||
# write_text
|
|
||||||
- path
|
|
||||||
- text
|
|
||||||
|
|
||||||
**> host_write_text path=`path` text=`text`**
|
|
||||||
|
|
||||||
# append_text
|
|
||||||
- path
|
|
||||||
- text
|
|
||||||
|
|
||||||
**> host_append_text path=`path` text=`text`**
|
|
||||||
|
|
||||||
# exists
|
|
||||||
- path
|
|
||||||
|
|
||||||
**> host_exists path=`path`**
|
|
||||||
|
|
||||||
# list_dir
|
|
||||||
- path
|
|
||||||
|
|
||||||
**> host_list_dir path=`path`**
|
|
||||||
|
|
||||||
# make_dir
|
|
||||||
- path
|
|
||||||
|
|
||||||
**> host_make_dir path=`path`**
|
|
||||||
|
|
||||||
# remove
|
|
||||||
- path
|
|
||||||
|
|
||||||
**> host_remove path=`path`**
|
|
||||||
@@ -1,25 +0,0 @@
|
|||||||
---
|
|
||||||
title: lib/json
|
|
||||||
description: JSON parse/stringify (shared EN/ZH import)
|
|
||||||
---
|
|
||||||
|
|
||||||
# parse
|
|
||||||
- text
|
|
||||||
|
|
||||||
**> host_json_parse text=`text`**
|
|
||||||
|
|
||||||
# stringify
|
|
||||||
- value
|
|
||||||
|
|
||||||
**> host_json_stringify value=`value`**
|
|
||||||
|
|
||||||
# get
|
|
||||||
- value
|
|
||||||
- key
|
|
||||||
|
|
||||||
**> host_json_get value=`value` key=`key`**
|
|
||||||
|
|
||||||
# keys
|
|
||||||
- value
|
|
||||||
|
|
||||||
**> host_json_keys value=`value`**
|
|
||||||
-200
@@ -1,200 +0,0 @@
|
|||||||
---
|
|
||||||
title: lib/math
|
|
||||||
description: High-school math — num, random, formula, plot
|
|
||||||
---
|
|
||||||
|
|
||||||
# pi
|
|
||||||
|
|
||||||
**> host_pi**
|
|
||||||
|
|
||||||
# e
|
|
||||||
|
|
||||||
**> host_e**
|
|
||||||
|
|
||||||
# num
|
|
||||||
- value
|
|
||||||
|
|
||||||
**> host_num value=`value`**
|
|
||||||
|
|
||||||
# add
|
|
||||||
- a
|
|
||||||
- b
|
|
||||||
|
|
||||||
**> host_math_add a=`a` b=`b`**
|
|
||||||
|
|
||||||
# sub
|
|
||||||
- a
|
|
||||||
- b
|
|
||||||
|
|
||||||
**> host_math_sub a=`a` b=`b`**
|
|
||||||
|
|
||||||
# mul
|
|
||||||
- a
|
|
||||||
- b
|
|
||||||
|
|
||||||
**> host_math_mul a=`a` b=`b`**
|
|
||||||
|
|
||||||
# div
|
|
||||||
- a
|
|
||||||
- b
|
|
||||||
|
|
||||||
**> host_math_div a=`a` b=`b`**
|
|
||||||
|
|
||||||
# pow
|
|
||||||
- a
|
|
||||||
- b
|
|
||||||
|
|
||||||
**> host_math_pow a=`a` b=`b`**
|
|
||||||
|
|
||||||
# neg
|
|
||||||
- value
|
|
||||||
|
|
||||||
**> host_math_neg value=`value`**
|
|
||||||
|
|
||||||
# sin
|
|
||||||
- value
|
|
||||||
|
|
||||||
**> host_math_sin value=`value`**
|
|
||||||
|
|
||||||
# cos
|
|
||||||
- value
|
|
||||||
|
|
||||||
**> host_math_cos value=`value`**
|
|
||||||
|
|
||||||
# tan
|
|
||||||
- value
|
|
||||||
|
|
||||||
**> host_math_tan value=`value`**
|
|
||||||
|
|
||||||
# asin
|
|
||||||
- value
|
|
||||||
|
|
||||||
**> host_math_asin value=`value`**
|
|
||||||
|
|
||||||
# acos
|
|
||||||
- value
|
|
||||||
|
|
||||||
**> host_math_acos value=`value`**
|
|
||||||
|
|
||||||
# atan
|
|
||||||
- value
|
|
||||||
|
|
||||||
**> host_math_atan value=`value`**
|
|
||||||
|
|
||||||
# sqrt
|
|
||||||
- value
|
|
||||||
|
|
||||||
**> host_math_sqrt value=`value`**
|
|
||||||
|
|
||||||
# abs
|
|
||||||
- value
|
|
||||||
|
|
||||||
**> host_math_abs value=`value`**
|
|
||||||
|
|
||||||
# ln
|
|
||||||
- value
|
|
||||||
|
|
||||||
**> host_math_ln value=`value`**
|
|
||||||
|
|
||||||
# exp
|
|
||||||
- value
|
|
||||||
|
|
||||||
**> host_math_exp value=`value`**
|
|
||||||
|
|
||||||
# floor
|
|
||||||
- value
|
|
||||||
|
|
||||||
**> host_math_floor value=`value`**
|
|
||||||
|
|
||||||
# ceil
|
|
||||||
- value
|
|
||||||
|
|
||||||
**> host_math_ceil value=`value`**
|
|
||||||
|
|
||||||
# min
|
|
||||||
- a
|
|
||||||
- b
|
|
||||||
|
|
||||||
**> host_math_min a=`a` b=`b`**
|
|
||||||
|
|
||||||
# max
|
|
||||||
- a
|
|
||||||
- b
|
|
||||||
|
|
||||||
**> host_math_max a=`a` b=`b`**
|
|
||||||
|
|
||||||
# random
|
|
||||||
|
|
||||||
**> host_random**
|
|
||||||
|
|
||||||
# random_int
|
|
||||||
- min
|
|
||||||
- max
|
|
||||||
|
|
||||||
**> host_random_int min=`min` max=`max`**
|
|
||||||
|
|
||||||
# seed
|
|
||||||
- value
|
|
||||||
|
|
||||||
**> host_seed value=`value`**
|
|
||||||
|
|
||||||
# formula
|
|
||||||
- text
|
|
||||||
|
|
||||||
**> host_formula value=`text`**
|
|
||||||
|
|
||||||
# simplify
|
|
||||||
- formula
|
|
||||||
|
|
||||||
**> host_simplify value=`formula`**
|
|
||||||
|
|
||||||
# expand
|
|
||||||
- formula
|
|
||||||
|
|
||||||
**> host_expand value=`formula`**
|
|
||||||
|
|
||||||
# diff
|
|
||||||
- formula
|
|
||||||
- var
|
|
||||||
|
|
||||||
**> host_diff formula=`formula` var=`var`**
|
|
||||||
|
|
||||||
# subs
|
|
||||||
- formula
|
|
||||||
- var
|
|
||||||
- value
|
|
||||||
|
|
||||||
**> host_subs formula=`formula` var=`var` value=`value`**
|
|
||||||
|
|
||||||
# eval
|
|
||||||
- formula
|
|
||||||
- var
|
|
||||||
- value
|
|
||||||
|
|
||||||
**> host_eval formula=`formula` var=`var` value=`value`**
|
|
||||||
|
|
||||||
# solve
|
|
||||||
- formula
|
|
||||||
- var
|
|
||||||
|
|
||||||
**> host_solve formula=`formula` var=`var`**
|
|
||||||
|
|
||||||
# plot
|
|
||||||
- formula
|
|
||||||
- var
|
|
||||||
- min
|
|
||||||
- max
|
|
||||||
|
|
||||||
**> host_plot formula=`formula` var=`var` min=`min` max=`max`**
|
|
||||||
|
|
||||||
# plot_points
|
|
||||||
- xs
|
|
||||||
- ys
|
|
||||||
|
|
||||||
**> host_plot_points xs=`xs` ys=`ys`**
|
|
||||||
|
|
||||||
# plot_conic
|
|
||||||
- kind
|
|
||||||
- a
|
|
||||||
|
|
||||||
**> host_plot_conic kind=`kind` a=`a`**
|
|
||||||
@@ -1,20 +0,0 @@
|
|||||||
---
|
|
||||||
title: lib/net
|
|
||||||
description: English minimal HTTP wrappers
|
|
||||||
---
|
|
||||||
|
|
||||||
# http_get
|
|
||||||
- url
|
|
||||||
|
|
||||||
**> host_http_get url=`url`**
|
|
||||||
|
|
||||||
# http_post
|
|
||||||
- url
|
|
||||||
- body
|
|
||||||
|
|
||||||
**> host_http_post url=`url` body=`body`**
|
|
||||||
|
|
||||||
# url_encode
|
|
||||||
- text
|
|
||||||
|
|
||||||
**> host_url_encode text=`text`**
|
|
||||||
@@ -1,33 +0,0 @@
|
|||||||
---
|
|
||||||
title: lib/sys
|
|
||||||
description: English system wrappers
|
|
||||||
---
|
|
||||||
|
|
||||||
# env_get
|
|
||||||
- name
|
|
||||||
|
|
||||||
**> host_env_get name=`name`**
|
|
||||||
|
|
||||||
# env_set
|
|
||||||
- name
|
|
||||||
- value
|
|
||||||
|
|
||||||
**> host_env_set name=`name` value=`value`**
|
|
||||||
|
|
||||||
# args
|
|
||||||
|
|
||||||
**> host_args**
|
|
||||||
|
|
||||||
# cwd
|
|
||||||
|
|
||||||
**> host_cwd**
|
|
||||||
|
|
||||||
# exit
|
|
||||||
- code
|
|
||||||
|
|
||||||
**> host_exit code=`code`**
|
|
||||||
|
|
||||||
# exec
|
|
||||||
- cmd
|
|
||||||
|
|
||||||
**> host_exec cmd=`cmd`**
|
|
||||||
@@ -1,15 +0,0 @@
|
|||||||
---
|
|
||||||
title: lib/table
|
|
||||||
description: English table helpers over len / at
|
|
||||||
---
|
|
||||||
|
|
||||||
# rows
|
|
||||||
- xs
|
|
||||||
|
|
||||||
**> len `xs`**
|
|
||||||
|
|
||||||
# row_at
|
|
||||||
- xs
|
|
||||||
- i
|
|
||||||
|
|
||||||
**> at value=`xs` index=`i`**
|
|
||||||
@@ -1,21 +0,0 @@
|
|||||||
---
|
|
||||||
title: lib/text
|
|
||||||
description: English text helpers over trim / split / join
|
|
||||||
---
|
|
||||||
|
|
||||||
# str_trim
|
|
||||||
- s
|
|
||||||
|
|
||||||
**> trim `s`**
|
|
||||||
|
|
||||||
# str_split
|
|
||||||
- s
|
|
||||||
- sep
|
|
||||||
|
|
||||||
**> split value=`s` sep=`sep`**
|
|
||||||
|
|
||||||
# str_join
|
|
||||||
- xs
|
|
||||||
- sep
|
|
||||||
|
|
||||||
**> join value=`xs` sep=`sep`**
|
|
||||||
@@ -1,29 +0,0 @@
|
|||||||
---
|
|
||||||
title: lib/time
|
|
||||||
description: English time wrappers
|
|
||||||
---
|
|
||||||
|
|
||||||
# now_unix
|
|
||||||
|
|
||||||
**> host_now_unix**
|
|
||||||
|
|
||||||
# now_ms
|
|
||||||
|
|
||||||
**> host_now_ms**
|
|
||||||
|
|
||||||
# format
|
|
||||||
- unix
|
|
||||||
- pattern
|
|
||||||
|
|
||||||
**> host_format_time unix=`unix` pattern=`pattern`**
|
|
||||||
|
|
||||||
# sleep_ms
|
|
||||||
- ms
|
|
||||||
|
|
||||||
**> host_sleep_ms ms=`ms`**
|
|
||||||
|
|
||||||
# parse
|
|
||||||
- text
|
|
||||||
- pattern
|
|
||||||
|
|
||||||
**> host_parse_time text=`text` pattern=`pattern`**
|
|
||||||
@@ -1,25 +0,0 @@
|
|||||||
---
|
|
||||||
title: lib/外联
|
|
||||||
description: 通过本机解释器运行绑定的代码围栏与内联源码
|
|
||||||
---
|
|
||||||
|
|
||||||
# 设置命令
|
|
||||||
- 语言
|
|
||||||
- 命令
|
|
||||||
|
|
||||||
**> host_foreign_set_cmd lang=`语言` cmd=`命令`**
|
|
||||||
|
|
||||||
# 运行
|
|
||||||
- 代码
|
|
||||||
|
|
||||||
**> host_foreign_run code=`代码`**
|
|
||||||
|
|
||||||
# 按语言运行
|
|
||||||
- 语言
|
|
||||||
- 源码
|
|
||||||
|
|
||||||
**> host_foreign_run_lang lang=`语言` source=`源码`**
|
|
||||||
|
|
||||||
# 语言表
|
|
||||||
|
|
||||||
**> host_foreign_langs**
|
|
||||||
-200
@@ -1,200 +0,0 @@
|
|||||||
---
|
|
||||||
title: lib/数学
|
|
||||||
description: 高中数学 — 数值、随机、公式、作图
|
|
||||||
---
|
|
||||||
|
|
||||||
# 圆周率
|
|
||||||
|
|
||||||
**> host_pi**
|
|
||||||
|
|
||||||
# 自然底数
|
|
||||||
|
|
||||||
**> host_e**
|
|
||||||
|
|
||||||
# 数
|
|
||||||
- value
|
|
||||||
|
|
||||||
**> host_num value=`value`**
|
|
||||||
|
|
||||||
# 加
|
|
||||||
- a
|
|
||||||
- b
|
|
||||||
|
|
||||||
**> host_math_add a=`a` b=`b`**
|
|
||||||
|
|
||||||
# 减
|
|
||||||
- a
|
|
||||||
- b
|
|
||||||
|
|
||||||
**> host_math_sub a=`a` b=`b`**
|
|
||||||
|
|
||||||
# 乘
|
|
||||||
- a
|
|
||||||
- b
|
|
||||||
|
|
||||||
**> host_math_mul a=`a` b=`b`**
|
|
||||||
|
|
||||||
# 除
|
|
||||||
- a
|
|
||||||
- b
|
|
||||||
|
|
||||||
**> host_math_div a=`a` b=`b`**
|
|
||||||
|
|
||||||
# 幂
|
|
||||||
- a
|
|
||||||
- b
|
|
||||||
|
|
||||||
**> host_math_pow a=`a` b=`b`**
|
|
||||||
|
|
||||||
# 负
|
|
||||||
- value
|
|
||||||
|
|
||||||
**> host_math_neg value=`value`**
|
|
||||||
|
|
||||||
# 正弦
|
|
||||||
- value
|
|
||||||
|
|
||||||
**> host_math_sin value=`value`**
|
|
||||||
|
|
||||||
# 余弦
|
|
||||||
- value
|
|
||||||
|
|
||||||
**> host_math_cos value=`value`**
|
|
||||||
|
|
||||||
# 正切
|
|
||||||
- value
|
|
||||||
|
|
||||||
**> host_math_tan value=`value`**
|
|
||||||
|
|
||||||
# 反正弦
|
|
||||||
- value
|
|
||||||
|
|
||||||
**> host_math_asin value=`value`**
|
|
||||||
|
|
||||||
# 反余弦
|
|
||||||
- value
|
|
||||||
|
|
||||||
**> host_math_acos value=`value`**
|
|
||||||
|
|
||||||
# 反正切
|
|
||||||
- value
|
|
||||||
|
|
||||||
**> host_math_atan value=`value`**
|
|
||||||
|
|
||||||
# 平方根
|
|
||||||
- value
|
|
||||||
|
|
||||||
**> host_math_sqrt value=`value`**
|
|
||||||
|
|
||||||
# 绝对值
|
|
||||||
- value
|
|
||||||
|
|
||||||
**> host_math_abs value=`value`**
|
|
||||||
|
|
||||||
# 对数
|
|
||||||
- value
|
|
||||||
|
|
||||||
**> host_math_ln value=`value`**
|
|
||||||
|
|
||||||
# 指数
|
|
||||||
- value
|
|
||||||
|
|
||||||
**> host_math_exp value=`value`**
|
|
||||||
|
|
||||||
# 向下取整
|
|
||||||
- value
|
|
||||||
|
|
||||||
**> host_math_floor value=`value`**
|
|
||||||
|
|
||||||
# 向上取整
|
|
||||||
- value
|
|
||||||
|
|
||||||
**> host_math_ceil value=`value`**
|
|
||||||
|
|
||||||
# 最小
|
|
||||||
- a
|
|
||||||
- b
|
|
||||||
|
|
||||||
**> host_math_min a=`a` b=`b`**
|
|
||||||
|
|
||||||
# 最大
|
|
||||||
- a
|
|
||||||
- b
|
|
||||||
|
|
||||||
**> host_math_max a=`a` b=`b`**
|
|
||||||
|
|
||||||
# 随机
|
|
||||||
|
|
||||||
**> host_random**
|
|
||||||
|
|
||||||
# 随机整数
|
|
||||||
- min
|
|
||||||
- max
|
|
||||||
|
|
||||||
**> host_random_int min=`min` max=`max`**
|
|
||||||
|
|
||||||
# 设种子
|
|
||||||
- value
|
|
||||||
|
|
||||||
**> host_seed value=`value`**
|
|
||||||
|
|
||||||
# 公式
|
|
||||||
- text
|
|
||||||
|
|
||||||
**> host_formula value=`text`**
|
|
||||||
|
|
||||||
# 化简
|
|
||||||
- formula
|
|
||||||
|
|
||||||
**> host_simplify value=`formula`**
|
|
||||||
|
|
||||||
# 展开
|
|
||||||
- formula
|
|
||||||
|
|
||||||
**> host_expand value=`formula`**
|
|
||||||
|
|
||||||
# 求导
|
|
||||||
- formula
|
|
||||||
- var
|
|
||||||
|
|
||||||
**> host_diff formula=`formula` var=`var`**
|
|
||||||
|
|
||||||
# 代入
|
|
||||||
- formula
|
|
||||||
- var
|
|
||||||
- value
|
|
||||||
|
|
||||||
**> host_subs formula=`formula` var=`var` value=`value`**
|
|
||||||
|
|
||||||
# 求值
|
|
||||||
- formula
|
|
||||||
- var
|
|
||||||
- value
|
|
||||||
|
|
||||||
**> host_eval formula=`formula` var=`var` value=`value`**
|
|
||||||
|
|
||||||
# 求解
|
|
||||||
- formula
|
|
||||||
- var
|
|
||||||
|
|
||||||
**> host_solve formula=`formula` var=`var`**
|
|
||||||
|
|
||||||
# 绘图
|
|
||||||
- formula
|
|
||||||
- var
|
|
||||||
- min
|
|
||||||
- max
|
|
||||||
|
|
||||||
**> host_plot formula=`formula` var=`var` min=`min` max=`max`**
|
|
||||||
|
|
||||||
# 绘点列
|
|
||||||
- xs
|
|
||||||
- ys
|
|
||||||
|
|
||||||
**> host_plot_points xs=`xs` ys=`ys`**
|
|
||||||
|
|
||||||
# 绘圆锥
|
|
||||||
- kind
|
|
||||||
- a
|
|
||||||
|
|
||||||
**> host_plot_conic kind=`kind` a=`a`**
|
|
||||||
@@ -1,41 +0,0 @@
|
|||||||
---
|
|
||||||
title: lib/文件
|
|
||||||
description: 中文文件系统包装
|
|
||||||
---
|
|
||||||
|
|
||||||
# 读文本
|
|
||||||
- 路径
|
|
||||||
|
|
||||||
**> host_read_text path=`路径`**
|
|
||||||
|
|
||||||
# 写文本
|
|
||||||
- 路径
|
|
||||||
- 内容
|
|
||||||
|
|
||||||
**> host_write_text path=`路径` text=`内容`**
|
|
||||||
|
|
||||||
# 追加文本
|
|
||||||
- 路径
|
|
||||||
- 内容
|
|
||||||
|
|
||||||
**> host_append_text path=`路径` text=`内容`**
|
|
||||||
|
|
||||||
# 存在
|
|
||||||
- 路径
|
|
||||||
|
|
||||||
**> host_exists path=`路径`**
|
|
||||||
|
|
||||||
# 列目录
|
|
||||||
- 路径
|
|
||||||
|
|
||||||
**> host_list_dir path=`路径`**
|
|
||||||
|
|
||||||
# 建目录
|
|
||||||
- 路径
|
|
||||||
|
|
||||||
**> host_make_dir path=`路径`**
|
|
||||||
|
|
||||||
# 删除
|
|
||||||
- 路径
|
|
||||||
|
|
||||||
**> host_remove path=`路径`**
|
|
||||||
@@ -1,21 +0,0 @@
|
|||||||
---
|
|
||||||
title: lib/文本
|
|
||||||
description: 中文文本库:去空白 / 拆分 / 拼接
|
|
||||||
---
|
|
||||||
|
|
||||||
# 去空白
|
|
||||||
- s
|
|
||||||
|
|
||||||
**> trim `s`**
|
|
||||||
|
|
||||||
# 拆分
|
|
||||||
- s
|
|
||||||
- sep
|
|
||||||
|
|
||||||
**> split value=`s` sep=`sep`**
|
|
||||||
|
|
||||||
# 拼接
|
|
||||||
- xs
|
|
||||||
- sep
|
|
||||||
|
|
||||||
**> join value=`xs` sep=`sep`**
|
|
||||||
@@ -1,29 +0,0 @@
|
|||||||
---
|
|
||||||
title: lib/时间
|
|
||||||
description: 中文时间包装
|
|
||||||
---
|
|
||||||
|
|
||||||
# 此刻秒
|
|
||||||
|
|
||||||
**> host_now_unix**
|
|
||||||
|
|
||||||
# 此刻毫秒
|
|
||||||
|
|
||||||
**> host_now_ms**
|
|
||||||
|
|
||||||
# 格式化
|
|
||||||
- 秒
|
|
||||||
- 格式
|
|
||||||
|
|
||||||
**> host_format_time unix=`秒` pattern=`格式`**
|
|
||||||
|
|
||||||
# 睡眠毫秒
|
|
||||||
- 毫秒
|
|
||||||
|
|
||||||
**> host_sleep_ms ms=`毫秒`**
|
|
||||||
|
|
||||||
# 解析时间
|
|
||||||
- 内容
|
|
||||||
- 格式
|
|
||||||
|
|
||||||
**> host_parse_time text=`内容` pattern=`格式`**
|
|
||||||
@@ -1,33 +0,0 @@
|
|||||||
---
|
|
||||||
title: lib/系统
|
|
||||||
description: 中文系统包装
|
|
||||||
---
|
|
||||||
|
|
||||||
# 取环境
|
|
||||||
- 名
|
|
||||||
|
|
||||||
**> host_env_get name=`名`**
|
|
||||||
|
|
||||||
# 设环境
|
|
||||||
- 名
|
|
||||||
- 值
|
|
||||||
|
|
||||||
**> host_env_set name=`名` value=`值`**
|
|
||||||
|
|
||||||
# 参数表
|
|
||||||
|
|
||||||
**> host_args**
|
|
||||||
|
|
||||||
# 工作目录
|
|
||||||
|
|
||||||
**> host_cwd**
|
|
||||||
|
|
||||||
# 退出
|
|
||||||
- 码
|
|
||||||
|
|
||||||
**> host_exit code=`码`**
|
|
||||||
|
|
||||||
# 执行
|
|
||||||
- 命令
|
|
||||||
|
|
||||||
**> host_exec cmd=`命令`**
|
|
||||||
@@ -1,20 +0,0 @@
|
|||||||
---
|
|
||||||
title: lib/网络
|
|
||||||
description: 中文简易网络包装
|
|
||||||
---
|
|
||||||
|
|
||||||
# 获取
|
|
||||||
- 地址
|
|
||||||
|
|
||||||
**> host_http_get url=`地址`**
|
|
||||||
|
|
||||||
# 提交
|
|
||||||
- 地址
|
|
||||||
- 内容
|
|
||||||
|
|
||||||
**> host_http_post url=`地址` body=`内容`**
|
|
||||||
|
|
||||||
# 编码地址
|
|
||||||
- 内容
|
|
||||||
|
|
||||||
**> host_url_encode text=`内容`**
|
|
||||||
-15
@@ -1,15 +0,0 @@
|
|||||||
---
|
|
||||||
title: lib/表
|
|
||||||
description: 中文表库:行数 / 取行
|
|
||||||
---
|
|
||||||
|
|
||||||
# 行数
|
|
||||||
- xs
|
|
||||||
|
|
||||||
**> len `xs`**
|
|
||||||
|
|
||||||
# 取行
|
|
||||||
- xs
|
|
||||||
- i
|
|
||||||
|
|
||||||
**> at value=`xs` index=`i`**
|
|
||||||
@@ -1,55 +0,0 @@
|
|||||||
---
|
|
||||||
title: Welcome to Marqdo
|
|
||||||
description: User docs home — code is documentation (English)
|
|
||||||
> lib/math.mq.md
|
|
||||||
> lib/foreign.mq.md
|
|
||||||
---
|
|
||||||
|
|
||||||
# main
|
|
||||||
|
|
||||||
Hi — thanks for reading this far. I am Marqdo’s developer. Marqdo is a language where **code is documentation, and documentation is code**: Markdown markers are the program structure, so what you read is what runs.
|
|
||||||
|
|
||||||
AI already prefers Markdown-shaped output. The idea was: why keep docs and code as two separate worlds? So Marqdo was born as a “docs are code” language. To keep every source renderable as Markdown, files use the `.mq.md` suffix. From early on we aimed for richer tooling — auto-generated YAML for OKF-style knowledge bases, even auto-generated slides — those are later goals. Happily, it already works well as a blogging tool: yes, this site is generated by Marqdo. And when AI writes Marqdo, you tend to burn fewer tokens — wallets everywhere thank you.
|
|
||||||
|
|
||||||
The language is still young: structure markers, bilingual core names (`print` / `打印`, …), importable stdlibs (see [`stdlib/`](stdlib/) on this site), local `view`, and static export. Contribute on [GitHub](https://github.com/cflmy/marqdo).
|
|
||||||
|
|
||||||
中文文档请看同目录的 [`00-欢迎.mq.md`](00-欢迎.mq.md)(叙述与内置均用中文)。
|
|
||||||
|
|
||||||
A small function to say hello:
|
|
||||||
|
|
||||||
> greet who=marqdo
|
|
||||||
|
|
||||||
Named args can include spaces:
|
|
||||||
|
|
||||||
> greet who=marqdo user
|
|
||||||
|
|
||||||
## greet
|
|
||||||
- who
|
|
||||||
|
|
||||||
> print text=Welcome, `who`!
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
Beyond the basics above, Marqdo also ships standard libraries: table, time, text, files, system, math, foreign, and more.
|
|
||||||
|
|
||||||
Math and foreign deserve a special mention. With the math library you can bind a formula like this:
|
|
||||||
|
|
||||||
`f` =
|
|
||||||
$$
|
|
||||||
x^2 - 2
|
|
||||||
$$
|
|
||||||
|
|
||||||
Then plot it:
|
|
||||||
|
|
||||||
*`_svg` = > plot formula=`f` var=x min=-3 max=3 *
|
|
||||||
|
|
||||||
The foreign library lets you call external code, for example:
|
|
||||||
|
|
||||||
`hi` =
|
|
||||||
```python
|
|
||||||
print("hello-from-python")
|
|
||||||
```
|
|
||||||
|
|
||||||
Under Markdown this stays easy to read — which is the point: Marqdo’s design is code as documentation, documentation as code.
|
|
||||||
|
|
||||||
Welcome again — enjoy exploring Marqdo.
|
|
||||||
@@ -1,56 +0,0 @@
|
|||||||
---
|
|
||||||
title: 欢迎使用 Marqdo
|
|
||||||
description: 用户文档首页 — 代码即文档(中文版)
|
|
||||||
> lib/数学.mq.md
|
|
||||||
> lib/外联.mq.md
|
|
||||||
---
|
|
||||||
|
|
||||||
# main
|
|
||||||
|
|
||||||
阅读到这里的朋友你好!我是 Marqdo 的开发者。Marqdo 是一门**代码即文档,文档即代码**的语言:Markdown 标记就是程序结构,你读到的就是能跑的程序。
|
|
||||||
|
|
||||||
AI 偏爱 Markdown结构的输出。作者的念头是:何必再把文档和代码拆成两套?我们来实现一个文档即代码的语言,所以marqdo应运而生,为了确保代码一定可以被渲染,marqdo的文件后缀定义为了`.mq.md`。在开发之处我们就尝试希望更丰富的支持,自动生成一个yaml文件使得 OKF 式知识库便捷的自动配置,乃至自动生成ppt,自然这都是以后的目标了。不过相当不错的是,至少这会成为一个不错的博客工具——对,这个站点就是 Marqdo 生成的,而且AI输出的时候会节约不少token,你知道的,token烧的太多,钱包会可怜的饿瘦的。
|
|
||||||
|
|
||||||
语言仍在起步:结构标记、中英内核双名(`打印` / `print` …)、可导入的标准库(见本站 [`stdlib/`](stdlib/))、本地 `view` 与静态导出。欢迎到 [GitHub](https://github.com/cflmy/marqdo) 一起做。
|
|
||||||
|
|
||||||
English docs: [`00-welcome.mq.md`](00-welcome.mq.md) (English prose and English builtins).
|
|
||||||
|
|
||||||
用一个小函数打个招呼:
|
|
||||||
|
|
||||||
> 问候 谁=marqdo
|
|
||||||
|
|
||||||
具名实参可以带空格:
|
|
||||||
|
|
||||||
> 问候 谁=marqdo user
|
|
||||||
|
|
||||||
## 问候
|
|
||||||
- 谁
|
|
||||||
|
|
||||||
> 打印 内容=欢迎,`谁`!
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
除了上面的一些基本内容之外,我还开发了这个语言的一些标准库,包括表、时间、文本、文件、系统、数学和外联等标准库。
|
|
||||||
|
|
||||||
其中数学库和外联库是我要着重提到的,例如数学库,你可以通过下面的方式调用:
|
|
||||||
|
|
||||||
`f` =
|
|
||||||
$$
|
|
||||||
x^2 - 2
|
|
||||||
$$
|
|
||||||
|
|
||||||
之后让我们画个图像吧!
|
|
||||||
|
|
||||||
*`_svg` = > 绘图 formula=`f` var=x min=-3 max=3 *
|
|
||||||
|
|
||||||
外联库则允许你调用外部代码,例如:
|
|
||||||
|
|
||||||
`hi` =
|
|
||||||
```python
|
|
||||||
print("hello-from-python")
|
|
||||||
```
|
|
||||||
|
|
||||||
这些代码在markdown下面都非常的易读,就像我说的,marqdo的设计思想就是代码即文档,
|
|
||||||
文档即代码。
|
|
||||||
|
|
||||||
最后,再次欢迎你,尽情体验marqdo吧!
|
|
||||||
@@ -1,26 +0,0 @@
|
|||||||
# 用户文档(可执行 · 可下载 · 中英双语)
|
|
||||||
|
|
||||||
本目录即面向访客的 Marqdo 介绍:每个 `.mq.md` 既是文稿也能 `marqdo run`,并随仓库 / 静态站一起下载。
|
|
||||||
|
|
||||||
**双语约定:** 拉丁文件名 → 英文叙述与英文内置;中文文件名 → 中文叙述与中文编程。成对放在同一目录。标准库:拉丁路径用英文 API,中文路径用中文 API;JSON 仅 `lib/json.mq.md`。
|
|
||||||
|
|
||||||
| 路径 | 内容 |
|
|
||||||
|------|------|
|
|
||||||
| [`00-welcome.mq.md`](00-welcome.mq.md) / [`00-欢迎.mq.md`](00-欢迎.mq.md) | 首页(英 / 中) |
|
|
||||||
| [`structure/`](structure/) | 基本结构 |
|
|
||||||
| [`keywords/`](keywords/) | 关键字与 L0 内置 |
|
|
||||||
| [`stdlib/`](stdlib/) | **标准库**(导入方式 + text/表/文件/时间/系统/json/网络/数学/外联) |
|
|
||||||
| [`features/`](features/) | 特性迭代 |
|
|
||||||
|
|
||||||
**不放** `errors/`:失败样例只在 `tests/errors/`。
|
|
||||||
|
|
||||||
开发文档在 [`doc/`](../doc/)。
|
|
||||||
|
|
||||||
## 浏览与生成 HTML
|
|
||||||
|
|
||||||
```bash
|
|
||||||
cargo run -- view public
|
|
||||||
cargo run -- view output public -o public
|
|
||||||
```
|
|
||||||
|
|
||||||
详见 [user-site.md](../doc/design/user-site.md)。
|
|
||||||
@@ -1,14 +0,0 @@
|
|||||||
---
|
|
||||||
title: Phase I — tree-walk interpreter
|
|
||||||
description: Lex · parse · check · tree-walk end to end
|
|
||||||
---
|
|
||||||
|
|
||||||
# main
|
|
||||||
|
|
||||||
Milestone: Phase I (tree-walk).
|
|
||||||
|
|
||||||
Pipeline: load → line classify → recursive-descent parse → semantic check → tree-walk eval. No Flex/Bison.
|
|
||||||
|
|
||||||
This page runs as a program — documentation is executable:
|
|
||||||
|
|
||||||
> print text=Phase I: tree-walk interpreter is live.
|
|
||||||
@@ -1,14 +0,0 @@
|
|||||||
---
|
|
||||||
title: 第一阶段 — 树遍历解释器
|
|
||||||
description: 词法 · 语法 · 语义 · 树遍历已贯通
|
|
||||||
---
|
|
||||||
|
|
||||||
# main
|
|
||||||
|
|
||||||
里程碑:第一阶段(树遍历)。
|
|
||||||
|
|
||||||
流水线:加载 → 行分类 → 递归下降语法 → 语义检查 → 树遍历执行。实现不用 Flex/Bison。
|
|
||||||
|
|
||||||
本页本身即可运行,证明「文档即程序」已落地:
|
|
||||||
|
|
||||||
> 打印 内容=第一阶段:树遍历解释器已就绪。
|
|
||||||
@@ -1,18 +0,0 @@
|
|||||||
---
|
|
||||||
title: Bytecode backend
|
|
||||||
description: `--backend bytecode` shares semantics with tree-walk
|
|
||||||
---
|
|
||||||
|
|
||||||
# main
|
|
||||||
|
|
||||||
Milestone: bytecode prototype.
|
|
||||||
|
|
||||||
The same `.mq.md` runs on tree-walk or the bytecode VM:
|
|
||||||
|
|
||||||
marqdo run FILE --backend tree
|
|
||||||
|
|
||||||
marqdo run FILE --backend bytecode
|
|
||||||
|
|
||||||
Output matches on both backends:
|
|
||||||
|
|
||||||
> print text=Bytecode backend: same program, alternate engine.
|
|
||||||
@@ -1,18 +0,0 @@
|
|||||||
---
|
|
||||||
title: 字节码后端
|
|
||||||
description: `--backend bytecode` 与树遍历共用语义
|
|
||||||
---
|
|
||||||
|
|
||||||
# main
|
|
||||||
|
|
||||||
里程碑:字节码原型。
|
|
||||||
|
|
||||||
同一套 `.mq.md` 可用树遍历或字节码 VM:
|
|
||||||
|
|
||||||
marqdo run FILE --backend tree
|
|
||||||
|
|
||||||
marqdo run FILE --backend bytecode
|
|
||||||
|
|
||||||
两种后端输出一致:
|
|
||||||
|
|
||||||
> 打印 内容=字节码后端:同一程序,另一引擎。
|
|
||||||
@@ -1,16 +0,0 @@
|
|||||||
---
|
|
||||||
title: view and the user docs site
|
|
||||||
description: Local browse and static export from the interpreter
|
|
||||||
---
|
|
||||||
|
|
||||||
# main
|
|
||||||
|
|
||||||
Milestone: `marqdo view` and `view output`.
|
|
||||||
|
|
||||||
Local: `marqdo view public`
|
|
||||||
|
|
||||||
Static export: `marqdo view output public -o public`
|
|
||||||
|
|
||||||
Executable user docs live under `public/`. Generated HTML (`index.html` / `pages/`) is for hosting; CI publishes to `gh-pages`.
|
|
||||||
|
|
||||||
> print text=Docs site: generated by the Marqdo interpreter, not hand-written HTML.
|
|
||||||
@@ -1,16 +0,0 @@
|
|||||||
---
|
|
||||||
title: view 与用户文档站
|
|
||||||
description: 本地浏览与静态导出由解释器生成
|
|
||||||
---
|
|
||||||
|
|
||||||
# main
|
|
||||||
|
|
||||||
里程碑:`marqdo view` 与 `view output`。
|
|
||||||
|
|
||||||
本地浏览:`marqdo view public`
|
|
||||||
|
|
||||||
静态导出:`marqdo view output public -o public`
|
|
||||||
|
|
||||||
用户可执行文档在 `public/`;生成的 HTML(`index.html` / `pages/`)供静态托管,CI 发布到 `gh-pages`。
|
|
||||||
|
|
||||||
> 打印 内容=文档站:由 Marqdo 解释器生成,不是手写 HTML。
|
|
||||||
@@ -1,23 +0,0 @@
|
|||||||
---
|
|
||||||
title: Booleans and logic
|
|
||||||
description: True / False / None and and / or / not
|
|
||||||
---
|
|
||||||
|
|
||||||
# main
|
|
||||||
|
|
||||||
Keywords: `True`, `False`, `None`, and `and` / `or` / `not`.
|
|
||||||
|
|
||||||
*`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
|
|
||||||
@@ -1,13 +0,0 @@
|
|||||||
---
|
|
||||||
title: Built-in input
|
|
||||||
description: Read one line from stdin; optional prompt. Demo via frontmatter stdin.
|
|
||||||
stdin: Ada
|
|
||||||
---
|
|
||||||
|
|
||||||
# main
|
|
||||||
|
|
||||||
The input builtin reads one line. For demos and marqdo view / static export, put sample lines in frontmatter (stdin:). CLI can also use a pipe or --stdin-file. Live view can override with the Preset input box.
|
|
||||||
|
|
||||||
*`name` = > input prompt=Name: *
|
|
||||||
|
|
||||||
> print text=Hello `name`!
|
|
||||||
@@ -1,14 +0,0 @@
|
|||||||
---
|
|
||||||
title: Built-in print
|
|
||||||
description: Named and positional forms
|
|
||||||
---
|
|
||||||
|
|
||||||
# main
|
|
||||||
|
|
||||||
The `print` builtin accepts named or positional arguments:
|
|
||||||
|
|
||||||
> print text=named form
|
|
||||||
|
|
||||||
> print positional
|
|
||||||
|
|
||||||
Named args may contain spaces; positional args may not.
|
|
||||||
@@ -1,34 +0,0 @@
|
|||||||
---
|
|
||||||
title: Built-ins len / str / int / type / trim / split / join / at
|
|
||||||
description: Host builtins for strings and tables
|
|
||||||
---
|
|
||||||
|
|
||||||
# main
|
|
||||||
|
|
||||||
Length and type:
|
|
||||||
|
|
||||||
*`s` = hello*
|
|
||||||
|
|
||||||
*`n` = > len `s`*
|
|
||||||
|
|
||||||
> print text=`n`
|
|
||||||
|
|
||||||
*`ty` = > type `s`*
|
|
||||||
|
|
||||||
> print text=`ty`
|
|
||||||
|
|
||||||
Trim, split, join, and index:
|
|
||||||
|
|
||||||
*`t` = > trim value= hi *
|
|
||||||
|
|
||||||
*`parts` = > split value=a,b sep=,*
|
|
||||||
|
|
||||||
*`mid` = > at value=`parts` index=0*
|
|
||||||
|
|
||||||
*`j` = > join value=`parts` sep=-*
|
|
||||||
|
|
||||||
> print text=`t`
|
|
||||||
|
|
||||||
> print text=`mid`
|
|
||||||
|
|
||||||
> print text=`j`
|
|
||||||
@@ -1,16 +0,0 @@
|
|||||||
---
|
|
||||||
title: 中英内核双名
|
|
||||||
description: 无需导入:打印、长度、文本、整数 与 print / len / …
|
|
||||||
---
|
|
||||||
|
|
||||||
# main
|
|
||||||
|
|
||||||
内核中英别名等价,可混用:
|
|
||||||
|
|
||||||
*`s` = 你好*
|
|
||||||
|
|
||||||
*`n` = > 长度 值=`s`*
|
|
||||||
|
|
||||||
> 打印 内容=`n`
|
|
||||||
|
|
||||||
> print text=also-english
|
|
||||||
@@ -1,23 +0,0 @@
|
|||||||
---
|
|
||||||
title: 布尔与逻辑
|
|
||||||
description: 真 / 假 / 空 与 且 / 或 / 非
|
|
||||||
---
|
|
||||||
|
|
||||||
# main
|
|
||||||
|
|
||||||
关键字:`真`、`假`、`空`,以及 `且` / `或` / `非`。
|
|
||||||
|
|
||||||
*`a` = 真*
|
|
||||||
*`b` = 假*
|
|
||||||
|
|
||||||
+ `a` 且 非 `b`
|
|
||||||
> 打印 内容=通过
|
|
||||||
+ *
|
|
||||||
> 打印 内容=失败
|
|
||||||
|
|
||||||
*`probe` = 1*
|
|
||||||
|
|
||||||
+ 空
|
|
||||||
> 打印 内容=空为真
|
|
||||||
+ *
|
|
||||||
> 打印 内容=空为假
|
|
||||||
@@ -1,14 +0,0 @@
|
|||||||
---
|
|
||||||
title: 内置 打印
|
|
||||||
description: 具名与位置两种写法
|
|
||||||
---
|
|
||||||
|
|
||||||
# main
|
|
||||||
|
|
||||||
内置 `打印` 接受具名或位置实参:
|
|
||||||
|
|
||||||
> 打印 内容=具名写法
|
|
||||||
|
|
||||||
> 打印 位置写法
|
|
||||||
|
|
||||||
具名实参可以带空格;位置实参不可以。
|
|
||||||
@@ -1,34 +0,0 @@
|
|||||||
---
|
|
||||||
title: 内置 长度 / 文本 / 整数 与 trim 等
|
|
||||||
description: 主机内置;中文别名覆盖常用几个
|
|
||||||
---
|
|
||||||
|
|
||||||
# main
|
|
||||||
|
|
||||||
长度与英文 `type`(类型无中文内核别名,见标准库文档):
|
|
||||||
|
|
||||||
*`s` = 你好*
|
|
||||||
|
|
||||||
*`n` = > 长度 值=`s`*
|
|
||||||
|
|
||||||
> 打印 内容=`n`
|
|
||||||
|
|
||||||
*`ty` = > type `s`*
|
|
||||||
|
|
||||||
> 打印 内容=`ty`
|
|
||||||
|
|
||||||
去空白、拆分、拼接、按下标(主机名仍为英文):
|
|
||||||
|
|
||||||
*`t` = > trim value= 嗨 *
|
|
||||||
|
|
||||||
*`parts` = > split value=甲,乙 sep=,*
|
|
||||||
|
|
||||||
*`mid` = > at value=`parts` index=0*
|
|
||||||
|
|
||||||
*`j` = > join value=`parts` sep=-*
|
|
||||||
|
|
||||||
> 打印 内容=`t`
|
|
||||||
|
|
||||||
> 打印 内容=`mid`
|
|
||||||
|
|
||||||
> 打印 内容=`j`
|
|
||||||
@@ -1,13 +0,0 @@
|
|||||||
---
|
|
||||||
title: 内置 输入
|
|
||||||
description: 从 stdin 读一行;可选提示。演示数据写在 frontmatter 输入。
|
|
||||||
输入: 小明
|
|
||||||
---
|
|
||||||
|
|
||||||
# main
|
|
||||||
|
|
||||||
内置「输入」读一行。演示与 marqdo view / 静态导出可在 frontmatter 写「输入:」(或 stdin:)。CLI 也可用管道或 --stdin-file。Live view 可用 Preset input 覆盖。
|
|
||||||
|
|
||||||
*`名字` = > 输入 提示=名字: *
|
|
||||||
|
|
||||||
> 打印 内容=你好 `名字`!
|
|
||||||
@@ -1,18 +0,0 @@
|
|||||||
---
|
|
||||||
title: Standard library — overview
|
|
||||||
description: How to import official lib modules
|
|
||||||
---
|
|
||||||
|
|
||||||
# main
|
|
||||||
|
|
||||||
Official libraries live under lib/ (alias std/). Import them in YAML frontmatter with a greater-than line, for example lib/text.mq.md or lib/fs.mq.md.
|
|
||||||
|
|
||||||
English-named files export English APIs; Chinese-named files export Chinese APIs. JSON is special: only lib/json.mq.md (shared by both languages).
|
|
||||||
|
|
||||||
No extra allow flags: importing a module means you intend to use it. Under marqdo view or static export, exit soft-fails and long sleeps are clamped so the console stays up.
|
|
||||||
|
|
||||||
Modules: text (text / 文本), table (table / 表), files (fs / 文件), time (time / 时间), system (sys / 系统), json (json only), net (net / 网络), math (math / 数学), foreign (foreign / 外联).
|
|
||||||
|
|
||||||
Sibling pages in this folder document each module. Chinese overview: 00-索引.mq.md.
|
|
||||||
|
|
||||||
> print text=stdlib overview ok
|
|
||||||
@@ -1,18 +0,0 @@
|
|||||||
---
|
|
||||||
title: 标准库 — 总览
|
|
||||||
description: 如何导入官方 lib 模块
|
|
||||||
---
|
|
||||||
|
|
||||||
# main
|
|
||||||
|
|
||||||
官方库在仓库 lib/(别名 std/)。在 YAML frontmatter 用大于号行导入,例如 lib/文本.mq.md 或 lib/文件.mq.md。
|
|
||||||
|
|
||||||
拉丁文件名导出英文 API;中文文件名导出中文 API。JSON 特例:只有 lib/json.mq.md(中英共用)。
|
|
||||||
|
|
||||||
导入即表示要用对应能力,无需再加允许旗标。marqdo view 或静态导出里,退出会软失败、长睡眠会被钳制,以免拖垮控制台。
|
|
||||||
|
|
||||||
模块:文本(text / 文本)、表(table / 表)、文件(fs / 文件)、时间(time / 时间)、系统(sys / 系统)、json(仅 json)、网络(net / 网络)、数学(math / 数学)、外联(foreign / 外联)。
|
|
||||||
|
|
||||||
各模块说明见本目录其它页。English: 00-overview.mq.md.
|
|
||||||
|
|
||||||
> 打印 内容=标准库总览就绪
|
|
||||||
@@ -1,20 +0,0 @@
|
|||||||
---
|
|
||||||
title: lib/foreign — external languages
|
|
||||||
description: Run local interpreters from Marqdo (English)
|
|
||||||
> lib/foreign.mq.md
|
|
||||||
---
|
|
||||||
|
|
||||||
# main
|
|
||||||
|
|
||||||
Import lib/foreign.mq.md. Bind a code fence like a formula: empty-RHS assign then a ```lang block. The value type is code. Call run code=`name` to execute via your local interpreter. run_lang runs an inline source string.
|
|
||||||
|
|
||||||
`hi` =
|
|
||||||
```python
|
|
||||||
print("hello-from-python")
|
|
||||||
```
|
|
||||||
|
|
||||||
Default command is python (Windows) or python3 (Unix). Override with set_cmd, env MARQDO_FOREIGN_PYTHON, or the command box in live view. Failures ask you to check that configuration.
|
|
||||||
|
|
||||||
*`out` = > run code=`hi` *
|
|
||||||
|
|
||||||
> print text=`out`
|
|
||||||
@@ -1,18 +0,0 @@
|
|||||||
---
|
|
||||||
title: lib/fs — files
|
|
||||||
description: Read and write text under the sandbox
|
|
||||||
> lib/fs.mq.md
|
|
||||||
---
|
|
||||||
|
|
||||||
# main
|
|
||||||
|
|
||||||
Import lib/fs.mq.md. Functions: read_text, write_text, append_text, exists, list_dir, make_dir, remove (path / text params).
|
|
||||||
|
|
||||||
Bare path words must not contain a slash character (parsed as division). Prefer a same-folder name or a variable.
|
|
||||||
|
|
||||||
*`ok` = > exists path=demo.txt *
|
|
||||||
|
|
||||||
+ `ok`
|
|
||||||
> print text=demo-present
|
|
||||||
+ *
|
|
||||||
> print text=demo-missing
|
|
||||||
@@ -1,19 +0,0 @@
|
|||||||
---
|
|
||||||
title: lib/json — JSON
|
|
||||||
description: Shared EN/ZH path; parse and stringify
|
|
||||||
> lib/json.mq.md
|
|
||||||
---
|
|
||||||
|
|
||||||
# main
|
|
||||||
|
|
||||||
Import lib/json.mq.md from both English and Chinese docs (no translated twin). Functions: parse(text), stringify(value), get(value, key), keys(value). Objects become the map runtime type.
|
|
||||||
|
|
||||||
*`obj` = > parse text={} *
|
|
||||||
|
|
||||||
*`ty` = > type `obj` *
|
|
||||||
|
|
||||||
> print text=`ty`
|
|
||||||
|
|
||||||
*`out` = > stringify value=`obj` *
|
|
||||||
|
|
||||||
> print text=`out`
|
|
||||||
@@ -1,38 +0,0 @@
|
|||||||
---
|
|
||||||
title: lib/math — numbers, formulas, plots
|
|
||||||
description: High-school math stdlib (English)
|
|
||||||
> lib/math.mq.md
|
|
||||||
---
|
|
||||||
|
|
||||||
# main
|
|
||||||
|
|
||||||
Import lib/math.mq.md. Runtime types: num (float) and formula (symbolic tree). Bind a formula with an empty-RHS assign followed by a `$$…$$` fence (same shape as table assigns). In view, Structure renders that fence with KaTeX.
|
|
||||||
|
|
||||||
`f` =
|
|
||||||
$$
|
|
||||||
x^2 - 2
|
|
||||||
$$
|
|
||||||
|
|
||||||
Numeric helpers: pi, e, num, add/sub/mul/div/pow, sin/cos/tan, sqrt/abs/ln/exp, floor/ceil, min/max. Random: seed, random, random_int (reproducible after seed).
|
|
||||||
|
|
||||||
Symbolic: formula(text), simplify, expand, diff, subs, eval, solve.
|
|
||||||
|
|
||||||
Plotting (already in the library): plot / plot_points / plot_conic return SVG text. Axes include arrows and tick labels; **grid is on by default** (pass grid=False / grid=假 to hide). Optional path= writes a file under the sandbox. With no path, CLI auto-writes stem-plot-n.svg and prints plot: …; view embeds the SVG under Execution.
|
|
||||||
|
|
||||||
diff / simplify / expand / partial subs return formula values so you can chain (e.g. differentiate twice, then plot or eval).
|
|
||||||
|
|
||||||
*`ty` = > type `f` *
|
|
||||||
|
|
||||||
> print text=`ty`
|
|
||||||
|
|
||||||
*`df` = > diff formula=`f` var=x *
|
|
||||||
|
|
||||||
> print text=`df`
|
|
||||||
|
|
||||||
*`roots` = > solve formula=`f` var=x *
|
|
||||||
|
|
||||||
> print text=`roots`
|
|
||||||
|
|
||||||
*`_svg` = > plot formula=`f` var=x min=-3 max=3 *
|
|
||||||
|
|
||||||
> print text=plot-ok
|
|
||||||
@@ -1,13 +0,0 @@
|
|||||||
---
|
|
||||||
title: lib/net — HTTP
|
|
||||||
description: Minimal HTTP client and URL encode
|
|
||||||
> lib/net.mq.md
|
|
||||||
---
|
|
||||||
|
|
||||||
# main
|
|
||||||
|
|
||||||
Import lib/net.mq.md. Functions: http_get(url) returns map status/body, http_post(url, body), url_encode(text). v1 speaks cleartext http only.
|
|
||||||
|
|
||||||
*`e` = > url_encode text=hello world *
|
|
||||||
|
|
||||||
> print text=`e`
|
|
||||||
@@ -1,18 +0,0 @@
|
|||||||
---
|
|
||||||
title: lib/sys — process
|
|
||||||
description: Env, cwd, args, exit, exec
|
|
||||||
> lib/sys.mq.md
|
|
||||||
---
|
|
||||||
|
|
||||||
# main
|
|
||||||
|
|
||||||
Import lib/sys.mq.md. Functions: env_get, env_set, args, cwd, exit(code), exec(cmd). Under view, exit soft-fails instead of killing the process.
|
|
||||||
|
|
||||||
*`d` = > cwd *
|
|
||||||
|
|
||||||
*`n` = > len `d` *
|
|
||||||
|
|
||||||
+ `n` > 0
|
|
||||||
> print text=cwd-ok
|
|
||||||
+ *
|
|
||||||
> print text=cwd-empty
|
|
||||||
@@ -1,24 +0,0 @@
|
|||||||
---
|
|
||||||
title: lib/table — lists
|
|
||||||
description: Row count and index helpers
|
|
||||||
> lib/table.mq.md
|
|
||||||
---
|
|
||||||
|
|
||||||
# main
|
|
||||||
|
|
||||||
Import lib/table.mq.md. Functions: rows(xs), row_at(xs, i). Single-column Markdown tables are lists at runtime.
|
|
||||||
|
|
||||||
`xs` =
|
|
||||||
|
|
||||||
| v |
|
|
||||||
|---|
|
|
||||||
| a |
|
|
||||||
| b |
|
|
||||||
|
|
||||||
*`n` = > rows xs=`xs`*
|
|
||||||
|
|
||||||
> print text=`n`
|
|
||||||
|
|
||||||
*`r` = > row_at xs=`xs` i=0*
|
|
||||||
|
|
||||||
> print text=`r`
|
|
||||||
@@ -1,19 +0,0 @@
|
|||||||
---
|
|
||||||
title: lib/text — strings
|
|
||||||
description: Trim, split, join wrappers
|
|
||||||
> lib/text.mq.md
|
|
||||||
---
|
|
||||||
|
|
||||||
# main
|
|
||||||
|
|
||||||
Import lib/text.mq.md. Functions: str_trim(s), str_split(s, sep), str_join(xs, sep).
|
|
||||||
|
|
||||||
*`t` = > str_trim s= marqdo *
|
|
||||||
|
|
||||||
> print text=`t`
|
|
||||||
|
|
||||||
*`parts` = > str_split s=a,b,c sep=,*
|
|
||||||
|
|
||||||
*`j` = > str_join xs=`parts` sep=-*
|
|
||||||
|
|
||||||
> print text=`j`
|
|
||||||
@@ -1,19 +0,0 @@
|
|||||||
---
|
|
||||||
title: lib/time — clock
|
|
||||||
description: Unix time, format, parse, sleep
|
|
||||||
> lib/time.mq.md
|
|
||||||
---
|
|
||||||
|
|
||||||
# main
|
|
||||||
|
|
||||||
Import lib/time.mq.md. Functions: now_unix, now_ms, format(unix, pattern), parse(text, pattern), sleep_ms(ms). Patterns use strftime.
|
|
||||||
|
|
||||||
*`s` = > format unix=0 pattern=%Y-%m-%d *
|
|
||||||
|
|
||||||
> print text=`s`
|
|
||||||
|
|
||||||
*`u` = > parse text=1970-01-01 00:00:00 pattern=%Y-%m-%d %H:%M:%S *
|
|
||||||
|
|
||||||
> print text=`u`
|
|
||||||
|
|
||||||
> sleep_ms ms=0
|
|
||||||
@@ -1,20 +0,0 @@
|
|||||||
---
|
|
||||||
title: lib/外联 — 外部语言
|
|
||||||
description: 从 Marqdo 调用本机解释器(中文)
|
|
||||||
> lib/外联.mq.md
|
|
||||||
---
|
|
||||||
|
|
||||||
# main
|
|
||||||
|
|
||||||
导入 lib/外联.mq.md。代码围栏与公式同构:空 RHS 赋值后跟 lang 代码块,得到 code 类型。用 运行 代码=`名` 调用本机解释器。
|
|
||||||
|
|
||||||
`hi` =
|
|
||||||
```python
|
|
||||||
print("hello-from-python")
|
|
||||||
```
|
|
||||||
|
|
||||||
默认命令可用 设置命令 或 MARQDO_FOREIGN_PYTHON 覆盖;live view 里可改命令框再点 Run。
|
|
||||||
|
|
||||||
*`out` = > 运行 代码=`hi` *
|
|
||||||
|
|
||||||
> print text=`out`
|
|
||||||
@@ -1,38 +0,0 @@
|
|||||||
---
|
|
||||||
title: lib/数学 — 数值、公式、作图
|
|
||||||
description: 高中数学标准库(中文)
|
|
||||||
> lib/数学.mq.md
|
|
||||||
---
|
|
||||||
|
|
||||||
# main
|
|
||||||
|
|
||||||
导入 lib/数学.mq.md。运行时类型:num(浮点)与 formula(符号树)。用空 RHS 赋值后跟 `$$…$$` 围栏绑定公式(与表格赋值同构)。view 的 Structure 会用 KaTeX 渲染该公式。
|
|
||||||
|
|
||||||
`f` =
|
|
||||||
$$
|
|
||||||
x^2 - 2
|
|
||||||
$$
|
|
||||||
|
|
||||||
数值:圆周率、自然底数、数、加/减/乘/除/幂、正弦/余弦/正切、平方根/绝对值/对数/指数、向下取整/向上取整、最小/最大。随机:设种子、随机、随机整数。
|
|
||||||
|
|
||||||
符号:公式、化简、展开、求导、代入、求值、求解。
|
|
||||||
|
|
||||||
作图(库已提供):绘图 / 绘点列 / 绘圆锥,返回 SVG 文本。坐标轴带箭头与刻度;**默认显示网格**(`grid=假` 可关闭)。可选 path= 写盘。无 path 时 CLI 自动写 stem-plot-n.svg 并打印 plot: …;view 在 Execution 内嵌 SVG。
|
|
||||||
|
|
||||||
求导 / 化简 / 展开 / 未完全数值化的代入仍返回 formula,可继续链式调用(例如求二阶导后再绘图或求值)。
|
|
||||||
|
|
||||||
*`ty` = > type `f` *
|
|
||||||
|
|
||||||
> print text=`ty`
|
|
||||||
|
|
||||||
*`df` = > 求导 formula=`f` var=x *
|
|
||||||
|
|
||||||
> print text=`df`
|
|
||||||
|
|
||||||
*`roots` = > 求解 formula=`f` var=x *
|
|
||||||
|
|
||||||
> print text=`roots`
|
|
||||||
|
|
||||||
*`_svg` = > 绘图 formula=`f` var=x min=-3 max=3 *
|
|
||||||
|
|
||||||
> print text=plot-ok
|
|
||||||
@@ -1,18 +0,0 @@
|
|||||||
---
|
|
||||||
title: lib/文件 — 文件系统
|
|
||||||
description: 沙箱内读写文本
|
|
||||||
> lib/文件.mq.md
|
|
||||||
---
|
|
||||||
|
|
||||||
# main
|
|
||||||
|
|
||||||
导入 lib/文件.mq.md。函数:读文本、写文本、追加文本、存在、列目录、建目录、删除。
|
|
||||||
|
|
||||||
裸路径字面量不要写斜杠(会被当成除法)。可用同目录文件名或变量。
|
|
||||||
|
|
||||||
*`ok` = > 存在 路径=demo.txt *
|
|
||||||
|
|
||||||
+ `ok`
|
|
||||||
> 打印 内容=有演示文件
|
|
||||||
+ *
|
|
||||||
> 打印 内容=无演示文件
|
|
||||||
@@ -1,19 +0,0 @@
|
|||||||
---
|
|
||||||
title: lib/文本 — 字符串
|
|
||||||
description: 去空白、拆分、拼接
|
|
||||||
> lib/文本.mq.md
|
|
||||||
---
|
|
||||||
|
|
||||||
# main
|
|
||||||
|
|
||||||
导入 lib/文本.mq.md。函数:去空白(s)、拆分(s, sep)、拼接(xs, sep)。
|
|
||||||
|
|
||||||
*`t` = > 去空白 s= marqdo *
|
|
||||||
|
|
||||||
> 打印 内容=`t`
|
|
||||||
|
|
||||||
*`parts` = > 拆分 s=甲,乙,丙 sep=,*
|
|
||||||
|
|
||||||
*`j` = > 拼接 xs=`parts` sep=-*
|
|
||||||
|
|
||||||
> 打印 内容=`j`
|
|
||||||
@@ -1,19 +0,0 @@
|
|||||||
---
|
|
||||||
title: lib/时间 — 时钟
|
|
||||||
description: Unix 时间、格式化、解析、睡眠
|
|
||||||
> lib/时间.mq.md
|
|
||||||
---
|
|
||||||
|
|
||||||
# main
|
|
||||||
|
|
||||||
导入 lib/时间.mq.md。函数:此刻秒、此刻毫秒、格式化(秒, 格式)、解析时间(内容, 格式)、睡眠毫秒(毫秒)。格式为 strftime。
|
|
||||||
|
|
||||||
*`s` = > 格式化 秒=0 格式=%Y-%m-%d *
|
|
||||||
|
|
||||||
> 打印 内容=`s`
|
|
||||||
|
|
||||||
*`u` = > 解析时间 内容=1970-01-01 00:00:00 格式=%Y-%m-%d %H:%M:%S *
|
|
||||||
|
|
||||||
> 打印 内容=`u`
|
|
||||||
|
|
||||||
> 睡眠毫秒 毫秒=0
|
|
||||||
@@ -1,18 +0,0 @@
|
|||||||
---
|
|
||||||
title: lib/系统 — 进程
|
|
||||||
description: 环境变量、工作目录、参数、退出、执行
|
|
||||||
> lib/系统.mq.md
|
|
||||||
---
|
|
||||||
|
|
||||||
# main
|
|
||||||
|
|
||||||
导入 lib/系统.mq.md。函数:取环境、设环境、参数表、工作目录、退出(码)、执行(命令)。view 下退出会软失败,不结束进程。
|
|
||||||
|
|
||||||
*`d` = > 工作目录 *
|
|
||||||
|
|
||||||
*`n` = > 长度 值=`d` *
|
|
||||||
|
|
||||||
+ `n` > 0
|
|
||||||
> 打印 内容=工作目录就绪
|
|
||||||
+ *
|
|
||||||
> 打印 内容=工作目录空
|
|
||||||
@@ -1,13 +0,0 @@
|
|||||||
---
|
|
||||||
title: lib/网络 — HTTP
|
|
||||||
description: 简易 HTTP 与地址编码
|
|
||||||
> lib/网络.mq.md
|
|
||||||
---
|
|
||||||
|
|
||||||
# main
|
|
||||||
|
|
||||||
导入 lib/网络.mq.md。函数:获取(地址) 返回 map status/body、提交(地址, 内容)、编码地址(内容)。本波仅明文 http。
|
|
||||||
|
|
||||||
*`e` = > 编码地址 内容=你好 *
|
|
||||||
|
|
||||||
> 打印 内容=`e`
|
|
||||||
@@ -1,24 +0,0 @@
|
|||||||
---
|
|
||||||
title: lib/表 — 列表
|
|
||||||
description: 行数与取行
|
|
||||||
> lib/表.mq.md
|
|
||||||
---
|
|
||||||
|
|
||||||
# main
|
|
||||||
|
|
||||||
导入 lib/表.mq.md。函数:行数(xs)、取行(xs, i)。单列表在运行时是列表。
|
|
||||||
|
|
||||||
`xs` =
|
|
||||||
|
|
||||||
| v |
|
|
||||||
|---|
|
|
||||||
| 甲 |
|
|
||||||
| 乙 |
|
|
||||||
|
|
||||||
*`n` = > 行数 xs=`xs`*
|
|
||||||
|
|
||||||
> 打印 内容=`n`
|
|
||||||
|
|
||||||
*`r` = > 取行 xs=`xs` i=0*
|
|
||||||
|
|
||||||
> 打印 内容=`r`
|
|
||||||
@@ -1,12 +0,0 @@
|
|||||||
---
|
|
||||||
title: Hello World
|
|
||||||
description: Smallest runnable doc
|
|
||||||
---
|
|
||||||
|
|
||||||
# main
|
|
||||||
|
|
||||||
Ordinary paragraphs are comments. `print` is a built-in, not a syntax marker.
|
|
||||||
|
|
||||||
Lines that start with Markdown emphasis markers can be treated as code — keep narrative as plain prose.
|
|
||||||
|
|
||||||
> print text=Hello World!
|
|
||||||
@@ -1,12 +0,0 @@
|
|||||||
---
|
|
||||||
title: 你好世界
|
|
||||||
description: 最小可运行文档
|
|
||||||
---
|
|
||||||
|
|
||||||
# main
|
|
||||||
|
|
||||||
普通段落是注释。`打印` 是内置函数,不是语法标记。
|
|
||||||
|
|
||||||
以 Markdown 强调标记开头的行可当作代码——叙述请用普通段落。
|
|
||||||
|
|
||||||
> 打印 内容=你好世界!
|
|
||||||
@@ -1,17 +0,0 @@
|
|||||||
---
|
|
||||||
title: Functions and named calls
|
|
||||||
description: `#` defines functions; `>` calls; `-` lists parameter names
|
|
||||||
---
|
|
||||||
|
|
||||||
# main
|
|
||||||
|
|
||||||
Use `#` / `##` for functions. Parameters are bare `- name` lines under the heading.
|
|
||||||
|
|
||||||
Call with `>` and named args `param=value`:
|
|
||||||
|
|
||||||
> greet who=World
|
|
||||||
|
|
||||||
## greet
|
|
||||||
- who
|
|
||||||
|
|
||||||
> print text=Hello `who`!
|
|
||||||
@@ -1,17 +0,0 @@
|
|||||||
---
|
|
||||||
title: 函数与具名调用
|
|
||||||
description: `#` 定义函数;`>` 调用;`-` 列出参数名
|
|
||||||
---
|
|
||||||
|
|
||||||
# main
|
|
||||||
|
|
||||||
用 `#` / `##` 定义函数。参数是标题下的裸 `- 名` 行。
|
|
||||||
|
|
||||||
用 `>` 与具名实参 `参数=值` 调用:
|
|
||||||
|
|
||||||
> 问候 谁=世界
|
|
||||||
|
|
||||||
## 问候
|
|
||||||
- 谁
|
|
||||||
|
|
||||||
> 打印 内容=你好 `谁`!
|
|
||||||
@@ -1,19 +0,0 @@
|
|||||||
---
|
|
||||||
title: Positional arguments
|
|
||||||
description: Bind by parameter order; named form still works
|
|
||||||
---
|
|
||||||
|
|
||||||
# main
|
|
||||||
|
|
||||||
Positional args bind in declaration order (no `who=` needed):
|
|
||||||
|
|
||||||
> greet Marqdo
|
|
||||||
|
|
||||||
Named form still works:
|
|
||||||
|
|
||||||
> greet who=World
|
|
||||||
|
|
||||||
## greet
|
|
||||||
- who
|
|
||||||
|
|
||||||
> print text=Hello `who`!
|
|
||||||
@@ -1,19 +0,0 @@
|
|||||||
---
|
|
||||||
title: 位置实参
|
|
||||||
description: 按参数声明顺序绑定;具名写法仍然可用
|
|
||||||
---
|
|
||||||
|
|
||||||
# main
|
|
||||||
|
|
||||||
位置实参按声明顺序绑定(不必写 `谁=`):
|
|
||||||
|
|
||||||
> 问候 Marqdo
|
|
||||||
|
|
||||||
具名写法仍然可用:
|
|
||||||
|
|
||||||
> 问候 谁=世界
|
|
||||||
|
|
||||||
## 问候
|
|
||||||
- 谁
|
|
||||||
|
|
||||||
> 打印 内容=你好 `谁`!
|
|
||||||
@@ -1,17 +0,0 @@
|
|||||||
---
|
|
||||||
title: Branch
|
|
||||||
description: `+` arms; a lone `*` arm is else
|
|
||||||
---
|
|
||||||
|
|
||||||
# main
|
|
||||||
|
|
||||||
Italic lines are statements. Branches use `+`; a head that is only `*` is the else arm.
|
|
||||||
|
|
||||||
*`x` = 0*
|
|
||||||
|
|
||||||
+ `x` > 0
|
|
||||||
> print text=positive
|
|
||||||
+ `x` < 0
|
|
||||||
> print text=negative
|
|
||||||
+ *
|
|
||||||
> print text=zero
|
|
||||||
@@ -1,17 +0,0 @@
|
|||||||
---
|
|
||||||
title: 分支
|
|
||||||
description: `+` 各臂;单独的 `*` 臂为否则
|
|
||||||
---
|
|
||||||
|
|
||||||
# main
|
|
||||||
|
|
||||||
斜体行是语句。分支用 `+`;表头仅为 `*` 的是否则臂。
|
|
||||||
|
|
||||||
*`x` = 0*
|
|
||||||
|
|
||||||
+ `x` > 0
|
|
||||||
> 打印 内容=正数
|
|
||||||
+ `x` < 0
|
|
||||||
> 打印 内容=负数
|
|
||||||
+ *
|
|
||||||
> 打印 内容=零
|
|
||||||
@@ -1,28 +0,0 @@
|
|||||||
---
|
|
||||||
title: Loops
|
|
||||||
description: Condition loops and table walks
|
|
||||||
---
|
|
||||||
|
|
||||||
# main
|
|
||||||
|
|
||||||
Inside a function body, `-` starts a loop (not a parameter).
|
|
||||||
|
|
||||||
Countdown:
|
|
||||||
|
|
||||||
*`n` = 3*
|
|
||||||
|
|
||||||
- `n` > 0
|
|
||||||
> print text=`n`
|
|
||||||
*`n` = `n` - 1*
|
|
||||||
|
|
||||||
Walk a table (tables are collections):
|
|
||||||
|
|
||||||
`basket` =
|
|
||||||
|
|
||||||
| fruit |
|
|
||||||
|-------|
|
|
||||||
| apple |
|
|
||||||
| pear |
|
|
||||||
|
|
||||||
- [fruit](basket)
|
|
||||||
> print text=today `fruit`
|
|
||||||
@@ -1,28 +0,0 @@
|
|||||||
---
|
|
||||||
title: 循环
|
|
||||||
description: 条件循环与表遍历
|
|
||||||
---
|
|
||||||
|
|
||||||
# main
|
|
||||||
|
|
||||||
在函数体里,`-` 表示循环(不是参数)。
|
|
||||||
|
|
||||||
倒数:
|
|
||||||
|
|
||||||
*`n` = 3*
|
|
||||||
|
|
||||||
- `n` > 0
|
|
||||||
> 打印 内容=`n`
|
|
||||||
*`n` = `n` - 1*
|
|
||||||
|
|
||||||
遍历表(表即集合):
|
|
||||||
|
|
||||||
`篮子` =
|
|
||||||
|
|
||||||
| 水果 |
|
|
||||||
|------|
|
|
||||||
| 苹果 |
|
|
||||||
| 梨 |
|
|
||||||
|
|
||||||
- [水果](篮子)
|
|
||||||
> 打印 内容=今天 `水果`
|
|
||||||
Loaded 100 of 228 files, more files were not shown because too many files have changed in this diff.
Show more
Reference in new issue
Block a user