Refocus manual on public language usage
This commit is contained in:
+54
-113
@@ -1,140 +1,81 @@
|
||||
# Components
|
||||
# Packages and Integrations
|
||||
|
||||
Decodal is split into a small runtime core and separate syntax tooling components.
|
||||
The public surface is intentionally organized by use case: execute Decodal with Rust or WebAssembly, edit Decodal on the Web with Lezer and CodeMirror, and integrate Decodal into general-purpose editors with Tree-sitter.
|
||||
Decodal は実行、ホスト組み込み、言語サービス、エディタ統合を用途別の package として提供する。
|
||||
|
||||
## Runtime components
|
||||
## Rust
|
||||
|
||||
### Rust crate
|
||||
### `decodal`
|
||||
|
||||
The `decodal` crate is the primary Rust runtime and embedding API.
|
||||
It owns parsing, evaluation, materialization, diagnostics, host-provided values, and schema/decode traits.
|
||||
Rust applications should use this crate when they want to load Decodal source, evaluate it, or embed Decodal into a host program.
|
||||
Rust アプリケーション向けの runtime と embedding API である。
|
||||
source の parse・evaluate・materialize、host global、source または structured value の import を扱う。
|
||||
|
||||
Important paths:
|
||||
|
||||
```text
|
||||
crates/decodal-core/
|
||||
crates/decodal-derive/
|
||||
```toml
|
||||
[dependencies]
|
||||
decodal = "0.4"
|
||||
```
|
||||
|
||||
`decodal-derive` provides optional derive macros for Rust struct integration.
|
||||
It is a companion to the runtime crate rather than an editor or syntax-highlighting component.
|
||||
Rust struct から Decodal schema と decoder を生成する場合は `derive` feature を有効にする。
|
||||
|
||||
### WebAssembly package
|
||||
|
||||
`decodal-wasm` exposes the runtime to browsers.
|
||||
The documentation site playground uses it to evaluate Decodal entirely in the browser.
|
||||
|
||||
Important paths:
|
||||
|
||||
```text
|
||||
crates/decodal-wasm/
|
||||
packages/decodal-wasm/
|
||||
```toml
|
||||
[dependencies]
|
||||
decodal = { version = "0.4", features = ["derive"] }
|
||||
```
|
||||
|
||||
The npm package is `decodal-wasm`.
|
||||
The JSR package is `@hare/decodal-wasm`.
|
||||
正規表現制約を検証する場合は `regex` feature を有効にする。
|
||||
この feature は `std` を必要とする。
|
||||
|
||||
The generated files in `packages/decodal-wasm/` are committed so the site can build without requiring every consumer to run `wasm-pack` first.
|
||||
The WebAssembly package is for execution, not syntax highlighting.
|
||||
### `decodal-language-service`
|
||||
|
||||
## Language tools
|
||||
transport に依存しない semantic evaluation と completion を提供する。
|
||||
アプリケーションの `HostEnvironment` をそのまま受け取るため、本番評価と編集時評価で global bindings と import 規則を共有できる。
|
||||
|
||||
Semantic editor integration lives in the host-configurable language service crate.
|
||||
It depends only on the runtime and accepts the same `HostEnvironment` implementation used by a production application.
|
||||
The LSP crate adapts that service to the Language Server Protocol over stdin/stdout.
|
||||
It provides full document synchronization, semantic diagnostics, and whole-document formatting.
|
||||
A host-specific LSP binary injects its loader and global schema configuration without reimplementing evaluation rules.
|
||||
### `decodal-lsp`
|
||||
|
||||
Important paths:
|
||||
language service を Language Server Protocol に接続する。
|
||||
stdio server のほか、client の `InitializeParams` からアプリケーション固有の environment を構築する library API を提供する。
|
||||
|
||||
```text
|
||||
crates/decodal-language-service/
|
||||
crates/decodal-lsp/
|
||||
### `decodal-language-tools`
|
||||
|
||||
source formatter など、source text を扱う共通ツールを提供する。
|
||||
formatter は Rust、LSP、WebAssembly の各統合から同じ実装を利用できる。
|
||||
|
||||
## JavaScript and WebAssembly
|
||||
|
||||
### `decodal-wasm`
|
||||
|
||||
browser と WebAssembly 対応 runtime 向けの evaluator と language service である。
|
||||
|
||||
```sh
|
||||
npm install decodal-wasm
|
||||
```
|
||||
|
||||
The default `decodal-lsp` binary reads Decodal imports from the filesystem.
|
||||
Embedded hosts can call its library entry point with a custom `LspEnvironment` to reuse structured imports and to make unsaved external documents, such as Markdown, visible to the loader.
|
||||
JSR では `@hare/decodal-wasm` として提供される。
|
||||
`DecodalLanguageService` に `globals`、`loadImport`、`completeImport` を渡すことで、JavaScript が所有する environment を評価と補完で共有できる。
|
||||
|
||||
Source formatting lives in a separate Rust language tools crate.
|
||||
It uses the canonical Decodal AST together with the runtime lexer's lossless syntax tokens, so native LSP and WebAssembly callers execute the same formatter implementation.
|
||||
### `decodal-codemirror`
|
||||
|
||||
This component is responsible for operations that must preserve source text details such as comments and whitespace.
|
||||
It is used by the CodeMirror package's bundled formatter WebAssembly and can also be used by an LSP adapter for formatting.
|
||||
It does not depend on Tree-sitter or Lezer.
|
||||
CodeMirror 6 向けの language support である。
|
||||
syntax highlighting、folding、indentation、Decodal formatter との統合を提供する。
|
||||
|
||||
Important paths:
|
||||
|
||||
```text
|
||||
crates/decodal-language-tools/
|
||||
```sh
|
||||
npm install decodal-codemirror
|
||||
```
|
||||
|
||||
The current language tools crate exposes the formatter.
|
||||
JSR では `@hare/decodal-codemirror` として提供される。
|
||||
semantic evaluation と completion が必要な場合は `decodal-wasm` の language service と組み合わせる。
|
||||
|
||||
## Web editor components
|
||||
## Editor syntax
|
||||
|
||||
The Web playground editor uses CodeMirror 6 with a generated Lezer parser.
|
||||
Lezer provides syntax highlighting, folding, indentation, and editor syntax tree behavior. The browser formatter command calls the canonical Rust formatter compiled to WebAssembly.
|
||||
Tree-sitter grammar は、Tree-sitter を採用するエディタで構文解析と highlighting を行うための統合である。
|
||||
Decodal runtime、formatter、LSP の利用には Tree-sitter は必要ない。
|
||||
|
||||
Important paths:
|
||||
用途ごとの選択は次の通りである。
|
||||
|
||||
```text
|
||||
editors/lezer-decodal/decodal.grammar
|
||||
packages/decodal-codemirror/src/decodal.js
|
||||
packages/decodal-codemirror/src/decodal-parser.js
|
||||
packages/decodal-codemirror/src/decodal-parser.terms.js
|
||||
packages/decodal-codemirror/src/format.js
|
||||
packages/decodal-codemirror/wasm/
|
||||
```
|
||||
- Rust での実行と組み込み: `decodal`
|
||||
- browser での実行と semantic tooling: `decodal-wasm`
|
||||
- CodeMirror 6: `decodal-codemirror`
|
||||
- transport 非依存の Rust language service: `decodal-language-service`
|
||||
- 一般的な editor client: `decodal-lsp`
|
||||
- Tree-sitter 採用 editor の syntax grammar: Tree-sitter integration
|
||||
|
||||
The npm package is `decodal-codemirror`.
|
||||
The JSR package is `@hare/decodal-codemirror`.
|
||||
|
||||
The Lezer grammar is derived from the canonical grammar documentation, but it is not a literal copy of the EBNF.
|
||||
Precedence and token conflict handling are represented in the Lezer grammar in the form CodeMirror needs.
|
||||
|
||||
## General editor components
|
||||
|
||||
Tree-sitter is the portable editor-integration grammar.
|
||||
Editors such as Zed, Neovim, Helix, and Emacs should consume this component when they need Decodal parsing or highlighting outside the Web playground.
|
||||
|
||||
Important paths:
|
||||
|
||||
```text
|
||||
editors/tree-sitter-decodal/grammar.js
|
||||
editors/tree-sitter-decodal/queries/highlights.scm
|
||||
editors/tree-sitter-decodal/queries/locals.scm
|
||||
editors/tree-sitter-decodal/src/
|
||||
```
|
||||
|
||||
The generated parser sources under `editors/tree-sitter-decodal/src/` are committed so editor integrations can consume the grammar without regenerating it first.
|
||||
|
||||
## Canonical grammar
|
||||
|
||||
The human-readable grammar lives in:
|
||||
|
||||
```text
|
||||
doc/manual/souce/language/grammar.md
|
||||
```
|
||||
|
||||
This EBNF is the language-level reference.
|
||||
The Rust parser, Lezer grammar, and Tree-sitter grammar should be kept aligned with it, but each implementation may encode precedence and recovery behavior in the form required by its parser generator or runtime.
|
||||
|
||||
## Syntax token API
|
||||
|
||||
The `decodal` crate exposes `tokenize_source`, `tokenize_source_with_source_id`, `SyntaxToken`, and `SyntaxTokenKind` for source-preserving tooling.
|
||||
Comments have explicit tokens, while whitespace is represented by gaps between token spans and can be recovered from the original source.
|
||||
The evaluator parser and formatter therefore share one lexical definition without making Tree-sitter an upstream dependency.
|
||||
|
||||
Consumers should otherwise use the component matching their environment:
|
||||
|
||||
- Rust execution and embedding: `decodal`
|
||||
- Browser execution: `decodal-wasm`
|
||||
- Web formatting and editor syntax: canonical formatter / CodeMirror / Lezer
|
||||
- Semantic editor analysis: `decodal-language-service`
|
||||
- Language Server Protocol integration: `decodal-lsp`
|
||||
- Rust formatting: `decodal-language-tools`
|
||||
- General editor syntax: Tree-sitter
|
||||
|
||||
Tree-sitter and Lezer remain downstream editor grammars and are not dependencies of the runtime formatter.
|
||||
具体的な environment の構築方法は [Embedding](./embedding.md) を参照する。
|
||||
|
||||
Reference in New Issue
Block a user