diff --git a/.github/workflows/reader.yml b/.github/workflows/reader.yml new file mode 100644 index 0000000..fb5ce29 --- /dev/null +++ b/.github/workflows/reader.yml @@ -0,0 +1,48 @@ +name: Reader acceptance +on: + pull_request: + branches: [master] + push: + branches: [master] +permissions: + contents: read +jobs: + reader: + runs-on: ubuntu-24.04 + timeout-minutes: 30 + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-node@v4 + with: + node-version: '24' + - uses: pnpm/action-setup@v4 + with: + version: 11.25.0 + - uses: ./.github/actions/setup-rust + - name: Install pinned mdBook tools + run: | + cargo install mdbook --version 0.4.52 --locked + cargo install mdbook-admonish --version 1.20.0 --locked + cargo install mdbook-katex --version 0.9.4 --locked + - name: Frozen dependencies and compiler lint + working-directory: web + run: | + pnpm install --frozen-lockfile + pnpm lint + pnpm typecheck + - name: Build, unit tests, generated links and repeatability + working-directory: web + run: | + pnpm build + pnpm test:generated + cp ../output/merge-acceptance/generated-inventory.json /tmp/reader-inventory.json + pnpm test + pnpm build + pnpm test:generated + cmp /tmp/reader-inventory.json ../output/merge-acceptance/generated-inventory.json + - name: Desktop engines and mobile profile simulations + working-directory: web + run: | + pnpm exec playwright install --with-deps chromium firefox webkit + pnpm test:browser + pnpm test:acceptance diff --git a/.gitignore b/.gitignore index 7585238..2e4de01 100644 --- a/.gitignore +++ b/.gitignore @@ -1 +1,8 @@ book +output/ +web/node_modules/ +web/dist/ +web/.cache/ +web/public/content.json +web/public/content/ +web/public/book-assets/ diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..b0df319 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,25 @@ +# Maintaining ALUX Programming + +This repository contains the original mdBook in `src/` and a multilingual reader in `web/`. Read [web/AGENTS.md](web/AGENTS.md) before changing reader content, typography, artwork, language routing or controls. It defines alignment, type sizes, capitalization, responsive behavior and the checks required after a change. + +- Keep the book's meaning, author attribution, equations, code, heading anchors and existing source links intact. Use semantic Markdown heading levels. Register new chapters in `src/SUMMARY.md`. +- Do not edit `web/public/content.json`, localized `web/public/content/`, copied `web/public/book-assets/` files or `web/dist/` by hand. Generate them with the existing scripts. +- The two magic reading modes share their type scale in `web/reader-presentation.css`. A fix must cover both `.folio-content` and `.continuous-prose`. Check the real reader separately. +- The web illustration mapping lives in `web/scripts/reader-presentation.ts`; see [web/ARTWORK.md](web/ARTWORK.md) for source and runtime assets. Retain original mdBook illustrations unless the task explicitly changes those sources. +- Keep the root English README and `docs/README..md` language introductions consistent. Use language names, relative links and a clear active-language marker. GitHub README links do not perform the website's automatic language selection. +- Keep public introductions concise and factual. Do not insert internal production notes, unverified deployment claims or private correspondence into the reader or README. +- Preserve mdBook as the content compiler. The typed JSON backend owns chapter structure; the native HTML renderer owns Markdown, preprocessors and canonical anchors. The shared model and localization live in `web/src/`; reader-specific code handles presentation and interaction only. Do not restore a second Markdown compiler or manual SUMMARY parser. +- Translations belong beside canonical chapters as `chapter..md`, selected by the web-only mdBook preprocessor. Keep one SUMMARY and stable chapter/heading identities, with English fallback for missing files. UI messages belong in `web/locales/ui/`; never restore prose dictionaries, token alignment or runtime DOM translation. Solid components own app state; imperative code is limited to opaque content, layout/animation and browser media adapters. Read `web/docs/source-localization-migration.md` before revising this boundary. +- Run `pnpm --dir web build`, `pnpm --dir web test` and the checks relevant to the changed behavior. Shared presentation changes require day/night, book/scroll, desktop/tablet/phone and all supported languages, including RTL. Inspect rendered pages as well as computed values. +- Follow the user's current branch and PR scope. Preserve unrelated changes; do not merge, enable auto-merge, deploy, change licensing or replace the publishing workflow without authorization. + +## Measurable acceptance, not another rewrite + +Follow [the merge acceptance ledger](web/docs/merge-acceptance.md) and [Tomislav's acceptance review](https://github.com/alux-network/alux-programming/pull/2#issuecomment-6420843360). Fix reproducible blockers; do not reopen the accepted architecture or redesign the readers. + +- Opening a chapter measures only its own layout resources. Do not paginate unseen chapters, even in background work, to obtain a global total. The owner selected explicitly labelled chapter progress until reliable exact-layout counts are available from real visits. +- Verify lifecycle cleanup and interrupted page turns with repeated browser scenarios; source inspection or one final screenshot is insufficient. +- English edits warn about potentially stale translations. Builds never silently mark translations reviewed or update their fingerprints. +- Verify a fresh tracked checkout with frozen installation, strict types, compiler lint, build/tests, deterministic repeated generated output and resolved links/anchors/assets. Add frontend CI without replacing original publishing. +- Mark each criterion **PASS / FAIL / NOT TESTED**, with command, actual engine/browser version and evidence. Mobile-profile Chromium/WebKit are simulations, not physical Android/iOS results. The owner has Android but no iPhone/iPad. +- Update this guide, `web/AGENTS.md` and the ledger together. Record remaining merge gates; local success is not authorization to merge or enable auto-merge. diff --git a/README.md b/README.md index 89fc06e..b6e186d 100644 --- a/README.md +++ b/README.md @@ -1,19 +1,38 @@ -# ALUX programming guidelines +# ALUX Programming -A book about **designing programs by meaning first** — specifying *what* a program means before deciding *how* it runs — in the style of Conal Elliott's Denotational Design, with a concrete path into Rust. +**English** · [简体中文](docs/README.zh.md) · [繁體中文](docs/README.zh-hant.md) · [日本語](docs/README.ja.md) · [한국어](docs/README.ko.md) · [Tiếng Việt](docs/README.vi.md) · [Deutsch](docs/README.de.md) · [Español](docs/README.es.md) · [Русский](docs/README.ru.md) · [Українська](docs/README.uk.md) · [العربية](docs/README.ar.md) -It provides the foundation for understanding and contributing to ALUX’s meaning-first codebase. +![ALUX Programming](web/public/social/alux-programming-en.jpg) -Built with [mdBook] and published to GitHub Pages: +A book about designing programs by first defining their meaning, then choosing how to execute them. It follows Conal Elliott’s denotational design approach through composition, laws and interpreters, with examples in Rust. -## What's inside +The book provides the foundation for understanding and contributing to ALUX’s meaning-first codebase. Written by Tomislav Grospic. -The book is organized in four parts (full table of contents in [`src/SUMMARY.md`](src/SUMMARY.md)): +[Read online](https://alux-network.github.io/alux-programming/) · [Contents](src/SUMMARY.md) · [Web reader setup](web/README.md) -- **The Semantic View** — denotations, compositionality, laws and interpretations, dependent types: the meaning-first foundation. -- **Design by Meaning in Rust** — capability algebras, derived meaning and composition, interpreters and effects, laws/scenarios/evidence, first-order programs, compiler pipelines, and a meaning-first workflow. -- **Concepts** — operational semantics, the expression problem, referential transparency, free monads, continuation-passing style, defunctionalization, branching and confluence. -- **Insights** — short essays connecting those concepts back to the semantic view (semantics to machines, the expression problem reloaded, referential transparency reloaded, and the EVM as an algebra). +## In the book + +- **The Semantic View** — denotations, compositionality, laws, interpretations and dependent types. +- **Design by Meaning in Rust** — capability traits, derived operations, interpreters, evidence and compiler pipelines. +- **Concepts** — operational semantics, free monads, continuations, defunctionalization and related mechanisms. +- **Insights** — connections between those mechanisms, program meaning and execution. + +## Multilingual web reader + +The web reader offers eleven languages, a paper book view and continuous scrolling, plus a plain technical view. A full contents page opens chapters directly. Book-view page numbers continue across chapters and adjust to the language, text size and window. Both worlds share font size, day/night mode, search and bookmarks. + +[Telegram and X preview](web/previews/social.html) · [Preview the reader](web/previews/index.html) · [Preview screenshots](web/previews/assets/) · [Reader maintenance guide](web/AGENTS.md) + +The preview HTML opens locally after checkout; its reader links require the local server below. The published online edition still uses mdBook. + +Requires Node.js 22+ and pnpm: + +```sh +pnpm --dir web install +pnpm --dir web dev +``` + +Open [127.0.0.1:4173](http://127.0.0.1:4173/). The reader selects an initial language and remembers a manual choice; all language editions remain available in the language menu. See [the maintenance guide](web/AGENTS.md) before adding content or changing the interface. ## Build and run locally diff --git a/docs/README.ar.md b/docs/README.ar.md new file mode 100644 index 0000000..8c76416 --- /dev/null +++ b/docs/README.ar.md @@ -0,0 +1,37 @@ +[English](../README.md) · [简体中文](README.zh.md) · [繁體中文](README.zh-hant.md) · [日本語](README.ja.md) · [한국어](README.ko.md) · [Tiếng Việt](README.vi.md) · [Deutsch](README.de.md) · [Español](README.es.md) · [Русский](README.ru.md) · [Українська](README.uk.md) · **العربية** + +
+ +# دليل البرمجة في ALUX + +![دليل البرمجة في ALUX](../web/public/social/alux-programming-ar.jpg) + +يشرح هذا الكتاب كيف نحدد معنى البرنامج أولًا، ثم نختار طريقة تنفيذه. يستند إلى التصميم الدلالي لدى Conal Elliott، ويربط التركيب والقوانين والمفسرات بسمات القدرات وأمثلة بلغة Rust. + +المؤلف: Tomislav Grospic. + +## محتويات الكتاب + +- الرؤية الدلالية: الدلالات والتركيبية والقوانين والتفسيرات والأنواع التابعة. +- التصميم بالمعنى في Rust: القدرات والعمليات المشتقة والمفسرات والأدلة وخطوط عمل المترجم. +- المفاهيم: الدلالات التشغيلية والمونادات الحرة والاستمراريات وإزالة الدوال والآليات المرتبطة بها. +- رؤى: صلة هذه الآليات بمعنى البرنامج وتنفيذه. + +## القراءة + +يدعم قارئ الويب إحدى عشرة لغة. يمكنك الاختيار بين تقليب الصفحات والتمرير المتصل وواجهة تقنية بسيطة، مع التحكم في حجم الخط والوضع الفاتح أو الداكن والبحث والإشارات المرجعية. يُحفظ اختيار اللغة اليدوي. + +يفتح الفهرس الكامل الفصول مباشرة. يستمر ترقيم الصفحات عبر الفصول ويُعاد حسابه عند تغيير اللغة أو حجم الخط أو النافذة. + +[فهرس النص الأصلي](../src/SUMMARY.md) · [Telegram / X](../web/previews/social.html) · [دليل الصيانة والتنسيق](../web/AGENTS.md) + +## التشغيل محليًا + +
+ +```sh +pnpm --dir web install +pnpm --dir web dev +``` + +[فتح النسخة العربية](http://127.0.0.1:4173/ar/) diff --git a/docs/README.de.md b/docs/README.de.md new file mode 100644 index 0000000..61d5cea --- /dev/null +++ b/docs/README.de.md @@ -0,0 +1,33 @@ +[English](../README.md) · [简体中文](README.zh.md) · [繁體中文](README.zh-hant.md) · [日本語](README.ja.md) · [한국어](README.ko.md) · [Tiếng Việt](README.vi.md) · **Deutsch** · [Español](README.es.md) · [Русский](README.ru.md) · [Українська](README.uk.md) · [العربية](README.ar.md) + +# ALUX-Programmierleitfaden + +![ALUX-Programmierleitfaden](../web/public/social/alux-programming-de.jpg) + +Dieses Buch beschreibt, wie man zuerst die Bedeutung eines Programms festlegt und danach seine Ausführung wählt. Es folgt Conal Elliotts denotationellem Entwurf und verbindet Komposition, Gesetze und Interpreter mit Capability-Traits und Beispielen in Rust. + +Autor: Tomislav Grospic. + +## Inhalt + +- Die semantische Sicht: Denotationen, Kompositionalität, Gesetze, Interpretationen und abhängige Typen. +- Entwurf nach Bedeutung in Rust: Capabilities, abgeleitete Operationen, Interpreter, Nachweise und Compiler-Pipelines. +- Konzepte: operationelle Semantik, freie Monaden, Fortsetzungen, Defunktionalisierung und verwandte Mechanismen. +- Einsichten: die Verbindung dieser Mechanismen mit Programmbedeutung und Ausführung. + +## Lesen + +Der Webreader unterstützt elf Sprachen. Zur Wahl stehen eine Buchansicht mit Seitenwechseln, fortlaufendes Scrollen und eine schlichte technische Ansicht. Schriftgröße, Tag-/Nachtmodus, Suche und Lesezeichen sind verfügbar. Eine manuell gewählte Sprache bleibt gespeichert. + +Das vollständige Inhaltsverzeichnis öffnet Kapitel direkt. Die Seitenzahlen laufen über Kapitelgrenzen hinweg und werden bei Änderungen von Sprache, Schriftgröße oder Fenstergröße neu berechnet. + +[Original-Inhaltsverzeichnis](../src/SUMMARY.md) · [Telegram / X](../web/previews/social.html) · [Wartungs- und Typografierichtlinien](../web/AGENTS.md) + +## Lokal starten + +```sh +pnpm --dir web install +pnpm --dir web dev +``` + +[Deutschen Reader öffnen](http://127.0.0.1:4173/de/) diff --git a/docs/README.es.md b/docs/README.es.md new file mode 100644 index 0000000..7fb3166 --- /dev/null +++ b/docs/README.es.md @@ -0,0 +1,33 @@ +[English](../README.md) · [简体中文](README.zh.md) · [繁體中文](README.zh-hant.md) · [日本語](README.ja.md) · [한국어](README.ko.md) · [Tiếng Việt](README.vi.md) · [Deutsch](README.de.md) · **Español** · [Русский](README.ru.md) · [Українська](README.uk.md) · [العربية](README.ar.md) + +# Guía de programación de ALUX + +![Guía de programación de ALUX](../web/public/social/alux-programming-es.jpg) + +Este libro explica cómo definir primero el significado de un programa y elegir después cómo ejecutarlo. Sigue el diseño denotacional de Conal Elliott y lleva la composición, las leyes y los intérpretes a ejemplos en Rust mediante traits de capacidades. + +Autor: Tomislav Grospic. + +## Contenido + +- La perspectiva semántica: denotaciones, composicionalidad, leyes, interpretaciones y tipos dependientes. +- Diseño por significado en Rust: capacidades, operaciones derivadas, intérpretes, evidencias y procesos de compilación. +- Conceptos: semántica operacional, mónadas libres, continuaciones, desfuncionalización y mecanismos relacionados. +- Reflexiones: la relación de estos mecanismos con el significado y la ejecución de los programas. + +## Leer + +El lector web admite once idiomas. Permite elegir entre páginas de libro, desplazamiento continuo y una vista técnica sencilla. Incluye tamaño de letra, modo claro/oscuro, búsqueda y marcadores. La elección manual del idioma se conserva. + +El índice completo abre cada capítulo directamente. La numeración continúa entre capítulos y se recalcula según el idioma, el tamaño de letra y la ventana. + +[Índice original](../src/SUMMARY.md) · [Telegram / X](../web/previews/social.html) · [Normas de mantenimiento y tipografía](../web/AGENTS.md) + +## Ejecutar en local + +```sh +pnpm --dir web install +pnpm --dir web dev +``` + +[Abrir el lector en español](http://127.0.0.1:4173/es/) diff --git a/docs/README.ja.md b/docs/README.ja.md new file mode 100644 index 0000000..feac71b --- /dev/null +++ b/docs/README.ja.md @@ -0,0 +1,33 @@ +[English](../README.md) · [简体中文](README.zh.md) · [繁體中文](README.zh-hant.md) · **日本語** · [한국어](README.ko.md) · [Tiếng Việt](README.vi.md) · [Deutsch](README.de.md) · [Español](README.es.md) · [Русский](README.ru.md) · [Українська](README.uk.md) · [العربية](README.ar.md) + +# ALUX プログラミングガイド + +![ALUX プログラミングガイド](../web/public/social/alux-programming-ja.jpg) + +プログラムが何を意味するかを定めてから、どう実行するかを選ぶための本です。Conal Elliott の指示的設計をもとに、合成、法則、インタープリターを説明し、Rust のケイパビリティ trait と具体例で実装につなげます。 + +著者:Tomislav Grospic。 + +## 本書の内容 + +- 意味論的な視点:指示、合成性、法則、解釈、依存型。 +- Rust における意味による設計:ケイパビリティ、導出された操作、インタープリター、根拠、コンパイラーパイプライン。 +- 概念:操作的意味論、自由モナド、継続、非関数化などの仕組み。 +- 考察:それらの仕組みと、プログラムの意味や実行との関係。 + +## 読む + +ウェブ版は11言語に対応しています。ページをめくる表示、スクロール表示、簡潔な技術文書の表示を選べます。文字サイズ、昼夜モード、検索、ブックマークを利用でき、手動で選んだ言語は次回も維持されます。 + +全体の目次から各章を直接開けます。ページ番号は章をまたいで続き、言語、文字サイズ、ウィンドウの大きさに応じて再計算されます。 + +[原文の目次](../src/SUMMARY.md) · [Telegram / X](../web/previews/social.html) · [保守・組版ガイド](../web/AGENTS.md) + +## ローカルで起動 + +```sh +pnpm --dir web install +pnpm --dir web dev +``` + +[日本語版を開く](http://127.0.0.1:4173/ja/) diff --git a/docs/README.ko.md b/docs/README.ko.md new file mode 100644 index 0000000..de4cd71 --- /dev/null +++ b/docs/README.ko.md @@ -0,0 +1,33 @@ +[English](../README.md) · [简体中文](README.zh.md) · [繁體中文](README.zh-hant.md) · [日本語](README.ja.md) · **한국어** · [Tiếng Việt](README.vi.md) · [Deutsch](README.de.md) · [Español](README.es.md) · [Русский](README.ru.md) · [Українська](README.uk.md) · [العربية](README.ar.md) + +# ALUX 프로그래밍 가이드 + +![ALUX 프로그래밍 가이드](../web/public/social/alux-programming-ko.jpg) + +프로그램이 무엇을 의미하는지 먼저 정의하고, 실행 방법은 그다음에 선택하는 설계를 다룹니다. Conal Elliott의 지시적 설계를 바탕으로 합성, 법칙, 해석기를 설명하고 Rust의 능력 trait와 예제를 통해 구현으로 이어갑니다. + +저자: Tomislav Grospic. + +## 책의 구성 + +- 의미론적 관점: 지시, 합성성, 법칙, 해석, 의존 타입. +- Rust에서 의미로 설계하기: 능력, 파생 연산, 해석기, 증거, 컴파일러 파이프라인. +- 개념: 연산 의미론, 자유 모나드, 연속, 비함수화 등의 메커니즘. +- 통찰: 이러한 메커니즘과 프로그램의 의미 및 실행 사이의 관계. + +## 읽기 + +웹 리더는 11개 언어를 지원합니다. 책장 넘기기, 스크롤, 간결한 기술 문서 보기 중에서 선택할 수 있습니다. 글자 크기, 주야간 모드, 검색, 책갈피를 제공하며 직접 선택한 언어를 기억합니다. + +전체 목차에서 각 장을 바로 열 수 있습니다. 페이지 번호는 장이 바뀌어도 이어지며 언어, 글자 크기, 창 크기에 따라 다시 계산됩니다. + +[원문 목차](../src/SUMMARY.md) · [Telegram / X](../web/previews/social.html) · [유지보수 및 조판 지침](../web/AGENTS.md) + +## 로컬 실행 + +```sh +pnpm --dir web install +pnpm --dir web dev +``` + +[한국어 리더 열기](http://127.0.0.1:4173/ko/) diff --git a/docs/README.ru.md b/docs/README.ru.md new file mode 100644 index 0000000..02262ac --- /dev/null +++ b/docs/README.ru.md @@ -0,0 +1,33 @@ +[English](../README.md) · [简体中文](README.zh.md) · [繁體中文](README.zh-hant.md) · [日本語](README.ja.md) · [한국어](README.ko.md) · [Tiếng Việt](README.vi.md) · [Deutsch](README.de.md) · [Español](README.es.md) · **Русский** · [Українська](README.uk.md) · [العربية](README.ar.md) + +# Руководство по программированию ALUX + +![Руководство по программированию ALUX](../web/public/social/alux-programming-ru.jpg) + +Эта книга о проектировании, в котором сначала определяют смысл программы, а затем выбирают способ её выполнения. Она развивает денотационный подход Конала Эллиотта и связывает композицию, законы и интерпретаторы с трейтами возможностей и примерами на Rust. + +Автор: Tomislav Grospic. + +## Содержание + +- Семантический взгляд: денотации, композиционность, законы, интерпретации и зависимые типы. +- Проектирование по смыслу в Rust: возможности, производные операции, интерпретаторы, свидетельства и конвейеры компилятора. +- Концепции: операционная семантика, свободные монады, продолжения, дефункционализация и связанные механизмы. +- Размышления: связь этих механизмов со смыслом и выполнением программ. + +## Чтение + +Веб-версия поддерживает одиннадцать языков. Доступны перелистывание страниц, непрерывная прокрутка и лаконичный технический режим. Можно менять размер шрифта и светлую или тёмную тему, искать по книге и сохранять закладки. Выбранный вручную язык сохраняется. + +Полное оглавление открывает главы напрямую. Нумерация страниц продолжается между главами и пересчитывается при изменении языка, размера шрифта или окна. + +[Оглавление оригинала](../src/SUMMARY.md) · [Telegram / X](../web/previews/social.html) · [Правила сопровождения и оформления](../web/AGENTS.md) + +## Локальный запуск + +```sh +pnpm --dir web install +pnpm --dir web dev +``` + +[Открыть русскую версию](http://127.0.0.1:4173/ru/) diff --git a/docs/README.uk.md b/docs/README.uk.md new file mode 100644 index 0000000..bbb8209 --- /dev/null +++ b/docs/README.uk.md @@ -0,0 +1,33 @@ +[English](../README.md) · [简体中文](README.zh.md) · [繁體中文](README.zh-hant.md) · [日本語](README.ja.md) · [한국어](README.ko.md) · [Tiếng Việt](README.vi.md) · [Deutsch](README.de.md) · [Español](README.es.md) · [Русский](README.ru.md) · **Українська** · [العربية](README.ar.md) + +# Посібник із програмування ALUX + +![Посібник із програмування ALUX](../web/public/social/alux-programming-uk.jpg) + +Ця книжка про проєктування, у якому спочатку визначають зміст програми, а потім обирають спосіб її виконання. Вона розвиває денотаційний підхід Конала Елліотта та пов’язує композицію, закони й інтерпретатори з трейтами можливостей і прикладами мовою Rust. + +Автор: Tomislav Grospic. + +## Зміст + +- Семантичний погляд: денотації, композиційність, закони, інтерпретації та залежні типи. +- Проєктування за змістом у Rust: можливості, похідні операції, інтерпретатори, свідчення та конвеєри компілятора. +- Концепції: операційна семантика, вільні монади, продовження, дефункціоналізація та пов’язані механізми. +- Міркування: зв’язок цих механізмів зі змістом і виконанням програм. + +## Читати + +Вебверсія підтримує одинадцять мов. Можна обрати перегортання сторінок, безперервне прокручування або простий технічний режим. Доступні розмір шрифту, світла й темна теми, пошук і закладки. Вибрана вручну мова зберігається. + +Повний зміст відкриває розділи безпосередньо. Нумерація сторінок продовжується між розділами й перераховується зі зміною мови, розміру шрифту або вікна. + +[Зміст оригіналу](../src/SUMMARY.md) · [Telegram / X](../web/previews/social.html) · [Правила супроводу й оформлення](../web/AGENTS.md) + +## Локальний запуск + +```sh +pnpm --dir web install +pnpm --dir web dev +``` + +[Відкрити українську версію](http://127.0.0.1:4173/uk/) diff --git a/docs/README.vi.md b/docs/README.vi.md new file mode 100644 index 0000000..aa0c2ed --- /dev/null +++ b/docs/README.vi.md @@ -0,0 +1,33 @@ +[English](../README.md) · [简体中文](README.zh.md) · [繁體中文](README.zh-hant.md) · [日本語](README.ja.md) · [한국어](README.ko.md) · **Tiếng Việt** · [Deutsch](README.de.md) · [Español](README.es.md) · [Русский](README.ru.md) · [Українська](README.uk.md) · [العربية](README.ar.md) + +# Hướng dẫn lập trình ALUX + +![Hướng dẫn lập trình ALUX](../web/public/social/alux-programming-vi.jpg) + +Cuốn sách trình bày cách xác định ý nghĩa của chương trình trước khi chọn cách thực thi. Dựa trên thiết kế theo ngữ nghĩa biểu thị của Conal Elliott, sách giải thích phép hợp thành, các luật và bộ thông dịch, rồi áp dụng chúng qua các trait năng lực và ví dụ bằng Rust. + +Tác giả: Tomislav Grospic. + +## Nội dung + +- Góc nhìn ngữ nghĩa: nghĩa biểu thị, tính hợp thành, các luật, cách diễn giải và kiểu phụ thuộc. +- Thiết kế theo ý nghĩa trong Rust: năng lực, phép toán dẫn xuất, bộ thông dịch, bằng chứng và quy trình biên dịch. +- Khái niệm: ngữ nghĩa thao tác, monad tự do, continuation, khử hàm và các cơ chế liên quan. +- Góc nhìn sâu: mối liên hệ giữa các cơ chế đó với ý nghĩa và cách thực thi chương trình. + +## Đọc sách + +Bản web hỗ trợ 11 ngôn ngữ, với chế độ lật trang, cuộn liên tục hoặc giao diện tài liệu kỹ thuật gọn gàng. Bạn có thể đổi cỡ chữ, chế độ sáng/tối, tìm kiếm và lưu dấu trang. Ngôn ngữ được chọn thủ công sẽ được ghi nhớ. + +Mục lục mở trực tiếp từng chương. Số trang nối tiếp qua các chương và được tính lại theo ngôn ngữ, cỡ chữ và kích thước cửa sổ. + +[Mục lục bản gốc](../src/SUMMARY.md) · [Telegram / X](../web/previews/social.html) · [Hướng dẫn bảo trì và trình bày](../web/AGENTS.md) + +## Chạy trên máy + +```sh +pnpm --dir web install +pnpm --dir web dev +``` + +[Mở bản tiếng Việt](http://127.0.0.1:4173/vi/) diff --git a/docs/README.zh-hant.md b/docs/README.zh-hant.md new file mode 100644 index 0000000..e4a1cc1 --- /dev/null +++ b/docs/README.zh-hant.md @@ -0,0 +1,33 @@ +[English](../README.md) · [简体中文](README.zh.md) · **繁體中文** · [日本語](README.ja.md) · [한국어](README.ko.md) · [Tiếng Việt](README.vi.md) · [Deutsch](README.de.md) · [Español](README.es.md) · [Русский](README.ru.md) · [Українська](README.uk.md) · [العربية](README.ar.md) + +# ALUX 程式設計指南 + +![ALUX 程式設計指南](../web/public/social/alux-programming-zh-hant.jpg) + +這本書從程式的含義出發談設計:先定義清楚的語義、組合規則和定律,再選擇實作方式。書中沿用 Conal Elliott 的指稱設計思路,透過 Rust 的能力 trait、解釋器和證據落實到程式碼中。 + +作者:Tomislav Grospic。 + +## 書中內容 + +- 語義視角:指稱、組合性、定律、解釋與依賴型別。 +- Rust 中的語義驅動設計:能力、衍生操作、解釋器、證據與編譯器流水線。 +- 概念:操作語義、自由單子、延續、去函式化等程式設計機制。 +- 洞見:這些機制與程式含義、執行方式之間的聯繫。 + +## 閱讀 + +網頁版支援十一種語言,可選擇翻頁、捲動或簡潔的技術閱讀介面,並提供字級、日夜模式、搜尋和書籤。首次進入會選擇初始語言,也可手動切換;手動選擇會被記住。 + +全書目錄可直接進入章節;翻頁閱讀的頁碼跨章連續,並隨語言、字級和視窗大小重新計算。 + +[原文目錄](../src/SUMMARY.md) · [Telegram / X](../web/previews/social.html) · [維護與排版規範](../web/AGENTS.md) + +## 在本機執行 + +```sh +pnpm --dir web install +pnpm --dir web dev +``` + +[開啟繁體中文閱讀入口](http://127.0.0.1:4173/zh-hant/) diff --git a/docs/README.zh.md b/docs/README.zh.md new file mode 100644 index 0000000..524f66d --- /dev/null +++ b/docs/README.zh.md @@ -0,0 +1,33 @@ +[English](../README.md) · **简体中文** · [繁體中文](README.zh-hant.md) · [日本語](README.ja.md) · [한국어](README.ko.md) · [Tiếng Việt](README.vi.md) · [Deutsch](README.de.md) · [Español](README.es.md) · [Русский](README.ru.md) · [Українська](README.uk.md) · [العربية](README.ar.md) + +# ALUX 编程指南 + +![ALUX 编程指南](../web/public/social/alux-programming-zh.jpg) + +这本书从程序的含义出发讲设计:先定义清楚的语义、组合规则和定律,再选择实现方式。书中沿用 Conal Elliott 的指称设计思路,通过 Rust 的能力 trait、解释器和证据把它落到代码中。 + +作者:Tomislav Grospic。 + +## 书中内容 + +- 语义视角:指称、组合性、定律、解释与依赖类型。 +- Rust 中的语义驱动设计:能力、派生操作、解释器、证据与编译器流水线。 +- 概念:操作语义、自由单子、延续、去函数化等编程机制。 +- 洞见:这些机制与程序含义、执行方式之间的联系。 + +## 阅读 + +网页版支持十一种语言,可选择翻页、滚动或简洁的技术阅读界面,支持字号、昼夜模式、搜索和书签。首次进入会选择初始语言,也可手动切换;手动选择会被记住。 + +全书目录可直接进入章节;翻页阅读的页码跨章连续,并随语言、字号和窗口大小重新计算。 + +[原文目录](../src/SUMMARY.md) · [Telegram / X](../web/previews/social.html) · [维护与排版规范](../web/AGENTS.md) + +## 本地运行 + +```sh +pnpm --dir web install +pnpm --dir web dev +``` + +[打开中文阅读入口](http://127.0.0.1:4173/zh/) diff --git a/src/about.ar.md b/src/about.ar.md new file mode 100644 index 0000000..d5e94cf --- /dev/null +++ b/src/about.ar.md @@ -0,0 +1,36 @@ + + +# حول الكتاب {#about} + +يختزل هذا الكتاب طريقة للتفكير في البرمجيات مستلهمة من **Denotational Design** لكونال إليوت. والفكرة الأساسية بسيطة وعميقة: + +```admonish note title="التصميم الدلالي" +*حدّد معنى البرنامج قبل تقرير كيفية تشغيله.* +``` + +وفق هذا المنظور، الحساب ليس تسلسلًا معتمًا من الخطوات، بل كيان رياضي شفاف. نبدأ بـ **مواصفات** بوصفها أوصافًا نقية وتركيبية لـ *ما* يعنيه البرنامج. ويُعبّر عنها ببنى جبرية، غالبًا في صورة سمات أو تواقيع أنواع. أما **التنفيذ**، أي *كيفية* تحقيق تلك المعاني، فهو طبقة منفصلة قابلة للاستبدال. + +بفصل المعنى عن الآليات، نكسب: + +* **الوضوح** — تُقرأ البرامج كتعريفات دقيقة. +* **قابلية التركيب** — تتوافق الأجزاء جبريًا. +* **قابلية إعادة الهيكلة** — يظل المعنى ثابتًا بينما يتطور التنفيذ. +* **الصحة** — يصبح الاستدلال على البرامج معادليًا لا تشغيليًا. + +تهدف هذه الإرشادات إلى تقديم تقنيات عملية لتطبيق هذا الأسلوب في لغات البرمجة الحديثة، ولا سيما Rust، مع الحفاظ على أناقة جذوره الرياضية ودقتها. + +يميز الكتاب عمدًا بين ثلاثة مستويات: + +* يحدد **المعنى** القيم والعلاقات والتحويلات قيد التصميم. +* يختار **التمثيل** كيفية ترميز تلك المعاني في الأنواع والبيانات. +* يختار **التنفيذ** كيفية تشغيل التمثيل على آلة. + +يلهم ALUX وTolang كثيرًا من الأمثلة، لكن فهم هذه الطبعة لا يتطلبهما. فالكتاب يطور المفردات أولًا. + +## مرجع mdBook {#reference-of-mdbook} + +[توثيق mdBook](https://rust-lang.github.io/mdBook/index.html) + +## مرجع ملحق mdbook **admonish** (مربعات التلميحات) {#reference-of-admonish-mdbook-plugin-tooltip-boxes} + +[توثيق admonish](https://tommilligan.github.io/mdbook-admonish/) diff --git a/src/about.de.md b/src/about.de.md new file mode 100644 index 0000000..a07a455 --- /dev/null +++ b/src/about.de.md @@ -0,0 +1,36 @@ + + +# Über {#about} + +Dieses Buch verdichtet eine von Conal Elliotts **Denotational Design** inspirierte Denkweise über Software. Die Grundidee ist einfach und zugleich tiefgreifend: + +```admonish note title="Denotational Design" +*Lege die Bedeutung eines Programms fest, bevor du entscheidest, wie es ausgeführt wird.* +``` + +Aus dieser Sicht ist Berechnung keine undurchsichtige Abfolge von Schritten, sondern ein transparentes mathematisches Objekt. Wir beginnen mit **Spezifikationen** als reinen, kompositionalen Beschreibungen dessen, *was* ein Programm bedeutet. Sie werden als algebraische Strukturen ausgedrückt, oft in Form von Traits oder Typsignaturen. Die **Implementierung** beschreibt getrennt und austauschbar, *wie* diese Bedeutungen realisiert werden. + +Wenn wir Bedeutung von Mechanik trennen, gewinnen wir: + +* **Klarheit** — Programme lesen sich wie präzise Definitionen. +* **Komponierbarkeit** — Teile fügen sich algebraisch zusammen. +* **Refaktorisierbarkeit** — Die Bedeutung bleibt fest, während sich die Implementierung weiterentwickelt. +* **Korrektheit** — Über Programme lässt sich mit Gleichungen statt anhand operationaler Abläufe schlussfolgern. + +Diese Richtlinien sollen praktische Techniken vermitteln, um diesen Stil in modernen Programmiersprachen — insbesondere Rust — anzuwenden, ohne Eleganz und Strenge seiner mathematischen Wurzeln einzubüßen. + +Das Buch unterscheidet bewusst drei Ebenen: + +* **Bedeutung** legt fest, welche Werte, Relationen und Transformationen entworfen werden. +* **Repräsentation** wählt, wie diese Bedeutungen in Typen und Daten kodiert werden. +* **Ausführung** legt fest, wie eine Repräsentation auf einer Maschine läuft. + +ALUX und Tolang liefern die Motivation für viele Beispiele, sind aber nicht erforderlich, um dieser Ausgabe zu folgen. Das Buch führt zunächst das Vokabular ein. + +## Dokumentation zu mdBook {#reference-of-mdbook} + +[mdBook-Dokumentation](https://rust-lang.github.io/mdBook/index.html) + +## Referenz zum **admonish**\-mdbook-Plugin (Hinweisfelder) {#reference-of-admonish-mdbook-plugin-tooltip-boxes} + +[admonish-Dokumentation](https://tommilligan.github.io/mdbook-admonish/) diff --git a/src/about.es.md b/src/about.es.md new file mode 100644 index 0000000..e94585a --- /dev/null +++ b/src/about.es.md @@ -0,0 +1,36 @@ + + +# Acerca del libro {#about} + +Este libro condensa una manera de pensar sobre el software inspirada en el **diseño denotacional** de Conal Elliott. La idea central es sencilla, pero profunda: + +```admonish note title="Diseño denotacional" +*Define el significado de un programa antes de decidir cómo se ejecuta.* +``` + +Desde este punto de vista, el cálculo no es una secuencia opaca de pasos, sino un objeto matemático transparente. Empezamos con **especificaciones** como descripciones puras y composicionales de *lo que* significa un programa. Se expresan como estructuras algebraicas, a menudo en forma de rasgos o signaturas de tipos. La **implementación**, es decir, *cómo* se realizan esos significados, constituye una capa separada e intercambiable. + +Al separar el significado de la mecánica, obtenemos: + +* **Claridad**: los programas se leen como definiciones precisas. +* **Componibilidad**: las partes encajan algebraicamente. +* **Capacidad de refactorización**: el significado permanece fijo mientras evoluciona la implementación. +* **Corrección**: el razonamiento sobre programas se vuelve ecuacional y no operacional. + +Estas pautas buscan ofrecer técnicas prácticas para aplicar este estilo en lenguajes de programación modernos, especialmente Rust, sin perder la elegancia ni el rigor de sus raíces matemáticas. + +El libro distingue intencionalmente tres niveles: + +* **Significado** define qué valores, relaciones y transformaciones se diseñan. +* **Representación** determina cómo se codifican esos significados en tipos y datos. +* **Ejecución** determina cómo se ejecuta una representación en una máquina. + +ALUX y Tolang motivan muchos de los ejemplos, pero no es necesario conocerlos para seguir esta edición. El libro desarrolla primero el vocabulario. + +## Documentación de mdbook {#reference-of-mdbook} + +[Documentación de mdBook](https://rust-lang.github.io/mdBook/index.html) + +## Documentación del plugin mdbook **admonish** (cuadros emergentes) {#reference-of-admonish-mdbook-plugin-tooltip-boxes} + +[Documentación de admonish](https://tommilligan.github.io/mdbook-admonish/) diff --git a/src/about.ja.md b/src/about.ja.md new file mode 100644 index 0000000..f9dfea7 --- /dev/null +++ b/src/about.ja.md @@ -0,0 +1,36 @@ + + +# 概要 {#about} + +本書では、Conal Elliottの**Denotational Design**に着想を得た、ソフトウェアについての考え方をまとめています。中核となる考えは単純でありながら深遠です。 + +```admonish note title="Denotational Design" +*プログラムの実行方法を決める前に、その意味を定義する。* +``` + +この考え方では、計算は不透明な手順の列ではなく、透明な数学的対象です。まず、プログラムが*何を*意味するかを純粋かつ合成可能に記述する**仕様**から始めます。多くの場合、代数構造、トレイト、型シグネチャで表現します。意味を*どう*実現するかを担う**実装**は、独立して交換可能な層です。 + +意味と仕組みを分けることで、次の利点を得られます。 + +* **明快さ** — プログラムが正確な定義のように読める。 +* **合成可能性** — 部品が代数的に組み合わさる。 +* **リファクタリングのしやすさ** — 実装が進化しても意味は固定される。 +* **正しさ** — 操作手順ではなく等式でプログラムを推論できる。 + +本書のガイドラインは、数学的な基盤の優雅さと厳密さを失わずに、現代のプログラミング言語、特にRustでこの設計を実践する技法を提供します。 + +本書では、意図的に三つの水準を区別します。 + +* **意味**では、どの値、関係、変換を設計しているかを定める。 +* **表現**では、その意味を型やデータにどう符号化するかを選ぶ。 +* **実行**では、機械上で表現をどう動かすかを選ぶ。 + +例の多くはALUXとTolangに着想を得ていますが、この版を読むためにそれらを知る必要はありません。本書ではまず語彙を定めます。 + +## mdbookの参照 {#reference-of-mdbook} + +[mdBookドキュメント](https://rust-lang.github.io/mdBook/index.html) + +## **admonish** mdbookプラグイン(ツールチップ表示)のリファレンス {#reference-of-admonish-mdbook-plugin-tooltip-boxes} + +[admonishドキュメント](https://tommilligan.github.io/mdbook-admonish/) diff --git a/src/about.ko.md b/src/about.ko.md new file mode 100644 index 0000000..b6422fd --- /dev/null +++ b/src/about.ko.md @@ -0,0 +1,36 @@ + + +# 소개 {#about} + +이 책은 Conal Elliott의 **Denotational Design**에서 영감을 얻은 소프트웨어 사고방식을 정리합니다. 핵심 아이디어는 단순하지만 깊은 의미가 있습니다: + +```admonish note title="표시적 설계" +*프로그램이 어떻게 실행될지 정하기 전에 그 의미를 정의하세요.* +``` + +이 관점에서 계산은 불투명한 단계의 나열이 아니라 투명한 수학적 대상입니다. 프로그램이 *무엇을* 의미하는지 순수하고 합성적으로 설명하는 **명세**에서 시작합니다. 대수 구조, 흔히 트레이트나 타입 시그니처 형태로 표현합니다. 그 의미를 *어떻게* 실현하는지에 해당하는 **구현**은 별도로 두고 서로 바꿀 수 있게 합니다. + +의미와 작동 장치를 분리하면 다음을 얻습니다: + +* **명확성** — 프로그램이 정확한 정의처럼 읽힙니다. +* **합성 가능성** — 부분들이 대수적으로 맞물립니다. +* **리팩터링 가능성** — 구현이 발전해도 의미는 그대로입니다. +* **정확성** — 프로그램을 작동 방식이 아니라 등식으로 추론합니다. + +이 지침은 수학적 토대의 우아함과 엄밀성을 잃지 않고, 특히 Rust 같은 현대 프로그래밍 언어에서 이 스타일을 적용할 실용적인 기법을 제공합니다. + +이 책은 세 수준을 의도적으로 구분합니다: + +* **의미**는 설계할 값, 관계, 변환이 무엇인지 명시합니다. +* **표현**은 그 의미를 타입과 데이터로 인코딩하는 방식을 선택합니다. +* **실행**은 표현이 기계에서 실행되는 방식을 선택합니다. + +많은 예시가 ALUX와 Tolang에서 동기를 얻었지만, 이 판을 따라가는 데 두 프로젝트가 필요한 것은 아닙니다. 이 책은 어휘부터 설명합니다. + +## mdbook 참고 자료 {#reference-of-mdbook} + +[mdBook 문서](https://rust-lang.github.io/mdBook/index.html) + +## **admonish** mdbook 플러그인 참고 자료 (툴팁 상자) {#reference-of-admonish-mdbook-plugin-tooltip-boxes} + +[admonish 문서](https://tommilligan.github.io/mdbook-admonish/) diff --git a/src/about.ru.md b/src/about.ru.md new file mode 100644 index 0000000..638c5c2 --- /dev/null +++ b/src/about.ru.md @@ -0,0 +1,36 @@ + + +# О книге {#about} + +В этой книге изложен способ мышления о программном обеспечении, вдохновлённый **денотационным проектированием** Конала Эллиотта. Основная мысль проста, но глубока: + +```admonish note title="Денотационное проектирование" +*Сначала определите смысл программы, а уже затем решайте, как она будет выполняться.* +``` + +С этой точки зрения вычисление — не непрозрачная последовательность шагов, а прозрачный математический объект. Мы начинаем со **спецификаций** — чистых композиционных описаний того, *что* означает программа. Они выражаются алгебраическими структурами, часто в форме трейтов или сигнатур типов. **Реализация**, то есть *как* воплощаются эти смыслы, образует отдельный взаимозаменяемый слой. + +Разделение смысла и механизмов даёт: + +* **Ясность** — программы читаются как точные определения. +* **Композиционность** — части соединяются алгебраически. +* **Удобство рефакторинга** — смысл остаётся неизменным, пока развивается реализация. +* **Корректность** — о программах можно рассуждать через равенства, а не через их операционное исполнение. + +Эти рекомендации предлагают практические способы применять такой подход в современных языках программирования, прежде всего в Rust, сохраняя элегантность и строгость его математических истоков. + +В книге намеренно различаются три уровня: + +* **Смысл** определяет, какие значения, отношения и преобразования проектируются. +* **Представление** определяет, как эти смыслы кодируются в типах и данных. +* **Выполнение** определяет, как представление выполняется на машине. + +ALUX и Tolang вдохновили многие примеры, но для чтения этого издания знакомство с ними не требуется. Сначала книга формирует необходимый словарь понятий. + +## Документация mdBook {#reference-of-mdbook} + +[Документация mdBook](https://rust-lang.github.io/mdBook/index.html) + +## Справка по плагину mdbook **admonish** (всплывающие подсказки) {#reference-of-admonish-mdbook-plugin-tooltip-boxes} + +[Документация admonish](https://tommilligan.github.io/mdbook-admonish/) diff --git a/src/about.uk.md b/src/about.uk.md new file mode 100644 index 0000000..b40fdbd --- /dev/null +++ b/src/about.uk.md @@ -0,0 +1,36 @@ + + +# Про книжку {#about} + +У книжці узагальнено спосіб мислення про програмне забезпечення, натхненний **денотаційним проєктуванням** Конала Елліотта. Основна ідея проста, але глибока: + +```admonish note title="Денотаційне проєктування" +*Спершу визначте значення програми, а потім вирішуйте, як вона виконуватиметься.* +``` + +Згідно з цим поглядом, обчислення — не непрозора послідовність кроків, а прозорий математичний об’єкт. Починаємо зі **специфікацій** як чистих композиційних описів *того, що* означає програма. Вони виражаються алгебраїчними структурами, часто у формі трейтів або сигнатур типів. **Реалізація**, тобто *те, як* втілюються ці значення, є окремим взаємозамінним рівнем. + +Розділивши значення й механізми, отримуємо: + +* **Ясність** — програми читаються як точні визначення. +* **Композиційність** — частини алгебраїчно поєднуються. +* **Можливість рефакторингу** — значення залишається незмінним, поки розвивається реалізація. +* **Коректність** — міркування про програми спирається на рівняння, а не на порядок виконання. + +Ці настанови мають надати практичні методи застосування такого підходу в сучасних мовах програмування, особливо Rust, не втрачаючи витонченості й строгості його математичних основ. + +Книжка навмисно розрізняє три рівні: + +* **Значення** визначає, які значення, відношення й перетворення проєктуються. +* **Представлення** визначає, як кодувати ці значення в типах і даних. +* **Виконання** визначає, як запускати представлення на машині. + +ALUX і Tolang надихають багато прикладів, але для читання цього видання вони не потрібні. Спершу книжка розвиває потрібну термінологію. + +## Документація mdBook {#reference-of-mdbook} + +[Документація mdBook](https://rust-lang.github.io/mdBook/index.html) + +## Довідник плагіна mdBook **admonish** (блоки з підказками) {#reference-of-admonish-mdbook-plugin-tooltip-boxes} + +[Документація admonish](https://tommilligan.github.io/mdbook-admonish/) diff --git a/src/about.vi.md b/src/about.vi.md new file mode 100644 index 0000000..6ca6fbf --- /dev/null +++ b/src/about.vi.md @@ -0,0 +1,36 @@ + + +# Giới thiệu {#about} + +Cuốn sách này chắt lọc một cách tư duy về phần mềm lấy cảm hứng từ **Thiết kế theo ngữ nghĩa** của Conal Elliott. Ý tưởng cốt lõi đơn giản nhưng sâu sắc: + +```admonish note title="Thiết kế theo ngữ nghĩa" +*Định nghĩa ý nghĩa của chương trình trước khi quyết định cách chạy nó.* +``` + +Theo góc nhìn này, tính toán không phải chuỗi bước mờ đục mà là đối tượng toán học trong suốt. Ta bắt đầu bằng **đặc tả** dưới dạng mô tả thuần, có thể hợp thành về *ý nghĩa* của chương trình. Chúng được biểu đạt thành cấu trúc đại số, thường dưới dạng đặc trưng hoặc chữ ký kiểu. **Cách triển khai** — *cách thức* hiện thực hóa những ý nghĩa ấy — là lớp riêng biệt, có thể thay thế. + +Bằng cách tách ý nghĩa khỏi cơ chế, ta có được: + +* **Rõ ràng** — chương trình đọc như định nghĩa chính xác. +* **Khả năng hợp thành** — các phần kết hợp với nhau theo đại số. +* **Khả năng tái cấu trúc** — ý nghĩa giữ nguyên khi cách triển khai phát triển. +* **Tính đúng đắn** — lập luận về chương trình dựa trên phương trình, không dựa trên vận hành. + +Các hướng dẫn này nhằm cung cấp kỹ thuật thực tiễn để áp dụng phong cách đó trong ngôn ngữ lập trình hiện đại, đặc biệt là Rust, mà không làm mất vẻ thanh nhã và tính chặt chẽ từ cội nguồn toán học. + +Cuốn sách chủ ý phân biệt ba cấp độ: + +* **Ý nghĩa** nêu các giá trị, quan hệ và phép biến đổi đang được thiết kế. +* **Biểu diễn** chọn cách mã hóa các ý nghĩa đó thành kiểu và dữ liệu. +* **Thực thi** chọn cách một biểu diễn chạy trên máy. + +ALUX và Tolang gợi ý nhiều ví dụ, nhưng bạn không cần biết chúng để theo dõi ấn bản này. Trước hết, cuốn sách phát triển từ vựng. + +## Tài liệu tham khảo mdbook {#reference-of-mdbook} + +[Tài liệu mdBook](https://rust-lang.github.io/mdBook/index.html) + +## Tài liệu tham khảo plugin mdbook **admonish** (các hộp chú giải) {#reference-of-admonish-mdbook-plugin-tooltip-boxes} + +[Tài liệu admonish](https://tommilligan.github.io/mdbook-admonish/) diff --git a/src/about.zh-hant.md b/src/about.zh-hant.md new file mode 100644 index 0000000..3972397 --- /dev/null +++ b/src/about.zh-hant.md @@ -0,0 +1,36 @@ + + +# 關於 {#about} + +本書提煉了一種軟體思維方式,靈感來自 Conal Elliott 的**指稱設計**。核心思想簡單而深刻: + +```admonish note title="指稱設計" +*先定義程式的含義,再決定它如何執行。* +``` + +在這一視角下,計算不是不透明的步驟序列,而是透明的數學物件。我們從**規範**開始,以純粹且可組合的方式描述程式*意味著什麼*。這些描述採用代數結構表達,通常表現為 trait 或型別簽名。**實作**——這些含義*如何*實現出來——則是獨立且可互換的一層。 + +將含義與機制分離後,我們便能獲得: + +* **清晰性**——程式讀起來像精確的定義。 +* **可組合性**——各部分可以按代數規則組合。 +* **可重構性**——實作持續演進時,含義仍保持不變。 +* **正確性**——推理程式時可以採用等式推理,而非操作層面的推理。 + +這些指南旨在提供實用技術,幫助讀者在現代程式語言中運用這一風格,尤其是 Rust,同時保留其數學根基的優雅與嚴謹。 + +本書有意區分三個層次: + +* **含義**說明所設計的值、關係與變換。 +* **表示**選擇如何將這些含義編碼為型別與資料。 +* **執行**選擇如何讓一種表示在機器上執行。 + +ALUX 與 Tolang 為許多示例提供了背景,但閱讀本版並不需要了解它們。本書會先介紹相關詞彙。 + +## mdBook 參考 {#reference-of-mdbook} + +[mdBook 文件](https://rust-lang.github.io/mdBook/index.html) + +## **admonish** mdbook 外掛參考(提示框) {#reference-of-admonish-mdbook-plugin-tooltip-boxes} + +[admonish 文件](https://tommilligan.github.io/mdbook-admonish/) diff --git a/src/about.zh.md b/src/about.zh.md new file mode 100644 index 0000000..d51fb32 --- /dev/null +++ b/src/about.zh.md @@ -0,0 +1,36 @@ + + +# 关于 {#about} + +本书提炼了一种软件思维方式,灵感来自 Conal Elliott 的**指称设计**。核心思想简单而深刻: + +```admonish note title="指称设计" +*先定义程序的含义,再决定它如何运行。* +``` + +在这一视角下,计算不是不透明的步骤序列,而是透明的数学对象。我们从**规范**开始,以纯粹且可组合的方式描述程序*意味着什么*。这些描述采用代数结构表达,通常表现为 trait 或类型签名。**实现**——这些含义*如何*实现出来——则是独立且可互换的一层。 + +将含义与机制分离后,我们便能获得: + +* **清晰性**——程序读起来像精确的定义。 +* **可组合性**——各部分可以按代数规则组合。 +* **可重构性**——实现持续演进时,含义仍保持不变。 +* **正确性**——推理程序时可以采用等式推理,而非操作层面的推理。 + +这些指南旨在提供实用技术,帮助读者在现代编程语言中运用这一风格,尤其是 Rust,同时保留其数学根基的优雅与严谨。 + +本书有意区分三个层次: + +* **含义**说明所设计的值、关系与变换。 +* **表示**选择如何将这些含义编码为类型与数据。 +* **执行**选择如何让一种表示在机器上运行。 + +ALUX 与 Tolang 为许多示例提供了背景,但阅读本版并不需要了解它们。本书会先介绍相关词汇。 + +## mdBook 参考 {#reference-of-mdbook} + +[mdBook 文档](https://rust-lang.github.io/mdBook/index.html) + +## **admonish** mdbook 插件参考(提示框) {#reference-of-admonish-mdbook-plugin-tooltip-boxes} + +[admonish 文档](https://tommilligan.github.io/mdbook-admonish/) diff --git a/src/concepts/branching.ar.md b/src/concepts/branching.ar.md new file mode 100644 index 0000000..6770405 --- /dev/null +++ b/src/concepts/branching.ar.md @@ -0,0 +1,208 @@ + + +# التفرع والتلاقي {#branching-and-confluence} + +```admonish tip title="ذات صلة" +الرؤية الدلالية: [الدلالات والتركيبية](../denotational-design/denotations.md)، [القوانين والتفسيرات](../denotational-design/laws-and-interpretations.md) +التصميم انطلاقًا من المعنى في Rust: [القوانين والسيناريوهات والأدلة](../rust-dd/laws.md) +المفاهيم: [الدلالات التشغيلية](operational_semantics.md) +``` + +يتناول التفرع والحتمية والتلاقي وتكافؤ المسارات والتشابه المحاكى بدائل العملية الحسابية. وهذه ليست خاصية واحدة. + +```admonish note title="الموضع الدلالي" +تفرع تدفق التحكم بنية تشغيلية. والتلاقي خاصية لعلاقة الاختزال. ويقارن تكافؤ المسارات والتشابه المحاكى السلوكيات. أما المساواة الدلالية فتقارن المعاني في مجال دلالي مختار. ويصرح التصميم السليم بعلاقة المساواة المطلوبة بدل الانتقال عفويًا بين هذه المفاهيم. +``` + +## التكافؤ السلوكي {#behavioral-equivalence} + +نادرًا ما تملك البرامج المتزامنة والتفاعلية نتيجة نهائية واحدة فقط. ومن نقاط البدء المعتادة **نظام انتقال موسوم**: + +$$ \mathcal{L} = (S, A_{\tau}, \to) $$ + +حيث $S$ مجموعة من الحالات، و$A_{\tau}$ مجموعة من وسوم الأفعال القابلة للملاحظة مع فعل داخلي $\tau$، و$\to\;\subseteq S \times A_{\tau} \times S$ علاقة الانتقال. ونكتب $p \xrightarrow{a} p'$ عندما تستطيع الحالة $p$ تنفيذ الفعل $a$ والانتقال إلى $p'$. + +يحدد التكافؤ السلوكي الفروق بين هذه الأنظمة التي نتعمد تجاهلها: + +* تتبع **ملاحظات الزمن الخطي** التنفيذات المكتملة أو الجزئية وتسجل ما حدث خلالها +* وتحتفظ **ملاحظات زمن التفرع** أيضًا بمواضع توافر البدائل وموعد حسم الخيارات + +لذلك قد يتيح نظامان المسارات نفسها مع اختلافهما في بنية التفرع. فقد يختار أحدهما بين فعلين قبل التفاعل، بينما يؤجل الآخر ذلك الاختيار إلى ما بعده. تتطابق تسلسلات الأفعال، لكن الإمكانات المستقبلية تختلف. + +يقدم طيف فان خلابيك [للزمن الخطي–زمن التفرع](https://ir.cwi.nl/pub/5685/5685.pdf) عرضًا منهجيًا معياريًا لهذه التكافؤات السلوكية. وهو ليس ترتيبًا من الأضعف إلى الأقوى؛ فكل نقطة تحفظ مجموعة مختلفة من الملاحظات. + +## التفرع في برامج Rust {#branching-in-rust-programs} + +يختار `if` فرعًا واحدًا وفق شرط: + +```rust,noplayground +fn sign(x: i32) -> i32 { + if x > 0 { + 1 + } else if x < 0 { + -1 + } else { + 0 + } +} +``` + +يختار `match` ذراعًا واحدًا وفق قيمة: + +```rust,noplayground +fn day_type(day: &str) -> &str { + match day { + "Saturday" | "Sunday" => "Weekend", + "Monday" | "Tuesday" | "Wednesday" | "Thursday" | "Friday" => "Weekday", + _ => "Unknown", + } +} +``` + +في لغة حتمية، تختار هذه البنى مسار تدفق تحكم متوقعًا للمدخلات الثابتة. وهذه الخاصية هي **الحتمية**، لا التلاقي. + +## ما معنى التلاقي {#what-confluence-means} + +تكون علاقة الاختزال متلاقية عندما يمكن جمع نتيجتي اختزال من الحد نفسه من جديد: + +$$ \begin{array}{ccccc} && a && \\ & \swarrow^{*} && \searrow^{*} & \\ b &&&& c \\ & \searrow^{*} && \swarrow^{*} & \\ && d && \end{array} $$ + +صوريًا، إذا: + +$$ a \to^* b \quad\text{and}\quad a \to^* c $$ + +فلا بد من وجود `d` بحيث: + +$$ b \to^* d \quad\text{and}\quad c \to^* d $$ + +يسمح التلاقي بأكثر من مسار اختزال. ويقول إن هذه المسارات متوافقة بمعنى إمكان وصولها إلى خلف مشترك. + +## الحتمية والتلاقي {#determinism-and-confluence} + +لا تتيح علاقة الاختزال الحتمية إلا خطوة تالية واحدة كحد أقصى لكل حالة. ولذلك تكون متلاقية بمعنى مباشر: فلا توجد خيارات متنافسة في خطوة واحدة تستلزم التوفيق بينها. + +لكن العكس غير صحيح. فقد يسمح النظام بترتيبات اختزال متعددة ويظل متلاقيًا لأن جميع الترتيبات تتفق في النهاية. + +توضح تعبيرات `if` و`match` العادية في Rust الاختيار الحتمي، لكنها لا توضح بذاتها جوهر التلاقي. + +## مبرهنة تشرتش–روسر {#churchrosser} + +تنص مبرهنة تشرتش–روسر على خاصية التلاقي لاختزال حساب لامبدا. فإذا اختُزل حد إلى نتيجتين بمسارين مختلفين، فلهاتين النتيجتين اختزال مشترك. + +عندما يوجد شكل معياري، يقتضي التلاقي أن يكون وحيدًا. ويدعم هذا الاستدلال المعادلي لأن ترتيب التقييم لا يغير الشكل المعياري النهائي. + +لا تعمم هذه النتيجة على البرامج الأمرية الاعتباطية. فقد تميز الآثار الجانبية وجدولة المهام غير الحتمية والإخفاق وملاحظة الحالات الوسيطة بين ترتيبات الاختزال. + +## المسارات {#traces} + +يسجل **المسار** تسلسلًا من الأفعال أو الحالات القابلة للملاحظة. وتحفظ دلالات المسارات عمدًا معلومات تشغيلية أكثر من دلالات النتائج وحدها. + +قد تعيد دالتان نقيتان النتيجة نفسها مع مرورهما بخطوات داخلية مختلفة. وتكونان متساويتين في دلالة النتائج إذا أُهملت تلك الخطوات، لكنهما ليستا بالضرورة متساويتين في دلالات المسارات. + +مع الآثار، قد يغير تبديل الشروط ترتيب الملاحظات: + +```rust,noplayground +fn is_admin() -> bool { + println!("checked admin"); + true +} + +fn is_user() -> bool { + println!("checked user"); + true +} +``` + +قد يؤدي فحص `is_admin` أولًا بدلًا من `is_user` إلى تصنيفات متكافئة مع مسارات طباعة مختلفة. + +السؤال التصميمي هو ما إذا كانت تلك المطبوعات تنتمي إلى المجال الدلالي المختار. + +## تكافؤ المسارات {#trace-equivalence} + +يتكافأ نظامان مساريًا حين يتيحان المسارات القابلة للملاحظة نفسها وفق نموذج المسارات المختار. + +قد يتجاهل تكافؤ المسارات بنية التفرع. فقد يولد نظامان المسارات نفسها، مع التزام أحدهما بخيار أبكر من الآخر. وقد يهم هذا الفرق في الأنظمة التفاعلية والمتزامنة. + +## التشابه المحاكى {#bisimulation} + +يربط التشابه المحاكى نظامي انتقال خطوة بخطوة. فكلما نفذ أحد النظامين انتقالًا قابلًا للملاحظة، وجب أن يتمكن الآخر من محاكاته، وأن تظل الحالات الناتجة مترابطة. + +تشمل صيغًا شائعة: + +* **التشابه المحاكى القوي**، ويطابق الانتقالات الفردية +* **التشابه المحاكى الضعيف**، ويتجاهل انتقالات داخلية مختارة +* **التشابه المحاكى التفرعي**، ويتجاهل العمل الداخلي مع الحفاظ على بنية الخيارات المهمة + +غالبًا ما يكون التشابه المحاكى مقارنة سلوكية أقوى من تكافؤ المسارات، لأنه يلاحظ بقاء البدائل متاحة أثناء التفاعل. + +
+النشأة والتعريفات الصورية + +طوّر ميلنر التكافؤ الرصدي للعمليات المتخاطبة في [*A Calculus of Communicating Systems*](https://www.lfcs.inf.ed.ac.uk/reports/86/ECS-LFCS-86-7/ECS-LFCS-86-7.pdf). ثم ميّز بارك التكافؤ المقابل استقرائيًا في [*Concurrency and Automata on Infinite Sequences*](https://wrap.warwick.ac.uk/id/eprint/47224/1/WRAP_Park_cs-rr-035.pdf)، مقدمًا علاقة النقطة الثابتة العظمى وطريقة البرهان المعروفتين الآن باسم التشابه المحاكى. واعتمد ميلنر هذه الطريقة وطورها أساسًا للاستدلال على سلوك العمليات. + +**التشابه المحاكى القوي.** في أنظمة الانتقال الموسوم، تكون العلاقة $R$ تشابهًا محاكيًا قويًا إذا كان $p\mathrel{R}q$ يقتضي، لكل فعل $a$: + +* إذا كان $p\xrightarrow{a}p'$، فتوجد حالة $q'$ تحقق $q\xrightarrow{a}q'$ و$p'\mathrel{R}q'$؛ و +* إذا كان $q\xrightarrow{a}q'$، فتوجد حالة $p'$ تحقق $p\xrightarrow{a}p'$ و$p'\mathrel{R}q'$. + +تكون حالتان متشابهتين محاكيًا إذا ربطتهما علاقة من هذا النوع. والتعريف استقرائي مشارك، فبعد مطابقة انتقال يجب أن تفي حالات الخلف بالالتزام السلوكي نفسه من جديد. + +**التشابه المحاكى التفرعي.** في عرض شائع لا يميز التباعد، تكون العلاقة المتماثلة $R$ تشابهًا محاكيًا تفرعيًا إذا كان $p\mathrel{R}q$ و$p\xrightarrow{a}p'$ يقتضيان أحد الأمرين: + +* $a = \tau$ و$p'\mathrel{R}q$، أو + +* وجود حالتين $q_0$ و$q'$ بحيث + + $$ q \xRightarrow{\tau} q_0 \xrightarrow{a} q', \qquad p\mathrel{R}q_0, \qquad p'\mathrel{R}q' $$ + + +تعني $\xRightarrow{\tau}$ هنا صفر انتقال داخلي أو أكثر. واشتراط بقاء الحالة الوسيطة $q_0$ مرتبطة بـ $p$ هو ما يحفظ إمكانية التفرع ذات الصلة مع السماح بتجاهل العمل الداخلي. وقدم فان خلابيك وفاييلاند هذا التكافؤ وطوّراه في [*Branching Time and Abstraction in Bisimulation Semantics*](https://ir.cwi.nl/pub/5564/5564D.pdf). + +
+ +## المساواة الدلالية {#denotational-equality} + +تعتمد المساواة الدلالية على المجال الدلالي المختار: + +$$ \llbracket P \rrbracket = \llbracket Q \rrbracket $$ + +قد يُبنى المجال نفسه من المسارات أو من أنظمة انتقال مع أخذ التشابه المحاكى في الحسبان أو من مجموعات النتائج أو من نموذج رياضي آخر. ولا يفرض التصميم الدلالي مساواة عامة واحدة؛ بل يتطلب اختيار المساواة صراحة واستخدامها تركيبيًا. + +العلاقة هي: + +1. ابدأ بالنظام التشغيلي. +2. اختر الملاحظات ذات الصلة. +3. اختر المجال الدلالي وعلاقة المساواة. + +## التفرع بوصفه بيانات {#branching-as-data} + +يظهر التفرع بنيويًا أيضًا في الأشجار. ويمكن تمثيل مسار ثنائي بتسلسل من قرارات اليسار واليمين. ويفيد هذا التمثيل في أشجار البادئات ومعرفات التنفيذ ومخططات القرار وعنونة الذاكرة. + +يفصل مثال موضع الفرع الدلالي في [لماذا يأتي المعنى أولًا](../denotational-design/semantic-view.md) عمدًا بين معنى الشجرة هذا وترميز واحد بمتجه بتات. + +وصف كونال إليوت عنونة الذاكرة عبر بنية شجرة أوراق ثنائية مثالية. وليس المقصود أن كل آلة تخزن حرفيًا شجرة على مستوى المصدر، بل أن نموذجًا تركيبيًا للشجرة قد يكشف بنية مفيدة تخفيها العناوين الرقمية المسطحة. + +
كونال إليوت — عنونة الذاكرة بوصفها شجرة أوراق ثنائية مثالية
+ +## مقارنة {#comparison} + +| المفهوم | الموضوع | السؤال المحوري | +| --- | --- | --- | +| تفرع تدفق التحكم | تنفيذ برنامج واحد | أي استمرارية يجري اختيارها؟ | +| الحتمية | علاقة الانتقال | هل تحدد الخطوة التالية على نحو فريد؟ | +| التلاقي | علاقة الاختزال | هل يمكن جمع الاختزالات المتباعدة؟ | +| تكافؤ المسارات | تسلسلات الأفعال القابلة للملاحظة | هل يتيح النظامان المسارات نفسها؟ | +| التشابه المحاكى | بنية الانتقال التفرعية | هل يستطيع النظامان محاكاة انتقالات بعضهما؟ | +| المساواة الدلالية | المجال الدلالي المختار | هل للبرامج المعنى المحدد نفسه؟ | + +قد تدعم هذه المفاهيم بعضها بعضًا، لكن لا ينبغي استخدام أي منها مرادفًا لغيره. + +## للمطالعة الإضافية {#further-reading} + +* [*A Calculus of Communicating Systems*](https://www.lfcs.inf.ed.ac.uk/reports/86/ECS-LFCS-86-7/ECS-LFCS-86-7.pdf) — عرض ميلنر التأسيسي لحساب الأنظمة المتخاطبة (CCS) والتكافؤ الرصدي +* [*Concurrency and Automata on Infinite Sequences*](https://wrap.warwick.ac.uk/id/eprint/47224/1/WRAP_Park_cs-rr-035.pdf) — توصيف بارك للتشابه المحاكى بالاستقراء المشارك +* [*Algebraic Laws for Nondeterminism and Concurrency*](https://www.scss.tcd.ie/matthew.hennessy/pubs/old/HMjacm85.pdf) — عرض هينيسي وميلنر للتكافؤ الرصدي والقوانين الجبرية +* [*What Is Branching Time and Why Use It?*](https://theory.stanford.edu/~rvg/branching/) ([ملف PDF مضغوط](https://cgi.cse.unsw.edu.au/~rvg/pub/branching.pdf.gz)) — دافع موجز للحفاظ على بنية التفرع +* [*The Linear Time–Branching Time Spectrum*](https://ir.cwi.nl/pub/5685/5685.pdf) — التصنيف المعياري للتكافؤات السلوكية +* [*Branching Time and Abstraction in Bisimulation Semantics*](https://ir.cwi.nl/pub/5564/5564D.pdf) — المعالجة التأسيسية للتشابه المحاكى التفرعي +* [*Three Logics for Branching Bisimulation*](https://ir.cwi.nl/pub/1370/1370D.pdf) — توصيفات منطقية عبر منطق على نمط هينيسي–ميلنر وCTL\* من دون الزمن التالي diff --git a/src/concepts/branching.de.md b/src/concepts/branching.de.md new file mode 100644 index 0000000..bd00054 --- /dev/null +++ b/src/concepts/branching.de.md @@ -0,0 +1,208 @@ + + +# Verzweigung und Konfluenz {#branching-and-confluence} + +```admonish tip title="Verwandte Themen" +The Semantic View: [Denotationen und Kompositionalität](../denotational-design/denotations.md), [Gesetze und Interpretationen](../denotational-design/laws-and-interpretations.md) +Design by Meaning in Rust: [Gesetze, Szenarien und Nachweise](../rust-dd/laws.md) +Concepts: [Operationale Semantik](operational_semantics.md) +``` + +Verzweigung, Determinismus, Konfluenz, Spuräquivalenz und Bisimulation betreffen alle Alternativen in Berechnungen. Sie bezeichnen jedoch unterschiedliche Eigenschaften. + +```admonish note title="Semantische Einordnung" +Verzweigung im Kontrollfluss ist eine operationale Struktur. Konfluenz ist eine Eigenschaft einer Reduktionsrelation. Spuräquivalenz und Bisimulation vergleichen Verhaltensweisen. Denotationelle Gleichheit vergleicht Bedeutungen in einem gewählten semantischen Bereich. Ein solider Entwurf nennt die benötigte Gleichheit, statt informell zwischen diesen Begriffen zu wechseln. +``` + +## Verhaltensäquivalenz {#behavioral-equivalence} + +Nebenläufige und interaktive Programme haben selten nur ein Endergebnis. Ein üblicher Ausgangspunkt ist ein **markiertes Übergangssystem**: + +$$ \mathcal{L} = (S, A_{\tau}, \to) $$ + +Dabei ist $S$ eine Zustandsmenge, $A_{\tau}$ eine Menge beobachtbarer Aktionsmarkierungen einschließlich der internen Aktion $\tau$ und $\to\;\subseteq S \times A_{\tau} \times S$ die Übergangsrelation. Wir schreiben $p \xrightarrow{a} p'$, wenn Zustand $p$ die Aktion $a$ ausführen und in $p'$ übergehen kann. + +Eine Verhaltensäquivalenz legt fest, welche Unterschiede zwischen solchen Systemen bewusst ausgeblendet werden: + +* **Beobachtungen in linearer Zeit** folgen abgeschlossenen oder partiellen Ausführungen und halten fest, was darin geschah +* **Beobachtungen in Verzweigungszeit** halten zusätzlich fest, wo Alternativen verfügbar waren und wann Entscheidungen getroffen wurden + +Zwei Systeme können also dieselben Spuren zulassen und sich dennoch in ihrer Verzweigungsstruktur unterscheiden. Das eine kann vor einer Interaktion zwischen zwei Aktionen wählen, das andere diese Wahl bis danach aufschieben. Die Aktionsfolgen stimmen überein, nicht aber die zukünftigen Möglichkeiten. + +Van Glabbeeks [linear-time–branching-time spectrum](https://ir.cwi.nl/pub/5685/5685.pdf) bietet die etablierte systematische Darstellung dieser Verhaltensäquivalenzen. Es ist keine Rangfolge von schwach bis stark; jeder Punkt bewahrt eine andere Menge von Beobachtungen. + +## Verzweigungen in Rust-Programmen {#branching-in-rust-programs} + +Ein `if` wählt anhand einer Bedingung einen Zweig aus: + +```rust,noplayground +fn sign(x: i32) -> i32 { + if x > 0 { + 1 + } else if x < 0 { + -1 + } else { + 0 + } +} +``` + +Ein `match` wählt anhand eines Werts einen Arm aus: + +```rust,noplayground +fn day_type(day: &str) -> &str { + match day { + "Saturday" | "Sunday" => "Weekend", + "Monday" | "Tuesday" | "Wednesday" | "Thursday" | "Friday" => "Weekday", + _ => "Unknown", + } +} +``` + +Bei festen Eingaben wählen diese Konstrukte in einer deterministischen Sprache einen vorhersehbaren Kontrollpfad aus. Diese Eigenschaft heißt **Determinismus**, nicht Konfluenz. + +## Was Konfluenz bedeutet {#what-confluence-means} + +Eine Reduktionsrelation ist konfluent, wenn sich zwei Reduktionen desselben Terms wieder zusammenführen lassen: + +$$ \begin{array}{ccccc} && a && \\ & \swarrow^{*} && \searrow^{*} & \\ b &&&& c \\ & \searrow^{*} && \swarrow^{*} & \\ && d && \end{array} $$ + +Formal gilt: Wenn + +$$ a \to^* b \quad\text{and}\quad a \to^* c $$ + +dann muss es ein `d` geben, sodass: + +$$ b \to^* d \quad\text{and}\quad c \to^* d $$ + +Konfluenz lässt mehrere Reduktionspfade zu. Sie besagt, dass diese Pfade insofern kompatibel sind, als sie einen gemeinsamen Nachfolger erreichen können. + +## Determinismus und Konfluenz {#determinism-and-confluence} + +Eine deterministische Reduktionsrelation hat von jedem Zustand aus höchstens einen Folgeschritt. Sie ist daher auf einfache Weise konfluent: Es gibt keine konkurrierenden Einzelschrittauswahlen, die zusammengeführt werden müssten. + +Die Umkehrung gilt nicht. Ein System kann mehrere Reduktionsreihenfolgen zulassen und dennoch konfluent sein, wenn alle Reihenfolgen schließlich übereinstimmen. + +Gewöhnliche Rust-Ausdrücke mit `if` und `match` veranschaulichen deterministische Auswahl. Den interessanten Gehalt von Konfluenz zeigen sie für sich genommen nicht. + +## Church–Rosser {#churchrosser} + +Der Satz von Church–Rosser formuliert eine Konfluenz-Eigenschaft für die Reduktion im Lambda-Kalkül. Reduziert sich ein Term über verschiedene Pfade zu zwei Ergebnissen, besitzen diese Ergebnisse einen gemeinsamen Redukt. + +Existiert eine Normalform, folgt aus Konfluenz, dass sie eindeutig ist. Das ermöglicht Gleichungsrechnungen, da die Auswertungsreihenfolge die endgültige Normalform nicht verändert. + +Verallgemeinere dieses Ergebnis nicht auf beliebige imperative Programme. Seiteneffekte, nichtdeterministische Ablaufplanung, Fehler und die Beobachtung von Zwischenzuständen können Reduktionsreihenfolgen unterscheidbar machen. + +## Spuren {#traces} + +Eine **Spur** zeichnet eine Folge beobachtbarer Aktionen oder Zustände auf. Spursemantik bewahrt bewusst mehr operative Informationen als eine Semantik, die nur das Ergebnis betrachtet. + +Zwei reine Funktionen können dasselbe Ergebnis liefern und dabei unterschiedliche interne Schritte durchlaufen. Werden diese Schritte ausgeblendet, sind sie in einer Ergebnisdenotation gleich. In einer Spursemantik müssen sie nicht gleich sein. + +Bei Effekten können unterschiedliche Prüfungsreihenfolgen die Beobachtungen verändern: + +```rust,noplayground +fn is_admin() -> bool { + println!("checked admin"); + true +} + +fn is_user() -> bool { + println!("checked user"); + true +} +``` + +`is_admin` zuerst zu prüfen und danach `is_user` oder die umgekehrte Reihenfolge kann äquivalente Klassifikationen ergeben, aber unterschiedliche Spuren ausgeben. + +Die Entwurfsfrage lautet, ob diese Ausgaben zum gewählten semantischen Bereich gehören. + +## Spuräquivalenz {#trace-equivalence} + +Zwei Systeme sind spuräquivalent, wenn sie unter dem gewählten Spurenmodell dieselben beobachtbaren Spuren zulassen. + +Spuräquivalenz kann die Verzweigungsstruktur ausblenden. Zwei Systeme können dieselben Spuren erzeugen, obwohl sich das eine früher als das andere auf eine Auswahl festlegt. Bei interaktiven und nebenläufigen Systemen kann dieser Unterschied wichtig sein. + +## Bisimulation {#bisimulation} + +Bisimulation setzt zwei Übergangssysteme Schritt für Schritt zueinander in Beziehung. Führt das eine System einen beobachtbaren Schritt aus, muss das andere ihn nachbilden können; die resultierenden Zustände müssen weiterhin zueinander in Beziehung stehen. + +Häufige Varianten sind: + +* **starke Bisimulation**, die einzelne Übergänge abgleicht +* **schwache Bisimulation**, die ausgewählte interne Übergänge ausblendet +* **Verzweigungsbisimulation**, die interne Arbeit ausblendet und zugleich wichtige Auswahlstrukturen bewahrt + +Bisimulation ist häufig ein stärkerer Verhaltensvergleich als Spuräquivalenz, da sie beobachtet, wie Alternativen während einer Interaktion verfügbar bleiben. + +
+Ursprünge und formale Definitionen + +Milner entwickelte die beobachtungsbezogene Äquivalenz kommunizierender Prozesse in [*A Calculus of Communicating Systems*](https://www.lfcs.inf.ed.ac.uk/reports/86/ECS-LFCS-86-7/ECS-LFCS-86-7.pdf). Park charakterisierte die zugehörige Äquivalenz anschließend koinduktiv in [*Concurrency and Automata on Infinite Sequences*](https://wrap.warwick.ac.uk/id/eprint/47224/1/WRAP_Park_cs-rr-035.pdf) und formulierte die größte Fixpunktrelation samt Beweismethode, die heute als Bisimulation bekannt ist. Milner übernahm und entwickelte diese Methode als Grundlage für Schlussfolgerungen über Prozessverhalten weiter. + +**Starke Bisimulation.** Für markierte Übergangssysteme ist eine Relation $R$ eine starke Bisimulation, wenn $p\mathrel{R}q$ gilt und für jede Aktion $a$ Folgendes zutrifft: + +* Falls $p\xrightarrow{a}p'$ gilt, gibt es ein $q'$, für das $q\xrightarrow{a}q'$ und $p'\mathrel{R}q'$ gelten; und +* falls $q\xrightarrow{a}q'$ gilt, gibt es ein $p'$, für das $p\xrightarrow{a}p'$ und $p'\mathrel{R}q'$ gelten. + +Zwei Zustände sind bisimilar, wenn sie durch eine Bisimulation in Beziehung gesetzt werden. Die Definition ist koinduktiv: Nach dem Abgleich eines Übergangs müssen die Nachfolgezustände dieselbe Verhaltensverpflichtung erneut erfüllen. + +**Verzweigungsbisimulation.** In einer gängigen Formulierung, die Divergenz außer Acht lässt, ist eine symmetrische Relation $R$ eine Verzweigungsbisimulation, wenn $p\mathrel{R}q$ und $p\xrightarrow{a}p'$ eine der folgenden Möglichkeiten implizieren: + +* $a = \tau$ und $p'\mathrel{R}q$, oder + +* es gibt Zustände $q_0$ und $q'$ mit folgenden Eigenschaften: + + $$ q \xRightarrow{\tau} q_0 \xrightarrow{a} q', \qquad p\mathrel{R}q_0, \qquad p'\mathrel{R}q' $$ + + +Hier bezeichnet $\xRightarrow{\tau}$ null oder mehr interne Übergänge. Die Forderung, dass der Zwischenzustand $q_0$ weiterhin mit $p$ in Beziehung steht, bewahrt das relevante Verzweigungspotenzial, während interne Arbeit ausgeblendet werden darf. Van Glabbeek und Weijland führten diese Äquivalenz in [*Branching Time and Abstraction in Bisimulation Semantics*](https://ir.cwi.nl/pub/5564/5564D.pdf) ein und entwickelten sie weiter. + +
+ +## Denotationelle Gleichheit {#denotational-equality} + +Denotationelle Gleichheit hängt vom gewählten semantischen Bereich ab: + +$$ \llbracket P \rrbracket = \llbracket Q \rrbracket $$ + +Der Bereich kann selbst aus Spuren, Übergangssystemen modulo Bisimulation, Ergebnismengen oder einem anderen mathematischen Modell bestehen. Denotational Design schreibt keine universelle Gleichheit vor. Es verlangt, dass die Gleichheit ausdrücklich gewählt und kompositional verwendet wird. + +Der Zusammenhang lautet: + +1. Mit dem operationalen System beginnen. +2. Die relevanten Beobachtungen auswählen. +3. Den semantischen Bereich und die Gleichheit wählen. + +## Verzweigung als Daten {#branching-as-data} + +Verzweigung tritt auch strukturell in Bäumen auf. Ein binärer Pfad lässt sich als Folge von Links-/Rechtsentscheidungen darstellen. Diese Repräsentation ist nützlich für Tries, Ausführungskennungen, Entscheidungsdiagramme und Speicheradressierung. + +Das semantische Beispiel zu Verzweigungspositionen in [Warum Bedeutung an erster Stelle steht](../denotational-design/semantic-view.md) trennt diese Baumbedeutung bewusst von einer Bitvektorkodierung. + +Conal Elliott hat die Speicheradressierung anhand der Struktur perfekter binärer Blätterbäume beschrieben. Es geht nicht darum, dass jede Maschine tatsächlich einen Quelltextbaum speichert. Vielmehr kann ein kompositionales Baummodell nützliche Strukturen sichtbar machen, die durch flache numerische Adressen verborgen bleiben. + +
Conal Elliott — Speicheradressierung als perfekter binärer Blätterbaum
+ +## Vergleich {#comparison} + +| Konzept | Gegenstand | Zentrale Frage | +| --- | --- | --- | +| Verzweigung im Kontrollfluss | Eine Programmausführung | Welche Fortsetzung wird ausgewählt? | +| Determinismus | Übergangsrelation | Ist der nächste Schritt eindeutig bestimmt? | +| Konfluenz | Reduktionsrelation | Lassen sich auseinanderlaufende Reduktionen zusammenführen? | +| Spuräquivalenz | Beobachtbare Aktionsfolgen | Lassen die Systeme dieselben Spuren zu? | +| Bisimulation | Verzweigte Übergangsstruktur | Können die Systeme die Züge des jeweils anderen nachbilden? | +| Denotationelle Gleichheit | Gewählter semantischer Bereich | Haben die Programme dieselbe spezifizierte Bedeutung? | + +Diese Begriffe können einander stützen, doch keiner sollte als Synonym für einen anderen verwendet werden. + +## Weiterführende Lektüre {#further-reading} + +* [*A Calculus of Communicating Systems*](https://www.lfcs.inf.ed.ac.uk/reports/86/ECS-LFCS-86-7/ECS-LFCS-86-7.pdf) — Milners grundlegende Ausarbeitung von CCS und beobachtungsbezogener Äquivalenz +* [*Concurrency and Automata on Infinite Sequences*](https://wrap.warwick.ac.uk/id/eprint/47224/1/WRAP_Park_cs-rr-035.pdf) — Parks koinduktive Charakterisierung der Bisimulation +* [*Algebraic Laws for Nondeterminism and Concurrency*](https://www.scss.tcd.ie/matthew.hennessy/pubs/old/HMjacm85.pdf) — Hennessy und Milner zu beobachtungsbezogener Kongruenz und algebraischen Gesetzen +* [*What Is Branching Time and Why Use It?*](https://theory.stanford.edu/~rvg/branching/) ([komprimiertes PDF](https://cgi.cse.unsw.edu.au/~rvg/pub/branching.pdf.gz)) — eine knappe Begründung für die Bewahrung der Verzweigungsstruktur +* [*The Linear Time–Branching Time Spectrum*](https://ir.cwi.nl/pub/5685/5685.pdf) — die etablierte Taxonomie der Verhaltensäquivalenzen +* [*Branching Time and Abstraction in Bisimulation Semantics*](https://ir.cwi.nl/pub/5564/5564D.pdf) — die grundlegende Abhandlung zur Verzweigungsbisimulation +* [*Three Logics for Branching Bisimulation*](https://ir.cwi.nl/pub/1370/1370D.pdf) — logische Charakterisierungen anhand Logiken im Stil von Hennessy–Milner und CTL\* ohne Next-Time-Operator diff --git a/src/concepts/branching.es.md b/src/concepts/branching.es.md new file mode 100644 index 0000000..c6e3f3a --- /dev/null +++ b/src/concepts/branching.es.md @@ -0,0 +1,208 @@ + + +# Ramificación y confluencia {#branching-and-confluence} + +```admonish tip title="Relacionado" +La perspectiva semántica: [Denotaciones y composicionalidad](../denotational-design/denotations.md), [Leyes e interpretaciones](../denotational-design/laws-and-interpretations.md) +Diseño basado en el significado en Rust: [Leyes, escenarios y pruebas](../rust-dd/laws.md) +Conceptos: [Semántica operacional](operational_semantics.md) +``` + +La ramificación, el determinismo, la confluencia, la equivalencia de trazas y la bisimulación se refieren a alternativas en el cálculo. No son la misma propiedad. + +```admonish note title="Ubicación semántica" +La ramificación del flujo de control es estructura operacional. La confluencia es una propiedad de una relación de reducción. La equivalencia de trazas y la bisimulación comparan comportamientos. La igualdad denotacional compara significados en un dominio semántico elegido. Un diseño sólido especifica qué igualdad necesita, en vez de alternar informalmente entre estas nociones. +``` + +## Equivalencia de comportamiento {#behavioral-equivalence} + +Los programas concurrentes e interactivos rara vez tienen un único resultado final. Un punto de partida habitual es un **sistema de transición etiquetado**: + +$$ \mathcal{L} = (S, A_{\tau}, \to) $$ + +donde $S$ es un conjunto de estados, $A_{\tau}$ es un conjunto de etiquetas de acciones observables junto con una acción interna $\tau$, y $\to\;\subseteq S \times A_{\tau} \times S$ es la relación de transición. Escribimos $p \xrightarrow{a} p'$ cuando el estado $p$ puede realizar la acción $a$ y pasar al estado $p'$. + +Una equivalencia de comportamiento especifica qué diferencias entre estos sistemas se omiten deliberadamente: + +* las **observaciones de tiempo lineal** siguen ejecuciones completas o parciales y registran lo que ocurrió durante ellas +* las **observaciones de tiempo ramificado** también conservan dónde había alternativas disponibles y cuándo se resolvieron las elecciones + +Por tanto, dos sistemas pueden admitir las mismas trazas y, aun así, diferir en su estructura de ramificación. Uno puede elegir entre dos acciones antes de una interacción, mientras que el otro aplaza la elección hasta después. Las secuencias de acciones coinciden, pero sus posibilidades futuras no. + +El [espectro de tiempo lineal y tiempo ramificado](https://ir.cwi.nl/pub/5685/5685.pdf) de van Glabbeek ofrece el análisis sistemático estándar de estas equivalencias de comportamiento. No es una escala de débil a fuerte: cada punto conserva un conjunto distinto de observaciones. + +## Ramificación en programas de Rust {#branching-in-rust-programs} + +Un `if` selecciona una rama según una condición: + +```rust,noplayground +fn sign(x: i32) -> i32 { + if x > 0 { + 1 + } else if x < 0 { + -1 + } else { + 0 + } +} +``` + +Un `match` selecciona una rama según un valor: + +```rust,noplayground +fn day_type(day: &str) -> &str { + match day { + "Saturday" | "Sunday" => "Weekend", + "Monday" | "Tuesday" | "Wednesday" | "Thursday" | "Friday" => "Weekday", + _ => "Unknown", + } +} +``` + +Con entradas fijas en un lenguaje determinista, estas construcciones seleccionan una ruta de flujo de control predecible. Esa propiedad es el **determinismo**, no la confluencia. + +## Qué significa la confluencia {#what-confluence-means} + +Una relación de reducción es confluente cuando dos reducciones desde el mismo término pueden volver a unirse: + +$$ \begin{array}{ccccc} && a && \\ & \swarrow^{*} && \searrow^{*} & \\ b &&&& c \\ & \searrow^{*} && \swarrow^{*} & \\ && d && \end{array} $$ + +Formalmente, si: + +$$ a \to^* b \quad\text{and}\quad a \to^* c $$ + +entonces debe existir algún `d` tal que: + +$$ b \to^* d \quad\text{and}\quad c \to^* d $$ + +La confluencia permite más de una ruta de reducción. Afirma que esas rutas son compatibles, en el sentido de que pueden alcanzar un sucesor común. + +## Determinismo y confluencia {#determinism-and-confluence} + +Una relación de reducción determinista tiene como máximo un siguiente paso desde cada estado. Por tanto, es confluente en un sentido directo: no hay elecciones simultáneas en conflicto que reconciliar. + +La implicación inversa no se cumple. Un sistema puede permitir varios órdenes de reducción y seguir siendo confluente porque todos terminan coincidiendo. + +Las expresiones `if` y `match` ordinarias de Rust muestran una selección determinista. Por sí solas no ilustran el contenido interesante de la confluencia. + +## Church–Rosser {#churchrosser} + +El teorema de Church–Rosser establece una propiedad de confluencia para la reducción del cálculo lambda. Si un término se reduce a dos resultados por rutas distintas, ambos tienen un reducto común. + +Si existe una forma normal, la confluencia implica que es única. Esto respalda el razonamiento ecuacional, porque el orden de evaluación no cambia la forma normal final. + +No generalices este resultado a programas imperativos arbitrarios. Los efectos secundarios, la planificación no determinista, los fallos y la observación de estados intermedios pueden distinguir los órdenes de reducción. + +## Trazas {#traces} + +Una **traza** registra una secuencia de acciones o estados observables. La semántica de trazas conserva intencionalmente más información operacional que una semántica basada solo en resultados. + +Dos funciones puras pueden devolver el mismo resultado tras distintos pasos internos. Son iguales en una denotación de resultados si se omiten esos pasos. No necesariamente son iguales en una semántica de trazas. + +Con efectos, cambiar el orden de las condiciones puede cambiar las observaciones: + +```rust,noplayground +fn is_admin() -> bool { + println!("checked admin"); + true +} + +fn is_user() -> bool { + println!("checked user"); + true +} +``` + +Comprobar primero `is_admin` y después `is_user` puede dar clasificaciones equivalentes, pero producir trazas distintas. + +La pregunta de diseño es si esas impresiones pertenecen al dominio semántico elegido. + +## Equivalencia de trazas {#trace-equivalence} + +Dos sistemas son equivalentes según las trazas cuando admiten las mismas trazas observables bajo el modelo de trazas seleccionado. + +La equivalencia de trazas puede omitir la estructura de ramificación. Dos sistemas pueden generar las mismas trazas aunque uno se comprometa con una elección antes que el otro. En sistemas interactivos y concurrentes, esa diferencia puede importar. + +## Bisimulación {#bisimulation} + +La bisimulación relaciona dos sistemas de transición paso a paso. Cada vez que un sistema realiza un movimiento observable, el otro debe poder igualarlo, y los estados resultantes deben seguir relacionados. + +Entre las variantes habituales se encuentran: + +* la **bisimulación fuerte**, que iguala transiciones individuales +* la **bisimulación débil**, que abstrae ciertas transiciones internas +* la **bisimulación ramificada**, que abstrae el trabajo interno y conserva estructuras de elección importantes + +La bisimulación suele ser una comparación de comportamiento más fuerte que la equivalencia de trazas, porque observa cómo se mantienen disponibles las alternativas durante la interacción. + +
+Orígenes y definiciones formales + +Milner desarrolló la equivalencia observacional para procesos comunicantes en [*A Calculus of Communicating Systems*](https://www.lfcs.inf.ed.ac.uk/reports/86/ECS-LFCS-86-7/ECS-LFCS-86-7.pdf). Park caracterizó después la equivalencia correspondiente mediante coinducción en [*Concurrency and Automata on Infinite Sequences*](https://wrap.warwick.ac.uk/id/eprint/47224/1/WRAP_Park_cs-rr-035.pdf), e introdujo la relación de punto fijo mayor y el método de demostración que hoy conocemos como bisimulación. Milner adoptó y desarrolló este método como fundamento para razonar sobre el comportamiento de procesos. + +**Bisimulación fuerte.** Para sistemas de transición etiquetados, una relación $R$ es una bisimulación fuerte cuando $p\mathrel{R}q$ implica, para cada acción $a$: + +* si $p\xrightarrow{a}p'$, entonces existe algún $q'$ que satisface $q\xrightarrow{a}q'$ y $p'\mathrel{R}q'$; y +* si $q\xrightarrow{a}q'$, entonces existe algún $p'$ que satisface $p\xrightarrow{a}p'$ y $p'\mathrel{R}q'$. + +Dos estados son bisimilares cuando alguna bisimulación los relaciona. La definición es coinductiva: tras igualar una transición, los estados sucesores deben volver a cumplir la misma obligación de comportamiento. + +**Bisimulación ramificada.** En una formulación habitual que ignora la divergencia, una relación simétrica $R$ es una bisimulación ramificada cuando $p\mathrel{R}q$ y $p\xrightarrow{a}p'$ implican alguna de estas posibilidades: + +* $a = \tau$ y $p'\mathrel{R}q$, o + +* existen estados $q_0$ y $q'$ tales que + + $$ q \xRightarrow{\tau} q_0 \xrightarrow{a} q', \qquad p\mathrel{R}q_0, \qquad p'\mathrel{R}q' $$ + + +Aquí, $\xRightarrow{\tau}$ denota cero o más transiciones internas. Exigir que el estado intermedio $q_0$ siga relacionado con $p$ es lo que preserva el potencial de ramificación pertinente, a la vez que permite ignorar el trabajo interno. Van Glabbeek y Weijland introdujeron y desarrollaron esta equivalencia en [*Branching Time and Abstraction in Bisimulation Semantics*](https://ir.cwi.nl/pub/5564/5564D.pdf). + +
+ +## Igualdad denotacional {#denotational-equality} + +La igualdad denotacional depende del dominio semántico seleccionado: + +$$ \llbracket P \rrbracket = \llbracket Q \rrbracket $$ + +El dominio puede construirse a partir de trazas, sistemas de transición considerados módulo de bisimulación, conjuntos de resultados u otro modelo matemático. El diseño denotacional no prescribe una igualdad universal. Exige elegirla explícitamente y usarla de forma composicional. + +La relación es la siguiente: + +1. Empieza por el sistema operacional. +2. Selecciona las observaciones pertinentes. +3. Elige el dominio semántico y la igualdad. + +## Ramificación como dato {#branching-as-data} + +La ramificación también aparece estructuralmente en árboles. Una ruta binaria puede representarse como una secuencia de decisiones izquierda/derecha. Esta representación resulta útil para tries, identificadores de ejecución, diagramas de decisión y direccionamiento de memoria. + +El ejemplo de posición de rama semántica en [Por qué el significado va primero](../denotational-design/semantic-view.md) separa deliberadamente este significado arbóreo de una codificación con vectores de bits. + +Conal Elliott ha descrito el direccionamiento de memoria mediante la estructura de árbol binario perfecto de hojas. La idea no es que todas las máquinas almacenen literalmente un árbol del código fuente, sino que un modelo composicional basado en árboles puede revelar estructuras útiles que quedan ocultas por las direcciones numéricas planas. + +
Conal Elliott: direccionamiento de memoria como árbol binario perfecto de hojas
+ +## Comparación {#comparison} + +| Concepto | Objeto | Pregunta central | +| --- | --- | --- | +| Ramificación del flujo de control | Una ejecución del programa | ¿Qué continuación se selecciona? | +| Determinismo | Relación de transición | ¿El siguiente paso queda determinado de manera única? | +| Confluencia | Relación de reducción | ¿Se pueden volver a unir las reducciones divergentes? | +| Equivalencia de trazas | Secuencias de acciones observables | ¿Admiten los sistemas las mismas trazas? | +| Bisimulación | Estructura de transiciones ramificadas | ¿Pueden los sistemas igualar los movimientos del otro? | +| Igualdad denotacional | Dominio semántico elegido | ¿Tienen los programas el mismo significado especificado? | + +Estas nociones pueden respaldarse entre sí, pero ninguna debe usarse como sinónimo de otra. + +## Para seguir leyendo {#further-reading} + +* [*A Calculus of Communicating Systems*](https://www.lfcs.inf.ed.ac.uk/reports/86/ECS-LFCS-86-7/ECS-LFCS-86-7.pdf) — desarrollo fundacional de CCS y de la equivalencia observacional de Milner +* [*Concurrency and Automata on Infinite Sequences*](https://wrap.warwick.ac.uk/id/eprint/47224/1/WRAP_Park_cs-rr-035.pdf) — caracterización coinductiva de la bisimulación de Park +* [*Algebraic Laws for Nondeterminism and Concurrency*](https://www.scss.tcd.ie/matthew.hennessy/pubs/old/HMjacm85.pdf) — análisis de Hennessy y Milner sobre congruencia observacional y leyes algebraicas +* [*What Is Branching Time and Why Use It?*](https://theory.stanford.edu/~rvg/branching/) ([PDF comprimido](https://cgi.cse.unsw.edu.au/~rvg/pub/branching.pdf.gz)) — motivación concisa para preservar la estructura de ramificación +* [*The Linear Time–Branching Time Spectrum*](https://ir.cwi.nl/pub/5685/5685.pdf) — taxonomía estándar de equivalencias de comportamiento +* [*Branching Time and Abstraction in Bisimulation Semantics*](https://ir.cwi.nl/pub/5564/5564D.pdf) — estudio fundacional de la bisimulación ramificada +* [*Three Logics for Branching Bisimulation*](https://ir.cwi.nl/pub/1370/1370D.pdf) — caracterizaciones lógicas mediante lógicas al estilo de Hennessy–Milner y CTL\* sin operador de tiempo siguiente diff --git a/src/concepts/branching.ja.md b/src/concepts/branching.ja.md new file mode 100644 index 0000000..5308a2e --- /dev/null +++ b/src/concepts/branching.ja.md @@ -0,0 +1,208 @@ + + +# 分岐と合流性 {#branching-and-confluence} + +```admonish tip title="関連項目" +意味論的な見方:[表示と合成性](../denotational-design/denotations.md)、[法則と解釈](../denotational-design/laws-and-interpretations.md) +Rustで意味から設計する:[法則、シナリオ、証拠](../rust-dd/laws.md) +概念:[操作的意味論](operational_semantics.md) +``` + +計算の選択肢には、分岐、決定性、合流性、トレース等価性、双模倣性が関わります。これらは同じ性質ではありません。 + +```admonish note title="意味論上の位置付け" +制御フローの分岐は操作上の構造です。合流性は簡約関係の性質です。トレース等価性と双模倣性は振る舞いを比較します。表示の等値性は、選択した意味論的領域で意味を比較します。健全な設計では、これらの概念を曖昧に行き来せず、必要とする等値性を明示します。 +``` + +## 振る舞いの等価性 {#behavioral-equivalence} + +並行プログラムや対話型プログラムの結果は、一つとは限りません。標準的な出発点は**ラベル付き遷移系**です。 + +$$ \mathcal{L} = (S, A_{\tau}, \to) $$ + +$S$は状態の集合、$A_{\tau}$は観測可能なアクションラベルの集合と内部アクション$\tau$、$\to\;\subseteq S \times A_{\tau} \times S$は遷移関係です。状態$p$がアクション$a$を実行して状態$p'$になる場合、$p \xrightarrow{a} p'$と書きます。 + +振る舞いの等価性では、こうしたシステム間でどの差異を意図的に無視するかを定めます。 + +* **線形時間の観測**は、完了した実行または部分実行をたどり、その途中で起きたことを記録する。 +* **分岐時間の観測**は、選択肢がどこで提示され、いつ選択が決まったかも保持する。 + +そのため、二つのシステムが同じトレースを持ちながら、分岐構造が異なることがあります。一方が対話の前に二つのアクションから選び、もう一方が対話の後まで選択を延期する場合です。アクションの列は同じでも、その後に可能なことは異なります。 + +Van Glabbeekの[線形時間・分岐時間スペクトル](https://ir.cwi.nl/pub/5685/5685.pdf)は、こうした振る舞いの等価性を体系的に分類した標準的な説明です。弱いものから強いものへの順位ではなく、それぞれ異なる観測の集合を保持します。 + +## Rustプログラムにおける分岐 {#branching-in-rust-programs} + +`if`は条件に応じて一つの分岐を選択します。 + +```rust,noplayground +fn sign(x: i32) -> i32 { + if x > 0 { + 1 + } else if x < 0 { + -1 + } else { + 0 + } +} +``` + +`match`は値に応じて一つのアームを選択します。 + +```rust,noplayground +fn day_type(day: &str) -> &str { + match day { + "Saturday" | "Sunday" => "Weekend", + "Monday" | "Tuesday" | "Wednesday" | "Thursday" | "Friday" => "Weekday", + _ => "Unknown", + } +} +``` + +決定的な言語で入力を固定すると、これらの構文は予測可能な制御フロー経路を選びます。これは**決定性**であり、合流性ではありません。 + +## 合流性の意味 {#what-confluence-means} + +簡約関係の合流性とは、同じ項から行った二つの簡約を、さらに簡約して再び合流させられる性質です。 + +$$ \begin{array}{ccccc} && a && \\ & \swarrow^{*} && \searrow^{*} & \\ b &&&& c \\ & \searrow^{*} && \swarrow^{*} & \\ && d && \end{array} $$ + +形式的には、次が成り立つなら: + +$$ a \to^* b \quad\text{and}\quad a \to^* c $$ + +`d`が存在し、次が成り立たなければなりません。 + +$$ b \to^* d \quad\text{and}\quad c \to^* d $$ + +合流性があっても複数の簡約経路は存在します。それらが共通の後続項へ到達できるという意味で、互いに両立することを表します。 + +## 決定性と合流性 {#determinism-and-confluence} + +決定的な簡約関係では、各状態からの次のステップは高々一つです。そのため、競合する一段階の選択肢を調整する必要がなく、単純な意味では合流的です。 + +逆は成り立ちません。複数の簡約順序を許しながら、最終的にすべてが一致するため合流的なシステムがあります。 + +通常のRustの`if`式と`match`式は、決定的な選択を示します。それだけでは、合流性の興味深い内容を説明できません。 + +## Church–Rosser {#churchrosser} + +Church–Rosserの定理は、ラムダ計算の簡約に関する合流性を示します。ある項が異なる簡約経路で二つの結果に簡約できるとき、それらの結果には共通の簡約形があります。 + +正規形が存在する場合、合流性によってそれが一意であると分かります。評価順が最終的な正規形を変えないため、等式に基づく推論を支えます。 + +この結果を任意の命令型プログラムに一般化しないでください。副作用、非決定的スケジューリング、失敗、中間状態の観測により、簡約順序の違いが意味を持つ場合があります。 + +## トレース {#traces} + +**トレース**は、観測可能なアクションまたは状態の列を記録します。トレース意味論は、結果だけを見る意味論より多くの操作情報を意図的に保持します。 + +二つの純粋関数は同じ結果を返しつつ、内部のステップが異なることがあります。結果のみの表示でそれらのステップを捨てるなら、その表示では等価です。トレース意味論では、必ずしも等価ではありません。 + +副作用がある場合、順序を変えると観測が変わることがあります。 + +```rust,noplayground +fn is_admin() -> bool { + println!("checked admin"); + true +} + +fn is_user() -> bool { + println!("checked user"); + true +} +``` + +`is_admin`を先に確認するか`is_user`を先に確認するかで、分類結果が等価でも出力トレースが異なることがあります。 + +この出力を選択した意味論的領域に含めるかが設計上の問いです。 + +## トレース等価性 {#trace-equivalence} + +選択したトレースモデルで同じ観測トレースを持つとき、二つのシステムはトレース等価です。 + +トレース等価性では分岐構造が無視されることがあります。一方が他方より早く選択を確定する場合も、同じトレースを生成することがあります。対話型および並行システムでは、この違いが重要な場合があります。 + +## 双模倣性 {#bisimulation} + +双模倣性は二つの遷移系を一段階ずつ関連付けます。一方のシステムが観測可能な動作を行うたびに、もう一方もそれに対応する動作を行えなければなりません。そして、遷移先の状態同士も関連したままでなければなりません。 + +一般的な変種: + +* **強双模倣性**:個々の遷移を対応付ける +* **弱双模倣性**:選択された内部遷移を抽象化する +* **分岐双模倣性**:重要な選択構造を保ちながら内部処理を抽象化する + +双模倣性は相互作用の間に選択肢がどう維持されるかを観測するため、トレース等価性より強い振る舞いの比較になることがよくあります。 + +
+由来と形式的な定義 + +Milnerは[*A Calculus of Communicating Systems*](https://www.lfcs.inf.ed.ac.uk/reports/86/ECS-LFCS-86-7/ECS-LFCS-86-7.pdf)で、通信プロセスの観測的等価性を発展させました。その後Parkは[*Concurrency and Automata on Infinite Sequences*](https://wrap.warwick.ac.uk/id/eprint/47224/1/WRAP_Park_cs-rr-035.pdf)で対応する等価性を余帰納的に特徴付け、現在双模倣性として知られる最大不動点関係と証明方法を示しました。Milnerはこの方法を採用し、プロセスの振る舞いを推論する基盤として発展させました。 + +強双模倣性。ラベル付き遷移系で、関係$R$が強双模倣であるとは、$p\mathrel{R}q$のとき、すべてのアクション$a$について次が成り立つことです。 + +* $p\xrightarrow{a}p'$なら、$q'$を満たす状態を経て$q\xrightarrow{a}q'$を実行し、遷移先が$p'\mathrel{R}q'$に関連付けられる状態が存在する。 +* $q\xrightarrow{a}q'$なら、$p'$を満たす状態を経て$p\xrightarrow{a}p'$を実行し、遷移先が$p'\mathrel{R}q'$に関連付けられる状態が存在する。 + +ある双模倣関係が二つの状態を関係付けるなら、それらの状態は双模倣的です。この定義は余帰納的です。遷移に対応付けた後も、遷移先の状態は同じ振る舞い上の責務を満たさなければなりません。 + +分岐双模倣性。一般的な発散を区別しない形式では、対称関係$R$が分岐双模倣であるとは、$p\mathrel{R}q$と$p\xrightarrow{a}p'$から次のいずれかが成り立つことです。 + +* $a = \tau$および$p'\mathrel{R}q$、または + +* 状態$q_0$と$q'$が存在し、次が成り立つ。 + + $$ q \xRightarrow{\tau} q_0 \xrightarrow{a} q', \qquad p\mathrel{R}q_0, \qquad p'\mathrel{R}q' $$ + + +ここで$\xRightarrow{\tau}$は内部遷移が0回以上であることを表します。中間状態$q_0$と$p$が引き続き関連することを要求するため、内部処理を無視しつつ、重要な分岐可能性を保持できます。Van GlabbeekとWeijlandは[*Branching Time and Abstraction in Bisimulation Semantics*](https://ir.cwi.nl/pub/5564/5564D.pdf)で、この等価性を導入し発展させました。 + +
+ +## 表示の等値性 {#denotational-equality} + +表示の等値性は、選択した意味論的領域によって決まります。 + +$$ \llbracket P \rrbracket = \llbracket Q \rrbracket $$ + +領域自体をトレース、双模倣性で割った遷移系、結果の集合、その他の数学的モデルから構築する場合があります。Denotational Designは万能の等値性を一つ指定しません。等値性を明示的に選び、合成的に使うことを求めます。 + +関係は次のとおりです。 + +1. 操作系を出発点にする。 +2. 関係する観測を選ぶ。 +3. 意味論的領域と等値性を選ぶ。 + +## データとしての分岐 {#branching-as-data} + +分岐は木構造にも現れます。二分木の経路は、左右の選択の列として表せます。この表現は、トライ、実行識別子、決定図、メモリーアドレス指定などに有用です。 + +[なぜ意味を先に考えるのか](../denotational-design/semantic-view.md)にある意味論的な分岐位置の例では、木としての意味と一つのビットベクトル符号化を意図的に分けています。 + +Conal Elliottは、完全二分リーフ木構造を使ったメモリーアドレス指定について説明しています。すべての機械がソースレベルの木をそのまま格納するという意味ではありません。合成可能な木モデルによって、平坦な数値アドレスに隠れた有用な構造を明らかにできるということです。 + +
Conal Elliott — 完全二分リーフ木としてのメモリーアドレス指定
+ +## 比較 {#comparison} + +| 概念 | 対象 | 中心となる問い | +| --- | --- | --- | +| 制御フローの分岐 | 一つのプログラム実行 | どの継続が選ばれるか。 | +| 決定性 | 遷移関係 | 次のステップは一意に定まるか。 | +| 合流性 | 簡約関係 | 分岐した簡約を合流させられるか。 | +| トレース等価性 | 観測可能なアクション列 | システムは同じトレースを持つか。 | +| 双模倣性 | 分岐を含む遷移構造 | システム同士で相手の動きに対応できるか。 | +| 表示の等値性 | 選択した意味論的領域 | プログラムは指定された意味を同じく持つか。 | + +これらの概念は互いに補い合うことがありますが、どれも別の概念の同義語として使うべきではありません。 + +## さらに読む {#further-reading} + +* [*A Calculus of Communicating Systems*](https://www.lfcs.inf.ed.ac.uk/reports/86/ECS-LFCS-86-7/ECS-LFCS-86-7.pdf) — MilnerによるCCSと観測的等価性の基礎的な展開 +* [*Concurrency and Automata on Infinite Sequences*](https://wrap.warwick.ac.uk/id/eprint/47224/1/WRAP_Park_cs-rr-035.pdf) — Parkによる双模倣性の余帰納的特徴付け +* [*Algebraic Laws for Nondeterminism and Concurrency*](https://www.scss.tcd.ie/matthew.hennessy/pubs/old/HMjacm85.pdf) — 観測的合同と代数法則に関するHennessyとMilnerの論文 +* [*What Is Branching Time and Why Use It?*](https://theory.stanford.edu/~rvg/branching/)([圧縮PDF](https://cgi.cse.unsw.edu.au/~rvg/pub/branching.pdf.gz))— 分岐構造を保つ動機を簡潔に説明 +* [*The Linear Time–Branching Time Spectrum*](https://ir.cwi.nl/pub/5685/5685.pdf) — 振る舞いの等価性に関する標準的な分類 +* [*Branching Time and Abstraction in Bisimulation Semantics*](https://ir.cwi.nl/pub/5564/5564D.pdf) — 分岐双模倣性に関する基礎的な論文 +* [*Three Logics for Branching Bisimulation*](https://ir.cwi.nl/pub/1370/1370D.pdf) — Hennessy–Milner型の論理や次時点演算子のないCTL\*による論理的な特徴付け diff --git a/src/concepts/branching.ko.md b/src/concepts/branching.ko.md new file mode 100644 index 0000000..4b1a3b6 --- /dev/null +++ b/src/concepts/branching.ko.md @@ -0,0 +1,208 @@ + + +# 분기와 합류성 {#branching-and-confluence} + +```admonish tip title="관련 항목" +의미론적 관점: [표시와 합성성](../denotational-design/denotations.md), [법칙과 해석](../denotational-design/laws-and-interpretations.md) +Rust에서 의미로 설계하기: [법칙, 시나리오, 증거](../rust-dd/laws.md) +개념: [작동 의미론](operational_semantics.md) +``` + +분기, 결정성, 합류성, 실행 기록 동치, 쌍방향 시뮬레이션은 모두 계산의 여러 가능성을 다룹니다. 하지만 같은 속성은 아닙니다. + +```admonish note title="의미론적 위치" +제어 흐름 분기는 작동 구조입니다. 합류성은 축약 관계의 속성입니다. 실행 기록 동치와 쌍방향 시뮬레이션은 동작을 비교합니다. 표시적 동등성은 선택한 의미론적 영역에서 의미를 비교합니다. 건전한 설계는 이런 개념 사이를 막연하게 오가지 말고 필요한 동등성이 무엇인지 명시합니다. +``` + +## 동작 동치 {#behavioral-equivalence} + +동시성 및 대화형 프로그램은 최종 결과가 하나뿐인 경우가 드뭅니다. 일반적인 출발점은 **레이블 전이 시스템**입니다: + +$$ \mathcal{L} = (S, A_{\tau}, \to) $$ + +여기서 $S$는 상태 집합이고, $A_{\tau}$은 관찰 가능한 동작 레이블과 내부 동작 $\tau$의 집합이며, $\to\;\subseteq S \times A_{\tau} \times S$은 전이 관계입니다. 상태 $p$가 동작 $a$을 수행해 $p'$가 될 수 있을 때 $p \xrightarrow{a} p'$라고 씁니다. + +동작 동치는 이런 시스템 사이에서 어떤 차이를 의도적으로 무시할지 지정합니다: + +* **선형 시간 관찰**은 완료되거나 부분적으로 실행된 과정을 따라가며 그동안 일어난 일을 기록합니다 +* **분기 시간 관찰**은 대안이 가능한 지점과 선택이 확정되는 시기도 보존합니다 + +따라서 두 시스템이 같은 실행 기록을 허용하면서도 분기 구조는 다를 수 있습니다. 하나는 상호작용 전에 두 동작 중 하나를 고르고 다른 하나는 상호작용 뒤로 선택을 미룰 수 있습니다. 동작 순서는 같지만 앞으로 가능한 경우는 다릅니다. + +van Glabbeek의 [선형 시간–분기 시간 스펙트럼](https://ir.cwi.nl/pub/5685/5685.pdf)은 이런 동작 동치를 체계적으로 설명하는 표준 틀입니다. 약한 것에서 강한 것으로 단순 순위를 매기는 것이 아니라, 각 지점이 서로 다른 관찰 집합을 보존합니다. + +## Rust 프로그램의 분기 {#branching-in-rust-programs} + +`if`는 조건에 따라 한 분기를 선택합니다: + +```rust,noplayground +fn sign(x: i32) -> i32 { + if x > 0 { + 1 + } else if x < 0 { + -1 + } else { + 0 + } +} +``` + +`match`는 값에 따라 한 갈래를 선택합니다: + +```rust,noplayground +fn day_type(day: &str) -> &str { + match day { + "Saturday" | "Sunday" => "Weekend", + "Monday" | "Tuesday" | "Wednesday" | "Thursday" | "Friday" => "Weekday", + _ => "Unknown", + } +} +``` + +결정적 언어에서 입력이 고정되어 있으면 이러한 구성은 예측 가능한 제어 흐름 경로를 선택합니다. 이 속성은 **결정성**이며 합류성이 아닙니다. + +## 합류성이란 {#what-confluence-means} + +같은 항에서 시작한 두 축약이 다시 하나로 합쳐질 수 있을 때 축약 관계는 합류적입니다: + +$$ \begin{array}{ccccc} && a && \\ & \swarrow^{*} && \searrow^{*} & \\ b &&&& c \\ & \searrow^{*} && \swarrow^{*} & \\ && d && \end{array} $$ + +형식적으로 다음이 성립하면: + +$$ a \to^* b \quad\text{and}\quad a \to^* c $$ + +그런 다음 어떤 `d`가 존재하여 다음이 성립해야 합니다: + +$$ b \to^* d \quad\text{and}\quad c \to^* d $$ + +합류성은 여러 축약 경로를 허용합니다. 그 경로들이 공통 후속 상태에 도달할 수 있다는 의미에서 서로 양립한다고 말합니다. + +## 결정성과 합류성 {#determinism-and-confluence} + +결정적 축약 관계에서는 상태마다 다음 단계가 최대 하나입니다. 따라서 조정해야 할 경쟁 전이가 없으므로 간단한 의미에서 합류적입니다. + +역은 성립하지 않습니다. 여러 축약 순서를 허용하면서도 모든 순서가 결국 같은 결과에 도달하는 시스템이 있을 수 있습니다. + +일반 Rust의 `if` 및 `match` 표현식은 결정적 선택의 예입니다. 그것만으로 합류성의 흥미로운 내용을 보여 주지는 않습니다. + +## Church–Rosser {#churchrosser} + +Church–Rosser 정리는 람다 계산의 축약에 대한 합류성 속성을 말합니다. 서로 다른 축약 경로로 하나의 항이 두 결과에 도달하면 그 결과들에는 공통 축약형이 있습니다. + +정규형이 존재한다면 합류성은 그 정규형이 유일함을 뜻합니다. 평가 순서와 무관하게 최종 정규형이 같으므로 등식 추론에 도움이 됩니다. + +이 결과를 임의의 명령형 프로그램에 일반화하지 마세요. 부작용, 비결정적 스케줄링, 실패, 중간 상태 관찰이 축약 순서를 구분할 수 있습니다. + +## 실행 기록 {#traces} + +**실행 기록**은 관찰 가능한 동작이나 상태의 시퀀스를 기록합니다. 실행 기록 의미론은 결과만 보는 의미론보다 작동 정보를 의도적으로 더 많이 보존합니다. + +두 순수 함수가 내부적으로 다른 단계를 거쳐도 같은 결과를 반환할 수 있습니다. 그 단계를 무시하는 결과 표시에선 서로 같습니다. 실행 기록 의미론에서는 반드시 같지는 않습니다. + +효과가 있으면 순서 변경이 관찰을 바꿀 수 있습니다: + +```rust,noplayground +fn is_admin() -> bool { + println!("checked admin"); + true +} + +fn is_user() -> bool { + println!("checked user"); + true +} +``` + +`is_admin`를 먼저 검사하는 것과 `is_user`를 먼저 검사하는 것은 동등한 분류 결과를 반환해도 서로 다른 실행 기록을 출력할 수 있습니다. + +그 출력이 선택한 의미론적 영역에 속하는지가 설계 질문입니다. + +## 실행 기록 동치 {#trace-equivalence} + +선택한 실행 기록 모델에서 같은 관찰 실행 기록을 허용할 때 두 시스템은 실행 기록 동치입니다. + +실행 기록 동치는 분기 구조를 무시할 수 있습니다. 한 시스템이 다른 시스템보다 일찍 선택을 확정해도 같은 실행 기록을 생성할 수 있습니다. 대화형 및 동시성 시스템에서는 그 차이가 중요할 수 있습니다. + +## 쌍방향 시뮬레이션 {#bisimulation} + +쌍방향 시뮬레이션은 두 전이 시스템을 단계별로 연관시킵니다. 한 시스템이 관찰 가능한 동작을 하면 다른 시스템도 이를 맞출 수 있어야 하며, 그 결과 상태들도 계속 연관되어야 합니다. + +일반적인 변형은 다음과 같습니다: + +* **강한 쌍방향 시뮬레이션**은 개별 전이를 대응시킵니다 +* **약한 쌍방향 시뮬레이션**은 선택된 내부 전이를 추상화합니다 +* **분기 쌍방향 시뮬레이션**은 중요한 선택 구조를 보존하면서 내부 작업을 추상화합니다 + +쌍방향 시뮬레이션은 상호작용 중 대안이 계속 가능한 방식을 관찰하므로 실행 기록 동치보다 더 강한 동작 비교인 경우가 많습니다. + +
+기원과 형식 정의 + +Milner는 [*A Calculus of Communicating Systems*](https://www.lfcs.inf.ed.ac.uk/reports/86/ECS-LFCS-86-7/ECS-LFCS-86-7.pdf)에서 통신 프로세스의 관찰적 동치를 발전시켰습니다. Park는 [*Concurrency and Automata on Infinite Sequences*](https://wrap.warwick.ac.uk/id/eprint/47224/1/WRAP_Park_cs-rr-035.pdf)에서 그에 대응하는 동치를 쌍대 귀납적으로 규정하여, 오늘날 쌍방향 시뮬레이션으로 알려진 최대 고정점 관계와 증명 방법을 제시했습니다. Milner는 이 방법을 프로세스 동작 추론의 토대로 채택하고 발전시켰습니다. + +**강한 쌍방향 시뮬레이션.** 레이블 전이 시스템에서 관계 $R$는 $p\mathrel{R}q$일 때 강한 쌍방향 시뮬레이션입니다. 모든 동작 $a$에 대해: + +* $p\xrightarrow{a}p'$이면 $q'$을 만족하는 어떤 $q\xrightarrow{a}q'$가 존재하고 $p'\mathrel{R}q'$이어야 합니다. 그리고 +* $q\xrightarrow{a}q'$이면 $p'$을 만족하는 어떤 $p\xrightarrow{a}p'$가 존재하고 $p'\mathrel{R}q'$이어야 합니다. + +어떤 쌍방향 시뮬레이션이 두 상태를 연관시키면 두 상태는 쌍방향 시뮬레이션 동치입니다. 정의는 쌍대 귀납적입니다. 전이를 대응시킨 뒤에도 후속 상태에 같은 동작 의무가 다시 적용됩니다. + +**분기 쌍방향 시뮬레이션.** 흔히 쓰이는 발산을 무시하는 설명에서 대칭 관계 $R$는 $p\mathrel{R}q$ 및 $p\xrightarrow{a}p'$가 참일 때 다음 둘 중 하나를 만족하면 분기 쌍방향 시뮬레이션입니다: + +* $a = \tau$ 및 $p'\mathrel{R}q$, 또는 + +* 다음과 같은 상태 $q_0$와 $q'$이 존재합니다 + + $$ q \xRightarrow{\tau} q_0 \xrightarrow{a} q', \qquad p\mathrel{R}q_0, \qquad p'\mathrel{R}q' $$ + + +여기서 $\xRightarrow{\tau}$는 내부 전이가 0회 이상 있음을 나타냅니다. 중간 상태 $q_0$가 $p$와 계속 연관되어야 한다는 조건은 내부 작업을 무시할 수 있게 하면서 관련 분기 가능성을 보존합니다. van Glabbeek과 Weijland는 [*Branching Time and Abstraction in Bisimulation Semantics*](https://ir.cwi.nl/pub/5564/5564D.pdf)에서 이 동치를 도입하고 발전시켰습니다. + +
+ +## 표시적 동등성 {#denotational-equality} + +표시적 동등성은 선택한 의미론적 영역에 따라 달라집니다: + +$$ \llbracket P \rrbracket = \llbracket Q \rrbracket $$ + +영역 자체가 실행 기록, 쌍방향 시뮬레이션에 따라 몫을 취한 전이 시스템, 결과 집합 또는 다른 수학적 모델로 구성될 수 있습니다. 표시적 설계는 보편적인 단일 동등성을 규정하지 않습니다. 동등성을 명시적으로 선택해 합성적으로 사용해야 합니다. + +관계는 다음과 같습니다: + +1. 작동 시스템에서 시작합니다. +2. 관련 관찰을 선택합니다. +3. 의미론적 영역과 동등성을 선택합니다. + +## 데이터로서의 분기 {#branching-as-data} + +분기는 트리 구조로도 나타납니다. 이진 경로는 왼쪽/오른쪽 선택의 시퀀스로 표현할 수 있습니다. 이 표현은 트라이, 실행 식별자, 결정 다이어그램, 메모리 주소 지정에 유용합니다. + +[왜 의미가 먼저인가](../denotational-design/semantic-view.md)의 분기 위치 의미 예시는 트리의 의미와 비트 벡터 인코딩 하나를 의도적으로 구분합니다. + +Conal Elliott는 완전 이진 리프 트리 구조를 사용해 메모리 주소 지정을 설명했습니다. 기계가 언제나 소스 수준 트리를 그대로 저장한다는 뜻이 아닙니다. 합성 가능한 트리 모델이 평면 수치 주소에서는 감춰진 유용한 구조를 드러낼 수 있다는 뜻입니다. + +
Conal Elliott — 완전 이진 리프 트리로 본 메모리 주소 지정
+ +## 비교 {#comparison} + +| 개념 | 대상 | 핵심 질문 | +| --- | --- | --- | +| 제어 흐름 분기 | 프로그램 실행 한 번 | 어떤 연속 실행이 선택되는가? | +| 결정성 | 전이 관계 | 다음 단계가 유일하게 정해지는가? | +| 합류성 | 축약 관계 | 서로 다른 축약이 합쳐질 수 있는가? | +| 실행 기록 동치 | 관찰 가능한 동작 시퀀스 | 시스템이 같은 실행 기록을 허용하는가? | +| 쌍방향 시뮬레이션 | 분기 전이 구조 | 시스템이 서로의 동작을 대응할 수 있는가? | +| 표시적 동등성 | 선택한 의미론적 영역 | 프로그램이 명세상 같은 의미를 가지는가? | + +이 개념들은 서로 뒷받침할 수 있지만, 어느 것도 다른 개념의 동의어로 사용해서는 안 됩니다. + +## 더 읽을거리 {#further-reading} + +* [*A Calculus of Communicating Systems*](https://www.lfcs.inf.ed.ac.uk/reports/86/ECS-LFCS-86-7/ECS-LFCS-86-7.pdf) — CCS와 관찰적 동치에 관한 Milner의 기초 저작 +* [*Concurrency and Automata on Infinite Sequences*](https://wrap.warwick.ac.uk/id/eprint/47224/1/WRAP_Park_cs-rr-035.pdf) — 쌍방향 시뮬레이션에 대한 Park의 쌍대 귀납적 정식화 +* [*Algebraic Laws for Nondeterminism and Concurrency*](https://www.scss.tcd.ie/matthew.hennessy/pubs/old/HMjacm85.pdf) — 관찰적 합동과 대수 법칙에 관한 Hennessy와 Milner의 연구 +* [*What Is Branching Time and Why Use It?*](https://theory.stanford.edu/~rvg/branching/) ([압축 PDF](https://cgi.cse.unsw.edu.au/~rvg/pub/branching.pdf.gz)) — 분기 구조를 보존하는 이유를 간결하게 설명 +* [*The Linear Time–Branching Time Spectrum*](https://ir.cwi.nl/pub/5685/5685.pdf) — 동작 동치의 표준 분류 +* [*Branching Time and Abstraction in Bisimulation Semantics*](https://ir.cwi.nl/pub/5564/5564D.pdf) — 분기 쌍방향 시뮬레이션의 기초 연구 +* [*Three Logics for Branching Bisimulation*](https://ir.cwi.nl/pub/1370/1370D.pdf) — 다음 시간 연산자가 없는 Hennessy–Milner식 논리와 CTL\*를 통한 논리적 특성화 diff --git a/src/concepts/branching.ru.md b/src/concepts/branching.ru.md new file mode 100644 index 0000000..fb717f5 --- /dev/null +++ b/src/concepts/branching.ru.md @@ -0,0 +1,208 @@ + + +# Ветвление и конфлюэнтность {#branching-and-confluence} + +```admonish tip title="Связанные материалы" +«Семантический взгляд»: [Денотации и композиционность](../denotational-design/denotations.md), [Законы и интерпретации](../denotational-design/laws-and-interpretations.md) +«Проектирование на основе смысла в Rust»: [Законы, сценарии и свидетельства](../rust-dd/laws.md) +«Понятия»: [Операционная семантика](operational_semantics.md) +``` + +Ветвление, детерминизм, конфлюэнтность, эквивалентность трасс и бисимуляция — разные свойства, связанные с альтернативами в вычислении. + +```admonish note title="Семантическое место" +Ветвление потока управления — операционная структура. Конфлюэнтность — свойство отношения редукции. Эквивалентность трасс и бисимуляция сравнивают поведение. Денотационное равенство сравнивает смыслы в выбранной семантической области. Корректный проект явно указывает нужное равенство, не смешивая эти понятия. +``` + +## Поведенческая эквивалентность {#behavioral-equivalence} + +У параллельных и интерактивных программ редко бывает лишь один конечный результат. Стандартной отправной точкой служит **система помеченных переходов**: + +$$ \mathcal{L} = (S, A_{\tau}, \to) $$ + +где $S$ — множество состояний, $A_{\tau}$ — множество меток наблюдаемых действий вместе с внутренним действием $\tau$, а $\to\;\subseteq S \times A_{\tau} \times S$ — отношение переходов. Запись $p \xrightarrow{a} p'$ означает, что состояние $p$ может выполнить действие $a$ и перейти в состояние $p'$. + +Поведенческая эквивалентность задаёт, какие различия между такими системами намеренно опускаются: + +* **Наблюдения линейного времени** следуют за завершёнными или частичными выполнениями и фиксируют происходившее +* **Наблюдения ветвящегося времени** также сохраняют информацию о том, где были доступны альтернативы и когда был сделан выбор + +Поэтому две системы могут допускать одни и те же трассы, но иметь разную структуру ветвления. Одна может выбирать между двумя действиями до взаимодействия, другая — откладывать выбор до его завершения. Последовательности действий совпадают, но будущие возможности различаются. + +Спектр [линейное время — ветвящееся время](https://ir.cwi.nl/pub/5685/5685.pdf) ван Глаббека систематически описывает такие поведенческие эквивалентности. Это не шкала от слабой к сильной: в каждой точке сохраняется свой набор наблюдений. + +## Ветвление в программах на Rust {#branching-in-rust-programs} + +`if` выбирает ветвь в зависимости от условия: + +```rust,noplayground +fn sign(x: i32) -> i32 { + if x > 0 { + 1 + } else if x < 0 { + -1 + } else { + 0 + } +} +``` + +`match` выбирает одну ветку по значению: + +```rust,noplayground +fn day_type(day: &str) -> &str { + match day { + "Saturday" | "Sunday" => "Weekend", + "Monday" | "Tuesday" | "Wednesday" | "Thursday" | "Friday" => "Weekday", + _ => "Unknown", + } +} +``` + +При фиксированных входных данных в детерминированном языке эти конструкции предсказуемо выбирают путь потока управления. Это свойство называется **детерминизмом**, а не конфлюэнтностью. + +## Что такое конфлюэнтность {#what-confluence-means} + +Отношение редукции конфлюэнтно, если два перехода из одного терма можно снова свести к общему результату: + +$$ \begin{array}{ccccc} && a && \\ & \swarrow^{*} && \searrow^{*} & \\ b &&&& c \\ & \searrow^{*} && \swarrow^{*} & \\ && d && \end{array} $$ + +Формально, если: + +$$ a \to^* b \quad\text{and}\quad a \to^* c $$ + +то должен существовать некоторый `d`, такой что: + +$$ b \to^* d \quad\text{and}\quad c \to^* d $$ + +Конфлюэнтность допускает несколько путей редукции. Она означает, что эти пути совместимы и могут привести к общему последующему состоянию. + +## Детерминизм и конфлюэнтность {#determinism-and-confluence} + +У детерминированного отношения редукции из каждого состояния возможен не более чем один следующий шаг. Поэтому оно конфлюэнтно в простом смысле: конкурирующих вариантов одного шага, которые нужно согласовывать, нет. + +Обратное неверно. Система может допускать разные порядки редукции и при этом быть конфлюэнтной, поскольку все порядки в итоге приводят к общему результату. + +Обычные выражения Rust `if` и `match` демонстрируют детерминированный выбор, но сами по себе не иллюстрируют содержательную конфлюэнтность. + +## Чёрч — Россер {#churchrosser} + +Теорема Чёрча — Россера утверждает конфлюэнтность редукции лямбда-исчисления. Если терм разными путями редукции переходит к двум результатам, у этих результатов есть общий редукт. + +Если нормальная форма существует, конфлюэнтность гарантирует её единственность. Это поддерживает рассуждения через равенства: порядок вычисления не меняет конечную нормальную форму. + +Не переносите этот результат на произвольные императивные программы. Побочные эффекты, недетерминированное планирование, сбои и наблюдение промежуточных состояний могут различать порядки редукции. + +## Трассы {#traces} + +**Трасса** фиксирует последовательность наблюдаемых действий или состояний. Трассовая семантика намеренно сохраняет больше операционной информации, чем семантика, учитывающая только результат. + +Две чистые функции могут возвращать один результат, пройдя через разные внутренние шаги. Они равны в денотации результатов, если эти шаги опускаются, но не обязательно равны в трассовой семантике. + +При наличии эффектов перестановка условий может менять наблюдаемые результаты: + +```rust,noplayground +fn is_admin() -> bool { + println!("checked admin"); + true +} + +fn is_user() -> bool { + println!("checked user"); + true +} +``` + +Если сначала проверить `is_admin`, а затем `is_user`, или наоборот, классификация может оказаться эквивалентной, но трассы печати будут различаться. + +Проектный вопрос состоит в том, входят ли эти сообщения в выбранную семантическую область. + +## Эквивалентность трасс {#trace-equivalence} + +Две системы эквивалентны по трассам, если в выбранной модели допускают одинаковые наблюдаемые трассы. + +Эквивалентность трасс может опускать структуру ветвления. Две системы могут порождать одинаковые трассы, даже если одна фиксирует выбор раньше другой. Для интерактивных и параллельных систем это различие может быть важным. + +## Бисимуляция {#bisimulation} + +Бисимуляция связывает две системы переходов шаг за шагом. Когда одна система выполняет наблюдаемый переход, другая должна уметь ему соответствовать, а полученные состояния должны оставаться связанными. + +Распространённые варианты: + +* **сильная бисимуляция**, сопоставляющая отдельные переходы +* **слабая бисимуляция**, опускающая выбранные внутренние переходы +* **ветвящаяся бисимуляция**, опускающая внутреннюю работу, но сохраняющая важную структуру выбора + +Бисимуляция часто даёт более строгий способ сравнения поведения, чем эквивалентность трасс, поскольку учитывает, какие альтернативы остаются доступными в ходе взаимодействия. + +
+Истоки и формальные определения + +Милнер разработал наблюдательную эквивалентность процессов в книге [*A Calculus of Communicating Systems*](https://www.lfcs.inf.ed.ac.uk/reports/86/ECS-LFCS-86-7/ECS-LFCS-86-7.pdf). Затем Парк дал коиндуктивную характеристику соответствующей эквивалентности в работе [*Concurrency and Automata on Infinite Sequences*](https://wrap.warwick.ac.uk/id/eprint/47224/1/WRAP_Park_cs-rr-035.pdf), введя отношение наибольшей неподвижной точки и метод доказательства, ныне известный как бисимуляция. Милнер перенял и развил этот метод как основу рассуждений о поведении процессов. + +**Сильная бисимуляция.** Для систем помеченных переходов отношение $R$ является сильной бисимуляцией, если из $p\mathrel{R}q$ следует для каждого действия $a$: + +* если $p\xrightarrow{a}p'$, то существует $q'$, удовлетворяющее $q\xrightarrow{a}q'$ и $p'\mathrel{R}q'$; и +* если $q\xrightarrow{a}q'$, то существует $p'$, удовлетворяющее $p\xrightarrow{a}p'$ и $p'\mathrel{R}q'$. + +Два состояния бисимилярны, если их связывает некоторая бисимуляция. Определение коиндуктивно: после сопоставления перехода состояния-преемники вновь должны удовлетворять тому же требованию поведения. + +**Ветвящаяся бисимуляция.** В распространённой версии, не учитывающей дивергенцию, симметричное отношение $R$ является ветвящейся бисимуляцией, если $p\mathrel{R}q$ и $p\xrightarrow{a}p'$ влекут одно из двух: + +* $a = \tau$ и $p'\mathrel{R}q$; или + +* существуют состояния $q_0$ и $q'$, такие что + + $$ q \xRightarrow{\tau} q_0 \xrightarrow{a} q', \qquad p\mathrel{R}q_0, \qquad p'\mathrel{R}q' $$ + + +Здесь $\xRightarrow{\tau}$ означает ноль или более внутренних переходов. Требование, чтобы промежуточное состояние $q_0$ оставалось связанным с $p$, сохраняет важные возможности ветвления, позволяя игнорировать внутреннюю работу. Ван Глаббек и Вейланд ввели и развили эту эквивалентность в работе [*Branching Time and Abstraction in Bisimulation Semantics*](https://ir.cwi.nl/pub/5564/5564D.pdf). + +
+ +## Денотационное равенство {#denotational-equality} + +Денотационное равенство зависит от выбранной семантической области: + +$$ \llbracket P \rrbracket = \llbracket Q \rrbracket $$ + +Сама область может быть построена на трассах, системах переходов по модулю бисимуляции, множествах результатов или другой математической модели. Денотационное проектирование не предписывает единого универсального равенства. Оно требует явно выбрать его и использовать композиционно. + +Связь между понятиями такова: + +1. Начните с операционной системы. +2. Выберите значимые наблюдения. +3. Выберите семантическую область и отношение равенства. + +## Ветвление как данные {#branching-as-data} + +Ветвление также встречается как структура дерева. Бинарный путь можно представить последовательностью решений «влево/вправо». Это полезное представление для префиксных деревьев, идентификаторов выполнения, диаграмм решений и адресации памяти. + +Пример семантической позиции ветвления в разделе [«Почему начинать нужно со смысла»](../denotational-design/semantic-view.md) намеренно отделяет смысл дерева от одного конкретного битового представления. + +Конал Эллиотт описывал адресацию памяти через структуру совершенного бинарного дерева листьев. Смысл не в том, что каждая машина буквально хранит исходное дерево, а в том, что композиционная модель дерева может раскрыть полезную структуру, скрытую плоскими числовыми адресами. + +
Конал Эллиотт — адресация памяти как совершенное бинарное дерево листьев
+ +## Сравнение {#comparison} + +| Понятие | Предмет | Главный вопрос | +| --- | --- | --- | +| Ветвление потока управления | Одно выполнение программы | Какое продолжение выбрано? | +| Детерминизм | Отношение переходов | Однозначно ли определён следующий шаг? | +| Конфлюэнтность | Отношение редукции | Можно ли свести расходящиеся редукции? | +| Эквивалентность трасс | Последовательности наблюдаемых действий | Допускают ли системы одни и те же трассы? | +| Бисимуляция | Структура ветвления переходов | Могут ли системы сопоставлять переходы друг друга? | +| Денотационное равенство | Выбранная семантическая область | Имеют ли программы один и тот же заданный смысл? | + +Эти понятия могут дополнять друг друга, но ни одно нельзя использовать как синоним другого. + +## Дополнительная литература {#further-reading} + +* [*A Calculus of Communicating Systems*](https://www.lfcs.inf.ed.ac.uk/reports/86/ECS-LFCS-86-7/ECS-LFCS-86-7.pdf) — основополагающая работа Милнера о CCS и наблюдательной эквивалентности +* [*Concurrency and Automata on Infinite Sequences*](https://wrap.warwick.ac.uk/id/eprint/47224/1/WRAP_Park_cs-rr-035.pdf) — коиндуктивная характеристика бисимуляции у Парка +* [*Algebraic Laws for Nondeterminism and Concurrency*](https://www.scss.tcd.ie/matthew.hennessy/pubs/old/HMjacm85.pdf) — работа Хеннесси и Милнера о наблюдательной конгруэнтности и алгебраических законах +* [*What Is Branching Time and Why Use It?*](https://theory.stanford.edu/~rvg/branching/) ([сжатый PDF](https://cgi.cse.unsw.edu.au/~rvg/pub/branching.pdf.gz)) — краткое обоснование того, зачем сохранять структуру ветвления +* [*The Linear Time–Branching Time Spectrum*](https://ir.cwi.nl/pub/5685/5685.pdf) — стандартная классификация поведенческих эквивалентностей +* [*Branching Time and Abstraction in Bisimulation Semantics*](https://ir.cwi.nl/pub/5564/5564D.pdf) — основополагающая работа о ветвящейся бисимуляции +* [*Three Logics for Branching Bisimulation*](https://ir.cwi.nl/pub/1370/1370D.pdf) — логические характеристики на основе логик в стиле Хеннесси — Милнера и CTL\* без оператора следующего времени diff --git a/src/concepts/branching.uk.md b/src/concepts/branching.uk.md new file mode 100644 index 0000000..6fd43af --- /dev/null +++ b/src/concepts/branching.uk.md @@ -0,0 +1,208 @@ + + +# Розгалуження та конфлюентність {#branching-and-confluence} + +```admonish tip title="Пов’язані матеріали" +Семантичний погляд: [Денотації та композиційність](../denotational-design/denotations.md), [Закони та інтерпретації](../denotational-design/laws-and-interpretations.md) +Проєктування від значення в Rust: [Закони, сценарії та свідчення](../rust-dd/laws.md) +Поняття: [Операційна семантика](operational_semantics.md) +``` + +Розгалуження, детермінізм, конфлюентність, еквівалентність трас і бісимілярність стосуються альтернатив в обчисленні. Це не одна й та сама властивість. + +```admonish note title="Семантичне місце" +Розгалуження потоку керування — це операційна структура. Конфлюентність — властивість відношення редукції. Еквівалентність трас і бісимілярність порівнюють поведінку. Денотаційна рівність порівнює значення у вибраній семантичній області. У коректному проєкті прямо вказують потрібну рівність, а не неформально переходять від одного поняття до іншого. +``` + +## Еквівалентність поведінки {#behavioral-equivalence} + +Паралельні й інтерактивні програми рідко мають лише один кінцевий результат. Зазвичай починають із **системи переходів із мітками**: + +$$ \mathcal{L} = (S, A_{\tau}, \to) $$ + +де $S$ — множина станів, $A_{\tau}$ — множина міток спостережуваних дій разом із внутрішньою дією $\tau$, а $\to\;\subseteq S \times A_{\tau} \times S$ — відношення переходів. Запис $p \xrightarrow{a} p'$ означає, що стан $p$ може виконати дію $a$ і перейти до $p'$. + +Еквівалентність поведінки визначає, які відмінності між такими системами навмисно ігнорують: + +* **Спостереження лінійного часу** простежують завершені чи часткові виконання й фіксують події на їхньому шляху +* **Спостереження розгалуженого часу** також зберігають інформацію про доступні альтернативи й момент остаточного вибору + +Тому дві системи можуть мати однакові траси, але різну структуру розгалуження. Одна може вибрати між двома діями до взаємодії, а інша — відкласти вибір до її завершення. Послідовності дій однакові, але майбутні можливості — ні. + +[Спектр еквівалентностей лінійного й розгалуженого часу](https://ir.cwi.nl/pub/5685/5685.pdf) ван Ґлаббека систематизує такі еквівалентності поведінки. Це не рейтинг від слабких до сильних: кожна точка спектра зберігає свій набір спостережень. + +## Розгалуження в програмах Rust {#branching-in-rust-programs} + +`if` вибирає одну гілку за умовою: + +```rust,noplayground +fn sign(x: i32) -> i32 { + if x > 0 { + 1 + } else if x < 0 { + -1 + } else { + 0 + } +} +``` + +`match` вибирає одну гілку за значенням: + +```rust,noplayground +fn day_type(day: &str) -> &str { + match day { + "Saturday" | "Sunday" => "Weekend", + "Monday" | "Tuesday" | "Wednesday" | "Thursday" | "Friday" => "Weekday", + _ => "Unknown", + } +} +``` + +За фіксованих вхідних даних у детермінованій мові ці конструкції вибирають передбачуваний шлях потоку керування. Це **детермінізм**, а не конфлюентність. + +## Що означає конфлюентність {#what-confluence-means} + +Відношення редукції є конфлюентним, якщо два перетворення того самого терма можна знову звести докупи: + +$$ \begin{array}{ccccc} && a && \\ & \swarrow^{*} && \searrow^{*} & \\ b &&&& c \\ & \searrow^{*} && \swarrow^{*} & \\ && d && \end{array} $$ + +Формально, якщо: + +$$ a \to^* b \quad\text{and}\quad a \to^* c $$ + +то має існувати деяке `d`, для якого: + +$$ b \to^* d \quad\text{and}\quad c \to^* d $$ + +Конфлюентність допускає кілька шляхів редукції. Вона стверджує, що ці шляхи узгоджуються, бо можуть привести до спільного наступника. + +## Детермінізм і конфлюентність {#determinism-and-confluence} + +У детермінованого відношення редукції з кожного стану можливий не більш як один наступний крок. Отже, воно конфлюентне у простому сенсі: немає конкуруючих однокрокових виборів, які треба узгоджувати. + +Обернене твердження хибне. Система може допускати кілька порядків редукції й лишатися конфлюентною, якщо всі вони зрештою узгоджуються. + +Звичайні вирази Rust `if` та `match` демонструють детермінований вибір, але самі по собі не показують нетривіальну суть конфлюентності. + +## Черч—Россер {#churchrosser} + +Теорема Черча—Россера стверджує конфлюентність для редукції лямбда-числення: якщо терм різними шляхами редукції переходить до двох результатів, вони мають спільне зведення. + +Якщо існує нормальна форма, конфлюентність гарантує її унікальність. Це підтримує рівняннєве міркування, адже порядок обчислення не змінює кінцеву нормальну форму. + +Не поширюйте цей результат на довільні імперативні програми. Побічні ефекти, недетермінований розклад, збої й спостереження проміжних станів можуть розрізняти порядки редукції. + +## Траси {#traces} + +**Траса** фіксує послідовність спостережуваних дій чи станів. Трасова семантика навмисно зберігає більше операційної інформації, ніж семантика лише результатів. + +Дві чисті функції можуть повертати однаковий результат, проходячи різні внутрішні кроки. Якщо ці кроки відкинуто, у денотації за результатом функції рівні. У трасовій семантиці вони не обов’язково рівні. + +За наявності ефектів перестановка умов може змінити спостереження: + +```rust,noplayground +fn is_admin() -> bool { + println!("checked admin"); + true +} + +fn is_user() -> bool { + println!("checked user"); + true +} +``` + +Перевірка `is_admin` першою або перевірка `is_user` першою може повернути еквівалентні класифікації, але створити різні траси виводу. + +Проєктне запитання полягає в тому, чи належить цей вивід до вибраної семантичної області. + +## Еквівалентність трас {#trace-equivalence} + +Дві системи є еквівалентними за трасами, якщо згідно з вибраною моделлю трас вони допускають ті самі спостережувані траси. + +Еквівалентність трас може не враховувати структуру розгалуження. Дві системи можуть породжувати ті самі траси, хоча одна фіксує вибір раніше за іншу. Для інтерактивних і паралельних систем це може мати значення. + +## Бісимілярність {#bisimulation} + +Бісимілярність співвідносить дві системи переходів покроково. Кожному спостережуваному кроку однієї системи має відповідати крок іншої, а отримані стани й далі мають бути співвіднесені. + +Поширені різновиди: + +* **сильна бісимілярність**, яка зіставляє окремі переходи +* **слабка бісимілярність**, яка абстрагується від вибраних внутрішніх переходів +* **розгалужена бісимілярність**, яка ігнорує внутрішню роботу, зберігаючи важливу структуру вибору + +Бісимілярність часто є сильнішим способом порівняти поведінку, ніж еквівалентність трас, адже вона враховує, які альтернативи лишаються доступними під час взаємодії. + +
+Походження та формальні визначення + +Мілнер розробив спостережувану еквівалентність для процесів взаємодії у [*A Calculus of Communicating Systems*](https://www.lfcs.inf.ed.ac.uk/reports/86/ECS-LFCS-86-7/ECS-LFCS-86-7.pdf). Парк згодом охарактеризував відповідну еквівалентність коіндуктивно у [*Concurrency and Automata on Infinite Sequences*](https://wrap.warwick.ac.uk/id/eprint/47224/1/WRAP_Park_cs-rr-035.pdf), сформулювавши відношення найбільшої нерухомої точки й метод доведення, який тепер називають бісимілярністю. Мілнер перейняв і розвинув цей метод як основу міркування про поведінку процесів. + +**Сильна бісимілярність.** Для систем переходів із мітками відношення $R$ є сильною бісимілярністю, якщо $p\mathrel{R}q$ виконується, а для кожної дії $a$: + +* якщо $p\xrightarrow{a}p'$, то існує $q'$, для якого виконується $q\xrightarrow{a}q'$ та $p'\mathrel{R}q'$; і +* якщо $q\xrightarrow{a}q'$, то існує $p'$, для якого виконується $p\xrightarrow{a}p'$ та $p'\mathrel{R}q'$. + +Два стани бісимілярні, якщо їх пов’язує певна бісимілярність. Визначення є коіндуктивним: після зіставлення переходу наступні стани мають знову виконувати те саме зобов’язання щодо поведінки. + +**Розгалужена бісимілярність.** У поширеному формулюванні, що не розрізняє дивергенцію, симетричне відношення $R$ є розгалуженою бісимілярністю, якщо $p\mathrel{R}q$ та $p\xrightarrow{a}p'$ означають один із двох варіантів: + +* $a = \tau$ і $p'\mathrel{R}q$; або + +* існують стани $q_0$ та $q'$, для яких + + $$ q \xRightarrow{\tau} q_0 \xrightarrow{a} q', \qquad p\mathrel{R}q_0, \qquad p'\mathrel{R}q' $$ + + +Тут $\xRightarrow{\tau}$ означає нуль або більше внутрішніх переходів. Вимога, щоб проміжний стан $q_0$ залишався співвіднесеним із $p$, зберігає важливу можливість розгалуження, дозволяючи ігнорувати внутрішню роботу. Ван Ґлаббек і Вейланд започаткували й розвинули цю еквівалентність у [*Branching Time and Abstraction in Bisimulation Semantics*](https://ir.cwi.nl/pub/5564/5564D.pdf). + +
+ +## Денотаційна рівність {#denotational-equality} + +Денотаційна рівність залежить від вибраної семантичної області: + +$$ \llbracket P \rrbracket = \llbracket Q \rrbracket $$ + +Сама область може бути побудована з трас, систем переходів з точністю до бісимілярності, множин результатів чи іншої математичної моделі. Денотаційне проєктування не задає одну універсальну рівність. Воно вимагає явно її вибрати й використовувати композиційно. + +Зв’язок такий: + +1. Візьміть операційну систему. +2. Виберіть потрібні спостереження. +3. Виберіть семантичну область і рівність. + +## Розгалуження як дані {#branching-as-data} + +Розгалуження також може мати структурне представлення у вигляді дерев. Бінарний шлях можна подати послідовністю рішень «ліворуч/праворуч». Це корисно для префіксних дерев, ідентифікаторів виконання, діаграм рішень і адресації пам’яті. + +У прикладі семантичної позиції в розгалуженні з розділу [Чому значення має бути першим](../denotational-design/semantic-view.md) це значення дерева навмисно відокремлено від одного бітового векторного кодування. + +Конал Елліотт описував адресацію пам’яті через структуру ідеального бінарного дерева листків. Ідеться не про те, що кожна машина буквально зберігає дерево з вихідного тексту; композиційна модель дерева може виявити корисну структуру, приховану за пласкими числовими адресами. + +
Конал Елліотт — адресація пам’яті як ідеальне бінарне дерево листків
+ +## Порівняння {#comparison} + +| Поняття | Предмет | Основне запитання | +| --- | --- | --- | +| Розгалуження потоку керування | Одне виконання програми | Яке продовження вибирається? | +| Детермінізм | Відношення переходів | Чи визначено наступний крок однозначно? | +| Конфлюентність | Відношення редукції | Чи можна звести розгалужені редукції докупи? | +| Еквівалентність трас | Послідовності спостережуваних дій | Чи допускають системи однакові траси? | +| Бісимілярність | Структура розгалужених переходів | Чи можуть системи зіставити переходи одна одної? | +| Денотаційна рівність | Вибрана семантична область | Чи мають програми те саме специфіковане значення? | + +Ці поняття можуть доповнювати одне одного, але жодне з них не є синонімом іншого. + +## Додаткові матеріали {#further-reading} + +* [*A Calculus of Communicating Systems*](https://www.lfcs.inf.ed.ac.uk/reports/86/ECS-LFCS-86-7/ECS-LFCS-86-7.pdf) — фундаментальна праця Мілнера про CCS і спостережувану еквівалентність +* [*Concurrency and Automata on Infinite Sequences*](https://wrap.warwick.ac.uk/id/eprint/47224/1/WRAP_Park_cs-rr-035.pdf) — коіндуктивна характеристика бісимілярності Парком +* [*Algebraic Laws for Nondeterminism and Concurrency*](https://www.scss.tcd.ie/matthew.hennessy/pubs/old/HMjacm85.pdf) — праця Геннесі й Мілнера про спостережувану конгруентність та алгебраїчні закони +* [*What Is Branching Time and Why Use It?*](https://theory.stanford.edu/~rvg/branching/) ([стислий PDF](https://cgi.cse.unsw.edu.au/~rvg/pub/branching.pdf.gz)) — коротке пояснення, чому важливо зберігати структуру розгалуження +* [*The Linear Time–Branching Time Spectrum*](https://ir.cwi.nl/pub/5685/5685.pdf) — стандартна таксономія еквівалентностей поведінки +* [*Branching Time and Abstraction in Bisimulation Semantics*](https://ir.cwi.nl/pub/5564/5564D.pdf) — фундаментальний виклад розгалуженої бісимілярності +* [*Three Logics for Branching Bisimulation*](https://ir.cwi.nl/pub/1370/1370D.pdf) — логічні характеристики через логіки у стилі Геннесі—Мілнера та CTL\* без оператора наступного часу diff --git a/src/concepts/branching.vi.md b/src/concepts/branching.vi.md new file mode 100644 index 0000000..0debb25 --- /dev/null +++ b/src/concepts/branching.vi.md @@ -0,0 +1,208 @@ + + +# Phân nhánh và hội tụ {#branching-and-confluence} + +```admonish tip title="Liên quan" +Góc nhìn ngữ nghĩa: [Ngữ nghĩa và tính hợp thành](../denotational-design/denotations.md), [Định luật và cách diễn giải](../denotational-design/laws-and-interpretations.md) +Thiết kế theo ngữ nghĩa trong Rust: [Định luật, tình huống và bằng chứng](../rust-dd/laws.md) +Khái niệm: [Ngữ nghĩa vận hành](operational_semantics.md) +``` + +Phân nhánh, tính tất định, tính hội tụ, tương đương vết và mô phỏng song hành đều liên quan đến các phương án khác nhau trong tính toán. Chúng không phải cùng một thuộc tính. + +```admonish note title="Vị trí ngữ nghĩa" +Phân nhánh luồng điều khiển là cấu trúc vận hành. Tính hội tụ là thuộc tính của quan hệ rút gọn. Tương đương vết và mô phỏng song hành so sánh hành vi. Đẳng thức ngữ nghĩa chỉ định so sánh ý nghĩa trong một miền ngữ nghĩa được chọn. Thiết kế vững chắc nêu rõ cần đẳng thức nào, thay vì chuyển đổi không chính thức giữa các khái niệm. +``` + +## Tương đương hành vi {#behavioral-equivalence} + +Chương trình đồng thời và tương tác hiếm khi chỉ có một kết quả cuối. Điểm khởi đầu tiêu chuẩn là một **hệ chuyển trạng thái gắn nhãn**: + +$$ \mathcal{L} = (S, A_{\tau}, \to) $$ + +trong đó $S$ là tập trạng thái, $A_{\tau}$ là tập nhãn hành động quan sát được cùng hành động nội bộ $\tau$, còn $\to\;\subseteq S \times A_{\tau} \times S$ là quan hệ chuyển tiếp. Ta viết $p \xrightarrow{a} p'$ khi trạng thái $p$ có thể thực hiện hành động $a$ rồi chuyển sang $p'$. + +Tương đương hành vi xác định những khác biệt nào giữa các hệ thống được chủ ý lược bỏ: + +* **quan sát thời gian tuyến tính** theo các lần thực thi hoàn tất hoặc từng phần và ghi lại những gì xảy ra +* **quan sát thời gian phân nhánh** còn giữ lại nơi có các phương án và thời điểm lựa chọn được xác định + +Vì vậy, hai hệ thống có thể cho phép cùng vết thực thi nhưng khác cấu trúc phân nhánh. Một hệ thống có thể chọn giữa hai hành động trước tương tác, còn hệ thống kia trì hoãn lựa chọn đến sau. Chuỗi hành động giống nhau, nhưng các khả năng tương lai thì không. + +[Phổ thời gian tuyến tính–thời gian phân nhánh](https://ir.cwi.nl/pub/5685/5685.pdf) của Van Glabbeek trình bày có hệ thống các dạng tương đương hành vi tiêu chuẩn. Đây không phải thứ bậc từ yếu đến mạnh; mỗi điểm bảo toàn một tập quan sát khác nhau. + +## Phân nhánh trong chương trình Rust {#branching-in-rust-programs} + +`if` chọn một nhánh theo điều kiện: + +```rust,noplayground +fn sign(x: i32) -> i32 { + if x > 0 { + 1 + } else if x < 0 { + -1 + } else { + 0 + } +} +``` + +`match` chọn một nhánh theo giá trị: + +```rust,noplayground +fn day_type(day: &str) -> &str { + match day { + "Saturday" | "Sunday" => "Weekend", + "Monday" | "Tuesday" | "Wednesday" | "Thursday" | "Friday" => "Weekday", + _ => "Unknown", + } +} +``` + +Với đầu vào cố định trong ngôn ngữ tất định, các cấu trúc này chọn một đường đi luồng điều khiển có thể dự đoán. Thuộc tính đó là **tính tất định**, không phải tính hội tụ. + +## Tính hội tụ có nghĩa gì {#what-confluence-means} + +Quan hệ rút gọn có tính hội tụ khi hai phép rút gọn từ cùng một số hạng có thể gặp lại nhau: + +$$ \begin{array}{ccccc} && a && \\ & \swarrow^{*} && \searrow^{*} & \\ b &&&& c \\ & \searrow^{*} && \swarrow^{*} & \\ && d && \end{array} $$ + +Về hình thức, nếu: + +$$ a \to^* b \quad\text{and}\quad a \to^* c $$ + +thì phải tồn tại một `d` sao cho: + +$$ b \to^* d \quad\text{and}\quad c \to^* d $$ + +Tính hội tụ cho phép có nhiều đường rút gọn. Nó nói các đường đó tương thích theo nghĩa chúng có thể đi đến cùng một trạng thái kế tiếp. + +## Tính tất định và tính hội tụ {#determinism-and-confluence} + +Quan hệ rút gọn tất định có nhiều nhất một bước tiếp theo từ mỗi trạng thái. Vì vậy, nó hội tụ theo nghĩa trực tiếp: không có lựa chọn một bước cạnh tranh nào cần điều hòa. + +Điều ngược lại không đúng. Một hệ thống có thể cho phép nhiều thứ tự rút gọn mà vẫn hội tụ vì mọi thứ tự cuối cùng đều thống nhất. + +Các biểu thức Rust thông thường `if` và `match` minh họa lựa chọn tất định. Tự chúng không minh họa nội dung thú vị của tính hội tụ. + +## Church–Rosser {#churchrosser} + +Định lý Church–Rosser phát biểu một tính chất hội tụ cho phép rút gọn lambda. Nếu một số hạng rút gọn thành hai kết quả theo các đường khác nhau, thì hai kết quả đó có dạng rút gọn chung. + +Khi tồn tại dạng chuẩn, tính hội tụ bảo đảm nó là duy nhất. Điều này hỗ trợ lập luận phương trình vì thứ tự đánh giá không làm đổi dạng chuẩn cuối cùng. + +Đừng khái quát kết quả này cho mọi chương trình mệnh lệnh. Hiệu ứng phụ, lập lịch không tất định, lỗi và quan sát trạng thái trung gian có thể khiến thứ tự rút gọn khác nhau. + +## Vết thực thi {#traces} + +**Vết thực thi** ghi lại chuỗi hành động hoặc trạng thái quan sát được. Ngữ nghĩa vết chủ ý bảo toàn nhiều thông tin vận hành hơn ngữ nghĩa chỉ xét kết quả. + +Hai hàm thuần có thể trả về cùng kết quả nhưng đi qua các bước nội bộ khác nhau. Chúng bằng nhau theo ngữ nghĩa chỉ định kết quả nếu các bước bị lược bỏ. Chúng không nhất thiết bằng nhau theo ngữ nghĩa vết. + +Khi có hiệu ứng, đổi thứ tự điều kiện có thể làm thay đổi quan sát: + +```rust,noplayground +fn is_admin() -> bool { + println!("checked admin"); + true +} + +fn is_user() -> bool { + println!("checked user"); + true +} +``` + +Kiểm tra `is_admin` trước rồi đến `is_user` có thể trả về phân loại tương đương nhưng tạo ra vết khác nhau khi in. + +Câu hỏi thiết kế là liệu các lần in đó có thuộc miền ngữ nghĩa được chọn hay không. + +## Tương đương vết {#trace-equivalence} + +Hai hệ thống tương đương vết khi chúng cho phép cùng các vết quan sát theo mô hình vết đã chọn. + +Tương đương vết có thể lược bỏ cấu trúc phân nhánh. Hai hệ thống có thể tạo ra cùng vết dù một hệ thống chốt lựa chọn sớm hơn hệ thống kia. Với hệ thống tương tác và đồng thời, khác biệt đó có thể quan trọng. + +## Mô phỏng song hành {#bisimulation} + +Mô phỏng song hành liên hệ hai hệ chuyển tiếp từng bước một. Mỗi khi một hệ thống thực hiện một bước quan sát được, hệ thống kia phải có thể bắt chước bước đó, và trạng thái kết quả phải tiếp tục có quan hệ. + +Các biến thể thường gặp gồm: + +* **mô phỏng song hành mạnh**, khớp từng chuyển tiếp riêng lẻ +* **mô phỏng song hành yếu**, trừu tượng hóa các chuyển tiếp nội bộ được chọn +* **mô phỏng song hành phân nhánh**, trừu tượng hóa công việc nội bộ nhưng bảo toàn cấu trúc lựa chọn quan trọng + +Mô phỏng song hành thường là phép so sánh hành vi mạnh hơn tương đương vết, vì nó quan sát cách các phương án còn sẵn có trong quá trình tương tác. + +
+Nguồn gốc và định nghĩa hình thức + +Milner phát triển tương đương quan sát cho các tiến trình giao tiếp trong [*A Calculus of Communicating Systems*](https://www.lfcs.inf.ed.ac.uk/reports/86/ECS-LFCS-86-7/ECS-LFCS-86-7.pdf). Sau đó Park đặc trưng hóa tương đương tương ứng bằng phương pháp đồng quy nạp trong [*Concurrency and Automata on Infinite Sequences*](https://wrap.warwick.ac.uk/id/eprint/47224/1/WRAP_Park_cs-rr-035.pdf), đưa ra quan hệ điểm bất động lớn nhất và phương pháp chứng minh nay được gọi là mô phỏng song hành. Milner tiếp nhận và phát triển phương pháp này thành nền tảng lập luận về hành vi tiến trình. + +**Mô phỏng song hành mạnh.** Với hệ chuyển trạng thái gắn nhãn, quan hệ $R$ là mô phỏng song hành mạnh nếu $p\mathrel{R}q$ kéo theo rằng, với mọi hành động $a$: + +* nếu $p\xrightarrow{a}p'$ thì tồn tại $q'$ thỏa mãn $q\xrightarrow{a}q'$ và $p'\mathrel{R}q'$; và +* nếu $q\xrightarrow{a}q'$ thì tồn tại $p'$ thỏa mãn $p\xrightarrow{a}p'$ và $p'\mathrel{R}q'$. + +Hai trạng thái là song hành tương đương nếu có một quan hệ mô phỏng song hành liên hệ chúng. Định nghĩa này mang tính đồng quy nạp: sau khi khớp chuyển tiếp, các trạng thái kế tiếp phải tiếp tục đáp ứng cùng nghĩa vụ hành vi. + +**Mô phỏng song hành phân nhánh.** Trong một cách trình bày phổ biến không xét phân kỳ, quan hệ đối xứng $R$ là mô phỏng song hành phân nhánh khi $p\mathrel{R}q$ và $p\xrightarrow{a}p'$ kéo theo một trong các trường hợp: + +* $a = \tau$ và $p'\mathrel{R}q$, hoặc + +* có các trạng thái $q_0$ và $q'$ sao cho + + $$ q \xRightarrow{\tau} q_0 \xrightarrow{a} q', \qquad p\mathrel{R}q_0, \qquad p'\mathrel{R}q' $$ + + +Ở đây $\xRightarrow{\tau}$ biểu thị không hoặc nhiều chuyển tiếp nội bộ. Yêu cầu trạng thái trung gian $q_0$ vẫn có quan hệ với $p$ chính là điều bảo toàn khả năng phân nhánh liên quan trong khi cho phép bỏ qua công việc nội bộ. Van Glabbeek và Weijland giới thiệu và phát triển tương đương này trong [*Thời gian phân nhánh và trừu tượng hóa trong ngữ nghĩa mô phỏng song hành*](https://ir.cwi.nl/pub/5564/5564D.pdf). + +
+ +## Đẳng thức ngữ nghĩa chỉ định {#denotational-equality} + +Đẳng thức ngữ nghĩa chỉ định phụ thuộc miền ngữ nghĩa được chọn: + +$$ \llbracket P \rrbracket = \llbracket Q \rrbracket $$ + +Bản thân miền có thể được xây dựng từ vết thực thi, hệ chuyển trạng thái lấy theo mô phỏng song hành, tập kết quả hoặc mô hình toán học khác. Thiết kế theo ngữ nghĩa không áp đặt một đẳng thức phổ quát. Nó yêu cầu chọn đẳng thức một cách tường minh và sử dụng nó theo tính hợp thành. + +Mối quan hệ là: + +1. Bắt đầu với hệ vận hành. +2. Chọn các quan sát liên quan. +3. Chọn miền ngữ nghĩa và đẳng thức. + +## Phân nhánh như dữ liệu {#branching-as-data} + +Phân nhánh cũng xuất hiện về mặt cấu trúc trong cây. Có thể biểu diễn đường đi nhị phân như chuỗi quyết định trái/phải. Cách biểu diễn này hữu ích cho trie, định danh thực thi, sơ đồ quyết định và đánh địa chỉ bộ nhớ. + +Ví dụ vị trí nhánh ngữ nghĩa trong [Vì sao ý nghĩa được đặt lên trước](../denotational-design/semantic-view.md) chủ ý tách biệt ý nghĩa cây này khỏi một cách mã hóa bằng vectơ bit. + +Conal Elliott mô tả việc đánh địa chỉ bộ nhớ thông qua cấu trúc cây lá nhị phân hoàn hảo. Ý không phải mọi máy đều lưu cây cấp nguồn theo nghĩa đen, mà là mô hình cây hợp thành có thể làm lộ cấu trúc hữu ích bị các địa chỉ số phẳng che khuất. + +
Conal Elliott — đánh địa chỉ bộ nhớ như cây lá nhị phân hoàn hảo
+ +## So sánh {#comparison} + +| Khái niệm | Đối tượng | Câu hỏi cốt lõi | +| --- | --- | --- | +| Phân nhánh luồng điều khiển | Một lần thực thi chương trình | Tiếp nối nào được chọn? | +| Tính tất định | Quan hệ chuyển tiếp | Bước tiếp theo có được xác định duy nhất không? | +| Tính hội tụ | Quan hệ rút gọn | Các phép rút gọn phân kỳ có thể gặp lại nhau không? | +| Tương đương vết | Chuỗi hành động quan sát được | Các hệ thống có cùng vết thực thi không? | +| Mô phỏng song hành | Cấu trúc chuyển tiếp phân nhánh | Các hệ thống có thể bắt chước bước của nhau không? | +| Đẳng thức ngữ nghĩa chỉ định | Miền ngữ nghĩa được chọn | Các chương trình có cùng ý nghĩa được đặc tả không? | + +Các khái niệm này có thể hỗ trợ lẫn nhau, nhưng không khái niệm nào nên được dùng như từ đồng nghĩa cho khái niệm khác. + +## Đọc thêm {#further-reading} + +* [*A Calculus of Communicating Systems*](https://www.lfcs.inf.ed.ac.uk/reports/86/ECS-LFCS-86-7/ECS-LFCS-86-7.pdf) — công trình nền tảng của Milner về CCS và tương đương quan sát +* [*Tính đồng thời và tự động trên chuỗi vô hạn*](https://wrap.warwick.ac.uk/id/eprint/47224/1/WRAP_Park_cs-rr-035.pdf) — đặc trưng hóa đồng quy nạp về mô phỏng song hành của Park +* [*Các định luật đại số cho tính không tất định và tính đồng thời*](https://www.scss.tcd.ie/matthew.hennessy/pubs/old/HMjacm85.pdf) — Hennessy và Milner về đồng dư quan sát và định luật đại số +* [*Thời gian phân nhánh là gì và vì sao sử dụng nó?*](https://theory.stanford.edu/~rvg/branching/) ([PDF nén](https://cgi.cse.unsw.edu.au/~rvg/pub/branching.pdf.gz)) — động lực ngắn gọn để bảo toàn cấu trúc phân nhánh +* [*Phổ thời gian tuyến tính–thời gian phân nhánh*](https://ir.cwi.nl/pub/5685/5685.pdf) — phân loại tiêu chuẩn của các tương đương hành vi +* [*Thời gian phân nhánh và trừu tượng hóa trong ngữ nghĩa mô phỏng song hành*](https://ir.cwi.nl/pub/5564/5564D.pdf) — công trình nền tảng về mô phỏng song hành phân nhánh +* [*Ba logic cho mô phỏng song hành phân nhánh*](https://ir.cwi.nl/pub/1370/1370D.pdf) — đặc trưng hóa logic thông qua logic kiểu Hennessy–Milner và CTL\* không có toán tử next diff --git a/src/concepts/branching.zh-hant.md b/src/concepts/branching.zh-hant.md new file mode 100644 index 0000000..0648750 --- /dev/null +++ b/src/concepts/branching.zh-hant.md @@ -0,0 +1,208 @@ + + +# 分支與合流 {#branching-and-confluence} + +```admonish tip title="相關內容" +語義視角:[指稱與組合性](../denotational-design/denotations.md)、[定律與解釋](../denotational-design/laws-and-interpretations.md) +Rust 中的語義驅動設計:[定律、場景與證據](../rust-dd/laws.md) +概念:[操作語義](operational_semantics.md) +``` + +分支、確定性、合流、軌跡等價與雙模擬都涉及計算中的多種可能,但它們並非同一種性質。 + +```admonish note title="語義定位" +控制流分支屬於操作結構。合流性是歸約關係的性質。軌跡等價與雙模擬用於比較行為。指稱等價則比較所選語義域中的含義。健全的設計應明確說明所需的等價關係,而不是非正式地在這些概念之間切換。 +``` + +## 行為等價 {#behavioral-equivalence} + +併發與互動式程式很少只有一個最終結果。一個常見的起點是**標記遷移系統**: + +$$ \mathcal{L} = (S, A_{\tau}, \to) $$ + +其中$S$是狀態集合,$A_{\tau}$是可觀察動作標籤與一個內部動作$\tau$的集合,$\to\;\subseteq S \times A_{\tau} \times S$是轉換關係。我們將$p \xrightarrow{a} p'$記作:狀態$p$可以執行動作$a$並變為$p'$。 + +行為等價會說明有意忽略這些系統之間的哪些差異: + +* **線性時間觀察**沿著已完成或部分執行記錄發生的事件 +* **分支時間觀察**還會保留何時出現了哪些選擇,以及選擇何時確定 + +因此,兩個系統可能有相同軌跡,卻具有不同分支結構。一個系統可能在互動前就在兩個動作間選擇,另一個系統則推遲到互動之後才選擇。動作序列相同,但後續可能性不同。 + +van Glabbeek 提出的[線性時間—分支時間譜](https://ir.cwi.nl/pub/5685/5685.pdf),系統整理了這些行為等價關係。它並非從弱到強的排序;譜中的每一點都保留不同的觀察。 + +## Rust 程式中的分支 {#branching-in-rust-programs} + +`if`會根據條件選擇一個分支: + +```rust,noplayground +fn sign(x: i32) -> i32 { + if x > 0 { + 1 + } else if x < 0 { + -1 + } else { + 0 + } +} +``` + +`match`會根據某個值選擇一個分支: + +```rust,noplayground +fn day_type(day: &str) -> &str { + match day { + "Saturday" | "Sunday" => "Weekend", + "Monday" | "Tuesday" | "Wednesday" | "Thursday" | "Friday" => "Weekday", + _ => "Unknown", + } +} +``` + +對於確定性語言中的固定輸入,這些構造會選擇可預測的控制流路徑。這種性質稱為**確定性**,而非合流性。 + +## 合流性的含義 {#what-confluence-means} + +如果某個項的兩種歸約方式最終能夠再次匯合,那麼該歸約關係就是合流的: + +$$ \begin{array}{ccccc} && a && \\ & \swarrow^{*} && \searrow^{*} & \\ b &&&& c \\ & \searrow^{*} && \swarrow^{*} & \\ && d && \end{array} $$ + +形式化地說,若: + +$$ a \to^* b \quad\text{and}\quad a \to^* c $$ + +則必然存在某個`d`,使得: + +$$ b \to^* d \quad\text{and}\quad c \to^* d $$ + +合流性允許存在多條歸約路徑。它表示這些路徑能夠到達共同後繼,因此彼此相容。 + +## 確定性與合流性 {#determinism-and-confluence} + +確定性歸約關係中,每個狀態最多隻有一個後續步驟。因此它自然滿足合流性:沒有相互競爭的單步選擇需要協調。 + +反過來則不成立。系統可以允許多種歸約順序,同時仍滿足合流性,因為所有順序最終都會得到相同結果。 + +普通 Rust 的`if`與`match`表示式展示了確定性選擇,但單憑它們無法體現合流性的有趣之處。 + +## Church–Rosser 性質 {#churchrosser} + +Church–Rosser 定理說明了 lambda 演算歸約的合流性質。如果一個項沿不同歸約路徑得到兩個結果,那麼這兩個結果存在共同歸約結果。 + +只要正規化存在,合流性就意味著它唯一。這支援等式推理,因為求值順序不會改變最終正規化。 + +不要將此結果推廣到任意命令式程式。副作用、非確定性排程、失敗以及對中間狀態的觀察,都可能使不同歸約順序產生差異。 + +## 軌跡 {#traces} + +**軌跡**記錄一系列可觀察動作或狀態。與只記錄結果的語義相比,軌跡語義有意保留更多操作資訊。 + +兩個純函式可以返回同一結果,卻經過不同內部步驟。如果結果指稱忽略了這些步驟,它們在該指稱下相等;但在軌跡語義下,它們未必相等。 + +存在效應時,調整檢查順序可能改變觀察: + +```rust,noplayground +fn is_admin() -> bool { + println!("checked admin"); + true +} + +fn is_user() -> bool { + println!("checked user"); + true +} +``` + +先檢查`is_admin`還是先檢查`is_user`,可能返回等價分類,卻列印出不同軌跡。 + +設計問題在於,這些列印資訊是否屬於所選語義域。 + +## 軌跡等價 {#trace-equivalence} + +如果兩個系統在選定的軌跡模型下允許相同的可觀察軌跡,它們就是軌跡等價的。 + +軌跡等價可能忽略分支結構。兩個系統可以生成相同軌跡,但一個比另一個更早確定選擇。在互動式與併發系統中,這種區別可能很重要。 + +## 雙模擬 {#bisimulation} + +雙模擬逐步關聯兩個遷移系統。每當一個系統執行可觀察動作,另一個系統就必須能夠匹配該動作,而且遷移後的狀態仍須保持關聯。 + +常見變體包括: + +* **強雙模擬**,用於匹配單個狀態轉換 +* **弱雙模擬**,用於抽象選定的內部轉換 +* **分支雙模擬**,用於抽象內部工作,同時保留重要的選擇結構 + +雙模擬通常比軌跡等價提供更強的行為比較,因為它會觀察互動過程中各種選擇是否仍然可用。 + +
+起源與形式定義 + +Milner 在[*《通訊系統演算》*](https://www.lfcs.inf.ed.ac.uk/reports/86/ECS-LFCS-86-7/ECS-LFCS-86-7.pdf)中為通訊過程發展了觀察等價。隨後 Park 在[*《無限序列上的併發與自動機》*](https://wrap.warwick.ac.uk/id/eprint/47224/1/WRAP_Park_cs-rr-035.pdf)中,以餘歸納方式刻畫了相應的等價關係,給出了現稱為雙模擬的最大不動點關係與證明方法。Milner 隨後採用並發展了這一方法,將其作為推理過程行為的基礎。 + +強雙模擬。對於標記遷移系統,若關係$R$滿足以下條件,則它是強雙模擬:當$p\mathrel{R}q$成立時,對於每個動作$a$: + +* 如果$p\xrightarrow{a}p'$成立,則存在某個$q'$,使得$q\xrightarrow{a}q'$與$p'\mathrel{R}q'$成立;並且 +* 如果$q\xrightarrow{a}q'$成立,則存在某個$p'$,使得$p\xrightarrow{a}p'$與$p'\mathrel{R}q'$成立。 + +如果存在某個雙模擬關係關聯兩個狀態,那麼它們就是雙模擬等價的。這一定義是餘歸納的:匹配某個狀態轉換後,後繼狀態必須再次滿足相同的行為義務。 + +分支雙模擬。在一種忽略發散的常見表述中,如果對稱關係$R$滿足以下條件,那麼它就是分支雙模擬:當$p\mathrel{R}q$與$p\xrightarrow{a}p'$成立時,以下情況至少一種成立: + +* $a = \tau$與$p'\mathrel{R}q$成立;或 + +* 存在狀態$q_0$與$q'$,使得 + + $$ q \xRightarrow{\tau} q_0 \xrightarrow{a} q', \qquad p\mathrel{R}q_0, \qquad p'\mathrel{R}q' $$ + + +這裡,$\xRightarrow{\tau}$表示零次或多次內部轉換。要求中間狀態$q_0$仍與$p$保持關聯,正是為了忽略內部工作時仍能保留相關的分支可能性。van Glabbeek 與 Weijland 在[*《雙模擬語義中的分支時間與抽象》*](https://ir.cwi.nl/pub/5564/5564D.pdf)中引入並發展了這一等價關係。 + +
+ +## 指稱相等 {#denotational-equality} + +指稱相等取決於所選語義域: + +$$ \llbracket P \rrbracket = \llbracket Q \rrbracket $$ + +語義域本身可以由軌跡、以雙模擬等價關係取商的遷移系統、結果集合或其他數學模型構成。指稱設計不規定某個通用等價關係,而是要求明確選擇等價關係,並以組合方式使用它。 + +其關係如下: + +1. 從作業系統開始。 +2. 選定相關觀察。 +3. 選擇語義域與等價關係。 + +## 作為資料的分支 {#branching-as-data} + +分支也會以樹的結構出現。二叉路徑可以表示為一串左右選擇。這種表示適用於字首樹、執行識別符號、決策圖與記憶體定址。 + +[《為何含義優先》](../denotational-design/semantic-view.md)中的語義分支位置示例,特意將樹的含義與一種位向量編碼區分開來。 + +Conal Elliott 曾用完美二叉葉樹結構描述記憶體定址。重點並不是每臺機器都會按字面儲存一棵源級樹,而是組合式樹模型能夠揭示扁平數值地址所隱藏的有用結構。 + +
Conal Elliott——將記憶體定址視為完美二叉葉樹
+ +## 對比 {#comparison} + +| 概念 | 研究物件 | 核心問題 | +| --- | --- | --- | +| 控制流分支 | 一次程式執行 | 會選擇哪個延續? | +| 確定性 | 轉換關係 | 下一步是否由當前狀態唯一決定? | +| 合流性 | 歸約關係 | 不同歸約路徑能否匯合? | +| 軌跡等價 | 可觀察動作序列 | 系統是否允許相同軌跡? | +| 雙模擬 | 分支轉換結構 | 系統能否匹配彼此的動作? | +| 指稱相等 | 所選語義域 | 程式是否具有相同的指定含義? | + +這些概念可以相互支援,但不能彼此互為同義詞。 + +## 延伸閱讀 {#further-reading} + +* [*《通訊系統演算》*](https://www.lfcs.inf.ed.ac.uk/reports/86/ECS-LFCS-86-7/ECS-LFCS-86-7.pdf)——Milner 對 CCS 與觀察等價的奠基性論述 +* [*《無限序列上的併發與自動機》*](https://wrap.warwick.ac.uk/id/eprint/47224/1/WRAP_Park_cs-rr-035.pdf)——Park 對雙模擬的餘歸納刻畫 +* [*《非確定性與併發的代數定律》*](https://www.scss.tcd.ie/matthew.hennessy/pubs/old/HMjacm85.pdf)——Hennessy 與 Milner 關於觀察同餘與代數定律的論述 +* [*《什麼是分支時間,為什麼要使用它?》*](https://theory.stanford.edu/~rvg/branching/)([壓縮版 PDF](https://cgi.cse.unsw.edu.au/~rvg/pub/branching.pdf.gz))——簡明闡述保留分支結構的動機 +* [*《線性時間—分支時間譜》*](https://ir.cwi.nl/pub/5685/5685.pdf)——行為等價的標準分類 +* [*《雙模擬語義中的分支時間與抽象》*](https://ir.cwi.nl/pub/5564/5564D.pdf)——分支雙模擬的奠基性論述 +* [*《分支雙模擬的三種邏輯》*](https://ir.cwi.nl/pub/1370/1370D.pdf)——透過 Hennessy–Milner 風格邏輯與不含下一時刻運算子的 CTL\* 給出邏輯刻畫 diff --git a/src/concepts/branching.zh.md b/src/concepts/branching.zh.md new file mode 100644 index 0000000..715dd92 --- /dev/null +++ b/src/concepts/branching.zh.md @@ -0,0 +1,208 @@ + + +# 分支与合流 {#branching-and-confluence} + +```admonish tip title="相关内容" +语义视角:[指称与组合性](../denotational-design/denotations.md)、[定律与解释](../denotational-design/laws-and-interpretations.md) +Rust 中的语义驱动设计:[定律、场景与证据](../rust-dd/laws.md) +概念:[操作语义](operational_semantics.md) +``` + +分支、确定性、合流、轨迹等价与双模拟都涉及计算中的多种可能,但它们并非同一种性质。 + +```admonish note title="语义定位" +控制流分支属于操作结构。合流性是归约关系的性质。轨迹等价与双模拟用于比较行为。指称等价则比较所选语义域中的含义。健全的设计应明确说明所需的等价关系,而不是非正式地在这些概念之间切换。 +``` + +## 行为等价 {#behavioral-equivalence} + +并发与交互式程序很少只有一个最终结果。一个常见的起点是**标记迁移系统**: + +$$ \mathcal{L} = (S, A_{\tau}, \to) $$ + +其中$S$是状态集合,$A_{\tau}$是可观察动作标签与一个内部动作$\tau$的集合,$\to\;\subseteq S \times A_{\tau} \times S$是转换关系。我们将$p \xrightarrow{a} p'$记作:状态$p$可以执行动作$a$并变为$p'$。 + +行为等价会说明有意忽略这些系统之间的哪些差异: + +* **线性时间观察**沿着已完成或部分执行记录发生的事件 +* **分支时间观察**还会保留何时出现了哪些选择,以及选择何时确定 + +因此,两个系统可能有相同轨迹,却具有不同分支结构。一个系统可能在交互前就在两个动作间选择,另一个系统则推迟到交互之后才选择。动作序列相同,但后续可能性不同。 + +van Glabbeek 提出的[线性时间—分支时间谱](https://ir.cwi.nl/pub/5685/5685.pdf),系统整理了这些行为等价关系。它并非从弱到强的排序;谱系中的每一点都保留不同的观察。 + +## Rust 程序中的分支 {#branching-in-rust-programs} + +`if`会根据条件选择一个分支: + +```rust,noplayground +fn sign(x: i32) -> i32 { + if x > 0 { + 1 + } else if x < 0 { + -1 + } else { + 0 + } +} +``` + +`match`会根据某个值选择一个分支: + +```rust,noplayground +fn day_type(day: &str) -> &str { + match day { + "Saturday" | "Sunday" => "Weekend", + "Monday" | "Tuesday" | "Wednesday" | "Thursday" | "Friday" => "Weekday", + _ => "Unknown", + } +} +``` + +对于确定性语言中的固定输入,这些构造会选择可预测的控制流路径。这种性质称为**确定性**,而非合流性。 + +## 合流性的含义 {#what-confluence-means} + +如果某个项的两种归约方式最终能够再次汇合,那么该归约关系就是合流的: + +$$ \begin{array}{ccccc} && a && \\ & \swarrow^{*} && \searrow^{*} & \\ b &&&& c \\ & \searrow^{*} && \swarrow^{*} & \\ && d && \end{array} $$ + +形式化地说,若: + +$$ a \to^* b \quad\text{and}\quad a \to^* c $$ + +则必然存在某个`d`,使得: + +$$ b \to^* d \quad\text{and}\quad c \to^* d $$ + +合流性允许存在多条归约路径。它表示这些路径能够到达共同后继,因此彼此兼容。 + +## 确定性与合流性 {#determinism-and-confluence} + +确定性归约关系中,每个状态最多只有一个后续步骤。因此它自然满足合流性:没有相互竞争的单步选择需要协调。 + +反过来则不成立。系统可以允许多种归约顺序,同时仍满足合流性,因为所有顺序最终都会得到相同结果。 + +普通 Rust 的`if`与`match`表达式展示了确定性选择,但单凭它们无法体现合流性的有趣之处。 + +## Church–Rosser 性质 {#churchrosser} + +Church–Rosser 定理说明了 lambda 演算归约的合流性质。如果一个项沿不同归约路径得到两个结果,那么这两个结果存在共同归约结果。 + +只要范式存在,合流性就意味着它唯一。这支持等式推理,因为求值顺序不会改变最终范式。 + +不要将此结果推广到任意命令式程序。副作用、非确定性调度、失败以及对中间状态的观察,都可能使不同归约顺序产生差异。 + +## 轨迹 {#traces} + +**轨迹**记录一系列可观察动作或状态。与只记录结果的语义相比,轨迹语义有意保留更多操作信息。 + +两个纯函数可以返回同一结果,却经过不同内部步骤。如果结果指称忽略了这些步骤,它们在该指称下相等;但在轨迹语义下,它们未必相等。 + +存在效应时,调整检查顺序可能改变观察: + +```rust,noplayground +fn is_admin() -> bool { + println!("checked admin"); + true +} + +fn is_user() -> bool { + println!("checked user"); + true +} +``` + +先检查`is_admin`还是先检查`is_user`,可能返回等价分类,却打印出不同轨迹。 + +设计问题在于,这些打印信息是否属于所选语义域。 + +## 轨迹等价 {#trace-equivalence} + +如果两个系统在选定的轨迹模型下允许相同的可观察轨迹,它们就是轨迹等价的。 + +轨迹等价可能忽略分支结构。两个系统可以生成相同轨迹,但一个比另一个更早确定选择。在交互式与并发系统中,这种区别可能很重要。 + +## 双模拟 {#bisimulation} + +双模拟逐步关联两个迁移系统。每当一个系统执行可观察动作,另一个系统就必须能够匹配该动作,而且转换后的状态仍须保持关联。 + +常见变体包括: + +* **强双模拟**,用于匹配单个状态转换 +* **弱双模拟**,用于抽象选定的内部转换 +* **分支双模拟**,用于抽象内部工作,同时保留重要的选择结构 + +双模拟通常比轨迹等价提供更强的行为比较,因为它会观察交互过程中各种选择是否仍然可用。 + +
+起源与形式定义 + +Milner 在[*《通信系统演算》*](https://www.lfcs.inf.ed.ac.uk/reports/86/ECS-LFCS-86-7/ECS-LFCS-86-7.pdf)中为通信过程发展了观察等价。随后 Park 在[*《无限序列上的并发与自动机》*](https://wrap.warwick.ac.uk/id/eprint/47224/1/WRAP_Park_cs-rr-035.pdf)中,以余归纳方式刻画了相应的等价关系,给出了现称为双模拟的最大不动点关系与证明方法。Milner 随后采用并发展了这一方法,将其作为推理过程行为的基础。 + +强双模拟。对于标记迁移系统,若关系$R$满足以下条件,则它是强双模拟:当$p\mathrel{R}q$成立时,对于每个动作$a$: + +* 如果$p\xrightarrow{a}p'$成立,则存在某个$q'$,使得$q\xrightarrow{a}q'$与$p'\mathrel{R}q'$成立;并且 +* 如果$q\xrightarrow{a}q'$成立,则存在某个$p'$,使得$p\xrightarrow{a}p'$与$p'\mathrel{R}q'$成立。 + +如果存在某个双模拟关系关联两个状态,那么它们就是双模拟等价的。这一定义是余归纳的:匹配某个状态转换后,后继状态必须再次满足相同的行为义务。 + +分支双模拟。在一种忽略发散的常见表述中,如果对称关系$R$满足以下条件,那么它就是分支双模拟:当$p\mathrel{R}q$与$p\xrightarrow{a}p'$成立时,以下情况至少一种成立: + +* $a = \tau$与$p'\mathrel{R}q$成立;或 + +* 存在状态$q_0$与$q'$,使得 + + $$ q \xRightarrow{\tau} q_0 \xrightarrow{a} q', \qquad p\mathrel{R}q_0, \qquad p'\mathrel{R}q' $$ + + +这里,$\xRightarrow{\tau}$表示零次或多次内部转换。要求中间状态$q_0$仍与$p$保持关联,正是为了忽略内部工作时仍能保留相关的分支可能性。van Glabbeek 与 Weijland 在[*《双模拟语义中的分支时间与抽象》*](https://ir.cwi.nl/pub/5564/5564D.pdf)中引入并发展了这一等价关系。 + +
+ +## 指称相等 {#denotational-equality} + +指称相等取决于所选语义域: + +$$ \llbracket P \rrbracket = \llbracket Q \rrbracket $$ + +语义域本身可以由轨迹、按双模拟等价取商后的迁移系统、结果集合或其他数学模型构成。指称设计不规定某个通用等价关系,而是要求明确选择等价关系,并以组合方式使用它。 + +其关系如下: + +1. 从操作系统开始。 +2. 选定相关观察。 +3. 选择语义域与等价关系。 + +## 作为数据的分支 {#branching-as-data} + +分支也会以树的结构出现。二叉路径可以表示为一串左右选择。这种表示适用于前缀树、执行标识符、决策图与内存寻址。 + +[《为何含义优先》](../denotational-design/semantic-view.md)中的语义分支位置示例,特意将树的含义与一种位向量编码区分开来。 + +Conal Elliott 曾用完美二叉叶树结构描述内存寻址。重点并不是每台机器都会按字面存储一棵源级树,而是组合式树模型能够揭示扁平数值地址所隐藏的有用结构。 + +
Conal Elliott——将内存寻址视为完美二叉叶树
+ +## 对比 {#comparison} + +| 概念 | 研究对象 | 核心问题 | +| --- | --- | --- | +| 控制流分支 | 一次程序执行 | 会选择哪个延续? | +| 确定性 | 转换关系 | 下一步是否由当前状态唯一决定? | +| 合流性 | 归约关系 | 不同归约路径能否汇合? | +| 轨迹等价 | 可观察动作序列 | 系统是否允许相同轨迹? | +| 双模拟 | 分支转换结构 | 系统能否匹配彼此的动作? | +| 指称相等 | 所选语义域 | 程序是否具有相同的指定含义? | + +这些概念可以相互支持,但不能彼此互为同义词。 + +## 延伸阅读 {#further-reading} + +* [*《通信系统演算》*](https://www.lfcs.inf.ed.ac.uk/reports/86/ECS-LFCS-86-7/ECS-LFCS-86-7.pdf)——Milner 对 CCS 与观察等价的奠基性论述 +* [*《无限序列上的并发与自动机》*](https://wrap.warwick.ac.uk/id/eprint/47224/1/WRAP_Park_cs-rr-035.pdf)——Park 对双模拟的余归纳刻画 +* [*《非确定性与并发的代数定律》*](https://www.scss.tcd.ie/matthew.hennessy/pubs/old/HMjacm85.pdf)——Hennessy 与 Milner 关于观察同余与代数定律的论述 +* [*《什么是分支时间,为什么要使用它?》*](https://theory.stanford.edu/~rvg/branching/)([压缩版 PDF](https://cgi.cse.unsw.edu.au/~rvg/pub/branching.pdf.gz))——简明阐述保留分支结构的动机 +* [*《线性时间—分支时间谱》*](https://ir.cwi.nl/pub/5685/5685.pdf)——行为等价的标准分类 +* [*《双模拟语义中的分支时间与抽象》*](https://ir.cwi.nl/pub/5564/5564D.pdf)——分支双模拟的奠基性论述 +* [*《分支双模拟的三种逻辑》*](https://ir.cwi.nl/pub/1370/1370D.pdf)——通过 Hennessy–Milner 风格逻辑与不含下一时刻运算符的 CTL\* 给出逻辑刻画 diff --git a/src/concepts/cps.ar.md b/src/concepts/cps.ar.md new file mode 100644 index 0000000..0da78bf --- /dev/null +++ b/src/concepts/cps.ar.md @@ -0,0 +1,88 @@ + + +# أسلوب تمرير الاستمرار (CPS) {#continuation-passing-style-cps} + +```admonish tip title="ذات صلة" +التصميم انطلاقًا من المعنى في Rust: [برامج من الرتبة الأولى](../rust-dd/first-order-programs.md)، [مسارات اللغة والمترجم](../rust-dd/compiler-pipelines.md) +المفاهيم: [الموناد الحر](free_monad.md)، [إزالة الدوال](defunctionalization.md) +الرؤى: [جبر EVM](../insights/evm-alg.md) +``` + +```admonish note title="الموضع الدلالي" +أسلوب تمرير الاستمرار تمثيل وتحويل برمجي يجعلان التحكم صريحًا. ويتوقف حفظه للمعنى على دلالات مصدر وهدف محددة، وعلى العلاقة بينهما. +``` + +## التعريف {#definition} + +أسلوب تمرير الاستمرار (CPS) طريقة لكتابة البرامج بحيث لا تعيد الدوال قيمًا مباشرة، بل تمرر نتيجتها إلى دالة أخرى تسمى *الاستمرارية*، وتمثل بقية البرنامج. + +## الدافع {#motivation} + +* يجعل تدفق التحكم صريحًا وقابلًا للبرمجة. +* يتيح تحويلات متقدمة مثل إدخال/إخراج غير حاجب، والخروج المبكر، والتوالد، والتراجع، وجدولة التزامن. +* يُستخدم في التمثيلات الوسيطة للمترجم لتبسيط التحسين والتحليل. + +## الصيغة الأساسية {#basic-form} + +بالأسلوب المباشر: + +```rust +fn add_one(x: i32) -> i32 { + x + 1 +} + +fn main() { + let y = add_one(41); + println!("{}", y); +} +``` + +بأسلوب تمرير الاستمرار: + +```rust +fn add_one_cps(x: i32, k: impl Fn(i32)) { + k(x + 1) +} + +fn main() { + add_one_cps(41, |y| { + println!("{}", y); + }); +} +``` + +هنا، `k` هي الاستمرارية. فبدلًا من إرجاع `x + 1`، نستدعي `k(x + 1)`. + +## الخصائص الأساسية {#key-properties} + +* كل استدعاءات الدوال هي *استدعاءات ذيلية* للاستمراريات. +* لا «تعود» العملية الحسابية الحالية إلى المستدعي؛ بل تنتقل إلى الاستمرارية. +* يصبح تدفق التحكم صريحًا في البرنامج. + +## العلاقة بالدوال عالية الرتبة {#relation-to-higher-order-functions} + +* في أسلوب تمرير الاستمرار، لا تعدو الاستمراريات أن تكون دوالًا عالية الرتبة. +* تتلقى كل خطوة من العملية الحسابية استمرارية تمثل ما ينبغي فعله تاليًا. + +## العلاقة بإزالة الدوال {#relation-to-defunctionalization} + +* في أسلوب تمرير الاستمرار، الاستمرارية قيمة دالة فعلية. +* تستبدل إزالة الدوال دالة الاستمرارية ببنية بيانات (تعداد) تمثل الخطوات التالية المحتملة، مع دالة `apply` لتفسيرها. + +## العلاقة بالمونادات الحرة {#relation-to-free-monads} + +* إن مُنشئ `FlatMap` في الموناد الحر هو استمرارية مخزنة بعينها. +* يشبه تفسير الموناد الحر تنفيذ شيفرة بأسلوب تمرير الاستمرار حيث تكون الاستمرارية جزءًا من بيانات البرنامج. +* يمكن ربط ترميزات مناسبة للموناد الحر بتمثيلات الاستمرارية في أسلوب تمرير الاستمرار بعد إزالة الدوال. + +## المزايا {#advantages} + +* تمثيل مرن لتدفق التحكم. +* استدلال أسهل على ترتيب التقييم. +* مفيد لتنفيذ المفسرات ومصححات الأخطاء والمُحسّنات وأزمنة تشغيل المهام غير المتزامنة. + +## العيوب {#disadvantages} + +* أكثر إسهابًا من الأسلوب المباشر. +* قد يصعب على البشر قراءته. +* يتطلب تحسين استدعاءات الذيل للكفاءة في اللغات التي لا تدعمه أصليًا. diff --git a/src/concepts/cps.de.md b/src/concepts/cps.de.md new file mode 100644 index 0000000..941731d --- /dev/null +++ b/src/concepts/cps.de.md @@ -0,0 +1,88 @@ + + +# Continuation-Passing Style (CPS) {#continuation-passing-style-cps} + +```admonish tip title="Verwandte Themen" +Design by Meaning in Rust: [Programme erster Ordnung](../rust-dd/first-order-programs.md), [Sprach- und Compiler-Pipelines](../rust-dd/compiler-pipelines.md) +Concepts: [Freie Monade](free_monad.md), [Defunktionalisierung](defunctionalization.md) +Insights: [EVM-Algebra](../insights/evm-alg.md) +``` + +```admonish note title="Semantische Einordnung" +CPS ist eine Repräsentation und Programmtransformation, die den Kontrollfluss explizit macht. Ob sie Bedeutung bewahrt, hängt von einer formulierten Quellsemantik, Zielsemantik und der Zuordnung zwischen ihnen ab. +``` + +## Definition {#definition} + +Continuation-Passing Style (CPS) ist eine Programmierweise, bei der Funktionen Werte nicht direkt zurückgeben. Stattdessen übergeben sie ihr Ergebnis an eine andere Funktion, die *Fortsetzung* genannt wird und den Rest des Programms darstellt. + +## Motivation {#motivation} + +* Macht Kontrollfluss explizit und programmierbar. +* Ermöglicht anspruchsvolle Transformationen wie nicht blockierende Ein-/Ausgabe, vorzeitige Abbrüche, Koroutinen, Backtracking und Nebenläufigkeitsplanung. +* Wird in Zwischenrepräsentationen von Compilern eingesetzt, um Optimierung und Analyse zu vereinfachen. + +## Grundform {#basic-form} + +Im direkten Stil: + +```rust +fn add_one(x: i32) -> i32 { + x + 1 +} + +fn main() { + let y = add_one(41); + println!("{}", y); +} +``` + +In CPS: + +```rust +fn add_one_cps(x: i32, k: impl Fn(i32)) { + k(x + 1) +} + +fn main() { + add_one_cps(41, |y| { + println!("{}", y); + }); +} +``` + +Hier ist `k` die Fortsetzung. Statt `x + 1` zurückzugeben, rufen wir `k(x + 1)` auf. + +## Wichtige Eigenschaften {#key-properties} + +* Alle Funktionsaufrufe sind *Endaufrufe* an Fortsetzungen. +* Die aktuelle Berechnung kehrt nicht zum Aufrufer zurück, sondern springt in die Fortsetzung. +* Der Kontrollfluss wird im Programm explizit. + +## Beziehung zu höherwertigen Funktionen {#relation-to-higher-order-functions} + +* In CPS sind Fortsetzungen einfach höherwertige Funktionen. +* Jeder Berechnungsschritt erhält eine Fortsetzung, die beschreibt, was als Nächstes zu tun ist. + +## Beziehung zur Defunktionalisierung {#relation-to-defunctionalization} + +* In CPS ist die Fortsetzung ein tatsächlicher Funktionswert. +* Defunktionalisierung ersetzt die Fortsetzungsfunktion durch eine Datenstruktur (Enum), die mögliche nächste Schritte darstellt, sowie eine `apply`\-Funktion, die sie interpretiert. + +## Beziehung zu freien Monaden {#relation-to-free-monads} + +* Der `FlatMap`\-Konstruktor einer freien Monade ist genau eine gespeicherte Fortsetzung. +* Eine freie Monade zu interpretieren, ähnelt der Ausführung von CPS-Code, in dem die Fortsetzung Teil der Programmdaten ist. +* Geeignete Kodierungen freier Monaden lassen sich mit CPS und defunktionalisierten Fortsetzungsrepräsentationen in Beziehung setzen. + +## Vorteile {#advantages} + +* Flexible Repräsentation des Kontrollflusses. +* Die Reihenfolge der Auswertung lässt sich leichter durchdenken. +* Leistungsstark bei der Implementierung von Interpretern, Debuggern, Optimierern und asynchronen Laufzeitumgebungen. + +## Nachteile {#disadvantages} + +* Umständlicher als der direkte Stil. +* Für Menschen mitunter schwerer zu lesen. +* Erfordert zur Effizienz Tail-Call-Optimierung in Sprachen ohne native Unterstützung. diff --git a/src/concepts/cps.es.md b/src/concepts/cps.es.md new file mode 100644 index 0000000..3da744c --- /dev/null +++ b/src/concepts/cps.es.md @@ -0,0 +1,88 @@ + + +# Estilo de paso de continuaciones (CPS) {#continuation-passing-style-cps} + +```admonish tip title="Relacionado" +Diseño basado en el significado en Rust: [Programas de primer orden](../rust-dd/first-order-programs.md), [Lenguaje y procesos de compilación](../rust-dd/compiler-pipelines.md) +Conceptos: [Mónada libre](free_monad.md), [Defuncionalización](defunctionalization.md) +Perspectivas: [Álgebra EVM](../insights/evm-alg.md) +``` + +```admonish note title="Ubicación semántica" +CPS es una representación y transformación de programas que hace explícito el control. Que preserve el significado depende de una semántica de origen y otra de destino, además de la correspondencia entre ellas. +``` + +## Definición {#definition} + +El estilo de paso de continuaciones (CPS) es una forma de escribir programas en la que las funciones no devuelven valores directamente. En su lugar, pasan el resultado a otra función llamada *continuación*, que representa el resto del programa. + +## Motivación {#motivation} + +* Hace explícito el flujo de control y permite programarlo. +* Permite transformaciones avanzadas, como la E/S no bloqueante, las salidas anticipadas, las corutinas, el retroceso y la planificación concurrente. +* Se usa en representaciones intermedias de compilador para simplificar la optimización y el análisis. + +## Forma básica {#basic-form} + +En estilo directo: + +```rust +fn add_one(x: i32) -> i32 { + x + 1 +} + +fn main() { + let y = add_one(41); + println!("{}", y); +} +``` + +En CPS: + +```rust +fn add_one_cps(x: i32, k: impl Fn(i32)) { + k(x + 1) +} + +fn main() { + add_one_cps(41, |y| { + println!("{}", y); + }); +} +``` + +Aquí, `k` es la continuación. En lugar de devolver `x + 1`, llamamos a `k(x + 1)`. + +## Propiedades clave {#key-properties} + +* Todas las llamadas a funciones son *llamadas de cola* a continuaciones. +* El cálculo actual nunca «vuelve» al llamador; en su lugar, salta a la continuación. +* El flujo de control queda explícito en el programa. + +## Relación con las funciones de orden superior {#relation-to-higher-order-functions} + +* En CPS, las continuaciones no son más que funciones de orden superior. +* Cada paso del cálculo recibe una continuación que representa lo que debe hacerse a continuación. + +## Relación con la defuncionalización {#relation-to-defunctionalization} + +* En CPS, la continuación es un valor de función real. +* La defuncionalización reemplaza la función de continuación por una estructura de datos (una enumeración) que representa los siguientes pasos posibles, junto con una función `apply` que los interpreta. + +## Relación con las mónadas libres {#relation-to-free-monads} + +* El constructor `FlatMap` de una mónada libre almacena precisamente una continuación. +* Interpretar una mónada libre es como ejecutar código CPS cuya continuación forma parte de los datos del programa. +* Las codificaciones adecuadas de mónadas libres pueden relacionarse con CPS y con las representaciones de continuaciones defuncionalizadas. + +## Ventajas {#advantages} + +* Representación flexible del flujo de control. +* Facilita el razonamiento sobre el orden de evaluación. +* Es muy útil para implementar intérpretes, depuradores, optimizadores y entornos de ejecución asíncronos. + +## Desventajas {#disadvantages} + +* Es más verboso que el estilo directo. +* Puede ser más difícil de leer para las personas. +* Requiere optimización de llamadas de cola para ser eficiente en lenguajes que no la admiten de forma nativa. diff --git a/src/concepts/cps.ja.md b/src/concepts/cps.ja.md new file mode 100644 index 0000000..63e7ba4 --- /dev/null +++ b/src/concepts/cps.ja.md @@ -0,0 +1,88 @@ + + +# 継続渡し形式(CPS) {#continuation-passing-style-cps} + +```admonish tip title="関連項目" +Rustで意味から設計する:[一階プログラム](../rust-dd/first-order-programs.md)、[言語とコンパイラーパイプライン](../rust-dd/compiler-pipelines.md) +概念:[自由モナド](free_monad.md)、[デファンクショナライズ](defunctionalization.md) +洞察:[EVM代数](../insights/evm-alg.md) +``` + +```admonish note title="意味論上の位置付け" +CPSは、制御を明示する表現およびプログラム変換です。意味を保つかどうかは、明示されたソース意味論、ターゲット意味論、それらの対応関係によって決まります。 +``` + +## 定義 {#definition} + +継続渡し形式(CPS)は、関数が値を直接返さず、結果を*継続*と呼ばれる別の関数へ渡す形でプログラムを書く方法です。継続はプログラムの残りを表します。 + +## 目的 {#motivation} + +* 制御フローを明示し、プログラムから扱えるようにする。 +* ノンブロッキングIO、早期終了、コルーチン、バックトラッキング、並行スケジューリングなどの高度な変換を可能にする。 +* 最適化や解析を単純化する目的で、コンパイラーの中間表現に使われる。 + +## 基本形式 {#basic-form} + +直接形式: + +```rust +fn add_one(x: i32) -> i32 { + x + 1 +} + +fn main() { + let y = add_one(41); + println!("{}", y); +} +``` + +CPS形式: + +```rust +fn add_one_cps(x: i32, k: impl Fn(i32)) { + k(x + 1) +} + +fn main() { + add_one_cps(41, |y| { + println!("{}", y); + }); +} +``` + +ここでは、`k`は継続です。`x + 1`を返すのではなく、`k(x + 1)`を呼び出します。 + +## 主な性質 {#key-properties} + +* 関数呼び出しはすべて、継続への*末尾呼び出し*です。 +* 現在の計算は呼び出し元に「戻り」ません。継続へ制御を移します。 +* プログラム内で制御フローが明示される。 + +## 高階関数との関係 {#relation-to-higher-order-functions} + +* CPSでは、継続は高階関数にすぎません。 +* 計算の各段階では、次に何をするかを表す継続を受け取ります。 + +## デファンクショナライズとの関係 {#relation-to-defunctionalization} + +* CPSでは、継続は実際の関数値です。 +* デファンクショナライズは、継続関数を、次のステップを表すデータ構造(列挙型)と、それを解釈する`apply`関数に置き換えます。 + +## 自由モナドとの関係 {#relation-to-free-monads} + +* 自由モナドの`FlatMap`構成子は、格納された継続そのものです。 +* 自由モナドを解釈することは、継続がプログラムデータの一部であるCPSコードを実行するようなものです。 +* 適切な自由モナド符号化は、CPSやデファンクショナライズされた継続表現と関連付けられます。 + +## 利点 {#advantages} + +* 柔軟な制御フロー表現。 +* 評価順を推論しやすくなる。 +* インタープリター、デバッガー、最適化器、非同期ランタイムの実装に有用。 + +## 欠点 {#disadvantages} + +* 直接形式に比べて冗長。 +* 人間には読みにくい場合がある。 +* 末尾呼び出しをネイティブにサポートしない言語では、効率のために末尾呼び出し最適化が必要。 diff --git a/src/concepts/cps.ko.md b/src/concepts/cps.ko.md new file mode 100644 index 0000000..6dbfda5 --- /dev/null +++ b/src/concepts/cps.ko.md @@ -0,0 +1,88 @@ + + +# 연속 전달 스타일(CPS) {#continuation-passing-style-cps} + +```admonish tip title="관련 항목" +Rust에서 의미로 설계하기: [일차 프로그램](../rust-dd/first-order-programs.md), [언어와 컴파일러 파이프라인](../rust-dd/compiler-pipelines.md) +개념: [자유 모나드](free_monad.md), [디펑셔널라이제이션](defunctionalization.md) +통찰: [EVM 대수](../insights/evm-alg.md) +``` + +```admonish note title="의미론적 위치" +CPS는 제어를 명시하는 표현이자 프로그램 변환입니다. 의미를 보존하는지는 명시된 소스 의미론과 대상 의미론 및 둘 사이의 대응 관계에 달려 있습니다. +``` + +## 정의 {#definition} + +연속 전달 스타일(CPS)은 함수가 값을 직접 반환하지 않는 프로그램 작성 방식입니다. 대신 프로그램의 나머지를 나타내는 *연속 실행*이라는 함수에 결과를 전달합니다. + +## 동기 {#motivation} + +* 제어 흐름을 명시하고 프로그램으로 다룰 수 있게 합니다. +* 논블로킹 IO, 조기 종료, 코루틴, 백트래킹, 동시성 스케줄링 같은 고급 변환을 가능하게 합니다. +* 최적화와 분석을 단순화하기 위해 컴파일러 중간 표현에서 사용됩니다. + +## 기본 형태 {#basic-form} + +직접 스타일: + +```rust +fn add_one(x: i32) -> i32 { + x + 1 +} + +fn main() { + let y = add_one(41); + println!("{}", y); +} +``` + +CPS: + +```rust +fn add_one_cps(x: i32, k: impl Fn(i32)) { + k(x + 1) +} + +fn main() { + add_one_cps(41, |y| { + println!("{}", y); + }); +} +``` + +여기서 `k`는 연속 실행입니다. `x + 1`를 직접 반환하는 대신 `k(x + 1)`를 호출합니다. + +## 주요 속성 {#key-properties} + +* 모든 함수 호출은 연속 실행에 대한 *꼬리 호출*입니다. +* 현재 계산은 호출자에게 “돌아오지” 않습니다. 대신 연속 실행으로 이동합니다. +* 프로그램에서 제어 흐름이 명시적으로 드러납니다. + +## 고차 함수와의 관계 {#relation-to-higher-order-functions} + +* CPS에서 연속 실행은 그저 고차 함수입니다. +* 계산의 각 단계는 다음에 할 일을 나타내는 연속 실행을 받습니다. + +## 디펑셔널라이제이션과의 관계 {#relation-to-defunctionalization} + +* CPS에서 연속 실행은 실제 함수 값입니다. +* 디펑셔널라이제이션은 연속 실행 함수를 다음 단계의 가능성을 나타내는 자료 구조(열거형)와 이를 해석하는 `apply` 함수로 대체합니다. + +## 자유 모나드와의 관계 {#relation-to-free-monads} + +* 자유 모나드의 `FlatMap` 생성자는 저장된 연속 실행입니다. +* 자유 모나드를 해석하는 것은 연속 실행이 프로그램 데이터에 포함된 CPS 코드를 실행하는 것과 같습니다. +* 적합한 자유 모나드 인코딩은 CPS 및 디펑셔널라이즈된 연속 실행 표현과 연관 지을 수 있습니다. + +## 장점 {#advantages} + +* 유연한 제어 흐름 표현. +* 평가 순서를 더 쉽게 추론할 수 있음. +* 인터프리터, 디버거, 최적화기, 비동기 런타임 구현에 유용함. + +## 단점 {#disadvantages} + +* 직접 스타일보다 장황함. +* 사람이 읽기 더 어려울 수 있음. +* 꼬리 호출 최적화가 기본 지원되지 않는 언어에서는 효율성을 위해 필요함. diff --git a/src/concepts/cps.ru.md b/src/concepts/cps.ru.md new file mode 100644 index 0000000..9e86f86 --- /dev/null +++ b/src/concepts/cps.ru.md @@ -0,0 +1,88 @@ + + +# Стиль передачи продолжений (CPS) {#continuation-passing-style-cps} + +```admonish tip title="Связанные материалы" +«Проектирование на основе смысла в Rust»: [Программы первого порядка](../rust-dd/first-order-programs.md), [Язык и конвейеры компилятора](../rust-dd/compiler-pipelines.md) +«Понятия»: [Свободная монада](free_monad.md), [Дефункционализация](defunctionalization.md) +«Идеи»: [Алгебра EVM](../insights/evm-alg.md) +``` + +```admonish note title="Семантическое место" +CPS — представление и преобразование программы, делающие управление явным. Сохранение смысла зависит от заданной семантики исходного и целевого языков и соответствия между ними. +``` + +## Определение {#definition} + +Стиль передачи продолжений (CPS) — способ писать программы, в котором функции не возвращают значения напрямую. Вместо этого они передают результат другой функции, называемой *продолжением* и представляющей остаток программы. + +## Зачем он нужен {#motivation} + +* Делает поток управления явным и программируемым. +* Позволяет выполнять сложные преобразования: неблокирующий ввод-вывод, досрочный выход, сопрограммы, возврат с перебором вариантов и планирование параллельных задач. +* Используется в промежуточных представлениях компиляторов для упрощения оптимизации и анализа. + +## Базовая форма {#basic-form} + +Прямой стиль: + +```rust +fn add_one(x: i32) -> i32 { + x + 1 +} + +fn main() { + let y = add_one(41); + println!("{}", y); +} +``` + +Стиль CPS: + +```rust +fn add_one_cps(x: i32, k: impl Fn(i32)) { + k(x + 1) +} + +fn main() { + add_one_cps(41, |y| { + println!("{}", y); + }); +} +``` + +Здесь `k` — продолжение. Вместо возврата значения `x + 1` мы вызываем `k(x + 1)`. + +## Основные свойства {#key-properties} + +* Все вызовы функций являются *хвостовыми вызовами* продолжений. +* Текущее вычисление никогда не «возвращается» к вызывающему коду, а переходит к продолжению. +* Поток управления становится явным в программе. + +## Связь с функциями высшего порядка {#relation-to-higher-order-functions} + +* В CPS продолжения — это обычные функции высшего порядка. +* Каждый шаг вычисления получает продолжение, которое задаёт, что делать дальше. + +## Связь с дефункционализацией {#relation-to-defunctionalization} + +* В CPS продолжение является настоящим значением-функцией. +* Дефункционализация заменяет функцию-продолжение структурой данных (перечислением), представляющей возможные следующие шаги, и функцией `apply` для их интерпретации. + +## Связь со свободными монадами {#relation-to-free-monads} + +* Конструктор `FlatMap` свободной монады и есть сохранённое продолжение. +* Интерпретация свободной монады похожа на выполнение кода CPS, в котором продолжение является частью данных программы. +* Подходящие кодирования свободных монад можно связать с CPS и представлениями дефункционализированных продолжений. + +## Преимущества {#advantages} + +* Гибкое представление потока управления. +* Упрощает рассуждения о порядке вычисления. +* Полезен при реализации интерпретаторов, отладчиков, оптимизаторов и асинхронных сред выполнения. + +## Недостатки {#disadvantages} + +* Более многословен по сравнению с прямым стилем. +* Может быть труднее для чтения. +* Для эффективной работы в языках без встроенной поддержки требует оптимизации хвостовых вызовов. diff --git a/src/concepts/cps.uk.md b/src/concepts/cps.uk.md new file mode 100644 index 0000000..e815182 --- /dev/null +++ b/src/concepts/cps.uk.md @@ -0,0 +1,88 @@ + + +# Стиль передавання продовжень (CPS) {#continuation-passing-style-cps} + +```admonish tip title="Пов’язані матеріали" +Проєктування від значення в Rust: [Програми першого порядку](../rust-dd/first-order-programs.md), [Мова й конвеєри компілятора](../rust-dd/compiler-pipelines.md) +Поняття: [Вільна монада](free_monad.md), [Дефункціоналізація](defunctionalization.md) +Інсайти: [Алгебра EVM](../insights/evm-alg.md) +``` + +```admonish note title="Семантичне місце" +CPS — це представлення й перетворення програм, яке робить керування явним. Чи зберігає воно значення, залежить від заданої семантики вихідної мови, цільової семантики та відповідності між ними. +``` + +## Визначення {#definition} + +Стиль передавання продовжень (CPS) — це спосіб писати програми, у якому функції не повертають значення безпосередньо. Натомість вони передають результат іншій функції — *продовженню*, що представляє решту програми. + +## Мотивація {#motivation} + +* Робить потік керування явним і програмованим. +* Уможливлює такі складні перетворення, як неблокувальний ввід-вивід, достроковий вихід, корутини, повернення назад і паралельне планування. +* Використовується в проміжних представленнях компілятора для спрощення оптимізації й аналізу. + +## Основна форма {#basic-form} + +У прямому стилі: + +```rust +fn add_one(x: i32) -> i32 { + x + 1 +} + +fn main() { + let y = add_one(41); + println!("{}", y); +} +``` + +У CPS: + +```rust +fn add_one_cps(x: i32, k: impl Fn(i32)) { + k(x + 1) +} + +fn main() { + add_one_cps(41, |y| { + println!("{}", y); + }); +} +``` + +Тут `k` — це продовження. Замість повернення `x + 1` ми викликаємо `k(x + 1)`. + +## Основні властивості {#key-properties} + +* Усі виклики функцій — це *кінцеві виклики* продовжень. +* Поточне обчислення ніколи не «повертається» до викликувача, а переходить до продовження. +* Потік керування стає явним у програмі. + +## Зв’язок із функціями вищого порядку {#relation-to-higher-order-functions} + +* У CPS продовження — це звичайні функції вищого порядку. +* Кожен крок обчислення отримує продовження, яке визначає наступну дію. + +## Зв’язок із дефункціоналізацією {#relation-to-defunctionalization} + +* У CPS продовження — це справжнє значення-функція. +* Дефункціоналізація замінює функцію-продовження структурою даних (переліком), що представляє можливі наступні кроки, і функцією `apply`, яка їх інтерпретує. + +## Зв’язок із вільними монадами {#relation-to-free-monads} + +* Конструктор `FlatMap` у вільній монаді — це збережене продовження. +* Інтерпретація вільної монади схожа на виконання коду CPS, де продовження є частиною даних програми. +* За відповідного кодування вільні монади можна пов’язати з CPS і представленнями дефункціоналізованих продовжень. + +## Переваги {#advantages} + +* Гнучке представлення потоку керування. +* Легше міркувати про порядок обчислення. +* Корисний інструмент для створення інтерпретаторів, налагоджувачів, оптимізаторів та асинхронних середовищ виконання. + +## Недоліки {#disadvantages} + +* Більш багатослівний порівняно з прямим стилем. +* Людям може бути важче читати. +* У мовах без вбудованої підтримки потрібна оптимізація кінцевих викликів для ефективного виконання. diff --git a/src/concepts/cps.vi.md b/src/concepts/cps.vi.md new file mode 100644 index 0000000..2e75b63 --- /dev/null +++ b/src/concepts/cps.vi.md @@ -0,0 +1,88 @@ + + +# Phong cách truyền tiếp nối (CPS) {#continuation-passing-style-cps} + +```admonish tip title="Liên quan" +Thiết kế theo ngữ nghĩa trong Rust: [Chương trình bậc nhất](../rust-dd/first-order-programs.md), [Quy trình ngôn ngữ và trình biên dịch](../rust-dd/compiler-pipelines.md) +Khái niệm: [Monad tự do](free_monad.md), [Phi chức năng hóa](defunctionalization.md) +Nhận định: [Đại số EVM](../insights/evm-alg.md) +``` + +```admonish note title="Vị trí ngữ nghĩa" +CPS là cách biểu diễn và phép biến đổi chương trình làm cho điều khiển trở nên tường minh. Việc nó có bảo toàn ý nghĩa hay không phụ thuộc vào ngữ nghĩa nguồn, ngữ nghĩa đích và mối tương ứng giữa chúng đã được nêu rõ. +``` + +## Định nghĩa {#definition} + +Phong cách truyền tiếp nối (CPS) là cách viết chương trình trong đó hàm không trả về giá trị trực tiếp. Thay vào đó, chúng truyền kết quả cho một hàm khác gọi là *tiếp nối*, biểu thị phần còn lại của chương trình. + +## Động lực {#motivation} + +* Làm cho luồng điều khiển trở nên tường minh và có thể lập trình. +* Cho phép các phép biến đổi nâng cao như IO không chặn, thoát sớm, coroutine, quay lui và lập lịch đồng thời. +* Được dùng trong biểu diễn trung gian của trình biên dịch để đơn giản hóa tối ưu hóa và phân tích. + +## Dạng cơ bản {#basic-form} + +Theo phong cách trực tiếp: + +```rust +fn add_one(x: i32) -> i32 { + x + 1 +} + +fn main() { + let y = add_one(41); + println!("{}", y); +} +``` + +Theo CPS: + +```rust +fn add_one_cps(x: i32, k: impl Fn(i32)) { + k(x + 1) +} + +fn main() { + add_one_cps(41, |y| { + println!("{}", y); + }); +} +``` + +Ở đây, `k` là tiếp nối. Thay vì trả về `x + 1`, ta gọi `k(x + 1)`. + +## Các thuộc tính chính {#key-properties} + +* Mọi lời gọi hàm đều là *lời gọi đuôi* đến các tiếp nối. +* Phép tính hiện tại không bao giờ “trả về” bên gọi; thay vào đó, nó nhảy vào tiếp nối. +* Luồng điều khiển trở nên tường minh trong chương trình. + +## Quan hệ với hàm bậc cao {#relation-to-higher-order-functions} + +* Trong CPS, tiếp nối chỉ là các hàm bậc cao. +* Mỗi bước tính toán nhận một tiếp nối biểu thị việc cần làm tiếp theo. + +## Quan hệ với phi chức năng hóa {#relation-to-defunctionalization} + +* Trong CPS, tiếp nối là một giá trị hàm thực sự. +* Phi chức năng hóa thay hàm tiếp nối bằng cấu trúc dữ liệu (enum) biểu diễn các bước tiếp theo có thể có, cùng một hàm `apply` để diễn giải chúng. + +## Quan hệ với monad tự do {#relation-to-free-monads} + +* Cấu trúc `FlatMap` trong monad tự do chính là tiếp nối được lưu trữ. +* Diễn giải monad tự do giống như chạy mã CPS trong đó tiếp nối là một phần của dữ liệu chương trình. +* Các cách mã hóa monad tự do phù hợp có thể liên hệ với CPS và cách biểu diễn tiếp nối đã phi chức năng hóa. + +## Ưu điểm {#advantages} + +* Biểu diễn luồng điều khiển linh hoạt. +* Dễ lập luận hơn về thứ tự đánh giá. +* Mạnh mẽ khi triển khai bộ diễn giải, trình gỡ lỗi, bộ tối ưu hóa và môi trường chạy bất đồng bộ. + +## Nhược điểm {#disadvantages} + +* Dài dòng hơn phong cách trực tiếp. +* Con người có thể khó đọc hơn. +* Cần tối ưu hóa lời gọi đuôi để đạt hiệu năng trong ngôn ngữ không hỗ trợ sẵn. diff --git a/src/concepts/cps.zh-hant.md b/src/concepts/cps.zh-hant.md new file mode 100644 index 0000000..74118b3 --- /dev/null +++ b/src/concepts/cps.zh-hant.md @@ -0,0 +1,88 @@ + + +# 延續傳遞風格(CPS) {#continuation-passing-style-cps} + +```admonish tip title="相關內容" +Rust 中的語義驅動設計:[一階程式](../rust-dd/first-order-programs.md)、[語言與編譯器流水線](../rust-dd/compiler-pipelines.md) +概念:[自由單子](free_monad.md)、[去函式化](defunctionalization.md) +洞見:[EVM 代數](../insights/evm-alg.md) +``` + +```admonish note title="語義定位" +CPS 是一種表示與程式變換,它會將控制流顯式化。它是否保留含義,取決於是否明確了源語義、目標語義及二者之間的對應關係。 +``` + +## 定義 {#definition} + +延續傳遞風格(CPS)是一種程式設計方式:函式不直接返回值,而是將結果傳給另一個稱為*延續*的函式;延續表示程式接下來的部分。 + +## 動機 {#motivation} + +* 使控制流顯式且可程式設計。 +* 支援非阻塞 IO、提前退出、協程、回溯與併發排程等高階變換。 +* 用於編譯器中間表示,以簡化最佳化與分析。 + +## 基本形式 {#basic-form} + +直接風格: + +```rust +fn add_one(x: i32) -> i32 { + x + 1 +} + +fn main() { + let y = add_one(41); + println!("{}", y); +} +``` + +CPS 風格: + +```rust +fn add_one_cps(x: i32, k: impl Fn(i32)) { + k(x + 1) +} + +fn main() { + add_one_cps(41, |y| { + println!("{}", y); + }); +} +``` + +這裡,`k`是延續。我們不再返回`x + 1`,而是呼叫`k(x + 1)`。 + +## 關鍵性質 {#key-properties} + +* 所有函式呼叫都是對延續的*尾呼叫*。 +* 當前計算永遠不會“返回”到呼叫者,而是跳入延續。 +* 程式中的控制流變得顯式。 + +## 與高階函式的關係 {#relation-to-higher-order-functions} + +* 在 CPS 中,延續就是高階函式。 +* 計算的每個步驟都會接收一個延續,用來表示下一步要做什麼。 + +## 與去函式化的關係 {#relation-to-defunctionalization} + +* 在 CPS 中,延續是實際的函式值。 +* 去函式化會把延續函式替換為表示可能後續步驟的資料結構(列舉),並提供一個`apply`函式來解釋這些步驟。 + +## 與自由單子的關係 {#relation-to-free-monads} + +* 自由單子中的`FlatMap`構造器恰好儲存了一個延續。 +* 解釋自由單子類似於執行 CPS 程式碼,只不過延續成為程式資料的一部分。 +* 適當的自由單子編碼可以與 CPS 以及去函式化的延續表示建立連結。 + +## 優點 {#advantages} + +* 控制流表示靈活。 +* 更容易推理求值順序。 +* 適用於實作直譯器、偵錯程式、最佳化器與非同步執行時。 + +## 缺點 {#disadvantages} + +* 比直接風格冗長。 +* 對人來說可能更難閱讀。 +* 在不提供原生支援的語言中,需要尾呼叫最佳化才能獲得較高效率。 diff --git a/src/concepts/cps.zh.md b/src/concepts/cps.zh.md new file mode 100644 index 0000000..d68ac08 --- /dev/null +++ b/src/concepts/cps.zh.md @@ -0,0 +1,88 @@ + + +# 延续传递风格(CPS) {#continuation-passing-style-cps} + +```admonish tip title="相关内容" +Rust 中的语义驱动设计:[一阶程序](../rust-dd/first-order-programs.md)、[语言与编译器流水线](../rust-dd/compiler-pipelines.md) +概念:[自由单子](free_monad.md)、[去函数化](defunctionalization.md) +洞见:[EVM 代数](../insights/evm-alg.md) +``` + +```admonish note title="语义定位" +CPS 是一种表示与程序变换,它会将控制流显式化。它是否保留含义,取决于是否明确了源语义、目标语义及二者之间的对应关系。 +``` + +## 定义 {#definition} + +延续传递风格(CPS)是一种编程方式:函数不直接返回值,而是将结果传给另一个称为*延续*的函数;延续表示程序接下来的部分。 + +## 动机 {#motivation} + +* 使控制流显式且可编程。 +* 支持非阻塞 IO、提前退出、协程、回溯与并发调度等高级变换。 +* 用于编译器中间表示,以简化优化与分析。 + +## 基本形式 {#basic-form} + +直接风格: + +```rust +fn add_one(x: i32) -> i32 { + x + 1 +} + +fn main() { + let y = add_one(41); + println!("{}", y); +} +``` + +CPS 风格: + +```rust +fn add_one_cps(x: i32, k: impl Fn(i32)) { + k(x + 1) +} + +fn main() { + add_one_cps(41, |y| { + println!("{}", y); + }); +} +``` + +这里,`k`是延续。我们不再返回`x + 1`,而是调用`k(x + 1)`。 + +## 关键性质 {#key-properties} + +* 所有函数调用都是对延续的*尾调用*。 +* 当前计算永远不会“返回”到调用者,而是跳入延续。 +* 程序中的控制流变得显式。 + +## 与高阶函数的关系 {#relation-to-higher-order-functions} + +* 在 CPS 中,延续就是高阶函数。 +* 计算的每个步骤都会接收一个延续,用来表示下一步要做什么。 + +## 与去函数化的关系 {#relation-to-defunctionalization} + +* 在 CPS 中,延续是实际的函数值。 +* 去函数化会把延续函数替换为表示可能后续步骤的数据结构(枚举),并提供一个`apply`函数来解释这些步骤。 + +## 与自由单子的关系 {#relation-to-free-monads} + +* 自由单子中的`FlatMap`构造器恰好存储了一个延续。 +* 解释自由单子类似于执行 CPS 代码,只不过延续成为程序数据的一部分。 +* 适当的自由单子编码可以与 CPS 以及去函数化的延续表示建立联系。 + +## 优点 {#advantages} + +* 控制流表示灵活。 +* 更容易推理求值顺序。 +* 适用于实现解释器、调试器、优化器与异步运行时。 + +## 缺点 {#disadvantages} + +* 比直接风格冗长。 +* 对人来说可能更难阅读。 +* 在不提供原生支持的语言中,需要尾调用优化才能获得较高效率。 diff --git a/src/concepts/defunctionalization.ar.md b/src/concepts/defunctionalization.ar.md new file mode 100644 index 0000000..5fe41c5 --- /dev/null +++ b/src/concepts/defunctionalization.ar.md @@ -0,0 +1,85 @@ + + +# إزالة الدوال {#defunctionalization} + +```admonish tip title="ذات صلة" +التصميم انطلاقًا من المعنى في Rust: [برامج من الرتبة الأولى](../rust-dd/first-order-programs.md)، [مسارات اللغة والمترجم](../rust-dd/compiler-pipelines.md) +المفاهيم: [الموناد الحر](free_monad.md)، [أسلوب تمرير الاستمرار](cps.md) +الرؤى: [جبر EVM](../insights/evm-alg.md) +``` + +```admonish note title="الموضع الدلالي" +تغيّر إزالة الدوال التمثيل مع استهداف الحفاظ على سلوك البرنامج. وفي التصميم الذي يبدأ بالمعنى، تفيد القيم المولدة من الرتبة الأولى عندما يحتاج مفسر آخر إلى فحص العمليات أو تركيبها قبل التنفيذ. +``` + +## التعريف {#definition} + +إزالة الدوال تحويل برمجي يستبدل الدوال عالية الرتبة ببنية بيانات من الرتبة الأولى تمثل الدوال الممكنة، مع دالة مفسر تطبقها. + +## الدافع {#motivation} + +لا تستطيع بعض اللغات أو المترجمات أو أزمنة التشغيل معالجة الدوال عالية الرتبة بكفاءة أو إطلاقًا. تتيح إزالة الدوال جعل البرنامج من الرتبة الأولى بالكامل، فيسهل تجميعه أو تحليله أو تسلسله أو تشغيله في بيئات مقيدة. + +## العملية {#the-process} + +1. حدد كل الدوال المحتملة عالية الرتبة التي يمكن إنشاؤها وتمريرها. +2. خصص لكل دالة منها وسمًا فريدًا في تعداد أو نوع مجموع، مع البيانات اللازمة لتشغيلها. +3. استبدل قيم الدوال بهذه الوسوم. +4. عرّف دالة `apply` تتلقى وسمًا ووسائط الدالة، ثم تطابق النمط على الوسم لتشغيل الكود الصحيح. + +## مثال في Rust {#example-in-rust} + +قبل: استخدام إغلاق + +```rust,noplayground +let k: Box i32> = Box::new(|x| x + 1); +println!("{}", k(41)); +``` + +بعد: صيغة أزيلت منها الدوال + +```rust,noplayground +enum Cont { + Add1 +} + +fn apply(c: Cont, x: i32) -> i32 { + match c { + Cont::Add1 => x + 1, + } +} + +println!("{}", apply(Cont::Add1, 41)); +``` + +## الخصائص {#properties} + +* أصبحت جميع الدوال ممثلة ببيانات بسيطة. +* أصبح البرنامج من الرتبة الأولى بالكامل. +* تحل دالة `apply` محل استدعاءات الدوال المباشرة. + +## التطبيقات {#applications} + +* تبسيط خلفية المترجم: تولد مترجمات كثيرة شيفرة بأسلوب تمرير الاستمرار ثم تزيل دوالها. +* تسلسل الدوال: يمكنك إرسال وسم التعداد عبر الشبكة أو تخزينه في ملف. +* التحليل الساكن: يسهل الاستدلال على الشيفرة من الرتبة الأولى. +* اشتقاق المفسرات: تقود إزالة الدوال طبيعيًا إلى نمط المفسر. + +## العلاقة بأسلوب تمرير الاستمرار {#relation-to-cps} + +في أسلوب تمرير الاستمرار (CPS)، تكون الاستمراريات دوالًا عالية الرتبة. وتحول إزالة الدوال شيفرة CPS هذه الاستمراريات إلى مجموعة منتهية من الحالات في تعداد مع دالة تطبيق. + +## العلاقة بالمونادات الحرة {#relation-to-free-monads} + +يمكن ربط تمثيلات مناسبة للموناد الحر باستمراريات أزيلت دوالها في برامج محولة إلى أسلوب تمرير الاستمرار. إنها صلة وثيقة، وليست تطابقًا عامًا بين البناءين. + +## التطبيق على مستوى الأنواع {#type-level-application} + +يمكن لإزالة الدوال أيضًا ترميز التطبيق على مستوى الأنواع في اللغات التي تفتقر إلى أنواع عالية الرتبة أصلية. وتطبق [تجربة جبريات الكائنات في C#](https://github.com/tgrospic/object-algebras) هذا الترميز الخفيف عبر `App` للتعبير عن جبريات الفونكتور والتطبيقي والموناد والآثار. + +## المراجع {#references} + +* رينولدز، J. C. (1972). *Definitional Interpreters for Higher-Order Programming Languages*. + [https://dl.acm.org/doi/epdf/10.1145/800194.805852](https://dl.acm.org/doi/epdf/10.1145/800194.805852) +* يالوب، J.، ووايت، L. (2014). *Lightweight Higher-Kinded Polymorphism* (يستخدم إزالة الدوال لترميز التطبيق على مستوى الأنواع). + [https://www.cl.cam.ac.uk/~jdy22/papers/lightweight-higher-kinded-polymorphism.pdf](https://www.cl.cam.ac.uk/~jdy22/papers/lightweight-higher-kinded-polymorphism.pdf) diff --git a/src/concepts/defunctionalization.de.md b/src/concepts/defunctionalization.de.md new file mode 100644 index 0000000..ab70ff3 --- /dev/null +++ b/src/concepts/defunctionalization.de.md @@ -0,0 +1,85 @@ + + +# Defunktionalisierung {#defunctionalization} + +```admonish tip title="Verwandte Themen" +Design by Meaning in Rust: [Programme erster Ordnung](../rust-dd/first-order-programs.md), [Sprach- und Compiler-Pipelines](../rust-dd/compiler-pipelines.md) +Concepts: [Freie Monade](free_monad.md), [Continuation-Passing Style](cps.md) +Insights: [EVM-Algebra](../insights/evm-alg.md) +``` + +```admonish note title="Semantische Einordnung" +Defunktionalisierung ändert die Repräsentation und soll dabei das Anwendungsverhalten bewahren. Im bedeutungsorientierten Entwurf sind erzeugte Werte erster Ordnung nützlich, wenn ein weiterer Interpreter Operationen vor der Ausführung untersuchen oder zusammensetzen muss. +``` + +## Definition {#definition} + +Defunktionalisierung ist eine Programmtransformation, die höherwertige Funktionen durch eine Datenstruktur erster Ordnung ersetzt, welche die möglichen Funktionen darstellt, sowie durch eine Interpreterfunktion, die sie anwendet. + +## Motivation {#motivation} + +Manche Sprachen, Compiler oder Laufzeitumgebungen können höherwertige Funktionen nicht effizient oder gar nicht verarbeiten. Durch Defunktionalisierung wird das Programm vollständig erstordentlich und lässt sich leichter kompilieren, analysieren, serialisieren oder in eingeschränkten Umgebungen ausführen. + +## Vorgehensweise {#the-process} + +1. Alle möglichen höherwertigen Funktionen bestimmen, die erzeugt und weitergereicht werden können. +2. Jeder solchen Funktion ein eindeutiges Tag in einem Enum oder Summentyp zuweisen, zusammen mit den für ihre Ausführung benötigten Daten. +3. Funktionswerte durch diese Tags ersetzen. +4. Eine `apply`\-Funktion definieren, die ein Tag und die Funktionsargumente erhält und dann anhand des Tags den passenden Code ausführt. + +## Beispiel in Rust {#example-in-rust} + +Vorher: mit einem Closure + +```rust,noplayground +let k: Box i32> = Box::new(|x| x + 1); +println!("{}", k(41)); +``` + +Nachher: defunktionalisierte Form + +```rust,noplayground +enum Cont { + Add1 +} + +fn apply(c: Cont, x: i32) -> i32 { + match c { + Cont::Add1 => x + 1, + } +} + +println!("{}", apply(Cont::Add1, 41)); +``` + +## Eigenschaften {#properties} + +* Alle Funktionen werden nun durch einfache Daten dargestellt. +* Das Programm wird vollständig erstordentlich. +* Die Funktion `apply` ersetzt direkte Funktionsaufrufe. + +## Anwendungen {#applications} + +* Vereinfachung des Compiler-Backends: Viele Compiler erzeugen CPS-Code und defunktionalisieren ihn anschließend. +* Serialisierung von Funktionen: Das Enum-Tag lässt sich über ein Netzwerk senden oder in einer Datei speichern. +* Statische Analyse: Erstordentlicher Code lässt sich leichter durchdenken. +* Ableitung von Interpretern: Defunktionalisierung führt auf natürliche Weise zu einem Interpreter-Muster. + +## Beziehung zu CPS {#relation-to-cps} + +In CPS (Continuation-Passing Style) sind Fortsetzungen höherwertige Funktionen. Defunktionalisierung von CPS-Code verwandelt diese Fortsetzungen in eine endliche Menge von Fällen in einem Enum sowie eine Anwendungsfunktion. + +## Beziehung zu freien Monaden {#relation-to-free-monads} + +Geeignete Repräsentationen freier Monaden lassen sich mit defunktionalisierten Fortsetzungen in CPS-transformierten Programmen in Beziehung setzen. Es besteht ein enger Zusammenhang, aber keine allgemeingültige Identität zwischen den beiden Konstruktionen. + +## Anwendung auf Typebene {#type-level-application} + +Defunktionalisierung kann auch Anwendungen auf Typebene in Sprachen ohne native Typen höherer Ordnung kodieren. Das [object-algebras C# experiment](https://github.com/tgrospic/object-algebras) setzt diese leichtgewichtige Kodierung mit `App` um und drückt damit Funktor-, Applikativ-, Monaden- und Effektalgebren aus. + +## Quellen {#references} + +* Reynolds, J. C. (1972). *Definitional Interpreters for Higher-Order Programming Languages*. + [https://dl.acm.org/doi/epdf/10.1145/800194.805852](https://dl.acm.org/doi/epdf/10.1145/800194.805852) +* Yallop, J. und White, L. (2014). *Lightweight Higher-Kinded Polymorphism* (verwendet Defunktionalisierung zur Kodierung von Anwendungen auf Typebene). + [https://www.cl.cam.ac.uk/~jdy22/papers/lightweight-higher-kinded-polymorphism.pdf](https://www.cl.cam.ac.uk/~jdy22/papers/lightweight-higher-kinded-polymorphism.pdf) diff --git a/src/concepts/defunctionalization.es.md b/src/concepts/defunctionalization.es.md new file mode 100644 index 0000000..af3f789 --- /dev/null +++ b/src/concepts/defunctionalization.es.md @@ -0,0 +1,85 @@ + + +# Defuncionalización {#defunctionalization} + +```admonish tip title="Relacionado" +Diseño basado en el significado en Rust: [Programas de primer orden](../rust-dd/first-order-programs.md), [Lenguaje y procesos de compilación](../rust-dd/compiler-pipelines.md) +Conceptos: [Mónada libre](free_monad.md), [Estilo de paso de continuaciones](cps.md) +Perspectivas: [Álgebra EVM](../insights/evm-alg.md) +``` + +```admonish note title="Ubicación semántica" +La defuncionalización cambia la representación con la intención de preservar el comportamiento de aplicación. En el diseño guiado por el significado, los valores generados de primer orden son útiles cuando otro intérprete debe inspeccionar o componer operaciones antes de ejecutarlas. +``` + +## Definición {#definition} + +La defuncionalización es una transformación de programas que reemplaza las funciones de orden superior por una estructura de datos de primer orden que representa las funciones posibles, junto con una función intérprete que las aplica. + +## Motivación {#motivation} + +Algunos lenguajes, compiladores o entornos de ejecución no pueden manejar funciones de orden superior de manera eficiente, o no pueden manejarlas en absoluto. Al defuncionalizar, el programa se convierte en un programa totalmente de primer orden, más fácil de compilar, analizar, serializar o ejecutar en entornos restringidos. + +## El proceso {#the-process} + +1. Identifica todas las funciones de orden superior posibles que se pueden crear y pasar de un lugar a otro. +2. Asigna a cada función una etiqueta única en una enumeración o tipo suma, junto con los datos que necesita para funcionar. +3. Reemplaza los valores de función por estas etiquetas. +4. Define una función `apply` que tome una etiqueta y los argumentos de la función, y luego use una coincidencia de patrones con la etiqueta para ejecutar el código adecuado. + +## Ejemplo en Rust {#example-in-rust} + +Antes: usar un cierre + +```rust,noplayground +let k: Box i32> = Box::new(|x| x + 1); +println!("{}", k(41)); +``` + +Después: forma defuncionalizada + +```rust,noplayground +enum Cont { + Add1 +} + +fn apply(c: Cont, x: i32) -> i32 { + match c { + Cont::Add1 => x + 1, + } +} + +println!("{}", apply(Cont::Add1, 41)); +``` + +## Propiedades {#properties} + +* Todas las funciones se representan ahora mediante datos simples. +* El programa queda reducido a primer orden. +* La función `apply` reemplaza las llamadas directas a funciones. + +## Aplicaciones {#applications} + +* Simplificación del backend del compilador: muchos compiladores generan código CPS y después lo defuncionalizan. +* Serialización de funciones: es posible enviar la etiqueta de la enumeración por una red o guardarla en un archivo. +* Análisis estático: el código de primer orden es más fácil de analizar. +* Derivación de intérpretes: la defuncionalización conduce de forma natural al patrón Intérprete. + +## Relación con CPS {#relation-to-cps} + +En CPS (estilo de paso de continuaciones), las continuaciones son funciones de orden superior. Defuncionalizar código CPS convierte estas continuaciones en un conjunto finito de casos de una enumeración, junto con una función de aplicación. + +## Relación con las mónadas libres {#relation-to-free-monads} + +Las representaciones adecuadas de mónadas libres pueden relacionarse con las continuaciones defuncionalizadas de programas transformados a CPS. Es una conexión estrecha, no una identidad universal entre ambas construcciones. + +## Aplicación de tipos a nivel de tipos {#type-level-application} + +La defuncionalización también permite codificar la aplicación de tipos a nivel de tipos en lenguajes sin tipos de orden superior nativos. El [experimento de álgebra de objetos en C#](https://github.com/tgrospic/object-algebras) aplica esta codificación ligera mediante `App` para expresar álgebras de funtores, aplicativos, mónadas y efectos. + +## Referencias {#references} + +* Reynolds, J. C. (1972). *Definitional Interpreters for Higher-Order Programming Languages*. + [https://dl.acm.org/doi/epdf/10.1145/800194.805852](https://dl.acm.org/doi/epdf/10.1145/800194.805852) +* Yallop, J. y White, L. (2014). *Lightweight Higher-Kinded Polymorphism* (usa la defuncionalización para codificar la aplicación a nivel de tipos). + [https://www.cl.cam.ac.uk/~jdy22/papers/lightweight-higher-kinded-polymorphism.pdf](https://www.cl.cam.ac.uk/~jdy22/papers/lightweight-higher-kinded-polymorphism.pdf) diff --git a/src/concepts/defunctionalization.ja.md b/src/concepts/defunctionalization.ja.md new file mode 100644 index 0000000..3eceab3 --- /dev/null +++ b/src/concepts/defunctionalization.ja.md @@ -0,0 +1,85 @@ + + +# 関数のデファンクショナライズ {#defunctionalization} + +```admonish tip title="関連項目" +Rustで意味から設計する:[一階プログラム](../rust-dd/first-order-programs.md)、[言語とコンパイラーパイプライン](../rust-dd/compiler-pipelines.md) +概念:[自由モナド](free_monad.md)、[継続渡し形式](cps.md) +洞察:[EVM代数](../insights/evm-alg.md) +``` + +```admonish note title="意味論上の位置付け" +デファンクショナライズは、関数適用の振る舞いを保つことを意図しつつ、表現を変えます。意味から始める設計では、実行前に別のインタープリターが操作を検査または合成する必要がある場合、生成された一階の値が役立ちます。 +``` + +## 定義 {#definition} + +デファンクショナライズとは、高階関数を、考えられる関数を表す一階データ構造と、それを適用するインタープリター関数に置き換えるプログラム変換です。 + +## 目的 {#motivation} + +言語、コンパイラー、ランタイムによっては、高階関数を効率的に扱えなかったり、まったく扱えなかったりします。デファンクショナライズすると、プログラムが一階だけになり、コンパイル、解析、シリアライズ、制限された環境での実行が容易になります。 + +## 手順 {#the-process} + +1. 生成され、受け渡される可能性のある高階関数をすべて特定する。 +2. 各関数に一意のタグを割り当て、列挙型または直和型と、その操作に必要なデータで表す。 +3. 関数値をこれらのタグに置き換える。 +4. タグと関数の引数を受け取り、タグでパターンマッチして適切なコードを実行する`apply`関数を定義する。 + +## Rustでの例 {#example-in-rust} + +変換前:クロージャを使う + +```rust,noplayground +let k: Box i32> = Box::new(|x| x + 1); +println!("{}", k(41)); +``` + +変換後:デファンクショナライズされた形式 + +```rust,noplayground +enum Cont { + Add1 +} + +fn apply(c: Cont, x: i32) -> i32 { + match c { + Cont::Add1 => x + 1, + } +} + +println!("{}", apply(Cont::Add1, 41)); +``` + +## 性質 {#properties} + +* すべての関数が単純なデータで表現される。 +* プログラムが一階だけになる。 +* `apply`関数が直接の関数呼び出しに取って代わる。 + +## 用途 {#applications} + +* コンパイラーバックエンドの単純化:多くのコンパイラーはCPSコードを生成してからデファンクショナライズします。 +* 関数のシリアライズ:列挙型のタグをネットワーク越しに送信したり、ファイルに格納したりできます。 +* 静的解析:一階コードのほうが推論しやすい。 +* インタープリターの導出:デファンクショナライズは自然にInterpreterパターンへつながる。 + +## CPSとの関係 {#relation-to-cps} + +CPS(継続渡し形式)では、継続は高階関数です。CPSコードをデファンクショナライズすると、継続が有限個のケースを持つ列挙型と適用関数になります。 + +## 自由モナドとの関係 {#relation-to-free-monads} + +適切な自由モナド表現は、CPS変換されたプログラムにあるデファンクショナライズ済みの継続と関連付けられます。密接な関係ではありますが、二つの構成が常に同一というわけではありません。 + +## 型レベルの適用 {#type-level-application} + +ネイティブな高カインド型を持たない言語では、デファンクショナライズを使って型レベルの適用も符号化できます。[オブジェクト代数を試すC#の実験](https://github.com/tgrospic/object-algebras)では、この軽量な符号化を`App`に適用して、ファンクター、アプリカティブ、モナド、副作用の代数を表します。 + +## 参考文献 {#references} + +* Reynolds, J. C.(1972)。*Definitional Interpreters for Higher-Order Programming Languages*。 + [https://dl.acm.org/doi/epdf/10.1145/800194.805852](https://dl.acm.org/doi/epdf/10.1145/800194.805852) +* Yallop, J.、White, L.(2014)。*Lightweight Higher-Kinded Polymorphism*(型レベルの適用をデファンクショナライズで符号化)。 + [https://www.cl.cam.ac.uk/~jdy22/papers/lightweight-higher-kinded-polymorphism.pdf](https://www.cl.cam.ac.uk/~jdy22/papers/lightweight-higher-kinded-polymorphism.pdf) diff --git a/src/concepts/defunctionalization.ko.md b/src/concepts/defunctionalization.ko.md new file mode 100644 index 0000000..829ea6a --- /dev/null +++ b/src/concepts/defunctionalization.ko.md @@ -0,0 +1,85 @@ + + +# 디펑셔널라이제이션 {#defunctionalization} + +```admonish tip title="관련 항목" +Rust에서 의미로 설계하기: [일차 프로그램](../rust-dd/first-order-programs.md), [언어와 컴파일러 파이프라인](../rust-dd/compiler-pipelines.md) +개념: [자유 모나드](free_monad.md), [연속 전달 스타일](cps.md) +통찰: [EVM 대수](../insights/evm-alg.md) +``` + +```admonish note title="의미론적 위치" +디펑셔널라이제이션은 프로그램 동작을 보존하려는 의도로 표현을 변경합니다. 의미 우선 설계에서는 실행 전에 다른 인터프리터가 연산을 검사하거나 합성해야 할 때 생성된 일차 값을 활용할 수 있습니다. +``` + +## 정의 {#definition} + +디펑셔널라이제이션은 고차 함수를 가능한 함수를 나타내는 일차 자료 구조와 그 함수를 적용하는 인터프리터 함수로 대체하는 프로그램 변환입니다. + +## 동기 {#motivation} + +일부 언어, 컴파일러, 런타임은 고차 함수를 효율적으로 처리할 수 없거나 전혀 지원하지 않습니다. 디펑셔널라이제이션을 하면 프로그램이 온전히 일차 형태가 되어 컴파일, 분석, 직렬화 또는 제한된 환경에서 실행하기 쉬워집니다. + +## 절차 {#the-process} + +1. 생성되어 전달될 수 있는 모든 고차 함수를 파악합니다. +2. 각 함수가 필요로 하는 데이터와 함께 열거형이나 합 타입에서 고유 태그를 부여합니다. +3. 함수 값을 이 태그로 바꿉니다. +4. 태그와 함수 인수를 받는 `apply` 함수를 정의한 다음, 태그를 패턴 매칭해 올바른 코드를 실행합니다. + +## Rust 예시 {#example-in-rust} + +변환 전: 클로저 사용 + +```rust,noplayground +let k: Box i32> = Box::new(|x| x + 1); +println!("{}", k(41)); +``` + +변환 후: 디펑셔널라이즈된 형태 + +```rust,noplayground +enum Cont { + Add1 +} + +fn apply(c: Cont, x: i32) -> i32 { + match c { + Cont::Add1 => x + 1, + } +} + +println!("{}", apply(Cont::Add1, 41)); +``` + +## 속성 {#properties} + +* 모든 함수가 이제 단순한 데이터로 표현됩니다. +* 프로그램은 순수한 일차 형태가 됩니다. +* `apply` 함수가 직접 함수 호출을 대체합니다. + +## 응용 {#applications} + +* 컴파일러 백엔드 단순화: 많은 컴파일러가 CPS 코드를 만든 다음 디펑셔널라이즈합니다. +* 함수 직렬화: 열거형 태그를 네트워크로 보내거나 파일에 저장할 수 있습니다. +* 정적 분석: 일차 코드는 추론하기 쉽습니다. +* 인터프리터 도출: 디펑셔널라이제이션은 자연스럽게 인터프리터 패턴으로 이어집니다. + +## CPS와의 관계 {#relation-to-cps} + +CPS(연속 전달 스타일)에서 연속 실행은 고차 함수입니다. CPS 코드를 디펑셔널라이즈하면 연속 실행이 열거형의 유한한 사례 집합과 적용 함수로 바뀝니다. + +## 자유 모나드와의 관계 {#relation-to-free-monads} + +적합한 자유 모나드 표현은 CPS로 변환된 프로그램의 디펑셔널라이즈된 연속 실행과 관련될 수 있습니다. 밀접한 연관은 있지만 두 구성이 항상 동일한 것은 아닙니다. + +## 타입 수준 애플리케이션 {#type-level-application} + +디펑셔널라이제이션은 고차 종류 타입을 기본 지원하지 않는 언어에서도 타입 수준 애플리케이션을 인코딩할 수 있습니다. [객체 대수를 적용한 C# 실험](https://github.com/tgrospic/object-algebras)은 `App`를 이용해 이 경량 인코딩을 적용하고, 펑터, 애플리케이티브, 모나드, 효과 대수를 표현합니다. + +## 참고 문헌 {#references} + +* Reynolds, J. C. (1972). *Definitional Interpreters for Higher-Order Programming Languages*. + [https://dl.acm.org/doi/epdf/10.1145/800194.805852](https://dl.acm.org/doi/epdf/10.1145/800194.805852) +* Yallop, J., White, L. (2014). *Lightweight Higher-Kinded Polymorphism* (디펑셔널라이제이션을 이용해 타입 수준 애플리케이션 인코딩). + [https://www.cl.cam.ac.uk/~jdy22/papers/lightweight-higher-kinded-polymorphism.pdf](https://www.cl.cam.ac.uk/~jdy22/papers/lightweight-higher-kinded-polymorphism.pdf) diff --git a/src/concepts/defunctionalization.ru.md b/src/concepts/defunctionalization.ru.md new file mode 100644 index 0000000..83a07e4 --- /dev/null +++ b/src/concepts/defunctionalization.ru.md @@ -0,0 +1,85 @@ + + +# Дефункционализация {#defunctionalization} + +```admonish tip title="Связанные материалы" +«Проектирование на основе смысла в Rust»: [Программы первого порядка](../rust-dd/first-order-programs.md), [Язык и конвейеры компилятора](../rust-dd/compiler-pipelines.md) +«Понятия»: [Свободная монада](free_monad.md), [Стиль передачи продолжений](cps.md) +«Идеи»: [Алгебра EVM](../insights/evm-alg.md) +``` + +```admonish note title="Семантическое место" +Дефункционализация меняет представление, стремясь сохранить поведение при применении функции. В проектировании с приоритетом смысла сгенерированные значения первого порядка полезны, когда другому интерпретатору нужно анализировать или компоновать операции до выполнения. +``` + +## Определение {#definition} + +Дефункционализация — преобразование программы, заменяющее функции высшего порядка структурой данных первого порядка, представляющей возможные функции, и функцией-интерпретатором, которая их применяет. + +## Зачем это нужно {#motivation} + +Некоторые языки, компиляторы или среды выполнения не поддерживают функции высшего порядка либо обрабатывают их неэффективно. Дефункционализация превращает программу в программу первого порядка, которую проще компилировать, анализировать, сериализовать или запускать в ограниченной среде. + +## Процесс {#the-process} + +1. Определите все функции высшего порядка, которые могут быть созданы и переданы. +2. Назначьте каждой такой функции отдельный тег в перечислении или суммарном типе вместе с данными, необходимыми для её работы. +3. Замените значения-функции этими тегами. +4. Определите функцию `apply`, принимающую тег и аргументы функции, а затем сопоставляющую тег с соответствующим кодом. + +## Пример на Rust {#example-in-rust} + +До: использование замыкания + +```rust,noplayground +let k: Box i32> = Box::new(|x| x + 1); +println!("{}", k(41)); +``` + +После: дефункционализированная форма + +```rust,noplayground +enum Cont { + Add1 +} + +fn apply(c: Cont, x: i32) -> i32 { + match c { + Cont::Add1 => x + 1, + } +} + +println!("{}", apply(Cont::Add1, 41)); +``` + +## Свойства {#properties} + +* Теперь все функции представлены простыми данными. +* Программа становится программой первого порядка. +* Функция `apply` заменяет прямые вызовы функций. + +## Применение {#applications} + +* Упрощение бэкенда компилятора: многие компиляторы создают код CPS, а затем дефункционализируют его. +* Сериализация функций: тег перечисления можно передать по сети или сохранить в файл. +* Статический анализ: рассуждать о коде первого порядка проще. +* Вывод интерпретаторов: дефункционализация естественным образом приводит к паттерну Интерпретатор. + +## Связь с CPS {#relation-to-cps} + +В CPS (стиле передачи продолжений) продолжения являются функциями высшего порядка. Дефункционализация кода CPS превращает их в конечный набор вариантов перечисления и функцию применения. + +## Связь со свободными монадами {#relation-to-free-monads} + +Подходящие представления свободных монад можно связать с дефункционализированными продолжениями в программах после CPS-преобразования. Это тесная связь, но не тождество двух построений во всех случаях. + +## Применение на уровне типов {#type-level-application} + +Дефункционализация также позволяет кодировать применение на уровне типов в языках без встроенной поддержки типов высшего рода. [Эксперимент с объектными алгебрами на C#](https://github.com/tgrospic/object-algebras) применяет это лёгкое кодирование через `App` для выражения алгебр функторов, аппликативов, монад и эффектов. + +## Источники {#references} + +* Рейнольдс, Дж. К. (1972). *Definitional Interpreters for Higher-Order Programming Languages*. + [https://dl.acm.org/doi/epdf/10.1145/800194.805852](https://dl.acm.org/doi/epdf/10.1145/800194.805852) +* Яллоп, Дж. и Уайт, Л. (2014). *Lightweight Higher-Kinded Polymorphism* (использует дефункционализацию для кодирования применения на уровне типов). + [https://www.cl.cam.ac.uk/~jdy22/papers/lightweight-higher-kinded-polymorphism.pdf](https://www.cl.cam.ac.uk/~jdy22/papers/lightweight-higher-kinded-polymorphism.pdf) diff --git a/src/concepts/defunctionalization.uk.md b/src/concepts/defunctionalization.uk.md new file mode 100644 index 0000000..f9f6288 --- /dev/null +++ b/src/concepts/defunctionalization.uk.md @@ -0,0 +1,85 @@ + + +# Дефункціоналізація {#defunctionalization} + +```admonish tip title="Пов’язані матеріали" +Проєктування від значення в Rust: [Програми першого порядку](../rust-dd/first-order-programs.md), [Мова й конвеєри компілятора](../rust-dd/compiler-pipelines.md) +Поняття: [Вільна монада](free_monad.md), [Стиль передавання продовжень](cps.md) +Інсайти: [Алгебра EVM](../insights/evm-alg.md) +``` + +```admonish note title="Семантичне місце" +Дефункціоналізація змінює представлення, прагнучи зберегти поведінку застосування. У проєктуванні, орієнтованому на значення, згенеровані значення першого порядку корисні, коли іншому інтерпретатору потрібно оглядати чи поєднувати операції до виконання. +``` + +## Визначення {#definition} + +Дефункціоналізація — це перетворення програми, яке замінює функції вищого порядку структурою даних першого порядку з представленням можливих функцій і функцією-інтерпретатором, яка їх застосовує. + +## Мотивація {#motivation} + +Деякі мови, компілятори чи середовища виконання не можуть ефективно обробляти функції вищого порядку або не можуть робити цього взагалі. Дефункціоналізація перетворює програму лише на конструкції першого порядку, які легше компілювати, аналізувати, серіалізувати чи виконувати в обмеженому середовищі. + +## Процес {#the-process} + +1. Визначте всі функції вищого порядку, які можуть бути створені й передані далі. +2. Призначте кожній такій функції унікальний тег у переліку чи сумарному типі разом із потрібними для її роботи даними. +3. Замініть значення-функції цими тегами. +4. Визначте функцію `apply`, яка приймає тег і аргументи функції, а потім зіставляє тег із відповідним кодом. + +## Приклад на Rust {#example-in-rust} + +До перетворення: замикання + +```rust,noplayground +let k: Box i32> = Box::new(|x| x + 1); +println!("{}", k(41)); +``` + +Після перетворення: дефункціоналізована форма + +```rust,noplayground +enum Cont { + Add1 +} + +fn apply(c: Cont, x: i32) -> i32 { + match c { + Cont::Add1 => x + 1, + } +} + +println!("{}", apply(Cont::Add1, 41)); +``` + +## Властивості {#properties} + +* Тепер усі функції представлені простими даними. +* Програма складається лише з конструкцій першого порядку. +* Функція `apply` замінює прямі виклики функцій. + +## Застосування {#applications} + +* Спрощення внутрішнього компонента компілятора: багато компіляторів генерують код CPS, а потім дефункціоналізують його. +* Серіалізація функцій: тег переліку можна надіслати мережею чи зберегти у файлі. +* Статичний аналіз: про код першого порядку легше міркувати. +* Виведення інтерпретаторів: дефункціоналізація природно приводить до патерну Interpreter. + +## Зв’язок із CPS {#relation-to-cps} + +У CPS (стилі передавання продовжень) продовження — це функції вищого порядку. Дефункціоналізація коду CPS перетворює ці продовження на скінченну множину варіантів переліку й функцію застосування. + +## Зв’язок із вільними монадами {#relation-to-free-monads} + +Відповідні представлення вільних монад можна пов’язати з дефункціоналізованими продовженнями у програмах, перетворених на CPS. Це тісний зв’язок, але не універсальна тотожність двох конструкцій. + +## Застосування на рівні типів {#type-level-application} + +Дефункціоналізацію також можна використовувати для кодування застосування на рівні типів у мовах без вбудованої підтримки типів вищого порядку. Експеримент із [об’єктними алгебрами в C#](https://github.com/tgrospic/object-algebras) використовує це легке кодування через `App` для вираження алгебр функторів, аплікативних функторів, монад та ефектів. + +## Джерела {#references} + +* Рейнольдс, Дж. К. (1972). *Definitional Interpreters for Higher-Order Programming Languages*. + [https://dl.acm.org/doi/epdf/10.1145/800194.805852](https://dl.acm.org/doi/epdf/10.1145/800194.805852) +* Яллоп, Дж. і Вайт, Л. (2014). *Lightweight Higher-Kinded Polymorphism* (кодування застосування на рівні типів через дефункціоналізацію). + [https://www.cl.cam.ac.uk/~jdy22/papers/lightweight-higher-kinded-polymorphism.pdf](https://www.cl.cam.ac.uk/~jdy22/papers/lightweight-higher-kinded-polymorphism.pdf) diff --git a/src/concepts/defunctionalization.vi.md b/src/concepts/defunctionalization.vi.md new file mode 100644 index 0000000..a736ccf --- /dev/null +++ b/src/concepts/defunctionalization.vi.md @@ -0,0 +1,85 @@ + + +# Phi chức năng hóa {#defunctionalization} + +```admonish tip title="Liên quan" +Thiết kế theo ngữ nghĩa trong Rust: [Chương trình bậc nhất](../rust-dd/first-order-programs.md), [Quy trình ngôn ngữ và trình biên dịch](../rust-dd/compiler-pipelines.md) +Khái niệm: [Monad tự do](free_monad.md), [Phong cách truyền tiếp nối](cps.md) +Nhận định: [Đại số EVM](../insights/evm-alg.md) +``` + +```admonish note title="Vị trí ngữ nghĩa" +Phi chức năng hóa thay đổi cách biểu diễn trong khi hướng tới bảo toàn hành vi ứng dụng. Trong thiết kế lấy ý nghĩa làm trọng tâm, các giá trị bậc nhất được tạo sinh hữu ích khi một bộ diễn giải khác cần kiểm tra hoặc hợp thành phép toán trước khi thực thi. +``` + +## Định nghĩa {#definition} + +Phi chức năng hóa là phép biến đổi chương trình thay các hàm bậc cao bằng cấu trúc dữ liệu bậc nhất biểu diễn các hàm có thể có, cùng một hàm diễn giải để áp dụng chúng. + +## Động lực {#motivation} + +Một số ngôn ngữ, trình biên dịch hoặc môi trường chạy không thể xử lý hàm bậc cao hiệu quả, thậm chí không thể xử lý. Phi chức năng hóa khiến chương trình hoàn toàn bậc nhất, nhờ đó dễ biên dịch, phân tích, tuần tự hóa hoặc chạy trong môi trường hạn chế. + +## Quy trình {#the-process} + +1. Xác định mọi hàm bậc cao có thể được tạo ra và truyền đi. +2. Gán cho mỗi hàm một thẻ duy nhất trong enum hoặc kiểu tổng, cùng mọi dữ liệu mà nó cần để hoạt động. +3. Thay các giá trị hàm bằng những thẻ này. +4. Định nghĩa hàm `apply` nhận một thẻ cùng các đối số hàm, sau đó đối sánh mẫu theo thẻ để chạy mã phù hợp. + +## Ví dụ trong Rust {#example-in-rust} + +Trước: dùng closure + +```rust,noplayground +let k: Box i32> = Box::new(|x| x + 1); +println!("{}", k(41)); +``` + +Sau: dạng đã phi chức năng hóa + +```rust,noplayground +enum Cont { + Add1 +} + +fn apply(c: Cont, x: i32) -> i32 { + match c { + Cont::Add1 => x + 1, + } +} + +println!("{}", apply(Cont::Add1, 41)); +``` + +## Thuộc tính {#properties} + +* Giờ mọi hàm đều được biểu diễn bằng dữ liệu đơn giản. +* Chương trình trở thành hoàn toàn bậc nhất. +* Hàm `apply` thay cho các lời gọi hàm trực tiếp. + +## Ứng dụng {#applications} + +* Đơn giản hóa backend trình biên dịch: nhiều trình biên dịch tạo mã CPS rồi phi chức năng hóa mã đó. +* Tuần tự hóa hàm: có thể gửi thẻ enum qua mạng hoặc lưu trong tệp. +* Phân tích tĩnh: mã bậc nhất dễ lập luận hơn. +* Suy ra bộ diễn giải: phi chức năng hóa tự nhiên dẫn đến mẫu bộ diễn giải. + +## Quan hệ với CPS {#relation-to-cps} + +Trong CPS (phong cách truyền tiếp nối), tiếp nối là hàm bậc cao. Phi chức năng hóa mã CPS chuyển các tiếp nối này thành tập trường hợp hữu hạn trong enum cùng hàm apply. + +## Quan hệ với monad tự do {#relation-to-free-monads} + +Các biểu diễn monad tự do phù hợp có thể liên hệ với tiếp nối đã phi chức năng hóa trong chương trình được chuyển đổi sang CPS. Đây là mối liên hệ chặt chẽ, không phải sự đồng nhất phổ quát giữa hai cấu trúc. + +## Phép áp dụng ở cấp kiểu {#type-level-application} + +Phi chức năng hóa cũng có thể mã hóa phép áp dụng ở cấp kiểu trong các ngôn ngữ không có kiểu bậc cao nguyên thủy. Thử nghiệm [đại số đối tượng C#](https://github.com/tgrospic/object-algebras) áp dụng cách mã hóa nhẹ này thông qua `App` để biểu đạt các đại số functor, applicative, monad và hiệu ứng. + +## Tài liệu tham khảo {#references} + +* Reynolds, J. C. (1972). *Definitional Interpreters for Higher-Order Programming Languages*. + [https://dl.acm.org/doi/epdf/10.1145/800194.805852](https://dl.acm.org/doi/epdf/10.1145/800194.805852) +* Yallop, J. và White, L. (2014). *Lightweight Higher-Kinded Polymorphism* (dùng phi chức năng hóa để mã hóa ứng dụng cấp kiểu). + [https://www.cl.cam.ac.uk/~jdy22/papers/lightweight-higher-kinded-polymorphism.pdf](https://www.cl.cam.ac.uk/~jdy22/papers/lightweight-higher-kinded-polymorphism.pdf) diff --git a/src/concepts/defunctionalization.zh-hant.md b/src/concepts/defunctionalization.zh-hant.md new file mode 100644 index 0000000..bc61962 --- /dev/null +++ b/src/concepts/defunctionalization.zh-hant.md @@ -0,0 +1,85 @@ + + +# 去函式化 {#defunctionalization} + +```admonish tip title="相關內容" +Rust 中的語義驅動設計:[一階程式](../rust-dd/first-order-programs.md)、[語言與編譯器流水線](../rust-dd/compiler-pipelines.md) +概念:[自由單子](free_monad.md)、[延續傳遞風格](cps.md) +洞見:[EVM 代數](../insights/evm-alg.md) +``` + +```admonish note title="語義定位" +去函式化會改變表示,同時力求保留函式應用的行為。在語義優先設計中,當另一個直譯器需要在執行前檢查或組合操作時,生成的一階值就很有用。 +``` + +## 定義 {#definition} + +去函式化是一種程式變換:它將高階函式替換為表示可能函式集合的一階資料結構,並提供一個應用這些函式的直譯器函式。 + +## 動機 {#motivation} + +有些語言、編譯器或執行時無法高效處理高階函式,甚至完全不支援。透過去函式化,程式會變成純一階形式,因此更容易編譯、分析、序列化,或在受限環境中執行。 + +## 處理過程 {#the-process} + +1. 找出所有可能被建立並傳遞的高階函式。 +2. 為每個函式分配列舉或和型別中的唯一標籤,並附上它執行時所需的資料。 +3. 用這些標籤替換函式值。 +4. 定義一個`apply`函式,接收標籤與函式引數,然後按標籤進行模式匹配並執行相應程式碼。 + +## Rust 示例 {#example-in-rust} + +之前:使用閉包 + +```rust,noplayground +let k: Box i32> = Box::new(|x| x + 1); +println!("{}", k(41)); +``` + +之後:去函式化形式 + +```rust,noplayground +enum Cont { + Add1 +} + +fn apply(c: Cont, x: i32) -> i32 { + match c { + Cont::Add1 => x + 1, + } +} + +println!("{}", apply(Cont::Add1, 41)); +``` + +## 性質 {#properties} + +* 現在所有函式都由簡單資料表示。 +* 程式變為純一階形式。 +* `apply`函式取代直接的函式呼叫。 + +## 應用 {#applications} + +* 簡化編譯器後端:許多編譯器會生成 CPS 程式碼,然後對其去函式化。 +* 函式序列化:可以透過網路傳送列舉標籤,也可以將其存入檔案。 +* 靜態分析:一階程式碼更容易推理。 +* 推導直譯器:去函式化會自然引出直譯器模式。 + +## 與 CPS 的關係 {#relation-to-cps} + +在 CPS(延續傳遞風格)中,延續是高階函式。對 CPS 程式碼去函式化,會將這些延續轉換為列舉中的有限分支集合,並提供一個應用函式。 + +## 與自由單子的關係 {#relation-to-free-monads} + +適當的自由單子表示可以與 CPS 變換程式中的去函式化延續相關聯。這是一種緊密連結,但不意味著兩種構造普遍等同。 + +## 型別層面的應用 {#type-level-application} + +去函式化還可以在不原生支援高階型別的語言中編碼型別層面的應用。[C# 物件代數實驗](https://github.com/tgrospic/object-algebras)透過`App`運用這種輕量級編碼,以表達函子、適用函子、單子與效應代數。 + +## 參考文獻 {#references} + +* Reynolds, J. C.(1972)。*《高階程式語言的定義直譯器》*。 + [https://dl.acm.org/doi/epdf/10.1145/800194.805852](https://dl.acm.org/doi/epdf/10.1145/800194.805852) +* Yallop, J. 與 White, L.(2014)。*《輕量級高階型別多型》*(使用去函式化來編碼型別層面的應用)。 + [https://www.cl.cam.ac.uk/~jdy22/papers/lightweight-higher-kinded-polymorphism.pdf](https://www.cl.cam.ac.uk/~jdy22/papers/lightweight-higher-kinded-polymorphism.pdf) diff --git a/src/concepts/defunctionalization.zh.md b/src/concepts/defunctionalization.zh.md new file mode 100644 index 0000000..3bfdf02 --- /dev/null +++ b/src/concepts/defunctionalization.zh.md @@ -0,0 +1,85 @@ + + +# 去函数化 {#defunctionalization} + +```admonish tip title="相关内容" +Rust 中的语义驱动设计:[一阶程序](../rust-dd/first-order-programs.md)、[语言与编译器流水线](../rust-dd/compiler-pipelines.md) +概念:[自由单子](free_monad.md)、[延续传递风格](cps.md) +洞见:[EVM 代数](../insights/evm-alg.md) +``` + +```admonish note title="语义定位" +去函数化会改变表示,同时力求保留函数应用的行为。在语义优先设计中,当另一个解释器需要在执行前检查或组合操作时,生成的一阶值就很有用。 +``` + +## 定义 {#definition} + +去函数化是一种程序变换:它将高阶函数替换为表示可能函数集合的一阶数据结构,并提供一个应用这些函数的解释器函数。 + +## 动机 {#motivation} + +有些语言、编译器或运行时无法高效处理高阶函数,甚至完全不支持。通过去函数化,程序会变成纯一阶形式,因此更容易编译、分析、序列化,或在受限环境中运行。 + +## 处理过程 {#the-process} + +1. 找出所有可能被创建并传递的高阶函数。 +2. 为每个函数分配枚举或和类型中的唯一标签,并附上它运行时所需的数据。 +3. 用这些标签替换函数值。 +4. 定义一个`apply`函数,接收标签与函数参数,然后按标签进行模式匹配并运行相应代码。 + +## Rust 示例 {#example-in-rust} + +之前:使用闭包 + +```rust,noplayground +let k: Box i32> = Box::new(|x| x + 1); +println!("{}", k(41)); +``` + +之后:去函数化形式 + +```rust,noplayground +enum Cont { + Add1 +} + +fn apply(c: Cont, x: i32) -> i32 { + match c { + Cont::Add1 => x + 1, + } +} + +println!("{}", apply(Cont::Add1, 41)); +``` + +## 性质 {#properties} + +* 现在所有函数都由简单数据表示。 +* 程序变为纯一阶形式。 +* `apply`函数取代直接的函数调用。 + +## 应用 {#applications} + +* 简化编译器后端:许多编译器会生成 CPS 代码,然后对其去函数化。 +* 函数序列化:可以通过网络发送枚举标签,也可以将其存入文件。 +* 静态分析:一阶代码更容易推理。 +* 推导解释器:去函数化会自然引出解释器模式。 + +## 与 CPS 的关系 {#relation-to-cps} + +在 CPS(延续传递风格)中,延续是高阶函数。对 CPS 代码去函数化,会将这些延续转换为枚举中的有限分支集合,并提供一个应用函数。 + +## 与自由单子的关系 {#relation-to-free-monads} + +适当的自由单子表示可以与 CPS 变换程序中的去函数化延续相关联。这是一种紧密联系,但不意味着两种构造普遍等同。 + +## 类型层面的应用 {#type-level-application} + +去函数化还可以在不原生支持高阶类型的语言中编码类型层面的应用。[C# 对象代数实验](https://github.com/tgrospic/object-algebras)通过`App`运用这种轻量级编码,以表达函子、适用函子、单子与效应代数。 + +## 参考文献 {#references} + +* Reynolds, J. C.(1972)。*《高阶编程语言的定义解释器》*。 + [https://dl.acm.org/doi/epdf/10.1145/800194.805852](https://dl.acm.org/doi/epdf/10.1145/800194.805852) +* Yallop, J. 与 White, L.(2014)。*《轻量级高阶类型多态》*(使用去函数化来编码类型层面的应用)。 + [https://www.cl.cam.ac.uk/~jdy22/papers/lightweight-higher-kinded-polymorphism.pdf](https://www.cl.cam.ac.uk/~jdy22/papers/lightweight-higher-kinded-polymorphism.pdf) diff --git a/src/concepts/expression-problem.ar.md b/src/concepts/expression-problem.ar.md new file mode 100644 index 0000000..894dc13 --- /dev/null +++ b/src/concepts/expression-problem.ar.md @@ -0,0 +1,288 @@ + + +# مسألة التعبير {#expression-problem} + +```admonish tip title="ذات صلة" +الرؤية الدلالية: [التصميم الدلالي](../denotational-design/design.md)، [الدلالات والتركيبية](../denotational-design/denotations.md) +التصميم انطلاقًا من المعنى في Rust: [جبريات القدرات](../rust-dd/capability-algebras.md)، [المعنى المشتق والتركيب](../rust-dd/derived-meaning.md) +الرؤى: [إعادة طرح مسألة التعبير](../insights/expression-problem.md) +``` + +```admonish note title="الموضع الدلالي" +تتناول مسألة التعبير التوسيع المعياري للتمثيلات والعمليات. ويقدم التصميم الدلالي سؤالًا أسبق: أي مفردات وتفسيرات دلالية تستحق التمثيل أصلًا؟ +``` + +تتناول مسألة التعبير لدى فيل وادلر توسيع اللغة **بُعدين في آنٍ واحد** من دون تعديل الشيفرة القائمة: + +* **إضافة صيغ بيانات جديدة** (أشكال تعبير جديدة، أي «صياغة»). +* **إضافة عمليات جديدة** (تفسيرات جديدة، أي «دلالات»). + +موطن التوتر الأساسي: + +* في أسلوب **البرمجة الوظيفية/أنواع البيانات الجبرية**، يسهل إضافة عمليات جديدة، لكن إضافة صيغ جديدة تتطلب تعديلًا واسعًا. +* في الأسلوب **كائني التوجه**، يسهل إضافة صيغ جديدة، لكن إضافة عمليات جديدة تتطلب تعديلًا واسعًا. + +يعرض هذا القسم الجانبين بأمثلة صغيرة في Haskell وJava. + +## Haskell (البرمجة الوظيفية / أنواع البيانات الجبرية) {#haskell-functional--adt} + +نبدأ بنوع بيانات جبري كلاسيكي للتعبيرات وعملتين. + +```haskell +data Expr + = Lit Int + | Add Expr Expr + +eval :: Expr -> Int +eval (Lit n) = n +eval (Add a b) = eval a + eval b + +pretty :: Expr -> String +pretty (Lit n) = show n +pretty (Add a b) = "(" ++ pretty a ++ " + " ++ pretty b ++ ")" +``` + +من السهل الآن **إضافة عملية جديدة**: + +```haskell +size :: Expr -> Int +size (Lit _) = 1 +size (Add a b) = 1 + size a + size b +``` + +لكن **إضافة صيغة جديدة** (مثل `Mul`) تفرض تعديلات في كل دالة: + +```haskell +data Expr + = Lit Int + | Add Expr Expr + | Mul Expr Expr + +eval :: Expr -> Int +eval (Lit n) = n +eval (Add a b) = eval a + eval b +eval (Mul a b) = eval a * eval b -- ✏️ UPDATE: new case + +pretty :: Expr -> String +pretty (Lit n) = show n +pretty (Add a b) = "(" ++ pretty a ++ " + " ++ pretty b ++ ")" +pretty (Mul a b) = "(" ++ pretty a ++ " * " ++ pretty b ++ ")" -- ✏️ UPDATE: new case + +size :: Expr -> Int +size (Lit _) = 1 +size (Add a b) = 1 + size a + size b +size (Mul a b) = 1 + size a + size b -- ✏️ UPDATE: new case +``` + +بمصطلحات وادلر، **توسيع البيانات ليس معياريًا** في نهج أنواع البيانات الجبرية. + +## Java (كائنية التوجه) {#java-object-oriented} + +نبدأ بواجهة وفئات ملموسة لكل صيغة. + +```java +// Expression variants +interface Expr { + int eval(); + String pretty(); +} + +final class Lit implements Expr { + private final int n; + + Lit(int n) { + this.n = n; + } + + public int eval() { + return n; + } + + public String pretty() { + return Integer.toString(n); + } +} + +final class Add implements Expr { + private final Expr a; + private final Expr b; + + Add(Expr a, Expr b) { + this.a = a; + this.b = b; + } + + public int eval() { + return a.eval() + b.eval(); + } + + public String pretty() { + return "(" + a.pretty() + " + " + b.pretty() + ")"; + } +} +``` + +من السهل الآن **إضافة صيغة جديدة**: + +```java +final class Mul implements Expr { + private final Expr a; + private final Expr b; + + Mul(Expr a, Expr b) { + this.a = a; + this.b = b; + } + + public int eval() { + return a.eval() * b.eval(); + } + + public String pretty() { + return "(" + a.pretty() + " * " + b.pretty() + ")"; + } +} +``` + +لكن **إضافة عملية جديدة** (مثل `size`) تتطلب تعديلًا واسعًا. يجب تعديل الواجهة وكل فئة: + +```java +interface Expr { + int eval(); + String pretty(); + int size(); // ✏️ UPDATE: new operation added here +} + +final class Lit implements Expr { + private final int n; + + Lit(int n) { this.n = n; } + + public int eval() { return n; } + public String pretty() { return Integer.toString(n); } + public int size() { return 1; } // ✏️ UPDATE: new method in every class +} + +final class Add implements Expr { + private final Expr a; + private final Expr b; + + Add(Expr a, Expr b) { this.a = a; this.b = b; } + + public int eval() { return a.eval() + b.eval(); } + public String pretty() { return "(" + a.pretty() + " + " + b.pretty() + ")"; } + public int size() { return 1 + a.size() + b.size(); } // ✏️ UPDATE: new method in every class +} + +final class Mul implements Expr { + private final Expr a; + private final Expr b; + + Mul(Expr a, Expr b) { this.a = a; this.b = b; } + + public int eval() { return a.eval() * b.eval(); } + public String pretty() { return "(" + a.pretty() + " * " + b.pretty() + ")"; } + public int size() { return 1 + a.size() + b.size(); } // ✏️ UPDATE: new method in every class +} +``` + +بمصطلحات وادلر، **توسيع العمليات ليس معياريًا** في نهج البرمجة كائنية التوجه. + +## ملخص (فكرة وادلر) {#summary-wadlers-point} + +* يفضل أسلوب البرمجة الوظيفية/أنواع البيانات الجبرية **العمليات الجديدة** لكنه يقاوم **الصيغ الجديدة**. +* يفضل الأسلوب كائني التوجه **الصيغ الجديدة** لكنه يقاوم **العمليات الجديدة**. +* تسأل مسألة التعبير عن تصميم يمكن فيه توسيع **البعدين كليهما** من دون تعديل الشيفرة القائمة. + +## شرح وادلر ومشهد الحلول (1998) {#wadlers-explanation-and-solution-landscape-1998} + +يصوغ وادلر المشكلة هكذا: توسيع نوع بيانات **بإضافة حالات** (صيغ جديدة)، وتوسيع **دوال على ذلك النوع** (عمليات جديدة)، *من دون إعادة تجميع الشيفرة القائمة* مع الحفاظ على **سلامة الأنواع الساكنة** (من دون تحويلات نوعية). + +يستخدم استعارة «الجدول»: + +* **الصفوف** = الحالات (الصيغ / المُنشئات) +* **الأعمدة** = الدوال (العمليات / التفسيرات) + +في أساليب **البرمجة الوظيفية/أنواع البيانات الجبرية**، تكون الصفوف ثابتة ويسهل إضافة الأعمدة. +وفي أساليب **البرمجة كائنية التوجه**، تكون الأعمدة ثابتة ويسهل إضافة الصفوف. +والتحدي هو جعل **الاتجاهين كليهما** قابلين للتوسيع. + +## حل وادلر المقترح (GJ والأنواع الافتراضية) {#wadlers-proposed-solution-gj--virtual-types} + +يعرض وادلر حلًا في GJ (Java العامة) باستخدام: + +* معامل مقيّد بـ `This` (`This extends LangF`) لمحاكاة **ThisType**. +* **الفئات والواجهات الداخلية** المفهرسة بـ `This` (الأنواع الافتراضية). +* A visitor-based structure that allows: + * الحالات الجديدة (مثل `Plus`) عبر اشتقاق فئة «عائلة اللغة» + * العمليات الجديدة (مثل `Show`) عبر إضافة زوار جدد + +تتمثل الحيلة في الإشارة إلى `This.Exp` و`This.Visitor` بحيث تظل كل مرحلة توسعة آمنة الأنواع وقابلة للتجميع المستقل. + +### تنبيه (الواجهات الداخلية في Java) {#caveat-java-inner-interfaces} + +يلاحظ وادلر أن Java تتعامل مع الواجهات الداخلية بوصفها **ساكنة**، ما يفسد حيلة الفهرسة. +ويقترح أن تخفيف هذا القيد سيجعل الحل ممكنًا؛ لكن ذلك لم يتغير حتى في Java الحديثة (فالواجهات المتداخلة تظل ساكنة ضمنيًا). + +## اتجاهات حلول أخرى مذكورة {#other-solution-directions-mentioned} + +1. نهج كوركي كارترايت يتطلب **توسيعًا معاكسًا للتغاير**: السماح لنوع التعبير الأساسي بأن يحل محل نوع ممتد. وهذا يفسر استخدام النقاط الثابتة: فعائلة اللغة الممتدة *ليست* نوعًا فرعيًا من الأصلية. + +2. نهج كيم بروس يتطلب **مُنشئات أنواع من الرتبة الأعلى** (أي جعل نوع ما معاملًا لمنشئ نوع). لا يدعم GJ ذلك مباشرة، لكن وادلر يرى أن الأنواع الافتراضية يمكنها محاكاته. + +3. نهج كريشنامورثي وآخرين (نمط الزائر الممتد) يعمل عبر تصميم زائر ممتد. **ليس ذا أنواع ساكنة** في بيئتهم (Pizza)، لذا تلزم تحويلات نوعية ديناميكية. + +4. توسيعات لغوية مخصصة يذكر وادلر حلين يعتمدان على ميزات صُممت خصيصًا للمشكلة. وهما أقل عمومية من نهج الأنواع الافتراضية. + + +## نقطتا وادلر {#wadlers-two-points} + +توضح رسالة وادلر نقطتين: + +1. مسألة التعبير **توتر بنيوي** بين توسيع البيانات وتوسيع العمليات. +2. Solutions are possible, but they tend to require either: + * ميزات نظام الأنواع التي تحاكي **الأنواع الافتراضية**، أو + * توسيعات لغوية مخصصة، أو + * مساومة على سلامة الأنواع الساكنة أو التجميع المستقل. + +## حل Featherweight Go (2020) {#featherweight-go-solution-2020} + +صاغ وادلر المشكلة وسمّاها عام 1998. وقدمت Featherweight Go (FG) وامتدادها العام FGG (Featherweight Generic Go) لاحقًا حلًا ملموسًا ساكنًا بالكامل في لغة شبيهة بـ Go تستخدم الواجهات البنيوية والأنواع العامة. + +يتضمن حل الورقة (الشكل 8، بصورة مبسطة) بنيتين، `Num` و`Plus`، وعملتين، `Eval` و`String`: + +```go +type Evaler interface { Eval() int } +type Stringer interface { String() string } + +type Num struct { value int } +type Plus(type a Any) struct { left a; right a } + +func (e Num) Eval() int { return e.value } +func (e Plus(type a Evaler)) Eval() int { return e.left.Eval() + e.right.Eval() } + +func (e Num) String() string { return fmt.Sprintf("%d", e.value) } +func (e Plus(type a Stringer)) String() string { + return fmt.Sprintf("(%s+%s)", e.left.String(), e.right.String()) +} + +type Expr interface { Evaler; Stringer } + +var e Expr = Plus(Expr){Num{1}, Num{2}} +``` + +الآلية: + +* **تمثيل تكراري عام.** لأبناء `Plus` معامل نوع `a` لا يقيّده سوى `Any`. ولا ترتبط البنية بواجهة مغلقة تسرد كل العمليات، ما يتيح إضافة عمليات لاحقًا. +* **قيود خاصة بكل عملية.** يحدد إعلان كل أسلوب قيد `a` بصورة مستقلة: `Plus(type a Evaler)` لـ `Eval` و`Plus(type a Stringer)` لـ `String`. ويعتمد ذلك على *المستقبِلات المتغايرة* في FGG: فقد يكون قيد مستقبل الأسلوب أقوى من القيد في إعلان النوع. +* **واجهات بنيوية.** تنفذ البنية واجهة بامتلاك أساليبها؛ لذلك يمكن تقديم `Expr` بعد `Num` و`Plus` دون المساس بها. ولا تُحدد مجموعة العمليات كاملة إلا عند إنشاء قيمة (`Plus(Expr){...}`). + +الحالات الجديدة هي بنى جديدة؛ والعمليات الجديدة واجهات وأساليب جديدة. ولا يتطلب أي منهما تغيير الإعلانات القائمة أو إعادة تجميعها، ولا حاجة إلى تأكيدات الأنواع. + +## المراجع {#references} + +* وادلر، P. (1998). *The Expression Problem*. مذكرة في قائمة مراسلات Java-Genericity. صياغة المشكلة وتسميتها. + [https://homepages.inf.ed.ac.uk/wadler/papers/expression/expression.txt](https://homepages.inf.ed.ac.uk/wadler/papers/expression/expression.txt) + +* غريسمير، R.، هو، R.، كوكي، W.، لانغه، J.، تايلور، I. L.، تونينيو، B.، وادلر، P.، يوشيدا، N. (2020). *Featherweight Go*. Proc. ACM Program. Lang. 4 (OOPSLA). حل لغوي ملموس لاحق، القسم 2.3. + [https://homepages.inf.ed.ac.uk/wadler/papers/fg/fg.pdf](https://homepages.inf.ed.ac.uk/wadler/papers/fg/fg.pdf) diff --git a/src/concepts/expression-problem.de.md b/src/concepts/expression-problem.de.md new file mode 100644 index 0000000..b9a86e6 --- /dev/null +++ b/src/concepts/expression-problem.de.md @@ -0,0 +1,288 @@ + + +# Expression Problem {#expression-problem} + +```admonish tip title="Verwandte Themen" +The Semantic View: [Denotational Design](../denotational-design/design.md), [Denotationen und Kompositionalität](../denotational-design/denotations.md) +Design by Meaning in Rust: [Capability-Algebren](../rust-dd/capability-algebras.md), [Abgeleitete Bedeutung und Komposition](../rust-dd/derived-meaning.md) +Insights: [Expression Problem reloaded](../insights/expression-problem.md) +``` + +```admonish note title="Semantische Einordnung" +Das Expression Problem betrifft die modulare Erweiterung von Repräsentationen und Operationen. Denotational Design setzt eine Frage früher an: Welches semantische Vokabular und welche Interpretationen sollten überhaupt repräsentiert werden? +``` + +Phil Wadlers Expression Problem betrifft die **gleichzeitige** Erweiterung einer Sprache in zwei Dimensionen, ohne bestehenden Code zu ändern: + +* **Neue Datenvarianten hinzufügen** (neue Ausdrucksformen, auch „Syntax“ genannt). +* **Neue Operationen hinzufügen** (neue Interpretationen, auch „Semantik“ genannt). + +Der grundlegende Zielkonflikt: + +* Im **funktionalen/ADT**\-Stil lassen sich neue Operationen leicht, neue Varianten dagegen nur mit Eingriffen ergänzen. +* Im **objektorientierten** Stil lassen sich neue Varianten leicht, neue Operationen dagegen nur mit Eingriffen ergänzen. + +Dieser Abschnitt zeigt beide Seiten anhand kleiner Beispiele in Haskell und Java. + +## Haskell (funktional / ADT) {#haskell-functional--adt} + +Wir beginnen mit einem klassischen ADT für Ausdrücke und zwei Operationen. + +```haskell +data Expr + = Lit Int + | Add Expr Expr + +eval :: Expr -> Int +eval (Lit n) = n +eval (Add a b) = eval a + eval b + +pretty :: Expr -> String +pretty (Lit n) = show n +pretty (Add a b) = "(" ++ pretty a ++ " + " ++ pretty b ++ ")" +``` + +Nun ist es einfach, **eine neue Operation hinzuzufügen**: + +```haskell +size :: Expr -> Int +size (Lit _) = 1 +size (Add a b) = 1 + size a + size b +``` + +Das **Hinzufügen einer neuen Variante** (z. B. `Mul`) erfordert dagegen Änderungen an jeder Funktion: + +```haskell +data Expr + = Lit Int + | Add Expr Expr + | Mul Expr Expr + +eval :: Expr -> Int +eval (Lit n) = n +eval (Add a b) = eval a + eval b +eval (Mul a b) = eval a * eval b -- ✏️ UPDATE: new case + +pretty :: Expr -> String +pretty (Lit n) = show n +pretty (Add a b) = "(" ++ pretty a ++ " + " ++ pretty b ++ ")" +pretty (Mul a b) = "(" ++ pretty a ++ " * " ++ pretty b ++ ")" -- ✏️ UPDATE: new case + +size :: Expr -> Int +size (Lit _) = 1 +size (Add a b) = 1 + size a + size b +size (Mul a b) = 1 + size a + size b -- ✏️ UPDATE: new case +``` + +Mit Wadlers Worten ist **die Erweiterung der Datentypen** im ADT-Ansatz nicht modular. + +## Java (objektorientiert) {#java-object-oriented} + +Wir beginnen mit einer Schnittstelle und konkreten Klassen für jede Variante. + +```java +// Expression variants +interface Expr { + int eval(); + String pretty(); +} + +final class Lit implements Expr { + private final int n; + + Lit(int n) { + this.n = n; + } + + public int eval() { + return n; + } + + public String pretty() { + return Integer.toString(n); + } +} + +final class Add implements Expr { + private final Expr a; + private final Expr b; + + Add(Expr a, Expr b) { + this.a = a; + this.b = b; + } + + public int eval() { + return a.eval() + b.eval(); + } + + public String pretty() { + return "(" + a.pretty() + " + " + b.pretty() + ")"; + } +} +``` + +Nun lässt sich **eine neue Variante hinzufügen**: + +```java +final class Mul implements Expr { + private final Expr a; + private final Expr b; + + Mul(Expr a, Expr b) { + this.a = a; + this.b = b; + } + + public int eval() { + return a.eval() * b.eval(); + } + + public String pretty() { + return "(" + a.pretty() + " * " + b.pretty() + ")"; + } +} +``` + +Das **Hinzufügen einer neuen Operation** (z. B. `size`) greift dagegen tief ein. Die Schnittstelle und jede Klasse müssen geändert werden: + +```java +interface Expr { + int eval(); + String pretty(); + int size(); // ✏️ UPDATE: new operation added here +} + +final class Lit implements Expr { + private final int n; + + Lit(int n) { this.n = n; } + + public int eval() { return n; } + public String pretty() { return Integer.toString(n); } + public int size() { return 1; } // ✏️ UPDATE: new method in every class +} + +final class Add implements Expr { + private final Expr a; + private final Expr b; + + Add(Expr a, Expr b) { this.a = a; this.b = b; } + + public int eval() { return a.eval() + b.eval(); } + public String pretty() { return "(" + a.pretty() + " + " + b.pretty() + ")"; } + public int size() { return 1 + a.size() + b.size(); } // ✏️ UPDATE: new method in every class +} + +final class Mul implements Expr { + private final Expr a; + private final Expr b; + + Mul(Expr a, Expr b) { this.a = a; this.b = b; } + + public int eval() { return a.eval() * b.eval(); } + public String pretty() { return "(" + a.pretty() + " * " + b.pretty() + ")"; } + public int size() { return 1 + a.size() + b.size(); } // ✏️ UPDATE: new method in every class +} +``` + +Mit Wadlers Worten ist **die Operationserweiterung** im OO-Ansatz nicht modular. + +## Zusammenfassung (Wadlers Aussage) {#summary-wadlers-point} + +* Der funktionale/ADT-Stil begünstigt **neue Operationen**, erschwert aber **neue Varianten**. +* Der OO-Stil begünstigt **neue Varianten**, erschwert aber **neue Operationen**. +* Das Expression Problem sucht einen Entwurf, in dem **beide** Dimensionen ohne Änderung des bestehenden Codes erweiterbar sind. + +## Wadlers Erklärung und Lösungsansätze (1998) {#wadlers-explanation-and-solution-landscape-1998} + +Wadler formuliert das Problem so: Einen Datentyp **um Fälle** (neue Varianten) und **Funktionen über diesen Datentyp** (neue Operationen) erweitern, *ohne bestehenden Code neu zu kompilieren* und dabei **statische Typsicherheit** (ohne Casts) bewahren. + +Er verwendet die Metapher einer „Tabelle“: + +* **Zeilen** = Fälle (Varianten / Konstruktoren) +* **Spalten** = Funktionen (Operationen / Interpretationen) + +In **funktionalen/ADT**\-Umgebungen sind die Zeilen festgelegt und neue Spalten lassen sich leicht ergänzen. +In **OO**\-Umgebungen sind die Spalten festgelegt und neue Zeilen lassen sich leicht ergänzen. +Die Herausforderung besteht darin, **beide Richtungen** erweiterbar zu machen. + +## Wadlers vorgeschlagene Lösung (GJ + virtuelle Typen) {#wadlers-proposed-solution-gj--virtual-types} + +Wadler stellt eine Lösung in GJ (Generic Java) vor, die Folgendes verwendet: + +* Einen an `This` gebundenen Parameter (`This extends LangF`), um **ThisType** zu simulieren. +* **Innere Klassen und Schnittstellen**, indiziert durch `This` (virtuelle Typen). +* A visitor-based structure that allows: + * Neue Fälle (z. B. `Plus`) durch Unterklassen der „Sprachfamilie“ + * Neue Operationen (z. B. `Show`) durch Hinzufügen neuer Visitor + +Der Trick besteht darin, auf `This.Exp` und `This.Visitor` zu verweisen, sodass jede Erweiterungsphase typsicher und unabhängig kompilierbar bleibt. + +### Einschränkung (innere Java-Schnittstellen) {#caveat-java-inner-interfaces} + +Wadler merkt an, dass Java innere Schnittstellen als **statisch** behandelt, wodurch der Indizierungstrick nicht funktioniert. +Er schlägt vor, diese Einschränkung zu lockern, um die Lösung praktikabel zu machen; auch im modernen Java hat sich daran nichts geändert (verschachtelte Schnittstellen bleiben implizit statisch). + +## Weitere erwähnte Lösungsansätze {#other-solution-directions-mentioned} + +1. Corky Cartwrights Ansatz Erfordert **kontravariante Erweiterung**: Ein Basisausdrucktyp muss für einen erweiterten Typ stehen dürfen. Das erklärt, warum Fixpunkte verwendet werden: Die erweiterte Sprachfamilie ist *kein* Untertyp der ursprünglichen. + +2. Kim Bruces Ansatz Erfordert **Typkonstruktoren höherer Ordnung** (einen Typ über einen Typkonstruktor zu parametrisieren). GJ unterstützt dies nicht direkt, doch Wadler zufolge können virtuelle Typen es simulieren. + +3. Krishnamurthi et al. (erweitertes Visitor-Muster) Basiert auf einem erweiterten Visitor-Entwurf. In ihrem Umfeld (Pizza) ist es **nicht statisch typisiert**, daher sind dynamische Casts erforderlich. + +4. Sprachspezifische Erweiterungen Wadler nennt zwei Lösungen, die eigens für das Problem entwickelte Sprachfunktionen voraussetzen. Sie sind weniger allgemein als der Ansatz mit virtuellen Typen. + + +## Wadlers zwei Aussagen {#wadlers-two-points} + +Wadlers E-Mail macht zwei Punkte deutlich: + +1. Das Expression Problem ist ein **struktureller Zielkonflikt** zwischen Daten- und Operationserweiterung. +2. Solutions are possible, but they tend to require either: + * Funktionen des Typsystems, die **virtuelle Typen** simulieren, oder + * sprachspezifische Erweiterungen, oder + * ein Kompromiss bei statischer Typsicherheit oder unabhängiger Kompilierung. + +## Featherweight-Go-Lösung (2020) {#featherweight-go-solution-2020} + +Wadler formuliert und benennt das Problem 1998. Featherweight Go (FG) und seine generische Erweiterung FGG (Featherweight Generic Go) liefern später eine konkrete, vollständig statische Lösung in einer Go-ähnlichen Sprache mit strukturellen Schnittstellen und Generics. + +Die Lösung des Artikels (Abb. 8, vereinfacht) umfasst zwei Strukturen, `Num` und `Plus`, sowie zwei Operationen, `Eval` und `String`: + +```go +type Evaler interface { Eval() int } +type Stringer interface { String() string } + +type Num struct { value int } +type Plus(type a Any) struct { left a; right a } + +func (e Num) Eval() int { return e.value } +func (e Plus(type a Evaler)) Eval() int { return e.left.Eval() + e.right.Eval() } + +func (e Num) String() string { return fmt.Sprintf("%d", e.value) } +func (e Plus(type a Stringer)) String() string { + return fmt.Sprintf("(%s+%s)", e.left.String(), e.right.String()) +} + +type Expr interface { Evaler; Stringer } + +var e Expr = Plus(Expr){Num{1}, Num{2}} +``` + +Der Mechanismus: + +* **Generische rekursive Repräsentation.** Die Kinder von `Plus` haben einen Typparameter `a`, der nur an `Any` gebunden ist. Die Struktur ist nicht an eine geschlossene Schnittstelle gebunden, die jede Operation aufführt, sodass spätere Operationen möglich bleiben. +* **Operationsspezifische Einschränkungen.** Jede Methodendeklaration beschränkt `a` unabhängig: `Plus(type a Evaler)` für `Eval`, `Plus(type a Stringer)` für `String`. Dies beruht auf *kovarianten Receivern* in FGG: Der Receiver-Bound einer Methode darf stärker sein als der Bound in der Typdeklaration. +* **Strukturelle Schnittstellen.** Eine Struktur implementiert eine Schnittstelle, indem sie deren Methoden besitzt. So kann `Expr` nach `Num` und `Plus` eingeführt werden, ohne diese zu ändern. Die vollständige Operationsmenge wird erst beim Aufbau eines Werts festgelegt (`Plus(Expr){...}`). + +Neue Fälle sind neue Strukturen; neue Operationen sind neue Schnittstellen und Methoden. Beides erfordert weder Änderung noch Neukompilierung bestehender Deklarationen, und Typzusicherungen sind nicht nötig. + +## Quellen {#references} + +* Wadler, P. (1998). *The Expression Problem*. Notiz auf der Mailingliste Java-Genericity. Formulierung und Benennung des Problems. + [https://homepages.inf.ed.ac.uk/wadler/papers/expression/expression.txt](https://homepages.inf.ed.ac.uk/wadler/papers/expression/expression.txt) + +* Griesemer, R., Hu, R., Kokke, W., Lange, J., Taylor, I. L., Toninho, B., Wadler, P. und Yoshida, N. (2020). *Featherweight Go*. Proc. ACM Program. Lang. 4 (OOPSLA). Eine spätere konkrete Lösung für die Sprache, Abschnitt 2.3. + [https://homepages.inf.ed.ac.uk/wadler/papers/fg/fg.pdf](https://homepages.inf.ed.ac.uk/wadler/papers/fg/fg.pdf) diff --git a/src/concepts/expression-problem.es.md b/src/concepts/expression-problem.es.md new file mode 100644 index 0000000..2826cfa --- /dev/null +++ b/src/concepts/expression-problem.es.md @@ -0,0 +1,288 @@ + + +# Problema de expresiones {#expression-problem} + +```admonish tip title="Relacionado" +La perspectiva semántica: [Diseño denotacional](../denotational-design/design.md), [Denotaciones y composicionalidad](../denotational-design/denotations.md) +Diseño basado en el significado en Rust: [Álgebras de capacidades](../rust-dd/capability-algebras.md), [Significado derivado y composición](../rust-dd/derived-meaning.md) +Perspectivas: [El problema de expresiones, reexaminado](../insights/expression-problem.md) +``` + +```admonish note title="Ubicación semántica" +El problema de expresiones trata de la extensión modular de representaciones y operaciones. El diseño denotacional adelanta una pregunta: ¿qué vocabulario semántico e interpretaciones merece la pena representar? +``` + +El problema de expresiones de Phil Wadler trata de extender **simultáneamente** un lenguaje en dos dimensiones sin modificar el código existente: + +* **Añadir nuevas variantes de datos** (nuevas formas de expresión, también llamadas «sintaxis»). +* **Añadir nuevas operaciones** (nuevas interpretaciones, también llamadas «semántica»). + +La tensión central: + +* Con el estilo **funcional/ADT**, es fácil añadir operaciones, pero añadir variantes resulta invasivo. +* Con el estilo **orientado a objetos**, es fácil añadir variantes, pero añadir operaciones resulta invasivo. + +Esta sección muestra ambos enfoques con ejemplos breves en Haskell y Java. + +## Haskell (funcional / ADT) {#haskell-functional--adt} + +Empezamos con un ADT clásico de expresiones y dos operaciones. + +```haskell +data Expr + = Lit Int + | Add Expr Expr + +eval :: Expr -> Int +eval (Lit n) = n +eval (Add a b) = eval a + eval b + +pretty :: Expr -> String +pretty (Lit n) = show n +pretty (Add a b) = "(" ++ pretty a ++ " + " ++ pretty b ++ ")" +``` + +Ahora es fácil **añadir una operación**: + +```haskell +size :: Expr -> Int +size (Lit _) = 1 +size (Add a b) = 1 + size a + size b +``` + +Pero **añadir una variante** (por ejemplo, `Mul`) obliga a editar todas las funciones: + +```haskell +data Expr + = Lit Int + | Add Expr Expr + | Mul Expr Expr + +eval :: Expr -> Int +eval (Lit n) = n +eval (Add a b) = eval a + eval b +eval (Mul a b) = eval a * eval b -- ✏️ UPDATE: new case + +pretty :: Expr -> String +pretty (Lit n) = show n +pretty (Add a b) = "(" ++ pretty a ++ " + " ++ pretty b ++ ")" +pretty (Mul a b) = "(" ++ pretty a ++ " * " ++ pretty b ++ ")" -- ✏️ UPDATE: new case + +size :: Expr -> Int +size (Lit _) = 1 +size (Add a b) = 1 + size a + size b +size (Mul a b) = 1 + size a + size b -- ✏️ UPDATE: new case +``` + +En palabras de Wadler, en el enfoque ADT **la extensión de datos no es modular**. + +## Java (orientado a objetos) {#java-object-oriented} + +Empezamos con una interfaz y clases concretas para cada variante. + +```java +// Expression variants +interface Expr { + int eval(); + String pretty(); +} + +final class Lit implements Expr { + private final int n; + + Lit(int n) { + this.n = n; + } + + public int eval() { + return n; + } + + public String pretty() { + return Integer.toString(n); + } +} + +final class Add implements Expr { + private final Expr a; + private final Expr b; + + Add(Expr a, Expr b) { + this.a = a; + this.b = b; + } + + public int eval() { + return a.eval() + b.eval(); + } + + public String pretty() { + return "(" + a.pretty() + " + " + b.pretty() + ")"; + } +} +``` + +Ahora es fácil **añadir una variante**: + +```java +final class Mul implements Expr { + private final Expr a; + private final Expr b; + + Mul(Expr a, Expr b) { + this.a = a; + this.b = b; + } + + public int eval() { + return a.eval() * b.eval(); + } + + public String pretty() { + return "(" + a.pretty() + " * " + b.pretty() + ")"; + } +} +``` + +Pero **añadir una operación** (por ejemplo, `size`) resulta invasivo. Hay que editar la interfaz y todas las clases: + +```java +interface Expr { + int eval(); + String pretty(); + int size(); // ✏️ UPDATE: new operation added here +} + +final class Lit implements Expr { + private final int n; + + Lit(int n) { this.n = n; } + + public int eval() { return n; } + public String pretty() { return Integer.toString(n); } + public int size() { return 1; } // ✏️ UPDATE: new method in every class +} + +final class Add implements Expr { + private final Expr a; + private final Expr b; + + Add(Expr a, Expr b) { this.a = a; this.b = b; } + + public int eval() { return a.eval() + b.eval(); } + public String pretty() { return "(" + a.pretty() + " + " + b.pretty() + ")"; } + public int size() { return 1 + a.size() + b.size(); } // ✏️ UPDATE: new method in every class +} + +final class Mul implements Expr { + private final Expr a; + private final Expr b; + + Mul(Expr a, Expr b) { this.a = a; this.b = b; } + + public int eval() { return a.eval() * b.eval(); } + public String pretty() { return "(" + a.pretty() + " * " + b.pretty() + ")"; } + public int size() { return 1 + a.size() + b.size(); } // ✏️ UPDATE: new method in every class +} +``` + +En palabras de Wadler, en el enfoque OO **la extensión de operaciones no es modular**. + +## Resumen (la idea de Wadler) {#summary-wadlers-point} + +* El estilo funcional/ADT favorece **las operaciones nuevas**, pero dificulta **las variantes nuevas**. +* El estilo OO favorece **las variantes nuevas**, pero dificulta **las operaciones nuevas**. +* El problema de expresiones busca un diseño en el que **ambas** dimensiones puedan ampliarse sin modificar el código existente. + +## La explicación y las propuestas de solución de Wadler (1998) {#wadlers-explanation-and-solution-landscape-1998} + +Wadler formula el problema así: extender un tipo de datos **por casos** (variantes nuevas) y ampliar las **funciones que operan sobre ese tipo** (operaciones nuevas), *sin recompilar el código existente* y preservando la **seguridad de tipos estática** (sin conversiones de tipo). + +Usa la metáfora de una «tabla»: + +* **Filas** = casos (variantes / constructores) +* **Columnas** = funciones (operaciones / interpretaciones) + +En entornos **funcionales/ADT**, las filas son fijas y resulta fácil añadir columnas. +En entornos **OO**, las columnas son fijas y resulta fácil añadir filas. +El reto consiste en permitir extensiones en **ambas direcciones**. + +## La solución propuesta por Wadler (GJ y tipos virtuales) {#wadlers-proposed-solution-gj--virtual-types} + +Wadler presenta una solución en GJ (Generic Java) que utiliza: + +* Un parámetro acotado por `This` (`This extends LangF`) para simular **ThisType**. +* **Clases e interfaces internas** indexadas por `This` (tipos virtuales). +* A visitor-based structure that allows: + * Casos nuevos (por ejemplo, `Plus`) mediante subclases de la «familia de lenguajes». + * Operaciones nuevas (por ejemplo, `Show`) mediante la incorporación de visitantes nuevos. + +El truco consiste en referirse a `This.Exp` y `This.Visitor` para que cada fase de extensión conserve la seguridad de tipos y pueda compilarse de forma independiente. + +### Advertencia (interfaces internas de Java) {#caveat-java-inner-interfaces} + +Wadler señala que Java trata las interfaces internas como **static**, lo que rompe el mecanismo de indexación. +Sugiere que relajar esta restricción haría viable la solución; la situación no ha cambiado en las versiones modernas de Java (las interfaces anidadas siguen siendo implícitamente estáticas). + +## Otras líneas de solución mencionadas {#other-solution-directions-mentioned} + +1. El enfoque de Corky Cartwright Exige una **extensión contravariante**: permitir que un tipo base de expresión represente uno extendido. Esto explica el uso de puntos fijos: la familia de lenguajes extendida *no* es un subtipo de la original. + +2. El enfoque de Kim Bruce Exige **constructores de tipos de orden superior** (parametrizar un tipo con un constructor de tipos). GJ no lo admite directamente, pero Wadler sostiene que los tipos virtuales pueden simularlo. + +3. Krishnamurthi et al. (patrón Visitor extendido) Funciona mediante un diseño de visitante extendido. En su entorno (Pizza) **no tiene tipado estático**, por lo que se requieren conversiones de tipo dinámicas. + +4. Extensiones de lenguaje específicas Wadler cita dos soluciones que dependen de características del lenguaje diseñadas específicamente para este problema. Son menos generales que el enfoque de tipos virtuales. + + +## Las dos ideas de Wadler {#wadlers-two-points} + +El correo de Wadler deja claras dos ideas: + +1. El problema de expresiones es una **tensión estructural** entre extender los datos y extender las operaciones. +2. Solutions are possible, but they tend to require either: + * Características del sistema de tipos que simulan **tipos virtuales**, o + * Extensiones de lenguaje específicas, o + * Un compromiso en la seguridad de tipos estática o en la compilación independiente. + +## Solución con Featherweight Go (2020) {#featherweight-go-solution-2020} + +Wadler formuló y nombró el problema en 1998. Más adelante, Featherweight Go (FG) y su extensión genérica FGG (Featherweight Generic Go) ofrecieron una solución concreta y totalmente estática en un lenguaje similar a Go, con interfaces estructurales y genéricos. + +La solución del artículo (figura 8, simplificada) tiene dos estructuras, `Num` y `Plus`, y dos operaciones, `Eval` y `String`: + +```go +type Evaler interface { Eval() int } +type Stringer interface { String() string } + +type Num struct { value int } +type Plus(type a Any) struct { left a; right a } + +func (e Num) Eval() int { return e.value } +func (e Plus(type a Evaler)) Eval() int { return e.left.Eval() + e.right.Eval() } + +func (e Num) String() string { return fmt.Sprintf("%d", e.value) } +func (e Plus(type a Stringer)) String() string { + return fmt.Sprintf("(%s+%s)", e.left.String(), e.right.String()) +} + +type Expr interface { Evaler; Stringer } + +var e Expr = Plus(Expr){Num{1}, Num{2}} +``` + +El mecanismo: + +* **Representación recursiva genérica.** Los elementos hijos de `Plus` tienen un parámetro de tipo `a` acotado únicamente por `Any`. La estructura no está ligada a una interfaz cerrada que enumere todas las operaciones, por lo que siguen siendo posibles las operaciones futuras. +* **Restricciones específicas de cada operación.** La declaración de cada método acota `a` de manera independiente: `Plus(type a Evaler)` para `Eval`, `Plus(type a Stringer)` para `String`. Esto depende de los *receptores covariantes* de FGG: la restricción del receptor de un método puede ser más fuerte que la restricción de la declaración del tipo. +* **Interfaces estructurales.** Una estructura implementa una interfaz si cuenta con sus métodos; así, `Expr` puede introducirse después de `Num` y `Plus` sin modificarlos. El conjunto completo de operaciones solo se fija al construir un valor (`Plus(Expr){...}`). + +Los casos nuevos son estructuras nuevas; las operaciones nuevas son interfaces y métodos nuevos. Ninguna de las dos extensiones exige cambiar o recompilar las declaraciones existentes, y no se necesitan aserciones de tipo. + +## Referencias {#references} + +* Wadler, P. (1998). *The Expression Problem*. Nota de la lista de correo Java-Genericity. Formulación y nombre del problema. + [https://homepages.inf.ed.ac.uk/wadler/papers/expression/expression.txt](https://homepages.inf.ed.ac.uk/wadler/papers/expression/expression.txt) + +* Griesemer, R., Hu, R., Kokke, W., Lange, J., Taylor, I. L., Toninho, B., Wadler, P. y Yoshida, N. (2020). *Featherweight Go*. Proc. ACM Program. Lang. 4 (OOPSLA). Una solución concreta posterior al problema, sección 2.3. + [https://homepages.inf.ed.ac.uk/wadler/papers/fg/fg.pdf](https://homepages.inf.ed.ac.uk/wadler/papers/fg/fg.pdf) diff --git a/src/concepts/expression-problem.ja.md b/src/concepts/expression-problem.ja.md new file mode 100644 index 0000000..34a68dd --- /dev/null +++ b/src/concepts/expression-problem.ja.md @@ -0,0 +1,288 @@ + + +# 式問題 {#expression-problem} + +```admonish tip title="関連項目" +意味論的な見方:[Denotational Design](../denotational-design/design.md)、[表示と合成性](../denotational-design/denotations.md) +Rustで意味から設計する:[ケイパビリティ代数](../rust-dd/capability-algebras.md)、[導出される意味と合成](../rust-dd/derived-meaning.md) +洞察:[Expression Problem再考](../insights/expression-problem.md) +``` + +```admonish note title="意味論上の位置付け" +Expression Problemは、表現と操作をモジュール式に拡張する問題です。Denotational Designは一つ手前の問いを立てます。そもそも、どの意味論上の語彙と解釈に表現する価値があるでしょうか。 +``` + +Phil Wadlerのexpression problemは、既存コードを変更せずに言語を二つの軸で**同時に**拡張することを扱います。 + +* **新しいデータのバリアント**(新しい式形式、すなわち「構文」)を追加する。 +* **新しい操作**(新しい解釈、すなわち「意味論」)を追加する。 + +中核となる緊張関係: + +* **関数型/ADT**のスタイルでは、新しい操作を追加しやすい一方、新しいバリアントを追加すると広範な変更が必要です。 +* **オブジェクト指向**のスタイルでは、新しいバリアントを追加しやすい一方、新しい操作を追加すると広範な変更が必要です。 + +この節では、HaskellとJavaの短い例で両面を示します。 + +## Haskell(関数型/ADT) {#haskell-functional--adt} + +式と二つの操作を定義する、典型的なADTから始めます。 + +```haskell +data Expr + = Lit Int + | Add Expr Expr + +eval :: Expr -> Int +eval (Lit n) = n +eval (Add a b) = eval a + eval b + +pretty :: Expr -> String +pretty (Lit n) = show n +pretty (Add a b) = "(" ++ pretty a ++ " + " ++ pretty b ++ ")" +``` + +ここでは、**新しい操作を追加する**のは簡単です。 + +```haskell +size :: Expr -> Int +size (Lit _) = 1 +size (Add a b) = 1 + size a + size b +``` + +しかし、**新しいバリアント**(例:`Mul`)を追加すると、すべての関数を変更する必要があります。 + +```haskell +data Expr + = Lit Int + | Add Expr Expr + | Mul Expr Expr + +eval :: Expr -> Int +eval (Lit n) = n +eval (Add a b) = eval a + eval b +eval (Mul a b) = eval a * eval b -- ✏️ UPDATE: new case + +pretty :: Expr -> String +pretty (Lit n) = show n +pretty (Add a b) = "(" ++ pretty a ++ " + " ++ pretty b ++ ")" +pretty (Mul a b) = "(" ++ pretty a ++ " * " ++ pretty b ++ ")" -- ✏️ UPDATE: new case + +size :: Expr -> Int +size (Lit _) = 1 +size (Add a b) = 1 + size a + size b +size (Mul a b) = 1 + size a + size b -- ✏️ UPDATE: new case +``` + +Wadlerの言葉では、ADT方式では**データの拡張がモジュール式ではない**のです。 + +## Java(オブジェクト指向) {#java-object-oriented} + +各バリアントのインターフェースと具体クラスから始めます。 + +```java +// Expression variants +interface Expr { + int eval(); + String pretty(); +} + +final class Lit implements Expr { + private final int n; + + Lit(int n) { + this.n = n; + } + + public int eval() { + return n; + } + + public String pretty() { + return Integer.toString(n); + } +} + +final class Add implements Expr { + private final Expr a; + private final Expr b; + + Add(Expr a, Expr b) { + this.a = a; + this.b = b; + } + + public int eval() { + return a.eval() + b.eval(); + } + + public String pretty() { + return "(" + a.pretty() + " + " + b.pretty() + ")"; + } +} +``` + +ここでは、**新しいバリアントを追加する**のは簡単です。 + +```java +final class Mul implements Expr { + private final Expr a; + private final Expr b; + + Mul(Expr a, Expr b) { + this.a = a; + this.b = b; + } + + public int eval() { + return a.eval() * b.eval(); + } + + public String pretty() { + return "(" + a.pretty() + " * " + b.pretty() + ")"; + } +} +``` + +しかし、**新しい操作**(例:`size`)の追加には広範な変更が必要です。インターフェースとすべてのクラスを変更しなければなりません。 + +```java +interface Expr { + int eval(); + String pretty(); + int size(); // ✏️ UPDATE: new operation added here +} + +final class Lit implements Expr { + private final int n; + + Lit(int n) { this.n = n; } + + public int eval() { return n; } + public String pretty() { return Integer.toString(n); } + public int size() { return 1; } // ✏️ UPDATE: new method in every class +} + +final class Add implements Expr { + private final Expr a; + private final Expr b; + + Add(Expr a, Expr b) { this.a = a; this.b = b; } + + public int eval() { return a.eval() + b.eval(); } + public String pretty() { return "(" + a.pretty() + " + " + b.pretty() + ")"; } + public int size() { return 1 + a.size() + b.size(); } // ✏️ UPDATE: new method in every class +} + +final class Mul implements Expr { + private final Expr a; + private final Expr b; + + Mul(Expr a, Expr b) { this.a = a; this.b = b; } + + public int eval() { return a.eval() * b.eval(); } + public String pretty() { return "(" + a.pretty() + " * " + b.pretty() + ")"; } + public int size() { return 1 + a.size() + b.size(); } // ✏️ UPDATE: new method in every class +} +``` + +Wadlerの言葉では、OO方式では**操作の拡張がモジュール式ではない**のです。 + +## まとめ(Wadlerの指摘) {#summary-wadlers-point} + +* 関数型/ADT方式は、**新しい操作**を追加しやすい一方、**新しいバリアント**を追加しにくい。 +* OO方式は、**新しいバリアント**を追加しやすい一方、**新しい操作**を追加しにくい。 +* expression problemが求めるのは、既存コードを変更せずに**両方**の軸を拡張できる設計です。 + +## Wadlerによる説明と解決策の概要(1998) {#wadlers-explanation-and-solution-landscape-1998} + +Wadlerはこの問題を、データ型の**ケースの追加**(新しいバリアント)と、そのデータ型を処理する**関数の拡張**(新しい操作)を、*既存コードを再コンパイルせず*、**静的な型安全性**(キャストなし)を保ちながら行うことと定義しています。 + +「表」のたとえを使います。 + +* **行**=ケース(バリアント/コンストラクター) +* **列**=関数(操作/解釈) + +**関数型/ADT**の環境では、行が固定され、列を簡単に追加できます。 +**OO**の環境では、列が固定され、行を簡単に追加できます。 +課題は、**両方向**を拡張可能にすることです。 + +## Wadlerの提案した解決策(GJ+virtual types) {#wadlers-proposed-solution-gj--virtual-types} + +WadlerはGeneric Java(GJ)を使う解決策を提示しています。そこでは次のものを使います。 + +* `This`境界付きパラメーター(`This extends LangF`)によって**ThisType**を模倣する。 +* **内部クラスとインターフェース**は、`This`(virtual types)で添字付けされます。 +* A visitor-based structure that allows: + * 「言語ファミリー」をサブクラス化して新しいケース(例:`Plus`)を追加する。 + * 新しいビジターを追加して新しい操作(例:`Show`)を加える。 + +各拡張段階で型安全性と個別コンパイルを保つには、`This.Exp`と`This.Visitor`を参照する方法が要点です。 + +### 注意点(Javaの内部インターフェース) {#caveat-java-inner-interfaces} + +Wadlerは、Javaでは内部インターフェースが**static**として扱われ、添字付けの仕組みが崩れると指摘します。 +この制限を緩めれば解決策は実用可能になると提案していますが、現在のJavaでも変わっていません(ネストしたインターフェースは暗黙にstaticです)。 + +## 挙げられているほかの解決方針 {#other-solution-directions-mentioned} + +1. Corky Cartwrightの方法 **反変な拡張**が必要です。基底の式型を拡張後の型の代わりに使えるようにします。 拡張された言語ファミリーが元の言語のサブタイプ*ではない*ため、ここで不動点を使う理由を説明できます。 + +2. Kim Bruceの方法 **高階型コンストラクター**(型コンストラクターを受け取る型パラメーター)が必要です。 GJはこれを直接サポートしませんが、Wadlerはvirtual typesで模倣できると論じています。 + +3. Krishnamurthiら(拡張ビジターパターン) 拡張ビジター設計によって実現します。 彼らの環境(Pizza)では**静的に型付けされない**ため、動的キャストが必要です。 + +4. 特別目的の言語拡張 Wadlerは、この問題専用に設計された言語機能に依存する二つの解決策を挙げています。 virtual typesによる方法ほど一般的ではありません。 + + +## Wadlerの二つの指摘 {#wadlers-two-points} + +Wadlerのメールからは、二つの要点が明確に分かります。 + +1. Expression Problemは、データの拡張と操作の拡張の間にある**構造的な緊張関係**です。 +2. Solutions are possible, but they tend to require either: + * **virtual types**を模倣する型システム機能 + * 特別目的の言語拡張 + * 静的型安全性または個別コンパイルに関する妥協 + +## Featherweight Goによる解決(2020) {#featherweight-go-solution-2020} + +Wadlerは1998年に問題を定式化して命名しました。その後、Featherweight Go(FG)とそのジェネリクス拡張であるFGG(Featherweight Generic Go)が、構造的インターフェースとジェネリクスを持つGo風言語において、具体的かつ完全に静的な解決策を示しました。 + +論文の解決策(図8、簡略版)には、構造`Num`と`Plus`、操作`Eval`と`String`がそれぞれ二つあります。 + +```go +type Evaler interface { Eval() int } +type Stringer interface { String() string } + +type Num struct { value int } +type Plus(type a Any) struct { left a; right a } + +func (e Num) Eval() int { return e.value } +func (e Plus(type a Evaler)) Eval() int { return e.left.Eval() + e.right.Eval() } + +func (e Num) String() string { return fmt.Sprintf("%d", e.value) } +func (e Plus(type a Stringer)) String() string { + return fmt.Sprintf("(%s+%s)", e.left.String(), e.right.String()) +} + +type Expr interface { Evaler; Stringer } + +var e Expr = Plus(Expr){Num{1}, Num{2}} +``` + +仕組み: + +* ジェネリックな再帰表現。`Plus`の子要素は、`Any`だけを境界とする型パラメーター`a`を持ちます。すべての操作を列挙した一つの閉じたインターフェースに構造を結び付けないため、後から操作を追加できます。 +* 操作ごとの制約。各メソッド宣言で`a`の境界を個別に定めます。`Eval`では`Plus(type a Evaler)`を、`String`では`Plus(type a Stringer)`を使います。FGGの*共変なレシーバー*に依存しており、型宣言にある境界より強い境界をメソッドのレシーバーに設定できます。 +* 構造的インターフェース。構造体がインターフェースを実装するには、そのメソッドを備えていればよいため、既存の`Num`と`Plus`に触れずに後から`Expr`を導入できます。値の構築時(`Plus(Expr){...}`)に限って、操作一式が固定されます。 + +新しいケースは新しい構造体、新しい操作は新しいインターフェースとメソッドで追加できます。既存の宣言を変更したり再コンパイルしたりする必要はなく、型アサーションも不要です。 + +## 参考文献 {#references} + +* Wadler, P.(1998)。*The Expression Problem*。Java-Genericityメーリングリストへの投稿。問題の定式化と命名。 + [https://homepages.inf.ed.ac.uk/wadler/papers/expression/expression.txt](https://homepages.inf.ed.ac.uk/wadler/papers/expression/expression.txt) + +* Griesemer, R., Hu, R., Kokke, W., Lange, J., Taylor, I. L., Toninho, B., Wadler, P., Yoshida, N.(2020)。*Featherweight Go*。Proc. ACM Program. Lang. 4(OOPSLA)。後年の具体的な言語解決策、第2.3節。 + [https://homepages.inf.ed.ac.uk/wadler/papers/fg/fg.pdf](https://homepages.inf.ed.ac.uk/wadler/papers/fg/fg.pdf) diff --git a/src/concepts/expression-problem.ko.md b/src/concepts/expression-problem.ko.md new file mode 100644 index 0000000..23f43de --- /dev/null +++ b/src/concepts/expression-problem.ko.md @@ -0,0 +1,288 @@ + + +# 표현식 문제 {#expression-problem} + +```admonish tip title="관련 항목" +의미론적 관점: [표시적 설계](../denotational-design/design.md), [표시와 합성성](../denotational-design/denotations.md) +Rust에서 의미로 설계하기: [케이퍼빌리티 대수](../rust-dd/capability-algebras.md), [파생 의미와 합성](../rust-dd/derived-meaning.md) +통찰: [표현식 문제 다시 보기](../insights/expression-problem.md) +``` + +```admonish note title="의미론적 위치" +표현식 문제는 표현과 연산을 모듈식으로 확장하는 문제입니다. 표시적 설계는 한 단계 앞선 질문을 던집니다. 어떤 의미 어휘와 해석을 애초에 표현할 가치가 있나요? +``` + +Phil Wadler의 표현식 문제는 기존 코드를 수정하지 않고 언어를 두 방향으로 **동시에** 확장하는 문제입니다: + +* **새 데이터 변형 추가** (새 표현식 형식, 즉 “구문”). +* **새 연산 추가** (새 해석, 즉 “의미론”). + +핵심적인 긴장 관계: + +* **함수형/ADT** 방식은 연산을 추가하기 쉽지만 변형 추가에는 많은 수정이 필요합니다. +* **객체 지향** 방식은 변형을 추가하기 쉽지만 연산 추가에는 많은 수정이 필요합니다. + +이 절에서는 작은 Haskell 및 Java 예시로 양쪽을 보여 줍니다. + +## Haskell (함수형/ADT) {#haskell-functional--adt} + +표현식과 연산 두 개를 위한 고전적인 ADT에서 시작하겠습니다. + +```haskell +data Expr + = Lit Int + | Add Expr Expr + +eval :: Expr -> Int +eval (Lit n) = n +eval (Add a b) = eval a + eval b + +pretty :: Expr -> String +pretty (Lit n) = show n +pretty (Add a b) = "(" ++ pretty a ++ " + " ++ pretty b ++ ")" +``` + +이제 **새 연산 추가**는 쉽습니다: + +```haskell +size :: Expr -> Int +size (Lit _) = 1 +size (Add a b) = 1 + size a + size b +``` + +하지만 **새 변형 추가** (예: `Mul`)를 하려면 모든 함수를 수정해야 합니다: + +```haskell +data Expr + = Lit Int + | Add Expr Expr + | Mul Expr Expr + +eval :: Expr -> Int +eval (Lit n) = n +eval (Add a b) = eval a + eval b +eval (Mul a b) = eval a * eval b -- ✏️ UPDATE: new case + +pretty :: Expr -> String +pretty (Lit n) = show n +pretty (Add a b) = "(" ++ pretty a ++ " + " ++ pretty b ++ ")" +pretty (Mul a b) = "(" ++ pretty a ++ " * " ++ pretty b ++ ")" -- ✏️ UPDATE: new case + +size :: Expr -> Int +size (Lit _) = 1 +size (Add a b) = 1 + size a + size b +size (Mul a b) = 1 + size a + size b -- ✏️ UPDATE: new case +``` + +Wadler의 용어로 말하면 ADT 방식에서는 **데이터 확장이 모듈식이 아닙니다**. + +## Java (객체 지향) {#java-object-oriented} + +인터페이스와 각 변형의 구체 클래스로 시작하겠습니다. + +```java +// Expression variants +interface Expr { + int eval(); + String pretty(); +} + +final class Lit implements Expr { + private final int n; + + Lit(int n) { + this.n = n; + } + + public int eval() { + return n; + } + + public String pretty() { + return Integer.toString(n); + } +} + +final class Add implements Expr { + private final Expr a; + private final Expr b; + + Add(Expr a, Expr b) { + this.a = a; + this.b = b; + } + + public int eval() { + return a.eval() + b.eval(); + } + + public String pretty() { + return "(" + a.pretty() + " + " + b.pretty() + ")"; + } +} +``` + +이제 **새 변형 추가**는 쉽습니다: + +```java +final class Mul implements Expr { + private final Expr a; + private final Expr b; + + Mul(Expr a, Expr b) { + this.a = a; + this.b = b; + } + + public int eval() { + return a.eval() * b.eval(); + } + + public String pretty() { + return "(" + a.pretty() + " * " + b.pretty() + ")"; + } +} +``` + +하지만 **새 연산 추가** (예: `size`)는 많은 수정을 요구합니다. 인터페이스와 모든 클래스를 수정해야 합니다: + +```java +interface Expr { + int eval(); + String pretty(); + int size(); // ✏️ UPDATE: new operation added here +} + +final class Lit implements Expr { + private final int n; + + Lit(int n) { this.n = n; } + + public int eval() { return n; } + public String pretty() { return Integer.toString(n); } + public int size() { return 1; } // ✏️ UPDATE: new method in every class +} + +final class Add implements Expr { + private final Expr a; + private final Expr b; + + Add(Expr a, Expr b) { this.a = a; this.b = b; } + + public int eval() { return a.eval() + b.eval(); } + public String pretty() { return "(" + a.pretty() + " + " + b.pretty() + ")"; } + public int size() { return 1 + a.size() + b.size(); } // ✏️ UPDATE: new method in every class +} + +final class Mul implements Expr { + private final Expr a; + private final Expr b; + + Mul(Expr a, Expr b) { this.a = a; this.b = b; } + + public int eval() { return a.eval() * b.eval(); } + public String pretty() { return "(" + a.pretty() + " * " + b.pretty() + ")"; } + public int size() { return 1 + a.size() + b.size(); } // ✏️ UPDATE: new method in every class +} +``` + +Wadler의 용어로 말하면 객체 지향 방식에서는 **연산 확장이 모듈식이 아닙니다**. + +## 요약 (Wadler의 지적) {#summary-wadlers-point} + +* 함수형/ADT 방식은 **새 연산**을 선호하지만 **새 변형**에는 약합니다. +* 객체 지향 방식은 **새 변형**을 선호하지만 **새 연산**에는 약합니다. +* 표현식 문제는 기존 코드를 수정하지 않고 **두** 방향을 모두 확장할 수 있는 설계를 찾습니다. + +## Wadler의 설명과 해결책의 흐름 (1998) {#wadlers-explanation-and-solution-landscape-1998} + +Wadler는 데이터형을 **사례별로** 확장하고 (새 변형), 그 데이터형에 대한 **함수도 확장하되** (새 연산), *기존 코드를 재컴파일하지 않고* **정적 타입 안전성**(캐스트 없음)을 유지하는 문제로 설명합니다. + +그는 “표”라는 비유를 사용합니다: + +* **행** = 사례 (변형/생성자) +* **열** = 함수 (연산/해석) + +**함수형/ADT** 환경에서는 행이 고정되고 열을 쉽게 추가할 수 있습니다. +**객체 지향** 환경에서는 열이 고정되고 행을 쉽게 추가할 수 있습니다. +과제는 **양쪽**을 모두 확장 가능하게 만드는 것입니다. + +## Wadler의 제안 (GJ + 가상 타입) {#wadlers-proposed-solution-gj--virtual-types} + +Wadler는 GJ (Generic Java)에서 다음을 이용한 해결책을 제시합니다: + +* `This`로 제한된 매개변수(`This extends LangF`)로 **ThisType**을 모사합니다. +* **`This`(가상 타입)으로 색인된 내부 클래스와 인터페이스**. +* A visitor-based structure that allows: + * “언어 계열”을 서브클래싱해 새 사례 추가 (예: `Plus`) + * 새 방문자를 추가해 새 연산 추가 (예: `Show`) + +각 확장 단계가 타입 안전성을 유지하고 독립적으로 컴파일되도록 `This.Exp`와 `This.Visitor`를 참조하는 것이 핵심입니다. + +### 주의 (Java 내부 인터페이스) {#caveat-java-inner-interfaces} + +Wadler는 Java가 내부 인터페이스를 **정적**으로 취급하여 색인화 기법을 깨뜨린다고 지적합니다. +이 제한을 완화하면 해결책이 가능해질 것이라고 제안했지만, 현대 Java에서도 달라지지 않았습니다(중첩 인터페이스는 여전히 암묵적으로 정적입니다). + +## 언급된 다른 해결 방향 {#other-solution-directions-mentioned} + +1. Corky Cartwright의 접근법 **반공변 확장**이 필요합니다. 기본 표현식 타입이 확장된 타입을 대신할 수 있게 합니다. 이것이 고정점을 사용하는 이유를 설명합니다. 확장된 언어 계열은 원래 타입의 서브타입이 *아닙니다*. + +2. Kim Bruce의 접근법 **고차 타입 생성자**(타입 생성자를 인수로 받는 타입)가 필요합니다. GJ는 이를 직접 지원하지 않지만 Wadler는 가상 타입으로 모사할 수 있다고 주장합니다. + +3. Krishnamurthi 외 (확장 방문자 패턴) 확장 방문자 설계로 동작합니다. 그들의 환경(Pizza)에서는 **정적 타입 검사를 받지 않으므로** 동적 캐스트가 필요합니다. + +4. 특수 목적 언어 확장 Wadler는 이 문제를 위해 특별히 설계된 언어 기능에 의존하는 해결책 두 가지를 소개합니다. 가상 타입 접근법보다 일반성이 낮습니다. + + +## Wadler가 강조한 두 가지 {#wadlers-two-points} + +Wadler의 이메일에서는 두 가지 점이 분명합니다: + +1. 표현식 문제는 데이터 확장과 연산 확장 사이의 **구조적 긴장 관계**입니다. +2. Solutions are possible, but they tend to require either: + * **가상 타입**을 모사하는 타입 시스템 기능, 또는 + * 특수 목적 언어 확장, 또는 + * 정적 타입 안전성이나 독립 컴파일을 일부 포기하는 방법이 필요합니다. + +## Featherweight Go 해결책 (2020) {#featherweight-go-solution-2020} + +Wadler는 1998년에 문제를 정식화하고 이름 붙였습니다. 이후 Featherweight Go(FG)와 제네릭 확장인 FGG(Featherweight Generic Go)는 구조적 인터페이스와 제네릭을 갖춘 Go 계열 언어에서 구체적이고 완전한 정적 해결책을 제시했습니다. + +논문의 해결책(그림 8, 단순화)은 구조 `Num`와 `Plus`, 연산 `Eval`와 `String`을 사용합니다: + +```go +type Evaler interface { Eval() int } +type Stringer interface { String() string } + +type Num struct { value int } +type Plus(type a Any) struct { left a; right a } + +func (e Num) Eval() int { return e.value } +func (e Plus(type a Evaler)) Eval() int { return e.left.Eval() + e.right.Eval() } + +func (e Num) String() string { return fmt.Sprintf("%d", e.value) } +func (e Plus(type a Stringer)) String() string { + return fmt.Sprintf("(%s+%s)", e.left.String(), e.right.String()) +} + +type Expr interface { Evaler; Stringer } + +var e Expr = Plus(Expr){Num{1}, Num{2}} +``` + +기제: + +* **제네릭 재귀 표현.** `Plus`의 자식은 `Any`만을 바운드로 갖는 타입 매개변수 `a`을 사용합니다. 구조는 가능한 모든 연산을 나열하는 하나의 닫힌 인터페이스에 묶이지 않으므로 이후 연산을 추가할 수 있습니다. +* **연산별 제약.** 각 메서드 선언은 `a`을 독립적으로 제한합니다. `Eval`에는 `Plus(type a Evaler)`을, `String`에는 `Plus(type a Stringer)`을 사용합니다. 이는 FGG의 *공변 수신자*에 의존합니다. 메서드의 수신자 바운드가 타입 선언의 바운드보다 강할 수 있습니다. +* **구조적 인터페이스.** 구조는 필요한 메서드를 갖추면 인터페이스를 구현하므로, `Num`과 `Plus`를 수정하지 않고도 `Expr`를 나중에 도입할 수 있습니다. 전체 연산 집합은 값이 만들어질 때에만 고정됩니다(`Plus(Expr){...}`). + +새 사례는 새 구조가 되고, 새 연산은 새 인터페이스와 메서드가 됩니다. 기존 선언을 변경하거나 재컴파일할 필요가 없으며, 타입 단언도 필요하지 않습니다. + +## 참고 문헌 {#references} + +* Wadler, P. (1998). *The Expression Problem*. Java-Genericity 메일링 리스트 문서. 문제의 정식화와 명명. + [https://homepages.inf.ed.ac.uk/wadler/papers/expression/expression.txt](https://homepages.inf.ed.ac.uk/wadler/papers/expression/expression.txt) + +* Griesemer, R., Hu, R., Kokke, W., Lange, J., Taylor, I. L., Toninho, B., Wadler, P., Yoshida, N. (2020). *Featherweight Go*. Proc. ACM Program. Lang. 4 (OOPSLA). 후속 언어의 구체적 해결책, 2.3절. + [https://homepages.inf.ed.ac.uk/wadler/papers/fg/fg.pdf](https://homepages.inf.ed.ac.uk/wadler/papers/fg/fg.pdf) diff --git a/src/concepts/expression-problem.md b/src/concepts/expression-problem.md index 27bc5e6..04f5830 100644 --- a/src/concepts/expression-problem.md +++ b/src/concepts/expression-problem.md @@ -249,7 +249,44 @@ Wadler’s email makes two points clear: - Special-purpose language extensions, or - A compromise on static type safety or independent compilation. +## Featherweight Go solution (2020) + +Wadler 1998 formulates and names the problem. Featherweight Go (FG) and its generic extension FGG (Featherweight Generic Go) later give a concrete, fully static solution in a Go-like language with structural interfaces and generics. + +The paper's solution (Fig. 8, simplified) has two structures, `Num` and `Plus`, and two operations, `Eval` and `String`: + +```go +type Evaler interface { Eval() int } +type Stringer interface { String() string } + +type Num struct { value int } +type Plus(type a Any) struct { left a; right a } + +func (e Num) Eval() int { return e.value } +func (e Plus(type a Evaler)) Eval() int { return e.left.Eval() + e.right.Eval() } + +func (e Num) String() string { return fmt.Sprintf("%d", e.value) } +func (e Plus(type a Stringer)) String() string { + return fmt.Sprintf("(%s+%s)", e.left.String(), e.right.String()) +} + +type Expr interface { Evaler; Stringer } + +var e Expr = Plus(Expr){Num{1}, Num{2}} +``` + +The mechanism: + +- **Generic recursive representation.** The children of `Plus` have a type parameter `a` bounded only by `Any`. The structure is not tied to one closed interface listing every operation, so later operations remain possible. +- **Operation-specific constraints.** Each method declaration bounds `a` independently: `Plus(type a Evaler)` for `Eval`, `Plus(type a Stringer)` for `String`. This relies on FGG's *covariant receivers*: a method's receiver bound may be stronger than the bound in the type declaration. +- **Structural interfaces.** A structure implements an interface by having its methods, so `Expr` can be introduced after `Num` and `Plus` without touching them. The full operation set is fixed only where a value is built (`Plus(Expr){...}`). + +New cases are new structures; new operations are new interfaces and methods. Neither requires changing or recompiling existing declarations, and no type assertions are needed. + ## References -* Wadler, P. (1998). *The Expression Problem*. Java-Genericity mailing list note. +* Wadler, P. (1998). *The Expression Problem*. Java-Genericity mailing list note. Formulation and naming of the problem. [https://homepages.inf.ed.ac.uk/wadler/papers/expression/expression.txt](https://homepages.inf.ed.ac.uk/wadler/papers/expression/expression.txt) + +* Griesemer, R., Hu, R., Kokke, W., Lange, J., Taylor, I. L., Toninho, B., Wadler, P., and Yoshida, N. (2020). *Featherweight Go*. Proc. ACM Program. Lang. 4 (OOPSLA). A later concrete language solution, Section 2.3. + [https://homepages.inf.ed.ac.uk/wadler/papers/fg/fg.pdf](https://homepages.inf.ed.ac.uk/wadler/papers/fg/fg.pdf) diff --git a/src/concepts/expression-problem.ru.md b/src/concepts/expression-problem.ru.md new file mode 100644 index 0000000..6cd13ce --- /dev/null +++ b/src/concepts/expression-problem.ru.md @@ -0,0 +1,288 @@ + + +# Проблема выражения {#expression-problem} + +```admonish tip title="Связанные материалы" +«Семантический взгляд»: [Денотационное проектирование](../denotational-design/design.md), [Денотации и композиционность](../denotational-design/denotations.md) +«Проектирование на основе смысла в Rust»: [Алгебры возможностей](../rust-dd/capability-algebras.md), [Производный смысл и композиция](../rust-dd/derived-meaning.md) +«Идеи»: [Проблема выражения: новый взгляд](../insights/expression-problem.md) +``` + +```admonish note title="Семантическое место" +Проблема выражения касается модульного расширения представлений и операций. Денотационное проектирование задаёт более ранний вопрос: какой семантический словарь и какие интерпретации вообще стоит представлять? +``` + +Проблема выражения, сформулированная Филом Уодлером, касается **одновременного** расширения языка по двум измерениям без изменения существующего кода: + +* **Добавление новых вариантов данных** (новых форм выражений, то есть «синтаксиса»). +* **Добавление новых операций** (новых интерпретаций, то есть «семантики»). + +Основное противоречие: + +* В **функциональном стиле/стиле ADT** легко добавлять операции, но добавление вариантов требует существенных изменений. +* В **объектно-ориентированном стиле** легко добавлять варианты, но добавление операций требует существенных изменений. + +В этом разделе обе стороны показаны на небольших примерах Haskell и Java. + +## Haskell (функциональный стиль / ADT) {#haskell-functional--adt} + +Начнём с классического ADT для выражений и двух операций. + +```haskell +data Expr + = Lit Int + | Add Expr Expr + +eval :: Expr -> Int +eval (Lit n) = n +eval (Add a b) = eval a + eval b + +pretty :: Expr -> String +pretty (Lit n) = show n +pretty (Add a b) = "(" ++ pretty a ++ " + " ++ pretty b ++ ")" +``` + +Теперь легко **добавить новую операцию**: + +```haskell +size :: Expr -> Int +size (Lit _) = 1 +size (Add a b) = 1 + size a + size b +``` + +Но **добавление нового варианта** (например, `Mul`) требует изменить каждую функцию: + +```haskell +data Expr + = Lit Int + | Add Expr Expr + | Mul Expr Expr + +eval :: Expr -> Int +eval (Lit n) = n +eval (Add a b) = eval a + eval b +eval (Mul a b) = eval a * eval b -- ✏️ UPDATE: new case + +pretty :: Expr -> String +pretty (Lit n) = show n +pretty (Add a b) = "(" ++ pretty a ++ " + " ++ pretty b ++ ")" +pretty (Mul a b) = "(" ++ pretty a ++ " * " ++ pretty b ++ ")" -- ✏️ UPDATE: new case + +size :: Expr -> Int +size (Lit _) = 1 +size (Add a b) = 1 + size a + size b +size (Mul a b) = 1 + size a + size b -- ✏️ UPDATE: new case +``` + +В терминологии Уодлера, в подходе ADT **расширение данных не является модульным**. + +## Java (объектно-ориентированный стиль) {#java-object-oriented} + +Начнём с интерфейса и конкретного класса для каждого варианта. + +```java +// Expression variants +interface Expr { + int eval(); + String pretty(); +} + +final class Lit implements Expr { + private final int n; + + Lit(int n) { + this.n = n; + } + + public int eval() { + return n; + } + + public String pretty() { + return Integer.toString(n); + } +} + +final class Add implements Expr { + private final Expr a; + private final Expr b; + + Add(Expr a, Expr b) { + this.a = a; + this.b = b; + } + + public int eval() { + return a.eval() + b.eval(); + } + + public String pretty() { + return "(" + a.pretty() + " + " + b.pretty() + ")"; + } +} +``` + +Теперь легко **добавить новый вариант**: + +```java +final class Mul implements Expr { + private final Expr a; + private final Expr b; + + Mul(Expr a, Expr b) { + this.a = a; + this.b = b; + } + + public int eval() { + return a.eval() * b.eval(); + } + + public String pretty() { + return "(" + a.pretty() + " * " + b.pretty() + ")"; + } +} +``` + +Но **добавление новой операции** (например, `size`) требует больших изменений. Нужно отредактировать интерфейс и каждый класс: + +```java +interface Expr { + int eval(); + String pretty(); + int size(); // ✏️ UPDATE: new operation added here +} + +final class Lit implements Expr { + private final int n; + + Lit(int n) { this.n = n; } + + public int eval() { return n; } + public String pretty() { return Integer.toString(n); } + public int size() { return 1; } // ✏️ UPDATE: new method in every class +} + +final class Add implements Expr { + private final Expr a; + private final Expr b; + + Add(Expr a, Expr b) { this.a = a; this.b = b; } + + public int eval() { return a.eval() + b.eval(); } + public String pretty() { return "(" + a.pretty() + " + " + b.pretty() + ")"; } + public int size() { return 1 + a.size() + b.size(); } // ✏️ UPDATE: new method in every class +} + +final class Mul implements Expr { + private final Expr a; + private final Expr b; + + Mul(Expr a, Expr b) { this.a = a; this.b = b; } + + public int eval() { return a.eval() * b.eval(); } + public String pretty() { return "(" + a.pretty() + " * " + b.pretty() + ")"; } + public int size() { return 1 + a.size() + b.size(); } // ✏️ UPDATE: new method in every class +} +``` + +В терминологии Уодлера, в ОО-подходе **расширение операций не является модульным**. + +## Итог (позиция Уодлера) {#summary-wadlers-point} + +* Функциональный стиль/ADT упрощает добавление **новых операций**, но затрудняет добавление **новых вариантов**. +* ОО-стиль упрощает добавление **новых вариантов**, но затрудняет добавление **новых операций**. +* Проблема выражения ставит вопрос о проектировании, при котором **оба** измерения расширяются без изменения существующего кода. + +## Объяснение Уодлера и пространство решений (1998) {#wadlers-explanation-and-solution-landscape-1998} + +Уодлер описывает задачу так: расширять тип данных **случаями** (новыми вариантами) и расширять **функции над этим типом данных**, *не перекомпилируя существующий код* и сохраняя **статическую типобезопасность** (без приведений типов). + +Он использует метафору «таблицы»: + +* **Строки** — случаи (варианты / конструкторы) +* **Столбцы** — функции (операции / интерпретации) + +В **функциональном стиле/стиле ADT** строки фиксированы, а столбцы добавлять легко. +В **ОО-подходе** столбцы фиксированы, а строки добавлять легко. +Задача — сделать расширяемыми **оба направления**. + +## Предложенное Уодлером решение (GJ и виртуальные типы) {#wadlers-proposed-solution-gj--virtual-types} + +Уодлер предлагает решение на языке GJ (Generic Java), используя: + +* Параметр с ограничением вида `This` (`This extends LangF`) для имитации **ThisType**. +* **Внутренние классы и интерфейсы**, индексированные через `This` (виртуальные типы). +* A visitor-based structure that allows: + * Новые случаи (например, `Plus`) добавляются наследованием от «семейства языка». + * Новые операции (например, `Show`) добавляются новыми посетителями. + +Приём состоит в использовании `This.Exp` и `This.Visitor` таким образом, чтобы каждый этап расширения оставался типобезопасным и компилировался независимо. + +### Ограничение (внутренние интерфейсы Java) {#caveat-java-inner-interfaces} + +Уодлер отмечает, что Java считает внутренние интерфейсы **статическими**, что нарушает приём индексирования. +Он предполагает, что снятие этого ограничения сделало бы решение применимым; в современной Java это не изменилось (вложенные интерфейсы по-прежнему неявно статические). + +## Другие упомянутые направления решения {#other-solution-directions-mentioned} + +1. Подход Корки Картрайта Требует **контравариантного расширения**: базовый тип выражения должен подменять расширенный. Этим объясняется применение неподвижных точек: расширенное семейство языков *не* является подтипом исходного. + +2. Подход Кима Брюса Требует **конструкторов типов высшего порядка** (тип параметризуется конструктором типов). GJ не поддерживает это напрямую, но Уодлер утверждает, что виртуальные типы могут это имитировать. + +3. Кришнамурти и соавторы (расширенный паттерн Visitor) Используется расширенный паттерн Visitor. В их среде (Pizza) типизация **не статическая**, поэтому необходимы динамические приведения. + +4. Специализированные расширения языка Уодлер приводит два решения, основанных на возможностях, специально разработанных для этой задачи. Они менее универсальны, чем подход с виртуальными типами. + + +## Два положения Уодлера {#wadlers-two-points} + +В письме Уодлера ясно сформулированы две мысли: + +1. Проблема выражения — это **структурное противоречие** между расширением данных и расширением операций. +2. Solutions are possible, but they tend to require either: + * Возможности системы типов, имитирующие **виртуальные типы**, либо + * специализированные расширения языка, либо + * компромисс между статической типобезопасностью и независимой компиляцией. + +## Решение на Featherweight Go (2020) {#featherweight-go-solution-2020} + +Уодлер сформулировал проблему и дал ей название в 1998 году. Позднее Featherweight Go (FG) и его обобщённое расширение FGG (Featherweight Generic Go) предложили конкретное полностью статическое решение для языка в духе Go со структурными интерфейсами и обобщёнными типами. + +В решении статьи (рис. 8, упрощённо) используются две структуры `Num` и `Plus` и две операции `Eval` и `String`: + +```go +type Evaler interface { Eval() int } +type Stringer interface { String() string } + +type Num struct { value int } +type Plus(type a Any) struct { left a; right a } + +func (e Num) Eval() int { return e.value } +func (e Plus(type a Evaler)) Eval() int { return e.left.Eval() + e.right.Eval() } + +func (e Num) String() string { return fmt.Sprintf("%d", e.value) } +func (e Plus(type a Stringer)) String() string { + return fmt.Sprintf("(%s+%s)", e.left.String(), e.right.String()) +} + +type Expr interface { Evaler; Stringer } + +var e Expr = Plus(Expr){Num{1}, Num{2}} +``` + +Механизм: + +* **Обобщённое рекурсивное представление.** Дочерние элементы `Plus` имеют параметр типа `a` с единственным ограничением `Any`. Структура не привязана к одному закрытому интерфейсу, перечисляющему все операции, поэтому позднее можно добавлять новые операции. +* **Ограничения для отдельных операций.** Объявление каждого метода независимо ограничивает `a`: `Plus(type a Evaler)` для `Eval` и `Plus(type a Stringer)` для `String`. Это опирается на *ковариантные получатели* в FGG: ограничение получателя метода может быть сильнее ограничения в объявлении типа. +* **Структурные интерфейсы.** Структура реализует интерфейс, если у неё есть его методы, поэтому `Expr` можно ввести после `Num` и `Plus`, не изменяя их. Полный набор операций фиксируется лишь при создании значения (`Plus(Expr){...}`). + +Новые случаи добавляются новыми структурами, а новые операции — интерфейсами и методами. Для этого не нужно менять или перекомпилировать существующие объявления и не требуются проверки типов во время выполнения. + +## Источники {#references} + +* Уодлер, П. (1998). *The Expression Problem*. Заметка в списке рассылки Java-Genericity. Формулировка проблемы и введение названия. + [https://homepages.inf.ed.ac.uk/wadler/papers/expression/expression.txt](https://homepages.inf.ed.ac.uk/wadler/papers/expression/expression.txt) + +* Гриземер, Р., Ху, Р., Кокке, В., Ланге, Й., Тейлор, И. Л., Тониньо, Б., Уодлер, П. и Ёсида, Н. (2020). *Featherweight Go*. Proc. ACM Program. Lang. 4 (OOPSLA). Позднейшее конкретное решение на уровне языка, раздел 2.3. + [https://homepages.inf.ed.ac.uk/wadler/papers/fg/fg.pdf](https://homepages.inf.ed.ac.uk/wadler/papers/fg/fg.pdf) diff --git a/src/concepts/expression-problem.uk.md b/src/concepts/expression-problem.uk.md new file mode 100644 index 0000000..c5f2895 --- /dev/null +++ b/src/concepts/expression-problem.uk.md @@ -0,0 +1,288 @@ + + +# Проблема виразів {#expression-problem} + +```admonish tip title="Пов’язані матеріали" +Семантичний погляд: [Денотаційне проєктування](../denotational-design/design.md), [Денотації та композиційність](../denotational-design/denotations.md) +Проєктування від значення в Rust: [Алгебри можливостей](../rust-dd/capability-algebras.md), [Похідне значення та композиція](../rust-dd/derived-meaning.md) +Інсайти: [Проблема виразів: новий погляд](../insights/expression-problem.md) +``` + +```admonish note title="Семантичне місце" +Проблема виразів стосується модульного розширення представлень і операцій. Денотаційне проєктування порушує попереднє запитання: яку семантичну термінологію та які інтерпретації взагалі варто представляти? +``` + +Проблема виразів Філа Ведлера стосується **одночасного** розширення мови у двох вимірах без зміни наявного коду: + +* **Додавати нові варіанти даних** (нові форми виразів, тобто «синтаксис»). +* **Додавати нові операції** (нові інтерпретації, тобто «семантику»). + +Основна суперечність: + +* У **функційному стилі / ADT** легко додавати нові операції, але додавання варіантів потребує втручання. +* В **об’єктно-орієнтованому стилі** легко додавати нові варіанти, але додавання операцій потребує втручання. + +У цьому розділі обидва боки показано на невеликих прикладах Haskell і Java. + +## Haskell (функційний стиль / ADT) {#haskell-functional--adt} + +Почнімо з класичного ADT для виразів і двох операцій. + +```haskell +data Expr + = Lit Int + | Add Expr Expr + +eval :: Expr -> Int +eval (Lit n) = n +eval (Add a b) = eval a + eval b + +pretty :: Expr -> String +pretty (Lit n) = show n +pretty (Add a b) = "(" ++ pretty a ++ " + " ++ pretty b ++ ")" +``` + +Тепер **додати нову операцію** легко: + +```haskell +size :: Expr -> Int +size (Lit _) = 1 +size (Add a b) = 1 + size a + size b +``` + +Але **додавання нового варіанта**, наприклад `Mul`, змушує змінювати кожну функцію: + +```haskell +data Expr + = Lit Int + | Add Expr Expr + | Mul Expr Expr + +eval :: Expr -> Int +eval (Lit n) = n +eval (Add a b) = eval a + eval b +eval (Mul a b) = eval a * eval b -- ✏️ UPDATE: new case + +pretty :: Expr -> String +pretty (Lit n) = show n +pretty (Add a b) = "(" ++ pretty a ++ " + " ++ pretty b ++ ")" +pretty (Mul a b) = "(" ++ pretty a ++ " * " ++ pretty b ++ ")" -- ✏️ UPDATE: new case + +size :: Expr -> Int +size (Lit _) = 1 +size (Add a b) = 1 + size a + size b +size (Mul a b) = 1 + size a + size b -- ✏️ UPDATE: new case +``` + +За формулюванням Ведлера, у підході ADT **розширення даних не є модульним**. + +## Java (об’єктно-орієнтований стиль) {#java-object-oriented} + +Почнімо з інтерфейсу й конкретних класів для кожного варіанта. + +```java +// Expression variants +interface Expr { + int eval(); + String pretty(); +} + +final class Lit implements Expr { + private final int n; + + Lit(int n) { + this.n = n; + } + + public int eval() { + return n; + } + + public String pretty() { + return Integer.toString(n); + } +} + +final class Add implements Expr { + private final Expr a; + private final Expr b; + + Add(Expr a, Expr b) { + this.a = a; + this.b = b; + } + + public int eval() { + return a.eval() + b.eval(); + } + + public String pretty() { + return "(" + a.pretty() + " + " + b.pretty() + ")"; + } +} +``` + +Тепер **додати новий варіант** легко: + +```java +final class Mul implements Expr { + private final Expr a; + private final Expr b; + + Mul(Expr a, Expr b) { + this.a = a; + this.b = b; + } + + public int eval() { + return a.eval() * b.eval(); + } + + public String pretty() { + return "(" + a.pretty() + " * " + b.pretty() + ")"; + } +} +``` + +Але **додавання нової операції**, наприклад `size`, потребує втручання. Потрібно змінити інтерфейс і кожен клас: + +```java +interface Expr { + int eval(); + String pretty(); + int size(); // ✏️ UPDATE: new operation added here +} + +final class Lit implements Expr { + private final int n; + + Lit(int n) { this.n = n; } + + public int eval() { return n; } + public String pretty() { return Integer.toString(n); } + public int size() { return 1; } // ✏️ UPDATE: new method in every class +} + +final class Add implements Expr { + private final Expr a; + private final Expr b; + + Add(Expr a, Expr b) { this.a = a; this.b = b; } + + public int eval() { return a.eval() + b.eval(); } + public String pretty() { return "(" + a.pretty() + " + " + b.pretty() + ")"; } + public int size() { return 1 + a.size() + b.size(); } // ✏️ UPDATE: new method in every class +} + +final class Mul implements Expr { + private final Expr a; + private final Expr b; + + Mul(Expr a, Expr b) { this.a = a; this.b = b; } + + public int eval() { return a.eval() * b.eval(); } + public String pretty() { return "(" + a.pretty() + " * " + b.pretty() + ")"; } + public int size() { return 1 + a.size() + b.size(); } // ✏️ UPDATE: new method in every class +} +``` + +За формулюванням Ведлера, у підході OO **розширення операцій не є модульним**. + +## Підсумок (думка Ведлера) {#summary-wadlers-point} + +* Функційний стиль / ADT сприяє **новим операціям**, але протистоїть **новим варіантам**. +* OO-стиль сприяє **новим варіантам**, але протистоїть **новим операціям**. +* Проблема виразів запитує, як спроєктувати систему, у якій **обидва** виміри можна розширювати без зміни наявного коду. + +## Пояснення Ведлера та огляд можливих рішень (1998) {#wadlers-explanation-and-solution-landscape-1998} + +Ведлер формулює проблему так: розширювати тип даних **додаванням варіантів** і розширювати **функції над цим типом** новими операціями, *не перекомпілюючи наявний код* і зберігаючи **статичну типобезпеку** (без приведень типів). + +Він використовує метафору «таблиці»: + +* **Рядки** = випадки (варіанти / конструктори) +* **Стовпці** = функції (операції / інтерпретації) + +**У** функційному стилі / ADT рядки фіксовані, а стовпці легко додавати. +У **OO**\-стилі фіксовані стовпці, а рядки легко додавати. +Завдання полягає в тому, щоб розширювати **обидва напрямки**. + +## Запропоноване Ведлером рішення (GJ + віртуальні типи) {#wadlers-proposed-solution-gj--virtual-types} + +Ведлер пропонує рішення в GJ (Generic Java), використовуючи: + +* Параметр з обмеженням `This` (`This extends LangF`) для імітації **ThisType**. +* **Внутрішні класи й інтерфейси**, індексовані через `This` (віртуальні типи). +* A visitor-based structure that allows: + * Нові випадки, наприклад `Plus`, додаються успадкуванням від «сімейства мови». + * Нові операції, наприклад `Show`, додаються як нові відвідувачі. + +Трюк полягає в посиланнях на `This.Exp` та `This.Visitor`, завдяки яким кожен етап розширення залишається типобезпечним і компілюється незалежно. + +### Застереження (внутрішні інтерфейси Java) {#caveat-java-inner-interfaces} + +Ведлер зауважує, що Java вважає внутрішні інтерфейси **статичними**, через що трюк з індексуванням не працює. +Він припускає, що послаблення цього обмеження зробило б рішення придатним, але в сучасній Java його досі не змінили (вкладені інтерфейси залишаються неявно статичними). + +## Інші згадані напрямки розв’язання {#other-solution-directions-mentioned} + +1. Підхід Коркі Картрайта Потребує **контраваріантного розширення**: базовий тип виразу має бути прийнятним замість розширеного. Це пояснює використання нерухомих точок: розширене сімейство мов *не* є підтипом початкового. + +2. Підхід Кіма Брюса Потребує **конструкторів типів вищого порядку** (параметризації типу конструктором типів). GJ не підтримує це безпосередньо, але Ведлер стверджує, що віртуальні типи можуть імітувати таку можливість. + +3. Підхід Крішнамурті та співавторів (розширений патерн Visitor) Використовує розширений патерн Visitor. У їхній системі (Pizza) **немає статичної типізації**, тому потрібні динамічні приведення типів. + +4. Спеціалізовані розширення мови Ведлер згадує два рішення, що спираються на функції мови, створені саме для цієї проблеми. Вони менш універсальні за підхід із віртуальними типами. + + +## Дві тези Ведлера {#wadlers-two-points} + +З листа Ведлера чітко випливають дві тези: + +1. Проблема виразів — це **структурна суперечність** між розширенням даних і розширенням операцій. +2. Solutions are possible, but they tend to require either: + * Функції системи типів, що імітують **віртуальні типи**, або + * спеціалізовані розширення мови, або + * компроміс щодо статичної типобезпеки чи незалежної компіляції. + +## Рішення Featherweight Go (2020) {#featherweight-go-solution-2020} + +Ведлер сформулював проблему й дав їй назву 1998 року. Пізніше Featherweight Go (FG) та його узагальнене розширення FGG (Featherweight Generic Go) запропонували конкретне повністю статичне рішення для мови на кшталт Go зі структурними інтерфейсами й узагальненнями. + +У статті описано спрощене рішення (рис. 8) із двома структурами, `Num` та `Plus`, і двома операціями, `Eval` та `String`: + +```go +type Evaler interface { Eval() int } +type Stringer interface { String() string } + +type Num struct { value int } +type Plus(type a Any) struct { left a; right a } + +func (e Num) Eval() int { return e.value } +func (e Plus(type a Evaler)) Eval() int { return e.left.Eval() + e.right.Eval() } + +func (e Num) String() string { return fmt.Sprintf("%d", e.value) } +func (e Plus(type a Stringer)) String() string { + return fmt.Sprintf("(%s+%s)", e.left.String(), e.right.String()) +} + +type Expr interface { Evaler; Stringer } + +var e Expr = Plus(Expr){Num{1}, Num{2}} +``` + +Механізм: + +* **Узагальнене рекурсивне представлення.** Дочірні елементи `Plus` мають параметр типу `a`, обмежений лише `Any`. Структура не прив’язана до одного закритого інтерфейсу, де перелічено всі операції, тож можна додавати нові. +* **Обмеження для окремих операцій.** Кожне оголошення методу незалежно обмежує `a`: `Plus(type a Evaler)` для `Eval` і `Plus(type a Stringer)` для `String`. Це спирається на *коваріантні отримувачі* у FGG: обмеження отримувача методу може бути сильнішим за обмеження в оголошенні типу. +* **Структурні інтерфейси.** Структура реалізує інтерфейс, якщо має потрібні методи, тож `Expr` можна оголосити після `Num` і `Plus`, не змінюючи їх. Повний набір операцій фіксується лише там, де створюють значення (`Plus(Expr){...}`). + +Нові випадки задаються новими структурами, а нові операції — новими інтерфейсами й методами. Не потрібно змінювати чи перекомпілювати наявні оголошення, і жодні перевірки типів під час виконання не потрібні. + +## Джерела {#references} + +* Ведлер, П. (1998). *The Expression Problem*. Повідомлення в поштовому списку Java-Genericity. Формулювання проблеми та надання їй назви. + [https://homepages.inf.ed.ac.uk/wadler/papers/expression/expression.txt](https://homepages.inf.ed.ac.uk/wadler/papers/expression/expression.txt) + +* Гриземер, Р., Ху, Р., Кокке, В., Ланге, Й., Тейлор, А. Л., Тоніньо, Б., Ведлер, П. та Йошида, Н. (2020). *Featherweight Go*. Праці ACM з мов програмування 4 (OOPSLA). Пізніше конкретне рішення для мови, розділ 2.3. + [https://homepages.inf.ed.ac.uk/wadler/papers/fg/fg.pdf](https://homepages.inf.ed.ac.uk/wadler/papers/fg/fg.pdf) diff --git a/src/concepts/expression-problem.vi.md b/src/concepts/expression-problem.vi.md new file mode 100644 index 0000000..5ea2016 --- /dev/null +++ b/src/concepts/expression-problem.vi.md @@ -0,0 +1,288 @@ + + +# Bài toán biểu thức {#expression-problem} + +```admonish tip title="Liên quan" +Góc nhìn ngữ nghĩa: [Thiết kế theo ngữ nghĩa](../denotational-design/design.md), [Ngữ nghĩa và tính hợp thành](../denotational-design/denotations.md) +Thiết kế theo ngữ nghĩa trong Rust: [Các đại số năng lực](../rust-dd/capability-algebras.md), [Ý nghĩa suy ra và phép hợp thành](../rust-dd/derived-meaning.md) +Nhận định: [Bài toán biểu thức trở lại](../insights/expression-problem.md) +``` + +```admonish note title="Vị trí ngữ nghĩa" +Bài toán biểu thức liên quan đến việc mở rộng mô-đun các cách biểu diễn và phép toán. Thiết kế theo ngữ nghĩa đặt ra sớm hơn một câu hỏi: ngay từ đầu, từ vựng ngữ nghĩa và những cách diễn giải nào đáng được biểu diễn? +``` + +Bài toán biểu thức của Phil Wadler nói về việc mở rộng **đồng thời** một ngôn ngữ theo hai chiều mà không chỉnh sửa mã hiện có: + +* **Thêm biến thể dữ liệu** (dạng biểu thức mới, còn gọi là “cú pháp”). +* **Thêm phép toán mới** (cách diễn giải mới, còn gọi là “ngữ nghĩa”). + +Mâu thuẫn cốt lõi: + +* Theo phong cách **hàm/ADT**, thêm phép toán mới thì dễ, nhưng thêm biến thể mới lại xâm lấn. +* Theo phong cách **hướng đối tượng**, thêm biến thể mới thì dễ, nhưng thêm phép toán mới lại xâm lấn. + +Phần này minh họa cả hai phía bằng các ví dụ Haskell và Java nhỏ. + +## Haskell (hàm / ADT) {#haskell-functional--adt} + +Ta bắt đầu với một ADT kinh điển cho biểu thức và hai phép toán. + +```haskell +data Expr + = Lit Int + | Add Expr Expr + +eval :: Expr -> Int +eval (Lit n) = n +eval (Add a b) = eval a + eval b + +pretty :: Expr -> String +pretty (Lit n) = show n +pretty (Add a b) = "(" ++ pretty a ++ " + " ++ pretty b ++ ")" +``` + +Giờ đây, **thêm phép toán mới** thật dễ dàng: + +```haskell +size :: Expr -> Int +size (Lit _) = 1 +size (Add a b) = 1 + size a + size b +``` + +Nhưng **thêm biến thể mới** (ví dụ `Mul`) buộc phải sửa mọi hàm: + +```haskell +data Expr + = Lit Int + | Add Expr Expr + | Mul Expr Expr + +eval :: Expr -> Int +eval (Lit n) = n +eval (Add a b) = eval a + eval b +eval (Mul a b) = eval a * eval b -- ✏️ UPDATE: new case + +pretty :: Expr -> String +pretty (Lit n) = show n +pretty (Add a b) = "(" ++ pretty a ++ " + " ++ pretty b ++ ")" +pretty (Mul a b) = "(" ++ pretty a ++ " * " ++ pretty b ++ ")" -- ✏️ UPDATE: new case + +size :: Expr -> Int +size (Lit _) = 1 +size (Add a b) = 1 + size a + size b +size (Mul a b) = 1 + size a + size b -- ✏️ UPDATE: new case +``` + +Theo cách diễn đạt của Wadler, trong hướng ADT, **mở rộng dữ liệu không có tính mô-đun**. + +## Java (hướng đối tượng) {#java-object-oriented} + +Ta bắt đầu với một giao diện và các lớp cụ thể cho từng biến thể. + +```java +// Expression variants +interface Expr { + int eval(); + String pretty(); +} + +final class Lit implements Expr { + private final int n; + + Lit(int n) { + this.n = n; + } + + public int eval() { + return n; + } + + public String pretty() { + return Integer.toString(n); + } +} + +final class Add implements Expr { + private final Expr a; + private final Expr b; + + Add(Expr a, Expr b) { + this.a = a; + this.b = b; + } + + public int eval() { + return a.eval() + b.eval(); + } + + public String pretty() { + return "(" + a.pretty() + " + " + b.pretty() + ")"; + } +} +``` + +Giờ đây, **thêm biến thể mới** thật dễ dàng: + +```java +final class Mul implements Expr { + private final Expr a; + private final Expr b; + + Mul(Expr a, Expr b) { + this.a = a; + this.b = b; + } + + public int eval() { + return a.eval() * b.eval(); + } + + public String pretty() { + return "(" + a.pretty() + " * " + b.pretty() + ")"; + } +} +``` + +Nhưng **thêm phép toán mới** (ví dụ `size`) lại xâm lấn. Bạn phải sửa giao diện và mọi lớp: + +```java +interface Expr { + int eval(); + String pretty(); + int size(); // ✏️ UPDATE: new operation added here +} + +final class Lit implements Expr { + private final int n; + + Lit(int n) { this.n = n; } + + public int eval() { return n; } + public String pretty() { return Integer.toString(n); } + public int size() { return 1; } // ✏️ UPDATE: new method in every class +} + +final class Add implements Expr { + private final Expr a; + private final Expr b; + + Add(Expr a, Expr b) { this.a = a; this.b = b; } + + public int eval() { return a.eval() + b.eval(); } + public String pretty() { return "(" + a.pretty() + " + " + b.pretty() + ")"; } + public int size() { return 1 + a.size() + b.size(); } // ✏️ UPDATE: new method in every class +} + +final class Mul implements Expr { + private final Expr a; + private final Expr b; + + Mul(Expr a, Expr b) { this.a = a; this.b = b; } + + public int eval() { return a.eval() * b.eval(); } + public String pretty() { return "(" + a.pretty() + " * " + b.pretty() + ")"; } + public int size() { return 1 + a.size() + b.size(); } // ✏️ UPDATE: new method in every class +} +``` + +Theo cách diễn đạt của Wadler, trong hướng OO, **mở rộng phép toán không có tính mô-đun**. + +## Tóm tắt (ý của Wadler) {#summary-wadlers-point} + +* Phong cách hàm/ADT thuận lợi cho **phép toán mới** nhưng không thuận lợi cho **biến thể mới**. +* Phong cách OO thuận lợi cho **biến thể mới** nhưng không thuận lợi cho **phép toán mới**. +* Bài toán biểu thức tìm kiếm thiết kế cho phép mở rộng **cả hai** chiều mà không chỉnh sửa mã hiện có. + +## Cách giải thích của Wadler và bức tranh các giải pháp (1998) {#wadlers-explanation-and-solution-landscape-1998} + +Wadler mô tả bài toán là: mở rộng một kiểu dữ liệu **bằng các trường hợp** (biến thể mới) và mở rộng **các hàm trên kiểu dữ liệu đó** (phép toán mới), *mà không biên dịch lại mã hiện có*, đồng thời giữ được **tính an toàn kiểu tĩnh** (không ép kiểu). + +Ông dùng phép ẩn dụ “bảng”: + +* **Hàng** = các trường hợp (biến thể / cấu trúc tạo) +* **Cột** = hàm (phép toán / cách diễn giải) + +Trong bối cảnh **hàm/ADT**, các hàng cố định còn dễ thêm cột. +Trong bối cảnh **OO**, các cột cố định còn dễ thêm hàng. +Thách thức là làm cho **cả hai hướng** đều mở rộng được. + +## Giải pháp Wadler đề xuất (GJ + kiểu ảo) {#wadlers-proposed-solution-gj--virtual-types} + +Wadler trình bày giải pháp trong GJ (Generic Java), sử dụng: + +* Tham số có cận `This` (`This extends LangF`) để mô phỏng **ThisType**. +* **Các lớp và giao diện bên trong** được đánh chỉ mục theo `This` (kiểu ảo). +* A visitor-based structure that allows: + * Các trường hợp mới (ví dụ `Plus`) bằng cách phân lớp “họ ngôn ngữ” + * Các phép toán mới (ví dụ `Show`) bằng cách thêm visitor mới + +Mẹo là tham chiếu đến `This.Exp` và `This.Visitor` sao cho mỗi giai đoạn mở rộng vẫn an toàn kiểu và có thể biên dịch độc lập. + +### Lưu ý (giao diện bên trong của Java) {#caveat-java-inner-interfaces} + +Wadler lưu ý rằng Java xem giao diện bên trong là **tĩnh**, làm hỏng thủ thuật đánh chỉ mục. +Ông đề xuất nới lỏng hạn chế này để giải pháp khả thi; điều đó vẫn chưa thay đổi trong Java hiện đại (giao diện lồng nhau vẫn mặc định là tĩnh). + +## Các hướng giải pháp khác được nhắc đến {#other-solution-directions-mentioned} + +1. Cách tiếp cận của Corky Cartwright Cần **mở rộng phản biến**: cho phép kiểu biểu thức cơ sở thay thế kiểu đã mở rộng. Điều này giải thích vì sao dùng điểm bất động: họ ngôn ngữ mở rộng *không phải* kiểu con của họ gốc. + +2. Cách tiếp cận của Kim Bruce Cần **bộ dựng kiểu bậc cao** (tham số hóa một kiểu theo bộ dựng kiểu). GJ không hỗ trợ trực tiếp điều này, nhưng Wadler lập luận kiểu ảo có thể mô phỏng nó. + +3. Krishnamurthi và cộng sự (mẫu Extended Visitor) Hoạt động nhờ thiết kế visitor mở rộng. **Không có kiểu tĩnh** trong ngữ cảnh của họ (Pizza), nên cần ép kiểu động. + +4. Phần mở rộng ngôn ngữ chuyên biệt Wadler dẫn hai giải pháp dựa vào tính năng ngôn ngữ được thiết kế riêng cho bài toán. Chúng kém tổng quát hơn cách tiếp cận kiểu ảo. + + +## Hai luận điểm của Wadler {#wadlers-two-points} + +Email của Wadler làm rõ hai điểm: + +1. Bài toán biểu thức là **mâu thuẫn cấu trúc** giữa việc mở rộng dữ liệu và mở rộng phép toán. +2. Solutions are possible, but they tend to require either: + * Các tính năng hệ kiểu mô phỏng **kiểu ảo**, hoặc + * Các phần mở rộng ngôn ngữ chuyên dụng, hoặc + * Sự thỏa hiệp về tính an toàn kiểu tĩnh hoặc biên dịch độc lập. + +## Giải pháp Featherweight Go (2020) {#featherweight-go-solution-2020} + +Wadler đưa ra và đặt tên cho bài toán vào năm 1998. Về sau, Featherweight Go (FG) và phần mở rộng tổng quát FGG (Featherweight Generic Go) đưa ra giải pháp cụ thể hoàn toàn tĩnh trong một ngôn ngữ kiểu Go với giao diện cấu trúc và generic. + +Giải pháp trong bài báo (Hình 8, dạng giản lược) có hai cấu trúc, `Num` và `Plus`, cùng hai phép toán, `Eval` và `String`: + +```go +type Evaler interface { Eval() int } +type Stringer interface { String() string } + +type Num struct { value int } +type Plus(type a Any) struct { left a; right a } + +func (e Num) Eval() int { return e.value } +func (e Plus(type a Evaler)) Eval() int { return e.left.Eval() + e.right.Eval() } + +func (e Num) String() string { return fmt.Sprintf("%d", e.value) } +func (e Plus(type a Stringer)) String() string { + return fmt.Sprintf("(%s+%s)", e.left.String(), e.right.String()) +} + +type Expr interface { Evaler; Stringer } + +var e Expr = Plus(Expr){Num{1}, Num{2}} +``` + +Cơ chế: + +* **Biểu diễn đệ quy tổng quát.** Các nút con của `Plus` có tham số kiểu `a` chỉ bị giới hạn bởi `Any`. Cấu trúc không bị gắn với một giao diện đóng liệt kê mọi phép toán, nên vẫn có thể thêm phép toán về sau. +* **Ràng buộc riêng cho từng phép toán.** Mỗi khai báo phương thức đặt cận độc lập cho `a`: `Plus(type a Evaler)` cho `Eval`, `Plus(type a Stringer)` cho `String`. Điều này dựa vào *bộ nhận hiệp biến* của FGG: cận bộ nhận của phương thức có thể mạnh hơn cận trong khai báo kiểu. +* **Giao diện cấu trúc.** Một cấu trúc triển khai giao diện chỉ cần có các phương thức của giao diện, nên có thể khai báo `Expr` sau `Num` và `Plus` mà không đụng đến chúng. Tập phép toán đầy đủ chỉ được cố định tại nơi tạo giá trị (`Plus(Expr){...}`). + +Các trường hợp mới là cấu trúc mới; các phép toán mới là giao diện và phương thức mới. Không điều nào đòi hỏi thay đổi hoặc biên dịch lại khai báo hiện có, và cũng không cần khẳng định kiểu. + +## Tài liệu tham khảo {#references} + +* Wadler, P. (1998). *The Expression Problem*. Ghi chú trên danh sách thư Java-Genericity. Nêu công thức và đặt tên cho bài toán. + [https://homepages.inf.ed.ac.uk/wadler/papers/expression/expression.txt](https://homepages.inf.ed.ac.uk/wadler/papers/expression/expression.txt) + +* Griesemer, R., Hu, R., Kokke, W., Lange, J., Taylor, I. L., Toninho, B., Wadler, P. và Yoshida, N. (2020). *Featherweight Go*. Proc. ACM Program. Lang. 4 (OOPSLA). Một giải pháp ngôn ngữ cụ thể về sau, Mục 2.3. + [https://homepages.inf.ed.ac.uk/wadler/papers/fg/fg.pdf](https://homepages.inf.ed.ac.uk/wadler/papers/fg/fg.pdf) diff --git a/src/concepts/expression-problem.zh-hant.md b/src/concepts/expression-problem.zh-hant.md new file mode 100644 index 0000000..3f6d05b --- /dev/null +++ b/src/concepts/expression-problem.zh-hant.md @@ -0,0 +1,288 @@ + + +# 表示式問題 {#expression-problem} + +```admonish tip title="相關內容" +語義視角:[指稱設計](../denotational-design/design.md)、[指稱與組合性](../denotational-design/denotations.md) +Rust 中的語義驅動設計:[能力代數](../rust-dd/capability-algebras.md)、[派生含義與組合](../rust-dd/derived-meaning.md) +洞見:[重新審視表示式問題](../insights/expression-problem.md) +``` + +```admonish note title="語義定位" +表示式問題關注表示與操作的模組化擴充。指稱設計則更早地提出一個問題:哪些語義詞彙與解釋值得表示? +``` + +Phil Wadler 提出的表示式問題關注如何在兩個維度上**同時**擴充語言,而無須修改現有程式碼: + +* **新增新的資料變體**(新的表示式形式,也稱“語法”)。 +* **新增新的操作**(新的解釋,也稱“語義”)。 + +核心矛盾: + +* 採用**函式式/代數資料型別**風格時,新增新操作很容易,但新增新變體會造成侵入式修改。 +* 採用**物件導向**風格時,新增新變體很容易,但新增新操作會造成侵入式修改。 + +本節用簡短的 Haskell 與 Java 示例展示兩面。 + +## Haskell(函式式/代數資料型別) {#haskell-functional--adt} + +先從一個經典的表示式代數資料型別及兩種操作開始。 + +```haskell +data Expr + = Lit Int + | Add Expr Expr + +eval :: Expr -> Int +eval (Lit n) = n +eval (Add a b) = eval a + eval b + +pretty :: Expr -> String +pretty (Lit n) = show n +pretty (Add a b) = "(" ++ pretty a ++ " + " ++ pretty b ++ ")" +``` + +現在,**新增新操作**很容易: + +```haskell +size :: Expr -> Int +size (Lit _) = 1 +size (Add a b) = 1 + size a + size b +``` + +但**新增新變體**(例如`Mul`)就要求修改每個函式: + +```haskell +data Expr + = Lit Int + | Add Expr Expr + | Mul Expr Expr + +eval :: Expr -> Int +eval (Lit n) = n +eval (Add a b) = eval a + eval b +eval (Mul a b) = eval a * eval b -- ✏️ UPDATE: new case + +pretty :: Expr -> String +pretty (Lit n) = show n +pretty (Add a b) = "(" ++ pretty a ++ " + " ++ pretty b ++ ")" +pretty (Mul a b) = "(" ++ pretty a ++ " * " ++ pretty b ++ ")" -- ✏️ UPDATE: new case + +size :: Expr -> Int +size (Lit _) = 1 +size (Add a b) = 1 + size a + size b +size (Mul a b) = 1 + size a + size b -- ✏️ UPDATE: new case +``` + +用 Wadler 的說法,在代數資料型別方法中,**資料擴充不具備模組化特性**。 + +## Java(物件導向) {#java-object-oriented} + +先從一個介面以及每種變體對應的具體類開始。 + +```java +// Expression variants +interface Expr { + int eval(); + String pretty(); +} + +final class Lit implements Expr { + private final int n; + + Lit(int n) { + this.n = n; + } + + public int eval() { + return n; + } + + public String pretty() { + return Integer.toString(n); + } +} + +final class Add implements Expr { + private final Expr a; + private final Expr b; + + Add(Expr a, Expr b) { + this.a = a; + this.b = b; + } + + public int eval() { + return a.eval() + b.eval(); + } + + public String pretty() { + return "(" + a.pretty() + " + " + b.pretty() + ")"; + } +} +``` + +現在,**新增新變體**很容易: + +```java +final class Mul implements Expr { + private final Expr a; + private final Expr b; + + Mul(Expr a, Expr b) { + this.a = a; + this.b = b; + } + + public int eval() { + return a.eval() * b.eval(); + } + + public String pretty() { + return "(" + a.pretty() + " * " + b.pretty() + ")"; + } +} +``` + +但**新增新操作**(例如`size`)則具有侵入性。你必須修改介面與每個類: + +```java +interface Expr { + int eval(); + String pretty(); + int size(); // ✏️ UPDATE: new operation added here +} + +final class Lit implements Expr { + private final int n; + + Lit(int n) { this.n = n; } + + public int eval() { return n; } + public String pretty() { return Integer.toString(n); } + public int size() { return 1; } // ✏️ UPDATE: new method in every class +} + +final class Add implements Expr { + private final Expr a; + private final Expr b; + + Add(Expr a, Expr b) { this.a = a; this.b = b; } + + public int eval() { return a.eval() + b.eval(); } + public String pretty() { return "(" + a.pretty() + " + " + b.pretty() + ")"; } + public int size() { return 1 + a.size() + b.size(); } // ✏️ UPDATE: new method in every class +} + +final class Mul implements Expr { + private final Expr a; + private final Expr b; + + Mul(Expr a, Expr b) { this.a = a; this.b = b; } + + public int eval() { return a.eval() * b.eval(); } + public String pretty() { return "(" + a.pretty() + " * " + b.pretty() + ")"; } + public int size() { return 1 + a.size() + b.size(); } // ✏️ UPDATE: new method in every class +} +``` + +用 Wadler 的說法,在物件導向方法中,**操作擴充不具備模組化特性**。 + +## 總結(Wadler 的觀點) {#summary-wadlers-point} + +* 函式式/代數資料型別風格傾向於**新增新操作**,但不利於**新增新變體**。 +* 物件導向風格傾向於**新增新變體**,但不利於**新增新操作**。 +* 表示式問題要求找到一種設計,使**兩個**維度都能擴充,而不必修改現有程式碼。 + +## Wadler 的解釋與解決方案概覽(1998) {#wadlers-explanation-and-solution-landscape-1998} + +Wadler 將問題表述為:擴充資料型別**的分支**(新變體),並擴充**該資料型別上的函式**(新操作),同時*不重新編譯現有程式碼*,且保留**靜態型別安全**(無需型別轉換)。 + +他用“表格”作比喻: + +* **行** = 分支(變體/構造器) +* **列** = 函式(操作/解釋) + +在**函式式/代數資料型別**環境中,行固定而列易於新增。 +在**物件導向**環境中,列固定而行易於新增。 +挑戰在於讓**兩個方向**都可擴充。 + +## Wadler 提出的解決方案(GJ + 虛擬型別) {#wadlers-proposed-solution-gj--virtual-types} + +Wadler 使用 GJ(泛型 Java)提出一種方案,其中包括: + +* 使用`This`有界引數(`This extends LangF`)模擬**ThisType**。 +* **內部類與介面**按`This`索引(虛擬型別)。 +* A visitor-based structure that allows: + * 透過繼承“語言族”來新增新分支(例如`Plus`) + * 透過新增新存取者來增加操作(例如`Show`) + +訣竅在於引用`This.Exp`與`This.Visitor`,使每個擴充階段都保持型別安全且可以獨立編譯。 + +### 注意事項(Java 內部介面) {#caveat-java-inner-interfaces} + +Wadler 指出,Java 會將內部介面視為**靜態的**,因此破壞了索引技巧。 +他認為放寬這一限制就能使方案可行;但現代 Java 仍未改變這一點(巢狀介面依舊隱式為靜態)。 + +## 提及的其他解決方向 {#other-solution-directions-mentioned} + +1. Corky Cartwright 的方法 要求**逆變擴充**:允許基礎表示式型別替代擴充型別。 這解釋了為何要使用不動點:擴充語言族*不是*原型別的子型別。 + +2. Kim Bruce 的方法 要求使用**高階型別構造器**(將型別構造器作為引數的型別引數化方式)。 GJ 不直接支援這一特性,但 Wadler 認為可以用虛擬型別模擬。 + +3. Krishnamurthi 等人(擴充存取者模式) 透過擴充存取者設計實現。 在他們的 Pizza 環境中**缺少靜態型別**,因此需要動態型別轉換。 + +4. 專用語言擴充 Wadler 提到了兩種依賴於專為該問題設計的語言特性的方案。 它們不如虛擬型別方案通用。 + + +## Wadler 的兩點總結 {#wadlers-two-points} + +Wadler 的郵件清楚地說明了兩點: + +1. 表示式問題是資料擴充與操作擴充之間的**結構性矛盾**。 +2. Solutions are possible, but they tend to require either: + * 可模擬**虛擬型別**的型別系統特性,或 + * 專用語言擴充,或 + * 對靜態型別安全或獨立編譯作出妥協。 + +## 輕量級 Go 方案(2020) {#featherweight-go-solution-2020} + +Wadler 於 1998 年提出並命名了這一問題。之後,輕量級 Go(FG)及其泛型擴充 FGG(輕量級泛型 Go)在一種類似 Go、採用結構化介面與泛型的語言中,給出了具體且完全靜態的解決方案。 + +論文中的方案(圖 8,簡化版)包含兩個結構`Num`與`Plus`,以及兩個操作`Eval`與`String`: + +```go +type Evaler interface { Eval() int } +type Stringer interface { String() string } + +type Num struct { value int } +type Plus(type a Any) struct { left a; right a } + +func (e Num) Eval() int { return e.value } +func (e Plus(type a Evaler)) Eval() int { return e.left.Eval() + e.right.Eval() } + +func (e Num) String() string { return fmt.Sprintf("%d", e.value) } +func (e Plus(type a Stringer)) String() string { + return fmt.Sprintf("(%s+%s)", e.left.String(), e.right.String()) +} + +type Expr interface { Evaler; Stringer } + +var e Expr = Plus(Expr){Num{1}, Num{2}} +``` + +其機制如下: + +* 泛型遞迴表示。`Plus`的子項具有一個型別引數`a`,其唯一約束為`Any`。該結構不繫結到列出所有操作的封閉介面,因此後續仍可新增操作。 +* 針對操作的約束。每個方法宣告都會獨立約束`a`:`Plus(type a Evaler)`用於`Eval`,`Plus(type a Stringer)`用於`String`。這依賴於 FGG 的*協變接收者*:方法接收者的約束可以比型別宣告中的約束更強。 +* 結構化介面。結構只要具有介面的方法就算實作了該介面,因此可以在不修改`Expr`和`Num`的情況下,於之後引入`Plus`。只有在構造值時,才需要確定完整的操作集合(`Plus(Expr){...}`)。 + +新分支只需增加新結構;新操作只需增加新介面與方法。二者都不需要修改或重新編譯現有宣告,也無需型別斷言。 + +## 參考文獻 {#references} + +* Wadler, P.(1998)。*《表示式問題》*。Java-Genericity 郵件列表說明。提出並命名了該問題。 + [https://homepages.inf.ed.ac.uk/wadler/papers/expression/expression.txt](https://homepages.inf.ed.ac.uk/wadler/papers/expression/expression.txt) + +* Griesemer, R., Hu, R., Kokke, W., Lange, J., Taylor, I. L., Toninho, B., Wadler, P. 與 Yoshida, N.(2020)。*《輕量級 Go》*。ACM Program. Lang. 4(OOPSLA)。後續的具體語言方案,見第 2.3 節。 + [https://homepages.inf.ed.ac.uk/wadler/papers/fg/fg.pdf](https://homepages.inf.ed.ac.uk/wadler/papers/fg/fg.pdf) diff --git a/src/concepts/expression-problem.zh.md b/src/concepts/expression-problem.zh.md new file mode 100644 index 0000000..546f3f0 --- /dev/null +++ b/src/concepts/expression-problem.zh.md @@ -0,0 +1,288 @@ + + +# 表达式问题 {#expression-problem} + +```admonish tip title="相关内容" +语义视角:[指称设计](../denotational-design/design.md)、[指称与组合性](../denotational-design/denotations.md) +Rust 中的语义驱动设计:[能力代数](../rust-dd/capability-algebras.md)、[派生含义与组合](../rust-dd/derived-meaning.md) +洞见:[重新审视表达式问题](../insights/expression-problem.md) +``` + +```admonish note title="语义定位" +表达式问题关注表示与操作的模块化扩展。指称设计则更早地提出一个问题:哪些语义词汇与解释值得表示? +``` + +Phil Wadler 提出的表达式问题关注如何在两个维度上**同时**扩展语言,而无须修改现有代码: + +* **添加新的数据变体**(新的表达式形式,也称“语法”)。 +* **添加新的操作**(新的解释,也称“语义”)。 + +核心矛盾: + +* 采用**函数式/代数数据类型**风格时,添加新操作很容易,但添加新变体会造成侵入式修改。 +* 采用**面向对象**风格时,添加新变体很容易,但添加新操作会造成侵入式修改。 + +本节用简短的 Haskell 与 Java 示例展示两面。 + +## Haskell(函数式/代数数据类型) {#haskell-functional--adt} + +先从一个经典的表达式代数数据类型及两种操作开始。 + +```haskell +data Expr + = Lit Int + | Add Expr Expr + +eval :: Expr -> Int +eval (Lit n) = n +eval (Add a b) = eval a + eval b + +pretty :: Expr -> String +pretty (Lit n) = show n +pretty (Add a b) = "(" ++ pretty a ++ " + " ++ pretty b ++ ")" +``` + +现在,**添加新操作**很容易: + +```haskell +size :: Expr -> Int +size (Lit _) = 1 +size (Add a b) = 1 + size a + size b +``` + +但**添加新变体**(例如`Mul`)就要求修改每个函数: + +```haskell +data Expr + = Lit Int + | Add Expr Expr + | Mul Expr Expr + +eval :: Expr -> Int +eval (Lit n) = n +eval (Add a b) = eval a + eval b +eval (Mul a b) = eval a * eval b -- ✏️ UPDATE: new case + +pretty :: Expr -> String +pretty (Lit n) = show n +pretty (Add a b) = "(" ++ pretty a ++ " + " ++ pretty b ++ ")" +pretty (Mul a b) = "(" ++ pretty a ++ " * " ++ pretty b ++ ")" -- ✏️ UPDATE: new case + +size :: Expr -> Int +size (Lit _) = 1 +size (Add a b) = 1 + size a + size b +size (Mul a b) = 1 + size a + size b -- ✏️ UPDATE: new case +``` + +用 Wadler 的说法,在代数数据类型方法中,**数据扩展不具备模块化特性**。 + +## Java(面向对象) {#java-object-oriented} + +先从一个接口以及每种变体对应的具体类开始。 + +```java +// Expression variants +interface Expr { + int eval(); + String pretty(); +} + +final class Lit implements Expr { + private final int n; + + Lit(int n) { + this.n = n; + } + + public int eval() { + return n; + } + + public String pretty() { + return Integer.toString(n); + } +} + +final class Add implements Expr { + private final Expr a; + private final Expr b; + + Add(Expr a, Expr b) { + this.a = a; + this.b = b; + } + + public int eval() { + return a.eval() + b.eval(); + } + + public String pretty() { + return "(" + a.pretty() + " + " + b.pretty() + ")"; + } +} +``` + +现在,**添加新变体**很容易: + +```java +final class Mul implements Expr { + private final Expr a; + private final Expr b; + + Mul(Expr a, Expr b) { + this.a = a; + this.b = b; + } + + public int eval() { + return a.eval() * b.eval(); + } + + public String pretty() { + return "(" + a.pretty() + " * " + b.pretty() + ")"; + } +} +``` + +但**添加新操作**(例如`size`)则具有侵入性。你必须修改接口与每个类: + +```java +interface Expr { + int eval(); + String pretty(); + int size(); // ✏️ UPDATE: new operation added here +} + +final class Lit implements Expr { + private final int n; + + Lit(int n) { this.n = n; } + + public int eval() { return n; } + public String pretty() { return Integer.toString(n); } + public int size() { return 1; } // ✏️ UPDATE: new method in every class +} + +final class Add implements Expr { + private final Expr a; + private final Expr b; + + Add(Expr a, Expr b) { this.a = a; this.b = b; } + + public int eval() { return a.eval() + b.eval(); } + public String pretty() { return "(" + a.pretty() + " + " + b.pretty() + ")"; } + public int size() { return 1 + a.size() + b.size(); } // ✏️ UPDATE: new method in every class +} + +final class Mul implements Expr { + private final Expr a; + private final Expr b; + + Mul(Expr a, Expr b) { this.a = a; this.b = b; } + + public int eval() { return a.eval() * b.eval(); } + public String pretty() { return "(" + a.pretty() + " * " + b.pretty() + ")"; } + public int size() { return 1 + a.size() + b.size(); } // ✏️ UPDATE: new method in every class +} +``` + +用 Wadler 的说法,在面向对象方法中,**操作扩展不具备模块化特性**。 + +## 总结(Wadler 的观点) {#summary-wadlers-point} + +* 函数式/代数数据类型风格倾向于**添加新操作**,但不利于**添加新变体**。 +* 面向对象风格倾向于**添加新变体**,但不利于**添加新操作**。 +* 表达式问题要求找到一种设计,使**两个**维度都能扩展,而不必修改现有代码。 + +## Wadler 的解释与解决方案概览(1998) {#wadlers-explanation-and-solution-landscape-1998} + +Wadler 将问题表述为:扩展数据类型**的分支**(新变体),并扩展**该数据类型上的函数**(新操作),同时*不重新编译现有代码*,且保留**静态类型安全**(无需类型转换)。 + +他用“表格”作比喻: + +* **行** = 分支(变体/构造器) +* **列** = 函数(操作/解释) + +在**函数式/代数数据类型**环境中,行固定而列易于添加。 +在**面向对象**环境中,列固定而行易于添加。 +挑战在于让**两个方向**都可扩展。 + +## Wadler 提出的解决方案(GJ + 虚拟类型) {#wadlers-proposed-solution-gj--virtual-types} + +Wadler 使用 GJ(泛型 Java)提出一种方案,其中包括: + +* 使用`This`有界参数(`This extends LangF`)模拟**ThisType**。 +* **内部类与接口**按`This`索引(虚拟类型)。 +* A visitor-based structure that allows: + * 通过继承“语言族”来添加新分支(例如`Plus`) + * 通过添加新访问者来增加操作(例如`Show`) + +诀窍在于引用`This.Exp`与`This.Visitor`,使每个扩展阶段都保持类型安全且可以独立编译。 + +### 注意事项(Java 内部接口) {#caveat-java-inner-interfaces} + +Wadler 指出,Java 会将内部接口视为**静态的**,因此破坏了索引技巧。 +他认为放宽这一限制就能使方案可行;但现代 Java 仍未改变这一点(嵌套接口依旧隐式为静态)。 + +## 提及的其他解决方向 {#other-solution-directions-mentioned} + +1. Corky Cartwright 的方法 要求**逆变扩展**:允许基础表达式类型替代扩展类型。 这解释了为何要使用不动点:扩展语言族*不是*原类型的子类型。 + +2. Kim Bruce 的方法 要求使用**高阶类型构造器**(将类型构造器作为参数的类型参数化方式)。 GJ 不直接支持这一特性,但 Wadler 认为可以用虚拟类型模拟。 + +3. Krishnamurthi 等人(扩展访问者模式) 通过扩展访问者设计实现。 在他们的 Pizza 环境中**缺少静态类型**,因此需要动态类型转换。 + +4. 专用语言扩展 Wadler 提到了两种依赖于专为该问题设计的语言特性的方案。 它们不如虚拟类型方案通用。 + + +## Wadler 的两点总结 {#wadlers-two-points} + +Wadler 的邮件清楚地说明了两点: + +1. 表达式问题是数据扩展与操作扩展之间的**结构性矛盾**。 +2. Solutions are possible, but they tend to require either: + * 可模拟**虚拟类型**的类型系统特性,或 + * 专用语言扩展,或 + * 对静态类型安全或独立编译作出妥协。 + +## 轻量级 Go 方案(2020) {#featherweight-go-solution-2020} + +Wadler 于 1998 年提出并命名了这一问题。之后,轻量级 Go(FG)及其泛型扩展 FGG(轻量级泛型 Go)在一种类似 Go、采用结构化接口与泛型的语言中,给出了具体且完全静态的解决方案。 + +论文中的方案(图 8,简化版)包含两个结构`Num`与`Plus`,以及两个操作`Eval`与`String`: + +```go +type Evaler interface { Eval() int } +type Stringer interface { String() string } + +type Num struct { value int } +type Plus(type a Any) struct { left a; right a } + +func (e Num) Eval() int { return e.value } +func (e Plus(type a Evaler)) Eval() int { return e.left.Eval() + e.right.Eval() } + +func (e Num) String() string { return fmt.Sprintf("%d", e.value) } +func (e Plus(type a Stringer)) String() string { + return fmt.Sprintf("(%s+%s)", e.left.String(), e.right.String()) +} + +type Expr interface { Evaler; Stringer } + +var e Expr = Plus(Expr){Num{1}, Num{2}} +``` + +其机制如下: + +* 泛型递归表示。`Plus`的子项具有一个类型参数`a`,其唯一约束为`Any`。该结构不绑定到列出所有操作的封闭接口,因此后续仍可添加操作。 +* 针对操作的约束。每个方法声明都会独立约束`a`:`Plus(type a Evaler)`用于`Eval`,`Plus(type a Stringer)`用于`String`。这依赖于 FGG 的*协变接收者*:方法接收者的约束可以比类型声明中的约束更强。 +* 结构化接口。结构只要具有接口的方法就算实现了该接口,因此可以在不修改`Expr`和`Num`的情况下,于之后引入`Plus`。只有在构造值时,才需要确定完整的操作集合(`Plus(Expr){...}`)。 + +新分支只需增加新结构;新操作只需增加新接口与方法。二者都不需要修改或重新编译现有声明,也无需类型断言。 + +## 参考文献 {#references} + +* Wadler, P.(1998)。*《表达式问题》*。Java-Genericity 邮件列表说明。提出并命名了该问题。 + [https://homepages.inf.ed.ac.uk/wadler/papers/expression/expression.txt](https://homepages.inf.ed.ac.uk/wadler/papers/expression/expression.txt) + +* Griesemer, R., Hu, R., Kokke, W., Lange, J., Taylor, I. L., Toninho, B., Wadler, P. 与 Yoshida, N.(2020)。*《轻量级 Go》*。ACM Program. Lang. 4(OOPSLA)。后续的具体语言方案,见第 2.3 节。 + [https://homepages.inf.ed.ac.uk/wadler/papers/fg/fg.pdf](https://homepages.inf.ed.ac.uk/wadler/papers/fg/fg.pdf) diff --git a/src/concepts/free_monad.ar.md b/src/concepts/free_monad.ar.md new file mode 100644 index 0000000..3585315 --- /dev/null +++ b/src/concepts/free_monad.ar.md @@ -0,0 +1,234 @@ + + +# الموناد الحر {#free-monad} + +```admonish tip title="ذات صلة" +التصميم انطلاقًا من المعنى في Rust: [برامج من الرتبة الأولى](../rust-dd/first-order-programs.md)، [المفسرات والآثار](../rust-dd/interpreters.md) +المفاهيم: [أسلوب تمرير الاستمرار](cps.md)، [إزالة الدوال](defunctionalization.md) +الرؤى: [جبر EVM](../insights/evm-alg.md) +``` + +```admonish note title="الموضع الدلالي" +الموناد الحر تمثيل لصياغة التعليمات مع تسلسل مولّد بحرية. ويختار فونكتور التعليمات المفردات سلفًا؛ ثم يرسم المفسر تلك الصياغة إلى مجال دلالي. إنه ترميز قوي واحد، لا تعريف التصميم الدلالي. +``` + +## ما الموناد الحر (نسخة Rust) {#what-is-a-free-monad-rust-version} + +يتيح لك **الموناد الحر** ما يلي: + +* **صِف** البرنامج بوصفه *بيانات*، ولا تشغّله فورًا. +* **فسّر** البرنامج لاحقًا بطريقة أو أكثر. + +تخيله على النحو التالي: + +> شجرة AST لعمليات ذات آثار + `bind`/`flat_map` لربطها في سلسلة. + +افصل بين: + +* **الصياغة** → تعداد للتعليمات. +* **التفسير** → تحويل يحافظ على البنية إلى مجال دلالي مختار. + +تعني «حرة» أن بنية الموناد مولدة من فونكتور `F` من دون إضافة معادلات تتجاوز قوانين الموناد. واختيار `F` يحدد صياغة التعليمات سلفًا؛ أما تفسير البرنامج الناتج فيوفر دلالة بعينها. + +## تنفيذ Rust {#rust-implementation} + +```admonish warning title="ترميز تخطيطي" +لا تدعم Rust معاملات أنواع مباشرة من الرتبة الأعلى، لذلك يحتاج تنفيذ الموناد الحر الإنتاجي إلى آليات إضافية على مستوى الأنواع أو فونكتور تعليمات متخصص. يوضح الكود التالي الشكل المقصود، وليس تنفيذًا عامًا جاهزًا للإدراج. +``` + +### نوع الموناد الحر {#free-monad-type} + +```rust,noplayground +#[derive(Clone)] +enum Free { + Pure(A), + Suspend(F), + FlatMap(Box>, Box Free>), +} + +impl Free { + fn pure(a: A) -> Self { + Free::Pure(a) + } + + fn flat_map(self, f: G) -> Free + where + G: Fn(A) -> Free + 'static, + F: 'static, + { + match self { + Free::Pure(a) => f(a), + Free::Suspend(op) => { + Free::FlatMap(Box::new(Free::Suspend(op)), Box::new(f)) + } + Free::FlatMap(inner, g) => { + Free::FlatMap(inner, Box::new(move |x| g(x).flat_map(f.clone()))) + } + } + } +} +``` + +### لغة DSL: عمليات وحدة التحكم {#dsl-console-operations} + +```rust,noplayground +#[derive(Clone)] +enum Console { + Print(String, A), + ReadLine(fn(String) -> A), +} + +// Smart constructors +fn print_line(s: &str) -> Free, ()> { + Free::Suspend(Console::Print(s.to_string(), ())) +} + +fn read_line() -> Free, String> { + Free::Suspend(Console::ReadLine(|input| Free::Pure(input))) +} +``` + +### المفسر {#interpreter} + +```rust,noplayground +fn run_console(mut prog: Free, A>) -> A { + loop { + match prog { + Free::Pure(a) => return a, + Free::Suspend(Console::Print(s, next)) => { + println!("{}", s); + prog = Free::Pure(next); + } + Free::Suspend(Console::ReadLine(f)) => { + let mut buf = String::new(); + std::io::stdin().read_line(&mut buf).unwrap(); + prog = f(buf.trim().to_string()); + } + Free::FlatMap(inner, cont) => match *inner { + Free::Pure(a) => prog = cont(a), + Free::Suspend(op) => prog = Free::Suspend(op), // minimal handling + _ => unimplemented!(), + }, + } + } +} +``` + +### الاستخدام {#usage} + +```rust,noplayground +fn main() { + let program = + print_line("What is your name?") + .flat_map(|_| read_line()) + .flat_map(|name| print_line(&format!("Hello, {name}!"))); + + run_console(program); +} +``` + +## الخلاصة {#takeaway} + +* **الصياغة** = `enum Console` (التعليمات المحتملة) +* **البرنامج** = `Free` (بيانات تصف الخطوات) +* **التفسير الملموس** = `run_console` +* الفائدة: يمكنك كتابة مفسرات متعددة للبرنامج نفسه، مثل تشغيله عبر IO حقيقي أو تسجيله في ملف أو تجميعه إلى لغة أخرى. + +## علاقته بالاستمراريات وأسلوب تمرير الاستمرار {#correlation-to-continuations-and-cps} + +**أسلوب تمرير الاستمرار (CPS)** طريقة لكتابة البرامج بحيث لا تعيد الدوال قيمًا مباشرة، بل تمرر النتائج إلى دالة أخرى (*الاستمرارية*) التي تمثل «بقية البرنامج». + +**الموناد الحر** هو في الأساس **برنامج كسلسلة من الخطوات**، حيث تقول كل خطوة: + +> «نفّذ هذا، ثم واصل ببقية البرنامج». + +إن «بقية البرنامج» هذه هي بالضبط **الاستمرارية** — دالة تحول النتيجة الحالية إلى الخطوة التالية. + +* في الموناد الحر بـ Rust: + + ```rust,noplayground + Free::FlatMap(Box>, Box Free>) + ``` + + `Box Free>` **هي الاستمرارية**. + +* عندما تفسر مونادًا حرًا، فأنت **تنفذ بأسلوب تمرير الاستمرار**: + + * بدلًا من إرجاع القيم مباشرة، تمررها إلى الاستمرارية التالية. + * تنتهي إلى حلقة من: `current_instruction -> feed result into continuation -> next instruction` +* **علاقة أسلوب تمرير الاستمرار**: + + * *تُرمّز المونادات الحرة أسلوب تمرير الاستمرار في بنية بيانات*. + * أما أسلوب تمرير الاستمرار *فهو تمثيل تدفق التحكم وقت التشغيل* للفكرة نفسها. + +**مقابلة سريعة**: + +| المفهوم | في أسلوب تمرير الاستمرار | في شجرة AST للموناد الحر | +| --- | --- | --- | +| نتيجة الخطوة | وسيط الاستمرارية | `A` في `Fn(A) -> Free` | +| الاستمرارية | الدالة `(A) -> R` | `Box Free>` | +| البرنامج | استمراريات متداخلة | صيغ `FlatMap` متداخلة | +| التنفيذ | استدعاء الدوال | مطابقة الأنماط والاستدعاء | + +## مقابلة أنماط التصميم لدى عصابة الأربعة {#gof-gang-of-four-design-patterns-mapping} + +المونادات الحرة **ليست** من أنماط عصابة الأربعة، لأنها مستمدة من نظرية البرمجة الوظيفية؛ لكنها **تشمل** أو **تحاكي** عدة أنماط: + +| نمط عصابة الأربعة | علاقته بالموناد الحر | +| --- | --- | +| **المفسر** | إن «شجرة AST + التشغيل» هو حرفيًا نمط المفسر؛ ويمنح الموناد الحر شجرة AST ومركّباتها مجانًا. | +| **الأمر** | كل صيغة `enum` في لغة DSL هي كائن أمر. ويربطها الموناد الحر كسلسلة تشبه أمرًا مركبًا. | +| **المركب** | بنية شجرة AST (التعليمات المتداخلة) مركب من الأوامر. | +| **الباني** | سلسلة `.flat_map` بانية متسلسلة للبرامج. | +| **الزائر** | المفسر في جوهره زائر لمجموعة التعليمات. | + +## لماذا يفوق الموناد الحر هذه الأنماط {#why-free-monad--these-patterns} + +* تتطلب أنماط عصابة الأربعة **عملًا يدويًا كائني التوجه**؛ إذ تعرّف فيها الواجهات والفئات وتؤلفها. + +* المونادات الحرة **جبرية**؛ إذ تعرّف *البيانات* للتعليمات و*الدوال* لتفسيرها. + +* وتحصل تلقائيًا على: + + * التسلسل (`flat_map`) + * التركيب + * مفسرات متعددة من دون المساس بالمنطق الأساسي + +**جدول ملخص**: + +| مفهوم الموناد الحر في البرمجة الوظيفية | نمط مكافئ لدى عصابة الأربعة / البرمجة كائنية التوجه | +| --- | --- | +| تعداد التعليمات | الأمر | +| شجرة AST للبرنامج | المركب | +| `flat_map` باني | الباني | +| دالة المفسر | المفسر / الزائر | +| مفسرات متعددة | الاستراتيجية | + +## علاقته بإزالة الدوال {#relation-to-defunctionalization} + +**إزالة الدوال** تحويل برمجي يستبدل الدوال عالية الرتبة ببنية بيانات من الرتبة الأولى تمثل الدوال الممكنة، مع مفسر يطبقها. + +في أسلوب تمرير الاستمرار، تكون الاستمراريات دوالًا عالية الرتبة. ويستبدل تحويل البرنامج بإزالة الدوال تلك الاستمراريات بتعداد لحالات الاستمرارية ودالة `apply` لتشغيلها. + +يمكن ربط الموناد الحر بالاستمراريات بعد إزالة دوالها داخل برنامج محول إلى أسلوب تمرير الاستمرار، وذلك في ترميزات مناسبة: + +1. ابدأ بنسخة من برنامجك بأسلوب تمرير الاستمرار. تُحمل «بقية البرنامج» في دوال الاستمرارية. +2. أزل دوال الاستمرارية واستبدلها بمجموعة منتهية من الحالات في نوع بيانات. +3. يمكن أن يكون لنوع البيانات الناتج من الرتبة الأولى شكل التعليمات والاستمرارية نفسه لتمثيل الموناد الحر. + +**أوجه التشابه الأساسية** + +* ينتج كل من المونادات الحرة وإزالة الدوال تمثيلًا حسابيًا بالبيانات، ويحتاج إلى مفسر لإعطاء تلك البيانات معنى. +* تحتوي صيغة `FlatMap` في الموناد الحر على الاستمرارية؛ وتستبدل إزالة الدوال هذا الإغلاق بحالة في نوع بيانات. + +**الفروق الأساسية** + +| الجانب | إزالة الدوال | الموناد الحر | +| --- | --- | --- | +| الغرض | تقنية مترجم آلية لإزالة الدوال عالية الرتبة | بناء جبري لفصل الصياغة عن الدلالات | +| المدخل | أي برنامج عالي الرتبة، وغالبًا بصيغة تمرير الاستمرار | فونكتور F يصف التعليمات الممكنة | +| المخرجات | تعداد لحالات الدوال مع دالة تطبيق | `Free` شجرة AST ومفسرات | +| هل هو موناد؟ | ليس بالضرورة | موناد دائمًا بحكم البناء | +| النطاق | تحويل عام | نمط برمجة وظيفية محدد | + +**ملخص** إزالة الدوال تقنية تحويل، أما المونادات الحرة فبناء جبري. يرتبطان ارتباطًا وثيقًا في بعض التمثيلات، لكن أحد البناءين لا يستلزم الآخر عمومًا دون افتراضات إضافية. diff --git a/src/concepts/free_monad.de.md b/src/concepts/free_monad.de.md new file mode 100644 index 0000000..1341abd --- /dev/null +++ b/src/concepts/free_monad.de.md @@ -0,0 +1,234 @@ + + +# Freie Monade {#free-monad} + +```admonish tip title="Verwandte Themen" +Design by Meaning in Rust: [Programme erster Ordnung](../rust-dd/first-order-programs.md), [Interpreter und Effekte](../rust-dd/interpreters.md) +Concepts: [Continuation-Passing Style](cps.md), [Defunktionalisierung](defunctionalization.md) +Insights: [EVM-Algebra](../insights/evm-alg.md) +``` + +```admonish note title="Semantische Einordnung" +Eine freie Monade ist eine Repräsentation von Instruktionssyntax mit frei erzeugter Sequenzierung. Der Instruktionsfunktor wählt bereits ein Vokabular; ein Interpreter bildet die Syntax anschließend auf einen semantischen Bereich ab. Sie ist eine leistungsstarke Kodierung, aber nicht die Definition von Denotational Design. +``` + +## Was ist eine freie Monade? (Rust-Version) {#what-is-a-free-monad-rust-version} + +Eine **freie Monade** ermöglicht: + +* Ein Programm als *Daten* zu **beschreiben**, statt es sofort auszuführen. +* Das Programm später auf eine oder mehrere Arten zu **interpretieren**. + +Man kann sie sich vorstellen als: + +> Einen AST nebenwirkungsreicher Operationen + `bind`/`flat_map` zum Verknüpfen. + +Man trennt: + +* **Syntax** → Enum der Instruktionen. +* **Interpretation** → eine strukturtreue Abbildung in einen gewählten semantischen Bereich. + +„Frei“ bedeutet, dass die Monadenstruktur aus einem Funktor `F` erzeugt wird, ohne über die Monadengesetze hinaus zusätzliche Gleichungen einzuführen. Mit der Wahl von `F` ist die Instruktionssyntax bereits festgelegt; die Interpretation des resultierenden Programms liefert eine bestimmte Denotation. + +## Rust-Implementierung {#rust-implementation} + +```admonish warning title="Schematische Kodierung" +Rust bietet keine direkten Typparameter höherer Ordnung. Eine produktive Kodierung freier Monaden benötigt daher zusätzliche Mechanismen auf Typebene oder einen spezialisierten Instruktionsfunktor. Der folgende Code zeigt die beabsichtigte Form; er ist keine sofort einsetzbare generische Implementierung. +``` + +### Typ einer freien Monade {#free-monad-type} + +```rust,noplayground +#[derive(Clone)] +enum Free { + Pure(A), + Suspend(F), + FlatMap(Box>, Box Free>), +} + +impl Free { + fn pure(a: A) -> Self { + Free::Pure(a) + } + + fn flat_map(self, f: G) -> Free + where + G: Fn(A) -> Free + 'static, + F: 'static, + { + match self { + Free::Pure(a) => f(a), + Free::Suspend(op) => { + Free::FlatMap(Box::new(Free::Suspend(op)), Box::new(f)) + } + Free::FlatMap(inner, g) => { + Free::FlatMap(inner, Box::new(move |x| g(x).flat_map(f.clone()))) + } + } + } +} +``` + +### DSL: Konsolenoperationen {#dsl-console-operations} + +```rust,noplayground +#[derive(Clone)] +enum Console { + Print(String, A), + ReadLine(fn(String) -> A), +} + +// Smart constructors +fn print_line(s: &str) -> Free, ()> { + Free::Suspend(Console::Print(s.to_string(), ())) +} + +fn read_line() -> Free, String> { + Free::Suspend(Console::ReadLine(|input| Free::Pure(input))) +} +``` + +### Interpreter {#interpreter} + +```rust,noplayground +fn run_console(mut prog: Free, A>) -> A { + loop { + match prog { + Free::Pure(a) => return a, + Free::Suspend(Console::Print(s, next)) => { + println!("{}", s); + prog = Free::Pure(next); + } + Free::Suspend(Console::ReadLine(f)) => { + let mut buf = String::new(); + std::io::stdin().read_line(&mut buf).unwrap(); + prog = f(buf.trim().to_string()); + } + Free::FlatMap(inner, cont) => match *inner { + Free::Pure(a) => prog = cont(a), + Free::Suspend(op) => prog = Free::Suspend(op), // minimal handling + _ => unimplemented!(), + }, + } + } +} +``` + +### Verwendung {#usage} + +```rust,noplayground +fn main() { + let program = + print_line("What is your name?") + .flat_map(|_| read_line()) + .flat_map(|name| print_line(&format!("Hello, {name}!"))); + + run_console(program); +} +``` + +## Fazit {#takeaway} + +* **Syntax** = `enum Console` (mögliche Instruktionen) +* **Programm** = `Free` (Daten, die Schritte beschreiben) +* **Konkrete Interpretation** = `run_console` +* Vorteil: Dasselbe Programm kann mehrere Interpreter haben — etwa echte IO ausführen, in eine Datei protokollieren oder in eine andere Sprache kompilieren. + +## Zusammenhang mit Fortsetzungen und CPS {#correlation-to-continuations-and-cps} + +**Continuation-Passing Style (CPS)** ist eine Programmierweise, bei der Funktionen Werte nie direkt zurückgeben, sondern die Ergebnisse an eine andere Funktion (die *Fortsetzung*) übergeben, die den „Rest des Programms“ darstellt. + +Eine **freie Monade** ist im Grunde ein **Programm als Folge von Schritten**, wobei jeder Schritt besagt: + +> „Führe dies aus und fahre dann mit dem Rest fort.“ + +Dieser „Rest des Programms“ ist genau eine **Fortsetzung** — eine Funktion vom aktuellen Ergebnis zum nächsten Schritt. + +* In unserer freien Monade in Rust: + + ```rust,noplayground + Free::FlatMap(Box>, Box Free>) + ``` + + `Box Free>` **ist die Fortsetzung**. + +* Wenn du eine freie Monade interpretierst, **führst du sie in CPS aus**: + + * Statt Werte direkt zurückzugeben, übergibst du sie an die nächste Fortsetzung. + * So entsteht eine Schleife aus: `current_instruction -> feed result into continuation -> next instruction` +* **CPS-Zusammenhang**: + + * Freie Monaden *kodieren CPS in einer Datenstruktur*. + * CPS *ist die Laufzeitdarstellung des Kontrollflusses* derselben Idee. + +**Kurzer Überblick**: + +| Konzept | In CPS | Im AST der freien Monade | +| --- | --- | --- | +| Ergebnis des Schritts | Argument der Fortsetzung | `A` in `Fn(A) -> Free` | +| Fortsetzung | Funktion `(A) -> R` | `Box Free>` | +| Programm | Verschachtelte Fortsetzungen | Verschachtelte `FlatMap`\-Varianten | +| Ausführung | Funktionsaufrufe | Pattern Matching und Aufrufe | + +## Zuordnung der GoF-Entwurfsmuster {#gof-gang-of-four-design-patterns-mapping} + +Freie Monaden gehören **nicht** zu den GoF-Mustern, da sie aus der funktionalen Programmierungstheorie stammen. Sie **umfassen** jedoch mehrere Muster oder **bilden** sie nach: + +| GoF-Muster | Beziehung zur freien Monade | +| --- | --- | +| **Interpreter** | Das Gesamtmuster „AST + Ausführung“ ist wörtlich das Interpreter-Muster. Freie Monaden liefern den AST und die Kombinatoren gleich mit. | +| **Befehl** | Jede `enum`\-Variante in der DSL ist ein Befehlsobjekt. Die freie Monade verkettet sie zu einem Makrobefehl. | +| **Kompositum** | Die AST-Struktur (verschachtelte Instruktionen) ist ein Kompositum aus Befehlen. | +| **Builder** | Die `.flat_map`\-Kette bildet einen flüssigen Builder für Programme. | +| **Visitor** | Der Interpreter ist im Wesentlichen ein Visitor über die Instruktionsmenge. | + +## Warum freie Monaden diesen Mustern überlegen sind {#why-free-monad--these-patterns} + +* GoF-Muster erfordern **manuelle objektorientierte Arbeit**: Schnittstellen und Klassen definieren und sie zusammensetzen. + +* Freie Monaden sind **algebraisch**: Man definiert *Daten* für Instruktionen und *Funktionen*, die sie interpretieren. + +* Automatisch erhält man: + + * Sequenzierung (`flat_map`) + * Komposition + * mehrere Interpreter, ohne die Kernlogik anzutasten + +**Zusammenfassungstabelle**: + +| Konzept freier Monaden (funktionale Programmierung) | Äquivalentes GoF-/OO-Muster | +| --- | --- | +| Instruktions-Enum | Befehl | +| Programm-AST | Kompositum | +| `flat_map`\-Builder | Builder | +| Interpreterfunktion | Interpreter / Visitor | +| Mehrere Interpreter | Strategie | + +## Beziehung zur Defunktionalisierung {#relation-to-defunctionalization} + +**Defunktionalisierung** ist eine Programmtransformation, die höherwertige Funktionen durch eine Datenstruktur erster Ordnung ersetzt, welche die möglichen Funktionen darstellt, sowie durch einen Interpreter, der sie anwendet. + +In CPS sind Fortsetzungen höherwertige Funktionen. Defunktionalisierung eines CPS-Programms ersetzt diese Fortsetzungen durch ein Enum ihrer Fälle und eine `apply`\-Funktion, die sie ausführt. + +Bei geeigneten Kodierungen lässt sich eine freie Monade mit defunktionalisierten Fortsetzungen in einem CPS-transformierten Programm in Beziehung setzen: + +1. Beginne mit einer CPS-Version deines Programms. Der „Rest des Programms“ wird in Fortsetzungsfunktionen mitgeführt. +2. Defunktionalisiere diese Fortsetzungsfunktionen zu einer endlichen Menge von Fällen in einem Datentyp. +3. Der resultierende Datentyp erster Ordnung kann dieselbe Struktur aus Instruktionen und Fortsetzungen haben wie eine Repräsentation als freie Monade. + +**Wichtige Ähnlichkeiten** + +* Sowohl freie Monaden als auch Defunktionalisierung erzeugen eine Datenrepräsentation der Berechnung und benötigen einen Interpreter, der diesen Daten Bedeutung verleiht. +* Der `FlatMap`\-Fall einer freien Monade enthält die Fortsetzung; die Defunktionalisierung ersetzt diesen Abschluss durch einen Fall in einem Datentyp. + +**Wichtige Unterschiede** + +| Aspekt | Defunktionalisierung | Freie Monade | +| --- | --- | --- | +| Zweck | Mechanische Compilertechnik zum Entfernen höherwertiger Funktionen | Algebraische Konstruktion zur Trennung von Syntax und Semantik | +| Eingabe | Beliebiges höherwertiges Programm, häufig in CPS-Form | Ein Funktor F, der mögliche Instruktionen beschreibt | +| Ausgabe | Enum der Funktionsfälle plus Anwendungsfunktion | `Free` AST plus Interpreter | +| Monadisch? | Nicht unbedingt | Von der Konstruktion her immer eine Monade | +| Umfang | Allgemeine Transformation | Spezifisches Muster der funktionalen Programmierung | + +**Zusammenfassung** Defunktionalisierung ist eine Transformationstechnik. Freie Monaden sind eine algebraische Konstruktion. In manchen Repräsentationen sind sie eng miteinander verwandt, doch ohne zusätzliche Annahmen lässt sich die eine im Allgemeinen nicht aus der anderen ableiten. diff --git a/src/concepts/free_monad.es.md b/src/concepts/free_monad.es.md new file mode 100644 index 0000000..4ae8478 --- /dev/null +++ b/src/concepts/free_monad.es.md @@ -0,0 +1,234 @@ + + +# Mónada libre {#free-monad} + +```admonish tip title="Relacionado" +Diseño basado en el significado en Rust: [Programas de primer orden](../rust-dd/first-order-programs.md), [Intérpretes y efectos](../rust-dd/interpreters.md) +Conceptos: [Estilo de paso de continuaciones](cps.md), [Defuncionalización](defunctionalization.md) +Perspectivas: [Álgebra EVM](../insights/evm-alg.md) +``` + +```admonish note title="Ubicación semántica" +Una mónada libre es una representación de la sintaxis de instrucciones con una secuenciación generada libremente. El functor de instrucciones ya determina un vocabulario; luego, un intérprete transforma esa sintaxis en un dominio semántico. Es una codificación potente, no la definición del diseño denotacional. +``` + +## Qué es una mónada libre (versión de Rust) {#what-is-a-free-monad-rust-version} + +Una **mónada libre** permite: + +* **Describir** un programa como *datos*, en lugar de ejecutarlo de inmediato. +* **Interpretar** ese programa más adelante de una o varias maneras. + +Imagínala así: + +> Un AST de operaciones con efectos + `bind`/`flat_map` para encadenarlas. + +Separas: + +* **Sintaxis** → enumeración de instrucciones. +* **Interpretación** → aplicación que preserva la estructura y lleva a un dominio semántico elegido. + +«Libre» significa que la estructura de mónada se genera a partir de un functor `F` sin añadir ecuaciones aparte de las leyes de mónada. La elección de `F` ya determina la sintaxis de las instrucciones; al interpretar el programa resultante se obtiene una denotación concreta. + +## Implementación en Rust {#rust-implementation} + +```admonish warning title="Codificación esquemática" +Rust no admite directamente parámetros de tipo de orden superior, por lo que una implementación de producción de una mónada libre necesita maquinaria adicional a nivel de tipos o un functor de instrucciones especializado. El siguiente código ilustra la forma pretendida; no es una implementación genérica lista para usar. +``` + +### Tipo de mónada libre {#free-monad-type} + +```rust,noplayground +#[derive(Clone)] +enum Free { + Pure(A), + Suspend(F), + FlatMap(Box>, Box Free>), +} + +impl Free { + fn pure(a: A) -> Self { + Free::Pure(a) + } + + fn flat_map(self, f: G) -> Free + where + G: Fn(A) -> Free + 'static, + F: 'static, + { + match self { + Free::Pure(a) => f(a), + Free::Suspend(op) => { + Free::FlatMap(Box::new(Free::Suspend(op)), Box::new(f)) + } + Free::FlatMap(inner, g) => { + Free::FlatMap(inner, Box::new(move |x| g(x).flat_map(f.clone()))) + } + } + } +} +``` + +### DSL: operaciones de consola {#dsl-console-operations} + +```rust,noplayground +#[derive(Clone)] +enum Console { + Print(String, A), + ReadLine(fn(String) -> A), +} + +// Smart constructors +fn print_line(s: &str) -> Free, ()> { + Free::Suspend(Console::Print(s.to_string(), ())) +} + +fn read_line() -> Free, String> { + Free::Suspend(Console::ReadLine(|input| Free::Pure(input))) +} +``` + +### Intérprete {#interpreter} + +```rust,noplayground +fn run_console(mut prog: Free, A>) -> A { + loop { + match prog { + Free::Pure(a) => return a, + Free::Suspend(Console::Print(s, next)) => { + println!("{}", s); + prog = Free::Pure(next); + } + Free::Suspend(Console::ReadLine(f)) => { + let mut buf = String::new(); + std::io::stdin().read_line(&mut buf).unwrap(); + prog = f(buf.trim().to_string()); + } + Free::FlatMap(inner, cont) => match *inner { + Free::Pure(a) => prog = cont(a), + Free::Suspend(op) => prog = Free::Suspend(op), // minimal handling + _ => unimplemented!(), + }, + } + } +} +``` + +### Uso {#usage} + +```rust,noplayground +fn main() { + let program = + print_line("What is your name?") + .flat_map(|_| read_line()) + .flat_map(|name| print_line(&format!("Hello, {name}!"))); + + run_console(program); +} +``` + +## Conclusión {#takeaway} + +* **Sintaxis** = `enum Console` (instrucciones posibles) +* **Programa** = `Free` (datos que describen los pasos) +* **Interpretación concreta** = `run_console` +* Ventaja: Puedes escribir varios intérpretes para un mismo programa; por ejemplo, ejecutarlo con IO real, registrarlo en un archivo o compilarlo a otro lenguaje. + +## Relación con las continuaciones y CPS {#correlation-to-continuations-and-cps} + +**El estilo de paso de continuaciones (CPS)** es una forma de escribir programas en la que las funciones nunca devuelven valores directamente, sino que pasan los resultados a otra función (la *continuación*), que representa «el resto del programa». + +Una **mónada libre** es, básicamente, un **programa como secuencia de pasos**, donde cada paso dice: + +> «Haz esto y luego continúa con el resto». + +Ese «resto del programa» es precisamente una **continuación**: una función que transforma el resultado actual en el siguiente paso. + +* En nuestra mónada libre de Rust: + + ```rust,noplayground + Free::FlatMap(Box>, Box Free>) + ``` + + `Box Free>` **es la continuación**. + +* Al interpretar una mónada libre, estás **ejecutando en CPS**: + + * En lugar de devolver los valores directamente, los pasas a la siguiente continuación. + * Se forma un ciclo de: `current_instruction -> feed result into continuation -> next instruction` +* **Relación con CPS**: + + * Las mónadas libres *codifican CPS en una estructura de datos*. + * CPS *es la representación del flujo de control durante la ejecución* de la misma idea. + +**Correspondencias rápidas**: + +| Concepto | En CPS | En el AST de la mónada libre | +| --- | --- | --- | +| Resultado del paso | Argumento de la continuación | `A` en `Fn(A) -> Free` | +| Continuación | Función `(A) -> R` | `Box Free>` | +| Programa | Continuaciones anidadas | Variantes `FlatMap` anidadas | +| Ejecución | Llamadas a funciones | Coincidencia de patrones + llamadas | + +## Correspondencia con los patrones de diseño GoF (Gang of Four) {#gof-gang-of-four-design-patterns-mapping} + +Las mónadas libres **no** forman parte de GoF, porque proceden de la teoría de la programación funcional, pero **abarcan** o **emulan** varios patrones: + +| Patrón GoF | Relación con la mónada libre | +| --- | --- | +| **Intérprete** | Todo el conjunto «AST + ejecutar» corresponde literalmente al patrón Intérprete; las mónadas libres proporcionan gratuitamente el AST y sus combinadores. | +| **Comando** | Cada variante `enum` del DSL es un objeto Comando. La mónada libre los encadena como un macrocomando. | +| **Compuesto** | La estructura del AST (instrucciones anidadas) es un compuesto de comandos. | +| **Constructor** | La cadena `.flat_map` funciona como un constructor fluido de programas. | +| **Visitante** | El intérprete es, en esencia, un visitante del conjunto de instrucciones. | + +## Por qué las mónadas libres superan a estos patrones {#why-free-monad--these-patterns} + +* Los patrones GoF implican **trabajo manual de programación orientada a objetos**: hay que definir interfaces y clases, y componerlas. + +* Las mónadas libres son **algebraicas**: se definen *datos* para las instrucciones y *funciones* para interpretarlas. + +* Se obtienen automáticamente: + + * Secuenciación (`flat_map`) + * Composición + * Varios intérpretes sin tocar la lógica central + +**Tabla resumen**: + +| Concepto de programación funcional de la mónada libre | Patrón equivalente de GoF / POO | +| --- | --- | +| Enumeración de instrucciones | Comando | +| AST del programa | Compuesto | +| Constructor `flat_map` | Constructor | +| Función intérprete | Intérprete / Visitante | +| Varios intérpretes | Estrategia | + +## Relación con la defuncionalización {#relation-to-defunctionalization} + +La **defuncionalización** es una transformación de programas que reemplaza las funciones de orden superior por una estructura de datos de primer orden que representa las funciones posibles, junto con un intérprete que las aplica. + +En CPS, las continuaciones son funciones de orden superior. Defuncionalizar un programa CPS reemplaza esas continuaciones por una enumeración de casos y una función `apply` para ejecutarlos. + +Con codificaciones adecuadas, una mónada libre puede relacionarse con las continuaciones defuncionalizadas de un programa transformado a CPS: + +1. Empieza con una versión CPS del programa. El «resto del programa» se lleva en funciones de continuación. +2. Defuncionaliza esas funciones de continuación en un conjunto finito de casos de un tipo de datos. +3. El tipo de datos de primer orden resultante puede tener la misma forma de instrucciones y continuaciones que una representación de mónada libre. + +**Similitudes clave** + +* Tanto las mónadas libres como la defuncionalización producen una representación de los datos del cálculo y requieren un intérprete que les dé significado. +* El caso `FlatMap` de una mónada libre contiene la continuación; la defuncionalización reemplaza ese cierre por un caso de un tipo de datos. + +**Diferencias clave** + +| Aspecto | Defuncionalización | Mónada libre | +| --- | --- | --- | +| Propósito | Técnica mecánica de compilador para eliminar funciones de orden superior | Construcción algebraica que separa la sintaxis de la semántica | +| Entrada | Cualquier programa de orden superior, a menudo en formato CPS | Un functor F que describe las instrucciones posibles | +| Salida | Enumeración de casos de función más una función de aplicación | AST `Free` más intérpretes | +| ¿Es una mónada? | No necesariamente | Siempre es una mónada por construcción | +| Alcance | Transformación general | Patrón específico de programación funcional | + +**Resumen** La defuncionalización es una técnica de transformación. Las mónadas libres son una construcción algebraica. En algunas representaciones guardan una relación estrecha, pero ninguna de las dos construcciones implica en general la otra sin supuestos adicionales. diff --git a/src/concepts/free_monad.ja.md b/src/concepts/free_monad.ja.md new file mode 100644 index 0000000..ae98c8a --- /dev/null +++ b/src/concepts/free_monad.ja.md @@ -0,0 +1,234 @@ + + +# 自由モナド {#free-monad} + +```admonish tip title="関連項目" +Rustで意味から設計する:[一階プログラム](../rust-dd/first-order-programs.md)、[インタープリターと副作用](../rust-dd/interpreters.md) +概念:[継続渡し形式](cps.md)、[関数のデファンクショナライズ](defunctionalization.md) +洞察:[EVM代数](../insights/evm-alg.md) +``` + +```admonish note title="意味論上の位置付け" +自由モナドは、自由に生成される逐次実行を伴う命令構文の表現です。命令ファンクターがすでに語彙を選び、インタープリターがその構文を意味論的領域へ写像します。強力な符号化の一つではありますが、Denotational Designの定義ではありません。 +``` + +## 自由モナドとは何か(Rust版) {#what-is-a-free-monad-rust-version} + +**自由モナド**を使うと、次のことができます。 + +* **プログラムを*データ*として記述**し、すぐには実行しない。 +* **そのプログラムを後で、一つまたは複数の方法で解釈**する。 + +次のように考えてください。 + +> 副作用のある操作のAST+それらを連結する`bind`/`flat_map`。 + +次のように分けます。 + +* **構文** → 命令の列挙型。 +* **解釈** → 選択した意味論的領域への、構造を保つ写像。 + +「自由」とは、モナドの法則を超える等式を加えず、ファンクター`F`からモナド構造を生成することです。`F`を選ぶと命令構文もすでに決まっています。構築されたプログラムを解釈することで、具体的な表示が与えられます。 + +## Rustでの実装 {#rust-implementation} + +```admonish warning title="模式的な符号化" +Rustには高カインド型の型パラメーターが直接ないため、本番向けの自由モナド符号化には追加の型レベルの仕組みか、専用の命令ファンクターが必要です。次のコードは意図する構造を示すものであり、そのまま使えるジェネリック実装ではありません。 +``` + +### 自由モナド型 {#free-monad-type} + +```rust,noplayground +#[derive(Clone)] +enum Free { + Pure(A), + Suspend(F), + FlatMap(Box>, Box Free>), +} + +impl Free { + fn pure(a: A) -> Self { + Free::Pure(a) + } + + fn flat_map(self, f: G) -> Free + where + G: Fn(A) -> Free + 'static, + F: 'static, + { + match self { + Free::Pure(a) => f(a), + Free::Suspend(op) => { + Free::FlatMap(Box::new(Free::Suspend(op)), Box::new(f)) + } + Free::FlatMap(inner, g) => { + Free::FlatMap(inner, Box::new(move |x| g(x).flat_map(f.clone()))) + } + } + } +} +``` + +### DSL:コンソール操作 {#dsl-console-operations} + +```rust,noplayground +#[derive(Clone)] +enum Console { + Print(String, A), + ReadLine(fn(String) -> A), +} + +// Smart constructors +fn print_line(s: &str) -> Free, ()> { + Free::Suspend(Console::Print(s.to_string(), ())) +} + +fn read_line() -> Free, String> { + Free::Suspend(Console::ReadLine(|input| Free::Pure(input))) +} +``` + +### インタープリター {#interpreter} + +```rust,noplayground +fn run_console(mut prog: Free, A>) -> A { + loop { + match prog { + Free::Pure(a) => return a, + Free::Suspend(Console::Print(s, next)) => { + println!("{}", s); + prog = Free::Pure(next); + } + Free::Suspend(Console::ReadLine(f)) => { + let mut buf = String::new(); + std::io::stdin().read_line(&mut buf).unwrap(); + prog = f(buf.trim().to_string()); + } + Free::FlatMap(inner, cont) => match *inner { + Free::Pure(a) => prog = cont(a), + Free::Suspend(op) => prog = Free::Suspend(op), // minimal handling + _ => unimplemented!(), + }, + } + } +} +``` + +### 使用例 {#usage} + +```rust,noplayground +fn main() { + let program = + print_line("What is your name?") + .flat_map(|_| read_line()) + .flat_map(|name| print_line(&format!("Hello, {name}!"))); + + run_console(program); +} +``` + +## 要点 {#takeaway} + +* **構文**=`enum Console`(考えられる命令) +* **プログラム**=`Free`(手順を記述するデータ) +* **具体的な解釈**=`run_console` +* 利点:同じプログラムに対して複数のインタープリターを記述できます。たとえば、実際のIOで実行する、ファイルに記録する、別の言語へコンパイルする、といったことができます。 + +## 継続およびCPSとの関連 {#correlation-to-continuations-and-cps} + +継続渡し形式(CPS)とは、関数が値を直接返さず、*継続*と呼ばれる別の関数へ結果を渡す形でプログラムを書く方法です。継続は「プログラムの残り」を表します。 + +**自由モナド**とは、基本的に、**手順の列として表したプログラム**です。各手順は次のように述べます。 + +> 「これを実行してから、残りに続く。」 + +この「プログラムの残り」こそが**継続**です。現在の結果から次の手順を返す関数です。 + +* Rustによる自由モナドでは: + + ```rust,noplayground + Free::FlatMap(Box>, Box Free>) + ``` + + `Box Free>`の**が継続**です。 + +* 自由モナドを解釈することは、**CPSで実行すること**です。 + + * 値を直接返す代わりに、次の継続へ渡します。 + * 次のループになります。 `current_instruction -> feed result into continuation -> next instruction` +* **CPSとの関係**: + + * 自由モナドは、*CPSをデータ構造に符号化する*ものです。 + * CPSは、同じ考え方を表す*ランタイムの制御フロー表現*です。 + +**簡易対応表**: + +| 概念 | CPSの場合 | 自由モナドASTの場合 | +| --- | --- | --- | +| ステップの結果 | 継続への引数 | `A`を`Fn(A) -> Free`に渡す | +| 継続 | 関数`(A) -> R` | `Box Free>` | +| プログラム | ネストされた継続 | ネストされた`FlatMap`バリアント | +| 実行 | 関数呼び出し | パターンマッチと呼び出し | + +## GoF(Gang of Four)デザインパターンとの対応 {#gof-gang-of-four-design-patterns-mapping} + +自由モナドは関数型プログラミング理論に由来するため、GoFのパターンでは**ありません**。しかし、いくつかのパターンを**包含**したり、**模倣**したりします。 + +| GoFパターン | 自由モナドとの関係 | +| --- | --- | +| **インタープリター** | 「AST+実行」の全体は文字どおりInterpreterパターンです。自由モナドはASTとコンビネーターを手軽に提供します。 | +| **Command** | DSLの各`enum`バリアントはCommandオブジェクトです。自由モナドはそれらをマクロコマンドのように連鎖させます。 | +| **Composite** | ASTの構造(ネストした命令)はコマンドのCompositeです。 | +| **Builder** | `.flat_map`の連鎖は、プログラムを構築する流れる形式のBuilderです。 | +| **Visitor** | インタープリターは本質的に命令集合へのVisitorです。 | + +## なぜ自由モナドはこれらのパターンより優れるのか {#why-free-monad--these-patterns} + +* GoFのパターンは**手作業によるOOP**です。インターフェース、クラス、合成を定義します。 + +* 自由モナドは**代数的**です。命令を表す*データ*と、それを解釈する*関数*を定義します。 + +* 次のものが自動的に得られます。 + + * 逐次実行(`flat_map`) + * 合成 + * 中核ロジックに触れない複数のインタープリター + +**まとめ表**: + +| 自由モナド(関数型プログラミングの概念) | 対応するGoF/OOPパターン | +| --- | --- | +| 命令の列挙型 | Command | +| プログラムAST | Composite | +| `flat_map`ビルダー | Builder | +| インタープリター関数 | Interpreter/Visitor | +| 複数のインタープリター | Strategy | + +## デファンクショナライズとの関係 {#relation-to-defunctionalization} + +**デファンクショナライズ**とは、高階関数を、それらの関数を表す一階データ構造と、それを適用するインタープリターに置き換えるプログラム変換です。 + +CPSでは継続が高階関数です。CPSプログラムをデファンクショナライズすると、継続が継続ケースの列挙型になり、`apply`実行する関数が用意されます。 + +適切な符号化を使うと、自由モナドを、CPS変換されたプログラム内のデファンクショナライズ済み継続と関連付けられます。 + +1. プログラムをCPS形式にします。「プログラムの残り」は継続関数が保持します。 +2. 継続関数をデファンクショナライズして、データ型の有限個のケースに置き換えます。 +3. こうして得られる一階データ型は、自由モナド表現と同じ命令および継続の形を取ることがあります。 + +**主な類似点** + +* 自由モナドもデファンクショナライズも計算をデータとして表現し、そのデータに意味を与えるためのインタープリターが必要です。 +* 自由モナドの`FlatMap`ケースには継続が格納され、デファンクショナライズではそのクロージャがデータ型のケースに置き換わります。 + +**主な相違点** + +| 観点 | デファンクショナライズ | 自由モナド | +| --- | --- | --- | +| 目的 | 高階関数を取り除くための機械的なコンパイラー技法 | 構文と意味論を分ける代数的な構成 | +| 入力 | 任意の高階プログラム、多くはCPS形式 | 考えられる命令を記述するファンクターF | +| 出力 | 関数ケースの列挙型と適用関数 | `Free` ASTとインタープリター | +| モナドか。 | 必ずしもそうではない | 構成上、常にモナドである | +| 適用範囲 | 一般的な変換 | 特定の関数型プログラミングパターン | + +**まとめ** デファンクショナライズは変換技法、自由モナドは代数的な構成です。一部の表現では密接に関連しますが、追加の仮定がなければ、一般に一方が他方を含意するわけではありません。 diff --git a/src/concepts/free_monad.ko.md b/src/concepts/free_monad.ko.md new file mode 100644 index 0000000..e70f3f5 --- /dev/null +++ b/src/concepts/free_monad.ko.md @@ -0,0 +1,234 @@ + + +# 자유 모나드 {#free-monad} + +```admonish tip title="관련 항목" +Rust에서 의미로 설계하기: [일차 프로그램](../rust-dd/first-order-programs.md), [인터프리터와 효과](../rust-dd/interpreters.md) +개념: [연속 전달 스타일](cps.md), [디펑셔널라이제이션](defunctionalization.md) +통찰: [EVM 대수](../insights/evm-alg.md) +``` + +```admonish note title="의미론적 위치" +자유 모나드는 자유롭게 생성되는 시퀀싱을 갖춘 명령어 구문의 표현입니다. 명령어 펑터가 이미 어휘를 선택하고, 인터프리터가 그 구문을 의미론적 영역으로 대응시킵니다. 이는 강력한 인코딩 하나이지 표시적 설계의 정의는 아닙니다. +``` + +## 자유 모나드란 무엇인가 (Rust 버전) {#what-is-a-free-monad-rust-version} + +**자유 모나드**를 사용하면 다음이 가능합니다: + +* **설명**만 하고 프로그램을 *데이터*로 표현합니다. 즉시 실행하지 않습니다. +* 나중에 프로그램을 한 가지 이상의 방법으로 **해석**합니다. + +다음처럼 생각해 보세요: + +> 효과가 있는 연산의 AST + 연산을 연결하는 `bind`/`flat_map`. + +다음을 분리합니다: + +* **구문** → 명령어 열거형. +* **해석** → 선택한 의미론적 영역으로 가는 구조 보존 사상. + +“자유”란 모나드 법칙 이외의 등식을 추가하지 않고 펑터 `F`에서 모나드 구조를 생성한다는 뜻입니다. `F`를 선택하는 순간 명령어 구문도 정해집니다. 만들어진 프로그램을 해석하면 구체적인 표시가 주어집니다. + +## Rust 구현 {#rust-implementation} + +```admonish warning title="개략적 인코딩" +Rust에는 고차 종류 타입 매개변수가 직접 없으므로 실제 자유 모나드 인코딩에는 추가 타입 수준 장치나 특수화된 명령어 펑터가 필요합니다. 다음 코드는 의도된 형태를 보여 주며 그대로 사용할 수 있는 범용 구현은 아닙니다. +``` + +### 자유 모나드 타입 {#free-monad-type} + +```rust,noplayground +#[derive(Clone)] +enum Free { + Pure(A), + Suspend(F), + FlatMap(Box>, Box Free>), +} + +impl Free { + fn pure(a: A) -> Self { + Free::Pure(a) + } + + fn flat_map(self, f: G) -> Free + where + G: Fn(A) -> Free + 'static, + F: 'static, + { + match self { + Free::Pure(a) => f(a), + Free::Suspend(op) => { + Free::FlatMap(Box::new(Free::Suspend(op)), Box::new(f)) + } + Free::FlatMap(inner, g) => { + Free::FlatMap(inner, Box::new(move |x| g(x).flat_map(f.clone()))) + } + } + } +} +``` + +### DSL: 콘솔 연산 {#dsl-console-operations} + +```rust,noplayground +#[derive(Clone)] +enum Console { + Print(String, A), + ReadLine(fn(String) -> A), +} + +// Smart constructors +fn print_line(s: &str) -> Free, ()> { + Free::Suspend(Console::Print(s.to_string(), ())) +} + +fn read_line() -> Free, String> { + Free::Suspend(Console::ReadLine(|input| Free::Pure(input))) +} +``` + +### 인터프리터 {#interpreter} + +```rust,noplayground +fn run_console(mut prog: Free, A>) -> A { + loop { + match prog { + Free::Pure(a) => return a, + Free::Suspend(Console::Print(s, next)) => { + println!("{}", s); + prog = Free::Pure(next); + } + Free::Suspend(Console::ReadLine(f)) => { + let mut buf = String::new(); + std::io::stdin().read_line(&mut buf).unwrap(); + prog = f(buf.trim().to_string()); + } + Free::FlatMap(inner, cont) => match *inner { + Free::Pure(a) => prog = cont(a), + Free::Suspend(op) => prog = Free::Suspend(op), // minimal handling + _ => unimplemented!(), + }, + } + } +} +``` + +### 사용법 {#usage} + +```rust,noplayground +fn main() { + let program = + print_line("What is your name?") + .flat_map(|_| read_line()) + .flat_map(|name| print_line(&format!("Hello, {name}!"))); + + run_console(program); +} +``` + +## 핵심 요점 {#takeaway} + +* **구문** = 가능한 명령어인 `enum Console` +* **프로그램** = 단계를 기술하는 데이터인 `Free` +* **구체적 해석** = `run_console` +* 장점: 같은 프로그램을 실제 IO로 실행하거나, 파일에 기록하거나, 다른 언어로 컴파일하는 등 여러 인터프리터를 작성할 수 있습니다. + +## 연속 실행 및 CPS와의 관계 {#correlation-to-continuations-and-cps} + +연속 전달 스타일(CPS)은 함수가 값을 직접 반환하지 않고, “프로그램의 나머지”를 나타내는 다른 함수인 *연속 실행*에 결과를 전달하는 방식으로 프로그램을 작성하는 기법입니다. + +**자유 모나드**는 기본적으로 **단계의 시퀀스로 된 프로그램**이며, 각 단계는 다음과 같이 말합니다: + +> “이 작업을 하고, 나머지를 계속 실행하세요.” + +그 “프로그램의 나머지”가 바로 **연속 실행**입니다. 현재 결과를 다음 단계로 전달하는 함수입니다. + +* Rust 자유 모나드에서는: + + ```rust,noplayground + Free::FlatMap(Box>, Box Free>) + ``` + + `Box Free>` **가 연속 실행**입니다. + +* 자유 모나드를 해석할 때는 **CPS로 실행**하는 것입니다: + + * 값을 직접 반환하는 대신 다음 연속 실행에 전달합니다. + * 결국 다음과 같은 반복 구조가 됩니다: `current_instruction -> feed result into continuation -> next instruction` +* **CPS와의 관계**: + + * 자유 모나드는 *CPS를 자료 구조에 인코딩합니다*. + * CPS는 같은 아이디어의 *런타임 제어 흐름 표현*입니다. + +**간단한 대응표**: + +| 개념 | CPS에서 | 자유 모나드 AST에서 | +| --- | --- | --- | +| 단계 결과 | 연속 실행의 인수 | `A`, `Fn(A) -> Free` 안의 | +| 연속 실행 | 함수 `(A) -> R` | `Box Free>` | +| 프로그램 | 중첩된 연속 실행 | 중첩된 `FlatMap` 변형 | +| 실행 | 함수 호출 | 패턴 매칭 후 호출 | + +## GoF(GoF 디자인 패턴) 대응 {#gof-gang-of-four-design-patterns-mapping} + +자유 모나드는 함수형 프로그래밍 이론에서 나온 것이므로 GoF의 **패턴은** 아니지만, 여러 패턴을 **포괄하거나** **모사**합니다: + +| GoF 패턴 | 자유 모나드와의 관계 | +| --- | --- | +| **인터프리터** | “AST + 실행” 전체가 문자 그대로 인터프리터 패턴입니다. 자유 모나드는 AST와 합성자를 무료로 제공합니다. | +| **명령** | DSL의 각 `enum` 변형은 명령 객체입니다. 자유 모나드는 이를 매크로 명령처럼 연결합니다. | +| **컴포지트** | AST 구조(중첩 명령어)는 명령의 컴포지트입니다. | +| **빌더** | `.flat_map` 연결은 프로그램을 위한 유창한 빌더입니다. | +| **비지터** | 인터프리터는 본질적으로 명령어 집합을 순회하는 비지터입니다. | + +## 왜 자유 모나드가 이 패턴들보다 나은가 {#why-free-monad--these-patterns} + +* GoF 패턴은 인터페이스와 클래스를 정의하고 이를 합성하는 **수작업 객체 지향 작업**입니다. + +* 자유 모나드는 **대수적**입니다. 명령어용 *데이터*와 이를 해석할 *함수*를 정의합니다. + +* 다음 기능을 자동으로 얻습니다: + + * 시퀀싱 (`flat_map`) + * 합성 + * 핵심 로직을 수정하지 않는 여러 인터프리터 + +**요약 표**: + +| 자유 모나드의 함수형 프로그래밍 개념 | 동등한 GoF/객체 지향 패턴 | +| --- | --- | +| 명령어 열거형 | 명령 | +| 프로그램 AST | 컴포지트 | +| `flat_map` 빌더 | 빌더 | +| 인터프리터 함수 | 인터프리터/비지터 | +| 여러 인터프리터 | 전략 | + +## 디펑셔널라이제이션과의 관계 {#relation-to-defunctionalization} + +**디펑셔널라이제이션**은 고차 함수를 가능한 함수들의 일차 데이터 구조와 그 데이터에 적용하는 인터프리터로 대체하는 프로그램 변환입니다. + +CPS에서 연속 실행은 고차 함수입니다. CPS 프로그램을 디펑셔널라이즈하면 연속 실행이 사례별 열거형과 이를 실행하는 `apply` 함수로 대체됩니다. + +적절한 인코딩에서는 자유 모나드를 CPS 변환 프로그램 안의 디펑셔널라이즈된 연속 실행과 연결할 수 있습니다: + +1. 프로그램을 CPS 버전으로 시작합니다. “프로그램의 나머지”는 연속 실행 함수에 담깁니다. +2. 그 연속 실행 함수를 데이터 타입의 유한한 사례 집합으로 디펑셔널라이즈합니다. +3. 결과 일차 데이터 타입은 자유 모나드 표현과 같은 명령어 및 연속 실행 형태를 가질 수 있습니다. + +**주요 공통점** + +* 자유 모나드와 디펑셔널라이제이션은 모두 계산을 데이터로 표현하며, 그 데이터에 의미를 부여하는 인터프리터가 필요합니다. +* 자유 모나드의 `FlatMap` 사례에는 연속 실행이 들어 있습니다. 디펑셔널라이제이션은 해당 클로저를 데이터 타입의 사례로 대체합니다. + +**주요 차이점** + +| 관점 | 디펑셔널라이제이션 | 자유 모나드 | +| --- | --- | --- | +| 목적 | 고차 함수를 제거하는 기계적 컴파일러 기법 | 구문과 의미론을 분리하는 대수적 구성 | +| 입력 | 모든 고차 프로그램, 흔히 CPS 형태 | 가능한 명령어를 기술하는 펑터 F | +| 출력 | 함수 사례의 열거형과 적용 함수 | `Free` AST와 인터프리터 | +| 모나드인가? | 반드시 그렇지는 않음 | 구성 방식상 항상 모나드 | +| 범위 | 일반적인 변환 | 특정 함수형 프로그래밍 패턴 | + +**요약** 디펑셔널라이제이션은 변환 기법이고 자유 모나드는 대수적 구성입니다. 일부 표현에서는 서로 밀접하게 관련되지만, 추가 가정 없이 어느 한쪽에서 다른 쪽이 일반적으로 따라오지는 않습니다. diff --git a/src/concepts/free_monad.ru.md b/src/concepts/free_monad.ru.md new file mode 100644 index 0000000..ef43c24 --- /dev/null +++ b/src/concepts/free_monad.ru.md @@ -0,0 +1,234 @@ + + +# Свободная монада {#free-monad} + +```admonish tip title="Связанные материалы" +«Проектирование на основе смысла в Rust»: [Программы первого порядка](../rust-dd/first-order-programs.md), [Интерпретаторы и эффекты](../rust-dd/interpreters.md) +«Понятия»: [Стиль передачи продолжений](cps.md), [Дефункционализация](defunctionalization.md) +«Идеи»: [Алгебра EVM](../insights/evm-alg.md) +``` + +```admonish note title="Семантическое место" +Свободная монада — это представление синтаксиса инструкций со свободно порождаемой последовательностью их выполнения. Функтор инструкций уже задаёт словарь; затем интерпретатор отображает этот синтаксис в семантическую область. Это один из мощных способов кодирования, но не определение денотационного проектирования. +``` + +## Что такое свободная монада (версия на Rust) {#what-is-a-free-monad-rust-version} + +**Свободная монада** позволяет: + +* **Описать** программу как *данные* — не выполняя её сразу. +* Позднее **интерпретировать** эту программу одним или несколькими способами. + +Представьте себе: + +> AST эффектных операций + `bind`/`flat_map` для их цепочки. + +Разделяются: + +* **Синтаксис** → перечисление инструкций. +* **Интерпретация** → отображение в выбранную семантическую область, сохраняющее структуру. + +Слово «свободная» означает, что структура монады порождается функтором `F` без добавления уравнений, кроме законов монады. Выбор `F` уже задаёт синтаксис инструкций; интерпретация полученной программы задаёт конкретную денотацию. + +## Реализация на Rust {#rust-implementation} + +```admonish warning title="Схематичное кодирование" +В Rust нет прямых параметров типов высшего рода, поэтому для промышленного кодирования свободной монады нужны дополнительные типовые механизмы или специализированный функтор инструкций. Следующий код иллюстрирует предполагаемую структуру, а не является готовой обобщённой реализацией. +``` + +### Тип свободной монады {#free-monad-type} + +```rust,noplayground +#[derive(Clone)] +enum Free { + Pure(A), + Suspend(F), + FlatMap(Box>, Box Free>), +} + +impl Free { + fn pure(a: A) -> Self { + Free::Pure(a) + } + + fn flat_map(self, f: G) -> Free + where + G: Fn(A) -> Free + 'static, + F: 'static, + { + match self { + Free::Pure(a) => f(a), + Free::Suspend(op) => { + Free::FlatMap(Box::new(Free::Suspend(op)), Box::new(f)) + } + Free::FlatMap(inner, g) => { + Free::FlatMap(inner, Box::new(move |x| g(x).flat_map(f.clone()))) + } + } + } +} +``` + +### DSL: операции консоли {#dsl-console-operations} + +```rust,noplayground +#[derive(Clone)] +enum Console { + Print(String, A), + ReadLine(fn(String) -> A), +} + +// Smart constructors +fn print_line(s: &str) -> Free, ()> { + Free::Suspend(Console::Print(s.to_string(), ())) +} + +fn read_line() -> Free, String> { + Free::Suspend(Console::ReadLine(|input| Free::Pure(input))) +} +``` + +### Интерпретатор {#interpreter} + +```rust,noplayground +fn run_console(mut prog: Free, A>) -> A { + loop { + match prog { + Free::Pure(a) => return a, + Free::Suspend(Console::Print(s, next)) => { + println!("{}", s); + prog = Free::Pure(next); + } + Free::Suspend(Console::ReadLine(f)) => { + let mut buf = String::new(); + std::io::stdin().read_line(&mut buf).unwrap(); + prog = f(buf.trim().to_string()); + } + Free::FlatMap(inner, cont) => match *inner { + Free::Pure(a) => prog = cont(a), + Free::Suspend(op) => prog = Free::Suspend(op), // minimal handling + _ => unimplemented!(), + }, + } + } +} +``` + +### Использование {#usage} + +```rust,noplayground +fn main() { + let program = + print_line("What is your name?") + .flat_map(|_| read_line()) + .flat_map(|name| print_line(&format!("Hello, {name}!"))); + + run_console(program); +} +``` + +## Вывод {#takeaway} + +* **Синтаксис** = `enum Console` (возможные инструкции) +* **Программа** = `Free` (данные, описывающие шаги) +* **Конкретная интерпретация** = `run_console` +* Преимущество: одну программу можно запускать через разные интерпретаторы — например, выполнять реальные операции ввода-вывода, записывать их в файл или компилировать в другой язык. + +## Связь с продолжениями и CPS {#correlation-to-continuations-and-cps} + +**Стиль передачи продолжений (CPS)** — способ писать программы, в котором функции не возвращают значения напрямую, а передают результат другой функции (*продолжению*), представляющему «остаток программы». + +**Свободная монада** — это по сути **программа как последовательность шагов**, где каждый шаг говорит: + +> «Сделай это, затем продолжи оставшуюся часть». + +Именно эта «оставшаяся часть программы» и есть **продолжение** — функция, отображающая текущий результат в следующий шаг. + +* В нашей свободной монаде на Rust: + + ```rust,noplayground + Free::FlatMap(Box>, Box Free>) + ``` + + `Box Free>` **и есть продолжение**. + +* При интерпретации свободной монады вы **выполняете программу в стиле CPS**: + + * Вместо прямого возврата значений вы передаёте их следующему продолжению. + * Получается цикл из: `current_instruction -> feed result into continuation -> next instruction` +* **Связь с CPS**: + + * Свободные монады *кодируют CPS в структуре данных*. + * CPS *представляет ту же идею как поток управления во время выполнения*. + +**Краткое соответствие**: + +| Понятие | В CPS | В AST свободной монады | +| --- | --- | --- | +| Результат шага | Аргумент продолжения | `A` в `Fn(A) -> Free` | +| Продолжение | Функция `(A) -> R` | `Box Free>` | +| Программа | Вложенные продолжения | Вложенные варианты `FlatMap` | +| Выполнение | Вызов функций | Сопоставление с образцом + вызов | + +## Соответствия паттернам GoF (Gang of Four) {#gof-gang-of-four-design-patterns-mapping} + +Свободные монады **не** относятся к паттернам GoF, поскольку происходят из теории функционального программирования, но они **обобщают** или **имитируют** несколько паттернов: + +| Паттерн GoF | Связь со свободной монадой | +| --- | --- | +| **Интерпретатор** | Вся конструкция «AST + запуск» буквально соответствует паттерну Интерпретатор: свободные монады просто предоставляют AST и комбинаторы. | +| **Команда** | Каждый вариант `enum` в DSL — объект-команда. Свободная монада выстраивает их в цепочку, подобно макрокоманде. | +| **Компоновщик** | Структура AST (вложенные инструкции) представляет собой компоновщик команд. | +| **Строитель** | Цепочка `.flat_map` — удобный интерфейс для последовательного построения программ. | +| **Посетитель** | Интерпретатор по сути является посетителем набора инструкций. | + +## Почему свободные монады шире этих паттернов {#why-free-monad--these-patterns} + +* Паттерны GoF требуют **ручной объектно-ориентированной работы**: нужно определить интерфейсы и классы, а затем скомпоновать их. + +* Свободные монады имеют **алгебраическую природу**: вы определяете *данные* для инструкций и *функции* для их интерпретации. + +* Автоматически предоставляются: + + * Последовательное выполнение (`flat_map`) + * Композиция + * Несколько интерпретаторов без изменений основной логики + +**Сводная таблица**: + +| Понятие ФП: свободная монада | Эквивалентный паттерн GoF/ООП | +| --- | --- | +| Перечисление инструкций | Команда | +| AST программы | Компоновщик | +| Цепочка-`flat_map` | Строитель | +| Функция-интерпретатор | Интерпретатор / Посетитель | +| Несколько интерпретаторов | Стратегия | + +## Связь с дефункционализацией {#relation-to-defunctionalization} + +**Дефункционализация** — преобразование программы, заменяющее функции высшего порядка структурой данных первого порядка, представляющей возможные функции, и интерпретатором, который их применяет. + +В CPS продолжения являются функциями высшего порядка. Дефункционализация программы в стиле CPS заменяет такие продолжения перечислением вариантов продолжения и функцией `apply` для их выполнения. + +При подходящем кодировании свободную монаду можно связать с дефункционализированными продолжениями внутри CPS-программы: + +1. Начните с версии программы в стиле CPS. «Остаток программы» хранится в функциях-продолжениях. +2. Преобразуйте эти функции-продолжения в конечный набор вариантов типа данных. +3. Полученный тип данных первого порядка может иметь ту же структуру инструкций и продолжений, что и представление свободной монады. + +**Основные сходства** + +* И свободные монады, и дефункционализация создают представление вычисления в виде данных и требуют интерпретатора, чтобы придать этим данным смысл. +* Вариант `FlatMap` свободной монады содержит продолжение; дефункционализация заменяет замыкание соответствующим вариантом типа данных. + +**Основные различия** + +| Аспект | Дефункционализация | Свободная монада | +| --- | --- | --- | +| Назначение | Механический приём компилятора для устранения функций высшего порядка | Алгебраическое построение для разделения синтаксиса и семантики | +| Вход | Любая программа высшего порядка, часто в форме CPS | Функтор F, описывающий возможные инструкции | +| Результат | Перечисление вариантов функций и функция применения | `Free` AST и интерпретаторы | +| Является ли монадой? | Не обязательно | По построению всегда является монадой | +| Область применения | Общее преобразование | Конкретный паттерн функционального программирования | + +**Итог** Дефункционализация — приём преобразования. Свободные монады — алгебраическое построение. В некоторых представлениях они тесно связаны, но в общем случае ни одно из построений не следует из другого без дополнительных предположений. diff --git a/src/concepts/free_monad.uk.md b/src/concepts/free_monad.uk.md new file mode 100644 index 0000000..920b5f7 --- /dev/null +++ b/src/concepts/free_monad.uk.md @@ -0,0 +1,234 @@ + + +# Вільна монада {#free-monad} + +```admonish tip title="Пов’язані матеріали" +Проєктування від значення в Rust: [Програми першого порядку](../rust-dd/first-order-programs.md), [Інтерпретатори й ефекти](../rust-dd/interpreters.md) +Поняття: [Стиль передавання продовжень](cps.md), [Дефункціоналізація](defunctionalization.md) +Інсайти: [Алгебра EVM](../insights/evm-alg.md) +``` + +```admonish note title="Семантичне місце" +Вільна монада — це представлення синтаксису інструкцій із вільно згенерованим послідовним виконанням. Функтор інструкцій уже визначає термінологію, а інтерпретатор відображає цей синтаксис у семантичну область. Це один потужний спосіб кодування, а не визначення денотаційного проєктування. +``` + +## Що таке вільна монада (версія для Rust) {#what-is-a-free-monad-rust-version} + +**Вільна монада** дає змогу: + +* **Описати** програму як *дані* — не запускаючи її відразу. +* **Пізніше інтерпретувати** цю програму одним чи кількома способами. + +Уявіть собі: + +> AST операцій з ефектами + `bind`/`flat_map` для їхнього поєднання в ланцюжок. + +Розділяються: + +* **Синтаксис** → перелік інструкцій. +* **Інтерпретація** → відображення зі збереженням структури у вибрану семантичну область. + +«Вільна» означає, що структура монади породжується з функтора `F` без додавання рівностей, крім законів монади. Вибір `F` уже визначає синтаксис інструкцій; інтерпретація створеної програми надає їй конкретну денотацію. + +## Реалізація в Rust {#rust-implementation} + +```admonish warning title="Схематичне кодування" +У Rust немає прямих параметрів типу вищого порядку, тому для виробничого кодування вільної монади потрібні додаткові механізми на рівні типів або спеціалізований функтор інструкцій. Наведений код ілюструє задуману форму, але це не готова універсальна реалізація. +``` + +### Тип вільної монади {#free-monad-type} + +```rust,noplayground +#[derive(Clone)] +enum Free { + Pure(A), + Suspend(F), + FlatMap(Box>, Box Free>), +} + +impl Free { + fn pure(a: A) -> Self { + Free::Pure(a) + } + + fn flat_map(self, f: G) -> Free + where + G: Fn(A) -> Free + 'static, + F: 'static, + { + match self { + Free::Pure(a) => f(a), + Free::Suspend(op) => { + Free::FlatMap(Box::new(Free::Suspend(op)), Box::new(f)) + } + Free::FlatMap(inner, g) => { + Free::FlatMap(inner, Box::new(move |x| g(x).flat_map(f.clone()))) + } + } + } +} +``` + +### DSL: операції консолі {#dsl-console-operations} + +```rust,noplayground +#[derive(Clone)] +enum Console { + Print(String, A), + ReadLine(fn(String) -> A), +} + +// Smart constructors +fn print_line(s: &str) -> Free, ()> { + Free::Suspend(Console::Print(s.to_string(), ())) +} + +fn read_line() -> Free, String> { + Free::Suspend(Console::ReadLine(|input| Free::Pure(input))) +} +``` + +### Інтерпретатор {#interpreter} + +```rust,noplayground +fn run_console(mut prog: Free, A>) -> A { + loop { + match prog { + Free::Pure(a) => return a, + Free::Suspend(Console::Print(s, next)) => { + println!("{}", s); + prog = Free::Pure(next); + } + Free::Suspend(Console::ReadLine(f)) => { + let mut buf = String::new(); + std::io::stdin().read_line(&mut buf).unwrap(); + prog = f(buf.trim().to_string()); + } + Free::FlatMap(inner, cont) => match *inner { + Free::Pure(a) => prog = cont(a), + Free::Suspend(op) => prog = Free::Suspend(op), // minimal handling + _ => unimplemented!(), + }, + } + } +} +``` + +### Використання {#usage} + +```rust,noplayground +fn main() { + let program = + print_line("What is your name?") + .flat_map(|_| read_line()) + .flat_map(|name| print_line(&format!("Hello, {name}!"))); + + run_console(program); +} +``` + +## Висновок {#takeaway} + +* **Синтаксис** = `enum Console` (можливі інструкції) +* **Програма** = `Free` (дані, що описують кроки) +* **Конкретна інтерпретація** = `run_console` +* Перевага: для тієї самої програми можна створити кілька інтерпретаторів — наприклад, виконати реальні операції вводу-виводу, записати журнал у файл або скомпілювати її іншою мовою. + +## Зв’язок із продовженнями та CPS {#correlation-to-continuations-and-cps} + +**Стиль передавання продовжень (CPS)** — це спосіб писати програми, у якому функції не повертають значення безпосередньо, а передають результат іншій функції — *продовженню*, що представляє «решту програми». + +**Вільна монада** — це, по суті, **програма як послідовність кроків**, де кожен крок каже: + +> «Зроби це, а потім продовжуй решту». + +Ця «решта програми» і є **продовженням** — функцією, яка перетворює поточний результат на наступний крок. + +* У нашій вільній монаді для Rust: + + ```rust,noplayground + Free::FlatMap(Box>, Box Free>) + ``` + + `Box Free>` **є продовженням**. + +* Інтерпретуючи вільну монаду, ми **виконуємо код у CPS**: + + * Замість прямого повернення значень ми передаємо їх наступному продовженню. + * У результаті маємо цикл із: `current_instruction -> feed result into continuation -> next instruction` +* **Зв’язок із CPS**: + + * Вільні монади *кодують CPS у структурі даних*. + * CPS *є представленням потоку керування під час виконання* тієї самої ідеї. + +**Коротка відповідність**: + +| Поняття | У CPS | В AST вільної монади | +| --- | --- | --- | +| Результат кроку | Аргумент продовження | `A` у `Fn(A) -> Free` | +| Продовження | Функція `(A) -> R` | `Box Free>` | +| Програма | Вкладені продовження | Вкладені варіанти `FlatMap` | +| Виконання | Виклик функцій | Зіставлення з шаблоном і виклик | + +## Відповідність патернам GoF (Банди чотирьох) {#gof-gang-of-four-design-patterns-mapping} + +Вільні монади **не** належать до патернів GoF, адже походять із теорії функційного програмування. Однак вони **узагальнюють** або **імітують** кілька патернів: + +| Патерн GoF | Зв’язок із вільною монадами | +| --- | --- | +| **Інтерпретатор** | Конструкція «AST + виконання» буквально відповідає патерну Interpreter — вільні монади просто надають AST і комбінатори. | +| **Команда** | Кожен варіант `enum` у DSL — це об’єкт-команда. Вільна монада поєднує їх, наче макрокоманду. | +| **Компоновщик** | Структура AST (вкладені інструкції) утворює композицію команд. | +| **Будівельник** | Ланцюжок `.flat_map` — це плавний будівельник програм. | +| **Відвідувач** | Інтерпретатор по суті обходить набір інструкцій як відвідувач. | + +## Чим вільна монада краща за ці патерни? {#why-free-monad--these-patterns} + +* Патерни GoF — це **ручна робота в ООП**: потрібно визначати інтерфейси й класи та поєднувати їх. + +* Вільні монади є **алгебраїчними**: ви визначаєте *дані* для інструкцій і *функції* для їх інтерпретації. + +* Автоматично отримуємо: + + * послідовність виконання (`flat_map`) + * композицію + * кілька інтерпретаторів без зміни основної логіки + +**Підсумкова таблиця**: + +| Поняття з функційного програмування — вільна монада | Відповідний патерн GoF / ООП | +| --- | --- | +| Перелік інструкцій | Команда | +| AST програми | Компоновщик | +| `flat_map` | Будівельник | +| Функція інтерпретатора | Інтерпретатор / відвідувач | +| Кілька інтерпретаторів | Стратегія | + +## Зв’язок із дефункціоналізацією {#relation-to-defunctionalization} + +**Дефункціоналізація** — це перетворення програми, яке замінює функції вищого порядку структурою даних першого порядку з представленням можливих функцій і інтерпретатором, що їх застосовує. + +У CPS продовження є функціями вищого порядку. Дефункціоналізація програми CPS замінює ці продовження переліком їхніх варіантів і функцією `apply`, яка їх виконує. + +За відповідного кодування вільну монаду можна пов’язати з дефункціоналізованими продовженнями у програмі, перетвореній на CPS: + +1. Почніть із версії програми в CPS. «Решту програми» містять функції-продовження. +2. Дефункціоналізуйте функції-продовження, замінивши їх скінченною множиною варіантів типу даних. +3. Отриманий тип даних першого порядку може мати таку саму форму інструкцій і продовжень, як і представлення вільної монади. + +**Основні подібності** + +* І вільні монади, і дефункціоналізація створюють представлення обчислення у вигляді даних та потребують інтерпретатора, який надасть цим даним значення. +* Варіант `FlatMap` вільної монади містить продовження; дефункціоналізація замінює це замикання варіантом типу даних. + +**Основні відмінності** + +| Аспект | Дефункціоналізація | Вільна монада | +| --- | --- | --- | +| Мета | Механічний прийом компілятора для усунення функцій вищого порядку | Алгебраїчна конструкція для відокремлення синтаксису від семантики | +| Вхідні дані | Будь-яка програма вищого порядку, часто у формі CPS | Функтор F, що описує можливі інструкції | +| Результат | Перелік варіантів функцій і функція застосування | `Free` AST і інтерпретатори | +| Монада? | Не обов’язково | Завжди є монадою за побудовою | +| Область застосування | Загальне перетворення | Конкретний патерн функційного програмування | + +**Підсумок** Дефункціоналізація — це техніка перетворення, а вільні монади — алгебраїчна конструкція. У деяких представленнях вони тісно пов’язані, але загалом жодна конструкція не означає автоматичної наявності іншої без додаткових припущень. diff --git a/src/concepts/free_monad.vi.md b/src/concepts/free_monad.vi.md new file mode 100644 index 0000000..729db09 --- /dev/null +++ b/src/concepts/free_monad.vi.md @@ -0,0 +1,234 @@ + + +# Monad tự do {#free-monad} + +```admonish tip title="Liên quan" +Thiết kế theo ngữ nghĩa trong Rust: [Chương trình bậc nhất](../rust-dd/first-order-programs.md), [Bộ diễn giải và hiệu ứng](../rust-dd/interpreters.md) +Khái niệm: [Phong cách truyền tiếp nối](cps.md), [Phi chức năng hóa](defunctionalization.md) +Nhận định: [Đại số EVM](../insights/evm-alg.md) +``` + +```admonish note title="Vị trí ngữ nghĩa" +Monad tự do là cách biểu diễn cú pháp lệnh cùng phép tuần tự hóa được sinh tự do. Bộ thông dịch lệnh đã chọn một từ vựng; sau đó bộ diễn giải ánh xạ cú pháp này vào miền ngữ nghĩa. Đây là một cách mã hóa mạnh mẽ, không phải định nghĩa của Thiết kế theo ngữ nghĩa. +``` + +## Monad tự do là gì (phiên bản Rust) {#what-is-a-free-monad-rust-version} + +**Monad tự do** cho phép bạn: + +* **Mô tả** chương trình dưới dạng *dữ liệu* — thay vì chạy ngay lập tức. +* **Diễn giải** chương trình đó về sau theo một hoặc nhiều cách. + +Hãy hình dung nó như sau: + +> AST của các phép toán có hiệu ứng + `bind`/`flat_map` để nối chúng lại. + +Bạn tách biệt: + +* **Cú pháp** → enum các lệnh. +* **Cách diễn giải** → ánh xạ bảo toàn cấu trúc vào miền ngữ nghĩa đã chọn. + +“Tự do” nghĩa là cấu trúc monad được sinh từ một functor `F` mà không thêm phương trình nào ngoài các định luật monad. Việc chọn `F` đã chọn cú pháp lệnh; diễn giải chương trình thu được sẽ cung cấp một ngữ nghĩa chỉ định cụ thể. + +## Triển khai bằng Rust {#rust-implementation} + +```admonish warning title="Cách mã hóa sơ đồ" +Rust không có tham số kiểu bậc cao trực tiếp, vì vậy cách mã hóa monad tự do dùng trong sản phẩm cần thêm cơ chế cấp kiểu hoặc một functor lệnh chuyên biệt. Đoạn mã sau minh họa hình dạng dự định; không phải triển khai tổng quát có thể dùng ngay. +``` + +### Kiểu monad tự do {#free-monad-type} + +```rust,noplayground +#[derive(Clone)] +enum Free { + Pure(A), + Suspend(F), + FlatMap(Box>, Box Free>), +} + +impl Free { + fn pure(a: A) -> Self { + Free::Pure(a) + } + + fn flat_map(self, f: G) -> Free + where + G: Fn(A) -> Free + 'static, + F: 'static, + { + match self { + Free::Pure(a) => f(a), + Free::Suspend(op) => { + Free::FlatMap(Box::new(Free::Suspend(op)), Box::new(f)) + } + Free::FlatMap(inner, g) => { + Free::FlatMap(inner, Box::new(move |x| g(x).flat_map(f.clone()))) + } + } + } +} +``` + +### DSL: các thao tác bảng điều khiển {#dsl-console-operations} + +```rust,noplayground +#[derive(Clone)] +enum Console { + Print(String, A), + ReadLine(fn(String) -> A), +} + +// Smart constructors +fn print_line(s: &str) -> Free, ()> { + Free::Suspend(Console::Print(s.to_string(), ())) +} + +fn read_line() -> Free, String> { + Free::Suspend(Console::ReadLine(|input| Free::Pure(input))) +} +``` + +### Bộ diễn giải {#interpreter} + +```rust,noplayground +fn run_console(mut prog: Free, A>) -> A { + loop { + match prog { + Free::Pure(a) => return a, + Free::Suspend(Console::Print(s, next)) => { + println!("{}", s); + prog = Free::Pure(next); + } + Free::Suspend(Console::ReadLine(f)) => { + let mut buf = String::new(); + std::io::stdin().read_line(&mut buf).unwrap(); + prog = f(buf.trim().to_string()); + } + Free::FlatMap(inner, cont) => match *inner { + Free::Pure(a) => prog = cont(a), + Free::Suspend(op) => prog = Free::Suspend(op), // minimal handling + _ => unimplemented!(), + }, + } + } +} +``` + +### Cách dùng {#usage} + +```rust,noplayground +fn main() { + let program = + print_line("What is your name?") + .flat_map(|_| read_line()) + .flat_map(|name| print_line(&format!("Hello, {name}!"))); + + run_console(program); +} +``` + +## Điểm chính {#takeaway} + +* **Cú pháp** = `enum Console` (các lệnh có thể có) +* **Chương trình** = `Free` (dữ liệu mô tả các bước) +* **Cách diễn giải cụ thể** = `run_console` +* Lợi ích: Bạn có thể viết nhiều bộ diễn giải cho cùng một chương trình — ví dụ chạy với IO thật, ghi nhật ký vào tệp hoặc biên dịch sang ngôn ngữ khác. + +## Tương quan với tiếp nối và CPS {#correlation-to-continuations-and-cps} + +**Phong cách truyền tiếp nối (CPS)** là cách viết chương trình trong đó hàm không bao giờ trả giá trị trực tiếp mà truyền kết quả cho một hàm khác (*tiếp nối*) biểu thị “phần còn lại của chương trình”. + +**Monad tự do** về cơ bản là một **chương trình dưới dạng chuỗi bước**, trong đó mỗi bước nói rằng: + +> “Làm việc này, rồi tiếp tục với phần còn lại.” + +“Phần còn lại của chương trình” đó chính là một **tiếp nối** — hàm ánh xạ kết quả hiện tại sang bước tiếp theo. + +* Trong monad tự do Rust của chúng ta: + + ```rust,noplayground + Free::FlatMap(Box>, Box Free>) + ``` + + `Box Free>` **là tiếp nối**. + +* Khi diễn giải monad tự do, bạn đang **chạy theo CPS**: + + * Thay vì trả về giá trị trực tiếp, bạn truyền chúng vào tiếp nối kế tiếp. + * Kết quả là một vòng lặp gồm: `current_instruction -> feed result into continuation -> next instruction` +* **Quan hệ CPS**: + + * Monad tự do *mã hóa CPS trong một cấu trúc dữ liệu*. + * CPS *là cách biểu diễn luồng điều khiển lúc chạy* của cùng ý tưởng. + +**Bảng đối chiếu nhanh**: + +| Khái niệm | Trong CPS | Trong AST monad tự do | +| --- | --- | --- | +| Kết quả bước | Đối số cho tiếp nối | `A` trong `Fn(A) -> Free` | +| Tiếp nối | Hàm `(A) -> R` | `Box Free>` | +| Chương trình | Tiếp nối lồng nhau | Các biến thể `FlatMap` lồng nhau | +| Thực thi | Gọi hàm | Đối sánh mẫu + gọi | + +## Ánh xạ với các mẫu thiết kế GoF (Gang of Four) {#gof-gang-of-four-design-patterns-mapping} + +Monad tự do **không thuộc** GoF vì chúng bắt nguồn từ lý thuyết lập trình hàm, nhưng chúng **bao hàm** hoặc **mô phỏng** một số mẫu: + +| Mẫu GoF | Quan hệ với monad tự do | +| --- | --- | +| **Interpreter** | Toàn bộ cấu trúc “AST + chạy” chính là mẫu Interpreter — monad tự do chỉ cung cấp AST và bộ kết hợp miễn phí. | +| **Command** | Mỗi biến thể `enum` trong DSL là một đối tượng Command. Monad tự do nối chuỗi chúng như một macro-command. | +| **Composite** | Cấu trúc AST (các lệnh lồng nhau) là Composite của các lệnh. | +| **Builder** | Chuỗi `.flat_map` là builder dạng nối chuỗi để tạo chương trình. | +| **Visitor** | Bộ diễn giải về cơ bản là visitor duyệt tập lệnh. | + +## Vì sao monad tự do vượt trội các mẫu này {#why-free-monad--these-patterns} + +* Mẫu GoF là công việc OO **thủ công** — bạn định nghĩa giao diện, lớp và cách hợp thành chúng. + +* Monad tự do có tính **đại số** — bạn định nghĩa *dữ liệu* cho lệnh và *hàm* để diễn giải chúng. + +* Bạn tự động có: + + * Tuần tự hóa (`flat_map`) + * Phép hợp thành + * Nhiều bộ diễn giải mà không đụng đến logic lõi + +**Bảng tóm tắt**: + +| Khái niệm FP monad tự do | Mẫu GoF/OOP tương đương | +| --- | --- | +| Enum lệnh | Command | +| AST chương trình | Composite | +| Builder `flat_map` | Builder | +| Hàm diễn giải | Interpreter / Visitor | +| Nhiều bộ diễn giải | Strategy | + +## Quan hệ với phi chức năng hóa {#relation-to-defunctionalization} + +**Phi chức năng hóa** là phép biến đổi chương trình thay hàm bậc cao bằng cấu trúc dữ liệu bậc nhất biểu diễn các hàm có thể có, cùng một bộ diễn giải áp dụng chúng. + +Trong CPS, tiếp nối là hàm bậc cao. Phi chức năng hóa chương trình CPS thay các tiếp nối đó bằng enum các trường hợp tiếp nối và một hàm `apply` để chạy chúng. + +Với cách mã hóa phù hợp, có thể liên hệ monad tự do với các tiếp nối đã phi chức năng hóa bên trong chương trình chuyển đổi sang CPS: + +1. Bắt đầu bằng phiên bản CPS của chương trình. “Phần còn lại của chương trình” được mang trong các hàm tiếp nối. +2. Phi chức năng hóa các hàm tiếp nối đó thành tập hữu hạn trường hợp trong kiểu dữ liệu. +3. Kiểu dữ liệu bậc nhất thu được có thể mang cùng hình dạng lệnh-và-tiếp-nối như một biểu diễn monad tự do. + +**Điểm tương đồng chính** + +* Cả monad tự do lẫn phi chức năng hóa đều tạo biểu diễn dữ liệu cho phép tính và cần bộ diễn giải để gán ý nghĩa cho dữ liệu đó. +* Trường hợp `FlatMap` trong monad tự do giữ tiếp nối; phi chức năng hóa thay closure đó bằng một trường hợp trong kiểu dữ liệu. + +**Khác biệt chính** + +| Khía cạnh | Phi chức năng hóa | Monad tự do | +| --- | --- | --- | +| Mục đích | Kỹ thuật trình biên dịch mang tính cơ học để loại bỏ hàm bậc cao | Cấu trúc đại số để tách cú pháp khỏi ngữ nghĩa | +| Đầu vào | Bất kỳ chương trình bậc cao nào, thường ở dạng CPS | Functor F mô tả các lệnh có thể có | +| Đầu ra | Enum các trường hợp hàm cùng hàm apply | `Free` AST cùng các bộ diễn giải | +| Monad? | Không nhất thiết | Luôn là monad do cách kiến tạo | +| Phạm vi | Phép biến đổi tổng quát | Mẫu lập trình hàm chuyên biệt | + +**Tóm tắt** Phi chức năng hóa là kỹ thuật biến đổi. Monad tự do là cấu trúc đại số. Chúng có liên hệ chặt chẽ trong một số cách biểu diễn, nhưng nói chung không cách nào suy ra cách kia nếu thiếu giả định bổ sung. diff --git a/src/concepts/free_monad.zh-hant.md b/src/concepts/free_monad.zh-hant.md new file mode 100644 index 0000000..f41945a --- /dev/null +++ b/src/concepts/free_monad.zh-hant.md @@ -0,0 +1,234 @@ + + +# 自由單子 {#free-monad} + +```admonish tip title="相關內容" +Rust 中的語義驅動設計:[一階程式](../rust-dd/first-order-programs.md)、[直譯器與效應](../rust-dd/interpreters.md) +概念:[延續傳遞風格](cps.md)、[去函式化](defunctionalization.md) +洞見:[EVM 代數](../insights/evm-alg.md) +``` + +```admonish note title="語義定位" +自由單子是一種表示指令語法與自由生成的順序組合的方式。指令函子已經選定了詞彙;隨後,直譯器會將該語法對映到某個語義域。它是一種強大的編碼方式,但並非指稱設計的定義。 +``` + +## 什麼是自由單子(Rust 版本) {#what-is-a-free-monad-rust-version} + +**自由單子**可以讓你: + +* **描述**程式時使用*資料*,而非立即執行程式。 +* 稍後以一種或多種方式**解釋**該程式。 + +可以將它想成: + +> 一個效應操作 AST + 用於串接步驟的`bind`/`flat_map`。 + +將以下兩者分開: + +* **語法** → 指令列舉。 +* **解釋** → 對映到所選語義域並保留結構。 + +“自由”意味著單子結構由函子`F`自由生成,除了單子定律之外不新增其他等式。選擇`F`本身就決定了指令語法;對結果程式作出解釋,則會賦予其特定指稱。 + +## Rust 實作 {#rust-implementation} + +```admonish warning title="示意性編碼" +Rust 不支援直接的高階型別引數,因此生產級自由單子編碼需要額外的型別機制,或專用指令函子。以下程式碼展示預期結構,並非可直接使用的泛型實作。 +``` + +### 自由單子型別 {#free-monad-type} + +```rust,noplayground +#[derive(Clone)] +enum Free { + Pure(A), + Suspend(F), + FlatMap(Box>, Box Free>), +} + +impl Free { + fn pure(a: A) -> Self { + Free::Pure(a) + } + + fn flat_map(self, f: G) -> Free + where + G: Fn(A) -> Free + 'static, + F: 'static, + { + match self { + Free::Pure(a) => f(a), + Free::Suspend(op) => { + Free::FlatMap(Box::new(Free::Suspend(op)), Box::new(f)) + } + Free::FlatMap(inner, g) => { + Free::FlatMap(inner, Box::new(move |x| g(x).flat_map(f.clone()))) + } + } + } +} +``` + +### 領域特定語言:控制檯操作 {#dsl-console-operations} + +```rust,noplayground +#[derive(Clone)] +enum Console { + Print(String, A), + ReadLine(fn(String) -> A), +} + +// Smart constructors +fn print_line(s: &str) -> Free, ()> { + Free::Suspend(Console::Print(s.to_string(), ())) +} + +fn read_line() -> Free, String> { + Free::Suspend(Console::ReadLine(|input| Free::Pure(input))) +} +``` + +### 直譯器 {#interpreter} + +```rust,noplayground +fn run_console(mut prog: Free, A>) -> A { + loop { + match prog { + Free::Pure(a) => return a, + Free::Suspend(Console::Print(s, next)) => { + println!("{}", s); + prog = Free::Pure(next); + } + Free::Suspend(Console::ReadLine(f)) => { + let mut buf = String::new(); + std::io::stdin().read_line(&mut buf).unwrap(); + prog = f(buf.trim().to_string()); + } + Free::FlatMap(inner, cont) => match *inner { + Free::Pure(a) => prog = cont(a), + Free::Suspend(op) => prog = Free::Suspend(op), // minimal handling + _ => unimplemented!(), + }, + } + } +} +``` + +### 用法 {#usage} + +```rust,noplayground +fn main() { + let program = + print_line("What is your name?") + .flat_map(|_| read_line()) + .flat_map(|name| print_line(&format!("Hello, {name}!"))); + + run_console(program); +} +``` + +## 要點 {#takeaway} + +* **語法** = `enum Console`(可能的指令) +* **程式** = `Free`(描述步驟的資料) +* **具體解釋** = `run_console` +* 優勢:同一個程式可以編寫多種直譯器,例如在真正的 IO 中執行、將日誌寫入檔案,或編譯為另一種語言。 + +## 與延續及 CPS 的關聯 {#correlation-to-continuations-and-cps} + +延續傳遞風格(CPS)是一種程式設計方式:函式不直接返回值,而是將結果傳給另一個函式(即*延續*),由它表示“程式接下來的部分”。 + +**自由單子**本質上是**由一系列步驟組成的程式**,每一步都會說: + +> “執行此操作,然後繼續處理剩餘部分。” + +這個“程式剩餘部分”正是一個**延續**——從當前結果對映到下一步的函式。 + +* 在我們的 Rust 自由單子中: + + ```rust,noplayground + Free::FlatMap(Box>, Box Free>) + ``` + + `Box Free>`**就是延續**。 + +* 解釋自由單子時,你其實是在**透過 CPS 執行**: + + * 你不會直接返回值,而是將它們傳給下一個延續。 + * 最終會進入如下迴圈: `current_instruction -> feed result into continuation -> next instruction` +* **CPS 關係**: + + * 自由單子*將 CPS 編碼進資料結構*。 + * CPS *則是同一思想的執行時控制流表示*。 + +**快速對照**: + +| 概念 | 在 CPS 中 | 在自由單子 AST 中 | +| --- | --- | --- | +| 步驟結果 | 延續的引數 | `A`在`Fn(A) -> Free`中 | +| 延續 | 函式`(A) -> R` | `Box Free>` | +| 程式 | 巢狀延續 | 巢狀的`FlatMap`變體 | +| 執行 | 呼叫函式 | 模式匹配並呼叫 | + +## GoF(四人幫)設計模式對映 {#gof-gang-of-four-design-patterns-mapping} + +自由單子**並不屬於**GoF,因為它來自函數語言程式設計理論,但可以**涵蓋**或**模擬**若干模式: + +| GoF 模式 | 自由單子與該模式的關係 | +| --- | --- | +| **直譯器** | 整個“AST + 執行”就是字面意義上的直譯器模式——自由單子直接提供 AST 與組合器。 | +| **命令** | DSL 中的每個`enum`變體都是一個命令物件。自由單子會像宏命令一樣串接它們。 | +| **組合** | AST 結構(巢狀指令)是命令的組合體。 | +| **構建器** | `.flat_map`鏈式呼叫為程式提供了流暢的構建器。 | +| **存取者** | 直譯器本質上是指令集的存取者。 | + +## 為什麼自由單子優於這些模式 {#why-free-monad--these-patterns} + +* GoF 模式是**手動的物件導向工作**——需要自行定義介面、類並將它們組合起來。 + +* 自由單子是**代數式的**——為指令定義*資料*,為其解釋定義*函式*。 + +* 你會自動獲得: + + * 順序組合(`flat_map`) + * 組合 + * 無需觸碰核心邏輯即可使用多種直譯器 + +**彙總表**: + +| 自由單子(函數語言程式設計概念) | 對應的 GoF/物件導向模式 | +| --- | --- | +| 指令列舉 | 命令 | +| 程式 AST | 組合體 | +| `flat_map`構建器 | 構建器 | +| 直譯器函式 | 直譯器/存取者 | +| 多種直譯器 | 策略 | + +## 與去函式化的關係 {#relation-to-defunctionalization} + +**去函式化**是一種程式變換:它將高階函式替換為表示可能函式集合的一階資料結構,並提供一個用於應用它們的直譯器。 + +在 CPS 中,延續是高階函式。對 CPS 程式去函式化,會將這些延續替換為延續分支列舉,並提供一個`apply`函式來執行它們。 + +對於適當的編碼,自由單子可以與 CPS 變換程式內部的去函式化延續連結起來: + +1. 從程式的 CPS 版本開始。“程式剩餘部分”由延續函式承載。 +2. 將這些延續函式去函式化為資料型別中的有限分支集合。 +3. 所得的一階資料型別可以具有與自由單子表示相同的指令與延續結構。 + +**關鍵相似之處** + +* 自由單子與去函式化都會生成計算的資料表示,並且都需要直譯器來賦予這些資料含義。 +* 自由單子中的`FlatMap`分支援有延續;去函式化則將該閉包替換為資料型別中的一個分支。 + +**關鍵區別** + +| 方面 | 去函式化 | 自由單子 | +| --- | --- | --- | +| 目的 | 消除高階函式的機械式編譯器技術 | 將語法與語義分離的代數構造 | +| 輸入 | 任意高階程式,通常採用 CPS 形式 | 描述可能指令的函子 F | +| 輸出 | 函式分支列舉及應用函式 | `Free`AST 與直譯器 | +| 是否為單子? | 不一定 | 根據構造始終是單子 | +| 範圍 | 通用變換 | 特定的函數語言程式設計模式 | + +**總結** 去函式化是一種變換技術,自由單子是一種代數構造。在某些表示中二者關係密切,但除非附加額外假設,否則通常不能由其中一種構造推出另一種。 diff --git a/src/concepts/free_monad.zh.md b/src/concepts/free_monad.zh.md new file mode 100644 index 0000000..49e3436 --- /dev/null +++ b/src/concepts/free_monad.zh.md @@ -0,0 +1,234 @@ + + +# 自由单子 {#free-monad} + +```admonish tip title="相关内容" +Rust 中的语义驱动设计:[一阶程序](../rust-dd/first-order-programs.md)、[解释器与效应](../rust-dd/interpreters.md) +概念:[延续传递风格](cps.md)、[去函数化](defunctionalization.md) +洞见:[EVM 代数](../insights/evm-alg.md) +``` + +```admonish note title="语义定位" +自由单子是一种表示指令语法与自由生成的顺序组合的方式。指令函子已经选定了词汇;随后,解释器会将该语法映射到某个语义域。它是一种强大的编码方式,但并非指称设计的定义。 +``` + +## 什么是自由单子(Rust 版本) {#what-is-a-free-monad-rust-version} + +**自由单子**可以让你: + +* **描述**程序时使用*数据*,而非立即运行程序。 +* 稍后以一种或多种方式**解释**该程序。 + +可以将它想成: + +> 一个效应操作 AST + 用于串接步骤的`bind`/`flat_map`。 + +将以下两者分开: + +* **语法** → 指令枚举。 +* **解释** → 映射到所选语义域并保留结构。 + +“自由”意味着单子结构由函子`F`自由生成,除了单子定律之外不添加其他等式。选择`F`本身就决定了指令语法;对结果程序作出解释,则会赋予其特定指称。 + +## Rust 实现 {#rust-implementation} + +```admonish warning title="示意性编码" +Rust 不支持直接的高阶类型参数,因此生产级自由单子编码需要额外的类型机制,或专用指令函子。以下代码展示预期结构,并非可直接使用的泛型实现。 +``` + +### 自由单子类型 {#free-monad-type} + +```rust,noplayground +#[derive(Clone)] +enum Free { + Pure(A), + Suspend(F), + FlatMap(Box>, Box Free>), +} + +impl Free { + fn pure(a: A) -> Self { + Free::Pure(a) + } + + fn flat_map(self, f: G) -> Free + where + G: Fn(A) -> Free + 'static, + F: 'static, + { + match self { + Free::Pure(a) => f(a), + Free::Suspend(op) => { + Free::FlatMap(Box::new(Free::Suspend(op)), Box::new(f)) + } + Free::FlatMap(inner, g) => { + Free::FlatMap(inner, Box::new(move |x| g(x).flat_map(f.clone()))) + } + } + } +} +``` + +### 领域特定语言:控制台操作 {#dsl-console-operations} + +```rust,noplayground +#[derive(Clone)] +enum Console { + Print(String, A), + ReadLine(fn(String) -> A), +} + +// Smart constructors +fn print_line(s: &str) -> Free, ()> { + Free::Suspend(Console::Print(s.to_string(), ())) +} + +fn read_line() -> Free, String> { + Free::Suspend(Console::ReadLine(|input| Free::Pure(input))) +} +``` + +### 解释器 {#interpreter} + +```rust,noplayground +fn run_console(mut prog: Free, A>) -> A { + loop { + match prog { + Free::Pure(a) => return a, + Free::Suspend(Console::Print(s, next)) => { + println!("{}", s); + prog = Free::Pure(next); + } + Free::Suspend(Console::ReadLine(f)) => { + let mut buf = String::new(); + std::io::stdin().read_line(&mut buf).unwrap(); + prog = f(buf.trim().to_string()); + } + Free::FlatMap(inner, cont) => match *inner { + Free::Pure(a) => prog = cont(a), + Free::Suspend(op) => prog = Free::Suspend(op), // minimal handling + _ => unimplemented!(), + }, + } + } +} +``` + +### 用法 {#usage} + +```rust,noplayground +fn main() { + let program = + print_line("What is your name?") + .flat_map(|_| read_line()) + .flat_map(|name| print_line(&format!("Hello, {name}!"))); + + run_console(program); +} +``` + +## 要点 {#takeaway} + +* **语法** = `enum Console`(可能的指令) +* **程序** = `Free`(描述步骤的数据) +* **具体解释** = `run_console` +* 优势:同一个程序可以编写多种解释器,例如在真正的 IO 中运行、将日志写入文件,或编译为另一种语言。 + +## 与延续及 CPS 的关联 {#correlation-to-continuations-and-cps} + +延续传递风格(CPS)是一种编程方式:函数不直接返回值,而是将结果传给另一个函数(即*延续*),由它表示“程序接下来的部分”。 + +**自由单子**本质上是**由一系列步骤组成的程序**,每一步都会说: + +> “执行此操作,然后继续处理剩余部分。” + +这个“程序剩余部分”正是一个**延续**——从当前结果映射到下一步的函数。 + +* 在我们的 Rust 自由单子中: + + ```rust,noplayground + Free::FlatMap(Box>, Box Free>) + ``` + + `Box Free>`**就是延续**。 + +* 解释自由单子时,你其实是在**通过 CPS 运行**: + + * 你不会直接返回值,而是将它们传给下一个延续。 + * 最终会进入如下循环: `current_instruction -> feed result into continuation -> next instruction` +* **CPS 关系**: + + * 自由单子*将 CPS 编码进数据结构*。 + * CPS *则是同一思想的运行时控制流表示*。 + +**快速对照**: + +| 概念 | 在 CPS 中 | 在自由单子 AST 中 | +| --- | --- | --- | +| 步骤结果 | 延续的参数 | `A`在`Fn(A) -> Free`中 | +| 延续 | 函数`(A) -> R` | `Box Free>` | +| 程序 | 嵌套延续 | 嵌套的`FlatMap`变体 | +| 执行 | 调用函数 | 模式匹配并调用 | + +## GoF(四人帮)设计模式映射 {#gof-gang-of-four-design-patterns-mapping} + +自由单子**并不属于**GoF,因为它来自函数式编程理论,但可以**涵盖**或**模拟**若干模式: + +| GoF 模式 | 自由单子与该模式的关系 | +| --- | --- | +| **解释器** | 整个“AST + 运行”就是字面意义上的解释器模式——自由单子直接提供 AST 与组合器。 | +| **命令** | DSL 中的每个`enum`变体都是一个命令对象。自由单子会像宏命令一样串接它们。 | +| **组合** | AST 结构(嵌套指令)是命令的组合体。 | +| **构建器** | `.flat_map`链式调用为程序提供了流畅的构建器。 | +| **访问者** | 解释器本质上是指令集的访问者。 | + +## 为什么自由单子优于这些模式 {#why-free-monad--these-patterns} + +* GoF 模式是**手动的面向对象工作**——需要自行定义接口、类并将它们组合起来。 + +* 自由单子是**代数式的**——为指令定义*数据*,为其解释定义*函数*。 + +* 你会自动获得: + + * 顺序组合(`flat_map`) + * 组合 + * 无需触碰核心逻辑即可使用多种解释器 + +**汇总表**: + +| 自由单子(函数式编程概念) | 对应的 GoF/面向对象模式 | +| --- | --- | +| 指令枚举 | 命令 | +| 程序 AST | 组合体 | +| `flat_map`构建器 | 构建器 | +| 解释器函数 | 解释器/访问者 | +| 多种解释器 | 策略 | + +## 与去函数化的关系 {#relation-to-defunctionalization} + +**去函数化**是一种程序变换:它将高阶函数替换为表示可能函数集合的一阶数据结构,并提供一个用于应用它们的解释器。 + +在 CPS 中,延续是高阶函数。对 CPS 程序去函数化,会将这些延续替换为延续分支枚举,并提供一个`apply`函数来运行它们。 + +对于适当的编码,自由单子可以与 CPS 变换程序内部的去函数化延续联系起来: + +1. 从程序的 CPS 版本开始。“程序剩余部分”由延续函数承载。 +2. 将这些延续函数去函数化为数据类型中的有限分支集合。 +3. 所得的一阶数据类型可以具有与自由单子表示相同的指令与延续结构。 + +**关键相似之处** + +* 自由单子与去函数化都会生成计算的数据表示,并且都需要解释器来赋予这些数据含义。 +* 自由单子中的`FlatMap`分支持有延续;去函数化则将该闭包替换为数据类型中的一个分支。 + +**关键区别** + +| 方面 | 去函数化 | 自由单子 | +| --- | --- | --- | +| 目的 | 消除高阶函数的机械式编译器技术 | 将语法与语义分离的代数构造 | +| 输入 | 任意高阶程序,通常采用 CPS 形式 | 描述可能指令的函子 F | +| 输出 | 函数分支枚举及应用函数 | `Free`AST 与解释器 | +| 是否为单子? | 不一定 | 根据构造始终是单子 | +| 范围 | 通用变换 | 特定的函数式编程模式 | + +**总结** 去函数化是一种变换技术,自由单子是一种代数构造。在某些表示中二者关系密切,但除非附加额外假设,否则通常不能由其中一种构造推出另一种。 diff --git a/src/concepts/index.ar.md b/src/concepts/index.ar.md new file mode 100644 index 0000000..d1b4336 --- /dev/null +++ b/src/concepts/index.ar.md @@ -0,0 +1,35 @@ + + +# مقدمة المفاهيم {#concepts-introduction} + +![Concepts — the programming machinery](../assets/concepts.png) + +```admonish tip title="ذات صلة" +الرؤية الدلالية: [لماذا يأتي المعنى أولًا](../denotational-design/semantic-view.md) +التصميم انطلاقًا من المعنى في Rust: [جبريات القدرات](../rust-dd/capability-algebras.md) +الرؤى: [مقدمة](../insights/index.md) +``` + +تشرح فصول هذا الجزء آليات برمجية وأدوات نظرية مهمة: + +* تصف الدلالات التشغيلية قواعد التنفيذ +* يجعل أسلوب تمرير الاستمرار تدفق التحكم صريحًا +* تحول إزالة الدوال السلوك المعروف عالي الرتبة إلى بيانات من الرتبة الأولى +* تمثل المونادات الحرة صياغة الآثار مع التسلسل +* تدير ترميزات مسألة التعبير قابلية التوسيع +* تدعم الشفافية المرجعية الاستبدال +* يقارن التلاقي والمسارات والتشابه المحاكى أشكال السلوك + +لا يحل التصميم الدلالي محل هذه المفاهيم، بل يضعها ضمن إطاره. + +```admonish quote title="الآليات في مقابل المعنى" +تشرح [المفاهيم](index.md) و[الرؤى](../insights/index.md) آليات برمجية مفيدة. ويشرح [التصميم الدلالي](../denotational-design/design.md) كيفية تحديد الآليات التي ينبغي الحفاظ عليها. +``` + +استخدم ثلاثة أسئلة أثناء قراءة كل فصل: + +1. هل يصف هذا المفهوم المعنى أم التمثيل أم التنفيذ أم تحويلًا بينها؟ +2. ما الملاحظات وعلاقات المساواة التي يحافظ عليها؟ +3. هل هو المواصفة أم أحد ترميزاتها أم أحد مفسراتها؟ + +كُتبت فصول عدة قبل اعتماد الكتاب هذا التسلسل الدلالي الصريح. وتُبقي أمثلتها التركيز التشغيلي عن قصد. وتصل الروابط السياقية وفصول الرؤى بينها وبين الرؤية الدلالية. diff --git a/src/concepts/index.de.md b/src/concepts/index.de.md new file mode 100644 index 0000000..c64433a --- /dev/null +++ b/src/concepts/index.de.md @@ -0,0 +1,35 @@ + + +# Einführung in Concepts {#concepts-introduction} + +![Concepts — the programming machinery](../assets/concepts.png) + +```admonish tip title="Verwandte Themen" +The Semantic View: [Warum Bedeutung an erster Stelle steht](../denotational-design/semantic-view.md) +Design by Meaning in Rust: [Capability-Algebren](../rust-dd/capability-algebras.md) +Insights: [Einführung](../insights/index.md) +``` + +Die Kapitel in diesem Teil erläutern wichtige Programmiermechanismen und theoretische Werkzeuge: + +* Operationale Semantik beschreibt Ausführungsregeln +* CPS macht Fortsetzungen des Kontrollflusses explizit +* Defunktionalisierung überführt bekanntes höherwertiges Verhalten in Daten erster Ordnung +* Freie Monaden stellen Effektsyntax mit Sequenzierung dar +* Kodierungen für das Expression Problem handhaben Erweiterbarkeit +* Referenzielle Transparenz ermöglicht Substitution +* Konfluenz, Spuren und Bisimulation vergleichen Verhaltensformen + +Diese Konzepte werden durch Denotational Design nicht ersetzt, sondern darin eingeordnet. + +```admonish quote title="Mechanik und Bedeutung" +[Concepts](index.md) und [Insights](../insights/index.md) erklären nützliche Programmiermechanismen. [Denotational Design](../denotational-design/design.md) erklärt, wie man entscheidet, was diese Mechanismen bewahren sollen. +``` + +Stelle beim Lesen jedes Kapitels drei Fragen: + +1. Beschreibt dieses Konzept Bedeutung, Repräsentation, Ausführung oder eine Transformation dazwischen? +2. Welche Beobachtungen und Gleichheiten bewahrt es? +3. Ist es die Spezifikation, eine ihrer Kodierungen oder ein Interpreter? + +Einige Kapitel wurden geschrieben, bevor das Buch diesen ausdrücklichen semantischen Aufbau angenommen hat. Ihre Beispiele legen absichtlich weiterhin den Schwerpunkt auf die Ausführung. Kontextuelle Verknüpfungen und Insights-Kapitel stellen den Bezug zur semantischen Sicht her. diff --git a/src/concepts/index.es.md b/src/concepts/index.es.md new file mode 100644 index 0000000..9f28b5a --- /dev/null +++ b/src/concepts/index.es.md @@ -0,0 +1,35 @@ + + +# Introducción a los conceptos {#concepts-introduction} + +![Concepts — the programming machinery](../assets/concepts.png) + +```admonish tip title="Relacionado" +La perspectiva semántica: [Por qué el significado va primero](../denotational-design/semantic-view.md) +Diseño basado en el significado en Rust: [Álgebras de capacidades](../rust-dd/capability-algebras.md) +Perspectivas: [Introducción](../insights/index.md) +``` + +Los capítulos de esta parte explican mecanismos importantes de programación y herramientas teóricas: + +* la semántica operacional describe reglas de ejecución +* CPS hace explícita la continuación del control +* la defuncionalización convierte comportamientos de orden superior conocidos en datos de primer orden +* los mónadas libres representan sintaxis de efectos con secuenciación +* las codificaciones del problema de expresiones gestionan la extensibilidad +* la transparencia referencial facilita la sustitución +* la confluencia, las trazas y la bisimulación comparan formas de comportamiento + +El diseño denotacional no sustituye estos conceptos; los integra. + +```admonish quote title="Maquinaria y significado" +[Conceptos](index.md) y [Perspectivas](../insights/index.md) explican mecanismos de programación útiles. [El diseño denotacional](../denotational-design/design.md) explica cómo decidir qué debe preservar esa maquinaria. +``` + +Al leer cada capítulo, formula estas tres preguntas: + +1. ¿Este concepto describe significado, representación, ejecución o una transformación entre ellos? +2. ¿Qué observaciones e igualdades preserva? +3. ¿Es la especificación, una de sus codificaciones o uno de sus intérpretes? + +Varios capítulos se escribieron antes de que el libro adoptara esta progresión semántica explícita. Sus ejemplos mantienen intencionalmente un enfoque operativo. Los enlaces contextuales y los capítulos de Perspectivas los conectan de nuevo con la visión semántica. diff --git a/src/concepts/index.ja.md b/src/concepts/index.ja.md new file mode 100644 index 0000000..8c301e2 --- /dev/null +++ b/src/concepts/index.ja.md @@ -0,0 +1,35 @@ + + +# 概念のはじめに {#concepts-introduction} + +![Concepts — the programming machinery](../assets/concepts.png) + +```admonish tip title="関連項目" +意味論的な見方:[なぜ意味を先に考えるのか](../denotational-design/semantic-view.md) +Rustで意味から設計する:[ケイパビリティ代数](../rust-dd/capability-algebras.md) +洞察:[はじめに](../insights/index.md) +``` + +このパートの章では、重要なプログラミングの仕組みと理論的なツールを解説します。 + +* 操作的意味論は実行規則を記述する +* CPSは継続を明示する +* デファンクショナライズは既知の高階の振る舞いを一階データに変換する +* 自由モナドは逐次実行を伴う副作用の構文を表す +* Expression Problemに関する符号化は拡張性を扱う +* 参照透過性は置換を支える +* 合流性、トレース、双模倣性は振る舞いの形式を比較する + +こうした概念をDenotational Designが置き換えるのではなく、その中に位置付けます。 + +```admonish quote title="仕組みと意味" +[概念](index.md)と[洞察](../insights/index.md)は、有用なプログラミングの仕組みを解説します。[Denotational Design](../denotational-design/design.md)は、その仕組みに何を保持させるべきかを判断する方法を解説します。 +``` + +各章を読むときは、次の三つを問いかけます。 + +1. この概念が記述するのは、意味、表現、実行、それらの間の変換のどれか。 +2. どの観測と等値性を保持するか。 +3. これは仕様なのか、仕様の符号化の一つなのか、それとも一つのインタープリターなのか。 + +本書が明示的な意味論的な流れを採用する前に書かれた章もあります。意図的に操作を重視した例はそのままにしています。文脈に応じたリンクと洞察の章で、意味論的な見方とのつながりを示します。 diff --git a/src/concepts/index.ko.md b/src/concepts/index.ko.md new file mode 100644 index 0000000..7dda6dd --- /dev/null +++ b/src/concepts/index.ko.md @@ -0,0 +1,35 @@ + + +# 개념 소개 {#concepts-introduction} + +![Concepts — the programming machinery](../assets/concepts.png) + +```admonish tip title="관련 항목" +의미론적 관점: [왜 의미가 먼저인가](../denotational-design/semantic-view.md) +Rust에서 의미로 설계하기: [케이퍼빌리티 대수](../rust-dd/capability-algebras.md) +통찰: [소개](../insights/index.md) +``` + +이 부분의 장에서는 중요한 프로그래밍 장치와 이론적 도구를 설명합니다: + +* 작동 의미론은 실행 규칙을 설명합니다 +* CPS는 제어의 연속을 명시합니다 +* 디펑셔널라이제이션은 알려진 고차 동작을 일차 데이터로 바꿉니다 +* 자유 모나드는 효과 구문을 시퀀싱과 함께 나타냅니다 +* 표현식 문제 인코딩은 확장성을 다룹니다 +* 참조 투명성은 치환을 뒷받침합니다 +* 합류성, 실행 기록, 쌍방향 시뮬레이션은 여러 형태의 동작을 비교합니다 + +이 개념들은 표시적 설계를 대체하지 않습니다. 표시적 설계 안에 배치됩니다. + +```admonish quote title="구현 장치와 의미" +[개념](index.md)과 [통찰](../insights/index.md)은 유용한 프로그래밍 장치를 설명합니다. [표시적 설계](../denotational-design/design.md)는 어떤 장치가 무엇을 보존해야 하는지 결정하는 방법을 설명합니다. +``` + +각 장을 읽을 때 다음 세 질문을 해보세요: + +1. 이 개념은 의미, 표현, 실행 또는 그 사이의 변환 중 무엇을 설명하나요? +2. 어떤 관찰과 등식을 보존하나요? +3. 이것은 명세인가요, 명세의 한 가지 인코딩인가요, 아니면 인터프리터인가요? + +이 책이 명시적인 의미론적 진행 순서를 채택하기 전에 쓰인 장도 있습니다. 그 예시가 작동 방식에 초점을 두는 것은 의도된 것입니다. 문맥 링크와 통찰 장에서 이를 의미론적 관점과 다시 연결합니다. diff --git a/src/concepts/index.ru.md b/src/concepts/index.ru.md new file mode 100644 index 0000000..c322a46 --- /dev/null +++ b/src/concepts/index.ru.md @@ -0,0 +1,35 @@ + + +# Введение в раздел «Понятия» {#concepts-introduction} + +![Concepts — the programming machinery](../assets/concepts.png) + +```admonish tip title="Связанные материалы" +«Семантический взгляд»: [Почему начинать нужно со смысла](../denotational-design/semantic-view.md) +«Проектирование на основе смысла в Rust»: [Алгебры возможностей](../rust-dd/capability-algebras.md) +«Идеи»: [Введение](../insights/index.md) +``` + +Главы этой части посвящены важным механизмам программирования и теоретическим инструментам: + +* операционная семантика описывает правила выполнения +* CPS делает продолжение управления явным +* дефункционализация превращает известное поведение высшего порядка в данные первого порядка +* свободные монады представляют синтаксис эффектов с последовательным выполнением +* кодирования проблемы выражения управляют расширяемостью +* референциальная прозрачность обеспечивает безопасную подстановку +* конфлюэнтность, трассы и бисимуляция позволяют сравнивать формы поведения + +Денотационное проектирование не заменяет эти понятия, а размещает их в общей картине. + +```admonish quote title="Механизмы и смысл" +[«Понятия»](index.md) и [«Идеи»](../insights/index.md) объясняют полезные механизмы программирования. [Денотационное проектирование](../denotational-design/design.md) объясняет, как решить, что именно эти механизмы должны сохранять. +``` + +При чтении каждой главы задавайте себе три вопроса: + +1. Описывает ли понятие смысл, представление, выполнение или преобразование между ними? +2. Какие наблюдения и равенства оно сохраняет? +3. Это спецификация, одно из её кодирований или один интерпретатор? + +Некоторые главы были написаны до того, как в книге появилось это явное семантическое развитие. Их примеры намеренно сохраняют операционный акцент. Контекстные ссылки и главы «Идеи» связывают их с семантическим взглядом. diff --git a/src/concepts/index.uk.md b/src/concepts/index.uk.md new file mode 100644 index 0000000..cb63854 --- /dev/null +++ b/src/concepts/index.uk.md @@ -0,0 +1,35 @@ + + +# Вступ до понять {#concepts-introduction} + +![Concepts — the programming machinery](../assets/concepts.png) + +```admonish tip title="Пов’язані матеріали" +Семантичний погляд: [Чому значення має бути першим](../denotational-design/semantic-view.md) +Проєктування від значення в Rust: [Алгебри можливостей](../rust-dd/capability-algebras.md) +Інсайти: [Вступ](../insights/index.md) +``` + +У розділах цієї частини пояснюються важливі механізми програмування й теоретичні інструменти: + +* операційна семантика описує правила виконання +* CPS робить продовження явним елементом керування +* дефункціоналізація перетворює відому поведінку вищого порядку на дані першого порядку +* вільні монади представляють синтаксис ефектів із послідовністю +* кодування проблеми виразів керують розширюваністю +* референційна прозорість підтримує підстановку +* конфлюентність, траси й бісимілярність дають змогу порівнювати форми поведінки + +Денотаційне проєктування не замінює ці поняття. Воно визначає їхнє місце. + +```admonish quote title="Механізми та значення" +[Поняття](index.md) й [Інсайти](../insights/index.md) пояснюють корисні механізми програмування. [Денотаційне проєктування](../denotational-design/design.md) пояснює, як визначити, що саме ці механізми мають зберігати. +``` + +Читаючи кожен розділ, ставте собі три запитання: + +1. Чи описує це поняття значення, представлення, виконання або перетворення між ними? +2. Які спостереження й рівності воно зберігає? +3. Чи є воно специфікацією, одним із її кодувань або одним з інтерпретаторів? + +Деякі розділи написано до того, як у книжці з’явився цей явний семантичний порядок. Їхні приклади навмисно зберігають акцент на виконанні. Контекстні посилання й розділи «Інсайти» пов’язують їх із семантичним поглядом. diff --git a/src/concepts/index.vi.md b/src/concepts/index.vi.md new file mode 100644 index 0000000..dc6afbc --- /dev/null +++ b/src/concepts/index.vi.md @@ -0,0 +1,35 @@ + + +# Giới thiệu phần Khái niệm {#concepts-introduction} + +![Concepts — the programming machinery](../assets/concepts.png) + +```admonish tip title="Liên quan" +Góc nhìn ngữ nghĩa: [Vì sao ý nghĩa được đặt lên trước](../denotational-design/semantic-view.md) +Thiết kế theo ngữ nghĩa trong Rust: [Các đại số năng lực](../rust-dd/capability-algebras.md) +Nhận định: [Giới thiệu](../insights/index.md) +``` + +Các chương trong phần này giải thích những cơ chế lập trình và công cụ lý thuyết quan trọng: + +* ngữ nghĩa vận hành mô tả quy tắc thực thi +* CPS làm cho phần tiếp nối điều khiển trở nên tường minh +* phi chức năng hóa chuyển hành vi bậc cao đã biết thành dữ liệu bậc nhất +* monad tự do biểu diễn cú pháp hiệu ứng kèm thứ tự hóa +* các cách mã hóa bài toán biểu thức quản lý khả năng mở rộng +* tính minh bạch tham chiếu hỗ trợ phép thế +* tính hội tụ, vết thực thi và mô phỏng song hành so sánh các dạng hành vi + +Thiết kế theo ngữ nghĩa không thay thế các khái niệm này. Nó đặt chúng vào đúng vị trí. + +```admonish quote title="Cơ chế và ý nghĩa" +[Các khái niệm](index.md) và [nhận định](../insights/index.md) giải thích những cơ chế lập trình hữu ích. [Thiết kế theo ngữ nghĩa](../denotational-design/design.md) giải thích cách xác định cơ chế cần bảo toàn điều gì. +``` + +Khi đọc mỗi chương, hãy đặt ba câu hỏi: + +1. Khái niệm này mô tả ý nghĩa, biểu diễn, thực thi hay phép biến đổi giữa chúng? +2. Nó bảo toàn những quan sát và đẳng thức nào? +3. Đây là đặc tả, một cách mã hóa đặc tả hay một bộ diễn giải? + +Một số chương được viết trước khi sách áp dụng tiến trình ngữ nghĩa tường minh này. Ví dụ trong đó chủ ý nhấn mạnh vận hành. Các liên kết theo ngữ cảnh và chương Nhận định kết nối chúng trở lại góc nhìn ngữ nghĩa. diff --git a/src/concepts/index.zh-hant.md b/src/concepts/index.zh-hant.md new file mode 100644 index 0000000..1723506 --- /dev/null +++ b/src/concepts/index.zh-hant.md @@ -0,0 +1,35 @@ + + +# 概念導讀 {#concepts-introduction} + +![Concepts — the programming machinery](../assets/concepts.png) + +```admonish tip title="相關內容" +語義視角:[為何含義優先](../denotational-design/semantic-view.md) +Rust 中的語義驅動設計:[能力代數](../rust-dd/capability-algebras.md) +洞見:[簡介](../insights/index.md) +``` + +本部分的章節將介紹重要的程式設計機制與理論工具: + +* 操作語義描述執行規則 +* CPS 會將控制流程中的延續顯式化 +* 去函式化將已知的高階行為轉為一階資料 +* 自由單子透過順序組合表示效應語法 +* 表示式問題編碼用於管理可擴充性 +* 引用透明性支援替換 +* 合流性、軌跡與雙模擬用於比較不同形式的行為 + +指稱設計並未取代這些概念,而是將它們放在合適的位置。 + +```admonish quote title="機制與含義" +[概念](index.md)與[洞見](../insights/index.md)用於說明實用的程式設計機制。[指稱設計](../denotational-design/design.md)則說明如何判斷這些機制應當保留什麼。 +``` + +閱讀每章時,思考以下三個問題: + +1. 這個概念描述的是含義、表示、執行,還是它們之間的某種變換? +2. 它保留了哪些觀察與等價關係? +3. 它是規範、規範的一種編碼,還是一種直譯器? + +有幾章寫於本書採用明確的語義遞進結構之前,其示例有意保留了操作層面的側重。相關頁面連結與“洞見”章節會將它們重新連線到語義視角。 diff --git a/src/concepts/index.zh.md b/src/concepts/index.zh.md new file mode 100644 index 0000000..460fea5 --- /dev/null +++ b/src/concepts/index.zh.md @@ -0,0 +1,35 @@ + + +# 概念导读 {#concepts-introduction} + +![Concepts — the programming machinery](../assets/concepts.png) + +```admonish tip title="相关内容" +语义视角:[为何含义优先](../denotational-design/semantic-view.md) +Rust 中的语义驱动设计:[能力代数](../rust-dd/capability-algebras.md) +洞见:[简介](../insights/index.md) +``` + +本部分的章节将介绍重要的编程机制与理论工具: + +* 操作语义描述执行规则 +* CPS 将控制延续显式化 +* 去函数化将已知的高阶行为转为一阶数据 +* 自由单子通过顺序组合表示效应语法 +* 表达式问题编码用于管理可扩展性 +* 引用透明性支持替换 +* 合流性、轨迹与双模拟用于比较不同形式的行为 + +指称设计并未取代这些概念,而是将它们放在合适的位置。 + +```admonish quote title="机制与含义" +[概念](index.md)与[洞见](../insights/index.md)用于说明实用的编程机制。[指称设计](../denotational-design/design.md)则说明如何判断这些机制应当保留什么。 +``` + +阅读每章时,思考以下三个问题: + +1. 这个概念描述的是含义、表示、执行,还是它们之间的某种变换? +2. 它保留了哪些观察与等价关系? +3. 它是规范、规范的一种编码,还是一种解释器? + +有几章写于本书采用明确的语义递进结构之前,其示例有意保留了操作层面的侧重。相关页面链接与“洞见”章节会将它们重新连接到语义视角。 diff --git a/src/concepts/operational_semantics.ar.md b/src/concepts/operational_semantics.ar.md new file mode 100644 index 0000000..16d219a --- /dev/null +++ b/src/concepts/operational_semantics.ar.md @@ -0,0 +1,121 @@ + + +# الدلالات التشغيلية {#operational-semantics} + +```admonish tip title="ذات صلة" +الرؤية الدلالية: [التصميم الدلالي](../denotational-design/design.md) +التصميم انطلاقًا من المعنى في Rust: [مسارات اللغة والمترجم](../rust-dd/compiler-pipelines.md) +المفاهيم: [الموناد الحر](free_monad.md)، [أسلوب تمرير الاستمرار](cps.md)، [إزالة الدوال](defunctionalization.md) +الرؤى: [من الدلالات إلى الآلات](../insights/operational_semantics.md) +``` + +## التعريف {#definition} + +تصف **الدلالات التشغيلية** سلوك البرنامج بواسطة أحكام التقييم أو الانتقالات بين **تهيئات**. وقد تحتوي التهيئة على جزء من البرنامج مع بيئة أو مخزن أو استمرارية أو حالة أخرى للآلة المجردة. + +الوصف رياضي؛ فهو يحدد التقييمات أو الانتقالات الصحيحة. وقد ينفذ مفسر أو آلة افتراضية تلك القواعد، لكن تنفيذًا بعينه ليس التعريف نفسه. + +```admonish note title="الموضع الدلالي" +الدلالات التشغيلية دقيقة، وليست مجرد تفاصيل تنفيذ غير رسمية. فهي تشرح السلوك عبر قواعد التقييم أو الانتقال. ويسأل [التصميم الدلالي](../denotational-design/design.md) سؤالًا تصميميًا مكملًا وأسبق: أي المعاني والمعادلات التركيبية ينبغي لتلك القواعد الحفاظ عليها؟ +``` + +## أنماط الدلالات التشغيلية {#styles-of-operational-semantics} + +### الخطوات الصغيرة (الدلالات التشغيلية البنيوية) {#small-step-structural-operational-semantics} + +تجزّأ العملية الحسابية إلى انتقالات ذرية: + +$$ \begin{aligned} 2 + 3 &\to 5 \\ (2 + 3) \cdot 4 &\to 5 \cdot 4 \to 20 \end{aligned} $$ + +مفيدة لنمذجة التزامن والتداخل والتنفيذ الجزئي. + +### الخطوات الكبيرة (الدلالات الطبيعية) {#big-step-natural-semantics} + +يصف التقييم من حيث النتائج النهائية: + +$$ (2 + 3) \cdot 4 \Downarrow 20 $$ + +غالبًا ما تكون أوضح للاستدلال على البرامج المنتهية. + +## القواعد الصورية {#formal-rules} + +تُعطى الدلالات التشغيلية عادةً بواسطة **قواعد استدلال**. للغة حسابية بسيطة: + +$$ E ::= n \mid E + E $$ + +يلزم ثلاث قواعد للتقييم من اليسار إلى اليمين: + +$$ \frac{E_1 \to E_1'}{E_1 + E_2 \to E_1' + E_2} \qquad \frac{E_2 \to E_2'}{n + E_2 \to n + E_2'} \qquad n_1 + n_2 \to n_3 \quad \text{where } n_3 = n_1 + n_2 $$ + +تختار القاعدتان الأوليان التعبير الفرعي التالي القابل للاختزال. وتنفذ القاعدة الثالثة الجمع بعد أن يصبح المعاملان قيمتين. + +مسار التقييم: + +$$ (1 + 2) + 3 \to 3 + 3 \to 6 $$ + +## لماذا يهم {#why-it-matters} + +* يوفر **نموذجًا دقيقًا شبيهًا بالآلة** للتنفيذ. +* أساس للمفسرات والآلات الافتراضية. +* يدعم الاستدلال على الصحة واستخدام الموارد والسلامة. + +## علاقته بالمفاهيم الأخرى {#relation-to-other-concepts} + +* يوفر **الموناد الحر** صياغة التعليمات وتسلسلها. ويمكن للقواعد التشغيلية وصف تقييم برنامج بهذه الصيغة. +* يجعل **أسلوب تمرير الاستمرار** بقية الحساب صريحة في صورة دالة استمرار. ويمكن للقواعد التشغيلية وصف كيفية تمرير القيم إلى تلك الدوال. +* تستبدل **إزالة الدوال** عائلة معلومة من الدوال ببيانات من الرتبة الأولى وعملية `apply`. ويمكن للقواعد التشغيلية وصف حالات الآلة الصريحة الناتجة. + +هذه كيانات وتحويلات قد تُعطى دلالات تشغيلية؛ لكنها ليست الدلالات التشغيلية نفسها. + +## عمليًا {#in-practice} + +يمكن للقواعد التشغيلية توجيه المفسر وتوفير نموذج دقيق لمقارنته به: + +* يمكن نمذجة **آلة EVM** طبيعيًا كنظام انتقال حالات بخطوات صغيرة، كما يمكن ربط تنفيذ كامل منتهٍ بحكم خطوات كبيرة. +* غالبًا ما تقابل قواعد الخطوات الصغيرة أذرع `match` في مفسر Rust. + +$$ n_1 + n_2 \to n_3 $$ + +يمكن تمثيل العلاقة الكاملة من اليسار إلى اليمين بشيفرة Rust: + +```rust,noplayground +enum Expr { + Num(i64), + Add(Box, Box), +} + +fn step(expr: Expr) -> Option { + match expr { + Expr::Num(_) => None, + Expr::Add(left, right) => match (*left, *right) { + (Expr::Num(a), Expr::Num(b)) => Some(Expr::Num(a + b)), + (left @ Expr::Num(_), right) => step(right).map(|next| { + Expr::Add(Box::new(left), Box::new(next)) + }), + (left, right) => step(left).map(|next| { + Expr::Add(Box::new(next), Box::new(right)) + }), + }, + } +} +``` + +تنفذ هذه الدالة انتقالًا واحدًا. ويؤدي تكرار التطبيق إلى المسار المعروض؛ وتعني إعادة `None` أن التعبير قيمة بالفعل. + +## الأسئلة التشغيلية والدلالية {#operational-and-denotational-questions} + +يمكن للقواعد التشغيلية إثبات السلامة والتقدم وحدود الموارد والتوافق مع التنفيذات. ويظهر القيد عندما تُختار الآليات التشغيلية قبل المعنى المجرد المقصود؛ فقد تتحول خيارات التنفيذ إلى التزامات دلالية عرضية. + +لا يرفض التصميم الدلالي الدلالات التشغيلية. بل يدعونا إلى تحديد المجال الدلالي والتركيب والقوانين أولًا، ثم ربط النموذج التشغيلي بها. + +| المنظور | السؤال | +| --- | --- | +| الدلالي | ما معنى البرنامج كله؟ | +| التشغيلي | بأي انتقالات يُقيّم؟ | +| الصحة | هل تحافظ تلك الانتقالات على المعنى المقصود؟ | + +توضح المقاطع التالية خطر التعامل مع الأوصاف التشغيلية بوصفها المصدر الوحيد للفهم. + +
الوصف التشغيلي ليس المعنى كله (1 من 2)
+ +
الوصف التشغيلي ليس المعنى كله (2 من 2)
diff --git a/src/concepts/operational_semantics.de.md b/src/concepts/operational_semantics.de.md new file mode 100644 index 0000000..1c5dab5 --- /dev/null +++ b/src/concepts/operational_semantics.de.md @@ -0,0 +1,121 @@ + + +# Operationale Semantik {#operational-semantics} + +```admonish tip title="Verwandte Themen" +The Semantic View: [Denotational Design](../denotational-design/design.md) +Design by Meaning in Rust: [Sprach- und Compiler-Pipelines](../rust-dd/compiler-pipelines.md) +Concepts: [Freie Monade](free_monad.md), [Continuation-Passing Style](cps.md), [Defunktionalisierung](defunctionalization.md) +Insights: [Von der Semantik zu Maschinen](../insights/operational_semantics.md) +``` + +## Definition {#definition} + +**Operationale Semantik** beschreibt Programmverhalten anhand von Auswertungsurteilen oder Übergängen zwischen **Konfigurationen**. Eine Konfiguration kann ein Programmfragment mit einer Umgebung, einem Speicher, einer Fortsetzung oder einem anderen abstrakten Maschinenzustand enthalten. + +Die Beschreibung ist mathematisch: Sie legt fest, welche Auswertungen oder Übergänge zulässig sind. Ein Interpreter oder eine virtuelle Maschine kann diese Regeln implementieren, ist aber selbst nicht die Definition. + +```admonish note title="Semantische Einordnung" +Operationale Semantik ist eine präzise Semantik und nicht bloß ein informelles Implementierungsdetail. Sie erklärt Verhalten anhand von Auswertungs- oder Übergangsregeln. [Denotational Design](../denotational-design/design.md) stellt die ergänzende, vorgelagerte Entwurfsfrage: Welche kompositionalen Bedeutungen und Gleichungen sollen diese Regeln bewahren? +``` + +## Stile der operationalen Semantik {#styles-of-operational-semantics} + +### Kleine Schritte (strukturelle operationale Semantik) {#small-step-structural-operational-semantics} + +Die Berechnung wird in atomare Übergänge zerlegt: + +$$ \begin{aligned} 2 + 3 &\to 5 \\ (2 + 3) \cdot 4 &\to 5 \cdot 4 \to 20 \end{aligned} $$ + +Nützlich zur Modellierung von Nebenläufigkeit, Interleaving und partieller Ausführung. + +### Große Schritte (natürliche Semantik) {#big-step-natural-semantics} + +Beschreibt die Auswertung anhand ihrer Endergebnisse: + +$$ (2 + 3) \cdot 4 \Downarrow 20 $$ + +Häufig leichter verständlich, wenn man über terminierende Programme nachdenkt. + +## Formale Regeln {#formal-rules} + +Operationale Semantik wird üblicherweise mit **Inferenzregeln** angegeben. Für eine einfache arithmetische Sprache gilt: + +$$ E ::= n \mid E + E $$ + +Für eine Auswertung von links nach rechts werden drei Regeln benötigt: + +$$ \frac{E_1 \to E_1'}{E_1 + E_2 \to E_1' + E_2} \qquad \frac{E_2 \to E_2'}{n + E_2 \to n + E_2'} \qquad n_1 + n_2 \to n_3 \quad \text{where } n_3 = n_1 + n_2 $$ + +Die ersten beiden Regeln wählen den nächsten reduzierbaren Teilausdruck aus. Die dritte addiert, sobald beide Operanden Werte sind. + +Auswertungsspur: + +$$ (1 + 2) + 3 \to 3 + 3 \to 6 $$ + +## Warum das wichtig ist {#why-it-matters} + +* Liefert ein **präzises, maschinenähnliches Modell** der Ausführung. +* Grundlage für Interpreter und virtuelle Maschinen. +* Unterstützt Überlegungen zu Korrektheit, Ressourcenverbrauch und Sicherheit. + +## Beziehung zu anderen Konzepten {#relation-to-other-concepts} + +* Eine **freie Monade** stellt Instruktionssyntax und Sequenzierung bereit. Operationale Regeln können beschreiben, wie ein Programm in dieser Repräsentation ausgewertet wird. +* **CPS** macht den restlichen Berechnungsablauf als Fortsetzung explizit. Operationale Regeln können beschreiben, wie Werte an diese Fortsetzungen übergeben werden. +* **Defunktionalisierung** ersetzt eine bekannte Familie von Funktionen durch Daten erster Ordnung und eine `apply`\-Operation. Operationale Regeln können die daraus entstehenden expliziten Maschinenzustände beschreiben. + +Dies sind Objekte und Transformationen, für die eine operationale Semantik angegeben werden kann. Sie sind selbst keine operationale Semantik. + +## In der Praxis {#in-practice} + +Operationale Regeln können einen Interpreter leiten und ein präzises Modell liefern, an dem er geprüft wird: + +* Die **EVM** lässt sich natürlich als Übergangssystem in kleinen Schritten modellieren; eine terminierende Gesamtausführung kann außerdem durch ein Urteil in großen Schritten beschrieben werden. +* Regeln in kleinen Schritten entsprechen häufig den `match`\-Armen in einem Rust-Interpreter. + +$$ n_1 + n_2 \to n_3 $$ + +Die vollständige Relation von links nach rechts lässt sich als Rust-Code darstellen: + +```rust,noplayground +enum Expr { + Num(i64), + Add(Box, Box), +} + +fn step(expr: Expr) -> Option { + match expr { + Expr::Num(_) => None, + Expr::Add(left, right) => match (*left, *right) { + (Expr::Num(a), Expr::Num(b)) => Some(Expr::Num(a + b)), + (left @ Expr::Num(_), right) => step(right).map(|next| { + Expr::Add(Box::new(left), Box::new(next)) + }), + (left, right) => step(left).map(|next| { + Expr::Add(Box::new(next), Box::new(right)) + }), + }, + } +} +``` + +Diese Funktion führt einen Übergang aus. Wiederholte Anwendung erzeugt die dargestellte Spur; die Rückgabe von `None` bedeutet, dass der Ausdruck bereits ein Wert ist. + +## Operationale und denotationelle Fragen {#operational-and-denotational-questions} + +Operationale Regeln können Sicherheit, Fortschritt, Ressourcengrenzen und die Übereinstimmung mit Implementierungen beweisen. Eine Einschränkung entsteht, wenn die operative Mechanik vor der beabsichtigten abstrakten Bedeutung gewählt wird: Implementierungsentscheidungen können versehentlich zu semantischen Festlegungen werden. + +Denotational Design lehnt operationale Semantik nicht ab. Es fordert dazu auf, zuerst den semantischen Bereich, die Komposition und die Gesetze festzulegen und anschließend das operationale Modell damit in Beziehung zu setzen. + +| Sicht | Frage | +| --- | --- | +| Denotationell | Was bedeutet das Gesamtprogramm? | +| Operational | Durch welche Übergänge wird es ausgewertet? | +| Korrektheit | Bewahren diese Übergänge die beabsichtigte Bedeutung? | + +Die folgenden Clips veranschaulichen die Gefahr, operationale Beschreibungen als einzige Erkenntnisquelle zu behandeln. + +
Die operationale Beschreibung ist nicht die ganze Bedeutung (1 von 2)
+ +
Die operationale Beschreibung ist nicht die ganze Bedeutung (2 von 2)
diff --git a/src/concepts/operational_semantics.es.md b/src/concepts/operational_semantics.es.md new file mode 100644 index 0000000..cdddc77 --- /dev/null +++ b/src/concepts/operational_semantics.es.md @@ -0,0 +1,121 @@ + + +# Semántica operacional {#operational-semantics} + +```admonish tip title="Relacionado" +La perspectiva semántica: [Diseño denotacional](../denotational-design/design.md) +Diseño basado en el significado en Rust: [Lenguaje y procesos de compilación](../rust-dd/compiler-pipelines.md) +Conceptos: [Mónada libre](free_monad.md), [Estilo de paso de continuaciones](cps.md), [Defuncionalización](defunctionalization.md) +Perspectivas: [De la semántica a las máquinas](../insights/operational_semantics.md) +``` + +## Definición {#definition} + +La **semántica operacional** describe el comportamiento de un programa mediante juicios de evaluación o transiciones entre **configuraciones**. Una configuración puede contener un fragmento de programa junto con un entorno, un almacén, una continuación u otro estado abstracto de máquina. + +La descripción es matemática: establece qué evaluaciones o transiciones son válidas. Un intérprete o una máquina virtual puede implementar esas reglas, pero una implementación concreta no es en sí misma la definición. + +```admonish note title="Ubicación semántica" +La semántica operacional es una semántica precisa, no un mero detalle informal de implementación. Explica el comportamiento mediante reglas de evaluación o transición. [El diseño denotacional](../denotational-design/design.md) plantea una pregunta de diseño previa y complementaria: ¿qué significados composicionales y ecuaciones deberían preservar esas reglas? +``` + +## Estilos de semántica operacional {#styles-of-operational-semantics} + +### Pequeños pasos (semántica operacional estructural) {#small-step-structural-operational-semantics} + +El cálculo se divide en transiciones atómicas: + +$$ \begin{aligned} 2 + 3 &\to 5 \\ (2 + 3) \cdot 4 &\to 5 \cdot 4 \to 20 \end{aligned} $$ + +Útil para modelar la concurrencia, la intercalación y la ejecución parcial. + +### Grandes pasos (semántica natural) {#big-step-natural-semantics} + +Describe la evaluación en términos de resultados finales: + +$$ (2 + 3) \cdot 4 \Downarrow 20 $$ + +Suele facilitar el razonamiento sobre programas que terminan. + +## Reglas formales {#formal-rules} + +La semántica operacional suele expresarse mediante **reglas de inferencia**. Para un lenguaje aritmético sencillo: + +$$ E ::= n \mid E + E $$ + +Para la evaluación de izquierda a derecha, se necesitan tres reglas: + +$$ \frac{E_1 \to E_1'}{E_1 + E_2 \to E_1' + E_2} \qquad \frac{E_2 \to E_2'}{n + E_2 \to n + E_2'} \qquad n_1 + n_2 \to n_3 \quad \text{where } n_3 = n_1 + n_2 $$ + +Las dos primeras reglas seleccionan la siguiente subexpresión reducible. La tercera realiza la suma cuando ambos operandos son valores. + +Traza de evaluación: + +$$ (1 + 2) + 3 \to 3 + 3 \to 6 $$ + +## Por qué es importante {#why-it-matters} + +* Proporciona un **modelo de ejecución preciso, similar a una máquina**. +* Sirve de base para intérpretes y máquinas virtuales. +* Permite razonar sobre corrección, uso de recursos y seguridad. + +## Relación con otros conceptos {#relation-to-other-concepts} + +* Una **mónada libre** proporciona sintaxis de instrucciones y secuenciación. Las reglas operacionales pueden describir cómo se evalúa un programa en esa representación. +* **CPS** hace explícito el resto del cálculo mediante una continuación. Las reglas operacionales pueden describir cómo se pasan valores a esas continuaciones. +* La **defuncionalización** reemplaza una familia conocida de funciones por datos de primer orden y una operación `apply`. Las reglas operacionales pueden describir los estados explícitos de máquina resultantes. + +Estos son objetos y transformaciones a los que se puede asignar una semántica operacional. No son semántica operacional en sí mismos. + +## En la práctica {#in-practice} + +Las reglas operacionales pueden guiar un intérprete y ofrecer un modelo preciso con el que comprobarlo: + +* La **EVM** se puede modelar de manera natural como un sistema de transición de estados de pequeños pasos, mientras que una ejecución completa que termina también puede relacionarse mediante un juicio de grandes pasos. +* Las reglas de pequeños pasos suelen corresponder directamente a `match` brazos de coincidencia en un intérprete de Rust. + +$$ n_1 + n_2 \to n_3 $$ + +La relación completa de izquierda a derecha anterior se puede representar con código Rust: + +```rust,noplayground +enum Expr { + Num(i64), + Add(Box, Box), +} + +fn step(expr: Expr) -> Option { + match expr { + Expr::Num(_) => None, + Expr::Add(left, right) => match (*left, *right) { + (Expr::Num(a), Expr::Num(b)) => Some(Expr::Num(a + b)), + (left @ Expr::Num(_), right) => step(right).map(|next| { + Expr::Add(Box::new(left), Box::new(next)) + }), + (left, right) => step(left).map(|next| { + Expr::Add(Box::new(next), Box::new(right)) + }), + }, + } +} +``` + +Esta función realiza una transición. Las aplicaciones repetidas producen la traza mostrada; devolver `None` significa que la expresión ya es un valor. + +## Preguntas operacionales y denotacionales {#operational-and-denotational-questions} + +Las reglas operacionales pueden demostrar seguridad, progreso, límites de recursos y correspondencia con las implementaciones. La limitación aparece cuando se elige primero la maquinaria operacional, antes de definir el significado abstracto pretendido: las decisiones de implementación pueden convertirse accidentalmente en compromisos semánticos. + +El diseño denotacional no rechaza la semántica operacional. Nos pide definir primero el dominio semántico, la composición y las leyes, y después relacionarlos con el modelo operacional. + +| Perspectiva | Pregunta | +| --- | --- | +| Denotacional | ¿Qué significa el programa completo? | +| Operacional | ¿Mediante qué transiciones se evalúa? | +| Corrección | ¿Preservan esas transiciones el significado pretendido? | + +Los siguientes vídeos ilustran el peligro de tratar las descripciones operacionales como la única fuente de conocimiento. + +
La descripción operacional no abarca todo el significado (1 de 2)
+ +
La descripción operacional no abarca todo el significado (2 de 2)
diff --git a/src/concepts/operational_semantics.ja.md b/src/concepts/operational_semantics.ja.md new file mode 100644 index 0000000..327e82c --- /dev/null +++ b/src/concepts/operational_semantics.ja.md @@ -0,0 +1,121 @@ + + +# 操作的意味論 {#operational-semantics} + +```admonish tip title="関連項目" +意味論的な見方:[Denotational Design](../denotational-design/design.md) +Rustで意味から設計する:[言語とコンパイラーパイプライン](../rust-dd/compiler-pipelines.md) +概念:[自由モナド](free_monad.md)、[継続渡し形式](cps.md)、[関数のデファンクショナライズ](defunctionalization.md) +洞察:[意味論から機械へ](../insights/operational_semantics.md) +``` + +## 定義 {#definition} + +**操作的意味論**は、評価判断または**構成**間の遷移によってプログラムの振る舞いを記述します。構成には、プログラム断片と環境、ストア、継続、その他の抽象機械状態を含める場合があります。 + +この記述は数学的なもので、どの評価や遷移が妥当かを述べます。インタープリターや仮想マシンがその規則を実装することはありますが、特定の実装自体が定義になるわけではありません。 + +```admonish note title="意味論上の位置付け" +操作的意味論は正確な意味論であり、単なる非形式的な実装詳細ではありません。評価規則または遷移規則によって振る舞いを説明します。[Denotational Design](../denotational-design/design.md)はそれを補う、より先行する設計上の問いを立てます。すなわち、どのような合成可能な意味と等式を、その規則に保持させるかです。 +``` + +## 操作的意味論の形式 {#styles-of-operational-semantics} + +### 小ステップ意味論(構造的操作意味論) {#small-step-structural-operational-semantics} + +計算を原子的な遷移に分解します。 + +$$ \begin{aligned} 2 + 3 &\to 5 \\ (2 + 3) \cdot 4 &\to 5 \cdot 4 \to 20 \end{aligned} $$ + +並行性、インターリーブ、部分実行のモデル化に有用です。 + +### 大ステップ意味論(自然意味論) {#big-step-natural-semantics} + +最終結果を使って評価を記述する。 + +$$ (2 + 3) \cdot 4 \Downarrow 20 $$ + +停止するプログラムについて推論する際に、明快なことが多い。 + +## 形式規則 {#formal-rules} + +操作的意味論は通常、**推論規則**で表されます。簡単な算術言語なら、次のようになります。 + +$$ E ::= n \mid E + E $$ + +左から右への評価には、三つの規則が必要です。 + +$$ \frac{E_1 \to E_1'}{E_1 + E_2 \to E_1' + E_2} \qquad \frac{E_2 \to E_2'}{n + E_2 \to n + E_2'} \qquad n_1 + n_2 \to n_3 \quad \text{where } n_3 = n_1 + n_2 $$ + +最初の二つの規則は、次に簡約できる部分式を選びます。三つ目は、両方のオペランドが値になった後で加算を行います。 + +評価トレース: + +$$ (1 + 2) + 3 \to 3 + 3 \to 6 $$ + +## なぜ重要か {#why-it-matters} + +* 実行について、**機械を厳密に模したモデル**を提供する。 +* インタープリターと仮想マシンの基盤となる。 +* 正しさ、リソース使用、安全性に関する推論を支える。 + +## ほかの概念との関係 {#relation-to-other-concepts} + +* **自由モナド**は命令構文と逐次実行を提供します。その表現で書かれたプログラムの評価は、操作規則で記述できます。 +* **CPS**は、計算の残りを継続として明示します。値がその継続へ渡される様子は、操作規則で記述できます。 +* **デファンクショナライズ**は既知の関数族を一階データに置き換え、`apply`操作を明示します。生成された機械状態は、操作規則で記述できます。 + +これらは操作的意味論を与えられる対象や変換であり、それ自体が操作的意味論なのではありません。 + +## 実践での利用 {#in-practice} + +操作規則を使うと、インタープリターを導き、照合のための厳密なモデルを提供できます。 + +* **EVM**は小ステップの状態遷移系として自然にモデル化できます。一方、停止する実行全体は大ステップの判断でも関連付けられます。 +* 小ステップ規則は、Rustインタープリターの`match`アームとよく対応することがあります。 + +$$ n_1 + n_2 \to n_3 $$ + +左から右への関係全体は、次のRustコードで表現できます。 + +```rust,noplayground +enum Expr { + Num(i64), + Add(Box, Box), +} + +fn step(expr: Expr) -> Option { + match expr { + Expr::Num(_) => None, + Expr::Add(left, right) => match (*left, *right) { + (Expr::Num(a), Expr::Num(b)) => Some(Expr::Num(a + b)), + (left @ Expr::Num(_), right) => step(right).map(|next| { + Expr::Add(Box::new(left), Box::new(next)) + }), + (left, right) => step(left).map(|next| { + Expr::Add(Box::new(next), Box::new(right)) + }), + }, + } +} +``` + +この関数は遷移を一度だけ実行します。繰り返し適用すると表示されたトレースになり、`None`を返す場合は式がすでに値になっています。 + +## 操作上の問いと表示上の問い {#operational-and-denotational-questions} + +操作規則を使うと、安全性、進行性、リソース境界、実装との対応関係を証明できます。意図された抽象的な意味を決める前に操作機構を選ぶと、実装上の選択が意図しない意味論上の約束になるおそれがあります。 + +Denotational Designは操作的意味論を否定しません。先に意味論的領域、合成、法則を明示し、その後で操作モデルとの関係を定めます。 + +| 観点 | 問い | +| --- | --- | +| 表示上 | プログラム全体は何を意味するか。 | +| 操作上 | どのような遷移で評価されるか。 | +| 正しさ | その遷移は意図された意味を保つか。 | + +次のクリップでは、操作上の記述だけを洞察のよりどころにする危険性を取り上げます。 + +
操作上の記述だけでは意味の全体を捉えられない(1/2)
+ +
操作上の記述だけでは意味の全体を捉えられない(2/2)
diff --git a/src/concepts/operational_semantics.ko.md b/src/concepts/operational_semantics.ko.md new file mode 100644 index 0000000..c2973da --- /dev/null +++ b/src/concepts/operational_semantics.ko.md @@ -0,0 +1,121 @@ + + +# 작동 의미론 {#operational-semantics} + +```admonish tip title="관련 항목" +의미론적 관점: [표시적 설계](../denotational-design/design.md) +Rust에서 의미로 설계하기: [언어와 컴파일러 파이프라인](../rust-dd/compiler-pipelines.md) +개념: [자유 모나드](free_monad.md), [연속 전달 스타일](cps.md), [디펑셔널라이제이션](defunctionalization.md) +통찰: [의미론에서 기계로](../insights/operational_semantics.md) +``` + +## 정의 {#definition} + +**작동 의미론**은 평가 판단이나 **구성** 사이의 전이로 프로그램 동작을 설명합니다. 구성에는 프로그램 일부와 함께 환경, 저장소, 연속 실행 기록 또는 다른 추상 기계 상태가 포함될 수 있습니다. + +이 설명은 수학적입니다. 어떤 평가나 전이가 유효한지 명시합니다. 인터프리터나 가상 머신이 그 규칙을 구현할 수 있지만, 특정 구현 자체가 정의는 아닙니다. + +```admonish note title="의미론적 위치" +작동 의미론은 비공식적인 구현 세부가 아니라 정확한 의미론입니다. 평가 규칙이나 전이 규칙으로 동작을 설명합니다. [표시적 설계](../denotational-design/design.md)는 이를 보완하는 선행 설계 질문을 던집니다. 그 규칙은 어떤 합성 가능한 의미와 등식을 보존해야 할까요? +``` + +## 작동 의미론의 유형 {#styles-of-operational-semantics} + +### 소단계 의미론(구조적 작동 의미론) {#small-step-structural-operational-semantics} + +계산을 원자적 전이로 나눕니다: + +$$ \begin{aligned} 2 + 3 &\to 5 \\ (2 + 3) \cdot 4 &\to 5 \cdot 4 \to 20 \end{aligned} $$ + +동시성, 인터리빙, 부분 실행을 모델링하는 데 유용합니다. + +### 대단계 의미론(자연 의미론) {#big-step-natural-semantics} + +최종 결과로 평가를 설명합니다: + +$$ (2 + 3) \cdot 4 \Downarrow 20 $$ + +종료하는 프로그램을 추론할 때 더 명확한 경우가 많습니다. + +## 형식 규칙 {#formal-rules} + +작동 의미론은 보통 **추론 규칙**으로 표현합니다. 간단한 산술 언어를 예로 들어 보겠습니다: + +$$ E ::= n \mid E + E $$ + +왼쪽에서 오른쪽으로 평가하려면 규칙 세 개가 필요합니다: + +$$ \frac{E_1 \to E_1'}{E_1 + E_2 \to E_1' + E_2} \qquad \frac{E_2 \to E_2'}{n + E_2 \to n + E_2'} \qquad n_1 + n_2 \to n_3 \quad \text{where } n_3 = n_1 + n_2 $$ + +앞의 두 규칙은 다음에 줄일 수식을 선택합니다. 세 번째 규칙은 피연산자가 모두 값이 되면 덧셈을 수행합니다. + +평가 추적: + +$$ (1 + 2) + 3 \to 3 + 3 \to 6 $$ + +## 중요한 이유 {#why-it-matters} + +* 실행에 대한 **정확한 기계식 모델**을 제공합니다. +* 인터프리터와 가상 머신의 토대입니다. +* 정확성, 자원 사용, 안전성을 추론하는 데 도움이 됩니다. + +## 다른 개념과의 관계 {#relation-to-other-concepts} + +* **자유 모나드**는 명령어 구문과 시퀀싱을 제공합니다. 작동 규칙은 해당 표현의 프로그램이 어떻게 평가되는지 설명할 수 있습니다. +* **CPS**는 계산의 나머지를 컨티뉴에이션으로 명시합니다. 작동 규칙은 값이 해당 컨티뉴에이션으로 전달되는 방식을 설명할 수 있습니다. +* **디펑셔널라이제이션**은 알려진 함수 계열을 일차 데이터와 `apply` 연산으로 대체합니다. 작동 규칙은 그 결과로 생긴 명시적 기계 상태를 설명할 수 있습니다. + +이들은 작동 의미론으로 설명할 수 있는 대상과 변환입니다. 그 자체가 작동 의미론은 아닙니다. + +## 실제 적용 {#in-practice} + +작동 규칙은 인터프리터를 안내하고 검사에 사용할 정확한 모델을 제공할 수 있습니다: + +* **EVM**은 소단계 상태 전이 시스템으로 자연스럽게 모델링할 수 있으며, 종료하는 전체 실행도 대단계 판단으로 연결할 수 있습니다. +* 소단계 규칙은 흔히 Rust 인터프리터의 `match` 분기와 직접 대응합니다. + +$$ n_1 + n_2 \to n_3 $$ + +위에 제시한 완전한 좌우 방향 관계는 Rust 코드로 나타낼 수 있습니다: + +```rust,noplayground +enum Expr { + Num(i64), + Add(Box, Box), +} + +fn step(expr: Expr) -> Option { + match expr { + Expr::Num(_) => None, + Expr::Add(left, right) => match (*left, *right) { + (Expr::Num(a), Expr::Num(b)) => Some(Expr::Num(a + b)), + (left @ Expr::Num(_), right) => step(right).map(|next| { + Expr::Add(Box::new(left), Box::new(next)) + }), + (left, right) => step(left).map(|next| { + Expr::Add(Box::new(next), Box::new(right)) + }), + }, + } +} +``` + +이 함수는 전이 한 번을 수행합니다. 반복 적용하면 표시된 추적이 만들어집니다. `None`을 반환한다는 것은 식이 이미 값임을 뜻합니다. + +## 작동적 질문과 표시적 질문 {#operational-and-denotational-questions} + +작동 규칙은 안전성, 진행성, 자원 한도, 구현과의 대응 관계를 증명할 수 있습니다. 의도한 추상 의미보다 먼저 작동 장치를 선택하면 한계가 나타납니다. 구현 선택이 의도치 않은 의미론적 약속이 될 수 있습니다. + +표시적 설계는 작동 의미론을 거부하지 않습니다. 먼저 의미론적 영역, 합성, 법칙을 명시한 다음 작동 모델을 이들과 연결하자는 것입니다. + +| 관점 | 질문 | +| --- | --- | +| 표시적 | 프로그램 전체는 무엇을 의미하나요? | +| 작동적 | 어떤 전이로 평가되나요? | +| 정확성 | 그 전이가 의도한 의미를 보존하나요? | + +다음 영상은 작동 설명을 통찰의 유일한 원천으로 삼을 때의 위험을 보여 줍니다. + +
작동 설명이 의미 전체는 아니다 (1/2)
+ +
작동 설명이 의미 전체는 아니다 (2/2)
diff --git a/src/concepts/operational_semantics.ru.md b/src/concepts/operational_semantics.ru.md new file mode 100644 index 0000000..66e71f4 --- /dev/null +++ b/src/concepts/operational_semantics.ru.md @@ -0,0 +1,121 @@ + + +# Операционная семантика {#operational-semantics} + +```admonish tip title="Связанные материалы" +«Семантический взгляд»: [Денотационное проектирование](../denotational-design/design.md) +«Проектирование на основе смысла в Rust»: [Язык и конвейеры компилятора](../rust-dd/compiler-pipelines.md) +«Понятия»: [Свободная монада](free_monad.md), [Стиль передачи продолжений](cps.md), [Дефункционализация](defunctionalization.md) +«Идеи»: [От семантики к машинам](../insights/operational_semantics.md) +``` + +## Определение {#definition} + +**Операционная семантика** описывает поведение программы с помощью оценочных суждений или переходов между **конфигурациями**. Конфигурация может содержать фрагмент программы вместе с окружением, хранилищем, продолжением или другим состоянием абстрактной машины. + +Это математическое описание, задающее допустимые вычисления или переходы. Интерпретатор или виртуальная машина могут реализовывать эти правила, но конкретная реализация сама по себе не является определением. + +```admonish note title="Семантическое место" +Операционная семантика — точная семантика, а не просто неформальная деталь реализации. Она объясняет поведение через правила вычисления и перехода. [Денотационное проектирование](../denotational-design/design.md) задаёт предшествующий и дополняющий вопрос проектирования: какие композиционные смыслы и уравнения должны сохранять эти правила? +``` + +## Виды операционной семантики {#styles-of-operational-semantics} + +### Малые шаги (структурная операционная семантика) {#small-step-structural-operational-semantics} + +Вычисление разбивается на атомарные переходы: + +$$ \begin{aligned} 2 + 3 &\to 5 \\ (2 + 3) \cdot 4 &\to 5 \cdot 4 \to 20 \end{aligned} $$ + +Полезно для моделирования параллелизма, чередования и частичного выполнения. + +### Большие шаги (естественная семантика) {#big-step-natural-semantics} + +Описывает вычисление через конечные результаты: + +$$ (2 + 3) \cdot 4 \Downarrow 20 $$ + +Часто позволяет яснее рассуждать о завершающихся программах. + +## Формальные правила {#formal-rules} + +Операционную семантику обычно задают с помощью **правил вывода**. Для простого арифметического языка: + +$$ E ::= n \mid E + E $$ + +Для вычисления слева направо нужны три правила: + +$$ \frac{E_1 \to E_1'}{E_1 + E_2 \to E_1' + E_2} \qquad \frac{E_2 \to E_2'}{n + E_2 \to n + E_2'} \qquad n_1 + n_2 \to n_3 \quad \text{where } n_3 = n_1 + n_2 $$ + +Первые два правила выбирают следующее сокращаемое подвыражение. Третье выполняет сложение, когда оба операнда уже являются значениями. + +Трасса вычисления: + +$$ (1 + 2) + 3 \to 3 + 3 \to 6 $$ + +## Зачем это нужно {#why-it-matters} + +* Даёт **точную модель выполнения, подобную машине**. +* Служит основой для интерпретаторов и виртуальных машин. +* Помогает рассуждать о корректности, расходе ресурсов и безопасности. + +## Связь с другими понятиями {#relation-to-other-concepts} + +* **Свободная монада** предоставляет синтаксис инструкций и последовательность их выполнения. Операционные правила могут описывать, как вычисляется программа в таком представлении. +* **CPS** явно представляет остаток вычисления в виде продолжения. Операционные правила могут описывать, как значения передаются этим продолжениям. +* **Дефункционализация** заменяет известное семейство функций данными первого порядка и операцией `apply`. Операционные правила могут описывать получившиеся явные состояния машины. + +Это объекты и преобразования, которым можно задать операционную семантику. Сами по себе они операционной семантикой не являются. + +## На практике {#in-practice} + +Операционные правила могут направлять разработку интерпретатора и служить точной моделью для его проверки: + +* **EVM** естественно моделируется системой переходов между состояниями с малыми шагами; завершающееся вычисление целиком также можно описать суждением о больших шагах. +* Правила с малыми шагами часто напрямую соответствуют ветвям `match` интерпретатора Rust. + +$$ n_1 + n_2 \to n_3 $$ + +Полное отношение вычисления слева направо выше можно выразить кодом Rust: + +```rust,noplayground +enum Expr { + Num(i64), + Add(Box, Box), +} + +fn step(expr: Expr) -> Option { + match expr { + Expr::Num(_) => None, + Expr::Add(left, right) => match (*left, *right) { + (Expr::Num(a), Expr::Num(b)) => Some(Expr::Num(a + b)), + (left @ Expr::Num(_), right) => step(right).map(|next| { + Expr::Add(Box::new(left), Box::new(next)) + }), + (left, right) => step(left).map(|next| { + Expr::Add(Box::new(next), Box::new(right)) + }), + }, + } +} +``` + +Эта функция выполняет один переход. Повторное применение даёт показанную трассу; возврат `None` означает, что выражение уже является значением. + +## Операционные и денотационные вопросы {#operational-and-denotational-questions} + +Операционные правила позволяют доказывать безопасность, прогресс, границы ресурсов и соответствие реализациям. Ограничение возникает, когда операционные механизмы выбирают раньше предполагаемого абстрактного смысла: проектные решения реализации могут случайно превратиться в семантические обязательства. + +Денотационное проектирование не отвергает операционную семантику. Оно предлагает сначала задать семантическую область, композицию и законы, а затем связать с ними операционную модель. + +| Взгляд | Вопрос | +| --- | --- | +| Денотационный | Что означает программа целиком? | +| Операционный | Посредством каких переходов она вычисляется? | +| Корректность | Сохраняют ли эти переходы предполагаемый смысл? | + +Следующие фрагменты показывают, почему операционное описание опасно считать единственным источником понимания. + +
Операционное описание — не весь смысл (1 из 2)
+ +
Операционное описание — не весь смысл (2 из 2)
diff --git a/src/concepts/operational_semantics.uk.md b/src/concepts/operational_semantics.uk.md new file mode 100644 index 0000000..3c67041 --- /dev/null +++ b/src/concepts/operational_semantics.uk.md @@ -0,0 +1,121 @@ + + +# Операційна семантика {#operational-semantics} + +```admonish tip title="Пов’язані матеріали" +Семантичний погляд: [Денотаційне проєктування](../denotational-design/design.md) +Проєктування від значення в Rust: [Мова й конвеєри компілятора](../rust-dd/compiler-pipelines.md) +Поняття: [Вільна монада](free_monad.md), [Стиль передавання продовжень](cps.md), [Дефункціоналізація](defunctionalization.md) +Інсайти: [Від семантики до машин](../insights/operational_semantics.md) +``` + +## Визначення {#definition} + +**Операційна семантика** описує поведінку програми за допомогою суджень про обчислення або переходів між **конфігураціями**. Конфігурація може містити фрагмент програми разом із середовищем, сховищем, продовженням чи іншим абстрактним станом машини. + +Це математичний опис: він визначає, які обчислення чи переходи є допустимими. Інтерпретатор або віртуальна машина можуть реалізувати ці правила, але конкретна реалізація сама по собі не є визначенням. + +```admonish note title="Семантичне місце" +Операційна семантика — це точна семантика, а не просто неформальні деталі реалізації. Вона пояснює поведінку правилами обчислення чи переходів. [Денотаційне проєктування](../denotational-design/design.md) ставить доповнювальне, попереднє проєктне запитання: які композиційні значення й рівності мають зберігати ці правила? +``` + +## Стилі операційної семантики {#styles-of-operational-semantics} + +### Малокрокова (структурна операційна семантика) {#small-step-structural-operational-semantics} + +Обчислення розбивається на атомарні переходи: + +$$ \begin{aligned} 2 + 3 &\to 5 \\ (2 + 3) \cdot 4 &\to 5 \cdot 4 \to 20 \end{aligned} $$ + +Корисно для моделювання паралельності, чергування та часткового виконання. + +### Великокрокова (природна семантика) {#big-step-natural-semantics} + +Описує обчислення через кінцеві результати: + +$$ (2 + 3) \cdot 4 \Downarrow 20 $$ + +Часто зрозуміліша для міркувань про програми, що завершуються. + +## Формальні правила {#formal-rules} + +Операційну семантику зазвичай задають **правилами виведення**. Розгляньмо просту арифметичну мову: + +$$ E ::= n \mid E + E $$ + +Для обчислення зліва направо потрібні три правила: + +$$ \frac{E_1 \to E_1'}{E_1 + E_2 \to E_1' + E_2} \qquad \frac{E_2 \to E_2'}{n + E_2 \to n + E_2'} \qquad n_1 + n_2 \to n_3 \quad \text{where } n_3 = n_1 + n_2 $$ + +Перші два правила визначають наступний редукований підвираз. Третє виконує додавання, коли обидва операнди вже є значеннями. + +Траса обчислення: + +$$ (1 + 2) + 3 \to 3 + 3 \to 6 $$ + +## Чому це важливо {#why-it-matters} + +* Надає **точну, схожу на машинну модель** виконання. +* Основа для інтерпретаторів і віртуальних машин. +* Допомагає міркувати про коректність, використання ресурсів і безпеку. + +## Зв’язок з іншими поняттями {#relation-to-other-concepts} + +* **Вільна монада** надає синтаксис інструкцій і їх послідовного виконання. Операційні правила можуть описувати обчислення програми в такому представленні. +* **CPS** робить продовження обчислення явним. Операційні правила можуть описувати, як значення передаються цим продовженням. +* **Дефункціоналізація** замінює відоме сімейство функцій даними першого порядку й операцією `apply`. Операційні правила можуть описувати отримані явні стани машини. + +Це об’єкти й перетворення, для яких можна задати операційну семантику. Самі вони не є операційною семантикою. + +## На практиці {#in-practice} + +Операційні правила можуть скеровувати роботу інтерпретатора й надавати точну модель для його перевірки: + +* **EVM** природно моделювати малокроковою системою переходів станів, а завершене виконання як ціле можна пов’язати з великокроковим судженням. +* Малокрокові правила часто безпосередньо відповідають гілкам `match` в інтерпретаторі Rust. + +$$ n_1 + n_2 \to n_3 $$ + +Повне відношення обчислення зліва направо можна представити кодом Rust: + +```rust,noplayground +enum Expr { + Num(i64), + Add(Box, Box), +} + +fn step(expr: Expr) -> Option { + match expr { + Expr::Num(_) => None, + Expr::Add(left, right) => match (*left, *right) { + (Expr::Num(a), Expr::Num(b)) => Some(Expr::Num(a + b)), + (left @ Expr::Num(_), right) => step(right).map(|next| { + Expr::Add(Box::new(left), Box::new(next)) + }), + (left, right) => step(left).map(|next| { + Expr::Add(Box::new(next), Box::new(right)) + }), + }, + } +} +``` + +Ця функція виконує один перехід. Повторне застосування дає показану трасу; повернення `None` означає, що вираз уже є значенням. + +## Операційні та денотаційні запитання {#operational-and-denotational-questions} + +Операційні правила дають змогу доводити безпеку, прогрес, межі ресурсів і відповідність реалізаціям. Обмеження виникає, коли операційні механізми вибирають раніше за задумане абстрактне значення: рішення реалізації можуть випадково стати семантичними зобов’язаннями. + +Денотаційне проєктування не відкидає операційну семантику. Воно пропонує спершу визначити семантичну область, композицію та закони, а потім пов’язати з ними операційну модель. + +| Погляд | Запитання | +| --- | --- | +| Денотаційний | Що означає програма як ціле? | +| Операційний | За допомогою яких переходів її обчислюють? | +| Коректність | Чи зберігають ці переходи задумане значення? | + +Наступні відеофрагменти показують, чим небезпечно вважати операційні описи єдиним джерелом розуміння. + +
Операційний опис не розкриває всього значення (1 із 2)
+ +
Операційний опис не розкриває всього значення (2 із 2)
diff --git a/src/concepts/operational_semantics.vi.md b/src/concepts/operational_semantics.vi.md new file mode 100644 index 0000000..b351527 --- /dev/null +++ b/src/concepts/operational_semantics.vi.md @@ -0,0 +1,121 @@ + + +# Ngữ nghĩa vận hành {#operational-semantics} + +```admonish tip title="Liên quan" +Góc nhìn ngữ nghĩa: [Thiết kế theo ngữ nghĩa](../denotational-design/design.md) +Thiết kế theo ngữ nghĩa trong Rust: [Quy trình ngôn ngữ và trình biên dịch](../rust-dd/compiler-pipelines.md) +Khái niệm: [Monad tự do](free_monad.md), [Phong cách truyền tiếp nối](cps.md), [Phi chức năng hóa](defunctionalization.md) +Nhận định: [Từ ngữ nghĩa đến máy móc](../insights/operational_semantics.md) +``` + +## Định nghĩa {#definition} + +**Ngữ nghĩa vận hành** mô tả hành vi chương trình bằng các phán đoán đánh giá hoặc chuyển tiếp giữa **cấu hình**. Một cấu hình có thể chứa một phần chương trình cùng môi trường, vùng lưu trữ, tiếp nối hoặc trạng thái máy trừu tượng khác. + +Mô tả này có tính toán học: nó nêu những phép đánh giá hoặc chuyển tiếp nào là hợp lệ. Bộ diễn giải hoặc máy ảo có thể triển khai các quy tắc đó, nhưng bản thân cách triển khai cụ thể không phải định nghĩa. + +```admonish note title="Vị trí ngữ nghĩa" +Ngữ nghĩa vận hành là ngữ nghĩa chính xác, không chỉ là chi tiết triển khai không chính thức. Nó giải thích hành vi bằng quy tắc đánh giá hoặc chuyển tiếp. [Thiết kế theo ngữ nghĩa](../denotational-design/design.md) đặt ra câu hỏi thiết kế bổ trợ, có trước: các ý nghĩa hợp thành và phương trình nào cần được những quy tắc đó bảo toàn? +``` + +## Các phong cách ngữ nghĩa vận hành {#styles-of-operational-semantics} + +### Bước nhỏ (ngữ nghĩa vận hành cấu trúc) {#small-step-structural-operational-semantics} + +Tính toán được chia thành các chuyển tiếp nguyên tử: + +$$ \begin{aligned} 2 + 3 &\to 5 \\ (2 + 3) \cdot 4 &\to 5 \cdot 4 \to 20 \end{aligned} $$ + +Hữu ích để mô hình hóa tính đồng thời, đan xen và thực thi từng phần. + +### Bước lớn (ngữ nghĩa tự nhiên) {#big-step-natural-semantics} + +Mô tả việc đánh giá theo kết quả cuối cùng: + +$$ (2 + 3) \cdot 4 \Downarrow 20 $$ + +Thường rõ ràng hơn khi lập luận về các chương trình kết thúc. + +## Quy tắc hình thức {#formal-rules} + +Ngữ nghĩa vận hành thường được đưa ra bằng **quy tắc suy diễn**. Với một ngôn ngữ số học đơn giản: + +$$ E ::= n \mid E + E $$ + +Với đánh giá từ trái sang phải, cần ba quy tắc: + +$$ \frac{E_1 \to E_1'}{E_1 + E_2 \to E_1' + E_2} \qquad \frac{E_2 \to E_2'}{n + E_2 \to n + E_2'} \qquad n_1 + n_2 \to n_3 \quad \text{where } n_3 = n_1 + n_2 $$ + +Hai quy tắc đầu chọn biểu thức con có thể rút gọn tiếp theo. Quy tắc thứ ba thực hiện phép cộng khi cả hai toán hạng đã là giá trị. + +Vết đánh giá: + +$$ (1 + 2) + 3 \to 3 + 3 \to 6 $$ + +## Vì sao điều này quan trọng {#why-it-matters} + +* Cung cấp một **mô hình thực thi chính xác, gần với máy**. +* Nền tảng cho bộ diễn giải và máy ảo. +* Hỗ trợ lập luận về tính đúng đắn, mức dùng tài nguyên và an toàn. + +## Quan hệ với các khái niệm khác {#relation-to-other-concepts} + +* **Monad tự do** cung cấp cú pháp lệnh và phép tuần tự hóa. Các quy tắc vận hành có thể mô tả cách chương trình trong biểu diễn đó được đánh giá. +* **CPS** làm phần còn lại của phép tính trở nên tường minh dưới dạng tiếp nối. Các quy tắc vận hành có thể mô tả cách giá trị được truyền cho các tiếp nối ấy. +* **Phi chức năng hóa** thay một họ hàm đã biết bằng dữ liệu bậc nhất và một phép toán `apply`. Các quy tắc vận hành có thể mô tả những trạng thái máy tường minh thu được. + +Đây là các đối tượng và phép biến đổi có thể được gán ngữ nghĩa vận hành. Bản thân chúng không phải ngữ nghĩa vận hành. + +## Trong thực tế {#in-practice} + +Quy tắc vận hành có thể hướng dẫn bộ diễn giải và cung cấp mô hình chính xác để kiểm tra nó: + +* **EVM** có thể được mô hình hóa tự nhiên như hệ chuyển trạng thái bước nhỏ, trong khi toàn bộ lần thực thi kết thúc cũng có thể được liên hệ bằng phán đoán bước lớn. +* Các quy tắc bước nhỏ thường tương ứng chặt chẽ với các nhánh `match` trong bộ diễn giải Rust. + +$$ n_1 + n_2 \to n_3 $$ + +Quan hệ trái sang phải đầy đủ ở trên có thể được biểu diễn bằng mã Rust: + +```rust,noplayground +enum Expr { + Num(i64), + Add(Box, Box), +} + +fn step(expr: Expr) -> Option { + match expr { + Expr::Num(_) => None, + Expr::Add(left, right) => match (*left, *right) { + (Expr::Num(a), Expr::Num(b)) => Some(Expr::Num(a + b)), + (left @ Expr::Num(_), right) => step(right).map(|next| { + Expr::Add(Box::new(left), Box::new(next)) + }), + (left, right) => step(left).map(|next| { + Expr::Add(Box::new(next), Box::new(right)) + }), + }, + } +} +``` + +Hàm này thực hiện một chuyển tiếp. Áp dụng lặp lại sẽ tạo ra vết hiển thị; trả về `None` nghĩa là biểu thức đã là một giá trị. + +## Câu hỏi vận hành và ngữ nghĩa chỉ định {#operational-and-denotational-questions} + +Các quy tắc vận hành có thể chứng minh tính an toàn, tiến triển, giới hạn tài nguyên và sự tương ứng với cách triển khai. Giới hạn xuất hiện khi chọn cơ chế vận hành trước ý nghĩa trừu tượng dự định: lựa chọn triển khai có thể vô tình trở thành cam kết ngữ nghĩa. + +Thiết kế theo ngữ nghĩa không bác bỏ ngữ nghĩa vận hành. Nó yêu cầu ta phát biểu trước miền ngữ nghĩa, phép hợp thành và các định luật, rồi liên hệ mô hình vận hành với chúng. + +| Góc nhìn | Câu hỏi | +| --- | --- | +| Ngữ nghĩa chỉ định | Toàn bộ chương trình có ý nghĩa gì? | +| Vận hành | Chương trình được đánh giá qua những chuyển tiếp nào? | +| Tính đúng đắn | Các chuyển tiếp đó có bảo toàn ý nghĩa dự định không? | + +Các đoạn phim sau gợi mở nguy cơ khi xem mô tả vận hành là nguồn hiểu biết duy nhất. + +
Mô tả vận hành không phải toàn bộ ý nghĩa (1/2)
+ +
Mô tả vận hành không phải toàn bộ ý nghĩa (2/2)
diff --git a/src/concepts/operational_semantics.zh-hant.md b/src/concepts/operational_semantics.zh-hant.md new file mode 100644 index 0000000..9b4c8f9 --- /dev/null +++ b/src/concepts/operational_semantics.zh-hant.md @@ -0,0 +1,121 @@ + + +# 操作語義 {#operational-semantics} + +```admonish tip title="相關內容" +語義視角:[指稱設計](../denotational-design/design.md) +Rust 中的語義驅動設計:[語言與編譯器流水線](../rust-dd/compiler-pipelines.md) +概念:[自由單子](free_monad.md)、[延續傳遞風格](cps.md)、[去函式化](defunctionalization.md) +洞見:[從語義到機器](../insights/operational_semantics.md) +``` + +## 定義 {#definition} + +**操作語義**透過求值判斷或**配置**之間的狀態轉換來描述程式行為。配置可能包含程式片段,以及環境、儲存、延續或其他抽象機器狀態。 + +這種描述具有數學性質:它陳述哪些求值或狀態轉換有效。直譯器或虛擬機器可以實作這些規則,但某個具體實作本身並非定義。 + +```admonish note title="語義定位" +操作語義是一種精確的語義,而非非正式的實作細節。它透過求值規則或轉換規則說明行為。[指稱設計](../denotational-design/design.md)提出了一個互補且更早的設計問題:這些規則應保留哪些可組合含義與等式? +``` + +## 操作語義的形式 {#styles-of-operational-semantics} + +### 小步操作語義(結構操作語義) {#small-step-structural-operational-semantics} + +計算被拆分為原子轉換: + +$$ \begin{aligned} 2 + 3 &\to 5 \\ (2 + 3) \cdot 4 &\to 5 \cdot 4 \to 20 \end{aligned} $$ + +適用於建模併發、交錯執行與部分執行。 + +### 大步操作語義(自然語義) {#big-step-natural-semantics} + +根據最終結果描述求值: + +$$ (2 + 3) \cdot 4 \Downarrow 20 $$ + +推理終止程式時通常更清晰。 + +## 形式規則 {#formal-rules} + +操作語義通常採用**推理規則**給出。對於簡單算術語言: + +$$ E ::= n \mid E + E $$ + +從左到右求值時,需要三條規則: + +$$ \frac{E_1 \to E_1'}{E_1 + E_2 \to E_1' + E_2} \qquad \frac{E_2 \to E_2'}{n + E_2 \to n + E_2'} \qquad n_1 + n_2 \to n_3 \quad \text{where } n_3 = n_1 + n_2 $$ + +前兩條規則確定下一個可歸約子表示式。兩個運算元都成為值後,第三條規則執行加法。 + +求值軌跡: + +$$ (1 + 2) + 3 \to 3 + 3 \to 6 $$ + +## 為何重要 {#why-it-matters} + +* 提供**精確的類機器模型**來描述執行。 +* 為直譯器與虛擬機器奠定基礎。 +* 支援對正確性、資源使用與安全性的推理。 + +## 與其他概念的關係 {#relation-to-other-concepts} + +* **自由單子**提供指令語法與順序組合。操作規則可以描述該表示中的程式如何求值。 +* **CPS**將計算剩餘部分顯式表示為延續。操作規則可以描述值如何傳遞給這些延續。 +* **去函式化**會將已知函式族替換為一階資料,並提供一個`apply`操作。操作規則可以描述由此產生的顯式機器狀態。 + +這些都是可以賦予操作語義的物件與變換,本身並不是操作語義。 + +## 實踐中的應用 {#in-practice} + +操作規則可以指導直譯器實現,並提供一個用於檢查實現的精確模型: + +* **EVM**可以自然地建模為小步狀態轉換系統;也可以透過大步判斷描述完整的終止執行。 +* 小步規則通常與 Rust 直譯器中的`match`分支非常相似。 + +$$ n_1 + n_2 \to n_3 $$ + +上文完整的從左到右求值關係可以表示為 Rust 程式碼: + +```rust,noplayground +enum Expr { + Num(i64), + Add(Box, Box), +} + +fn step(expr: Expr) -> Option { + match expr { + Expr::Num(_) => None, + Expr::Add(left, right) => match (*left, *right) { + (Expr::Num(a), Expr::Num(b)) => Some(Expr::Num(a + b)), + (left @ Expr::Num(_), right) => step(right).map(|next| { + Expr::Add(Box::new(left), Box::new(next)) + }), + (left, right) => step(left).map(|next| { + Expr::Add(Box::new(next), Box::new(right)) + }), + }, + } +} +``` + +這個函式執行一次狀態轉換。重複應用即可得到所示軌跡;返回`None`表示表示式已經是一個值。 + +## 操作問題與指稱問題 {#operational-and-denotational-questions} + +操作規則可以證明安全性、進展性質、資源上限以及與實作的對應關係。如果在預期的抽象含義明確之前就選定了操作機制,限制便會顯現:實作選擇可能意外變成語義承諾。 + +指稱設計並不否定操作語義。它要求先陳述語義域、組合與定律,再將操作模型與其關聯起來。 + +| 視角 | 問題 | +| --- | --- | +| 指稱 | 整個程式意味著什麼? | +| 操作 | 透過哪些狀態轉換求值? | +| 正確性 | 這些狀態轉換是否保留了預期含義? | + +以下片段用於說明,將操作描述視為唯一洞見來源的危險。 + +
操作描述並非全部含義(1/2)
+ +
操作描述並非全部含義(2/2)
diff --git a/src/concepts/operational_semantics.zh.md b/src/concepts/operational_semantics.zh.md new file mode 100644 index 0000000..6152302 --- /dev/null +++ b/src/concepts/operational_semantics.zh.md @@ -0,0 +1,121 @@ + + +# 操作语义 {#operational-semantics} + +```admonish tip title="相关内容" +语义视角:[指称设计](../denotational-design/design.md) +Rust 中的语义驱动设计:[语言与编译器流水线](../rust-dd/compiler-pipelines.md) +概念:[自由单子](free_monad.md)、[延续传递风格](cps.md)、[去函数化](defunctionalization.md) +洞见:[从语义到机器](../insights/operational_semantics.md) +``` + +## 定义 {#definition} + +**操作语义**通过求值判断或**配置**之间的状态转换来描述程序行为。配置可能包含程序片段,以及环境、存储、延续或其他抽象机器状态。 + +这种描述具有数学性质:它陈述哪些求值或状态转换有效。解释器或虚拟机可以实现这些规则,但某个具体实现本身并非定义。 + +```admonish note title="语义定位" +操作语义是一种精确的语义,不只是非正式的实现细节。它通过求值规则或状态转换规则说明行为。[指称设计](../denotational-design/design.md)提出了一个互补且更早的设计问题:这些规则应保留哪些可组合含义与等式? +``` + +## 操作语义的形式 {#styles-of-operational-semantics} + +### 小步操作语义(结构操作语义) {#small-step-structural-operational-semantics} + +计算被拆分为原子转换: + +$$ \begin{aligned} 2 + 3 &\to 5 \\ (2 + 3) \cdot 4 &\to 5 \cdot 4 \to 20 \end{aligned} $$ + +适用于建模并发、交错执行与部分执行。 + +### 大步操作语义(自然语义) {#big-step-natural-semantics} + +根据最终结果描述求值: + +$$ (2 + 3) \cdot 4 \Downarrow 20 $$ + +推理终止程序时通常更清晰。 + +## 形式规则 {#formal-rules} + +操作语义通常采用**推理规则**给出。对于简单算术语言: + +$$ E ::= n \mid E + E $$ + +从左到右求值时,需要三条规则: + +$$ \frac{E_1 \to E_1'}{E_1 + E_2 \to E_1' + E_2} \qquad \frac{E_2 \to E_2'}{n + E_2 \to n + E_2'} \qquad n_1 + n_2 \to n_3 \quad \text{where } n_3 = n_1 + n_2 $$ + +前两条规则确定下一个可归约子表达式。两个操作数都成为值后,第三条规则执行加法。 + +求值轨迹: + +$$ (1 + 2) + 3 \to 3 + 3 \to 6 $$ + +## 为何重要 {#why-it-matters} + +* 提供**精确的类机器模型**来描述执行。 +* 为解释器与虚拟机奠定基础。 +* 支持对正确性、资源使用与安全性的推理。 + +## 与其他概念的关系 {#relation-to-other-concepts} + +* **自由单子**提供指令语法与顺序组合。操作规则可以描述该表示中的程序如何求值。 +* **CPS**将计算剩余部分显式表示为延续。操作规则可以描述值如何传递给这些延续。 +* **去函数化**会将已知函数族替换为一阶数据,并提供一个`apply`操作。操作规则可以描述由此产生的显式机器状态。 + +这些都是可以赋予操作语义的对象与变换,本身并不是操作语义。 + +## 实践中的应用 {#in-practice} + +操作规则可以指导解释器实现,并提供一个用于检查实现的精确模型: + +* **EVM**可以自然地建模为小步状态转换系统;也可以通过大步判断描述完整的终止执行。 +* 小步规则通常与 Rust 解释器中的`match`分支非常相似。 + +$$ n_1 + n_2 \to n_3 $$ + +上文完整的从左到右求值关系可以表示为 Rust 代码: + +```rust,noplayground +enum Expr { + Num(i64), + Add(Box, Box), +} + +fn step(expr: Expr) -> Option { + match expr { + Expr::Num(_) => None, + Expr::Add(left, right) => match (*left, *right) { + (Expr::Num(a), Expr::Num(b)) => Some(Expr::Num(a + b)), + (left @ Expr::Num(_), right) => step(right).map(|next| { + Expr::Add(Box::new(left), Box::new(next)) + }), + (left, right) => step(left).map(|next| { + Expr::Add(Box::new(next), Box::new(right)) + }), + }, + } +} +``` + +这个函数执行一次状态转换。重复应用即可得到所示轨迹;返回`None`表示表达式已经是一个值。 + +## 操作问题与指称问题 {#operational-and-denotational-questions} + +操作规则可以证明安全性、进展性质、资源上限以及与实现的对应关系。如果在预期的抽象含义明确之前就选定了操作机制,限制便会显现:实现选择可能意外变成语义承诺。 + +指称设计并不否定操作语义。它要求先陈述语义域、组合与定律,再将操作模型与其关联起来。 + +| 视角 | 问题 | +| --- | --- | +| 指称 | 整个程序意味着什么? | +| 操作 | 通过哪些状态转换求值? | +| 正确性 | 这些状态转换是否保留了预期含义? | + +以下片段用于说明,将操作描述视为唯一洞见来源的危险。 + +
操作描述并非全部含义(1/2)
+ +
操作描述并非全部含义(2/2)
diff --git a/src/concepts/referential_transparency.ar.md b/src/concepts/referential_transparency.ar.md new file mode 100644 index 0000000..67a8e33 --- /dev/null +++ b/src/concepts/referential_transparency.ar.md @@ -0,0 +1,80 @@ + + +# الشفافية المرجعية {#referential-transparency} + +```admonish tip title="ذات صلة" +الرؤية الدلالية: [الدلالات والتركيبية](../denotational-design/denotations.md)، [القوانين والتفسيرات](../denotational-design/laws-and-interpretations.md) +الرؤى: [إعادة طرح الشفافية المرجعية](../insights/referential-transparency.md) +``` + +```admonish note title="الموضع الدلالي" +تعتمد الشفافية المرجعية على الدلالة والمساواة المختارتين. وهي تتيح الاستبدال حين يحافظ إحلال تعبير على معناه المحدد، حتى إن اختلفت التنفيذات تشغيليًا خلف الحد الدلالي. +``` + +الشفافية المرجعية (RT) خاصية الاستبدال في التعبيرات: يمكن استبدال التعبير بدلالته دون تغيير معنى البرنامج. + +اليوم، تُستخدم الشفافية المرجعية عمليًا أساسًا للاستدلال المعادلي وإعادة الهيكلة الآمنة وتصميم الواجهات القائمة على القوانين. + +## المعنى الأساسي {#core-meaning} + +تقول الشفافية المرجعية: + +* إذا كانت `e` تدل على `v` +* فإن استخدام `v` بدلًا من `e` يحافظ على المعنى + +هذا ادعاء دلالي، لا شعار لأسلوب كتابة الشيفرة. + +### النقاء {#purity} + +تعيد الدالة النقية المخرجات نفسها للمدخلات نفسها، ولا تُحدث آثارًا جانبية قابلة للملاحظة. والشفافية المرجعية قانون الاستبدال للتعبيرات: يجب أن يحافظ استبدال تعبير بدلالته على المعنى. لذلك فالنقاء طريقة شائعة لتحقيق الشفافية المرجعية عمليًا، بينما يظل معيارها الدلالي أوسع. راجع [إعادة طرح الشفافية المرجعية](../insights/referential-transparency.md) للتمييز بين النقاء والشفافية المرجعية في التصميم الدلالي. + +## السياق التاريخي {#historical-context} + +ترتبط الشفافية المرجعية بقوة بصياغة كريستوفر ستراشي في دلالات لغات البرمجة. ويفصل تناوله الاستدلال على القيم عن السلوك كثيف التحديث: + +* **قيم R**: قيم التعبيرات. +* **قيم L**: مواضع قابلة للإسناد. + +الفكرة الأساسية أن الاستبدال على مستوى التعبير يظل مستقرًا عند الاستدلال على القيم. أما الإسناد فيُدخل تحديثات على المواضع، ما يجعل الاستدلال بالاستبدال أصعب أو غير صحيح بصيغته الساذجة. + +## معنى الإسناد والآثار الجانبية هنا {#what-assignment-and-side-effects-mean-here} + +في هذا السياق: + +* **الإسناد** هو تحديث موضع (مثل `x := x + 1`) +* **الأثر الجانبي** هو أي تغيير قابل للملاحظة يتجاوز إرجاع قيمة + +الإسناد نوع محدد من الآثار الجانبية. + +لهذا تفشل الشفافية المرجعية في كثير من السياقات الأمرية: فقد يعتمد التقييم على سياق قابل للملاحظة خارج واجهة القيمة الصريحة للتعبير أو يغيّره. + +## كيف تعرض اللغات الحديثة الشفافية المرجعية {#how-modern-languages-present-rt} + +### Haskell {#haskell} + +تُعلَّم الشفافية المرجعية بوصفها أساس الاستدلال على التعبيرات النقية. وتكون الآثار صريحة في البنى ذات الأنواع (`IO`، وتمرير الحالة، والتجريدات ذات الصلة)، لذلك تحتل قوانين الاستبدال موقعًا محوريًا في الاستخدام اليومي. + +### Scala (Cats / Cats Effect) {#scala-cats--cats-effect} + +في ممارسات البرمجة الوظيفية بـ Scala، يقدم Cats Effect أكثر صيغ الشفافية المرجعية شيوعًا: + +* `IO[A]` وصف نقي لعمل ذي آثار +* تركيب قيم `IO` شفاف مرجعيًا +* التنفيذ صريح عند حدود وقت التشغيل (`unsafeRun*`) + +ويقارن Cats Effect ذلك أيضًا بالتقييم الفوري `Future`، وهو أحد أسباب تركيز نقاشات الشفافية المرجعية في Scala على الكسل وتأجيل التنفيذ. + +## الشفافية المرجعية اليوم {#rt-today} + +في المنظومات الحديثة، تُستخدم الشفافية المرجعية اختصارًا للسلوك الآمن للاستبدال. وفي الأنظمة متعددة الأنماط، تطبق الفرق عادةً ادعاءاتها على وحدات أو واجهات أو مناطق محددة ذات آثار معنونة بالأنواع، بدلًا من تعميمها على كل الشيفرة. + +للاطلاع على تفسير الشفافية المرجعية وفق التصميم الدلالي، راجع [إعادة طرح الشفافية المرجعية](../insights/referential-transparency.md). + +## المراجع {#references} + +* ستراشي، C. *Fundamental Concepts in Programming Languages* (مذكرات محاضرات Oxford PRG، 1967). + [https://reed.cs.depaul.edu/jriely/447/assets/articles/strachey-fundamental-concepts-in-programming-languages.pdf](https://reed.cs.depaul.edu/jriely/447/assets/articles/strachey-fundamental-concepts-in-programming-languages.pdf) +* توثيق Cats Effect: نوع البيانات `IO` وملاحظات عن الشفافية المرجعية والتقييم الكسول. + [https://typelevel.org/cats-effect/docs/datatypes/io](https://typelevel.org/cats-effect/docs/datatypes/io) +* مدونة Typelevel: *موناد IO في Cats* (دافع المقارنة بين عدم النقاء في Scala والشفافية المرجعية). + [https://typelevel.org/blog/2017/05/02/io-monad-for-cats.html](https://typelevel.org/blog/2017/05/02/io-monad-for-cats.html) diff --git a/src/concepts/referential_transparency.de.md b/src/concepts/referential_transparency.de.md new file mode 100644 index 0000000..94e92a2 --- /dev/null +++ b/src/concepts/referential_transparency.de.md @@ -0,0 +1,80 @@ + + +# Referenzielle Transparenz {#referential-transparency} + +```admonish tip title="Verwandte Themen" +The Semantic View: [Denotationen und Kompositionalität](../denotational-design/denotations.md), [Gesetze und Interpretationen](../denotational-design/laws-and-interpretations.md) +Insights: [Referential transparency reloaded](../insights/referential-transparency.md) +``` + +```admonish note title="Semantische Einordnung" +Referenzielle Transparenz hängt von der gewählten Denotation und Gleichheit ab. Sie ermöglicht Substitution, wenn das Ersetzen eines Ausdrucks seine festgelegte Bedeutung bewahrt — auch wenn sich Implementierungen hinter der semantischen Grenze operational unterscheiden. +``` + +Referenzielle Transparenz (RT) ist die Substitutionseigenschaft von Ausdrücken: Ein Ausdruck kann durch seine Denotation ersetzt werden, ohne die Programmbedeutung zu verändern. + +Heute dient RT in der Praxis als Grundlage für Gleichungsrechnungen, sicheres Refactoring und gesetzesgeleiteten API-Entwurf. + +## Grundbedeutung {#core-meaning} + +RT besagt: + +* wenn `e` `v` bezeichnet +* dann bewahrt die Verwendung von `v` anstelle von `e` die Bedeutung + +Dies ist eine semantische Aussage und kein Schlagwort für Programmierstil. + +### Reinheit {#purity} + +Eine reine Funktion liefert für dieselben Eingaben dieselbe Ausgabe und hat keine beobachtbaren Seiteneffekte. RT ist das Substitutionsgesetz für Ausdrücke: Ein Ausdruck kann durch seine Denotation ersetzt werden, ohne die Bedeutung zu verändern. Reinheit ist daher ein verbreiteter Weg, RT in der Praxis zu erreichen; RT ist das umfassendere semantische Kriterium. Die Unterscheidung von Reinheit und RT im DD wird in [Referential transparency reloaded](../insights/referential-transparency.md) erläutert. + +## Historischer Kontext {#historical-context} + +In der Semantik von Programmiersprachen ist RT eng mit der Darstellung von Christopher Strachey verbunden. Seine Behandlung trennt das Schlussfolgern über Werte von Verhalten mit vielen Aktualisierungen: + +* **R-Werte**: Ausdruckswerte. +* **L-Werte**: zuweisbare Speicherorte. + +Entscheidend ist, dass die Substitution auf Ausdrucksebene stabil bleibt, solange über Werte geschlossen wird. Zuweisungen aktualisieren Speicherorte und erschweren das Substitutionsschließen oder machen es in seiner naiven Form ungültig. + +## Was Zuweisungen und Seiteneffekte hier bedeuten {#what-assignment-and-side-effects-mean-here} + +In diesem Kontext gilt: + +* **Zuweisung** bedeutet, einen Speicherort zu aktualisieren (z. B. `x := x + 1`). +* Ein **Seiteneffekt** ist jede beobachtbare Änderung über die Rückgabe eines Werts hinaus. + +Eine Zuweisung ist eine bestimmte Art von Seiteneffekt. + +Darum scheitert RT in vielen imperativen Umgebungen: Die Auswertung kann von einem beobachtbaren Kontext außerhalb der expliziten Wertschnittstelle des Ausdrucks abhängen oder ihn verändern. + +## Wie moderne Sprachen RT darstellen {#how-modern-languages-present-rt} + +### Haskell {#haskell} + +RT wird als Standardmethode zum Schlussfolgern über reine Ausdrücke gelehrt. Effekte sind in typisierten Konstruktionen ausdrücklich dargestellt (`IO`, Zustandsweitergabe und verwandte Abstraktionen), daher sind Substitutionsgesetze zentral für den täglichen Gebrauch. + +### Scala (Cats / Cats Effect) {#scala-cats--cats-effect} + +In der funktionalen Scala-Praxis bietet Cats Effect die verbreitetste Darstellung von RT: + +* `IO[A]` ist eine reine Beschreibung nebenwirkungsreicher Arbeit +* Die Komposition von `IO`\-Werten ist referenziell transparent +* Die Ausführung wird an Laufzeitgrenzen ausdrücklich ausgelöst (`unsafeRun*`). + +Cats Effect stellt dem außerdem die eager `Future`\-Auswertung gegenüber. Das ist ein Grund, warum RT-Diskussionen in Scala Verzögerung und faule Auswertung betonen. + +## RT heute {#rt-today} + +In modernen Ökosystemen dient RT als Kurzform für substitutionssicheres Verhalten. In Systemen mit mehreren Programmierparadigmen wenden Teams RT-Aussagen meist auf bestimmte Module, APIs oder Bereiche mit typisierten Effekten an, statt auf den gesamten Code. + +Die Interpretation von RT im Denotational Design wird in [Referential transparency reloaded](../insights/referential-transparency.md) erläutert. + +## Quellen {#references} + +* Strachey, C. *Fundamental Concepts in Programming Languages* (Oxford PRG-Vorlesungsnotizen, 1967). + [https://reed.cs.depaul.edu/jriely/447/assets/articles/strachey-fundamental-concepts-in-programming-languages.pdf](https://reed.cs.depaul.edu/jriely/447/assets/articles/strachey-fundamental-concepts-in-programming-languages.pdf) +* Cats-Effect-Dokumentation: `IO` Datentyp sowie Hinweise zu RT und verzögerter Auswertung. + [https://typelevel.org/cats-effect/docs/datatypes/io](https://typelevel.org/cats-effect/docs/datatypes/io) +* Typelevel-Blog: *An IO monad for cats* (Motivation zu Unreinheit in Scala und RT). + [https://typelevel.org/blog/2017/05/02/io-monad-for-cats.html](https://typelevel.org/blog/2017/05/02/io-monad-for-cats.html) diff --git a/src/concepts/referential_transparency.es.md b/src/concepts/referential_transparency.es.md new file mode 100644 index 0000000..03820c7 --- /dev/null +++ b/src/concepts/referential_transparency.es.md @@ -0,0 +1,80 @@ + + +# Transparencia referencial {#referential-transparency} + +```admonish tip title="Relacionado" +La perspectiva semántica: [Denotaciones y composicionalidad](../denotational-design/denotations.md), [Leyes e interpretaciones](../denotational-design/laws-and-interpretations.md) +Perspectivas: [Transparencia referencial, reexaminada](../insights/referential-transparency.md) +``` + +```admonish note title="Ubicación semántica" +La transparencia referencial depende de la denotación y la igualdad elegidas. Permite la sustitución cuando reemplazar una expresión preserva el significado especificado, aunque las implementaciones difieran operacionalmente detrás del límite semántico. +``` + +La transparencia referencial (RT) es la propiedad de sustitución de las expresiones: se puede reemplazar una expresión por su denotación sin alterar el significado del programa. + +Hoy en día, la RT se usa en la práctica como fundamento del razonamiento ecuacional, la refactorización segura y el diseño de API basado en leyes. + +## Significado central {#core-meaning} + +La RT afirma: + +* si `e` denota `v` +* entonces usar `v` en lugar de `e` preserva el significado + +Es una afirmación semántica, no un eslogan de estilo de programación. + +### Pureza {#purity} + +Una función pura devuelve el mismo resultado con las mismas entradas y no tiene efectos secundarios observables. La RT es la ley de sustitución para expresiones: reemplazar una expresión por su denotación debe preservar el significado. Por tanto, la pureza es una forma habitual de lograr la RT en la práctica, mientras que la RT es un criterio semántico más amplio. Consulta [Transparencia referencial, reexaminada](../insights/referential-transparency.md) para conocer la distinción del diseño denotacional entre pureza y RT. + +## Contexto histórico {#historical-context} + +En la semántica de los lenguajes de programación, la RT se asocia estrechamente con el planteamiento de Christopher Strachey. Su tratamiento separa el razonamiento sobre valores del comportamiento con abundantes actualizaciones: + +* **Valores R**: valores de expresiones. +* **Valores L**: ubicaciones a las que se puede asignar un valor. + +La idea clave es que la sustitución en el nivel de las expresiones es estable si razonamos sobre valores. La asignación introduce actualizaciones de ubicaciones y dificulta el razonamiento por sustitución, o lo invalida en su forma ingenua. + +## Qué significan aquí la asignación y los efectos secundarios {#what-assignment-and-side-effects-mean-here} + +En este contexto: + +* **asignación** significa actualizar una ubicación (por ejemplo, `x := x + 1`) +* **efecto secundario** es cualquier cambio observable además de devolver un valor + +La asignación es un tipo específico de efecto secundario. + +Por eso falla la RT en muchos contextos imperativos: la evaluación puede depender del contexto observable externo a la interfaz de valores explícitos de la expresión o modificarlo. + +## Cómo presentan la RT los lenguajes modernos {#how-modern-languages-present-rt} + +### Haskell {#haskell} + +La RT se enseña como el modo predeterminado de razonar sobre expresiones puras. Los efectos son explícitos en construcciones tipadas (`IO`, paso de estado y abstracciones relacionadas), por lo que las leyes de sustitución son fundamentales en el uso diario. + +### Scala (Cats / Cats Effect) {#scala-cats--cats-effect} + +En la práctica de la programación funcional en Scala, Cats Effect proporciona el enfoque de RT más habitual: + +* `IO[A]` es una descripción pura de un trabajo con efectos +* la composición de valores `IO` tiene transparencia referencial +* la ejecución es explícita en los límites del entorno de ejecución (`unsafeRun*`) + +Cats Effect también contrasta esto con la evaluación `Future` ansiosa, una de las razones por las que los debates sobre RT en Scala hacen hincapié en la evaluación perezosa y la ejecución diferida. + +## La RT hoy {#rt-today} + +En los ecosistemas modernos, RT se usa como abreviatura de comportamiento seguro para la sustitución. En los sistemas que combinan paradigmas, los equipos suelen aplicar las afirmaciones de RT a módulos, API o regiones con efectos tipados concretos, en lugar de aplicarlas globalmente a todo el código. + +Para consultar la interpretación de RT en el diseño denotacional, véase [Transparencia referencial, reexaminada](../insights/referential-transparency.md). + +## Referencias {#references} + +* Strachey, C. *Fundamental Concepts in Programming Languages* (apuntes de clase del PRG de Oxford, 1967). + [https://reed.cs.depaul.edu/jriely/447/assets/articles/strachey-fundamental-concepts-in-programming-languages.pdf](https://reed.cs.depaul.edu/jriely/447/assets/articles/strachey-fundamental-concepts-in-programming-languages.pdf) +* Documentación de Cats Effect: tipo de datos `IO` y notas sobre RT/evaluación perezosa. + [https://typelevel.org/cats-effect/docs/datatypes/io](https://typelevel.org/cats-effect/docs/datatypes/io) +* Blog de Typelevel: *An IO monad for cats* (motivación sobre impureza en Scala frente a RT). + [https://typelevel.org/blog/2017/05/02/io-monad-for-cats.html](https://typelevel.org/blog/2017/05/02/io-monad-for-cats.html) diff --git a/src/concepts/referential_transparency.ja.md b/src/concepts/referential_transparency.ja.md new file mode 100644 index 0000000..c3de605 --- /dev/null +++ b/src/concepts/referential_transparency.ja.md @@ -0,0 +1,80 @@ + + +# 参照透過性 {#referential-transparency} + +```admonish tip title="関連項目" +意味論的な見方:[表示と合成性](../denotational-design/denotations.md)、[法則と解釈](../denotational-design/laws-and-interpretations.md) +洞察:[参照透過性再考](../insights/referential-transparency.md) +``` + +```admonish note title="意味論上の位置付け" +参照透過性は、選択した表示と等値性に依存します。式を置き換えても、意味論上の境界の内側で実装上の振る舞いが異なることはありますが、仕様で定めた意味が保たれるなら置換を認めます。 +``` + +参照透過性(RT)とは、式の置換に関する性質です。式をその表示に置き換えても、プログラムの意味は変わりません。 + +今日の実践では、RTは等式による推論、安全なリファクタリング、法則に基づくAPI設計の基礎として使われています。 + +## 中核となる意味 {#core-meaning} + +RTは次のように述べます。 + +* `e`が`v`を表すなら、 +* `v`を`e`の代わりに使っても意味は保たれる。 + +これは意味論上の主張であり、コーディングスタイルの標語ではありません。 + +### 純粋性 {#purity} + +純粋関数は、同じ入力に対して同じ出力を返し、観測可能な副作用を持ちません。RTは式に関する置換法則です。式をその表示に置き換えても意味が保たれなければなりません。そのため純粋性は、実践上RTを得る一般的な方法の一つであり、RTはより広い意味論上の基準です。DDにおける純粋性とRTの区別については、[参照透過性再考](../insights/referential-transparency.md)を参照してください。 + +## 歴史的背景 {#historical-context} + +プログラミング言語の意味論では、RTはChristopher Stracheyの定式化と強く結び付いています。彼の考察では、値についての推論と更新を伴う振る舞いを分けています。 + +* **R値**:式の値。 +* **L値**:代入できる場所。 + +要点は、値についての推論を保てば、式レベルの置換は安定しているということです。代入によって場所の更新が導入され、単純な置換による推論が難しくなったり、無効になったりします。 + +## ここでの代入と副作用の意味 {#what-assignment-and-side-effects-mean-here} + +この文脈では: + +* **代入**とは場所を更新することです(例:`x := x + 1`)。 +* **副作用**とは、値を返すこと以外にある観測可能な変化です。 + +代入は特定の種類の副作用です。 + +これが多くの命令型環境でRTが成り立たない理由です。評価は、式の明示的な値のインターフェース外にある観測可能なコンテキストに依存したり、それを変更したりすることがあります。 + +## 現代の言語でRTをどう扱うか {#how-modern-languages-present-rt} + +### Haskell {#haskell} + +RTは純粋な式についての標準的な推論方法として教えられています。副作用は型付き構成(`IO`、状態の受け渡し、関連する抽象化など)で明示するため、日常的な利用で置換法則が中心的な役割を果たします。 + +### Scala(Cats/Cats Effect) {#scala-cats--cats-effect} + +Scalaの関数型プログラミングでは、Cats Effectが一般的なRTの説明を提供します。 + +* `IO[A]`は、副作用のある処理を純粋に記述する +* `IO`値の合成にはRTが成り立つ +* ランタイム境界(`unsafeRun*`)で実行を明示する + +Cats Effectは即時の`Future`評価とも対比されます。そのため、ScalaでのRTの議論では遅延性と実行の先送りが強調されます。 + +## 今日のRT {#rt-today} + +現代のエコシステム全体で、RTは置換しても安全な振る舞いを指す略称として使われています。 複数のパラダイムを組み合わせるシステムでは、コード全体に一律に適用せず、特定のモジュール、API、副作用を型で扱う領域にRTの主張を適用するのが一般的です。 + +RTをDenotational Designの観点から解釈する場合は、[参照透過性再考](../insights/referential-transparency.md)を参照してください。 + +## 参考文献 {#references} + +* Strachey, C. *Fundamental Concepts in Programming Languages*(Oxford PRG講義ノート、1967)。 + [https://reed.cs.depaul.edu/jriely/447/assets/articles/strachey-fundamental-concepts-in-programming-languages.pdf](https://reed.cs.depaul.edu/jriely/447/assets/articles/strachey-fundamental-concepts-in-programming-languages.pdf) +* Cats Effectドキュメント:`IO`データ型とRT/遅延評価について。 + [https://typelevel.org/cats-effect/docs/datatypes/io](https://typelevel.org/cats-effect/docs/datatypes/io) +* Typelevelブログ:*An IO monad for cats*(Scalaの不純性とRTをめぐる動機)。 + [https://typelevel.org/blog/2017/05/02/io-monad-for-cats.html](https://typelevel.org/blog/2017/05/02/io-monad-for-cats.html) diff --git a/src/concepts/referential_transparency.ko.md b/src/concepts/referential_transparency.ko.md new file mode 100644 index 0000000..aeff5e6 --- /dev/null +++ b/src/concepts/referential_transparency.ko.md @@ -0,0 +1,80 @@ + + +# 참조 투명성 {#referential-transparency} + +```admonish tip title="관련 항목" +의미론적 관점: [표시와 합성성](../denotational-design/denotations.md), [법칙과 해석](../denotational-design/laws-and-interpretations.md) +통찰: [참조 투명성 다시 보기](../insights/referential-transparency.md) +``` + +```admonish note title="의미론적 위치" +참조 투명성은 선택한 표시와 동등성에 따라 달라집니다. 식을 해당 표시로 바꿔도 명세된 의미가 보존된다면 치환할 수 있으며, 의미론적 경계 뒤에서 구현이 작동하는 방식은 달라도 됩니다. +``` + +참조 투명성(RT)은 표현식의 치환 속성입니다. 프로그램의 의미를 바꾸지 않고 표현식을 그 표시에 해당하는 값으로 대체할 수 있습니다. + +오늘날 RT는 등식 추론, 안전한 리팩터링, 법칙 중심 API 설계의 토대로 실무에서 사용됩니다. + +## 핵심 의미 {#core-meaning} + +RT는 다음을 말합니다: + +* `e`가 `v`을 나타낸다면 +* `e` 대신 `v`를 사용해도 의미가 보존됩니다 + +이는 코딩 스타일의 구호가 아니라 의미론적 주장입니다. + +### 순수성 {#purity} + +순수 함수는 같은 입력에 항상 같은 출력을 반환하고 관찰 가능한 부작용이 없습니다. RT는 표현식의 치환 법칙으로, 표현식을 그 표시에 해당하는 값으로 바꿔도 의미가 보존되어야 합니다. 따라서 순수성은 실무에서 RT를 얻는 흔한 방법이고, RT는 더 넓은 의미론적 기준입니다. 표시적 설계에서 순수성과 RT를 구분하는 내용은 [참조 투명성 다시 보기](../insights/referential-transparency.md)를 참고하세요. + +## 역사적 맥락 {#historical-context} + +프로그래밍 언어 의미론에서 RT는 Christopher Strachey의 설명과 깊은 관련이 있습니다. 그의 논의는 값에 대한 추론과 갱신이 많은 동작을 구분합니다: + +* **R값**: 표현식의 값. +* **L값**: 대입할 수 있는 위치. + +핵심은 값에 대한 추론을 유지할 때 표현식 수준 치환이 안정적이라는 점입니다. 대입은 위치를 갱신하므로 치환 추론을 어렵게 하거나 단순한 형태에서는 무효로 만듭니다. + +## 이 문맥에서 대입과 부작용의 의미 {#what-assignment-and-side-effects-mean-here} + +이 문맥에서는 다음과 같습니다: + +* **대입**은 위치를 갱신합니다 (예: `x := x + 1`) +* **부작용**은 값을 반환하는 것 외의 관찰 가능한 모든 변화입니다 + +대입은 특정 종류의 부작용입니다. + +이 때문에 여러 명령형 환경에서 RT가 성립하지 않습니다. 평가가 표현식의 명시적 값 인터페이스 밖에 있는 관찰 가능한 컨텍스트에 의존하거나 이를 변경할 수 있습니다. + +## 현대 언어에서 RT를 다루는 방식 {#how-modern-languages-present-rt} + +### Haskell {#haskell} + +RT는 순수 표현식의 기본 추론 방식으로 가르칩니다. 효과는 타입이 지정된 구성(`IO`, 상태 전달 및 관련 추상화)에 명시되므로 치환 법칙이 일상적인 사용의 핵심입니다. + +### Scala (Cats/Cats Effect) {#scala-cats--cats-effect} + +Scala 함수형 프로그래밍에서 Cats Effect는 가장 흔히 RT를 다음과 같이 설명합니다: + +* `IO[A]`는 효과가 있는 작업을 순수하게 기술합니다 +* `IO` 값의 합성은 참조 투명합니다 +* 실행은 런타임 경계(`unsafeRun*`)에서 명시적으로 이루어집니다 + +Cats Effect는 이를 즉시 `Future` 평가와 대조합니다. 그래서 Scala의 RT 논의는 지연성과 실행 연기를 강조하기도 합니다. + +## 오늘날의 RT {#rt-today} + +현대의 여러 생태계에서 RT는 치환이 안전한 동작을 줄여 부르는 말로 사용됩니다. 여러 패러다임이 섞인 시스템에서는 보통 전체 코드에 일괄 적용하기보다 특정 모듈, API, 효과 타입 영역에 RT 주장을 적용합니다. + +RT의 표시적 설계 관점은 [참조 투명성 다시 보기](../insights/referential-transparency.md)를 참고하세요. + +## 참고 문헌 {#references} + +* Strachey, C. *프로그래밍 언어의 기본 개념* (Oxford PRG 강의 노트, 1967). + [https://reed.cs.depaul.edu/jriely/447/assets/articles/strachey-fundamental-concepts-in-programming-languages.pdf](https://reed.cs.depaul.edu/jriely/447/assets/articles/strachey-fundamental-concepts-in-programming-languages.pdf) +* Cats Effect 문서: `IO` 데이터 타입과 RT/지연 평가 설명. + [https://typelevel.org/cats-effect/docs/datatypes/io](https://typelevel.org/cats-effect/docs/datatypes/io) +* Typelevel 블로그: *Cats용 IO 모나드* (Scala의 부수성 대 RT 동기). + [https://typelevel.org/blog/2017/05/02/io-monad-for-cats.html](https://typelevel.org/blog/2017/05/02/io-monad-for-cats.html) diff --git a/src/concepts/referential_transparency.ru.md b/src/concepts/referential_transparency.ru.md new file mode 100644 index 0000000..9c06c56 --- /dev/null +++ b/src/concepts/referential_transparency.ru.md @@ -0,0 +1,80 @@ + + +# Референциальная прозрачность {#referential-transparency} + +```admonish tip title="Связанные материалы" +«Семантический взгляд»: [Денотации и композиционность](../denotational-design/denotations.md), [Законы и интерпретации](../denotational-design/laws-and-interpretations.md) +«Идеи»: [Референциальная прозрачность: новый взгляд](../insights/referential-transparency.md) +``` + +```admonish note title="Семантическое место" +Референциальная прозрачность зависит от выбранной денотации и отношения равенства. Она допускает подстановку, когда замена выражения сохраняет заданный смысл, даже если реализации операционно различаются за семантической границей. +``` + +Референциальная прозрачность (RT) — свойство подстановки для выражений: выражение можно заменить его денотацией, не меняя смысл программы. + +Сегодня RT на практике служит основой для рассуждений через равенства, безопасного рефакторинга и проектирования API, опирающегося на законы. + +## Основной смысл {#core-meaning} + +RT утверждает: + +* если `e` обозначает `v` +* то использование `v` вместо `e` сохраняет смысл + +Это семантическое утверждение, а не лозунг о стиле написания кода. + +### Чистота {#purity} + +Чистая функция возвращает одинаковый результат при одинаковых входных данных и не имеет наблюдаемых побочных эффектов. RT — закон подстановки для выражений: замена выражения его денотацией должна сохранять смысл. Поэтому чистота — распространённый практический способ добиться RT, тогда как RT является более широким семантическим критерием. Различие между чистотой и RT в контексте денотационного проектирования см. в разделе [«Референциальная прозрачность: новый взгляд»](../insights/referential-transparency.md). + +## Исторический контекст {#historical-context} + +В семантике языков программирования RT тесно связана с трактовкой Кристофера Стрейчи. Его подход отделяет рассуждения о значениях от поведения, насыщенного обновлениями: + +* **R-значения**: значения выражений. +* **L-значения**: изменяемые присваиванием области памяти. + +Главная мысль в том, что подстановка на уровне выражений стабильна, пока мы рассуждаем о значениях. Присваивание обновляет области памяти и усложняет подстановочные рассуждения либо делает их неверными в наивной форме. + +## Что здесь означают присваивание и побочные эффекты {#what-assignment-and-side-effects-mean-here} + +В этом контексте: + +* **присваивание** — обновление области памяти (например, `x := x + 1`) +* **побочный эффект** — любое наблюдаемое изменение помимо возврата значения + +Присваивание — частный вид побочного эффекта. + +Поэтому во многих императивных системах RT не выполняется: вычисление может зависеть от наблюдаемого контекста вне явного интерфейса значений выражения или изменять его. + +## Как современные языки трактуют RT {#how-modern-languages-present-rt} + +### Haskell {#haskell} + +RT преподаётся как способ рассуждения по умолчанию для чистых выражений. Эффекты явно представлены типизированными конструкциями (`IO`, передачей состояния и другими абстракциями), поэтому законы подстановки постоянно используются на практике. + +### Scala (Cats / Cats Effect) {#scala-cats--cats-effect} + +В функциональном программировании на Scala наиболее распространённое изложение RT даёт Cats Effect: + +* `IO[A]` — чистое описание работы с эффектами +* композиция значений `IO` удовлетворяет RT +* выполнение явно происходит на границах среды выполнения (`unsafeRun*`) + +Cats Effect также противопоставляет это немедленному вычислению `Future`. Поэтому обсуждения RT в Scala часто подчёркивают ленивость и отложенное выполнение. + +## RT сегодня {#rt-today} + +В современных экосистемах RT часто используют как сокращённое обозначение поведения, допускающего безопасную подстановку. В системах со смешанными парадигмами обычно относят утверждения о RT к конкретным модулям, API или областям с типизированными эффектами, а не ко всему коду. + +Трактовка RT в денотационном проектировании рассматривается в разделе [«Референциальная прозрачность: новый взгляд»](../insights/referential-transparency.md). + +## Источники {#references} + +* Стрейчи, К. *Fundamental Concepts in Programming Languages* (конспект лекций Oxford PRG, 1967). + [https://reed.cs.depaul.edu/jriely/447/assets/articles/strachey-fundamental-concepts-in-programming-languages.pdf](https://reed.cs.depaul.edu/jriely/447/assets/articles/strachey-fundamental-concepts-in-programming-languages.pdf) +* Документация Cats Effect: тип данных `IO` и заметки об RT и ленивом вычислении. + [https://typelevel.org/cats-effect/docs/datatypes/io](https://typelevel.org/cats-effect/docs/datatypes/io) +* Блог Typelevel: *An IO monad for cats* (о мотивации, связанной с императивностью Scala и RT). + [https://typelevel.org/blog/2017/05/02/io-monad-for-cats.html](https://typelevel.org/blog/2017/05/02/io-monad-for-cats.html) diff --git a/src/concepts/referential_transparency.uk.md b/src/concepts/referential_transparency.uk.md new file mode 100644 index 0000000..e80bc48 --- /dev/null +++ b/src/concepts/referential_transparency.uk.md @@ -0,0 +1,80 @@ + + +# Референційна прозорість {#referential-transparency} + +```admonish tip title="Пов’язані матеріали" +Семантичний погляд: [Денотації та композиційність](../denotational-design/denotations.md), [Закони та інтерпретації](../denotational-design/laws-and-interpretations.md) +Інсайти: [Референційна прозорість: новий погляд](../insights/referential-transparency.md) +``` + +```admonish note title="Семантичне місце" +Референційна прозорість залежить від вибраної денотації та рівності. Вона дозволяє підстановку, якщо заміна виразу зберігає визначене значення, навіть коли реалізації за семантичною межею операційно відрізняються. +``` + +Референційна прозорість (RT) — це властивість підстановки виразів: вираз можна замінити його денотацією, не змінюючи значення програми. + +Сьогодні RT використовують як основу для рівняннєвого міркування, безпечного рефакторингу та проєктування API, керованого законами. + +## Основне значення {#core-meaning} + +RT стверджує: + +* якщо `e` позначає `v` +* то використання `v` замість `e` зберігає значення + +Це семантичне твердження, а не гасло про стиль коду. + +### Чистота {#purity} + +Чиста функція повертає той самий результат за тих самих вхідних даних і не має спостережуваних побічних ефектів. RT — це закон підстановки для виразів: заміна виразу його денотацією має зберігати значення. Тож чистота — поширений практичний спосіб досягти RT, а RT — ширший семантичний критерій. Відмінність між чистотою та RT у денотаційному проєктуванні див. у розділі [Референційна прозорість: новий погляд](../insights/referential-transparency.md). + +## Історичний контекст {#historical-context} + +У семантиці мов програмування RT тісно пов’язана з формулюванням Крістофера Страчи. У його підході міркування про значення відокремлено від поведінки з численними оновленнями: + +* **R-значення**: значення виразів. +* **L-значення**: місця, яким можна присвоювати значення. + +Головна думка: підстановка на рівні виразів стабільна, поки ми міркуємо про значення. Присвоєння оновлює місця й ускладнює міркування за допомогою підстановки або робить його некоректним у наївному вигляді. + +## Що тут означають присвоєння й побічні ефекти {#what-assignment-and-side-effects-mean-here} + +У цьому контексті: + +* **присвоєння** — це оновлення місця (наприклад, `x := x + 1`) +* **побічний ефект** — будь-яка спостережувана зміна, крім повернення значення + +Присвоєння — це окремий різновид побічного ефекту. + +Саме тому RT порушується в багатьох імперативних системах: обчислення може залежати від спостережуваного контексту поза явним інтерфейсом значень виразу або змінювати його. + +## Як сучасні мови подають RT {#how-modern-languages-present-rt} + +### Haskell {#haskell} + +RT викладають як стандартний спосіб міркування про чисті вирази. Ефекти є явними в типізованих конструкціях (`IO`, передавання стану та споріднені абстракції), тому закони підстановки важливі в повсякденному використанні. + +### Scala (Cats / Cats Effect) {#scala-cats--cats-effect} + +У практиці функційного програмування на Scala найпоширеніше формулювання RT дає Cats Effect: + +* `IO[A]` — це чистий опис роботи з ефектами +* композиція значень `IO` є референційно прозорою +* виконання є явним на межах середовища виконання (`unsafeRun*`) + +Cats Effect також протиставляє це нетерплячому обчисленню `Future`; тому в обговореннях RT у Scala наголошують на лінивості й відкладеному виконанні. + +## RT сьогодні {#rt-today} + +У сучасних екосистемах RT є скороченням для поведінки, безпечної для підстановки. У змішаних парадигмах команди зазвичай застосовують твердження RT до конкретних модулів, API чи ділянок із типізованими ефектами, а не до всього коду загалом. + +Денотаційне тлумачення RT див. у розділі [Референційна прозорість: новий погляд](../insights/referential-transparency.md). + +## Джерела {#references} + +* Страчи, К. *Fundamental Concepts in Programming Languages* (лекційні нотатки Oxford PRG, 1967). + [https://reed.cs.depaul.edu/jriely/447/assets/articles/strachey-fundamental-concepts-in-programming-languages.pdf](https://reed.cs.depaul.edu/jriely/447/assets/articles/strachey-fundamental-concepts-in-programming-languages.pdf) +* Документація Cats Effect: нотатки про тип даних `IO`, RT і ліниве обчислення. + [https://typelevel.org/cats-effect/docs/datatypes/io](https://typelevel.org/cats-effect/docs/datatypes/io) +* Блоґ Typelevel: *An IO monad for cats* (чому в Scala обговорюють неістотність побічних ефектів та RT). + [https://typelevel.org/blog/2017/05/02/io-monad-for-cats.html](https://typelevel.org/blog/2017/05/02/io-monad-for-cats.html) diff --git a/src/concepts/referential_transparency.vi.md b/src/concepts/referential_transparency.vi.md new file mode 100644 index 0000000..55e4a43 --- /dev/null +++ b/src/concepts/referential_transparency.vi.md @@ -0,0 +1,80 @@ + + +# Tính minh bạch tham chiếu {#referential-transparency} + +```admonish tip title="Liên quan" +Góc nhìn ngữ nghĩa: [Ngữ nghĩa và tính hợp thành](../denotational-design/denotations.md), [Định luật và cách diễn giải](../denotational-design/laws-and-interpretations.md) +Nhận định: [Tính minh bạch tham chiếu trở lại](../insights/referential-transparency.md) +``` + +```admonish note title="Vị trí ngữ nghĩa" +Tính minh bạch tham chiếu phụ thuộc vào ngữ nghĩa chỉ định và đẳng thức đã chọn. Nó cho phép phép thế khi thay biểu thức bằng ngữ nghĩa chỉ định của nó vẫn bảo toàn ý nghĩa được đặc tả, ngay cả khi cách triển khai khác nhau về vận hành phía sau ranh giới ngữ nghĩa. +``` + +Tính minh bạch tham chiếu (RT) là thuộc tính thế của biểu thức: có thể thay biểu thức bằng ngữ nghĩa chỉ định của nó mà không làm đổi ý nghĩa chương trình. + +Ngày nay, RT được dùng trong thực tế làm nền tảng cho lập luận phương trình, tái cấu trúc an toàn và thiết kế API dựa trên định luật. + +## Ý nghĩa cốt lõi {#core-meaning} + +RT phát biểu: + +* nếu `e` biểu thị `v` +* thì dùng `v` thay cho `e` sẽ bảo toàn ý nghĩa + +Đây là khẳng định ngữ nghĩa, không phải khẩu hiệu về phong cách viết mã. + +### Tính thuần {#purity} + +Hàm thuần trả về cùng đầu ra với cùng đầu vào và không có hiệu ứng phụ quan sát được. RT là định luật thế cho biểu thức: thay biểu thức bằng ngữ nghĩa chỉ định phải bảo toàn ý nghĩa. Vì vậy, tính thuần là một cách phổ biến để có RT trong thực tế, còn RT là tiêu chí ngữ nghĩa rộng hơn. Xem [Tính minh bạch tham chiếu trở lại](../insights/referential-transparency.md) để biết phân biệt giữa tính thuần và RT theo DD. + +## Bối cảnh lịch sử {#historical-context} + +Trong ngữ nghĩa ngôn ngữ lập trình, RT gắn chặt với cách đặt vấn đề của Christopher Strachey. Cách ông trình bày phân biệt lập luận về giá trị với hành vi nặng về cập nhật: + +* **Giá trị R**: giá trị biểu thức. +* **Giá trị L**: các vị trí có thể được gán. + +Điểm then chốt là phép thế ở cấp biểu thức ổn định khi ta chỉ lập luận về giá trị. Phép gán đưa vào cập nhật vị trí, khiến lập luận bằng phép thế khó hơn hoặc không còn hợp lệ theo dạng ngây thơ. + +## Ý nghĩa của phép gán và hiệu ứng phụ ở đây {#what-assignment-and-side-effects-mean-here} + +Trong ngữ cảnh này: + +* **phép gán** là cập nhật một vị trí (ví dụ `x := x + 1`) +* **hiệu ứng phụ** là mọi thay đổi quan sát được ngoài việc trả về giá trị + +Phép gán là một dạng hiệu ứng phụ cụ thể. + +Vì vậy RT thất bại trong nhiều bối cảnh mệnh lệnh: việc đánh giá có thể phụ thuộc hoặc làm thay đổi ngữ cảnh quan sát được bên ngoài giao diện giá trị tường minh của biểu thức. + +## RT được trình bày ra sao trong ngôn ngữ hiện đại {#how-modern-languages-present-rt} + +### Haskell {#haskell} + +RT được dạy như cách lập luận mặc định cho biểu thức thuần. Hiệu ứng được biểu đạt tường minh bằng cấu trúc có kiểu (`IO`, truyền trạng thái và các phép trừu tượng liên quan), vì vậy định luật thế là trọng tâm trong sử dụng hằng ngày. + +### Scala (Cats / Cats Effect) {#scala-cats--cats-effect} + +Trong thực hành FP với Scala, Cats Effect đưa ra cách trình bày RT phổ biến nhất: + +* `IO[A]` là mô tả thuần túy của công việc có hiệu ứng +* phép hợp thành các giá trị `IO` có tính RT +* thực thi được tường minh hóa tại ranh giới môi trường chạy (`unsafeRun*`) + +Cats Effect cũng đối chiếu điều này với việc đánh giá `Future` háo hức, một lý do khiến thảo luận RT trong Scala nhấn mạnh tính lười và thực thi trì hoãn. + +## RT ngày nay {#rt-today} + +Trong các hệ sinh thái hiện đại, RT thường được dùng làm cách gọi tắt cho hành vi an toàn với phép thế. Trong hệ thống kết hợp nhiều mô hình, các nhóm thường áp dụng khẳng định RT cho những mô-đun, API hoặc vùng có kiểu hiệu ứng cụ thể, thay vì áp dụng toàn cục cho mọi mã. + +Để biết cách diễn giải RT theo Thiết kế theo ngữ nghĩa, xem [Tính minh bạch tham chiếu trở lại](../insights/referential-transparency.md). + +## Tài liệu tham khảo {#references} + +* Strachey, C. *Fundamental Concepts in Programming Languages* (ghi chú bài giảng Oxford PRG, 1967). + [https://reed.cs.depaul.edu/jriely/447/assets/articles/strachey-fundamental-concepts-in-programming-languages.pdf](https://reed.cs.depaul.edu/jriely/447/assets/articles/strachey-fundamental-concepts-in-programming-languages.pdf) +* Tài liệu Cats Effect: `IO` kiểu dữ liệu và ghi chú về RT/đánh giá lười. + [https://typelevel.org/cats-effect/docs/datatypes/io](https://typelevel.org/cats-effect/docs/datatypes/io) +* Blog Typelevel: *An IO monad for cats* (động cơ về tính không thuần và RT trong Scala). + [https://typelevel.org/blog/2017/05/02/io-monad-for-cats.html](https://typelevel.org/blog/2017/05/02/io-monad-for-cats.html) diff --git a/src/concepts/referential_transparency.zh-hant.md b/src/concepts/referential_transparency.zh-hant.md new file mode 100644 index 0000000..cde83f6 --- /dev/null +++ b/src/concepts/referential_transparency.zh-hant.md @@ -0,0 +1,80 @@ + + +# 引用透明性 {#referential-transparency} + +```admonish tip title="相關內容" +語義視角:[指稱與組合性](../denotational-design/denotations.md)、[定律與解釋](../denotational-design/laws-and-interpretations.md) +洞見:[重新審視引用透明性](../insights/referential-transparency.md) +``` + +```admonish note title="語義定位" +引用透明性取決於所選指稱與等價關係。當替換表示式不會改變指定含義時,它允許進行替換,即使語義邊界背後的實作操作有所不同。 +``` + +引用透明性(RT)是表示式的替換性質:可以用一個表示式的指稱替換該表示式,而不改變程式含義。 + +如今,實踐中通常將 RT 作為等式推理、安全重構與定律驅動 API 設計的基礎。 + +## 核心含義 {#core-meaning} + +RT 表示: + +* 如果`e`指稱`v` +* 那麼,以`v`代替`e`會保留含義 + +這是語義主張,而非編碼風格口號。 + +### 純性 {#purity} + +純函式對相同輸入總是返回相同輸出,並且沒有可觀察的副作用。RT 是表示式的替換定律:用其指稱替換表示式必須保留含義。因此,純函式是實踐中實現 RT 的一種常見方式,而 RT 是更廣泛的語義標準。關於指稱設計中純性與 RT 的區別,請參閱[《重新審視引用透明性》](../insights/referential-transparency.md)。 + +## 歷史背景 {#historical-context} + +在程式語言語義中,RT 與 Christopher Strachey 的表述密切相關。他的論述將值推理與以更新為主的行為區分開來: + +* **R 值**:表示式的值。 +* **L 值**:可以賦值的位置。 + +關鍵在於:當我們進行值層面的推理時,表示式級別的替換是穩定的。賦值會引入位置更新,使替換推理變得困難,甚至不再以樸素形式成立。 + +## 這裡的賦值與副作用意味著什麼 {#what-assignment-and-side-effects-mean-here} + +在此上下文中: + +* **賦值**是對某個位置進行更新(例如`x := x + 1`) +* **副作用**是返回值之外任何可觀察的變化 + +賦值是一種特定的副作用。 + +這就是 RT 在許多命令式環境中失效的原因:求值可能依賴或改變表示式顯式值介面以外的可觀察上下文。 + +## 現代語言如何呈現 RT {#how-modern-languages-present-rt} + +### Haskell {#haskell} + +純表示式通常被當作預設推理物件來教授 RT。效應透過型別化構造顯式表達(例如`IO`、狀態傳遞及相關抽象),所以替換定律在日常使用中居於核心地位。 + +### Scala(Cats / Cats Effect) {#scala-cats--cats-effect} + +在 Scala 函數語言程式設計實踐中,Cats Effect 提供了最常見的 RT 解釋方式: + +* `IO[A]`是對帶效應工作的純描述 +* 組合`IO`值滿足 RT +* 在執行時邊界顯式執行(`unsafeRun*`) + +Cats Effect 也將其與急切求值`Future`作對比,這也是 Scala 中討論 RT 時強調惰性與延遲執行的原因之一。 + +## 當代的 RT {#rt-today} + +在現代生態系統中,RT 常被用作“行為可安全替換”的簡稱。 在多正規化系統中,團隊通常會將 RT 主張應用於特定模組、API 或帶效應型別的區域,而不是全域性套用於所有程式碼。 + +關於 RT 在指稱設計中的解讀,請參閱[《重新審視引用透明性》](../insights/referential-transparency.md)。 + +## 參考文獻 {#references} + +* Strachey, C. *《程式語言的基本概念》*(牛津 PRG 講義,1967)。 + [https://reed.cs.depaul.edu/jriely/447/assets/articles/strachey-fundamental-concepts-in-programming-languages.pdf](https://reed.cs.depaul.edu/jriely/447/assets/articles/strachey-fundamental-concepts-in-programming-languages.pdf) +* Cats Effect 文件:`IO`資料型別及 RT/惰性求值說明。 + [https://typelevel.org/cats-effect/docs/datatypes/io](https://typelevel.org/cats-effect/docs/datatypes/io) +* Typelevel 部落格:*《Cats 的 IO 單子》*(討論 Scala 的副作用與 RT 動機)。 + [https://typelevel.org/blog/2017/05/02/io-monad-for-cats.html](https://typelevel.org/blog/2017/05/02/io-monad-for-cats.html) diff --git a/src/concepts/referential_transparency.zh.md b/src/concepts/referential_transparency.zh.md new file mode 100644 index 0000000..697b5b4 --- /dev/null +++ b/src/concepts/referential_transparency.zh.md @@ -0,0 +1,80 @@ + + +# 引用透明性 {#referential-transparency} + +```admonish tip title="相关内容" +语义视角:[指称与组合性](../denotational-design/denotations.md)、[定律与解释](../denotational-design/laws-and-interpretations.md) +洞见:[重新审视引用透明性](../insights/referential-transparency.md) +``` + +```admonish note title="语义定位" +引用透明性取决于所选指称与等价关系。当替换表达式不会改变指定含义时,它允许进行替换,即使语义边界背后的实现操作有所不同。 +``` + +引用透明性(RT)是表达式的替换性质:可以用一个表达式的指称替换该表达式,而不改变程序含义。 + +如今,实践中通常将 RT 作为等式推理、安全重构与定律驱动 API 设计的基础。 + +## 核心含义 {#core-meaning} + +RT 表示: + +* 如果`e`指称`v` +* 那么,以`v`代替`e`会保留含义 + +这是语义主张,而非编码风格口号。 + +### 纯性 {#purity} + +纯函数对相同输入总是返回相同输出,并且没有可观察的副作用。RT 是表达式的替换定律:用其指称替换表达式必须保留含义。因此,纯函数是实践中实现 RT 的一种常见方式,而 RT 是更广泛的语义标准。关于指称设计中纯性与 RT 的区别,请参阅[《重新审视引用透明性》](../insights/referential-transparency.md)。 + +## 历史背景 {#historical-context} + +在编程语言语义中,RT 与 Christopher Strachey 的表述密切相关。他的论述将值推理与以更新为主的行为区分开来: + +* **R 值**:表达式的值。 +* **L 值**:可以赋值的位置。 + +关键在于:当我们进行值层面的推理时,表达式级别的替换是稳定的。赋值会引入位置更新,使替换推理变得困难,甚至不再以朴素形式成立。 + +## 这里的赋值与副作用意味着什么 {#what-assignment-and-side-effects-mean-here} + +在此上下文中: + +* **赋值**是对某个位置进行更新(例如`x := x + 1`) +* **副作用**是返回值之外任何可观察的变化 + +赋值是一种特定的副作用。 + +这就是 RT 在许多命令式环境中失效的原因:求值可能依赖或改变表达式显式值接口以外的可观察上下文。 + +## 现代语言如何呈现 RT {#how-modern-languages-present-rt} + +### Haskell {#haskell} + +纯表达式通常被当作默认推理对象来教授 RT。效应通过类型化构造显式表达(例如`IO`、状态传递及相关抽象),所以替换定律在日常使用中居于核心地位。 + +### Scala(Cats / Cats Effect) {#scala-cats--cats-effect} + +在 Scala 函数式编程实践中,Cats Effect 提供了最常见的 RT 解释方式: + +* `IO[A]`是对带效应工作的纯描述 +* 组合`IO`值满足 RT +* 在运行时边界显式执行(`unsafeRun*`) + +Cats Effect 也将其与急切求值`Future`作对比,这也是 Scala 中讨论 RT 时强调惰性与延迟执行的原因之一。 + +## 当代的 RT {#rt-today} + +在现代生态系统中,RT 常被用作“行为可安全替换”的简称。 在多范式系统中,团队通常会将 RT 主张应用于特定模块、API 或带效应类型的区域,而不是全局套用于所有代码。 + +关于 RT 在指称设计中的解读,请参阅[《重新审视引用透明性》](../insights/referential-transparency.md)。 + +## 参考文献 {#references} + +* Strachey, C. *《编程语言的基本概念》*(牛津 PRG 讲义,1967)。 + [https://reed.cs.depaul.edu/jriely/447/assets/articles/strachey-fundamental-concepts-in-programming-languages.pdf](https://reed.cs.depaul.edu/jriely/447/assets/articles/strachey-fundamental-concepts-in-programming-languages.pdf) +* Cats Effect 文档:`IO`数据类型及 RT/惰性求值说明。 + [https://typelevel.org/cats-effect/docs/datatypes/io](https://typelevel.org/cats-effect/docs/datatypes/io) +* Typelevel 博客:*《Cats 的 IO 单子》*(讨论 Scala 的副作用与 RT 动机)。 + [https://typelevel.org/blog/2017/05/02/io-monad-for-cats.html](https://typelevel.org/blog/2017/05/02/io-monad-for-cats.html) diff --git a/src/denotational-design/denotations.ar.md b/src/denotational-design/denotations.ar.md new file mode 100644 index 0000000..c41cdc7 --- /dev/null +++ b/src/denotational-design/denotations.ar.md @@ -0,0 +1,162 @@ + + +# الدلالات والتركيبية {#denotations-and-compositionality} + +```admonish tip title="ذات صلة" +المنظور الدلالي: [لماذا يأتي المعنى أولًا](semantic-view.md)، [التصميم الدلالي (Denotational Design)](design.md)، [القوانين والتفسيرات](laws-and-interpretations.md) +التصميم انطلاقًا من المعنى في Rust: [جبر القدرات](../rust-dd/capability-algebras.md) +المفاهيم: [الشفافية المرجعية](../concepts/referential_transparency.md)، [التشعب والتلاقي](../concepts/branching.md) +``` + +```admonish note title="الفكرة الأساسية" +الدلالة دالة معنى تنقل الصياغة إلى مجال دلالي مختار. ويكون علم الدلالة تركيبيًا عندما يتحدد معنى الكل بمعاني أجزائه، وهذا ما يتيح التساوي الدلالي والاستبدال الآمن. +``` + +**الدلالة** هي المعنى المسند إلى جزء من الصياغة أو إلى بنية برمجية. ونكتب عادةً: + +$$ \llbracket e \rrbracket $$ + +للدلالة على «معنى التعبير `e`». + +لا تقتضي الأقواس أن تكون الدلالة عددًا. فقد يدل البرنامج، بحسب المجال، على: + +* قيمة +* دالة +* علاقة +* مجموعة من النتائج الممكنة +* تحويل للحالة +* توزيع احتمالي +* سلوك العملية +* نتيجة جزئية + +لذلك ليس أول قرار تصميمي هو «أي بنية ينبغي أن تحتفظ بهذا؟» بل «ما المجال الدلالي الذي يحتوي المعاني التي تهمنا؟» + +## المجالات الدلالية {#semantic-domains} + +في التعبيرات الحسابية، قد يكون المجال البسيط هو الأعداد الصحيحة: + +$$ \llbracket e \rrbracket_{eval} \in \mathbb{Z} $$ + +وفي التنسيق، يمكن تفسير لغة التعبيرات نفسها على أنها نص: + +$$ \llbracket e \rrbracket_{pretty} \in \mathsf{String} $$ + +وفي حساب ذي آثار جانبية، قد يكون المجال تحويلًا للحالة: + +$$ \llbracket p \rrbracket : \mathsf{State} \to \mathsf{Result} \times \mathsf{State} $$ + +أما في لغة متزامنة، فقد يصف المجال سلوك العملية القابل للملاحظة بدلًا من مسار واحد محدد مسبقًا. + +يحدد المجال المختار الفروق ذات المعنى. فإذا لم يتضمن المجال الزمن، فقد تدل تنفيذان مختلفان في التوقيت على البرنامج نفسه. وإذا أُدرج استهلاك الموارد، فقد يصبح الفرق نفسه دلاليًا. + +## يتجاهل التجريد بعض التفاصيل عمدًا {#abstraction-forgets-intentionally} + +تتجاهل الدلالة المفيدة تفاصيل الآلة غير ذات الصلة. + +في موضع فرع، قد تحافظ الدلالة على المسار من الجذر وتتجاهل: + +* تخطيط البايتات +* استراتيجية التخصيص +* سلوك الذاكرة المخبأة +* تنسيق التسلسل + +في برنامج HTTP، قد تحافظ دلالة محمولة على الأسلوب والمسار وأدوار الإدخال والعملية ودور الإخراج، مع تجاهل الموجّه أو المنفّذ الذي سيستضيفه. + +في مرحلة من المترجم، قد تحافظ الدلالة على الترجمة من المصدر المطبّع إلى معنى قابل للتنفيذ، مع تجاهل المخازن المؤقتة وترتيب الاجتياز. + +التجاهل ليس عيبًا؛ فهو ما يجعل التمثيلات البديلة متكافئة. + +## التركيبية {#compositionality} + +يكون علم الدلالة **تركيبيًا** عندما يتحدد معنى الكل بمعاني أجزائه وطريقة جمعها. + +في الجمع: + +$$ \llbracket a + b \rrbracket = \llbracket a \rrbracket + \llbracket b \rrbracket $$ + +في تركيب الدوال بالتتابع: + +$$ \llbracket g \circ f \rrbracket = \llbracket g \rrbracket \circ \llbracket f \rrbracket $$ + +في عامل العملية المتوازية، يحتاج المجال الدلالي إلى تركيب متوازٍ مقابل: + +$$ \llbracket P \mid Q \rrbracket = \llbracket P \rrbracket \otimes \llbracket Q \rrbracket $$ + +يعتمد العامل الدقيق $\otimes$ على نموذج العملية المختار. والنقطة المهمة هي أن تركيب الصياغة يقابل بانتظام تركيبًا دلاليًا. + +تتيح التركيبية الاستدلال المحلي. فإذا كان لجزأين الدلالة نفسها، أمكن استبدال أحدهما بالآخر داخل أي سياق تركيبي: + +$$ \llbracket P \rrbracket = \llbracket Q \rrbracket \implies \llbracket C(P) \rrbracket = \llbracket C(Q) \rrbracket $$ + +هذا هو الأساس الذي يقوم عليه الاستبدال الآمن وإعادة الهيكلة الدلالية. + +## التساوي الدلالي {#semantic-equality} + +لا يلزم أن تكون البرامج متطابقة نصيًا أو تشغيليًا كي تكون متساوية دلاليًا. + +تأمل تنفيذين لموضع فرع: + +$$ \lbrack \mathsf{Left}, \mathsf{Right}, \mathsf{Left} \rbrack $$ + +وترميزًا عدديًا يمثل المسار نفسه. تختلف قيمهما في الذاكرة، لكن قد تتساوى دلالتاهما. + +وبالمثل، قد تجتاز مرحلتان من المترجم الصياغة بترتيبين مختلفين، لكنهما تنتجان ملفات تنفيذية ذات السلوك المحدد نفسه. أما اشتراط التطابق بايتًا ببايت فهو قانون مستقل وأقوى. + +سمِّ دائمًا نوع التساوي الذي تدّعيه: + +* تساوي القيم +* التساوي البنيوي +* تساوي التمثيل المعياري +* تكافؤ المسارات +* التشابه المحاكي +* التكافؤ الرصدي +* التساوي الدلالي + +الخلط بين هذه الأنواع من التساوي مصدر شائع للقوانين الخاطئة. + +## الخارجية نسبية {#externality-is-relative} + +لنفترض أن لحساب ما المعنى التالي: + +$$ H \times E \to O $$ + +بالنسبة إلى `H`، يكون الدليل `E` خارجيًا. وإذا اختار تجريد جديد `H × E` حاملًا له، صار ذلك الدليل داخليًا ضمن الحد الجديد. + +تكتسب هذه الملاحظة أهميتها عند التعامل مع الآثار والسياق. لا توجد حقيقة «بيئية» بإطلاق. السؤال هو ما إذا كان الحامل الدلالي الحالي يتضمنها وما القوانين التي تحكمها. + +```admonish warning title="تجنب كائن سياق شاملًا" +لا تحل مسألة الحدود هذه بكائن سياق شامل. سمِّ كل معنى مقبول على أنه قدرة أو قيمة صريحة. +``` + +## المعنى الأولي والمعنى المشتق {#primitive-and-derived-meaning} + +العمليات الأولية هي المفردات المختارة للمجال الدلالي. أما العمليات المشتقة فتُعرّف انطلاقًا منها. + +قد تتألف المفردات الأولية الصغيرة لمواضع الفروع من: + +* موضع الجذر +* الامتداد باتجاه معين +* ملاحظة المسار من موضع إلى آخر + +ويمكن بعد ذلك اشتقاق ما يلي: + +* الامتداد يسارًا +* الامتداد يمينًا +* الإنشاء من مسار +* اختبار ما إذا كان موضع سلفًا لموضع آخر +* اختبار ما إذا كان موضع نسلًا لموضع آخر + +هذا الفرق خيار تصميم لا حقيقة ميتافيزيقية. فضّل مجموعة أولية صغيرة تجعل صياغة القوانين والتفسيرات البديلة سهلة. + +## اختبار مفيد {#a-useful-test} + +قبل تقديم واجهة برمجية، أكمل الجمل التالية: + +* تعني قيم هذا التجريد ... +* الملاحظات الأولية هي ... +* التركيبات ذات المعنى هي ... +* تكون قيمتان متكافئتين عندما ... +* يجب على كل تنفيذ الحفاظ على ... +* يتجاهل التجريد عمدًا ... + +إذا تعذر إكمال هذه الجمل، فلن توفر زيادة آليات التنفيذ المعنى الناقص. diff --git a/src/denotational-design/denotations.de.md b/src/denotational-design/denotations.de.md new file mode 100644 index 0000000..21252e3 --- /dev/null +++ b/src/denotational-design/denotations.de.md @@ -0,0 +1,162 @@ + + +# Denotationen und Kompositionalität {#denotations-and-compositionality} + +```admonish tip title="Verwandte Themen" +The Semantic View: [Warum Bedeutung an erster Stelle steht](semantic-view.md), [Denotational Design](design.md), [Gesetze und Interpretationen](laws-and-interpretations.md) +Design by Meaning in Rust: [Capability-Algebren](../rust-dd/capability-algebras.md) +Concepts: [Referenzielle Transparenz](../concepts/referential_transparency.md), [Verzweigung und Konfluenz](../concepts/branching.md) +``` + +```admonish note title="Grundidee" +Eine Denotation ist eine Bedeutungsfunktion von der Syntax in einen gewählten semantischen Bereich. Eine Semantik ist kompositional, wenn sich die Bedeutung eines Ganzen aus den Bedeutungen seiner Teile ergibt. Dadurch werden semantische Gleichheit und sicheres Ersetzen möglich. +``` + +Eine **Denotation** ist die Bedeutung, die einem Syntaxelement oder einer Programmkonstruktion zugewiesen wird. Häufig schreiben wir: + +$$ \llbracket e \rrbracket $$ + +für „die Bedeutung des Ausdrucks `e`“. + +Die Klammern legen nicht fest, dass die Denotation eine Zahl sein muss. Je nach Bereich kann ein Programm Folgendes bezeichnen: + +* einen Wert +* eine Funktion +* eine Relation +* eine Menge möglicher Ergebnisse +* eine Zustandstransformation +* eine Wahrscheinlichkeitsverteilung +* das Verhalten eines Prozesses +* ein Teilergebnis + +Die erste Entwurfsentscheidung lautet daher nicht: „Welche Struktur soll das aufnehmen?“, sondern: „Welcher semantische Bereich enthält die Bedeutungen, die uns wichtig sind?“ + +## Semantische Bereiche {#semantic-domains} + +Für arithmetische Ausdrücke kann ein einfacher Bereich aus den ganzen Zahlen bestehen: + +$$ \llbracket e \rrbracket_{eval} \in \mathbb{Z} $$ + +Bei der Formatierung kann dieselbe Ausdruckssprache als Text interpretiert werden: + +$$ \llbracket e \rrbracket_{pretty} \in \mathsf{String} $$ + +Bei einer Berechnung mit Seiteneffekten könnte der Bereich eine Zustandstransformation sein: + +$$ \llbracket p \rrbracket : \mathsf{State} \to \mathsf{Result} \times \mathsf{State} $$ + +Bei einer nebenläufigen Sprache kann der Bereich das beobachtbare Prozessverhalten beschreiben, statt eine einzige vorgegebene Ablaufspur. + +Der gewählte Bereich bestimmt, welche Unterschiede Bedeutung haben. Ist Zeitverhalten nicht Teil des Bereichs, können zwei Implementierungen trotz unterschiedlichen Timings dasselbe Programm bezeichnen. Wird der Ressourcenverbrauch einbezogen, kann derselbe Unterschied semantisch relevant werden. + +## Abstraktion blendet bewusst aus {#abstraction-forgets-intentionally} + +Eine nützliche Denotation blendet irrelevante Maschinendetails aus. + +Für eine Verzweigungsposition kann die Denotation den Pfad von der Wurzel bewahren und zugleich Folgendes ausblenden: + +* Byteanordnung +* Allokationsstrategie +* Cache-Verhalten +* Serialisierungsformat + +Für ein HTTP-Programm kann eine portable Denotation Methode, Pfad, Eingaberollen, Operation und Ausgaberolle bewahren und zugleich ausblenden, welcher Router oder Executor das Programm ausführt. + +Für eine Compilerstufe kann die Denotation die Übersetzung von normalisiertem Quelltext in ausführbare Bedeutung bewahren und zugleich temporäre Puffer und die Reihenfolge der Durchläufe ausblenden. + +Ausblenden ist kein Mangel. Dadurch werden alternative Repräsentationen äquivalent. + +## Kompositionalität {#compositionality} + +Eine Semantik ist **kompositional**, wenn sich die Bedeutung eines Ganzen aus den Bedeutungen seiner Teile und der Art ihrer Verknüpfung ergibt. + +Für die Addition: + +$$ \llbracket a + b \rrbracket = \llbracket a \rrbracket + \llbracket b \rrbracket $$ + +Für die sequenzielle Komposition von Funktionen: + +$$ \llbracket g \circ f \rrbracket = \llbracket g \rrbracket \circ \llbracket f \rrbracket $$ + +Für einen Operator paralleler Prozesse braucht der semantische Bereich eine entsprechende parallele Komposition: + +$$ \llbracket P \mid Q \rrbracket = \llbracket P \rrbracket \otimes \llbracket Q \rrbracket $$ + +Der konkrete Operator $\otimes$ hängt vom gewählten Prozessmodell ab. Entscheidend ist, dass sich die syntaktische Komposition systematisch auf die semantische Komposition abbildet. + +Kompositionalität ermöglicht lokales Schlussfolgern. Haben zwei Teile dieselbe Denotation, kann der eine in jedem kompositionalen Kontext durch den anderen ersetzt werden: + +$$ \llbracket P \rrbracket = \llbracket Q \rrbracket \implies \llbracket C(P) \rrbracket = \llbracket C(Q) \rrbracket $$ + +Darauf beruhen sicheres Ersetzen und semantisches Refactoring. + +## Semantische Gleichheit {#semantic-equality} + +Programme müssen weder textuell noch operational identisch sein, um semantisch gleich zu sein. + +Betrachte zwei Implementierungen einer Verzweigungsposition: + +$$ \lbrack \mathsf{Left}, \mathsf{Right}, \mathsf{Left} \rbrack $$ + +und eine Ganzzahlkodierung, die denselben Pfad bezeichnet. Ihre gespeicherten Werte unterscheiden sich, ihre Denotationen können jedoch gleich sein. + +Ebenso können zwei Compiler-Pässe die Syntax in unterschiedlicher Reihenfolge durchlaufen und dennoch ausführbare Programme mit demselben spezifizierten Verhalten erzeugen. Ob Byte-für-Byte-Gleichheit erforderlich ist, ist ein separates, strengeres Gesetz. + +Benenne immer die behauptete Gleichheit: + +* Wertgleichheit +* strukturelle Gleichheit +* Gleichheit der kanonischen Repräsentation +* Spuräquivalenz +* Bisimilarität +* beobachtungsbezogene Äquivalenz +* denotationelle Gleichheit + +Diese Gleichheiten zu verwechseln, ist eine häufige Quelle falscher Gesetze. + +## Externalität ist relativ {#externality-is-relative} + +Angenommen, eine Berechnung hat folgende Bedeutung: + +$$ H \times E \to O $$ + +Bezogen auf `H` ist der Nachweis `E` extern. Wählt eine neue Abstraktion `H × E` als ihren Träger, wird dieser Nachweis innerhalb der neuen Grenze intern. + +Diese Beobachtung ist für Effekte und Kontexte wichtig. Keine Tatsache ist grundsätzlich eine Umgebungsbedingung. Entscheidend ist, ob der aktuelle semantische Träger sie einschließt und welche Gesetze dafür gelten. + +```admonish warning title="Kein universelles Kontextobjekt" +Löse diese Grenzfrage nicht mit einem universellen Kontextobjekt. Benenne jede zugelassene Bedeutung als Capability oder expliziten Wert. +``` + +## Primitive und abgeleitete Bedeutung {#primitive-and-derived-meaning} + +Primitive Operationen bilden das gewählte Vokabular des semantischen Bereichs. Abgeleitete Operationen werden daraus definiert. + +Für Verzweigungspositionen könnte ein kleines primitives Vokabular so aussehen: + +* Eine Wurzelposition +* Erweiterung um eine Richtung +* Beobachtung des Pfads von einer Position zu einer anderen + +Daraus lassen sich ableiten: + +* Nach links erweitern +* Nach rechts erweitern +* Aus einem Pfad konstruieren +* Prüfen, ob eine Position Vorfahr einer anderen ist +* Prüfen, ob eine Position Nachfahr einer anderen ist + +Diese Unterscheidung ist eine Entwurfsentscheidung, keine metaphysische Tatsache. Bevorzuge eine kleine Menge primitiver Operationen, mit der sich Gesetze und alternative Interpretationen leicht formulieren lassen. + +## Ein nützlicher Test {#a-useful-test} + +Vervollständige vor dem Einführen einer Programmierschnittstelle diese Sätze: + +* Werte dieser Abstraktion bedeuten ... +* Die primitiven Beobachtungen sind ... +* Die sinnvollen Kompositionen sind ... +* Zwei Werte sind äquivalent, wenn ... +* Jede Implementierung muss ... bewahren +* Die Abstraktion blendet bewusst ... aus + +Lassen sich diese Sätze nicht vervollständigen, liefert zusätzliche Implementierungsmechanik nicht die fehlende Bedeutung. diff --git a/src/denotational-design/denotations.es.md b/src/denotational-design/denotations.es.md new file mode 100644 index 0000000..838ff51 --- /dev/null +++ b/src/denotational-design/denotations.es.md @@ -0,0 +1,162 @@ + + +# Denotaciones y composicionalidad {#denotations-and-compositionality} + +```admonish tip title="Relacionado" +La perspectiva semántica: [Por qué el significado va primero](semantic-view.md), [Diseño denotacional](design.md), [Leyes e interpretaciones](laws-and-interpretations.md) +Diseño por significado en Rust: [Álgebras de capacidades](../rust-dd/capability-algebras.md) +Conceptos: [Transparencia referencial](../concepts/referential_transparency.md), [Ramificación y confluencia](../concepts/branching.md) +``` + +```admonish note title="Idea central" +Una denotación es una función de significado desde la sintaxis hacia un dominio semántico elegido. Una semántica es composicional cuando el significado del todo queda determinado por los significados de sus partes, lo que permite la igualdad semántica y la sustitución segura. +``` + +Una **denotación** es el significado asignado a un fragmento de sintaxis o a una construcción de programación. A menudo escribimos: + +$$ \llbracket e \rrbracket $$ + +para «el significado de la expresión `e`». + +Los corchetes no exigen que la denotación sea un número. Según el dominio, un programa puede denotar: + +* un valor +* una función +* una relación +* un conjunto de resultados posibles +* una transformación de estado +* una distribución de probabilidad +* el comportamiento de un proceso +* un resultado parcial + +Por tanto, la primera decisión de diseño no es «¿qué estructura debe contener esto?», sino «¿qué dominio semántico contiene los significados que nos importan?». + +## Dominios semánticos {#semantic-domains} + +Para expresiones aritméticas, un dominio sencillo puede ser el de los números enteros: + +$$ \llbracket e \rrbracket_{eval} \in \mathbb{Z} $$ + +Para el formato, el mismo lenguaje de expresiones puede interpretarse como texto: + +$$ \llbracket e \rrbracket_{pretty} \in \mathsf{String} $$ + +Para un cálculo con efectos, el dominio podría ser una transformación de estado: + +$$ \llbracket p \rrbracket : \mathsf{State} \to \mathsf{Result} \times \mathsf{State} $$ + +Para un lenguaje concurrente, el dominio puede describir el comportamiento observable del proceso en lugar de una única traza predeterminada. + +El dominio elegido determina qué diferencias tienen significado. Si el tiempo no forma parte del dominio, dos implementaciones con distintos tiempos pueden denotar el mismo programa. Si se incluye el consumo de recursos, esa misma diferencia puede volverse semántica. + +## La abstracción omite detalles intencionalmente {#abstraction-forgets-intentionally} + +Una denotación útil omite detalles irrelevantes de la máquina. + +Para una posición de ramificación, la denotación puede conservar el camino desde la raíz y omitir: + +* disposición de bytes +* estrategia de asignación +* comportamiento de la caché +* formato de serialización + +Para un programa HTTP, una denotación portable puede conservar el método, la ruta, los roles de entrada, la operación y el rol de salida, y omitir qué enrutador o ejecutor lo alojará. + +Para una fase del compilador, la denotación puede conservar la traducción desde el código fuente normalizado hasta el significado ejecutable, y omitir los búferes temporales y el orden de recorrido. + +Omitir no es un defecto. Es lo que hace equivalentes a representaciones alternativas. + +## Composicionalidad {#compositionality} + +Una semántica es **composicional** cuando el significado del todo viene determinado por los significados de sus partes y por cómo se combinan. + +Para la suma: + +$$ \llbracket a + b \rrbracket = \llbracket a \rrbracket + \llbracket b \rrbracket $$ + +Para la composición secuencial de funciones: + +$$ \llbracket g \circ f \rrbracket = \llbracket g \rrbracket \circ \llbracket f \rrbracket $$ + +Para un operador de procesos paralelos, el dominio semántico necesita una composición paralela correspondiente: + +$$ \llbracket P \mid Q \rrbracket = \llbracket P \rrbracket \otimes \llbracket Q \rrbracket $$ + +El operador exacto $\otimes$ depende del modelo de proceso elegido. Lo importante es que la composición sintáctica se corresponda sistemáticamente con la composición semántica. + +La composicionalidad permite razonar localmente. Si dos partes tienen la misma denotación, una puede sustituirse por la otra dentro de cualquier contexto composicional: + +$$ \llbracket P \rrbracket = \llbracket Q \rrbracket \implies \llbracket C(P) \rrbracket = \llbracket C(Q) \rrbracket $$ + +Esta es la base de la sustitución segura y la refactorización semántica. + +## Igualdad semántica {#semantic-equality} + +Los programas no necesitan ser idénticos textual u operacionalmente para ser semánticamente iguales. + +Considera dos implementaciones de una posición de ramificación: + +$$ \lbrack \mathsf{Left}, \mathsf{Right}, \mathsf{Left} \rbrack $$ + +y una codificación entera que denota el mismo camino. Sus valores en memoria son distintos, pero sus denotaciones pueden ser iguales. + +Del mismo modo, dos pasadas del compilador pueden recorrer la sintaxis en órdenes distintos y producir ejecutables con el mismo comportamiento especificado. Exigir igualdad byte por byte es una ley aparte y más fuerte. + +Nombra siempre la igualdad que afirmas: + +* igualdad de valores +* igualdad estructural +* igualdad de representación canónica +* equivalencia de trazas +* bisimilaridad +* equivalencia observacional +* igualdad denotacional + +Confundir estas igualdades es una fuente común de leyes falsas. + +## La externalidad es relativa {#externality-is-relative} + +Supongamos que un cálculo tiene el siguiente significado: + +$$ H \times E \to O $$ + +Respecto de `H`, la evidencia `E` es externa. Si una nueva abstracción elige `H × E` como su portador, esa evidencia pasa a ser interna al nuevo límite. + +Esta observación importa para los efectos y el contexto. Ningún hecho es «ambiental» de forma absoluta. La cuestión es si el portador semántico actual lo incluye y qué leyes lo rigen. + +```admonish warning title="Evita un objeto de contexto universal" +No resuelvas esta cuestión de límites con un objeto de contexto universal. Nombra cada significado admitido como capacidad o valor explícito. +``` + +## Significado primitivo y derivado {#primitive-and-derived-meaning} + +Las operaciones primitivas son el vocabulario elegido para el dominio semántico. Las operaciones derivadas se definen a partir de ellas. + +Para posiciones de ramificación, un pequeño vocabulario primitivo podría incluir: + +* Una posición raíz +* Crecer en una dirección +* Observar el camino de una posición a otra + +A partir de ello se pueden derivar: + +* Crecer a la izquierda +* Crecer a la derecha +* Construir a partir de un camino +* Comprobar si una posición es antecesora de otra +* Comprobar si una posición es descendiente de otra + +La distinción es una decisión de diseño, no un hecho metafísico. Prefiere un conjunto primitivo reducido que facilite expresar leyes e interpretaciones alternativas. + +## Una prueba útil {#a-useful-test} + +Antes de introducir una interfaz de programación, completa estas frases: + +* Los valores de esta abstracción significan ... +* Las observaciones primitivas son ... +* Las composiciones significativas son ... +* Dos valores son equivalentes cuando ... +* Toda implementación debe preservar ... +* La abstracción omite intencionalmente ... + +Si no puedes completar estas frases, más mecanismos de implementación no aportarán el significado que falta. diff --git a/src/denotational-design/denotations.ja.md b/src/denotational-design/denotations.ja.md new file mode 100644 index 0000000..5d18dcd --- /dev/null +++ b/src/denotational-design/denotations.ja.md @@ -0,0 +1,162 @@ + + +# 表示と合成性 {#denotations-and-compositionality} + +```admonish tip title="関連項目" +意味論的な見方:[なぜ意味を先に考えるのか](semantic-view.md)、[Denotational Design](design.md)、[法則と解釈](laws-and-interpretations.md) +Rustで意味から設計する:[ケイパビリティ代数](../rust-dd/capability-algebras.md) +概念:[参照透過性](../concepts/referential_transparency.md)、[分岐と合流性](../concepts/branching.md) +``` + +```admonish note title="中心となる考え方" +表示とは、構文から選択した意味論的領域への意味関数です。全体の意味が部分の意味によって定まるとき、その意味論は合成的です。これにより意味上の等値性と安全な置換が可能になります。 +``` + +**表示**とは、構文の一部またはプログラミング構成要素に割り当てられた意味です。通常、次のように表記します。 + +$$ \llbracket e \rrbracket $$ + +「式`e`の意味」を表します。 + +この括弧は、表示が数値でなければならないという意味ではありません。意味論的領域によって、プログラムは次のものを表し得ます。 + +* 値 +* 関数 +* 関係 +* 起こり得る結果の集合 +* 状態変換 +* 確率分布 +* プロセスの振る舞い +* 部分的な結果 + +したがって、最初の設計判断は「この値をどの構造体に保持させるか」ではありません。「必要な意味を含む意味論的領域は何か」です。 + +## 意味論的領域 {#semantic-domains} + +算術式の場合、単純な領域として整数を選べます。 + +$$ \llbracket e \rrbracket_{eval} \in \mathbb{Z} $$ + +書式設定では、同じ式言語をテキストとして解釈できます。 + +$$ \llbracket e \rrbracket_{pretty} \in \mathsf{String} $$ + +副作用のある計算では、領域は状態変換かもしれません。 + +$$ \llbracket p \rrbracket : \mathsf{State} \to \mathsf{Result} \times \mathsf{State} $$ + +並行言語では、領域はあらかじめ定められた一つのトレースではなく、観測可能なプロセスの振る舞いを記述する場合があります。 + +選択した領域によって、どの差異に意味があるかが決まります。領域に時間が含まれなければ、実行時間の異なる二つの実装が同じプログラムを表すことがあります。リソース消費を含めた場合、同じ差異が意味論上の差異になることがあります。 + +## 抽象化では意図的に情報を捨てる {#abstraction-forgets-intentionally} + +有用な表示は、関係のない機械上の詳細を捨てます。 + +分岐位置の表示では、根からの経路を保持しつつ、次の情報を捨てる場合があります。 + +* バイト配置 +* 割り当て方式 +* キャッシュの振る舞い +* シリアライズ形式 + +HTTPプログラムの移植可能な表示では、メソッド、パス、入力の役割、操作、出力の役割を保持しながら、どのルーターや実行器が処理するかを捨てることができます。 + +コンパイラーステージの表示では、一時バッファーや走査順を捨て、正規化されたソースから実行可能な意味への変換を保持できます。 + +情報を捨てることは欠陥ではありません。別の表現を等価とみなせるようにするものです。 + +## 合成性 {#compositionality} + +全体の意味が部分の意味と、それらを組み合わせる方法によって定まるとき、意味論は**合成的**です。 + +加算の場合: + +$$ \llbracket a + b \rrbracket = \llbracket a \rrbracket + \llbracket b \rrbracket $$ + +関数の逐次合成の場合: + +$$ \llbracket g \circ f \rrbracket = \llbracket g \rrbracket \circ \llbracket f \rrbracket $$ + +並列プロセス演算子の場合、意味論的領域には対応する並列合成が必要です。 + +$$ \llbracket P \mid Q \rrbracket = \llbracket P \rrbracket \otimes \llbracket Q \rrbracket $$ + +正確な演算子$\otimes$は選択したプロセスモデルによって異なります。重要なのは、構文の合成が体系的に意味論上の合成へ対応することです。 + +合成性が局所的な推論を可能にします。二つの部分の表示が同じなら、合成的な文脈では一方を他方で置き換えられます。 + +$$ \llbracket P \rrbracket = \llbracket Q \rrbracket \implies \llbracket C(P) \rrbracket = \llbracket C(Q) \rrbracket $$ + +これが安全な置換と意味論に基づくリファクタリングの土台です。 + +## 意味論的等値性 {#semantic-equality} + +プログラムは、テキスト上も操作上も同一でなくても、意味論的に等価であり得ます。 + +分岐位置の二つの実装を考えます。 + +$$ \lbrack \mathsf{Left}, \mathsf{Right}, \mathsf{Left} \rbrack $$ + +そして同じ経路を表す整数による符号化を考えます。メモリー上の値は異なりますが、表示は等しい場合があります。 + +同様に、二つのコンパイラーパスが異なる順序で構文を走査しても、指定された振る舞いが同じ実行可能ファイルを生成することがあります。バイト単位の一致が必要かどうかは、別途定めるより強い法則です。 + +主張する等値性の種類は、必ず明示します。 + +* 値の等価性 +* 構造的等価性 +* 正準表現の等価性 +* トレース等価性 +* 双模倣性 +* 観測的等価性 +* 表示の等値性 + +これらの等値性を混同すると、誤った法則を立てることがよくあります。 + +## 外部性は相対的 {#externality-is-relative} + +ある計算が次の意味を持つとします。 + +$$ H \times E \to O $$ + +`H`に対して、証拠`E`は外部にあります。新しい抽象化が`H × E`を担体として選ぶと、その証拠は新たな境界の内部になります。 + +この見方は、副作用やコンテキストに関わります。「環境に属する」事実というものが絶対的にあるわけではありません。現在の意味論的担体がその事実を含むか、そしてどの法則がそれを支配するかが問題です。 + +```admonish warning title="万能なコンテキストオブジェクトを避ける" +この境界の問題を万能なコンテキストオブジェクトで解決しないでください。認められた各意味は、ケイパビリティまたは明示的な値として名付けます。 +``` + +## 基本的な意味と導出される意味 {#primitive-and-derived-meaning} + +基本操作とは、意味論的領域の語彙として選ばれた操作です。導出操作は、それらから定義されます。 + +分岐位置の場合、小さな基本語彙として次のものが考えられます。 + +* 根となる位置 +* 方向による拡張 +* ある位置から別の位置への経路の観測 + +そこから次の操作を導出できます。 + +* 左へ伸ばす +* 右へ伸ばす +* 経路から構築する +* ある位置が別の位置の祖先かどうかを判定する +* ある位置が別の位置の子孫かどうかを判定する + +この区別は設計上の選択であり、形而上学的な事実ではありません。法則と別の解釈を明確に述べられる、小さな基本操作の集合を優先してください。 + +## 有用な確認方法 {#a-useful-test} + +プログラミングインターフェースを導入する前に、次の文を完成させます。 + +* この抽象化の値が意味するのは…… +* 基本となる観測は…… +* 意味のある合成は…… +* 二つの値が等価なのは……の場合 +* すべての実装が保持しなければならないのは…… +* この抽象化が意図的に捨てるのは…… + +これらの文を完成できないなら、不足している意味を実装の仕組みを増やして補うことはできません。 diff --git a/src/denotational-design/denotations.ko.md b/src/denotational-design/denotations.ko.md new file mode 100644 index 0000000..9f3ad43 --- /dev/null +++ b/src/denotational-design/denotations.ko.md @@ -0,0 +1,162 @@ + + +# 표시와 합성성 {#denotations-and-compositionality} + +```admonish tip title="관련 항목" +의미론적 관점: [왜 의미가 먼저인가](semantic-view.md), [표시적 설계](design.md), [법칙과 해석](laws-and-interpretations.md) +Rust에서 의미로 설계하기: [케이퍼빌리티 대수](../rust-dd/capability-algebras.md) +개념: [참조 투명성](../concepts/referential_transparency.md), [분기와 합류성](../concepts/branching.md) +``` + +```admonish note title="핵심 아이디어" +표시는 구문을 선택한 의미론적 영역으로 대응시키는 의미 함수입니다. 전체의 의미가 각 부분의 의미로 정해질 때 그 의미론은 합성적이며, 이로써 의미론적 등식과 안전한 치환이 가능해집니다. +``` + +**표시**란 구문 조각이나 프로그래밍 구성 요소에 부여된 의미입니다. 흔히 다음과 같이 씁니다: + +$$ \llbracket e \rrbracket $$ + +“표현식 `e`의 의미”를 나타냅니다. + +대괄호로 표시한다고 해서 표시가 숫자여야 하는 것은 아닙니다. 영역에 따라 프로그램은 다음을 나타낼 수 있습니다: + +* 값 +* 함수 +* 관계 +* 가능한 결과의 집합 +* 상태 변환 +* 확률 분포 +* 프로세스 동작 +* 부분 결과 + +따라서 첫 설계 결정은 “이 값을 어떤 구조체에 담을까?”가 아닙니다. “관심 있는 의미를 담을 의미론적 영역은 무엇인가?”입니다. + +## 의미론적 영역 {#semantic-domains} + +산술 표현식의 간단한 영역은 정수일 수 있습니다: + +$$ \llbracket e \rrbracket_{eval} \in \mathbb{Z} $$ + +서식 지정에서는 같은 표현식 언어를 텍스트로 해석할 수 있습니다: + +$$ \llbracket e \rrbracket_{pretty} \in \mathsf{String} $$ + +효과가 있는 계산의 영역은 상태 변환일 수 있습니다: + +$$ \llbracket p \rrbracket : \mathsf{State} \to \mathsf{Result} \times \mathsf{State} $$ + +동시성 언어의 영역은 미리 정해진 하나의 실행 기록이 아니라 관찰 가능한 프로세스 동작을 기술할 수 있습니다. + +선택한 영역이 어떤 차이를 의미 있는 것으로 볼지 결정합니다. 시간 정보가 영역에 없다면 실행 시간이 다른 두 구현도 같은 프로그램을 나타낼 수 있습니다. 자원 소비가 포함된다면 같은 차이가 의미론적 차이가 될 수 있습니다. + +## 추상화는 의도적으로 잊습니다 {#abstraction-forgets-intentionally} + +유용한 표시는 중요하지 않은 기계 세부 사항을 잊습니다. + +분기 위치의 경우, 표시는 루트에서 이어지는 경로를 보존하면서 다음을 잊을 수 있습니다: + +* 바이트 레이아웃 +* 할당 전략 +* 캐시 동작 +* 직렬화 형식 + +HTTP 프로그램의 이식 가능한 표시는 어떤 라우터나 실행기가 이를 호스팅할지는 잊고 메서드, 경로, 입력 역할, 연산, 출력 역할을 보존할 수 있습니다. + +컴파일러 단계의 표시는 임시 버퍼와 순회 순서는 잊고 정규화된 소스에서 실행 가능한 의미로의 변환을 보존할 수 있습니다. + +잊는 것은 결함이 아닙니다. 그래야 서로 다른 표현이 동치가 됩니다. + +## 합성성 {#compositionality} + +전체의 의미가 각 부분의 의미와 부분을 결합하는 방식으로 결정될 때 의미론은 **합성적**입니다. + +덧셈의 경우: + +$$ \llbracket a + b \rrbracket = \llbracket a \rrbracket + \llbracket b \rrbracket $$ + +함수의 순차 합성의 경우: + +$$ \llbracket g \circ f \rrbracket = \llbracket g \rrbracket \circ \llbracket f \rrbracket $$ + +병렬 프로세스 연산자의 경우, 의미론적 영역에는 이에 대응하는 병렬 합성이 필요합니다: + +$$ \llbracket P \mid Q \rrbracket = \llbracket P \rrbracket \otimes \llbracket Q \rrbracket $$ + +정확한 연산자 $\otimes$는 선택한 프로세스 모델에 따라 달라집니다. 중요한 것은 구문 합성이 의미 합성에 체계적으로 대응한다는 점입니다. + +합성성은 국소 추론을 가능하게 합니다. 두 부분의 표시가 같다면 합성적 컨텍스트 안에서 한 부분을 다른 부분으로 바꿀 수 있습니다: + +$$ \llbracket P \rrbracket = \llbracket Q \rrbracket \implies \llbracket C(P) \rrbracket = \llbracket C(Q) \rrbracket $$ + +이 원리가 안전한 치환과 의미론적 리팩터링의 토대입니다. + +## 의미론적 등식 {#semantic-equality} + +프로그램이 의미론적으로 같으려면 텍스트나 작동 방식이 동일할 필요는 없습니다. + +분기 위치의 두 가지 구현을 생각해 보세요: + +$$ \lbrack \mathsf{Left}, \mathsf{Right}, \mathsf{Left} \rbrack $$ + +그리고 같은 경로를 나타내는 정수 인코딩이 있습니다. 메모리 값은 다르지만 표시는 같을 수 있습니다. + +마찬가지로 두 컴파일러 패스가 구문을 서로 다른 순서로 순회하면서도 명세된 동작이 같은 실행 파일을 만들 수 있습니다. 바이트 단위로 같은 결과가 필요한지는 별도의 더 강한 법칙입니다. + +어떤 등식을 주장하는지 항상 명시하세요: + +* 값의 동등성 +* 구조적 동등성 +* 정규 표현의 동등성 +* 실행 기록 동치 +* 쌍방향 시뮬레이션 동치 +* 관찰적 동치 +* 표시적 동등성 + +이 등식들을 혼동하면 잘못된 법칙을 세우기 쉽습니다. + +## 외부성은 상대적입니다 {#externality-is-relative} + +계산에 다음과 같은 의미가 있다고 가정해 봅시다: + +$$ H \times E \to O $$ + +`H`을 기준으로 보면 증거 `E`은 외부에 있습니다. 새로운 추상화가 `H × E`를 기반 집합으로 선택하면 그 증거는 새 경계 안에 포함됩니다. + +이 관찰은 효과와 컨텍스트를 다룰 때 중요합니다. 어떤 사실도 절대적으로 “환경적”이지 않습니다. 현재 의미론적 기반 집합이 그 사실을 포함하는지, 어떤 법칙이 이를 다스리는지가 관건입니다. + +```admonish warning title="범용 컨텍스트 객체를 피하세요" +범용 컨텍스트 객체로 이 경계 문제를 해결하려 하지 마세요. 허용된 의미 각각을 케이퍼빌리티 또는 명시적 값으로 나타내세요. +``` + +## 기본 의미와 파생 의미 {#primitive-and-derived-meaning} + +기본 연산은 의미론적 영역의 어휘로 선택한 연산입니다. 파생 연산은 기본 연산으로 정의합니다. + +분기 위치의 작은 기본 어휘는 다음과 같을 수 있습니다: + +* 루트 위치 +* 방향에 따른 확장 +* 한 위치에서 다른 위치까지의 경로 관찰 + +그런 다음 다음을 파생할 수 있습니다: + +* 왼쪽으로 확장 +* 오른쪽으로 확장 +* 경로에서 구성 +* 한 위치가 다른 위치의 조상인지 판정 +* 한 위치가 다른 위치의 자손인지 판정 + +이 구분은 형이상학적 사실이 아니라 설계 선택입니다. 법칙과 대안적 해석을 쉽게 표현할 수 있도록 작은 기본 집합을 선택하세요. + +## 유용한 점검 {#a-useful-test} + +프로그래밍 인터페이스를 도입하기 전에 다음 문장을 완성해 보세요: + +* 이 추상화의 값은 ...을 의미한다 +* 기본 관찰은 ...이다 +* 의미 있는 합성은 ...이다 +* 두 값은 ...일 때 동치다 +* 모든 구현은 ...을 보존해야 한다 +* 이 추상화는 ...을 의도적으로 잊는다 + +이 문장들을 완성할 수 없다면, 구현 장치를 더 늘려도 빠진 의미를 채울 수 없습니다. diff --git a/src/denotational-design/denotations.ru.md b/src/denotational-design/denotations.ru.md new file mode 100644 index 0000000..42a302d --- /dev/null +++ b/src/denotational-design/denotations.ru.md @@ -0,0 +1,162 @@ + + +# Денотации и композиционность {#denotations-and-compositionality} + +```admonish tip title="Связанные материалы" +«Семантический взгляд»: [Почему начинать нужно со смысла](semantic-view.md), [Денотационное проектирование](design.md), [Законы и интерпретации](laws-and-interpretations.md) +«Проектирование на основе смысла в Rust»: [Алгебры возможностей](../rust-dd/capability-algebras.md) +«Понятия»: [Референциальная прозрачность](../concepts/referential_transparency.md), [Ветвление и конфлюэнтность](../concepts/branching.md) +``` + +```admonish note title="Основная идея" +Денотация — это функция смысла, переводящая синтаксис в выбранную семантическую область. Семантика композиционна, когда смысл целого определяется смыслами его частей; именно это делает возможными семантическое равенство и безопасную подстановку. +``` + +**Денотация** — это смысл, приписанный фрагменту синтаксиса или конструкции языка программирования. Часто её записывают так: + +$$ \llbracket e \rrbracket $$ + +«смысл выражения `e`». + +Скобки не означают, что денотация обязательно является числом. В зависимости от области программа может обозначать: + +* значение +* функцию +* отношение +* множество возможных результатов +* преобразование состояния +* распределение вероятностей +* поведение процесса +* частичный результат + +Поэтому первое проектное решение — не «какая структура должна это хранить?», а «в какой семантической области находятся интересующие нас значения?» + +## Семантические области {#semantic-domains} + +Для арифметических выражений простой областью могут быть целые числа: + +$$ \llbracket e \rrbracket_{eval} \in \mathbb{Z} $$ + +Для форматирования тот же язык выражений можно интерпретировать как текст: + +$$ \llbracket e \rrbracket_{pretty} \in \mathsf{String} $$ + +Для вычисления с эффектами областью может быть преобразование состояния: + +$$ \llbracket p \rrbracket : \mathsf{State} \to \mathsf{Result} \times \mathsf{State} $$ + +Для параллельного языка область может описывать наблюдаемое поведение процессов, а не одну заранее заданную трассу. + +Выбранная область определяет, какие различия имеют смысл. Если время не входит в область, две реализации с разным временем работы всё равно могут обозначать одну и ту же программу. Если в область включены затраты ресурсов, это различие уже может стать семантическим. + +## Абстракция намеренно отбрасывает детали {#abstraction-forgets-intentionally} + +Полезная денотация отбрасывает несущественные детали машины. + +Для позиции в ветвлении денотация может сохранять путь от корня, опуская при этом: + +* расположение байтов +* стратегию выделения памяти +* поведение кэша +* формат сериализации + +Для программы HTTP переносимая денотация может сохранять метод, путь, роли входных данных, операцию и роль результата, опуская конкретный маршрутизатор или исполнитель. + +Для этапа компилятора денотация может сохранять перевод нормализованного исходного текста в исполняемый смысл, опуская временные буферы и порядок обхода. + +Отбрасывание деталей — не недостаток. Благодаря ему разные представления могут быть эквивалентны. + +## Композиционность {#compositionality} + +Семантика **композиционна**, когда смысл целого определяется смыслами его частей и способом их объединения. + +Для сложения: + +$$ \llbracket a + b \rrbracket = \llbracket a \rrbracket + \llbracket b \rrbracket $$ + +Для последовательной композиции функций: + +$$ \llbracket g \circ f \rrbracket = \llbracket g \rrbracket \circ \llbracket f \rrbracket $$ + +Для оператора параллельного процесса семантической области нужна соответствующая параллельная композиция: + +$$ \llbracket P \mid Q \rrbracket = \llbracket P \rrbracket \otimes \llbracket Q \rrbracket $$ + +Точный оператор $\otimes$ зависит от выбранной модели процессов. Важно, что композиции синтаксиса систематически соответствуют семантическим композициям. + +Композиционность позволяет рассуждать локально. Если у двух частей одинаковая денотация, одну можно заменить другой внутри любого композиционного контекста: + +$$ \llbracket P \rrbracket = \llbracket Q \rrbracket \implies \llbracket C(P) \rrbracket = \llbracket C(Q) \rrbracket $$ + +На этом основаны безопасная подстановка и семантический рефакторинг. + +## Семантическое равенство {#semantic-equality} + +Чтобы быть семантически равными, программы не обязаны совпадать текстуально или операционно. + +Рассмотрим две реализации позиции в ветвлении: + +$$ \lbrack \mathsf{Left}, \mathsf{Right}, \mathsf{Left} \rbrack $$ + +и целочисленное представление, обозначающее тот же путь. Значения в памяти различаются, но их денотации могут быть равны. + +Точно так же два прохода компилятора могут обходить синтаксис в разном порядке, но создавать исполняемые файлы с одинаковым заданным поведением. Требование побайтового совпадения — отдельный, более сильный закон. + +Всегда уточняйте, о каком равенстве идёт речь: + +* равенство значений +* структурное равенство +* равенство канонических представлений +* эквивалентность трасс +* Бисимилярность +* контекстная эквивалентность +* денотационное равенство + +Смешение этих понятий — частый источник ошибочных законов. + +## Внешнее относительно границы {#externality-is-relative} + +Предположим, вычисление имеет такой смысл: + +$$ H \times E \to O $$ + +Относительно `H`, свидетельство `E` является внешним. Если новая абстракция выбирает `H × E` в качестве носителя, это свидетельство становится внутренним относительно новой границы. + +Это наблюдение важно для эффектов и контекста. Нет факта, который был бы «средовым» абсолютно. Важно, включает ли его текущий семантический носитель и какие законы им управляют. + +```admonish warning title="Не вводите универсальный объект контекста" +Не решайте вопрос о границах с помощью универсального объекта контекста. Явно называйте каждое допустимое значение — как возможность или отдельное значение. +``` + +## Примитивный и производный смысл {#primitive-and-derived-meaning} + +Примитивные операции образуют выбранный словарь семантической области. Производные операции определяются через них. + +Для позиции в ветвлении небольшой набор примитивов может включать: + +* Корневую позицию +* Продвижение в заданном направлении +* Наблюдение пути от одной позиции до другой + +Из них можно вывести: + +* Продвижение влево +* Продвижение вправо +* Построение по пути +* Проверка, является ли одна позиция предком другой +* Проверка, является ли одна позиция потомком другой + +Это различие — проектное решение, а не метафизический факт. Предпочитайте небольшой набор примитивов, с которым легко формулировать законы и альтернативные интерпретации. + +## Полезная проверка {#a-useful-test} + +Прежде чем вводить интерфейс программирования, закончите следующие фразы: + +* Значения этой абстракции означают… +* Первичные наблюдения — это… +* Значимые композиции — это… +* Два значения эквивалентны, если… +* Каждая реализация должна сохранять… +* Абстракция намеренно опускает… + +Если закончить эти фразы не получается, дополнительные механизмы реализации не восполнят недостающий смысл. diff --git a/src/denotational-design/denotations.uk.md b/src/denotational-design/denotations.uk.md new file mode 100644 index 0000000..3737ecf --- /dev/null +++ b/src/denotational-design/denotations.uk.md @@ -0,0 +1,162 @@ + + +# Денотації та композиційність {#denotations-and-compositionality} + +```admonish tip title="Пов’язані матеріали" +Семантичний погляд: [Чому значення має бути першим](semantic-view.md), [Денотаційне проєктування](design.md), [Закони та інтерпретації](laws-and-interpretations.md) +Проєктування від значення в Rust: [Алгебри можливостей](../rust-dd/capability-algebras.md) +Поняття: [Референційна прозорість](../concepts/referential_transparency.md), [Розгалуження та конфлюентність](../concepts/branching.md) +``` + +```admonish note title="Основна ідея" +Денотація — це функція значення, що відображає синтаксис у вибрану семантичну область. Семантика є композиційною, коли значення цілого визначається значеннями його частин; саме це робить можливими семантичну рівність і безпечну підстановку. +``` + +**Денотація** — це значення, яке надається фрагменту синтаксису чи програмній конструкції. Часто записують так: + +$$ \llbracket e \rrbracket $$ + +для «значення виразу `e`». + +Денотація не обов’язково має бути числом. Залежно від області програма може позначати: + +* значення +* функцію +* відношення +* множину можливих результатів +* перетворення стану +* розподіл імовірностей +* поведінку процесу +* частковий результат + +Отже, перше проєктне рішення — не «яка структура має це зберігати?», а «яка семантична область містить потрібні нам значення?» + +## Семантичні області {#semantic-domains} + +Для арифметичних виразів простою семантичною областю можуть бути цілі числа: + +$$ \llbracket e \rrbracket_{eval} \in \mathbb{Z} $$ + +Для форматування ту саму мову виразів можна інтерпретувати як текст: + +$$ \llbracket e \rrbracket_{pretty} \in \mathsf{String} $$ + +Для обчислення з ефектами областю може бути перетворення стану: + +$$ \llbracket p \rrbracket : \mathsf{State} \to \mathsf{Result} \times \mathsf{State} $$ + +Для паралельної мови область може описувати спостережувану поведінку процесу, а не одну наперед визначену трасу. + +Вибрана область визначає, які відмінності є значущими. Якщо часу немає в області, дві реалізації з різним часом виконання все одно можуть позначати ту саму програму. Якщо врахувати витрати ресурсів, ця ж відмінність може стати семантичною. + +## Абстракція навмисно забуває {#abstraction-forgets-intentionally} + +Корисна денотація відкидає несуттєві деталі машини. + +Для позиції в розгалуженні денотація може зберігати шлях від кореня, відкидаючи: + +* розташування байтів +* стратегію виділення пам’яті +* поведінку кешу +* формат серіалізації + +Для HTTP-програми переносна денотація може зберігати метод, шлях, ролі вхідних даних, операцію та роль вихідних даних, не зберігаючи інформацію про те, який маршрутизатор чи виконавець її обслуговуватиме. + +Для етапу компілятора денотація може зберігати перетворення нормалізованого коду на виконуване значення, не зберігаючи тимчасові буфери та порядок обходу. + +Забування — не вада. Саме воно робить рівноцінними альтернативні представлення. + +## Композиційність {#compositionality} + +Семантика є **композиційною**, коли значення цілого визначається значеннями його частин і способом їх поєднання. + +Для додавання: + +$$ \llbracket a + b \rrbracket = \llbracket a \rrbracket + \llbracket b \rrbracket $$ + +Для послідовної композиції функцій: + +$$ \llbracket g \circ f \rrbracket = \llbracket g \rrbracket \circ \llbracket f \rrbracket $$ + +Для оператора паралельного процесу семантична область має передбачати відповідну паралельну композицію: + +$$ \llbracket P \mid Q \rrbracket = \llbracket P \rrbracket \otimes \llbracket Q \rrbracket $$ + +Конкретний оператор $\otimes$ залежить від вибраної моделі процесів. Важливо, що композиція синтаксису систематично відображається в семантичну композицію. + +Композиційність дає змогу міркувати локально. Якщо дві частини мають однакову денотацію, одну можна замінити іншою в будь-якому композиційному контексті: + +$$ \llbracket P \rrbracket = \llbracket Q \rrbracket \implies \llbracket C(P) \rrbracket = \llbracket C(Q) \rrbracket $$ + +На цьому ґрунтуються безпечна підстановка та семантичний рефакторинг. + +## Семантична рівність {#semantic-equality} + +Програми не обов’язково мають бути текстово чи операційно тотожними, щоб бути семантично рівними. + +Розгляньмо дві реалізації позиції в розгалуженні: + +$$ \lbrack \mathsf{Left}, \mathsf{Right}, \mathsf{Left} \rbrack $$ + +і кодування цілим числом, яке позначає той самий шлях. Значення в пам’яті в них різні, але денотації можуть бути рівними. + +Так само два проходи компілятора можуть обходити синтаксис у різному порядку, але створювати виконувані файли з однаковою специфікованою поведінкою. Чи потрібна побайтова рівність — окремий, сильніший закон. + +Завжди уточнюйте, про яку саме рівність ідеться: + +* рівність значень +* структурна рівність +* рівність канонічних представлень +* еквівалентність трас +* бісимілярність +* спостережувана еквівалентність +* денотаційна рівність + +Плутанина між цими видами рівності часто призводить до хибних законів. + +## Зовнішність є відносною {#externality-is-relative} + +Припустімо, обчислення має значення: + +$$ H \times E \to O $$ + +Відносно `H` свідчення `E` є зовнішнім. Якщо нова абстракція вибирає `H × E` як носій, це свідчення стає внутрішнім для нової межі. + +Це спостереження важливе для ефектів і контексту. Жоден факт не є абсолютно «зовнішнім щодо середовища». Питання в тому, чи містить поточний семантичний носій цей факт і які закони ним керують. + +```admonish warning title="Уникайте універсального об’єкта контексту" +Не розв’язуйте це питання меж за допомогою універсального об’єкта контексту. Називайте кожне допустиме значення окремою можливістю або явним значенням. +``` + +## Примітивне й похідне значення {#primitive-and-derived-meaning} + +Примітивні операції утворюють термінологію, вибрану для семантичної області. Похідні операції визначаються на їх основі. + +Для позицій у розгалуженні невелика множина примітивних понять може включати: + +* Кореневу позицію +* Розширення в заданому напрямку +* Спостереження шляху від однієї позиції до іншої + +Тоді можна вивести: + +* Розширення ліворуч +* Розширення праворуч +* Конструювання за шляхом +* Перевірку, чи є одна позиція предком іншої +* Перевірку, чи є одна позиція нащадком іншої + +Це розрізнення є проєктним рішенням, а не метафізичним фактом. Віддавайте перевагу невеликому набору примітивів, із яким легко формулювати закони й альтернативні інтерпретації. + +## Корисна перевірка {#a-useful-test} + +Перш ніж створювати програмний інтерфейс, завершіть ці речення: + +* Значення цієї абстракції означають ... +* Примітивні спостереження — це ... +* Значущі композиції — це ... +* Два значення є еквівалентними, коли ... +* Кожна реалізація має зберігати ... +* Абстракція навмисно відкидає ... + +Якщо ці речення неможливо завершити, додаткові механізми реалізації не заповнять прогалину у визначенні значення. diff --git a/src/denotational-design/denotations.vi.md b/src/denotational-design/denotations.vi.md new file mode 100644 index 0000000..590917e --- /dev/null +++ b/src/denotational-design/denotations.vi.md @@ -0,0 +1,162 @@ + + +# Ngữ nghĩa chỉ định và tính hợp thành {#denotations-and-compositionality} + +```admonish tip title="Liên quan" +Góc nhìn ngữ nghĩa: [Vì sao ý nghĩa được đặt lên trước](semantic-view.md), [Thiết kế theo ngữ nghĩa](design.md), [Định luật và cách diễn giải](laws-and-interpretations.md) +Thiết kế theo ngữ nghĩa trong Rust: [Các đại số năng lực](../rust-dd/capability-algebras.md) +Khái niệm: [Tính minh bạch tham chiếu](../concepts/referential_transparency.md), [Phân nhánh và hội tụ](../concepts/branching.md) +``` + +```admonish note title="Ý tưởng cốt lõi" +Ngữ nghĩa chỉ định là một hàm ý nghĩa từ cú pháp sang miền ngữ nghĩa được chọn. Ngữ nghĩa có tính hợp thành khi ý nghĩa của toàn thể được xác định bởi ý nghĩa các phần, nhờ đó có thể xác lập đẳng thức ngữ nghĩa và phép thay thế an toàn. +``` + +**Ngữ nghĩa chỉ định** là ý nghĩa được gán cho một đoạn cú pháp hoặc cấu trúc lập trình. Ta thường viết: + +$$ \llbracket e \rrbracket $$ + +để chỉ “ý nghĩa của biểu thức `e`”. + +Ký hiệu ngoặc không bắt buộc ngữ nghĩa chỉ định phải là một số. Tùy miền, chương trình có thể biểu thị: + +* một giá trị +* một hàm +* một quan hệ +* một tập hợp kết quả có thể có +* một phép biến đổi trạng thái +* một phân phối xác suất +* hành vi của một tiến trình +* một kết quả từng phần + +Vì vậy, quyết định thiết kế đầu tiên không phải là “cấu trúc nào nên chứa nó?” mà là “miền ngữ nghĩa nào chứa các ý nghĩa ta quan tâm?” + +## Miền ngữ nghĩa {#semantic-domains} + +Với biểu thức số học, miền đơn giản có thể là các số nguyên: + +$$ \llbracket e \rrbracket_{eval} \in \mathbb{Z} $$ + +Với việc định dạng, cùng ngôn ngữ biểu thức đó có thể được diễn giải thành văn bản: + +$$ \llbracket e \rrbracket_{pretty} \in \mathsf{String} $$ + +Với phép tính có hiệu ứng, miền có thể là một phép biến đổi trạng thái: + +$$ \llbracket p \rrbracket : \mathsf{State} \to \mathsf{Result} \times \mathsf{State} $$ + +Với ngôn ngữ đồng thời, miền có thể mô tả hành vi tiến trình quan sát được thay vì một vết thực thi định trước. + +Miền được chọn quyết định những khác biệt nào có ý nghĩa. Nếu thời gian không có trong miền, hai cách triển khai có thời gian chạy khác nhau vẫn có thể biểu thị cùng một chương trình. Nếu mức tiêu thụ tài nguyên được đưa vào, chính khác biệt đó có thể trở thành khác biệt ngữ nghĩa. + +## Trừu tượng hóa là chủ ý quên đi {#abstraction-forgets-intentionally} + +Một ngữ nghĩa chỉ định hữu ích sẽ lược bỏ chi tiết máy không liên quan. + +Với một vị trí nhánh, ngữ nghĩa chỉ định có thể giữ lại đường đi từ gốc, đồng thời lược bỏ: + +* bố cục byte +* chiến lược cấp phát +* hành vi bộ nhớ đệm +* định dạng tuần tự hóa + +Với chương trình HTTP, ngữ nghĩa chỉ định khả chuyển có thể giữ lại phương thức, đường dẫn, vai trò đầu vào, phép toán và vai trò đầu ra, đồng thời lược bỏ bộ định tuyến hoặc bộ thực thi nào sẽ lưu trữ nó. + +Với một giai đoạn trình biên dịch, ngữ nghĩa chỉ định có thể giữ phép dịch từ mã nguồn chuẩn hóa sang ý nghĩa thực thi, đồng thời lược bỏ các bộ đệm tạm và thứ tự duyệt. + +Lược bỏ không phải là khiếm khuyết. Chính điều đó khiến các cách biểu diễn khác nhau có thể tương đương. + +## Tính hợp thành {#compositionality} + +Ngữ nghĩa có tính **hợp thành** khi ý nghĩa của toàn thể được xác định bởi ý nghĩa các phần và cách kết hợp chúng. + +Với phép cộng: + +$$ \llbracket a + b \rrbracket = \llbracket a \rrbracket + \llbracket b \rrbracket $$ + +Với phép hợp thành hàm tuần tự: + +$$ \llbracket g \circ f \rrbracket = \llbracket g \rrbracket \circ \llbracket f \rrbracket $$ + +Với toán tử tiến trình song song, miền ngữ nghĩa cần có phép hợp thành song song tương ứng: + +$$ \llbracket P \mid Q \rrbracket = \llbracket P \rrbracket \otimes \llbracket Q \rrbracket $$ + +Toán tử chính xác $\otimes$ phụ thuộc vào mô hình tiến trình được chọn. Điểm quan trọng là phép hợp thành cú pháp được ánh xạ một cách có hệ thống sang phép hợp thành ngữ nghĩa. + +Tính hợp thành cho phép suy luận cục bộ. Nếu hai phần có cùng ngữ nghĩa chỉ định, có thể thay phần này bằng phần kia trong mọi ngữ cảnh hợp thành: + +$$ \llbracket P \rrbracket = \llbracket Q \rrbracket \implies \llbracket C(P) \rrbracket = \llbracket C(Q) \rrbracket $$ + +Đây là nền tảng cho phép thay thế an toàn và tái cấu trúc ngữ nghĩa. + +## Đẳng thức ngữ nghĩa {#semantic-equality} + +Các chương trình không cần giống nhau về văn bản hay cách vận hành để tương đương về ngữ nghĩa. + +Hãy xét hai cách triển khai vị trí nhánh: + +$$ \lbrack \mathsf{Left}, \mathsf{Right}, \mathsf{Left} \rbrack $$ + +và một cách mã hóa bằng số nguyên biểu thị cùng đường đi. Giá trị bộ nhớ của chúng khác nhau, nhưng ngữ nghĩa chỉ định của chúng có thể bằng nhau. + +Tương tự, hai lượt của trình biên dịch có thể duyệt cú pháp theo thứ tự khác nhau nhưng tạo ra các tệp thực thi có hành vi như nhau theo đặc tả. Việc có yêu cầu chúng giống hệt từng byte hay không là một định luật riêng, mạnh hơn. + +Luôn nêu rõ loại đẳng thức đang được khẳng định: + +* đẳng thức giá trị +* đẳng thức cấu trúc +* đẳng thức biểu diễn chuẩn tắc +* tương đương vết thực thi +* tính mô phỏng song hành +* tương đương quan sát +* đẳng thức ngữ nghĩa chỉ định + +Nhầm lẫn những đẳng thức này là nguyên nhân phổ biến dẫn đến các định luật sai. + +## Tính ngoại tại phụ thuộc tương quan {#externality-is-relative} + +Giả sử một phép tính có ý nghĩa như sau: + +$$ H \times E \to O $$ + +Xét theo `H`, bằng chứng `E` là bên ngoài. Nếu một lớp trừu tượng mới chọn `H × E` làm đối tượng mang, bằng chứng ấy trở thành nội tại trong ranh giới mới. + +Nhận xét này quan trọng đối với hiệu ứng và ngữ cảnh. Không có sự kiện nào “thuộc môi trường” một cách tuyệt đối. Cần hỏi đối tượng mang ngữ nghĩa hiện tại có bao gồm nó không và những định luật nào chi phối nó. + +```admonish warning title="Tránh một đối tượng ngữ cảnh toàn năng" +Đừng giải quyết câu hỏi về ranh giới này bằng một đối tượng ngữ cảnh toàn năng. Hãy nêu rõ từng ý nghĩa được chấp nhận dưới dạng năng lực hoặc giá trị tường minh. +``` + +## Ý nghĩa nguyên thủy và ý nghĩa suy ra {#primitive-and-derived-meaning} + +Các phép toán nguyên thủy là từ vựng được chọn cho miền ngữ nghĩa. Các phép toán suy ra được định nghĩa từ chúng. + +Với vị trí nhánh, một tập từ vựng nguyên thủy gọn có thể gồm: + +* Một vị trí gốc +* Mở rộng theo một hướng +* Quan sát đường đi từ vị trí này đến vị trí khác + +Sau đó có thể suy ra: + +* Mở rộng sang trái +* Mở rộng sang phải +* Tạo từ một đường đi +* Kiểm tra xem một vị trí có phải tổ tiên của vị trí khác không +* Kiểm tra xem một vị trí có phải hậu duệ của vị trí khác không + +Sự phân biệt này là lựa chọn thiết kế, không phải sự thật siêu hình. Hãy ưu tiên tập nguyên thủy nhỏ giúp phát biểu định luật và các cách diễn giải khác dễ dàng. + +## Một phép thử hữu ích {#a-useful-test} + +Trước khi đưa vào giao diện lập trình, hãy hoàn thành các câu sau: + +* Các giá trị của lớp trừu tượng này có ý nghĩa là ... +* Các quan sát nguyên thủy là ... +* Các phép hợp thành có ý nghĩa là ... +* Hai giá trị tương đương khi ... +* Mọi cách triển khai phải bảo toàn ... +* Lớp trừu tượng này chủ ý lược bỏ ... + +Nếu không thể hoàn thành các câu này, thêm cơ chế triển khai sẽ không bù đắp được ý nghĩa còn thiếu. diff --git a/src/denotational-design/denotations.zh-hant.md b/src/denotational-design/denotations.zh-hant.md new file mode 100644 index 0000000..478fade --- /dev/null +++ b/src/denotational-design/denotations.zh-hant.md @@ -0,0 +1,162 @@ + + +# 指稱與組合性 {#denotations-and-compositionality} + +```admonish tip title="相關內容" +語義視角:[為何含義優先](semantic-view.md)、[指稱設計](design.md)、[定律與解釋](laws-and-interpretations.md) +Rust 中的語義驅動設計:[能力代數](../rust-dd/capability-algebras.md) +概念:[引用透明性](../concepts/referential_transparency.md)、[分支與合流](../concepts/branching.md) +``` + +```admonish note title="核心思想" +指稱是從語法對映到所選語義域的含義函式。當整體的含義由各部分的含義確定時,語義就是組合式的;這使語義等價與安全替換成為可能。 +``` + +**指稱**是賦予一段語法或一個程式設計構造的含義。通常記作: + +$$ \llbracket e \rrbracket $$ + +表示“表示式`e`的含義”。 + +這些括號並不要求指稱必須是一個數字。根據所選語義域,程式可以指稱: + +* 一個值 +* 一個函式 +* 一個關係 +* 一組可能結果 +* 一個狀態變換 +* 一個機率分佈 +* 一種過程行為 +* 一個部分結果 + +因此,第一個設計決策不是“用哪個結構體來儲存它?”,而是“我們關心的含義屬於哪個語義域?” + +## 語義域 {#semantic-domains} + +對於算術表示式,一個簡單的語義域可以是整數: + +$$ \llbracket e \rrbracket_{eval} \in \mathbb{Z} $$ + +對於格式化,同一種表示式語言也可以解釋為文字: + +$$ \llbracket e \rrbracket_{pretty} \in \mathsf{String} $$ + +對於帶效應的計算,語義域可以是狀態變換: + +$$ \llbracket p \rrbracket : \mathsf{State} \to \mathsf{Result} \times \mathsf{State} $$ + +對於併發語言,語義域可以描述可觀察到的過程行為,而非某一條預先確定的軌跡。 + +所選語義域決定哪些差異有意義。如果語義域不包含時間,那麼兩個時序不同的實作仍可能指稱同一個程式。如果把資源消耗納入語義域,這種差異就可能具有語義意義。 + +## 抽象會有意忽略細節 {#abstraction-forgets-intentionally} + +有用的指稱會忽略無關的機器細節。 + +對於分支位置,指稱可以保留從根到該位置的路徑,同時忽略: + +* 位元組佈局 +* 分配策略 +* 快取行為 +* 序列化格式 + +對於 HTTP 程式,可移植的指稱可以保留方法、路徑、輸入角色、操作和輸出角色,同時忽略承載它的路由器或執行器。 + +對於編譯器階段,指稱可以保留從正規化原始碼到可執行含義的轉換,同時忽略臨時緩衝區與遍歷順序。 + +忽略細節不是缺陷。正是如此,不同表示才可能等價。 + +## 組合性 {#compositionality} + +當整體的含義由各部分的含義及其組合方式共同決定時,語義就是**組合式的**。 + +對於加法: + +$$ \llbracket a + b \rrbracket = \llbracket a \rrbracket + \llbracket b \rrbracket $$ + +對於順序函式組合: + +$$ \llbracket g \circ f \rrbracket = \llbracket g \rrbracket \circ \llbracket f \rrbracket $$ + +對於並行過程運算子,語義域需要相應的並行組合: + +$$ \llbracket P \mid Q \rrbracket = \llbracket P \rrbracket \otimes \llbracket Q \rrbracket $$ + +具體運算子$\otimes$取決於所選的過程模型。關鍵在於,語法組合應系統地對映到語義組合。 + +組合性支援區域性推理。如果兩個部分的指稱相同,就可以在任意組合上下文中相互替換: + +$$ \llbracket P \rrbracket = \llbracket Q \rrbracket \implies \llbracket C(P) \rrbracket = \llbracket C(Q) \rrbracket $$ + +這是安全替換與語義重構的基礎。 + +## 語義等價 {#semantic-equality} + +程式不必在文字或操作上完全相同,才能在語義上等價。 + +考慮分支位置的兩種實作: + +$$ \lbrack \mathsf{Left}, \mathsf{Right}, \mathsf{Left} \rbrack $$ + +以及一種指稱相同路徑的整數編碼。它們的記憶體值不同,但指稱可能相等。 + +同樣,兩個編譯器過程可以按不同順序遍歷語法,卻生成行為符合相同規範的可執行檔案。是否要求逐位元組相等,是另一個更強的定律。 + +務必明確指出所聲稱的等價關係: + +* 值相等 +* 結構相等 +* 規範表示相等 +* 軌跡等價 +* 雙模擬 +* 觀察等價 +* 指稱相等 + +混淆這些等價關係,是錯誤定律的常見來源。 + +## 外部性是相對的 {#externality-is-relative} + +假設某個計算具有如下含義: + +$$ H \times E \to O $$ + +相對於`H`而言,證據`E`是外部的。如果新的抽象選擇`H × E`作為承載物件,那麼這些證據對於新的邊界來說就變成內部的。 + +這一觀察對效應與上下文都很重要。沒有任何事實絕對屬於“環境”。關鍵在於當前語義承載物件是否包含該事實,以及有哪些定律支配它。 + +```admonish warning title="避免使用通用上下文物件" +不要用一個通用上下文物件來解決這個邊界問題。將每種允許的含義明確命名為一種能力或顯式值。 +``` + +## 基本含義與派生含義 {#primitive-and-derived-meaning} + +基本操作是選作語義域詞彙的操作。派生操作則由基本操作定義。 + +對於分支位置,一組精簡的基本詞彙可以包括: + +* 一個根位置 +* 沿某個方向延伸 +* 觀察一個位置到另一個位置的路徑 + +由此可以派生: + +* 向左延伸 +* 向右延伸 +* 根據路徑構造位置 +* 測試一個位置是否為另一個位置的祖先 +* 測試一個位置是否為另一個位置的後代 + +這種區分是設計選擇,而非形而上學事實。應優先採用精簡的基本操作集合,讓定律與其他解釋更容易表述。 + +## 一項實用檢驗 {#a-useful-test} + +在引入程式設計介面之前,先補全以下句子: + +* 這個抽象中的值意味著…… +* 基本觀察包括…… +* 有意義的組合包括…… +* 當……時,兩個值等價 +* 每種實作都必須保留…… +* 該抽象有意忽略…… + +如果這些句子無法補全,再多的實作機制也無法補上缺失的含義。 diff --git a/src/denotational-design/denotations.zh.md b/src/denotational-design/denotations.zh.md new file mode 100644 index 0000000..48f5f78 --- /dev/null +++ b/src/denotational-design/denotations.zh.md @@ -0,0 +1,162 @@ + + +# 指称与组合性 {#denotations-and-compositionality} + +```admonish tip title="相关内容" +语义视角:[为何含义优先](semantic-view.md)、[指称设计](design.md)、[定律与解释](laws-and-interpretations.md) +Rust 中的语义驱动设计:[能力代数](../rust-dd/capability-algebras.md) +概念:[引用透明性](../concepts/referential_transparency.md)、[分支与合流](../concepts/branching.md) +``` + +```admonish note title="核心思想" +指称是从语法映射到所选语义域的含义函数。当整体的含义由各部分的含义确定时,语义就是组合式的;这使语义等价与安全替换成为可能。 +``` + +**指称**是赋予一段语法或一个编程构造的含义。通常记作: + +$$ \llbracket e \rrbracket $$ + +表示“表达式`e`的含义”。 + +这些括号并不要求指称必须是一个数字。根据所选语义域,程序可以指称: + +* 一个值 +* 一个函数 +* 一个关系 +* 一组可能结果 +* 一个状态变换 +* 一个概率分布 +* 一种过程行为 +* 一个部分结果 + +因此,第一个设计决策不是“用哪个结构体来保存它?”,而是“我们关心的含义属于哪个语义域?” + +## 语义域 {#semantic-domains} + +对于算术表达式,一个简单的语义域可以是整数: + +$$ \llbracket e \rrbracket_{eval} \in \mathbb{Z} $$ + +对于格式化,同一种表达式语言也可以解释为文本: + +$$ \llbracket e \rrbracket_{pretty} \in \mathsf{String} $$ + +对于带效应的计算,语义域可以是状态变换: + +$$ \llbracket p \rrbracket : \mathsf{State} \to \mathsf{Result} \times \mathsf{State} $$ + +对于并发语言,语义域可以描述可观察到的过程行为,而非某一条预先确定的轨迹。 + +所选语义域决定哪些差异有意义。如果语义域不包含时间,那么两个时序不同的实现仍可能指称同一个程序。如果把资源消耗纳入语义域,这种差异就可能具有语义意义。 + +## 抽象会有意忽略细节 {#abstraction-forgets-intentionally} + +有用的指称会忽略无关的机器细节。 + +对于分支位置,指称可以保留从根到该位置的路径,同时忽略: + +* 字节布局 +* 分配策略 +* 缓存行为 +* 序列化格式 + +对于 HTTP 程序,可移植的指称可以保留方法、路径、输入角色、操作和输出角色,同时忽略承载它的路由器或执行器。 + +对于编译器阶段,指称可以保留从规范化源代码到可执行含义的转换,同时忽略临时缓冲区与遍历顺序。 + +忽略细节不是缺陷。正是如此,不同表示才可能等价。 + +## 组合性 {#compositionality} + +当整体的含义由各部分的含义及其组合方式共同决定时,语义就是**组合式的**。 + +对于加法: + +$$ \llbracket a + b \rrbracket = \llbracket a \rrbracket + \llbracket b \rrbracket $$ + +对于顺序函数组合: + +$$ \llbracket g \circ f \rrbracket = \llbracket g \rrbracket \circ \llbracket f \rrbracket $$ + +对于并行过程运算符,语义域需要相应的并行组合: + +$$ \llbracket P \mid Q \rrbracket = \llbracket P \rrbracket \otimes \llbracket Q \rrbracket $$ + +具体运算符$\otimes$取决于所选的过程模型。关键在于,语法组合应系统地映射到语义组合。 + +组合性支持局部推理。如果两个部分的指称相同,就可以在任意组合上下文中相互替换: + +$$ \llbracket P \rrbracket = \llbracket Q \rrbracket \implies \llbracket C(P) \rrbracket = \llbracket C(Q) \rrbracket $$ + +这是安全替换与语义重构的基础。 + +## 语义等价 {#semantic-equality} + +程序不必在文本或操作上完全相同,才能在语义上等价。 + +考虑分支位置的两种实现: + +$$ \lbrack \mathsf{Left}, \mathsf{Right}, \mathsf{Left} \rbrack $$ + +以及一种指称相同路径的整数编码。它们的内存值不同,但指称可能相等。 + +同样,两个编译器过程可以按不同顺序遍历语法,却生成行为符合相同规范的可执行文件。是否要求逐字节相等,是另一个更强的定律。 + +务必明确指出所声称的等价关系: + +* 值相等 +* 结构相等 +* 规范表示相等 +* 轨迹等价 +* 双模拟 +* 观察等价 +* 指称相等 + +混淆这些等价关系,是错误定律的常见来源。 + +## 外部性是相对的 {#externality-is-relative} + +假设某个计算具有如下含义: + +$$ H \times E \to O $$ + +相对于`H`而言,证据`E`是外部的。如果新的抽象选择`H × E`作为承载对象,那么这些证据对于新的边界来说就变成内部的。 + +这一观察对效应与上下文都很重要。没有任何事实绝对属于“环境”。关键在于当前语义承载对象是否包含该事实,以及有哪些定律支配它。 + +```admonish warning title="避免使用通用上下文对象" +不要用一个通用上下文对象来解决这个边界问题。将每种允许的含义明确命名为一种能力或显式值。 +``` + +## 基本含义与派生含义 {#primitive-and-derived-meaning} + +基本操作是选作语义域词汇的操作。派生操作则由基本操作定义。 + +对于分支位置,一组精简的基本词汇可以包括: + +* 一个根位置 +* 沿某个方向延伸 +* 观察一个位置到另一个位置的路径 + +由此可以派生: + +* 向左延伸 +* 向右延伸 +* 根据路径构造位置 +* 测试一个位置是否为另一个位置的祖先 +* 测试一个位置是否为另一个位置的后代 + +这种区分是设计选择,而非形而上学事实。应优先采用精简的基本操作集合,让定律与其他解释更容易表述。 + +## 一项实用检验 {#a-useful-test} + +在引入编程接口之前,先补全以下句子: + +* 这个抽象中的值意味着…… +* 基本观察包括…… +* 有意义的组合包括…… +* 当……时,两个值等价 +* 每种实现都必须保留…… +* 该抽象有意忽略…… + +如果这些句子无法补全,再多的实现机制也无法补上缺失的含义。 diff --git a/src/denotational-design/dependent-types.ar.md b/src/denotational-design/dependent-types.ar.md new file mode 100644 index 0000000..e8a96ef --- /dev/null +++ b/src/denotational-design/dependent-types.ar.md @@ -0,0 +1,80 @@ + + +# الأنواع التابعة والبراهين {#dependent-types-and-proofs} + +```admonish tip title="ذات صلة" +المنظور الدلالي: [التصميم الدلالي (Denotational Design)](design.md)، [القوانين والتفسيرات](laws-and-interpretations.md) +التصميم انطلاقًا من المعنى في Rust: [الأنواع الدلالية في Rust](../rust-dd/semantic-types.md)، [القوانين والسيناريوهات والأدلة](../rust-dd/laws.md) +``` + +```admonish note title="الموضع الدلالي" +تعبر الأنواع التابعة عن قضايا وأدلة مفهرسة بالقيم ضمن نظام الأنواع. ويمكنها ترميز جزء من المواصفة الدلالية، لكنها لا تختار تلك المواصفة؛ إذ يجب أن تتضح الخاصية المقصودة قبل تحويلها إلى نوع. +``` + +## أنواع مفهرسة بالقيم {#types-indexed-by-values} + +يكون النوع *تابعًا* عندما يمكن أن يعتمد على قيمة. لذا يستطيع النوع التابع وصف شكل القيمة والعلاقة التي يجب أن تحققها أيضًا. + +من الأمثلة: + +* `Vec` — متجه مفهرس بطوله `n` +* `Matrix` — مصفوفة مفهرسة بأبعادها +* `Proof

` — دليل على قضية `p` + +على سبيل المثال: + +```hs +append : Vec -> Vec -> Vec +``` + +يصرح نوع النتيجة بأن إلحاق متجهين طولهما `n` و`m` ينتج متجهًا طوله `n + m`. + +## الدوال التابعة {#dependent-functions} + +يُكتب نوع الدالة التابعة هكذا: + +$$ \Pi (x : A).\,B(x) $$ + +لكل قيمة $x$ من النوع $A$، تكون النتيجة من النوع $B(x)$. قارن: + +$$ \begin{aligned} f &\colon A \to B \\ g &\colon (x : A) \to B(x) \end{aligned} $$ + +نوع نتيجة $f$ ثابت. أما نوع نتيجة $g$ فقد يتغير بحسب مدخلها. + +وفقًا لمقابلة القضايا بالأنواع، يمكن للنوع أن يصرح بقضية، ويكون المصطلح الذي ينتمي إلى ذلك النوع بمثابة برهانها. وهذا يدعم واجهات API لا يمكن فيها إنشاء حالات أو انتقالات أو تركيبات غير صالحة. + +## العلاقة بالتصميم الدلالي {#relationship-to-denotational-design} + +يسأل التصميم الدلالي أولًا: + +1. ما المجال الدلالي؟ +2. ما الملاحظات والتركيبات المهمة؟ +3. ما القوانين التي يجب أن تصح؟ + +يمكن للأنواع التابعة بعد ذلك استيعاب بعض تلك الإجابات داخليًا. فقد يسجل فهرس النوع طول متجه أو حالة بروتوكول أو عمق مكدس أو حدًا للموارد أو برهانًا على أن إنشاءين يدلان على النتيجة نفسها. + +الترتيب مهم. لا يوفّر النوع المتطور معنى مفقودًا. ولا يقوّي المواصفة إلا إذا كانت القضية المفهرسة تصف بالفعل فرقًا دلاليًا مقصودًا أو ثابتًا تمثيليًا مختارًا عمدًا. + +```admonish warning title="لا تخلط بين القضايا الدلالية والثوابت التمثيلية" +يمكن ترميز كليهما في الأنواع، لكن سلطتهما مختلفة. يجب على كل مفسر متوافق الحفاظ على القضية الدلالية. أما الثابت التمثيلي فلا يقيّد سوى التمثيل الذي اختاره. +``` + +## البراهين والأدلة القابلة للتنفيذ {#proofs-and-executable-evidence} + +يثبت البرهان قضية في ظل افتراضات معلنة. وتقدم اختبارات الخصائص والسيناريوهات واختبارات الوحدة أدلة تنفيذية محدودة. وقد يتيح ترميز قضية بنوع تابع لفحص الأنواع أن يتحقق من حد البرهان، لكنه لا يحوّل الاختبار إلى برهان ولا يجعل المترجم مصدر القضية. + +هذا هو الفصل نفسه المعتمد في الكتاب كله: يحدد المعنى والقوانين الالتزام، وتتحقق الأدوات منه أو تحققه. + +## تطبيق النموذج في Rust {#applying-the-model-in-rust} + +ليست Rust لغة ذات أنواع تابعة بالكامل، لكن المعممات الثابتة وtypestate والأنواع المرتبطة وحدود السمات يمكنها التعبير عن علاقات مفهرسة مفيدة. تنقل هذه الترميزات الفحوص إلى وقت الترجمة، وغالبًا ما تحافظ على التمثيلات الملموسة الكفؤة. + +يبقى التصور الموجّه نحو البرهان قيّمًا حتى حين تعجز Rust عن التعبير عن القضية كاملة. صرّح بالثابت بوضوح، ورمّز الجزء الذي يستطيع نظام الأنواع فرضه، واحتفظ بالقوانين أو الاختبارات للباقي. يخدم الترميز المواصفة ولا يحل محلها. + +```admonish example title="شبكة مفهرسة بموضعها" +يُجسّد [`typed-grid-rs`](https://github.com/tgrospic/typed-grid-rs) الفكرة `Matrix` أعلاه في Rust المستقرة. تصبح كل خلية نوعًا مفهرسًا بإحداثياتها، مثل `Pos0x0` و`Pos1x2`، وتعيد الحركة نوع موضع *مختلفًا*: + +يدل `Pos0x0.right()` على `Pos1x0`؛ وتجاوز الحافة ليس خطأ وقت التشغيل، بل برنامجًا لا يجتاز فحص الأنواع لأن الحركة المقابلة لا تُولَّد عند الحد. + +هذا هو الرفع نفسه الذي يصفه القسم: يُرقّى الإحداثي الذي كان سيعيش في عالم القيم إلى النوع، ويصبح التنقل الصالح دالة تامة يُتحقق منها وقت الترجمة. أنواع العلامات بلا حجم، لذا لا تكلف القضية المفهرسة شيئًا وقت التشغيل. +``` diff --git a/src/denotational-design/dependent-types.de.md b/src/denotational-design/dependent-types.de.md new file mode 100644 index 0000000..1e624b9 --- /dev/null +++ b/src/denotational-design/dependent-types.de.md @@ -0,0 +1,80 @@ + + +# Abhängige Typen und Beweise {#dependent-types-and-proofs} + +```admonish tip title="Verwandte Themen" +The Semantic View: [Denotational Design](design.md), [Gesetze und Interpretationen](laws-and-interpretations.md) +Design by Meaning in Rust: [Semantische Typen in Rust](../rust-dd/semantic-types.md), [Gesetze, Szenarien und Nachweise](../rust-dd/laws.md) +``` + +```admonish note title="Semantische Einordnung" +Abhängige Typen drücken wertindizierte Aussagen und Nachweise in einem Typsystem aus. Sie können Teile einer semantischen Spezifikation kodieren, wählen diese Spezifikation aber nicht aus: Die beabsichtigte Eigenschaft muss klar sein, bevor sie in einen Typ übertragen wird. +``` + +## Typen mit Wertindizes {#types-indexed-by-values} + +Ein Typ ist *abhängig*, wenn er von einem Wert abhängen kann. Ein abhängiger Typ kann daher nicht nur die Form eines Werts beschreiben, sondern auch eine Beziehung, die dieser Wert erfüllen muss. + +Beispiele dafür sind: + +* `Vec` — ein Vektor, dessen Länge als Index dient `n` +* `Matrix` — eine Matrix, deren Dimensionen als Indizes dienen +* `Proof

` — ein Nachweis für eine Aussage `p` + +Zum Beispiel: + +```hs +append : Vec -> Vec -> Vec +``` + +Der Ergebnistyp besagt, dass beim Anhängen von Vektoren der Längen `n` und `m` ein Vektor der Länge `n + m` entsteht. + +## Abhängige Funktionen {#dependent-functions} + +Ein abhängiger Funktionstyp wird so geschrieben: + +$$ \Pi (x : A).\,B(x) $$ + +Für jeden Wert $x$ vom Typ $A$ hat das Ergebnis den Typ $B(x)$. Vergleiche: + +$$ \begin{aligned} f &\colon A \to B \\ g &\colon (x : A) \to B(x) \end{aligned} $$ + +Der Ergebnistyp von $f$ ist fest. Der Ergebnistyp von $g$ kann sich mit der Eingabe ändern. + +Im Rahmen der Entsprechung zwischen Aussagen und Typen kann ein Typ eine Aussage formulieren, und ein Term dieses Typs kann als ihr Beweis dienen. Das ermöglicht APIs, in denen ungültige Zustände, Übergänge oder Kompositionen nicht konstruiert werden können. + +## Beziehung zu Denotational Design {#relationship-to-denotational-design} + +Denotational Design fragt zuerst: + +1. Was ist der semantische Bereich? +2. Welche Beobachtungen und Kompositionen sind wichtig? +3. Welche Gesetze müssen gelten? + +Abhängige Typen können einige dieser Antworten anschließend internalisieren. Ein Typindex kann die Länge eines Vektors, einen Protokollzustand, eine Stapeltiefe, eine Ressourcengrenze oder den Beweis festhalten, dass zwei Konstruktionen dasselbe Ergebnis bezeichnen. + +Die Reihenfolge ist wichtig. Ein anspruchsvoller Typ liefert keine fehlende Bedeutung. Er stärkt eine Spezifikation nur dann, wenn die indizierte Aussage bereits eine beabsichtigte semantische Unterscheidung oder eine bewusst gewählte Repräsentationsinvariante beschreibt. + +```admonish warning title="Semantische Aussagen nicht mit Repräsentationsinvarianten verwechseln" +Beides lässt sich in Typen kodieren, besitzt aber unterschiedliche Geltung. Jede kompatible Interpretation muss eine semantische Aussage bewahren. Eine Repräsentationsinvariante beschränkt nur die Repräsentation, für die sie festgelegt wurde. +``` + +## Beweise und ausführbare Nachweise {#proofs-and-executable-evidence} + +Ein Beweis zeigt eine Aussage unter den genannten Annahmen. Eigenschafts-, Szenario- und Unit-Tests liefern endliche ausführbare Nachweise. Wird eine Aussage in einem abhängigen Typ kodiert, kann die Typprüfung einen Beweisterm verifizieren; dadurch werden Tests aber nicht zu Beweisen, und der Compiler wird nicht zur Quelle der Aussage. + +Hier gilt dieselbe Trennung wie im ganzen Buch: Bedeutung und Gesetze formulieren die Verpflichtung; Werkzeuge prüfen sie oder setzen sie um. + +## Das Modell in Rust anwenden {#applying-the-model-in-rust} + +Rust ist keine vollständig abhängig typisierte Sprache, doch Const Generics, Typzustände, assoziierte Typen und Trait Bounds können nützliche indexierte Beziehungen ausdrücken. Solche Kodierungen können Prüfungen zur Compile-Zeit verlagern und oft effiziente konkrete Repräsentationen bewahren. + +Das beweisorientierte Denkmodell bleibt wertvoll, auch wenn Rust die vollständige Aussage nicht ausdrücken kann. Formuliere die Invariante ausdrücklich, kodiere den Teil, den das Typsystem erzwingen kann, und sichere den Rest durch Gesetze oder Tests ab. Die Kodierung dient der Spezifikation; sie ersetzt sie nicht. + +```admonish example title="Ein nach Position indiziertes Gitter" +[`typed-grid-rs`](https://github.com/tgrospic/typed-grid-rs) setzt die oben beschriebene `Matrix` Idee in stabilem Rust um. Jede Zelle wird zu einem Typ, der durch ihre Koordinate indiziert ist — `Pos0x0`, `Pos1x2` und so weiter —, und ein Zug gibt einen *anderen* Positionstyp zurück: + +`Pos0x0.right()` bezeichnet `Pos1x0`; ein Schritt über den Rand ist kein Laufzeitfehler, sondern ein Programm, das die Typprüfung nicht besteht, weil der entsprechende Zug am Rand nie erzeugt wird. + +Dies ist dieselbe Anhebung, die der Abschnitt beschreibt: Die Koordinate, die sonst in der Wertebene läge, wird in den Typ übernommen, und gültige Navigation wird zu einer totalen, zur Compile-Zeit geprüften Funktion. Die Markertypen sind größenlos, daher verursacht die indizierte Aussage zur Laufzeit keinen Aufwand. +``` diff --git a/src/denotational-design/dependent-types.es.md b/src/denotational-design/dependent-types.es.md new file mode 100644 index 0000000..fb80baf --- /dev/null +++ b/src/denotational-design/dependent-types.es.md @@ -0,0 +1,80 @@ + + +# Tipos dependientes y pruebas {#dependent-types-and-proofs} + +```admonish tip title="Relacionado" +La perspectiva semántica: [Diseño denotacional](design.md), [Leyes e interpretaciones](laws-and-interpretations.md) +Diseño por significado en Rust: [Tipos semánticos en Rust](../rust-dd/semantic-types.md), [Leyes, escenarios y evidencia](../rust-dd/laws.md) +``` + +```admonish note title="Ubicación semántica" +Los tipos dependientes expresan proposiciones indexadas por valores y evidencia dentro de un sistema de tipos. Pueden codificar parte de una especificación semántica, pero no la eligen: la propiedad prevista debe estar clara antes de incorporarla a un tipo. +``` + +## Tipos indexados por valores {#types-indexed-by-values} + +Un tipo es *dependiente* cuando puede depender de un valor. Por tanto, puede describir no solo la forma de un valor, sino también una relación que ese valor debe satisfacer. + +Algunos ejemplos: + +* `Vec` — un vector indexado por su longitud `n` +* `Matrix` — una matriz indexada por sus dimensiones +* `Proof

` — evidencia de una proposición `p` + +Por ejemplo: + +```hs +append : Vec -> Vec -> Vec +``` + +El tipo de resultado expresa que concatenar vectores de longitudes `n` y `m` produce uno de longitud `n + m`. + +## Funciones dependientes {#dependent-functions} + +Un tipo de función dependiente se escribe así: + +$$ \Pi (x : A).\,B(x) $$ + +Para cada valor $x$ de tipo $A$, el resultado tiene tipo $B(x)$. Compárese con: + +$$ \begin{aligned} f &\colon A \to B \\ g &\colon (x : A) \to B(x) \end{aligned} $$ + +El tipo de resultado de $f$ es fijo. El tipo de resultado de $g$ puede variar según la entrada. + +Según la correspondencia entre proposiciones y tipos, un tipo puede expresar una proposición y un término que habite ese tipo puede servir como prueba. Esto permite API donde no se pueden construir estados, transiciones ni composiciones inválidos. + +## Relación con el Diseño denotacional {#relationship-to-denotational-design} + +El Diseño denotacional pregunta primero: + +1. ¿Cuál es el dominio semántico? +2. ¿Qué observaciones y composiciones importan? +3. ¿Qué leyes deben cumplirse? + +Los tipos dependientes pueden interiorizar después algunas respuestas. Un índice de tipo puede registrar la longitud de un vector, el estado de un protocolo, la profundidad de la pila, un límite de recursos o una prueba de que dos construcciones denotan el mismo resultado. + +El orden importa. Un tipo sofisticado no aporta el significado que falta. Solo fortalece una especificación cuando la proposición indexada ya describe una distinción semántica prevista o un invariante de representación elegido deliberadamente. + +```admonish warning title="No confundas las proposiciones semánticas con los invariantes de representación" +Ambos pueden codificarse en tipos, pero tienen distinta autoridad. Todo intérprete compatible debe preservar una proposición semántica. Un invariante de representación solo restringe la representación que lo eligió. +``` + +## Pruebas y evidencia ejecutable {#proofs-and-executable-evidence} + +Una prueba establece una proposición bajo supuestos declarados. Los tests de propiedades, escenarios y unidades aportan evidencia ejecutable finita. Codificar una proposición en un tipo dependiente puede permitir que el sistema de tipos verifique un término de prueba, pero no convierte los tests en pruebas ni hace que el compilador sea la fuente de la proposición. + +Es la misma separación que recorre el libro: el significado y las leyes expresan la obligación; las herramientas la comprueban o la realizan. + +## Aplicar el modelo en Rust {#applying-the-model-in-rust} + +Rust no es un lenguaje completamente dependiente de tipos, pero los genéricos constantes, typestate, tipos asociados y restricciones de traits pueden expresar relaciones indexadas útiles. Estas codificaciones pueden trasladar comprobaciones al tiempo de compilación y suelen preservar representaciones concretas eficientes. + +El modelo mental orientado a las pruebas sigue siendo valioso aunque Rust no pueda expresar la proposición completa. Explicita el invariante, codifica la parte que el sistema de tipos puede imponer y conserva leyes o tests para el resto. La codificación sirve a la especificación; no la sustituye. + +```admonish example title="Una cuadrícula indexada por posición" +[`typed-grid-rs`](https://github.com/tgrospic/typed-grid-rs) realiza la idea `Matrix` anterior en Rust estable. Cada celda se convierte en un tipo indexado por sus coordenadas — `Pos0x0`, `Pos1x2`, etc. — y un movimiento devuelve un tipo de posición *diferente*: + +`Pos0x0.right()` denota `Pos1x0`; salirse del borde no es un error en tiempo de ejecución, sino un programa que no supera la comprobación de tipos, porque ese movimiento no se genera en el límite. + +Es la misma elevación que describe esta sección: la coordenada que viviría en el mundo de los valores se promueve al tipo, y la navegación válida se vuelve una función total comprobada en tiempo de compilación. Los tipos marcador tienen tamaño cero, por lo que la proposición indexada no cuesta nada en tiempo de ejecución. +``` diff --git a/src/denotational-design/dependent-types.ja.md b/src/denotational-design/dependent-types.ja.md new file mode 100644 index 0000000..8cf32f4 --- /dev/null +++ b/src/denotational-design/dependent-types.ja.md @@ -0,0 +1,80 @@ + + +# 依存型と証明 {#dependent-types-and-proofs} + +```admonish tip title="関連項目" +意味論的な見方:[Denotational Design](design.md)、[法則と解釈](laws-and-interpretations.md) +Rustで意味から設計する:[Rustの意味論的型](../rust-dd/semantic-types.md)、[法則、シナリオ、証拠](../rust-dd/laws.md) +``` + +```admonish note title="意味論上の位置付け" +依存型は、型システムで値に応じた命題と証拠を表現します。意味論的仕様の一部を符号化できますが、仕様自体を選ぶものではありません。型に組み込む前に、意図する性質を明確にする必要があります。 +``` + +## 値で添字付けされた型 {#types-indexed-by-values} + +値に応じて変化する型を*依存型*といいます。そのため依存型は、値の形だけでなく、その値が満たすべき関係も記述できます。 + +例: + +* `Vec` — 長さで添字付けされたベクトル `n` +* `Matrix` — 次元で添字付けされた行列 +* `Proof

` — 命題の証拠 `p` + +たとえば、次のようになります。 + +```hs +append : Vec -> Vec -> Vec +``` + +結果の型は、長さ`n`と`m`のベクトルを連結すると、長さ`n + m`のベクトルができることを示しています。 + +## 依存関数 {#dependent-functions} + +依存関数型は次のように書きます。 + +$$ \Pi (x : A).\,B(x) $$ + +型$A$の各値$x$に対して、結果の型は$B(x)$になります。次と比べてください。 + +$$ \begin{aligned} f &\colon A \to B \\ g &\colon (x : A) \to B(x) \end{aligned} $$ + +$f$の結果型は固定です。$g$の結果型は入力によって変わることがあります。 + +命題即型対応のもとでは、型で命題を述べ、その型を満たす項を証明として使えます。これにより、不正な状態、遷移、合成を構築できないAPIを実現できます。 + +## Denotational Designとの関係 {#relationship-to-denotational-design} + +Denotational Designでは、まず次を問います。 + +1. 意味論的領域は何か。 +2. 重要な観測と合成は何か。 +3. 満たすべき法則はどれか。 + +依存型を使うと、これらの答えの一部を型の内部で表現できます。型の添字に、ベクトルの長さ、プロトコルの状態、スタックの深さ、リソース上限、二つの構成が同じ結果を表すことの証明などを記録できます。 + +順序が重要です。高度な型を使っても、不足している意味は補えません。添字付きの命題が意図された意味論上の区別、または意図的に選んだ表現不変条件をすでに記述している場合に限り、仕様を強化できます。 + +```admonish warning title="意味論的命題と表現不変条件を混同しない" +どちらも型に符号化できますが、権限の範囲は異なります。意味論的命題は、互換性のあるすべてのインタープリターで保持されなければなりません。表現不変条件が制約するのは、それを選んだ表現だけです。 +``` + +## 証明と実行可能な証拠 {#proofs-and-executable-evidence} + +証明は、明示された仮定のもとで命題が成り立つことを示します。プロパティテスト、シナリオテスト、単体テストは有限の実行可能な証拠を提供します。依存型に命題を符号化すれば、型検査で証明項を検証できる場合がありますが、テストが証明に変わるわけでも、コンパイラーが命題の出所になるわけでもありません。 + +本書全体で使うのと同じ区分です。意味と法則が責務を述べ、ツールがそれを検査または実現します。 + +## このモデルをRustに適用する {#applying-the-model-in-rust} + +Rustは完全な依存型付き言語ではありませんが、constジェネリクス、typestate、関連型、トレイト境界によって有用な添字付き関係を表現できます。こうした符号化によって検査をコンパイル時に行え、多くの場合、効率的な具体表現を保てます。 + +Rustで命題全体を表せない場合も、証明指向の考え方は有用です。不変条件を明示し、型システムで強制できる部分を符号化し、残りは法則やテストで検証します。符号化は仕様に役立つものであり、仕様を置き換えるものではありません。 + +```admonish example title="位置を型で添字付けした格子" +[`typed-grid-rs`](https://github.com/tgrospic/typed-grid-rs)は、先ほどの`Matrix`の考え方を安定版Rustで実現します。各セルは座標`Pos0x0`、`Pos1x2`などで添字付けされた型になり、移動すると*別の*位置型が返ります。 + +`Pos0x0.right()`は`Pos1x0`を表します。境界の外への移動は実行時エラーではありません。境界では該当する移動が生成されないため、型検査に通らないプログラムになります。 + +これは、この節で説明した持ち上げと同じです。値の世界に置かれる座標を型へ昇格させ、有効な移動を全域的でコンパイル時に検査される関数にします。マーカー型はサイズがゼロなので、添字付き命題による実行時のコストはありません。 +``` diff --git a/src/denotational-design/dependent-types.ko.md b/src/denotational-design/dependent-types.ko.md new file mode 100644 index 0000000..777146c --- /dev/null +++ b/src/denotational-design/dependent-types.ko.md @@ -0,0 +1,80 @@ + + +# 종속 타입과 증명 {#dependent-types-and-proofs} + +```admonish tip title="관련 항목" +의미론적 관점: [표시적 설계](design.md), [법칙과 해석](laws-and-interpretations.md) +Rust에서 의미로 설계하기: [Rust의 의미 타입](../rust-dd/semantic-types.md), [법칙, 시나리오, 증거](../rust-dd/laws.md) +``` + +```admonish note title="의미론적 위치" +종속 타입은 값에 색인된 명제와 증거를 타입 시스템으로 표현합니다. 의미론적 명세의 일부를 인코딩할 수 있지만, 명세 자체를 선택하지는 않습니다. 어떤 속성을 타입으로 승격하기 전에 의도한 속성이 분명해야 합니다. +``` + +## 값으로 색인된 타입 {#types-indexed-by-values} + +값에 따라 달라질 수 있는 타입을 *종속 타입*이라고 합니다. 따라서 종속 타입은 값의 형태뿐 아니라 그 값이 만족해야 하는 관계도 기술할 수 있습니다. + +예를 들면 다음과 같습니다: + +* `Vec` — 길이를 색인으로 갖는 벡터 `n` +* `Matrix` — 크기를 색인으로 갖는 행렬 +* `Proof

` — 명제 `p`의 증거 + +예를 들어: + +```hs +append : Vec -> Vec -> Vec +``` + +결과 타입은 길이가 `n`인 벡터와 길이가 `m`인 벡터를 이어 붙이면 길이가 `n + m`인 벡터가 됨을 명시합니다. + +## 종속 함수 {#dependent-functions} + +종속 함수 타입은 다음과 같이 씁니다: + +$$ \Pi (x : A).\,B(x) $$ + +타입 $A$을 갖는 각 값 $x$에 대해 결과는 타입 $B(x)$을 갖습니다. 다음과 비교해 보세요: + +$$ \begin{aligned} f &\colon A \to B \\ g &\colon (x : A) \to B(x) \end{aligned} $$ + +$f$의 결과 타입은 고정되어 있습니다. $g$의 결과 타입은 입력에 따라 달라질 수 있습니다. + +명제와 타입의 대응 관계에서 타입은 명제를 나타낼 수 있고, 그 타입의 항은 증명으로 쓰일 수 있습니다. 이를 통해 잘못된 상태, 전이, 합성을 만들 수 없는 API를 구성할 수 있습니다. + +## 표시적 설계와의 관계 {#relationship-to-denotational-design} + +표시적 설계는 먼저 다음을 묻습니다: + +1. 의미론적 영역은 무엇인가? +2. 어떤 관찰과 합성이 중요한가? +3. 어떤 법칙이 성립해야 하는가? + +그 다음 종속 타입으로 일부 답을 내부화할 수 있습니다. 타입 색인은 벡터 길이, 프로토콜 상태, 스택 깊이, 자원 한도 또는 두 구성이 같은 결과를 나타낸다는 증명을 기록할 수 있습니다. + +순서가 중요합니다. 정교한 타입이 빠진 의미를 보충하지는 않습니다. 색인된 명제가 의도된 의미 구분이나 의식적으로 선택한 표현 불변량을 이미 설명할 때에만 명세를 강화합니다. + +```admonish warning title="의미론적 명제와 표현 불변량을 혼동하지 마세요" +둘 다 타입에 인코딩될 수 있지만 권위는 다릅니다. 의미론적 명제는 호환되는 모든 인터프리터가 보존해야 합니다. 표현 불변량은 이를 선택한 표현에만 제약을 둡니다. +``` + +## 증명과 실행 가능한 증거 {#proofs-and-executable-evidence} + +증명은 명시된 가정 아래에서 명제가 성립함을 보입니다. 속성 테스트, 시나리오, 단위 테스트는 유한하고 실행 가능한 증거를 제공합니다. 종속 타입에 명제를 인코딩하면 타입 검사가 증명 항을 검증할 수 있지만, 테스트가 증명으로 바뀌거나 컴파일러가 명제의 근원이 되는 것은 아닙니다. + +이는 책 전반에서 사용하는 구분과 같습니다. 의미와 법칙이 의무를 명시하고, 도구는 이를 점검하거나 실현합니다. + +## Rust에 모델 적용하기 {#applying-the-model-in-rust} + +Rust는 완전한 종속 타입 언어는 아니지만 const 제네릭, 타입 상태, 연관 타입, 트레이트 바운드로 유용한 색인 관계를 표현할 수 있습니다. 이러한 인코딩은 검사를 컴파일 시간으로 옮기며 효율적인 구체 표현을 유지하는 경우가 많습니다. + +Rust가 완전한 명제를 표현할 수 없더라도 증명 중심 사고방식은 유용합니다. 불변량을 명시하고, 타입 시스템이 강제할 수 있는 부분을 인코딩하며, 나머지는 법칙이나 테스트로 확인하세요. 인코딩은 명세를 따르는 수단이지 대체물이 아닙니다. + +```admonish example title="위치로 색인된 격자" +[`typed-grid-rs`](https://github.com/tgrospic/typed-grid-rs)는 위에서 설명한 `Matrix` 아이디어를 안정화 Rust로 구현합니다. 각 칸은 좌표 `Pos0x0`, `Pos1x2` 등을 색인으로 갖는 타입이 되고, 이동 결과는 *서로 다른* 위치 타입이 됩니다: + +`Pos0x0.right()`은 `Pos1x0`을 나타냅니다. 경계를 벗어나는 이동은 런타임 오류가 아니라 타입 검사를 통과하지 못하는 프로그램입니다. 경계에서는 해당 이동이 생성되지 않기 때문입니다. + +이것이 이 절에서 설명한 승격과 같습니다. 값 영역에 놓였을 좌표를 타입으로 올리면 유효한 이동이 항상 정의되고 컴파일 시간에 검사됩니다. 표식 타입은 크기가 0이므로 색인된 명제의 런타임 비용은 없습니다. +``` diff --git a/src/denotational-design/dependent-types.ru.md b/src/denotational-design/dependent-types.ru.md new file mode 100644 index 0000000..e65f045 --- /dev/null +++ b/src/denotational-design/dependent-types.ru.md @@ -0,0 +1,80 @@ + + +# Зависимые типы и доказательства {#dependent-types-and-proofs} + +```admonish tip title="Связанные материалы" +«Семантический взгляд»: [Денотационное проектирование](design.md), [Законы и интерпретации](laws-and-interpretations.md) +«Проектирование на основе смысла в Rust»: [Семантические типы в Rust](../rust-dd/semantic-types.md), [Законы, сценарии и свидетельства](../rust-dd/laws.md) +``` + +```admonish note title="Семантическое место" +Зависимые типы выражают зависящие от значений утверждения и свидетельства в системе типов. Они могут кодировать часть семантической спецификации, но не выбирают её: прежде чем включать свойство в тип, нужно ясно сформулировать, что именно оно означает. +``` + +## Типы, индексированные значениями {#types-indexed-by-values} + +Тип называется *зависимым*, если он может зависеть от значения. Поэтому зависимый тип описывает не только структуру значения, но и отношение, которому оно должно удовлетворять. + +Примеры: + +* `Vec` — вектор, индексированный своей длиной `n` +* `Matrix` — матрица, индексированная своими размерами +* `Proof

` — свидетельство истинности утверждения `p` + +Например: + +```hs +append : Vec -> Vec -> Vec +``` + +Тип результата указывает, что при объединении векторов длиной `n` и `m` получается вектор длиной `n + m`. + +## Зависимые функции {#dependent-functions} + +Тип зависимой функции записывается так: + +$$ \Pi (x : A).\,B(x) $$ + +Для каждого значения $x$ типа $A$ результат имеет тип $B(x)$. Сравните: + +$$ \begin{aligned} f &\colon A \to B \\ g &\colon (x : A) \to B(x) \end{aligned} $$ + +Тип результата $f$ фиксирован. Тип результата $g$ может меняться в зависимости от входного значения. + +В соответствии с соответствием «утверждения как типы» тип может выражать утверждение, а терм, принадлежащий этому типу, — служить его доказательством. Благодаря этому можно проектировать API так, чтобы недопустимые состояния, переходы или композиции было невозможно создать. + +## Связь с денотационным проектированием {#relationship-to-denotational-design} + +Денотационное проектирование сначала задаёт вопросы: + +1. Какова семантическая область? +2. Какие наблюдения и композиции важны? +3. Какие законы должны выполняться? + +Затем зависимые типы могут включить часть ответов в систему типов. Индекс типа может фиксировать длину вектора, состояние протокола, глубину стека, ограничение ресурсов или доказательство того, что две конструкции обозначают один и тот же результат. + +Порядок имеет значение. Сложный тип не восполняет недостающий смысл. Он усиливает спецификацию лишь тогда, когда индексируемое утверждение уже описывает предполагаемое семантическое различие или намеренно выбранный инвариант представления. + +```admonish warning title="Не смешивайте семантические утверждения с инвариантами представления" +И те и другие можно кодировать в типах, но они обладают разной силой. Семантическое утверждение обязан сохранять каждый совместимый интерпретатор. Инвариант представления ограничивает только то представление, для которого он выбран. +``` + +## Доказательства и исполняемые свидетельства {#proofs-and-executable-evidence} + +Доказательство устанавливает утверждение при заданных предположениях. Тесты свойств, сценариев и модульные тесты дают конечные исполняемые свидетельства. Кодирование утверждения зависимым типом может позволить системе типов проверить терм-доказательство, но не превращает тестирование в доказательство и не делает компилятор источником самого утверждения. + +Во всей книге используется одно и то же разграничение: смысл и законы формулируют обязательство, а инструменты проверяют или реализуют его. + +## Применение модели в Rust {#applying-the-model-in-rust} + +Rust не является языком с полноценными зависимыми типами, однако обобщённые константные параметры, типовые состояния, ассоциированные типы и ограничения трейтов позволяют выражать полезные индексированные отношения. Такое кодирование может перенести проверки на этап компиляции и при этом часто сохраняет эффективность конкретных представлений. + +Подход, ориентированный на доказательства, полезен, даже когда Rust не позволяет выразить утверждение целиком. Явно сформулируйте инвариант, закодируйте ту его часть, которую может обеспечить система типов, а остальное покройте законами или тестами. Кодирование служит спецификации, но не заменяет её. + +```admonish example title="Сетка, индексированная положением" +[`typed-grid-rs`](https://github.com/tgrospic/typed-grid-rs) реализует `Matrix`описанную выше идею в стабильном Rust. Каждая ячейка становится типом, индексированным своей координатой — `Pos0x0`, `Pos1x2` и так далее, — а переход возвращает тип позиции *отличный* от исходного: + +`Pos0x0.right()` обозначает `Pos1x0`; выход за край — не ошибка времени выполнения, а программа, которая не проходит проверку типов, поскольку на границе соответствующий переход никогда не генерируется. + +Это тот же перенос, который описан в разделе: координата, которая обычно находилась бы среди значений, помещается в тип, а допустимая навигация становится тотальной функцией, проверяемой во время компиляции. Типы-маркеры имеют нулевой размер, поэтому индексируемое утверждение ничего не стоит во время выполнения. +``` diff --git a/src/denotational-design/dependent-types.uk.md b/src/denotational-design/dependent-types.uk.md new file mode 100644 index 0000000..e091950 --- /dev/null +++ b/src/denotational-design/dependent-types.uk.md @@ -0,0 +1,80 @@ + + +# Залежні типи та доведення {#dependent-types-and-proofs} + +```admonish tip title="Пов’язані матеріали" +Семантичний погляд: [Денотаційне проєктування](design.md), [Закони та інтерпретації](laws-and-interpretations.md) +Проєктування від значення в Rust: [Семантичні типи в Rust](../rust-dd/semantic-types.md), [Закони, сценарії та свідчення](../rust-dd/laws.md) +``` + +```admonish note title="Семантичне місце" +Залежні типи виражають твердження з індексами-значеннями й свідчення в системі типів. Вони можуть кодувати частину семантичної специфікації, але не визначають її: перш ніж переносити бажану властивість у тип, її потрібно чітко сформулювати. +``` + +## Типи з індексами-значеннями {#types-indexed-by-values} + +Тип є *залежним*, якщо може залежати від значення. Тому залежний тип може описувати не лише форму значення, а й відношення, якого це значення має дотримуватися. + +Приклади: + +* `Vec` — вектор з індексом, що задає його довжину `n` +* `Matrix` — матриця з індексами, що задають її розміри +* `Proof

` — свідчення на підтвердження твердження `p` + +Наприклад: + +```hs +append : Vec -> Vec -> Vec +``` + +Тип результату стверджує, що дописування векторів довжини `n` та `m` дає вектор довжини `n + m`. + +## Залежні функції {#dependent-functions} + +Тип залежної функції записують так: + +$$ \Pi (x : A).\,B(x) $$ + +Для кожного значення $x$ типу $A$ результат має тип $B(x)$. Порівняймо: + +$$ \begin{aligned} f &\colon A \to B \\ g &\colon (x : A) \to B(x) \end{aligned} $$ + +Тип результату $f$ є фіксованим. Тип результату $g$ може змінюватися залежно від вхідного значення. + +Згідно з відповідністю між твердженнями й типами, тип може формулювати твердження, а терм цього типу може слугувати його доведенням. Це дає змогу створювати API, у яких неможливо побудувати некоректні стани, переходи чи композиції. + +## Зв’язок із денотаційним проєктуванням {#relationship-to-denotational-design} + +Денотаційне проєктування спершу запитує: + +1. Яка тут семантична область? +2. Які спостереження й композиції важливі? +3. Які закони мають виконуватися? + +Залежні типи можуть включити частину відповідей у систему типів. Індекс типу може фіксувати довжину вектора, стан протоколу, глибину стека, межу ресурсів або доведення того, що дві конструкції позначають однаковий результат. + +Порядок важливий. Складний тип не заповнює прогалини у визначенні значення. Він посилює специфікацію, лише коли індексоване твердження вже описує задуману семантичну відмінність або навмисно вибраний інваріант представлення. + +```admonish warning title="Не плутайте семантичні твердження з інваріантами представлення" +І ті, й ті можна закодувати в типах, але їхня роль різна. Семантичне твердження має зберігатися в кожному сумісному інтерпретаторі. Інваріант представлення обмежує лише те представлення, для якого його вибрали. +``` + +## Доведення й виконувані свідчення {#proofs-and-executable-evidence} + +Доведення встановлює твердження за зазначених припущень. Тести властивостей, сценарії та модульні тести надають скінченні виконувані свідчення. Кодування твердження в залежному типі може дозволити перевірити терм-доведення під час перевірки типів, але не перетворює тестування на доведення й не робить компілятор джерелом самого твердження. + +У книжці послідовно розрізняють ці речі: значення й закони визначають вимогу, а інструменти її перевіряють або реалізують. + +## Застосування моделі в Rust {#applying-the-model-in-rust} + +Rust не є повністю залежно типізованою мовою, але константні узагальнення, типізація станів, асоційовані типи та обмеження трейтів дають змогу виражати корисні індексовані зв’язки. Такі кодування можуть переносити перевірки на етап компіляції й часто зберігають ефективні конкретні представлення. + +Модель мислення, орієнтована на доведення, лишається корисною, навіть якщо Rust не може виразити твердження повністю. Явно сформулюйте інваріант, закодуйте ту частину, яку може забезпечити система типів, а решту покрийте законами чи тестами. Кодування служить специфікації, а не замінює її. + +```admonish example title="Сітка з індексом-позицією" +[`typed-grid-rs`](https://github.com/tgrospic/typed-grid-rs) реалізує описану вище ідею `Matrix` у стабільному Rust. Кожна клітинка стає типом з індексом-координатою — `Pos0x0`, `Pos1x2` тощо, — а перехід повертає тип позиції *іншої*: + +`Pos0x0.right()` позначає `Pos1x0`; вихід за край не є помилкою під час виконання — програма просто не проходить перевірку типів, адже на межі відповідний перехід ніколи не генерується. + +Це та сама операція перенесення на рівень типів, яку описано в розділі: координату, що мала б бути звичайним значенням, перетворюють на тип, а коректну навігацію задають як повну функцію, перевірювану під час компіляції. Маркерні типи мають нульовий розмір, тож індексоване твердження нічого не коштує під час виконання. +``` diff --git a/src/denotational-design/dependent-types.vi.md b/src/denotational-design/dependent-types.vi.md new file mode 100644 index 0000000..d3cacd2 --- /dev/null +++ b/src/denotational-design/dependent-types.vi.md @@ -0,0 +1,80 @@ + + +# Kiểu phụ thuộc và chứng minh {#dependent-types-and-proofs} + +```admonish tip title="Liên quan" +Góc nhìn ngữ nghĩa: [Thiết kế theo ngữ nghĩa](design.md), [Định luật và cách diễn giải](laws-and-interpretations.md) +Thiết kế theo ngữ nghĩa trong Rust: [Kiểu ngữ nghĩa trong Rust](../rust-dd/semantic-types.md), [Định luật, tình huống và bằng chứng](../rust-dd/laws.md) +``` + +```admonish note title="Vị trí ngữ nghĩa" +Kiểu phụ thuộc biểu đạt các mệnh đề và bằng chứng được đánh chỉ mục theo giá trị trong một hệ kiểu. Chúng có thể mã hóa một phần đặc tả ngữ nghĩa, nhưng không chọn đặc tả đó: thuộc tính dự định phải rõ ràng trước khi được đưa vào kiểu. +``` + +## Kiểu được đánh chỉ mục theo giá trị {#types-indexed-by-values} + +Một kiểu là *phụ thuộc* khi nó có thể phụ thuộc vào một giá trị. Do đó, kiểu phụ thuộc có thể mô tả không chỉ hình dạng của giá trị mà còn cả một quan hệ mà giá trị phải thỏa mãn. + +Ví dụ gồm: + +* `Vec` — một vectơ được đánh chỉ mục theo độ dài `n` +* `Matrix` — ma trận được đánh chỉ mục theo kích thước +* `Proof

` — bằng chứng cho mệnh đề `p` + +Chẳng hạn: + +```hs +append : Vec -> Vec -> Vec +``` + +Kiểu kết quả phát biểu rằng nối các vectơ có độ dài `n` và `m` sẽ tạo ra vectơ có độ dài `n + m`. + +## Hàm phụ thuộc {#dependent-functions} + +Kiểu hàm phụ thuộc được viết như sau: + +$$ \Pi (x : A).\,B(x) $$ + +Với mỗi giá trị $x$ thuộc kiểu $A$, kết quả có kiểu $B(x)$. Hãy so sánh: + +$$ \begin{aligned} f &\colon A \to B \\ g &\colon (x : A) \to B(x) \end{aligned} $$ + +Kiểu kết quả của $f$ là cố định. Kiểu kết quả của $g$ có thể thay đổi theo đầu vào. + +Theo tương ứng mệnh đề-là-kiểu, một kiểu có thể phát biểu mệnh đề và một số hạng thuộc kiểu đó có thể làm chứng minh cho mệnh đề. Điều này hỗ trợ các API trong đó không thể tạo ra trạng thái, chuyển tiếp hoặc phép hợp thành không hợp lệ. + +## Quan hệ với Thiết kế theo ngữ nghĩa {#relationship-to-denotational-design} + +Thiết kế theo ngữ nghĩa trước hết đặt câu hỏi: + +1. Miền ngữ nghĩa là gì? +2. Những quan sát và phép hợp thành nào quan trọng? +3. Những định luật nào phải đúng? + +Sau đó, kiểu phụ thuộc có thể nội tại hóa một số câu trả lời. Chỉ mục kiểu có thể ghi lại độ dài vectơ, trạng thái giao thức, độ sâu ngăn xếp, giới hạn tài nguyên hoặc bằng chứng rằng hai kiến tạo biểu thị cùng một kết quả. + +Thứ tự rất quan trọng. Kiểu tinh vi không thể bù đắp ý nghĩa còn thiếu. Nó chỉ củng cố đặc tả khi mệnh đề được đánh chỉ mục đã mô tả một khác biệt ngữ nghĩa dự định hoặc bất biến biểu diễn được chọn có chủ ý. + +```admonish warning title="Đừng nhầm mệnh đề ngữ nghĩa với bất biến biểu diễn" +Cả hai đều có thể được mã hóa bằng kiểu nhưng có thẩm quyền khác nhau. Mọi bộ diễn giải tương thích phải bảo toàn mệnh đề ngữ nghĩa. Bất biến biểu diễn chỉ ràng buộc cách biểu diễn đã chọn nó. +``` + +## Chứng minh và bằng chứng thực thi được {#proofs-and-executable-evidence} + +Chứng minh xác lập một mệnh đề theo các giả định đã nêu. Kiểm thử thuộc tính, tình huống và đơn vị cung cấp bằng chứng thực thi hữu hạn. Mã hóa mệnh đề trong kiểu phụ thuộc có thể cho phép trình kiểm tra kiểu xác minh một số hạng chứng minh, nhưng điều đó không biến kiểm thử thành chứng minh hay biến trình biên dịch thành nguồn gốc của mệnh đề. + +Đây là cùng một sự phân tách được dùng trong toàn cuốn sách: ý nghĩa và định luật nêu nghĩa vụ; công cụ kiểm tra hoặc hiện thực hóa nghĩa vụ đó. + +## Áp dụng mô hình trong Rust {#applying-the-model-in-rust} + +Rust không phải ngôn ngữ có kiểu phụ thuộc đầy đủ, nhưng generic hằng, typestate, kiểu liên kết và ràng buộc đặc trưng có thể biểu đạt những quan hệ đánh chỉ mục hữu ích. Các cách mã hóa này có thể chuyển việc kiểm tra sang thời điểm biên dịch và thường vẫn giữ được cách biểu diễn cụ thể hiệu quả. + +Mô hình tư duy hướng chứng minh vẫn hữu ích ngay cả khi Rust không thể biểu đạt mệnh đề đầy đủ. Hãy nêu rõ bất biến, mã hóa phần mà hệ kiểu có thể thực thi, rồi giữ lại định luật hoặc kiểm thử cho phần còn lại. Cách mã hóa phục vụ đặc tả, chứ không thay thế nó. + +```admonish example title="Lưới được đánh chỉ mục theo vị trí" +[`typed-grid-rs`](https://github.com/tgrospic/typed-grid-rs) hiện thực hóa ý tưởng `Matrix` ở trên trong Rust ổn định. Mỗi ô trở thành kiểu được đánh chỉ mục theo tọa độ — `Pos0x0`, `Pos1x2`, v.v. — và một bước di chuyển trả về kiểu vị trí *khác*: + +`Pos0x0.right()` biểu thị `Pos1x0`; bước ra khỏi mép không phải lỗi lúc chạy mà là chương trình không kiểm tra kiểu được, vì chuyển động tương ứng không bao giờ được sinh ra ở biên. + +Đây chính là phép nâng mà phần này mô tả: tọa độ vốn nằm trong thế giới giá trị được đưa vào kiểu, và việc điều hướng hợp lệ trở thành hàm toàn phần được kiểm tra lúc biên dịch. Các kiểu đánh dấu có kích thước bằng không, vì vậy mệnh đề được đánh chỉ mục không tốn chi phí khi chạy. +``` diff --git a/src/denotational-design/dependent-types.zh-hant.md b/src/denotational-design/dependent-types.zh-hant.md new file mode 100644 index 0000000..3287fcd --- /dev/null +++ b/src/denotational-design/dependent-types.zh-hant.md @@ -0,0 +1,80 @@ + + +# 依賴型別與證明 {#dependent-types-and-proofs} + +```admonish tip title="相關內容" +語義視角:[指稱設計](design.md)、[定律與解釋](laws-and-interpretations.md) +Rust 中的語義驅動設計:[Rust 中的語義型別](../rust-dd/semantic-types.md)、[定律、場景與證據](../rust-dd/laws.md) +``` + +```admonish note title="語義定位" +依賴型別可在型別系統中表達由值索引的命題與證據。它們可以編碼語義規範的一部分,卻不能替我們選擇規範:在把預期性質提升為型別之前,必須先弄清楚該性質。 +``` + +## 由值索引的型別 {#types-indexed-by-values} + +當型別可以依賴某個值時,它就是*依賴*的。因此,依賴型別不僅能描述值的形態,還能描述該值必須滿足的關係。 + +例如: + +* `Vec` —— 由長度索引的向量 `n` +* `Matrix` —— 由維度索引的矩陣 +* `Proof

` —— 某個命題的證據 `p` + +例如: + +```hs +append : Vec -> Vec -> Vec +``` + +結果型別表明,將長度分別為`n`和`m`的向量拼接後,會得到長度為`n + m`的向量。 + +## 依賴函式 {#dependent-functions} + +依賴函式型別寫作: + +$$ \Pi (x : A).\,B(x) $$ + +對於每個值$x$(型別為$A$),結果的型別為$B(x)$。比較: + +$$ \begin{aligned} f &\colon A \to B \\ g &\colon (x : A) \to B(x) \end{aligned} $$ + +$f$的結果型別是固定的。$g$的結果型別則可能隨輸入變化。 + +根據“命題即型別”的對應關係,型別可以陳述一個命題,而擁有該型別的項可以充當證明。這有助於構建 API,使無效狀態、轉換或組合無法被構造出來。 + +## 與指稱設計的關係 {#relationship-to-denotational-design} + +指稱設計首先會問: + +1. 語義域是什麼? +2. 哪些觀察與組合很重要? +3. 必須滿足哪些定律? + +隨後,依賴型別可以將其中一些答案內化。型別索引可以記錄向量長度、協議狀態、棧深度、資源上限,或兩個構造指稱同一結果的證明。 + +順序很重要。複雜的型別無法補上缺失的含義。只有當索引命題已經描述了預期的語義區別或刻意選擇的表示不變數時,它才會強化規範。 + +```admonish warning title="不要混淆語義命題與表示不變數" +二者都可以編碼到型別中,但權威範圍不同。每個相容直譯器都必須保留語義命題;表示不變數則只約束選擇它的那種表示。 +``` + +## 證明與可執行證據 {#proofs-and-executable-evidence} + +證明會在給定假設下確立一個命題。性質測試、場景測試與單元測試則提供有限的可執行證據。將命題編碼為依賴型別,可能讓型別檢查器驗證證明項,但這並不會把測試變成證明,也不會讓編譯器成為命題的來源。 + +本書始終採用同樣的區分:含義與定律陳述義務,工具負責檢查或實現它們。 + +## 在 Rust 中運用該模型 {#applying-the-model-in-rust} + +Rust 並非完全依賴型別語言,但 const 泛型、型別狀態、關聯型別與 trait 約束可以表達有用的索引關係。這些編碼方式能夠把檢查移到編譯期,而且通常保留高效的具體表示。 + +即便 Rust 無法表達完整命題,證明導向的思維方式仍然有價值。明確陳述不變數,編碼型別系統能夠強制的部分,併為其餘部分保留定律或測試。編碼服務於規範,而非取代規範。 + +```admonish example title="以位置為索引的網格" +[`typed-grid-rs`](https://github.com/tgrospic/typed-grid-rs)在穩定版 Rust 中實現了上述`Matrix`構想。每個格子都是一個由座標索引的型別——`Pos0x0`、`Pos1x2`等等——而移動會返回一種位置*不同*的型別: + +`Pos0x0.right()`指稱`Pos1x0`;越過邊緣不是執行時錯誤,而是無法透過型別檢查的程式,因為到達邊界時不會生成相應的移動操作。 + +這正是本節所述的提升:原本屬於值世界的座標被提升到型別中,有效導航於是成為總函式,並在編譯期接受檢查。這些標記型別的大小為零,因此索引命題不產生執行時開銷。 +``` diff --git a/src/denotational-design/dependent-types.zh.md b/src/denotational-design/dependent-types.zh.md new file mode 100644 index 0000000..75ff719 --- /dev/null +++ b/src/denotational-design/dependent-types.zh.md @@ -0,0 +1,80 @@ + + +# 依赖类型与证明 {#dependent-types-and-proofs} + +```admonish tip title="相关内容" +语义视角:[指称设计](design.md)、[定律与解释](laws-and-interpretations.md) +Rust 中的语义驱动设计:[Rust 中的语义类型](../rust-dd/semantic-types.md)、[定律、场景与证据](../rust-dd/laws.md) +``` + +```admonish note title="语义定位" +依赖类型可在类型系统中表达由值索引的命题与证据。它们可以编码语义规范的一部分,却不能替我们选择规范:在把预期性质提升为类型之前,必须先弄清楚该性质。 +``` + +## 由值索引的类型 {#types-indexed-by-values} + +当类型可以依赖某个值时,它就是*依赖*的。因此,依赖类型不仅能描述值的形态,还能描述该值必须满足的关系。 + +例如: + +* `Vec` —— 由长度索引的向量 `n` +* `Matrix` —— 由维度索引的矩阵 +* `Proof

` —— 某个命题的证据 `p` + +例如: + +```hs +append : Vec -> Vec -> Vec +``` + +结果类型表明,将长度分别为`n`和`m`的向量拼接后,会得到长度为`n + m`的向量。 + +## 依赖函数 {#dependent-functions} + +依赖函数类型写作: + +$$ \Pi (x : A).\,B(x) $$ + +对于每个值$x$(类型为$A$),结果的类型为$B(x)$。比较: + +$$ \begin{aligned} f &\colon A \to B \\ g &\colon (x : A) \to B(x) \end{aligned} $$ + +$f$的结果类型是固定的。$g$的结果类型则可能随输入变化。 + +根据“命题即类型”的对应关系,类型可以陈述一个命题,而拥有该类型的项可以充当证明。这有助于构建 API,使无效状态、转换或组合无法被构造出来。 + +## 与指称设计的关系 {#relationship-to-denotational-design} + +指称设计首先会问: + +1. 语义域是什么? +2. 哪些观察与组合很重要? +3. 必须满足哪些定律? + +随后,依赖类型可以将其中一些答案内化。类型索引可以记录向量长度、协议状态、栈深度、资源上限,或两个构造指称同一结果的证明。 + +顺序很重要。复杂的类型无法补上缺失的含义。只有当索引命题已经描述了预期的语义区别或刻意选择的表示不变量时,它才会强化规范。 + +```admonish warning title="不要混淆语义命题与表示不变量" +二者都可以编码到类型中,但权威范围不同。每个兼容解释器都必须保留语义命题;表示不变量则只约束选择它的那种表示。 +``` + +## 证明与可执行证据 {#proofs-and-executable-evidence} + +证明会在给定假设下确立一个命题。性质测试、场景测试与单元测试则提供有限的可执行证据。将命题编码为依赖类型,可能让类型检查器验证证明项,但这并不会把测试变成证明,也不会让编译器成为命题的来源。 + +本书始终采用同样的区分:含义与定律陈述义务,工具负责检查或实现它们。 + +## 在 Rust 中运用该模型 {#applying-the-model-in-rust} + +Rust 并非完全依赖类型语言,但 const 泛型、类型状态、关联类型与 trait 约束可以表达有用的索引关系。这些编码方式能够把检查移到编译期,而且通常保留高效的具体表示。 + +即便 Rust 无法表达完整命题,证明导向的思维方式仍然有价值。明确陈述不变量,编码类型系统能够强制的部分,并为其余部分保留定律或测试。编码服务于规范,而非取代规范。 + +```admonish example title="以位置为索引的网格" +[`typed-grid-rs`](https://github.com/tgrospic/typed-grid-rs)在稳定版 Rust 中实现了上述`Matrix`构想。每个格子都是一个由坐标索引的类型——`Pos0x0`、`Pos1x2`等等——而移动会返回一种位置*不同*的类型: + +`Pos0x0.right()`指称`Pos1x0`;越过边缘不是运行时错误,而是无法通过类型检查的程序,因为到达边界时不会生成相应的移动操作。 + +这正是本节所述的提升:原本属于值世界的坐标被提升到类型中,有效导航于是成为总函数,并在编译期接受检查。这些标记类型的大小为零,因此索引命题不产生运行时开销。 +``` diff --git a/src/denotational-design/design.ar.md b/src/denotational-design/design.ar.md new file mode 100644 index 0000000..b454512 --- /dev/null +++ b/src/denotational-design/design.ar.md @@ -0,0 +1,168 @@ + + +# التصميم الدلالي (Denotational Design) {#denotational-design} + +```admonish tip title="ذات صلة" +المنظور الدلالي: [الدلالات والتركيبية](denotations.md)، [القوانين والتفسيرات](laws-and-interpretations.md) +التصميم انطلاقًا من المعنى في Rust: [جبر القدرات](../rust-dd/capability-algebras.md)، [المعنى المشتق والتركيب](../rust-dd/derived-meaning.md) +``` + +```admonish note title="الفكرة الأساسية" +يشتق التصميم الدلالي واجهة برمجية من معانٍ بسيطة وتركيبية ومستقلة عن التنفيذ، بحيث يوجّه علم الدلالة التصميم بدلًا من أن يصف الواجهة بعد إنشائها. +``` + +التصميم الدلالي ممارسة لاشتقاق واجهة برمجية من معانٍ بسيطة وتركيبية ومستقلة عن التنفيذ. + +طوّر المنهجية وسمّاها [Conal Elliott](http://conal.net/). وخطوتها المحورية ليست مجرد إسناد دلالات إلى لغة أو واجهة API موجودة، بل جعل علم الدلالة موجّهًا لتصميم الواجهة نفسها. + +## دورة التصميم {#the-design-loop} + +اتبع هذا الترتيب: + +1. اختر المجال الدلالي. +2. حدّد البنية المهمة في ذلك المجال. +3. اختر مفردات صغيرة من العمليات الأولية. +4. اشتق العمليات المفيدة بصورة تركيبية. +5. صرّح بالقوانين التي تخضع لها تلك العمليات. +6. اختر تمثيلًا واحدًا أو أكثر. +7. نفّذ تفسيرات تحافظ على البنية. +8. تحقق منها بالقوانين والنماذج والسيناريوهات. + +يبدأ التصميم الذي يضع التمثيل أولًا عادةً من الخطوة 6، ثم يحاول إعادة بناء الخطوات 1–5 بعد ذلك. + +## تصميم جبر للفروع {#designing-a-branch-algebra} + +لنعد إلى مواضع الفروع. المعنى المطلوب هو مسار منتهٍ في بنية تشعب ثنائية. + +قد يكون أحد أنواع الجبر الأولي الممكنة: + +$$ \begin{aligned} \operatorname{root} &\colon \mathtt{()} \to \mathsf{Branch} \\ \operatorname{grow} &\colon \mathsf{Branch} \times \mathsf{Direction} \to \mathsf{Branch} \\ \operatorname{path} &\colon \mathsf{Branch} \times \mathsf{Branch} \rightharpoonup \operatorname{List}(\mathsf{Direction}) \end{aligned} $$ + +يعني السهم الجزئي $\rightharpoonup$ أن ملاحظة المسار لا توجد إلا عندما يكون موضع الفرع الأول سلفًا لموضع الفرع الثاني. + +وتنبثق منه عمليات مفيدة: + +$$ \begin{aligned} \operatorname{left}(b) &= \operatorname{grow}(b, \mathsf{Left}) \\ \operatorname{right}(b) &= \operatorname{grow}(b, \mathsf{Right}) \\ \operatorname{is\_ancestor}(a,b) &\iff \operatorname{path}(a,b)\ \text{is defined} \\ \operatorname{from\_path}(d_s) &= \operatorname{fold}(\operatorname{grow}, \operatorname{root}, d_s) \end{aligned} $$ + +لا يذكر هذا الجبر متجهات أو أعدادًا صحيحة أو كسورًا أو مفاتيح قواعد بيانات أو بايتات. تأتي تلك الخيارات لاحقًا. + +## البنية قبل الملاءمة {#structure-before-convenience} + +ينبغي للمفردات الأولية أن تكشف البنية التي يعتمد عليها الشيفرة اللاحقة، لا أن تكون مجموعة بكل أسلوب مريح يتيحه تنفيذ واحد. + +````admonish warning title="ارفض العمليات الأولية التي تبدأ بالتمثيل" +تجمع هذه السمة ترتيب التخزين وموضع الإعداد وتمثيل البتات وسير عمل مركبًا. لكنها لا تعزل معنى الفرع: + +```rust,noplayground +trait BranchManager { + // not recommended: exposes machinery, not semantic observations + fn storage(&self) -> &BranchTable; + fn config(&self) -> &BranchConfig; + fn raw_bits(&self) -> &[u64]; + fn grow_and_save(&mut self, right: bool); +} +``` +```` + +قد تظل واجهة API دلالية مشتملة على آثار إذا كانت الآثار جزءًا من المجال المختار. القاعدة ليست «يجب أن يكون كل شيء نقيًا»، بل «يجب أن يصرّح كل عنصر أولي بمعنى متماسك». + +## الترميز ليس منهجية {#encoding-is-not-methodology} + +لا يشترط التصميم الدلالي: + +* Haskell +* ترميز tagless-final +* جبر الكائنات +* المونادات الحرة +* شجرة AST واحدة +* الدوال النقية فقط +* مصطلحات نظرية الفئات في كل واجهة API + +قد تكون هذه ترميزات أو وسائل شرح مفيدة، لكن لا يعرّف أي منها المنهجية. + +```admonish note title="ترميزات Rust" +في Rust، تُعد السمات الصغيرة والأنواع المرتبطة وأساليب الامتداد والدوال العامة وقيم البرامج من الرتبة الأولى ترميزات عملية. وتتوقف قيمتها على مدى حفاظها على تصميم دلالي واضح. +``` + +## مورفزمات فئات الأنواع {#type-class-morphisms} + +يمكن فهم المنهجية من خلال تطبيقات تحافظ على البنية. + +لنفترض أن واجهة تصف جبرًا دلاليًا. يربط التنفيذ قيمه وعملياته المجردة بتمثيل ملموس. ويجب على التنفيذ الصحيح الحفاظ على العمليات والقوانين ذات الصلة. + +إذا كان `encode` يربط الفروع المجردة بحامل ملموس، فيبدو الحفاظ على الامتداد هكذا: + +$$ \operatorname{encode}(\operatorname{grow}(b,d)) = \operatorname{grow}_{\mathsf{concrete}}(\operatorname{encode}(b),d) $$ + +التنفيذ ليس مجرد مجموعة أساليب تتطابق أسماؤها. بل يُقصد به أن يكون مورفزمًا يحترم البنية الجبرية. + +## ما الذي يجعل التجريد جيدًا {#what-counts-as-a-good-abstraction} + +يتسم تجريد DD الجيد بعدة خصائص: + +* لقيمه معنى مقصود وبسيط. +* تكشف عناصره الأولية عن ملاحظات أو إنشاءات دلالية. +* يُشتق السلوك الأكبر من تلك العناصر الأولية. +* لا تعتمد قوانينه على تمثيل واحد. +* يمكن لتنفيذات مستقلة تفسيره. +* لا تظهر التفاصيل التشغيلية إلا عند الحاجة إليها. + +الصغر وحده لا يكفي. فالسمة الصغيرة التي تكشف `get_manager()` تظل بادئة بالتمثيل. وقد يكون الجبر الأكبر مبررًا إذا كوّنت عملياته بنية دلالية متماسكة. + +## القيم الدلالية والحوامل المجردة {#semantic-values-and-abstract-carriers} + +ليس كل نوع ملموس ممنوعًا في المواصفة. + +استخدم نوعًا مرتبطًا عندما ينبغي للمفسر اختيار الحامل: + +```rust,noplayground +trait BranchAlg { + type Branch; +} +``` + +استخدم نوعًا ملموسًا عندما يكون مفردة دلالية مستقرة: + +```rust,noplayground +enum Direction { + Left, + Right, +} +``` + +ليس الفرق «المجرّد جيد والملموس سيئ»، بل بين المفردات الدلالية وتمثيل الآلة العارض. + +## المواصفة هي الدلالة، ولا يلزم أن تكون قابلة للتنفيذ {#the-specification-is-the-denotation-and-it-need-not-execute} + +المواصفة هي الدلالة: المعنى الرياضي المسند إلى كل بنية. وتنبع قوتها من تحررها من قيود الكفاءة، بل وحتى قابلية التنفيذ. + +```admonish quote title="Conal Elliott" +غالبًا ما يكون تعريف دلالة أسهل بكثير وأكثر إضاءة من تعريف تنفيذ، لأنه لا يواجه قيود الكفاءة أو مشتتاتها، ولا حتى قيود قابلية التنفيذ. + +— [التصميم الدلالي: من المعاني إلى البرامج (LambdaJam 2015)](https://github.com/conal/talk-2014-lambdajam-denotational-design) +``` + +المثال المرجعي هو FRP (البرمجة التفاعلية الوظيفية): يُعرّف `Behavior a` على أنه دالة في الزمن المتصل، + +$$\llbracket\,\cdot\,\rrbracket : \mathsf{Behavior}\ a \to (\mathbb{R} \to a)$$ + +ذلك النموذج دقيق لكنه غير قابل للتنفيذ — إذ لا يمكنك تعداد الأعداد الحقيقية. وقد يدل البرنامج كذلك على مجموعة من النتائج؛ لا يُنفّذ أي من النموذجين، وهذا هو المقصود. يُختار المعنى لبساطته ودقته، لا بحسب كيفية حسابه. + +تُترك قابلية التنفيذ والكفاءة بالكامل لـ *التنفيذ*، وهو أثر مستقل تثبته صحيحًا قوانين التشاكل (مورفزمات فئات الأنواع) التي تربطه بالمعنى: يجب أن تنقل دالة المعنى كل تركيب نحوي إلى التركيب الدلالي المقابل. وكما يقول Conal، تمنح الدلالة «تعريفًا لا لبس فيه *لما* ينبغي تنفيذه تحديدًا، مع إبقاء مساحة واسعة للإبداع في *كيفية* التنفيذ». + +في Rust، تعبّر عدة آثار عن أجزاء من هذه المواصفة، ويصادف أن بعضها قابل للتنفيذ. قابلية التنفيذ أمر عارض، وليست ما يجعلها مواصفة: + +* النثر يصرح بالمعنى المقصود +* السمات تصرح بالعناصر الأولية المتاحة +* الامتدادات تصرح بالاشتقاقات +* القوانين تصرح بالتساويات المطلوبة +* المفسرات تبيّن إمكان التحقيق +* الاختبارات تقدم دليلًا محدودًا + +اقرأها مجتمعة، مع منح المعنى والقوانين سلطة أعلى من الآليات الملموسة. + +## للمزيد من القراءة {#further-reading} + +* [التصميم الدلالي: من البرامج إلى المعاني (BayHac 2014)](https://github.com/conal/talk-2014-bayhac-denotational-design) +* [Denotational design with type class morphisms](http://conal.net/papers/type-class-morphisms/) +* [كتابات ومحاضرات Conal Elliott](http://conal.net/) diff --git a/src/denotational-design/design.de.md b/src/denotational-design/design.de.md new file mode 100644 index 0000000..90645ba --- /dev/null +++ b/src/denotational-design/design.de.md @@ -0,0 +1,168 @@ + + +# Denotational Design {#denotational-design} + +```admonish tip title="Verwandte Themen" +The Semantic View: [Denotationen und Kompositionalität](denotations.md), [Gesetze und Interpretationen](laws-and-interpretations.md) +Design by Meaning in Rust: [Capability-Algebren](../rust-dd/capability-algebras.md), [Abgeleitete Bedeutung und Komposition](../rust-dd/derived-meaning.md) +``` + +```admonish note title="Grundidee" +Denotational Design leitet eine Programmierschnittstelle aus einfachen, kompositionalen und implementierungsunabhängigen Bedeutungen ab. So leitet die Semantik den Entwurf, statt eine bereits entworfene Schnittstelle nachträglich zu beschreiben. +``` + +Denotational Design ist die Praxis, eine Programmierschnittstelle aus einfachen, kompositionalen und implementierungsunabhängigen Bedeutungen abzuleiten. + +Die Methode wurde von [Conal Elliott](http://conal.net/) entwickelt und benannt. Ihr zentraler Schritt besteht nicht nur darin, einer bestehenden Sprache oder API eine Semantik zuzuweisen. Vielmehr lässt man die Semantik den Entwurf der API selbst leiten. + +## Der Entwurfszyklus {#the-design-loop} + +Gehe in dieser Reihenfolge vor: + +1. Den semantischen Bereich wählen. +2. Die relevante Struktur in diesem Bereich bestimmen. +3. Ein kleines Vokabular primitiver Operationen wählen. +4. Nützliche Operationen kompositional ableiten. +5. Die Gesetze formulieren, denen diese Operationen folgen. +6. Eine oder mehrere Repräsentationen auswählen. +7. Interpretationen implementieren, die die Struktur bewahren. +8. Sie anhand von Gesetzen, Modellen und Szenarien validieren. + +Ein repräsentationsorientierter Entwurf beginnt häufig bei Schritt 6 und versucht anschließend, die Schritte 1 bis 5 nachträglich zu rekonstruieren. + +## Eine Verzweigungsalgebra entwerfen {#designing-a-branch-algebra} + +Kehren wir zu Verzweigungspositionen zurück. Die gewünschte Bedeutung ist ein endlicher Pfad in einer binären Verzweigungsstruktur. + +Eine mögliche primitive Algebra lautet: + +$$ \begin{aligned} \operatorname{root} &\colon \mathtt{()} \to \mathsf{Branch} \\ \operatorname{grow} &\colon \mathsf{Branch} \times \mathsf{Direction} \to \mathsf{Branch} \\ \operatorname{path} &\colon \mathsf{Branch} \times \mathsf{Branch} \rightharpoonup \operatorname{List}(\mathsf{Direction}) \end{aligned} $$ + +Der partielle Pfeil $\rightharpoonup$ bedeutet, dass die Pfadbeobachtung nur existiert, wenn der erste Zweig ein Vorfahr des zweiten ist. + +Daraus ergeben sich nützliche Operationen: + +$$ \begin{aligned} \operatorname{left}(b) &= \operatorname{grow}(b, \mathsf{Left}) \\ \operatorname{right}(b) &= \operatorname{grow}(b, \mathsf{Right}) \\ \operatorname{is\_ancestor}(a,b) &\iff \operatorname{path}(a,b)\ \text{is defined} \\ \operatorname{from\_path}(d_s) &= \operatorname{fold}(\operatorname{grow}, \operatorname{root}, d_s) \end{aligned} $$ + +Diese Algebra erwähnt weder Vektoren noch Ganzzahlen, Brüche, Datenbankschlüssel oder Bytes. Diese Entscheidungen folgen später. + +## Struktur vor Bequemlichkeit {#structure-before-convenience} + +Das primitive Vokabular sollte die Struktur sichtbar machen, von der nachgelagerter Code abhängt. Es sollte keine Sammlung aller praktischen Methoden einer einzelnen Implementierung sein. + +````admonish warning title="Repräsentationsorientierte Primitive ablehnen" +Dieses Trait bündelt Speicheranordnung, Konfigurationsort, Bitrepräsentation und einen zusammengesetzten Arbeitsablauf. Es isoliert nicht die Bedeutung der Verzweigung: + +```rust,noplayground +trait BranchManager { + // not recommended: exposes machinery, not semantic observations + fn storage(&self) -> &BranchTable; + fn config(&self) -> &BranchConfig; + fn raw_bits(&self) -> &[u64]; + fn grow_and_save(&mut self, right: bool); +} +``` +```` + +Eine semantische API kann weiterhin Effekte enthalten, wenn Effekte zum gewählten Bereich gehören. Die Regel lautet nicht: „Alles muss rein sein.“ Sie lautet: „Jede primitive Operation muss eine schlüssige Bedeutung angeben.“ + +## Kodierung ist keine Methodik {#encoding-is-not-methodology} + +Denotational Design setzt Folgendes nicht voraus: + +* Haskell +* Tagless-Final-Kodierung +* Objektalgebren +* freie Monaden +* einen einzelnen AST +* ausschließlich reine Funktionen +* kategorientheoretische Begriffe in jeder API + +All dies kann als Kodierung oder Erklärungshilfe nützlich sein. Nichts davon definiert die Methode. + +```admonish note title="Rust-Kodierungen" +In Rust sind kleine Traits, assoziierte Typen, Erweiterungsmethoden, generische Funktionen und Werte von Programmen erster Ordnung praktische Kodierungen. Ihr Wert hängt davon ab, ob sie einen klaren semantischen Entwurf bewahren. +``` + +## Morphismen von Typklassen {#type-class-morphisms} + +Eine Möglichkeit, die Methode zu verstehen, sind strukturtreue Abbildungen. + +Angenommen, eine Schnittstelle beschreibt eine semantische Algebra. Eine Implementierung bildet deren abstrakte Werte und Operationen auf eine konkrete Repräsentation ab. Eine gültige Implementierung muss die relevanten Operationen und Gesetze bewahren. + +Wenn `encode` abstrakte Zweige auf einen konkreten Träger abbildet, sieht die Bewahrung der Erweiterung so aus: + +$$ \operatorname{encode}(\operatorname{grow}(b,d)) = \operatorname{grow}_{\mathsf{concrete}}(\operatorname{encode}(b),d) $$ + +Die Implementierung ist nicht bloß eine Sammlung von Methoden mit passenden Namen. Sie soll ein Morphismus sein, der die algebraische Struktur respektiert. + +## Was eine gute Abstraktion ausmacht {#what-counts-as-a-good-abstraction} + +Eine gute DD-Abstraktion hat mehrere Eigenschaften: + +* Ihre Werte haben eine einfache, beabsichtigte Bedeutung. +* Ihre primitiven Operationen machen semantische Beobachtungen oder Konstruktionen zugänglich. +* Umfangreicheres Verhalten wird aus diesen primitiven Operationen abgeleitet. +* Ihre Gesetze hängen nicht von einer bestimmten Repräsentation ab. +* Unabhängige Implementierungen können sie interpretieren. +* Operative Details treten erst dort auf, wo sie relevant werden. + +Kleinheit allein genügt nicht. Ein winziges Trait, das `get_manager()` offenlegt, ist weiterhin repräsentationsorientiert. Eine umfangreichere Algebra kann gerechtfertigt sein, wenn ihre Operationen eine schlüssige semantische Struktur bilden. + +## Semantische Werte und abstrakte Träger {#semantic-values-and-abstract-carriers} + +Nicht jeder konkrete Typ ist in einer Spezifikation verboten. + +Verwende einen assoziierten Typ, wenn der Interpreter den Träger wählen soll: + +```rust,noplayground +trait BranchAlg { + type Branch; +} +``` + +Verwende einen konkreten Typ, wenn er zum stabilen semantischen Vokabular gehört: + +```rust,noplayground +enum Direction { + Left, + Right, +} +``` + +Die Unterscheidung lautet nicht „abstrakt gut, konkret schlecht“, sondern semantisches Vokabular gegenüber zufälliger Maschinenrepräsentation. + +## Die Spezifikation ist die Denotation und muss nicht ausführbar sein {#the-specification-is-the-denotation-and-it-need-not-execute} + +Die Spezifikation ist die Denotation: die jedem Konstrukt zugewiesene mathematische Bedeutung. Ihre Stärke liegt darin, dass sie frei von Effizienzbeschränkungen und sogar von der Forderung nach Ausführbarkeit ist. + +```admonish quote title="Conal Elliott" +Oft ist es viel einfacher und aufschlussreicher, eine Denotation als eine Implementierung zu definieren, denn sie unterliegt keinerlei Effizienzbeschränkungen oder Ablenkungen und muss nicht einmal ausführbar sein. + +— [Denotational Design: from meanings to programs (LambdaJam 2015)](https://github.com/conal/talk-2014-lambdajam-denotational-design) +``` + +Das kanonische Beispiel ist FRP (Functional Reactive Programming): Ein `Behavior a` wird als Funktion der kontinuierlichen Zeit definiert, + +$$\llbracket\,\cdot\,\rrbracket : \mathsf{Behavior}\ a \to (\mathbb{R} \to a)$$ + +Dieses Modell ist präzise, aber nicht ausführbar — die reellen Zahlen lassen sich nicht aufzählen. Ein Programm kann ebenso eine Ergebnismenge bezeichnen; keines der beiden Modelle wird ausgeführt, und genau darum geht es. Die Bedeutung wird nach Einfachheit und Präzision gewählt, nicht danach, wie sie berechnet wird. + +Ausführbarkeit und Effizienz werden vollständig der *Implementierung* überlassen, einem getrennten Artefakt, dessen Korrektheit durch Homomorphiegesetze (Morphismen von Typklassen) gewährleistet wird, die es auf die Bedeutung zurückführen: Die Bedeutungsfunktion muss jede syntaktische Komposition auf die entsprechende semantische abbilden. Wie Conal es ausdrückt, liefert die Denotation „eine eindeutige Definition dessen, *was* implementiert werden soll, lässt aber viel Spielraum für Kreativität beim *Wie*.“ + +In Rust bringen mehrere Artefakte Teile dieser Spezifikation zum Ausdruck, und manche davon sind zufällig ausführbar. Die Ausführbarkeit ist nebensächlich; sie macht ein Artefakt nicht zur Spezifikation: + +* Prosa formuliert die beabsichtigte Bedeutung +* Traits legen verfügbare Primitive fest +* Erweiterungen formulieren Ableitungen +* Gesetze formulieren erforderliche Gleichheiten +* Interpreter zeigen die Realisierbarkeit +* Tests liefern endliche Nachweise + +Lies sie gemeinsam und gib Bedeutung und Gesetzen Vorrang vor konkreten Mechanismen. + +## Weiterführende Lektüre {#further-reading} + +* [Denotational Design: from programs to meanings (BayHac 2014)](https://github.com/conal/talk-2014-bayhac-denotational-design) +* [Denotational design with type class morphisms](http://conal.net/papers/type-class-morphisms/) +* [Conal Elliott's writings and talks](http://conal.net/) diff --git a/src/denotational-design/design.es.md b/src/denotational-design/design.es.md new file mode 100644 index 0000000..6b48995 --- /dev/null +++ b/src/denotational-design/design.es.md @@ -0,0 +1,168 @@ + + +# Diseño denotacional {#denotational-design} + +```admonish tip title="Relacionado" +La perspectiva semántica: [Denotaciones y composicionalidad](denotations.md), [Leyes e interpretaciones](laws-and-interpretations.md) +Diseño por significado en Rust: [Álgebras de capacidades](../rust-dd/capability-algebras.md), [Significado derivado y composición](../rust-dd/derived-meaning.md) +``` + +```admonish note title="Idea central" +El Diseño denotacional deriva una interfaz de programación a partir de significados simples, composicionales e independientes de la implementación, dejando que la semántica guíe el diseño en lugar de describir una interfaz a posteriori. +``` + +El Diseño denotacional es la práctica de derivar una interfaz de programación a partir de significados simples, composicionales e independientes de la implementación. + +La metodología fue desarrollada y nombrada por [Conal Elliott](http://conal.net/). Su movimiento central no consiste simplemente en asignar semántica a un lenguaje o API existente, sino en dejar que la semántica guíe el diseño de la propia API. + +## El ciclo de diseño {#the-design-loop} + +Sigue este orden: + +1. Elige el dominio semántico. +2. Identifica la estructura importante en ese dominio. +3. Elige un vocabulario reducido de operaciones primitivas. +4. Deriva operaciones útiles de forma composicional. +5. Enuncia las leyes que cumplen esas operaciones. +6. Elige una o varias representaciones. +7. Implementa interpretaciones que preserven la estructura. +8. Valídalas mediante leyes, modelos y escenarios. + +El diseño centrado en la representación suele empezar en el paso 6 e intenta reconstruir después los pasos 1–5. + +## Diseñar un álgebra de ramificación {#designing-a-branch-algebra} + +Volvamos a las posiciones de ramificación. El significado deseado es un camino finito en una estructura de ramificación binaria. + +Un posible álgebra primitiva es: + +$$ \begin{aligned} \operatorname{root} &\colon \mathtt{()} \to \mathsf{Branch} \\ \operatorname{grow} &\colon \mathsf{Branch} \times \mathsf{Direction} \to \mathsf{Branch} \\ \operatorname{path} &\colon \mathsf{Branch} \times \mathsf{Branch} \rightharpoonup \operatorname{List}(\mathsf{Direction}) \end{aligned} $$ + +La flecha parcial $\rightharpoonup$ significa que la observación del camino solo existe cuando la primera rama es antecesora de la segunda. + +De ahí se derivan operaciones útiles: + +$$ \begin{aligned} \operatorname{left}(b) &= \operatorname{grow}(b, \mathsf{Left}) \\ \operatorname{right}(b) &= \operatorname{grow}(b, \mathsf{Right}) \\ \operatorname{is\_ancestor}(a,b) &\iff \operatorname{path}(a,b)\ \text{is defined} \\ \operatorname{from\_path}(d_s) &= \operatorname{fold}(\operatorname{grow}, \operatorname{root}, d_s) \end{aligned} $$ + +Este álgebra no menciona vectores, enteros, fracciones, claves de base de datos ni bytes. Esas decisiones vienen después. + +## La estructura antes que la comodidad {#structure-before-convenience} + +El vocabulario primitivo debe revelar la estructura de la que depende el código posterior. No debe ser una colección de todos los métodos convenientes disponibles en una implementación. + +````admonish warning title="Rechaza las primitivas centradas en la representación" +Este trait agrupa la disposición del almacenamiento, la ubicación de configuración, la representación de bits y un flujo de trabajo compuesto. No aísla el significado de la ramificación: + +```rust,noplayground +trait BranchManager { + // not recommended: exposes machinery, not semantic observations + fn storage(&self) -> &BranchTable; + fn config(&self) -> &BranchConfig; + fn raw_bits(&self) -> &[u64]; + fn grow_and_save(&mut self, right: bool); +} +``` +```` + +Una API semántica puede incluir efectos si forman parte del dominio elegido. La regla no es «todo debe ser puro», sino «cada primitiva debe expresar un significado coherente». + +## La codificación no es la metodología {#encoding-is-not-methodology} + +El Diseño denotacional no exige: + +* Haskell +* codificación tagless-final +* álgebras de objetos +* mónadas libres +* un único AST +* solo funciones puras +* terminología de teoría de categorías en cada API + +Pueden ser codificaciones o herramientas explicativas útiles. Ninguna define el método. + +```admonish note title="Codificaciones en Rust" +En Rust, los traits pequeños, los tipos asociados, los métodos de extensión, las funciones genéricas y los valores de programa de primer orden son codificaciones prácticas. Su valor depende de que preserven un diseño semántico claro. +``` + +## Morfismos de clases de tipos {#type-class-morphisms} + +Una forma de entender el método es mediante aplicaciones que preservan la estructura. + +Supongamos que una interfaz describe un álgebra semántica. Una implementación asigna sus valores y operaciones abstractos a una representación concreta. Una implementación válida debe preservar las operaciones y leyes pertinentes. + +Si `encode` asigna ramas abstractas a un portador concreto, la preservación del crecimiento tiene este aspecto: + +$$ \operatorname{encode}(\operatorname{grow}(b,d)) = \operatorname{grow}_{\mathsf{concrete}}(\operatorname{encode}(b),d) $$ + +La implementación no es simplemente un conjunto de métodos con nombres coincidentes. Debe ser un morfismo que respete la estructura algebraica. + +## Qué caracteriza a una buena abstracción {#what-counts-as-a-good-abstraction} + +Una buena abstracción DD tiene varias propiedades: + +* Sus valores tienen un significado previsto y sencillo. +* Sus primitivas exponen observaciones o construcciones semánticas. +* El comportamiento más amplio se deriva de esas primitivas. +* Sus leyes no dependen de una sola representación. +* Pueden interpretarla implementaciones independientes. +* Los detalles operacionales aparecen solo cuando son pertinentes. + +Ser pequeño no basta. Un trait diminuto que expone `get_manager()` sigue centrado en la representación. Un álgebra mayor puede justificarse cuando sus operaciones forman una estructura semántica coherente. + +## Valores semánticos y portadores abstractos {#semantic-values-and-abstract-carriers} + +La especificación no tiene por qué excluir todos los tipos concretos. + +Usa un tipo asociado cuando el intérprete deba elegir el portador: + +```rust,noplayground +trait BranchAlg { + type Branch; +} +``` + +Usa un tipo concreto cuando forme parte de un vocabulario semántico estable: + +```rust,noplayground +enum Direction { + Left, + Right, +} +``` + +La distinción no es «abstracto bueno, concreto malo», sino entre vocabulario semántico y representación accidental de máquina. + +## La especificación es la denotación, y no tiene por qué ejecutarse {#the-specification-is-the-denotation-and-it-need-not-execute} + +La especificación es la denotación: el significado matemático asignado a cada construcción. Su poder proviene de estar libre de las restricciones de eficiencia e incluso de ejecutabilidad. + +```admonish quote title="Conal Elliott" +A menudo es mucho más fácil y esclarecedor definir una denotación que una implementación, porque no está sometida a restricciones ni distracciones de eficiencia, ni siquiera de ejecutabilidad. + +— [Denotational Design: from meanings to programs (LambdaJam 2015)](https://github.com/conal/talk-2014-lambdajam-denotational-design) +``` + +El ejemplo canónico es FRP (programación reactiva funcional): un `Behavior a` se define como una función del tiempo continuo, + +$$\llbracket\,\cdot\,\rrbracket : \mathsf{Behavior}\ a \to (\mathbb{R} \to a)$$ + +Ese modelo es preciso, pero no ejecutable: no se pueden enumerar los números reales. Del mismo modo, un programa puede denotar un conjunto de resultados; ninguno de los dos modelos se ejecuta, y ese es precisamente el objetivo. El significado se elige por su sencillez y precisión, no por cómo se calculará. + +La ejecutabilidad y la eficiencia recaen por completo en la *implementación*, un artefacto separado cuya corrección establecen leyes de homomorfismo (morfismos de clases de tipos) que la relacionan con el significado: la función de significado debe llevar cada composición sintáctica a la composición semántica correspondiente. Como dice Conal, la denotación proporciona «una definición inequívoca de exactamente *qué* implementar, dejando a la vez mucho margen para la creatividad sobre *cómo* hacerlo». + +En Rust, varios artefactos expresan partes de esta especificación, y algunos resultan ser ejecutables. La ejecutabilidad es incidental; no es lo que los convierte en especificación: + +* la prosa expresa el significado previsto +* los traits expresan las primitivas disponibles +* las extensiones expresan las derivaciones +* las leyes expresan las igualdades exigidas +* los intérpretes demuestran que puede realizarse +* las pruebas aportan evidencia finita + +Léelos en conjunto, dando al significado y a las leyes mayor autoridad que a los mecanismos concretos. + +## Lecturas adicionales {#further-reading} + +* [Denotational Design: from programs to meanings (BayHac 2014)](https://github.com/conal/talk-2014-bayhac-denotational-design) +* [Denotational design with type class morphisms](http://conal.net/papers/type-class-morphisms/) +* [Escritos y conferencias de Conal Elliott](http://conal.net/) diff --git a/src/denotational-design/design.ja.md b/src/denotational-design/design.ja.md new file mode 100644 index 0000000..0c686c5 --- /dev/null +++ b/src/denotational-design/design.ja.md @@ -0,0 +1,168 @@ + + +# Denotational Design {#denotational-design} + +```admonish tip title="関連項目" +意味論的な見方:[表示と合成性](denotations.md)、[法則と解釈](laws-and-interpretations.md) +Rustで意味から設計する:[ケイパビリティ代数](../rust-dd/capability-algebras.md)、[導出される意味と合成](../rust-dd/derived-meaning.md) +``` + +```admonish note title="中心となる考え方" +Denotational Designでは、単純で合成可能かつ実装に依存しない意味からプログラミングインターフェースを導きます。後付けでインターフェースを説明するのではなく、意味論を設計の指針とします。 +``` + +Denotational Designとは、単純で合成可能かつ実装に依存しない意味から、プログラミングインターフェースを導く実践です。 + +この方法論は[Conal Elliott](http://conal.net/)が開発し、命名しました。中心となるのは、既存の言語やAPIに意味論を割り当てることだけではありません。意味論をAPIそのものの設計指針にすることです。 + +## 設計の反復手順 {#the-design-loop} + +次の順序で進めます。 + +1. 意味論的領域を選ぶ。 +2. その領域で重要な構造を特定する。 +3. 基本操作の小さな語彙を選ぶ。 +4. 有用な操作を合成的に導出する。 +5. それらの操作が従う法則を述べる。 +6. 一つまたは複数の表現を選ぶ。 +7. 構造を保持する解釈を実装する。 +8. 法則、モデル、シナリオを使って妥当性を確認する。 + +表現先行の設計では、一般に手順6から始め、後から手順1〜5を再構成しようとします。 + +## 分岐代数を設計する {#designing-a-branch-algebra} + +分岐位置に戻りましょう。求める意味は、二分岐構造における有限経路です。 + +基本代数の一例は次のとおりです。 + +$$ \begin{aligned} \operatorname{root} &\colon \mathtt{()} \to \mathsf{Branch} \\ \operatorname{grow} &\colon \mathsf{Branch} \times \mathsf{Direction} \to \mathsf{Branch} \\ \operatorname{path} &\colon \mathsf{Branch} \times \mathsf{Branch} \rightharpoonup \operatorname{List}(\mathsf{Direction}) \end{aligned} $$ + +部分関数$\rightharpoonup$は、最初の分岐が二つ目の祖先である場合にのみ、経路の観測が存在することを表します。 + +ここから有用な操作を導けます。 + +$$ \begin{aligned} \operatorname{left}(b) &= \operatorname{grow}(b, \mathsf{Left}) \\ \operatorname{right}(b) &= \operatorname{grow}(b, \mathsf{Right}) \\ \operatorname{is\_ancestor}(a,b) &\iff \operatorname{path}(a,b)\ \text{is defined} \\ \operatorname{from\_path}(d_s) &= \operatorname{fold}(\operatorname{grow}, \operatorname{root}, d_s) \end{aligned} $$ + +この代数は、ベクトル、整数、分数、データベースキー、バイト列に言及しません。そうした選択は後で行います。 + +## 利便性より先に構造を定める {#structure-before-convenience} + +基本語彙によって、下流のコードが依存する構造を明らかにします。一つの実装で利用できる便利なメソッドをすべて集めるのではありません。 + +````admonish warning title="表現先行の基本操作を避ける" +このトレイトは、格納方法、設定の場所、ビット表現、複合ワークフローをひとまとめにしています。分岐の意味を切り分けていません。 + +```rust,noplayground +trait BranchManager { + // not recommended: exposes machinery, not semantic observations + fn storage(&self) -> &BranchTable; + fn config(&self) -> &BranchConfig; + fn raw_bits(&self) -> &[u64]; + fn grow_and_save(&mut self, right: bool); +} +``` +```` + +選択した領域に副作用が含まれるなら、意味論的APIにも副作用を含められます。「すべて純粋でなければならない」という規則ではありません。「基本操作はそれぞれ一貫した意味を述べなければならない」という規則です。 + +## 符号化は方法論ではない {#encoding-is-not-methodology} + +Denotational Designが次のものを必須とするわけではありません。 + +* Haskell +* tagless-final符号化 +* オブジェクト代数 +* 自由モナド +* 一つのAST +* 純粋関数のみ +* すべてのAPIに圏論の用語を使うこと + +これらは有用な符号化や説明手段になり得ますが、どれも方法論を定義するものではありません。 + +```admonish note title="Rustでの符号化" +Rustでは、小さなトレイト、関連型、拡張メソッド、ジェネリック関数、一階のプログラム値が実用的な符号化手段になります。その価値は、明確な意味論的設計を保てるかどうかで決まります。 +``` + +## 型クラスの準同型 {#type-class-morphisms} + +この方法を、構造を保つ写像として理解する方法があります。 + +インターフェースが意味論的代数を記述するとします。実装は、その抽象値と操作を具体的な表現へ写像します。有効な実装は、関係する操作と法則を保持しなければなりません。 + +`encode`が抽象的な分岐を具体的な担体へ写像するとき、拡張を保持する性質は次のように表せます。 + +$$ \operatorname{encode}(\operatorname{grow}(b,d)) = \operatorname{grow}_{\mathsf{concrete}}(\operatorname{encode}(b),d) $$ + +実装は、名前の一致するメソッドを集めただけのものではありません。代数構造を尊重する準同型として意図されています。 + +## 優れた抽象化とは何か {#what-counts-as-a-good-abstraction} + +優れたDenotational Designの抽象化には、次のような性質があります。 + +* 値が単純で意図の明確な意味を持つ。 +* 基本操作が意味論的な観測または構築を表す。 +* より大きな振る舞いが基本操作から導出される。 +* 法則が特定の表現に依存しない。 +* 独立した実装がそれを解釈できる。 +* 操作上の詳細は関係する場面でのみ現れる。 + +小さいだけでは不十分です。`get_manager()`を公開する小さなトレイトでも、表現先行のままです。より大きな代数でも、各操作が一貫した意味論的構造を成すなら正当化できます。 + +## 意味論的な値と抽象的な担体 {#semantic-values-and-abstract-carriers} + +仕様に具体型を一切含めてはならないわけではありません。 + +インタープリターに担体を選ばせる場合は、関連型を使います。 + +```rust,noplayground +trait BranchAlg { + type Branch; +} +``` + +安定した意味論上の語彙なら、具体型を使います。 + +```rust,noplayground +enum Direction { + Left, + Right, +} +``` + +違いは「抽象が善で、具体が悪」ということではありません。意味論上の語彙か、偶然の機械表現かという違いです。 + +## 仕様とは表示であり、実行可能である必要はない {#the-specification-is-the-denotation-and-it-need-not-execute} + +仕様とは表示、つまり各構成要素に割り当てられた数学的な意味です。その強みは、効率性や実行可能性にさえ縛られないことにあります。 + +```admonish quote title="Conal Elliott" +表示を定義するほうが実装よりはるかに簡単で、理解も深まることがよくあります。効率性や実行可能性に伴う制約や雑音がないからです。 + +— [Denotational Design:意味からプログラムへ(LambdaJam 2015)](https://github.com/conal/talk-2014-lambdajam-denotational-design) +``` + +典型例はFRP(関数型リアクティブプログラミング)です。`Behavior a`は連続時間の関数として定義されます。 + +$$\llbracket\,\cdot\,\rrbracket : \mathsf{Behavior}\ a \to (\mathbb{R} \to a)$$ + +そのモデルは正確ですが、実行できません。実数を列挙できないからです。同様に、プログラムが結果の集合を表す場合もあります。どちらのモデルも実行しませんが、それこそが要点です。計算方法ではなく、単純さと正確さを基準に意味を選びます。 + +実行可能性と効率性は、意味に立ち返って正しさを保つ準同型の法則(型クラスの準同型)で制約された別個の成果物、*実装*に全面的に委ねられます。意味関数は、構文上の各合成を対応する意味論上の合成へ写さなければなりません。Conalの言葉を借りれば、表示によって「実装すべき*もの*を曖昧さなく定義しつつ、実装*方法*には大きな創意工夫の余地を残せます」。 + +Rustでは、この仕様の一部を複数の成果物で表現でき、その中には実行可能なものもあります。実行可能であることは付随的な性質であり、仕様である理由ではありません。 + +* 文章は意図された意味を述べる +* トレイトは利用可能な基本操作を述べる +* 拡張は導出方法を述べる +* 法則は要求される等式を述べる +* インタープリターは実現可能性を示す +* テストは有限の証拠を提供する + +具体的な仕組みよりも、意味と法則に権限を持たせて、これらを併せて読みます。 + +## さらに読む {#further-reading} + +* [Denotational Design:プログラムから意味へ(BayHac 2014)](https://github.com/conal/talk-2014-bayhac-denotational-design) +* [型クラスの準同型によるDenotational Design](http://conal.net/papers/type-class-morphisms/) +* [Conal Elliottの著作と講演](http://conal.net/) diff --git a/src/denotational-design/design.ko.md b/src/denotational-design/design.ko.md new file mode 100644 index 0000000..24237dc --- /dev/null +++ b/src/denotational-design/design.ko.md @@ -0,0 +1,168 @@ + + +# 표시적 설계 {#denotational-design} + +```admonish tip title="관련 항목" +의미론적 관점: [표시와 합성성](denotations.md), [법칙과 해석](laws-and-interpretations.md) +Rust에서 의미로 설계하기: [케이퍼빌리티 대수](../rust-dd/capability-algebras.md), [파생 의미와 합성](../rust-dd/derived-meaning.md) +``` + +```admonish note title="핵심 아이디어" +표시적 설계는 단순하고 합성 가능하며 구현에 독립적인 의미에서 프로그래밍 인터페이스를 도출하여, 사후에 인터페이스를 설명하는 대신 의미론이 설계를 이끌게 합니다. +``` + +표시적 설계란 단순하고 합성 가능하며 구현에 독립적인 의미에서 프로그래밍 인터페이스를 도출하는 방법입니다. + +이 방법론은 [Conal Elliott](http://conal.net/)가 개발하고 이름 붙였습니다. 핵심은 기존 언어나 API에 의미론을 부여하는 데 그치지 않습니다. 의미론이 API 자체의 설계를 이끌도록 하는 것입니다. + +## 설계 순환 {#the-design-loop} + +다음 순서를 따르세요: + +1. 의미론적 영역을 선택합니다. +2. 그 영역에서 중요한 구조를 파악합니다. +3. 기본 연산의 어휘를 작게 선택합니다. +4. 유용한 연산을 합성적으로 도출합니다. +5. 그 연산이 따르는 법칙을 명시합니다. +6. 하나 이상의 표현을 선택합니다. +7. 구조를 보존하는 해석을 구현합니다. +8. 법칙, 모델, 시나리오를 이용해 검증합니다. + +표현 우선 설계는 흔히 6단계에서 시작한 뒤 1~5단계를 사후에 재구성하려 합니다. + +## 분기 대수 설계 {#designing-a-branch-algebra} + +분기 위치로 돌아가 봅시다. 원하는 의미는 이진 분기 구조 안의 유한한 경로입니다. + +가능한 기본 대수의 한 예는 다음과 같습니다: + +$$ \begin{aligned} \operatorname{root} &\colon \mathtt{()} \to \mathsf{Branch} \\ \operatorname{grow} &\colon \mathsf{Branch} \times \mathsf{Direction} \to \mathsf{Branch} \\ \operatorname{path} &\colon \mathsf{Branch} \times \mathsf{Branch} \rightharpoonup \operatorname{List}(\mathsf{Direction}) \end{aligned} $$ + +부분 함수 $\rightharpoonup$는 첫 번째 분기가 두 번째 분기의 조상일 때만 경로를 관찰할 수 있음을 뜻합니다. + +여기서 유용한 연산을 도출할 수 있습니다: + +$$ \begin{aligned} \operatorname{left}(b) &= \operatorname{grow}(b, \mathsf{Left}) \\ \operatorname{right}(b) &= \operatorname{grow}(b, \mathsf{Right}) \\ \operatorname{is\_ancestor}(a,b) &\iff \operatorname{path}(a,b)\ \text{is defined} \\ \operatorname{from\_path}(d_s) &= \operatorname{fold}(\operatorname{grow}, \operatorname{root}, d_s) \end{aligned} $$ + +이 대수는 벡터, 정수, 분수, 데이터베이스 키, 바이트를 언급하지 않습니다. 그런 선택은 나중에 합니다. + +## 편의보다 구조를 먼저 {#structure-before-convenience} + +기본 어휘는 후속 코드가 의존하는 구조를 드러내야 합니다. 특정 구현에서 편리하게 쓸 수 있는 메서드를 모두 모아 놓은 집합이어서는 안 됩니다. + +````admonish warning title="표현 우선 기본 연산은 피하세요" +이 트레이트는 저장 배치, 설정 위치, 비트 표현, 복합 작업 흐름을 한데 묶습니다. 분기의 의미를 분리해 드러내지 못합니다: + +```rust,noplayground +trait BranchManager { + // not recommended: exposes machinery, not semantic observations + fn storage(&self) -> &BranchTable; + fn config(&self) -> &BranchConfig; + fn raw_bits(&self) -> &[u64]; + fn grow_and_save(&mut self, right: bool); +} +``` +```` + +선택한 영역에 효과가 포함된다면 의미론적 API에도 효과가 들어갈 수 있습니다. 규칙은 “모든 것이 순수해야 한다”가 아닙니다. “각 기본 연산은 일관된 의미를 명시해야 한다”입니다. + +## 인코딩은 방법론이 아닙니다 {#encoding-is-not-methodology} + +표시적 설계에 다음은 필수 조건이 아닙니다: + +* Haskell +* 태그리스 파이널 인코딩 +* 객체 대수 +* 자유 모나드 +* 단일 AST +* 순수 함수만 사용하기 +* 모든 API에서 범주론 용어 사용하기 + +이들은 유용한 인코딩이나 설명 도구일 수 있지만, 어느 것도 방법론을 정의하지는 않습니다. + +```admonish note title="Rust 인코딩" +Rust에서는 작은 트레이트, 연관 타입, 확장 메서드, 제네릭 함수, 일차 프로그램 값이 실용적인 인코딩입니다. 그 가치는 명확한 의미론적 설계를 보존하는지에 달려 있습니다. +``` + +## 타입 클래스 사상 {#type-class-morphisms} + +이 방법을 이해하는 한 가지 방식은 구조를 보존하는 사상으로 바라보는 것입니다. + +인터페이스가 의미론적 대수를 설명한다고 가정해 봅시다. 구현은 추상 값과 연산을 구체적인 표현으로 대응시킵니다. 올바른 구현은 관련 연산과 법칙을 보존해야 합니다. + +`encode`가 추상 분기를 구체적인 기반 집합으로 대응시킨다면, 확장의 보존은 다음과 같습니다: + +$$ \operatorname{encode}(\operatorname{grow}(b,d)) = \operatorname{grow}_{\mathsf{concrete}}(\operatorname{encode}(b),d) $$ + +구현은 이름만 맞춘 메서드 모음이 아닙니다. 대수적 구조를 따르는 사상이어야 합니다. + +## 좋은 추상화의 조건 {#what-counts-as-a-good-abstraction} + +좋은 표시적 설계 추상화에는 다음과 같은 특성이 있습니다: + +* 값이 단순하고 의도된 의미를 가집니다. +* 기본 연산이 의미론적 관찰이나 구성을 드러냅니다. +* 더 큰 동작을 기본 연산에서 도출합니다. +* 법칙이 특정 표현에 의존하지 않습니다. +* 독립적인 구현이 이를 해석할 수 있습니다. +* 작동 세부 사항은 관련성이 생길 때만 나타납니다. + +작다는 것만으로는 충분하지 않습니다. `get_manager()`만 노출하는 작은 트레이트도 여전히 표현 우선입니다. 연산들이 일관된 의미 구조를 이룬다면 더 큰 대수를 정당화할 수 있습니다. + +## 의미 값과 추상 기반 집합 {#semantic-values-and-abstract-carriers} + +구체 타입을 모두 명세에서 배제해야 하는 것은 아닙니다. + +인터프리터가 기반 집합을 선택해야 할 때는 연관 타입을 사용하세요: + +```rust,noplayground +trait BranchAlg { + type Branch; +} +``` + +안정적인 의미 어휘라면 구체 타입을 사용하세요: + +```rust,noplayground +enum Direction { + Left, + Right, +} +``` + +추상은 좋고 구체는 나쁘다는 구분이 아닙니다. 의미 어휘와 우연히 선택된 기계 표현의 구분입니다. + +## 명세는 표시이며 실행될 필요가 없습니다 {#the-specification-is-the-denotation-and-it-need-not-execute} + +명세는 표시, 즉 각 구성 요소에 부여되는 수학적 의미입니다. 효율성은 물론 실행 가능성의 제약에서도 자유롭다는 점이 그 힘입니다. + +```admonish quote title="Conal Elliott" +표시는 효율성의 제약이나 방해, 심지어 실행 가능성의 제약도 받지 않으므로 구현보다 정의하기가 훨씬 쉽고 더 많은 통찰을 주는 경우가 많습니다. + +— [표시적 설계: 의미에서 프로그램으로 (LambdaJam 2015)](https://github.com/conal/talk-2014-lambdajam-denotational-design) +``` + +대표적인 예는 FRP(함수형 반응형 프로그래밍)입니다. `Behavior a`은 연속 시간의 함수로 정의됩니다. + +$$\llbracket\,\cdot\,\rrbracket : \mathsf{Behavior}\ a \to (\mathbb{R} \to a)$$ + +그 모델은 정확하지만 실행할 수 없습니다. 실수를 모두 열거할 수는 없기 때문입니다. 마찬가지로 프로그램이 결과의 집합을 나타낼 수도 있습니다. 어느 모델도 실행되지는 않으며, 바로 그 점이 핵심입니다. 의미는 계산 방식이 아니라 단순성과 정확성에 따라 선택합니다. + +실행 가능성과 효율성은 전적으로 별도 산출물인 *구현*에 맡깁니다. 의미로 되돌아가는 준동형 법칙(타입 클래스 사상)이 구현의 정확성을 뒷받침합니다. 의미 함수는 각 구문 합성을 대응하는 의미 합성으로 옮겨야 합니다. Conal의 표현을 빌리면, 표시는 “무엇을 구현할지 *정확히* 명확하게 정의하면서, *어떻게* 구현할지는 창의적으로 정할 여지를 넉넉히 남깁니다.” + +Rust에서는 여러 산출물이 이 명세의 일부를 표현하며, 그중 일부는 우연히 실행 가능하기도 합니다. 실행 가능성은 부수적인 특성이지, 그것을 명세로 만드는 조건은 아닙니다: + +* 산문은 의도된 의미를 명시합니다 +* 트레이트는 사용할 수 있는 기본 연산을 명시합니다 +* 확장은 도출 과정을 명시합니다 +* 법칙은 필요한 등식을 명시합니다 +* 인터프리터는 실현 가능성을 보여 줍니다 +* 테스트는 유한한 증거를 제공합니다 + +구체적인 구현 장치보다 의미와 법칙에 더 큰 권위를 두고 함께 읽으세요. + +## 더 읽을거리 {#further-reading} + +* [표시적 설계: 프로그램에서 의미로 (BayHac 2014)](https://github.com/conal/talk-2014-bayhac-denotational-design) +* [타입 클래스 사상을 이용한 표시적 설계](http://conal.net/papers/type-class-morphisms/) +* [Conal Elliott의 글과 강연](http://conal.net/) diff --git a/src/denotational-design/design.ru.md b/src/denotational-design/design.ru.md new file mode 100644 index 0000000..3857bdb --- /dev/null +++ b/src/denotational-design/design.ru.md @@ -0,0 +1,168 @@ + + +# Денотационное проектирование {#denotational-design} + +```admonish tip title="Связанные материалы" +«Семантический взгляд»: [Денотации и композиционность](denotations.md), [Законы и интерпретации](laws-and-interpretations.md) +«Проектирование на основе смысла в Rust»: [Алгебры возможностей](../rust-dd/capability-algebras.md), [Производный смысл и композиция](../rust-dd/derived-meaning.md) +``` + +```admonish note title="Основная идея" +Денотационное проектирование выводит интерфейс программирования из простых композиционных значений, независимых от реализации. Благодаря этому семантика направляет проектирование, а не описывает интерфейс задним числом. +``` + +Денотационное проектирование — это практика выведения интерфейса программирования из простых композиционных значений, не зависящих от реализации. + +Методологию разработал и назвал [Конал Эллиотт](http://conal.net/). Её основной ход — не просто назначить семантику уже существующему языку или API, а позволить семантике направлять проектирование самого API. + +## Цикл проектирования {#the-design-loop} + +Соблюдайте такой порядок: + +1. Выберите семантическую область. +2. Определите значимую для этой области структуру. +3. Выберите небольшой словарь примитивных операций. +4. Композиционно выведите полезные операции. +5. Сформулируйте законы, которым подчиняются эти операции. +6. Выберите одно или несколько представлений. +7. Реализуйте интерпретации, сохраняющие структуру. +8. Проверьте их с помощью законов, моделей и сценариев. + +Проектирование от представления обычно начинается с шага 6, а затем пытается восстановить шаги 1–5. + +## Проектирование алгебры ветвлений {#designing-a-branch-algebra} + +Вернёмся к позициям в ветвлении. Требуемый смысл — конечный путь в бинарной ветвящейся структуре. + +Один из возможных вариантов примитивной алгебры: + +$$ \begin{aligned} \operatorname{root} &\colon \mathtt{()} \to \mathsf{Branch} \\ \operatorname{grow} &\colon \mathsf{Branch} \times \mathsf{Direction} \to \mathsf{Branch} \\ \operatorname{path} &\colon \mathsf{Branch} \times \mathsf{Branch} \rightharpoonup \operatorname{List}(\mathsf{Direction}) \end{aligned} $$ + +Частичная стрелка $\rightharpoonup$ означает, что наблюдение пути определено, только если первая ветвь является предком второй. + +Отсюда следуют полезные операции: + +$$ \begin{aligned} \operatorname{left}(b) &= \operatorname{grow}(b, \mathsf{Left}) \\ \operatorname{right}(b) &= \operatorname{grow}(b, \mathsf{Right}) \\ \operatorname{is\_ancestor}(a,b) &\iff \operatorname{path}(a,b)\ \text{is defined} \\ \operatorname{from\_path}(d_s) &= \operatorname{fold}(\operatorname{grow}, \operatorname{root}, d_s) \end{aligned} $$ + +В этой алгебре нет упоминаний векторов, целых чисел, дробей, ключей базы данных или байтов. Эти решения принимаются позднее. + +## Сначала структура, затем удобство {#structure-before-convenience} + +Примитивный словарь должен раскрывать структуру, от которой зависит последующий код. Это не должен быть набор всех удобных методов, доступных в одной реализации. + +````admonish warning title="Откажитесь от примитивов, зависящих от представления" +Этот трейт объединяет схему хранения, место размещения конфигурации, битовое представление и составной рабочий процесс. Он не выделяет смысл ветвления: + +```rust,noplayground +trait BranchManager { + // not recommended: exposes machinery, not semantic observations + fn storage(&self) -> &BranchTable; + fn config(&self) -> &BranchConfig; + fn raw_bits(&self) -> &[u64]; + fn grow_and_save(&mut self, right: bool); +} +``` +```` + +Семантический API всё же может включать эффекты, если они входят в выбранную область. Правило не в том, что «всё должно быть чистым», а в том, что «каждый примитив должен выражать связный смысл». + +## Кодирование — не методология {#encoding-is-not-methodology} + +Денотационное проектирование не требует: + +* Haskell +* кодирования tagless-final +* объектных алгебр +* свободных монад +* единственного AST +* только чистых функций +* терминологии теории категорий в каждом API + +Всё это может быть полезными способами кодирования или средствами объяснения. Но ничто из перечисленного не определяет метод. + +```admonish note title="Способы кодирования в Rust" +В Rust небольшие трейты, ассоциированные типы, методы-расширения, обобщённые функции и значения программ первого порядка служат практическими способами кодирования. Их польза зависит от того, сохраняют ли они ясный семантический замысел. +``` + +## Морфизмы классов типов {#type-class-morphisms} + +Один из способов понять этот метод — рассмотреть отображения, сохраняющие структуру. + +Предположим, интерфейс описывает семантическую алгебру. Реализация отображает её абстрактные значения и операции в конкретное представление. Корректная реализация должна сохранять нужные операции и законы. + +Если `encode` отображает абстрактные ветви в конкретный носитель, сохранение операции роста выглядит так: + +$$ \operatorname{encode}(\operatorname{grow}(b,d)) = \operatorname{grow}_{\mathsf{concrete}}(\operatorname{encode}(b),d) $$ + +Реализация — не просто набор методов с совпадающими именами. От неё ожидается, что она будет морфизмом, сохраняющим алгебраическую структуру. + +## Признаки хорошей абстракции {#what-counts-as-a-good-abstraction} + +Удачная абстракция в рамках DD обладает несколькими свойствами: + +* Её значения имеют простой предполагаемый смысл. +* Её примитивы выражают семантические наблюдения или построения. +* Более сложное поведение выводится из этих примитивов. +* Её законы не зависят от конкретного представления. +* Её можно интерпретировать в независимых реализациях. +* Операционные детали появляются только там, где становятся значимы. + +Одной малости недостаточно. Крошечный трейт, открывающий `get_manager()`, всё ещё может зависеть от представления. Более крупная алгебра оправдана, если её операции образуют единую связную семантическую структуру. + +## Семантические значения и абстрактные носители {#semantic-values-and-abstract-carriers} + +Не каждый конкретный тип нужно исключать из спецификации. + +Используйте ассоциированный тип, если интерпретатор должен выбирать носитель: + +```rust,noplayground +trait BranchAlg { + type Branch; +} +``` + +Используйте конкретный тип, если он входит в устойчивый семантический словарь: + +```rust,noplayground +enum Direction { + Left, + Right, +} +``` + +Различие проходит не между «абстрактное — хорошо, конкретное — плохо», а между семантическим словарём и случайными особенностями машинного представления. + +## Спецификация — это денотация, и ей не обязательно исполняться {#the-specification-is-the-denotation-and-it-need-not-execute} + +Спецификация — это денотация: математический смысл, присвоенный каждой конструкции. Её сила в том, что она свободна от ограничений эффективности и даже исполнимости. + +```admonish quote title="Конал Эллиотт" +Часто определить денотацию гораздо проще и поучительнее, чем реализацию, поскольку при этом не приходится учитывать ограничения или отвлекающие факторы эффективности и даже исполнимости. + +— [Denotational Design: from meanings to programs (LambdaJam 2015)](https://github.com/conal/talk-2014-lambdajam-denotational-design) +``` + +Канонический пример — FRP (функциональное реактивное программирование): `Behavior a` задаётся как функция непрерывного времени, + +$$\llbracket\,\cdot\,\rrbracket : \mathsf{Behavior}\ a \to (\mathbb{R} \to a)$$ + +Эта модель точна, но не исполнима — перечислить вещественные числа невозможно. Программа также может обозначать множество результатов; ни одна из этих моделей не выполняется, и в этом смысл. Значение выбирают ради простоты и точности, а не с оглядкой на то, как оно будет вычисляться. + +Исполнимость и эффективность целиком относятся к *реализации* — отдельному артефакту, корректность которого поддерживают законы гомоморфизма (морфизмы классов типов), связывающие его со смыслом: функция смысла должна переводить каждую композицию синтаксиса в соответствующую семантическую композицию. Как говорит Конал, денотация даёт «однозначное определение того, *что* именно нужно реализовать, оставляя при этом большой простор для творчества в том, *как* это сделать». + +В Rust разные артефакты выражают отдельные части этой спецификации, и некоторые из них можно исполнять. Исполнимость здесь случайна и сама по себе не превращает артефакт в спецификацию: + +* проза формулирует предполагаемый смысл +* трейты задают доступные примитивы +* методы-расширения задают производные операции +* законы задают требуемые равенства +* интерпретаторы демонстрируют реализуемость +* тесты дают конечное свидетельство + +Рассматривайте их вместе, отдавая смыслу и законам приоритет над конкретными механизмами. + +## Дополнительная литература {#further-reading} + +* [Denotational Design: from programs to meanings (BayHac 2014)](https://github.com/conal/talk-2014-bayhac-denotational-design) +* [Denotational design with type class morphisms](http://conal.net/papers/type-class-morphisms/) +* [Работы и доклады Конала Эллиотта](http://conal.net/) diff --git a/src/denotational-design/design.uk.md b/src/denotational-design/design.uk.md new file mode 100644 index 0000000..58d92ee --- /dev/null +++ b/src/denotational-design/design.uk.md @@ -0,0 +1,168 @@ + + +# Денотаційне проєктування {#denotational-design} + +```admonish tip title="Пов’язані матеріали" +Семантичний погляд: [Денотації та композиційність](denotations.md), [Закони та інтерпретації](laws-and-interpretations.md) +Проєктування від значення в Rust: [Алгебри можливостей](../rust-dd/capability-algebras.md), [Похідне значення та композиція](../rust-dd/derived-meaning.md) +``` + +```admonish note title="Основна ідея" +Денотаційне проєктування виводить програмний інтерфейс із простих композиційних значень, незалежних від реалізації, завдяки чому семантика спрямовує проєктування, а не описує інтерфейс постфактум. +``` + +Денотаційне проєктування — це практика виведення програмного інтерфейсу з простих композиційних значень, незалежних від реалізації. + +Методологію розробив і назвав [Конал Елліотт](http://conal.net/). Її головний крок полягає не просто в наданні семантики вже наявній мові чи API. Семантика має спрямовувати проєктування самого API. + +## Цикл проєктування {#the-design-loop} + +Дотримуйтеся такого порядку: + +1. Виберіть семантичну область. +2. Визначте структуру, важливу в цій області. +3. Виберіть невеликий набір примітивних операцій. +4. Композиційно виведіть корисні операції. +5. Сформулюйте закони, яким підпорядковуються ці операції. +6. Виберіть одне або кілька представлень. +7. Реалізуйте інтерпретації, що зберігають цю структуру. +8. Перевірте їх за допомогою законів, моделей і сценаріїв. + +Проєктування, у якому спершу визначають представлення, зазвичай починається з кроку 6, а кроки 1–5 намагаються відновити вже потім. + +## Проєктування алгебри розгалужень {#designing-a-branch-algebra} + +Повернімося до позицій у розгалуженні. Потрібне значення — це скінченний шлях у бінарній структурі розгалуження. + +Можлива примітивна алгебра: + +$$ \begin{aligned} \operatorname{root} &\colon \mathtt{()} \to \mathsf{Branch} \\ \operatorname{grow} &\colon \mathsf{Branch} \times \mathsf{Direction} \to \mathsf{Branch} \\ \operatorname{path} &\colon \mathsf{Branch} \times \mathsf{Branch} \rightharpoonup \operatorname{List}(\mathsf{Direction}) \end{aligned} $$ + +Часткова стрілка $\rightharpoonup$ означає, що спостереження шляху існує лише тоді, коли перша гілка є предком другої. + +Звідси випливають корисні операції: + +$$ \begin{aligned} \operatorname{left}(b) &= \operatorname{grow}(b, \mathsf{Left}) \\ \operatorname{right}(b) &= \operatorname{grow}(b, \mathsf{Right}) \\ \operatorname{is\_ancestor}(a,b) &\iff \operatorname{path}(a,b)\ \text{is defined} \\ \operatorname{from\_path}(d_s) &= \operatorname{fold}(\operatorname{grow}, \operatorname{root}, d_s) \end{aligned} $$ + +Ця алгебра не згадує вектори, цілі числа, дроби, ключі бази даних чи байти. Такі рішення ухвалюють пізніше. + +## Спершу структура, потім зручність {#structure-before-convenience} + +Примітивна термінологія має виявляти структуру, від якої залежить подальший код. Це не має бути набір усіх зручних методів, доступних в одній реалізації. + +````admonish warning title="Відкидайте примітиви, що виходять із представлення" +Цей трейт поєднує організацію сховища, розташування конфігурації, бітове представлення та складений робочий процес. Він не виокремлює значення розгалуження: + +```rust,noplayground +trait BranchManager { + // not recommended: exposes machinery, not semantic observations + fn storage(&self) -> &BranchTable; + fn config(&self) -> &BranchConfig; + fn raw_bits(&self) -> &[u64]; + fn grow_and_save(&mut self, right: bool); +} +``` +```` + +Семантичний API усе ще може містити ефекти, якщо ефекти належать до вибраної області. Правило не в тому, що «все має бути чистим». Кожен примітив має виражати цілісне значення. + +## Кодування — це не методологія {#encoding-is-not-methodology} + +Денотаційне проєктування не вимагає: + +* Haskell +* кодування tagless-final +* об’єктних алгебр +* вільних монад +* єдиного AST +* лише чистих функцій +* термінології теорії категорій у кожному API + +Це можуть бути корисні засоби кодування чи пояснення, але жоден із них не визначає методологію. + +```admonish note title="Кодування в Rust" +У Rust практичними способами кодування є невеликі трейти, асоційовані типи, методи-розширення, узагальнені функції та значення програм першого порядку. Їхня користь залежить від того, чи зберігають вони чіткий семантичний задум. +``` + +## Морфізми типів-класів {#type-class-morphisms} + +Один зі способів зрозуміти цю методологію — через відображення, що зберігають структуру. + +Припустімо, інтерфейс описує семантичну алгебру. Реалізація відображає її абстрактні значення й операції в конкретне представлення. Коректна реалізація має зберігати відповідні операції та закони. + +Якщо `encode` відображає абстрактні гілки в конкретний носій, збереження розширення має такий вигляд: + +$$ \operatorname{encode}(\operatorname{grow}(b,d)) = \operatorname{grow}_{\mathsf{concrete}}(\operatorname{encode}(b),d) $$ + +Реалізація — не просто набір методів зі схожими назвами. Від неї очікується, що вона буде морфізмом, який зберігає алгебраїчну структуру. + +## Що робить абстракцію вдалою? {#what-counts-as-a-good-abstraction} + +Вдала абстракція денотаційного проєктування має кілька властивостей: + +* Її значення мають простий задуманий сенс. +* Її примітиви виражають семантичні спостереження чи побудови. +* Складніша поведінка виводиться з цих примітивів. +* Її закони не залежать від одного представлення. +* Її можуть інтерпретувати незалежні реалізації. +* Операційні деталі з’являються лише тоді, коли стають доречними. + +Малої кількості операцій недостатньо. Крихітний трейт, що відкриває `get_manager()`, усе ще може виходити з представлення. Більша алгебра виправдана, якщо її операції утворюють одну цілісну семантичну структуру. + +## Семантичні значення й абстрактні носії {#semantic-values-and-abstract-carriers} + +Не кожен конкретний тип потрібно виключати зі специфікації. + +Використовуйте асоційований тип, коли носій має вибирати інтерпретатор: + +```rust,noplayground +trait BranchAlg { + type Branch; +} +``` + +Використовуйте конкретний тип, коли він є сталою частиною семантичної термінології: + +```rust,noplayground +enum Direction { + Left, + Right, +} +``` + +Розрізнення не зводиться до «абстрактне — добре, конкретне — погано». Йдеться про семантичну термінологію на противагу випадковому машинному представленню. + +## Специфікація є денотацією й не мусить виконуватися {#the-specification-is-the-denotation-and-it-need-not-execute} + +Специфікація — це денотація, тобто математичне значення, призначене кожній конструкції. Її сила полягає в тому, що вона не обмежена вимогами ефективності й навіть можливістю виконання. + +```admonish quote title="Конал Елліотт" +Часто визначити денотацію набагато легше й наочніше, ніж реалізацію, адже на денотацію не впливають обмеження й відволікальні чинники, пов’язані з ефективністю чи навіть можливістю виконання. + +— [Denotational Design: from meanings to programs (LambdaJam 2015)](https://github.com/conal/talk-2014-lambdajam-denotational-design) +``` + +Канонічний приклад — FRP (функціональне реактивне програмування): `Behavior a` визначається як функція неперервного часу, + +$$\llbracket\,\cdot\,\rrbracket : \mathsf{Behavior}\ a \to (\mathbb{R} \to a)$$ + +Ця модель точна, але невиконувана — дійсні числа неможливо перелічити. Так само програма може позначати множину результатів; жодна з цих моделей не виконується, і в цьому їхній сенс. Значення вибирають заради простоти й точності, а не заради способу обчислення. + +Вимоги до виконання й ефективності повністю покладаються на *реалізацію* — окремий артефакт, коректність якого підтримують закони гомоморфізму (морфізми типів-класів), що пов’язують його зі значенням: функція значення має переводити кожну синтаксичну композицію у відповідну семантичну. Як каже Конал, денотація дає «однозначне визначення того, *що саме* потрібно реалізувати, залишаючи водночас великий простір для творчого вибору щодо того, *як* це зробити». + +У Rust частини цієї специфікації виражають різні артефакти, деякі з яких можуть виконуватися. Можливість виконання — побічна властивість, а не те, що робить артефакт специфікацією: + +* проза формулює задумане значення +* трейти визначають доступні примітиви +* розширення описують похідні конструкції +* закони визначають потрібні рівності +* інтерпретатори демонструють можливість реалізації +* тести надають скінченні свідчення + +Розглядайте їх разом, надаючи значенню й законам вищий пріоритет, ніж конкретним механізмам. + +## Додаткові матеріали {#further-reading} + +* [Denotational Design: from programs to meanings (BayHac 2014)](https://github.com/conal/talk-2014-bayhac-denotational-design) +* [Denotational design with type class morphisms](http://conal.net/papers/type-class-morphisms/) +* [Conal Elliott's writings and talks](http://conal.net/) diff --git a/src/denotational-design/design.vi.md b/src/denotational-design/design.vi.md new file mode 100644 index 0000000..7460baa --- /dev/null +++ b/src/denotational-design/design.vi.md @@ -0,0 +1,168 @@ + + +# Thiết kế theo ngữ nghĩa {#denotational-design} + +```admonish tip title="Liên quan" +Góc nhìn ngữ nghĩa: [Ngữ nghĩa và tính hợp thành](denotations.md), [Định luật và cách diễn giải](laws-and-interpretations.md) +Thiết kế theo ngữ nghĩa trong Rust: [Các đại số năng lực](../rust-dd/capability-algebras.md), [Ý nghĩa suy ra và phép hợp thành](../rust-dd/derived-meaning.md) +``` + +```admonish note title="Ý tưởng cốt lõi" +Thiết kế theo ngữ nghĩa suy ra giao diện lập trình từ các ý nghĩa đơn giản, có thể hợp thành và độc lập với triển khai, để ngữ nghĩa dẫn dắt thiết kế thay vì chỉ mô tả giao diện sau khi đã tạo ra. +``` + +Thiết kế theo ngữ nghĩa là phương pháp suy ra giao diện lập trình từ các ý nghĩa đơn giản, có thể hợp thành và độc lập với cách triển khai. + +Phương pháp này do [Conal Elliott](http://conal.net/) phát triển và đặt tên. Bước cốt lõi không chỉ là gán ngữ nghĩa cho một ngôn ngữ hay API có sẵn, mà là để ngữ nghĩa dẫn dắt chính việc thiết kế API. + +## Vòng lặp thiết kế {#the-design-loop} + +Thực hiện theo thứ tự này: + +1. Chọn miền ngữ nghĩa. +2. Xác định cấu trúc quan trọng trong miền đó. +3. Chọn tập từ vựng nhỏ gồm các phép toán nguyên thủy. +4. Suy ra các phép toán hữu ích bằng tính hợp thành. +5. Phát biểu các định luật mà những phép toán đó tuân theo. +6. Chọn một hoặc nhiều cách biểu diễn. +7. Triển khai các cách diễn giải bảo toàn cấu trúc. +8. Thẩm định chúng bằng định luật, mô hình và tình huống. + +Thiết kế ưu tiên biểu diễn thường bắt đầu ở bước 6 rồi cố khôi phục các bước 1–5 sau đó. + +## Thiết kế đại số nhánh {#designing-a-branch-algebra} + +Hãy quay lại các vị trí nhánh. Ý nghĩa mong muốn là một đường đi hữu hạn trong cấu trúc phân nhánh nhị phân. + +Một đại số nguyên thủy có thể là: + +$$ \begin{aligned} \operatorname{root} &\colon \mathtt{()} \to \mathsf{Branch} \\ \operatorname{grow} &\colon \mathsf{Branch} \times \mathsf{Direction} \to \mathsf{Branch} \\ \operatorname{path} &\colon \mathsf{Branch} \times \mathsf{Branch} \rightharpoonup \operatorname{List}(\mathsf{Direction}) \end{aligned} $$ + +Ánh xạ từng phần $\rightharpoonup$ có nghĩa là chỉ tồn tại phép quan sát đường đi khi nhánh thứ nhất là tổ tiên của nhánh thứ hai. + +Từ đó có các phép toán hữu ích: + +$$ \begin{aligned} \operatorname{left}(b) &= \operatorname{grow}(b, \mathsf{Left}) \\ \operatorname{right}(b) &= \operatorname{grow}(b, \mathsf{Right}) \\ \operatorname{is\_ancestor}(a,b) &\iff \operatorname{path}(a,b)\ \text{is defined} \\ \operatorname{from\_path}(d_s) &= \operatorname{fold}(\operatorname{grow}, \operatorname{root}, d_s) \end{aligned} $$ + +Đại số này không nhắc đến vectơ, số nguyên, phân số, khóa cơ sở dữ liệu hay byte. Những lựa chọn đó được quyết định sau. + +## Cấu trúc trước sự tiện lợi {#structure-before-convenience} + +Tập từ vựng nguyên thủy cần làm lộ rõ cấu trúc mà mã phía sau phụ thuộc vào. Nó không nên là tập hợp mọi phương thức tiện lợi có trong một cách triển khai. + +````admonish warning title="Loại bỏ các phép toán nguyên thủy ưu tiên biểu diễn" +Đặc trưng này gộp cách sắp xếp lưu trữ, vị trí cấu hình, biểu diễn bit và quy trình công việc kết hợp. Nó không tách riêng ý nghĩa của nhánh: + +```rust,noplayground +trait BranchManager { + // not recommended: exposes machinery, not semantic observations + fn storage(&self) -> &BranchTable; + fn config(&self) -> &BranchConfig; + fn raw_bits(&self) -> &[u64]; + fn grow_and_save(&mut self, right: bool); +} +``` +```` + +API ngữ nghĩa vẫn có thể bao gồm hiệu ứng nếu hiệu ứng thuộc miền được chọn. Quy tắc không phải là “mọi thứ đều phải thuần”. Quy tắc là “mọi phép toán nguyên thủy phải nêu một ý nghĩa mạch lạc”. + +## Mã hóa không phải phương pháp {#encoding-is-not-methodology} + +Thiết kế theo ngữ nghĩa không đòi hỏi: + +* Haskell +* mã hóa tagless-final +* đại số đối tượng +* monad tự do +* một AST duy nhất +* chỉ dùng hàm thuần +* thuật ngữ lý thuyết phạm trù trong mọi API + +Những thứ này có thể là cách mã hóa hoặc công cụ giải thích hữu ích. Không thứ nào định nghĩa phương pháp. + +```admonish note title="Các cách mã hóa trong Rust" +Trong Rust, đặc trưng nhỏ, kiểu liên kết, phương thức mở rộng, hàm tổng quát và giá trị chương trình bậc nhất là các cách mã hóa thực tiễn. Giá trị của chúng tùy thuộc vào việc chúng có bảo toàn thiết kế ngữ nghĩa rõ ràng hay không. +``` + +## Ánh xạ đồng cấu của lớp kiểu {#type-class-morphisms} + +Một cách hiểu phương pháp này là qua các ánh xạ bảo toàn cấu trúc. + +Giả sử một giao diện mô tả đại số ngữ nghĩa. Cách triển khai ánh xạ các giá trị và phép toán trừu tượng vào một cách biểu diễn cụ thể. Cách triển khai hợp lệ phải bảo toàn các phép toán và định luật liên quan. + +Nếu `encode` ánh xạ các nhánh trừu tượng vào một đối tượng mang cụ thể, thì tính bảo toàn phép mở rộng có dạng: + +$$ \operatorname{encode}(\operatorname{grow}(b,d)) = \operatorname{grow}_{\mathsf{concrete}}(\operatorname{encode}(b),d) $$ + +Cách triển khai không chỉ là tập hợp phương thức có tên tương ứng. Nó được kỳ vọng là một đồng cấu tôn trọng cấu trúc đại số. + +## Thế nào là một trừu tượng hóa tốt {#what-counts-as-a-good-abstraction} + +Một phép trừu tượng hóa DD tốt có một số đặc tính: + +* Các giá trị có ý nghĩa dự định đơn giản. +* Các phép toán nguyên thủy bộc lộ những quan sát hoặc kiến tạo ngữ nghĩa. +* Hành vi phức tạp hơn được suy ra từ các phép toán nguyên thủy đó. +* Các định luật không phụ thuộc vào một cách biểu diễn duy nhất. +* Các cách triển khai độc lập có thể diễn giải nó. +* Chi tiết vận hành chỉ xuất hiện khi chúng trở nên liên quan. + +Chỉ nhỏ gọn thôi thì chưa đủ. Một đặc trưng bé xíu chỉ phơi bày `get_manager()` vẫn ưu tiên biểu diễn. Một đại số lớn hơn có thể hợp lý khi các phép toán của nó tạo thành một cấu trúc ngữ nghĩa nhất quán. + +## Giá trị ngữ nghĩa và đối tượng mang trừu tượng {#semantic-values-and-abstract-carriers} + +Không phải mọi kiểu cụ thể đều bị cấm trong đặc tả. + +Dùng kiểu liên kết khi bộ diễn giải cần chọn đối tượng mang: + +```rust,noplayground +trait BranchAlg { + type Branch; +} +``` + +Dùng kiểu cụ thể khi nó là từ vựng ngữ nghĩa ổn định: + +```rust,noplayground +enum Direction { + Left, + Right, +} +``` + +Sự phân biệt không phải “trừu tượng tốt, cụ thể xấu”, mà là giữa từ vựng ngữ nghĩa và cách biểu diễn máy tình cờ được chọn. + +## Đặc tả chính là ngữ nghĩa chỉ định, và không nhất thiết phải thực thi {#the-specification-is-the-denotation-and-it-need-not-execute} + +Đặc tả chính là ngữ nghĩa chỉ định: ý nghĩa toán học được gán cho từng cấu trúc. Sức mạnh của nó đến từ việc không bị ràng buộc bởi hiệu năng, thậm chí bởi khả năng thực thi. + +```admonish quote title="Conal Elliott" +Việc định nghĩa ngữ nghĩa chỉ định thường dễ dàng và khai sáng hơn nhiều so với việc triển khai, vì nó không bị ràng buộc hay phân tâm bởi hiệu năng, thậm chí bởi khả năng thực thi. + +— [Denotational Design: from meanings to programs (LambdaJam 2015)](https://github.com/conal/talk-2014-lambdajam-denotational-design) +``` + +Ví dụ kinh điển là FRP (Lập trình phản ứng hàm): một `Behavior a` được định nghĩa như hàm theo thời gian liên tục, + +$$\llbracket\,\cdot\,\rrbracket : \mathsf{Behavior}\ a \to (\mathbb{R} \to a)$$ + +Mô hình đó chính xác nhưng không thể thực thi — ta không thể liệt kê các số thực. Tương tự, chương trình có thể biểu thị một tập kết quả; cả hai mô hình đều không chạy được, và đó chính là chủ ý. Ý nghĩa được chọn vì sự đơn giản và chính xác, chứ không phải cách tính toán. + +Khả năng thực thi và hiệu năng được đẩy hoàn toàn sang *cách triển khai*, một tạo phẩm riêng được bảo đảm tính đúng đắn bằng các định luật đồng cấu (đồng cấu lớp kiểu) liên hệ nó với ý nghĩa: hàm ý nghĩa phải ánh xạ mỗi phép hợp thành cú pháp sang phép hợp thành ngữ nghĩa tương ứng. Như Conal diễn đạt, ngữ nghĩa chỉ định đưa ra “định nghĩa rõ ràng *về chính xác điều cần triển khai*, đồng thời để lại nhiều không gian sáng tạo về *cách thực hiện*.” + +Trong Rust, một số tạo phẩm thể hiện các phần của đặc tả này, và có tạo phẩm tình cờ thực thi được. Khả năng thực thi chỉ là thuộc tính phụ; nó không khiến chúng trở thành đặc tả: + +* văn xuôi nêu ý nghĩa dự định +* đặc trưng nêu các phép toán nguyên thủy có sẵn +* phần mở rộng nêu các phép suy ra +* định luật nêu các đẳng thức bắt buộc +* bộ diễn giải chứng minh khả năng hiện thực hóa +* kiểm thử cung cấp bằng chứng hữu hạn + +Hãy đọc chúng cùng nhau, đặt ý nghĩa và định luật cao hơn cơ chế cụ thể về mặt thẩm quyền. + +## Đọc thêm {#further-reading} + +* [Denotational Design: from programs to meanings (BayHac 2014)](https://github.com/conal/talk-2014-bayhac-denotational-design) +* [Denotational design with type class morphisms](http://conal.net/papers/type-class-morphisms/) +* [Các bài viết và bài nói chuyện của Conal Elliott](http://conal.net/) diff --git a/src/denotational-design/design.zh-hant.md b/src/denotational-design/design.zh-hant.md new file mode 100644 index 0000000..f8a6859 --- /dev/null +++ b/src/denotational-design/design.zh-hant.md @@ -0,0 +1,168 @@ + + +# 指稱設計 {#denotational-design} + +```admonish tip title="相關內容" +語義視角:[指稱與組合性](denotations.md)、[定律與解釋](laws-and-interpretations.md) +Rust 中的語義驅動設計:[能力代數](../rust-dd/capability-algebras.md)、[派生含義與組合](../rust-dd/derived-meaning.md) +``` + +```admonish note title="核心思想" +指稱設計從簡單、可組合且獨立於實作的含義推導出程式設計介面,讓語義來引導設計,而不是事後描述介面。 +``` + +指稱設計是一種從簡單、可組合且獨立於實作的含義推導程式設計介面的方法。 + +該方法由[Conal Elliott](http://conal.net/)提出並命名。它的核心做法不僅是為現有語言或 API 賦予語義,而是讓語義引導 API 本身的設計。 + +## 設計迴圈 {#the-design-loop} + +按以下順序進行: + +1. 選擇語義域。 +2. 確定該語義域中重要的結構。 +3. 選擇一組精簡的基本操作詞彙。 +4. 以組合方式派生有用操作。 +5. 陳述這些操作遵循的定律。 +6. 選擇一種或多種表示。 +7. 實作能夠保留該結構的解釋。 +8. 透過定律、模型與場景進行驗證。 + +表示優先的設計通常從第 6 步開始,然後試圖事後補出第 1 至第 5 步。 + +## 設計分支代數 {#designing-a-branch-algebra} + +回到分支位置。預期含義是二叉分支結構中的有限路徑。 + +一種可能的基本代數是: + +$$ \begin{aligned} \operatorname{root} &\colon \mathtt{()} \to \mathsf{Branch} \\ \operatorname{grow} &\colon \mathsf{Branch} \times \mathsf{Direction} \to \mathsf{Branch} \\ \operatorname{path} &\colon \mathsf{Branch} \times \mathsf{Branch} \rightharpoonup \operatorname{List}(\mathsf{Direction}) \end{aligned} $$ + +偏箭頭$\rightharpoonup$表示路徑觀察僅在第一個分支是第二個分支的祖先時才存在。 + +由此可得一些有用操作: + +$$ \begin{aligned} \operatorname{left}(b) &= \operatorname{grow}(b, \mathsf{Left}) \\ \operatorname{right}(b) &= \operatorname{grow}(b, \mathsf{Right}) \\ \operatorname{is\_ancestor}(a,b) &\iff \operatorname{path}(a,b)\ \text{is defined} \\ \operatorname{from\_path}(d_s) &= \operatorname{fold}(\operatorname{grow}, \operatorname{root}, d_s) \end{aligned} $$ + +這個代數沒有提到向量、整數、分數、資料庫鍵或位元組。這些選擇留待後續。 + +## 先結構,後便利 {#structure-before-convenience} + +基本詞彙應揭示下游程式碼所依賴的結構,而不應變成某種實作上所有便利方法的集合。 + +````admonish warning title="拒絕表示優先的基本操作" +這個 trait 將儲存佈局、配置位置、位表示和複合工作流捆綁在一起,並未隔離分支含義: + +```rust,noplayground +trait BranchManager { + // not recommended: exposes machinery, not semantic observations + fn storage(&self) -> &BranchTable; + fn config(&self) -> &BranchConfig; + fn raw_bits(&self) -> &[u64]; + fn grow_and_save(&mut self, right: bool); +} +``` +```` + +當效應屬於所選語義域時,語義 API 仍然可以包含效應。規則並不是“所有東西都必須是純函式”,而是“每個基本操作都必須表達連貫的含義”。 + +## 編碼方式不是方法論 {#encoding-is-not-methodology} + +指稱設計不要求使用: + +* Haskell +* tagless-final 編碼 +* 物件代數 +* 自由單子 +* 單一抽象語法樹 +* 僅使用純函式 +* 每個 API 都採用範疇論術語 + +這些可以是有用的編碼方式或解釋工具,但沒有一種能夠定義該方法。 + +```admonish note title="Rust 編碼方式" +在 Rust 中,小型 trait、關聯型別、擴充方法、泛型函式和一階程式值都是實用的編碼方式。它們的價值取決於是否保留了清晰的語義設計。 +``` + +## 型別類態射 {#type-class-morphisms} + +理解該方法的一種方式,是把它看作保結構對映。 + +假設某個介面描述了一個語義代數。實作會將其抽象值與操作對映到具體表示中。有效實作必須保留相關操作與定律。 + +如果`encode`將抽象分支對映到具體載體,那麼保留延伸操作的形式如下: + +$$ \operatorname{encode}(\operatorname{grow}(b,d)) = \operatorname{grow}_{\mathsf{concrete}}(\operatorname{encode}(b),d) $$ + +實作不只是一個方法名稱相同的集合。它應當是一個尊重代數結構的態射。 + +## 什麼樣的抽象才算好 {#what-counts-as-a-good-abstraction} + +一個好的指稱設計抽象具備以下特徵: + +* 其中的值具有簡單明確的預期含義。 +* 基本操作用於揭示語義觀察或構造。 +* 更大的行為由這些基本操作派生。 +* 其定律不依賴某一種表示。 +* 可以由彼此獨立的實作來解釋。 +* 只有在相關時才引入操作細節。 + +僅僅精簡還不夠。即使一個小型 trait 暴露了`get_manager()`,它仍可能是表示優先的。若某個更大的代數包含的操作構成連貫的語義結構,也可能是合理的。 + +## 語義值與抽象載體 {#semantic-values-and-abstract-carriers} + +並非所有具體型別都不能寫入規範。 + +當直譯器應當選擇載體時,使用關聯型別: + +```rust,noplayground +trait BranchAlg { + type Branch; +} +``` + +當某個型別屬於穩定的語義詞彙時,使用具體型別: + +```rust,noplayground +enum Direction { + Left, + Right, +} +``` + +區別並非“抽象好,具體壞”,而是語義詞彙與偶然的機器表示之別。 + +## 規範就是指稱,而且不必可執行 {#the-specification-is-the-denotation-and-it-need-not-execute} + +規範就是指稱:賦予每種構造的數學含義。它的力量在於不受效率約束,甚至不必能夠執行。 + +```admonish quote title="Conal Elliott" +定義指稱通常比實作容易得多,也更能帶來啟發,因為指稱不受效率或可執行性的約束,也不會受到它們的干擾。 + +——[《指稱設計:從含義到程式》(LambdaJam 2015)](https://github.com/conal/talk-2014-lambdajam-denotational-design) +``` + +經典示例是 FRP(函式式響應式程式設計):`Behavior a`被定義為連續時間上的函式, + +$$\llbracket\,\cdot\,\rrbracket : \mathsf{Behavior}\ a \to (\mathbb{R} \to a)$$ + +這個模型很精確,卻無法執行——實數無法逐個列舉。程式也可以指稱一組結果;這兩種模型都無法執行,但這正是其用意所在。選擇含義是為了簡潔和精確,而不是為了計算方式。 + +可執行性與效率完全交由*實作*負責;實作是獨立產物,藉助將其與含義關聯起來的同態定律(型別類態射)來保證正確性:含義函式必須把每種語法組合對映為相應的語義組合。正如 Conal 所說,指稱給出了對*待實作之事*明確無歧義的定義,同時為*如何*實作留下了很大的創作空間。 + +在 Rust 中,有幾種產物可以表達這份規範的部分內容,其中一些恰好可以執行。可執行性只是偶然屬性,不是它們成為規範的原因: + +* 說明文字陳述預期含義 +* trait 陳述可用的基本操作 +* 擴充陳述派生方式 +* 定律陳述必需的等式 +* 直譯器展示可實現性 +* 測試提供有限證據 + +應結合起來閱讀,並讓含義與定律在權威性上優先於具體機制。 + +## 延伸閱讀 {#further-reading} + +* [《指稱設計:從程式到含義》(BayHac 2014)](https://github.com/conal/talk-2014-bayhac-denotational-design) +* [《藉助型別類態射進行指稱設計》](http://conal.net/papers/type-class-morphisms/) +* [Conal Elliott 的文章與演講](http://conal.net/) diff --git a/src/denotational-design/design.zh.md b/src/denotational-design/design.zh.md new file mode 100644 index 0000000..55802b7 --- /dev/null +++ b/src/denotational-design/design.zh.md @@ -0,0 +1,168 @@ + + +# 指称设计 {#denotational-design} + +```admonish tip title="相关内容" +语义视角:[指称与组合性](denotations.md)、[定律与解释](laws-and-interpretations.md) +Rust 中的语义驱动设计:[能力代数](../rust-dd/capability-algebras.md)、[派生含义与组合](../rust-dd/derived-meaning.md) +``` + +```admonish note title="核心思想" +指称设计从简单、可组合且独立于实现的含义推导出编程接口,让语义来引导设计,而不是事后描述接口。 +``` + +指称设计是一种从简单、可组合且独立于实现的含义推导编程接口的方法。 + +该方法由[Conal Elliott](http://conal.net/)提出并命名。它的核心做法不仅是为现有语言或 API 赋予语义,而是让语义引导 API 本身的设计。 + +## 设计循环 {#the-design-loop} + +按以下顺序进行: + +1. 选择语义域。 +2. 确定该语义域中重要的结构。 +3. 选择一组精简的基本操作词汇。 +4. 以组合方式派生有用操作。 +5. 陈述这些操作遵循的定律。 +6. 选择一种或多种表示。 +7. 实现能够保留该结构的解释。 +8. 通过定律、模型与场景进行验证。 + +表示优先的设计通常从第 6 步开始,然后试图事后补出第 1 至第 5 步。 + +## 设计分支代数 {#designing-a-branch-algebra} + +回到分支位置。预期含义是二叉分支结构中的有限路径。 + +一种可能的基本代数是: + +$$ \begin{aligned} \operatorname{root} &\colon \mathtt{()} \to \mathsf{Branch} \\ \operatorname{grow} &\colon \mathsf{Branch} \times \mathsf{Direction} \to \mathsf{Branch} \\ \operatorname{path} &\colon \mathsf{Branch} \times \mathsf{Branch} \rightharpoonup \operatorname{List}(\mathsf{Direction}) \end{aligned} $$ + +偏箭头$\rightharpoonup$表示路径观察仅在第一个分支是第二个分支的祖先时才存在。 + +由此可得一些有用操作: + +$$ \begin{aligned} \operatorname{left}(b) &= \operatorname{grow}(b, \mathsf{Left}) \\ \operatorname{right}(b) &= \operatorname{grow}(b, \mathsf{Right}) \\ \operatorname{is\_ancestor}(a,b) &\iff \operatorname{path}(a,b)\ \text{is defined} \\ \operatorname{from\_path}(d_s) &= \operatorname{fold}(\operatorname{grow}, \operatorname{root}, d_s) \end{aligned} $$ + +这个代数没有提到向量、整数、分数、数据库键或字节。这些选择留待后续。 + +## 先结构,后便利 {#structure-before-convenience} + +基本词汇应揭示下游代码所依赖的结构,而不应变成某种实现上所有便利方法的集合。 + +````admonish warning title="拒绝表示优先的基本操作" +这个 trait 将存储布局、配置位置、位表示和复合工作流捆绑在一起,并未隔离分支含义: + +```rust,noplayground +trait BranchManager { + // not recommended: exposes machinery, not semantic observations + fn storage(&self) -> &BranchTable; + fn config(&self) -> &BranchConfig; + fn raw_bits(&self) -> &[u64]; + fn grow_and_save(&mut self, right: bool); +} +``` +```` + +当效应属于所选语义域时,语义 API 仍然可以包含效应。规则并不是“所有东西都必须是纯函数”,而是“每个基本操作都必须表达连贯的含义”。 + +## 编码方式不是方法论 {#encoding-is-not-methodology} + +指称设计不要求使用: + +* Haskell +* tagless-final 编码 +* 对象代数 +* 自由单子 +* 单一抽象语法树 +* 仅使用纯函数 +* 每个 API 都采用范畴论术语 + +这些可以是有用的编码方式或解释工具,但没有一种能够定义该方法。 + +```admonish note title="Rust 编码方式" +在 Rust 中,小型 trait、关联类型、扩展方法、泛型函数和一阶程序值都是实用的编码方式。它们的价值取决于是否保留了清晰的语义设计。 +``` + +## 类型类态射 {#type-class-morphisms} + +理解该方法的一种方式,是把它看作保结构映射。 + +假设某个接口描述了一个语义代数。实现会将其抽象值与操作映射到具体表示中。有效实现必须保留相关操作与定律。 + +如果`encode`将抽象分支映射到具体载体,那么保留延伸操作的形式如下: + +$$ \operatorname{encode}(\operatorname{grow}(b,d)) = \operatorname{grow}_{\mathsf{concrete}}(\operatorname{encode}(b),d) $$ + +实现不只是一个方法名称相同的集合。它应当是一个尊重代数结构的态射。 + +## 什么样的抽象才算好 {#what-counts-as-a-good-abstraction} + +一个好的指称设计抽象具备以下特征: + +* 其中的值具有简单明确的预期含义。 +* 基本操作用于揭示语义观察或构造。 +* 更大的行为由这些基本操作派生。 +* 其定律不依赖某一种表示。 +* 可以由彼此独立的实现来解释。 +* 只有在相关时才引入操作细节。 + +仅仅精简还不够。即使一个小型 trait 暴露了`get_manager()`,它仍可能是表示优先的。若某个更大的代数包含的操作构成连贯的语义结构,也可能是合理的。 + +## 语义值与抽象载体 {#semantic-values-and-abstract-carriers} + +并非所有具体类型都不能写入规范。 + +当解释器应当选择载体时,使用关联类型: + +```rust,noplayground +trait BranchAlg { + type Branch; +} +``` + +当某个类型属于稳定的语义词汇时,使用具体类型: + +```rust,noplayground +enum Direction { + Left, + Right, +} +``` + +区别并非“抽象好,具体坏”,而是语义词汇与偶然的机器表示之别。 + +## 规范就是指称,而且不必可执行 {#the-specification-is-the-denotation-and-it-need-not-execute} + +规范就是指称:赋予每种构造的数学含义。它的力量在于不受效率约束,甚至不必能够执行。 + +```admonish quote title="Conal Elliott" +定义指称通常比实现容易得多,也更能带来启发,因为指称不受效率或可执行性的约束,也不会受到它们的干扰。 + +——[《指称设计:从含义到程序》(LambdaJam 2015)](https://github.com/conal/talk-2014-lambdajam-denotational-design) +``` + +经典示例是 FRP(函数式响应式编程):`Behavior a`被定义为连续时间上的函数, + +$$\llbracket\,\cdot\,\rrbracket : \mathsf{Behavior}\ a \to (\mathbb{R} \to a)$$ + +这个模型很精确,却无法执行——实数无法逐个枚举。程序也可以指称一组结果;这两种模型都无法运行,但这正是其用意所在。选择含义是为了简洁和精确,而不是为了计算方式。 + +可执行性与效率完全交由*实现*负责;实现是独立产物,借助将其与含义关联起来的同态定律(类型类态射)来保证正确性:含义函数必须把每种语法组合映射为相应的语义组合。正如 Conal 所说,指称给出了对*待实现之事*明确无歧义的定义,同时为*如何*实现留下了很大的创作空间。 + +在 Rust 中,有几种产物可以表达这份规范的部分内容,其中一些恰好可以执行。可执行性只是偶然属性,不是它们成为规范的原因: + +* 说明文字陈述预期含义 +* trait 陈述可用的基本操作 +* 扩展陈述派生方式 +* 定律陈述必需的等式 +* 解释器展示可实现性 +* 测试提供有限证据 + +应结合起来阅读,并让含义与定律在权威性上优先于具体机制。 + +## 延伸阅读 {#further-reading} + +* [《指称设计:从程序到含义》(BayHac 2014)](https://github.com/conal/talk-2014-bayhac-denotational-design) +* [《借助类型类态射进行指称设计》](http://conal.net/papers/type-class-morphisms/) +* [Conal Elliott 的文章与演讲](http://conal.net/) diff --git a/src/denotational-design/laws-and-interpretations.ar.md b/src/denotational-design/laws-and-interpretations.ar.md new file mode 100644 index 0000000..9ed0a1d --- /dev/null +++ b/src/denotational-design/laws-and-interpretations.ar.md @@ -0,0 +1,108 @@ + + +# القوانين والتفسيرات {#laws-and-interpretations} + +```admonish tip title="ذات صلة" +المنظور الدلالي: [التصميم الدلالي (Denotational Design)](design.md) +التصميم انطلاقًا من المعنى في Rust: [القوانين والسيناريوهات والأدلة](../rust-dd/laws.md)، [المفسرات والآثار](../rust-dd/interpreters.md) +المفاهيم: [التشعب والتلاقي](../concepts/branching.md) +``` + +```admonish note title="الفكرة الأساسية" +تحدد القوانين علاقة عمليات الواجهة الدلالية بعضها ببعض، ويسند التفسير حوامل ملموسة يتعين عليها الحفاظ على تلك القوانين. ويحدد التساوي المختار أي الفروق بين المفسرات ذات معنى وأيها حر. +``` + +تسمي الواجهة الدلالية العمليات، وتحدد القوانين علاقة تلك العمليات. ومن دون قوانين، قد يطابق تنفيذان توقيعات Rust نفسها، لكنهما يختلفان في معنى التجريد. + +## تُكمل القوانين المفردات {#laws-complete-the-vocabulary} + +تشمل القوانين المفيدة لمواضع الفروع ما يلي: + +$$ \begin{aligned} \operatorname{path}(b,b) &= \lbrack\,\rbrack \\ \operatorname{path}(\operatorname{root}, \operatorname{from\_path}(d_s)) &= d_s \\ \operatorname{from\_path}(\operatorname{path}(\operatorname{root},b)) &= b \\ \operatorname{is\_ancestor}(b,b) &= \mathsf{true} \\ \operatorname{left}(b) &\ne \operatorname{right}(b) \end{aligned} $$ + +تشرح هذه القوانين أكثر مما تستطيع تعليقات الأساليب. فهي تصف الهوية وإعادة البناء والانعكاسية والفصل. + +ليست كل معادلة مغرية صحيحة. فقد يفيض تمثيل ذو عرض ثابت عند عمق شديد مثلًا. وقد يكون ذلك أحد الأمور التالية: + +* قيدًا في المفسر خارج مجاله المسموح +* خطأً دلاليًا يجب على الواجهة إظهاره +* دليلًا على خطأ الحامل المختار + +يجب أن يحدد التصميم أيها المقصود. + +## التفسير {#interpretation} + +**التفسير** يسند حوامل وعمليات ملموسة إلى جبر دلالي. + +| برنامج دلالي | تفسيرات محتملة | +| --- | --- | +| موضع فرع | مسار بتات، وشجرة عددية، وصيغة رمزية | +| برنامج تعبيرات | مُقيِّم، وطابع منسق، ومُحسِّن | +| برنامج API مكتوب الأنواع | مسارات خادم قابلة للتنفيذ، وتوثيق، ومولّد عميل | + +يمكن أن يكون للبرنامج نفسه تفسيرات متعددة لأنه لا يطابق أي نتيجة بعينها. + +## التزامات التنفيذ {#implementation-obligations} + +يجب على المفسر الحفاظ على البنية التي تدّعيها المواصفة. + +إذا كان الدمج تجميعيًا في البرنامج الدلالي: + +$$ (a \oplus b) \oplus c = a \oplus (b \oplus c) $$ + +فينبغي للمفسرات الحفاظ على المعنى القابل للملاحظة لذلك التجميع. وإذا حُدد ترتيب المسارات أيضًا، وجب أن يشمل التساوي الترتيب. أما إذا أُهمل الترتيب عمدًا، فقد تختلف التنفيذات تشغيليًا مع بقائها متساوية دلاليًا. + +لذلك يجب اختيار المجال الدلالي والتساوي قبل كتابة القوانين. + +## القوانين والبراهين والاختبارات {#laws-proofs-and-tests} + +هذه المصطلحات غير قابلة للتبادل: + +* **القانون** خاصية مقصودة للتجريد، ويُراد لها أن تصح عمومًا. +* **البرهان** يثبت قانونًا في ظل افتراضات معلنة. +* **اختبار الخاصية** يفحص أمثلة مولّدة كثيرة. +* **اختبار السيناريو** يفحص حالة منتهية واحدة ذات معنى. +* **اختبار الوحدة** يفحص سلوكًا ملموسًا واحدًا. + +الاختبارات دليل قابل للتنفيذ وليست برهانًا عامًا. لكنها قيّمة مع ذلك لإمكان إعادة استخدامها مع كل مفسر. + +## دليل قابل للتنفيذ {#executable-evidence} + +القوانين الدلالية مستقلة عن تنفيذاتها. وتقدم الفحوص القابلة للتنفيذ أدلة محدودة على حفاظ المفسر على تلك القوانين: تفحص اختبارات الخصائص ادعاءات تشبه المعادلات، بينما تفحص السيناريوهات تفاعلات قابلة للملاحظة. وعندما تُكتب بلغة العمليات الدلالية وحدها، يمكن إعادة استخدام الدليل نفسه بين المفسرات المتوافقة. تدعم الاختبارات المواصفة، لكنها لا تعرّفها ولا تثبتها. + +تُعرض ترميزات Rust في [القوانين والسيناريوهات والأدلة](../rust-dd/laws.md). + +## تعدد المفسرات يوضح المعنى {#multiple-interpreters-clarify-meaning} + +لا يلزم وجود تنفيذ ثانٍ لكل سمة صغيرة، لكنه اختبار تصميم قوي. + +إذا لم يمكن صياغة قانون يُفترض أنه مجرد إلا باستخدام حقول التنفيذ الأول، فمن المرجح أن الحد الدلالي غير صحيح. وإذا استطاع مفسر ثانٍ تنفيذ العناصر الأولية والوفاء بالقوانين نفسها من دون تقليد التمثيل الأول، ازدادت مصداقية التجريد. + +تكون المفسرات المحايدة مفيدة على نحو خاص: + +* يكشف المفسر النصي بنية البرنامج +* يعزل النموذج الصرف في الذاكرة القوانين +* يكشف مفسر التتبع الملاحظات المختارة +* ينفذ مفسر الإنتاج آثارًا حقيقية + +## يحدد التساوي حرية إعادة الهيكلة {#equality-determines-refactoring-freedom} + +يمنح كل تساوٍ دلالي حريةً في التنفيذ. فإذا تساوى تمثيلان بحسب الدلالة المختارة، جاز للتنفيذ استبدال أحدهما بالآخر. + +وتمنح كل ملاحظة محذوفة حرية أيضًا. إذا لم يكن ترتيب التخصيص دلاليًا، جاز تغييره. وإذا كان ترتيب الأساليب دلاليًا، فلا يجوز تغييره. + +لذلك ليست القوانين قيودًا على الصحة فحسب؛ فهي تحدد الحيز الآمن للتحسين والاستبدال والتطور. + +## نقطة تحقق {#checkpoint} + +قبل الانتقال إلى ترميزات Rust، تحقّق من قدرتك على الإجابة عن الآتي: + +1. ما الحامل الدلالي؟ +2. ما الذي يتجاهله التجريد عمدًا؟ +3. ما العمليات الأولية؟ +4. ما العمليات المشتقة؟ +5. ما التساوي المستخدم؟ +6. ما القوانين التي يجب على كل مفسر الحفاظ عليها؟ +7. ما الدليل الذي سيُشترك فيه بين المفسرات؟ + +يعرض باقي الكتاب إجابة عملية واحدة باستخدام Rust. إنها ترميز لهذه الصورة الدلالية، لا بديل عنها. diff --git a/src/denotational-design/laws-and-interpretations.de.md b/src/denotational-design/laws-and-interpretations.de.md new file mode 100644 index 0000000..307718d --- /dev/null +++ b/src/denotational-design/laws-and-interpretations.de.md @@ -0,0 +1,108 @@ + + +# Gesetze und Interpretationen {#laws-and-interpretations} + +```admonish tip title="Verwandte Themen" +The Semantic View: [Denotational Design](design.md) +Design by Meaning in Rust: [Gesetze, Szenarien und Nachweise](../rust-dd/laws.md), [Interpreter und Effekte](../rust-dd/interpreters.md) +Concepts: [Verzweigung und Konfluenz](../concepts/branching.md) +``` + +```admonish note title="Grundidee" +Gesetze beschreiben, wie die Operationen einer semantischen Schnittstelle zusammenhängen. Eine Interpretation weist ihnen konkrete Träger zu und muss diese Gesetze bewahren. Die gewählte Gleichheit bestimmt, welche Unterschiede zwischen Interpretern Bedeutung haben und welche frei bleiben. +``` + +Eine semantische Schnittstelle benennt Operationen. Gesetze legen ihre Beziehungen fest. Ohne Gesetze können zwei Implementierungen dieselben Rust-Signaturen erfüllen und sich dennoch über die Abstraktion uneinig sein. + +## Gesetze vervollständigen das Vokabular {#laws-complete-the-vocabulary} + +Für Verzweigungspositionen gehören beispielsweise folgende Gesetze dazu: + +$$ \begin{aligned} \operatorname{path}(b,b) &= \lbrack\,\rbrack \\ \operatorname{path}(\operatorname{root}, \operatorname{from\_path}(d_s)) &= d_s \\ \operatorname{from\_path}(\operatorname{path}(\operatorname{root},b)) &= b \\ \operatorname{is\_ancestor}(b,b) &= \mathsf{true} \\ \operatorname{left}(b) &\ne \operatorname{right}(b) \end{aligned} $$ + +Diese Gesetze erklären mehr als Methodenkommentare. Sie beschreiben Identität, Rekonstruktion, Reflexivität und Trennung. + +Nicht jede ansprechende Gleichung gilt. Eine Repräsentation mit fester Breite kann beispielsweise bei extremer Tiefe überlaufen. Dann handelt es sich entweder um: + +* eine Einschränkung des Interpreters außerhalb seines zugelassenen Bereichs +* einen semantischen Fehler, den die Schnittstelle offenlegen muss +* einen Hinweis darauf, dass der gewählte Träger falsch ist + +Der Entwurf muss klarstellen, welcher Fall vorliegt. + +## Interpretation {#interpretation} + +Eine **Interpretation** weist einer semantischen Algebra konkrete Träger und Operationen zu. + +| Semantisches Programm | Mögliche Interpretationen | +| --- | --- | +| Verzweigungsposition | Bitpfad, numerischer Baum, symbolische Form | +| Ausdrucksprogramm | Auswerter, Pretty-Printer, Optimierer | +| Programm einer typisierten API | Ausführbare Serverrouten, Dokumentation, Client-Generator | + +Dasselbe Programm kann mehrere Interpretationen haben, weil das Programm mit keinem einzelnen Ergebnis identisch ist. + +## Pflichten der Implementierung {#implementation-obligations} + +Ein Interpreter muss die Struktur bewahren, die in der Spezifikation behauptet wird. + +Ist das Zusammenführen im semantischen Programm assoziativ: + +$$ (a \oplus b) \oplus c = a \oplus (b \oplus c) $$ + +dann sollten Interpreter die beobachtbare Bedeutung dieser Verknüpfung bewahren. Ist auch die Routenreihenfolge spezifiziert, muss die Gleichheit die Reihenfolge berücksichtigen. Wird die Reihenfolge bewusst ausgeblendet, dürfen Implementierungen sich operational unterscheiden und dennoch semantisch gleich sein. + +Darum müssen der semantische Bereich und die Gleichheit gewählt werden, bevor Gesetze formuliert werden. + +## Gesetze, Beweise und Tests {#laws-proofs-and-tests} + +Diese Begriffe sind nicht austauschbar: + +* Ein **Gesetz** ist eine allgemein geltende Eigenschaft, die für die Abstraktion vorgesehen ist. +* Ein **Beweis** zeigt ein Gesetz unter den genannten Annahmen. +* Ein **Eigenschaftstest** prüft zahlreiche generierte Beispiele. +* Ein **Szenariotest** prüft eine aussagekräftige, endliche Situation. +* Ein **Unit-Test** prüft ein konkretes Verhalten. + +Tests sind ausführbare Nachweise, keine allgemeinen Beweise. Sie bleiben dennoch wertvoll, weil sie für jeden Interpreter wiederverwendet werden können. + +## Ausführbarer Nachweis {#executable-evidence} + +Semantische Gesetze sind von ihren Implementierungen unabhängig. Ausführbare Prüfungen liefern endliche Nachweise dafür, dass ein Interpreter diese Gesetze bewahrt: Eigenschaftsprüfungen untersuchen gleichungsartige Behauptungen, während Szenarien beobachtbare Interaktionen prüfen. Werden sie ausschließlich mit semantischen Operationen formuliert, lassen sich dieselben Nachweise über kompatible Interpreter hinweg wiederverwenden. Tests stützen eine Spezifikation; sie definieren oder beweisen sie nicht. + +Die Rust-Kodierungen werden in [Gesetze, Szenarien und Nachweise](../rust-dd/laws.md) entwickelt. + +## Mehrere Interpreter klären die Bedeutung {#multiple-interpreters-clarify-meaning} + +Nicht jedes kleine Trait braucht eine zweite Implementierung, doch sie ist ein aussagekräftiger Entwurfstest. + +Lässt sich ein vermeintlich abstraktes Gesetz nur mit Feldern der ersten Implementierung formulieren, stimmt die semantische Grenze wahrscheinlich nicht. Kann ein zweiter Interpreter die primitiven Operationen implementieren und dieselben Gesetze erfüllen, ohne die erste Repräsentation nachzuahmen, gewinnt die Abstraktion an Glaubwürdigkeit. + +Neutrale Interpreter sind besonders nützlich: + +* Ein Text-Interpreter macht die Programmstruktur sichtbar +* Ein reines In-Memory-Modell isoliert die Gesetze +* Ein Tracing-Interpreter macht ausgewählte Beobachtungen sichtbar +* Ein Produktionsinterpreter führt reale Effekte aus + +## Gleichheit bestimmt die Freiheit beim Refactoring {#equality-determines-refactoring-freedom} + +Jede semantische Gleichheit gewährt Implementierungsfreiheit. Sind zwei Repräsentationen gemäß der gewählten Denotation gleich, darf eine Implementierung die eine durch die andere ersetzen. + +Auch jede ausgelassene Beobachtung gewährt Freiheit. Ist die Allokationsreihenfolge semantisch irrelevant, darf sie sich ändern. Ist die Reihenfolge der Methodenaufrufe semantisch relevant, darf sie sich nicht ändern. + +Gesetze sind daher nicht nur Korrektheitsbedingungen. Sie bestimmen den sicheren Spielraum für Optimierung, Austausch und Weiterentwicklung. + +## Zwischenstand {#checkpoint} + +Beantworte vor dem Einstieg in die Rust-Kodierungen diese Fragen: + +1. Was ist der semantische Träger? +2. Was blendet die Abstraktion bewusst aus? +3. Welche Operationen sind primitiv? +4. Welche Operationen sind abgeleitet? +5. Welche Gleichheit wird verwendet? +6. Welche Gesetze muss jeder Interpreter bewahren? +7. Welche Nachweise werden zwischen Interpretern geteilt? + +Der Rest des Buches zeigt eine praktische Antwort in Rust. Sie ist eine Kodierung dieses semantischen Bildes, kein Ersatz dafür. diff --git a/src/denotational-design/laws-and-interpretations.es.md b/src/denotational-design/laws-and-interpretations.es.md new file mode 100644 index 0000000..d37a589 --- /dev/null +++ b/src/denotational-design/laws-and-interpretations.es.md @@ -0,0 +1,108 @@ + + +# Leyes e interpretaciones {#laws-and-interpretations} + +```admonish tip title="Relacionado" +La perspectiva semántica: [Diseño denotacional](design.md) +Diseño por significado en Rust: [Leyes, escenarios y evidencia](../rust-dd/laws.md), [Intérpretes y efectos](../rust-dd/interpreters.md) +Conceptos: [Ramificación y confluencia](../concepts/branching.md) +``` + +```admonish note title="Idea central" +Las leyes expresan cómo se relacionan las operaciones de una interfaz semántica, y una interpretación asigna portadores concretos que deben preservar esas leyes. La igualdad elegida fija qué diferencias entre intérpretes tienen significado y cuáles son libres. +``` + +Una interfaz semántica nombra operaciones. Las leyes expresan cómo se relacionan. Sin leyes, dos implementaciones pueden cumplir las mismas firmas de Rust y aun así discrepar sobre la abstracción. + +## Las leyes completan el vocabulario {#laws-complete-the-vocabulary} + +Para las posiciones de ramificación, algunas leyes útiles son: + +$$ \begin{aligned} \operatorname{path}(b,b) &= \lbrack\,\rbrack \\ \operatorname{path}(\operatorname{root}, \operatorname{from\_path}(d_s)) &= d_s \\ \operatorname{from\_path}(\operatorname{path}(\operatorname{root},b)) &= b \\ \operatorname{is\_ancestor}(b,b) &= \mathsf{true} \\ \operatorname{left}(b) &\ne \operatorname{right}(b) \end{aligned} $$ + +Estas leyes explican más de lo que pueden hacerlo los comentarios de métodos. Describen identidad, reconstrucción, reflexividad y separación. + +No todas las ecuaciones atractivas son válidas. Por ejemplo, una representación de ancho fijo puede desbordarse a una profundidad extrema. Eso puede ser: + +* una limitación del intérprete fuera del dominio admitido +* un error semántico que la interfaz debe exponer +* evidencia de que el portador elegido es incorrecto + +El diseño debe indicar cuál de estas opciones se aplica. + +## Interpretación {#interpretation} + +Una **interpretación** asigna portadores y operaciones concretos a un álgebra semántica. + +| Programa semántico | Interpretaciones posibles | +| --- | --- | +| Posición de ramificación | Ruta de bits, árbol numérico, forma simbólica | +| Programa de expresiones | Evaluador, impresor de formato, optimizador | +| Programa de API tipada | Rutas de servidor ejecutables, documentación, generador de clientes | + +Un mismo programa puede tener varias interpretaciones porque no es idéntico a ningún resultado concreto. + +## Obligaciones de implementación {#implementation-obligations} + +Un intérprete debe preservar la estructura que afirma la especificación. + +Si la fusión es asociativa en el programa semántico: + +$$ (a \oplus b) \oplus c = a \oplus (b \oplus c) $$ + +los intérpretes deben preservar entonces el significado observable de esa asociación. Si también se especifica el orden de las rutas, la igualdad debe incluirlo. Si se omite intencionalmente, las implementaciones pueden diferir operacionalmente y seguir siendo semánticamente iguales. + +Por eso hay que elegir el dominio semántico y la igualdad antes de escribir leyes. + +## Leyes, pruebas y tests {#laws-proofs-and-tests} + +Estos términos no son intercambiables: + +* Una **ley** es una propiedad que se pretende universal para la abstracción. +* Una **prueba** establece una ley bajo supuestos declarados. +* Un **test de propiedades** comprueba muchos ejemplos generados. +* Un **test de escenario** comprueba una situación finita con significado. +* Un **test unitario** comprueba un comportamiento concreto. + +Los tests son evidencia ejecutable, no una prueba universal. Aun así, son valiosos porque se pueden reutilizar con todos los intérpretes. + +## Evidencia ejecutable {#executable-evidence} + +Las leyes semánticas son independientes de sus implementaciones. Las comprobaciones ejecutables aportan evidencia finita de que un intérprete preserva esas leyes: los tests de propiedades ejercitan afirmaciones semejantes a ecuaciones, mientras que los escenarios ejercitan interacciones observables. Si se expresan solo en términos de operaciones semánticas, la misma evidencia puede reutilizarse entre intérpretes compatibles. Los tests respaldan una especificación; no la definen ni la demuestran. + +Las codificaciones de Rust se desarrollan en [Leyes, escenarios y evidencia](../rust-dd/laws.md). + +## Varios intérpretes aclaran el significado {#multiple-interpreters-clarify-meaning} + +No se necesita una segunda implementación para cada trait pequeño, pero es una potente prueba de diseño. + +Si una supuesta ley abstracta solo puede expresarse mediante campos de la primera implementación, probablemente el límite semántico sea incorrecto. Si un segundo intérprete puede implementar las primitivas y cumplir las mismas leyes sin imitar la primera representación, la abstracción gana credibilidad. + +Los intérpretes neutrales son especialmente útiles: + +* un intérprete textual revela la estructura del programa +* un modelo puro en memoria aísla las leyes +* un intérprete de trazas revela las observaciones elegidas +* un intérprete de producción realiza efectos reales + +## La igualdad determina la libertad de refactorización {#equality-determines-refactoring-freedom} + +Cada igualdad semántica concede libertad a la implementación. Si dos representaciones son iguales según la denotación elegida, una implementación puede sustituir una por la otra. + +Toda observación omitida también concede libertad. Si el orden de asignación no es semántico, puede cambiar. Si el orden de los métodos sí lo es, no debe cambiar. + +Por tanto, las leyes no son solo restricciones de corrección. Definen el espacio seguro para optimizar, sustituir y evolucionar. + +## Punto de control {#checkpoint} + +Antes de pasar a las codificaciones de Rust, verifica que puedes responder: + +1. ¿Cuál es el portador semántico? +2. ¿Qué omite intencionalmente la abstracción? +3. ¿Qué operaciones son primitivas? +4. ¿Qué operaciones son derivadas? +5. ¿Qué igualdad se está usando? +6. ¿Qué leyes debe preservar cada intérprete? +7. ¿Qué evidencia se compartirá entre intérpretes? + +El resto del libro muestra una respuesta práctica en Rust. Es una codificación de esta imagen semántica, no un reemplazo de ella. diff --git a/src/denotational-design/laws-and-interpretations.ja.md b/src/denotational-design/laws-and-interpretations.ja.md new file mode 100644 index 0000000..5de9c4d --- /dev/null +++ b/src/denotational-design/laws-and-interpretations.ja.md @@ -0,0 +1,108 @@ + + +# 法則と解釈 {#laws-and-interpretations} + +```admonish tip title="関連項目" +意味論的な見方:[Denotational Design](design.md) +Rustで意味から設計する:[法則、シナリオ、証拠](../rust-dd/laws.md)、[インタープリターと副作用](../rust-dd/interpreters.md) +概念:[分岐と合流性](../concepts/branching.md) +``` + +```admonish note title="中心となる考え方" +法則は意味論的インターフェースの操作同士の関係を述べ、解釈は具体的な担体を割り当てて、それらの法則を保持しなければなりません。選択した等値性によって、インタープリター間のどの差異に意味があり、どの差異が自由に変更できるかが決まります。 +``` + +意味論的インターフェースは操作に名前を付けます。法則は、それらの操作の関係を述べます。法則がなければ、二つの実装が同じRustのシグネチャを満たしながら、抽象化について異なる解釈をすることがあります。 + +## 法則が語彙を完成させる {#laws-complete-the-vocabulary} + +分岐位置に関する有用な法則には、次のものがあります。 + +$$ \begin{aligned} \operatorname{path}(b,b) &= \lbrack\,\rbrack \\ \operatorname{path}(\operatorname{root}, \operatorname{from\_path}(d_s)) &= d_s \\ \operatorname{from\_path}(\operatorname{path}(\operatorname{root},b)) &= b \\ \operatorname{is\_ancestor}(b,b) &= \mathsf{true} \\ \operatorname{left}(b) &\ne \operatorname{right}(b) \end{aligned} $$ + +これらの法則は、メソッドコメント以上のことを説明します。恒等性、再構成、反射性、分離性を記述します。 + +魅力的に見える等式がすべて妥当とは限りません。たとえば、固定幅の表現は極端に深い位置でオーバーフローすることがあります。それは次のいずれかです。 + +* 許容された領域の外におけるインタープリターの制限 +* インターフェースで明示すべき意味論上の誤り +* 選択した担体が適切でない証拠 + +どれに当たるかを設計で示す必要があります。 + +## 解釈 {#interpretation} + +**解釈**は、意味論的代数に具体的な担体と操作を割り当てます。 + +| 意味論的プログラム | 考えられる解釈 | +| --- | --- | +| 分岐位置 | ビット経路、数値による木構造、記号表現 | +| 式プログラム | 評価器、整形表示器、最適化器 | +| 型付きAPIプログラム | 実行可能なサーバールート、ドキュメント、クライアント生成器 | + +プログラムはどの結果とも同一ではないため、同じプログラムに複数の解釈を与えられます。 + +## 実装上の責務 {#implementation-obligations} + +インタープリターは、仕様が主張する構造を保持しなければなりません。 + +意味論上のプログラムでmergeが結合的なら、次のようになります。 + +$$ (a \oplus b) \oplus c = a \oplus (b \oplus c) $$ + +インタープリターは、その結び付け方が持つ観測可能な意味を保持する必要があります。ルートの順序も仕様で定めるなら、等値性に順序を含めます。順序を意図的に捨てるなら、実装上の振る舞いが異なっていても意味論的に等価な場合があります。 + +そのため、法則を記述する前に意味論的領域と等値性を選ぶ必要があります。 + +## 法則、証明、テスト {#laws-proofs-and-tests} + +これらの用語は同じ意味ではありません。 + +* **法則**とは、抽象化に普遍的に当てはまることを意図した性質です。 +* **証明**とは、明示された仮定のもとで法則が成り立つことを示すものです。 +* **プロパティテスト**は、生成した多数の例を検査します。 +* **シナリオテスト**は、意味のある有限の状況を一つ検査します。 +* **単体テスト**は、具体的な振る舞いを一つ検査します。 + +テストは実行可能な証拠であり、普遍的な証明ではありません。それでも、すべてのインタープリターで再利用できるため有用です。 + +## 実行可能な証拠 {#executable-evidence} + +意味論的な法則は実装から独立しています。実行可能な検査は、インタープリターが法則を保持することの有限の証拠を示します。プロパティ検査は等式に似た主張を確かめ、シナリオ検査は観測可能な相互作用を確かめます。意味論的操作だけを使って書けば、互換性のあるインタープリター間で同じ証拠を再利用できます。テストは仕様を支えますが、定義したり証明したりするものではありません。 + +Rustでの符号化は、[法則、シナリオ、証拠](../rust-dd/laws.md)で扱います。 + +## 複数のインタープリターが意味を明確にする {#multiple-interpreters-clarify-meaning} + +小さなトレイトすべてに二つ目の実装が必要なわけではありませんが、有力な設計検査になります。 + +抽象的な法則とされるものを最初の実装のフィールドを使わないと述べられないなら、意味論的な境界が適切でない可能性があります。二つ目のインタープリターが最初の表現を模倣せずに基本操作を実装し、同じ法則を満たせるなら、その抽象化の信頼性は高まっています。 + +中立的なインタープリターは特に有用です。 + +* テキストインタープリターはプログラム構造を明らかにする +* 純粋なインメモリモデルは法則を切り分ける +* トレースインタープリターは選択された観測を明らかにする +* 本番インタープリターは実際の副作用を実行する + +## 等値性がリファクタリングの自由度を決める {#equality-determines-refactoring-freedom} + +あらゆる意味論的等値性が実装の自由度をもたらします。選択した表示で二つの表現が等しいなら、実装では一方を他方に置き換えられます。 + +観測を一つ省くたびに自由度も得られます。割り当て順が意味論上の要件でなければ、変更できます。メソッド順が意味論上の要件なら、変更できません。 + +したがって法則は、正しさの制約であるだけでなく、最適化、置換、進化を安全に行える範囲も定義します。 + +## 確認 {#checkpoint} + +Rustでの符号化に進む前に、次の問いに答えられることを確認します。 + +1. 意味論的な担体は何か。 +2. 抽象化が意図的に捨てるものは何か。 +3. 基本操作はどれか。 +4. 導出される操作はどれか。 +5. どの等値性を使うか。 +6. すべてのインタープリターが保持すべき法則はどれか。 +7. どの証拠をインタープリター間で共有するか。 + +本書の残りでは、Rustを使った実践的な答えを一つ示します。これは意味論的な構図の符号化であり、その置き換えではありません。 diff --git a/src/denotational-design/laws-and-interpretations.ko.md b/src/denotational-design/laws-and-interpretations.ko.md new file mode 100644 index 0000000..0179f5f --- /dev/null +++ b/src/denotational-design/laws-and-interpretations.ko.md @@ -0,0 +1,108 @@ + + +# 법칙과 해석 {#laws-and-interpretations} + +```admonish tip title="관련 항목" +의미론적 관점: [표시적 설계](design.md) +Rust에서 의미로 설계하기: [법칙, 시나리오, 증거](../rust-dd/laws.md), [인터프리터와 효과](../rust-dd/interpreters.md) +개념: [분기와 합류성](../concepts/branching.md) +``` + +```admonish note title="핵심 아이디어" +법칙은 의미론적 인터페이스의 연산들이 어떤 관계를 이루는지 명시하고, 해석은 그 법칙을 보존해야 하는 구체적인 기반 집합을 지정합니다. 어떤 동등성을 선택하느냐에 따라 인터프리터 사이의 어떤 차이가 의미 있고 어떤 차이는 허용되는지가 정해집니다. +``` + +의미론적 인터페이스는 연산의 이름을 정하고, 법칙은 연산 간 관계를 정합니다. 법칙이 없다면 두 구현이 같은 Rust 시그니처를 만족하면서도 추상화의 의미에는 서로 다르게 해석할 수 있습니다. + +## 법칙은 어휘를 완성합니다 {#laws-complete-the-vocabulary} + +분기 위치에 유용한 법칙은 다음과 같습니다: + +$$ \begin{aligned} \operatorname{path}(b,b) &= \lbrack\,\rbrack \\ \operatorname{path}(\operatorname{root}, \operatorname{from\_path}(d_s)) &= d_s \\ \operatorname{from\_path}(\operatorname{path}(\operatorname{root},b)) &= b \\ \operatorname{is\_ancestor}(b,b) &= \mathsf{true} \\ \operatorname{left}(b) &\ne \operatorname{right}(b) \end{aligned} $$ + +이 법칙들은 메서드 주석보다 많은 것을 설명합니다. 항등성, 재구성, 반사성, 분리를 기술합니다. + +그럴듯해 보이는 모든 등식이 유효한 것은 아닙니다. 예를 들어 고정 폭 표현은 매우 깊은 위치에서 오버플로할 수 있습니다. 이는 다음 중 하나입니다: + +* 허용된 영역 밖에서 발생하는 인터프리터의 한계 +* 인터페이스에 드러내야 하는 의미론적 오류 +* 선택한 기반 집합이 잘못되었다는 증거 + +설계에서 어느 경우인지 밝혀야 합니다. + +## 해석 {#interpretation} + +**해석**은 의미론적 대수에 구체적인 기반 집합과 연산을 지정합니다. + +| 의미론적 프로그램 | 가능한 해석 | +| --- | --- | +| 분기 위치 | 비트 경로, 수치 트리, 기호 표현 | +| 표현식 프로그램 | 평가, 예쁘게 출력하기, 최적화 | +| 타입이 있는 API 프로그램 | 실행 가능한 서버 경로, 문서, 클라이언트 생성기 | + +프로그램 자체는 특정 결과 하나와 동일하지 않으므로 같은 프로그램에 여러 해석을 적용할 수 있습니다. + +## 구현 의무 {#implementation-obligations} + +인터프리터는 명세가 주장하는 구조를 보존해야 합니다. + +의미론적 프로그램에서 병합이 결합 법칙을 만족한다면: + +$$ (a \oplus b) \oplus c = a \oplus (b \oplus c) $$ + +인터프리터도 그 결합 방식이 관찰 가능한 의미에 미치는 영향을 보존해야 합니다. 경로 순서 역시 명세에 포함된다면 등식에도 그 순서가 반영되어야 합니다. 순서를 의도적으로 무시한다면 구현상의 동작이 서로 달라도 의미론적으로 동등할 수 있습니다. + +따라서 법칙을 작성하기 전에 의미론적 영역과 동등성부터 선택해야 합니다. + +## 법칙, 증명, 테스트 {#laws-proofs-and-tests} + +이 용어들은 서로 바꿔 쓸 수 없습니다: + +* **법칙**은 추상화에 보편적으로 적용하려는 속성입니다. +* **증명**은 명시된 가정 아래에서 법칙이 성립함을 보입니다. +* **속성 테스트**는 생성된 여러 예를 검사합니다. +* **시나리오 테스트**는 의미 있는 유한 상황 하나를 검사합니다. +* **단위 테스트**는 구체적인 동작 하나를 검사합니다. + +테스트는 실행 가능한 증거이지 보편적 증명은 아닙니다. 그래도 모든 인터프리터에 재사용할 수 있어 가치가 있습니다. + +## 실행 가능한 증거 {#executable-evidence} + +의미론적 법칙은 구현과 독립적입니다. 실행 가능한 검사는 인터프리터가 그 법칙을 보존한다는 유한한 증거를 제공합니다. 속성 검사는 등식 형태의 주장을 점검하고 시나리오는 관찰 가능한 상호작용을 확인합니다. 의미론적 연산만 사용해 작성하면 호환되는 여러 인터프리터에서 같은 증거를 재사용할 수 있습니다. 테스트는 명세를 뒷받침할 뿐, 명세를 정의하거나 증명하지 않습니다. + +Rust 인코딩은 [법칙, 시나리오, 증거](../rust-dd/laws.md)에서 다룹니다. + +## 여러 인터프리터로 의미를 명확히 하기 {#multiple-interpreters-clarify-meaning} + +작은 트레이트마다 두 번째 구현이 필요한 것은 아니지만, 이는 강력한 설계 점검 방법입니다. + +추상적인 법칙을 첫 구현의 필드를 사용해야만 표현할 수 있다면 의미론적 경계가 잘못되었을 가능성이 큽니다. 두 번째 인터프리터가 첫 표현을 흉내 내지 않고 기본 연산을 구현해 같은 법칙을 만족할 수 있다면 추상화의 신뢰성이 높아집니다. + +중립적인 인터프리터는 특히 유용합니다: + +* 텍스트 인터프리터는 프로그램 구조를 드러냅니다 +* 순수한 메모리 모델은 법칙을 분리해 보여 줍니다 +* 추적 인터프리터는 선택된 관찰을 드러냅니다 +* 운영 인터프리터는 실제 효과를 수행합니다 + +## 동등성이 리팩터링의 자유를 결정합니다 {#equality-determines-refactoring-freedom} + +각 의미론적 동등성은 구현상의 자유를 부여합니다. 선택한 표시로 두 표현이 같다면 구현은 하나를 다른 하나로 바꿀 수 있습니다. + +관찰을 생략할 때마다 자유도 생깁니다. 할당 순서가 의미론적 요소가 아니라면 바뀔 수 있습니다. 메서드 순서가 의미론적 요소라면 바뀌어서는 안 됩니다. + +따라서 법칙은 정확성 제약일 뿐 아니라 최적화, 교체, 발전이 안전하게 이루어질 수 있는 범위도 정의합니다. + +## 점검 {#checkpoint} + +Rust 인코딩으로 넘어가기 전에 다음 질문에 답할 수 있는지 확인하세요: + +1. 의미론적 기반 집합은 무엇인가요? +2. 추상화가 의도적으로 잊는 것은 무엇인가요? +3. 어떤 연산이 기본 연산인가요? +4. 어떤 연산을 도출하나요? +5. 어떤 동등성을 사용하나요? +6. 모든 인터프리터가 보존해야 하는 법칙은 무엇인가요? +7. 인터프리터 간에 어떤 증거를 공유하나요? + +책의 나머지 부분에서는 실용적인 Rust 구현 한 가지를 보여 줍니다. 이는 의미론적 관점을 인코딩한 것이지, 그 관점을 대체하는 것은 아닙니다. diff --git a/src/denotational-design/laws-and-interpretations.ru.md b/src/denotational-design/laws-and-interpretations.ru.md new file mode 100644 index 0000000..c8bea82 --- /dev/null +++ b/src/denotational-design/laws-and-interpretations.ru.md @@ -0,0 +1,108 @@ + + +# Законы и интерпретации {#laws-and-interpretations} + +```admonish tip title="Связанные материалы" +«Семантический взгляд»: [Денотационное проектирование](design.md) +«Проектирование на основе смысла в Rust»: [Законы, сценарии и свидетельства](../rust-dd/laws.md), [Интерпретаторы и эффекты](../rust-dd/interpreters.md) +«Понятия»: [Ветвление и конфлюэнтность](../concepts/branching.md) +``` + +```admonish note title="Основная идея" +Законы задают отношения между операциями семантического интерфейса, а интерпретация назначает конкретные носители, которые должны сохранять эти законы. Выбранное отношение равенства определяет, какие различия между интерпретаторами значимы, а какие допустимы. +``` + +Семантический интерфейс называет операции, а законы определяют отношения между ними. Без законов две реализации могут соответствовать одним и тем же сигнатурам Rust, но по-разному понимать абстракцию. + +## Законы дополняют словарь {#laws-complete-the-vocabulary} + +Для позиций в ветвлении полезны такие законы: + +$$ \begin{aligned} \operatorname{path}(b,b) &= \lbrack\,\rbrack \\ \operatorname{path}(\operatorname{root}, \operatorname{from\_path}(d_s)) &= d_s \\ \operatorname{from\_path}(\operatorname{path}(\operatorname{root},b)) &= b \\ \operatorname{is\_ancestor}(b,b) &= \mathsf{true} \\ \operatorname{left}(b) &\ne \operatorname{right}(b) \end{aligned} $$ + +Эти законы говорят больше, чем комментарии к методам: они описывают тождество, восстановление, рефлексивность и различение. + +Не каждое привлекательное равенство верно. Например, представление фиксированной ширины может переполниться на предельной глубине. Это может быть: + +* ограничением интерпретатора за пределами поддерживаемой им области +* семантической ошибкой, которую интерфейс обязан отражать +* свидетельством того, что выбран неподходящий носитель + +Проект должен указывать, какой именно вариант имеет место. + +## Интерпретация {#interpretation} + +**Интерпретация** сопоставляет семантической алгебре конкретные носители и операции. + +| Программа как семантика | Возможные интерпретации | +| --- | --- | +| Позиция в ветвлении | Путь из битов, числовая модель дерева, символьная форма | +| Программа с выражениями | Вычислитель, форматировщик, оптимизатор | +| Программа с типизированным API | Исполняемые маршруты сервера, документация, генератор клиента | + +У одной программы может быть несколько интерпретаций, потому что она не тождественна ни одному из результатов. + +## Обязательства реализации {#implementation-obligations} + +Интерпретатор должен сохранять структуру, заявленную спецификацией. + +Если в семантической программе слияние ассоциативно: + +$$ (a \oplus b) \oplus c = a \oplus (b \oplus c) $$ + +то интерпретаторы должны сохранять наблюдаемый смысл этой ассоциации. Если спецификация задаёт и порядок маршрутов, равенство должно учитывать порядок. Если порядок намеренно опущен, реализации могут различаться операционно, оставаясь семантически равными. + +Поэтому семантическую область и отношение равенства нужно выбрать до формулировки законов. + +## Законы, доказательства и тесты {#laws-proofs-and-tests} + +Эти понятия не взаимозаменяемы: + +* **Закон** — универсальное свойство абстракции, которое должно выполняться. +* **Доказательство** устанавливает закон при заданных предположениях. +* **Тест свойств** проверяет множество сгенерированных примеров. +* **Тест сценария** проверяет одну содержательную конечную ситуацию. +* **Модульный тест** проверяет одно конкретное поведение. + +Тесты — исполняемые свидетельства, а не универсальное доказательство. При этом их ценность в том, что их можно применять к каждому интерпретатору. + +## Исполняемое свидетельство {#executable-evidence} + +Семантические законы не зависят от реализации. Исполняемые проверки дают конечное свидетельство того, что интерпретатор сохраняет эти законы: проверки свойств исследуют утверждения, похожие на уравнения, а сценарии — наблюдаемые взаимодействия. Если формулировать их только через семантические операции, одно и то же свидетельство можно использовать повторно для совместимых интерпретаторов. Тесты поддерживают спецификацию, но не определяют и не доказывают её. + +Способы кодирования в Rust рассматриваются в разделе [«Законы, сценарии и свидетельства»](../rust-dd/laws.md). + +## Несколько интерпретаторов помогают прояснить смысл {#multiple-interpreters-clarify-meaning} + +Не для каждого небольшого трейта нужна вторая реализация, но это мощный способ проверить проектное решение. + +Если закон, объявленный абстрактным, можно сформулировать только через поля первой реализации, семантическая граница, вероятно, выбрана неверно. Если второй интерпретатор способен реализовать примитивы и соблюдать те же законы, не копируя первое представление, доверие к абстракции возрастает. + +Особенно полезны нейтральные интерпретаторы: + +* текстовый интерпретатор раскрывает структуру программы +* чистая модель в памяти изолирует законы +* трассирующий интерпретатор показывает выбранные наблюдения +* промышленный интерпретатор выполняет реальные эффекты + +## Равенство определяет свободу рефакторинга {#equality-determines-refactoring-freedom} + +Каждое семантическое равенство даёт реализации свободу. Если по выбранной денотации два представления равны, реализация может заменить одно другим. + +Свободу даёт и каждое опущенное наблюдение. Если порядок выделения памяти не относится к семантике, его можно изменить. Если порядок вызова методов семантически значим, менять его нельзя. + +Законы — не только ограничения корректности. Они определяют безопасные возможности для оптимизации, замены и развития. + +## Контрольный список {#checkpoint} + +Прежде чем перейти к способам кодирования в Rust, убедитесь, что можете ответить на вопросы: + +1. Каков семантический носитель? +2. Какие детали абстракция намеренно опускает? +3. Какие операции являются примитивными? +4. Какие операции являются производными? +5. Какое отношение равенства используется? +6. Какие законы обязан сохранять каждый интерпретатор? +7. Какие свидетельства будут общими для нескольких интерпретаторов? + +В оставшейся части книги показан один практический способ для Rust. Это кодирование данной семантической картины, а не её замена. diff --git a/src/denotational-design/laws-and-interpretations.uk.md b/src/denotational-design/laws-and-interpretations.uk.md new file mode 100644 index 0000000..bbc0936 --- /dev/null +++ b/src/denotational-design/laws-and-interpretations.uk.md @@ -0,0 +1,108 @@ + + +# Закони та інтерпретації {#laws-and-interpretations} + +```admonish tip title="Пов’язані матеріали" +Семантичний погляд: [Денотаційне проєктування](design.md) +Проєктування від значення в Rust: [Закони, сценарії та свідчення](../rust-dd/laws.md), [Інтерпретатори й ефекти](../rust-dd/interpreters.md) +Поняття: [Розгалуження та конфлюентність](../concepts/branching.md) +``` + +```admonish note title="Основна ідея" +Закони визначають взаємозв’язки між операціями семантичного інтерфейсу, а інтерпретація призначає конкретні носії, зберігаючи ці закони. Вибрана рівність визначає, які відмінності між інтерпретаторами мають значення, а які можна вільно змінювати. +``` + +Семантичний інтерфейс задає назви операцій, а закони визначають їхні взаємозв’язки. Без законів дві реалізації можуть мати однакові сигнатури Rust, але по-різному трактувати абстракцію. + +## Закони доповнюють термінологію {#laws-complete-the-vocabulary} + +Для позицій у розгалуженні корисні такі закони: + +$$ \begin{aligned} \operatorname{path}(b,b) &= \lbrack\,\rbrack \\ \operatorname{path}(\operatorname{root}, \operatorname{from\_path}(d_s)) &= d_s \\ \operatorname{from\_path}(\operatorname{path}(\operatorname{root},b)) &= b \\ \operatorname{is\_ancestor}(b,b) &= \mathsf{true} \\ \operatorname{left}(b) &\ne \operatorname{right}(b) \end{aligned} $$ + +Ці закони пояснюють більше, ніж можуть пояснити коментарі до методів. Вони описують тотожність, відновлення, рефлексивність і розділення. + +Не кожне привабливе рівняння є коректним. Наприклад, представлення з фіксованою шириною може переповнитися на надзвичайно великій глибині. Тоді це або: + +* обмеження інтерпретатора за межами допустимої області +* семантична помилка, яку інтерфейс має оприлюднити +* свідчення того, що вибрано неправильний носій + +Проєктування має визначати, який варіант правильний. + +## Інтерпретація {#interpretation} + +**Інтерпретація** призначає семантичній алгебрі конкретні носії та операції. + +| Семантична програма | Можливі інтерпретації | +| --- | --- | +| Позиція в розгалуженні | Бітовий шлях, числове дерево, символьна форма | +| Програма виразів | Обчислювач, засіб форматування, оптимізатор | +| Програма типізованого API | Маршрути виконуваного сервера, документація, генератор клієнта | + +Та сама програма може мати кілька інтерпретацій, бо вона не тотожна жодному окремому результату. + +## Вимоги до реалізації {#implementation-obligations} + +Інтерпретатор має зберігати структуру, визначену специфікацією. + +Якщо злиття є асоціативним у семантичній програмі: + +$$ (a \oplus b) \oplus c = a \oplus (b \oplus c) $$ + +інтерпретатори мають зберігати спостережуване значення цієї асоціації. Якщо специфікація також визначає порядок маршрутів, рівність має враховувати порядок. Якщо порядок навмисно не береться до уваги, реалізації можуть відрізнятися операційно, залишаючись семантично рівними. + +Саме тому семантичну область і рівність слід вибирати до формулювання законів. + +## Закони, доведення й тести {#laws-proofs-and-tests} + +Ці поняття не взаємозамінні: + +* **Закон** — це властивість абстракції, яка має виконуватися завжди. +* **Доведення** встановлює закон за зазначених припущень. +* **Перевірка властивостей** перевіряє багато згенерованих прикладів. +* **Перевірка сценарію** перевіряє одну змістовну скінченну ситуацію. +* **Модульний тест** перевіряє одну конкретну поведінку. + +Тести — це виконувані свідчення, а не універсальне доведення. Вони все одно цінні, адже їх можна повторно запускати для кожного інтерпретатора. + +## Виконувані свідчення {#executable-evidence} + +Семантичні закони не залежать від реалізацій. Виконувані перевірки дають скінченні свідчення того, що інтерпретатор зберігає ці закони: перевірки властивостей тестують твердження, схожі на рівності, а сценарії — спостережувані взаємодії. Якщо їх сформульовано лише через семантичні операції, ті самі свідчення можна повторно використати для сумісних інтерпретаторів. Тести підтримують специфікацію, але не визначають і не доводять її. + +Кодування в Rust розглянуто в розділі [Закони, сценарії та свідчення](../rust-dd/laws.md). + +## Кілька інтерпретаторів допомагають прояснити значення {#multiple-interpreters-clarify-meaning} + +Для кожного невеликого трейту не обов’язково мати другу реалізацію, але це дієвий спосіб перевірити проєктне рішення. + +Якщо закон, який нібито не залежить від представлення, можна сформулювати лише через поля першої реалізації, семантичну межу, ймовірно, визначено неправильно. Якщо другий інтерпретатор може реалізувати примітиви й виконувати ті самі закони без наслідування першого представлення, абстракція стає переконливішою. + +Особливо корисні інтерпретатори без реальних ефектів: + +* текстовий інтерпретатор виявляє структуру програми +* чиста модель у пам’яті ізолює закони +* трасувальний інтерпретатор виявляє вибрані спостереження +* промисловий інтерпретатор виконує реальні ефекти + +## Рівність визначає свободу рефакторингу {#equality-determines-refactoring-freedom} + +Кожна семантична рівність надає реалізації свободу. Якщо два представлення рівні за вибраною денотацією, реалізація може замінити одне іншим. + +Кожне опущене спостереження також надає свободу. Якщо порядок виділення пам’яті не є семантичним, його можна змінювати. Якщо порядок методів є семантичним, змінювати його не можна. + +Отже, закони — це не лише обмеження коректності. Вони визначають безпечні межі оптимізації, заміни та розвитку. + +## Контрольні запитання {#checkpoint} + +Перш ніж переходити до кодування в Rust, переконайтеся, що можете відповісти на такі запитання: + +1. Що є семантичним носієм? +2. Що абстракція навмисно відкидає? +3. Які операції є примітивними? +4. Які операції є похідними? +5. Яка рівність використовується? +6. Які закони має зберігати кожен інтерпретатор? +7. Які свідчення повторно використовуватимуть різні інтерпретатори? + +Далі в книжці показано один практичний спосіб відповісти на ці запитання мовою Rust. Це кодування семантичного бачення, а не його заміна. diff --git a/src/denotational-design/laws-and-interpretations.vi.md b/src/denotational-design/laws-and-interpretations.vi.md new file mode 100644 index 0000000..116ea95 --- /dev/null +++ b/src/denotational-design/laws-and-interpretations.vi.md @@ -0,0 +1,108 @@ + + +# Định luật và cách diễn giải {#laws-and-interpretations} + +```admonish tip title="Liên quan" +Góc nhìn ngữ nghĩa: [Thiết kế theo ngữ nghĩa](design.md) +Thiết kế theo ngữ nghĩa trong Rust: [Định luật, tình huống và bằng chứng](../rust-dd/laws.md), [Bộ diễn giải và hiệu ứng](../rust-dd/interpreters.md) +Khái niệm: [Phân nhánh và hội tụ](../concepts/branching.md) +``` + +```admonish note title="Ý tưởng cốt lõi" +Các định luật nêu quan hệ giữa những phép toán của giao diện ngữ nghĩa, còn cách diễn giải gán các đối tượng mang cụ thể phải bảo toàn những định luật đó. Đẳng thức được chọn xác định khác biệt nào giữa các bộ diễn giải là có ý nghĩa và khác biệt nào được tự do. +``` + +Giao diện ngữ nghĩa đặt tên cho các phép toán. Định luật nêu quan hệ giữa chúng. Không có định luật, hai cách triển khai có thể cùng đáp ứng chữ ký Rust nhưng vẫn bất đồng về phép trừu tượng. + +## Định luật hoàn thiện từ vựng {#laws-complete-the-vocabulary} + +Với vị trí nhánh, các định luật hữu ích bao gồm: + +$$ \begin{aligned} \operatorname{path}(b,b) &= \lbrack\,\rbrack \\ \operatorname{path}(\operatorname{root}, \operatorname{from\_path}(d_s)) &= d_s \\ \operatorname{from\_path}(\operatorname{path}(\operatorname{root},b)) &= b \\ \operatorname{is\_ancestor}(b,b) &= \mathsf{true} \\ \operatorname{left}(b) &\ne \operatorname{right}(b) \end{aligned} $$ + +Các định luật này giải thích nhiều hơn chú thích phương thức. Chúng mô tả tính đơn vị, phép tái dựng, tính phản xạ và tính phân biệt. + +Không phải phương trình hấp dẫn nào cũng đúng. Chẳng hạn, cách biểu diễn độ rộng cố định có thể tràn ở độ sâu cực lớn. Khi đó, đây là: + +* giới hạn của bộ diễn giải nằm ngoài miền được chấp nhận +* lỗi ngữ nghĩa mà giao diện cần bộc lộ +* bằng chứng cho thấy đối tượng mang được chọn là sai + +Thiết kế phải nêu rõ lựa chọn nào đúng. + +## Diễn giải {#interpretation} + +**Cách diễn giải** gán các đối tượng mang và phép toán cụ thể cho một đại số ngữ nghĩa. + +| Chương trình ngữ nghĩa | Các cách diễn giải khả dĩ | +| --- | --- | +| Vị trí nhánh | Đường đi bit, cây số, dạng ký hiệu | +| Chương trình biểu thức | Bộ đánh giá, bộ in đẹp, bộ tối ưu hóa | +| Chương trình API có kiểu | Các tuyến máy chủ thực thi được, tài liệu, bộ tạo ứng dụng khách | + +Cùng một chương trình có thể có nhiều cách diễn giải vì bản thân chương trình không đồng nhất với bất kỳ kết quả nào. + +## Nghĩa vụ triển khai {#implementation-obligations} + +Bộ diễn giải phải bảo toàn cấu trúc mà đặc tả tuyên bố. + +Nếu phép gộp có tính kết hợp trong chương trình ngữ nghĩa: + +$$ (a \oplus b) \oplus c = a \oplus (b \oplus c) $$ + +thì bộ diễn giải cần bảo toàn ý nghĩa quan sát được của phép kết hợp đó. Nếu thứ tự tuyến cũng được đặc tả, đẳng thức phải bao gồm cả thứ tự. Nếu chủ ý lược bỏ thứ tự, các cách triển khai có thể khác nhau về vận hành nhưng vẫn tương đương ngữ nghĩa. + +Vì vậy cần chọn miền ngữ nghĩa và quan hệ đẳng thức trước khi viết định luật. + +## Định luật, chứng minh và kiểm thử {#laws-proofs-and-tests} + +Các thuật ngữ này không thể thay thế cho nhau: + +* **Định luật** là thuộc tính được dự định áp dụng tổng quát cho phép trừu tượng. +* **Chứng minh** xác lập một định luật dưới các giả định đã nêu. +* **Kiểm thử thuộc tính** kiểm tra nhiều ví dụ được tạo sinh. +* **Kiểm thử tình huống** kiểm tra một trường hợp hữu hạn có ý nghĩa. +* **Kiểm thử đơn vị** kiểm tra một hành vi cụ thể. + +Kiểm thử là bằng chứng có thể thực thi, không phải chứng minh phổ quát. Dù vậy, chúng vẫn hữu ích vì có thể dùng lại với mọi bộ diễn giải. + +## Bằng chứng có thể thực thi {#executable-evidence} + +Các định luật ngữ nghĩa độc lập với cách triển khai. Kiểm tra có thể thực thi cung cấp bằng chứng hữu hạn rằng bộ diễn giải bảo toàn những định luật đó: kiểm tra thuộc tính khảo sát các khẳng định dạng phương trình, còn kiểm tra tình huống khảo sát tương tác quan sát được. Khi chỉ dùng các phép toán ngữ nghĩa, có thể tái sử dụng cùng bằng chứng giữa các bộ diễn giải tương thích. Kiểm thử hỗ trợ đặc tả; chúng không định nghĩa hay chứng minh đặc tả. + +Các cách mã hóa Rust được trình bày trong [Định luật, tình huống và bằng chứng](../rust-dd/laws.md). + +## Nhiều bộ diễn giải giúp làm rõ ý nghĩa {#multiple-interpreters-clarify-meaning} + +Không cần cách triển khai thứ hai cho mọi đặc trưng nhỏ, nhưng đây là phép thử thiết kế mạnh mẽ. + +Nếu một định luật được cho là trừu tượng chỉ có thể phát biểu bằng các trường của cách triển khai đầu tiên, có lẽ ranh giới ngữ nghĩa chưa đúng. Nếu bộ diễn giải thứ hai có thể triển khai các phép toán nguyên thủy và đáp ứng cùng định luật mà không bắt chước cách biểu diễn đầu tiên, thì phép trừu tượng đang trở nên đáng tin hơn. + +Các bộ diễn giải trung lập đặc biệt hữu ích: + +* bộ diễn giải văn bản làm lộ cấu trúc chương trình +* mô hình thuần trong bộ nhớ giúp cô lập các định luật +* bộ diễn giải truy vết làm lộ các quan sát được chọn +* bộ diễn giải sản xuất thực thi các hiệu ứng thực + +## Đẳng thức quyết định quyền tự do tái cấu trúc {#equality-determines-refactoring-freedom} + +Mọi đẳng thức ngữ nghĩa đều trao quyền tự do cho cách triển khai. Nếu hai cách biểu diễn bằng nhau theo ngữ nghĩa chỉ định đã chọn, cách triển khai có thể thay thế cách này bằng cách kia. + +Mọi quan sát bị lược bỏ cũng tạo ra quyền tự do. Nếu thứ tự cấp phát không thuộc ngữ nghĩa thì có thể thay đổi. Nếu thứ tự phương thức thuộc ngữ nghĩa thì không được đổi. + +Vì thế, định luật không chỉ là ràng buộc về tính đúng đắn. Chúng xác định phạm vi an toàn cho tối ưu hóa, thay thế và phát triển. + +## Điểm kiểm tra {#checkpoint} + +Trước khi chuyển sang các cách mã hóa Rust, hãy xác minh bạn có thể trả lời: + +1. Đối tượng mang ngữ nghĩa là gì? +2. Phép trừu tượng chủ ý lược bỏ điều gì? +3. Các phép toán nào là nguyên thủy? +4. Các phép toán nào được suy ra? +5. Đang dùng đẳng thức nào? +6. Mọi bộ diễn giải phải bảo toàn những định luật nào? +7. Bằng chứng nào sẽ được dùng chung giữa các bộ diễn giải? + +Phần còn lại của cuốn sách trình bày một câu trả lời thực tiễn bằng Rust. Đó là cách mã hóa bức tranh ngữ nghĩa này, không phải thứ thay thế nó. diff --git a/src/denotational-design/laws-and-interpretations.zh-hant.md b/src/denotational-design/laws-and-interpretations.zh-hant.md new file mode 100644 index 0000000..91564a5 --- /dev/null +++ b/src/denotational-design/laws-and-interpretations.zh-hant.md @@ -0,0 +1,108 @@ + + +# 定律與解釋 {#laws-and-interpretations} + +```admonish tip title="相關內容" +語義視角:[指稱設計](design.md) +Rust 中的語義驅動設計:[定律、場景與證據](../rust-dd/laws.md)、[直譯器與效應](../rust-dd/interpreters.md) +概念:[分支與合流](../concepts/branching.md) +``` + +```admonish note title="核心思想" +定律說明語義介面中的操作如何相互關聯;解釋則指定必須保留這些定律的具體載體。所選等價關係決定直譯器之間哪些差異有意義,哪些差異可以自由變化。 +``` + +語義介面為操作命名,定律說明這些操作之間的關係。沒有定律時,兩個實作可以滿足相同的 Rust 函式簽名,卻對抽象的含義各執一詞。 + +## 定律補全詞彙 {#laws-complete-the-vocabulary} + +對於分支位置,有用的定律包括: + +$$ \begin{aligned} \operatorname{path}(b,b) &= \lbrack\,\rbrack \\ \operatorname{path}(\operatorname{root}, \operatorname{from\_path}(d_s)) &= d_s \\ \operatorname{from\_path}(\operatorname{path}(\operatorname{root},b)) &= b \\ \operatorname{is\_ancestor}(b,b) &= \mathsf{true} \\ \operatorname{left}(b) &\ne \operatorname{right}(b) \end{aligned} $$ + +這些定律所說明的內容,遠超方法註釋。它們描述了單位元、重構、自反性與分離性。 + +並非每個看起來合理的等式都有效。例如,定寬表示可能在深度極大時溢位。這可能是: + +* 直譯器在其適用域之外的限制 +* 介面必須暴露的語義錯誤 +* 所選載體有誤的證據 + +設計必須說明屬於哪一種。 + +## 解釋 {#interpretation} + +**解釋**為語義代數指定具體載體與操作。 + +| 語義程式 | 可能的解釋 | +| --- | --- | +| 分支位置 | 位路徑、數值樹、符號形式 | +| 表示式程式 | 求值器、漂亮列印器、最佳化器 | +| 型別化 API 程式 | 可執行的伺服器路由、文件、客戶端生成器 | + +同一個程式可以有多種解釋,因為程式並不等同於某一種結果。 + +## 實作義務 {#implementation-obligations} + +直譯器必須保留規範所聲稱的結構。 + +如果語義程式中的合併滿足結合律: + +$$ (a \oplus b) \oplus c = a \oplus (b \oplus c) $$ + +那麼直譯器就應當保留這種結合方式的可觀察含義。如果路由順序也有規範要求,等價關係就必須包含順序。如果有意忽略順序,實作可以在操作層面不同,但仍保持語義等價。 + +因此,必須先選定語義域與等價關係,再編寫定律。 + +## 定律、證明與測試 {#laws-proofs-and-tests} + +這些術語不能互換: + +* **定律**是抽象所普遍要求的性質。 +* **證明**在給定假設下確立某條定律。 +* **性質測試**檢查大量生成的示例。 +* **場景測試**檢查一個有意義的有限情境。 +* **單元測試**檢查一種具體行為。 + +測試是可執行的證據,而非普遍證明。它們仍然很有價值,因為可以用來檢查每個直譯器。 + +## 可執行證據 {#executable-evidence} + +語義定律獨立於其實作。可執行檢查為直譯器是否保留這些定律提供有限證據:性質檢查用於考察類似等式的主張,場景則用於考察可觀察的互動。如果只使用語義操作來編寫,同一組證據就能在相容的直譯器之間複用。測試為規範提供支援,但不定義也不證明規範。 + +Rust 編碼方式見[《定律、場景與證據》](../rust-dd/laws.md)。 + +## 多個直譯器有助於澄清含義 {#multiple-interpreters-clarify-meaning} + +並非每個小型 trait 都需要第二種實作,但第二種實作是一項有力的設計檢驗。 + +如果一條自稱抽象的定律只能用第一種實作的欄位來表述,那麼語義邊界很可能劃錯了。如果第二個直譯器無需模仿第一個表示,就能實作基本操作並滿足同一組定律,那麼這個抽象就更站得住腳。 + +中性直譯器尤其有用: + +* 文字直譯器會揭示程式結構 +* 純記憶體模型會隔離定律 +* 追蹤直譯器會揭示選定的觀察 +* 生產直譯器會執行真實效應 + +## 等價關係決定重構自由度 {#equality-determines-refactoring-freedom} + +每一種語義等價都賦予實作一定自由。如果根據選定的指稱,兩個表示相等,實作就可以互換它們。 + +每一種被忽略的觀察也會帶來自由。如果分配順序不屬於語義,它就可以改變。如果方法順序屬於語義,就不能改變。 + +因此,定律不只是正確性約束。它們還界定了最佳化、替換與演進的安全空間。 + +## 檢查點 {#checkpoint} + +繼續學習 Rust 編碼方式之前,請確認自己能回答: + +1. 語義載體是什麼? +2. 抽象有意忽略了什麼? +3. 哪些操作是基本操作? +4. 哪些操作是派生操作? +5. 採用哪種等價關係? +6. 每個直譯器都必須保留哪些定律? +7. 哪些證據會在直譯器之間共享? + +本書其餘部分將展示一種實用的 Rust 解法。它是這幅語義圖景的一種編碼,而非其替代品。 diff --git a/src/denotational-design/laws-and-interpretations.zh.md b/src/denotational-design/laws-and-interpretations.zh.md new file mode 100644 index 0000000..472ddfa --- /dev/null +++ b/src/denotational-design/laws-and-interpretations.zh.md @@ -0,0 +1,108 @@ + + +# 定律与解释 {#laws-and-interpretations} + +```admonish tip title="相关内容" +语义视角:[指称设计](design.md) +Rust 中的语义驱动设计:[定律、场景与证据](../rust-dd/laws.md)、[解释器与效应](../rust-dd/interpreters.md) +概念:[分支与合流](../concepts/branching.md) +``` + +```admonish note title="核心思想" +定律说明语义接口中的操作如何相互关联;解释则指定必须保留这些定律的具体载体。所选等价关系决定解释器之间哪些差异有意义,哪些差异可以自由变化。 +``` + +语义接口为操作命名,定律说明这些操作之间的关系。没有定律时,两个实现可以满足相同的 Rust 函数签名,却对抽象的含义各执一词。 + +## 定律补全词汇 {#laws-complete-the-vocabulary} + +对于分支位置,有用的定律包括: + +$$ \begin{aligned} \operatorname{path}(b,b) &= \lbrack\,\rbrack \\ \operatorname{path}(\operatorname{root}, \operatorname{from\_path}(d_s)) &= d_s \\ \operatorname{from\_path}(\operatorname{path}(\operatorname{root},b)) &= b \\ \operatorname{is\_ancestor}(b,b) &= \mathsf{true} \\ \operatorname{left}(b) &\ne \operatorname{right}(b) \end{aligned} $$ + +这些定律所说明的内容,远超方法注释。它们描述了单位元、重构、自反性与分离性。 + +并非每个看起来合理的等式都有效。例如,定宽表示可能在深度极大时溢出。这可能是: + +* 解释器在其适用域之外的限制 +* 接口必须暴露的语义错误 +* 所选载体有误的证据 + +设计必须说明属于哪一种。 + +## 解释 {#interpretation} + +**解释**为语义代数指定具体载体与操作。 + +| 语义程序 | 可能的解释 | +| --- | --- | +| 分支位置 | 位路径、数值树、符号形式 | +| 表达式程序 | 求值器、漂亮打印器、优化器 | +| 类型化 API 程序 | 可执行的服务器路由、文档、客户端生成器 | + +同一个程序可以有多种解释,因为程序并不等同于某一种结果。 + +## 实现义务 {#implementation-obligations} + +解释器必须保留规范所声称的结构。 + +如果语义程序中的合并满足结合律: + +$$ (a \oplus b) \oplus c = a \oplus (b \oplus c) $$ + +那么解释器就应当保留这种结合方式的可观察含义。如果路由顺序也有规范要求,等价关系就必须包含顺序。如果有意忽略顺序,实现可以在操作层面不同,但仍保持语义等价。 + +因此,必须先选定语义域与等价关系,再编写定律。 + +## 定律、证明与测试 {#laws-proofs-and-tests} + +这些术语不能互换: + +* **定律**是抽象所普遍要求的性质。 +* **证明**在给定假设下确立某条定律。 +* **性质测试**检查大量生成的示例。 +* **场景测试**检查一个有意义的有限情境。 +* **单元测试**检查一种具体行为。 + +测试是可执行的证据,而非普遍证明。它们仍然很有价值,因为可以用来检查每个解释器。 + +## 可执行证据 {#executable-evidence} + +语义定律独立于其实现。可执行检查为解释器是否保留这些定律提供有限证据:性质检查用于考察类似等式的主张,场景则用于考察可观察的交互。如果只使用语义操作来编写,同一组证据就能在兼容的解释器之间复用。测试为规范提供支持,但不定义也不证明规范。 + +Rust 编码方式见[《定律、场景与证据》](../rust-dd/laws.md)。 + +## 多个解释器有助于澄清含义 {#multiple-interpreters-clarify-meaning} + +并非每个小型 trait 都需要第二种实现,但第二种实现是一项有力的设计检验。 + +如果一条自称抽象的定律只能用第一种实现的字段来表述,那么语义边界很可能划错了。如果第二个解释器无需模仿第一个表示,就能实现基本操作并满足同一组定律,那么这个抽象就更站得住脚。 + +中性解释器尤其有用: + +* 文本解释器会揭示程序结构 +* 纯内存模型会隔离定律 +* 追踪解释器会揭示选定的观察 +* 生产解释器会执行真实效应 + +## 等价关系决定重构自由度 {#equality-determines-refactoring-freedom} + +每一种语义等价都赋予实现一定自由。如果根据选定的指称,两个表示相等,实现就可以互换它们。 + +每一种被忽略的观察也会带来自由。如果分配顺序不属于语义,它就可以改变。如果方法顺序属于语义,就不能改变。 + +因此,定律不只是正确性约束。它们还界定了优化、替换与演进的安全空间。 + +## 检查点 {#checkpoint} + +继续学习 Rust 编码方式之前,请确认自己能回答: + +1. 语义载体是什么? +2. 抽象有意忽略了什么? +3. 哪些操作是基本操作? +4. 哪些操作是派生操作? +5. 采用哪种等价关系? +6. 每个解释器都必须保留哪些定律? +7. 哪些证据会在解释器之间共享? + +本书其余部分将展示一种实用的 Rust 解法。它是这幅语义图景的一种编码,而非其替代品。 diff --git a/src/denotational-design/semantic-view.ar.md b/src/denotational-design/semantic-view.ar.md new file mode 100644 index 0000000..916ccf0 --- /dev/null +++ b/src/denotational-design/semantic-view.ar.md @@ -0,0 +1,143 @@ + + +# لماذا يأتي المعنى أولًا {#why-meaning-comes-first} + +![The semantic view — choosing what a program means before how it runs](../assets/semantic-view.png) + +```admonish tip title="ذات صلة" +المنظور الدلالي: [الدلالات والتركيبية](denotations.md)، [التصميم الدلالي (Denotational Design)](design.md) +التصميم انطلاقًا من المعنى في Rust: [جبر القدرات](../rust-dd/capability-algebras.md) +المفاهيم: [مقدمة](../concepts/index.md) +``` + +```admonish note title="تمهيد" +يختار التصميم الدلالي معنى البرنامج أولًا، ثم يشتق المفردات والتمثيل واستراتيجية التنفيذ التي تحافظ عليه. تقارن هذه الصفحة هذا الترتيب الدلالي بالترتيب الذي يبدأ بالتمثيل وتتّبعه معظم البرمجيات. +``` + +يُصمَّم معظم البرمجيات بالترتيب الذي ستُنفَّذ به: + +1. اختر الحالة. +2. اختر تدفق التحكم. +3. اكشف عن أساليب تحيط بتلك الآليات. +4. اشرح لاحقًا ما كان يُفترض أن تعنيه تلك الأساليب. + +يعكس التصميم الدلالي ذلك الترتيب: + +1. اختر المعنى. +2. حدّد بنيته التركيبية. +3. اشتق المفردات من تلك البنية. +4. اختر التمثيلات واستراتيجيات التنفيذ. +5. تحقّق من أنها تحافظ على المعنى. + +هذا الانعكاس هو المنظور الدلالي. + +```admonish quote title="الآليات والمعنى" +تشرح [المفاهيم](../concepts/index.md) و[الرؤى](../insights/index.md) آليات برمجية مفيدة. أما [التصميم الدلالي (Denotational Design)](design.md) فيشرح كيفية تحديد ما ينبغي لهذه الآليات الحفاظ عليه. +``` + +## ثلاثة أسئلة {#three-questions} + +أبقِ ثلاثة أسئلة منفصلة عند تصميم البرنامج. + +| المنظور | السؤال | مخرجات نموذجية | +| --- | --- | --- | +| دلالي | ما معنى هذا البرنامج؟ | قيم، وعلاقات، ودوال، ومعادلات، وقوانين | +| تمثيلي | كيف يُرمَّز ذلك المعنى؟ | أنواع Rust، والسمات، وأشجار AST، والجداول، والأشجار، والبايت كود | +| تشغيلي | كيف يُنفَّذ التمثيل؟ | حلقات، وتعديلات، ومهام، ورسائل، ومفسرات، وآلات افتراضية | + +المنظورات الثلاثة مهمة. والخطأ هو السماح للتمثيل أو التنفيذ بأن يعرّف المنظور الدلالي ضمنيًا. + +الدلالات التشغيلية وصف دقيق وقيّم للتنفيذ. ويمكنها وصف كل انتقال يجريه المُقيِّم. لكنها تجيب مع ذلك عن سؤال تصميمي مختلف عن الوصف الدلالي. فالسؤال الدلالي هو: ما القيمة الرياضية القابلة للملاحظة التي يدل عليها البرنامج كله، وما المعادلات التي ينبغي أن تصح بصرف النظر عن استراتيجية التنفيذ؟ + +## مثال صغير {#a-small-example} + +لنفترض أن نظامًا يحدد مواقع ضمن عملية متشعبة. + +قد يبدأ التصميم الذي يضع التمثيل أولًا بمتجه بتات: + +```rust,noplayground +struct BranchId(Vec); +``` + +ثم تتكاثر الأساليب حول الحقول: إضافة بت، واقتطاع بادئة، ومقارنة المتجهات، وتسلسل البايتات. + +يبدأ المنظور الدلالي من مكان آخر: + +* هناك موضع جذر. +* يمكن أن يمتد الموضع إلى اليسار أو اليمين. +* قد يكون موضع ما سلفًا لموضع آخر. +* يمكن ملاحظة المسار بين السلف والنسل. + +تظل هذه العبارات ذات معنى حتى لو أصبح التمثيل لاحقًا عددًا صحيحًا أو إحداثيًا في شجرة أو قيمة هجينة مدمجة أو مفتاحًا في قاعدة بيانات. متجه البتات تفسير واحد لموضع فرع، وليس تعريفه. + +## المعنى ليس توثيقًا يُضاف بعد الواقعة {#meaning-is-not-documentation-after-the-fact} + +كتابة نثر يصف واجهة API ملموسة لا تجعل التصميم دلاليًا. يجب أن يقيّد المعنى واجهة API قبل اختيار التمثيل. + +ينبغي للوصف الدلالي أن يبيّن لنا: + +* ما الفروق المهمة +* ما الملاحظات الأولية +* كيف تتركب المعاني الأكبر +* ما المعادلات الصحيحة +* ما الذي يجب على كل تنفيذ الحفاظ عليه +* ما التفاصيل التي تُنسى عمدًا + +إذا كان الأثر الدقيق الوحيد هو بنية حالة أو حلقة تنفيذ، فما زال التنفيذ يملك المعنى. + +## التجريد مقابل المعنى {#abstraction-versus-meaning} + +````admonish warning title="سمة السياق لا تعرّف المعنى" +قد تخفي الواجهة الآليات من دون أن تشرح المعنى: + +```rust,noplayground +trait ApplicationContext { + fn database(&self) -> &Database; + fn settings(&self) -> &Settings; + fn runtime(&self) -> &Runtime; +} +``` + +تجرّد هذه الواجهة الوصول إلى المكونات الملموسة. لكنها لا تحدد الملاحظات الدلالية التي يتطلبها الحساب. +```` + +````admonish success title="اسأل عن المعنى مباشرة" +تطلب الواجهة المتمحورة حول المعنى الملاحظة نفسها: + +```rust,noplayground +trait BranchAlg { + type Branch; + + fn branch_root(&self) -> Self::Branch; + fn branch_grow(&self, branch: &Self::Branch, direction: Direction) -> Self::Branch; + fn branch_path( + &self, + ancestor: &Self::Branch, + descendant: &Self::Branch, + ) -> Option>; +} +``` +```` + +يفيد عكس التبعيات، لكن التصميم الدلالي يتطلب أكثر من ذلك: يجب تنظيم حدّ التجريد حول المعنى لا حول موقع التخزين. + +## اتجاه السلطة {#the-direction-of-authority} + +عندما تختلف الآثار، لا تمنح السلطة للأثر الأقرب إلى الشيفرة القابلة للتشغيل. اسأل عما يتعين على كل أثر الحفاظ عليه. + +| الدور | ما الذي ينتمي إليه | المسؤولية | +| --- | --- | --- | +| **المعنى** | الملاحظات والفروق والتساويات المقصودة في المجال | يحدد المقصود بالصحة | +| **المواصفة** | المجالات الدلالية، والدلالات، والأنواع، والعمليات الأولية، والقوانين، والتركيبات المشتقة | يصرّح بذلك المعنى بدقة | +| **التحقيق** | التمثيلات الملموسة، والمفسرات، والمترجمات، وبيئات التشغيل، والتخزين، والجدولة | ينفذ المواصفة من دون تغييرها | +| **الدليل** | البراهين، وفحوص القوانين، والسيناريوهات، والمقارنات بين المفسرات | يربط التحقيق بالمواصفة؛ لكنه لا يعرّف المعنى بمفرده | + +ينتج عن ذلك قاعدة عملية لحل الخلاف: + +* إذا خالف التنفيذ قانونًا دلاليًا، فغيّر التنفيذ. +* إذا ناقض الاختبار القانون الذي يفترض أن يتحقق منه، فغيّر الاختبار. +* إذا أخفقت المواصفة الصورية في التعبير عن المعنى المقصود للمجال، فراجع المواصفة. + +يُصنَّف الأثر بحسب دوره لا بحسب صياغته. فقد تنتمي سمة Rust أو برنامج من الرتبة الأولى إلى المواصفة عندما يحافظ مباشرة على بنية دلالية مختارة؛ وقد لا يكون نوع Rust آخر سوى ترميز ملموس واحد. وقد تكون الدلالات التشغيلية الصورية جزءًا من مواصفة اللغة أيضًا، لكن تظل انتقالاتها خاضعة للملاحظات والتكافؤات التي تقصدها اللغة. + +يمكن الآن تحديد موضع CPS، وإزالة الدوال، والمونادات الحرة، والآلات الافتراضية، وبيئات تشغيل البروتوكولات، ومسارات المترجمات من دون التساؤل عن التجريد النهائي. فكل منها تمثيل مفيد أو تقنية تنفيذ تناسب مستهلكين معينين. وتحدد المواصفة الدلالية ما يجب على كل تقنية مختارة الحفاظ عليه. diff --git a/src/denotational-design/semantic-view.de.md b/src/denotational-design/semantic-view.de.md new file mode 100644 index 0000000..37c04cd --- /dev/null +++ b/src/denotational-design/semantic-view.de.md @@ -0,0 +1,143 @@ + + +# Warum Bedeutung an erster Stelle steht {#why-meaning-comes-first} + +![The semantic view — choosing what a program means before how it runs](../assets/semantic-view.png) + +```admonish tip title="Verwandte Themen" +The Semantic View: [Denotationen und Kompositionalität](denotations.md), [Denotational Design](design.md) +Design by Meaning in Rust: [Capability-Algebren](../rust-dd/capability-algebras.md) +Concepts: [Einführung](../concepts/index.md) +``` + +```admonish note title="Orientierung" +Denotational Design legt zuerst die Bedeutung eines Programms fest und leitet daraus anschließend Vokabular, Repräsentation und Ausführungsstrategie ab, die diese Bedeutung bewahren. Diese Seite stellt diese semantische Reihenfolge der in den meisten Softwareprojekten üblichen Reihenfolge gegenüber, bei der die Repräsentation an erster Stelle steht. +``` + +Die meisten Softwaresysteme werden in der Reihenfolge entworfen, in der sie ausgeführt werden: + +1. Zustand festlegen. +2. Kontrollfluss festlegen. +3. Methoden um diese Mechanismen herum bereitstellen. +4. Anschließend erklären, was die Methoden bedeuten sollten. + +Denotational Design kehrt diese Reihenfolge um: + +1. Bedeutung festlegen. +2. Die Kompositionsstruktur bestimmen. +3. Aus dieser Struktur ein Vokabular ableiten. +4. Repräsentationen und Ausführungsstrategien auswählen. +5. Überprüfen, ob sie die Bedeutung bewahren. + +Diese Umkehrung ist die semantische Sicht. + +```admonish quote title="Mechanik und Bedeutung" +[Concepts](../concepts/index.md) und [Insights](../insights/index.md) erklären nützliche Programmiermechanismen. [Denotational Design](design.md) erklärt, wie man entscheidet, was diese Mechanismen bewahren sollen. +``` + +## Drei Fragen {#three-questions} + +Halte beim Entwurf eines Programms drei Fragen auseinander. + +| Sicht | Frage | Typische Artefakte | +| --- | --- | --- | +| Semantisch | Was bedeutet dieses Programm? | Werte, Relationen, Funktionen, Gleichungen, Gesetze | +| Repräsentativ | Wie wird diese Bedeutung kodiert? | Rust-Typen, Traits, ASTs, Tabellen, Bäume, Bytecode | +| Operativ | Wie wird die Repräsentation ausgeführt? | Schleifen, Mutation, Tasks, Nachrichten, Interpreter, virtuelle Maschinen | + +Alle drei Sichtweisen sind wichtig. Der Fehler besteht darin, zuzulassen, dass Repräsentation oder Ausführung die semantische Sicht unbemerkt festlegt. + +Eine operationale Semantik beschreibt die Ausführung präzise und auf wertvolle Weise. Sie kann jeden Übergang eines Auswerters darstellen. Dennoch beantwortet sie eine andere Entwurfsfrage als eine denotationelle Darstellung. Die denotationelle Frage lautet, welchen beobachtbaren mathematischen Wert das Gesamtprogramm bezeichnet und welche Gleichungen unabhängig von der Ausführungsstrategie gelten sollen. + +## Ein kleines Beispiel {#a-small-example} + +Angenommen, ein System identifiziert Positionen in einem Verzweigungsprozess. + +Ein repräsentationsorientierter Entwurf könnte mit einem Bitvektor beginnen: + +```rust,noplayground +struct BranchId(Vec); +``` + +Um die Felder herum entstehen dann Methoden: ein Bit anhängen, ein Präfix ausschneiden, Vektoren vergleichen, Bytes serialisieren. + +Die semantische Sicht setzt an einem anderen Punkt an: + +* Es gibt eine Wurzelposition. +* Eine Position kann nach links oder rechts erweitert werden. +* Eine Position kann Vorfahr einer anderen sein. +* Der Pfad zwischen einem Vorfahren und einem Nachfahren lässt sich beobachten. + +Diese Aussagen bleiben sinnvoll, auch wenn die Repräsentation später zu einer Ganzzahl, einer Baumkoordinate, einem kompakten Hybridwert oder einem Datenbankschlüssel wird. Der Bitvektor ist eine Interpretation der Verzweigungsposition, nicht deren Definition. + +## Bedeutung ist keine nachträgliche Dokumentation {#meaning-is-not-documentation-after-the-fact} + +Prosa über eine konkrete API zu schreiben, macht den Entwurf noch nicht denotationell. Die Bedeutung muss die API einschränken, bevor die Repräsentation gewählt wird. + +Eine semantische Darstellung sollte uns sagen: + +* welche Unterscheidungen wichtig sind +* welche Beobachtungen grundlegend sind +* wie sich größere Bedeutungen zusammensetzen +* welche Gleichungen gelten +* was jede Implementierung bewahren muss +* welche Einzelheiten bewusst ausgeblendet werden + +Wenn das einzige präzise Artefakt eine Zustandsstruktur oder eine Ausführungsschleife ist, bestimmt weiterhin die Implementierung die Bedeutung. + +## Abstraktion und Bedeutung {#abstraction-versus-meaning} + +````admonish warning title="Ein Kontext-Trait definiert keine Bedeutung" +Eine Schnittstelle kann Mechanismen verbergen, ohne die Bedeutung zu erklären: + +```rust,noplayground +trait ApplicationContext { + fn database(&self) -> &Database; + fn settings(&self) -> &Settings; + fn runtime(&self) -> &Runtime; +} +``` + +Diese Schnittstelle abstrahiert den Zugriff auf konkrete Komponenten. Sie nennt nicht die semantischen Beobachtungen, die eine Berechnung voraussetzt. +```` + +````admonish success title="Direkt nach der Bedeutung fragen" +Eine bedeutungsorientierte Schnittstelle fragt nach der Beobachtung selbst: + +```rust,noplayground +trait BranchAlg { + type Branch; + + fn branch_root(&self) -> Self::Branch; + fn branch_grow(&self, branch: &Self::Branch, direction: Direction) -> Self::Branch; + fn branch_path( + &self, + ancestor: &Self::Branch, + descendant: &Self::Branch, + ) -> Option>; +} +``` +```` + +Dependency Inversion ist hilfreich, aber Denotational Design verlangt mehr: Die Abstraktionsgrenze muss sich an der Bedeutung statt am Speicherort orientieren. + +## Die Richtung der Autorität {#the-direction-of-authority} + +Wenn Artefakte einander widersprechen, überlasse nicht demjenigen die Deutungshoheit, das dem ausführbaren Code am nächsten ist. Frage, was jedes Artefakt bewahren muss. + +| Rolle | Was hier hingehört | Verantwortung | +| --- | --- | --- | +| **Bedeutung** | Beabsichtigte Beobachtungen, Unterscheidungen und Gleichheiten des Fachgebiets | Legt fest, was Korrektheit bedeutet | +| **Spezifikation** | Semantische Bereiche, Denotationen, Typen, primitive Operationen, Gesetze und abgeleitete Kompositionen | Formuliert diese Bedeutung präzise | +| **Realisierung** | Konkrete Repräsentationen, Interpreter, Compiler, Laufzeitumgebungen, Speicher und Ablaufplanung | Setzt die Spezifikation um, ohne sie zu verändern | +| **Nachweis** | Beweise, Gesetzesprüfungen, Szenarien und Vergleiche zwischen Interpretern | Verknüpft eine Realisierung mit der Spezifikation; definiert die Bedeutung aber nicht selbst | + +Daraus ergibt sich eine praktische Regel zur Klärung von Widersprüchen: + +* Verletzt eine Implementierung ein semantisches Gesetz, ändere die Implementierung. +* Widerspricht ein Test dem Gesetz, das er prüfen sollte, ändere den Test. +* Bringt die formale Spezifikation die beabsichtigte Bedeutung des Fachgebiets nicht zum Ausdruck, überarbeite die Spezifikation. + +Ein Artefakt wird nach seiner Rolle eingeordnet, nicht nach seiner Syntax. Ein Rust-Trait oder ein Programm erster Ordnung kann zur Spezifikation gehören, wenn es die gewählte semantische Struktur direkt bewahrt; ein anderer Rust-Typ kann lediglich eine konkrete Kodierung sein. Auch eine formale operationale Semantik kann Teil einer Sprachspezifikation sein, doch ihre Übergänge müssen sich an den Beobachtungen und Äquivalenzen messen lassen, die die Sprache vorsieht. + +CPS, Defunktionalisierung, freie Monaden, virtuelle Maschinen, Protokoll-Laufzeitumgebungen und Compiler-Pipelines lassen sich nun einordnen, ohne zu fragen, welche davon die endgültige Abstraktion ist. Jede davon ist für bestimmte Nutzer eine nützliche Repräsentations- oder Ausführungstechnik. Die semantische Spezifikation legt fest, was jede gewählte Technik bewahren muss. diff --git a/src/denotational-design/semantic-view.es.md b/src/denotational-design/semantic-view.es.md new file mode 100644 index 0000000..416985e --- /dev/null +++ b/src/denotational-design/semantic-view.es.md @@ -0,0 +1,143 @@ + + +# Por qué el significado va primero {#why-meaning-comes-first} + +![The semantic view — choosing what a program means before how it runs](../assets/semantic-view.png) + +```admonish tip title="Relacionado" +La perspectiva semántica: [Denotaciones y composicionalidad](denotations.md), [Diseño denotacional](design.md) +Diseño por significado en Rust: [Álgebras de capacidades](../rust-dd/capability-algebras.md) +Conceptos: [Introducción](../concepts/index.md) +``` + +```admonish note title="Orientación" +El Diseño denotacional elige primero el significado de un programa y después deriva el vocabulario, la representación y la estrategia de ejecución necesarios para preservarlo. Esta página contrasta ese orden semántico con el orden centrado en la representación que sigue la mayor parte del software. +``` + +La mayoría del software se diseña en el orden en que se ejecutará: + +1. Elegir el estado. +2. Elegir el flujo de control. +3. Exponer métodos alrededor de esos mecanismos. +4. Explicar después qué significado se pretendía dar a los métodos. + +El Diseño denotacional invierte ese orden: + +1. Elegir el significado. +2. Identificar su estructura composicional. +3. Derivar un vocabulario a partir de esa estructura. +4. Elegir representaciones y estrategias de ejecución. +5. Verificar que preservan el significado. + +Esta inversión es la perspectiva semántica. + +```admonish quote title="Mecanismos frente a significado" +[Conceptos](../concepts/index.md) y [Perspectivas](../insights/index.md) explican mecanismos de programación útiles. El [Diseño denotacional](design.md) explica cómo decidir qué deben preservar esos mecanismos. +``` + +## Tres preguntas {#three-questions} + +Al diseñar un programa, mantén separadas tres preguntas. + +| Perspectiva | Pregunta | Artefactos habituales | +| --- | --- | --- | +| Semántica | ¿Qué significa este programa? | valores, relaciones, funciones, ecuaciones, leyes | +| Representacional | ¿Cómo se codifica ese significado? | tipos de Rust, traits, AST, tablas, árboles, bytecode | +| Operacional | ¿Cómo se ejecuta la representación? | bucles, mutaciones, tareas, mensajes, intérpretes, máquinas virtuales | + +Las tres perspectivas importan. El error consiste en permitir que la representación o la ejecución definan silenciosamente la perspectiva semántica. + +La semántica operacional ofrece una explicación precisa y valiosa de la ejecución. Puede describir cada transición que realiza un evaluador. Aun así, responde a una pregunta de diseño distinta de la perspectiva denotacional. La pregunta denotacional es qué valor matemático observable denota el programa completo y qué ecuaciones deben cumplirse independientemente de la estrategia de ejecución. + +## Un ejemplo sencillo {#a-small-example} + +Supongamos que un sistema identifica posiciones en un proceso de ramificación. + +Un diseño centrado en la representación puede empezar con un vector de bits: + +```rust,noplayground +struct BranchId(Vec); +``` + +Después se añaden métodos alrededor de los campos: agregar un bit, extraer un prefijo, comparar vectores y serializar bytes. + +La perspectiva semántica empieza en otro lugar: + +* Existe una posición raíz. +* Una posición puede crecer hacia la izquierda o hacia la derecha. +* Una posición puede ser antecesora de otra. +* Se puede observar el camino entre una posición antecesora y una descendiente. + +Estas afirmaciones siguen teniendo sentido si más adelante la representación se convierte en un entero, una coordenada de árbol, un valor híbrido compacto o una clave de base de datos. El vector de bits es una interpretación de la posición de ramificación, no su definición. + +## El significado no es documentación posterior {#meaning-is-not-documentation-after-the-fact} + +Escribir prosa sobre una API concreta no convierte el diseño en denotacional. El significado debe restringir la API antes de elegir la representación. + +Una descripción semántica debe indicar: + +* qué distinciones importan +* qué observaciones son primitivas +* cómo se componen significados mayores +* qué ecuaciones son válidas +* qué debe preservar cada implementación +* qué detalles se olvidan intencionalmente + +Si el único artefacto preciso es una estructura de estado o un bucle de ejecución, la implementación sigue siendo dueña del significado. + +## Abstracción frente a significado {#abstraction-versus-meaning} + +````admonish warning title="Un trait de contexto no define el significado" +Una interfaz puede ocultar mecanismos sin explicar el significado: + +```rust,noplayground +trait ApplicationContext { + fn database(&self) -> &Database; + fn settings(&self) -> &Settings; + fn runtime(&self) -> &Runtime; +} +``` + +Esta interfaz abstrae el acceso a componentes concretos. No especifica las observaciones semánticas que requiere un cálculo. +```` + +````admonish success title="Pregunta directamente por el significado" +Una interfaz orientada al significado solicita la propia observación: + +```rust,noplayground +trait BranchAlg { + type Branch; + + fn branch_root(&self) -> Self::Branch; + fn branch_grow(&self, branch: &Self::Branch, direction: Direction) -> Self::Branch; + fn branch_path( + &self, + ancestor: &Self::Branch, + descendant: &Self::Branch, + ) -> Option>; +} +``` +```` + +La inversión de dependencias es útil, pero el Diseño denotacional exige más: el límite de abstracción debe organizarse en torno al significado, no a la ubicación del almacenamiento. + +## La dirección de la autoridad {#the-direction-of-authority} + +Cuando los artefactos discrepen, no concedas autoridad al que esté más cerca del código en ejecución. Pregunta qué debe preservar cada artefacto. + +| Rol | Qué corresponde aquí | Responsabilidad | +| --- | --- | --- | +| **Significado** | Observaciones, distinciones e igualdades previstas del dominio | Decide qué significa la corrección | +| **Especificación** | Dominios semánticos, denotaciones, tipos, operaciones primitivas, leyes y composiciones derivadas | Expresa ese significado con precisión | +| **Realización** | Representaciones concretas, intérpretes, compiladores, entornos de ejecución, almacenamiento y planificación | Implementa la especificación sin cambiarla | +| **Evidencia** | Pruebas, verificaciones de leyes, escenarios y comparaciones entre intérpretes | Conecta una realización con la especificación; no define por sí sola el significado | + +Esto ofrece una regla práctica para resolver discrepancias: + +* Si una implementación infringe una ley semántica, cambia la implementación. +* Si una prueba contradice la ley que pretendía comprobar, cambia la prueba. +* Si la especificación formal no expresa el significado previsto del dominio, revisa la especificación. + +Un artefacto se clasifica por su función, no por su sintaxis. Un trait de Rust o un programa de primer orden puede formar parte de la especificación cuando preserva directamente la estructura semántica elegida; otro tipo de Rust puede ser solo una codificación concreta. Una semántica operacional formal también puede formar parte de una especificación de lenguaje, pero sus transiciones siguen respondiendo a las observaciones y equivalencias que pretende el lenguaje. + +Ahora se pueden ubicar CPS, la defuncionalización, las mónadas libres, las máquinas virtuales, los entornos de ejecución de protocolos y las canalizaciones de compilación sin preguntarse cuál es la abstracción definitiva. Cada técnica es una representación o estrategia de ejecución útil para ciertos consumidores. La especificación semántica indica qué debe preservar toda técnica elegida. diff --git a/src/denotational-design/semantic-view.ja.md b/src/denotational-design/semantic-view.ja.md new file mode 100644 index 0000000..9bbb6f6 --- /dev/null +++ b/src/denotational-design/semantic-view.ja.md @@ -0,0 +1,143 @@ + + +# なぜ意味を先に考えるのか {#why-meaning-comes-first} + +![The semantic view — choosing what a program means before how it runs](../assets/semantic-view.png) + +```admonish tip title="関連項目" +意味論的な見方:[表示と合成性](denotations.md)、[Denotational Design](design.md) +Rustで意味から設計する:[ケイパビリティ代数](../rust-dd/capability-algebras.md) +概念:[はじめに](../concepts/index.md) +``` + +```admonish note title="概要" +Denotational Designでは、まずプログラムの意味を定め、それを保つための語彙、表現、実行戦略を導きます。このページでは、この意味論的な順序と、多くのソフトウェアが従う表現先行の順序を対比します。 +``` + +多くのソフトウェアは、実行される順序で設計されます。 + +1. 状態を選ぶ。 +2. 制御フローを選ぶ。 +3. その仕組みを囲むメソッドを公開する。 +4. そのメソッドが何を意味するはずだったのかを後から説明する。 + +Denotational Designでは、この順序を逆にします。 + +1. 意味を選ぶ。 +2. その合成構造を特定する。 +3. その構造から語彙を導く。 +4. 表現と実行戦略を選ぶ。 +5. それらが意味を保つことを検証する。 + +この逆転が意味論的な見方です。 + +```admonish quote title="仕組みと意味" +[概念](../concepts/index.md)と[洞察](../insights/index.md)は、有用なプログラミングの仕組みを解説します。[Denotational Design](design.md)は、その仕組みに何を保持させるべきかを判断する方法を解説します。 +``` + +## 三つの問い {#three-questions} + +プログラムを設計するときは、三つの問いを分けて考えます。 + +| 観点 | 問い | 典型的な成果物 | +| --- | --- | --- | +| 意味論 | このプログラムは何を意味するか。 | 値、関係、関数、等式、法則 | +| 表現 | その意味はどのように符号化されるか。 | Rustの型、トレイト、AST、テーブル、木構造、バイトコード | +| 操作 | その表現はどのように実行されるか。 | ループ、変更、タスク、メッセージ、インタープリター、仮想マシン | + +三つの観点はどれも重要です。表現や実行に意味論的な見方を暗黙に定義させることが誤りです。 + +操作的意味論は、実行を正確に記述する価値ある方法です。評価器が行うすべての遷移を記述できます。それでも、表示に基づく説明とは別の設計上の問いに答えています。表示に基づく問いは、プログラム全体がどの観測可能な数学的値を表すのか、そして実行戦略にかかわらずどの等式が成り立つべきか、というものです。 + +## 小さな例 {#a-small-example} + +分岐する過程の中の位置を識別するシステムを考えます。 + +表現を先に考える設計では、ビットベクトルから始めるかもしれません。 + +```rust,noplayground +struct BranchId(Vec); +``` + +すると各フィールドを中心に、ビットの追加、接頭部分の切り出し、ベクトルの比較、バイト列へのシリアライズといったメソッドが増えていきます。 + +意味論的な見方では、別のところから始めます。 + +* 根となる位置がある。 +* 位置は左または右へ伸ばせる。 +* ある位置が別の位置の祖先である場合がある。 +* 祖先と子孫の間の経路を観測できる。 + +表現が後に整数、木の座標、コンパクトなハイブリッド値、データベースキーのいずれになっても、これらの記述は意味を保ちます。ビットベクトルは分岐位置の一つの解釈であり、その定義ではありません。 + +## 意味は事後的なドキュメントではない {#meaning-is-not-documentation-after-the-fact} + +具体的なAPIについて文章を書いても、設計が表示に基づくものになるわけではありません。表現を選ぶ前に、意味がAPIを制約しなければなりません。 + +意味論的な説明では、次のことが分かる必要があります。 + +* どの違いが重要か +* どの観測が基本となるか +* より大きな意味がどのように合成されるか +* どの等式が妥当か +* あらゆる実装が何を保持すべきか +* どの詳細を意図的に捨てるか + +正確な成果物が状態構造体や実行ループしかないなら、意味を依然として実装が所有しています。 + +## 抽象化と意味 {#abstraction-versus-meaning} + +````admonish warning title="コンテキストのトレイトは意味を定義しない" +インターフェースは仕組みを隠せても、意味を説明するとは限りません。 + +```rust,noplayground +trait ApplicationContext { + fn database(&self) -> &Database; + fn settings(&self) -> &Settings; + fn runtime(&self) -> &Runtime; +} +``` + +このインターフェースは具体的なコンポーネントへのアクセスを抽象化しています。計算に必要な意味論的観測は述べていません。 +```` + +````admonish success title="意味を直接問う" +意味を中心に据えたインターフェースは、観測そのものを求めます。 + +```rust,noplayground +trait BranchAlg { + type Branch; + + fn branch_root(&self) -> Self::Branch; + fn branch_grow(&self, branch: &Self::Branch, direction: Direction) -> Self::Branch; + fn branch_path( + &self, + ancestor: &Self::Branch, + descendant: &Self::Branch, + ) -> Option>; +} +``` +```` + +依存関係の逆転は有用ですが、Denotational Designではさらに、抽象化の境界を格納場所ではなく意味を中心に組織することが求められます。 + +## 権限の所在 {#the-direction-of-authority} + +成果物同士が食い違うとき、実行コードに最も近いものに権限を与えてはいけません。それぞれの成果物が何を保持する責務を負うのかを確認します。 + +| 役割 | ここに含めるもの | 責務 | +| --- | --- | --- | +| **意味** | 対象領域において意図された観測、区別、等値性 | 正しさの意味を決める | +| **仕様** | 意味論的領域、表示、型、基本操作、法則、導出される合成 | その意味を正確に述べる | +| **実現** | 具体的な表現、インタープリター、コンパイラー、ランタイム、格納、スケジューリング | 仕様を変えずに実装する | +| **証拠** | 証明、法則の検査、シナリオ、インタープリター間の比較 | 実現と仕様を結び付ける。単独で意味を定義するものではない | + +この区分から、意見が食い違ったときの実践的な規則が得られます。 + +* 実装が意味論的な法則に違反するなら、実装を変更する。 +* テストが検証対象の法則と矛盾するなら、テストを変更する。 +* 形式仕様が意図された対象領域の意味を表現できていないなら、仕様を改訂する。 + +成果物は構文ではなく役割で分類されます。選択した意味構造を直接保持するRustのトレイトや一階プログラムは仕様に含まれることがあります。一方、別のRust型は具体的な符号化の一つにすぎない場合があります。形式的な操作的意味論も言語仕様の一部になり得ますが、その遷移は、言語が意図する観測と等価性に従う必要があります。 + +CPS、関数のデファンクショナライズ、自由モナド、仮想マシン、プロトコルランタイム、コンパイラーパイプラインを、どれが最終的な抽象化かと問わずに位置付けられるようになります。それぞれ特定の利用者に役立つ表現または実行技法です。意味論的な仕様が、選択したすべての技法に何を保持させるべきかを示します。 diff --git a/src/denotational-design/semantic-view.ko.md b/src/denotational-design/semantic-view.ko.md new file mode 100644 index 0000000..ff46271 --- /dev/null +++ b/src/denotational-design/semantic-view.ko.md @@ -0,0 +1,143 @@ + + +# 왜 의미가 먼저인가 {#why-meaning-comes-first} + +![The semantic view — choosing what a program means before how it runs](../assets/semantic-view.png) + +```admonish tip title="관련 항목" +의미론적 관점: [표시와 합성성](denotations.md), [표시적 설계](design.md) +Rust에서 의미로 설계하기: [케이퍼빌리티 대수](../rust-dd/capability-algebras.md) +개념: [소개](../concepts/index.md) +``` + +```admonish note title="개요" +표시적 설계에서는 프로그램의 의미를 먼저 정한 다음, 그 의미를 보존하도록 어휘, 표현, 실행 전략을 도출합니다. 이 페이지에서는 대부분의 소프트웨어가 따르는 표현 우선 순서와 이러한 의미론적 순서를 대조합니다. +``` + +대부분의 소프트웨어는 실행될 순서에 맞춰 설계됩니다: + +1. 상태를 선택합니다. +2. 제어 흐름을 선택합니다. +3. 그 장치에 맞춰 메서드를 노출합니다. +4. 메서드가 무엇을 의미하도록 의도했는지는 나중에 설명합니다. + +표시적 설계는 그 순서를 뒤집습니다: + +1. 의미를 선택합니다. +2. 의미의 합성 구조를 파악합니다. +3. 그 구조에서 어휘를 도출합니다. +4. 표현과 실행 전략을 선택합니다. +5. 그 표현과 전략이 의미를 보존하는지 검증합니다. + +이러한 역전이 의미론적 관점입니다. + +```admonish quote title="구현 장치와 의미" +[개념](../concepts/index.md)과 [통찰](../insights/index.md)은 유용한 프로그래밍 장치를 설명합니다. [표시적 설계](design.md)는 어떤 장치가 무엇을 보존해야 하는지 결정하는 방법을 설명합니다. +``` + +## 세 가지 질문 {#three-questions} + +프로그램을 설계할 때는 세 가지 질문을 구분하세요. + +| 관점 | 질문 | 일반적인 산출물 | +| --- | --- | --- | +| 의미론적 | 이 프로그램은 무엇을 의미하는가? | 값, 관계, 함수, 등식, 법칙 | +| 표현적 | 그 의미는 어떻게 인코딩되는가? | Rust 타입, 트레이트, AST, 테이블, 트리, 바이트코드 | +| 작동적 | 그 표현은 어떻게 실행되는가? | 루프, 변경, 태스크, 메시지, 인터프리터, 가상 머신 | + +세 관점은 모두 중요합니다. 표현이나 실행이 의미론적 관점을 소리 없이 정의하도록 두는 것이 문제입니다. + +작동적 의미론은 실행을 정확하고 가치 있게 설명합니다. 평가기가 수행하는 모든 전이를 기술할 수 있습니다. 그러나 표시적 설명과는 다른 설계 질문에 답합니다. 표시적 관점에서 묻는 것은 프로그램 전체가 나타내는 관찰 가능한 수학적 값이 무엇인지, 그리고 실행 전략과 무관하게 어떤 등식이 성립해야 하는지입니다. + +## 간단한 예 {#a-small-example} + +분기 구조에서 위치를 식별하는 시스템을 생각해 봅시다. + +표현 우선 설계는 비트 벡터에서 시작할 수 있습니다: + +```rust,noplayground +struct BranchId(Vec); +``` + +그런 다음 필드에 맞춰 메서드가 늘어납니다. 비트 추가, 접두부 자르기, 벡터 비교, 바이트 직렬화 등이 그 예입니다. + +의미론적 관점은 다른 곳에서 시작합니다: + +* 루트 위치가 있습니다. +* 위치는 왼쪽이나 오른쪽으로 확장할 수 있습니다. +* 한 위치가 다른 위치의 조상일 수 있습니다. +* 조상과 자손 사이의 경로를 관찰할 수 있습니다. + +표현이 나중에 정수, 트리 좌표, 압축 하이브리드 값, 데이터베이스 키로 바뀌더라도 이러한 설명은 여전히 의미가 있습니다. 비트 벡터는 분기 위치를 해석하는 한 가지 방법일 뿐, 그 정의 자체는 아닙니다. + +## 의미는 사후 문서화가 아닙니다 {#meaning-is-not-documentation-after-the-fact} + +구체적인 API를 설명하는 글을 쓴다고 설계가 표시적이 되는 것은 아닙니다. 표현을 선택하기 전에 의미가 API를 제약해야 합니다. + +의미론적 설명은 다음을 알려야 합니다: + +* 어떤 구분이 중요한지 +* 어떤 관찰이 원시적인지 +* 더 큰 의미가 어떻게 합성되는지 +* 어떤 등식이 유효한지 +* 모든 구현이 무엇을 보존해야 하는지 +* 어떤 세부 사항을 의도적으로 버리는지 + +정확한 산출물이 상태 구조체나 실행 루프뿐이라면, 의미는 여전히 구현에 좌우됩니다. + +## 추상화와 의미 {#abstraction-versus-meaning} + +````admonish warning title="컨텍스트 트레이트는 의미를 정의하지 않습니다" +인터페이스는 의미를 설명하지 않은 채 구현 장치를 감출 수 있습니다: + +```rust,noplayground +trait ApplicationContext { + fn database(&self) -> &Database; + fn settings(&self) -> &Settings; + fn runtime(&self) -> &Runtime; +} +``` + +이 인터페이스는 구체적인 구성 요소에 대한 접근을 추상화합니다. 계산에 필요한 의미론적 관찰을 명시하지는 않습니다. +```` + +````admonish success title="의미를 직접 묻기" +의미 중심 인터페이스는 관찰 자체를 요청합니다: + +```rust,noplayground +trait BranchAlg { + type Branch; + + fn branch_root(&self) -> Self::Branch; + fn branch_grow(&self, branch: &Self::Branch, direction: Direction) -> Self::Branch; + fn branch_path( + &self, + ancestor: &Self::Branch, + descendant: &Self::Branch, + ) -> Option>; +} +``` +```` + +의존성 역전은 유용하지만 표시적 설계는 더 많은 것을 요구합니다. 추상화 경계는 저장 위치가 아니라 의미를 중심으로 구성해야 합니다. + +## 권한의 방향 {#the-direction-of-authority} + +산출물들이 서로 다를 때 실행 코드에 가장 가까운 것에 권위를 주지 마세요. 각 산출물이 무엇을 보존해야 하는지 물으세요. + +| 역할 | 여기에 속하는 것 | 책임 | +| --- | --- | --- | +| **의미** | 해당 영역에서 의도한 관찰, 구분, 등식 | 정확성의 의미를 결정합니다 | +| **명세** | 의미론적 영역, 표시, 타입, 기본 연산, 법칙, 파생 합성 | 그 의미를 정확하게 기술합니다 | +| **실현** | 구체적 표현, 인터프리터, 컴파일러, 런타임, 저장소, 스케줄링 | 명세를 바꾸지 않고 구현합니다 | +| **증거** | 증명, 법칙 검사, 시나리오, 인터프리터 간 비교 | 실현을 명세와 연결하지만, 그 자체로 의미를 정의하지는 않습니다 | + +이 구분은 의견이 다를 때 해결하는 실용적인 규칙을 제공합니다: + +* 구현이 의미론적 법칙을 위반하면 구현을 고칩니다. +* 테스트가 검사하려던 법칙과 모순되면 테스트를 고칩니다. +* 형식 명세가 의도한 영역의 의미를 표현하지 못하면 명세를 수정합니다. + +산출물은 문법이 아니라 역할에 따라 분류합니다. Rust 트레이트나 일차 프로그램은 선택한 의미 구조를 직접 보존한다면 명세에 속할 수 있고, 다른 Rust 타입은 하나의 구체적인 인코딩일 수 있습니다. 형식적 작동 의미론도 언어 명세의 일부일 수 있지만, 그 전이 역시 언어가 의도한 관찰 및 동치 관계에 부합해야 합니다. + +이제 CPS, 디펑셔널라이제이션, 자유 모나드, 가상 머신, 프로토콜 런타임, 컴파일러 파이프라인 중 무엇이 최종 추상화인지 따지지 않고도 각각을 제자리에 둘 수 있습니다. 이들은 특정 사용자를 위한 유용한 표현 또는 실행 기법입니다. 의미론적 명세는 선택된 모든 기법이 무엇을 보존해야 하는지 알려줍니다. diff --git a/src/denotational-design/semantic-view.ru.md b/src/denotational-design/semantic-view.ru.md new file mode 100644 index 0000000..0ab8abb --- /dev/null +++ b/src/denotational-design/semantic-view.ru.md @@ -0,0 +1,143 @@ + + +# Почему начинать нужно со смысла {#why-meaning-comes-first} + +![The semantic view — choosing what a program means before how it runs](../assets/semantic-view.png) + +```admonish tip title="Связанные материалы" +«Семантический взгляд»: [Денотации и композиционность](denotations.md), [Денотационное проектирование](design.md) +«Проектирование на основе смысла в Rust»: [Алгебры возможностей](../rust-dd/capability-algebras.md) +«Понятия»: [Введение](../concepts/index.md) +``` + +```admonish note title="Обзор" +Денотационное проектирование сначала определяет смысл программы, а затем выводит из него словарь понятий, представление и стратегию выполнения, которые этот смысл сохраняют. На этой странице семантический порядок сопоставляется с порядком «сначала представление», которому следует большинство программных систем. +``` + +Большинство программ проектируют в том порядке, в котором они будут выполняться: + +1. Выбрать состояние. +2. Выбрать поток управления. +3. Определить методы вокруг этих механизмов. +4. Затем объяснить, какой смысл предполагалось вложить в методы. + +Денотационное проектирование меняет этот порядок на обратный: + +1. Определить смысл. +2. Выявить его композиционную структуру. +3. Вывести из этой структуры словарь понятий. +4. Выбрать представления и стратегии выполнения. +5. Проверить, что они сохраняют смысл. + +Это и есть семантический взгляд. + +```admonish quote title="Механизмы и смысл" +[«Понятия»](../concepts/index.md) и [«Идеи»](../insights/index.md) объясняют полезные механизмы программирования. [Денотационное проектирование](design.md) объясняет, как решить, что именно эти механизмы должны сохранять. +``` + +## Три вопроса {#three-questions} + +При проектировании программы не смешивайте три вопроса. + +| Взгляд | Вопрос | Типичные артефакты | +| --- | --- | --- | +| Семантический | Что означает эта программа? | значения, отношения, функции, уравнения, законы | +| Репрезентационный | Как закодирован этот смысл? | типы Rust, трейты, AST, таблицы, деревья, байткод | +| Операционный | Как выполняется это представление? | циклы, мутации, задачи, сообщения, интерпретаторы, виртуальные машины | + +Важны все три взгляда. Ошибка — позволить представлению или выполнению незаметно определять семантический взгляд. + +Операционная семантика даёт точное и ценное описание выполнения. Она может описывать каждый переход, выполняемый вычислителем. Но она отвечает на другой проектный вопрос, чем денотационное описание. Денотационный вопрос состоит в том, какому наблюдаемому математическому значению соответствует программа целиком и какие равенства должны выполняться независимо от стратегии выполнения. + +## Небольшой пример {#a-small-example} + +Предположим, система задаёт позиции в ветвящемся процессе. + +Проектирование от представления может начаться с битового вектора: + +```rust,noplayground +struct BranchId(Vec); +``` + +Затем вокруг полей появляются методы: добавить бит, взять префикс, сравнить векторы, сериализовать байты. + +Семантический взгляд начинает с другого: + +* Есть корневая позиция. +* Позицию можно продолжить влево или вправо. +* Одна позиция может быть предком другой. +* Можно наблюдать путь от предка к потомку. + +Эти утверждения остаются осмысленными, даже если позднее представление станет целым числом, координатой дерева, компактным гибридным значением или ключом базы данных. Битовый вектор — одна из интерпретаций позиции в ветвлении, а не её определение. + +## Смысл — не пояснение задним числом {#meaning-is-not-documentation-after-the-fact} + +Описание конкретного API прозой само по себе не делает проектирование денотационным. Смысл должен ограничивать API до выбора представления. + +Семантическое описание должно указывать: + +* какие различия важны +* какие наблюдения являются первичными +* как складываются более сложные значения +* какие равенства верны +* что обязана сохранять каждая реализация +* какие детали намеренно опускаются + +Если единственные точные артефакты — структура состояния или цикл выполнения, реализация по-прежнему задаёт смысл. + +## Абстракция и смысл {#abstraction-versus-meaning} + +````admonish warning title="Трейт контекста не определяет смысл" +Интерфейс может скрыть механизмы, не объясняя смысл: + +```rust,noplayground +trait ApplicationContext { + fn database(&self) -> &Database; + fn settings(&self) -> &Settings; + fn runtime(&self) -> &Runtime; +} +``` + +Этот интерфейс абстрагирует доступ к конкретным компонентам. Он не задаёт семантические наблюдения, необходимые вычислению. +```` + +````admonish success title="Запрашивать смысл напрямую" +Интерфейс, ориентированный на смысл, запрашивает само наблюдение: + +```rust,noplayground +trait BranchAlg { + type Branch; + + fn branch_root(&self) -> Self::Branch; + fn branch_grow(&self, branch: &Self::Branch, direction: Direction) -> Self::Branch; + fn branch_path( + &self, + ancestor: &Self::Branch, + descendant: &Self::Branch, + ) -> Option>; +} +``` +```` + +Инверсия зависимостей полезна, но денотационное проектирование требует большего: граница абстракции должна строиться вокруг смысла, а не места хранения. + +## Кому принадлежит решающее слово {#the-direction-of-authority} + +Если артефакты противоречат друг другу, не отдавайте решающее слово тому, который ближе всего к исполняемому коду. Спросите, что каждый артефакт обязан сохранять. + +| Роль | Что относится к этой роли | Ответственность | +| --- | --- | --- | +| **Смысл** | Задуманные наблюдения, различия и равенства предметной области | Определяет, что считать корректностью | +| **Спецификация** | Семантические области, денотации, типы, примитивные операции, законы и производные композиции | Точно формулирует этот смысл | +| **Воплощение** | Конкретные представления, интерпретаторы, компиляторы, среды выполнения, хранение и планирование | Реализует спецификацию, не изменяя её | +| **Подтверждение** | Доказательства, проверки законов, сценарии и сравнения разных интерпретаторов | Связывает воплощение со спецификацией, но само по себе не определяет смысл | + +Отсюда следует практическое правило разрешения разногласий: + +* Если реализация нарушает семантический закон, измените реализацию. +* Если тест противоречит закону, который он должен проверять, измените тест. +* Если формальная спецификация не выражает предполагаемый смысл предметной области, пересмотрите спецификацию. + +Артефакт классифицируется по своей роли, а не по синтаксису. Трейт Rust или программа первого порядка могут относиться к спецификации, если напрямую сохраняют выбранную семантическую структуру; другой тип Rust может быть лишь одним конкретным способом кодирования. Формальная операционная семантика тоже может входить в спецификацию языка, но её переходы должны соответствовать наблюдениям и эквивалентностям, которые подразумевает язык. + +Теперь CPS, дефункционализацию, свободные монады, виртуальные машины, среды выполнения протоколов и конвейеры компиляции можно рассматривать без вопроса, какой из них является окончательной абстракцией. Каждый из этих подходов — полезный способ представления или выполнения для определённых потребителей. Семантическая спецификация задаёт, что обязана сохранять каждая выбранная техника. diff --git a/src/denotational-design/semantic-view.uk.md b/src/denotational-design/semantic-view.uk.md new file mode 100644 index 0000000..4f58e79 --- /dev/null +++ b/src/denotational-design/semantic-view.uk.md @@ -0,0 +1,143 @@ + + +# Чому значення має бути першим {#why-meaning-comes-first} + +![The semantic view — choosing what a program means before how it runs](../assets/semantic-view.png) + +```admonish tip title="Пов’язані матеріали" +Семантичний погляд: [Денотації та композиційність](denotations.md), [Денотаційне проєктування](design.md) +Проєктування від значення в Rust: [Алгебри можливостей](../rust-dd/capability-algebras.md) +Поняття: [Вступ](../concepts/index.md) +``` + +```admonish note title="Вступний огляд" +Денотаційне проєктування спершу визначає значення програми, а потім виводить із нього термінологію, представлення та стратегію виконання, що мають це значення зберегти. На цій сторінці цей семантичний порядок зіставлено з порядком, у якому спочатку визначають представлення, — саме так створюють більшість програмного забезпечення. +``` + +Більшість програмного забезпечення проєктують у порядку його виконання: + +1. Вибрати стан. +2. Вибрати потік керування. +3. Створити методи навколо цих механізмів. +4. Потім пояснити, що мали означати ці методи. + +Денотаційне проєктування змінює цей порядок на протилежний: + +1. Визначити значення. +2. Виявити його композиційну структуру. +3. Вивести термінологію з цієї структури. +4. Вибрати представлення та стратегії виконання. +5. Переконатися, що вони зберігають значення. + +Це і є семантичний погляд. + +```admonish quote title="Механізми та значення" +[Поняття](../concepts/index.md) й [Інсайти](../insights/index.md) пояснюють корисні механізми програмування. [Денотаційне проєктування](design.md) пояснює, як визначити, що саме ці механізми мають зберігати. +``` + +## Три запитання {#three-questions} + +Під час проєктування програми розглядайте три запитання окремо. + +| Погляд | Запитання | Типові артефакти | +| --- | --- | --- | +| Семантичний | Що означає ця програма? | значення, відношення, функції, рівняння, закони | +| Репрезентаційний | Як закодовано це значення? | типи Rust, трейти, AST, таблиці, дерева, байткод | +| Операційний | Як виконується це представлення? | цикли, мутації, завдання, повідомлення, інтерпретатори, віртуальні машини | + +Усі три погляди важливі. Помилка полягає в тому, що представлення чи виконання непомітно визначає семантичний погляд. + +Операційна семантика — це точний і цінний опис виконання. Вона може описати кожен перехід, який здійснює обчислювач. Однак вона відповідає на інше проєктне запитання, ніж денотаційний опис. Денотаційне запитання полягає в тому, яке спостережуване математичне значення позначає програма як ціле та які рівності мають виконуватися незалежно від стратегії виконання. + +## Невеликий приклад {#a-small-example} + +Уявімо систему, яка позначає позиції в процесі розгалуження. + +Проєктування, у якому спершу визначають представлення, може початися з бітового вектора: + +```rust,noplayground +struct BranchId(Vec); +``` + +Потім навколо полів додають методи: дописати біт, узяти зріз префікса, порівняти вектори, серіалізувати байти. + +Семантичний погляд починається з іншого: + +* Є коренева позиція. +* Позицію можна розширити ліворуч або праворуч. +* Одна позиція може бути предком іншої. +* Можна спостерігати шлях між предком і нащадком. + +Ці твердження залишаються змістовними, навіть якщо згодом представлення зміниться на ціле число, координату в дереві, компактне гібридне значення або ключ бази даних. Бітовий вектор — це одна з інтерпретацій позиції в розгалуженні, а не її визначення. + +## Значення — це не документація постфактум {#meaning-is-not-documentation-after-the-fact} + +Опис конкретного API прозою не робить проєктування денотаційним. Значення має задавати обмеження для API до того, як вибрано представлення. + +Семантичний опис має визначати: + +* які відмінності мають значення +* які спостереження є примітивними +* як поєднуються складніші значення +* які рівності є коректними +* що має зберігати кожна реалізація +* які деталі навмисно відкинуто + +Якщо єдиним точним артефактом є структура стану чи цикл виконання, то значення все ще визначається реалізацією. + +## Абстракція та значення {#abstraction-versus-meaning} + +````admonish warning title="Трейт контексту не визначає значення" +Інтерфейс може приховувати механізми, не пояснюючи значення: + +```rust,noplayground +trait ApplicationContext { + fn database(&self) -> &Database; + fn settings(&self) -> &Settings; + fn runtime(&self) -> &Runtime; +} +``` + +Цей інтерфейс абстрагує доступ до конкретних компонентів. Він не визначає семантичних спостережень, потрібних для обчислення. +```` + +````admonish success title="Запитуйте про значення безпосередньо" +Інтерфейс, орієнтований на значення, запитує саме про спостереження: + +```rust,noplayground +trait BranchAlg { + type Branch; + + fn branch_root(&self) -> Self::Branch; + fn branch_grow(&self, branch: &Self::Branch, direction: Direction) -> Self::Branch; + fn branch_path( + &self, + ancestor: &Self::Branch, + descendant: &Self::Branch, + ) -> Option>; +} +``` +```` + +Інверсія залежностей корисна, але денотаційне проєктування вимагає більшого: межу абстракції слід організувати навколо значення, а не місця зберігання. + +## Напрямок визначення {#the-direction-of-authority} + +Коли артефакти суперечать один одному, не надавайте перевагу тому, який найближчий до виконуваного коду. З’ясуйте, що саме кожен артефакт має зберігати. + +| Роль | Що тут має бути | Відповідальність | +| --- | --- | --- | +| **Значення** | Передбачені спостереження, відмінності та рівності предметної області | Визначає, що вважається коректністю | +| **Специфікація** | Семантичні області, денотації, типи, примітивні операції, закони та похідні композиції | Точно формулює це значення | +| **Реалізація** | Конкретні представлення, інтерпретатори, компілятори, середовища виконання, сховища та планувальники | Втілює специфікацію, не змінюючи її | +| **Підтвердження** | Доведення, перевірки законів, сценарії та порівняння різних інтерпретаторів | Пов’язує реалізацію зі специфікацією, але саме по собі не визначає значення | + +Звідси випливає практичне правило розв’язання суперечностей: + +* Якщо реалізація порушує семантичний закон, змініть реалізацію. +* Якщо тест суперечить закону, який мав перевіряти, змініть тест. +* Якщо формальна специфікація не виражає задумане значення предметної області, перегляньте специфікацію. + +Артефакт класифікують за його роллю, а не синтаксисом. Трейт Rust або програма першого порядку можуть належати до специфікації, якщо безпосередньо зберігають вибрану семантичну структуру; інший тип Rust може бути лише одним конкретним кодуванням. Формальна операційна семантика також може бути частиною специфікації мови, але її переходи мають відповідати спостереженням і еквівалентностям, закладеним у задум мови. + +Тепер CPS, дефункціоналізацію, вільні монади, віртуальні машини, середовища виконання протоколів і конвеєри компіляції можна розглядати без запитання, який із них є остаточною абстракцією. Кожен із цих підходів — корисна техніка представлення чи виконання для певних споживачів. Семантична специфікація визначає, що має зберігати кожна вибрана техніка. diff --git a/src/denotational-design/semantic-view.vi.md b/src/denotational-design/semantic-view.vi.md new file mode 100644 index 0000000..14b0679 --- /dev/null +++ b/src/denotational-design/semantic-view.vi.md @@ -0,0 +1,143 @@ + + +# Vì sao ý nghĩa được đặt lên trước {#why-meaning-comes-first} + +![The semantic view — choosing what a program means before how it runs](../assets/semantic-view.png) + +```admonish tip title="Liên quan" +Góc nhìn ngữ nghĩa: [Ngữ nghĩa và tính hợp thành](denotations.md), [Thiết kế theo ngữ nghĩa](design.md) +Thiết kế theo ngữ nghĩa trong Rust: [Các đại số năng lực](../rust-dd/capability-algebras.md) +Khái niệm: [Giới thiệu](../concepts/index.md) +``` + +```admonish note title="Định hướng" +Thiết kế theo ngữ nghĩa chọn ý nghĩa của chương trình trước, rồi suy ra từ vựng, cách biểu diễn và chiến lược thực thi để bảo toàn ý nghĩa đó. Trang này đối chiếu thứ tự ngữ nghĩa ấy với cách thiết kế ưu tiên biểu diễn mà phần lớn phần mềm đang theo. +``` + +Phần lớn phần mềm được thiết kế theo thứ tự mà nó sẽ chạy: + +1. Chọn trạng thái. +2. Chọn luồng điều khiển. +3. Tạo các phương thức xoay quanh cơ chế đó. +4. Sau đó mới giải thích các phương thức được dự định mang ý nghĩa gì. + +Thiết kế theo ngữ nghĩa đảo ngược thứ tự ấy: + +1. Chọn ý nghĩa. +2. Xác định cấu trúc hợp thành của ý nghĩa. +3. Suy ra từ vựng từ cấu trúc đó. +4. Chọn cách biểu diễn và chiến lược thực thi. +5. Xác minh rằng chúng bảo toàn ý nghĩa. + +Sự đảo ngược này chính là góc nhìn ngữ nghĩa. + +```admonish quote title="Cơ chế và ý nghĩa" +[Các khái niệm](../concepts/index.md) và [nhận định](../insights/index.md) giải thích những cơ chế lập trình hữu ích. [Thiết kế theo ngữ nghĩa](design.md) giải thích cách xác định cơ chế cần bảo toàn điều gì. +``` + +## Ba câu hỏi {#three-questions} + +Khi thiết kế chương trình, hãy tách biệt ba câu hỏi. + +| Góc nhìn | Câu hỏi | Sản phẩm thường gặp | +| --- | --- | --- | +| Ngữ nghĩa | Chương trình này có ý nghĩa gì? | giá trị, quan hệ, hàm, phương trình, định luật | +| Biểu diễn | Ý nghĩa đó được mã hóa như thế nào? | kiểu Rust, đặc trưng, AST, bảng, cây, bytecode | +| Vận hành | Cách biểu diễn được thực thi ra sao? | vòng lặp, biến đổi trạng thái, tác vụ, thông điệp, bộ diễn giải, máy ảo | + +Cả ba góc nhìn đều quan trọng. Sai lầm là để biểu diễn hoặc thực thi âm thầm định nghĩa góc nhìn ngữ nghĩa. + +Ngữ nghĩa vận hành là mô tả chính xác và có giá trị về việc thực thi. Nó có thể mô tả mọi chuyển tiếp mà bộ đánh giá thực hiện. Tuy vậy, nó vẫn trả lời một câu hỏi thiết kế khác với cách tiếp cận ngữ nghĩa chỉ định. Câu hỏi ngữ nghĩa chỉ định là chương trình hoàn chỉnh biểu thị giá trị toán học quan sát được nào và những phương trình nào phải đúng bất kể chiến lược thực thi. + +## Một ví dụ nhỏ {#a-small-example} + +Giả sử một hệ thống xác định các vị trí trong một quá trình phân nhánh. + +Thiết kế ưu tiên biểu diễn có thể bắt đầu bằng một vectơ bit: + +```rust,noplayground +struct BranchId(Vec); +``` + +Sau đó, các phương thức phát sinh quanh những trường dữ liệu: nối thêm bit, lấy lát cắt tiền tố, so sánh vectơ, tuần tự hóa byte. + +Góc nhìn ngữ nghĩa bắt đầu từ nơi khác: + +* Có một vị trí gốc. +* Một vị trí có thể mở rộng sang trái hoặc phải. +* Một vị trí có thể là tổ tiên của vị trí khác. +* Có thể quan sát đường đi giữa tổ tiên và hậu duệ. + +Những phát biểu đó vẫn có ý nghĩa nếu sau này cách biểu diễn trở thành số nguyên, tọa độ cây, giá trị lai gọn nhẹ hoặc khóa cơ sở dữ liệu. Vectơ bit là một cách diễn giải vị trí nhánh, chứ không phải định nghĩa của nó. + +## Ý nghĩa không phải phần tài liệu viết sau cùng {#meaning-is-not-documentation-after-the-fact} + +Viết văn xuôi về một API cụ thể không biến thiết kế thành thiết kế ngữ nghĩa chỉ định. Ý nghĩa phải ràng buộc API trước khi chọn cách biểu diễn. + +Một mô tả ngữ nghĩa cần cho biết: + +* những khác biệt nào quan trọng +* những quan sát nào là nguyên thủy +* các ý nghĩa lớn hơn hợp thành ra sao +* những phương trình nào hợp lệ +* mọi cách triển khai phải bảo toàn điều gì +* những chi tiết nào được chủ ý lược bỏ + +Nếu sản phẩm duy nhất có độ chính xác là một cấu trúc trạng thái hoặc vòng lặp thực thi, thì ý nghĩa vẫn thuộc về phần triển khai. + +## Trừu tượng hóa và ý nghĩa {#abstraction-versus-meaning} + +````admonish warning title="Đặc trưng ngữ cảnh không định nghĩa ý nghĩa" +Giao diện có thể che giấu cơ chế mà không giải thích ý nghĩa: + +```rust,noplayground +trait ApplicationContext { + fn database(&self) -> &Database; + fn settings(&self) -> &Settings; + fn runtime(&self) -> &Runtime; +} +``` + +Giao diện này trừu tượng hóa quyền truy cập vào các thành phần cụ thể. Nó không nêu các quan sát ngữ nghĩa mà phép tính cần có. +```` + +````admonish success title="Hỏi trực tiếp về ý nghĩa" +Giao diện định hướng theo ý nghĩa yêu cầu chính quan sát đó: + +```rust,noplayground +trait BranchAlg { + type Branch; + + fn branch_root(&self) -> Self::Branch; + fn branch_grow(&self, branch: &Self::Branch, direction: Direction) -> Self::Branch; + fn branch_path( + &self, + ancestor: &Self::Branch, + descendant: &Self::Branch, + ) -> Option>; +} +``` +```` + +Đảo ngược phụ thuộc rất hữu ích, nhưng Thiết kế theo ngữ nghĩa đòi hỏi nhiều hơn: ranh giới trừu tượng phải được tổ chức xoay quanh ý nghĩa, chứ không phải vị trí lưu trữ. + +## Hướng thẩm quyền {#the-direction-of-authority} + +Khi các tạo phẩm bất đồng, đừng trao thẩm quyền cho tạo phẩm gần với mã đang chạy nhất. Hãy hỏi mỗi tạo phẩm cần bảo toàn điều gì. + +| Vai trò | Nội dung thuộc về đây | Trách nhiệm | +| --- | --- | --- | +| **Ý nghĩa** | Các quan sát, khác biệt và đẳng thức dự định của miền | Quyết định thế nào là đúng | +| **Đặc tả** | Miền ngữ nghĩa, ngữ nghĩa chỉ định, kiểu, phép toán nguyên thủy, định luật và phép hợp thành suy ra | Phát biểu ý nghĩa đó một cách chính xác | +| **Hiện thực hóa** | Cách biểu diễn cụ thể, bộ diễn giải, trình biên dịch, môi trường chạy, lưu trữ và lập lịch | Triển khai đặc tả mà không thay đổi nó | +| **Bằng chứng** | Chứng minh, kiểm tra định luật, tình huống và so sánh giữa các bộ diễn giải | Kết nối một cách hiện thực hóa với đặc tả; bản thân nó không định nghĩa ý nghĩa | + +Từ đó có một quy tắc thực tế để giải quyết bất đồng: + +* Nếu một cách triển khai vi phạm định luật ngữ nghĩa, hãy sửa cách triển khai. +* Nếu một bài kiểm thử mâu thuẫn với định luật mà nó cần kiểm tra, hãy sửa bài kiểm thử. +* Nếu đặc tả hình thức không diễn đạt được ý nghĩa dự định của miền, hãy chỉnh sửa đặc tả. + +Một tạo phẩm được phân loại theo vai trò, không phải cú pháp. Một đặc trưng Rust hoặc chương trình bậc nhất có thể thuộc về đặc tả khi nó trực tiếp bảo toàn cấu trúc ngữ nghĩa đã chọn; một kiểu Rust khác có thể chỉ là một cách mã hóa cụ thể. Ngữ nghĩa vận hành hình thức cũng có thể là một phần của đặc tả ngôn ngữ, nhưng các bước chuyển tiếp của nó vẫn phải tuân theo những quan sát và quan hệ tương đương mà ngôn ngữ hướng tới. + +Giờ đây có thể đặt CPS, phi chức năng hóa, monad tự do, máy ảo, môi trường chạy giao thức và quy trình biên dịch vào đúng chỗ mà không cần hỏi cái nào là trừu tượng cuối cùng. Mỗi kỹ thuật đều là một cách biểu diễn hoặc thực thi hữu ích cho một số đối tượng sử dụng. Đặc tả ngữ nghĩa cho biết mọi kỹ thuật được chọn phải bảo toàn điều gì. diff --git a/src/denotational-design/semantic-view.zh-hant.md b/src/denotational-design/semantic-view.zh-hant.md new file mode 100644 index 0000000..c543629 --- /dev/null +++ b/src/denotational-design/semantic-view.zh-hant.md @@ -0,0 +1,143 @@ + + +# 為何含義優先 {#why-meaning-comes-first} + +![The semantic view — choosing what a program means before how it runs](../assets/semantic-view.png) + +```admonish tip title="相關內容" +語義視角:[指稱與組合性](denotations.md)、[指稱設計](design.md) +Rust 中的語義驅動設計:[能力代數](../rust-dd/capability-algebras.md) +概念:[簡介](../concepts/index.md) +``` + +```admonish note title="導讀" +指稱設計先確定程式的含義,再推導出詞彙、表示與執行策略,以保留該含義。本頁將這種語義順序與大多數軟體採用的表示優先順序作對比。 +``` + +大多數軟體按照執行順序來設計: + +1. 選擇狀態。 +2. 選擇控制流。 +3. 圍繞這些機制公開方法。 +4. 事後再解釋這些方法原本意在表達什麼。 + +指稱設計將順序倒轉: + +1. 選擇含義。 +2. 確定其組合結構。 +3. 從該結構推導詞彙。 +4. 選擇表示與執行策略。 +5. 驗證它們是否保留了原有含義。 + +這種倒轉就是語義視角。 + +```admonish quote title="機制與含義" +[概念](../concepts/index.md)與[洞見](../insights/index.md)用於說明實用的程式設計機制。[指稱設計](design.md)則說明如何判斷這些機制應當保留什麼。 +``` + +## 三個問題 {#three-questions} + +設計程式時,要把三個問題分開考慮。 + +| 視角 | 問題 | 典型產物 | +| --- | --- | --- | +| 語義 | 這個程式意味著什麼? | 值、關係、函式、等式、定律 | +| 表示 | 這個含義如何編碼? | Rust 型別、trait、抽象語法樹、表、樹、位元組碼 | +| 操作 | 這種表示如何執行? | 迴圈、可變狀態、任務、訊息、直譯器、虛擬機器 | + +這三種視角都很重要。錯誤在於讓表示或執行悄然替語義視角下定義。 + +操作語義對執行過程作出精確且有價值的說明。它可以描述求值器執行的每一次狀態轉換,但它回答的設計問題仍與指稱描述不同。指稱問題關注整個程式所指稱的可觀察數學值,以及無論採用何種執行策略都應成立的等式。 + +## 一個小例子 {#a-small-example} + +假設某個系統要標識分支過程中的位置。 + +表示優先的設計可能從一個位向量開始: + +```rust,noplayground +struct BranchId(Vec); +``` + +隨後,方法圍繞這些欄位不斷增加:追加一位、擷取字首、比較向量、序列化位元組。 + +語義視角從別處開始: + +* 存在一個根位置。 +* 位置可以向左或向右延伸。 +* 一個位置可以是另一個位置的祖先。 +* 可以觀察祖先與後代之間的路徑。 + +即便表示後來變成整數、樹座標、緊湊的混合值或資料庫鍵,這些陳述仍然有意義。位向量只是對分支位置的一種解釋,而不是它的定義。 + +## 含義不是事後補寫的文件 {#meaning-is-not-documentation-after-the-fact} + +為具體 API 寫說明文字,並不會讓設計變成指稱式設計。含義必須先約束 API,然後才能選擇表示。 + +語義描述應當說明: + +* 哪些區別很重要 +* 哪些觀察是基本的 +* 更大的含義如何組合 +* 哪些等式有效 +* 每種實作都必須保留什麼 +* 哪些細節有意忽略 + +如果唯一精確的產物只是狀態結構體或執行迴圈,那麼含義仍由實作掌控。 + +## 抽象與含義 {#abstraction-versus-meaning} + +````admonish warning title="上下文 trait 並不定義含義" +一個介面可以隱藏機制,卻不解釋含義: + +```rust,noplayground +trait ApplicationContext { + fn database(&self) -> &Database; + fn settings(&self) -> &Settings; + fn runtime(&self) -> &Runtime; +} +``` + +這個介面抽象了對具體元件的存取,但沒有說明計算所要求的語義觀察。 +```` + +````admonish success title="直接詢問含義" +面向含義的介面會直接詢問所需的觀察: + +```rust,noplayground +trait BranchAlg { + type Branch; + + fn branch_root(&self) -> Self::Branch; + fn branch_grow(&self, branch: &Self::Branch, direction: Direction) -> Self::Branch; + fn branch_path( + &self, + ancestor: &Self::Branch, + descendant: &Self::Branch, + ) -> Option>; +} +``` +```` + +依賴倒置固然有用,但指稱設計要求更多:抽象邊界必須圍繞含義組織,而不是圍繞儲存位置。 + +## 權威的方向 {#the-direction-of-authority} + +當各類產物彼此矛盾時,不要把權威交給最接近執行程式碼的那個。應當先問每個產物各自必須保留什麼。 + +| 角色 | 此處應包含什麼 | 職責 | +| --- | --- | --- | +| **含義** | 領域預期的觀察、區別與相等關係 | 決定正確性的含義 | +| **規範** | 語義域、指稱、型別、基本操作、定律與派生組合 | 精確陳述含義 | +| **實現** | 具體表示、直譯器、編譯器、執行時、儲存與排程 | 實作規範而不改變規範 | +| **證據** | 證明、定律檢查、場景與跨直譯器比較 | 將實現與規範關聯起來;它本身不定義含義 | + +由此得到一條解決分歧的實用規則: + +* 如果實作違反了語義定律,就修改實作。 +* 如果測試與它原本要檢查的定律相矛盾,就修改測試。 +* 如果形式規範未能表達預期的領域含義,就修訂規範。 + +產物應按其作用分類,而不是按其語法分類。Rust trait 或一階程式若直接保留了選定的語義結構,就可以屬於規範;另一個 Rust 型別則可能只是某種具體編碼。形式操作語義也可以屬於語言規範,但其中的狀態轉換仍須符合該語言所要求的觀察與等價關係。 + +CPS、去函式化、自由單子、虛擬機器、協議執行時和編譯器流水線,如今都可以放在適當的位置,而無須爭論哪一種才是最終抽象。它們各自是適用於特定使用者的表示或執行技術。語義規範說明每種選用的技術都必須保留什麼。 diff --git a/src/denotational-design/semantic-view.zh.md b/src/denotational-design/semantic-view.zh.md new file mode 100644 index 0000000..9184211 --- /dev/null +++ b/src/denotational-design/semantic-view.zh.md @@ -0,0 +1,143 @@ + + +# 为何含义优先 {#why-meaning-comes-first} + +![The semantic view — choosing what a program means before how it runs](../assets/semantic-view.png) + +```admonish tip title="相关内容" +语义视角:[指称与组合性](denotations.md)、[指称设计](design.md) +Rust 中的语义驱动设计:[能力代数](../rust-dd/capability-algebras.md) +概念:[简介](../concepts/index.md) +``` + +```admonish note title="导读" +指称设计先确定程序的含义,再推导出词汇、表示与执行策略,以保留该含义。本页将这种语义顺序与大多数软件采用的表示优先顺序作对比。 +``` + +大多数软件按照运行顺序来设计: + +1. 选择状态。 +2. 选择控制流。 +3. 围绕这些机制公开方法。 +4. 事后再解释这些方法原本意在表达什么。 + +指称设计将顺序倒转: + +1. 选择含义。 +2. 确定其组合结构。 +3. 从该结构推导词汇。 +4. 选择表示与执行策略。 +5. 验证它们是否保留了原有含义。 + +这种倒转就是语义视角。 + +```admonish quote title="机制与含义" +[概念](../concepts/index.md)与[洞见](../insights/index.md)用于说明实用的编程机制。[指称设计](design.md)则说明如何判断这些机制应当保留什么。 +``` + +## 三个问题 {#three-questions} + +设计程序时,要把三个问题分开考虑。 + +| 视角 | 问题 | 典型产物 | +| --- | --- | --- | +| 语义 | 这个程序意味着什么? | 值、关系、函数、等式、定律 | +| 表示 | 这个含义如何编码? | Rust 类型、trait、抽象语法树、表、树、字节码 | +| 操作 | 这种表示如何执行? | 循环、可变状态、任务、消息、解释器、虚拟机 | + +这三种视角都很重要。错误在于让表示或执行悄然替语义视角下定义。 + +操作语义对执行过程作出精确且有价值的说明。它可以描述求值器执行的每一次状态转换,但它回答的设计问题仍与指称描述不同。指称问题关注整个程序所指称的可观察数学值,以及无论采用何种执行策略都应成立的等式。 + +## 一个小例子 {#a-small-example} + +假设某个系统要标识分支过程中的位置。 + +表示优先的设计可能从一个位向量开始: + +```rust,noplayground +struct BranchId(Vec); +``` + +随后,方法围绕这些字段不断增加:追加一位、截取前缀、比较向量、序列化字节。 + +语义视角从别处开始: + +* 存在一个根位置。 +* 位置可以向左或向右延伸。 +* 一个位置可以是另一个位置的祖先。 +* 可以观察祖先与后代之间的路径。 + +即便表示后来变成整数、树坐标、紧凑的混合值或数据库键,这些陈述仍然有意义。位向量只是对分支位置的一种解释,而不是它的定义。 + +## 含义不是事后补写的文档 {#meaning-is-not-documentation-after-the-fact} + +为具体 API 写说明文字,并不会让设计变成指称式设计。含义必须先约束 API,然后才能选择表示。 + +语义描述应当说明: + +* 哪些区别很重要 +* 哪些观察是基本的 +* 更大的含义如何组合 +* 哪些等式有效 +* 每种实现都必须保留什么 +* 哪些细节有意忽略 + +如果唯一精确的产物只是状态结构体或执行循环,那么含义仍由实现掌控。 + +## 抽象与含义 {#abstraction-versus-meaning} + +````admonish warning title="上下文 trait 并不定义含义" +一个接口可以隐藏机制,却不解释含义: + +```rust,noplayground +trait ApplicationContext { + fn database(&self) -> &Database; + fn settings(&self) -> &Settings; + fn runtime(&self) -> &Runtime; +} +``` + +这个接口抽象了对具体组件的访问,但没有说明计算所要求的语义观察。 +```` + +````admonish success title="直接询问含义" +面向含义的接口会直接询问所需的观察: + +```rust,noplayground +trait BranchAlg { + type Branch; + + fn branch_root(&self) -> Self::Branch; + fn branch_grow(&self, branch: &Self::Branch, direction: Direction) -> Self::Branch; + fn branch_path( + &self, + ancestor: &Self::Branch, + descendant: &Self::Branch, + ) -> Option>; +} +``` +```` + +依赖倒置固然有用,但指称设计要求更多:抽象边界必须围绕含义组织,而不是围绕存储位置。 + +## 权威的方向 {#the-direction-of-authority} + +当各类产物彼此矛盾时,不要把权威交给最接近运行代码的那个。应当先问每个产物各自必须保留什么。 + +| 角色 | 此处应包含什么 | 职责 | +| --- | --- | --- | +| **含义** | 领域预期的观察、区别与相等关系 | 决定正确性的含义 | +| **规范** | 语义域、指称、类型、基本操作、定律与派生组合 | 精确陈述含义 | +| **实现** | 具体表示、解释器、编译器、运行时、存储与调度 | 实现规范而不改变规范 | +| **证据** | 证明、定律检查、场景与跨解释器比较 | 将实现与规范关联起来;它本身不定义含义 | + +由此得到一条解决分歧的实用规则: + +* 如果实现违反了语义定律,就修改实现。 +* 如果测试与它原本要检查的定律相矛盾,就修改测试。 +* 如果形式规范未能表达预期的领域含义,就修订规范。 + +产物应按其作用分类,而不是按其语法分类。Rust trait 或一阶程序若直接保留了选定的语义结构,就可以属于规范;另一个 Rust 类型则可能只是某种具体编码。形式操作语义也可以属于语言规范,但其中的状态转换仍须符合该语言所要求的观察与等价关系。 + +CPS、去函数化、自由单子、虚拟机、协议运行时和编译器流水线,如今都可以放在适当的位置,而无须争论哪一种才是最终抽象。它们各自是适用于特定使用者的表示或执行技术。语义规范说明每种选用的技术都必须保留什么。 diff --git a/src/index.ar.md b/src/index.ar.md new file mode 100644 index 0000000..75d0e46 --- /dev/null +++ b/src/index.ar.md @@ -0,0 +1,39 @@ + + +```admonish warning title="مشروع ALUX" +قاعدة شيفرة ALUX قيد التطوير النشط، ولم تُنشر بعد للعامة. +``` + +# إرشادات برمجة ALUX {#alux-programming-guidelines} + +```admonish note title="ملاحظة" +يؤسس هذا الكتاب للمعرفة اللازمة لفهم قاعدة شيفرة ALUX التي تبدأ بالمعنى والمساهمة فيها. وينطلق من مبدأ محوري في [التصميم الدلالي (Denotational Design)](denotational-design/design.md): عرّف معنى البرامج قبل أن تقرر كيفية عملها. + +اقتداءً بـ Conal Elliott، يتعامل الكتاب مع الحوسبة بوصفها كيانًا رياضيًا واضحًا، لا سلسلة خطوات معتمة. + +تُعبَّر المواصفات عن [سمات القدرة البسيطة والتركيبية](rust-dd/capability-algebras.md) التي تصف *ما* يعنيه البرنامج. ويوفر [المفسرون](rust-dd/interpreters.md) طرائق متبادلة *لتحقيق* تلك المعاني. + +والنتيجة برمجيات يسهل فهم قواعد تركيبها، ومتطلبات تنفيذها، و[معادلاتها الصحيحة](denotational-design/laws-and-interpretations.md) واختبارها. +``` + +```admonish quote title="الآليات والمعنى" +تشرح [المفاهيم](concepts/index.md) و[الرؤى](insights/index.md) آليات برمجية مفيدة. أما [التصميم الدلالي (Denotational Design)](denotational-design/design.md) فيشرح كيفية تحديد ما ينبغي لهذه الآليات الحفاظ عليه. +``` + +## كيفية قراءة هذا الكتاب {#how-to-read-this-book} + +اقرأ الكتاب عبر ثلاث طبقات: + +* يقدّم [**المنظور الدلالي**](denotational-design/semantic-view.md) مفهومي [الدلالات والتركيبية](denotational-design/denotations.md)، و[القوانين والتفسيرات](denotational-design/laws-and-interpretations.md)، والعلاقة بين المعنى والتمثيل. +* يحوّل [**التصميم انطلاقًا من المعنى في Rust**](rust-dd/capability-algebras.md) ذلك المنظور إلى [قدرات صغيرة](rust-dd/capability-algebras.md)، و[امتدادات مشتقة](rust-dd/derived-meaning.md)، و[برامج من الرتبة الأولى](rust-dd/first-order-programs.md)، و[مفسرات خفيفة](rust-dd/interpreters.md). +* تشرح [**المفاهيم**](concepts/index.md) و[**الرؤى**](insights/index.md) نماذج التنفيذ والترميزات والتحويلات والروابط المهمة. + +المبادئ الدلالية مستقلة عن اللغة. لغة التنفيذ الأساسية هي Rust، ويربط [مسار لغوي متزامن](rust-dd/compiler-pipelines.md) هذه المبادئ بـ Tolang. + +## لمن هذا الكتاب {#who-this-book-is-for} + +* المبرمجون الذين يريدون أن تظل البرمجيات المعقدة، مع تطورها، **وحداتية وقابلة للتركيب والاختبار والصيانة**. +* المطورون الساعون إلى **ربط نظرية الفئات وأنظمة الأنواع وتصميم البرامج**. +* القراء الملمّون بتقنيات التمثيل والتنفيذ، مثل [**المونادات الحرة**](concepts/free_monad.md)، و[**أسلوب تمرير الاستمرار (CPS)**](concepts/cps.md)، و[**إزالة الدوال**](concepts/defunctionalization.md)، والراغبون في فهم كيف تخدم تلك الآليات التصميم الذي يبدأ بالمعنى بدلًا من أن تحدده. +* القراء الملمّون بـ [**الأنواع التابعة**](denotational-design/dependent-types.md) والبرمجة الموجّهة نحو البراهين، والراغبون في تطبيق هذا التصور عند كتابة Rust عالية الأداء. +* المساهمون الذين يحتاجون إلى قراءة [مواصفات Rust التي تبدأ بالمعنى](rust-dd/capability-algebras.md) وفهم كيفية [ترجمة لغة متزامنة](rust-dd/compiler-pipelines.md) من دون جعل المترجم تعريفًا للغة. diff --git a/src/index.de.md b/src/index.de.md new file mode 100644 index 0000000..926f17b --- /dev/null +++ b/src/index.de.md @@ -0,0 +1,39 @@ + + +```admonish warning title="ALUX-Projekt" +Die ALUX-Codebasis befindet sich in aktiver Entwicklung und ist noch nicht öffentlich verfügbar. +``` + +# Programmierrichtlinien für ALUX {#alux-programming-guidelines} + +```admonish note title="Hinweis" +Dieses Buch vermittelt die Grundlagen, die nötig sind, um die bedeutungsorientierte Codebasis von ALUX zu verstehen und daran mitzuwirken. Es beginnt mit einem zentralen Prinzip des [Denotational Design](denotational-design/design.md): zuerst festzulegen, was Programme bedeuten, und erst danach zu entscheiden, wie sie funktionieren. + +In Anlehnung an Conal Elliott behandelt es Berechnung als klaren mathematischen Gegenstand statt als undurchsichtige Folge von Schritten. + +Spezifikationen werden in einfachen, zusammensetzbaren [Capability-Traits](rust-dd/capability-algebras.md) formuliert, die beschreiben, *was* ein Programm bedeutet. [Interpreter](rust-dd/interpreters.md) bieten austauschbare Wege, diese Bedeutungen *zu realisieren*. + +Das Ergebnis ist Software, deren Kompositionsregeln, Implementierungspflichten und [gültige Gleichungen](denotational-design/laws-and-interpretations.md) leichter zu erkennen und zu testen sind. +``` + +```admonish quote title="Mechanik und Bedeutung" +[Concepts](concepts/index.md) und [Insights](insights/index.md) erklären nützliche Programmiermechanismen. [Denotational Design](denotational-design/design.md) erklärt, wie man entscheidet, was diese Mechanismen bewahren sollen. +``` + +## So liest du dieses Buch {#how-to-read-this-book} + +Lies das Buch auf drei Ebenen: + +* [**The Semantic View**](denotational-design/semantic-view.md) führt [Denotationen und Kompositionalität](denotational-design/denotations.md), [Gesetze und Interpretationen](denotational-design/laws-and-interpretations.md) sowie den Zusammenhang zwischen Bedeutung und Repräsentation ein. +* [**Design by Meaning in Rust**](rust-dd/capability-algebras.md) überträgt diese Sicht auf [kleine Capabilities](rust-dd/capability-algebras.md), [abgeleitete Erweiterungen](rust-dd/derived-meaning.md), [Programme erster Ordnung](rust-dd/first-order-programs.md) und [schlanke Interpreter](rust-dd/interpreters.md). +* [**Concepts**](concepts/index.md) und [**Insights**](insights/index.md) erklären wichtige Ausführungsmodelle, Kodierungen, Transformationen und Zusammenhänge. + +Die semantischen Prinzipien sind sprachunabhängig. Rust ist die primäre Implementierungssprache, und eine [Pipeline für nebenläufige Sprachen](rust-dd/compiler-pipelines.md) verbindet diese Prinzipien mit Tolang. + +## Für wen ist dieses Buch gedacht? {#who-this-book-is-for} + +* Programmierer, denen daran liegt, dass komplexe Software sich bei ihrer Weiterentwicklung **modular, komponierbar, testbar und wartbar** bleibt. +* Entwickler, die **Kategorientheorie, Typsysteme und Programmentwurf miteinander verbinden** möchten. +* Leser, die mit Repräsentations- und Ausführungstechniken wie [**freien Monaden**](concepts/free_monad.md), [**Continuation-Passing Style (CPS)**](concepts/cps.md) und [**Defunktionalisierung**](concepts/defunctionalization.md) vertraut sind und verstehen möchten, wie diese Mechanismen einem bedeutungsorientierten Entwurf dienen, statt ihn zu definieren. +* Leser, die mit [**abhängigen Typen**](denotational-design/dependent-types.md) und beweisorientierter Programmierung vertraut sind und dieses Denkmodell beim Schreiben von leistungsstarkem Rust anwenden möchten. +* Mitwirkende, die [bedeutungsorientierte Rust-Spezifikationen](rust-dd/capability-algebras.md) lesen und verstehen müssen, wie [eine nebenläufige Sprache kompiliert werden kann](rust-dd/compiler-pipelines.md), ohne ihren Compiler zur Definition der Sprache zu machen. diff --git a/src/index.es.md b/src/index.es.md new file mode 100644 index 0000000..6b1b00d --- /dev/null +++ b/src/index.es.md @@ -0,0 +1,39 @@ + + +```admonish warning title="Proyecto ALUX" +La base de código de ALUX está en desarrollo activo y aún no está disponible públicamente. +``` + +# Directrices de programación de ALUX {#alux-programming-guidelines} + +```admonish note title="nota" +Este libro desarrolla los fundamentos necesarios para comprender y contribuir a la base de código de ALUX, centrada en el significado. Comienza con un principio central del [Diseño denotacional](denotational-design/design.md): definir qué significan los programas antes de decidir cómo funcionan. + +Siguiendo a Conal Elliott, trata el cálculo como un objeto matemático claro, no como una secuencia opaca de pasos. + +Las especificaciones se expresan mediante [traits de capacidad](rust-dd/capability-algebras.md) simples y composicionales que describen *qué* significa un programa. Los [intérpretes](rust-dd/interpreters.md) ofrecen formas intercambiables de *realizar* esos significados. + +El resultado es un software cuyas reglas de composición, obligaciones de implementación y [ecuaciones válidas](denotational-design/laws-and-interpretations.md) son más fáciles de ver y probar. +``` + +```admonish quote title="Mecanismos frente a significado" +[Conceptos](concepts/index.md) y [Perspectivas](insights/index.md) explican mecanismos de programación útiles. El [Diseño denotacional](denotational-design/design.md) explica cómo decidir qué deben preservar esos mecanismos. +``` + +## Cómo leer este libro {#how-to-read-this-book} + +Lee el libro en tres capas: + +* [**La perspectiva semántica**](denotational-design/semantic-view.md) presenta [denotaciones y composicionalidad](denotational-design/denotations.md), [leyes e interpretaciones](denotational-design/laws-and-interpretations.md), y la relación entre significado y representación. +* [**Diseño por significado en Rust**](rust-dd/capability-algebras.md) convierte esa perspectiva en [capacidades pequeñas](rust-dd/capability-algebras.md), [extensiones derivadas](rust-dd/derived-meaning.md), [programas de primer orden](rust-dd/first-order-programs.md) e [intérpretes ligeros](rust-dd/interpreters.md). +* [**Conceptos**](concepts/index.md) y [**Perspectivas**](insights/index.md) explican modelos de ejecución, codificaciones, transformaciones y conexiones importantes. + +Los principios semánticos son independientes del lenguaje. Rust es el lenguaje de implementación principal, y [una canalización de lenguaje concurrente](rust-dd/compiler-pipelines.md) conecta estos principios con Tolang. + +## A quién va dirigido este libro {#who-this-book-is-for} + +* Programadores que quieren que el software complejo siga siendo **modular, componible, comprobable y mantenible** a medida que evoluciona. +* Desarrolladores que buscan **conectar la teoría de categorías, los sistemas de tipos y el diseño de programas**. +* Lectores familiarizados con técnicas de representación y operacionales —como [**mónadas libres**](concepts/free_monad.md), [**estilo de paso de continuaciones (CPS)**](concepts/cps.md) y [**defuncionalización**](concepts/defunctionalization.md)— que quieran entender cómo esos mecanismos sirven al diseño centrado en el significado, en vez de definirlo. +* Lectores familiarizados con [**tipos dependientes**](denotational-design/dependent-types.md) y programación orientada a pruebas que quieran aplicar ese modelo mental al escribir Rust de alto rendimiento. +* Colaboradores que necesitan leer [especificaciones de Rust centradas en el significado](rust-dd/capability-algebras.md) y comprender cómo [compilar un lenguaje concurrente](rust-dd/compiler-pipelines.md) sin convertir su compilador en la definición del lenguaje. diff --git a/src/index.ja.md b/src/index.ja.md new file mode 100644 index 0000000..b7bc97d --- /dev/null +++ b/src/index.ja.md @@ -0,0 +1,39 @@ + + +```admonish warning title="ALUXプロジェクト" +ALUXのコードベースは現在開発中であり、まだ一般公開されていません。 +``` + +# ALUXプログラミングガイドライン {#alux-programming-guidelines} + +```admonish note title="注記" +本書では、ALUXの意味を第一に考えるコードベースを理解し、開発に参加するための基礎を築きます。まず、[Denotational Design](denotational-design/design.md)の中心原則として、プログラムがどのように動くかを決める前に、プログラムが何を意味するかを定義します。 + +Conal Elliottに倣い、計算を不透明な手順の列ではなく、明快な数学的対象として扱います。 + +仕様は、プログラムが*何を*意味するかを記述する、単純で合成可能な[ケイパビリティのトレイト](rust-dd/capability-algebras.md)として表します。[インタープリター](rust-dd/interpreters.md)は、その意味を*実現*するための、互いに置き換え可能な方法を提供します。 + +その結果、合成規則、実装上の責務、[妥当な等式](denotational-design/laws-and-interpretations.md)を把握し、テストしやすいソフトウェアになります。 +``` + +```admonish quote title="仕組みと意味" +[概念](concepts/index.md)と[洞察](insights/index.md)は、有用なプログラミングの仕組みを解説します。[Denotational Design](denotational-design/design.md)は、その仕組みに何を保持させるべきかを判断する方法を解説します。 +``` + +## 本書の読み方 {#how-to-read-this-book} + +本書は次の三層に分けて読んでください。 + +* [**意味論的な見方**](denotational-design/semantic-view.md)では、[表示と合成性](denotational-design/denotations.md)、[法則と解釈](denotational-design/laws-and-interpretations.md)、そして意味と表現の関係を紹介します。 +* [**Rustで意味から設計する**](rust-dd/capability-algebras.md)では、その見方を[小さなケイパビリティ](rust-dd/capability-algebras.md)、[導出される拡張](rust-dd/derived-meaning.md)、[一階プログラム](rust-dd/first-order-programs.md)、[薄いインタープリター](rust-dd/interpreters.md)へと具体化します。 +* [**概念**](concepts/index.md)と[**洞察**](insights/index.md)は、重要な実行モデル、符号化、変換、関連性を解説します。 + +意味論の原則は言語に依存しません。主な実装言語はRustであり、[並行言語のパイプライン](rust-dd/compiler-pipelines.md)によって、これらの原則をTolangへと結び付けます。 + +## 本書の対象読者 {#who-this-book-is-for} + +* 進化する複雑なソフトウェアを、**モジュール化され、合成可能で、テストしやすく、保守しやすい**状態に保ちたいプログラマー。 +* **圏論、型システム、プログラム設計を結び付けたい**開発者。 +* [**自由モナド**](concepts/free_monad.md)、[**継続渡し形式(CPS)**](concepts/cps.md)、[**関数のデファンクショナライズ**](concepts/defunctionalization.md)などの表現技法や実行技法に詳しく、それらの仕組みが意味を第一に考える設計を定義するのではなく、どう支えるのかを理解したい読者。 +* [**依存型**](denotational-design/dependent-types.md)と証明指向プログラミングに詳しく、その考え方を高性能なRustの記述に活かしたい読者。 +* [意味を第一に考えるRustの仕様](rust-dd/capability-algebras.md)を読み、コンパイラーを言語の定義とせずに[並行言語をコンパイルする方法](rust-dd/compiler-pipelines.md)を理解する必要のあるコントリビューター。 diff --git a/src/index.ko.md b/src/index.ko.md new file mode 100644 index 0000000..ba1fcdf --- /dev/null +++ b/src/index.ko.md @@ -0,0 +1,39 @@ + + +```admonish warning title="ALUX 프로젝트" +ALUX 코드베이스는 현재 활발히 개발 중이며 아직 공개되지 않았습니다. +``` + +# ALUX 프로그래밍 지침 {#alux-programming-guidelines} + +```admonish note title="참고" +이 책은 프로그램이 어떻게 작동하는지를 정하기 전에 무엇을 의미하는지 정의한다는 [표시적 설계](denotational-design/design.md)의 핵심 원칙에서 출발해, 의미를 우선하는 ALUX 코드베이스를 이해하고 기여하는 데 필요한 토대를 다룹니다. + +Conal Elliott의 관점을 따라, 계산을 불투명한 단계의 나열이 아니라 명확한 수학적 대상으로 다룹니다. + +명세는 프로그램이 *무엇을* 의미하는지 설명하는 단순하고 합성 가능한 [케이퍼빌리티 트레이트](rust-dd/capability-algebras.md)로 표현합니다. [인터프리터](rust-dd/interpreters.md)는 그러한 의미를 *실현하는* 상호 교환 가능한 방법을 제공합니다. + +그 결과, 합성 규칙과 구현 의무, [유효한 등식](denotational-design/laws-and-interpretations.md)을 더 쉽게 파악하고 시험할 수 있는 소프트웨어가 만들어집니다. +``` + +```admonish quote title="구현 장치와 의미" +[개념](concepts/index.md)과 [통찰](insights/index.md)은 유용한 프로그래밍 장치를 설명합니다. [표시적 설계](denotational-design/design.md)는 어떤 장치가 무엇을 보존해야 하는지 결정하는 방법을 설명합니다. +``` + +## 이 책 읽는 법 {#how-to-read-this-book} + +이 책은 세 층위로 읽으세요: + +* [**의미론적 관점**](denotational-design/semantic-view.md)에서는 [표시와 합성성](denotational-design/denotations.md), [법칙과 해석](denotational-design/laws-and-interpretations.md), 의미와 표현 사이의 관계를 소개합니다. +* [**Rust에서 의미로 설계하기**](rust-dd/capability-algebras.md)에서는 그 관점을 [작은 케이퍼빌리티](rust-dd/capability-algebras.md), [파생 확장](rust-dd/derived-meaning.md), [일차 프로그램](rust-dd/first-order-programs.md), [얇은 인터프리터](rust-dd/interpreters.md)로 구체화합니다. +* [**개념**](concepts/index.md)과 [**통찰**](insights/index.md)은 중요한 실행 모델, 인코딩, 변환, 연관성을 설명합니다. + +의미론적 원칙은 특정 언어에 종속되지 않습니다. 주요 구현 언어는 Rust이며, [동시성 언어 파이프라인](rust-dd/compiler-pipelines.md)이 이 원칙들을 Tolang과 연결합니다. + +## 이 책의 대상 독자 {#who-this-book-is-for} + +* 소프트웨어가 발전하는 동안에도 복잡한 소프트웨어를 **모듈화하고, 합성 가능하며, 테스트하고 유지보수할 수 있는** 상태로 두고 싶은 프로그래머. +* **범주론, 타입 시스템, 프로그램 설계를 연결**하려는 개발자. +* [**자유 모나드**](concepts/free_monad.md), [**연속 전달 스타일(CPS)**](concepts/cps.md), [**디펑셔널라이제이션**](concepts/defunctionalization.md) 같은 표현 및 실행 기법에 익숙하며, 그러한 장치가 의미 우선 설계를 정의하는 것이 아니라 어떻게 뒷받침하는지 알고 싶은 독자. +* [**종속 타입**](denotational-design/dependent-types.md)과 증명 중심 프로그래밍에 익숙하고, 고성능 Rust를 작성하면서 그 사고방식을 적용하려는 독자. +* [의미 우선 Rust 명세](rust-dd/capability-algebras.md)를 읽고, 동시성 언어의 정의를 컴파일러에 맡기지 않으면서도 [동시성 언어를 컴파일하는 방법](rust-dd/compiler-pipelines.md)을 이해해야 하는 기여자. diff --git a/src/index.ru.md b/src/index.ru.md new file mode 100644 index 0000000..cc76c04 --- /dev/null +++ b/src/index.ru.md @@ -0,0 +1,39 @@ + + +```admonish warning title="Проект ALUX" +Кодовая база ALUX активно разрабатывается и пока недоступна публично. +``` + +# Руководство по программированию на ALUX {#alux-programming-guidelines} + +```admonish note title="примечание" +Эта книга закладывает основу, необходимую для понимания кодовой базы ALUX, в которой смысл ставится на первое место, и для участия в её разработке. Отправной точкой служит ключевой принцип [денотационного проектирования](denotational-design/design.md): сначала определить, что означают программы, и лишь затем решать, как они работают. + +Следуя подходу Конала Эллиотта, книга рассматривает вычисление как ясный математический объект, а не как непрозрачную последовательность шагов. + +Спецификации выражаются через простые композиционные [трейты возможностей](rust-dd/capability-algebras.md), описывающие *что* означает программа. [Интерпретаторы](rust-dd/interpreters.md) дают взаимозаменяемые способы *реализовать* эти значения. + +В результате получаются программы, в которых правила композиции, требования к реализации и [верные равенства](denotational-design/laws-and-interpretations.md) легче увидеть и проверить. +``` + +```admonish quote title="Механизмы и смысл" +[«Понятия»](concepts/index.md) и [«Идеи»](insights/index.md) объясняют полезные механизмы программирования. [Денотационное проектирование](denotational-design/design.md) объясняет, как решить, что именно эти механизмы должны сохранять. +``` + +## Как читать эту книгу {#how-to-read-this-book} + +Читайте книгу на трёх уровнях: + +* [**«Семантический взгляд»**](denotational-design/semantic-view.md) знакомит с [денотациями и композиционностью](denotational-design/denotations.md), [законами и интерпретациями](denotational-design/laws-and-interpretations.md), а также со связью между смыслом и представлением. +* [**«Проектирование на основе смысла в Rust»**](rust-dd/capability-algebras.md) воплощает этот взгляд в [небольших трейтах возможностей](rust-dd/capability-algebras.md), [производных расширениях](rust-dd/derived-meaning.md), [программах первого порядка](rust-dd/first-order-programs.md) и [тонких интерпретаторах](rust-dd/interpreters.md). +* [**«Понятия»**](concepts/index.md) и [**«Идеи»**](insights/index.md) объясняют важные модели выполнения, способы кодирования, преобразования и взаимосвязи. + +Семантические принципы не зависят от языка. Основной язык реализации — Rust; [конвейер обработки параллельного языка](rust-dd/compiler-pipelines.md) связывает эти принципы с Tolang. + +## Для кого эта книга {#who-this-book-is-for} + +* Для программистов, которые хотят, чтобы сложное программное обеспечение оставалось **модульным, допускающим композицию, тестируемым и удобным в сопровождении** по мере развития. +* Для разработчиков, стремящихся **связать теорию категорий, системы типов и проектирование программ**. +* Для читателей, знакомых с репрезентационными и операционными методами — такими как [**свободные монады**](concepts/free_monad.md), [**стиль передачи продолжений (CPS)**](concepts/cps.md) и [**дефункционализация**](concepts/defunctionalization.md), — которые хотят понять, как эти механизмы служат проектированию, ставящему смысл на первое место, а не определяют его. +* Для читателей, знакомых с [**зависимыми типами**](denotational-design/dependent-types.md) и программированием, ориентированным на доказательства, которые хотят применять этот подход при написании высокопроизводительного кода на Rust. +* Для участников разработки, которым нужно читать [спецификации Rust, ставящие смысл на первое место](rust-dd/capability-algebras.md), и понимать, как [параллельный язык можно компилировать](rust-dd/compiler-pipelines.md), не превращая компилятор в определение самого языка. diff --git a/src/index.uk.md b/src/index.uk.md new file mode 100644 index 0000000..28ac703 --- /dev/null +++ b/src/index.uk.md @@ -0,0 +1,39 @@ + + +```admonish warning title="Проєкт ALUX" +Кодова база ALUX активно розробляється й поки що недоступна публічно. +``` + +# Настанови з програмування ALUX {#alux-programming-guidelines} + +```admonish note title="примітка" +Ця книжка закладає основу, потрібну для розуміння кодової бази ALUX, у якій значення ставиться на перше місце, та участі в її розробці. Вона починається з головного принципу — [денотаційного проєктування](denotational-design/design.md): спершу визначити, що означають програми, а вже потім вирішувати, як вони працюють. + +За Коналом Елліоттом, обчислення розглядається як чіткий математичний об’єкт, а не як непрозора послідовність кроків. + +Специфікації виражаються простими композиційними [трейтами можливостей](rust-dd/capability-algebras.md), які описують, *що* означає програма. [Інтерпретатори](rust-dd/interpreters.md) надають взаємозамінні способи *реалізувати* ці значення. + +У результаті маємо програмне забезпечення, у якому правила композиції, вимоги до реалізації та [коректні рівності](denotational-design/laws-and-interpretations.md) легше побачити й перевірити. +``` + +```admonish quote title="Механізми та значення" +[Поняття](concepts/index.md) й [осяяння](insights/index.md) пояснюють корисні механізми програмування. [Денотаційне проєктування](denotational-design/design.md) пояснює, як визначити, що саме ці механізми мають зберігати. +``` + +## Як читати цю книжку {#how-to-read-this-book} + +Читайте книжку у три етапи: + +* [**Семантичний погляд**](denotational-design/semantic-view.md) знайомить із [денотаціями та композиційністю](denotational-design/denotations.md), [законами й інтерпретаціями](denotational-design/laws-and-interpretations.md), а також зі зв’язком між значенням і представленням. +* [**Проєктування від значення в Rust**](rust-dd/capability-algebras.md) втілює цей погляд у [невеликих можливостях](rust-dd/capability-algebras.md), [похідних розширеннях](rust-dd/derived-meaning.md), [програмах першого порядку](rust-dd/first-order-programs.md) та [тонких інтерпретаторах](rust-dd/interpreters.md). +* [**Поняття**](concepts/index.md) та [**Інсайти**](insights/index.md) пояснюють важливі моделі виконання, кодування, перетворення та зв’язки. + +Семантичні принципи не залежать від мови програмування. Основною мовою реалізації є Rust, а [конвеєр паралельної мови](rust-dd/compiler-pipelines.md) пов’язує ці принципи з Tolang. + +## Для кого ця книжка {#who-this-book-is-for} + +* Для програмістів, які прагнуть, щоб складне програмне забезпечення залишалося **модульним, композиційним, придатним до тестування й супроводу** в міру розвитку. +* Для розробників, які прагнуть **поєднати теорію категорій, системи типів і проєктування програм**. +* Для читачів, знайомих із техніками представлення та виконання — зокрема [**вільними монадами**](concepts/free_monad.md), [**стилем передавання продовжень (CPS)**](concepts/cps.md) і [**дефункціоналізацією**](concepts/defunctionalization.md), — які хочуть зрозуміти, як ці механізми служать проєктуванню, де на першому місці значення, а не визначають його. +* Для читачів, знайомих із [**залежними типами**](denotational-design/dependent-types.md) та програмуванням, орієнтованим на доведення, які хочуть застосовувати цю модель мислення під час написання високопродуктивного коду Rust. +* Для учасників розробки, яким потрібно читати [специфікації Rust, орієнтовані на значення](rust-dd/capability-algebras.md), і розуміти, як [можна компілювати паралельну мову](rust-dd/compiler-pipelines.md), не перетворюючи її компілятор на визначення самої мови. diff --git a/src/index.vi.md b/src/index.vi.md new file mode 100644 index 0000000..82562ea --- /dev/null +++ b/src/index.vi.md @@ -0,0 +1,39 @@ + + +```admonish warning title="Dự án ALUX" +Mã nguồn ALUX đang được phát triển tích cực và chưa được công bố rộng rãi. +``` + +# Hướng dẫn lập trình ALUX {#alux-programming-guidelines} + +```admonish note title="ghi chú" +Cuốn sách này xây dựng nền tảng cần thiết để hiểu và đóng góp vào cơ sở mã lấy ý nghĩa làm trọng tâm của ALUX, bắt đầu từ nguyên lý cốt lõi của [Thiết kế theo ngữ nghĩa](denotational-design/design.md): xác định ý nghĩa của chương trình trước khi quyết định cách chương trình vận hành. + +Theo Conal Elliott, cuốn sách xem tính toán là một đối tượng toán học rõ ràng, thay vì một chuỗi bước mờ đục. + +Các đặc tả được biểu đạt bằng những [đặc trưng năng lực](rust-dd/capability-algebras.md) đơn giản, có thể hợp thành, mô tả *ý nghĩa* của chương trình. [Các bộ diễn giải](rust-dd/interpreters.md) cung cấp những cách *hiện thực hóa* các ý nghĩa đó mà có thể thay thế cho nhau. + +Nhờ vậy, các quy tắc hợp thành, nghĩa vụ triển khai và [các phương trình hợp lệ](denotational-design/laws-and-interpretations.md) của phần mềm trở nên dễ nhận biết và kiểm thử hơn. +``` + +```admonish quote title="Cơ chế và ý nghĩa" +[Các khái niệm](concepts/index.md) và [nhận định](insights/index.md) giải thích những cơ chế lập trình hữu ích. [Thiết kế theo ngữ nghĩa](denotational-design/design.md) giải thích cách xác định cơ chế cần bảo toàn điều gì. +``` + +## Cách đọc cuốn sách này {#how-to-read-this-book} + +Hãy đọc sách theo ba lớp: + +* [**Góc nhìn ngữ nghĩa**](denotational-design/semantic-view.md) giới thiệu [ngữ nghĩa và tính hợp thành](denotational-design/denotations.md), [các định luật và cách diễn giải](denotational-design/laws-and-interpretations.md), cùng mối quan hệ giữa ý nghĩa và biểu diễn. +* [**Thiết kế theo ngữ nghĩa trong Rust**](rust-dd/capability-algebras.md) chuyển góc nhìn đó thành [các năng lực nhỏ](rust-dd/capability-algebras.md), [các mở rộng được suy ra](rust-dd/derived-meaning.md), [chương trình bậc nhất](rust-dd/first-order-programs.md) và [các bộ diễn giải mỏng](rust-dd/interpreters.md). +* [**Các khái niệm**](concepts/index.md) và [**nhận định**](insights/index.md) giải thích những mô hình thực thi, cách mã hóa, phép biến đổi và mối liên hệ quan trọng. + +Các nguyên lý ngữ nghĩa không phụ thuộc ngôn ngữ. Rust là ngôn ngữ triển khai chính, còn [một quy trình ngôn ngữ đồng thời](rust-dd/compiler-pipelines.md) kết nối các nguyên lý này với Tolang. + +## Cuốn sách dành cho ai {#who-this-book-is-for} + +* Lập trình viên muốn phần mềm phức tạp vẫn **mô-đun, có thể hợp thành, kiểm thử và bảo trì** khi phát triển. +* Nhà phát triển muốn **kết nối lý thuyết phạm trù, hệ kiểu và thiết kế chương trình**. +* Độc giả quen thuộc với các kỹ thuật biểu diễn và vận hành—như [**monad tự do**](concepts/free_monad.md), [**phong cách truyền tiếp nối (CPS)**](concepts/cps.md) và [**phi chức năng hóa**](concepts/defunctionalization.md)—muốn hiểu cách những cơ chế ấy phục vụ, thay vì định nghĩa, thiết kế lấy ý nghĩa làm trọng tâm. +* Độc giả quen thuộc với [**kiểu phụ thuộc**](denotational-design/dependent-types.md) và lập trình hướng chứng minh, muốn áp dụng mô hình tư duy đó khi viết Rust hiệu năng cao. +* Người đóng góp cần đọc [đặc tả Rust lấy ý nghĩa làm trọng tâm](rust-dd/capability-algebras.md) và hiểu cách [biên dịch một ngôn ngữ đồng thời](rust-dd/compiler-pipelines.md) mà không biến trình biên dịch thành định nghĩa của ngôn ngữ. diff --git a/src/index.zh-hant.md b/src/index.zh-hant.md new file mode 100644 index 0000000..89a2bff --- /dev/null +++ b/src/index.zh-hant.md @@ -0,0 +1,39 @@ + + +```admonish warning title="ALUX 專案" +ALUX 程式碼庫仍在積極開發中,尚未公開。 +``` + +# ALUX 程式設計指南 {#alux-programming-guidelines} + +```admonish note title="注" +本書將介紹理解並參與 ALUX 語義優先程式碼庫所需的基礎,從[指稱設計](denotational-design/design.md)的一項核心原則講起:先定義程式的含義,再決定程式如何執行。 + +沿襲 Conal Elliott 的思路,本書將計算視為清晰的數學物件,而不是不透明的步驟序列。 + +規範以簡單、可組合的[能力 trait](rust-dd/capability-algebras.md)表達,用來描述程式*意味著什麼*。[直譯器](rust-dd/interpreters.md)提供可互換的方式來*實現*這些含義。 + +這樣一來,軟體的組合規則、實作義務和[有效等式](denotational-design/laws-and-interpretations.md)都更容易理解和測試。 +``` + +```admonish quote title="機制與含義" +[概念](concepts/index.md)與[洞見](insights/index.md)用於說明實用的程式設計機制。[指稱設計](denotational-design/design.md)則說明如何判斷這些機制應當保留什麼。 +``` + +## 如何閱讀本書 {#how-to-read-this-book} + +本書分三個層次閱讀: + +* [**語義視角**](denotational-design/semantic-view.md)介紹[指稱與組合性](denotational-design/denotations.md)、[定律與解釋](denotational-design/laws-and-interpretations.md),以及含義與表示之間的關係。 +* [**Rust 中的語義驅動設計**](rust-dd/capability-algebras.md)將這一視角落實為[小型能力](rust-dd/capability-algebras.md)、[派生擴充](rust-dd/derived-meaning.md)、[一階程式](rust-dd/first-order-programs.md)和[輕量級直譯器](rust-dd/interpreters.md)。 +* [**概念**](concepts/index.md)與[**洞見**](insights/index.md)介紹重要的執行模型、編碼、變換與連結。 + +語義原則不依賴特定語言。Rust 是主要實作語言;一條[併發語言處理流水線](rust-dd/compiler-pipelines.md)將這些原則與 Tolang 連結起來。 + +## 本書適合誰 {#who-this-book-is-for} + +* 希望複雜軟體在不斷演進時仍能保持**模組化、可組合、可測試且易於維護**的程式設計師。 +* 希望**連結範疇論、型別系統與程式設計**的開發者。 +* 熟悉表示與操作技術的讀者——例如[**自由單子**](concepts/free_monad.md)、[**延續傳遞風格(CPS)**](concepts/cps.md)和[**去函式化**](concepts/defunctionalization.md)——希望理解這些機制如何服務於語義優先設計,而非定義它。 +* 熟悉[**依賴型別**](denotational-design/dependent-types.md)與證明導向程式設計,並希望在編寫高效能 Rust 時運用這套思維方式的讀者。 +* 需要閱讀[語義優先的 Rust 規範](rust-dd/capability-algebras.md),並理解如何[編譯並行語言](rust-dd/compiler-pipelines.md)而不以編譯器本身來定義語言的貢獻者。 diff --git a/src/index.zh.md b/src/index.zh.md new file mode 100644 index 0000000..e972d72 --- /dev/null +++ b/src/index.zh.md @@ -0,0 +1,39 @@ + + +```admonish warning title="ALUX 项目" +ALUX 代码库仍在积极开发中,尚未公开。 +``` + +# ALUX 编程指南 {#alux-programming-guidelines} + +```admonish note title="注" +本书将介绍理解并参与 ALUX 语义优先代码库所需的基础,从[指称设计](denotational-design/design.md)的一项核心原则讲起:先定义程序的含义,再决定程序如何运行。 + +沿袭 Conal Elliott 的思路,本书将计算视为清晰的数学对象,而不是不透明的步骤序列。 + +规范以简单、可组合的[能力 trait](rust-dd/capability-algebras.md)表达,用来描述程序*意味着什么*。[解释器](rust-dd/interpreters.md)提供可互换的方式来*实现*这些含义。 + +这样一来,软件的组合规则、实现义务和[有效等式](denotational-design/laws-and-interpretations.md)都更容易理解和测试。 +``` + +```admonish quote title="机制与含义" +[概念](concepts/index.md)与[洞见](insights/index.md)用于说明实用的编程机制。[指称设计](denotational-design/design.md)则说明如何判断这些机制应当保留什么。 +``` + +## 如何阅读本书 {#how-to-read-this-book} + +本书分三个层次阅读: + +* [**语义视角**](denotational-design/semantic-view.md)介绍[指称与组合性](denotational-design/denotations.md)、[定律与解释](denotational-design/laws-and-interpretations.md),以及含义与表示之间的关系。 +* [**Rust 中的语义驱动设计**](rust-dd/capability-algebras.md)将这一视角落实为[小型能力](rust-dd/capability-algebras.md)、[派生扩展](rust-dd/derived-meaning.md)、[一阶程序](rust-dd/first-order-programs.md)和[轻量级解释器](rust-dd/interpreters.md)。 +* [**概念**](concepts/index.md)与[**洞见**](insights/index.md)介绍重要的执行模型、编码、变换与联系。 + +语义原则不依赖特定语言。Rust 是主要实现语言;一条[并发语言处理流水线](rust-dd/compiler-pipelines.md)将这些原则与 Tolang 联系起来。 + +## 本书适合谁 {#who-this-book-is-for} + +* 希望复杂软件在不断演进时仍能保持**模块化、可组合、可测试且易于维护**的程序员。 +* 希望**连接范畴论、类型系统与程序设计**的开发者。 +* 熟悉表示与操作技术的读者——例如[**自由单子**](concepts/free_monad.md)、[**延续传递风格(CPS)**](concepts/cps.md)和[**去函数化**](concepts/defunctionalization.md)——希望理解这些机制如何服务于语义优先设计,而非定义它。 +* 熟悉[**依赖类型**](denotational-design/dependent-types.md)与证明导向编程,并希望在编写高性能 Rust 时运用这套思维方式的读者。 +* 需要阅读[语义优先的 Rust 规范](rust-dd/capability-algebras.md),并理解如何[编译并发语言](rust-dd/compiler-pipelines.md),而不以编译器本身作为语言定义依据的贡献者。 diff --git a/src/insights/evm-alg.ar.md b/src/insights/evm-alg.ar.md new file mode 100644 index 0000000..77fb124 --- /dev/null +++ b/src/insights/evm-alg.ar.md @@ -0,0 +1,268 @@ + + +# جبر EVM {#evm-algebra} + +```admonish tip title="ذات صلة" +التصميم انطلاقًا من المعنى في Rust: [المفسرات والآثار](../rust-dd/interpreters.md)، [برامج من الرتبة الأولى](../rust-dd/first-order-programs.md)، [مسارات اللغة والمترجم](../rust-dd/compiler-pipelines.md) +المفاهيم: [الدلالات التشغيلية](../concepts/operational_semantics.md)، [الموناد الحر](../concepts/free_monad.md)، [أسلوب تمرير الاستمرار](../concepts/cps.md)، [إزالة الدوال](../concepts/defunctionalization.md) +``` + +**آلة Ethereum الافتراضية (EVM)** وحدة معالجة افتراضية مكدسية تنفذ **شيفرة Ethereum البايتية**، أي الصيغة المجمعة للعقود الذكية المكتوبة بـ Solidity أو Vyper أو لغة أخرى متوافقة مع EVM. + +على المستوى الأدنى: + +* تعالج EVM **شفرات العمليات** (ADD وPUSH وJUMP وSSTORE وغيرها). +* Execution state includes: + * **المكدس**: مكدس بيانات أخير ما يدخل أول ما يخرج للمعاملات. + * **الذاكرة**: مصفوفة بايتات مؤقتة للقيم المؤقتة. + * **التخزين**: مخزن دائم أزواج مفتاح/قيمة لكل عقد. + * **عداد البرنامج**: يشير إلى شفرة العملية التالية. + * **الغاز**: قياس يفرض تكلفة على خطوات التنفيذ. + +## EVM بوصفها نمط مفسر {#evm-as-an-interpreter-pattern} + +عميل EVM مفسر للغة تعليمات: + +* **مجموعة التعليمات** = شفرات عمليات EVM (تعداد لصيغ متعددة). +* **البرنامج** = تسلسل من التعليمات. +* **المفسر** = قاعدة كيفية تغيير كل شفرة عملية لحالة الآلة. +* **المفسرات المتعددة** = مواصفة EVM ثابتة، لكن Geth وNethermind وBesu وErigon تطبيقات بديلة للمفسر نفسه. + +هذا هو الخيط الواصل بين ثلاث تقنيات في هذا الكتاب — **المونادات الحرة** و**أسلوب تمرير الاستمرار** و**إزالة الدوال** — التي لا تختلف إلا في طريقة تمثيلها *بقية البرنامج*. + +## ثلاثة ترميزات لآلة واحدة {#three-encodings-of-one-machine} + +ينفذ كل ترميز أدناه البرنامج الثابت نفسه: + +```text +push 2; push 3; add; sstore 1 5; load 1 -> v; push v +``` + +وتنتج عنها جميعًا الملاحظة نفسها: + +```text +stack: [5, 5] +storage: {1: 5} +``` + +لا تختلف إلا في تمثيل التحكم — «ما الذي ينبغي فعله تاليًا». + +

+الموناد الحر — البرنامج بيانات؛ ويمنحه مفسر معنى + +ينشئ فونكتور التعليمات شجرة برنامج. و`and_then` هو الربط المونادي، و`run` مفسر واحد — ويمكن لمفسر ثانٍ (مترجم إلى الشيفرة البايتية) طي الشجرة نفسها. ويُخصص `Free` العام لمجموعة التعليمات هذه لكي يُجمَّع في Rust المستقرة. + +```rust +use std::collections::HashMap; + +struct State { stack: Vec, storage: HashMap } + +// The free monad over the EVM instruction set: a program is data — a tree of +// instructions ending in `Pure`, each carrying its continuation. +enum Free { + Pure(A), + Push(u64, Box>), + Add(Box>), + SStore(u64, u64, Box>), + SLoad(u64, Box Free>), +} + +impl Free { + // Monadic bind: graft `k` onto every leaf of the program. + fn and_then(self, k: impl FnOnce(A) -> Free + 'static) -> Free { + match self { + Free::Pure(a) => k(a), + Free::Push(v, next) => Free::Push(v, Box::new(next.and_then(k))), + Free::Add(next) => Free::Add(Box::new(next.and_then(k))), + Free::SStore(x, y, next) => Free::SStore(x, y, Box::new(next.and_then(k))), + Free::SLoad(key, cont) => Free::SLoad(key, Box::new(move |v| cont(v).and_then(k))), + } + } +} + +fn push(v: u64) -> Free<()> { Free::Push(v, Box::new(Free::Pure(()))) } +fn add() -> Free<()> { Free::Add(Box::new(Free::Pure(()))) } +fn sstore(k: u64, v: u64) -> Free<()> { Free::SStore(k, v, Box::new(Free::Pure(()))) } +fn sload(k: u64) -> Free { Free::SLoad(k, Box::new(|v| Free::Pure(v))) } + +// Interpreter: give the program data meaning against the machine state. +fn run(mut prog: Free<()>, st: &mut State) { + loop { + prog = match prog { + Free::Pure(()) => return, + Free::Push(v, next) => { st.stack.push(v); *next } + Free::Add(next) => { + let b = st.stack.pop().unwrap(); + let a = st.stack.pop().unwrap(); + st.stack.push(a + b); + *next + } + Free::SStore(k, v, next) => { st.storage.insert(k, v); *next } + Free::SLoad(k, cont) => { let v = *st.storage.get(&k).unwrap_or(&0); cont(v) } + }; + } +} + +fn main() { + let program = push(2) + .and_then(|_| push(3)) + .and_then(|_| add()) + .and_then(|_| sstore(1, 5)) + .and_then(|_| sload(1)) + .and_then(|v| push(v)); + + let mut st = State { stack: vec![], storage: HashMap::new() }; + run(program, &mut st); + println!("stack: {:?}", st.stack); + println!("storage: {:?}", st.storage); +} +``` + +
+ +
+أسلوب تمرير الاستمرار (CPS) — تستدعي كل شفرة عملية «بقية البرنامج» + +ينفذ كل معالج عمله ثم يستدعي الاستمرارية `k`. و`sload` يمرر القيمة المحملة إلى استمرارية تتوقعها. ويصبح التحكم صريحًا عبر استمراريات متداخلة، من دون أي بنية بيانات للبرنامج. + +```rust +use std::collections::HashMap; + +struct State { stack: Vec, storage: HashMap } + +// Each opcode does its work, then calls the continuation `k` = "the rest of +// the program". `sload` passes the loaded value on to its continuation. +fn push(st: &mut State, v: u64, k: impl FnOnce(&mut State)) { + st.stack.push(v); + k(st); +} +fn add(st: &mut State, k: impl FnOnce(&mut State)) { + let b = st.stack.pop().unwrap(); + let a = st.stack.pop().unwrap(); + st.stack.push(a + b); + k(st); +} +fn sstore(st: &mut State, key: u64, val: u64, k: impl FnOnce(&mut State)) { + st.storage.insert(key, val); + k(st); +} +fn sload(st: &mut State, key: u64, k: impl FnOnce(&mut State, u64)) { + let v = *st.storage.get(&key).unwrap_or(&0); + k(st, v); +} + +fn main() { + let mut st = State { stack: vec![], storage: HashMap::new() }; + + push(&mut st, 2, |st| { + push(st, 3, |st| { + add(st, |st| { + sstore(st, 1, 5, |st| { + sload(st, 1, |st, v| { + push(st, v, |_st| {}); + }); + }); + }); + }); + }); + + println!("stack: {:?}", st.stack); + println!("storage: {:?}", st.storage); +} +``` + +
+ +
+أزيلت دواله — تصبح استدعاءات العمليات بيانات يشغلها apply واحد + +بينما *تستدعي* نسختا الموناد الحر وCPS العمليات (`push(2)` و`add()` و`sstore(1, 5)` و`sload(1)`) — وهو جبر صغير يكاد يُقرأ كمواصفة — تجسّد إزالة الدوال كل استدعاء في بيانات من الرتبة الأولى. ثم تفسر تلك البيانات `apply` دالة واحدة، وتنهار الاستمراريات أيضًا: تصبح «بقية البرنامج» الفهرس التالي (`pc`). اقرأها بوصفها جبر العمليات مكتوبًا كبيانات، مع `apply` مفسره الوحيد. + +```rust +use std::collections::HashMap; + +struct State { stack: Vec, storage: HashMap } + +// The EVM algebra reified: where the other encodings CALL `push(2)`, `add()`, +// `sstore(1, 5)`, `sload(1)`, each such call becomes a first-order value — a +// tag with its arguments. +enum Op { + Push(u64), + Add, + SStore(u64, u64), + SLoad(u64), +} + +// `apply` is the single interpreter for the reified operations: it gives each +// tag its meaning against the machine state. +fn apply(op: &Op, st: &mut State) { + match op { + Op::Push(v) => st.stack.push(*v), + Op::Add => { + let b = st.stack.pop().unwrap(); + let a = st.stack.pop().unwrap(); + st.stack.push(a + b); + } + Op::SStore(k, v) => { st.storage.insert(*k, *v); } + Op::SLoad(k) => { + let v = *st.storage.get(k).unwrap_or(&0); + st.stack.push(v); + } + } +} + +fn main() { + // The program is now data: a flat list of reified operation calls. + let code = vec![ + Op::Push(2), + Op::Push(3), + Op::Add, + Op::SStore(1, 5), + Op::SLoad(1), + ]; + + // `pc` is the defunctionalized continuation: "the rest of the program" is + // just the next index. + let mut st = State { stack: vec![], storage: HashMap::new() }; + let mut pc = 0; + while pc < code.len() { + apply(&code[pc], &mut st); + pc += 1; + } + + println!("stack: {:?}", st.stack); + println!("storage: {:?}", st.storage); +} +``` + +
+ +## من الاستمراريات إلى الشيفرة البايتية {#from-continuations-to-bytecode} + +الترميزات الثلاثة هي الحساب نفسه على مسافات مختلفة من الآلة: + +* ينشئ **الموناد الحر** البرنامج *جبريًا* كبيانات، ثم يفسره. ويمكن طي الشجرة نفسها عبر عدة مفسرات: لتشغيلها أو طباعتها الجميلة أو تجميعها. +* يزيل **أسلوب تمرير الاستمرار (CPS)** بنية البيانات ويجعل التحكم صريحًا: «نفذ شفرة العملية هذه ثم استدعِ الاستمرارية». وتتدفق القيمة المحملة إلى الاستمرارية التي تحتاج إليها. +* يحوّل **إزالة الدوال** *استدعاءات* العمليات إلى بيانات من الرتبة الأولى، ويقرأها بدالة `apply` واحدة، بينما تنهار الاستمراريات إلى `pc` على `Vec`. حلقة القيادة هي منحدر CPS بلا إغلاقات. + +```admonish note title="تشبيه، لا اشتقاق" +يمكن تحليل EVM بوصفها آلة مجردة من الرتبة الأولى يشبه عداد برنامجها الصريح تمثيلًا للتحكم أزيلت دواله. لكن هذا التشابه البنيوي لا يثبت وحده أن شيفرة EVM البايتية نتجت عن تحويل CPS أعقبته إزالة للدوال. +``` + +## الرؤية الأساسية {#key-insight} + +| المفهوم | عالم الموناد الحر | واقع EVM | +| --- | --- | --- | +| نوع التعليمة | تعداد لشفرات العمليات | شفرات عمليات EVM ثابتة | +| تمثيل البرنامج | شجرة مبنية من `Free
` | مصفوفة شيفرة بايتية خطية | +| الاستمرارية | إغلاق في عقدة التعليمة | عداد البرنامج (`pc`) | +| المفسر | مطابقة أنماط البرنامج | تبديل شفرة العملية وتعديل حالة الآلة الافتراضية | +| مفسرات متعددة | طيات مختلفة للبرنامج نفسه | تطبيقات متعددة لعملاء Ethereum | + +## كيفية انطباق ذلك على EVM الحقيقية {#how-this-maps-to-the-real-evm} + +* تعكس **مجموعة التعليمات** (صيغ `Free` أو تعداد `Op`) مجموعة شفرات عمليات EVM. +* يمثل **البرنامج** (شجرة `Free` أو استمراريات متداخلة أو `Vec`) العقد قبل التجميع وبعده. +* يمثل **المفسر** (`run` أو معالجات CPS أو `apply`) ما ينفذه عميل مثل Geth أو Besu أو Nethermind. +* تمثل **حالة الآلة** (`stack` و`storage`) المكدس والذاكرة والتخزين في EVM. +* شيفرة EVM البايتية الحقيقية هي الصيغة التي أزيلت دوالها: مصفوفة تعليمات مسطحة مفهرسة بعداد برنامج، تمامًا مثل الترميز منزوع الدوال أعلاه. diff --git a/src/insights/evm-alg.de.md b/src/insights/evm-alg.de.md new file mode 100644 index 0000000..9367d18 --- /dev/null +++ b/src/insights/evm-alg.de.md @@ -0,0 +1,268 @@ + + +# EVM-Algebra {#evm-algebra} + +```admonish tip title="Verwandte Themen" +Design by Meaning in Rust: [Interpreter und Effekte](../rust-dd/interpreters.md), [Programme erster Ordnung](../rust-dd/first-order-programs.md), [Sprach- und Compiler-Pipelines](../rust-dd/compiler-pipelines.md) +Concepts: [Operationale Semantik](../concepts/operational_semantics.md), [Freie Monade](../concepts/free_monad.md), [Continuation-Passing Style](../concepts/cps.md), [Defunktionalisierung](../concepts/defunctionalization.md) +``` + +Die **Ethereum Virtual Machine (EVM)** ist eine stapelbasierte virtuelle CPU, die **Ethereum-Bytecode** ausführt, also die kompilierte Form von Smart Contracts in Solidity, Vyper oder einer anderen EVM-kompatiblen Sprache. + +Auf der untersten Ebene: + +* Die EVM verarbeitet **Opcodes** (ADD, PUSH, JUMP, SSTORE usw.). +* Execution state includes: + * **Stapel**: LIFO-Datenstapel für Operanden. + * **Speicher**: vorübergehendes Byte-Array für temporäre Werte. + * **Persistenter Speicher**: dauerhafter Schlüssel-Wert-Speicher für jeden Vertrag. + * **Programmzähler**: verweist auf den nächsten Opcode. + * **Gas**: misst die Ausführungskosten der einzelnen Schritte. + +## Die EVM als Interpreter-Muster {#evm-as-an-interpreter-pattern} + +Ein EVM-Client ist ein Interpreter für eine Instruktionssprache: + +* **Instruktionsmenge** = EVM-Opcodes (ein Enum mit Varianten). +* **Programm** = eine Folge von Instruktionen. +* **Interpreter** = die Regel, nach der jeder Opcode den Maschinenzustand ändert. +* **Mehrere Interpreter** = Die EVM-Spezifikation ist festgelegt; Geth, Nethermind, Besu und Erigon sind alternative Implementierungen desselben Interpreters. + +Drei Techniken ziehen sich durch dieses Buch — **freie Monaden**, **Continuation-Passing Style** und **Defunktionalisierung** — und unterscheiden sich nur darin, wie sie *den Rest des Programms* darstellen. + +## Drei Kodierungen einer Maschine {#three-encodings-of-one-machine} + +Jede der folgenden Kodierungen führt dasselbe festgelegte Programm aus: + +```text +push 2; push 3; add; sstore 1 5; load 1 -> v; push v +``` + +und jede erzeugt dieselbe Beobachtung: + +```text +stack: [5, 5] +storage: {1: 5} +``` + +Sie unterscheiden sich nur darin, wie die Steuerung — „was als Nächstes zu tun ist“ — dargestellt wird. + +
+Freie Monade — das Programm sind Daten; ein Interpreter gibt ihnen Bedeutung + +Der Instruktionsfunktor erzeugt einen Programmbaum. `and_then` ist monadisches Binden, und `run` ist ein Interpreter — ein zweiter Interpreter (ein Compiler zu Bytecode) könnte denselben Baum falten. Das generische `Free` ist auf diese Instruktionsmenge spezialisiert, damit es mit stabilem Rust kompiliert. + +```rust +use std::collections::HashMap; + +struct State { stack: Vec, storage: HashMap } + +// The free monad over the EVM instruction set: a program is data — a tree of +// instructions ending in `Pure`, each carrying its continuation. +enum Free { + Pure(A), + Push(u64, Box>), + Add(Box>), + SStore(u64, u64, Box>), + SLoad(u64, Box Free>), +} + +impl Free { + // Monadic bind: graft `k` onto every leaf of the program. + fn and_then(self, k: impl FnOnce(A) -> Free + 'static) -> Free { + match self { + Free::Pure(a) => k(a), + Free::Push(v, next) => Free::Push(v, Box::new(next.and_then(k))), + Free::Add(next) => Free::Add(Box::new(next.and_then(k))), + Free::SStore(x, y, next) => Free::SStore(x, y, Box::new(next.and_then(k))), + Free::SLoad(key, cont) => Free::SLoad(key, Box::new(move |v| cont(v).and_then(k))), + } + } +} + +fn push(v: u64) -> Free<()> { Free::Push(v, Box::new(Free::Pure(()))) } +fn add() -> Free<()> { Free::Add(Box::new(Free::Pure(()))) } +fn sstore(k: u64, v: u64) -> Free<()> { Free::SStore(k, v, Box::new(Free::Pure(()))) } +fn sload(k: u64) -> Free { Free::SLoad(k, Box::new(|v| Free::Pure(v))) } + +// Interpreter: give the program data meaning against the machine state. +fn run(mut prog: Free<()>, st: &mut State) { + loop { + prog = match prog { + Free::Pure(()) => return, + Free::Push(v, next) => { st.stack.push(v); *next } + Free::Add(next) => { + let b = st.stack.pop().unwrap(); + let a = st.stack.pop().unwrap(); + st.stack.push(a + b); + *next + } + Free::SStore(k, v, next) => { st.storage.insert(k, v); *next } + Free::SLoad(k, cont) => { let v = *st.storage.get(&k).unwrap_or(&0); cont(v) } + }; + } +} + +fn main() { + let program = push(2) + .and_then(|_| push(3)) + .and_then(|_| add()) + .and_then(|_| sstore(1, 5)) + .and_then(|_| sload(1)) + .and_then(|v| push(v)); + + let mut st = State { stack: vec![], storage: HashMap::new() }; + run(program, &mut st); + println!("stack: {:?}", st.stack); + println!("storage: {:?}", st.storage); +} +``` + +
+ +
+Continuation-Passing Style (CPS) — jeder Opcode ruft den „Rest des Programms“ auf + +Jeder Handler erledigt seine Arbeit und ruft dann die Fortsetzung `k` auf. `sload` übergibt den geladenen Wert an eine Fortsetzung, die ihn erwartet. Die Steuerung ist als verschachtelte Fortsetzungen explizit; eine Programmdatenstruktur gibt es nicht. + +```rust +use std::collections::HashMap; + +struct State { stack: Vec, storage: HashMap } + +// Each opcode does its work, then calls the continuation `k` = "the rest of +// the program". `sload` passes the loaded value on to its continuation. +fn push(st: &mut State, v: u64, k: impl FnOnce(&mut State)) { + st.stack.push(v); + k(st); +} +fn add(st: &mut State, k: impl FnOnce(&mut State)) { + let b = st.stack.pop().unwrap(); + let a = st.stack.pop().unwrap(); + st.stack.push(a + b); + k(st); +} +fn sstore(st: &mut State, key: u64, val: u64, k: impl FnOnce(&mut State)) { + st.storage.insert(key, val); + k(st); +} +fn sload(st: &mut State, key: u64, k: impl FnOnce(&mut State, u64)) { + let v = *st.storage.get(&key).unwrap_or(&0); + k(st, v); +} + +fn main() { + let mut st = State { stack: vec![], storage: HashMap::new() }; + + push(&mut st, 2, |st| { + push(st, 3, |st| { + add(st, |st| { + sstore(st, 1, 5, |st| { + sload(st, 1, |st, v| { + push(st, v, |_st| {}); + }); + }); + }); + }); + }); + + println!("stack: {:?}", st.stack); + println!("storage: {:?}", st.storage); +} +``` + +
+ +
+Defunktionalisiert — Operationsaufrufe werden zu Daten, die von einem apply ausgeführt werden + +Während freie Monaden und CPS-Versionen Operationen (`push(2)`, `add()`, `sstore(1, 5)`, `sload(1)`) *aufrufen* — eine kleine Algebra, die fast wie eine Spezifikation zu lesen ist —, reifiziert die Defunktionalisierung jeden Aufruf als Daten erster Ordnung. Eine einzige `apply`\-Funktion interpretiert diese Daten; auch die Fortsetzungen werden zusammengezogen: Der „Rest des Programms“ wird zum nächsten Index (`pc`). Man kann es als Operationsalgebra lesen, die als Daten geschrieben ist und `apply` als einzigen Interpreter verwendet. + +```rust +use std::collections::HashMap; + +struct State { stack: Vec, storage: HashMap } + +// The EVM algebra reified: where the other encodings CALL `push(2)`, `add()`, +// `sstore(1, 5)`, `sload(1)`, each such call becomes a first-order value — a +// tag with its arguments. +enum Op { + Push(u64), + Add, + SStore(u64, u64), + SLoad(u64), +} + +// `apply` is the single interpreter for the reified operations: it gives each +// tag its meaning against the machine state. +fn apply(op: &Op, st: &mut State) { + match op { + Op::Push(v) => st.stack.push(*v), + Op::Add => { + let b = st.stack.pop().unwrap(); + let a = st.stack.pop().unwrap(); + st.stack.push(a + b); + } + Op::SStore(k, v) => { st.storage.insert(*k, *v); } + Op::SLoad(k) => { + let v = *st.storage.get(k).unwrap_or(&0); + st.stack.push(v); + } + } +} + +fn main() { + // The program is now data: a flat list of reified operation calls. + let code = vec![ + Op::Push(2), + Op::Push(3), + Op::Add, + Op::SStore(1, 5), + Op::SLoad(1), + ]; + + // `pc` is the defunctionalized continuation: "the rest of the program" is + // just the next index. + let mut st = State { stack: vec![], storage: HashMap::new() }; + let mut pc = 0; + while pc < code.len() { + apply(&code[pc], &mut st); + pc += 1; + } + + println!("stack: {:?}", st.stack); + println!("storage: {:?}", st.storage); +} +``` + +
+ +## Von Fortsetzungen zu Bytecode {#from-continuations-to-bytecode} + +Die drei Kodierungen stellen dieselbe Berechnung dar, jeweils in unterschiedlicher Nähe zur Maschine: + +* **Freie Monade** konstruiert das Programm *algebraisch* als Daten und interpretiert es anschließend. Derselbe Baum kann von mehreren Interpretern gefaltet werden: einem, der ihn ausführt, einem Pretty-Printer und einem Compiler. +* **CPS** entfernt die Datenstruktur und macht die Steuerung explizit: „Führe diesen Opcode aus und rufe dann die Fortsetzung auf.“ Der geladene Wert fließt zur Fortsetzung, die ihn benötigt. +* **Defunktionalisierung** verwandelt Operations*aufrufe* in Daten erster Ordnung und liest sie mit einem `apply` wieder aus; Fortsetzungen werden zu einem `pc` über einem `Vec` zusammengeführt. Die Treiberschleife ist ein CPS-Trampolin ohne Closures. + +```admonish note title="Analogie, keine Herleitung" +Die EVM lässt sich als abstrakte Maschine erster Ordnung mit explizitem Programmzähler analysieren, der einer defunktionalisierten Steuerungsrepräsentation ähnelt. Diese strukturelle Analogie beweist für sich genommen nicht, dass EVM-Bytecode aus einer CPS-Transformation mit anschließender Defunktionalisierung hervorgegangen ist. +``` + +## Zentrale Erkenntnis {#key-insight} + +| Konzept | Welt der freien Monade | EVM-Wirklichkeit | +| --- | --- | --- | +| Instruktionstyp | Enum der Opcodes | Festgelegte EVM-Opcodes | +| Programmdarstellung | Baum aus `Free
` aufgebaut | Lineares Bytecode-Array | +| Fortsetzung | Closure im Instruktionsknoten | Programmzähler (`pc`) | +| Interpreter | Pattern Matching über das Programm | Nach Opcode verzweigen und VM-Zustand verändern | +| Mehrere Interpreter | Verschiedene Faltungen desselben Programms | Mehrere Implementierungen von Ethereum-Clients | + +## Übertragung auf die reale EVM {#how-this-maps-to-the-real-evm} + +* Die **Instruktionsmenge** (die Varianten von `Free` oder das Enum `Op`) spiegelt die Menge der EVM-Opcodes wider. +* Das **Programm** (ein `Free`\-Baum, verschachtelte Fortsetzungen oder eine `Vec`) ist der Vertrag vor und nach der Kompilierung. +* Der **Interpreter** (`run`, CPS-Handler oder `apply`) wird von einem Client wie Geth, Besu oder Nethermind implementiert. +* Der **Maschinenzustand** (`stack`, `storage`) besteht aus Stapel, Speicher und persistentem Speicher der EVM. +* Realer EVM-Bytecode ist die defunktionalisierte Form: ein flaches Instruktionsarray mit Programmzählerindex, genau wie die oben gezeigte defunktionalisierte Kodierung. diff --git a/src/insights/evm-alg.es.md b/src/insights/evm-alg.es.md new file mode 100644 index 0000000..0bdad2f --- /dev/null +++ b/src/insights/evm-alg.es.md @@ -0,0 +1,268 @@ + + +# Álgebra EVM {#evm-algebra} + +```admonish tip title="Relacionado" +Diseño basado en el significado en Rust: [Intérpretes y efectos](../rust-dd/interpreters.md), [Programas de primer orden](../rust-dd/first-order-programs.md), [Lenguaje y procesos de compilación](../rust-dd/compiler-pipelines.md) +Conceptos: [Semántica operacional](../concepts/operational_semantics.md), [Mónada libre](../concepts/free_monad.md), [Estilo de paso de continuaciones](../concepts/cps.md), [Defuncionalización](../concepts/defunctionalization.md) +``` + +La **máquina virtual de Ethereum (EVM)** es una CPU virtual basada en pila que ejecuta el **bytecode de Ethereum**, la forma compilada de los contratos inteligentes escritos en Solidity, Vyper u otro lenguaje compatible con la EVM. + +En el nivel más bajo: + +* La EVM procesa **códigos de operación** (ADD, PUSH, JUMP, SSTORE, etc.). +* Execution state includes: + * **Pila**: pila de datos LIFO para operandos. + * **Memoria**: matriz transitoria de bytes para valores temporales. + * **Almacenamiento**: almacén persistente de pares clave-valor para cada contrato. + * **Contador de programa**: apunta al siguiente código de operación. + * **Gas**: medición que cobra por los pasos de ejecución. + +## La EVM como patrón Intérprete {#evm-as-an-interpreter-pattern} + +Un cliente de la EVM es un intérprete de un lenguaje de instrucciones: + +* **Conjunto de instrucciones** = códigos de operación de la EVM (una enumeración de variantes). +* **Programa** = una secuencia de instrucciones. +* **Intérprete** = la regla que indica cómo cada código de operación modifica el estado de máquina. +* **Varios intérpretes** = la especificación de la EVM es fija, pero Geth, Nethermind, Besu y Erigon son implementaciones alternativas del mismo intérprete. + +Este es el hilo conductor de tres técnicas de este libro: **mónadas libres**, **estilo de paso de continuaciones** y **defuncionalización**, que solo difieren en cómo representan el *resto del programa*. + +## Tres codificaciones de una máquina {#three-encodings-of-one-machine} + +Cada codificación de abajo ejecuta el mismo programa fijo: + +```text +push 2; push 3; add; sstore 1 5; load 1 -> v; push v +``` + +y todas producen la misma observación: + +```text +stack: [5, 5] +storage: {1: 5} +``` + +Solo difieren en la representación del control (es decir, «qué hacer a continuación») + +
+Mónada libre — el programa son datos; un intérprete les da significado + +El functor de instrucciones genera un árbol de programa. `and_then` es el bind monádico y `run` es un intérprete; un segundo intérprete (un compilador a bytecode) podría plegar el mismo árbol. El genérico `Free` se especializa para este conjunto de instrucciones a fin de compilar con Rust estable. + +```rust +use std::collections::HashMap; + +struct State { stack: Vec, storage: HashMap } + +// The free monad over the EVM instruction set: a program is data — a tree of +// instructions ending in `Pure`, each carrying its continuation. +enum Free { + Pure(A), + Push(u64, Box>), + Add(Box>), + SStore(u64, u64, Box>), + SLoad(u64, Box Free>), +} + +impl Free { + // Monadic bind: graft `k` onto every leaf of the program. + fn and_then(self, k: impl FnOnce(A) -> Free + 'static) -> Free { + match self { + Free::Pure(a) => k(a), + Free::Push(v, next) => Free::Push(v, Box::new(next.and_then(k))), + Free::Add(next) => Free::Add(Box::new(next.and_then(k))), + Free::SStore(x, y, next) => Free::SStore(x, y, Box::new(next.and_then(k))), + Free::SLoad(key, cont) => Free::SLoad(key, Box::new(move |v| cont(v).and_then(k))), + } + } +} + +fn push(v: u64) -> Free<()> { Free::Push(v, Box::new(Free::Pure(()))) } +fn add() -> Free<()> { Free::Add(Box::new(Free::Pure(()))) } +fn sstore(k: u64, v: u64) -> Free<()> { Free::SStore(k, v, Box::new(Free::Pure(()))) } +fn sload(k: u64) -> Free { Free::SLoad(k, Box::new(|v| Free::Pure(v))) } + +// Interpreter: give the program data meaning against the machine state. +fn run(mut prog: Free<()>, st: &mut State) { + loop { + prog = match prog { + Free::Pure(()) => return, + Free::Push(v, next) => { st.stack.push(v); *next } + Free::Add(next) => { + let b = st.stack.pop().unwrap(); + let a = st.stack.pop().unwrap(); + st.stack.push(a + b); + *next + } + Free::SStore(k, v, next) => { st.storage.insert(k, v); *next } + Free::SLoad(k, cont) => { let v = *st.storage.get(&k).unwrap_or(&0); cont(v) } + }; + } +} + +fn main() { + let program = push(2) + .and_then(|_| push(3)) + .and_then(|_| add()) + .and_then(|_| sstore(1, 5)) + .and_then(|_| sload(1)) + .and_then(|v| push(v)); + + let mut st = State { stack: vec![], storage: HashMap::new() }; + run(program, &mut st); + println!("stack: {:?}", st.stack); + println!("storage: {:?}", st.storage); +} +``` + +
+ +
+Estilo de paso de continuaciones (CPS) — cada código de operación llama al «resto del programa» + +Cada manejador realiza su trabajo y luego invoca la continuación `k`. `sload` pasa el valor cargado a una continuación que lo espera. El control queda explícito mediante continuaciones anidadas, sin ninguna estructura de datos de programa. + +```rust +use std::collections::HashMap; + +struct State { stack: Vec, storage: HashMap } + +// Each opcode does its work, then calls the continuation `k` = "the rest of +// the program". `sload` passes the loaded value on to its continuation. +fn push(st: &mut State, v: u64, k: impl FnOnce(&mut State)) { + st.stack.push(v); + k(st); +} +fn add(st: &mut State, k: impl FnOnce(&mut State)) { + let b = st.stack.pop().unwrap(); + let a = st.stack.pop().unwrap(); + st.stack.push(a + b); + k(st); +} +fn sstore(st: &mut State, key: u64, val: u64, k: impl FnOnce(&mut State)) { + st.storage.insert(key, val); + k(st); +} +fn sload(st: &mut State, key: u64, k: impl FnOnce(&mut State, u64)) { + let v = *st.storage.get(&key).unwrap_or(&0); + k(st, v); +} + +fn main() { + let mut st = State { stack: vec![], storage: HashMap::new() }; + + push(&mut st, 2, |st| { + push(st, 3, |st| { + add(st, |st| { + sstore(st, 1, 5, |st| { + sload(st, 1, |st, v| { + push(st, v, |_st| {}); + }); + }); + }); + }); + }); + + println!("stack: {:?}", st.stack); + println!("storage: {:?}", st.storage); +} +``` + +
+ +
+Defuncionalizado — las llamadas a operaciones se convierten en datos ejecutados por un único apply + +Mientras las versiones de mónada libre y CPS *llaman* a las operaciones (`push(2)`, `add()`, `sstore(1, 5)`, `sload(1)`) —un álgebra pequeña que casi parece una especificación—, la defuncionalización reifica cada llamada como datos de primer orden. Después, una sola función `apply` interpreta esos datos, y las continuaciones también se reducen: el «resto del programa» pasa a ser el siguiente índice (`pc`). Léelo como el álgebra de operaciones expresada en datos, con `apply` como su único intérprete. + +```rust +use std::collections::HashMap; + +struct State { stack: Vec, storage: HashMap } + +// The EVM algebra reified: where the other encodings CALL `push(2)`, `add()`, +// `sstore(1, 5)`, `sload(1)`, each such call becomes a first-order value — a +// tag with its arguments. +enum Op { + Push(u64), + Add, + SStore(u64, u64), + SLoad(u64), +} + +// `apply` is the single interpreter for the reified operations: it gives each +// tag its meaning against the machine state. +fn apply(op: &Op, st: &mut State) { + match op { + Op::Push(v) => st.stack.push(*v), + Op::Add => { + let b = st.stack.pop().unwrap(); + let a = st.stack.pop().unwrap(); + st.stack.push(a + b); + } + Op::SStore(k, v) => { st.storage.insert(*k, *v); } + Op::SLoad(k) => { + let v = *st.storage.get(k).unwrap_or(&0); + st.stack.push(v); + } + } +} + +fn main() { + // The program is now data: a flat list of reified operation calls. + let code = vec![ + Op::Push(2), + Op::Push(3), + Op::Add, + Op::SStore(1, 5), + Op::SLoad(1), + ]; + + // `pc` is the defunctionalized continuation: "the rest of the program" is + // just the next index. + let mut st = State { stack: vec![], storage: HashMap::new() }; + let mut pc = 0; + while pc < code.len() { + apply(&code[pc], &mut st); + pc += 1; + } + + println!("stack: {:?}", st.stack); + println!("storage: {:?}", st.storage); +} +``` + +
+ +## De las continuaciones al bytecode {#from-continuations-to-bytecode} + +Las tres codificaciones representan el mismo cálculo desde distintas distancias respecto a la máquina: + +* **La mónada libre** construye algebraicamente el programa *como datos* y luego lo interpreta. El mismo árbol puede plegarse con varios intérpretes: uno que lo ejecuta, otro que lo imprime de forma legible y otro que lo compila. +* **CPS** elimina la estructura de datos y hace explícito el control: «ejecuta este código de operación y luego llama a la continuación». El valor cargado llega a la continuación que lo necesita. +* **La defuncionalización** convierte las *llamadas* a operaciones en datos de primer orden y las interpreta con un único `apply`, mientras que las continuaciones se reducen a un `pc` sobre un `Vec`. El bucle controlador es un trampoline CPS sin cierres. + +```admonish note title="Analogía, no derivación" +La EVM se puede analizar como una máquina abstracta de primer orden cuyo contador de programa explícito se asemeja a una representación de control defuncionalizada. Esta analogía estructural no demuestra por sí misma que el bytecode de la EVM se haya obtenido mediante una transformación CPS seguida de defuncionalización. +``` + +## Idea clave {#key-insight} + +| Concepto | En el modelo de mónada libre | Realidad de la EVM | +| --- | --- | --- | +| Tipo de instrucción | Enumeración de códigos de operación | Códigos de operación fijos de la EVM | +| Representación del programa | Árbol construido con `Free
` | Matriz lineal de bytecode | +| Continuación | Cierre en el nodo de instrucción | Contador de programa (`pc`) | +| Intérprete | Coincidencia de patrones sobre el programa | Selección según el código de operación y modificación del estado de la máquina virtual | +| Varios intérpretes | Distintos pliegues del mismo programa | Varias implementaciones de clientes de Ethereum | + +## Correspondencia con la EVM real {#how-this-maps-to-the-real-evm} + +* El **conjunto de instrucciones** (las variantes de `Free` o la enumeración `Op`) refleja el conjunto de códigos de operación de la EVM. +* El **programa** (un árbol `Free`, continuaciones anidadas o un `Vec`) es el contrato antes y después de la compilación. +* El **intérprete** (`run`, los manejadores CPS o `apply`) es lo que implementa un cliente como Geth, Besu o Nethermind. +* El **estado de máquina** (`stack`, `storage`) comprende la pila, la memoria y el almacenamiento de la EVM. +* El bytecode real de la EVM tiene forma defuncionalizada: es una matriz plana de instrucciones indexada por un contador de programa, justo como en la codificación defuncionalizada anterior. diff --git a/src/insights/evm-alg.ja.md b/src/insights/evm-alg.ja.md new file mode 100644 index 0000000..21ee053 --- /dev/null +++ b/src/insights/evm-alg.ja.md @@ -0,0 +1,268 @@ + + +# EVM代数 {#evm-algebra} + +```admonish tip title="関連項目" +Rustで意味から設計する:[インタープリターと副作用](../rust-dd/interpreters.md)、[一階プログラム](../rust-dd/first-order-programs.md)、[言語とコンパイラーパイプライン](../rust-dd/compiler-pipelines.md) +概念:[操作的意味論](../concepts/operational_semantics.md)、[自由モナド](../concepts/free_monad.md)、[継続渡し形式](../concepts/cps.md)、[関数のデファンクショナライズ](../concepts/defunctionalization.md) +``` + +Ethereum Virtual Machine(EVM)は、**Ethereumバイトコード**を実行するスタックベースの仮想CPUです。このバイトコードはSolidity、Vyper、その他のEVM互換言語で書かれたスマートコントラクトのコンパイル結果です。 + +最も低いレベルでは: + +* EVMは**オペコード**(ADD、PUSH、JUMP、SSTOREなど)を処理する。 +* Execution state includes: + * **スタック**:オペランド用の後入れ先出しデータスタック。 + * **メモリー**:一時的な値を格納するバイト配列。 + * **ストレージ**:コントラクトごとに用意される永続的なキー・バリューストア。 + * **プログラムカウンター**:次のオペコードを指す。 + * **Gas**:実行ステップに課金する計量機構。 + +## インタープリターパターンとしてのEVM {#evm-as-an-interpreter-pattern} + +EVMクライアントは命令言語のインタープリターです。 + +* **命令セット**=EVMオペコード(バリアントの列挙型)。 +* **プログラム**=命令の列。 +* **インタープリター**=各オペコードによって機械状態がどう変わるかを定める規則。 +* **複数のインタープリター**=EVMの仕様は固定されており、Geth、Nethermind、Besu、Erigonは同じインタープリターの代替実装である。 + +本書で扱う三つの技法、**自由モナド**、**継続渡し形式**、**デファンクショナライズ**を結ぶ筋道は、*プログラムの残り*をどう表すかの違いです。 + +## 一つの機械を表す三つの符号化 {#three-encodings-of-one-machine} + +以下の各符号化は、同じ固定プログラムを実行します。 + +```text +push 2; push 3; add; sstore 1 5; load 1 -> v; push v +``` + +どの形式でも同じ観測結果になります。 + +```text +stack: [5, 5] +storage: {1: 5} +``` + +違うのは、制御、つまり「次に何をするか」の表現方法だけです。 + +
+自由モナド — プログラムをデータとして表し、インタープリターが意味を与える + +命令ファンクターがプログラム木を生成します。`and_then`はモナド的bindで、`run`は一つのインタープリターです(バイトコードへのコンパイラーなど、二つ目のインタープリターでも同じ木をfoldできます)。ジェネリックな`Free`は、この命令セットに特化することで安定版Rustでもコンパイルできます。 + +```rust +use std::collections::HashMap; + +struct State { stack: Vec, storage: HashMap } + +// The free monad over the EVM instruction set: a program is data — a tree of +// instructions ending in `Pure`, each carrying its continuation. +enum Free { + Pure(A), + Push(u64, Box>), + Add(Box>), + SStore(u64, u64, Box>), + SLoad(u64, Box Free>), +} + +impl Free { + // Monadic bind: graft `k` onto every leaf of the program. + fn and_then(self, k: impl FnOnce(A) -> Free + 'static) -> Free { + match self { + Free::Pure(a) => k(a), + Free::Push(v, next) => Free::Push(v, Box::new(next.and_then(k))), + Free::Add(next) => Free::Add(Box::new(next.and_then(k))), + Free::SStore(x, y, next) => Free::SStore(x, y, Box::new(next.and_then(k))), + Free::SLoad(key, cont) => Free::SLoad(key, Box::new(move |v| cont(v).and_then(k))), + } + } +} + +fn push(v: u64) -> Free<()> { Free::Push(v, Box::new(Free::Pure(()))) } +fn add() -> Free<()> { Free::Add(Box::new(Free::Pure(()))) } +fn sstore(k: u64, v: u64) -> Free<()> { Free::SStore(k, v, Box::new(Free::Pure(()))) } +fn sload(k: u64) -> Free { Free::SLoad(k, Box::new(|v| Free::Pure(v))) } + +// Interpreter: give the program data meaning against the machine state. +fn run(mut prog: Free<()>, st: &mut State) { + loop { + prog = match prog { + Free::Pure(()) => return, + Free::Push(v, next) => { st.stack.push(v); *next } + Free::Add(next) => { + let b = st.stack.pop().unwrap(); + let a = st.stack.pop().unwrap(); + st.stack.push(a + b); + *next + } + Free::SStore(k, v, next) => { st.storage.insert(k, v); *next } + Free::SLoad(k, cont) => { let v = *st.storage.get(&k).unwrap_or(&0); cont(v) } + }; + } +} + +fn main() { + let program = push(2) + .and_then(|_| push(3)) + .and_then(|_| add()) + .and_then(|_| sstore(1, 5)) + .and_then(|_| sload(1)) + .and_then(|v| push(v)); + + let mut st = State { stack: vec![], storage: HashMap::new() }; + run(program, &mut st); + println!("stack: {:?}", st.stack); + println!("storage: {:?}", st.storage); +} +``` + +
+ +
+継続渡し形式(CPS) — 各オペコードが「プログラムの残り」を呼び出す + +各ハンドラーは処理を行い、その後継続`k`を呼び出します。`sload`では、読み込んだ値をそれを受け取る継続に渡します。制御はネストされた継続として明示され、プログラムのデータ構造はありません。 + +```rust +use std::collections::HashMap; + +struct State { stack: Vec, storage: HashMap } + +// Each opcode does its work, then calls the continuation `k` = "the rest of +// the program". `sload` passes the loaded value on to its continuation. +fn push(st: &mut State, v: u64, k: impl FnOnce(&mut State)) { + st.stack.push(v); + k(st); +} +fn add(st: &mut State, k: impl FnOnce(&mut State)) { + let b = st.stack.pop().unwrap(); + let a = st.stack.pop().unwrap(); + st.stack.push(a + b); + k(st); +} +fn sstore(st: &mut State, key: u64, val: u64, k: impl FnOnce(&mut State)) { + st.storage.insert(key, val); + k(st); +} +fn sload(st: &mut State, key: u64, k: impl FnOnce(&mut State, u64)) { + let v = *st.storage.get(&key).unwrap_or(&0); + k(st, v); +} + +fn main() { + let mut st = State { stack: vec![], storage: HashMap::new() }; + + push(&mut st, 2, |st| { + push(st, 3, |st| { + add(st, |st| { + sstore(st, 1, 5, |st| { + sload(st, 1, |st, v| { + push(st, v, |_st| {}); + }); + }); + }); + }); + }); + + println!("stack: {:?}", st.stack); + println!("storage: {:?}", st.storage); +} +``` + +
+ +
+デファンクショナライズ — 操作の呼び出しをデータに変え、一つのapplyで実行する + +自由モナド版とCPS版は、仕様のように読める小さな代数である操作(`push(2)`、`add()`、`sstore(1, 5)`、`sload(1)`)を*呼び出します*。デファンクショナライズでは、各呼び出しを一階データとして再構化します。一つの`apply`関数でそのデータを解釈し、継続もまとめます。「プログラムの残り」は次のインデックス(`pc`)になります。操作の代数をデータとして記述し、`apply`一つのインタープリターで解釈すると考えてください。 + +```rust +use std::collections::HashMap; + +struct State { stack: Vec, storage: HashMap } + +// The EVM algebra reified: where the other encodings CALL `push(2)`, `add()`, +// `sstore(1, 5)`, `sload(1)`, each such call becomes a first-order value — a +// tag with its arguments. +enum Op { + Push(u64), + Add, + SStore(u64, u64), + SLoad(u64), +} + +// `apply` is the single interpreter for the reified operations: it gives each +// tag its meaning against the machine state. +fn apply(op: &Op, st: &mut State) { + match op { + Op::Push(v) => st.stack.push(*v), + Op::Add => { + let b = st.stack.pop().unwrap(); + let a = st.stack.pop().unwrap(); + st.stack.push(a + b); + } + Op::SStore(k, v) => { st.storage.insert(*k, *v); } + Op::SLoad(k) => { + let v = *st.storage.get(k).unwrap_or(&0); + st.stack.push(v); + } + } +} + +fn main() { + // The program is now data: a flat list of reified operation calls. + let code = vec![ + Op::Push(2), + Op::Push(3), + Op::Add, + Op::SStore(1, 5), + Op::SLoad(1), + ]; + + // `pc` is the defunctionalized continuation: "the rest of the program" is + // just the next index. + let mut st = State { stack: vec![], storage: HashMap::new() }; + let mut pc = 0; + while pc < code.len() { + apply(&code[pc], &mut st); + pc += 1; + } + + println!("stack: {:?}", st.stack); + println!("storage: {:?}", st.storage); +} +``` + +
+ +## 継続からバイトコードへ {#from-continuations-to-bytecode} + +三つの符号化は、機械との距離の異なる場所から同じ計算を見たものです。 + +* **自由モナド**では、プログラムを*代数的に*データとして構築し、その後で解釈します。同じ木を複数のインタープリターでfoldできます。実行用、整形表示用、コンパイル用などを用意できます。 +* **CPS**ではデータ構造を取り除き、制御を明示します。「このオペコードを実行し、その後に継続を呼び出す」。読み込んだ値は、それを必要とする継続へ流れます。 +* **デファンクショナライズ**では、操作の*呼び出し*を一階データにし、一つの`apply`で読み戻します。同時に継続は、`Vec`上の`pc`へと縮約されます。ドライブループはクロージャのないCPSトランポリンです。 + +```admonish note title="類推であり、導出ではない" +EVMは、明示的なプログラムカウンターを持つ一階抽象機械として分析できます。その構造はデファンクショナライズされた制御表現に似ています。しかしこの類似だけでは、EVMバイトコードがCPS変換の後にデファンクショナライズして得られた証明にはなりません。 +``` + +## 主な洞察 {#key-insight} + +| 概念 | 自由モナドの世界 | EVMの実際 | +| --- | --- | --- | +| 命令型 | オペコードの列挙型 | 固定されたEVMオペコード | +| プログラム表現 | `Free
`から構築される木 | 線形のバイトコード配列 | +| 継続 | 命令ノードのクロージャ | プログラムカウンター(`pc`) | +| インタープリター | プログラムに対するパターンマッチ | オペコードのswitchとVM状態の変更 | +| 複数のインタープリター | 同じプログラムの異なるfold | 複数のEthereumクライアント実装 | + +## 実際のEVMとの対応 {#how-this-maps-to-the-real-evm} + +* **命令セット**(`Free`のバリアント、または`Op`列挙型)はEVMオペコード集合に対応します。 +* **プログラム**(`Free`木、ネストされた継続、または`Vec`)はコンパイル前後のコントラクトを表します。 +* **インタープリター**(`run`、CPSハンドラー、または`apply`)は、Geth、Besu、Nethermindなどのクライアントが実装するものです。 +* **機械状態**(`stack`、`storage`)はEVMのスタック、メモリー、ストレージです。 +* 実際のEVMバイトコードはデファンクショナライズされた形式です。上記のデファンクショナライズ符号化と同じく、プログラムカウンターでインデックス付けされた平坦な命令配列です。 diff --git a/src/insights/evm-alg.ko.md b/src/insights/evm-alg.ko.md new file mode 100644 index 0000000..466f9fd --- /dev/null +++ b/src/insights/evm-alg.ko.md @@ -0,0 +1,268 @@ + + +# EVM 대수 {#evm-algebra} + +```admonish tip title="관련 항목" +Rust에서 의미로 설계하기: [인터프리터와 효과](../rust-dd/interpreters.md), [일차 프로그램](../rust-dd/first-order-programs.md), [언어와 컴파일러 파이프라인](../rust-dd/compiler-pipelines.md) +개념: [작동 의미론](../concepts/operational_semantics.md), [자유 모나드](../concepts/free_monad.md), [연속 전달 스타일](../concepts/cps.md), [디펑셔널라이제이션](../concepts/defunctionalization.md) +``` + +이더리움 가상 머신(EVM)은 **이더리움 바이트코드**를 실행하는 스택 기반 가상 CPU입니다. Solidity, Vyper 또는 다른 EVM 호환 언어로 작성한 스마트 계약을 컴파일한 형식입니다. + +가장 낮은 수준에서: + +* EVM은 **연산 코드**(ADD, PUSH, JUMP, SSTORE 등)를 처리합니다. +* Execution state includes: + * **스택**: 피연산자를 담는 후입선출 데이터 스택. + * **메모리**: 임시 값을 위한 휘발성 바이트 배열. + * **저장소**: 각 계약을 위한 영속 키-값 저장소. + * **프로그램 카운터**: 다음 연산 코드의 위치. + * **가스**: 실행 단계마다 비용을 부과하는 계량 장치 + +## 인터프리터 패턴으로서의 EVM {#evm-as-an-interpreter-pattern} + +EVM 클라이언트는 명령어 언어를 해석하는 인터프리터입니다: + +* **명령어 집합** = EVM 연산 코드 (변형의 열거형). +* **프로그램** = 명령어 시퀀스. +* **인터프리터** = 각 연산 코드가 기계 상태를 바꾸는 규칙. +* **여러 인터프리터** = EVM 명세는 고정되어 있지만 Geth, Nethermind, Besu, Erigon은 같은 인터프리터의 대안 구현입니다. + +이 책의 세 기법 **자유 모나드**, **연속 전달 스타일**, **디펑셔널라이제이션**을 관통하는 주제는 같습니다. *프로그램의 나머지*를 표현하는 방식만 다릅니다. + +## 하나의 기계, 세 가지 인코딩 {#three-encodings-of-one-machine} + +아래 각 인코딩은 같은 고정 프로그램을 실행합니다: + +```text +push 2; push 3; add; sstore 1 5; load 1 -> v; push v +``` + +그리고 모두 같은 관찰 결과를 냅니다: + +```text +stack: [5, 5] +storage: {1: 5} +``` + +제어, 즉 “다음에 할 일”을 표현하는 방식만 다릅니다. + +
+자유 모나드 — 프로그램은 데이터이며 인터프리터가 의미를 부여합니다 + +명령어 펑터가 프로그램 트리를 생성합니다. `and_then`는 모나드 바인드이고 `run`는 인터프리터 하나입니다. 두 번째 인터프리터(바이트코드 컴파일러)가 같은 트리를 폴드할 수도 있습니다. 제네릭 `Free`는 안정화 Rust에서 컴파일되도록 이 명령어 집합에 맞게 특수화되어 있습니다. + +```rust +use std::collections::HashMap; + +struct State { stack: Vec, storage: HashMap } + +// The free monad over the EVM instruction set: a program is data — a tree of +// instructions ending in `Pure`, each carrying its continuation. +enum Free { + Pure(A), + Push(u64, Box>), + Add(Box>), + SStore(u64, u64, Box>), + SLoad(u64, Box Free>), +} + +impl Free { + // Monadic bind: graft `k` onto every leaf of the program. + fn and_then(self, k: impl FnOnce(A) -> Free + 'static) -> Free { + match self { + Free::Pure(a) => k(a), + Free::Push(v, next) => Free::Push(v, Box::new(next.and_then(k))), + Free::Add(next) => Free::Add(Box::new(next.and_then(k))), + Free::SStore(x, y, next) => Free::SStore(x, y, Box::new(next.and_then(k))), + Free::SLoad(key, cont) => Free::SLoad(key, Box::new(move |v| cont(v).and_then(k))), + } + } +} + +fn push(v: u64) -> Free<()> { Free::Push(v, Box::new(Free::Pure(()))) } +fn add() -> Free<()> { Free::Add(Box::new(Free::Pure(()))) } +fn sstore(k: u64, v: u64) -> Free<()> { Free::SStore(k, v, Box::new(Free::Pure(()))) } +fn sload(k: u64) -> Free { Free::SLoad(k, Box::new(|v| Free::Pure(v))) } + +// Interpreter: give the program data meaning against the machine state. +fn run(mut prog: Free<()>, st: &mut State) { + loop { + prog = match prog { + Free::Pure(()) => return, + Free::Push(v, next) => { st.stack.push(v); *next } + Free::Add(next) => { + let b = st.stack.pop().unwrap(); + let a = st.stack.pop().unwrap(); + st.stack.push(a + b); + *next + } + Free::SStore(k, v, next) => { st.storage.insert(k, v); *next } + Free::SLoad(k, cont) => { let v = *st.storage.get(&k).unwrap_or(&0); cont(v) } + }; + } +} + +fn main() { + let program = push(2) + .and_then(|_| push(3)) + .and_then(|_| add()) + .and_then(|_| sstore(1, 5)) + .and_then(|_| sload(1)) + .and_then(|v| push(v)); + + let mut st = State { stack: vec![], storage: HashMap::new() }; + run(program, &mut st); + println!("stack: {:?}", st.stack); + println!("storage: {:?}", st.storage); +} +``` + +
+ +
+연속 전달 스타일(CPS) — 각 연산 코드가 “프로그램의 나머지”를 호출합니다 + +각 핸들러는 작업을 한 다음 연속 실행 `k`를 호출합니다. `sload`은 로드한 값을 그 값을 기대하는 연속 실행에 전달합니다. 프로그램 데이터 구조 없이 중첩된 연속 실행으로 제어를 명시합니다. + +```rust +use std::collections::HashMap; + +struct State { stack: Vec, storage: HashMap } + +// Each opcode does its work, then calls the continuation `k` = "the rest of +// the program". `sload` passes the loaded value on to its continuation. +fn push(st: &mut State, v: u64, k: impl FnOnce(&mut State)) { + st.stack.push(v); + k(st); +} +fn add(st: &mut State, k: impl FnOnce(&mut State)) { + let b = st.stack.pop().unwrap(); + let a = st.stack.pop().unwrap(); + st.stack.push(a + b); + k(st); +} +fn sstore(st: &mut State, key: u64, val: u64, k: impl FnOnce(&mut State)) { + st.storage.insert(key, val); + k(st); +} +fn sload(st: &mut State, key: u64, k: impl FnOnce(&mut State, u64)) { + let v = *st.storage.get(&key).unwrap_or(&0); + k(st, v); +} + +fn main() { + let mut st = State { stack: vec![], storage: HashMap::new() }; + + push(&mut st, 2, |st| { + push(st, 3, |st| { + add(st, |st| { + sstore(st, 1, 5, |st| { + sload(st, 1, |st, v| { + push(st, v, |_st| {}); + }); + }); + }); + }); + }); + + println!("stack: {:?}", st.stack); + println!("storage: {:?}", st.storage); +} +``` + +
+ +
+디펑셔널라이즈됨 — 연산 호출이 데이터가 되고 하나의 apply가 실행합니다 + +자유 모나드와 CPS 버전은 연산(`push(2)`, `add()`, `sstore(1, 5)`, `sload(1)`)을 *호출*합니다. 이는 명세처럼 읽히는 작은 대수입니다. 디펑셔널라이제이션은 각 호출을 일차 데이터로 재구화합니다. 하나의 `apply` 함수가 데이터를 해석하고 연속 실행도 단순해집니다. “프로그램의 나머지”가 다음 인덱스(`pc`)가 됩니다. 이를 연산 대수를 데이터로 작성하고 `apply`라는 단일 인터프리터로 해석하는 것으로 읽어 보세요. + +```rust +use std::collections::HashMap; + +struct State { stack: Vec, storage: HashMap } + +// The EVM algebra reified: where the other encodings CALL `push(2)`, `add()`, +// `sstore(1, 5)`, `sload(1)`, each such call becomes a first-order value — a +// tag with its arguments. +enum Op { + Push(u64), + Add, + SStore(u64, u64), + SLoad(u64), +} + +// `apply` is the single interpreter for the reified operations: it gives each +// tag its meaning against the machine state. +fn apply(op: &Op, st: &mut State) { + match op { + Op::Push(v) => st.stack.push(*v), + Op::Add => { + let b = st.stack.pop().unwrap(); + let a = st.stack.pop().unwrap(); + st.stack.push(a + b); + } + Op::SStore(k, v) => { st.storage.insert(*k, *v); } + Op::SLoad(k) => { + let v = *st.storage.get(k).unwrap_or(&0); + st.stack.push(v); + } + } +} + +fn main() { + // The program is now data: a flat list of reified operation calls. + let code = vec![ + Op::Push(2), + Op::Push(3), + Op::Add, + Op::SStore(1, 5), + Op::SLoad(1), + ]; + + // `pc` is the defunctionalized continuation: "the rest of the program" is + // just the next index. + let mut st = State { stack: vec![], storage: HashMap::new() }; + let mut pc = 0; + while pc < code.len() { + apply(&code[pc], &mut st); + pc += 1; + } + + println!("stack: {:?}", st.stack); + println!("storage: {:?}", st.storage); +} +``` + +
+ +## 연속 실행에서 바이트코드까지 {#from-continuations-to-bytecode} + +세 인코딩은 같은 계산을 기계와의 거리를 달리해 보여 줍니다: + +* **자유 모나드**는 프로그램을 데이터로 *대수적으로* 구성한 다음 해석합니다. 실행, 예쁘게 출력, 컴파일 등 여러 인터프리터가 같은 트리를 폴드할 수 있습니다. +* **CPS**는 데이터 구조를 없애고 제어를 명시합니다. “이 연산 코드를 실행한 다음 연속 실행을 호출”하는 방식입니다. 로드된 값은 이를 필요로 하는 연속 실행에 전달됩니다. +* **디펑셔널라이제이션**은 연산 *호출*을 일차 데이터로 바꾸고 하나의 `apply`로 이를 다시 읽습니다. 연속 실행은 `pc`을 통해 `Vec`로 합쳐집니다. 드라이버 루프는 클로저가 없는 CPS 트램펄린입니다. + +```admonish note title="도출이 아닌 유사성" +EVM은 명시적인 프로그램 카운터가 디펑셔널라이즈된 제어 표현과 닮은 일차 추상 기계로 분석할 수 있습니다. 그러나 이런 구조적 유사성만으로 EVM 바이트코드가 CPS 변환 뒤 디펑셔널라이제이션을 거쳐 만들어졌다는 점이 증명되지는 않습니다. +``` + +## 핵심 통찰 {#key-insight} + +| 개념 | 자유 모나드 세계 | EVM의 실제 모습 | +| --- | --- | --- | +| 명령어 타입 | 연산 코드 열거형 | 고정된 EVM 연산 코드 | +| 프로그램 표현 | `Free
`에서 구성한 트리 | 선형 바이트코드 배열 | +| 연속 실행 | 명령어 노드의 클로저 | 프로그램 카운터 (`pc`) | +| 인터프리터 | 프로그램 패턴 매칭 | 연산 코드 분기와 VM 상태 변경 | +| 여러 인터프리터 | 같은 프로그램을 서로 다르게 폴드 | 여러 이더리움 클라이언트 구현 | + +## 실제 EVM에 대응시키기 {#how-this-maps-to-the-real-evm} + +* **명령어 집합** (`Free`의 변형 또는 `Op` 열거형)은 EVM 연산 코드 집합과 대응합니다. +* **프로그램** (`Free` 트리, 중첩 연속 실행 또는 `Vec`)은 컴파일 전후의 계약입니다. +* **인터프리터** (`run`, CPS 핸들러 또는 `apply`)는 Geth, Besu, Nethermind 같은 클라이언트가 구현하는 것입니다. +* **기계 상태** (`stack`, `storage`)는 EVM의 스택, 메모리, 저장소입니다. +* 실제 EVM 바이트코드는 디펑셔널라이즈된 형태입니다. 프로그램 카운터로 색인하는 평면 명령어 배열로, 앞서 본 디펑셔널라이즈 인코딩과 정확히 같습니다. diff --git a/src/insights/evm-alg.ru.md b/src/insights/evm-alg.ru.md new file mode 100644 index 0000000..34190f9 --- /dev/null +++ b/src/insights/evm-alg.ru.md @@ -0,0 +1,268 @@ + + +# Алгебра EVM {#evm-algebra} + +```admonish tip title="Связанные материалы" +«Проектирование на основе смысла в Rust»: [Интерпретаторы и эффекты](../rust-dd/interpreters.md), [Программы первого порядка](../rust-dd/first-order-programs.md), [Язык и конвейеры компилятора](../rust-dd/compiler-pipelines.md) +«Понятия»: [Операционная семантика](../concepts/operational_semantics.md), [Свободная монада](../concepts/free_monad.md), [Стиль передачи продолжений](../concepts/cps.md), [Дефункционализация](../concepts/defunctionalization.md) +``` + +**Виртуальная машина Ethereum (EVM)** — это стековый виртуальный процессор, который исполняет **байткод Ethereum** — скомпилированное представление смарт-контрактов, написанных на Solidity, Vyper или другом совместимом с EVM языке. + +На самом низком уровне: + +* EVM обрабатывает **опкоды** (ADD, PUSH, JUMP, SSTORE и т. д.). +* Execution state includes: + * **Стек**: стек данных LIFO для операндов. + * **Память**: временный массив байтов для промежуточных значений. + * **Хранилище**: постоянное хранилище пар «ключ — значение» каждого контракта. + * **Счётчик команд**: указывает на следующую операцию. + * **Газ**: единица учёта, в которой оплачиваются шаги выполнения. + +## EVM как паттерн интерпретатора {#evm-as-an-interpreter-pattern} + +Клиент EVM — интерпретатор языка инструкций: + +* **Набор инструкций** = опкоды EVM (перечисление вариантов). +* **Программа** = последовательность инструкций. +* **Интерпретатор** = правило изменения состояния машины для каждой операции. +* **Несколько интерпретаторов** = спецификация EVM неизменна, но Geth, Nethermind, Besu и Erigon — альтернативные реализации одного интерпретатора. + +В этом и состоит связь трёх методов книги — **свободных монад**, **стиля передачи продолжений** и **дефункционализации**, — различающихся только представлением *оставшейся части программы*. + +## Три кодирования одной машины {#three-encodings-of-one-machine} + +Каждое кодирование ниже выполняет одну и ту же фиксированную программу: + +```text +push 2; push 3; add; sstore 1 5; load 1 -> v; push v +``` + +и каждое выдаёт одно и то же наблюдение: + +```text +stack: [5, 5] +storage: {1: 5} +``` + +Различается только способ представления управления — «что делать дальше». + +
+Свободная монада — программа является данными; интерпретатор придаёт им смысл + +Функтор инструкций порождает дерево программы. `and_then` — монадическая операция bind, а `run` — один из интерпретаторов; второй интерпретатор (компилятор в байткод) может свернуть то же дерево. Обобщённый `Free` специализируется для этого набора инструкций, чтобы компилироваться в стабильном Rust. + +```rust +use std::collections::HashMap; + +struct State { stack: Vec, storage: HashMap } + +// The free monad over the EVM instruction set: a program is data — a tree of +// instructions ending in `Pure`, each carrying its continuation. +enum Free { + Pure(A), + Push(u64, Box>), + Add(Box>), + SStore(u64, u64, Box>), + SLoad(u64, Box Free>), +} + +impl Free { + // Monadic bind: graft `k` onto every leaf of the program. + fn and_then(self, k: impl FnOnce(A) -> Free + 'static) -> Free { + match self { + Free::Pure(a) => k(a), + Free::Push(v, next) => Free::Push(v, Box::new(next.and_then(k))), + Free::Add(next) => Free::Add(Box::new(next.and_then(k))), + Free::SStore(x, y, next) => Free::SStore(x, y, Box::new(next.and_then(k))), + Free::SLoad(key, cont) => Free::SLoad(key, Box::new(move |v| cont(v).and_then(k))), + } + } +} + +fn push(v: u64) -> Free<()> { Free::Push(v, Box::new(Free::Pure(()))) } +fn add() -> Free<()> { Free::Add(Box::new(Free::Pure(()))) } +fn sstore(k: u64, v: u64) -> Free<()> { Free::SStore(k, v, Box::new(Free::Pure(()))) } +fn sload(k: u64) -> Free { Free::SLoad(k, Box::new(|v| Free::Pure(v))) } + +// Interpreter: give the program data meaning against the machine state. +fn run(mut prog: Free<()>, st: &mut State) { + loop { + prog = match prog { + Free::Pure(()) => return, + Free::Push(v, next) => { st.stack.push(v); *next } + Free::Add(next) => { + let b = st.stack.pop().unwrap(); + let a = st.stack.pop().unwrap(); + st.stack.push(a + b); + *next + } + Free::SStore(k, v, next) => { st.storage.insert(k, v); *next } + Free::SLoad(k, cont) => { let v = *st.storage.get(&k).unwrap_or(&0); cont(v) } + }; + } +} + +fn main() { + let program = push(2) + .and_then(|_| push(3)) + .and_then(|_| add()) + .and_then(|_| sstore(1, 5)) + .and_then(|_| sload(1)) + .and_then(|v| push(v)); + + let mut st = State { stack: vec![], storage: HashMap::new() }; + run(program, &mut st); + println!("stack: {:?}", st.stack); + println!("storage: {:?}", st.storage); +} +``` + +
+ +
+Стиль передачи продолжений (CPS) — каждая операция вызывает «оставшуюся часть программы» + +Каждый обработчик выполняет свою работу, а затем вызывает продолжение `k`. `sload` передаёт загруженное значение продолжению, которое его ожидает. Управление явно представлено вложенными продолжениями; структуры данных программы нет. + +```rust +use std::collections::HashMap; + +struct State { stack: Vec, storage: HashMap } + +// Each opcode does its work, then calls the continuation `k` = "the rest of +// the program". `sload` passes the loaded value on to its continuation. +fn push(st: &mut State, v: u64, k: impl FnOnce(&mut State)) { + st.stack.push(v); + k(st); +} +fn add(st: &mut State, k: impl FnOnce(&mut State)) { + let b = st.stack.pop().unwrap(); + let a = st.stack.pop().unwrap(); + st.stack.push(a + b); + k(st); +} +fn sstore(st: &mut State, key: u64, val: u64, k: impl FnOnce(&mut State)) { + st.storage.insert(key, val); + k(st); +} +fn sload(st: &mut State, key: u64, k: impl FnOnce(&mut State, u64)) { + let v = *st.storage.get(&key).unwrap_or(&0); + k(st, v); +} + +fn main() { + let mut st = State { stack: vec![], storage: HashMap::new() }; + + push(&mut st, 2, |st| { + push(st, 3, |st| { + add(st, |st| { + sstore(st, 1, 5, |st| { + sload(st, 1, |st, v| { + push(st, v, |_st| {}); + }); + }); + }); + }); + }); + + println!("stack: {:?}", st.stack); + println!("storage: {:?}", st.storage); +} +``` + +
+ +
+Дефункционализированная форма — вызовы операций становятся данными, которые выполняет один apply + +В версиях со свободной монадой и CPS операции *вызываются* (`push(2)`, `add()`, `sstore(1, 5)`, `sload(1)`) — это небольшая алгебра, почти похожая на спецификацию. Дефункционализация реифицирует каждый вызов в данные первого порядка. Затем один метод `apply` интерпретирует эти данные, а продолжения тоже сворачиваются: «оставшаяся часть программы» становится следующим индексом (`pc`). Это алгебра операций, записанная в виде данных, и её единственный интерпретатор `apply`. + +```rust +use std::collections::HashMap; + +struct State { stack: Vec, storage: HashMap } + +// The EVM algebra reified: where the other encodings CALL `push(2)`, `add()`, +// `sstore(1, 5)`, `sload(1)`, each such call becomes a first-order value — a +// tag with its arguments. +enum Op { + Push(u64), + Add, + SStore(u64, u64), + SLoad(u64), +} + +// `apply` is the single interpreter for the reified operations: it gives each +// tag its meaning against the machine state. +fn apply(op: &Op, st: &mut State) { + match op { + Op::Push(v) => st.stack.push(*v), + Op::Add => { + let b = st.stack.pop().unwrap(); + let a = st.stack.pop().unwrap(); + st.stack.push(a + b); + } + Op::SStore(k, v) => { st.storage.insert(*k, *v); } + Op::SLoad(k) => { + let v = *st.storage.get(k).unwrap_or(&0); + st.stack.push(v); + } + } +} + +fn main() { + // The program is now data: a flat list of reified operation calls. + let code = vec![ + Op::Push(2), + Op::Push(3), + Op::Add, + Op::SStore(1, 5), + Op::SLoad(1), + ]; + + // `pc` is the defunctionalized continuation: "the rest of the program" is + // just the next index. + let mut st = State { stack: vec![], storage: HashMap::new() }; + let mut pc = 0; + while pc < code.len() { + apply(&code[pc], &mut st); + pc += 1; + } + + println!("stack: {:?}", st.stack); + println!("storage: {:?}", st.storage); +} +``` + +
+ +## От продолжений к байткоду {#from-continuations-to-bytecode} + +Три кодирования — одна и та же программа, показанная на разном расстоянии от машины: + +* **Свободная монада** строит программу *алгебраически* в виде данных, а затем интерпретирует её. То же дерево могут сворачивать разные интерпретаторы: один запускает его, другой форматирует, третий компилирует. +* **CPS** убирает структуру данных и делает управление явным: «выполни эту операцию, затем вызови продолжение». Загруженное значение передаётся нужному продолжению. +* **Дефункционализация** превращает *вызовы* операций в данные первого порядка и считывает их одной операцией `apply`; продолжения сворачиваются в `pc` на `Vec`. Цикл-драйвер — это трамплин CPS без замыканий. + +```admonish note title="Аналогия, а не вывод" +EVM можно рассматривать как абстрактную машину первого порядка с явным счётчиком команд, напоминающим дефункционализированное представление управления. Эта структурная аналогия сама по себе не доказывает, что байткод EVM получен CPS-преобразованием с последующей дефункционализацией. +``` + +## Основная мысль {#key-insight} + +| Понятие | Мир свободных монад | Реальность EVM | +| --- | --- | --- | +| Тип инструкции | Перечисление операций | Фиксированный набор операций EVM | +| Представление программы | Дерево, построенное из `Free
` | Линейный массив байткода | +| Продолжение | Замыкание внутри узла инструкции | Счётчик команд (`pc`) | +| Интерпретатор | Сопоставление с образцом для программы | Выбор операции и изменение состояния виртуальной машины | +| Несколько интерпретаторов | Разные свёртки одной программы | Несколько реализаций клиента Ethereum | + +## Связь с настоящей EVM {#how-this-maps-to-the-real-evm} + +* **Набор инструкций** (варианты `Free` или перечисление `Op`) отражает набор операций EVM. +* **Программа** (дерево `Free`, вложенные продолжения или `Vec`) — это контракт до и после компиляции. +* **Интерпретатор** (`run`, обработчики CPS или `apply`) — то, что реализует клиент вроде Geth, Besu или Nethermind. +* **Состояние машины** (`stack`, `storage`) — это стек, память и хранилище EVM. +* Настоящий байткод EVM — дефункционализированная форма: плоский массив инструкций с индексом-счётчиком команд, в точности как в кодировании выше. diff --git a/src/insights/evm-alg.uk.md b/src/insights/evm-alg.uk.md new file mode 100644 index 0000000..bd1d470 --- /dev/null +++ b/src/insights/evm-alg.uk.md @@ -0,0 +1,268 @@ + + +# Алгебра EVM {#evm-algebra} + +```admonish tip title="Пов’язані матеріали" +Проєктування від значення в Rust: [Інтерпретатори й ефекти](../rust-dd/interpreters.md), [Програми першого порядку](../rust-dd/first-order-programs.md), [Мова й конвеєри компілятора](../rust-dd/compiler-pipelines.md) +Поняття: [Операційна семантика](../concepts/operational_semantics.md), [Вільна монада](../concepts/free_monad.md), [Стиль передавання продовжень](../concepts/cps.md), [Дефункціоналізація](../concepts/defunctionalization.md) +``` + +**Віртуальна машина Ethereum (EVM)** — це віртуальний процесор на основі стека, який виконує **байткод Ethereum** — скомпільовану форму смартконтрактів, написаних мовою Solidity, Vyper чи іншою сумісною з EVM мовою. + +На найнижчому рівні: + +* EVM обробляє **опкоди** (ADD, PUSH, JUMP, SSTORE тощо). +* Execution state includes: + * **Стек**: стек даних для операндів за принципом LIFO. + * **Пам’ять**: тимчасовий масив байтів для проміжних значень. + * **Сховище**: постійне сховище пар «ключ — значення» для кожного контракту. + * **Лічильник команд**: вказує на наступний опкод. + * **Газ**: облік витрат за кроки виконання. + +## EVM як патерн інтерпретатора {#evm-as-an-interpreter-pattern} + +Клієнт EVM — це інтерпретатор мови інструкцій: + +* **Набір інструкцій** = опкоди EVM (перелік варіантів). +* **Програма** = послідовність інструкцій. +* **Інтерпретатор** = правило, за яким кожен опкод змінює стан машини. +* **Кілька інтерпретаторів** = специфікація EVM фіксована, але Geth, Nethermind, Besu та Erigon є альтернативними реалізаціями цього інтерпретатора. + +Це наскрізна тема трьох методів у цій книжці — **вільних монад**, **стилю передавання продовжень** і **дефункціоналізації**, — які відрізняються лише способом представлення *решти програми*. + +## Три кодування однієї машини {#three-encodings-of-one-machine} + +У кожному наведеному нижче кодуванні виконується та сама фіксована програма: + +```text +push 2; push 3; add; sstore 1 5; load 1 -> v; push v +``` + +і кожне дає те саме спостереження: + +```text +stack: [5, 5] +storage: {1: 5} +``` + +Відрізняється лише спосіб представлення керування — «що робити далі». + +
+Вільна монада — програма є даними, а інтерпретатор надає їй значення + +Функтор інструкцій породжує дерево програми. `and_then` — монадичне зв’язування, а `run` — один з інтерпретаторів; другий інтерпретатор (компілятор у байткод) може згорнути те саме дерево. Узагальнений `Free` спеціалізовано для цього набору інструкцій, щоб він компілювався у стабільному Rust. + +```rust +use std::collections::HashMap; + +struct State { stack: Vec, storage: HashMap } + +// The free monad over the EVM instruction set: a program is data — a tree of +// instructions ending in `Pure`, each carrying its continuation. +enum Free { + Pure(A), + Push(u64, Box>), + Add(Box>), + SStore(u64, u64, Box>), + SLoad(u64, Box Free>), +} + +impl Free { + // Monadic bind: graft `k` onto every leaf of the program. + fn and_then(self, k: impl FnOnce(A) -> Free + 'static) -> Free { + match self { + Free::Pure(a) => k(a), + Free::Push(v, next) => Free::Push(v, Box::new(next.and_then(k))), + Free::Add(next) => Free::Add(Box::new(next.and_then(k))), + Free::SStore(x, y, next) => Free::SStore(x, y, Box::new(next.and_then(k))), + Free::SLoad(key, cont) => Free::SLoad(key, Box::new(move |v| cont(v).and_then(k))), + } + } +} + +fn push(v: u64) -> Free<()> { Free::Push(v, Box::new(Free::Pure(()))) } +fn add() -> Free<()> { Free::Add(Box::new(Free::Pure(()))) } +fn sstore(k: u64, v: u64) -> Free<()> { Free::SStore(k, v, Box::new(Free::Pure(()))) } +fn sload(k: u64) -> Free { Free::SLoad(k, Box::new(|v| Free::Pure(v))) } + +// Interpreter: give the program data meaning against the machine state. +fn run(mut prog: Free<()>, st: &mut State) { + loop { + prog = match prog { + Free::Pure(()) => return, + Free::Push(v, next) => { st.stack.push(v); *next } + Free::Add(next) => { + let b = st.stack.pop().unwrap(); + let a = st.stack.pop().unwrap(); + st.stack.push(a + b); + *next + } + Free::SStore(k, v, next) => { st.storage.insert(k, v); *next } + Free::SLoad(k, cont) => { let v = *st.storage.get(&k).unwrap_or(&0); cont(v) } + }; + } +} + +fn main() { + let program = push(2) + .and_then(|_| push(3)) + .and_then(|_| add()) + .and_then(|_| sstore(1, 5)) + .and_then(|_| sload(1)) + .and_then(|v| push(v)); + + let mut st = State { stack: vec![], storage: HashMap::new() }; + run(program, &mut st); + println!("stack: {:?}", st.stack); + println!("storage: {:?}", st.storage); +} +``` + +
+ +
+Стиль передавання продовжень (CPS) — кожен опкод викликає «решту програми» + +Кожен обробник виконує свою роботу, а потім викликає продовження `k`. `sload` передає завантажене значення продовженню, яке на нього очікує. Керування явне й представлене вкладеними продовженнями; структури даних програми взагалі немає. + +```rust +use std::collections::HashMap; + +struct State { stack: Vec, storage: HashMap } + +// Each opcode does its work, then calls the continuation `k` = "the rest of +// the program". `sload` passes the loaded value on to its continuation. +fn push(st: &mut State, v: u64, k: impl FnOnce(&mut State)) { + st.stack.push(v); + k(st); +} +fn add(st: &mut State, k: impl FnOnce(&mut State)) { + let b = st.stack.pop().unwrap(); + let a = st.stack.pop().unwrap(); + st.stack.push(a + b); + k(st); +} +fn sstore(st: &mut State, key: u64, val: u64, k: impl FnOnce(&mut State)) { + st.storage.insert(key, val); + k(st); +} +fn sload(st: &mut State, key: u64, k: impl FnOnce(&mut State, u64)) { + let v = *st.storage.get(&key).unwrap_or(&0); + k(st, v); +} + +fn main() { + let mut st = State { stack: vec![], storage: HashMap::new() }; + + push(&mut st, 2, |st| { + push(st, 3, |st| { + add(st, |st| { + sstore(st, 1, 5, |st| { + sload(st, 1, |st, v| { + push(st, v, |_st| {}); + }); + }); + }); + }); + }); + + println!("stack: {:?}", st.stack); + println!("storage: {:?}", st.storage); +} +``` + +
+ +
+Дефункціоналізований — виклики операцій стають даними, які виконує один apply + +Там, де версії з вільною монадою та CPS *викликають* операції (`push(2)`, `add()`, `sstore(1, 5)`, `sload(1)`) — невелику алгебру, що майже читається як специфікація, — дефункціоналізація перетворює кожен виклик на дані першого порядку. Потім одна функція `apply` інтерпретує ці дані, а продовження також згортаються: «решта програми» стає наступним індексом (`pc`). Це алгебра операцій, записана як дані, з єдиним інтерпретатором `apply`. + +```rust +use std::collections::HashMap; + +struct State { stack: Vec, storage: HashMap } + +// The EVM algebra reified: where the other encodings CALL `push(2)`, `add()`, +// `sstore(1, 5)`, `sload(1)`, each such call becomes a first-order value — a +// tag with its arguments. +enum Op { + Push(u64), + Add, + SStore(u64, u64), + SLoad(u64), +} + +// `apply` is the single interpreter for the reified operations: it gives each +// tag its meaning against the machine state. +fn apply(op: &Op, st: &mut State) { + match op { + Op::Push(v) => st.stack.push(*v), + Op::Add => { + let b = st.stack.pop().unwrap(); + let a = st.stack.pop().unwrap(); + st.stack.push(a + b); + } + Op::SStore(k, v) => { st.storage.insert(*k, *v); } + Op::SLoad(k) => { + let v = *st.storage.get(k).unwrap_or(&0); + st.stack.push(v); + } + } +} + +fn main() { + // The program is now data: a flat list of reified operation calls. + let code = vec![ + Op::Push(2), + Op::Push(3), + Op::Add, + Op::SStore(1, 5), + Op::SLoad(1), + ]; + + // `pc` is the defunctionalized continuation: "the rest of the program" is + // just the next index. + let mut st = State { stack: vec![], storage: HashMap::new() }; + let mut pc = 0; + while pc < code.len() { + apply(&code[pc], &mut st); + pc += 1; + } + + println!("stack: {:?}", st.stack); + println!("storage: {:?}", st.storage); +} +``` + +
+ +## Від продовжень до байткоду {#from-continuations-to-bytecode} + +Ці три кодування показують те саме обчислення на різній відстані від машини: + +* **Вільна монада** алгебраїчно будує програму *як дані*, а потім інтерпретує її. Те саме дерево можуть згорнути різні інтерпретатори: один запускає його, інший форматує, ще інший компілює. +* **CPS** усуває структуру даних і робить керування явним: «виконай цей опкод, а тоді виклич продовження». Завантажене значення передається продовженню, якому воно потрібне. +* **Дефункціоналізація** перетворює *виклики* операцій на дані першого порядку й знову зчитує їх однією функцією `apply`, а продовження згортаються в `pc` над `Vec`. Цикл-драйвер — це трамплін CPS без замикань. + +```admonish note title="Аналогія, а не виведення" +EVM можна аналізувати як абстрактну машину першого порядку, явний лічильник команд якої нагадує дефункціоналізоване представлення керування. Однак сама ця структурна аналогія не доводить, що байткод EVM отримано перетворенням CPS із подальшою дефункціоналізацією. +``` + +## Основне осяяння {#key-insight} + +| Поняття | Світ вільних монад | Реальна EVM | +| --- | --- | --- | +| Тип інструкцій | Перелік опкодів | Фіксовані опкоди EVM | +| Представлення програми | Дерево, побудоване з `Free
` | Лінійний масив байткоду | +| Продовження | Замикання у вузлі інструкції | Лічильник команд (`pc`) | +| Інтерпретатор | Зіставлення програми з шаблоном | Вибір опкоду й зміна стану віртуальної машини | +| Кілька інтерпретаторів | Різні згортання тієї самої програми | Кілька реалізацій клієнта Ethereum | + +## Як це відповідає реальній EVM {#how-this-maps-to-the-real-evm} + +* **Набір інструкцій** (варіанти `Free` або перелік `Op`) відповідає набору опкодів EVM. +* **Програма** (дерево `Free`, вкладені продовження чи `Vec`) — це контракт до й після компіляції. +* **Інтерпретатор** (`run`, обробники CPS чи `apply`) реалізує клієнт на кшталт Geth, Besu чи Nethermind. +* **Стан машини** (`stack`, `storage`) охоплює стек, пам’ять і сховище EVM. +* Справжній байткод EVM є дефункціоналізованою формою: пласким масивом інструкцій з індексом-лічильником команд, точно як наведене вище дефункціоналізоване кодування. diff --git a/src/insights/evm-alg.vi.md b/src/insights/evm-alg.vi.md new file mode 100644 index 0000000..d0f0474 --- /dev/null +++ b/src/insights/evm-alg.vi.md @@ -0,0 +1,268 @@ + + +# Đại số EVM {#evm-algebra} + +```admonish tip title="Liên quan" +Thiết kế theo ngữ nghĩa trong Rust: [Bộ diễn giải và hiệu ứng](../rust-dd/interpreters.md), [Chương trình bậc nhất](../rust-dd/first-order-programs.md), [Quy trình ngôn ngữ và trình biên dịch](../rust-dd/compiler-pipelines.md) +Khái niệm: [Ngữ nghĩa vận hành](../concepts/operational_semantics.md), [Monad tự do](../concepts/free_monad.md), [Phong cách truyền tiếp nối](../concepts/cps.md), [Phi chức năng hóa](../concepts/defunctionalization.md) +``` + +**Máy ảo Ethereum (EVM)** là CPU ảo dựa trên ngăn xếp, thực thi **bytecode Ethereum**, tức dạng đã biên dịch của hợp đồng thông minh viết bằng Solidity, Vyper hoặc ngôn ngữ tương thích EVM khác. + +Ở cấp thấp nhất: + +* EVM xử lý **opcode** (ADD, PUSH, JUMP, SSTORE, v.v.). +* Execution state includes: + * **Ngăn xếp**: ngăn xếp dữ liệu LIFO cho toán hạng. + * **Bộ nhớ**: mảng byte tạm thời cho giá trị trung gian. + * **Lưu trữ**: kho khóa-giá trị bền vững cho từng hợp đồng. + * **Bộ đếm chương trình**: trỏ đến opcode tiếp theo. + * **Gas**: cơ chế đo lường tính phí cho các bước thực thi. + +## EVM như mẫu bộ diễn giải {#evm-as-an-interpreter-pattern} + +Máy khách EVM là bộ diễn giải trên ngôn ngữ lệnh: + +* **Tập lệnh** = các opcode EVM (enum các biến thể). +* **Chương trình** = chuỗi lệnh. +* **Bộ diễn giải** = quy tắc cho cách mỗi opcode thay đổi trạng thái máy. +* **Nhiều bộ diễn giải** = đặc tả EVM cố định, nhưng Geth, Nethermind, Besu và Erigon là các cách triển khai thay thế của cùng bộ diễn giải. + +Đây là mạch xuyên suốt của ba kỹ thuật trong sách — **monad tự do**, **phong cách truyền tiếp nối** và **phi chức năng hóa** — chúng chỉ khác ở cách biểu diễn *phần còn lại của chương trình*. + +## Ba cách mã hóa của một máy {#three-encodings-of-one-machine} + +Mỗi cách mã hóa bên dưới chạy cùng một chương trình cố định: + +```text +push 2; push 3; add; sstore 1 5; load 1 -> v; push v +``` + +và mỗi cách đều tạo ra cùng một quan sát: + +```text +stack: [5, 5] +storage: {1: 5} +``` + +Chúng chỉ khác cách biểu diễn điều khiển — “tiếp theo cần làm gì”. + +
+Monad tự do — chương trình là dữ liệu; bộ diễn giải gán ý nghĩa cho nó + +Functor lệnh sinh ra cây chương trình. `and_then` là bind của monad, còn `run` là một bộ diễn giải — bộ thứ hai (trình biên dịch sang bytecode) có thể gấp cùng cây đó. `Free` tổng quát được chuyên biệt hóa cho tập lệnh này để biên dịch được với Rust ổn định. + +```rust +use std::collections::HashMap; + +struct State { stack: Vec, storage: HashMap } + +// The free monad over the EVM instruction set: a program is data — a tree of +// instructions ending in `Pure`, each carrying its continuation. +enum Free { + Pure(A), + Push(u64, Box>), + Add(Box>), + SStore(u64, u64, Box>), + SLoad(u64, Box Free>), +} + +impl Free { + // Monadic bind: graft `k` onto every leaf of the program. + fn and_then(self, k: impl FnOnce(A) -> Free + 'static) -> Free { + match self { + Free::Pure(a) => k(a), + Free::Push(v, next) => Free::Push(v, Box::new(next.and_then(k))), + Free::Add(next) => Free::Add(Box::new(next.and_then(k))), + Free::SStore(x, y, next) => Free::SStore(x, y, Box::new(next.and_then(k))), + Free::SLoad(key, cont) => Free::SLoad(key, Box::new(move |v| cont(v).and_then(k))), + } + } +} + +fn push(v: u64) -> Free<()> { Free::Push(v, Box::new(Free::Pure(()))) } +fn add() -> Free<()> { Free::Add(Box::new(Free::Pure(()))) } +fn sstore(k: u64, v: u64) -> Free<()> { Free::SStore(k, v, Box::new(Free::Pure(()))) } +fn sload(k: u64) -> Free { Free::SLoad(k, Box::new(|v| Free::Pure(v))) } + +// Interpreter: give the program data meaning against the machine state. +fn run(mut prog: Free<()>, st: &mut State) { + loop { + prog = match prog { + Free::Pure(()) => return, + Free::Push(v, next) => { st.stack.push(v); *next } + Free::Add(next) => { + let b = st.stack.pop().unwrap(); + let a = st.stack.pop().unwrap(); + st.stack.push(a + b); + *next + } + Free::SStore(k, v, next) => { st.storage.insert(k, v); *next } + Free::SLoad(k, cont) => { let v = *st.storage.get(&k).unwrap_or(&0); cont(v) } + }; + } +} + +fn main() { + let program = push(2) + .and_then(|_| push(3)) + .and_then(|_| add()) + .and_then(|_| sstore(1, 5)) + .and_then(|_| sload(1)) + .and_then(|v| push(v)); + + let mut st = State { stack: vec![], storage: HashMap::new() }; + run(program, &mut st); + println!("stack: {:?}", st.stack); + println!("storage: {:?}", st.storage); +} +``` + +
+ +
+Phong cách truyền tiếp nối (CPS) — mỗi opcode gọi “phần còn lại của chương trình” + +Mỗi handler thực hiện công việc rồi gọi tiếp nối `k`. `sload` truyền giá trị được nạp cho tiếp nối đang đợi giá trị đó. Điều khiển tường minh dưới dạng tiếp nối lồng nhau, hoàn toàn không có cấu trúc dữ liệu chương trình. + +```rust +use std::collections::HashMap; + +struct State { stack: Vec, storage: HashMap } + +// Each opcode does its work, then calls the continuation `k` = "the rest of +// the program". `sload` passes the loaded value on to its continuation. +fn push(st: &mut State, v: u64, k: impl FnOnce(&mut State)) { + st.stack.push(v); + k(st); +} +fn add(st: &mut State, k: impl FnOnce(&mut State)) { + let b = st.stack.pop().unwrap(); + let a = st.stack.pop().unwrap(); + st.stack.push(a + b); + k(st); +} +fn sstore(st: &mut State, key: u64, val: u64, k: impl FnOnce(&mut State)) { + st.storage.insert(key, val); + k(st); +} +fn sload(st: &mut State, key: u64, k: impl FnOnce(&mut State, u64)) { + let v = *st.storage.get(&key).unwrap_or(&0); + k(st, v); +} + +fn main() { + let mut st = State { stack: vec![], storage: HashMap::new() }; + + push(&mut st, 2, |st| { + push(st, 3, |st| { + add(st, |st| { + sstore(st, 1, 5, |st| { + sload(st, 1, |st, v| { + push(st, v, |_st| {}); + }); + }); + }); + }); + }); + + println!("stack: {:?}", st.stack); + println!("storage: {:?}", st.storage); +} +``` + +
+ +
+Đã phi chức năng hóa — lời gọi phép toán trở thành dữ liệu do một apply duy nhất chạy + +Trong các phiên bản monad tự do và CPS, các phép toán (`push(2)`, `add()`, `sstore(1, 5)`, `sload(1)`) được *gọi* — một đại số nhỏ gần như đọc được như đặc tả. Phi chức năng hóa tái hóa mỗi lời gọi thành dữ liệu bậc nhất. Sau đó, một hàm `apply` diễn giải dữ liệu đó, đồng thời các tiếp nối cũng sụp lại: “phần còn lại của chương trình” trở thành chỉ mục kế tiếp (`pc`). Hãy đọc đây là đại số phép toán được viết dưới dạng dữ liệu, trong đó `apply` là bộ diễn giải duy nhất. + +```rust +use std::collections::HashMap; + +struct State { stack: Vec, storage: HashMap } + +// The EVM algebra reified: where the other encodings CALL `push(2)`, `add()`, +// `sstore(1, 5)`, `sload(1)`, each such call becomes a first-order value — a +// tag with its arguments. +enum Op { + Push(u64), + Add, + SStore(u64, u64), + SLoad(u64), +} + +// `apply` is the single interpreter for the reified operations: it gives each +// tag its meaning against the machine state. +fn apply(op: &Op, st: &mut State) { + match op { + Op::Push(v) => st.stack.push(*v), + Op::Add => { + let b = st.stack.pop().unwrap(); + let a = st.stack.pop().unwrap(); + st.stack.push(a + b); + } + Op::SStore(k, v) => { st.storage.insert(*k, *v); } + Op::SLoad(k) => { + let v = *st.storage.get(k).unwrap_or(&0); + st.stack.push(v); + } + } +} + +fn main() { + // The program is now data: a flat list of reified operation calls. + let code = vec![ + Op::Push(2), + Op::Push(3), + Op::Add, + Op::SStore(1, 5), + Op::SLoad(1), + ]; + + // `pc` is the defunctionalized continuation: "the rest of the program" is + // just the next index. + let mut st = State { stack: vec![], storage: HashMap::new() }; + let mut pc = 0; + while pc < code.len() { + apply(&code[pc], &mut st); + pc += 1; + } + + println!("stack: {:?}", st.stack); + println!("storage: {:?}", st.storage); +} +``` + +
+ +## Từ tiếp nối đến bytecode {#from-continuations-to-bytecode} + +Ba cách mã hóa là cùng một phép tính được quan sát ở những khoảng cách khác nhau với máy: + +* **Monad tự do** dựng chương trình *bằng đại số* dưới dạng dữ liệu rồi diễn giải nó. Có thể gấp cùng cây đó bằng nhiều bộ diễn giải — một bộ chạy nó, một bộ in định dạng đẹp, một bộ biên dịch nó. +* **CPS** loại bỏ cấu trúc dữ liệu và làm điều khiển tường minh: “thực hiện opcode này, rồi gọi tiếp nối”. Giá trị được nạp chảy đến tiếp nối cần nó. +* **Phi chức năng hóa** chuyển các *lời gọi* phép toán thành dữ liệu bậc nhất, rồi đọc lại chúng bằng một `apply`; các tiếp nối cũng rút gọn thành `pc` trên một `Vec`. Vòng lặp điều khiển là một trampoline CPS không dùng closure. + +```admonish note title="Phép loại suy, không phải phép suy dẫn" +Có thể phân tích EVM như máy trừu tượng bậc nhất với bộ đếm chương trình tường minh giống cách biểu diễn điều khiển đã phi chức năng hóa. Phép loại suy cấu trúc này tự nó không chứng minh bytecode EVM thu được từ phép biến đổi CPS rồi phi chức năng hóa. +``` + +## Nhận định chính {#key-insight} + +| Khái niệm | Mô hình monad tự do | Thực tế EVM | +| --- | --- | --- | +| Kiểu lệnh | Enum opcode | Các opcode EVM cố định | +| Cách biểu diễn chương trình | Cây dựng từ `Free
` | Mảng bytecode tuyến tính | +| Tiếp nối | Closure trong nút lệnh | Bộ đếm chương trình (`pc`) | +| Bộ diễn giải | Đối sánh mẫu trên chương trình | Chuyển nhánh theo opcode, biến đổi trạng thái máy ảo | +| Nhiều bộ diễn giải | Các phép gấp khác nhau trên cùng chương trình | Nhiều cách triển khai máy khách Ethereum | + +## Ánh xạ này vào EVM thực tế {#how-this-maps-to-the-real-evm} + +* **Tập lệnh** (các biến thể của `Free` hoặc enum `Op`) phản chiếu tập opcode EVM. +* **Chương trình** (cây `Free`, tiếp nối lồng nhau hoặc `Vec`) là hợp đồng trước và sau khi biên dịch. +* **Bộ diễn giải** (`run`, các handler CPS hoặc `apply`) là thứ mà máy khách như Geth, Besu hoặc Nethermind triển khai. +* **Trạng thái máy** (`stack`, `storage`) là ngăn xếp, bộ nhớ và vùng lưu trữ của EVM. +* Bytecode EVM thực tế là dạng đã phi chức năng hóa: mảng lệnh phẳng được đánh chỉ mục bằng bộ đếm chương trình, đúng bằng cách mã hóa đã phi chức năng hóa ở trên. diff --git a/src/insights/evm-alg.zh-hant.md b/src/insights/evm-alg.zh-hant.md new file mode 100644 index 0000000..91309a0 --- /dev/null +++ b/src/insights/evm-alg.zh-hant.md @@ -0,0 +1,268 @@ + + +# EVM 代數 {#evm-algebra} + +```admonish tip title="相關內容" +Rust 中的語義驅動設計:[直譯器與效應](../rust-dd/interpreters.md)、[一階程式](../rust-dd/first-order-programs.md)、[語言與編譯器流水線](../rust-dd/compiler-pipelines.md) +概念:[操作語義](../concepts/operational_semantics.md)、[自由單子](../concepts/free_monad.md)、[延續傳遞風格](../concepts/cps.md)、[去函式化](../concepts/defunctionalization.md) +``` + +以太坊虛擬機器(EVM)是一種基於棧的虛擬 CPU,用於執行**以太坊位元組碼**,後者是以 Solidity、Vyper 或其他相容 EVM 的語言編寫的智慧合約編譯後的形式。 + +在最低層: + +* EVM 會處理**操作碼**(ADD、PUSH、JUMP、SSTORE 等)。 +* Execution state includes: + * **棧**:後進先出的運算元資料棧。 + * **記憶體**:用於臨時值的瞬態位元組陣列。 + * **儲存**:每份合約對應的持久鍵值儲存。 + * **程式計數器**:指向下一條操作碼。 + * **Gas**:對執行步驟計量並收費。 + +## 作為直譯器模式的 EVM {#evm-as-an-interpreter-pattern} + +EVM 客戶端是對一門指令語言的直譯器: + +* **指令集** = EVM 操作碼(由多個變體組成的列舉)。 +* **程式** = 一系列指令。 +* **直譯器** = 每種操作碼如何改變機器狀態的規則。 +* **多個直譯器** = EVM 規範固定,但 Geth、Nethermind、Besu 與 Erigon 是同一直譯器的不同實作。 + +本書中的三種技術——**自由單子**、**延續傳遞風格**與**去函式化**——貫穿同一條主線;它們只在如何表示*程式剩餘部分*上有所不同。 + +## 一臺機器的三種編碼 {#three-encodings-of-one-machine} + +以下每種編碼都執行同一個固定程式: + +```text +push 2; push 3; add; sstore 1 5; load 1 -> v; push v +``` + +而且每種編碼都會產生相同的觀察結果: + +```text +stack: [5, 5] +storage: {1: 5} +``` + +它們的區別僅在於如何表示控制流——“接下來要做什麼”。 + +
+自由單子——程式是資料;直譯器賦予它含義 + +指令函子會生成程式樹。`and_then`是單子 bind,`run`是一種直譯器——另一個直譯器(編譯為位元組碼)也可以摺疊同一棵樹。泛型`Free`針對這套指令集專門化,因此可以在穩定版 Rust 中編譯。 + +```rust +use std::collections::HashMap; + +struct State { stack: Vec, storage: HashMap } + +// The free monad over the EVM instruction set: a program is data — a tree of +// instructions ending in `Pure`, each carrying its continuation. +enum Free { + Pure(A), + Push(u64, Box>), + Add(Box>), + SStore(u64, u64, Box>), + SLoad(u64, Box Free>), +} + +impl Free { + // Monadic bind: graft `k` onto every leaf of the program. + fn and_then(self, k: impl FnOnce(A) -> Free + 'static) -> Free { + match self { + Free::Pure(a) => k(a), + Free::Push(v, next) => Free::Push(v, Box::new(next.and_then(k))), + Free::Add(next) => Free::Add(Box::new(next.and_then(k))), + Free::SStore(x, y, next) => Free::SStore(x, y, Box::new(next.and_then(k))), + Free::SLoad(key, cont) => Free::SLoad(key, Box::new(move |v| cont(v).and_then(k))), + } + } +} + +fn push(v: u64) -> Free<()> { Free::Push(v, Box::new(Free::Pure(()))) } +fn add() -> Free<()> { Free::Add(Box::new(Free::Pure(()))) } +fn sstore(k: u64, v: u64) -> Free<()> { Free::SStore(k, v, Box::new(Free::Pure(()))) } +fn sload(k: u64) -> Free { Free::SLoad(k, Box::new(|v| Free::Pure(v))) } + +// Interpreter: give the program data meaning against the machine state. +fn run(mut prog: Free<()>, st: &mut State) { + loop { + prog = match prog { + Free::Pure(()) => return, + Free::Push(v, next) => { st.stack.push(v); *next } + Free::Add(next) => { + let b = st.stack.pop().unwrap(); + let a = st.stack.pop().unwrap(); + st.stack.push(a + b); + *next + } + Free::SStore(k, v, next) => { st.storage.insert(k, v); *next } + Free::SLoad(k, cont) => { let v = *st.storage.get(&k).unwrap_or(&0); cont(v) } + }; + } +} + +fn main() { + let program = push(2) + .and_then(|_| push(3)) + .and_then(|_| add()) + .and_then(|_| sstore(1, 5)) + .and_then(|_| sload(1)) + .and_then(|v| push(v)); + + let mut st = State { stack: vec![], storage: HashMap::new() }; + run(program, &mut st); + println!("stack: {:?}", st.stack); + println!("storage: {:?}", st.storage); +} +``` + +
+ +
+延續傳遞風格(CPS)——每個操作碼都會呼叫“程式剩餘部分” + +每個處理器完成工作後都會呼叫延續`k`。`sload`會將載入的值傳遞給一個需要該值的延續。控制流以巢狀延續的形式顯式表達,完全沒有程式資料結構。 + +```rust +use std::collections::HashMap; + +struct State { stack: Vec, storage: HashMap } + +// Each opcode does its work, then calls the continuation `k` = "the rest of +// the program". `sload` passes the loaded value on to its continuation. +fn push(st: &mut State, v: u64, k: impl FnOnce(&mut State)) { + st.stack.push(v); + k(st); +} +fn add(st: &mut State, k: impl FnOnce(&mut State)) { + let b = st.stack.pop().unwrap(); + let a = st.stack.pop().unwrap(); + st.stack.push(a + b); + k(st); +} +fn sstore(st: &mut State, key: u64, val: u64, k: impl FnOnce(&mut State)) { + st.storage.insert(key, val); + k(st); +} +fn sload(st: &mut State, key: u64, k: impl FnOnce(&mut State, u64)) { + let v = *st.storage.get(&key).unwrap_or(&0); + k(st, v); +} + +fn main() { + let mut st = State { stack: vec![], storage: HashMap::new() }; + + push(&mut st, 2, |st| { + push(st, 3, |st| { + add(st, |st| { + sstore(st, 1, 5, |st| { + sload(st, 1, |st, v| { + push(st, v, |_st| {}); + }); + }); + }); + }); + }); + + println!("stack: {:?}", st.stack); + println!("storage: {:?}", st.storage); +} +``` + +
+ +
+去函式化——操作呼叫變成由一個apply執行的資料 + +自由單子與 CPS 版本會*呼叫*操作(`push(2)`、`add()`、`sstore(1, 5)`、`sload(1)`)——這是一種幾乎可直接讀作規範說明的小型代數;去函式化則將每次呼叫具體化為一階資料。接著由一個`apply`函式解釋這些資料,延續也會隨之摺疊:「程式剩餘部分」變成下一個索引(`pc`)。可以把它看作以資料形式書寫的操作代數,並由`apply`這個單一直譯器解釋。 + +```rust +use std::collections::HashMap; + +struct State { stack: Vec, storage: HashMap } + +// The EVM algebra reified: where the other encodings CALL `push(2)`, `add()`, +// `sstore(1, 5)`, `sload(1)`, each such call becomes a first-order value — a +// tag with its arguments. +enum Op { + Push(u64), + Add, + SStore(u64, u64), + SLoad(u64), +} + +// `apply` is the single interpreter for the reified operations: it gives each +// tag its meaning against the machine state. +fn apply(op: &Op, st: &mut State) { + match op { + Op::Push(v) => st.stack.push(*v), + Op::Add => { + let b = st.stack.pop().unwrap(); + let a = st.stack.pop().unwrap(); + st.stack.push(a + b); + } + Op::SStore(k, v) => { st.storage.insert(*k, *v); } + Op::SLoad(k) => { + let v = *st.storage.get(k).unwrap_or(&0); + st.stack.push(v); + } + } +} + +fn main() { + // The program is now data: a flat list of reified operation calls. + let code = vec![ + Op::Push(2), + Op::Push(3), + Op::Add, + Op::SStore(1, 5), + Op::SLoad(1), + ]; + + // `pc` is the defunctionalized continuation: "the rest of the program" is + // just the next index. + let mut st = State { stack: vec![], storage: HashMap::new() }; + let mut pc = 0; + while pc < code.len() { + apply(&code[pc], &mut st); + pc += 1; + } + + println!("stack: {:?}", st.stack); + println!("storage: {:?}", st.storage); +} +``` + +
+ +## 從延續到位元組碼 {#from-continuations-to-bytecode} + +以下三種編碼呈現的是同一計算,只是各自與機器的距離不同: + +* **自由單子**先以*代數方式*將程式構造為資料,再對其作出解釋。同一棵樹可以由多個直譯器摺疊:一個執行它,一個漂亮列印它,一個編譯它。 +* **CPS**會移除資料結構並顯式表示控制流:“執行此操作碼,然後呼叫延續。”載入的值會流向需要它的延續。 +* **去函式化**會將操作的*呼叫*轉換為一階資料,並由一個`apply`函式解釋這些資料;延續則摺疊為一個`pc`,其操作對象是`Vec`。驅動迴圈就是一個不使用閉包的 CPS 蹦床。 + +```admonish note title="類比,而非推導" +EVM 可以分析為一階抽象機,其顯式程式計數器類似於去函式化的控制表示。但這種結構類比本身無法證明 EVM 位元組碼是經 CPS 變換再去函式化得到的。 +``` + +## 關鍵洞見 {#key-insight} + +| 概念 | 自由單子世界 | EVM 實際情況 | +| --- | --- | --- | +| 指令型別 | 操作碼列舉 | 固定的 EVM 操作碼 | +| 程式表示 | 由`Free
`構造的樹 | 線性位元組碼陣列 | +| 延續 | 指令節點中的閉包 | 程式計數器(`pc`) | +| 直譯器 | 對程式進行模式匹配 | 按操作碼切換分支,並修改虛擬機器狀態 | +| 多種直譯器 | 對同一程式進行不同摺疊 | 多個以太坊客戶端實作 | + +## 與真實 EVM 的對應 {#how-this-maps-to-the-real-evm} + +* **指令集**(`Free`的變體,或`Op`列舉)對應 EVM 操作碼集合。 +* **程式**(`Free`樹、巢狀延續或`Vec`)表示編譯前後的合約。 +* **直譯器**(`run`、CPS 處理器或`apply`)是 Geth、Besu 或 Nethermind 等客戶端所實作的部分。 +* **機器狀態**(`stack`、`storage`)是 EVM 的棧、記憶體與儲存。 +* 真實的 EVM 位元組碼是去函式化後的形式:由程式計數器索引的扁平指令陣列,恰如上文展示的去函式化編碼。 diff --git a/src/insights/evm-alg.zh.md b/src/insights/evm-alg.zh.md new file mode 100644 index 0000000..39498d3 --- /dev/null +++ b/src/insights/evm-alg.zh.md @@ -0,0 +1,268 @@ + + +# EVM 代数 {#evm-algebra} + +```admonish tip title="相关内容" +Rust 中的语义驱动设计:[解释器与效应](../rust-dd/interpreters.md)、[一阶程序](../rust-dd/first-order-programs.md)、[语言与编译器流水线](../rust-dd/compiler-pipelines.md) +概念:[操作语义](../concepts/operational_semantics.md)、[自由单子](../concepts/free_monad.md)、[延续传递风格](../concepts/cps.md)、[去函数化](../concepts/defunctionalization.md) +``` + +以太坊虚拟机(EVM)是一种基于栈的虚拟 CPU,用于执行**以太坊字节码**,后者是以 Solidity、Vyper 或其他兼容 EVM 的语言编写的智能合约编译后的形式。 + +在最低层: + +* EVM 会处理**操作码**(ADD、PUSH、JUMP、SSTORE 等)。 +* Execution state includes: + * **栈**:后进先出的操作数数据栈。 + * **内存**:用于临时值的瞬态字节数组。 + * **存储**:每份合约对应的持久键值存储。 + * **程序计数器**:指向下一条操作码。 + * **Gas**:对执行步骤计量并收费。 + +## 作为解释器模式的 EVM {#evm-as-an-interpreter-pattern} + +EVM 客户端是对一门指令语言的解释器: + +* **指令集** = EVM 操作码(由多个变体组成的枚举)。 +* **程序** = 一系列指令。 +* **解释器** = 每种操作码如何改变机器状态的规则。 +* **多个解释器** = EVM 规范固定,但 Geth、Nethermind、Besu 与 Erigon 是同一解释器的不同实现。 + +本书中的三种技术——**自由单子**、**延续传递风格**与**去函数化**——贯穿同一条主线;它们只在如何表示*程序剩余部分*上有所不同。 + +## 一台机器的三种编码 {#three-encodings-of-one-machine} + +以下每种编码都运行同一个固定程序: + +```text +push 2; push 3; add; sstore 1 5; load 1 -> v; push v +``` + +而且每种编码都会产生相同的观察结果: + +```text +stack: [5, 5] +storage: {1: 5} +``` + +它们的区别仅在于如何表示控制流——“接下来要做什么”。 + +
+自由单子——程序是数据;解释器赋予它含义 + +指令函子会生成程序树。`and_then`是单子 bind,`run`是一种解释器——另一个解释器(编译为字节码)也可以折叠同一棵树。泛型`Free`针对这套指令集专门化,因此可以在稳定版 Rust 中编译。 + +```rust +use std::collections::HashMap; + +struct State { stack: Vec, storage: HashMap } + +// The free monad over the EVM instruction set: a program is data — a tree of +// instructions ending in `Pure`, each carrying its continuation. +enum Free { + Pure(A), + Push(u64, Box>), + Add(Box>), + SStore(u64, u64, Box>), + SLoad(u64, Box Free>), +} + +impl Free { + // Monadic bind: graft `k` onto every leaf of the program. + fn and_then(self, k: impl FnOnce(A) -> Free + 'static) -> Free { + match self { + Free::Pure(a) => k(a), + Free::Push(v, next) => Free::Push(v, Box::new(next.and_then(k))), + Free::Add(next) => Free::Add(Box::new(next.and_then(k))), + Free::SStore(x, y, next) => Free::SStore(x, y, Box::new(next.and_then(k))), + Free::SLoad(key, cont) => Free::SLoad(key, Box::new(move |v| cont(v).and_then(k))), + } + } +} + +fn push(v: u64) -> Free<()> { Free::Push(v, Box::new(Free::Pure(()))) } +fn add() -> Free<()> { Free::Add(Box::new(Free::Pure(()))) } +fn sstore(k: u64, v: u64) -> Free<()> { Free::SStore(k, v, Box::new(Free::Pure(()))) } +fn sload(k: u64) -> Free { Free::SLoad(k, Box::new(|v| Free::Pure(v))) } + +// Interpreter: give the program data meaning against the machine state. +fn run(mut prog: Free<()>, st: &mut State) { + loop { + prog = match prog { + Free::Pure(()) => return, + Free::Push(v, next) => { st.stack.push(v); *next } + Free::Add(next) => { + let b = st.stack.pop().unwrap(); + let a = st.stack.pop().unwrap(); + st.stack.push(a + b); + *next + } + Free::SStore(k, v, next) => { st.storage.insert(k, v); *next } + Free::SLoad(k, cont) => { let v = *st.storage.get(&k).unwrap_or(&0); cont(v) } + }; + } +} + +fn main() { + let program = push(2) + .and_then(|_| push(3)) + .and_then(|_| add()) + .and_then(|_| sstore(1, 5)) + .and_then(|_| sload(1)) + .and_then(|v| push(v)); + + let mut st = State { stack: vec![], storage: HashMap::new() }; + run(program, &mut st); + println!("stack: {:?}", st.stack); + println!("storage: {:?}", st.storage); +} +``` + +
+ +
+延续传递风格(CPS)——每个操作码都会调用“程序剩余部分” + +每个处理器完成工作后都会调用延续`k`。`sload`会将加载的值传递给一个需要该值的延续。控制流以嵌套延续的形式显式表达,完全没有程序数据结构。 + +```rust +use std::collections::HashMap; + +struct State { stack: Vec, storage: HashMap } + +// Each opcode does its work, then calls the continuation `k` = "the rest of +// the program". `sload` passes the loaded value on to its continuation. +fn push(st: &mut State, v: u64, k: impl FnOnce(&mut State)) { + st.stack.push(v); + k(st); +} +fn add(st: &mut State, k: impl FnOnce(&mut State)) { + let b = st.stack.pop().unwrap(); + let a = st.stack.pop().unwrap(); + st.stack.push(a + b); + k(st); +} +fn sstore(st: &mut State, key: u64, val: u64, k: impl FnOnce(&mut State)) { + st.storage.insert(key, val); + k(st); +} +fn sload(st: &mut State, key: u64, k: impl FnOnce(&mut State, u64)) { + let v = *st.storage.get(&key).unwrap_or(&0); + k(st, v); +} + +fn main() { + let mut st = State { stack: vec![], storage: HashMap::new() }; + + push(&mut st, 2, |st| { + push(st, 3, |st| { + add(st, |st| { + sstore(st, 1, 5, |st| { + sload(st, 1, |st, v| { + push(st, v, |_st| {}); + }); + }); + }); + }); + }); + + println!("stack: {:?}", st.stack); + println!("storage: {:?}", st.storage); +} +``` + +
+ +
+去函数化——操作调用变成由一个apply执行的数据 + +自由单子与 CPS 版本会*调用*操作(`push(2)`、`add()`、`sstore(1, 5)`、`sload(1)`)——这是一种几乎可直接读作规范说明的小型代数;去函数化则将每次调用具体化为一阶数据。随后由一个`apply`函数解释这些数据,延续也会随之折叠:“程序剩余部分”变成下一个索引(`pc`)。可以把它看作以数据形式书写的操作代数,并由`apply`这个单一解释器解释。 + +```rust +use std::collections::HashMap; + +struct State { stack: Vec, storage: HashMap } + +// The EVM algebra reified: where the other encodings CALL `push(2)`, `add()`, +// `sstore(1, 5)`, `sload(1)`, each such call becomes a first-order value — a +// tag with its arguments. +enum Op { + Push(u64), + Add, + SStore(u64, u64), + SLoad(u64), +} + +// `apply` is the single interpreter for the reified operations: it gives each +// tag its meaning against the machine state. +fn apply(op: &Op, st: &mut State) { + match op { + Op::Push(v) => st.stack.push(*v), + Op::Add => { + let b = st.stack.pop().unwrap(); + let a = st.stack.pop().unwrap(); + st.stack.push(a + b); + } + Op::SStore(k, v) => { st.storage.insert(*k, *v); } + Op::SLoad(k) => { + let v = *st.storage.get(k).unwrap_or(&0); + st.stack.push(v); + } + } +} + +fn main() { + // The program is now data: a flat list of reified operation calls. + let code = vec![ + Op::Push(2), + Op::Push(3), + Op::Add, + Op::SStore(1, 5), + Op::SLoad(1), + ]; + + // `pc` is the defunctionalized continuation: "the rest of the program" is + // just the next index. + let mut st = State { stack: vec![], storage: HashMap::new() }; + let mut pc = 0; + while pc < code.len() { + apply(&code[pc], &mut st); + pc += 1; + } + + println!("stack: {:?}", st.stack); + println!("storage: {:?}", st.storage); +} +``` + +
+ +## 从延续到字节码 {#from-continuations-to-bytecode} + +以下三种编码是同一计算在距机器远近不同的视角下呈现的形式: + +* **自由单子**先以*代数方式*将程序构造为数据,再对其作出解释。同一棵树可以由多个解释器折叠:一个运行它,一个漂亮打印它,一个编译它。 +* **CPS**会移除数据结构并显式表示控制流:“执行此操作码,然后调用延续。”加载的值会流向需要它的延续。 +* **去函数化**会将操作的*调用*转换为一阶数据,并由一个`apply`函数解释这些数据;延续则折叠为一个`pc`,其操作对象是`Vec`。驱动循环就是一个不使用闭包的 CPS 蹦床。 + +```admonish note title="类比,而非推导" +EVM 可以分析为一阶抽象机,其显式程序计数器类似于去函数化的控制表示。但这种结构类比本身无法证明 EVM 字节码是经 CPS 变换再去函数化得到的。 +``` + +## 关键洞见 {#key-insight} + +| 概念 | 自由单子世界 | EVM 实际情况 | +| --- | --- | --- | +| 指令类型 | 操作码枚举 | 固定的 EVM 操作码 | +| 程序表示 | 由`Free
`构造的树 | 线性字节码数组 | +| 延续 | 指令节点中的闭包 | 程序计数器(`pc`) | +| 解释器 | 对程序进行模式匹配 | 按操作码切换分支,并修改虚拟机状态 | +| 多种解释器 | 对同一程序进行不同折叠 | 多个以太坊客户端实现 | + +## 与真实 EVM 的对应 {#how-this-maps-to-the-real-evm} + +* **指令集**(`Free`的变体,或`Op`枚举)对应 EVM 操作码集合。 +* **程序**(`Free`树、嵌套延续或`Vec`)表示编译前后的合约。 +* **解释器**(`run`、CPS 处理器或`apply`)是 Geth、Besu 或 Nethermind 等客户端所实现的部分。 +* **机器状态**(`stack`、`storage`)是 EVM 的栈、内存与存储。 +* 真实的 EVM 字节码是去函数化后的形式:由程序计数器索引的扁平指令数组,恰如上文展示的去函数化编码。 diff --git a/src/insights/expression-problem.ar.md b/src/insights/expression-problem.ar.md new file mode 100644 index 0000000..c3b6e9f --- /dev/null +++ b/src/insights/expression-problem.ar.md @@ -0,0 +1,226 @@ + + +# إعادة طرح مسألة التعبير {#expression-problem-reloaded} + +```admonish tip title="ذات صلة" +الرؤية الدلالية: [التصميم الدلالي](../denotational-design/design.md) +التصميم انطلاقًا من المعنى في Rust: [جبريات القدرات](../rust-dd/capability-algebras.md)، [المعنى المشتق والتركيب](../rust-dd/derived-meaning.md)، [المفسرات والآثار](../rust-dd/interpreters.md) +المفاهيم: [مسألة التعبير](../concepts/expression-problem.md) +``` + +تعرض هذه الصفحة حلًا عمليًا لمسألة التعبير قائمًا على السمات: كيفية إضافة صيغ تعبير وعمليات جديدة من دون إعادة كتابة الشيفرة القائمة مرارًا. التصميم **على نمط كونال** في فكرته، وترميزه **من نمط tagless-final/جبريات الكائنات**. عمليًا: نحدد المعنى التركيبي أولًا (واجهات قدرات صغيرة ومواصفات برامج على مستوى الامتدادات)، ثم نوفر مفسرات ملموسة. وينتمي الترميز الملموس إلى عائلة أسلوب **tagless-final** لدى أوليغ كيسليوف و**جبريات الكائنات**: تحدد واجهات المُنشئات (`LitAlg`، `AddAlg`، `MulAlg`) توقيع اللغة، وتكتب البرامج بصورة متعددة الأشكال اعتمادًا على تلك الواجهات، وتوفر التطبيقات الملموسة (مثل `Eval` أو `Pretty`) التفسيرات. وهذا يتجنب الالتزام بشجرة AST مغلقة واحدة مع الحفاظ على الأنواع الساكنة وقابلية التوسيع في البعدين. وتقدم هذه الصفحة حلًا عمليًا لـ *مسألة التعبير*. + +نهج أوليغ دلالي صراحة: يسند المعنى التركيبي أولًا، ثم يحقق الآثار والمفسرات كطبقات دلالية معيارية. وفي مسألة التعبير، لهذا يكون التوافق مع التصميم الدلالي متوقعًا لا عرضيًا. فصياغة كونال للتصميم الدلالي تقرر الأولوية نفسها مباشرة: حدد المعنى تركيبيًا أولًا، وتعامل مع استراتيجيات التنفيذ الملموسة بوصفها ثانوية وقابلة للاستبدال. + +في مثال لغة التعبير، يعني هذا الترميز ما يلي: + +* **تُمثّل مفردات المُنشئات** بسمات جبرية صغيرة ومستقلة. +* **التفسيرات** هي تطبيقات لتلك السمات. +* تضيف الصياغة الجديدة سمة جديدة وتترك الشيفرة القديمة دون تغيير. +* تضيف الدلالات الجديدة نوع مفسر جديدًا وتترك الشيفرة القديمة دون تغيير. + +`lit` و`add` عمليتان دلاليتان وليستا مُنشئين لشجرة AST مميزة. فشجرة AST تفسير واحد ضمن عدة تفسيرات. + +```admonish example title="جبريات الكائنات في C#" +هذا الترميز ليس خاصًا بـ Rust. تطور [`object-algebras`](https://github.com/tgrospic/object-algebras) النمط في C# وتتجاوز الحامل الثابت المستخدم هنا. في هذه الصفحة يختار كل مفسر `Self::Expr` ملموسًا واحدًا، أي نوعًا عاديًا. أما جبريات C# فتجردها على نوع *منشئ* `F` — `FunctorAlg`، `MonadAlg`، `BankingDsl` — يحمل النتائج على هيئة `App` بدلًا من `F` غير القانوني. + +لا تتضمن C# أنواعًا من الرتبة الأعلى من الدرجة الأولى، لذا يقوم `App` مقام التطبيق `F(a)`، الذي تستعيده أغلفة الحقن/الإسقاط. وهذه `App`حيلة [هي بالضبط إزالة الدوال](../concepts/defunctionalization.md): يتحول التجريد الذي لا تستطيع اللغة التعبير عنه إلى بيانات من الرتبة الأولى تُطبّق عند الطلب. وتواجه Rust الحد نفسه؛ إذ تفتقر هي أيضًا إلى أنواع من الرتبة الأعلى من الدرجة الأولى. +``` + +## حدد قدرات صياغة صغيرة {#specify-tiny-syntax-capabilities} + +يصبح كل مُنشئ سمة صغيرة. وهذا هو **المواصفة**. + +```rust,noplayground +trait LitAlg { + type Expr; + + fn lit(&self, n: i64) -> Self::Expr; +} + +trait AddAlg { + type Expr; + + fn add(&self, a: Self::Expr, b: Self::Expr) -> Self::Expr; +} +``` + +تكتب البرامج بوصفها **امتدادات** فوق السمات الجبرية؛ وهذه الامتدادات جزء من المواصفة أيضًا، وتجمع المواصفات الصغيرة في مواصفات برامج قابلة لإعادة الاستخدام: + +```rust,noplayground +#[ext(name = ExprPrograms)] +impl This +where + This: LitAlg + AddAlg, +{ + fn expr_basic(&self) -> This::Expr { + self.add(self.lit(2), self.lit(3)) + } +} +``` + +`#[ext(...)]` ماكرو من الحزمة [`extend`، وتقلل الشيفرة النمطية بإنشاء أساليب الامتداد من كتلة `impl`؛ وليست ميزة جديدة في لغة Rust.](https://docs.rs/extend/latest/extend/) + +## أضف تفسيرًا جديدًا {#add-new-interpretation} + +تنفذ المفسرات المواصفة. ولا حاجة إلى تغيير الصياغة. + +```rust,noplayground +struct Eval; + +impl LitAlg for Eval { + type Expr = i64; + + fn lit(&self, n: i64) -> i64 { n } +} + +impl AddAlg for Eval { + type Expr = i64; + + fn add(&self, a: i64, b: i64) -> i64 { a + b } +} + +struct Pretty; + +impl LitAlg for Pretty { + type Expr = String; + + fn lit(&self, n: i64) -> String { n.to_string() } +} + +impl AddAlg for Pretty { + type Expr = String; + + fn add(&self, a: String, b: String) -> String { + format!("({a} + {b})") + } +} +``` + +يمكن الآن تفسير التعبير نفسه بطرق مختلفة: + +```rust,noplayground +let eval = Eval; +let pretty = Pretty; + +let v: i64 = eval.expr_basic(); // 5 +let s: String = pretty.expr_basic(); // "(2 + 3)" +``` + +## أضف صياغة جديدة (سمة قدرة جديدة) {#add-new-syntax-new-capability-trait} + +لإضافة `Mul`، عرّف سمة جديدة. وتبقى الشيفرة القائمة دون تغيير. + +```rust,noplayground +trait MulAlg { + type Expr; + + fn mul(&self, a: Self::Expr, b: Self::Expr) -> Self::Expr; +} + +#[ext(name = ExprProgramsMul)] +impl This +where + This: LitAlg + AddAlg + MulAlg, +{ + fn expr_with_mul(&self) -> This::Expr { + self.mul(self.add(self.lit(2), self.lit(3)), self.lit(4)) + } +} +``` + +تظل المفسرات القائمة صالحة للتعبيرات القديمة. +وإذا أرادت دعم الصياغة الجديدة، فلتنفذ السمة الجديدة: + +```rust,noplayground +impl MulAlg for Eval { + type Expr = i64; + + fn mul(&self, a: i64, b: i64) -> i64 { a * b } +} + +impl MulAlg for Pretty { + type Expr = String; + + fn mul(&self, a: String, b: String) -> String { + format!("({a} * {b})") + } +} +``` + +## لماذا يحل هذا مسألة التعبير {#why-this-solves-the-expression-problem} + +لمسألة التعبير التقليدية محوران على تمثيل: + +* إضافة صيغ جديدة (حالات) +* إضافة عمليات جديدة + +يعيد التصميم الدلالي صياغة المحورين: + +* **وسّع المفردات الدلالية**: عرّف سمة قدرة جديدة (`MulAlg`). +* **أضف تفسيرًا جديدًا** لهذه المفردات: عرّف نوع مفسر جديدًا (`Eval` أو `Pretty` أو منشئ شجرة AST أو مولد شيفرة). + +يركب المحوران بصورة مستقلة: + +* لا تتغير البرامج القائمة ما لم تتطلب القدرة الجديدة. يظل `expr_basic` يطلب `LitAlg + AddAlg` فقط. +* لا تتغير المفسرات القائمة ما لم تختر تفسير القدرة الجديدة. ويستمر `Eval` بلا `impl MulAlg` في تشغيل كل برنامج لا يستخدم `mul`. + +لا يلغي هذا مصفوفة التنفيذ. فإذا كان ينبغي لـ `Eval` و`Pretty` تفسير `mul`، احتاج كلاهما إلى `impl MulAlg`. لكن تنظيم المصفوفة يتغير: كل خلية *عملية دلالية × تفسير*، ولا تتمحور أي خلية حول تمثيل مميز، ولا يعتمد كل برنامج إلا على القدرات التي يستخدمها. + +## القوانين جزء من المواصفة {#laws-belong-to-the-specification} + +يتكوّن الجبر الدلالي من حامل وعمليات وقوانين. يختار التفسير الحامل (`type Expr`)، بينما تنتمي العمليات والقوانين إلى المواصفة. مثلًا، تحدد دلالة حسابية لـ `LitAlg + AddAlg` ما يلي: + +```text +add(lit(m), lit(n)) = lit(m + n) +``` + +تحقق `Eval` هذا القانون، ولا تحققه `Pretty`: فـ `"(2 + 3)"` ليست `"5"`. وكلاهما مفسر صالح لتوقيع الصياغة، لكن `Eval` وحده نموذج للمواصفة الحسابية. يُذكر القانون مرة واحدة مقابل السمات، وهو الذي يحدد المفسرات المؤهلة. لا يملكه أي مفسر. + +## الرؤية الختامية: Featherweight Go في مقابل التصميم الدلالي {#final-insight-featherweight-go-vs-denotational-design} + +شخّص وادلر مسألة التعبير على مستوى آليات اللغة: الصفوف في مقابل الأعمدة في ظل الأنواع الساكنة والتوسعة المعيارية. ويقدم [Featherweight Go](../concepts/expression-problem.md#featherweight-go-solution-2020) حلًا ملموسًا: يبقي `Plus(type a Any)` التمثيل التكراري عامًا، ويقيّد كل عملية `a` باستقلال (`Plus(type a Evaler)` لـ `Eval` و`Plus(type a Stringer)` لـ `String`). ولا يرتبط التمثيل بواجهة تعبير مغلقة واحدة، لذا يظل المحوران مفتوحين. + +تبدأ الحلول التقليدية بالتمثيل وتسأل كيف تبقي محوري التوسعة مفتوحين. ويتقدم Featherweight Go بعيدًا على نحو لافت بجعل التمثيل التكراري عامًا وقابلًا للتوسيع البنيوي. أما التصميم الدلالي فينقل الحد خطوة إلى الخلف: التمثيل ليس النموذج. النموذج هو الجبر وقوانينه؛ والتمثيل أحد التفسيرات الممكنة. + +**يجعل Featherweight Go التمثيل قابلًا للتوسيع، ويجعل التصميم الدلالي التمثيل اختياريًا.** + +| | Featherweight Go | التصميم الدلالي | +| --- | --- | --- | +| المركز الدلالي | تمثيل قابل للتوسيع | الجبر والقوانين | +| `Num`/`Plus`, `lit`/`add` | البنى (صيغ التمثيل) | العمليات الدلالية | +| `Eval`, `String`/`Pretty` | الأساليب والواجهات | التفسيرات | +| البنية التكرارية | تمثيل عام ومفتوح (`Plus(a)`) | غير مطلوب | +| الحامل | نوع التعبير المُمثَّل | يختاره المفسر (`type Expr`) | +| شجرة AST | يبقى التمثيل محوريًا | اختياري، تفسير واحد من بين تفسيرات كثيرة | +| خلية المصفوفة | حالة × عملية → أسلوب | عملية دلالية × تفسير → `impl` | +| سلوك جديد | إضافة أساليب وواجهات | إضافة القدرات أو تركيبها | +| تنفيذ جديد | تجسيدات بنيوية جديدة | مفسر جديد | + +يسأل وادلر كيف يمكن توسيع المحورين في تمثيل. أما التصميم الدلالي فيسأل لماذا ينبغي للتمثيل أن يملك أيًا من المحورين. + +حدد المعنى التركيبي أولًا ثم اختر الترميزات. تصبح مسألة التعبير خيارًا هندسيًا بين الترميزات، لا مأزقًا مفاهيميًا. + +**ينبغي أن يكون معنى اللغة مستقلًا عن فكرة الآلة.** + +
ينبغي أن يكون معنى اللغة مستقلًا عن الآلة
+ +## المراجع {#references} + +* إليوت، C. *Denotational design with type class morphisms*. + [http://conal.net/papers/type-class-morphisms/](http://conal.net/papers/type-class-morphisms/) + +* إليوت، C. *Compiling to categories*. + [http://conal.net/papers/compiling-to-categories/](http://conal.net/papers/compiling-to-categories/) + +* كيسليوف، O. *Tagless-final style* (عرض ودروس وأوراق بحثية عن الترميزات النهائية والمفسرات ذات الأنواع القابلة للتوسيع). + [https://okmij.org/ftp/tagless-final/](https://okmij.org/ftp/tagless-final/) + +* كيسليوف، O. *Having an Effect* (عرض تعريفي/دلالي للآثار والمفسرات القابلة للتوسيع). + [https://okmij.org/ftp/Computation/having-effect.html#defint](https://okmij.org/ftp/Computation/having-effect.html#defint) + +* غريسمير، R.، هو، R.، كوكي، W.، لانغه، J.، تايلور، I. L.، تونينيو، B.، وادلر، P.، ويوشيدا، N. (2020). *Featherweight Go*. Proc. ACM Program. Lang. 4 (OOPSLA). يعرض القسم 2.3 الحل البنيوي العام المقارن أعلاه. + [https://homepages.inf.ed.ac.uk/wadler/papers/fg/fg.pdf](https://homepages.inf.ed.ac.uk/wadler/papers/fg/fg.pdf) + +* أوليفيرا، B. C. d. S.، وكوك، W. R. (2012). *Extensibility for the Masses: Practical Extensibility with Object Algebras*. + [https://www.cs.utexas.edu/~wcook/Drafts/2012/ecoop2012.pdf](https://www.cs.utexas.edu/~wcook/Drafts/2012/ecoop2012.pdf) diff --git a/src/insights/expression-problem.de.md b/src/insights/expression-problem.de.md new file mode 100644 index 0000000..94763b6 --- /dev/null +++ b/src/insights/expression-problem.de.md @@ -0,0 +1,226 @@ + + +# Expression Problem neu betrachtet {#expression-problem-reloaded} + +```admonish tip title="Verwandte Themen" +The Semantic View: [Denotational Design](../denotational-design/design.md) +Design by Meaning in Rust: [Capability-Algebren](../rust-dd/capability-algebras.md), [Abgeleitete Bedeutung und Komposition](../rust-dd/derived-meaning.md), [Interpreter und Effekte](../rust-dd/interpreters.md) +Concepts: [Expression Problem](../concepts/expression-problem.md) +``` + +Diese Seite stellt eine praktische, traitbasierte Lösung für das *Expression Problem* vor: Wie lassen sich neue Ausdrucksformen und Operationen hinzufügen, ohne bestehenden Code immer wieder umzuschreiben? Der Entwurf folgt **Conals Stil**, die Kodierung ist **tagless-final/Objektalgebra**. Konkret: Zuerst spezifizieren wir kompositionale Bedeutung (kleine Capability-Schnittstellen und Programmspezifikationen auf Erweiterungsebene), dann ergänzen wir konkrete Interpreter. Die konkrete Kodierung gehört zur selben Familie wie Oleg Kiselyovs Stil **tagless-final** und **Object Algebras**: Konstruktorschnittstellen (`LitAlg`, `AddAlg`, `MulAlg`) definieren die Sprachsignatur, Programme werden polymorph über diesen Schnittstellen geschrieben, und konkrete Implementierungen wie `Eval` oder `Pretty` liefern Interpretationen. So wird kein einzelner geschlossener AST festgeschrieben, während statische Typisierung und Erweiterbarkeit in beiden Dimensionen erhalten bleiben. + +Olegs Ansatz ist ausdrücklich denotationell: Zuerst wird kompositionale Bedeutung zugewiesen, anschließend werden Effekte und Interpreter als modulare semantische Ebenen realisiert. Beim Expression Problem ist die Übereinstimmung mit Denotational Design daher zu erwarten und nicht zufällig. Conals Formulierung des Denotational Design räumt derselben Priorität ausdrücklich Vorrang ein: Bedeutung zuerst kompositional spezifizieren, konkrete Ausführungsstrategien als nachgeordnet und austauschbar behandeln. + +Für das Beispiel einer Ausdruckssprache bedeutet diese Kodierung: + +* **Das Konstruktionsvokabular** wird als kleine, unabhängige Algebra-Traits modelliert. +* **Interpretationen** sind Implementierungen dieser Traits. +* Neue Syntax fügt ein neues Trait hinzu, ohne alten Code anzutasten. +* Neue Semantik fügt einen neuen Interprettyp hinzu, ohne alten Code anzutasten. + +`lit` und `add` sind semantische Operationen, keine Konstruktoren eines privilegierten AST. Ein AST ist eine Interpretation unter mehreren. + +```admonish example title="Objektalgebren in C#" +Diese Kodierung ist nicht auf Rust beschränkt. [`object-algebras`](https://github.com/tgrospic/object-algebras) entwickelt das Muster in C# weiter und geht über den hier verwendeten festen Träger hinaus. Auf dieser Seite wählt jeder Interpreter einen konkreten `Self::Expr`, also einen gewöhnlichen Typ. Die C#-Algebren abstrahieren stattdessen über einen *Typkonstruktor* `F` — `FunctorAlg`, `MonadAlg`, `BankingDsl` — und tragen Ergebnisse als `App` statt des unzulässigen `F
`. + +C# kennt keine Typen höherer Ordnung als Werte erster Klasse; deshalb steht `App` für die Anwendung `F(a)`, die durch Inject-/Project-Wrapper wiederhergestellt wird. Dieser `App`Trick ist genau [Defunktionalisierung](../concepts/defunctionalization.md): Die Abstraktion, die die Sprache nicht ausdrücken kann, wird zu Daten erster Ordnung, die bei Bedarf angewendet werden. Rust stößt an dieselbe Grenze und bietet ebenfalls keine Typen höherer Ordnung als Werte erster Klasse. +``` + +## Kleine Syntax-Capabilities spezifizieren {#specify-tiny-syntax-capabilities} + +Jeder Konstruktor wird zu einem kleinen Trait. Das ist die **Spezifikation (Spec)**. + +```rust,noplayground +trait LitAlg { + type Expr; + + fn lit(&self, n: i64) -> Self::Expr; +} + +trait AddAlg { + type Expr; + + fn add(&self, a: Self::Expr, b: Self::Expr) -> Self::Expr; +} +``` + +Programme werden als **Erweiterungen** über den Algebra-Traits formuliert. Diese Erweiterungen gehören ebenfalls zur Spezifikation und verbinden kleinere Spezifikationen zu wiederverwendbaren Spezifikationen auf Programmebene: + +```rust,noplayground +#[ext(name = ExprPrograms)] +impl This +where + This: LitAlg + AddAlg, +{ + fn expr_basic(&self) -> This::Expr { + self.add(self.lit(2), self.lit(3)) + } +} +``` + +`#[ext(...)]` ist ein Makro aus dem [`extend`Crate](https://docs.rs/extend/latest/extend/), das Boilerplate reduziert, indem es Erweiterungsmethoden aus einem `impl`\-Block generiert. Es ist keine neue Sprachfunktion von Rust. + +## Eine neue Interpretation ergänzen {#add-new-interpretation} + +Interpreter implementieren die Spezifikation. Syntaxänderungen sind nicht erforderlich. + +```rust,noplayground +struct Eval; + +impl LitAlg for Eval { + type Expr = i64; + + fn lit(&self, n: i64) -> i64 { n } +} + +impl AddAlg for Eval { + type Expr = i64; + + fn add(&self, a: i64, b: i64) -> i64 { a + b } +} + +struct Pretty; + +impl LitAlg for Pretty { + type Expr = String; + + fn lit(&self, n: i64) -> String { n.to_string() } +} + +impl AddAlg for Pretty { + type Expr = String; + + fn add(&self, a: String, b: String) -> String { + format!("({a} + {b})") + } +} +``` + +Nun lässt sich derselbe Ausdruck unterschiedlich interpretieren: + +```rust,noplayground +let eval = Eval; +let pretty = Pretty; + +let v: i64 = eval.expr_basic(); // 5 +let s: String = pretty.expr_basic(); // "(2 + 3)" +``` + +## Neue Syntax hinzufügen (neues Capability-Trait) {#add-new-syntax-new-capability-trait} + +Um `Mul` hinzuzufügen, definiere ein neues Trait. Bestehender Code bleibt unangetastet. + +```rust,noplayground +trait MulAlg { + type Expr; + + fn mul(&self, a: Self::Expr, b: Self::Expr) -> Self::Expr; +} + +#[ext(name = ExprProgramsMul)] +impl This +where + This: LitAlg + AddAlg + MulAlg, +{ + fn expr_with_mul(&self) -> This::Expr { + self.mul(self.add(self.lit(2), self.lit(3)), self.lit(4)) + } +} +``` + +Bestehende Interpreter funktionieren weiterhin für alte Ausdrücke. +Wenn sie die neue Syntax unterstützen sollen, implementieren sie das neue Trait: + +```rust,noplayground +impl MulAlg for Eval { + type Expr = i64; + + fn mul(&self, a: i64, b: i64) -> i64 { a * b } +} + +impl MulAlg for Pretty { + type Expr = String; + + fn mul(&self, a: String, b: String) -> String { + format!("({a} * {b})") + } +} +``` + +## Warum dies das Expression Problem löst {#why-this-solves-the-expression-problem} + +Das klassische Expression Problem hat zwei Achsen für eine Repräsentation: + +* neue Varianten (Fälle) hinzufügen +* neue Operationen hinzufügen + +Denotational Design formuliert die Achsen neu: + +* **Das semantische Vokabular erweitern**: ein neues Capability-Trait definieren (`MulAlg`). +* **Eine neue Interpretation** dieses Vokabulars ergänzen: einen neuen Interprettyp definieren (`Eval`, `Pretty`, einen AST-Builder oder einen Codegenerator). + +Die beiden Achsen lassen sich unabhängig kombinieren: + +* Bestehende Programme bleiben unverändert, sofern sie die neue Capability nicht benötigen. `expr_basic` verlangt weiterhin nur `LitAlg + AddAlg`. +* Bestehende Interpreter bleiben unverändert, sofern sie die neue Capability nicht interpretieren sollen. `Eval` ohne `impl MulAlg` führt weiterhin jedes Programm aus, das `mul` nicht verwendet. + +Die Implementierungsmatrix verschwindet dadurch nicht. Sollen sowohl `Eval` als auch `Pretty` `mul` interpretieren, benötigen beide ein `impl MulAlg`. Die Matrix wird jedoch anders organisiert: Jedes Feld steht für *semantische Operation × Interpretation*; kein Feld ist um eine privilegierte Repräsentation herum organisiert, und jedes Programm hängt nur von den verwendeten Capabilities ab. + +## Gesetze gehören zur Spezifikation {#laws-belong-to-the-specification} + +Eine semantische Algebra besteht aus einem Träger, Operationen und Gesetzen. Der Träger (`type Expr`) wird durch die Interpretation gewählt; Operationen und Gesetze gehören zur Spezifikation. Eine arithmetische Bedeutung von `LitAlg + AddAlg` besagt beispielsweise: + +```text +add(lit(m), lit(n)) = lit(m + n) +``` + +`Eval` erfüllt dieses Gesetz. `Pretty` tut es nicht: `"(2 + 3)"` ist nicht `"5"`. Beide sind gültige Interpreter der Syntaxsignatur, aber nur `Eval` ist ein Modell der arithmetischen Spezifikation. Das Gesetz wird einmal über die Traits formuliert und entscheidet, welche Interpreter zulässig sind. Keinem Interpreter gehört es. + +## Abschließende Erkenntnis: Featherweight Go und Denotational Design {#final-insight-featherweight-go-vs-denotational-design} + +Wadler analysierte das Expression Problem auf der Ebene der Sprachmechanismen: Zeilen und Spalten unter statischer Typisierung und modularer Erweiterbarkeit. [Featherweight Go](../concepts/expression-problem.md#featherweight-go-solution-2020) liefert eine konkrete Lösung: `Plus(type a Any)` hält die rekursive Repräsentation generisch, und jede Operation schränkt `a` unabhängig ein (`Plus(type a Evaler)` für `Eval`, `Plus(type a Stringer)` für `String`). Die Repräsentation ist nicht an eine einzige geschlossene Ausdrucksschnittstelle gebunden, sodass beide Achsen offenbleiben. + +Traditionelle Lösungen beginnen bei der Repräsentation und fragen, wie sich beide Erweiterungsachsen offenhalten lassen. Featherweight Go geht erstaunlich weit, indem es die rekursive Repräsentation generisch und strukturell erweiterbar macht. Denotational Design setzt die Grenze einen Schritt früher: Die Repräsentation ist nicht das Modell. Das Modell ist die Algebra samt ihren Gesetzen; die Repräsentation ist eine mögliche Interpretation. + +**Featherweight Go macht die Repräsentation erweiterbar. Denotational Design macht die Repräsentation optional.** + +| | Featherweight Go | Denotational Design | +| --- | --- | --- | +| Semantischer Schwerpunkt | erweiterbare Repräsentation | Algebra und Gesetze | +| `Num`/`Plus`, `lit`/`add` | Strukturen (Repräsentationsformen) | semantische Operationen | +| `Eval`, `String`/`Pretty` | Methoden und Schnittstellen | Interpretationen | +| Rekursive Struktur | generische, offene Repräsentation (`Plus(a)`) | nicht erforderlich | +| Träger | der dargestellte Ausdruckstyp | vom Interpreter gewählt (`type Expr`) | +| AST | Repräsentation bleibt zentral | optional, eine Interpretation unter vielen | +| Matrixfeld | Fall × Operation → Methode | semantische Operation × Interpretation → `impl` | +| Neues Verhalten | Methoden und Schnittstellen ergänzen | Capabilities ergänzen oder zusammensetzen | +| Neue Implementierung | neue strukturelle Realisierungen | neuer Interpreter | + +Wadler fragt, wie sich beide Achsen einer Repräsentation erweitern lassen. Denotational Design fragt, warum die Repräsentation für eine der beiden Achsen zuständig sein sollte. + +Zuerst kompositionale Bedeutung definieren, dann Kodierungen auswählen. Das Expression Problem wird dadurch zu einer technischen Wahl zwischen Kodierungen statt zu einer begrifflichen Sackgasse. + +**Die Bedeutung einer Sprache sollte unabhängig von der Vorstellung einer Maschine sein.** + +
Die Bedeutung einer Sprache sollte unabhängig von der Maschine sein
+ +## Quellen {#references} + +* Elliott, C. *Denotational design with type class morphisms*. + [http://conal.net/papers/type-class-morphisms/](http://conal.net/papers/type-class-morphisms/) + +* Elliott, C. *Compiling to categories*. + [http://conal.net/papers/compiling-to-categories/](http://conal.net/papers/compiling-to-categories/) + +* Kiselyov, O. *Tagless-final style* (Übersichten, Tutorials und Artikel zu finalen Kodierungen und erweiterbaren typisierten Interpretern). + [https://okmij.org/ftp/tagless-final/](https://okmij.org/ftp/tagless-final/) + +* Kiselyov, O. *Having an Effect* (definitorische/denotationelle Einordnung von Effekten und erweiterbaren Interpretern). + [https://okmij.org/ftp/Computation/having-effect.html#defint](https://okmij.org/ftp/Computation/having-effect.html#defint) + +* Griesemer, R., Hu, R., Kokke, W., Lange, J., Taylor, I. L., Toninho, B., Wadler, P. und Yoshida, N. (2020). *Featherweight Go*. Proc. ACM Program. Lang. 4 (OOPSLA). Abschnitt 2.3 stellt die oben verglichene generische strukturelle Lösung vor. + [https://homepages.inf.ed.ac.uk/wadler/papers/fg/fg.pdf](https://homepages.inf.ed.ac.uk/wadler/papers/fg/fg.pdf) + +* Oliveira, B. C. d. S. und Cook, W. R. (2012). *Extensibility for the Masses: Practical Extensibility with Object Algebras*. + [https://www.cs.utexas.edu/~wcook/Drafts/2012/ecoop2012.pdf](https://www.cs.utexas.edu/~wcook/Drafts/2012/ecoop2012.pdf) diff --git a/src/insights/expression-problem.es.md b/src/insights/expression-problem.es.md new file mode 100644 index 0000000..e4045e3 --- /dev/null +++ b/src/insights/expression-problem.es.md @@ -0,0 +1,226 @@ + + +# El problema de expresiones, reexaminado {#expression-problem-reloaded} + +```admonish tip title="Relacionado" +La perspectiva semántica: [Diseño denotacional](../denotational-design/design.md) +Diseño basado en el significado en Rust: [Álgebras de capacidades](../rust-dd/capability-algebras.md), [Significado derivado y composición](../rust-dd/derived-meaning.md), [Intérpretes y efectos](../rust-dd/interpreters.md) +Conceptos: [Problema de expresiones](../concepts/expression-problem.md) +``` + +Esta página presenta una solución práctica al *problema de expresiones* basada en rasgos: cómo añadir nuevas formas de expresión y nuevas operaciones sin reescribir repetidamente el código existente. El diseño sigue el **estilo de Conal** y usa una codificación **tagless-final/álgebra de objetos**. En concreto: primero especificamos el significado composicional (interfaces de capacidades pequeñas y especificaciones de programas por extensión) y solo después proporcionamos intérpretes concretos. La codificación concreta pertenece a la misma familia que el estilo **tagless-final** de Oleg Kiselyov y las **álgebras de objetos**: las interfaces de constructores (`LitAlg`, `AddAlg`, `MulAlg`) definen la signatura del lenguaje; los programas se escriben de forma polimórfica respecto a esas interfaces, y las implementaciones concretas (como `Eval` o `Pretty`) proporcionan interpretaciones. Así se evita comprometerse con un único AST cerrado, a la vez que se preservan el tipado estático y la extensibilidad en ambas dimensiones. + +El enfoque de Oleg es explícitamente denotacional: primero asigna un significado composicional y después materializa los efectos y los intérpretes como capas semánticas modulares. Para el problema de expresiones, la alineación con el diseño denotacional es, por tanto, deliberada y no accidental. La formulación de diseño denotacional de Conal expresa directamente la misma prioridad: especificar primero el significado de forma composicional y tratar las estrategias de ejecución concretas como secundarias y reemplazables. + +En el ejemplo del lenguaje de expresiones, esta codificación significa: + +* **El vocabulario de constructores** se modela mediante rasgos algebraicos pequeños e independientes. +* **Las interpretaciones** son implementaciones de esos rasgos. +* La sintaxis nueva añade un rasgo nuevo y deja intacto el código antiguo. +* La semántica nueva añade un tipo de intérprete nuevo y deja intacto el código antiguo. + +`lit` y `add` son operaciones semánticas, no constructores de un AST privilegiado. Un AST es una interpretación entre otras. + +```admonish example title="Álgebras de objetos en C#" +Esta codificación no es exclusiva de Rust. [`object-algebras`](https://github.com/tgrospic/object-algebras) desarrolla el patrón en C# y va más allá del portador fijo que se usa aquí. En esta página, cada intérprete elige un `Self::Expr` concreto, un tipo simple. En cambio, las álgebras de C# abstraen sobre un *constructor* de tipos `F` — `FunctorAlg`, `MonadAlg`, `BankingDsl` — que transporta resultados como `App` en lugar del ilegal `F
`. + +C# no ofrece tipos de orden superior de primera clase, así que `App` representa la aplicación `F(a)`, que se recupera mediante envoltorios inject/project. Ese truco de `App` es precisamente la [defuncionalización](../concepts/defunctionalization.md): la abstracción que el lenguaje no puede expresar se convierte en datos de primer orden, aplicados bajo demanda. Rust se enfrenta al mismo límite: tampoco cuenta con tipos de orden superior de primera clase. +``` + +## Especifica capacidades de sintaxis pequeñas {#specify-tiny-syntax-capabilities} + +Cada constructor se convierte en un rasgo pequeño. Esta es la **especificación**. + +```rust,noplayground +trait LitAlg { + type Expr; + + fn lit(&self, n: i64) -> Self::Expr; +} + +trait AddAlg { + type Expr; + + fn add(&self, a: Self::Expr, b: Self::Expr) -> Self::Expr; +} +``` + +Los programas se escriben como **extensiones** de los rasgos algebraicos; estas extensiones también forman parte de la especificación y permiten componer especificaciones pequeñas en especificaciones reutilizables a nivel de programa: + +```rust,noplayground +#[ext(name = ExprPrograms)] +impl This +where + This: LitAlg + AddAlg, +{ + fn expr_basic(&self) -> This::Expr { + self.add(self.lit(2), self.lit(3)) + } +} +``` + +`#[ext(...)]` es una macro de la biblioteca [`extend`](https://docs.rs/extend/latest/extend/) que reduce el código repetitivo generando métodos de extensión a partir de un bloque `impl`; no es una característica nueva del lenguaje Rust. + +## Añade una interpretación nueva {#add-new-interpretation} + +Los intérpretes implementan la especificación. No hace falta cambiar la sintaxis. + +```rust,noplayground +struct Eval; + +impl LitAlg for Eval { + type Expr = i64; + + fn lit(&self, n: i64) -> i64 { n } +} + +impl AddAlg for Eval { + type Expr = i64; + + fn add(&self, a: i64, b: i64) -> i64 { a + b } +} + +struct Pretty; + +impl LitAlg for Pretty { + type Expr = String; + + fn lit(&self, n: i64) -> String { n.to_string() } +} + +impl AddAlg for Pretty { + type Expr = String; + + fn add(&self, a: String, b: String) -> String { + format!("({a} + {b})") + } +} +``` + +Ahora se puede interpretar la misma expresión de distintas maneras: + +```rust,noplayground +let eval = Eval; +let pretty = Pretty; + +let v: i64 = eval.expr_basic(); // 5 +let s: String = pretty.expr_basic(); // "(2 + 3)" +``` + +## Añade sintaxis nueva (un rasgo de capacidad nuevo) {#add-new-syntax-new-capability-trait} + +Para añadir `Mul`, define un rasgo nuevo. El código existente permanece intacto. + +```rust,noplayground +trait MulAlg { + type Expr; + + fn mul(&self, a: Self::Expr, b: Self::Expr) -> Self::Expr; +} + +#[ext(name = ExprProgramsMul)] +impl This +where + This: LitAlg + AddAlg + MulAlg, +{ + fn expr_with_mul(&self) -> This::Expr { + self.mul(self.add(self.lit(2), self.lit(3)), self.lit(4)) + } +} +``` + +Los intérpretes existentes siguen funcionando con las expresiones antiguas. +Si quieren admitir la sintaxis nueva, implementan el rasgo nuevo: + +```rust,noplayground +impl MulAlg for Eval { + type Expr = i64; + + fn mul(&self, a: i64, b: i64) -> i64 { a * b } +} + +impl MulAlg for Pretty { + type Expr = String; + + fn mul(&self, a: String, b: String) -> String { + format!("({a} * {b})") + } +} +``` + +## Por qué esto resuelve el problema de expresiones {#why-this-solves-the-expression-problem} + +El problema de expresiones tradicional tiene dos ejes sobre una representación: + +* añadir variantes nuevas (casos) +* añadir operaciones nuevas + +El diseño denotacional replantea los ejes: + +* **Amplía el vocabulario semántico**: define un rasgo de capacidad nuevo (`MulAlg`). +* **Añade una interpretación nueva** de ese vocabulario: define un tipo de intérprete nuevo (`Eval`, `Pretty`, un constructor de AST o un generador de código). + +Los dos ejes se componen de manera independiente: + +* Los programas existentes no cambian, salvo que requieran la capacidad nueva. `expr_basic` sigue requiriendo únicamente `LitAlg + AddAlg`. +* Los intérpretes existentes no cambian, salvo que decidan interpretar la capacidad nueva. `Eval` sin `impl MulAlg` sigue ejecutando todos los programas que no usen `mul`. + +Esto no elimina la matriz de implementaciones. Si tanto `Eval` como `Pretty` deben interpretar `mul`, ambos necesitan una implementación `impl MulAlg`. Lo que cambia es la organización de la matriz: cada celda es *operación semántica × interpretación*, ninguna celda gira en torno a una representación privilegiada, y cada programa depende solo de las capacidades que usa. + +## Las leyes pertenecen a la especificación {#laws-belong-to-the-specification} + +Un álgebra semántica consta de un portador, operaciones y leyes. El portador (`type Expr`) lo elige la interpretación; las operaciones y leyes pertenecen a la especificación. Por ejemplo, un significado aritmético de `LitAlg + AddAlg` establece: + +```text +add(lit(m), lit(n)) = lit(m + n) +``` + +`Eval` satisface esta ley. `Pretty` no la satisface: `"(2 + 3)"` no es `"5"`. Ambos son intérpretes válidos de la signatura sintáctica, pero solo `Eval` es un modelo de la especificación aritmética. La ley se formula una sola vez respecto a los rasgos y determina qué intérpretes cumplen los requisitos. No pertenece a ningún intérprete. + +## Perspectiva final: Featherweight Go frente al diseño denotacional {#final-insight-featherweight-go-vs-denotational-design} + +Wadler diagnosticó el problema de expresiones en el nivel de los mecanismos del lenguaje: filas frente a columnas con tipado estático y extensiones modulares. [Featherweight Go](../concepts/expression-problem.md#featherweight-go-solution-2020) ofrece una solución concreta: `Plus(type a Any)` mantiene genérica la representación recursiva y cada operación impone sus propias restricciones a `a` (`Plus(type a Evaler)` para `Eval`, `Plus(type a Stringer)` para `String`). La representación no está ligada a una única interfaz cerrada de expresiones, así que ambos ejes permanecen abiertos. + +Las soluciones tradicionales parten de la representación y preguntan cómo mantener abiertos ambos ejes de extensión. Featherweight Go lleva esta idea sorprendentemente lejos al hacer genérica y extensible estructuralmente la representación recursiva. El diseño denotacional adelanta un paso el límite: la representación no es el modelo. El modelo es el álgebra y sus leyes; la representación es una interpretación posible. + +**Featherweight Go hace extensible la representación. El diseño denotacional vuelve opcional la representación.** + +| | Featherweight Go | Diseño denotacional | +| --- | --- | --- | +| Centro semántico | representación extensible | álgebra y leyes | +| `Num`/`Plus`, `lit`/`add` | estructuras (formas de representación) | operaciones semánticas | +| `Eval`, `String`/`Pretty` | métodos e interfaces | interpretaciones | +| Estructura recursiva | representación genérica y abierta (`Plus(a)`) | no se requiere ninguna | +| Portador | el tipo de expresión representado | lo elige el intérprete (`type Expr`) | +| AST | la representación sigue siendo central | opcional, una interpretación entre muchas | +| Celda de la matriz | caso × operación → método | operación semántica × interpretación → `impl` | +| Comportamiento nuevo | añadir métodos e interfaces | añadir o componer capacidades | +| Implementación nueva | nuevas realizaciones estructurales | nuevo intérprete | + +Wadler pregunta cómo extender ambos ejes de una representación. El diseño denotacional pregunta por qué la representación debería controlar cualquiera de los dos. + +Primero define el significado composicional; después, elige las codificaciones. El problema de expresiones se convierte en una decisión de ingeniería entre codificaciones, no en un callejón conceptual sin salida. + +**El significado de un lenguaje debe ser independiente de la idea de una máquina.** + +
El significado de un lenguaje debe ser independiente de la máquina
+ +## Referencias {#references} + +* Elliott, C. *Denotational design with type class morphisms*. + [http://conal.net/papers/type-class-morphisms/](http://conal.net/papers/type-class-morphisms/) + +* Elliott, C. *Compiling to categories*. + [http://conal.net/papers/compiling-to-categories/](http://conal.net/papers/compiling-to-categories/) + +* Kiselyov, O. *Tagless-final style* (introducción, tutoriales y artículos sobre codificaciones finales e intérpretes tipados extensibles). + [https://okmij.org/ftp/tagless-final/](https://okmij.org/ftp/tagless-final/) + +* Kiselyov, O. *Having an Effect* (enfoque denotacional y de definiciones para efectos e intérpretes extensibles). + [https://okmij.org/ftp/Computation/having-effect.html#defint](https://okmij.org/ftp/Computation/having-effect.html#defint) + +* Griesemer, R., Hu, R., Kokke, W., Lange, J., Taylor, I. L., Toninho, B., Wadler, P. y Yoshida, N. (2020). *Featherweight Go*. Proc. ACM Program. Lang. 4 (OOPSLA). La sección 2.3 presenta la solución estructural genérica comparada arriba. + [https://homepages.inf.ed.ac.uk/wadler/papers/fg/fg.pdf](https://homepages.inf.ed.ac.uk/wadler/papers/fg/fg.pdf) + +* Oliveira, B. C. d. S. y Cook, W. R. (2012). *Extensibility for the Masses: Practical Extensibility with Object Algebras*. + [https://www.cs.utexas.edu/~wcook/Drafts/2012/ecoop2012.pdf](https://www.cs.utexas.edu/~wcook/Drafts/2012/ecoop2012.pdf) diff --git a/src/insights/expression-problem.ja.md b/src/insights/expression-problem.ja.md new file mode 100644 index 0000000..731aa88 --- /dev/null +++ b/src/insights/expression-problem.ja.md @@ -0,0 +1,226 @@ + + +# Expression Problem再考 {#expression-problem-reloaded} + +```admonish tip title="関連項目" +意味論的な見方:[Denotational Design](../denotational-design/design.md) +Rustで意味から設計する:[ケイパビリティ代数](../rust-dd/capability-algebras.md)、[導出される意味と合成](../rust-dd/derived-meaning.md)、[インタープリターと副作用](../rust-dd/interpreters.md) +概念:[Expression Problem](../concepts/expression-problem.md) +``` + +このページでは、既存コードを何度も書き直さずに、新しい式形式と新しい操作を追加する方法である*Expression Problem*に対し、トレイトを使った実践的な解決策を示します。設計は**Conal流**、符号化は**tagless-final/オブジェクト代数方式**です。具体的には、まず合成可能な意味(小さなケイパビリティインターフェースと拡張レベルのプログラム仕様)を定め、その後に具体的なインタープリターを提供します。具体的な符号化は、Oleg Kiselyovの**tagless-final**形式や**オブジェクト代数**と同じ系統です。コンストラクターインターフェース(`LitAlg`、`AddAlg`、`MulAlg`)が言語のシグネチャを定め、プログラムをこれらのインターフェースに対して多相的に記述し、具体実装(`Eval`や`Pretty`など)が解釈を与えます。これにより、閉じた一つのASTに決め打ちせず、静的型付けと二つの軸の拡張性を保てます。 + +Olegの方法は明示的に表示に基づいています。まず合成可能な意味を割り当て、その後に副作用やインタープリターをモジュール式の意味論層として実現します。Expression Problemに対してDenotational Designと歩調が合うのは、偶然ではなく、この理由によるものです。ConalのDenotational Designも、まず合成的に意味を定め、具体的な実行戦略は後から交換可能なものとして扱うという優先順位を明示します。 + +式言語の例では、次のように符号化します。 + +* **コンストラクターの語彙**を小さく独立した代数トレイトで表す。 +* **解釈**を、それらのトレイトの実装で表す。 +* 新しい構文を追加すると新しいトレイトが加わり、既存コードは変更しない。 +* 新しい意味論を追加すると新しいインタープリター型が加わり、既存コードは変更しない。 + +`lit`と`add`は意味論的操作であり、特権的なASTのコンストラクターではありません。ASTは複数ある解釈の一つです。 + +```admonish example title="C#におけるオブジェクト代数" +この符号化はRust固有ではありません。[`object-algebras`](https://github.com/tgrospic/object-algebras)ではC#でこのパターンを発展させ、ここで使う固定担体を越えて抽象化します。このページでは各インタープリターが平易な具体型である`Self::Expr`を選びます。一方C#の代数では、型*コンストラクター*`F`(`FunctorAlg`、`MonadAlg`、`BankingDsl`)を抽象化し、不正な`F
`の代わりに結果を`App`として持ち運びます。 + +C#に第一級の高カインド型はないため、`App`が適用`F(a)`の代わりとなり、inject/projectラッパーを通じて実現します。この`App`トリックはまさに[デファンクショナライズ](../concepts/defunctionalization.md)です。言語で表現できない抽象化を一階データにし、必要に応じて適用します。Rustにも第一級の高カインド型がないため、同じ制約があります。 +``` + +## 小さな構文ケイパビリティを定める {#specify-tiny-syntax-capabilities} + +各コンストラクターを小さなトレイトにします。これが仕様(spec)です。 + +```rust,noplayground +trait LitAlg { + type Expr; + + fn lit(&self, n: i64) -> Self::Expr; +} + +trait AddAlg { + type Expr; + + fn add(&self, a: Self::Expr, b: Self::Expr) -> Self::Expr; +} +``` + +プログラムを代数トレイト上の**拡張**として記述します。これらの拡張も仕様の一部であり、小さな仕様を組み合わせて再利用可能なプログラムレベルの仕様にします。 + +```rust,noplayground +#[ext(name = ExprPrograms)] +impl This +where + This: LitAlg + AddAlg, +{ + fn expr_basic(&self) -> This::Expr { + self.add(self.lit(2), self.lit(3)) + } +} +``` + +`#[ext(...)]`は[`extend`クレートのマクロ](https://docs.rs/extend/latest/extend/)で、`impl`ブロックから拡張メソッドを生成して定型コードを減らします。Rustの新しい言語機能ではありません。 + +## 新しい解釈を追加する {#add-new-interpretation} + +インタープリターが仕様を実装します。構文を変更する必要はありません。 + +```rust,noplayground +struct Eval; + +impl LitAlg for Eval { + type Expr = i64; + + fn lit(&self, n: i64) -> i64 { n } +} + +impl AddAlg for Eval { + type Expr = i64; + + fn add(&self, a: i64, b: i64) -> i64 { a + b } +} + +struct Pretty; + +impl LitAlg for Pretty { + type Expr = String; + + fn lit(&self, n: i64) -> String { n.to_string() } +} + +impl AddAlg for Pretty { + type Expr = String; + + fn add(&self, a: String, b: String) -> String { + format!("({a} + {b})") + } +} +``` + +同じ式を別の方法で解釈できます。 + +```rust,noplayground +let eval = Eval; +let pretty = Pretty; + +let v: i64 = eval.expr_basic(); // 5 +let s: String = pretty.expr_basic(); // "(2 + 3)" +``` + +## 新しい構文を追加する(新しいケイパビリティトレイト) {#add-new-syntax-new-capability-trait} + +`Mul`を追加するには、新しいトレイトを定義します。既存コードは変更しません。 + +```rust,noplayground +trait MulAlg { + type Expr; + + fn mul(&self, a: Self::Expr, b: Self::Expr) -> Self::Expr; +} + +#[ext(name = ExprProgramsMul)] +impl This +where + This: LitAlg + AddAlg + MulAlg, +{ + fn expr_with_mul(&self) -> This::Expr { + self.mul(self.add(self.lit(2), self.lit(3)), self.lit(4)) + } +} +``` + +既存のインタープリターは古い式で引き続き動作します。 +新しい構文が必要なら、新しいトレイトを実装します。 + +```rust,noplayground +impl MulAlg for Eval { + type Expr = i64; + + fn mul(&self, a: i64, b: i64) -> i64 { a * b } +} + +impl MulAlg for Pretty { + type Expr = String; + + fn mul(&self, a: String, b: String) -> String { + format!("({a} * {b})") + } +} +``` + +## Expression Problemをどう解決するか {#why-this-solves-the-expression-problem} + +従来のExpression Problemは、表現に関する二つの軸を扱います。 + +* 新しいバリアント(ケース)を追加する +* 新しい操作を追加する + +Denotational Designは、軸を次のように捉え直します。 + +* **意味論上の語彙を拡張する**:新しいケイパビリティトレイト(`MulAlg`)を定義する。 +* その語彙に対する**新しい解釈を追加する**:新しいインタープリター型(`Eval`、`Pretty`、ASTビルダー、コード生成器など)を定義する。 + +二つの軸は独立して合成できます。 + +* 新しいケイパビリティが必要でない限り、既存プログラムは変更しません。`expr_basic`が必要とするのは`LitAlg + AddAlg`だけです。 +* 新しいケイパビリティを解釈する必要がない限り、既存インタープリターは変更しません。`impl MulAlg`を持たない`Eval`でも、`mul`を使わないすべてのプログラムを引き続き実行できます。 + +実装の組み合わせ表そのものがなくなるわけではありません。`Eval`と`Pretty`の両方で`mul`を解釈する必要があるなら、それぞれに`impl MulAlg`が要ります。変わるのは表の整理の仕方です。各セルは*意味論的操作×解釈*となり、特権的な表現を中心に整理せず、各プログラムは使うケイパビリティだけに依存します。 + +## 法則は仕様に属する {#laws-belong-to-the-specification} + +意味論的代数は、担体、操作、法則で構成されます。担体(`type Expr`)は解釈が選び、操作と法則は仕様に属します。たとえば、`LitAlg + AddAlg`の算術上の意味は次のように述べます。 + +```text +add(lit(m), lit(n)) = lit(m + n) +``` + +`Eval`はこの法則を満たします。`Pretty`は満たしません。`"(2 + 3)"`は`"5"`ではないからです。どちらも構文シグネチャの有効なインタープリターですが、算術仕様のモデルとなるのは`Eval`だけです。法則はトレイトに対して一度だけ述べ、それを満たすインタープリターを選びます。どのインタープリターも法則を所有しません。 + +## 最後の洞察:Featherweight GoとDenotational Design {#final-insight-featherweight-go-vs-denotational-design} + +Wadlerは、静的型付けとモジュール式の拡張のもとで、行と列をどう扱うかという言語機構の水準でExpression Problemを捉えました。[Featherweight Go](../concepts/expression-problem.md#featherweight-go-solution-2020)は具体策を与えます。`Plus(type a Any)`では再帰表現をジェネリックに保ち、各操作が`a`を個別に制約します(`Eval`には`Plus(type a Evaler)`、`String`には`Plus(type a Stringer)`)。表現を一つの閉じた式インターフェースに結び付けないため、両方の軸を開いたままにできます。 + +従来の解決策では、表現から出発して二つの拡張軸を開いたままにする方法を問います。Featherweight Goは、再帰表現をジェネリックかつ構造的に拡張可能にして、この問題を驚くほどのところまで解決します。Denotational Designは境界を一歩手前へ移します。表現がモデルではありません。モデルは代数とその法則であり、表現は考えられる解釈の一つです。 + +**Featherweight Goは表現を拡張可能にし、Denotational Designは表現を任意にする。** + +| | Featherweight Go | Denotational Design | +| --- | --- | --- | +| 意味論上の中心 | 拡張可能な表現 | 代数と法則 | +| `Num`/`Plus`, `lit`/`add` | 構造(表現形式) | 意味論的操作 | +| `Eval`, `String`/`Pretty` | メソッドとインターフェース | 解釈 | +| 再帰構造 | ジェネリックで開かれた表現(`Plus(a)`) | 不要 | +| 担体 | 表現される式の型 | インタープリターが選ぶ(`type Expr`) | +| AST | 表現が中心のまま | 任意。複数ある解釈の一つ | +| 表のセル | ケース×操作→メソッド | 意味論的操作×解釈→`impl` | +| 新しい振る舞い | メソッドとインターフェースを追加する | ケイパビリティを追加または合成する | +| 新しい実装 | 新たな構造的実現 | 新しいインタープリター | + +Wadlerは、表現の両方の軸をどう拡張するかを問います。Denotational Designは、そもそも表現がいずれかの軸を所有すべきなのかを問います。 + +まず合成可能な意味を定め、それから符号化を選びます。Expression Problemは、概念的な行き詰まりではなく、符号化の間で行うエンジニアリング上の選択になります。 + +**言語の意味は機械という考えから独立しているべきである。** + +
言語の意味は機械から独立しているべきである
+ +## 参考文献 {#references} + +* Elliott, C. *Denotational design with type class morphisms*。 + [http://conal.net/papers/type-class-morphisms/](http://conal.net/papers/type-class-morphisms/) + +* Elliott, C. *Compiling to categories*。 + [http://conal.net/papers/compiling-to-categories/](http://conal.net/papers/compiling-to-categories/) + +* Kiselyov, O. *Tagless-final形式*(final形式の符号化と拡張可能な型付きインタープリターに関する概説、チュートリアル、論文)。 + [https://okmij.org/ftp/tagless-final/](https://okmij.org/ftp/tagless-final/) + +* Kiselyov, O. *Having an Effect*(副作用と拡張可能なインタープリターの定義的/表示的な考察)。 + [https://okmij.org/ftp/Computation/having-effect.html#defint](https://okmij.org/ftp/Computation/having-effect.html#defint) + +* Griesemer, R., Hu, R., Kokke, W., Lange, J., Taylor, I. L., Toninho, B., Wadler, P., Yoshida, N.(2020)。*Featherweight Go*。Proc. ACM Program. Lang. 4(OOPSLA)。第2.3節では、上で比較したジェネリックな構造的解決策を示しています。 + [https://homepages.inf.ed.ac.uk/wadler/papers/fg/fg.pdf](https://homepages.inf.ed.ac.uk/wadler/papers/fg/fg.pdf) + +* Oliveira, B. C. d. S.、Cook, W. R.(2012)。*Extensibility for the Masses: Practical Extensibility with Object Algebras*。 + [https://www.cs.utexas.edu/~wcook/Drafts/2012/ecoop2012.pdf](https://www.cs.utexas.edu/~wcook/Drafts/2012/ecoop2012.pdf) diff --git a/src/insights/expression-problem.ko.md b/src/insights/expression-problem.ko.md new file mode 100644 index 0000000..582a56b --- /dev/null +++ b/src/insights/expression-problem.ko.md @@ -0,0 +1,226 @@ + + +# 표현식 문제 다시 보기 {#expression-problem-reloaded} + +```admonish tip title="관련 항목" +의미론적 관점: [표시적 설계](../denotational-design/design.md) +Rust에서 의미로 설계하기: [케이퍼빌리티 대수](../rust-dd/capability-algebras.md), [파생 의미와 합성](../rust-dd/derived-meaning.md), [인터프리터와 효과](../rust-dd/interpreters.md) +개념: [표현식 문제](../concepts/expression-problem.md) +``` + +이 페이지에서는 *표현식 문제*에 대한 실용적인 트레이트 기반 해결책을 소개합니다. 기존 코드를 반복해서 다시 쓰지 않고 표현식 형식과 연산을 어떻게 추가할 수 있을까요? 이 해결책은 설계 면에서 **Conal식**이고 인코딩 면에서 **태그리스 파이널/객체 대수** 방식입니다. 구체적으로는 합성 의미를 먼저 명세하고(작은 케이퍼빌리티 인터페이스와 확장 수준의 프로그램 명세), 그다음 구체 인터프리터를 제공합니다. 구체 인코딩은 Oleg Kiselyov의 **태그리스 파이널** 방식 및 **객체 대수**와 같은 계열입니다. 생성자 인터페이스(`LitAlg`, `AddAlg`, `MulAlg`)가 언어 시그니처를 정의하고, 프로그램은 그 인터페이스에 대해 다형적으로 작성되며, 구체 구현(`Eval` 또는 `Pretty` 등)이 해석을 제공합니다. 이 방식은 닫힌 AST 하나에 고정하지 않으면서 두 차원에서 정적 타입과 확장성을 유지합니다. + +Oleg의 접근은 명시적으로 표시적입니다. 먼저 합성 의미를 부여하고 효과 및 인터프리터를 모듈식 의미 계층으로 실현합니다. 표현식 문제에서 표시적 설계와 정렬되는 것은 우연이 아니라 당연합니다. Conal의 표시적 설계 정식화도 같은 우선순위를 분명히 합니다. 의미를 합성적으로 먼저 명세하고 구체 실행 전략은 부차적이고 교체 가능한 것으로 취급합니다. + +표현식 언어 예에서 이 인코딩은 다음을 뜻합니다: + +* **생성자 어휘**는 작고 독립적인 대수 트레이트로 모델링합니다. +* **해석**은 이러한 트레이트의 구현입니다. +* 새 구문을 추가할 때 새 트레이트를 만들고 기존 코드는 그대로 둡니다. +* 새 의미론을 추가할 때 새 인터프리터 타입을 만들고 기존 코드는 그대로 둡니다. + +`lit`와 `add`은 특권 AST의 생성자가 아니라 의미론적 연산입니다. AST는 여러 해석 중 하나입니다. + +```admonish example title="C#의 객체 대수" +이 인코딩은 Rust에만 국한되지 않습니다. [`object-algebras`](https://github.com/tgrospic/object-algebras)에서는 C#으로 이 패턴을 발전시키고 여기서 사용하는 고정 기반 집합을 넘어섭니다. 이 페이지에서 각 인터프리터는 일반 타입인 구체적인 `Self::Expr` 하나를 선택합니다. C# 대수는 대신 타입 *생성자* `F` — `FunctorAlg`, `MonadAlg`, `BankingDsl` — 를 추상화하고, 사용할 수 없는 `F
` 대신 결과를 `App`로 전달합니다. + +C#에는 일급 고차 종류 타입이 없으므로 `App`가 애플리케이션 `F(a)`을 대신하고, 주입/투영 래퍼를 통해 되찾습니다. 이 `App` 기법이 바로 [디펑셔널라이제이션](../concepts/defunctionalization.md)입니다. 언어로 표현할 수 없는 추상화가 일차 데이터가 되어 필요할 때 적용됩니다. Rust도 일급 고차 종류 타입이 없으므로 같은 한계에 부딪힙니다. +``` + +## 작은 구문 케이퍼빌리티 명세하기 {#specify-tiny-syntax-capabilities} + +각 생성자는 작은 트레이트가 됩니다. 이것이 명세(spec)입니다. + +```rust,noplayground +trait LitAlg { + type Expr; + + fn lit(&self, n: i64) -> Self::Expr; +} + +trait AddAlg { + type Expr; + + fn add(&self, a: Self::Expr, b: Self::Expr) -> Self::Expr; +} +``` + +프로그램은 대수 트레이트에 대한 **확장**으로 작성합니다. 이 확장도 명세의 일부이며 작은 명세를 재사용 가능한 프로그램 수준 명세로 합성합니다: + +```rust,noplayground +#[ext(name = ExprPrograms)] +impl This +where + This: LitAlg + AddAlg, +{ + fn expr_basic(&self) -> This::Expr { + self.add(self.lit(2), self.lit(3)) + } +} +``` + +`#[ext(...)]`는 [`extend` 크레이트의 매크로입니다](https://docs.rs/extend/latest/extend/). `impl` 블록에서 확장 메서드를 생성해 상용구를 줄이며, 새로운 Rust 언어 기능은 아닙니다. + +## 새 해석 추가 {#add-new-interpretation} + +인터프리터가 명세를 구현합니다. 구문을 바꿀 필요는 없습니다. + +```rust,noplayground +struct Eval; + +impl LitAlg for Eval { + type Expr = i64; + + fn lit(&self, n: i64) -> i64 { n } +} + +impl AddAlg for Eval { + type Expr = i64; + + fn add(&self, a: i64, b: i64) -> i64 { a + b } +} + +struct Pretty; + +impl LitAlg for Pretty { + type Expr = String; + + fn lit(&self, n: i64) -> String { n.to_string() } +} + +impl AddAlg for Pretty { + type Expr = String; + + fn add(&self, a: String, b: String) -> String { + format!("({a} + {b})") + } +} +``` + +이제 같은 표현식을 여러 방식으로 해석할 수 있습니다: + +```rust,noplayground +let eval = Eval; +let pretty = Pretty; + +let v: i64 = eval.expr_basic(); // 5 +let s: String = pretty.expr_basic(); // "(2 + 3)" +``` + +## 새 구문 추가 (새 케이퍼빌리티 트레이트) {#add-new-syntax-new-capability-trait} + +`Mul`를 추가하려면 새 트레이트를 정의하세요. 기존 코드는 그대로 둡니다. + +```rust,noplayground +trait MulAlg { + type Expr; + + fn mul(&self, a: Self::Expr, b: Self::Expr) -> Self::Expr; +} + +#[ext(name = ExprProgramsMul)] +impl This +where + This: LitAlg + AddAlg + MulAlg, +{ + fn expr_with_mul(&self) -> This::Expr { + self.mul(self.add(self.lit(2), self.lit(3)), self.lit(4)) + } +} +``` + +기존 인터프리터는 예전 표현식에서 계속 작동합니다. +새 구문도 지원하려면 새 트레이트를 구현합니다: + +```rust,noplayground +impl MulAlg for Eval { + type Expr = i64; + + fn mul(&self, a: i64, b: i64) -> i64 { a * b } +} + +impl MulAlg for Pretty { + type Expr = String; + + fn mul(&self, a: String, b: String) -> String { + format!("({a} * {b})") + } +} +``` + +## 이것이 표현식 문제를 해결하는 이유 {#why-this-solves-the-expression-problem} + +전통적인 표현식 문제에는 표현을 기준으로 두 축이 있습니다: + +* 새 변형(사례) 추가 +* 새 연산 추가 + +표시적 설계는 축을 다시 설명합니다: + +* **의미 어휘 확장**: 새 케이퍼빌리티 트레이트(`MulAlg`)를 정의합니다. +* **그 어휘에 대한 새 해석 추가**: 새 인터프리터 타입(`Eval`, `Pretty`, AST 빌더, 코드 생성기)을 정의합니다. + +두 축은 독립적으로 합성됩니다: + +* 새 케이퍼빌리티가 필요하지 않다면 기존 프로그램을 바꿀 필요가 없습니다. `expr_basic`는 여전히 `LitAlg + AddAlg`만 요구합니다. +* 새 케이퍼빌리티를 해석하기로 하지 않는 한 기존 인터프리터를 바꾸지 않아도 됩니다. `impl MulAlg`가 없는 `Eval`도 `mul`를 사용하지 않는 모든 프로그램을 계속 실행합니다. + +구현 행렬이 사라지는 것은 아닙니다. `Eval`와 `Pretty`가 모두 `mul`를 해석해야 한다면 둘 다 `impl MulAlg`가 필요합니다. 달라지는 점은 행렬을 구성하는 방식입니다. 각 칸이 *의미 연산 × 해석*이며 특권 표현을 중심으로 구성된 칸이 없고, 각 프로그램은 사용하는 케이퍼빌리티에만 의존합니다. + +## 법칙은 명세에 속합니다 {#laws-belong-to-the-specification} + +의미론적 대수는 기반 집합, 연산, 법칙으로 이루어집니다. 기반 집합(`type Expr`)은 해석이 선택하지만 연산과 법칙은 명세에 속합니다. 예를 들어 산술의 의미인 `LitAlg + AddAlg`은 다음을 명시합니다: + +```text +add(lit(m), lit(n)) = lit(m + n) +``` + +`Eval`는 이 법칙을 만족합니다. `Pretty`는 만족하지 않습니다. `"(2 + 3)"`는 `"5"`이 아닙니다. 둘 다 구문 시그니처의 유효한 인터프리터지만, `Eval`만 산술 명세의 모델입니다. 법칙은 트레이트를 대상으로 한 번 명시하여 어떤 인터프리터가 적합한지 결정합니다. 어느 인터프리터도 법칙을 소유하지 않습니다. + +## 마지막 통찰: Featherweight Go와 표시적 설계 {#final-insight-featherweight-go-vs-denotational-design} + +Wadler는 정적 타입과 모듈식 확장에서 행과 열의 문제로 언어 기제 수준의 표현식 문제를 진단했습니다. [Featherweight Go](../concepts/expression-problem.md#featherweight-go-solution-2020)는 구체적인 해결책을 제공합니다. `Plus(type a Any)`로 재귀 표현을 제네릭하게 유지하고 각 연산은 `a`을 독립적으로 제한합니다(`Eval`에는 `Plus(type a Evaler)`, `String`에는 `Plus(type a Stringer)`). 표현이 닫힌 표현식 인터페이스 하나에 묶이지 않으므로 두 축이 모두 열려 있습니다. + +전통적인 해결책은 표현에서 시작해 확장 두 축을 모두 열어 두는 방법을 묻습니다. Featherweight Go는 재귀 표현을 제네릭하고 구조적으로 확장 가능하게 만들어 놀라울 만큼 멀리 나아갑니다. 표시적 설계는 경계를 한 단계 더 앞당깁니다. 표현이 모델은 아닙니다. 모델은 대수와 그 법칙이며 표현은 가능한 해석 중 하나입니다. + +**Featherweight Go는 표현을 확장 가능하게 합니다. 표시적 설계는 표현을 선택 사항으로 만듭니다.** + +| | Featherweight Go | 표시적 설계 | +| --- | --- | --- | +| 의미의 중심 | 확장 가능한 표현 | 대수와 법칙 | +| `Num`/`Plus`, `lit`/`add` | 구조 (표현 형식) | 의미론적 연산 | +| `Eval`, `String`/`Pretty` | 메서드와 인터페이스 | 해석 | +| 재귀 구조 | 제네릭하고 열린 표현 (`Plus(a)`) | 필요 없음 | +| 기반 집합 | 표현된 표현식 타입 | 인터프리터가 선택 (`type Expr`) | +| AST | 표현이 계속 중심에 있음 | 선택 사항이며 여러 해석 중 하나 | +| 행렬의 한 칸 | 사례 × 연산 → 메서드 | 의미론적 연산 × 해석 → `impl` | +| 새 동작 | 메서드와 인터페이스 추가 | 케이퍼빌리티 추가 또는 합성 | +| 새 구현 | 새 구조적 실현 | 새 인터프리터 | + +Wadler는 표현의 두 축을 확장하는 법을 묻습니다. 표시적 설계는 왜 표현이 어느 축이든 소유해야 하는지 묻습니다. + +합성 가능한 의미를 먼저 정의하고 인코딩을 선택하세요. 그러면 표현식 문제는 개념적 교착 상태가 아니라 인코딩 사이에서 내리는 엔지니어링 선택이 됩니다. + +**언어의 의미는 기계라는 개념과 독립적이어야 합니다.** + +
언어의 의미는 기계와 독립적이어야 합니다
+ +## 참고 문헌 {#references} + +* Elliott, C. *Denotational design with type class morphisms*. + [http://conal.net/papers/type-class-morphisms/](http://conal.net/papers/type-class-morphisms/) + +* Elliott, C. *Compiling to categories*. + [http://conal.net/papers/compiling-to-categories/](http://conal.net/papers/compiling-to-categories/) + +* Kiselyov, O. *Tagless-final style* (파이널 인코딩 및 확장 가능한 타입 인터프리터에 관한 개요, 튜토리얼, 논문). + [https://okmij.org/ftp/tagless-final/](https://okmij.org/ftp/tagless-final/) + +* Kiselyov, O. *Having an Effect* (효과와 확장 가능한 인터프리터에 대한 정의적/표시적 관점). + [https://okmij.org/ftp/Computation/having-effect.html#defint](https://okmij.org/ftp/Computation/having-effect.html#defint) + +* Griesemer, R., Hu, R., Kokke, W., Lange, J., Taylor, I. L., Toninho, B., Wadler, P., Yoshida, N. (2020). *Featherweight Go*. Proc. ACM Program. Lang. 4 (OOPSLA). 2.3절에서 위와 비교한 제네릭 구조적 해결책을 설명합니다. + [https://homepages.inf.ed.ac.uk/wadler/papers/fg/fg.pdf](https://homepages.inf.ed.ac.uk/wadler/papers/fg/fg.pdf) + +* Oliveira, B. C. d. S., Cook, W. R. (2012). *Extensibility for the Masses: Practical Extensibility with Object Algebras*. + [https://www.cs.utexas.edu/~wcook/Drafts/2012/ecoop2012.pdf](https://www.cs.utexas.edu/~wcook/Drafts/2012/ecoop2012.pdf) diff --git a/src/insights/expression-problem.md b/src/insights/expression-problem.md index 74f119b..e11d5ff 100644 --- a/src/insights/expression-problem.md +++ b/src/insights/expression-problem.md @@ -18,6 +18,8 @@ For the expression-language example, this encoding means: - New syntax adds a new trait, leaving old code untouched. - New semantics adds a new interpreter type, leaving old code untouched. +`lit` and `add` are semantic operations, not constructors of a privileged AST. An AST is one interpretation among others. + ```admonish example title="Object algebras in C#" This encoding is not Rust-specific. [`object-algebras`](https://github.com/tgrospic/object-algebras) develops the pattern in C# and pushes past the fixed carrier used here. On this page each interpreter picks one concrete `Self::Expr`, a plain type. The C# algebras instead abstract over a type *constructor* `F` — `FunctorAlg`, `MonadAlg`, `BankingDsl` — carrying results as `App` in place of the illegal `F
`. @@ -147,19 +149,56 @@ impl MulAlg for Pretty { ## Why this solves the Expression Problem -- **Add new operations**: define a new interpreter type implementing the same specs. -- **Add new variants**: define a new capability trait and use it only where needed. -- **No edits** to existing expressions or interpreters unless they opt into new syntax. +The traditional Expression Problem has two axes over a representation: + +- add new variants (cases) +- add new operations + +Denotational Design reframes the axes: + +- **Extend the semantic vocabulary**: define a new capability trait (`MulAlg`). +- **Add a new interpretation** of that vocabulary: define a new interpreter type (`Eval`, `Pretty`, an AST builder, a code generator). -This keeps the design modular: simple specs, extension by composition, and thin concrete implementations. +The two axes compose independently: -## Final insight: Wadler vs Denotational Design +- Existing programs do not change unless they require the new capability. `expr_basic` still asks only for `LitAlg + AddAlg`. +- Existing interpreters do not change unless they choose to interpret the new capability. `Eval` without `impl MulAlg` still runs every program that does not use `mul`. -Wadler diagnosed the Expression Problem correctly at the level of language mechanisms: rows vs columns under static typing and modular extension. But that framing starts after the key mistake is already made: treating concrete representation as the model. +This does not remove the implementation matrix. If `Eval` and `Pretty` should both interpret `mul`, both need an `impl MulAlg`. What changes is how the matrix is organized: each cell is *semantic operation × interpretation*, no cell is organized around a privileged representation, and each program depends only on the capabilities it uses. + +## Laws belong to the specification + +A semantic algebra is a carrier, operations, and laws. The carrier (`type Expr`) is chosen by the interpretation; the operations and laws belong to the specification. For example, an arithmetic meaning of `LitAlg + AddAlg` states: + +```text +add(lit(m), lit(n)) = lit(m + n) +``` -Denotational Design moves the diagnosis upstream. The core failure is representation-first programming: encoding machine structure (ADT, class graph, memory layout) before specifying meaning. Once that commitment is made, extensibility tradeoffs appear as “deep problems.” +`Eval` satisfies this law. `Pretty` does not: `"(2 + 3)"` is not `"5"`. Both are valid interpreters of the syntax signature, but only `Eval` is a model of the arithmetic specification. The law is stated once, against the traits, and decides which interpreters qualify. No interpreter owns it. -From a meaning-first view, many of these tensions are self-inflicted. Define compositional meaning first, then choose encodings. The Expression Problem becomes an engineering choice among encodings, not a conceptual deadlock. +## Final insight: Featherweight Go vs Denotational Design + +Wadler diagnosed the Expression Problem at the level of language mechanisms: rows vs columns under static typing and modular extension. [Featherweight Go](../concepts/expression-problem.md#featherweight-go-solution-2020) gives a concrete solution: `Plus(type a Any)` keeps the recursive representation generic, and each operation constrains `a` independently (`Plus(type a Evaler)` for `Eval`, `Plus(type a Stringer)` for `String`). The representation is not tied to one closed expression interface, so both axes stay open. + +Traditional solutions start from the representation and ask how to keep both extension axes open. Featherweight Go pushes this surprisingly far by making the recursive representation generic and structurally extensible. Denotational Design moves the boundary one step earlier: representation is not the model. The model is the algebra and its laws; representation is one possible interpretation. + +**Featherweight Go makes representation extensible. Denotational Design makes representation optional.** + +| | Featherweight Go | Denotational Design | +|----------------------|------------------------------------------|------------------------------------------| +| Semantic center | extensible representation | algebra and laws | +| `Num`/`Plus`, `lit`/`add` | structures (representation forms) | semantic operations | +| `Eval`, `String`/`Pretty` | methods and interfaces | interpretations | +| Recursive structure | generic, open representation (`Plus(a)`) | none required | +| Carrier | the represented expression type | chosen by the interpreter (`type Expr`) | +| AST | representation remains central | optional, one interpretation among many | +| Matrix cell | case × operation → method | semantic operation × interpretation → `impl` | +| New behavior | add methods and interfaces | add or compose capabilities | +| New implementation | new structural realizations | new interpreter | + +Wadler asks how to extend both axes of a representation. Denotational Design asks why representation should own either axis. + +Define compositional meaning first, then choose encodings. The Expression Problem becomes an engineering choice among encodings, not a conceptual deadlock. **Meaning of a language should be independent of the idea of a machine.** @@ -190,5 +229,8 @@ From a meaning-first view, many of these tensions are self-inflicted. Define com * Kiselyov, O. *Having an Effect* (definitional/denotational framing of effects and extensible interpreters). [https://okmij.org/ftp/Computation/having-effect.html#defint](https://okmij.org/ftp/Computation/having-effect.html#defint) +* Griesemer, R., Hu, R., Kokke, W., Lange, J., Taylor, I. L., Toninho, B., Wadler, P., and Yoshida, N. (2020). *Featherweight Go*. Proc. ACM Program. Lang. 4 (OOPSLA). Section 2.3 gives the generic structural solution compared above. + [https://homepages.inf.ed.ac.uk/wadler/papers/fg/fg.pdf](https://homepages.inf.ed.ac.uk/wadler/papers/fg/fg.pdf) + * Oliveira, B. C. d. S., and Cook, W. R. (2012). *Extensibility for the Masses: Practical Extensibility with Object Algebras*. [https://www.cs.utexas.edu/~wcook/Drafts/2012/ecoop2012.pdf](https://www.cs.utexas.edu/~wcook/Drafts/2012/ecoop2012.pdf) diff --git a/src/insights/expression-problem.ru.md b/src/insights/expression-problem.ru.md new file mode 100644 index 0000000..8148260 --- /dev/null +++ b/src/insights/expression-problem.ru.md @@ -0,0 +1,226 @@ + + +# Проблема выражения: новый взгляд {#expression-problem-reloaded} + +```admonish tip title="Связанные материалы" +«Семантический взгляд»: [Денотационное проектирование](../denotational-design/design.md) +«Проектирование на основе смысла в Rust»: [Алгебры возможностей](../rust-dd/capability-algebras.md), [Производный смысл и композиция](../rust-dd/derived-meaning.md), [Интерпретаторы и эффекты](../rust-dd/interpreters.md) +«Понятия»: [Проблема выражения](../concepts/expression-problem.md) +``` + +На этой странице представлен практический основанный на трейтах подход к *проблеме выражения*: как добавлять новые формы выражений и операции, не переписывая постоянно существующий код. В основе проектирования лежит подход **в духе Конала**, а кодирование использует стиль **tagless-final / объектные алгебры**. Сначала задаётся композиционный смысл (небольшие интерфейсы возможностей и спецификации программ на уровне расширений), а затем предоставляются конкретные интерпретаторы. Конкретное кодирование относится к тому же семейству, что и стиль **tagless-final** Олега Киселёва и **объектные алгебры**: интерфейсы-конструкторы (`LitAlg`, `AddAlg`, `MulAlg`) задают сигнатуру языка, программы записываются полиморфно через эти интерфейсы, а конкретные реализации (например, `Eval` или `Pretty`) предоставляют интерпретации. Так удаётся не привязываться к одному закрытому AST, сохраняя статическую типизацию и расширяемость по обоим измерениям. + +Подход Олега явно денотационный: сначала назначается композиционный смысл, а затем эффекты и интерпретаторы реализуются в виде модульных семантических слоёв. Для проблемы выражения именно поэтому связь с денотационным проектированием ожидаема, а не случайна. В формулировке Конала Эллиотта приоритет тот же: сначала композиционно задаётся смысл, а конкретные стратегии выполнения рассматриваются как вторичные и заменяемые. + +Для примера языка выражений это кодирование означает следующее: + +* **Словарь конструкторов** моделируется небольшими независимыми трейтовыми алгебрами. +* **Интерпретации** являются реализациями этих трейтов. +* Новый синтаксис добавляет новый трейт, не затрагивая старый код. +* Новая семантика добавляет новый тип интерпретатора, не затрагивая старый код. + +`lit` и `add` — семантические операции, а не конструкторы привилегированного AST. AST — лишь одна из возможных интерпретаций. + +```admonish example title="Объектные алгебры в C#" +Это кодирование не специфично для Rust. [`object-algebras`](https://github.com/tgrospic/object-algebras) развивает этот паттерн на C# и выходит за пределы фиксированного носителя, используемого здесь. На этой странице каждый интерпретатор выбирает один конкретный `Self::Expr`, обычный тип. Алгебры C# абстрагируются от типового *конструктора* `F` — `FunctorAlg`, `MonadAlg`, `BankingDsl`, — который передаёт результаты как `App` вместо недопустимого `F`. + +В C# нет типов высшего рода первого класса, поэтому `App` заменяет применение `F(a)`, восстановленное с помощью обёрток inject/project. Этот приём с `App` — и есть [дефункционализация](../concepts/defunctionalization.md): абстракция, которую язык не может выразить, становится данными первого порядка и применяется по требованию. Rust сталкивается с тем же ограничением: у него тоже нет типов высшего рода первого класса. +``` + +## Задайте небольшой синтаксис возможностей {#specify-tiny-syntax-capabilities} + +Каждому конструктору соответствует небольшой трейт. Это **спецификация (spec)**. + +```rust,noplayground +trait LitAlg { + type Expr; + + fn lit(&self, n: i64) -> Self::Expr; +} + +trait AddAlg { + type Expr; + + fn add(&self, a: Self::Expr, b: Self::Expr) -> Self::Expr; +} +``` + +Программы записываются как **расширения** поверх алгебр-трейтов. Эти расширения также входят в спецификацию: они компонуют небольшие спецификации в повторно используемые спецификации на уровне программы. + +```rust,noplayground +#[ext(name = ExprPrograms)] +impl This +where + This: LitAlg + AddAlg, +{ + fn expr_basic(&self) -> This::Expr { + self.add(self.lit(2), self.lit(3)) + } +} +``` + +`#[ext(...)]` — макрос из крейта [`extend`crate](https://docs.rs/extend/latest/extend/), который уменьшает шаблонный код, генерируя методы-расширения из блока `impl`; это не новая возможность языка Rust. + +## Добавьте новую интерпретацию {#add-new-interpretation} + +Интерпретаторы реализуют спецификацию. Менять синтаксис не нужно. + +```rust,noplayground +struct Eval; + +impl LitAlg for Eval { + type Expr = i64; + + fn lit(&self, n: i64) -> i64 { n } +} + +impl AddAlg for Eval { + type Expr = i64; + + fn add(&self, a: i64, b: i64) -> i64 { a + b } +} + +struct Pretty; + +impl LitAlg for Pretty { + type Expr = String; + + fn lit(&self, n: i64) -> String { n.to_string() } +} + +impl AddAlg for Pretty { + type Expr = String; + + fn add(&self, a: String, b: String) -> String { + format!("({a} + {b})") + } +} +``` + +Теперь одно и то же выражение можно интерпретировать по-разному: + +```rust,noplayground +let eval = Eval; +let pretty = Pretty; + +let v: i64 = eval.expr_basic(); // 5 +let s: String = pretty.expr_basic(); // "(2 + 3)" +``` + +## Добавьте новый синтаксис (новый трейт возможности) {#add-new-syntax-new-capability-trait} + +Чтобы добавить `Mul`, определите новый трейт. Существующий код не затрагивается. + +```rust,noplayground +trait MulAlg { + type Expr; + + fn mul(&self, a: Self::Expr, b: Self::Expr) -> Self::Expr; +} + +#[ext(name = ExprProgramsMul)] +impl This +where + This: LitAlg + AddAlg + MulAlg, +{ + fn expr_with_mul(&self) -> This::Expr { + self.mul(self.add(self.lit(2), self.lit(3)), self.lit(4)) + } +} +``` + +Существующие интерпретаторы продолжают работать с прежними выражениями. +Если им нужен новый синтаксис, они реализуют новый трейт: + +```rust,noplayground +impl MulAlg for Eval { + type Expr = i64; + + fn mul(&self, a: i64, b: i64) -> i64 { a * b } +} + +impl MulAlg for Pretty { + type Expr = String; + + fn mul(&self, a: String, b: String) -> String { + format!("({a} * {b})") + } +} +``` + +## Почему это решает проблему выражения {#why-this-solves-the-expression-problem} + +Традиционная проблема выражения задаёт два направления расширения представления: + +* добавление новых вариантов (случаев) +* добавление новых операций + +Денотационное проектирование переосмысливает эти направления: + +* **Расширить семантический словарь**: определить новый трейт возможности (`MulAlg`). +* **Добавить новую интерпретацию** словаря: определить новый тип интерпретатора (`Eval`, `Pretty`, построитель AST или генератор кода). + +Эти два направления компонуют независимо: + +* Существующие программы не меняются, если им не требуется новая возможность. `expr_basic`, как и прежде, требует только `LitAlg + AddAlg`. +* Существующие интерпретаторы не меняются, пока не решат интерпретировать новую возможность. `Eval` без `impl MulAlg` по-прежнему выполняет все программы, не использующие `mul`. + +Матрица реализаций никуда не исчезает. Если `Eval` и `Pretty` должны интерпретировать `mul`, обоим нужен `impl MulAlg`. Меняется организация матрицы: каждая ячейка — это *семантическая операция × интерпретация*; ни одна не строится вокруг привилегированного представления, и каждая программа зависит только от используемых ею возможностей. + +## Законы относятся к спецификации {#laws-belong-to-the-specification} + +Семантическая алгебра состоит из носителя, операций и законов. Носитель (`type Expr`) выбирает интерпретация; операции и законы принадлежат спецификации. Например, арифметический смысл `LitAlg + AddAlg` задаёт следующее: + +```text +add(lit(m), lit(n)) = lit(m + n) +``` + +`Eval` удовлетворяет этому закону. `Pretty` — нет: `"(2 + 3)"` не равно `"5"`. Оба интерпретатора реализуют сигнатуру синтаксиса, но моделью арифметической спецификации является только `Eval`. Закон один раз формулируется для трейтов и определяет, какие интерпретаторы подходят. Ни один интерпретатор не владеет законом. + +## Заключительная мысль: Featherweight Go и денотационное проектирование {#final-insight-featherweight-go-vs-denotational-design} + +Уодлер сформулировал проблему выражения на уровне механизмов языка: строки и столбцы при статической типизации и модульном расширении. [Featherweight Go](../concepts/expression-problem.md#featherweight-go-solution-2020) предлагает конкретное решение: `Plus(type a Any)` оставляет рекурсивное представление обобщённым, а каждая операция независимо ограничивает `a` (`Plus(type a Evaler)` для `Eval`, `Plus(type a Stringer)` для `String`). Представление не связано с одним закрытым интерфейсом выражений, поэтому оба направления остаются открытыми. + +Традиционные решения начинают с представления и ищут способ оставить открытыми оба направления расширения. Featherweight Go удивительно далеко продвигается, делая рекурсивное представление обобщённым и структурно расширяемым. Денотационное проектирование перемещает границу ещё на шаг раньше: представление — не модель. Модель — это алгебра и её законы; представление — лишь одна возможная интерпретация. + +**Featherweight Go делает представление расширяемым. Денотационное проектирование делает его необязательным.** + +| | Featherweight Go | Денотационное проектирование | +| --- | --- | --- | +| Семантический центр | расширяемое представление | алгебра и законы | +| `Num`/`Plus`, `lit`/`add` | структуры (формы представления) | семантические операции | +| `Eval`, `String`/`Pretty` | методы и интерфейсы | интерпретации | +| Рекурсивная структура | обобщённое открытое представление (`Plus(a)`) | не требуется | +| Носитель | тип представления выражения | выбирается интерпретатором (`type Expr`) | +| AST | представление остаётся центральным | необязателен, одна из многих интерпретаций | +| Ячейка матрицы | случай × операция → метод | семантическая операция × интерпретация → `impl` | +| Новое поведение | добавление методов и интерфейсов | добавление или композиция возможностей | +| Новая реализация | новые структурные реализации | новый интерпретатор | + +Уодлер спрашивает, как расширить оба направления представления. Денотационное проектирование спрашивает, почему представление должно владеть хотя бы одним из них. + +Сначала задайте композиционный смысл, затем выбирайте кодирование. Проблема выражения становится инженерным выбором между кодированиями, а не концептуальным тупиком. + +**Смысл языка должен быть независим от представления о машине.** + +
Смысл языка должен быть независим от машины
+ +## Источники {#references} + +* Эллиотт, К. *Denotational design with type class morphisms*. + [http://conal.net/papers/type-class-morphisms/](http://conal.net/papers/type-class-morphisms/) + +* Эллиотт, К. *Compiling to categories*. + [http://conal.net/papers/compiling-to-categories/](http://conal.net/papers/compiling-to-categories/) + +* Киселёв, О. *Стиль tagless-final* (обзор, учебные материалы и статьи о финальных кодированиях и расширяемых типизированных интерпретаторах). + [https://okmij.org/ftp/tagless-final/](https://okmij.org/ftp/tagless-final/) + +* Киселёв, О. *Having an Effect* (денотационное и определяющее изложение эффектов и расширяемых интерпретаторов). + [https://okmij.org/ftp/Computation/having-effect.html#defint](https://okmij.org/ftp/Computation/having-effect.html#defint) + +* Гриземер, Р., Ху, Р., Кокке, В., Ланге, Й., Тейлор, И. Л., Тониньо, Б., Уодлер, П. и Ёсида, Н. (2020). *Featherweight Go*. Proc. ACM Program. Lang. 4 (OOPSLA). В разделе 2.3 описано сравниваемое выше обобщённое структурное решение. + [https://homepages.inf.ed.ac.uk/wadler/papers/fg/fg.pdf](https://homepages.inf.ed.ac.uk/wadler/papers/fg/fg.pdf) + +* Оливейра, Б. К. д. С. и Кук, У. Р. (2012). *Extensibility for the Masses: Practical Extensibility with Object Algebras*. + [https://www.cs.utexas.edu/~wcook/Drafts/2012/ecoop2012.pdf](https://www.cs.utexas.edu/~wcook/Drafts/2012/ecoop2012.pdf) diff --git a/src/insights/expression-problem.uk.md b/src/insights/expression-problem.uk.md new file mode 100644 index 0000000..ebe5282 --- /dev/null +++ b/src/insights/expression-problem.uk.md @@ -0,0 +1,226 @@ + + +# Проблема виразів: новий погляд {#expression-problem-reloaded} + +```admonish tip title="Пов’язані матеріали" +Семантичний погляд: [Денотаційне проєктування](../denotational-design/design.md) +Проєктування від значення в Rust: [Алгебри можливостей](../rust-dd/capability-algebras.md), [Похідне значення та композиція](../rust-dd/derived-meaning.md), [Інтерпретатори й ефекти](../rust-dd/interpreters.md) +Поняття: [Проблема виразів](../concepts/expression-problem.md) +``` + +На цій сторінці наведено практичне рішення *проблеми виразів* на основі трейтів: як додавати нові форми виразів і нові операції, не переписуючи щоразу наявний код. За задумом це **підхід у стилі Конала**, а за кодуванням — **tagless-final / об’єктна алгебра**. Спочатку визначаємо композиційне значення (невеликі інтерфейси можливостей і специфікації програм на рівні розширень), а вже потім надаємо конкретні інтерпретатори. Це кодування належить до того самого сімейства, що й стиль **tagless-final** Олега Кісельова та **об’єктні алгебри**: інтерфейси конструкторів (`LitAlg`, `AddAlg`, `MulAlg`) визначають сигнатуру мови, програми записуються узагальнено через ці інтерфейси, а конкретні реалізації (наприклад, `Eval` чи `Pretty`) задають інтерпретації. Це дає змогу не прив’язуватися до одного закритого AST і водночас зберегти статичну типізацію та розширюваність у двох вимірах. + +Підхід Олега від початку є денотаційним: спершу призначити композиційні значення, а потім реалізувати ефекти й інтерпретатори як модульні семантичні рівні. Тому зв’язок із денотаційним проєктуванням у розв’язанні проблеми виразів очікуваний, а не випадковий. Формулювання денотаційного проєктування Коналом прямо визначає той самий пріоритет: спершу композиційно описати значення, а конкретні стратегії виконання вважати другорядними й замінними. + +Для прикладу з мовою виразів це кодування означає: + +* **Термінологію конструкторів** моделюють як невеликі незалежні трейти-алгебри. +* **Інтерпретації** — це реалізації цих трейтів. +* Новий синтаксис додає новий трейт, не зачіпаючи старий код. +* Нова семантика додає новий тип інтерпретатора, не зачіпаючи старий код. + +`lit` та `add` — семантичні операції, а не конструктори особливого AST. AST є лише однією з можливих інтерпретацій. + +```admonish example title="Об’єктні алгебри в C#" +Це кодування не прив’язане до Rust. Розділ [`object-algebras`](https://github.com/tgrospic/object-algebras) розвиває той самий патерн у C# і виходить за межі фіксованого носія, використаного тут. На цій сторінці кожен інтерпретатор вибирає один конкретний `Self::Expr` — звичайний тип. Натомість алгебри C# абстрагуються над конструктором типу *конструктором* `F` — `FunctorAlg`, `MonadAlg`, `BankingDsl` — і містять результати у вигляді `App` замість недозволеного `F
`. + +Оскільки C# не має типів вищого порядку першого класу, `App` замінює застосування `F(a)`, яке відновлюється обгортками inject/project. Цей трюк із `App` і є [дефункціоналізацією](../concepts/defunctionalization.md): абстракція, якої мова не може виразити, стає даними першого порядку й застосовується за потреби. Rust стикається з тією самою межею — у ньому теж немає типів вищого порядку першого класу. +``` + +## Задайте невеликі можливості синтаксису {#specify-tiny-syntax-capabilities} + +Кожен конструктор стає невеликим трейтом. Це і є **специфікація**. + +```rust,noplayground +trait LitAlg { + type Expr; + + fn lit(&self, n: i64) -> Self::Expr; +} + +trait AddAlg { + type Expr; + + fn add(&self, a: Self::Expr, b: Self::Expr) -> Self::Expr; +} +``` + +Програми записують як **розширення** над трейтами-алгебрами; вони також належать до специфікації й поєднують менші специфікації в повторно використовувані специфікації на рівні програм: + +```rust,noplayground +#[ext(name = ExprPrograms)] +impl This +where + This: LitAlg + AddAlg, +{ + fn expr_basic(&self) -> This::Expr { + self.add(self.lit(2), self.lit(3)) + } +} +``` + +`#[ext(...)]` — це макрос із крейту [`extend`](https://docs.rs/extend/latest/extend/), який скорочує шаблонний код, генеруючи методи-розширення з блоку `impl`. Це не нова функція мови Rust. + +## Додайте нову інтерпретацію {#add-new-interpretation} + +Інтерпретатори реалізують специфікацію. Змінювати синтаксис не потрібно. + +```rust,noplayground +struct Eval; + +impl LitAlg for Eval { + type Expr = i64; + + fn lit(&self, n: i64) -> i64 { n } +} + +impl AddAlg for Eval { + type Expr = i64; + + fn add(&self, a: i64, b: i64) -> i64 { a + b } +} + +struct Pretty; + +impl LitAlg for Pretty { + type Expr = String; + + fn lit(&self, n: i64) -> String { n.to_string() } +} + +impl AddAlg for Pretty { + type Expr = String; + + fn add(&self, a: String, b: String) -> String { + format!("({a} + {b})") + } +} +``` + +Тепер той самий вираз можна інтерпретувати по-різному: + +```rust,noplayground +let eval = Eval; +let pretty = Pretty; + +let v: i64 = eval.expr_basic(); // 5 +let s: String = pretty.expr_basic(); // "(2 + 3)" +``` + +## Додайте новий синтаксис (новий трейт можливостей) {#add-new-syntax-new-capability-trait} + +Щоб додати `Mul`, визначте новий трейт. Наявний код лишається без змін. + +```rust,noplayground +trait MulAlg { + type Expr; + + fn mul(&self, a: Self::Expr, b: Self::Expr) -> Self::Expr; +} + +#[ext(name = ExprProgramsMul)] +impl This +where + This: LitAlg + AddAlg + MulAlg, +{ + fn expr_with_mul(&self) -> This::Expr { + self.mul(self.add(self.lit(2), self.lit(3)), self.lit(4)) + } +} +``` + +Старі інтерпретатори й далі працюють зі старими виразами. +Якщо їм потрібен новий синтаксис, вони реалізують новий трейт: + +```rust,noplayground +impl MulAlg for Eval { + type Expr = i64; + + fn mul(&self, a: i64, b: i64) -> i64 { a * b } +} + +impl MulAlg for Pretty { + type Expr = String; + + fn mul(&self, a: String, b: String) -> String { + format!("({a} * {b})") + } +} +``` + +## Чому це розв’язує проблему виразів {#why-this-solves-the-expression-problem} + +У традиційній проблемі виразів є два виміри представлення: + +* додавати нові варіанти (випадки) +* додавати нові операції + +Денотаційне проєктування переосмислює ці виміри: + +* **Розширюйте семантичну термінологію**: визначайте новий трейт можливостей (`MulAlg`). +* **Додавайте нову інтерпретацію** цієї термінології: визначайте новий тип інтерпретатора (`Eval`, `Pretty`, будівельник AST чи генератор коду). + +Обидва виміри композиційно поєднуються незалежно: + +* Наявні програми не змінюються, якщо їм не потрібна нова можливість. `expr_basic` і далі вимагає лише `LitAlg + AddAlg`. +* Наявні інтерпретатори не змінюються, якщо не вирішать інтерпретувати нову можливість. `Eval` без `impl MulAlg` і далі виконує всі програми, що не використовують `mul`. + +Це не усуває матрицю реалізацій. Якщо `Eval` та `Pretty` мають інтерпретувати `mul`, обом потрібен `impl MulAlg`. Змінюється організація матриці: кожна клітинка — це *семантична операція × інтерпретація*; жодна не побудована навколо привілейованого представлення, а кожна програма залежить лише від використовуваних можливостей. + +## Закони належать до специфікації {#laws-belong-to-the-specification} + +Семантична алгебра складається з носія, операцій і законів. Носій (`type Expr`) вибирає інтерпретація, а операції й закони належать до специфікації. Наприклад, арифметичне значення `LitAlg + AddAlg` визначає, що: + +```text +add(lit(m), lit(n)) = lit(m + n) +``` + +`Eval` виконує цей закон, а `Pretty` — ні: `"(2 + 3)"` не дорівнює `"5"`. Обидва є допустимими інтерпретаторами сигнатури синтаксису, але лише `Eval` є моделлю арифметичної специфікації. Закон визначено один раз для трейтів і саме він визначає, які інтерпретатори підходять. Жоден інтерпретатор не володіє ним. + +## Підсумкове осяяння: Featherweight Go і денотаційне проєктування {#final-insight-featherweight-go-vs-denotational-design} + +Ведлер визначив проблему виразів на рівні механізмів мови: рядки й стовпці за умов статичної типізації та модульного розширення. [Featherweight Go](../concepts/expression-problem.md#featherweight-go-solution-2020) пропонує конкретне рішення: `Plus(type a Any)` зберігає рекурсивне представлення узагальненим, а кожна операція окремо обмежує `a` (`Plus(type a Evaler)` для `Eval`, `Plus(type a Stringer)` для `String`). Представлення не прив’язане до одного закритого інтерфейсу виразів, тож обидва виміри залишаються відкритими. + +Традиційні рішення починають із представлення й запитують, як залишити відкритими обидва виміри розширення. Featherweight Go просувається напрочуд далеко завдяки узагальненому рекурсивному представленню зі структурною розширюваністю. Денотаційне проєктування зміщує межу на крок раніше: представлення не є моделлю. Модель — це алгебра та її закони, а представлення — одна з можливих інтерпретацій. + +**Featherweight Go робить представлення розширюваним. Денотаційне проєктування робить представлення необов’язковим.** + +| | Featherweight Go | Денотаційне проєктування | +| --- | --- | --- | +| Семантичний центр | розширюване представлення | алгебра й закони | +| `Num`/`Plus`, `lit`/`add` | структури (форми представлення) | семантичні операції | +| `Eval`, `String`/`Pretty` | методи й інтерфейси | інтерпретації | +| Рекурсивна структура | узагальнене відкрите представлення (`Plus(a)`) | не потрібна | +| Носій | тип представленого виразу | вибирається інтерпретатором (`type Expr`) | +| AST | представлення лишається центральним | необов’язкове, одна з багатьох інтерпретацій | +| Клітинка матриці | випадок × операція → метод | семантична операція × інтерпретація → `impl` | +| Нова поведінка | додати методи й інтерфейси | додати або композиційно поєднати можливості | +| Нова реалізація | нові структурні реалізації | новий інтерпретатор | + +Ведлер питає, як розширювати обидва виміри представлення. Денотаційне проєктування питає, чому представлення взагалі має визначати будь-який із них. + +Спершу визначте композиційне значення, а потім вибирайте кодування. Проблема виразів перетвориться з концептуального глухого кута на інженерний вибір між кодуваннями. + +**Значення мови має не залежати від поняття машини.** + +
Значення мови має не залежати від машини
+ +## Джерела {#references} + +* Елліотт, К. *Denotational design with type class morphisms*. + [http://conal.net/papers/type-class-morphisms/](http://conal.net/papers/type-class-morphisms/) + +* Елліотт, К. *Compiling to categories*. + [http://conal.net/papers/compiling-to-categories/](http://conal.net/papers/compiling-to-categories/) + +* Кісельов, О. *Tagless-final style* (огляд, посібники й статті про фінальні кодування та розширювані типізовані інтерпретатори). + [https://okmij.org/ftp/tagless-final/](https://okmij.org/ftp/tagless-final/) + +* Кісельов, О. *Having an Effect* (денотаційне формулювання ефектів і розширюваних інтерпретаторів). + [https://okmij.org/ftp/Computation/having-effect.html#defint](https://okmij.org/ftp/Computation/having-effect.html#defint) + +* Гриземер, Р., Ху, Р., Кокке, В., Ланге, Й., Тейлор, А. Л., Тоніньо, Б., Ведлер, П. та Йошида, Н. (2020). *Featherweight Go*. Праці ACM з мов програмування 4 (OOPSLA). У розділі 2.3 наведено порівнюване вище узагальнене структурне рішення. + [https://homepages.inf.ed.ac.uk/wadler/papers/fg/fg.pdf](https://homepages.inf.ed.ac.uk/wadler/papers/fg/fg.pdf) + +* Олівейра, Б. К. д. С. і Кук, В. Р. (2012). *Extensibility for the Masses: Practical Extensibility with Object Algebras*. + [https://www.cs.utexas.edu/~wcook/Drafts/2012/ecoop2012.pdf](https://www.cs.utexas.edu/~wcook/Drafts/2012/ecoop2012.pdf) diff --git a/src/insights/expression-problem.vi.md b/src/insights/expression-problem.vi.md new file mode 100644 index 0000000..2b87dc3 --- /dev/null +++ b/src/insights/expression-problem.vi.md @@ -0,0 +1,226 @@ + + +# Bài toán biểu thức trở lại {#expression-problem-reloaded} + +```admonish tip title="Liên quan" +Góc nhìn ngữ nghĩa: [Thiết kế theo ngữ nghĩa](../denotational-design/design.md) +Thiết kế theo ngữ nghĩa trong Rust: [Các đại số năng lực](../rust-dd/capability-algebras.md), [Ý nghĩa suy ra và phép hợp thành](../rust-dd/derived-meaning.md), [Bộ diễn giải và hiệu ứng](../rust-dd/interpreters.md) +Khái niệm: [Bài toán biểu thức](../concepts/expression-problem.md) +``` + +Trang này trình bày giải pháp thực tiễn dựa trên đặc trưng cho *Bài toán biểu thức*: làm sao thêm dạng biểu thức và phép toán mới mà không phải liên tục viết lại mã hiện có. Thiết kế của giải pháp theo phong cách **Conal**, còn cách mã hóa thuộc kiểu **tagless-final/đại số đối tượng**. Cụ thể, trước hết ta đặc tả ý nghĩa hợp thành (các giao diện năng lực nhỏ và đặc tả chương trình ở cấp phần mở rộng), rồi mới cung cấp các bộ diễn giải cụ thể. Cách mã hóa cụ thể thuộc cùng họ với phong cách **tagless-final** của Oleg Kiselyov và **đại số đối tượng**: giao diện cấu trúc (`LitAlg`, `AddAlg`, `MulAlg`) định nghĩa chữ ký ngôn ngữ, chương trình được viết đa hình dựa trên các giao diện đó, còn các cách triển khai cụ thể như `Eval` hoặc `Pretty` cung cấp cách diễn giải. Nhờ vậy, không cần cam kết với một AST đóng duy nhất mà vẫn giữ được kiểu tĩnh và khả năng mở rộng theo cả hai chiều. + +Cách tiếp cận của Oleg tường minh mang tính ngữ nghĩa chỉ định: trước hết gán ý nghĩa hợp thành, rồi hiện thực hóa hiệu ứng/bộ diễn giải thành các lớp ngữ nghĩa mô-đun. Với Bài toán biểu thức, vì vậy sự tương hợp với Thiết kế theo ngữ nghĩa là có chủ ý chứ không phải ngẫu nhiên. Cách trình bày Thiết kế theo ngữ nghĩa của Conal nêu trực tiếp cùng ưu tiên: trước hết đặc tả ý nghĩa theo tính hợp thành, còn chiến lược thực thi cụ thể là thứ yếu và có thể thay thế. + +Với ví dụ ngôn ngữ biểu thức, cách mã hóa này có nghĩa: + +* **Từ vựng cấu trúc tạo** được mô hình hóa thành các đặc trưng đại số nhỏ, độc lập. +* **Các cách diễn giải** là những cách triển khai các đặc trưng đó. +* Cú pháp mới bổ sung đặc trưng mới mà không đụng đến mã cũ. +* Ngữ nghĩa mới bổ sung kiểu bộ diễn giải mới mà không đụng đến mã cũ. + +`lit` và `add` là các phép toán ngữ nghĩa, không phải cấu trúc tạo của một AST được ưu tiên. AST chỉ là một cách diễn giải trong số nhiều cách. + +```admonish example title="Đại số đối tượng trong C#" +Cách mã hóa này không riêng cho Rust. [`object-algebras`](https://github.com/tgrospic/object-algebras) phát triển mẫu này trong C# và vượt qua đối tượng mang cố định dùng ở đây. Trên trang này, mỗi bộ diễn giải chọn một `Self::Expr` cụ thể, tức kiểu thông thường. Thay vào đó, đại số C# trừu tượng hóa trên *bộ dựng* kiểu `F` — `FunctorAlg`, `MonadAlg`, `BankingDsl` — mang kết quả dưới dạng `App` thay cho `F
` bất hợp lệ. + +C# không có kiểu bậc cao hạng nhất, vì vậy `App` thay mặt cho phép áp dụng `F(a)`, được khôi phục qua các lớp bọc inject/project. Mẹo `App` này chính là [phi chức năng hóa](../concepts/defunctionalization.md): phép trừu tượng mà ngôn ngữ không thể biểu đạt được chuyển thành dữ liệu bậc nhất để áp dụng khi cần. Rust cũng chạm cùng giới hạn — ngôn ngữ này cũng thiếu kiểu bậc cao hạng nhất. +``` + +## Đặc tả các năng lực cú pháp nhỏ {#specify-tiny-syntax-capabilities} + +Mỗi cấu trúc tạo trở thành một đặc trưng nhỏ. Đây là **đặc tả**. + +```rust,noplayground +trait LitAlg { + type Expr; + + fn lit(&self, n: i64) -> Self::Expr; +} + +trait AddAlg { + type Expr; + + fn add(&self, a: Self::Expr, b: Self::Expr) -> Self::Expr; +} +``` + +Chương trình được viết dưới dạng **phần mở rộng** trên các đặc trưng đại số; phần mở rộng này cũng là một phần của đặc tả và kết hợp các đặc tả nhỏ thành đặc tả chương trình có thể tái sử dụng: + +```rust,noplayground +#[ext(name = ExprPrograms)] +impl This +where + This: LitAlg + AddAlg, +{ + fn expr_basic(&self) -> This::Expr { + self.add(self.lit(2), self.lit(3)) + } +} +``` + +`#[ext(...)]` là macro từ crate [`extend`](https://docs.rs/extend/latest/extend/), dùng để giảm mã khuôn mẫu bằng cách tạo phương thức mở rộng từ khối `impl`; đây không phải tính năng mới của ngôn ngữ Rust. + +## Thêm cách diễn giải mới {#add-new-interpretation} + +Bộ diễn giải triển khai đặc tả. Không cần thay đổi cú pháp. + +```rust,noplayground +struct Eval; + +impl LitAlg for Eval { + type Expr = i64; + + fn lit(&self, n: i64) -> i64 { n } +} + +impl AddAlg for Eval { + type Expr = i64; + + fn add(&self, a: i64, b: i64) -> i64 { a + b } +} + +struct Pretty; + +impl LitAlg for Pretty { + type Expr = String; + + fn lit(&self, n: i64) -> String { n.to_string() } +} + +impl AddAlg for Pretty { + type Expr = String; + + fn add(&self, a: String, b: String) -> String { + format!("({a} + {b})") + } +} +``` + +Giờ cùng biểu thức có thể được diễn giải theo cách khác: + +```rust,noplayground +let eval = Eval; +let pretty = Pretty; + +let v: i64 = eval.expr_basic(); // 5 +let s: String = pretty.expr_basic(); // "(2 + 3)" +``` + +## Thêm cú pháp mới (đặc trưng năng lực mới) {#add-new-syntax-new-capability-trait} + +Để thêm `Mul`, hãy định nghĩa đặc trưng mới. Mã hiện có vẫn nguyên vẹn. + +```rust,noplayground +trait MulAlg { + type Expr; + + fn mul(&self, a: Self::Expr, b: Self::Expr) -> Self::Expr; +} + +#[ext(name = ExprProgramsMul)] +impl This +where + This: LitAlg + AddAlg + MulAlg, +{ + fn expr_with_mul(&self) -> This::Expr { + self.mul(self.add(self.lit(2), self.lit(3)), self.lit(4)) + } +} +``` + +Các bộ diễn giải hiện có vẫn hoạt động với biểu thức cũ. +Nếu muốn hỗ trợ cú pháp mới, chúng triển khai đặc trưng mới: + +```rust,noplayground +impl MulAlg for Eval { + type Expr = i64; + + fn mul(&self, a: i64, b: i64) -> i64 { a * b } +} + +impl MulAlg for Pretty { + type Expr = String; + + fn mul(&self, a: String, b: String) -> String { + format!("({a} * {b})") + } +} +``` + +## Vì sao cách này giải quyết Bài toán biểu thức {#why-this-solves-the-expression-problem} + +Bài toán biểu thức truyền thống có hai trục trên một cách biểu diễn: + +* thêm biến thể mới (trường hợp) +* thêm phép toán mới + +Thiết kế theo ngữ nghĩa diễn đạt lại hai trục: + +* **Mở rộng từ vựng ngữ nghĩa**: định nghĩa đặc trưng năng lực mới (`MulAlg`). +* **Thêm cách diễn giải mới** cho từ vựng đó: định nghĩa kiểu bộ diễn giải mới (`Eval`, `Pretty`, bộ dựng AST hoặc bộ sinh mã). + +Hai trục hợp thành độc lập: + +* Chương trình hiện có không thay đổi trừ khi chúng cần năng lực mới. `expr_basic` vẫn chỉ yêu cầu `LitAlg + AddAlg`. +* Bộ diễn giải hiện có không thay đổi trừ khi chúng chọn diễn giải năng lực mới. `Eval` không có `impl MulAlg` vẫn chạy mọi chương trình không dùng đến `mul`. + +Cách này không loại bỏ ma trận triển khai. Nếu `Eval` và `Pretty` đều cần diễn giải `mul` thì cả hai đều cần `impl MulAlg`. Điều thay đổi là cách tổ chức ma trận: mỗi ô là *phép toán ngữ nghĩa × cách diễn giải*, không ô nào xoay quanh cách biểu diễn được ưu tiên, và mỗi chương trình chỉ phụ thuộc vào các năng lực nó sử dụng. + +## Định luật thuộc về đặc tả {#laws-belong-to-the-specification} + +Đại số ngữ nghĩa gồm đối tượng mang, phép toán và định luật. Đối tượng mang (`type Expr`) do cách diễn giải chọn; phép toán và định luật thuộc về đặc tả. Chẳng hạn, ý nghĩa số học của `LitAlg + AddAlg` phát biểu: + +```text +add(lit(m), lit(n)) = lit(m + n) +``` + +`Eval` thỏa mãn định luật này. `Pretty` thì không: `"(2 + 3)"` không bằng `"5"`. Cả hai đều là bộ diễn giải hợp lệ cho chữ ký cú pháp, nhưng chỉ `Eval` là mô hình của đặc tả số học. Định luật được phát biểu một lần dựa trên các đặc trưng và quyết định bộ diễn giải nào đạt yêu cầu. Không bộ diễn giải nào sở hữu nó. + +## Nhận định cuối: Featherweight Go và Thiết kế theo ngữ nghĩa {#final-insight-featherweight-go-vs-denotational-design} + +Wadler chẩn đoán Bài toán biểu thức ở cấp cơ chế ngôn ngữ: hàng và cột dưới ràng buộc kiểu tĩnh và khả năng mở rộng mô-đun. [Featherweight Go](../concepts/expression-problem.md#featherweight-go-solution-2020) đưa ra giải pháp cụ thể: `Plus(type a Any)` giữ biểu diễn đệ quy ở dạng tổng quát, còn từng phép toán đặt ràng buộc riêng lên `a` (`Plus(type a Evaler)` cho `Eval`, `Plus(type a Stringer)` cho `String`). Cách biểu diễn không bị gắn với một giao diện biểu thức đóng, nên cả hai trục vẫn mở. + +Các giải pháp truyền thống bắt đầu từ cách biểu diễn rồi hỏi làm sao mở cả hai trục mở rộng. Featherweight Go đẩy ý tưởng này đi khá xa khi làm cho biểu diễn đệ quy tổng quát và có thể mở rộng theo cấu trúc. Thiết kế theo ngữ nghĩa đẩy ranh giới sớm hơn một bước: biểu diễn không phải mô hình. Mô hình là đại số và các định luật của nó; biểu diễn là một cách diễn giải khả dĩ. + +**Featherweight Go giúp mở rộng cách biểu diễn. Thiết kế theo ngữ nghĩa khiến biểu diễn trở thành tùy chọn.** + +| | Featherweight Go | Thiết kế theo ngữ nghĩa | +| --- | --- | --- | +| Trung tâm ngữ nghĩa | biểu diễn có thể mở rộng | đại số và định luật | +| `Num`/`Plus`, `lit`/`add` | cấu trúc (dạng biểu diễn) | phép toán ngữ nghĩa | +| `Eval`, `String`/`Pretty` | phương thức và giao diện | cách diễn giải | +| Cấu trúc đệ quy | biểu diễn tổng quát, mở (`Plus(a)`) | không bắt buộc | +| Đối tượng mang | kiểu biểu thức được biểu diễn | do bộ diễn giải chọn (`type Expr`) | +| AST | biểu diễn vẫn là trung tâm | tùy chọn, là một trong nhiều cách diễn giải | +| Ô ma trận | trường hợp × phép toán → phương thức | phép toán ngữ nghĩa × cách diễn giải → `impl` | +| Hành vi mới | thêm phương thức và giao diện | thêm hoặc hợp thành năng lực | +| Cách triển khai mới | các hiện thực hóa cấu trúc mới | bộ diễn giải mới | + +Wadler hỏi cách mở rộng cả hai trục của một cách biểu diễn. Thiết kế theo ngữ nghĩa hỏi vì sao cách biểu diễn phải sở hữu trục nào trong hai trục. + +Trước hết định nghĩa ý nghĩa hợp thành, rồi chọn cách mã hóa. Bài toán biểu thức trở thành lựa chọn kỹ thuật giữa các cách mã hóa, chứ không còn là bế tắc khái niệm. + +**Ý nghĩa của ngôn ngữ cần độc lập với khái niệm máy móc.** + +
Ý nghĩa của ngôn ngữ cần độc lập với máy móc
+ +## Tài liệu tham khảo {#references} + +* Elliott, C. *Denotational design with type class morphisms*. + [http://conal.net/papers/type-class-morphisms/](http://conal.net/papers/type-class-morphisms/) + +* Elliott, C. *Compiling to categories*. + [http://conal.net/papers/compiling-to-categories/](http://conal.net/papers/compiling-to-categories/) + +* Kiselyov, O. *Tagless-final style* (tổng quan, hướng dẫn và bài viết về mã hóa final và bộ diễn giải có kiểu mở rộng). + [https://okmij.org/ftp/tagless-final/](https://okmij.org/ftp/tagless-final/) + +* Kiselyov, O. *Having an Effect* (cách trình bày hiệu ứng theo hướng định nghĩa/ngữ nghĩa chỉ định và bộ diễn giải mở rộng). + [https://okmij.org/ftp/Computation/having-effect.html#defint](https://okmij.org/ftp/Computation/having-effect.html#defint) + +* Griesemer, R., Hu, R., Kokke, W., Lange, J., Taylor, I. L., Toninho, B., Wadler, P. và Yoshida, N. (2020). *Featherweight Go*. Proc. ACM Program. Lang. 4 (OOPSLA). Mục 2.3 trình bày giải pháp cấu trúc tổng quát được so sánh ở trên. + [https://homepages.inf.ed.ac.uk/wadler/papers/fg/fg.pdf](https://homepages.inf.ed.ac.uk/wadler/papers/fg/fg.pdf) + +* Oliveira, B. C. d. S. và Cook, W. R. (2012). *Extensibility for the Masses: Practical Extensibility with Object Algebras*. + [https://www.cs.utexas.edu/~wcook/Drafts/2012/ecoop2012.pdf](https://www.cs.utexas.edu/~wcook/Drafts/2012/ecoop2012.pdf) diff --git a/src/insights/expression-problem.zh-hant.md b/src/insights/expression-problem.zh-hant.md new file mode 100644 index 0000000..e7b63b4 --- /dev/null +++ b/src/insights/expression-problem.zh-hant.md @@ -0,0 +1,226 @@ + + +# 重新審視表示式問題 {#expression-problem-reloaded} + +```admonish tip title="相關內容" +語義視角:[指稱設計](../denotational-design/design.md) +Rust 中的語義驅動設計:[能力代數](../rust-dd/capability-algebras.md)、[派生含義與組合](../rust-dd/derived-meaning.md)、[直譯器與效應](../rust-dd/interpreters.md) +概念:[表示式問題](../concepts/expression-problem.md) +``` + +本頁介紹一種基於 trait 的實用解法來處理*表示式問題*:如何新增新的表示式形式與操作,而不必反覆重寫現有程式碼。 該解法的設計**遵循 Conal 風格**,編碼方式則採用**無標籤最終編碼/物件代數**。具體而言,我們先規定可組合含義(小型能力介面與擴充層面的程式規範),再提供具體直譯器。這種編碼與 Oleg Kiselyov 的**無標籤最終**風格及**物件代數**屬於同一型別:構造器介面(`LitAlg`、`AddAlg`、`MulAlg`)定義語言簽名,程式以多型方式針對這些介面編寫,具體實作(例如`Eval`或`Pretty`)則提供解釋。這樣既避免繫結到某個封閉 AST,又保留了兩個維度上的靜態型別與可擴充性。 + +Oleg 的方法明確採用指稱式設計:先賦予可組合含義,再將效應與直譯器實現為模組化語義層。對於表示式問題而言,這正是它與指稱設計契合的原因,而非偶然。Conal 對指稱設計的表述也明確提出相同優先順序:先以組合方式規定含義,再將具體執行策略視為次要且可替換的部分。 + +對於表示式語言示例,這種編碼意味著: + +* **構造器詞彙**由小型、獨立的代數 trait 建模。 +* **解釋**是這些 trait 的實作。 +* 新語法會新增新 trait,而不觸碰舊程式碼。 +* 新語義會新增新的直譯器型別,而不觸碰舊程式碼。 + +`lit`與`add`是語義操作,而非特權 AST 的構造器。AST 只是多種解釋中的一種。 + +```admonish example title="C# 中的物件代數" +這種編碼並非 Rust 特有。[`object-algebras`](https://github.com/tgrospic/object-algebras)在 C# 中發展了這一模式,並突破了本頁採用的固定載體。在本頁中,每個直譯器會選擇一個具體的`Self::Expr`普通型別。而 C# 代數會抽象出一個型別*構造器*`F`——`FunctorAlg`、`MonadAlg`、`BankingDsl`——並將結果作為`App`承載,而不是採用不合法的`F
`。 + +C# 沒有一等高階型別,因此以`App`代替應用`F(a)`,並透過注入/投影包裝器還原。這種`App`技巧正是[去函式化](../concepts/defunctionalization.md):語言無法表達的抽象被轉為一階資料,並在需要時應用。Rust 也遇到了同樣的限制——它同樣缺少一等高階型別。 +``` + +## 規定小型語法能力 {#specify-tiny-syntax-capabilities} + +每種構造器都會成為一個小型 trait。這就是**規範**。 + +```rust,noplayground +trait LitAlg { + type Expr; + + fn lit(&self, n: i64) -> Self::Expr; +} + +trait AddAlg { + type Expr; + + fn add(&self, a: Self::Expr, b: Self::Expr) -> Self::Expr; +} +``` + +程式以代數 trait 之上的**擴充**形式編寫。這些擴充也屬於規範,並可將較小規範組合為可複用的程式級規範: + +```rust,noplayground +#[ext(name = ExprPrograms)] +impl This +where + This: LitAlg + AddAlg, +{ + fn expr_basic(&self) -> This::Expr { + self.add(self.lit(2), self.lit(3)) + } +} +``` + +`#[ext(...)]`是來自[`extend`crate 的宏](https://docs.rs/extend/latest/extend/),用於從`impl`塊中生成擴充方法以減少樣板程式碼;它不是新的 Rust 語言特性。 + +## 新增新的解釋 {#add-new-interpretation} + +直譯器實作規範,無需修改語法。 + +```rust,noplayground +struct Eval; + +impl LitAlg for Eval { + type Expr = i64; + + fn lit(&self, n: i64) -> i64 { n } +} + +impl AddAlg for Eval { + type Expr = i64; + + fn add(&self, a: i64, b: i64) -> i64 { a + b } +} + +struct Pretty; + +impl LitAlg for Pretty { + type Expr = String; + + fn lit(&self, n: i64) -> String { n.to_string() } +} + +impl AddAlg for Pretty { + type Expr = String; + + fn add(&self, a: String, b: String) -> String { + format!("({a} + {b})") + } +} +``` + +現在,同一個表示式可以有不同的解釋: + +```rust,noplayground +let eval = Eval; +let pretty = Pretty; + +let v: i64 = eval.expr_basic(); // 5 +let s: String = pretty.expr_basic(); // "(2 + 3)" +``` + +## 新增新語法(新能力 trait) {#add-new-syntax-new-capability-trait} + +要新增`Mul`,只需定義一個新 trait。現有程式碼保持不變。 + +```rust,noplayground +trait MulAlg { + type Expr; + + fn mul(&self, a: Self::Expr, b: Self::Expr) -> Self::Expr; +} + +#[ext(name = ExprProgramsMul)] +impl This +where + This: LitAlg + AddAlg + MulAlg, +{ + fn expr_with_mul(&self) -> This::Expr { + self.mul(self.add(self.lit(2), self.lit(3)), self.lit(4)) + } +} +``` + +現有直譯器仍可處理舊表示式。 +如果它們需要支援新語法,就實作新 trait: + +```rust,noplayground +impl MulAlg for Eval { + type Expr = i64; + + fn mul(&self, a: i64, b: i64) -> i64 { a * b } +} + +impl MulAlg for Pretty { + type Expr = String; + + fn mul(&self, a: String, b: String) -> String { + format!("({a} * {b})") + } +} +``` + +## 為什麼這能解決表示式問題 {#why-this-solves-the-expression-problem} + +傳統表示式問題包含表示上的兩個維度: + +* 新增新的變體(分支) +* 新增新操作 + +指稱設計重新詮釋了這兩個維度: + +* **擴充語義詞彙**:定義新的能力 trait(`MulAlg`)。 +* **為該詞彙新增新的解釋**:定義新的直譯器型別(`Eval`、`Pretty`、AST 構造器或程式碼生成器)。 + +這兩個維度可以獨立組合: + +* 除非需要新能力,否則現有程式無需修改。`expr_basic`仍然只要求`LitAlg + AddAlg`。 +* 除非選擇解釋新能力,否則現有直譯器無需修改。`Eval`即使沒有`impl MulAlg`,仍可執行所有不使用`mul`的程式。 + +這並沒有消除實作矩陣。如果`Eval`與`Pretty`都需要解釋`mul`,二者都需要`impl MulAlg`。變化在於矩陣的組織方式:每個單元格都是*語義操作 × 解釋*;沒有任何單元格圍繞特權表示組織;每個程式只依賴自己使用的能力。 + +## 定律屬於規範 {#laws-belong-to-the-specification} + +語義代數由載體、操作與定律構成。載體(`type Expr`)由解釋選擇;操作與定律則屬於規範。例如,算術含義`LitAlg + AddAlg`規定: + +```text +add(lit(m), lit(n)) = lit(m + n) +``` + +`Eval`滿足這條定律。`Pretty`則不滿足:`"(2 + 3)"`並不等於`"5"`。二者都是語法簽名的有效解釋,但只有`Eval`才是算術規範的模型。這條定律只需針對 trait 陳述一次,並由它決定哪些直譯器符合要求。它不屬於任何直譯器。 + +## 最終洞見:輕量級 Go 與指稱設計 {#final-insight-featherweight-go-vs-denotational-design} + +Wadler 在語言機制層面診斷了表示式問題:靜態型別與模組化擴充下的行列問題。[輕量級 Go](../concepts/expression-problem.md#featherweight-go-solution-2020)給出了一種具體解法:`Plus(type a Any)`保持遞迴表示的泛型性,並讓每種操作獨立約束`a`(`Plus(type a Evaler)`對應`Eval`,`Plus(type a Stringer)`對應`String`)。表示不會繫結到某個封閉表示式介面,因此兩個維度都保持開放。 + +傳統解法從表示出發,思考如何開放兩個擴充維度。輕量級 Go 將這一點推進得出人意料地遠:它讓遞迴表示具有泛型性與結構可擴充性。指稱設計則將邊界提前了一步:表示並非模型。模型是代數及其定律;表示只是可能的解釋之一。 + +**輕量級 Go 讓表示可以擴充。指稱設計讓表示成為可選項。** + +| | 輕量級 Go | 指稱設計 | +| --- | --- | --- | +| 語義核心 | 可擴充表示 | 代數與定律 | +| `Num`/`Plus`, `lit`/`add` | 結構(表示形式) | 語義操作 | +| `Eval`, `String`/`Pretty` | 方法與介面 | 解釋 | +| 遞迴結構 | 泛型、開放表示(`Plus(a)`) | 無需遞迴表示 | +| 載體 | 所表示的表示式型別 | 由直譯器選擇(`type Expr`) | +| AST | 表示仍居於核心 | 可選,是多種解釋之一 | +| 矩陣單元格 | 分支 × 操作 → 方法 | 語義操作 × 解釋 → `impl` | +| 新行為 | 新增方法與介面 | 新增或組合能力 | +| 新實作 | 新的結構實現 | 新的直譯器 | + +Wadler 詢問如何擴充表示的兩個維度。指稱設計則詢問為什麼表示應當掌握這兩個維度。 + +先定義可組合含義,再選擇編碼。這樣,表示式問題就成為編碼之間的工程選擇,而不再是概念上的死結。 + +**語言的含義應獨立於機器這一概念。** + +
語言的含義應獨立於機器
+ +## 參考文獻 {#references} + +* Elliott, C. *《藉助型別類態射進行指稱設計》*。 + [http://conal.net/papers/type-class-morphisms/](http://conal.net/papers/type-class-morphisms/) + +* Elliott, C. *《編譯到範疇》*。 + [http://conal.net/papers/compiling-to-categories/](http://conal.net/papers/compiling-to-categories/) + +* Kiselyov, O. *《無標籤最終風格》*(關於最終編碼與可擴充型別直譯器的概覽、教程與論文)。 + [https://okmij.org/ftp/tagless-final/](https://okmij.org/ftp/tagless-final/) + +* Kiselyov, O. *《擁有一種效應》*(對效應與可擴充直譯器的定義式/指稱式闡述)。 + [https://okmij.org/ftp/Computation/having-effect.html#defint](https://okmij.org/ftp/Computation/having-effect.html#defint) + +* Griesemer, R., Hu, R., Kokke, W., Lange, J., Taylor, I. L., Toninho, B., Wadler, P. 與 Yoshida, N.(2020)。*《輕量級 Go》*。ACM Program. Lang. 4(OOPSLA)。第 2.3 節給出了上文比較的泛型結構化解法。 + [https://homepages.inf.ed.ac.uk/wadler/papers/fg/fg.pdf](https://homepages.inf.ed.ac.uk/wadler/papers/fg/fg.pdf) + +* Oliveira, B. C. d. S. 與 Cook, W. R.(2012)。*《面向大眾的可擴充性:借助物件代數實現實用的可擴充設計》*。 + [https://www.cs.utexas.edu/~wcook/Drafts/2012/ecoop2012.pdf](https://www.cs.utexas.edu/~wcook/Drafts/2012/ecoop2012.pdf) diff --git a/src/insights/expression-problem.zh.md b/src/insights/expression-problem.zh.md new file mode 100644 index 0000000..854832c --- /dev/null +++ b/src/insights/expression-problem.zh.md @@ -0,0 +1,226 @@ + + +# 重新审视表达式问题 {#expression-problem-reloaded} + +```admonish tip title="相关内容" +语义视角:[指称设计](../denotational-design/design.md) +Rust 中的语义驱动设计:[能力代数](../rust-dd/capability-algebras.md)、[派生含义与组合](../rust-dd/derived-meaning.md)、[解释器与效应](../rust-dd/interpreters.md) +概念:[表达式问题](../concepts/expression-problem.md) +``` + +本页介绍一种基于 trait 的实用解法来处理*表达式问题*:如何添加新的表达式形式与操作,而不必反复重写现有代码。 该解法的设计**遵循 Conal 风格**,编码方式则采用**无标签最终编码/对象代数**。具体而言,我们先规定可组合含义(小型能力接口与扩展层面的程序规范),再提供具体解释器。这种编码与 Oleg Kiselyov 的**无标签最终**风格及**对象代数**属于同一类型:构造器接口(`LitAlg`、`AddAlg`、`MulAlg`)定义语言签名,程序以多态方式针对这些接口编写,具体实现(例如`Eval`或`Pretty`)则提供解释。这样既避免绑定到某个封闭 AST,又保留了两个维度上的静态类型与可扩展性。 + +Oleg 的方法明确采用指称式设计:先赋予可组合含义,再将效应与解释器实现为模块化语义层。对于表达式问题而言,这正是它与指称设计契合的原因,而非偶然。Conal 对指称设计的表述也明确提出相同优先级:先以组合方式规定含义,再将具体执行策略视为次要且可替换的部分。 + +对于表达式语言示例,这种编码意味着: + +* **构造器词汇**由小型、独立的代数 trait 建模。 +* **解释**是这些 trait 的实现。 +* 新语法会添加新 trait,而不触碰旧代码。 +* 新语义会添加新的解释器类型,而不触碰旧代码。 + +`lit`与`add`是语义操作,而非特权 AST 的构造器。AST 只是多种解释中的一种。 + +```admonish example title="C# 中的对象代数" +这种编码并非 Rust 特有。[`object-algebras`](https://github.com/tgrospic/object-algebras)在 C# 中发展了这一模式,并突破了本页采用的固定载体。在本页中,每个解释器会选择一个具体的`Self::Expr`普通类型。而 C# 代数会抽象出一个类型*构造器*`F`——`FunctorAlg`、`MonadAlg`、`BankingDsl`——并将结果作为`App`承载,而不是采用不合法的`F
`。 + +C# 没有一等高阶类型,因此以`App`代替应用`F(a)`,并通过注入/投影包装器还原。这种`App`技巧正是[去函数化](../concepts/defunctionalization.md):语言无法表达的抽象被转为一阶数据,并在需要时应用。Rust 也遇到了同样的限制——它同样缺少一等高阶类型。 +``` + +## 规定小型语法能力 {#specify-tiny-syntax-capabilities} + +每种构造器都会成为一个小型 trait。这就是**规范**。 + +```rust,noplayground +trait LitAlg { + type Expr; + + fn lit(&self, n: i64) -> Self::Expr; +} + +trait AddAlg { + type Expr; + + fn add(&self, a: Self::Expr, b: Self::Expr) -> Self::Expr; +} +``` + +程序以代数 trait 之上的**扩展**形式编写。这些扩展也属于规范,并可将较小规范组合为可复用的程序级规范: + +```rust,noplayground +#[ext(name = ExprPrograms)] +impl This +where + This: LitAlg + AddAlg, +{ + fn expr_basic(&self) -> This::Expr { + self.add(self.lit(2), self.lit(3)) + } +} +``` + +`#[ext(...)]`是来自[`extend`crate 的宏](https://docs.rs/extend/latest/extend/),用于从`impl`块中生成扩展方法以减少样板代码;它不是新的 Rust 语言特性。 + +## 添加新的解释 {#add-new-interpretation} + +解释器实现规范,无需修改语法。 + +```rust,noplayground +struct Eval; + +impl LitAlg for Eval { + type Expr = i64; + + fn lit(&self, n: i64) -> i64 { n } +} + +impl AddAlg for Eval { + type Expr = i64; + + fn add(&self, a: i64, b: i64) -> i64 { a + b } +} + +struct Pretty; + +impl LitAlg for Pretty { + type Expr = String; + + fn lit(&self, n: i64) -> String { n.to_string() } +} + +impl AddAlg for Pretty { + type Expr = String; + + fn add(&self, a: String, b: String) -> String { + format!("({a} + {b})") + } +} +``` + +现在,同一个表达式可以有不同的解释: + +```rust,noplayground +let eval = Eval; +let pretty = Pretty; + +let v: i64 = eval.expr_basic(); // 5 +let s: String = pretty.expr_basic(); // "(2 + 3)" +``` + +## 添加新语法(新能力 trait) {#add-new-syntax-new-capability-trait} + +要添加`Mul`,只需定义一个新 trait。现有代码保持不变。 + +```rust,noplayground +trait MulAlg { + type Expr; + + fn mul(&self, a: Self::Expr, b: Self::Expr) -> Self::Expr; +} + +#[ext(name = ExprProgramsMul)] +impl This +where + This: LitAlg + AddAlg + MulAlg, +{ + fn expr_with_mul(&self) -> This::Expr { + self.mul(self.add(self.lit(2), self.lit(3)), self.lit(4)) + } +} +``` + +现有解释器仍可处理旧表达式。 +如果它们需要支持新语法,就实现新 trait: + +```rust,noplayground +impl MulAlg for Eval { + type Expr = i64; + + fn mul(&self, a: i64, b: i64) -> i64 { a * b } +} + +impl MulAlg for Pretty { + type Expr = String; + + fn mul(&self, a: String, b: String) -> String { + format!("({a} * {b})") + } +} +``` + +## 为什么这能解决表达式问题 {#why-this-solves-the-expression-problem} + +传统表达式问题包含表示上的两个维度: + +* 添加新的变体(分支) +* 添加新操作 + +指称设计重新诠释了这两个维度: + +* **扩展语义词汇**:定义新的能力 trait(`MulAlg`)。 +* **为该词汇添加新的解释**:定义新的解释器类型(`Eval`、`Pretty`、AST 构造器或代码生成器)。 + +这两个维度可以独立组合: + +* 除非需要新能力,否则现有程序无需修改。`expr_basic`仍然只要求`LitAlg + AddAlg`。 +* 除非选择解释新能力,否则现有解释器无需修改。`Eval`即使没有`impl MulAlg`,仍可运行所有不使用`mul`的程序。 + +这并没有消除实现矩阵。如果`Eval`与`Pretty`都需要解释`mul`,二者都需要`impl MulAlg`。变化在于矩阵的组织方式:每个单元格都是*语义操作 × 解释*;没有任何单元格围绕特权表示组织;每个程序只依赖自己使用的能力。 + +## 定律属于规范 {#laws-belong-to-the-specification} + +语义代数由载体、操作与定律构成。载体(`type Expr`)由解释选择;操作与定律则属于规范。例如,算术含义`LitAlg + AddAlg`规定: + +```text +add(lit(m), lit(n)) = lit(m + n) +``` + +`Eval`满足这条定律。`Pretty`则不满足:`"(2 + 3)"`并不等于`"5"`。二者都是语法签名的有效解释,但只有`Eval`才是算术规范的模型。这条定律只需针对 trait 陈述一次,并由它决定哪些解释器符合要求。它不属于任何解释器。 + +## 最终洞见:轻量级 Go 与指称设计 {#final-insight-featherweight-go-vs-denotational-design} + +Wadler 在语言机制层面诊断了表达式问题:静态类型与模块化扩展下的行列问题。[轻量级 Go](../concepts/expression-problem.md#featherweight-go-solution-2020)给出了一种具体解法:`Plus(type a Any)`保持递归表示的泛型性,并让每种操作独立约束`a`(`Plus(type a Evaler)`对应`Eval`,`Plus(type a Stringer)`对应`String`)。表示不会绑定到某个封闭表达式接口,因此两个维度都保持开放。 + +传统解法从表示出发,思考如何开放两个扩展维度。轻量级 Go 将这一点推进得出人意料地远:它让递归表示具有泛型性与结构可扩展性。指称设计则将边界提前了一步:表示并非模型。模型是代数及其定律;表示只是可能的解释之一。 + +**轻量级 Go 让表示可以扩展。指称设计让表示成为可选项。** + +| | 轻量级 Go | 指称设计 | +| --- | --- | --- | +| 语义核心 | 可扩展表示 | 代数与定律 | +| `Num`/`Plus`, `lit`/`add` | 结构(表示形式) | 语义操作 | +| `Eval`, `String`/`Pretty` | 方法与接口 | 解释 | +| 递归结构 | 泛型、开放表示(`Plus(a)`) | 无需递归表示 | +| 载体 | 所表示的表达式类型 | 由解释器选择(`type Expr`) | +| AST | 表示仍居于核心 | 可选,是多种解释之一 | +| 矩阵单元格 | 分支 × 操作 → 方法 | 语义操作 × 解释 → `impl` | +| 新行为 | 添加方法与接口 | 添加或组合能力 | +| 新实现 | 新的结构实现 | 新的解释器 | + +Wadler 询问如何扩展表示的两个维度。指称设计则询问为什么表示应当掌握这两个维度。 + +先定义可组合含义,再选择编码。这样,表达式问题就成为编码之间的工程选择,而不再是概念上的死结。 + +**语言的含义应独立于机器这一概念。** + +
语言的含义应独立于机器
+ +## 参考文献 {#references} + +* Elliott, C. *《借助类型类态射进行指称设计》*。 + [http://conal.net/papers/type-class-morphisms/](http://conal.net/papers/type-class-morphisms/) + +* Elliott, C. *《编译到范畴》*。 + [http://conal.net/papers/compiling-to-categories/](http://conal.net/papers/compiling-to-categories/) + +* Kiselyov, O. *《无标签最终风格》*(关于最终编码与可扩展类型解释器的概览、教程与论文)。 + [https://okmij.org/ftp/tagless-final/](https://okmij.org/ftp/tagless-final/) + +* Kiselyov, O. *《拥有一种效应》*(对效应与可扩展解释器的定义式/指称式阐述)。 + [https://okmij.org/ftp/Computation/having-effect.html#defint](https://okmij.org/ftp/Computation/having-effect.html#defint) + +* Griesemer, R., Hu, R., Kokke, W., Lange, J., Taylor, I. L., Toninho, B., Wadler, P. 与 Yoshida, N.(2020)。*《轻量级 Go》*。ACM Program. Lang. 4(OOPSLA)。第 2.3 节给出了上文比较的泛型结构化解法。 + [https://homepages.inf.ed.ac.uk/wadler/papers/fg/fg.pdf](https://homepages.inf.ed.ac.uk/wadler/papers/fg/fg.pdf) + +* Oliveira, B. C. d. S. 与 Cook, W. R.(2012)。*《面向大众的可扩展性:借助对象代数实现实用的可扩展设计》*。 + [https://www.cs.utexas.edu/~wcook/Drafts/2012/ecoop2012.pdf](https://www.cs.utexas.edu/~wcook/Drafts/2012/ecoop2012.pdf) diff --git a/src/insights/index.ar.md b/src/insights/index.ar.md new file mode 100644 index 0000000..c49f3e8 --- /dev/null +++ b/src/insights/index.ar.md @@ -0,0 +1,23 @@ + + +# مقدمة الرؤى {#insights-introduction} + +![Insights — connecting concepts back to the semantic view](../assets/insights.png) + +```admonish tip title="ذات صلة" +الرؤية الدلالية: [لماذا يأتي المعنى أولًا](../denotational-design/semantic-view.md) +التصميم انطلاقًا من المعنى في Rust: [جبريات القدرات](../rust-dd/capability-algebras.md) +المفاهيم: [مقدمة](../concepts/index.md) +``` + +تصل الرؤى المفاهيم البرمجية بعضها ببعض وبالتصميمات العملية. + +أفضل قراءة هذه الرؤى بعد [الرؤية الدلالية](../denotational-design/semantic-view.md) و[التصميم انطلاقًا من المعنى في Rust](../rust-dd/capability-algebras.md). فهذا الأساس يمنع الخلط بين ترميز مفيد وتعريف المعنى. + +والتمييز المتكرر هو: + +1. ابدأ بالمواصفة الدلالية. +2. اختر تمثيلًا أو تحويلًا. +3. قدّم تفسيرًا تشغيليًا. + +قد تعبر الرؤية الطبقات الثلاث كلها. وحين يحدث ذلك، اسأل عن موضع كل ادعاء وأي قانون يربط الطبقات. diff --git a/src/insights/index.de.md b/src/insights/index.de.md new file mode 100644 index 0000000..cd6aff9 --- /dev/null +++ b/src/insights/index.de.md @@ -0,0 +1,23 @@ + + +# Einführung in Insights {#insights-introduction} + +![Insights — connecting concepts back to the semantic view](../assets/insights.png) + +```admonish tip title="Verwandte Themen" +The Semantic View: [Warum Bedeutung an erster Stelle steht](../denotational-design/semantic-view.md) +Design by Meaning in Rust: [Capability-Algebren](../rust-dd/capability-algebras.md) +Concepts: [Einführung](../concepts/index.md) +``` + +Insights verbinden Programmierkonzepte miteinander und mit praktischen Entwürfen. + +Am besten liest man sie nach [The Semantic View](../denotational-design/semantic-view.md) und [Design by Meaning in Rust](../rust-dd/capability-algebras.md). Diese Grundlage verhindert, dass eine nützliche Kodierung mit der Definition der Bedeutung verwechselt wird. + +Die wiederkehrende Unterscheidung lautet: + +1. Mit der semantischen Spezifikation beginnen. +2. Eine Repräsentation oder Transformation auswählen. +3. Eine operationale Interpretation angeben. + +Ein Insight kann alle drei Ebenen durchlaufen. Frage in diesem Fall, wohin die jeweilige Aussage gehört und welches Gesetz die Ebenen miteinander verbindet. diff --git a/src/insights/index.es.md b/src/insights/index.es.md new file mode 100644 index 0000000..620f174 --- /dev/null +++ b/src/insights/index.es.md @@ -0,0 +1,23 @@ + + +# Introducción a Perspectivas {#insights-introduction} + +![Insights — connecting concepts back to the semantic view](../assets/insights.png) + +```admonish tip title="Relacionado" +La perspectiva semántica: [Por qué el significado va primero](../denotational-design/semantic-view.md) +Diseño basado en el significado en Rust: [Álgebras de capacidades](../rust-dd/capability-algebras.md) +Conceptos: [Introducción](../concepts/index.md) +``` + +Perspectivas conecta los conceptos de programación entre sí y con los diseños prácticos. + +Conviene leer estos capítulos después de [La perspectiva semántica](../denotational-design/semantic-view.md) y [Diseño basado en el significado en Rust](../rust-dd/capability-algebras.md). Ese fundamento evita confundir una codificación útil con la definición del significado. + +La distinción recurrente es: + +1. Empieza por la especificación semántica. +2. Elige una representación o transformación. +3. Proporciona una interpretación operacional. + +Una perspectiva puede abarcar las tres capas. Si lo hace, pregunta dónde corresponde cada afirmación y qué ley conecta esas capas. diff --git a/src/insights/index.ja.md b/src/insights/index.ja.md new file mode 100644 index 0000000..fbb69bd --- /dev/null +++ b/src/insights/index.ja.md @@ -0,0 +1,23 @@ + + +# 洞察のはじめに {#insights-introduction} + +![Insights — connecting concepts back to the semantic view](../assets/insights.png) + +```admonish tip title="関連項目" +意味論的な見方:[なぜ意味を先に考えるのか](../denotational-design/semantic-view.md) +Rustで意味から設計する:[ケイパビリティ代数](../rust-dd/capability-algebras.md) +概念:[はじめに](../concepts/index.md) +``` + +洞察では、プログラミングの概念同士と、実践的な設計とのつながりを説明します。 + +[意味論的な見方](../denotational-design/semantic-view.md)と[Rustで意味から設計する](../rust-dd/capability-algebras.md)を読んだ後に読むのが最適です。その基礎があれば、有用な符号化を意味の定義と取り違えずに済みます。 + +繰り返し現れる区別は次のとおりです。 + +1. 意味論的な仕様から始める。 +2. 表現または変換を選ぶ。 +3. 操作上の解釈を与える。 + +洞察の中には、この三つの層すべてにまたがるものがあります。その場合、それぞれの主張がどこに属し、どの法則が層をつなぐかを問います。 diff --git a/src/insights/index.ko.md b/src/insights/index.ko.md new file mode 100644 index 0000000..ac3183b --- /dev/null +++ b/src/insights/index.ko.md @@ -0,0 +1,23 @@ + + +# 통찰 소개 {#insights-introduction} + +![Insights — connecting concepts back to the semantic view](../assets/insights.png) + +```admonish tip title="관련 항목" +의미론적 관점: [왜 의미가 먼저인가](../denotational-design/semantic-view.md) +Rust에서 의미로 설계하기: [케이퍼빌리티 대수](../rust-dd/capability-algebras.md) +통찰: [소개](../concepts/index.md) +``` + +통찰 장에서는 프로그래밍 개념들을 서로 연결하고 실용적인 설계와 연관 짓습니다. + +[의미론적 관점](../denotational-design/semantic-view.md)과 [Rust에서 의미로 설계하기](../rust-dd/capability-algebras.md)를 읽은 뒤 보는 것이 좋습니다. 이 토대가 있으면 유용한 인코딩을 의미의 정의로 착각하지 않게 됩니다. + +계속해서 강조하는 구분은 다음과 같습니다: + +1. 의미론적 명세에서 시작합니다. +2. 표현이나 변환을 선택합니다. +3. 작동 해석을 제공합니다. + +통찰은 세 계층 모두에 걸칠 수 있습니다. 이때 각 주장이 어느 계층에 속하고 어떤 법칙이 계층들을 연결하는지 확인하세요. diff --git a/src/insights/index.ru.md b/src/insights/index.ru.md new file mode 100644 index 0000000..fdb5461 --- /dev/null +++ b/src/insights/index.ru.md @@ -0,0 +1,23 @@ + + +# Введение в «Идеи» {#insights-introduction} + +![Insights — connecting concepts back to the semantic view](../assets/insights.png) + +```admonish tip title="Связанные материалы" +«Семантический взгляд»: [Почему начинать нужно со смысла](../denotational-design/semantic-view.md) +«Проектирование на основе смысла в Rust»: [Алгебры возможностей](../rust-dd/capability-algebras.md) +«Понятия»: [Введение](../concepts/index.md) +``` + +Раздел «Идеи» связывает программные понятия друг с другом и с практическим проектированием. + +Лучше читать его после разделов [«Семантический взгляд»](../denotational-design/semantic-view.md) и [«Проектирование на основе смысла в Rust»](../rust-dd/capability-algebras.md). Эта основа не позволяет принять полезное кодирование за определение смысла. + +Повторяющееся различие: + +1. Начинайте с семантической спецификации. +2. Выбирайте представление или преобразование. +3. Задавайте операционную интерпретацию. + +Идея может затрагивать все три слоя. В таком случае уточняйте, к какому слою относится каждое утверждение и какой закон связывает слои. diff --git a/src/insights/index.uk.md b/src/insights/index.uk.md new file mode 100644 index 0000000..3be234b --- /dev/null +++ b/src/insights/index.uk.md @@ -0,0 +1,23 @@ + + +# Вступ до «Осяянь» {#insights-introduction} + +![Insights — connecting concepts back to the semantic view](../assets/insights.png) + +```admonish tip title="Пов’язані матеріали" +Семантичний погляд: [Чому значення має бути першим](../denotational-design/semantic-view.md) +Проєктування від значення в Rust: [Алгебри можливостей](../rust-dd/capability-algebras.md) +Поняття: [Вступ](../concepts/index.md) +``` + +«Інсайти» пов’язують поняття програмування між собою та з практичними проєктами. + +Їх найкраще читати після розділів [Семантичний погляд](../denotational-design/semantic-view.md) та [Проєктування від значення в Rust](../rust-dd/capability-algebras.md). Ця основа не дасть сплутати корисне кодування з визначенням самого значення. + +Повторюване розрізнення таке: + +1. Починайте із семантичної специфікації. +2. Вибирайте представлення чи перетворення. +3. Додавайте операційну інтерпретацію. + +«Інсайти» може охоплювати всі три рівні. У такому разі з’ясуйте, до якого рівня належить кожне твердження та який закон пов’язує ці рівні. diff --git a/src/insights/index.vi.md b/src/insights/index.vi.md new file mode 100644 index 0000000..1c8ee45 --- /dev/null +++ b/src/insights/index.vi.md @@ -0,0 +1,23 @@ + + +# Giới thiệu phần Nhận định {#insights-introduction} + +![Insights — connecting concepts back to the semantic view](../assets/insights.png) + +```admonish tip title="Liên quan" +Góc nhìn ngữ nghĩa: [Vì sao ý nghĩa được đặt lên trước](../denotational-design/semantic-view.md) +Thiết kế theo ngữ nghĩa trong Rust: [Các đại số năng lực](../rust-dd/capability-algebras.md) +Khái niệm: [Giới thiệu](../concepts/index.md) +``` + +Các phần nhận định kết nối những khái niệm lập trình với nhau và với thiết kế thực tiễn. + +Tốt nhất nên đọc chúng sau [Góc nhìn ngữ nghĩa](../denotational-design/semantic-view.md) và [Thiết kế theo ngữ nghĩa trong Rust](../rust-dd/capability-algebras.md). Nền tảng đó giúp tránh nhầm lẫn một cách mã hóa hữu ích với định nghĩa ý nghĩa. + +Sự phân biệt lặp lại là: + +1. Bắt đầu từ đặc tả ngữ nghĩa. +2. Chọn cách biểu diễn hoặc phép biến đổi. +3. Cung cấp cách diễn giải vận hành. + +Một nhận định có thể đi qua cả ba lớp. Khi đó, hãy hỏi mỗi khẳng định thuộc về đâu và định luật nào kết nối các lớp. diff --git a/src/insights/index.zh-hant.md b/src/insights/index.zh-hant.md new file mode 100644 index 0000000..840f7ea --- /dev/null +++ b/src/insights/index.zh-hant.md @@ -0,0 +1,23 @@ + + +# 洞見導讀 {#insights-introduction} + +![Insights — connecting concepts back to the semantic view](../assets/insights.png) + +```admonish tip title="相關內容" +語義視角:[為何含義優先](../denotational-design/semantic-view.md) +Rust 中的語義驅動設計:[能力代數](../rust-dd/capability-algebras.md) +概念:[簡介](../concepts/index.md) +``` + +洞見將程式設計概念與彼此之間的連結,以及實際設計連結起來。 + +最好先讀完[《語義視角》](../denotational-design/semantic-view.md)與[《Rust 中的語義驅動設計》](../rust-dd/capability-algebras.md)再閱讀洞見。這樣的基礎有助於避免將一種有用的編碼方式誤認為含義的定義。 + +貫穿始終的區分是: + +1. 從語義規範開始。 +2. 選擇表示或變換。 +3. 提供操作解釋。 + +一則洞見可能橫跨這三個層次。若確實如此,請判斷每項主張屬於哪個層次,以及由哪條定律連線這些層次。 diff --git a/src/insights/index.zh.md b/src/insights/index.zh.md new file mode 100644 index 0000000..eaaffbe --- /dev/null +++ b/src/insights/index.zh.md @@ -0,0 +1,23 @@ + + +# 洞见导读 {#insights-introduction} + +![Insights — connecting concepts back to the semantic view](../assets/insights.png) + +```admonish tip title="相关内容" +语义视角:[为何含义优先](../denotational-design/semantic-view.md) +Rust 中的语义驱动设计:[能力代数](../rust-dd/capability-algebras.md) +概念:[简介](../concepts/index.md) +``` + +洞见将编程概念与彼此之间的联系,以及实际设计联系起来。 + +最好先读完[《语义视角》](../denotational-design/semantic-view.md)与[《Rust 中的语义驱动设计》](../rust-dd/capability-algebras.md)再阅读洞见。这样的基础有助于避免将一种有用的编码方式误认为含义的定义。 + +贯穿始终的区分是: + +1. 从语义规范开始。 +2. 选择表示或变换。 +3. 提供操作解释。 + +一则洞见可能横跨这三个层次。若确实如此,请判断每项主张属于哪个层次,以及由哪条定律连接这些层次。 diff --git a/src/insights/operational_semantics.ar.md b/src/insights/operational_semantics.ar.md new file mode 100644 index 0000000..95b0e72 --- /dev/null +++ b/src/insights/operational_semantics.ar.md @@ -0,0 +1,181 @@ + + +# من الدلالات إلى الآلات {#semantics-to-machines} + +```admonish tip title="ذات صلة" +التصميم انطلاقًا من المعنى في Rust: [برامج من الرتبة الأولى](../rust-dd/first-order-programs.md)، [مسارات اللغة والمترجم](../rust-dd/compiler-pipelines.md) +المفاهيم: [الدلالات التشغيلية](../concepts/operational_semantics.md)، [الموناد الحر](../concepts/free_monad.md)، [أسلوب تمرير الاستمرار](../concepts/cps.md)، [إزالة الدوال](../concepts/defunctionalization.md) +``` + +## ما الذي تصفه الدلالات التشغيلية {#what-operational-semantics-describes} + +تحدد الدلالات التشغيلية سلوك تمثيل برنامج مختار. وهي تعرّف أحكام التقييم أو علاقة انتقال على تهيئات مثل: + +$$ (\mathit{program}, \mathit{state}) \longrightarrow (\mathit{program}', \mathit{state}') $$ + +قد يكون البرنامج صياغة مصدر أو قيمة موناد حر أو حدًا بأسلوب تمرير الاستمرار أو شيفرة بايتية أو حالة آلة أزيلت دوالها. ولا يشكل أي تمثيل من هذه *دلالات تشغيلية*. فالدلالات التشغيلية تشرح كيفية تقييم قيم التمثيل المختار أو انتقالها. + +هذا الاتجاه مهم. يمنحنا التمثيل شيئًا يمكن وصف سلوكه؛ أما إضافة وصف تشغيلي فلا تشرح المعنى الذي ينبغي أن تحمله اللغة. + +## برامج الموناد الحر {#free-monad-programs} + +يوفر الموناد الحر صياغة التعليمات مع تسلسل مولد بحرية. لكنه لا يوفر سلوك تلك التعليمات. + +يمكن للدلالات التشغيلية لبرنامج موناد حر تعريف تهيئات تتضمن التعليمة الحالية واستمراريتها وأي حالة للآلة. ثم تشرح قواعدها، مثلًا، كيف تغيّر تعليمة معلقة الحالة وتمرر نتيجتها إلى بقية البرنامج. + +هذا تفسير ممكن واحد. ويمكن بدلًا من ذلك طي البرنامج الحر نفسه في نموذج دلالي أو تجميعه إلى لغة أخرى أو تحليله أو عرضه من دون تنفيذه. + +
+من الحر إلى الأحرر: ما الذي كشفه البحث + +قد يتساءل من عرف المونادات الحرة بوصفها بنية عامة للبرامج ذات الآثار عن سبب انتقال النقاش لاحقًا إلى البنى الأحرر والآثار القابلة للتوسيع والمعالجات. لم يتخلّ البحث ببساطة عن المونادات الحرة، بل عزل ما توفره فعلًا، وقاس مواضع إخفاق تمثيلاتها الشائعة، ثم حمل البنية المفيدة إلى الأمام. + +اشتق كيسليوف وإيشي المونادات الأحرر بإزالة القيود والشيفرة النمطية تدريجيًا من تمثيلات الحدود ذات الآثار. في التمثيل الأحرر، قد تنتج التعليمة نوعًا وسيطًا مخفيًا عن نوع البرنامج النهائي، وتربط استمرارية صريحة تلك النتيجة ببقية الحساب. لذلك لم يعد توقيع التعليمة بحاجة إلى مثيل `Functor`. + +يحسن هذا التغيير القدرة التعبيرية، لكنه لا يحل مشكلة الأداء بحد ذاته. فالتمثيل الأحرر المباشر ما زال يركّب الاستمراريات كما يركّب إلحاق القوائم المرتبط من اليسار: قد يتطلب معالجة سلسلة من طلبات $n$ عملًا قدره $O(n^2)$. ويكشف إظهار الاستمرارية الفرصة الحقيقية؛ إذ يمكن تخزينها كتسلسل محاذٍ للأنواع تتطابق فيه أنواع النتائج والمدخلات المتجاورة بحكم البناء. ويزيل وصل هذا التسلسل بكفاءة الاجتياز الحساس للارتباط. + +تتيح الاتحادات المفتوحة لمفسر الآثار القابلة للتوسيع إضافة أنواع طلبات محددة ودمجها وإزالتها. وهذا يعالج تركيب الآثار المعياري وبنية المعالجات، لكنه لا يوفر معادلات مجال بعينه ولا يحدد متى يعني برنامجان ذوا آثار الشيء نفسه. + +الخلاصة أدق من «الأحرر أفضل من الحر». كشفت المونادات الحرة فصلًا مفيدًا بين الطلبات والتفسير. وأزالت ترميزات الأحرر قيدًا غير ضروري؛ وعالجت طوابير الأنواع المحاذية مشكلة أداء مقيسة؛ وحسنت الآثار القابلة للتوسيع التركيب. احتفظت كل خطوة بمعرفة السابقة مع تضييق الادعاء الذي تقدمه. وظل التفسير الدلالي قرارًا منفصلًا طوال الوقت. + +راجع كيسليوف وإيشي، [*Freer Monads, More Extensible Effects*](https://okmij.org/ftp/Haskell/extensible/more.pdf). + +
+ +## برامج أسلوب تمرير الاستمرار {#cps-programs} + +يمثل أسلوب تمرير الاستمرار بقية الحساب صراحة في صورة استمرارية. وتصف دلالاته التشغيلية سلوكًا مثل: + +* تقييم تعبير CPS الحالي؛ +* تمرير قيمة ناتجة إلى استمراريتها؛ +* نقل التحكم عند تطبيق تلك الاستمرارية. + +يكشف أسلوب تمرير الاستمرار التحكم بصيغة يسهل وصفها تشغيليًا، لكنه تمثيل أو تحويل برمجي، لا دلالات تشغيلية. ويتطلب ربط برنامج بالأسلوب المباشر بترجمته إلى CPS تحديد دلالات المصدر والهدف مع حجة للحفاظ على المعنى. + +
+ما وراء CPS: حين يلزم فحص الاستمراريات + +أسلوب تمرير الاستمرار علاج مألوف للإلحاق والربط الحساسين للارتباط. فبدلًا من تكرار اجتياز بنية مرتبطة من اليسار، يمثل الحساب المتبقي بتركيب الدوال. ويكون ذلك فعالًا حين تكون العملية الوحيدة على الاستمرارية هي تطبيقها في النهاية. + +حدد فان در بلوخ وكيسليوف الحد الفاصل: فبعض المستهلكات تحتاج إلى فحص نتيجة وسيطة أو تعديلها قبل المتابعة. وقد يتطلب البحث غير الحتمي والمكررات والمونادات الحرة والآثار القابلة للتوسيع هذا الوصول. ويخفي أسلوب تمرير الاستمرار التسلسل المفاهيمي داخل دالة، لذا يتطلب استعادة البنية الوسيطة إعادة تجسيدها كبيانات، ما قد يمحو ميزة الأداء. + +يمثل بديلهما التسلسل المخفي مباشرة في بنية بيانات محاذية للأنواع. وتدعم هذه البنية تركيبًا فعالًا بغض النظر عن الارتباط، مع الحفاظ على الوصول الكفء إلى النتائج الوسيطة. وتضمن الأنواع أن كل حساب مخزن ينتج المدخل الذي تتوقعه الخطوة التالية. + +الخلاصة الأوسع ليست أن التسلسلات المحاذية للأنواع تهزم أسلوب تمرير الاستمرار. بل إن هذا الأسلوب ممتاز في *تطبيق* الاستمراريات وأقل ملاءمة حين يحتاج المستهلك إلى *فحصها*. ويصقل بحث التحكم المحدد الدرس أكثر: فبدلًا من التعامل مع المستقبل كله كاستمرارية واحدة غير متمايزة، تحدد المحددات أي جزء من الحساب المحيط يمكن التقاطه والتلاعب به. + +لم تختف هذه الأفكار، بل تواصل دروسها في معالجات الآثار واشتقاق الآلات المجردة وعوامل التحكم ذات الأنواع وتمثيلات الآثار الكفؤة. وما تغير هو التوقع بأن يكون أسلوب تمرير الاستمرار وحده التجريد النهائي. + +راجع فان در بلوخ وكيسليوف، [*Reflection without Remorse*](https://okmij.org/ftp/Haskell/zseq.pdf). وللسياق الأوسع للتحكم، راجع [مجموعة كيسليوف عن الاستمراريات والتحكم المحدد](https://okmij.org/ftp/continuations/index.html). + +
+ +## آلات أزيلت دوالها {#defunctionalized-machines} + +تستبدل إزالة الدوال عائلة معلومة من قيم الدوال، مثل استمراريات CPS، بمُنشئات من الرتبة الأولى وعملية `apply`. ويمكن للدلالات التشغيلية بعد ذلك وصف الانتقالات بين التهيئات الصريحة الناتجة. + +قد تشتق هذه الانتقالات آلة مجردة بعد تحويل ملموس إلى CPS تتبعه إزالة للدوال. وهذا اشتقاق قوي، لكنه ليس تعريفًا عامًا للدلالات التشغيلية: لا يلزم أن تنشأ القواعد التشغيلية من CPS، كما أن الآلة الاعتباطية من الرتبة الأولى ليست بذلك آلة استمرارية أزيلت دوالها. + +
+رينولدز: بدايات إزالة الدوال + +قدم جون سي. رينولدز إزالة الدوال في دراسته لعام 1972 للمفسرات التعريفية. ولم يبدأ بآلة افتراضية من الرتبة الأولى، بل بمفسر عالي الرتبة: كانت الدوال في اللغة المُعرِّفة تمثل البيئات والاستمراريات وأجزاء أخرى من اللغة قيد التعريف. + +يرصد التحويل العائلة المنتهية من تجريدات الدوال التي قد تظهر في البرنامج كله. ويستبدل كل تجريد بمُنشئ من الرتبة الأولى يحمل قيم متغيراته الحرة، ثم يستبدل تطبيق الدوال بعملية `apply` واحدة تفاضل على تلك المُنشئات. وهكذا يتحول ما كان ضمنيًا في اللغة المُعرِّفة إلى جبر صريح للإغلاقات أو الاستمراريات. + +عند تطبيق ذلك على مفسر قائم على الاستمراريات، تكشف الخطوة عن آلة: تصبح مُنشئات الاستمرارية حالات تحكم، وتصبح المتغيرات الملتقطة بيانات آلة مخزنة، وتصبح `apply` موزع الانتقالات. لا تُخمّن الآلة أولًا، بل تُشتق من مقيّم عالي الرتبة. + +وشدد رينولدز أيضًا على كلفة هذا الوضوح. تحتوي الآلة الناتجة خيارات تمثيل صحيحة لكنها ليست فريدة. وقد تنتج خيارات مُنشئات أو تحويلات سابقة مختلفة مجموعات مختلفة من «التروس والعجلات» الشبيهة بالآلات مع حفظ السلوك نفسه. ولذلك تكشف إزالة الدوال بنية تشغيلية، لا معنى اللغة الحتمي الوحيد. + +نظّم دانفي ونيلسن لاحقًا تقنية رينولدز بوصفها تحويلًا للبرنامج الكامل، ودرسا إعادة تحويل الدوال باعتبارها معكوسه. وخلاصتهما الأعمق أن التحويل جسر: ينقل المواصفات وحجج الصحة بين التعريفات عالية الرتبة والآلات من الرتبة الأولى، وقد يكشف أن برامج تبدو غير مترابطة هي تمثيلان للبنية نفسها. + +يمنح هذا المسار البحثي التقنية مكانتها المناسبة. إزالة الدوال أكثر من استبدال الإغلاقات بتعداد، لكنها أقل من أن تكون أساسًا كونيًا: إنها انتقال يحفظ الدلالات بين تمثيلات يجب إثبات العلاقة بينها. + +راجع رينولدز، [*Definitional Interpreters for Higher-Order Programming Languages*](https://homepages.inf.ed.ac.uk/wadler/papers/papers-we-love/reynolds-definitional-interpreters-1972.pdf)، ودانفي ونيلسن، [*Defunctionalization at Work*](https://tidsskrift.dk/brics/article/view/21684). + +
+ +## دورة التمثيل التشغيلي {#the-operational-representation-cycle} + +من الأخطاء المتكررة البحث عن تمثيل تشغيلي واحد يحل كل مشكلة برمجية. يستعيد كل تمثيل شيئًا أخفاه السابق، لكنه يجعل شأنًا آخر أصعب: + +$$ \text{higher-order program} \longrightarrow \text{free syntax} \longrightarrow \text{CPS} \longrightarrow \text{first-order machine} \longrightarrow \text{higher abstraction} $$ + +لا تدعي الأسهم وجود مسار معالجة ضروري للمترجم. بل تعرض حركة تصميمية متكررة: اكشف ما يخفيه التمثيل الحالي، ثم أخفِ الآليات التي أدخلها هذا الكشف. + +| التمثيل | ما الذي يتيحه | الضغط الذي يسببه | +| --- | --- | --- | +| دوال عالية الرتبة | تركيب مباشر وتجريد لغة المضيف | يمكن لمستهلك عام استدعاء دالة، لكنه لا يستطيع فحص بنيتها المخفية | +| صياغة حرة مع تسلسل | برامج كبيانات قابلة للتركيب والتفسير | لا توفر الحرية معادلات المجال أو التطبيع أو التقييم الكفء أو فحص الدوال المخزنة | +| أسلوب تمرير الاستمرار | يصبح ترتيب التقييم وبقية الحساب صريحين | يمرر ترميز CPS للبرنامج الكامل الاستمراريات عبر كل الواجهات تقريبًا | +| تحكم من الرتبة الأولى بعد إزالة الدوال | تصبح الاستمراريات حالات قابلة للفحص والتسلسل | يجب صيانة المُنشئات والوسائط المخزنة وحالات الانتقال وعملية `apply` صراحة | +| تجريد أعلى فوق الآلة | تصبح الآليات أسهل استخدامًا | تُخفى البنية مجددًا حين يحتاج المترجم أو المجدول أو مصحح الأخطاء أو المحسن إلى فحصها | + +هذه الضغوط بنيوية. يتطلب الفحص بيانات. وتحويل السلوك إلى بيانات يُدخل مُنشئات ومفسرًا. ويعيد إخفاء تلك المُنشئات التجريد الملائم، لكنه يزيل إمكانية الوصول نفسها التي تحتاج إليها المستهلكات لتحليل البرامج أو تحويلها. + +المفاضلة في الموناد الحر مفيدة على نحو خاص. فهو يحل مشكلة دقيقة واحدة: يولد التسلسل لفونكتور تعليمات من دون فرض معادلات تتجاوز قوانين الموناد. وهذا الضمان حدّه أيضًا. فهو لا يعرف قوانين المجال. فإذا كان ينبغي أن يكون إسنادان إلى الخلية نفسها مكافئين للإسناد الأخير وحده، يظل البرنامج الحر محتويًا على التعليمتين حتى يوحدهما تطبيع أو تفسير خاص بالمجال. لذلك يجب أن يأتي التحسين والشكل المعياري والمساواة الدلالية من مكان آخر. + +كما أن إعادة تمثيل التعليمات لا تجعل البرنامج كله قابلًا للفحص على نحو موحد. ففي الترميزات الشائعة، تكون التعليمة المعلقة ظاهرة، لكن استمراريتها دالة بلغة المضيف. ولا يستطيع محلل عام فحص البنية المستقبلية المخفية خلف تلك الدالة دون تقديم نتيجة وتطبيقها. وتعني إعادة تمثيل الاستمرارية لاستعادة الفحص الانتقال نحو تمثيل من الرتبة الأولى أو أزيلت دواله، فنعود إلى الجزء التالي من الدورة. + +تعتمد كلفة التقييم أيضًا على التمثيل. فقد تتطلب شجرة ساذجة من عمليات الربط المتسلسلة من اليسار اجتيازًا متكررًا وعملًا تربيعيًا. وقد يسبب تحويل يكرر البرامج الفرعية المتبقية نموًا أسيًا. ويمكن لترميزات Codensity أو الأحرر أو المتخصصة تحسين كلف محددة، لكن باختيار تمثيلات ومفاضلات مختلفة. النمو الأسي ممكن، لكنه ليس قانونًا أصيلًا للمونادات الحرة. + +لذلك فالموناد الحر ليس حلًا كونيًا. إنه يوفر صياغة مع تسلسل مشروع، لا معادلات المجال المقصودة ولا شكلًا معياريًا ولا رؤية بنيوية كاملة ولا تنفيذًا كفؤًا تلقائيًا. وبالمثل، لا يلزم أن ينتشر CPS في النظام كله عند استخدامه محليًا، ولا تكون إزالة الدوال مرهقة إلا بقدر عائلة الدوال والقيم الملتقطة التي يجب إعادة تمثيلها. + +تظهر الدورة حين يُطلب من كل ترميز جديد أن يصبح الأساس الكوني. فيحل إزعاجًا تشغيليًا سابقًا ثم يصبح مصدر التعقيد العرضي التالي. + +لهذا لا تتقارب النقاشات حول «أفضل تجريد» ما دامت تشغيلية بالكامل. تُقارن الدوال عالية الرتبة والصياغة الحرة وCPS والآلات من الرتبة الأولى كما لو لزم أن يتفوق أحدها على سواه. لكن *الأفضل* لا معنى له قبل تحديد ما يجب الحفاظ عليه ومن سيستهلك النتيجة: + +* يفضل التنفيذ المباشر الاستدعاءات العادية والتمثيل المخفي؛ +* يتطلب التحويل والتحليل بنية قابلة للفحص؛ +* يتطلب التسلسل بيانات من الرتبة الأولى؛ +* قد تفضل قابلية التوسيع إضافة تفسيرات أو إضافة صياغة، ونادرًا ما تفضلهما بالتساوي؛ +* قد يتطلب التزامن ملاحظات تتجاهل عمدًا خيارات جدولة كثيرة. + +هذه متطلبات مختلفة، لا براهين متعاقبة على تفوق تجريد واحد كونيًا. قد تساعد الخصائص التشغيلية في اختيار تنفيذ لغرض محدد، لكنها لا تحدد الغرض أو ما الفروق ذات المعنى. + +وينطبق التحفظ نفسه على التفكير التسلسلي. يمكن للدلالات التشغيلية وصف الأنظمة المتزامنة وغير الحتمية، لكن تسلسل خطوات آلة واحدة ليس إلا تمثيلًا ممكنًا لسلوكها. فإذا جُعل ترتيب الجدولة مرجعًا حاسمًا مبكرًا، اختلفت التنفيذات المتكافئة لمجرد اختلاف تداخل آلياتها. على النموذج الدلالي أن يقرر أولًا أي الملاحظات تميز البرامج المتزامنة؛ ثم تُقيّم الجداول التشغيلية وفق ذلك القرار. + +## مثال عملي: آلة EVM {#real-example-the-evm} + +يمكن فهم آلة Ethereum الافتراضية (EVM) تشغيليًا: + +* **الحالة**: عداد البرنامج، والمكدس، والذاكرة، والتخزين، والغاز +* **قواعد الانتقال**: قاعدة لكل شفرة عملية (`ADD` و`PUSH` و`SSTORE` وغيرها) +* **التنفيذ**: تطبيق قواعد الخطوات الصغيرة مرارًا حتى التوقف + +شيفرة EVM البايتية بيانات تعليمات من الرتبة الأولى. ويحدد الوصف التشغيلي كيفية تغير تهيئة EVM لكل شفرة عملية؛ وينفذ عميل ملموس ذلك السلوك. + +قد تشبه حلقة التوزيع وعداد البرنامج فيها آلة مجردة أزيلت دوالها. لكن تسميتها استمراريات أزيلت دوالها تتطلب مصدرًا عالي الرتبة وتحويلًا ملموسًا وعلاقة مثبتة، لا مجرد حلقة مشابهة في المظهر. + +## كسر الدورة: المعنى قبل الآليات {#breaking-the-cycle-meaning-before-machinery} + +تجيب الأوصاف التشغيلية والدلالية عن أسئلة مختلفة: + +$$ \begin{aligned} \llbracket p \rrbracket &\in D && \text{what does the program mean?} \\ c &\longrightarrow c' && \text{how does this representation step?} \end{aligned} $$ + +يختار التطوير الذي يبدأ بالمعنى المجال الدلالي والتركيب والملاحظات والقوانين قبل الالتزام بتمثيل آلة. وبعد اختيار نظام انتقال، يربط التزام صحته الطبقتين. وتكون صيغة مألوفة لادعاء حفظ الخطوة الصامتة، عند تعريف معنى مناسب للتهيئات الكاملة، كما يلي: + +$$ c \longrightarrow c' \quad \Longrightarrow \quad \operatorname{meaning}(c) = \operatorname{meaning}(c') $$ + +قد تستخدم العلاقة الدقيقة بدلًا من ذلك التكافؤ الرصدي أو المسارات أو التشابه المحاكى. والمهم أن تكون الآلة مسؤولة أمام المعنى المقصود. + +لا يختار التصميم الدلالي فائزًا من الدورة، بل ينشئ مصدرًا ثابتًا للمرجعية خارجها: + +1. عرّف المجال الدلالي والعمليات والتركيب والقوانين. +2. اكتب البرامج بمفردات ذلك المعنى. +3. اختر تمثيلًا لمستهلك ملموس: التنفيذ المباشر أو الفحص أو التجميع أو الجدولة أو التسلسل أو التحليل. +4. اربط كل تمثيل وتحويل مختار بالمعنى نفسه. + +لذلك يمكن لمفسر عالي الرتبة وبرنامج من الرتبة الأولى أن يتعايشا. ولا يلزم أن يكون أي منهما تعريف اللغة. فقد يخدم الأول التنفيذ المباشر، والثاني المستهلكين الذين يحتاجون إلى البنية. وتوافقهما التزام دلالي، لا افتراض بتطابق آلياتهما. + +```admonish note title="لا يوجد تجريد تشغيلي أخير" +يكشف كل تمثيل تشغيلي بعض البنية ويخفي أخرى. والمعنى هو النقطة الثابتة التي تُختار انطلاقًا منها التمثيلات المناسبة وتُربط بعضها ببعض. +``` + +## ملخص {#summary} + +* تصف الدلالات التشغيلية التقييم أو الانتقالات لتمثيل مختار. +* توفر المونادات الحرة صياغة التعليمات والتسلسل، لكن السلوك يظل بحاجة إلى تفسير. +* يكشف أسلوب تمرير الاستمرار الاستمراريات؛ وقد تصف القواعد التشغيلية كيف تمرر برامج CPS القيم والتحكم. +* قد تحول إزالة الدوال برنامجًا معينًا عالي الرتبة إلى آلة من الرتبة الأولى يمكن وصف انتقالاتها تشغيليًا. +* إن التعامل مع أي ترميز منها بوصفه كونيًا يخلق دورة من إعادة تجسيد البنية وإخفائها. +* يحدد المعنى الدلالي ما يجب أن تحافظ عليه تلك الانتقالات. diff --git a/src/insights/operational_semantics.de.md b/src/insights/operational_semantics.de.md new file mode 100644 index 0000000..09e37d9 --- /dev/null +++ b/src/insights/operational_semantics.de.md @@ -0,0 +1,181 @@ + + +# Von der Semantik zu Maschinen {#semantics-to-machines} + +```admonish tip title="Verwandte Themen" +Design by Meaning in Rust: [Programme erster Ordnung](../rust-dd/first-order-programs.md), [Sprach- und Compiler-Pipelines](../rust-dd/compiler-pipelines.md) +Concepts: [Operationale Semantik](../concepts/operational_semantics.md), [Freie Monade](../concepts/free_monad.md), [Continuation-Passing Style](../concepts/cps.md), [Defunktionalisierung](../concepts/defunctionalization.md) +``` + +## Was operationale Semantik beschreibt {#what-operational-semantics-describes} + +Operationale Semantik spezifiziert das Verhalten einer gewählten Programmrepräsentation. Sie definiert Auswertungsurteile oder eine Übergangsrelation über Konfigurationen wie: + +$$ (\mathit{program}, \mathit{state}) \longrightarrow (\mathit{program}', \mathit{state}') $$ + +Das Programm kann Quellsyntax, ein Wert einer freien Monade, ein CPS-Term, Bytecode oder ein defunktionalisierter Maschinenzustand sein. Keine dieser Repräsentationen *ist* operationale Semantik. Diese beschreibt, wie Werte der gewählten Repräsentation ausgewertet werden oder Übergänge durchlaufen. + +Diese Richtung ist wichtig. Eine Repräsentation liefert einen Gegenstand, dessen Verhalten beschrieben werden kann; eine operationale Beschreibung erklärt nicht, was die Sprache bedeuten sollte. + +## Programme mit freien Monaden {#free-monad-programs} + +Eine freie Monade stellt Instruktionssyntax samt frei erzeugter Sequenzierung bereit. Sie legt nicht das Verhalten dieser Instruktionen fest. + +Eine operationale Semantik für ein Programm mit freier Monade kann Konfigurationen mit der aktuellen Instruktion, ihrer Fortsetzung und einem möglichen Maschinenzustand definieren. Ihre Regeln erklären dann beispielsweise, wie eine ausgesetzte Instruktion den Zustand ändert und ihr Ergebnis an das restliche Programm übergibt. + +Das ist eine mögliche Interpretation. Dasselbe freie Programm kann stattdessen in ein denotationelles Modell gefaltet, in eine andere Sprache kompiliert, analysiert oder dargestellt werden, ohne es auszuführen. + +
+Von free zu freer: Was die Forschung herausgefunden hat + +Leser, die freie Monaden als allgemeine Architektur für Programme mit Effekten kennengelernt haben, fragen sich vielleicht, warum sich die Diskussion später zu freer-Konstruktionen, erweiterbaren Effekten und Handlern verlagert hat. Die Forschung hat freie Monaden nicht einfach verworfen. Sie hat herausgearbeitet, was sie tatsächlich leisten, untersucht, wo ihre verbreiteten Repräsentationen scheitern, und die brauchbare Struktur weiterentwickelt. + +Kiselyov und Ishii leiten freer-Monaden her, indem sie Beschränkungen und Boilerplate von Repräsentationen effektvoller Terme schrittweise entfernen. In der freer-Repräsentation kann eine Instruktion einen Zwischentyp liefern, der im endgültigen Programmtyp verborgen bleibt; eine explizite Fortsetzung verbindet dieses Ergebnis mit dem restlichen Berechnungsablauf. Die Instruktionssignatur benötigt daher keine `Functor`\-Instanz mehr. + +Das verbessert die Ausdrucksmöglichkeiten, löst aber nicht von selbst das Leistungsproblem. Eine direkte freer-Repräsentation verkettet Fortsetzungen weiterhin wie linksassoziiertes Anhängen an eine Liste: Das Verarbeiten einer Folge von $n$ Anfragen kann $O(n^2)$ Aufwand erfordern. Die explizite Fortsetzung macht die eigentliche Chance sichtbar — man kann sie als typausgerichtete Sequenz speichern, deren benachbarte Ergebnis- und Eingabetypen konstruktionsbedingt zusammenpassen. Effizientes Verketten dieser Sequenz beseitigt den von der Assoziation abhängigen Durchlauf. + +Offene Vereinigungen ermöglichen es einem Interpreter für erweiterbare Effekte anschließend, ausgewählte Anfragetypen hinzuzufügen, zu kombinieren und zu eliminieren. Das löst Probleme bei der modularen Effektkomposition und Handlerstruktur. Die Gleichungen eines bestimmten Fachgebiets oder die Frage, wann zwei Programme mit Effekten dieselbe Bedeutung haben, werden dadurch weiterhin nicht festgelegt. + +Das Fazit ist präziser als „freer ist besser als free“. Freie Monaden machten eine wertvolle Trennung zwischen Anfragen und Interpretation sichtbar. Freer-Kodierungen beseitigten eine unnötige Beschränkung; typausgerichtete Queues lösten ein gemessenes Leistungsproblem; erweiterbare Effekte verbesserten die Komposition. Jeder Schritt bewahrte Erkenntnisse aus dem vorherigen und schränkte zugleich die Behauptung ein. Die semantische Interpretation blieb dabei stets eine separate Entscheidung. + +Siehe Kiselyov und Ishii, [*Freer Monads, More Extensible Effects*](https://okmij.org/ftp/Haskell/extensible/more.pdf). + +
+ +## CPS-Programme {#cps-programs} + +Continuation-Passing Style (CPS) stellt den Rest einer Berechnung ausdrücklich als Fortsetzung dar. Eine operationale Semantik für CPS beschreibt etwa: + +* den aktuellen CPS-Ausdruck auswerten; +* einen erzeugten Wert an seine Fortsetzung übergeben; +* die Kontrolle übertragen, wenn diese Fortsetzung angewendet wird. + +CPS macht den Kontrollfluss auf eine operational leicht beschreibbare Weise sichtbar, ist aber eine Repräsentation oder Programmtransformation — keine operationale Semantik. Um ein Programm im direkten Stil mit seiner CPS-Übersetzung in Beziehung zu setzen, braucht es formulierte Quell- und Zielsemantiken sowie einen Bewahrungsnachweis. + +
+Über CPS hinaus: Wenn Fortsetzungen untersucht werden müssen + +CPS ist eine gängige Lösung für assoziationsabhängiges Anhängen und Binden. Statt eine linksassoziierte Struktur wiederholt zu durchlaufen, stellt es den verbleibenden Berechnungsablauf durch Funktionskomposition dar. Bleibt als einzige Operation auf der Fortsetzung ihre spätere Anwendung, kann diese Repräsentation effizient sein. + +Van der Ploeg und Kiselyov benennen die Grenze: Manche Nutzer müssen ein Zwischenergebnis untersuchen oder verändern, bevor die Berechnung fortgesetzt wird. Nichtdeterministische Suche, Iteratees, freie Monaden und erweiterbare Effekte können diesen Zugriff benötigen. CPS verbirgt die begriffliche Sequenz in einer Funktion; die Rekonstruktion der Zwischenstruktur erfordert daher eine Rückwandlung in Daten und kann den Leistungsvorteil zunichtemachen. + +Ihre Alternative stellt die verborgene Sequenz direkt als typausgerichtete Datenstruktur dar. Sie ermöglicht effiziente Komposition unabhängig von der Assoziation und bewahrt zugleich den effizienten Zugriff auf Zwischenergebnisse. Die Typen stellen sicher, dass jede gespeicherte Berechnung genau die Eingabe erzeugt, die die nächste erwartet. + +Die weitergehende Schlussfolgerung lautet nicht, dass typausgerichtete Sequenzen CPS überlegen sind. CPS eignet sich hervorragend zum *Anwenden* von Fortsetzungen, aber weniger, wenn ein Nutzer sie *untersuchen* muss. Die Forschung zu begrenzter Kontrolle schärft diese Erkenntnis weiter: Statt die gesamte Zukunft als eine undifferenzierte Fortsetzung zu behandeln, legen Delimiter fest, welcher Teil der umgebenden Berechnung erfasst und bearbeitet werden darf. + +Diese Ideen sind nicht verschwunden. Ihre Lehren leben in Effekt-Handlern, Herleitungen abstrakter Maschinen, typisierten Kontrolloperatoren und effizienten Repräsentationen von Effekten weiter. Verändert hat sich die Erwartung, CPS allein müsse die endgültige Abstraktion sein. + +Siehe van der Ploeg und Kiselyov, [*Reflection without Remorse*](https://okmij.org/ftp/Haskell/zseq.pdf). Für den breiteren Kontrollflusskontext siehe Kiselyovs [continuations and delimited-control collection](https://okmij.org/ftp/continuations/index.html). + +
+ +## Defunktionalisierte Maschinen {#defunctionalized-machines} + +Defunktionalisierung ersetzt eine bekannte Familie von Funktionswerten, etwa CPS-Fortsetzungen, durch Konstruktoren erster Ordnung und eine `apply`\-Operation. Die operationale Semantik kann dann Übergänge zwischen den daraus entstehenden expliziten Konfigurationen beschreiben. + +Auf eine konkrete CPS-Transformation kann Defunktionalisierung folgen, um eine abstrakte Maschine herzuleiten. Diese Herleitung ist leistungsstark, aber keine allgemeine Definition operationaler Semantik: Operationale Regeln müssen nicht aus CPS hervorgehen, und eine beliebige Maschine erster Ordnung ist deshalb noch keine defunktionalisierte Fortsetzungsmaschine. + +
+Reynolds: Der Ursprung der Defunktionalisierung + +John C. Reynolds führte Defunktionalisierung 1972 in seiner Untersuchung definierender Interpreter ein. Ausgangspunkt war keine virtuelle Maschine erster Ordnung, sondern ein Interpreter höherer Ordnung: Funktionen in der definierenden Sprache stellten Umgebungen, Fortsetzungen und andere Teile der zu definierenden Sprache dar. + +Die Transformation betrachtet die endliche Familie von Funktionsabstraktionen, die im gesamten Programm auftreten kann. Sie ersetzt jede Abstraktion durch einen Konstruktor erster Ordnung, der die Werte ihrer freien Variablen enthält, und ersetzt anschließend die Funktionsanwendung durch eine einzige `apply`\-Operation, die anhand dieser Konstruktoren verzweigt. Was in der definierenden Sprache implizit war, wird zu einer expliziten Algebra von Abschlüssen oder Fortsetzungen. + +Auf einen Interpreter mit Fortsetzungen angewandt, macht dieser Schritt eine Maschine sichtbar: Fortsetzungskonstruktoren werden zu Steuerzuständen, erfasste Variablen zu gespeicherten Maschinendaten und `apply` zum Übergangsverteiler. Die Maschine wird nicht zuerst erraten, sondern aus einem Auswerter höherer Ordnung hergeleitet. + +Reynolds betonte auch den Preis dieser Klarheit. Die resultierende Maschine enthält Repräsentationsentscheidungen, die korrekt, aber nicht eindeutig sind. Andere Konstruktoren oder vorangehende Transformationen können andere Ansammlungen maschinenartiger „Rädchen und Zahnräder“ ergeben und dennoch dasselbe Verhalten bewahren. Defunktionalisierung legt also eine operationale Struktur offen, nicht die einzig mögliche Bedeutung der Sprache. + +Danvy und Nielsen systematisierten Reynolds’ Technik später als Transformation für vollständige Programme und untersuchten Re-Funktionalisierung als ihre Umkehrung. Ihre weitergehende Schlussfolgerung lautet, dass diese Transformation eine Brücke bildet: Sie kann Spezifikationen und Korrektheitsargumente zwischen Definitionen höherer Ordnung und Maschinen erster Ordnung übertragen und zeigen, dass scheinbar unabhängige Programme zwei Repräsentationen derselben Struktur sind. + +Diese Forschungslinie bestimmt den angemessenen Stellenwert der Technik. Defunktionalisierung ist mehr als der Ersatz von Closures durch ein Enum, aber weniger als eine universelle Grundlage: Sie ist ein bedeutungserhaltender Übergang zwischen Repräsentationen, deren Entsprechung nachgewiesen werden muss. + +Siehe Reynolds, [*Definitional Interpreters for Higher-Order Programming Languages*](https://homepages.inf.ed.ac.uk/wadler/papers/papers-we-love/reynolds-definitional-interpreters-1972.pdf), sowie Danvy und Nielsen, [*Defunctionalization at Work*](https://tidsskrift.dk/brics/article/view/21684). + +
+ +## Der Zyklus operationaler Repräsentationen {#the-operational-representation-cycle} + +Ein wiederkehrender Fehler ist die Suche nach einer einzigen operationalen Repräsentation, die alle Programmierprobleme löst. Jede Repräsentation macht etwas sichtbar, das die vorige verbarg, erschwert dadurch jedoch einen anderen Aspekt: + +$$ \text{higher-order program} \longrightarrow \text{free syntax} \longrightarrow \text{CPS} \longrightarrow \text{first-order machine} \longrightarrow \text{higher abstraction} $$ + +Die Pfeile behaupten keine notwendige Compiler-Pipeline. Sie zeigen eine wiederkehrende Entwurfsbewegung: sichtbar machen, was die aktuelle Repräsentation verbirgt, und anschließend die durch diese Offenlegung eingeführte Mechanik verbergen. + +| Repräsentation | Was dadurch möglich wird | Welche Schwierigkeiten dadurch entstehen | +| --- | --- | --- | +| Funktionen höherer Ordnung | Direkte Komposition und Abstraktionen der Hostsprache | Ein generischer Nutzer kann eine Funktion aufrufen, aber nicht ihre verborgene Struktur untersuchen | +| Freie Syntax mit Sequenzierung | Programme als Daten, die sich zusammensetzen und interpretieren lassen | Fachliche Gleichungen, Normalisierung, effiziente Auswertung und Einsicht in gespeicherte Funktionen sind nicht durch Freiheit gegeben | +| CPS | Auswertungsreihenfolge und restlicher Berechnungsablauf werden explizit | Eine CPS-Kodierung des gesamten Programms führt Fortsetzungen durch nahezu alle Schnittstellen | +| Defunktionalisierte Steuerung erster Ordnung | Fortsetzungen werden zu untersuchbaren, serialisierbaren Fällen | Konstruktoren, gespeicherte Argumente, Übergangszustände und eine `apply`\-Operation müssen ausdrücklich gepflegt werden | +| Eine höhere Abstraktion über der Maschine | Die Mechanik wird leichter verwendbar | Die Struktur wird erneut verborgen, wenn Compiler, Scheduler, Debugger oder Optimierer sie untersuchen müssen | + +Die Herausforderungen sind strukturell. Inspektion erfordert Daten. Wird Verhalten in Daten verwandelt, braucht es Konstruktoren und einen Interpreter. Werden diese Konstruktoren verborgen, entsteht wieder eine bequeme Abstraktion — doch genau der Zugriff, den Nutzer zur Analyse oder Transformation von Programmen benötigen, geht verloren. + +Der Zielkonflikt freier Monaden ist besonders aufschlussreich. Eine freie Monade löst ein genau umrissenes Problem: Sie erzeugt Sequenzierung für einen Instruktionsfunktor, ohne über die Monadengesetze hinaus Gleichungen aufzuerlegen. Diese Garantie ist zugleich ihre Grenze. Sie kennt die Gesetze des Fachgebiets nicht. Sollen etwa zwei Schreibvorgänge in dieselbe Zelle dem letzten Schreibvorgang entsprechen, enthält das freie Programm weiterhin beide Instruktionen, bis eine fachgebietsspezifische Normalisierung oder Interpretation sie zusammenführt. Optimierung, kanonische Form und semantische Gleichheit müssen daher anderswoher kommen. + +Auch die Reifizierung von Instruktionen macht nicht das gesamte Programm einheitlich untersuchbar. In verbreiteten Kodierungen ist eine ausgesetzte Instruktion sichtbar, ihre Fortsetzung jedoch eine Funktion der Hostsprache. Ein generischer Analysator kann die zukünftige Struktur hinter dieser Funktion nicht untersuchen, ohne ein Ergebnis zu liefern und sie anzuwenden. Die Reifizierung der Fortsetzung ermöglicht wieder Inspektion, indem sie in Richtung einer Darstellung erster Ordnung oder defunktionalisierten Repräsentation führt — und damit zum nächsten Teil des Zyklus zurückkehrt. + +Auch die Auswertungskosten hängen von der Repräsentation ab. Ein naiver Baum linksassoziierter Bindungen kann wiederholte Durchläufe und quadratischen Aufwand erfordern. Eine Transformation, die verbleibende Teilprogramme dupliziert, kann exponentielles Wachstum verursachen. Kodierungen nach dem Codensity-Stil, freer-Kodierungen oder spezialisierte Darstellungen verbessern bestimmte Kosten, indem sie andere Repräsentationen und Zielkonflikte wählen. Exponentielles Wachstum ist möglich, aber kein inhärentes Gesetz freier Monaden. + +Darum ist eine freie Monade keine Universallösung. Sie bietet Syntax mit gesetzmäßiger Sequenzierung, nicht die beabsichtigten Gleichungen des Fachgebiets, eine kanonische Normalform, vollständige strukturelle Sichtbarkeit oder eine automatisch effiziente Implementierung. Ebenso muss CPS nicht das gesamte System durchziehen, wenn es lokal verwendet wird; Defunktionalisierung wird nur im Verhältnis zur Familie von Funktionen und erfassten Werten umständlich, die reifiziert werden müssen. + +Der Zyklus entsteht, wenn jede neue Kodierung zur universellen Grundlage gemacht werden soll. Sie löst die letzte operationale Unbequemlichkeit und wird anschließend selbst zur Quelle zufälliger Komplexität. + +Darum kommen Debatten über die „beste Abstraktion“ nicht zu einem Ergebnis, wenn sie vollständig operational bleiben. Funktionen höherer Ordnung, freie Syntax, CPS und Maschinen erster Ordnung werden verglichen, als müsse eine davon allen anderen überlegen sein. Doch *besser* hat keine Bedeutung, bevor der Vergleich festlegt, was bewahrt werden muss und wer das Ergebnis nutzen wird: + +* direkte Ausführung begünstigt gewöhnliche Aufrufe und verborgene Repräsentationen; +* Transformation und Analyse benötigen untersuchbare Strukturen; +* Serialisierung benötigt Daten erster Ordnung; +* Erweiterbarkeit kann das Hinzufügen von Interpretationen oder Syntax begünstigen, aber selten beides gleichermaßen; +* Nebenläufigkeit kann Beobachtungen erfordern, die bewusst viele Entscheidungen des Schedulers ausblenden. + +Das sind unterschiedliche Anforderungen, keine aufeinanderfolgenden Beweise dafür, dass eine Abstraktion universell überlegen ist. Operationale Eigenschaften können bei der Wahl einer Implementierung für einen klar benannten Zweck helfen; sie können weder den Zweck vorgeben noch bestimmen, welche Unterschiede Bedeutung haben. + +Dieselbe Vorsicht gilt für sequenzielles Denken. Operationale Semantik kann nebenläufige und nichtdeterministische Systeme beschreiben, doch eine einzelne Folge von Maschinenschritten ist nur eine mögliche Repräsentation ihres Verhaltens. Wird die Reihenfolge des Schedulers zu früh als maßgeblich gesetzt, unterscheiden sich äquivalente Ausführungen allein deshalb, weil ihre Mechanismen anders verschränkt wurden. Das semantische Modell muss zuerst festlegen, welche Beobachtungen nebenläufige Programme unterscheiden; anschließend lassen sich operationale Abläufe daran messen. + +## Reales Beispiel: die EVM {#real-example-the-evm} + +Die Ethereum Virtual Machine (EVM) lässt sich operational verstehen: + +* **Zustand**: Programmzähler, Stapel, Speicher, dauerhafter Speicher, Gas +* **Übergangsregeln**: je eine pro Opcode (`ADD`, `PUSH`, `SSTORE` usw.) +* **Ausführung**: kleine Schritte wiederholt anwenden, bis die Ausführung anhält + +EVM-Bytecode sind Instruktionsdaten erster Ordnung. Eine operationale Beschreibung legt fest, wie sich eine EVM-Konfiguration bei jedem Opcode ändert; ein konkreter Client implementiert dieses Verhalten. + +Ihre Verteilerschleife und ihr Programmzähler können einer defunktionalisierten abstrakten Maschine ähneln. Sie jedoch als defunktionalisierte Fortsetzungen zu bezeichnen, erfordert eine konkrete Funktion höherer Ordnung als Quelle, eine Transformation und deren Entsprechungsnachweis — eine ähnlich aussehende Schleife genügt nicht. + +## Den Zyklus durchbrechen: Bedeutung vor Mechanik {#breaking-the-cycle-meaning-before-machinery} + +Operationale und denotationelle Beschreibungen beantworten unterschiedliche Fragen: + +$$ \begin{aligned} \llbracket p \rrbracket &\in D && \text{what does the program mean?} \\ c &\longrightarrow c' && \text{how does this representation step?} \end{aligned} $$ + +Eine bedeutungsorientierte Entwicklung wählt den semantischen Bereich, Komposition, Beobachtungen und Gesetze, bevor sie sich auf eine Maschinenrepräsentation festlegt. Nach der Wahl eines Übergangssystems verbindet eine Korrektheitsverpflichtung beide Ebenen. Für eine passend definierte Bedeutung vollständiger Konfigurationen hat eine typische Behauptung zur Bewahrung stiller Schritte die Form: + +$$ c \longrightarrow c' \quad \Longrightarrow \quad \operatorname{meaning}(c) = \operatorname{meaning}(c') $$ + +Die genaue Relation kann stattdessen beobachtungsbezogene Äquivalenz, Spuren oder Bisimilarität verwenden. Entscheidend ist, dass die Maschine der beabsichtigten Bedeutung verpflichtet bleibt. + +Denotational Design kürt keinen Sieger im Zyklus. Es schafft eine stabile Autorität außerhalb davon: + +1. Semantischen Bereich, Operationen, Komposition und Gesetze festlegen. +2. Programme in Begriffen dieser Bedeutung schreiben. +3. Eine Repräsentation für einen konkreten Nutzer auswählen: direkte Ausführung, Inspektion, Kompilierung, Ablaufplanung, Serialisierung oder Analyse. +4. Jede gewählte Repräsentation und Transformation auf dieselbe Bedeutung zurückführen. + +Ein Interpreter höherer Ordnung und ein Programm erster Ordnung können daher nebeneinander bestehen. Keines davon muss die Sprachdefinition sein. Das erste kann der direkten Ausführung dienen, das zweite Nutzern, die Struktur benötigen. Ihre Übereinstimmung ist eine semantische Verpflichtung, keine Annahme, dass ihre Mechanismen identisch sind. + +```admonish note title="Keine endgültige operationale Abstraktion" +Jede operationale Repräsentation macht manche Strukturen sichtbar und verbirgt andere. Bedeutung ist der stabile Ausgangspunkt, von dem aus sich geeignete Repräsentationen auswählen und zueinander in Beziehung setzen lassen. +``` + +## Zusammenfassung {#summary} + +* Operationale Semantik beschreibt die Auswertung oder Übergänge für eine gewählte Repräsentation. +* Freie Monaden stellen Instruktionssyntax und Sequenzierung bereit; ihr Verhalten erfordert weiterhin eine Interpretation. +* CPS macht Fortsetzungen sichtbar; operationale Regeln können beschreiben, wie CPS-Programme Werte und Kontrolle weitergeben. +* Defunktionalisierung kann ein bestimmtes Programm höherer Ordnung in eine Maschine erster Ordnung überführen, deren Übergänge sich operational formulieren lassen. +* Wird eine dieser Kodierungen als universell behandelt, entsteht ein Zyklus aus Reifizierung und Verbergen von Strukturen. +* Die denotationelle Bedeutung bestimmt, was diese Übergänge bewahren müssen. diff --git a/src/insights/operational_semantics.es.md b/src/insights/operational_semantics.es.md new file mode 100644 index 0000000..153f63b --- /dev/null +++ b/src/insights/operational_semantics.es.md @@ -0,0 +1,181 @@ + + +# De la semántica a las máquinas {#semantics-to-machines} + +```admonish tip title="Relacionado" +Diseño basado en el significado en Rust: [Programas de primer orden](../rust-dd/first-order-programs.md), [Lenguaje y procesos de compilación](../rust-dd/compiler-pipelines.md) +Conceptos: [Semántica operacional](../concepts/operational_semantics.md), [Mónada libre](../concepts/free_monad.md), [Estilo de paso de continuaciones](../concepts/cps.md), [Defuncionalización](../concepts/defunctionalization.md) +``` + +## Qué describe la semántica operacional {#what-operational-semantics-describes} + +La semántica operacional especifica cómo se comporta una representación de programa elegida. Define juicios de evaluación o una relación de transición sobre configuraciones como: + +$$ (\mathit{program}, \mathit{state}) \longrightarrow (\mathit{program}', \mathit{state}') $$ + +El programa puede ser sintaxis fuente, un valor de mónada libre, un término CPS, bytecode o un estado de máquina defuncionalizado. Ninguna de esas representaciones *es* semántica operacional. La semántica operacional describe cómo se evalúan o avanzan los valores de la representación elegida. + +Esta dirección importa. Una representación nos ofrece algo cuyo comportamiento se puede describir; añadir una descripción operacional no explica qué debería significar el lenguaje. + +## Programas de mónada libre {#free-monad-programs} + +Una mónada libre proporciona sintaxis de instrucciones junto con una secuenciación generada libremente. No define el comportamiento de esas instrucciones. + +Una semántica operacional para un programa de mónada libre puede definir configuraciones que contengan la instrucción actual, su continuación y cualquier estado de máquina. Las reglas explican, por ejemplo, cómo una instrucción suspendida modifica el estado y pasa su resultado al resto del programa. + +Esa es una posible interpretación. El mismo programa libre también puede plegarse en un modelo denotacional, compilarse a otro lenguaje, analizarse o representarse sin ejecutarse. + +
+De libre a freer: qué reveló la investigación + +Quienes conocieron las mónadas libres como una arquitectura general para programas con efectos quizá se pregunten por qué el debate pasó después a las construcciones freer, los efectos extensibles y los manejadores. La investigación no descartó sin más las mónadas libres. Aisló qué aportan realmente, midió dónde fallan sus representaciones habituales y conservó la estructura útil. + +Kiselyov e Ishii derivan mónadas freer al eliminar progresivamente restricciones y código repetitivo de las representaciones de términos con efectos. En la representación freer, una instrucción puede producir un tipo intermedio oculto en el tipo final del programa, y una continuación explícita conecta ese resultado con el resto del cálculo. Por ello, la signatura de instrucciones ya no necesita una instancia `Functor`. + +Ese cambio mejora la expresividad, pero no resuelve por sí mismo el rendimiento. Una representación freer directa sigue componiendo continuaciones como la concatenación de listas asociada a la izquierda: procesar una cadena de solicitudes $n$ puede requerir $O(n^2)$ trabajo. Al hacer explícita la continuación, se revela la verdadera oportunidad: se puede almacenar como una secuencia alineada por tipos, cuyos tipos de resultado y entrada adyacentes coinciden por construcción. La concatenación eficiente de esa secuencia elimina el recorrido sensible a la asociación. + +Las uniones abiertas permiten luego que un intérprete de efectos extensibles añada, combine y elimine tipos de solicitud seleccionados. Esto resuelve la composición modular de efectos y la estructura de manejadores. Aun así, no proporciona las ecuaciones de un dominio concreto ni decide cuándo dos programas con efectos tienen el mismo significado. + +La conclusión es más precisa que «freer es mejor que free». Las mónadas libres revelaron una separación valiosa entre solicitudes e interpretación. Las codificaciones freer eliminaron una restricción innecesaria; las colas alineadas por tipos abordaron un problema de rendimiento medido; los efectos extensibles mejoraron la composición. Cada paso conservó lo aprendido en el anterior y delimitó mejor la afirmación. La interpretación semántica siguió siendo una decisión independiente. + +Consulta Kiselyov e Ishii, [*Freer Monads, More Extensible Effects*](https://okmij.org/ftp/Haskell/extensible/more.pdf). + +
+ +## Programas CPS {#cps-programs} + +El estilo de paso de continuaciones (CPS) representa explícitamente el resto del cálculo mediante una continuación. Una semántica operacional de CPS describe comportamientos como: + +* evaluar la expresión CPS actual; +* pasar un valor producido a su continuación; +* transferir el control al aplicar esa continuación. + +CPS expone el control de una forma cómoda para describir operacionalmente, pero es una representación o transformación de programas, no una semántica operacional. Relacionar un programa de estilo directo con su traducción CPS requiere especificar las semánticas de origen y destino y demostrar su preservación. + +
+Más allá de CPS: cuándo hay que inspeccionar las continuaciones + +CPS es una solución estándar para el append y el bind sensibles a la asociación. En lugar de recorrer repetidamente una estructura asociada a la izquierda, representa el cálculo restante mediante composición de funciones. Esta representación puede ser eficiente cuando la única operación sobre la continuación es su aplicación final. + +Van der Ploeg y Kiselyov identifican el límite: algunos consumidores deben examinar o modificar un resultado intermedio antes de continuar. La búsqueda no determinista, los iteratees, las mónadas libres y los efectos extensibles pueden requerir ese acceso. CPS oculta la secuencia conceptual dentro de una función, por lo que recuperar la estructura intermedia requiere convertirla de nuevo en datos y puede anular la ventaja de rendimiento. + +Su alternativa representa directamente la secuencia oculta como una estructura de datos alineada por tipos. Permite una composición eficiente sin importar la asociación y conserva un acceso eficiente a los resultados intermedios. Los tipos garantizan que cada cálculo almacenado produzca la entrada que espera el siguiente. + +La conclusión más amplia no es que las secuencias alineadas por tipos venzan a CPS. CPS es excelente para *aplicar* continuaciones y menos adecuado cuando un consumidor debe *inspeccionarlas*. La investigación sobre control delimitado afina aún más la lección: en lugar de tratar todo el futuro como una única continuación indiferenciada, los delimitadores especifican qué parte del cálculo circundante se puede capturar y manipular. + +Estas ideas no desaparecieron. Sus lecciones continúan en los manejadores de efectos, las derivaciones de máquinas abstractas, los operadores de control tipados y las representaciones eficientes de efectos. Lo que cambió fue la expectativa de que CPS por sí solo debía ser la abstracción final. + +Consulta van der Ploeg y Kiselyov, [*Reflection without Remorse*](https://okmij.org/ftp/Haskell/zseq.pdf). Para un panorama más amplio del control, consulta la [colección de Kiselyov sobre continuaciones y control delimitado](https://okmij.org/ftp/continuations/index.html). + +
+ +## Máquinas defuncionalizadas {#defunctionalized-machines} + +La defuncionalización reemplaza una familia conocida de valores de función, como las continuaciones CPS, por constructores de primer orden y una operación `apply`. La semántica operacional puede describir entonces las transiciones entre las configuraciones explícitas resultantes. + +Tras aplicar una transformación CPS concreta seguida de una defuncionalización, esas transiciones pueden derivar una máquina abstracta. Es una derivación potente, pero no define la semántica operacional en general: las reglas operacionales no tienen por qué originarse en CPS, y una máquina arbitraria de primer orden no se convierte por ello en una máquina de continuaciones defuncionalizada. + +
+Reynolds: los orígenes de la defuncionalización + +John C. Reynolds introdujo la defuncionalización en su estudio de 1972 sobre los intérpretes denotacionales. No partió de una máquina virtual de primer orden, sino de un intérprete de orden superior: las funciones del lenguaje de definición representaban entornos, continuaciones y otros elementos del lenguaje definido. + +La transformación identifica la familia finita de abstracciones de función que puede aparecer en todo el programa. Reemplaza cada abstracción por un constructor de primer orden que contiene los valores de sus variables libres; luego, sustituye la aplicación de funciones por una operación `apply` que distribuye la ejecución según esos constructores. Lo implícito en el lenguaje de definición se convierte en un álgebra explícita de cierres o continuaciones. + +Aplicado a un intérprete basado en continuaciones, este paso revela una máquina: los constructores de continuación se convierten en estados de control, las variables capturadas pasan a ser datos almacenados en la máquina y `apply` se convierte en el despachador de transiciones. La máquina no se inventa de antemano; se deriva de un evaluador de orden superior. + +Reynolds también subrayó el coste de esta claridad. La máquina resultante contiene decisiones de representación correctas, pero no únicas. Distintas elecciones de constructores o transformaciones previas pueden producir colecciones distintas de engranajes y piezas de máquina, sin cambiar el comportamiento. Por tanto, la defuncionalización revela una estructura operacional, no el único significado inevitable del lenguaje. + +Danvy y Nielsen sistematizaron después la técnica de Reynolds como transformación de programas completos y estudiaron la refuncionalización como su inversa. Su conclusión más profunda es que la transformación sirve de puente: permite transferir especificaciones y argumentos de corrección entre definiciones de orden superior y máquinas de primer orden, y revela que programas aparentemente distintos pueden ser dos representaciones de la misma estructura. + +Esta trayectoria de investigación confiere a la técnica su autoridad adecuada. La defuncionalización es más que reemplazar cierres por una enumeración, pero menos que un fundamento universal: es un paso que preserva la semántica entre representaciones y cuya correspondencia debe establecerse. + +Consulta a Reynolds, [*Definitional Interpreters for Higher-Order Programming Languages*](https://homepages.inf.ed.ac.uk/wadler/papers/papers-we-love/reynolds-definitional-interpreters-1972.pdf), y a Danvy y Nielsen, [*Defunctionalization at Work*](https://tidsskrift.dk/brics/article/view/21684). + +
+ +## El ciclo de representación operacional {#the-operational-representation-cycle} + +Un error recurrente es buscar una única representación operacional que resuelva todos los problemas de programación. Cada representación recupera algo que la anterior ocultaba, pero dificulta otra preocupación: + +$$ \text{higher-order program} \longrightarrow \text{free syntax} \longrightarrow \text{CPS} \longrightarrow \text{first-order machine} \longrightarrow \text{higher abstraction} $$ + +Las flechas no afirman que exista un proceso de compilación obligatorio. Muestran un movimiento de diseño recurrente: hacer explícito lo que la representación actual oculta y, después, ocultar la maquinaria que introdujo esa exposición. + +| Representación | Qué permite representar | Qué dificultades introduce | +| --- | --- | --- | +| Funciones de orden superior | Composición directa y abstracción del lenguaje anfitrión | Un consumidor genérico puede llamar a una función, pero no inspeccionar su estructura oculta | +| Sintaxis libre con secuenciación | Programas como datos componibles e interpretables | La libertad no proporciona ecuaciones del dominio, normalización, evaluación eficiente ni inspección de funciones almacenadas | +| CPS | El orden de evaluación y el resto del cálculo se vuelven explícitos | Una codificación CPS de todo el programa propaga continuaciones por casi todas las interfaces | +| Control defuncionalizado de primer orden | Las continuaciones se convierten en casos inspeccionables y serializables | Hay que mantener explícitamente constructores, argumentos almacenados, estados de transición y una operación `apply` | +| Una abstracción de nivel superior sobre la máquina | La maquinaria se vuelve más fácil de usar | La estructura vuelve a quedar oculta cuando un compilador, planificador, depurador u optimizador necesita inspeccionarla | + +Las dificultades son estructurales. Inspeccionar requiere datos. Convertir el comportamiento en datos introduce constructores y un intérprete. Ocultar esos constructores restaura una abstracción cómoda, pero elimina el acceso que necesitan los consumidores que analizan o transforman programas. + +El equilibrio de las mónadas libres es especialmente ilustrativo. Una mónada libre resuelve un problema preciso: genera secuenciación para un functor de instrucciones sin imponer ecuaciones aparte de las leyes de mónada. Esa garantía también marca su límite: no conoce las leyes del dominio. Si dos escrituras a la misma celda deberían equivaler a conservar solo la última, el programa libre sigue conteniendo ambas instrucciones hasta que una normalización o interpretación específica del dominio las identifique. Por tanto, la optimización, la forma canónica y la igualdad semántica deben venir de otra parte. + +Tampoco basta con reificar las instrucciones para hacer que todo el programa sea inspeccionable de manera uniforme. En las codificaciones habituales, la instrucción suspendida es visible, pero su continuación es una función del lenguaje anfitrión. Un analizador genérico no puede inspeccionar la estructura futura que hay detrás de esa función sin proporcionar un resultado y aplicarla. Reificar la continuación recupera la capacidad de inspección al pasar a una representación de primer orden o defuncionalizada; así se vuelve a la siguiente parte del ciclo. + +El coste de evaluación también depende de la representación. Un árbol ingenuo de binds asociados a la izquierda puede requerir recorridos repetidos y trabajo cuadrático. Una transformación que duplique subprogramas residuales puede provocar un crecimiento exponencial. Las codificaciones estilo Codensity, freer o especializadas pueden mejorar costes concretos, pero lo hacen eligiendo otras representaciones y equilibrios. El crecimiento exponencial es posible, pero no es una ley intrínseca de las mónadas libres. + +Por eso una mónada libre no es una solución universal. Proporciona sintaxis con secuenciación sujeta a leyes, pero no las ecuaciones del dominio pretendido, una forma normal canónica, visibilidad estructural completa ni una implementación automáticamente eficiente. Del mismo modo, CPS no tiene por qué extenderse por todo un sistema si se usa localmente, y la defuncionalización solo resulta engorrosa en proporción a la familia de funciones y los valores capturados que deba reificar. + +El ciclo aparece cuando se pretende que cada nueva codificación se convierta en el fundamento universal. Resuelve el inconveniente operacional anterior y luego se convierte en la siguiente fuente de complejidad accidental. + +Por eso los debates sobre la «mejor abstracción» no llegan a una conclusión cuando permanecen exclusivamente en el plano operacional. Se comparan las funciones de orden superior, la sintaxis libre, CPS y las máquinas de primer orden como si una debiera dominar a las demás. Pero *mejor* no significa nada hasta que la comparación especifica qué debe preservarse y quién consumirá el resultado: + +* la ejecución directa favorece las llamadas habituales y la representación oculta; +* la transformación y el análisis requieren una estructura inspeccionable; +* la serialización requiere datos de primer orden; +* la extensibilidad puede favorecer la incorporación de interpretaciones o de sintaxis, pero rara vez ambas por igual; +* la concurrencia puede exigir observaciones que ignoren deliberadamente muchas decisiones de planificación. + +Son requisitos distintos, no pruebas sucesivas de que una abstracción sea universalmente superior. Las propiedades operacionales pueden ayudar a elegir una implementación para un propósito especificado; no pueden aportar ese propósito ni decidir qué distinciones son significativas. + +La misma cautela se aplica al pensamiento secuencial. La semántica operacional puede describir sistemas concurrentes y no deterministas, pero una única secuencia de pasos de máquina es solo una representación posible de su comportamiento. Si se da autoridad demasiado pronto al orden de planificación, las ejecuciones equivalentes se vuelven distintas únicamente porque sus mecanismos se intercalaron de otra manera. El modelo semántico debe decidir primero qué observaciones distinguen los programas concurrentes; después se pueden evaluar las planificaciones operacionales según esa decisión. + +## Ejemplo real: la EVM {#real-example-the-evm} + +La máquina virtual de Ethereum (EVM) se puede entender operacionalmente: + +* **Estado**: contador de programa, pila, memoria, almacenamiento y gas +* **Reglas de transición**: una por cada código de operación (`ADD`, `PUSH`, `SSTORE`, etc.) +* **Ejecución**: se aplican repetidamente reglas de pequeños pasos hasta detenerse + +El bytecode de la EVM son datos de instrucciones de primer orden. Una descripción operacional especifica cómo cambia una configuración de la EVM para cada código de operación; un cliente concreto implementa ese comportamiento. + +Su ciclo de despacho y su contador de programa pueden parecerse a una máquina abstracta defuncionalizada. Sin embargo, llamarlos continuaciones defuncionalizadas exige un origen de orden superior, una transformación y una correspondencia concretos; no basta con que un ciclo tenga un aspecto parecido. + +## Romper el ciclo: el significado antes que la maquinaria {#breaking-the-cycle-meaning-before-machinery} + +Las descripciones operacionales y denotacionales responden a preguntas distintas: + +$$ \begin{aligned} \llbracket p \rrbracket &\in D && \text{what does the program mean?} \\ c &\longrightarrow c' && \text{how does this representation step?} \end{aligned} $$ + +Un desarrollo guiado por el significado elige el dominio semántico, la composición, las observaciones y las leyes antes de comprometerse con una representación de máquina. Una vez elegido un sistema de transición, su obligación de corrección conecta ambas capas. Para un significado de configuraciones completas definido adecuadamente, una afirmación típica de preservación de pasos silenciosos tiene esta forma: + +$$ c \longrightarrow c' \quad \Longrightarrow \quad \operatorname{meaning}(c) = \operatorname{meaning}(c') $$ + +La relación exacta puede usar equivalencia observacional, trazas o bisimilaridad. Lo importante es que la máquina responda ante el significado pretendido. + +El diseño denotacional no elige un ganador del ciclo. Establece una fuente estable de autoridad fuera de él: + +1. Define el dominio semántico, las operaciones, la composición y las leyes. +2. Escribe los programas en términos de ese significado. +3. Elige una representación para un consumidor concreto: ejecución directa, inspección, compilación, planificación, serialización o análisis. +4. Relaciona cada representación y transformación elegida con el mismo significado. + +Por tanto, pueden coexistir un intérprete de orden superior y un programa de primer orden. Ninguno tiene que ser la definición del lenguaje. El primero puede servir para la ejecución directa; el segundo, para los consumidores que necesitan estructura. Que concuerden es una obligación semántica, no una suposición de que sus mecanismos sean idénticos. + +```admonish note title="No existe una abstracción operacional definitiva" +Toda representación operacional expone parte de la estructura y oculta otra. El significado es el punto estable desde el que se pueden elegir y relacionar las representaciones adecuadas. +``` + +## Resumen {#summary} + +* La semántica operacional describe la evaluación o las transiciones de una representación elegida. +* Las mónadas libres proporcionan sintaxis de instrucciones y secuenciación, cuyo comportamiento aún requiere interpretación. +* CPS hace explícitas las continuaciones; las reglas operacionales pueden describir cómo los programas CPS pasan valores y control. +* La defuncionalización puede convertir un programa concreto de orden superior en una máquina de primer orden cuyas transiciones se describen operacionalmente. +* Tratar cualquiera de estas codificaciones como universal genera un ciclo de reificación y ocultación de estructuras. +* El significado denotacional determina qué deben preservar esas transiciones. diff --git a/src/insights/operational_semantics.ja.md b/src/insights/operational_semantics.ja.md new file mode 100644 index 0000000..a77c324 --- /dev/null +++ b/src/insights/operational_semantics.ja.md @@ -0,0 +1,181 @@ + + +# 意味論から機械へ {#semantics-to-machines} + +```admonish tip title="関連項目" +Rustで意味から設計する:[一階プログラム](../rust-dd/first-order-programs.md)、[言語とコンパイラーパイプライン](../rust-dd/compiler-pipelines.md) +概念:[操作的意味論](../concepts/operational_semantics.md)、[自由モナド](../concepts/free_monad.md)、[継続渡し形式](../concepts/cps.md)、[関数のデファンクショナライズ](../concepts/defunctionalization.md) +``` + +## 操作的意味論が記述するもの {#what-operational-semantics-describes} + +操作的意味論は、選択したプログラム表現がどう振る舞うかを定めます。評価判断、または次のような構成に対する遷移関係を定義します。 + +$$ (\mathit{program}, \mathit{state}) \longrightarrow (\mathit{program}', \mathit{state}') $$ + +プログラムはソース構文、自由モナド値、CPS項、バイトコード、デファンクショナライズされた機械状態かもしれません。これらの表現はいずれも操作的意味論*ではありません*。操作的意味論は、選択した表現の値がどのように評価または遷移するかを説明するものです。 + +この方向性は重要です。表現があれば、その振る舞いを記述できます。しかし操作上の記述を追加しても、その言語が本来持つべき意味は説明されません。 + +## 自由モナドのプログラム {#free-monad-programs} + +自由モナドは命令構文と自由に生成される逐次実行を提供しますが、命令の振る舞いは定めません。 + +自由モナドのプログラムに対する操作的意味論では、現在の命令、その継続、機械状態を含む構成を定義できます。たとえば、中断中の命令がどのように状態を変え、結果を残りのプログラムへ渡すかを規則で説明します。 + +これは可能な解釈の一つです。同じ自由プログラムを表示モデルへfoldしたり、別の言語へコンパイルしたり、解析したり、実行せずに描画したりすることもできます。 + +
+自由モナドからfreerへ:研究で分かったこと + +副作用のあるプログラムを構成する一般的なアーキテクチャとして自由モナドを知った読者は、なぜ後にfreer構成、拡張可能な副作用、ハンドラーへ議論が移ったのか疑問に思うかもしれません。研究は自由モナドを単に捨てたのではありません。自由モナドが実際に提供するものを切り分け、一般的な表現がうまくいかない箇所を測定し、有用な構造を引き継ぎました。 + +KiselyovとIshiiは、副作用項の表現から制約や定型コードを段階的に取り除き、freerモナドを導出しました。freer表現では、命令が最終的なプログラム型からは見えない中間型の値を生成でき、明示的な継続が結果を計算の残りへ接続します。そのため、命令シグネチャに`Functor`インスタンスは不要になります。 + +この変更で表現力は向上しますが、それだけでは性能の問題は解決しません。素朴なfreer表現では、左結合のリスト追加と同様に継続を合成します。$n$件の要求列を処理するには$O(n^2)$の計算量がかかることがあります。継続を明示すると、実際の改善点が見えてきます。隣り合う結果型と入力型が構築時に一致する、型整列された列として継続を保持できます。この列を効率的に連結すれば、結合の仕方に依存する走査が不要になります。 + +次にopen unionを使うと、拡張可能な副作用のインタープリターで、選択した要求型を追加、合成、除去できます。これによってモジュール式の副作用合成とハンドラー構造を扱えます。それでも、特定の領域の等式を提供したり、副作用を持つ二つのプログラムが同じ意味か判断したりするわけではありません。 + +結論は「freerはfreeより優れている」より正確です。自由モナドは要求と解釈を分離する価値ある方法を示しました。freer符号化は不要な制約を除き、型整列キューは測定された性能問題に対処し、拡張可能な副作用は合成を改善しました。各段階は前の知見を引き継ぎながら、主張の範囲を絞りました。意味論的な解釈は最初から最後まで独立した判断でした。 + +KiselyovとIshiiの[*Freer Monads, More Extensible Effects*](https://okmij.org/ftp/Haskell/extensible/more.pdf)を参照してください。 + +
+ +## CPSプログラム {#cps-programs} + +継続渡し形式(CPS)では、計算の残りを継続として明示します。CPSに対する操作的意味論では、次のような振る舞いを記述します。 + +* 現在のCPS式を評価する。 +* 生成された値を継続へ渡す。 +* 継続が適用されたときに制御を移す。 + +CPSは制御を操作上記述しやすい形で明らかにしますが、表現またはプログラム変換であり、操作的意味論ではありません。直接形式のプログラムとそのCPS変換を関連付けるには、ソースとターゲットの意味論を明示し、保持を示す必要があります。 + +
+CPSを越えて:継続を検査する必要があるとき + +CPSは、結合の仕方に依存する追加やbindの負荷を抑える標準的な方法です。左結合構造を何度も走査する代わりに、関数合成によって残りの計算を表します。継続に対する操作が最終的な適用だけなら、この表現は効率的です。 + +van der PloegとKiselyovはその限界を示しています。継続する前に中間結果を調べたり変更したりする必要のある利用側もあります。非決定的探索、列挙子、自由モナド、拡張可能な副作用では、このようなアクセスが必要になる場合があります。CPSでは概念的な列が関数の中に隠れるため、中間構造を復元するにはデータへの再反映が必要になり、性能上の利点が失われることがあります。 + +代わりに隠れた列を、型整列されたデータ構造として直接表現します。これにより、結合の仕方によらない効率的な合成と、中間結果への効率的なアクセスを両立できます。各計算が次の計算に必要な入力を生成することは、型で保証されます。 + +広い意味での結論は、型整列列がCPSを打ち負かすということではありません。CPSは継続の*適用*には適していますが、利用側が継続を*検査*する場合には適さないことがあるということです。区切られた制御に関する研究は、周囲の計算全体を一つの区別のない継続として扱う代わりに、どの範囲を捕捉し操作できるかを区切りが示すという、さらに精密な教訓を与えます。 + +これらの考え方は失われていません。副作用ハンドラー、抽象機械の導出、型付き制御演算子、効率的な副作用表現に今も活かされています。変わったのは、CPSだけが最終的な抽象化であるべきだという期待です。 + +van der PloegとKiselyovの[*Reflection without Remorse*](https://okmij.org/ftp/Haskell/zseq.pdf)を参照してください。制御全般については、Kiselyovの[継続と区切られた制御の資料集](https://okmij.org/ftp/continuations/index.html)を参照してください。 + +
+ +## デファンクショナライズされた機械 {#defunctionalized-machines} + +デファンクショナライズでは、CPSの継続など、既知の関数値の族を一階構成子と`apply`操作に置き換えます。これにより、生成された明示的な構成間の遷移を操作的意味論で記述できます。 + +具体的なCPS変換の後にデファンクショナライズを行えば、抽象機械を導出できます。これは強力な導出方法ですが、一般的な操作的意味論の定義ではありません。操作規則はCPSに由来する必要はなく、一階機械も、見た目が似ているというだけでデファンクショナライズされた継続機械になるわけではありません。 + +
+Reynolds:デファンクショナライズの始まり + +John C. Reynoldsは、1972年の定義的インタープリターに関する研究でデファンクショナライズを導入しました。出発点は一階仮想マシンではなく、高階インタープリターでした。定義に用いる言語の関数が、定義対象の言語における環境、継続、その他の要素を表していました。 + +この変換では、プログラム全体に現れ得る有限個の関数抽象を特定します。各抽象を、自由変数の値を持つ一階構成子に置き換え、関数適用を、構成子を振り分ける一つの`apply`操作に置き換えます。定義に用いる言語の中で暗黙だったものが、クロージャまたは継続の明示的な代数になります。 + +継続に基づくインタープリターに適用すると、機械が見えてきます。継続構成子は制御状態になり、捕捉された変数は格納された機械データになり、`apply`は遷移の振り分け器になります。機械を先に推測するのではなく、高階評価器から導出します。 + +Reynoldsは、明確さによって生じる代償も強調しました。導出される機械は正しいものの一意ではない表現上の選択を含みます。異なる構成子や先行する変換を選ぶと、振る舞いを保ったまま「機械の歯車や車輪」に似た構造が異なる形で得られます。そのため、デファンクショナライズは操作構造を明らかにしますが、その言語に不可避な唯一の意味を示すわけではありません。 + +DanvyとNielsenは後に、Reynoldsの技法をプログラム全体に適用する変換として体系化し、逆変換のリファンクショナライズを研究しました。さらに深い結論として、この変換は橋渡しの役割を持ちます。高階な定義と一階機械の間で仕様や正しさの議論を移し、無関係に見えるプログラムが同じ構造の異なる表現だと明らかにできます。 + +この研究の系譜は、この技法に適切な権威を与えます。デファンクショナライズはクロージャを列挙型に置き換えるだけのものより強力ですが、普遍的な基盤というには限定的です。対応関係の確立が必要な、意味を保つ表現間の移行です。 + +Reynoldsの[*Definitional Interpreters for Higher-Order Programming Languages*](https://homepages.inf.ed.ac.uk/wadler/papers/papers-we-love/reynolds-definitional-interpreters-1972.pdf)と、DanvyとNielsenの[*Defunctionalization at Work*](https://tidsskrift.dk/brics/article/view/21684)を参照してください。 + +
+ +## 操作表現のサイクル {#the-operational-representation-cycle} + +よくある誤りは、あらゆるプログラミング上の問題を解決する一つの操作表現を探すことです。各表現は、前の表現が隠していたものを明らかにしますが、その代わり別の課題を難しくします。 + +$$ \text{higher-order program} \longrightarrow \text{free syntax} \longrightarrow \text{CPS} \longrightarrow \text{first-order machine} \longrightarrow \text{higher abstraction} $$ + +矢印は必須のコンパイラーパイプラインを意味しません。現在の表現が隠すものを明らかにし、そのために導入した仕組みを再び隠すという、繰り返し現れる設計の動きを示します。 + +| 表現 | 可能になること | 新たに生じる負担 | +| --- | --- | --- | +| 高階関数 | 直接的な合成とホスト言語の抽象化 | ジェネリックな利用側は関数を呼び出せるが、隠された構造を検査できない | +| 逐次実行を備えた自由構文 | 合成・解釈可能なデータとしてのプログラム | 領域の等式、正規化、効率的な評価、格納された関数の検査は自由構文だけでは提供されない | +| CPS | 評価順と計算の残りを明示できる | プログラム全体をCPSで符号化すると、ほぼすべてのインターフェースに継続を通すことになる | +| デファンクショナライズされた一階制御 | 継続が検査・シリアライズ可能なケースになる | 構成子、格納した引数、遷移状態、`apply`操作を明示的に保守する必要がある | +| 機械より上位の抽象化 | 仕組みが使いやすくなる | コンパイラー、スケジューラー、デバッガー、最適化器が検査する必要があると、構造が再び隠れる | + +こうした負担は構造に起因します。検査にはデータが必要です。振る舞いをデータにすると、構成子とインタープリターが加わります。それらを隠せば抽象化は使いやすくなりますが、プログラムを解析・変換する利用側が必要とするアクセスも失われます。 + +自由モナドのトレードオフは特に示唆的です。自由モナドが解決するのは、命令ファンクターからモナドの法則を超える等式を課さずに逐次実行を生成するという、一つの明確な問題です。同じ保証が限界でもあります。領域の法則は分かりません。たとえば同じセルへの二回の書き込みを最後の書き込みと等価に扱うべき場合でも、領域固有の正規化または解釈で同一視するまでは、自由プログラムに両方の命令が残ります。したがって、最適化、正準形、意味論的等値性は別の場所から与える必要があります。 + +命令を再構化しただけでは、プログラム全体を一様に検査できるようにもなりません。一般的な符号化では、中断中の命令は見えますが、その継続はホスト言語の関数です。ジェネリックな解析器は、結果を与えて関数を適用せずに、その関数の先にある構造を検査できません。継続をデータへ再構化して検査可能にすると、一階表現またはデファンクショナライズされた表現へ近づき、サイクルの次の段階に戻ります。 + +評価コストも同様に表現に依存します。左結合されたbindの素朴な木では、繰り返し走査が必要となり、二次の計算量が生じることがあります。残余サブプログラムを複製する変換は、指数的な増大を引き起こす可能性があります。Codensity形式、freer形式、専用の符号化は特定のコストを改善できますが、それぞれ別の表現とトレードオフを選んでいます。指数的な増大は起こり得ますが、自由モナド固有の法則ではありません。 + +そのため自由モナドは万能な解決策ではありません。自由モナドが提供するのは、法則に従う逐次実行を伴う構文であり、意図された領域の等式、正準形、完全な構造の可視性、自動的に効率のよい実装ではありません。同様に、CPSも局所的に使うならシステム全体へ広げる必要はありません。デファンクショナライズが煩雑かどうかは、再構化する関数族や捕捉値の規模によって決まります。 + +各新しい符号化を普遍的な基盤にしようとすると、このサイクルが現れます。直前の操作上の不便を解決した結果、次の偶発的な複雑さの原因になります。 + +そのため、「最良の抽象化」をめぐる議論が操作面だけにとどまると、結論に至りません。高階関数、自由構文、CPS、一階機械を、どれか一つが他より優れていなければならないかのように比べます。しかし、何を保持するかと、誰が結果を利用するかを定めない限り、*よりよい*の意味は定まりません。 + +* 直接実行では通常の呼び出しと隠された表現が有利になる。 +* 変換と解析では検査可能な構造が必要になる。 +* シリアライズでは一階データが必要になる。 +* 拡張性のために、解釈の追加または構文の追加を容易にする設計を選べるが、通常は両方を同じように容易にはできない。 +* 並行性では、多くのスケジューリング上の選択を意図的に無視する観測が必要な場合がある。 + +これらは異なる要件であり、一つの抽象化が普遍的に優れていることを順に証明するものではありません。操作上の性質は目的を定めたうえで実装選択に役立ちますが、目的を与えたり、どの区別に意味があるかを決めたりはしません。 + +逐次的な考え方にも同じ注意が必要です。操作的意味論は並行・非決定的システムを記述できますが、機械のステップを一列に並べたものは、振る舞いを表現する方法の一つにすぎません。スケジュール順を早々に権威あるものとして扱うと、機械上で異なる順にインターリーブされたというだけで、等価な実行が異なるものになってしまいます。まず意味論モデルで、並行プログラム間のどの観測を違いとして扱うかを決め、その後に操作上のスケジュールを評価します。 + +## 実例:EVM {#real-example-the-evm} + +Ethereum Virtual Machine(EVM)は操作的に理解できます。 + +* **状態**:プログラムカウンター、スタック、メモリー、ストレージ、gas +* **遷移規則**:各オペコード(`ADD`、`PUSH`、`SSTORE`など)につき一つ +* **実行**:停止するまで小ステップ規則を繰り返し適用する + +EVMバイトコードは一階の命令データです。操作的な説明では、各オペコードに応じてEVMの構成がどう変化するかを定め、具体的なクライアントがその振る舞いを実装します。 + +EVMのディスパッチループとプログラムカウンターは、デファンクショナライズされた抽象機械に似ていることがあります。しかし、それらをデファンクショナライズされた継続と呼ぶには、具体的な高階ソース、変換、対応関係が必要です。見た目が似たループだけでは足りません。 + +## サイクルを断つ:仕組みより先に意味を定める {#breaking-the-cycle-meaning-before-machinery} + +操作上の説明と表示上の説明は、異なる問いに答えます。 + +$$ \begin{aligned} \llbracket p \rrbracket &\in D && \text{what does the program mean?} \\ c &\longrightarrow c' && \text{how does this representation step?} \end{aligned} $$ + +意味から始める開発では、機械表現を決める前に意味論的領域、合成、観測、法則を選びます。遷移系を選んだ後に、正しさの責務で二つの層をつなぎます。完全な構成に対する適切な意味を定めた場合、典型的な静かなステップの保持は次の形になります。 + +$$ c \longrightarrow c' \quad \Longrightarrow \quad \operatorname{meaning}(c) = \operatorname{meaning}(c') $$ + +正確な関係には、観測的等価性、トレース、双模倣性を使うこともあります。重要なのは、機械が意図された意味に対して責任を負うことです。 + +Denotational Designは、このサイクルの勝者を決めません。サイクルの外に安定した基準を置きます。 + +1. 意味論的領域、操作、合成、法則を定義する。 +2. その意味に沿ってプログラムを書く。 +3. 具体的な利用者に合わせて表現を選ぶ。直接実行、検査、コンパイル、スケジューリング、シリアライズ、解析など。 +4. 選択した各表現と変換を、同じ意味へ結び付ける。 + +高階インタープリターと一階プログラムは共存できます。どちらも言語の定義になる必要はありません。前者は直接実行に、後者は構造を必要とする利用側に役立ちます。仕組みが同じだという前提ではなく、意味論上の責務として一致を確認します。 + +```admonish note title="操作的な抽象化に最終形はない" +どの操作表現も、ある構造を明らかにする一方で別の構造を隠します。適切な表現を選び、その関係を定めるための安定した基準が意味です。 +``` + +## まとめ {#summary} + +* 操作的意味論は、選択した表現に対する評価や遷移を記述する。 +* 自由モナドは命令構文と逐次実行を提供するが、振る舞いの解釈は別途必要である。 +* CPSは継続を明示し、操作規則でCPSプログラムが値と制御を渡す様子を記述できる。 +* デファンクショナライズによって特定の高階プログラムを一階機械に変換でき、その遷移を操作的に述べられる。 +* いずれかの符号化を普遍的なものとして扱うと、構造を再構化したり隠したりするサイクルが生じる。 +* 表示上の意味が、遷移で保持すべきものを定める。 diff --git a/src/insights/operational_semantics.ko.md b/src/insights/operational_semantics.ko.md new file mode 100644 index 0000000..39ece3a --- /dev/null +++ b/src/insights/operational_semantics.ko.md @@ -0,0 +1,181 @@ + + +# 의미론에서 기계로 {#semantics-to-machines} + +```admonish tip title="관련 항목" +Rust에서 의미로 설계하기: [일차 프로그램](../rust-dd/first-order-programs.md), [언어와 컴파일러 파이프라인](../rust-dd/compiler-pipelines.md) +개념: [작동 의미론](../concepts/operational_semantics.md), [자유 모나드](../concepts/free_monad.md), [연속 전달 스타일](../concepts/cps.md), [디펑셔널라이제이션](../concepts/defunctionalization.md) +``` + +## 작동 의미론이 설명하는 것 {#what-operational-semantics-describes} + +작동 의미론은 선택한 프로그램 표현이 어떻게 동작하는지 명시합니다. 다음과 같은 구성을 대상으로 평가 판단이나 전이 관계를 정의합니다: + +$$ (\mathit{program}, \mathit{state}) \longrightarrow (\mathit{program}', \mathit{state}') $$ + +프로그램은 소스 구문, 자유 모나드 값, CPS 항, 바이트코드 또는 디펑셔널라이즈된 기계 상태일 수 있습니다. 어떤 표현도 그 자체가 작동 의미론은 *아닙니다*. 작동 의미론은 선택한 표현의 값이 어떻게 평가되거나 전이되는지 설명합니다. + +방향성이 중요합니다. 표현은 동작을 설명할 대상을 제공하지만, 작동 설명을 덧붙여도 언어가 무엇을 의미해야 하는지는 설명되지 않습니다. + +## 자유 모나드 프로그램 {#free-monad-programs} + +자유 모나드는 명령어 구문과 자유롭게 생성되는 시퀀싱을 제공합니다. 명령어가 어떤 동작을 하는지는 제공하지 않습니다. + +자유 모나드 프로그램의 작동 의미론은 현재 명령어, 연속 실행, 기계 상태를 포함하는 구성을 정의할 수 있습니다. 규칙은 예를 들어 보류된 명령어가 상태를 어떻게 바꾸고 결과를 나머지 프로그램에 어떻게 전달하는지 설명합니다. + +이는 가능한 해석 하나입니다. 같은 자유 프로그램을 실행하지 않고 표시적 모델로 폴드하거나 다른 언어로 컴파일하거나 분석하거나 렌더링할 수도 있습니다. + +
+자유에서 프리어로: 연구를 통해 알게 된 것 + +효과가 있는 프로그램의 일반 아키텍처로 자유 모나드를 접한 독자는 왜 이후 논의가 프리어 구성, 확장 효과, 핸들러로 이동했는지 궁금할 수 있습니다. 연구에서 자유 모나드를 단순히 버린 것은 아닙니다. 실제로 제공하는 것을 분리하고, 흔한 표현의 한계를 측정한 뒤, 유용한 구조를 이어 갔습니다. + +Kiselyov와 Ishii는 효과 항의 표현에서 제약과 상용구를 점진적으로 제거해 프리어 모나드를 도출합니다. 프리어 표현에서 명령어는 최종 프로그램 타입에는 드러나지 않는 중간 타입을 낼 수 있고, 명시적인 연속 실행이 그 결과를 계산의 나머지에 연결합니다. 따라서 명령어 시그니처에 `Functor` 인스턴스가 더는 필요하지 않습니다. + +이 변화는 표현력을 높이지만 그 자체로 성능 문제를 해결하지는 않습니다. 직접적인 프리어 표현은 여전히 왼쪽 결합 리스트 덧붙이기처럼 연속 실행을 합성할 수 있습니다. $n$ 요청의 연결을 처리하는 데 $O(n^2)$의 작업이 걸릴 수 있습니다. 연속 실행을 드러내면 기회가 보입니다. 결과 타입과 입력 타입이 타입으로 일치하는 타입 정렬 시퀀스로 저장할 수 있습니다. 그 시퀀스를 효율적으로 연결하면 결합 순서에 따른 순회를 없앨 수 있습니다. + +그런 다음 열린 유니언을 이용해 확장 효과 인터프리터가 선택한 요청 타입을 추가, 결합, 제거할 수 있습니다. 이는 모듈식 효과 합성과 핸들러 구조 문제를 다룹니다. 하지만 특정 영역의 등식을 제공하거나 효과가 있는 두 프로그램의 의미가 언제 같은지는 결정하지 않습니다. + +결론은 “프리보다 프리어가 낫다”보다 정확합니다. 자유 모나드는 요청과 해석을 분리하는 가치 있는 방법을 보여 주었습니다. 프리어 인코딩은 불필요한 제약을 제거했고, 타입 정렬 큐는 측정된 성능 문제를 해결했으며, 확장 효과는 합성을 개선했습니다. 각 단계는 앞선 단계의 지식을 유지하면서 주장의 범위를 좁혔습니다. 의미론적 해석은 전 과정에서 별도의 결정으로 남았습니다. + +Kiselyov와 Ishii의 [*Freer Monads, More Extensible Effects*](https://okmij.org/ftp/Haskell/extensible/more.pdf)를 참고하세요. + +
+ +## CPS 프로그램 {#cps-programs} + +연속 전달 스타일(CPS)은 계산의 나머지를 연속 실행으로 명시합니다. CPS의 작동 의미론은 다음 동작을 설명합니다: + +* 현재 CPS 표현식 평가; +* 생성한 값을 연속 실행에 전달; +* 연속 실행을 적용할 때 제어 이전. + +CPS는 작동 방식으로 설명하기 쉬운 형태로 제어를 드러내지만, 표현이나 프로그램 변환이지 작동 의미론은 아닙니다. 직접 스타일 프로그램과 CPS 번역을 연결하려면 명시적인 소스 및 대상 의미론과 보존 논증이 필요합니다. + +
+CPS를 넘어서: 연속 실행을 검사해야 할 때 + +CPS는 결합 순서에 민감한 덧붙이기와 바인드를 피하는 표준 기법입니다. 왼쪽으로 결합된 구조를 반복해서 순회하는 대신 함수 합성을 사용해 계산의 나머지를 나타냅니다. 연속 실행에 적용하는 것만 가능하다면 효율적일 수 있습니다. + +van der Ploeg와 Kiselyov는 경계를 짚어냅니다. 일부 사용자는 계속하기 전에 중간 결과를 검사하거나 수정해야 합니다. 비결정적 탐색, 이터레이터, 자유 모나드, 확장 효과가 모두 이런 접근을 필요로 할 수 있습니다. CPS는 개념적 시퀀스를 함수 안에 감추므로 중간 구조를 복원하려면 데이터로 다시 반영해야 하고, 그 과정에서 성능 이점을 잃을 수 있습니다. + +이들은 숨겨진 시퀀스를 타입 정렬 자료 구조로 직접 표현하는 대안을 제시합니다. 결합 순서와 관계없이 효율적인 합성을 지원하면서 중간 결과에도 효율적으로 접근할 수 있습니다. 각 계산이 다음 계산에서 기대하는 입력을 만든다는 사실을 타입이 보장합니다. + +더 넓은 결론은 타입 정렬 시퀀스가 CPS를 이긴다는 것이 아닙니다. CPS는 연속 실행을 *적용*하는 데 탁월하지만, 사용자가 이를 *검사*해야 할 때는 적합성이 떨어집니다. 구획 제어 연구는 교훈을 더 구체화합니다. 전체 미래를 하나의 구분 없는 연속 실행으로 다루는 대신, 구획자가 주변 계산에서 어느 부분을 포착하고 조작할 수 있는지 지정합니다. + +이러한 아이디어는 사라지지 않았습니다. 그 교훈은 효과 핸들러, 추상 기계 도출, 타입이 지정된 제어 연산자, 효율적인 효과 표현에 이어집니다. 달라진 것은 CPS만으로 최종 추상화를 이뤄야 한다는 기대입니다. + +van der Ploeg와 Kiselyov의 [*Reflection without Remorse*](https://okmij.org/ftp/Haskell/zseq.pdf)를 참고하세요. 더 넓은 제어 주제는 Kiselyov의 [연속 실행 및 구획 제어 모음](https://okmij.org/ftp/continuations/index.html)을 참고하세요. + +
+ +## 디펑셔널라이즈된 기계 {#defunctionalized-machines} + +디펑셔널라이제이션은 CPS 연속 실행 같은 알려진 함수 값 계열을 일차 생성자와 `apply` 연산으로 대체합니다. 그러면 작동 의미론으로 결과 명시 구성 사이의 전이를 설명할 수 있습니다. + +구체적인 CPS 변환에 디펑셔널라이제이션을 이어 적용하면 그 전이들로 추상 기계를 도출할 수 있습니다. 강력한 도출 방법이지만 작동 의미론 일반의 정의는 아닙니다. 작동 규칙이 반드시 CPS에서 나올 필요는 없으며, 임의의 일차 기계가 자동으로 디펑셔널라이즈된 연속 실행 기계가 되는 것도 아닙니다. + +
+Reynolds: 디펑셔널라이제이션의 시작 + +John C. Reynolds는 1972년 정의적 인터프리터 연구에서 디펑셔널라이제이션을 소개했습니다. 출발점은 일차 가상 머신이 아니라 고차 인터프리터였습니다. 정의 언어의 함수가 환경, 연속 실행 및 정의 대상 언어의 다른 부분을 나타냈습니다. + +이 변환은 전체 프로그램에 나타날 수 있는 유한한 함수 추상화 계열을 살펴봅니다. 각 추상화를 자유 변수 값을 담은 일차 생성자로 바꾸고, 함수 적용은 그 생성자를 판별하는 하나의 `apply` 연산으로 대체합니다. 정의 언어 안에 암묵적으로 있던 것이 클로저나 연속 실행의 명시적 대수가 됩니다. + +연속 실행 기반 인터프리터에 적용하면 기계 구조가 드러납니다. 연속 실행 생성자는 제어 상태가 되고, 포착한 변수는 저장된 기계 데이터가 되며, `apply`는 전이 디스패처가 됩니다. 기계를 먼저 추측하는 것이 아니라 고차 평가기에서 도출합니다. + +Reynolds는 이런 명료함의 대가도 강조했습니다. 결과 기계에는 올바르지만 유일하지 않은 표현 선택이 들어갑니다. 생성자를 다르게 선택하거나 선행 변환을 달리하면 동작은 같아도 기계와 같은 “톱니와 바퀴”의 집합이 달라질 수 있습니다. 따라서 디펑셔널라이제이션은 작동 구조를 드러내지만 언어의 유일한 필연적 의미를 드러내지는 않습니다. + +이후 Danvy와 Nielsen은 Reynolds의 기법을 전체 프로그램 변환으로 체계화하고 역변환인 리펑셔널라이제이션을 연구했습니다. 더 깊은 결론은 이 변환이 다리라는 점입니다. 고차 정의와 일차 기계 사이에서 명세와 정확성 논증을 옮길 수 있고, 겉보기에는 무관한 프로그램이 같은 구조의 서로 다른 표현임을 드러낼 수 있습니다. + +이 연구 계보가 이 기법의 적절한 권위를 보여 줍니다. 디펑셔널라이제이션은 클로저를 열거형으로 바꾸는 것 이상이지만 보편적 토대는 아닙니다. 대응 관계를 증명해야 하는 표현 사이에서 의미를 보존하며 이동하는 방법입니다. + +Reynolds의 [*Definitional Interpreters for Higher-Order Programming Languages*](https://homepages.inf.ed.ac.uk/wadler/papers/papers-we-love/reynolds-definitional-interpreters-1972.pdf)와 Danvy 및 Nielsen의 [*Defunctionalization at Work*](https://tidsskrift.dk/brics/article/view/21684)을 참고하세요. + +
+ +## 작동 표현의 순환 {#the-operational-representation-cycle} + +모든 프로그래밍 문제를 해결하는 작동 표현 하나를 찾으려는 것은 흔한 실수입니다. 각 표현은 이전 표현이 감춘 것을 되살리지만 다른 문제를 더 어렵게 만듭니다: + +$$ \text{higher-order program} \longrightarrow \text{free syntax} \longrightarrow \text{CPS} \longrightarrow \text{first-order machine} \longrightarrow \text{higher abstraction} $$ + +화살표는 필연적인 컴파일러 파이프라인을 주장하지 않습니다. 현재 표현이 감추는 것을 드러낸 다음, 그 과정에서 새로 생긴 장치를 감추는 반복적인 설계 움직임을 보여 줍니다. + +| 표현 | 제공하는 것 | 유발하는 부담 | +| --- | --- | --- | +| 고차 함수 | 직접 합성과 호스트 언어의 추상화 | 제네릭 사용자는 함수를 호출할 수 있지만 숨겨진 구조는 검사할 수 없습니다 | +| 시퀀싱을 갖춘 자유 구문 | 합성하고 해석할 수 있는 데이터로서의 프로그램 | 자유 구성만으로는 영역 등식, 정규화, 효율적인 평가, 저장된 함수의 검사를 제공하지 않습니다 | +| CPS | 평가 순서와 계산의 나머지가 명시됩니다 | 프로그램 전체의 CPS 인코딩은 거의 모든 인터페이스에 연속 실행을 전달합니다 | +| 디펑셔널라이즈된 일차 제어 | 연속 실행이 검사 및 직렬화 가능한 사례가 됩니다 | 생성자, 저장된 인수, 전이 상태, `apply` 연산을 명시적으로 관리해야 합니다 | +| 기계 위의 상위 추상화 | 장치를 사용하기 쉬워집니다 | 컴파일러, 스케줄러, 디버거, 최적화기가 구조를 검사해야 할 때 다시 감춰집니다 | + +이 부담은 구조에서 비롯됩니다. 검사는 데이터가 있어야 가능합니다. 동작을 데이터로 바꾸면 생성자와 인터프리터가 생깁니다. 생성자를 감추면 편리한 추상화가 돌아오지만 프로그램을 분석하거나 변환하는 사용자가 필요한 바로 그 접근이 사라집니다. + +자유 모나드의 절충은 특히 시사적입니다. 자유 모나드는 하나의 정확한 문제를 해결합니다. 모나드 법칙 외에 등식을 추가하지 않고 명령어 펑터의 시퀀싱을 생성합니다. 이 보장은 동시에 한계이기도 합니다. 도메인의 법칙은 알지 못합니다. 같은 셀에 대한 두 쓰기가 최종 쓰기와 같아야 하더라도, 도메인별 정규화나 해석이 이를 식별하기 전까지 자유 프로그램에는 명령어 둘이 모두 남습니다. 따라서 최적화, 정규형, 의미론적 동등성은 다른 곳에서 제공해야 합니다. + +명령어를 재구화해도 전체 프로그램을 일관되게 검사할 수 있는 것은 아닙니다. 일반적인 인코딩에서는 보류된 명령어가 보이지만 그 연속 실행은 호스트 언어의 함수입니다. 제네릭 분석기는 결과를 제공해 함수를 적용하지 않는 한 그 함수 뒤의 미래 구조를 검사할 수 없습니다. 연속 실행을 재구화하면 검사 기능이 돌아오지만 일차 또는 디펑셔널라이즈된 표현으로 이동하여 순환의 다음 단계로 돌아갑니다. + +평가 비용도 표현에 따라 다릅니다. 왼쪽으로 결합된 바인드 트리를 단순하게 쓰면 반복 순회와 제곱 시간 작업이 필요할 수 있습니다. 남은 하위 프로그램을 복제하는 변환은 지수적 증가를 초래할 수 있습니다. Codensity형, 프리어형 또는 특수화 인코딩은 다른 표현과 절충을 선택해 특정 비용을 개선할 수 있습니다. 지수적 증가는 가능하지만 자유 모나드의 고유 법칙은 아닙니다. + +따라서 자유 모나드는 만능 해법이 아닙니다. 법칙에 맞는 시퀀싱을 갖춘 구문을 제공할 뿐, 의도된 영역 등식, 정규형, 완전한 구조 가시성, 자동으로 효율적인 구현을 제공하지 않습니다. 마찬가지로 CPS를 국소적으로 쓸 때 시스템 전체에 퍼질 필요는 없으며, 디펑셔널라이제이션의 번거로움은 재구화해야 하는 함수 계열과 포착된 값의 규모에 비례합니다. + +새 인코딩을 보편적 토대로 삼으려 할 때 순환이 나타납니다. 이전 작동상의 불편을 해결한 뒤 다음 우발적 복잡성의 원인이 됩니다. + +그래서 “최고의 추상화”에 관한 논쟁을 작동 방식에만 가두면 결론이 나지 않습니다. 고차 함수, 자유 구문, CPS, 일차 기계를 마치 하나가 다른 것을 반드시 압도해야 하는 것처럼 비교합니다. 그러나 무엇을 보존해야 하고 누가 결과를 사용할지 명시하지 않으면 *더 낫다*는 말은 의미가 없습니다: + +* 직접 실행은 일반 호출과 숨겨진 표현을 선호합니다; +* 변환과 분석에는 검사 가능한 구조가 필요합니다; +* 직렬화에는 일차 데이터가 필요합니다; +* 확장성은 해석 추가나 구문 추가 중 하나를 선호할 수 있지만 대개 양쪽을 똑같이 선호하지는 않습니다; +* 동시성에서는 많은 스케줄링 선택을 의도적으로 무시하는 관찰이 필요할 수 있습니다. + +이는 서로 다른 요구 사항이지 하나의 추상화가 보편적으로 우월하다는 연속된 증거가 아닙니다. 작동 특성으로 명시된 목적에 맞는 구현을 선택할 수는 있지만, 목적을 대신하거나 어떤 구분이 의미 있는지 결정할 수는 없습니다. + +순차적인 사고에도 같은 주의가 필요합니다. 작동 의미론으로 동시 및 비결정적 시스템을 설명할 수 있지만, 기계 단계의 단일 시퀀스는 그 동작 표현 중 하나일 뿐입니다. 스케줄 순서를 너무 일찍 권위 있는 것으로 만들면 기계적 실행이 다르게 인터리빙되었다는 이유만으로 동등한 실행이 달라집니다. 의미 모델은 먼저 동시성 프로그램을 구분하는 관찰이 무엇인지 정해야 하고, 작동 스케줄은 그 결정에 비추어 평가해야 합니다. + +## 실제 예: EVM {#real-example-the-evm} + +이더리움 가상 머신(EVM)은 작동 방식으로 이해할 수 있습니다: + +* **상태**: 프로그램 카운터, 스택, 메모리, 저장소, 가스 +* **전이 규칙**: 각 연산 코드(`ADD`, `PUSH`, `SSTORE` 등)에 하나씩 +* **실행**: 정지할 때까지 소단계 규칙을 반복 적용 + +EVM 바이트코드는 일차 명령어 데이터입니다. 작동 설명은 각 연산 코드에서 EVM 구성이 어떻게 바뀌는지 명시하고, 구체적인 클라이언트가 그 동작을 구현합니다. + +디스패치 루프와 프로그램 카운터는 디펑셔널라이즈된 추상 기계와 비슷해 보일 수 있습니다. 그러나 이를 디펑셔널라이즈된 연속 실행이라고 부르려면 겉모양이 비슷한 루프만으로는 부족하고 구체적인 고차 소스, 변환, 대응 관계가 필요합니다. + +## 순환 끊기: 구현 장치보다 의미를 먼저 {#breaking-the-cycle-meaning-before-machinery} + +작동 설명과 표시 설명은 서로 다른 질문에 답합니다: + +$$ \begin{aligned} \llbracket p \rrbracket &\in D && \text{what does the program mean?} \\ c &\longrightarrow c' && \text{how does this representation step?} \end{aligned} $$ + +의미 우선 개발에서는 기계 표현을 확정하기 전에 의미론적 영역, 합성, 관찰, 법칙을 선택합니다. 전이 시스템을 선택한 뒤에는 정확성 의무가 두 계층을 연결합니다. 전체 구성을 적절히 정의한 의미에 대해 일반적인 무음 전이 보존 주장은 다음과 같은 형식입니다: + +$$ c \longrightarrow c' \quad \Longrightarrow \quad \operatorname{meaning}(c) = \operatorname{meaning}(c') $$ + +정확한 관계는 관찰적 동치, 실행 기록, 쌍방향 시뮬레이션을 사용할 수 있습니다. 중요한 것은 기계를 의도된 의미에 비추어 검증할 수 있어야 한다는 점입니다. + +표시적 설계는 순환에서 승자를 고르지 않습니다. 그 바깥에 안정적인 권위의 원천을 세웁니다: + +1. 의미론적 영역, 연산, 합성, 법칙을 정의합니다. +2. 그 의미를 바탕으로 프로그램을 작성합니다. +3. 직접 실행, 검사, 컴파일, 스케줄링, 직렬화, 분석 등 구체적 사용자를 위한 표현을 선택합니다. +4. 선택한 모든 표현과 변환을 같은 의미에 연결합니다. + +따라서 고차 인터프리터와 일차 프로그램은 함께 존재할 수 있습니다. 둘 중 어느 쪽도 언어의 정의일 필요는 없습니다. 전자는 직접 실행을 담당하고 후자는 구조가 필요한 사용자를 지원할 수 있습니다. 두 기계적 방식이 동일하다는 가정이 아니라 두 표현이 일치해야 한다는 의미론적 의무가 있습니다. + +```admonish note title="최종 작동 추상화는 없습니다" +모든 작동 표현은 어떤 구조를 드러내고 다른 구조를 감춥니다. 의미는 적절한 표현을 선택하고 연관 짓는 안정적인 기준입니다. +``` + +## 요약 {#summary} + +* 작동 의미론은 선택된 표현의 평가나 전이를 설명합니다. +* 자유 모나드는 명령어 구문과 시퀀싱을 제공하지만 그 동작은 여전히 해석이 필요합니다. +* CPS는 연속 실행을 드러내며, 작동 규칙은 CPS 프로그램에서 값과 제어가 전달되는 방식을 설명할 수 있습니다. +* 디펑셔널라이제이션은 특정 고차 프로그램을 작동 규칙으로 전이를 명시할 수 있는 일차 기계로 바꿀 수 있습니다. +* 이러한 인코딩 중 하나를 보편적인 것으로 취급하면 구조를 재구화하고 감추는 순환이 생깁니다. +* 표시적 의미가 그 전이가 무엇을 보존해야 하는지 결정합니다. diff --git a/src/insights/operational_semantics.ru.md b/src/insights/operational_semantics.ru.md new file mode 100644 index 0000000..15dfc0f --- /dev/null +++ b/src/insights/operational_semantics.ru.md @@ -0,0 +1,181 @@ + + +# От семантики к машинам {#semantics-to-machines} + +```admonish tip title="Связанные материалы" +«Проектирование на основе смысла в Rust»: [Программы первого порядка](../rust-dd/first-order-programs.md), [Язык и конвейеры компилятора](../rust-dd/compiler-pipelines.md) +«Понятия»: [Операционная семантика](../concepts/operational_semantics.md), [Свободная монада](../concepts/free_monad.md), [Стиль передачи продолжений](../concepts/cps.md), [Дефункционализация](../concepts/defunctionalization.md) +``` + +## Что описывает операционная семантика {#what-operational-semantics-describes} + +Операционная семантика задаёт поведение выбранного представления программы. Она определяет оценочные суждения или отношение переходов над конфигурациями, например: + +$$ (\mathit{program}, \mathit{state}) \longrightarrow (\mathit{program}', \mathit{state}') $$ + +Программой может быть синтаксис исходного языка, значение свободной монады, терм CPS, байткод или дефункционализированное состояние машины. Ни одно из этих представлений *не является* операционной семантикой. Операционная семантика описывает, как вычисляются значения выбранного представления или как они переходят к следующему шагу. + +Направление здесь важно. Представление даёт объект, поведение которого можно описать; операционное описание само по себе не объясняет, каким должен быть смысл языка. + +## Программы на свободных монадах {#free-monad-programs} + +Свободная монада предоставляет синтаксис инструкций и свободно порождённую последовательность их выполнения, но не поведение этих инструкций. + +Операционная семантика программы на свободной монаде может задавать конфигурации с текущей инструкцией, её продолжением и состоянием машины. Затем правила описывают, например, как приостановленная инструкция изменяет состояние и передаёт результат оставшейся части программы. + +Это одна из возможных интерпретаций. Ту же свободную программу можно свернуть в денотационную модель, скомпилировать в другой язык, проанализировать или визуализировать без выполнения. + +
+От свободных монад к freer: выводы исследований + +Читателей, которые встретили свободные монады как общую архитектуру программ с эффектами, может удивить, почему позднее обсуждение сместилось к freer-конструкциям, расширяемым эффектам и обработчикам. Свободные монады не были просто отброшены. Исследователи выделили то, что они действительно предоставляют, измерили ограничения распространённых представлений и развили полезную структуру. + +Киселёв и Исии выводят freer-монады, постепенно снимая ограничения и шаблонный код в представлениях термов с эффектами. В freer-представлении инструкция может выдавать промежуточный тип, скрытый от типа конечной программы, а явное продолжение связывает результат с оставшейся частью вычисления. Поэтому сигнатуре инструкции больше не требуется экземпляр `Functor`. + +Это повышает выразительность, но само по себе не решает проблему производительности. Прямое freer-представление по-прежнему компонует продолжения так же, как конкатенация списков, сцепленных слева: обработка цепочки из $n$ запросов может требовать $O(n^2)$ работы. Явное продолжение показывает реальную возможность: хранить его как типизированную по последовательности структуру, где тип результата одного элемента по построению совпадает с типом входа следующего. Эффективная конкатенация такой последовательности устраняет обход, зависящий от порядка ассоциации. + +Открытые объединения позволяют интерпретатору расширяемых эффектов добавлять, объединять и устранять выбранные типы запросов. Это решает задачи модульной композиции эффектов и структуры обработчиков, но не предоставляет уравнений конкретной предметной области и не решает, когда две программы с эффектами имеют один и тот же смысл. + +Вывод точнее, чем «freer лучше свободных». Свободные монады показали ценность разделения запросов и интерпретации. Freer-кодирование устранило ненужное ограничение; типизированные очереди устранили измеренную проблему производительности; расширяемые эффекты улучшили композицию. Каждый шаг сохранял полезные знания предыдущего и уточнял утверждение. Семантическая интерпретация всё это время оставалась отдельным решением. + +См. Киселёва и Исии, [*Freer Monads, More Extensible Effects*](https://okmij.org/ftp/Haskell/extensible/more.pdf). + +
+ +## Программы CPS {#cps-programs} + +Стиль передачи продолжений (CPS) явно представляет остаток вычисления в виде продолжения. Операционная семантика CPS описывает такое поведение, как: + +* вычисление текущего выражения CPS; +* передача созданного значения его продолжению; +* передача управления при применении этого продолжения. + +CPS раскрывает управление в форме, удобной для операционного описания, но остаётся представлением или преобразованием программы, а не операционной семантикой. Чтобы связать программу прямого стиля с её переводом в CPS, нужны заданные семантики исходного и целевого языков и доказательство сохранения смысла. + +
+За пределами CPS: когда продолжения нужно анализировать + +CPS — стандартное решение проблемы конкатенации и bind, зависящих от ассоциации. Вместо повторного обхода структуры, сцепленной слева, он представляет оставшееся вычисление композицией функций. Это эффективно, когда единственная операция над продолжением — его последующее применение. + +Ван дер Плоег и Киселёв определяют границу применимости: некоторым потребителям нужно проверять или изменять промежуточный результат перед продолжением. К таким случаям относятся недетерминированный поиск, итераторы, свободные монады и расширяемые эффекты. CPS скрывает концептуальную последовательность внутри функции; для восстановления промежуточной структуры требуется рефлексия обратно в данные, что может свести преимущество в производительности на нет. + +Их альтернатива напрямую представляет скрытую последовательность типизированной по последовательности структурой данных. Она обеспечивает эффективную композицию независимо от порядка ассоциации и сохраняет эффективный доступ к промежуточным результатам. Типы гарантируют, что каждое сохранённое вычисление выдаёт именно тот вход, который требуется следующему. + +Общий вывод не в том, что типизированные по последовательности структуры превосходят CPS. CPS отлично подходит для *применения* продолжений, но хуже — когда их нужно *анализировать*. Исследования ограниченного управления уточняют этот урок: вместо одного неразличимого продолжения для всего будущего разделители указывают, какую часть окружающего вычисления можно захватить и изменить. + +Эти идеи не исчезли. Они продолжают влиять на обработчики эффектов, вывод абстрактных машин, типизированные операторы управления и эффективные представления эффектов. Изменилось лишь ожидание, будто CPS должен быть окончательной абстракцией. + +См. ван дер Плога и Киселёва, [*Reflection without Remorse*](https://okmij.org/ftp/Haskell/zseq.pdf). О более широком контексте управления см. [собрание материалов Киселёва о продолжениях и ограниченном управлении](https://okmij.org/ftp/continuations/index.html). + +
+ +## Дефункционализированные машины {#defunctionalized-machines} + +Дефункционализация заменяет известное семейство значений-функций, например продолжений CPS, конструкторами первого порядка и операцией `apply`. Тогда операционная семантика может описывать переходы между получившимися явными конфигурациями. + +Конкретное CPS-преобразование с последующей дефункционализацией позволяет вывести абстрактную машину. Это мощный способ вывода, но не общее определение операционной семантики: операционные правила не обязаны происходить из CPS, а произвольная машина первого порядка от этого не становится машиной дефункционализированных продолжений. + +
+Рейнольдс: истоки дефункционализации + +Джон К. Рейнольдс ввёл дефункционализацию в исследовании определяющих интерпретаторов 1972 года. Он исходил не из виртуальной машины первого порядка, а из интерпретатора высшего порядка: функции определяющего языка представляли окружения, продолжения и другие части описываемого языка. + +Преобразование учитывает конечное семейство функциональных абстракций, которые могут встретиться во всей программе. Каждая абстракция заменяется конструктором первого порядка, хранящим значения её свободных переменных, а применение функции — одной операцией `apply`, выбирающей действие по конструктору. Неявная структура определяющего языка становится явной алгеброй замыканий или продолжений. + +При применении к интерпретатору на основе продолжений этот шаг раскрывает машину: конструкторы продолжений становятся состояниями управления, захваченные переменные — данными машины, а `apply` — диспетчером переходов. Машину не придумывают заранее, а выводят из интерпретатора высшего порядка. + +Рейнольдс также подчёркивал цену этой ясности. Полученная машина содержит решения о представлении, которые корректны, но не единственны. Разные конструкторы или предварительные преобразования приводят к разным наборам похожих на машину «шестерёнок и колёс», сохраняя при этом поведение. Дефункционализация раскрывает операционную структуру, а не единственный неизбежный смысл языка. + +Позднее Данви и Нильсен систематизировали метод Рейнольдса как преобразование всей программы и изучили рефункционализацию как обратное преобразование. Более общий вывод в том, что дефункционализация служит мостом: она переносит спецификации и доказательства корректности между определениями высшего порядка и машинами первого порядка, а также показывает, как внешне несвязанные программы могут быть двумя представлениями одной структуры. + +Эта линия исследований точно определяет силу метода. Дефункционализация — больше, чем замена замыканий перечислением, но меньше, чем универсальная основа: это сохраняющий смысл переход между представлениями, соответствие которых необходимо установить. + +См. Рейнольдса, [*Definitional Interpreters for Higher-Order Programming Languages*](https://homepages.inf.ed.ac.uk/wadler/papers/papers-we-love/reynolds-definitional-interpreters-1972.pdf), и Данви и Нильсена, [*Defunctionalization at Work*](https://tidsskrift.dk/brics/article/view/21684). + +
+ +## Цикл операционных представлений {#the-operational-representation-cycle} + +Распространённая ошибка — искать одно операционное представление, которое решит все задачи программирования. Каждое представление раскрывает то, что скрывало предыдущее, но затрудняет рассмотрение другого аспекта: + +$$ \text{higher-order program} \longrightarrow \text{free syntax} \longrightarrow \text{CPS} \longrightarrow \text{first-order machine} \longrightarrow \text{higher abstraction} $$ + +Стрелки не задают обязательный конвейер компиляции. Они показывают повторяющийся ход проектирования: раскрыть то, что скрывает текущее представление, а затем скрыть механизмы, добавленные этим раскрытием. + +| Представление | Что оно делает доступным | Какие ограничения вводит | +| --- | --- | --- | +| Функции высшего порядка | Прямая композиция и абстракции языка-хозяина | Обобщённый потребитель может вызвать функцию, но не может исследовать скрытую в ней структуру | +| Свободный синтаксис с последовательностью выполнения | Программы представлены данными, которые можно компоновать и интерпретировать | Свободная структура сама по себе не задаёт уравнения предметной области, нормализацию, эффективное вычисление и анализ сохранённых функций | +| CPS | Порядок вычисления и оставшаяся часть программы становятся явными | В CPS-преобразовании всей программы продолжения проходят почти через каждый интерфейс | +| Дефункционализированное управление первого порядка | Продолжения становятся анализируемыми и сериализуемыми вариантами данных | Конструкторы, сохранённые аргументы, состояния переходов и операция `apply` требуют явного сопровождения | +| Более высокий уровень абстракции над машиной | С механизмами становится удобнее работать | Структура снова скрывается, когда компилятору, планировщику, отладчику или оптимизатору нужно её анализировать | + +Эти ограничения структурные. Для анализа нужны данные. Превращение поведения в данные добавляет конструкторы и интерпретатор. Сокрытие конструкторов возвращает удобную абстракцию, но лишает доступа потребителей, которым нужно анализировать или преобразовывать программы. + +Компромисс свободной монады особенно поучителен. Свободная монада решает одну конкретную задачу: порождает последовательность выполнения для функтора инструкций, не вводя уравнений сверх законов монады. Это же ограничивает её возможности: она не знает законов предметной области. Если две записи в одну ячейку должны быть эквивалентны последней записи, свободная программа всё равно содержит обе инструкции, пока нормализация или интерпретация предметной области не объединит их. Оптимизация, каноническая форма и семантическое равенство должны быть заданы где-то ещё. + +И реификация инструкций не делает программу целиком доступной для анализа. В распространённых кодированиях приостановленная инструкция видна, а её продолжение остаётся функцией языка-хозяина. Обобщённый анализатор не может исследовать будущую структуру за этой функцией, не задав результат и не применив её. Реификация продолжения возвращает возможность анализа через переход к представлению первого порядка или дефункционализации — и приводит к следующему этапу цикла. + +Стоимость вычисления также зависит от представления. Наивное дерево операций bind, сцепленных слева, может требовать повторного обхода и квадратичных затрат. Преобразование, дублирующее остаточные подпрограммы, может привести к экспоненциальному росту. Кодирования в стиле codensity, freer или специализированные решения улучшают отдельные затраты, выбирая другие представления и компромиссы. Экспоненциальный рост возможен, но не является неотъемлемым законом свободных монад. + +Поэтому свободная монада не является универсальным решением. Она даёт синтаксис с последовательностью выполнения, подчиняющейся законам монады, но не уравнения предметной области, каноническую нормальную форму, полную структурную видимость или автоматически эффективную реализацию. Точно так же CPS не обязательно распространять на всю систему, если применять его локально, а дефункционализация сложна лишь настолько, насколько велико семейство функций и захватываемых значений, которое приходится реифицировать. + +Цикл возникает, когда от каждого нового кодирования требуют стать универсальным основанием. Оно устраняет прежнее операционное неудобство, а затем само становится новым источником случайной сложности. + +Поэтому споры о «лучшем» уровне абстракции не сходятся, если остаются только операционными. Функции высшего порядка, свободный синтаксис, CPS и машины первого порядка сравнивают так, будто одно должно превосходить остальные. Но *лучше* ничего не значит, пока сравнение не определяет, что нужно сохранить и кому нужен результат: + +* прямое выполнение поощряет обычные вызовы и скрытое представление; +* преобразование и анализ требуют структуры, доступной для изучения; +* сериализация требует данных первого порядка; +* расширяемость может способствовать добавлению интерпретаций или синтаксиса, но редко в одинаковой мере обоим; +* для параллельности могут понадобиться наблюдения, намеренно опускающие множество решений планировщика. + +Это разные требования, а не последовательные доказательства универсального превосходства одной абстракции. Операционные свойства могут помочь выбрать реализацию для заданной цели, но не задают саму цель и не решают, какие различия имеют смысл. + +То же предостережение относится к последовательному мышлению. Операционная семантика может описывать параллельные и недетерминированные системы, однако одна последовательность машинных шагов — лишь один вариант представления их поведения. Если слишком рано придать порядку планирования решающее значение, эквивалентные выполнения станут различаться лишь потому, что их механизмы чередовались по-разному. Сначала семантическая модель должна определить, какие наблюдения различают параллельные программы; затем операционные расписания можно оценить согласно этому решению. + +## Пример из практики: EVM {#real-example-the-evm} + +Виртуальную машину Ethereum (EVM) можно описать операционно: + +* **Состояние**: счётчик команд, стек, память, хранилище, газ +* **Правила переходов**: по одному для каждой операции (`ADD`, `PUSH`, `SSTORE` и т. д.) +* **Выполнение**: повторное применение правил малых шагов до остановки + +Байткод EVM — данные инструкций первого порядка. Операционное описание задаёт изменение конфигурации EVM для каждой операции, а конкретный клиент реализует это поведение. + +Цикл диспетчеризации и счётчик команд могут напоминать дефункционализированную абстрактную машину. Однако называть их дефункционализированными продолжениями можно только при наличии конкретного источника высшего порядка, преобразования и соответствия, а не на основании внешнего сходства циклов. + +## Разорвать цикл: смысл прежде механизмов {#breaking-the-cycle-meaning-before-machinery} + +Операционное и денотационное описания отвечают на разные вопросы: + +$$ \begin{aligned} \llbracket p \rrbracket &\in D && \text{what does the program mean?} \\ c &\longrightarrow c' && \text{how does this representation step?} \end{aligned} $$ + +Разработка с приоритетом смысла сначала выбирает семантическую область, композицию, наблюдения и законы и только затем закрепляет представление машины. После выбора системы переходов обязательство корректности связывает два слоя. Для подходящего определения смысла полных конфигураций типичное утверждение о сохранении смысла при бесшумном переходе имеет вид: + +$$ c \longrightarrow c' \quad \Longrightarrow \quad \operatorname{meaning}(c) = \operatorname{meaning}(c') $$ + +Вместо этого отношения могут использовать контекстную эквивалентность, трассы или бисимилярность. Важно, чтобы машина отвечала за соответствие предполагаемому смыслу. + +Денотационное проектирование не выбирает победителя в этом цикле, а создаёт устойчивый источник решений вне его: + +1. Определите семантическую область, операции, композицию и законы. +2. Пишите программы в терминах этого смысла. +3. Выбирайте представление под конкретную задачу: выполнение, анализ, компиляцию, планирование, сериализацию или проверку. +4. Связывайте каждое выбранное представление и преобразование с одним и тем же смыслом. + +Поэтому интерпретатор высшего порядка и программа первого порядка могут сосуществовать. Ни один из них не обязан определять язык. Первый может обеспечивать прямое выполнение, второй — обслуживать потребителей, которым нужна структура. Их согласие — семантическое обязательство, а не предположение, что механизмы должны совпадать. + +```admonish note title="Окончательной операционной абстракции нет" +Каждое операционное представление раскрывает одни структуры и скрывает другие. Устойчивой точкой остаётся смысл: исходя из него выбирают подходящие представления и связывают их друг с другом. +``` + +## Итоги {#summary} + +* Операционная семантика описывает вычисление или переходы для выбранного представления. +* Свободные монады дают синтаксис инструкций и последовательность выполнения, поведение которой всё ещё требует интерпретации. +* CPS раскрывает продолжения; операционные правила могут описывать передачу значений и управления в программах CPS. +* Дефункционализация может преобразовать конкретную программу высшего порядка в машину первого порядка с операционно задаваемыми переходами. +* Если считать какое-либо одно из этих кодирований универсальным, возникает цикл повторной реификации и сокрытия структуры. +* Денотационный смысл определяет, что именно должны сохранять эти переходы. diff --git a/src/insights/operational_semantics.uk.md b/src/insights/operational_semantics.uk.md new file mode 100644 index 0000000..920908f --- /dev/null +++ b/src/insights/operational_semantics.uk.md @@ -0,0 +1,181 @@ + + +# Від семантики до машин {#semantics-to-machines} + +```admonish tip title="Пов’язані матеріали" +Проєктування від значення в Rust: [Програми першого порядку](../rust-dd/first-order-programs.md), [Мова й конвеєри компілятора](../rust-dd/compiler-pipelines.md) +Поняття: [Операційна семантика](../concepts/operational_semantics.md), [Вільна монада](../concepts/free_monad.md), [Стиль передавання продовжень](../concepts/cps.md), [Дефункціоналізація](../concepts/defunctionalization.md) +``` + +## Що описує операційна семантика {#what-operational-semantics-describes} + +Операційна семантика визначає поведінку вибраного представлення програми. Вона задає судження про обчислення чи відношення переходів між конфігураціями, наприклад: + +$$ (\mathit{program}, \mathit{state}) \longrightarrow (\mathit{program}', \mathit{state}') $$ + +Програма може бути синтаксисом вихідної мови, значенням вільної монади, термом CPS, байткодом чи дефункціоналізованим станом машини. Жодне з цих представлень *не є* операційною семантикою. Операційна семантика описує, як обчислюються чи переходять значення вибраного представлення. + +Цей напрямок важливий. Представлення дає матеріал, поведінку якого можна описати; операційний опис сам по собі не пояснює, яке значення має мати мова. + +## Програми вільних монад {#free-monad-programs} + +Вільна монада надає синтаксис інструкцій і вільно породжене послідовне виконання. Але вона не визначає поведінку цих інструкцій. + +Операційна семантика програми вільної монади може визначати конфігурації, що містять поточну інструкцію, її продовження й стан машини. Тоді правила пояснюють, наприклад, як призупинена інструкція змінює стан і передає результат решті програми. + +Це одна можлива інтерпретація. Ту саму програму вільної монади можна згорнути в денотаційну модель, скомпілювати іншою мовою, проаналізувати чи відтворити без виконання. + +
+Від free до freer: що виявили дослідження + +Читачі, які сприймали вільні монади як загальну архітектуру програм з ефектами, можуть запитати, чому згодом увага перемістилася до конструкцій freer, розширюваних ефектів і обробників. Дослідження не просто відкинули вільні монади. Воно відокремило те, що вони справді дають, виміряло, де не справляються поширені представлення, і зберегло корисну структуру. + +Кісельов та Ішії виводять freer-монади, поступово усуваючи обмеження й шаблонний код із представлень термів з ефектами. У freer-представленні інструкція може повертати проміжний тип, прихований у кінцевому типі програми, а явне продовження пов’язує цей результат із рештою обчислення. Тому сигнатурі інструкції більше не потрібен екземпляр `Functor`. + +Це робить представлення виразнішим, але саме по собі не вирішує проблеми продуктивності. Пряме freer-представлення й далі поєднує продовження так само, як додають елементи до лівоасоційованого списку: обробка ланцюжка з $n$ запитів може потребувати $O(n^2)$ роботи. Явне представлення продовження виявляє можливість — зберігати його як типово узгоджену послідовність, у якій тип результату одного елемента збігається з типом входу наступного. Ефективна конкатенація цієї послідовності усуває обхід, залежний від асоціативності. + +Відкриті об’єднання дають інтерпретатору розширюваних ефектів змогу додавати, поєднувати й усувати вибрані типи запитів. Це допомагає модульно комбінувати ефекти й структурувати обробники, але не визначає рівнянь конкретної предметної області й не вирішує, коли дві програми з ефектами мають те саме значення. + +Висновок точніший за твердження «freer кращий за free». Вільні монади виявили корисне розділення між запитами й інтерпретацією. Кодування freer прибрало зайве обмеження; типово узгоджені черги розв’язали виміряну проблему продуктивності; розширювані ефекти поліпшили композицію. Кожен крок зберіг знання попереднього, водночас точніше окреслюючи свої твердження. Семантичну інтерпретацію й надалі вибирали окремо. + +Див. Кісельов та Ішії, [*Freer Monads, More Extensible Effects*](https://okmij.org/ftp/Haskell/extensible/more.pdf). + +
+ +## Програми CPS {#cps-programs} + +Стиль передавання продовжень (CPS) явно представляє решту обчислення як продовження. Операційна семантика для CPS описує, зокрема: + +* обчислення поточного виразу CPS; +* передавання створеного значення продовженню; +* передавання керування під час застосування продовження. + +CPS відкриває потік керування у формі, яку зручно описувати операційно, але це представлення чи перетворення програми, а не операційна семантика. Щоб пов’язати програму в прямому стилі з її перетворенням CPS, потрібні задані семантики вихідної та цільової мов і доведення збереження значення. + +
+За межами CPS: коли потрібно оглядати продовження + +CPS — усталений спосіб позбутися додавання та зв’язування, чутливих до асоціативності. Замість повторного обходу лівоасоційованої структури він представляє решту обчислення композицією функцій. Це може бути ефективним, коли продовження лише зрештою застосовують. + +Ван дер Плог та Кісельов визначають межу цього підходу: деяким споживачам потрібно оглядати чи змінювати проміжний результат до продовження. Такий доступ може знадобитися в недетермінованому пошуку, ітераторах, вільних монадах і розширюваних ефектах. CPS приховує концептуальну послідовність у функції, тому її відновлення вимагає знову перетворити функцію на дані й може знищити перевагу в продуктивності. + +Їхній альтернативний підхід явно представляє приховану послідовність типово узгодженою структурою даних. Вона ефективно композиційно поєднується незалежно від асоціативності й водночас дає швидкий доступ до проміжних результатів. Типи гарантують, що кожне збережене обчислення видає значення, очікуване наступним. + +Ширший висновок не в тому, що типово узгоджені послідовності долають CPS. CPS чудово *застосовує* продовження, але менш придатний, коли споживачеві потрібно їх *оглядати*. Дослідження обмеженого керування посилюють цей урок: замість ставитися до всього майбутнього як до одного нерозрізненого продовження, роздільники визначають, яку саме частину навколишнього обчислення можна захопити й змінити. + +Ці ідеї не зникли. Вони залишилися в обробниках ефектів, виведенні абстрактних машин, типізованих операторах керування та ефективних представленнях ефектів. Змінилося очікування, ніби одного CPS досить як остаточної абстракції. + +Див. ван дер Плог та Кісельов, [*Reflection without Remorse*](https://okmij.org/ftp/Haskell/zseq.pdf). Ширший контекст керування описано в [continuations and delimited-control collection](https://okmij.org/ftp/continuations/index.html). + +
+ +## Дефункціоналізовані машини {#defunctionalized-machines} + +Дефункціоналізація замінює відоме сімейство значень-функцій, наприклад продовження CPS, конструкторами першого порядку й операцією `apply`. Тоді операційна семантика може описувати переходи між явними конфігураціями, що утворилися. + +Якщо спершу перетворити програму на CPS, а потім дефункціоналізувати, з цих переходів можна вивести абстрактну машину. Це потужний спосіб її отримати, але не загальне визначення операційної семантики: операційні правила не мусять походити з CPS, а довільна машина першого порядку не стає через це машиною дефункціоналізованих продовжень. + +
+Рейнольдс: початок дефункціоналізації + +У 1972 році Джон К. Рейнольдс запровадив дефункціоналізацію у своєму дослідженні денотаційних інтерпретаторів. Він починав не з віртуальної машини першого порядку, а з інтерпретатора вищого порядку: функції мови, якою було написано визначення, представляли середовища, продовження та інші частини мови, яку визначав інтерпретатор. + +Перетворення визначає скінченне сімейство функційних абстракцій, які можуть з’явитися в усій програмі. Воно замінює кожну абстракцію конструктором першого порядку, що містить значення вільних змінних, а застосування функції — однією операцією `apply`, яка вибирає гілку за конструктором. Те, що мова визначення робила неявно, стає явною алгеброю замикань або продовжень. + +Застосування цього підходу до інтерпретатора з продовженнями відкриває машину: конструктори продовжень стають станами керування, захоплені змінні — збереженими даними машини, а `apply` — диспетчером переходів. Машину не вигадують заздалегідь, а виводять із обчислювача вищого порядку. + +Рейнольдс також наголошував на ціні такої ясності. Отримана машина містить рішення щодо представлення, які є коректними, але не єдино можливими. Інші конструктори чи попередні перетворення можуть дати інший набір «шестерень і коліс» машини, зберігаючи ту саму поведінку. Отже, дефункціоналізація виявляє операційну структуру, але не єдино правильне значення мови. + +Пізніше Данві та Нільсен систематизували метод Рейнольдса як перетворення всієї програми й дослідили рефункціоналізацію як обернену операцію. Їхній глибший висновок полягає в тому, що перетворення слугує мостом: воно переносить специфікації та аргументи щодо коректності між визначеннями вищого порядку й машинами першого порядку, а також може показати, що на перший погляд різні програми є двома представленнями тієї самої структури. + +Ця історія досліджень визначає належну вагу методу. Дефункціоналізація — це більше, ніж замінити замикання переліком, але менше, ніж універсальна основа: це семантично збережне перетворення між представленнями, відповідність між якими треба встановити. + +Див. Рейнольдс, [*Definitional Interpreters for Higher-Order Programming Languages*](https://homepages.inf.ed.ac.uk/wadler/papers/papers-we-love/reynolds-definitional-interpreters-1972.pdf); Данві та Нільсен, [*Defunctionalization at Work*](https://tidsskrift.dk/brics/article/view/21684). + +
+ +## Цикл операційних представлень {#the-operational-representation-cycle} + +Поширена помилка — шукати одне операційне представлення, яке розв’язує всі проблеми програмування. Кожне представлення відкриває щось, приховане попереднім, але ускладнює інше: + +$$ \text{higher-order program} \longrightarrow \text{free syntax} \longrightarrow \text{CPS} \longrightarrow \text{first-order machine} \longrightarrow \text{higher abstraction} $$ + +Стрілки не задають обов’язковий конвеєр компілятора. Вони показують типовий рух у проєктуванні: відкрити те, що приховує поточне представлення, а потім приховати механізми, запроваджені цим відкриттям. + +| Представлення | Що воно відкриває | Які труднощі створює | +| --- | --- | --- | +| Функції вищого порядку | Безпосередня композиція й абстракції мови | Універсальний споживач може викликати функцію, але не може оглянути її приховану структуру | +| Синтаксис із послідовним виконанням | Програми як дані, які можна поєднувати й інтерпретувати | Вільність не надає рівнянь предметної області, нормалізації, ефективного обчислення чи огляду збережених функцій | +| CPS | Порядок обчислення й решта обчислення стають явними | Кодування всієї програми в CPS протягує продовження майже через кожен інтерфейс | +| Дефункціоналізоване керування першого порядку | Продовження стають доступними для огляду випадками, які можна серіалізувати | Потрібно явно підтримувати конструктори, збережені аргументи, стани переходів і операцію `apply` | +| Абстракція вищого рівня над машиною | Механізмами стає легше користуватися | Структура знову прихована, коли компілятору, планувальнику, налагоджувачу чи оптимізатору потрібно її оглянути | + +Ці труднощі мають структурну природу. Для огляду потрібні дані. Перетворення поведінки на дані вимагає конструкторів та інтерпретатора. Приховування конструкторів знову спрощує абстракцію, але прибирає доступ, необхідний споживачам, які аналізують чи перетворюють програми. + +Компроміс вільної монади особливо показовий. Вона розв’язує одну чітку проблему: породжує послідовне виконання для функтора інструкцій, не додаючи рівнянь поза законами монади. Ця гарантія одночасно є її обмеженням — вона не знає законів предметної області. Якщо два записи в ту саму комірку мають бути еквівалентні останньому запису, вільна програма все одно містить обидві інструкції, доки нормалізація чи інтерпретація, специфічна для області, не ототожнить їх. Отже, оптимізація, канонічна форма й семантична рівність мають визначатися десь іще. + +І перетворення інструкцій на дані не робить усю програму доступною для огляду. У поширених кодуваннях призупинена інструкція видима, але її продовження — це функція мови, у якій написано програму. Загальний аналізатор не може оглянути майбутню структуру за цією функцією, не підставивши результат і не застосувавши її. Перетворення продовження на дані знову відкриває структуру, наближаючи представлення до першого порядку чи дефункціоналізованої форми, — і повертає нас до наступної ланки циклу. + +Вартість обчислення так само залежить від представлення. Наївне дерево лівоасоційованих зв’язувань може вимагати повторних обходів і квадратичної роботи. Перетворення, що дублює залишкові підпрограми, може спричинити експоненційне зростання. Кодування у стилі codensity, freer чи спеціалізовані конструкції можуть поліпшити окремі показники, але ціною іншого представлення й компромісів. Експоненційне зростання можливе, але це не внутрішній закон вільних монад. + +Саме тому вільна монада не є універсальним розв’язанням. Вона надає синтаксис із послідовним виконанням за законами, але не рівняння задуманої предметної області, канонічну нормальну форму, повну видимість структури чи автоматично ефективну реалізацію. Так само CPS не обов’язково поширювати на всю систему, якщо використовувати його локально, а дефункціоналізація є громіздкою лише настільки, наскільки великим є сімейство функцій і захоплених значень, які треба представити. + +Цикл виникає тоді, коли від кожного нового кодування очікують, що воно стане універсальною основою. Воно усуває попередню операційну незручність, а потім саме стає новим джерелом випадкової складності. + +Тому суперечки про «найкращу абстракцію» не завершуються, доки залишаються суто операційними. Функції вищого порядку, вільний синтаксис, CPS і машини першого порядку порівнюють так, ніби одне з них має переважати всі інші. Та поняття *краще* не має сенсу, доки порівняння не визначає, що саме треба зберегти й кому потрібен результат: + +* пряме виконання сприяє звичайним викликам і прихованому представленню; +* перетворення й аналіз потребують доступної для огляду структури; +* серіалізація потребує даних першого порядку; +* розширюваність може сприяти додаванню інтерпретацій або синтаксису, але рідко однаково обом; +* паралельність може вимагати спостережень, що навмисно ігнорують багато рішень планувальника. + +Це різні вимоги, а не послідовні докази універсальної переваги однієї абстракції. Операційні властивості можуть допомогти вибрати реалізацію для чітко заданої мети, але самі не визначають мету чи значущі відмінності. + +Те саме застереження стосується послідовного мислення. Операційна семантика може описувати паралельні й недетерміновані системи, але одна послідовність кроків машини є лише одним із можливих представлень їхньої поведінки. Якщо зарано визнати порядок планування визначальним, еквівалентні виконання відрізнятимуться лише через різний порядок механічного чергування. Семантична модель має спершу визначити, які спостереження розрізняють паралельні програми; потім за ними можна оцінювати операційні графіки виконання. + +## Реальний приклад: EVM {#real-example-the-evm} + +Ethereum Virtual Machine (EVM) можна розуміти операційно: + +* **Стан**: лічильник команд, стек, пам’ять, сховище, газ +* **Правила переходів**: по одному для кожного опкоду (`ADD`, `PUSH`, `SSTORE` тощо) +* **Виконання**: повторне застосування малокрокових правил до зупинки + +Байткод EVM — це дані інструкцій першого порядку. Операційний опис визначає, як змінюється конфігурація EVM для кожного опкоду; конкретний клієнт реалізує цю поведінку. + +Цикл диспетчеризації та лічильник команд EVM можуть нагадувати дефункціоналізовану абстрактну машину. Однак називати їх дефункціоналізованими продовженнями можна лише за наявності конкретного джерела вищого порядку, перетворення та відповідності між ними, а не лише через зовнішню схожість циклу. + +## Розірвати цикл: спершу значення, потім механізми {#breaking-the-cycle-meaning-before-machinery} + +Операційний і денотаційний описи відповідають на різні запитання: + +$$ \begin{aligned} \llbracket p \rrbracket &\in D && \text{what does the program mean?} \\ c &\longrightarrow c' && \text{how does this representation step?} \end{aligned} $$ + +Розробка, орієнтована на значення, визначає семантичну область, композицію, спостереження та закони, перш ніж вибирати представлення машини. Щойно вибрано систему переходів, зобов’язання щодо її коректності пов’язує обидва рівні. Для належно визначеного значення повних конфігурацій типове твердження про збереження під час тихого кроку має такий вигляд: + +$$ c \longrightarrow c' \quad \Longrightarrow \quad \operatorname{meaning}(c) = \operatorname{meaning}(c') $$ + +Замість звичайної рівності може використовуватися спостережувана еквівалентність, траси чи бісимілярність. Важливо, щоб машина відповідала за збереження задуму. + +Денотаційне проєктування не вибирає переможця в цьому циклі. Воно встановлює стабільне джерело визначення поза ним: + +1. Визначте семантичну область, операції, композицію та закони. +2. Пишіть програми відповідно до цього значення. +3. Виберіть представлення для конкретного споживача: прямого виконання, огляду, компіляції, планування, серіалізації чи аналізу. +4. Пов’яжіть кожне вибране представлення й перетворення з тим самим значенням. + +Тому інтерпретатор вищого порядку та програма першого порядку можуть співіснувати. Жодне з них не мусить бути визначенням мови. Перше може забезпечувати пряме виконання, а друге — обслуговувати споживачів, яким потрібна структура. Їхня узгодженість — семантичне зобов’язання, а не припущення, що механізми тотожні. + +```admonish note title="Остаточної операційної абстракції не існує" +Кожне операційне представлення відкриває одні структури й приховує інші. Значення є сталою відправною точкою для вибору відповідних представлень і встановлення зв’язків між ними. +``` + +## Підсумок {#summary} + +* Операційна семантика описує обчислення чи переходи вибраного представлення. +* Вільні монади надають синтаксис інструкцій і послідовне виконання, поведінку яких іще має визначити інтерпретація. +* CPS відкриває продовження; операційні правила можуть описувати передавання значень і керування в програмах CPS. +* Дефункціоналізація може перетворити певну програму вищого порядку на машину першого порядку, переходи якої можна визначити операційно. +* Якщо вважати будь-яке з цих кодувань універсальним, виникає цикл перетворення структури на дані та її приховування. +* Денотаційне значення визначає, що саме мають зберігати ці переходи. diff --git a/src/insights/operational_semantics.vi.md b/src/insights/operational_semantics.vi.md new file mode 100644 index 0000000..3c51a0e --- /dev/null +++ b/src/insights/operational_semantics.vi.md @@ -0,0 +1,181 @@ + + +# Từ ngữ nghĩa đến máy móc {#semantics-to-machines} + +```admonish tip title="Liên quan" +Thiết kế theo ngữ nghĩa trong Rust: [Chương trình bậc nhất](../rust-dd/first-order-programs.md), [Quy trình ngôn ngữ và trình biên dịch](../rust-dd/compiler-pipelines.md) +Khái niệm: [Ngữ nghĩa vận hành](../concepts/operational_semantics.md), [Monad tự do](../concepts/free_monad.md), [Phong cách truyền tiếp nối](../concepts/cps.md), [Phi chức năng hóa](../concepts/defunctionalization.md) +``` + +## Ngữ nghĩa vận hành mô tả điều gì {#what-operational-semantics-describes} + +Ngữ nghĩa vận hành đặc tả cách một cách biểu diễn chương trình được chọn hoạt động. Nó định nghĩa phán đoán đánh giá hoặc quan hệ chuyển tiếp trên những cấu hình như: + +$$ (\mathit{program}, \mathit{state}) \longrightarrow (\mathit{program}', \mathit{state}') $$ + +Chương trình có thể là cú pháp nguồn, giá trị monad tự do, số hạng CPS, bytecode hoặc trạng thái máy đã phi chức năng hóa. Không cách biểu diễn nào trong số đó *là* ngữ nghĩa vận hành. Ngữ nghĩa vận hành là mô tả cách các giá trị trong cách biểu diễn đã chọn được đánh giá hoặc chuyển bước. + +Hướng này quan trọng. Cách biểu diễn cung cấp đối tượng để mô tả hành vi; bổ sung mô tả vận hành không giải thích được ngôn ngữ nên mang ý nghĩa gì. + +## Chương trình monad tự do {#free-monad-programs} + +Monad tự do cung cấp cú pháp lệnh cùng phép tuần tự hóa được sinh tự do. Nó không cung cấp hành vi của các lệnh đó. + +Ngữ nghĩa vận hành cho chương trình monad tự do có thể định nghĩa cấu hình chứa lệnh hiện tại, tiếp nối và mọi trạng thái máy. Sau đó, các quy tắc giải thích, chẳng hạn, cách một lệnh tạm dừng thay đổi trạng thái và chuyển kết quả của nó cho phần chương trình còn lại. + +Đó là một cách diễn giải khả dĩ. Cùng chương trình tự do ấy cũng có thể được gấp vào mô hình ngữ nghĩa chỉ định, biên dịch sang ngôn ngữ khác, phân tích hoặc kết xuất mà không chạy. + +
+Từ monad tự do đến freer: nghiên cứu đã phát hiện điều gì + +Độc giả từng gặp monad tự do như kiến trúc tổng quát cho chương trình có hiệu ứng có thể tự hỏi vì sao cuộc thảo luận sau đó chuyển sang cấu trúc freer, hiệu ứng mở rộng và handler. Nghiên cứu không đơn thuần loại bỏ monad tự do. Nó cô lập những gì monad tự do thực sự cung cấp, đo lường điểm thất bại của các cách biểu diễn phổ biến và giữ lại cấu trúc hữu ích. + +Kiselyov và Ishii suy ra monad freer bằng cách lần lượt gỡ bỏ các ràng buộc và mã khuôn mẫu khỏi cách biểu diễn số hạng có hiệu ứng. Trong biểu diễn freer, một lệnh có thể tạo ra kiểu trung gian bị ẩn khỏi kiểu chương trình cuối cùng, còn một tiếp nối tường minh kết nối kết quả đó với phần tính toán còn lại. Vì vậy, chữ ký lệnh không còn cần một thể hiện `Functor`. + +Thay đổi đó tăng tính biểu đạt nhưng tự nó không giải quyết hiệu năng. Biểu diễn freer trực tiếp vẫn hợp thành các tiếp nối như phép nối danh sách kết hợp trái: xử lý chuỗi gồm $n$ yêu cầu có thể tốn $O(n^2)$ công việc. Việc làm lộ tiếp nối cho thấy cơ hội thực sự — có thể lưu nó trong một chuỗi căn chỉnh theo kiểu, trong đó kiểu kết quả và kiểu đầu vào kế cận khớp nhau theo cấu trúc. Ghép chuỗi hiệu quả loại bỏ phép duyệt nhạy với tính kết hợp. + +Sau đó, hợp các kiểu mở cho phép bộ diễn giải hiệu ứng mở thêm, kết hợp và loại bỏ các kiểu yêu cầu đã chọn. Điều này giải quyết việc hợp thành hiệu ứng mô-đun và cấu trúc handler. Nó vẫn không cung cấp các phương trình của một miền cụ thể hay quyết định khi nào hai chương trình có hiệu ứng mang cùng ý nghĩa. + +Kết luận chính xác hơn câu “freer tốt hơn free”. Monad tự do phát hiện sự phân tách có giá trị giữa yêu cầu và cách diễn giải. Cách mã hóa freer gỡ bỏ một ràng buộc không cần thiết; hàng đợi căn chỉnh theo kiểu xử lý vấn đề hiệu năng đã đo được; hiệu ứng mở rộng cải thiện phép hợp thành. Mỗi bước giữ lại hiểu biết từ bước trước đồng thời thu hẹp phạm vi khẳng định. Cách diễn giải ngữ nghĩa vẫn luôn là quyết định riêng. + +Xem Kiselyov và Ishii, [*Freer Monads, More Extensible Effects*](https://okmij.org/ftp/Haskell/extensible/more.pdf). + +
+ +## Chương trình CPS {#cps-programs} + +Phong cách truyền tiếp nối (CPS) biểu diễn tường minh phần còn lại của phép tính dưới dạng tiếp nối. Ngữ nghĩa vận hành cho CPS mô tả các hành vi như: + +* đánh giá biểu thức CPS hiện tại; +* truyền giá trị vừa tạo cho tiếp nối; +* chuyển quyền điều khiển khi tiếp nối đó được áp dụng. + +CPS làm lộ điều khiển theo dạng thuận tiện để mô tả về mặt vận hành, nhưng nó là cách biểu diễn hoặc phép biến đổi chương trình — không phải ngữ nghĩa vận hành. Muốn liên hệ chương trình theo phong cách trực tiếp với bản dịch CPS, cần nêu ngữ nghĩa nguồn, ngữ nghĩa đích và lập luận về tính bảo toàn. + +
+Vượt ra ngoài CPS: khi cần kiểm tra tiếp nối + +CPS là cách khắc phục tiêu chuẩn cho phép nối và bind nhạy với tính kết hợp. Thay vì duyệt lặp lại một cấu trúc kết hợp trái, nó biểu diễn phép tính còn lại bằng phép hợp thành hàm. Cách biểu diễn này có thể hiệu quả khi thao tác duy nhất trên tiếp nối là áp dụng cuối cùng. + +Van der Ploeg và Kiselyov xác định ranh giới: một số bên sử dụng phải kiểm tra hoặc sửa đổi kết quả trung gian trước khi tiếp tục. Tìm kiếm không tất định, iteratee, monad tự do và hiệu ứng mở rộng đều có thể cần truy cập như vậy. CPS giấu chuỗi khái niệm bên trong một hàm, nên muốn khôi phục cấu trúc trung gian phải phản chiếu nó trở lại thành dữ liệu, có thể làm mất lợi thế hiệu năng. + +Giải pháp thay thế của họ biểu diễn trực tiếp chuỗi ẩn dưới dạng cấu trúc dữ liệu căn chỉnh theo kiểu. Cấu trúc này hỗ trợ hợp thành hiệu quả bất kể tính kết hợp, đồng thời giữ khả năng truy cập hiệu quả vào kết quả trung gian. Kiểu bảo đảm mỗi phép tính được lưu tạo ra đầu vào mà phép kế tiếp mong đợi. + +Kết luận rộng hơn không phải là chuỗi căn chỉnh theo kiểu đánh bại CPS. CPS rất phù hợp để *áp dụng* tiếp nối và kém phù hợp hơn khi bên sử dụng phải *kiểm tra* chúng. Nghiên cứu về điều khiển có giới hạn còn làm sắc nét bài học: thay vì xem toàn bộ tương lai là một tiếp nối không phân biệt, dấu phân cách nêu rõ phần nào của phép tính xung quanh có thể được bắt giữ và thao tác. + +Những ý tưởng này không biến mất. Bài học của chúng tiếp tục trong handler hiệu ứng, suy dẫn máy trừu tượng, toán tử điều khiển có kiểu và cách biểu diễn hiệu ứng hiệu quả. Điều thay đổi là kỳ vọng rằng chỉ riêng CPS phải trở thành phép trừu tượng cuối cùng. + +Xem van der Ploeg và Kiselyov, [*Phản chiếu không hối tiếc*](https://okmij.org/ftp/Haskell/zseq.pdf). Để biết thêm về điều khiển, xem [tuyển tập về tiếp nối và điều khiển có giới hạn](https://okmij.org/ftp/continuations/index.html). + +
+ +## Máy đã phi chức năng hóa {#defunctionalized-machines} + +Phi chức năng hóa thay một họ giá trị hàm đã biết, chẳng hạn tiếp nối CPS, bằng các cấu trúc bậc nhất và phép toán `apply`. Sau đó, ngữ nghĩa vận hành có thể mô tả chuyển tiếp giữa các cấu hình tường minh thu được. + +Sau một phép biến đổi CPS cụ thể rồi phi chức năng hóa, các chuyển tiếp ấy có thể suy ra một máy trừu tượng. Đây là phép suy dẫn mạnh mẽ, nhưng không phải định nghĩa chung của ngữ nghĩa vận hành: quy tắc vận hành không nhất thiết bắt nguồn từ CPS, và máy bậc nhất bất kỳ không tự động trở thành máy tiếp nối đã phi chức năng hóa. + +
+Reynolds: nguồn gốc của phi chức năng hóa + +John C. Reynolds giới thiệu phi chức năng hóa trong nghiên cứu năm 1972 về bộ diễn giải định nghĩa. Điểm xuất phát của ông không phải máy ảo bậc nhất mà là bộ diễn giải bậc cao: hàm trong ngôn ngữ định nghĩa biểu diễn môi trường, tiếp nối và các phần khác của ngôn ngữ được định nghĩa. + +Phép biến đổi quan sát họ hữu hạn các trừu tượng hàm có thể xuất hiện trong toàn chương trình. Nó thay mỗi trừu tượng bằng cấu trúc bậc nhất mang các giá trị biến tự do, rồi thay phép áp dụng hàm bằng một phép toán `apply` duy nhất điều phối theo các cấu trúc đó. Điều vốn ngầm trong ngôn ngữ định nghĩa trở thành đại số tường minh của closure hoặc tiếp nối. + +Khi áp dụng cho bộ diễn giải dựa trên tiếp nối, bước này làm lộ một máy: các cấu trúc tiếp nối trở thành trạng thái điều khiển, biến được bắt giữ trở thành dữ liệu máy được lưu trữ, còn `apply` trở thành bộ điều phối chuyển tiếp. Máy không được phỏng đoán trước mà được suy ra từ bộ đánh giá bậc cao. + +Reynolds cũng nhấn mạnh cái giá của sự rõ ràng này. Máy thu được chứa những lựa chọn biểu diễn đúng đắn nhưng không duy nhất. Các lựa chọn cấu trúc khác nhau hoặc phép biến đổi trước đó có thể tạo ra những tập “bánh răng và cơ cấu” kiểu máy khác nhau mà vẫn bảo toàn cùng hành vi. Vì thế phi chức năng hóa làm lộ cấu trúc vận hành, chứ không phải ý nghĩa tất yếu duy nhất của ngôn ngữ. + +Về sau Danvy và Nielsen hệ thống hóa kỹ thuật của Reynolds thành phép biến đổi toàn chương trình và nghiên cứu tái chức năng hóa như phép nghịch đảo. Kết luận sâu hơn của họ là phép biến đổi này đóng vai trò cây cầu: nó có thể chuyển đặc tả và lập luận đúng đắn giữa định nghĩa bậc cao và máy bậc nhất, đồng thời làm lộ rằng các chương trình có vẻ không liên quan thực ra là hai cách biểu diễn cùng một cấu trúc. + +Dòng nghiên cứu này xác định đúng thẩm quyền của kỹ thuật. Phi chức năng hóa không chỉ là thay closure bằng enum, nhưng cũng không phải nền tảng phổ quát: đó là phép chuyển bảo toàn ngữ nghĩa giữa các cách biểu diễn mà mối tương ứng cần được xác lập. + +Xem Reynolds, [*Bộ diễn giải định nghĩa cho ngôn ngữ lập trình bậc cao*](https://homepages.inf.ed.ac.uk/wadler/papers/papers-we-love/reynolds-definitional-interpreters-1972.pdf), và Danvy cùng Nielsen, [*Phi chức năng hóa trong thực tế*](https://tidsskrift.dk/brics/article/view/21684). + +
+ +## Chu trình biểu diễn vận hành {#the-operational-representation-cycle} + +Một sai lầm lặp lại là tìm kiếm một cách biểu diễn vận hành giải quyết mọi vấn đề lập trình. Mỗi cách biểu diễn khôi phục điều mà cách trước che giấu, nhưng khiến mối quan tâm khác trở nên khó hơn: + +$$ \text{higher-order program} \longrightarrow \text{free syntax} \longrightarrow \text{CPS} \longrightarrow \text{first-order machine} \longrightarrow \text{higher abstraction} $$ + +Các mũi tên không khẳng định một quy trình trình biên dịch bắt buộc. Chúng cho thấy sự dịch chuyển thiết kế thường gặp: làm lộ điều mà cách biểu diễn hiện tại che giấu, rồi che lại cơ chế được đưa vào bởi sự bộc lộ đó. + +| Cách biểu diễn | Điều nó làm sẵn có | Áp lực nó tạo ra | +| --- | --- | --- | +| Hàm bậc cao | Phép hợp thành trực tiếp và trừu tượng hóa của ngôn ngữ chủ | Bên sử dụng tổng quát có thể gọi hàm, nhưng không thể kiểm tra cấu trúc bị ẩn của nó | +| Cú pháp tự do kèm tuần tự hóa | Chương trình dưới dạng dữ liệu có thể hợp thành và diễn giải | Tính tự do không cung cấp phương trình miền, chuẩn hóa, đánh giá hiệu quả hay khả năng kiểm tra các hàm được lưu trữ | +| CPS | Thứ tự đánh giá và phần tính toán còn lại trở nên tường minh | Mã hóa CPS toàn chương trình luồn tiếp nối qua gần như mọi giao diện | +| Điều khiển bậc nhất đã phi chức năng hóa | Tiếp nối trở thành các trường hợp có thể kiểm tra và tuần tự hóa | Phải tường minh duy trì các cấu trúc, đối số được lưu, trạng thái chuyển tiếp và phép toán `apply` | +| Một lớp trừu tượng cao hơn trên máy | Cơ chế trở nên dễ dùng hơn | Cấu trúc lại bị che giấu khi trình biên dịch, bộ lập lịch, trình gỡ lỗi hoặc bộ tối ưu hóa cần kiểm tra | + +Các áp lực này mang tính cấu trúc. Việc kiểm tra đòi hỏi dữ liệu. Chuyển hành vi thành dữ liệu đưa vào các cấu trúc và bộ diễn giải. Che giấu lại những cấu trúc đó phục hồi phép trừu tượng thuận tiện nhưng tước bỏ chính quyền truy cập mà bên sử dụng cần để phân tích hoặc biến đổi chương trình. + +Đánh đổi của monad tự do đặc biệt giàu tính gợi mở. Monad tự do giải quyết một vấn đề chính xác: nó sinh ra phép tuần tự hóa cho functor lệnh mà không áp đặt phương trình nào ngoài các định luật monad. Cam kết đó cũng chính là giới hạn. Nó không biết các định luật của miền. Nếu hai lần ghi vào cùng ô tương đương với lần ghi cuối cùng, chương trình tự do vẫn chứa cả hai lệnh cho đến khi phép chuẩn hóa hoặc cách diễn giải đặc thù miền nhận diện chúng. Vì thế, tối ưu hóa, dạng chuẩn tắc và đẳng thức ngữ nghĩa phải đến từ nơi khác. + +Tái hóa lệnh cũng không làm toàn bộ chương trình có thể kiểm tra đồng nhất. Trong các cách mã hóa phổ biến, lệnh đang tạm dừng hiển thị được, nhưng tiếp nối của nó là hàm trong ngôn ngữ chủ. Bộ phân tích tổng quát không thể kiểm tra cấu trúc tương lai bị ẩn sau hàm đó nếu không cung cấp kết quả rồi áp dụng hàm. Tái hóa tiếp nối giúp khôi phục khả năng kiểm tra bằng cách tiến về biểu diễn bậc nhất hoặc đã phi chức năng hóa — và đưa chúng ta trở lại bước kế tiếp của chu trình. + +Chi phí đánh giá cũng phụ thuộc cách biểu diễn. Cây bind kết hợp trái ngây thơ có thể cần duyệt lặp đi lặp lại, gây công việc bậc hai. Phép biến đổi sao chép các chương trình con còn lại có thể khiến kích thước tăng theo hàm mũ. Các cách mã hóa Codensity, freer hoặc chuyên biệt có thể cải thiện những chi phí nhất định, nhưng bằng cách chọn cách biểu diễn và đánh đổi khác. Tăng trưởng hàm mũ có thể xảy ra; đó không phải định luật nội tại của monad tự do. + +Đó là lý do monad tự do không phải giải pháp phổ quát. Nó cung cấp cú pháp cùng phép tuần tự hóa hợp luật, chứ không cung cấp phương trình miền dự định, dạng chuẩn tắc, khả năng quan sát cấu trúc hoàn chỉnh hay cách triển khai tự động hiệu quả. Tương tự, CPS không cần lan ra toàn hệ thống khi chỉ được dùng cục bộ; phi chức năng hóa chỉ trở nên cồng kềnh tương ứng với quy mô họ hàm và các giá trị được bắt giữ mà nó cần tái hóa. + +Chu trình xuất hiện khi mỗi cách mã hóa mới được yêu cầu trở thành nền tảng phổ quát. Nó giải quyết bất tiện vận hành trước đó rồi trở thành nguồn phức tạp ngoài ý muốn tiếp theo. + +Vì thế, tranh luận về “phép trừu tượng tốt nhất” không đi đến thống nhất khi chỉ giới hạn ở vận hành. Hàm bậc cao, cú pháp tự do, CPS và máy bậc nhất được so sánh như thể một dạng phải vượt trội mọi dạng còn lại. Nhưng *tốt hơn* không có nghĩa cho đến khi phép so sánh nêu rõ cần bảo toàn điều gì và ai sẽ sử dụng kết quả: + +* thực thi trực tiếp ưu tiên lời gọi thông thường và biểu diễn được che giấu; +* biến đổi và phân tích đòi hỏi cấu trúc có thể kiểm tra; +* tuần tự hóa đòi hỏi dữ liệu bậc nhất; +* khả năng mở rộng có thể thuận lợi hơn khi thêm cách diễn giải hoặc thêm cú pháp, nhưng hiếm khi thuận lợi đồng đều cho cả hai; +* tính đồng thời có thể đòi hỏi các quan sát chủ ý bỏ qua nhiều lựa chọn lập lịch. + +Đây là những yêu cầu khác nhau, không phải các chứng minh liên tiếp rằng một phép trừu tượng vượt trội phổ quát. Thuộc tính vận hành có thể giúp chọn cách triển khai cho mục đích đã nêu; chúng không thể cung cấp mục đích hay quyết định khác biệt nào có ý nghĩa. + +Cùng sự thận trọng đó áp dụng cho tư duy tuần tự. Ngữ nghĩa vận hành có thể mô tả hệ thống đồng thời và không tất định, nhưng một chuỗi bước máy duy nhất chỉ là một cách biểu diễn hành vi khả dĩ. Nếu thứ tự lập lịch được xem là thẩm quyền quá sớm, các lần thực thi tương đương sẽ bị xem là khác nhau chỉ vì cơ chế của chúng đan xen khác đi. Trước hết, mô hình ngữ nghĩa phải quyết định quan sát nào phân biệt các chương trình đồng thời; sau đó mới đánh giá lịch vận hành theo quyết định ấy. + +## Ví dụ thực tế: EVM {#real-example-the-evm} + +Máy ảo Ethereum (EVM) có thể được hiểu theo góc nhìn vận hành: + +* **Trạng thái**: bộ đếm chương trình, ngăn xếp, bộ nhớ, lưu trữ, gas +* **Quy tắc chuyển tiếp**: mỗi opcode có một quy tắc (`ADD`, `PUSH`, `SSTORE`, v.v.) +* **Thực thi**: liên tục áp dụng quy tắc bước nhỏ đến khi dừng + +Bytecode EVM là dữ liệu lệnh bậc nhất. Mô tả vận hành nêu cách cấu hình EVM thay đổi theo từng opcode; một máy khách cụ thể triển khai hành vi đó. + +Vòng lặp điều phối và bộ đếm chương trình có thể trông giống máy trừu tượng đã phi chức năng hóa. Tuy nhiên, gọi chúng là tiếp nối đã phi chức năng hóa đòi hỏi nguồn bậc cao, phép biến đổi và mối tương ứng cụ thể — không chỉ một vòng lặp có vẻ tương tự. + +## Phá vỡ chu trình: ý nghĩa trước cơ chế {#breaking-the-cycle-meaning-before-machinery} + +Các mô tả vận hành và ngữ nghĩa chỉ định trả lời những câu hỏi khác nhau: + +$$ \begin{aligned} \llbracket p \rrbracket &\in D && \text{what does the program mean?} \\ c &\longrightarrow c' && \text{how does this representation step?} \end{aligned} $$ + +Phát triển lấy ý nghĩa làm trọng tâm chọn miền ngữ nghĩa, phép hợp thành, quan sát và định luật trước khi cam kết với cách biểu diễn máy. Một khi đã chọn hệ chuyển tiếp, nghĩa vụ đúng đắn của nó là nối kết hai lớp. Với ý nghĩa cấu hình hoàn chỉnh được định nghĩa phù hợp, một khẳng định bảo toàn qua bước nội bộ điển hình có dạng: + +$$ c \longrightarrow c' \quad \Longrightarrow \quad \operatorname{meaning}(c) = \operatorname{meaning}(c') $$ + +Quan hệ chính xác có thể dùng tương đương quan sát, vết thực thi hoặc mô phỏng song hành. Điều quan trọng là máy phải chịu trách nhiệm trước ý nghĩa dự định. + +Thiết kế theo ngữ nghĩa không chọn bên thắng trong chu trình. Nó thiết lập nguồn thẩm quyền ổn định bên ngoài chu trình đó: + +1. Định nghĩa miền ngữ nghĩa, phép toán, phép hợp thành và định luật. +2. Viết chương trình theo ý nghĩa đó. +3. Chọn cách biểu diễn cho bên sử dụng cụ thể: thực thi trực tiếp, kiểm tra, biên dịch, lập lịch, tuần tự hóa hoặc phân tích. +4. Liên hệ mọi cách biểu diễn và phép biến đổi đã chọn trở lại cùng ý nghĩa. + +Vì vậy, bộ diễn giải bậc cao và chương trình bậc nhất có thể cùng tồn tại. Không dạng nào cần là định nghĩa ngôn ngữ. Dạng thứ nhất có thể phục vụ thực thi trực tiếp; dạng thứ hai có thể phục vụ bên sử dụng cần cấu trúc. Sự thống nhất giữa chúng là nghĩa vụ ngữ nghĩa, chứ không phải giả định rằng cơ chế của chúng giống nhau. + +```admonish note title="Không có phép trừu tượng vận hành cuối cùng" +Mọi cách biểu diễn vận hành đều làm lộ một số cấu trúc và che giấu cấu trúc khác. Ý nghĩa là điểm ổn định để lựa chọn và liên hệ các cách biểu diễn phù hợp. +``` + +## Tóm tắt {#summary} + +* Ngữ nghĩa vận hành mô tả đánh giá hoặc chuyển tiếp cho một cách biểu diễn đã chọn. +* Monad tự do cung cấp cú pháp lệnh và phép tuần tự hóa, nhưng hành vi vẫn cần một cách diễn giải. +* CPS làm lộ tiếp nối; quy tắc vận hành có thể mô tả cách chương trình CPS truyền giá trị và điều khiển. +* Phi chức năng hóa có thể chuyển một chương trình bậc cao cụ thể thành máy bậc nhất với các chuyển tiếp được mô tả theo vận hành. +* Xem bất kỳ cách mã hóa nào trong số này là phổ quát sẽ tạo ra chu trình tái hóa rồi che giấu cấu trúc. +* Ý nghĩa ngữ nghĩa chỉ định xác định các chuyển tiếp đó phải bảo toàn điều gì. diff --git a/src/insights/operational_semantics.zh-hant.md b/src/insights/operational_semantics.zh-hant.md new file mode 100644 index 0000000..692d162 --- /dev/null +++ b/src/insights/operational_semantics.zh-hant.md @@ -0,0 +1,181 @@ + + +# 從語義到機器 {#semantics-to-machines} + +```admonish tip title="相關內容" +Rust 中的語義驅動設計:[一階程式](../rust-dd/first-order-programs.md)、[語言與編譯器流水線](../rust-dd/compiler-pipelines.md) +概念:[操作語義](../concepts/operational_semantics.md)、[自由單子](../concepts/free_monad.md)、[延續傳遞風格](../concepts/cps.md)、[去函式化](../concepts/defunctionalization.md) +``` + +## 操作語義描述什麼 {#what-operational-semantics-describes} + +操作語義規定所選程式表示的行為。它透過判斷或配置上的轉換關係來定義求值,例如: + +$$ (\mathit{program}, \mathit{state}) \longrightarrow (\mathit{program}', \mathit{state}') $$ + +程式可以是源語法、自由單子值、CPS 項、位元組碼或去函式化的機器狀態。這些表示無一*就是*操作語義。操作語義是對所選表示中的值如何求值或轉換的說明。 + +方向很重要。表示為我們提供了一個可描述其行為的物件;補充操作描述並不能解釋該語言應有何種含義。 + +## 自由單子程式 {#free-monad-programs} + +自由單子提供指令語法與自由生成的順序組合,但不會提供這些指令的行為。 + +自由單子程式的操作語義可以定義包含當前指令、其延續與任意機器狀態的配置。隨後,規則會說明例如掛起的指令如何改變狀態,並將結果傳遞給程式剩餘部分。 + +這是一種可能的解釋。同一個自由程式也可以摺疊為指稱模型、編譯成另一種語言、接受分析,或直接渲染,而無需執行。 + +
+從自由到更自由:研究揭示了什麼 + +曾將自由單子視為效應程式通用架構的讀者,可能會好奇,為什麼後來研究轉向 freer 構造、可擴充效應與處理器。研究並沒有簡單拋棄自由單子,而是分離出它們真正提供的內容,衡量常見表示的失效之處,並將有用結構延續下來。 + +Kiselyov 與 Ishii 透過逐步移除效應項表示中的約束與樣板程式碼,推導出 freer 單子。在 freer 表示中,指令可以產生一箇中間型別,而該型別被隱藏在最終程式型別之外;顯式延續則將該結果連線到計算的其餘部分。因此,指令簽名不再需要`Functor`例項。 + +這種變化提升了表達能力,但本身並未解決效能問題。直接的 freer 表示仍然像左結合的列表追加那樣組合延續:處理一串$n$請求可能需要$O(n^2)$的工作量。將延續顯式化後,就能看見真正的機會——可以把它儲存為型別對齊序列,相鄰結果與輸入型別由構造保證匹配。高效拼接該序列即可消除對結合順序敏感的遍歷。 + +開放聯合型別隨後讓可擴充效應直譯器能夠新增、組合與消除選定的請求型別。這解決了模組化效應組合與處理器結構問題,但仍未提供某個具體領域的等式,也不會決定兩個帶效應程式何時具有相同含義。 + +結論比“freer 優於 free”更加精確:自由單子揭示了請求與解釋之間有價值的分離;freer 編碼去除了不必要的約束;型別對齊佇列解決了經測量確認的效能問題;可擴充效應改善了組合。每一步都保留前一步的經驗,同時縮小主張範圍。語義解釋始終是另一項獨立決定。 + +參見 Kiselyov 與 Ishii 的論文[*《Freer 單子:更具可擴充性的效應》*](https://okmij.org/ftp/Haskell/extensible/more.pdf)。 + +
+ +## CPS 程式 {#cps-programs} + +延續傳遞風格(CPS)會將計算剩餘部分顯式表示為延續。CPS 的操作語義會描述以下行為: + +* 對當前 CPS 表示式求值; +* 將生成的值傳遞給其延續; +* 應用該延續時轉移控制權。 + +CPS 將控制流變為便於從操作層面描述的形式,但它是一種表示或程式變換,而非操作語義。要將直接風格程式與其 CPS 翻譯關聯起來,必須明確源語義、目標語義並給出保義論證。 + +
+超越 CPS:何時必須檢查延續 + +CPS 是解決結合順序敏感的追加與 bind 的常見方法。它不再反覆遍歷左結合結構,而是透過函式組合表示剩餘計算。如果對延續唯一要做的操作是最終應用,這種表示就很高效。 + +van der Ploeg 與 Kiselyov 指出了適用邊界:有些使用者必須在繼續之前檢查或修改中間結果。非確定性搜尋、迭代器、自由單子與可擴充效應都可能需要此類存取。CPS 會將概念上的序列隱藏在函式中,因此要恢復中間結構就需要反射回資料,從而可能抵消效能優勢。 + +他們提出的替代方案會將隱藏序列直接表示為型別對齊資料結構。它無論結合順序如何都能高效組合,同時保留對中間結果的高效存取。型別會確保每個儲存的計算都能產生下一個計算所需的輸入。 + +更廣泛的結論並非型別對齊序列擊敗 CPS,而是 CPS 擅長*應用*延續;當使用者必須*檢查*延續時,它就不那麼合適。關於帶界控制的研究進一步深化了這一教訓:不要將整個未來視作一個無法區分的延續,而應使用分界符明確可捕獲與操縱的周邊計算範圍。 + +這些思想並未消失。它們的經驗繼續影響效應處理器、抽象機器推導、有型別控制運算子與高效效應表示。變化的是,人們不再認為 CPS 單獨就應成為最終抽象。 + +參見 van der Ploeg 與 Kiselyov 的論文[*《無悔反射》*](https://okmij.org/ftp/Haskell/zseq.pdf)。關於更廣泛的控制模型,另請參閱 Kiselyov 的[延續與帶界控制文集](https://okmij.org/ftp/continuations/index.html)。 + +
+ +## 去函式化機器 {#defunctionalized-machines} + +去函式化會將已知的函式值集合(例如 CPS 延續)替換為一階構造器,並提供一個`apply`操作。隨後,操作語義可以描述這些顯式配置之間的狀態轉換。 + +在具體的 CPS 變換之後再進行去函式化,可以推導出抽象機器。這是一種強有力的推導方式,但不是操作語義的通用定義:操作規則不必源自 CPS,任意一階機器也不會因此自動成為去函式化的延續機器。 + +
+Reynolds:去函式化的起源 + +John C. Reynolds 在 1972 年關於定義直譯器的研究中引入了去函式化。他的起點並非一階虛擬機器,而是高階直譯器:定義語言中的函式表示環境、延續及所定義語言的其他部分。 + +該變換會觀察整個程式中可能出現的有限函式抽象集合。它將每個抽象替換為一個一階構造器,並攜帶其自由變數的值;隨後將函式應用替換為一個按構造器分派的`apply`操作。原本隱含在定義語言中的內容,就此變成顯式的閉包或延續代數。 + +將這一做法應用於基於延續的直譯器,可以顯露出一臺機器:延續構造器變為控制狀態,被捕獲變數變為儲存的機器資料,`apply`則變成轉換分派器。機器不是預先猜出來的,而是從高階求值器推導出來的。 + +Reynolds 也強調了這種清晰度的代價。所得機器包含正確但不唯一的表示選擇。不同的構造器選擇或前置變換可能生成不同的、類似機器的“齒輪與部件”,但仍保留相同的行為。因此,去函式化顯露的是一種操作結構,而非語言唯一必然的含義。 + +Danvy 與 Nielsen 後來將 Reynolds 的技術系統化為全程式變換,並研究了作為其逆變換的重新函式化。他們更深層的結論是:這種變換是一座橋樑,能夠在高階定義與一階機器之間傳遞規範與正確性論證,還能揭示表面上無關的程式其實是同一結構的兩種表示。 + +這條研究脈絡說明了該技術應有的權威範圍。去函式化不只是把閉包替換為列舉,但也不是普遍基礎:它是在兩種表示間保義轉換,其對應關係必須得到確立。 + +參見 Reynolds 的[*《高階程式語言的定義直譯器》*](https://homepages.inf.ed.ac.uk/wadler/papers/papers-we-love/reynolds-definitional-interpreters-1972.pdf),以及 Danvy 與 Nielsen 的[*《去函式化的實踐》*](https://tidsskrift.dk/brics/article/view/21684)。 + +
+ +## 操作表示迴圈 {#the-operational-representation-cycle} + +一種常見錯誤是試圖尋找能解決所有程式設計問題的單一操作表示。每種表示都會恢復前一種表示隱藏的內容,但也會使另一種關切更難處理: + +$$ \text{higher-order program} \longrightarrow \text{free syntax} \longrightarrow \text{CPS} \longrightarrow \text{first-order machine} \longrightarrow \text{higher abstraction} $$ + +這些箭頭並不表示編譯器必須採用某條流水線,而是展示一種反覆出現的設計演進:顯露當前表示隱藏的內容,隨後再隱藏此次顯露引入的機制。 + +| 表示 | 使哪些內容可見 | 引入了何種壓力 | +| --- | --- | --- | +| 高階函式 | 直接組合與宿主語言抽象 | 泛型使用者可以呼叫函式,卻無法檢查函式隱藏的結構 | +| 帶順序組合的自由語法 | 以資料形式表示、可組合並可解釋的程式 | 自由性本身不提供領域等式、正規化、高效求值,也不支援檢查已儲存的函式 | +| CPS | 求值順序與計算剩餘部分變得顯式 | 全程式 CPS 編碼會讓延續貫穿幾乎每個介面 | +| 去函式化的一階控制 | 延續變成可檢查、可序列化的分支 | 必須顯式維護構造器、已存引數、轉換狀態與一個`apply`操作 | +| 對機器作更高層抽象 | 機制變得更易使用 | 編譯器、排程器、偵錯程式或最佳化器需要檢查結構時,它又被隱藏起來 | + +這些壓力來自結構本身。檢查需要資料;將行為轉為資料會引入構造器與直譯器;隱藏這些構造器可以恢復便利的抽象,卻會移除分析或變換程式的使用者所需的存取能力。 + +自由單子的取捨尤其具有啟發性。自由單子解決了一個精確問題:為指令函子生成順序組合,而不施加單子定律之外的等式。這一保證也構成了它的侷限。它不瞭解領域定律。如果對同一單元格的兩次寫入應當等價於最終那次寫入,那麼自由程式仍會保留兩條指令,直到領域專用的正規化或解釋將它們識別為等價。因此,最佳化、規範形式與語義等價必須由其他機制提供。 + +將指令具體化為資料,也不會讓整個程式都可檢查。在常見編碼中,掛起的指令可見,但其延續卻是宿主語言函式。泛型分析器無法檢查該函式背後的未來結構,除非提供結果並應用該函式。將延續具體化可以恢復可檢查性,但會轉向一階或去函式化表示——於是又回到了迴圈的下一環。 + +求值開銷同樣取決於表示。左結合繫結構成的樸素樹可能需要反覆遍歷,導致二次複雜度。複製剩餘子程式的變換可能導致指數級增長。Codensity 風格、freer 或專用編碼可以改善特定開銷,但代價是選擇了不同的表示與取捨。指數級增長確實可能發生,但不是自由單子的固有定律。 + +這就是自由單子並非通用解法的原因。它提供帶定律的順序組合語法,但不提供預期領域等式、規範正規化、完整結構可見性或自動高效的實作。同樣,區域性使用 CPS 並不需要擴散到整個系統;去函式化只有在需要具體化的函式族與捕獲值變多時才會變得繁瑣。 + +當人們要求每種新編碼都成為通用基礎時,就會出現這個迴圈。它解決了上一種操作不便,隨後又成為新的偶然複雜性來源。 + +因此,如果討論“最佳抽象”時只關注操作特性,爭論就難以收斂。高階函式、自由語法、CPS 與一階機器被拿來比較,彷彿其中一種必須勝過其他所有方案。但在說明必須保留什麼、結果由誰使用之前,“*更好*”沒有明確含義: + +* 直接執行偏好普通呼叫與隱藏表示; +* 變換與分析需要可檢查的結構; +* 序列化需要一階資料; +* 可擴充性可能更偏好增加解釋,也可能更偏好增加語法,但兩者很少同樣容易; +* 併發可能需要有意忽略許多排程選擇的觀察。 + +這些是不同要求,而非某種抽象普遍更優的逐級證明。操作特性有助於為既定目的選擇實作,卻不能提供該目的,也不能決定哪些區別有意義。 + +同樣的謹慎也適用於順序思維。操作語義可以描述併發與非確定性系統,但單一機器步驟序列只是表示其行為的一種可能方式。如果過早將排程順序視為權威,不同交錯機制就會讓本來等價的執行顯得不同。語義模型必須先決定哪些觀察可以區分併發程式,隨後再根據該決定評判操作排程。 + +## 真實示例:EVM {#real-example-the-evm} + +以操作視角理解以太坊虛擬機器(EVM): + +* **狀態**:程式計數器、棧、記憶體、儲存、Gas +* **轉換規則**:每個操作碼各有一條(`ADD`、`PUSH`、`SSTORE`等) +* **執行**:反覆應用小步規則,直至停止 + +EVM 位元組碼是一階指令資料。操作性描述會規定每種操作碼如何改變 EVM 配置;具體客戶端則負責實作該行為。 + +它的分派迴圈與程式計數器可能類似於去函式化抽象機。但若要稱其為去函式化延續,就必須提供具體高階源程式、變換與對應關係,不能只憑迴圈看起來相似。 + +## 打破迴圈:機制之前先確定含義 {#breaking-the-cycle-meaning-before-machinery} + +操作描述與指稱描述回答不同的問題: + +$$ \begin{aligned} \llbracket p \rrbracket &\in D && \text{what does the program mean?} \\ c &\longrightarrow c' && \text{how does this representation step?} \end{aligned} $$ + +語義優先的開發會先選擇語義域、組合、觀察與定律,再確定機器表示。一旦選定轉換系統,其正確性義務就負責連線這兩個層次。對於恰當定義的完整配置含義,典型的靜默步驟保留主張如下: + +$$ c \longrightarrow c' \quad \Longrightarrow \quad \operatorname{meaning}(c) = \operatorname{meaning}(c') $$ + +具體關係也可以改用觀察等價、軌跡或雙模擬。關鍵在於,機器必須對預期含義負責。 + +指稱設計不會從迴圈中選出勝者,而是在迴圈之外建立穩定的權威來源: + +1. 定義語義域、操作、組合與定律。 +2. 根據這些含義編寫程式。 +3. 針對具體使用者選擇表示:直接執行、檢查、編譯、排程、序列化或分析。 +4. 將每種選定的表示與變換都關聯回同一含義。 + +因此,高階直譯器與一階程式可以共存。二者都不必成為語言定義。前者可以服務於直接執行;後者可以服務於需要結構的使用者。二者一致是一項語義義務,而非假定其機制相同。 + +```admonish note title="不存在最終的操作抽象" +每種操作表示都會顯露某些結構並隱藏另一些結構。含義是穩定的出發點,我們據此選擇恰當的表示並建立它們之間的連結。 +``` + +## 總結 {#summary} + +* 操作語義描述所選表示的求值或狀態轉換。 +* 自由單子提供指令語法與順序組合,但其行為仍需要解釋。 +* CPS 會顯露延續;操作規則可以描述 CPS 程式如何傳遞值與控制權。 +* 去函式化可以將某個高階程式轉換為一階機器,並以操作規則描述其狀態轉換。 +* 將其中任意一種編碼視為通用方案,都會造成結構不斷被具體化又被隱藏的迴圈。 +* 指稱含義決定這些狀態轉換必須保留什麼。 diff --git a/src/insights/operational_semantics.zh.md b/src/insights/operational_semantics.zh.md new file mode 100644 index 0000000..8b94d71 --- /dev/null +++ b/src/insights/operational_semantics.zh.md @@ -0,0 +1,181 @@ + + +# 从语义到机器 {#semantics-to-machines} + +```admonish tip title="相关内容" +Rust 中的语义驱动设计:[一阶程序](../rust-dd/first-order-programs.md)、[语言与编译器流水线](../rust-dd/compiler-pipelines.md) +概念:[操作语义](../concepts/operational_semantics.md)、[自由单子](../concepts/free_monad.md)、[延续传递风格](../concepts/cps.md)、[去函数化](../concepts/defunctionalization.md) +``` + +## 操作语义描述什么 {#what-operational-semantics-describes} + +操作语义规定所选程序表示的行为。它通过判断或配置上的转换关系来定义求值,例如: + +$$ (\mathit{program}, \mathit{state}) \longrightarrow (\mathit{program}', \mathit{state}') $$ + +程序可以是源语法、自由单子值、CPS 项、字节码或去函数化的机器状态。这些表示无一*就是*操作语义。操作语义是对所选表示中的值如何求值或转换的说明。 + +方向很重要。表示为我们提供了一个可描述其行为的对象;补充操作描述并不能解释该语言应有何种含义。 + +## 自由单子程序 {#free-monad-programs} + +自由单子提供指令语法与自由生成的顺序组合,但不会提供这些指令的行为。 + +自由单子程序的操作语义可以定义包含当前指令、其延续与任意机器状态的配置。随后,规则会说明例如挂起的指令如何改变状态,并将结果传递给程序剩余部分。 + +这是一种可能的解释。同一个自由程序也可以折叠为指称模型、编译成另一种语言、接受分析,或直接渲染,而无需执行。 + +
+从自由到更自由:研究揭示了什么 + +曾将自由单子视为效应程序通用架构的读者,可能会好奇,为什么后来研究转向 freer 构造、可扩展效应与处理器。研究并没有简单抛弃自由单子,而是分离出它们真正提供的内容,衡量常见表示的失效之处,并将有用结构延续下来。 + +Kiselyov 与 Ishii 通过逐步移除效应项表示中的约束与样板代码,推导出 freer 单子。在 freer 表示中,指令可以产生一个中间类型,而该类型被隐藏在最终程序类型之外;显式延续则将该结果连接到计算的其余部分。因此,指令签名不再需要`Functor`实例。 + +这种变化提升了表达能力,但本身并未解决性能问题。直接的 freer 表示仍然像左结合的列表追加那样组合延续:处理一串$n$请求可能需要$O(n^2)$的工作量。将延续显式化后,就能看见真正的机会——可以把它存储为类型对齐序列,相邻结果与输入类型由构造保证匹配。高效拼接该序列即可消除对结合顺序敏感的遍历。 + +开放联合类型随后让可扩展效应解释器能够添加、组合与消除选定的请求类型。这解决了模块化效应组合与处理器结构问题,但仍未提供某个具体领域的等式,也不会决定两个带效应程序何时具有相同含义。 + +结论比“freer 优于 free”更加精确:自由单子揭示了请求与解释之间有价值的分离;freer 编码去除了不必要的约束;类型对齐队列解决了经测量确认的性能问题;可扩展效应改善了组合。每一步都保留前一步的经验,同时缩小主张范围。语义解释始终是另一项独立决定。 + +参见 Kiselyov 与 Ishii 的论文[*《Freer 单子:更具可扩展性的效应》*](https://okmij.org/ftp/Haskell/extensible/more.pdf)。 + +
+ +## CPS 程序 {#cps-programs} + +延续传递风格(CPS)会将计算剩余部分显式表示为延续。CPS 的操作语义会描述以下行为: + +* 对当前 CPS 表达式求值; +* 将生成的值传递给其延续; +* 应用该延续时转移控制权。 + +CPS 将控制流变为便于从操作层面描述的形式,但它是一种表示或程序变换,而非操作语义。要将直接风格程序与其 CPS 翻译关联起来,必须明确源语义、目标语义并给出保义论证。 + +
+超越 CPS:何时必须检查延续 + +CPS 是解决结合顺序敏感的追加与 bind 的常见方法。它不再反复遍历左结合结构,而是通过函数组合表示剩余计算。如果对延续唯一要做的操作是最终应用,这种表示就很高效。 + +van der Ploeg 与 Kiselyov 指出了适用边界:有些使用者必须在继续之前检查或修改中间结果。非确定性搜索、迭代器、自由单子与可扩展效应都可能需要此类访问。CPS 会将概念上的序列隐藏在函数中,因此要恢复中间结构就需要反射回数据,从而可能抵消性能优势。 + +他们提出的替代方案会将隐藏序列直接表示为类型对齐数据结构。它无论结合顺序如何都能高效组合,同时保留对中间结果的高效访问。类型会确保每个存储的计算都能产生下一个计算所需的输入。 + +更广泛的结论并非类型对齐序列击败 CPS,而是 CPS 擅长*应用*延续;当使用者必须*检查*延续时,它就不那么合适。关于带界控制的研究进一步深化了这一教训:不要将整个未来视作一个无法区分的延续,而应使用分界符明确可捕获与操纵的周边计算范围。 + +这些思想并未消失。它们的经验继续影响效应处理器、抽象机器推导、有类型控制运算符与高效效应表示。变化的是,人们不再认为 CPS 单独就应成为最终抽象。 + +参见 van der Ploeg 与 Kiselyov 的论文[*《无悔反射》*](https://okmij.org/ftp/Haskell/zseq.pdf)。关于更广泛的控制模型,另请参阅 Kiselyov 的[延续与带界控制文集](https://okmij.org/ftp/continuations/index.html)。 + +
+ +## 去函数化机器 {#defunctionalized-machines} + +去函数化会将已知的函数值集合(例如 CPS 延续)替换为一阶构造器,并提供一个`apply`操作。随后,操作语义可以描述这些显式配置之间的状态转换。 + +在具体的 CPS 变换之后再进行去函数化,可以推导出抽象机器。这是一种强有力的推导方式,但不是操作语义的通用定义:操作规则不必源自 CPS,任意一阶机器也不会因此自动成为去函数化的延续机器。 + +
+Reynolds:去函数化的起源 + +John C. Reynolds 在 1972 年关于定义解释器的研究中引入了去函数化。他的起点并非一阶虚拟机,而是高阶解释器:定义语言中的函数表示环境、延续及所定义语言的其他部分。 + +该变换会观察整个程序中可能出现的有限函数抽象集合。它将每个抽象替换为一个一阶构造器,并携带其自由变量的值;随后将函数应用替换为一个按构造器分派的`apply`操作。原本隐含在定义语言中的内容,就此变成显式的闭包或延续代数。 + +将这一做法应用于基于延续的解释器,可以显露出一台机器:延续构造器变为控制状态,被捕获变量变为存储的机器数据,`apply`则变成转换分派器。机器不是预先猜出来的,而是从高阶求值器推导出来的。 + +Reynolds 也强调了这种清晰度的代价。所得机器包含正确但不唯一的表示选择。不同的构造器选择或前置变换可能生成不同的、类似机器的“齿轮与部件”,但仍保留相同的行为。因此,去函数化显露的是一种操作结构,而非语言唯一必然的含义。 + +Danvy 与 Nielsen 后来将 Reynolds 的技术系统化为全程序变换,并研究了作为其逆变换的重新函数化。他们更深层的结论是:这种变换是一座桥梁,能够在高阶定义与一阶机器之间传递规范与正确性论证,还能揭示表面上无关的程序其实是同一结构的两种表示。 + +这条研究脉络说明了该技术应有的权威范围。去函数化不只是把闭包替换为枚举,但也不是普遍基础:它是在两种表示间保义转换,其对应关系必须得到确立。 + +参见 Reynolds 的[*《高阶编程语言的定义解释器》*](https://homepages.inf.ed.ac.uk/wadler/papers/papers-we-love/reynolds-definitional-interpreters-1972.pdf),以及 Danvy 与 Nielsen 的[*《去函数化的实践》*](https://tidsskrift.dk/brics/article/view/21684)。 + +
+ +## 操作表示循环 {#the-operational-representation-cycle} + +一种常见错误是试图寻找能解决所有编程问题的单一操作表示。每种表示都会恢复前一种表示隐藏的内容,但也会使另一种关切更难处理: + +$$ \text{higher-order program} \longrightarrow \text{free syntax} \longrightarrow \text{CPS} \longrightarrow \text{first-order machine} \longrightarrow \text{higher abstraction} $$ + +这些箭头并不表示编译器必须采用某条流水线,而是展示一种反复出现的设计演进:显露当前表示隐藏的内容,随后再隐藏此次显露引入的机制。 + +| 表示 | 使哪些内容可见 | 引入了何种压力 | +| --- | --- | --- | +| 高阶函数 | 直接组合与宿主语言抽象 | 泛型使用者可以调用函数,却无法检查函数隐藏的结构 | +| 带顺序组合的自由语法 | 以数据形式表示、可组合并可解释的程序 | 自由性本身不提供领域等式、规范化、高效求值,也不支持检查已存储的函数 | +| CPS | 求值顺序与计算剩余部分变得显式 | 全程序 CPS 编码会让延续贯穿几乎每个接口 | +| 去函数化的一阶控制 | 延续变成可检查、可序列化的分支 | 必须显式维护构造器、已存参数、转换状态与一个`apply`操作 | +| 对机器作更高层抽象 | 机制变得更易使用 | 编译器、调度器、调试器或优化器需要检查结构时,它又被隐藏起来 | + +这些压力来自结构本身。检查需要数据;将行为转为数据会引入构造器与解释器;隐藏这些构造器可以恢复便利的抽象,却会移除分析或变换程序的使用者所需的访问能力。 + +自由单子的取舍尤其具有启发性。自由单子解决了一个精确问题:为指令函子生成顺序组合,而不施加单子定律之外的等式。这一保证也构成了它的局限。它不了解领域定律。如果对同一单元格的两次写入应当等价于最终那次写入,那么自由程序仍会保留两条指令,直到领域专用的规范化或解释将它们识别为等价。因此,优化、规范形式与语义等价必须由其他机制提供。 + +将指令具体化为数据,也不会让整个程序都可检查。在常见编码中,挂起的指令可见,但其延续却是宿主语言函数。泛型分析器无法检查该函数背后的未来结构,除非提供结果并应用该函数。将延续具体化可以恢复可检查性,但会转向一阶或去函数化表示——于是又回到了循环的下一环。 + +求值开销同样取决于表示。左结合绑定构成的朴素树可能需要反复遍历,导致二次复杂度。复制剩余子程序的变换可能导致指数级增长。Codensity 风格、freer 或专用编码可以改善特定开销,但代价是选择了不同的表示与取舍。指数级增长确实可能发生,但不是自由单子的固有定律。 + +这就是自由单子并非通用解法的原因。它提供带定律的顺序组合语法,但不提供预期领域等式、规范范式、完整结构可见性或自动高效的实现。同样,局部使用 CPS 并不需要扩散到整个系统;去函数化只有在需要具体化的函数族与捕获值变多时才会变得繁琐。 + +当人们要求每种新编码都成为通用基础时,就会出现这个循环。它解决了上一种操作不便,随后又成为新的偶然复杂性来源。 + +因此,如果讨论“最佳抽象”时只关注操作特性,争论就难以收敛。高阶函数、自由语法、CPS 与一阶机器被拿来比较,仿佛其中一种必须胜过其他所有方案。但在说明必须保留什么、结果由谁使用之前,“*更好*”没有明确含义: + +* 直接执行偏好普通调用与隐藏表示; +* 变换与分析需要可检查的结构; +* 序列化需要一阶数据; +* 可扩展性可能更偏好增加解释,也可能更偏好增加语法,但两者很少同样容易; +* 并发可能需要有意忽略许多调度选择的观察。 + +这些是不同要求,而非某种抽象普遍更优的逐级证明。操作特性有助于为既定目的选择实现,却不能提供该目的,也不能决定哪些区别有意义。 + +同样的谨慎也适用于顺序思维。操作语义可以描述并发与非确定性系统,但单一机器步骤序列只是表示其行为的一种可能方式。如果过早将调度顺序视为权威,不同交错机制就会让本来等价的执行显得不同。语义模型必须先决定哪些观察可以区分并发程序,随后再根据该决定评判操作调度。 + +## 真实示例:EVM {#real-example-the-evm} + +以操作视角理解以太坊虚拟机(EVM): + +* **状态**:程序计数器、栈、内存、存储、Gas +* **转换规则**:每个操作码各有一条(`ADD`、`PUSH`、`SSTORE`等) +* **执行**:反复应用小步规则,直至停止 + +EVM 字节码是一阶指令数据。操作性描述会规定每种操作码如何改变 EVM 配置;具体客户端则负责实现该行为。 + +它的分派循环与程序计数器可能类似于去函数化抽象机。但若要称其为去函数化延续,就必须提供具体高阶源程序、变换与对应关系,不能只凭循环看起来相似。 + +## 打破循环:机制之前先确定含义 {#breaking-the-cycle-meaning-before-machinery} + +操作描述与指称描述回答不同的问题: + +$$ \begin{aligned} \llbracket p \rrbracket &\in D && \text{what does the program mean?} \\ c &\longrightarrow c' && \text{how does this representation step?} \end{aligned} $$ + +语义优先的开发会先选择语义域、组合、观察与定律,再确定机器表示。一旦选定转换系统,其正确性义务就负责连接这两个层次。对于恰当定义的完整配置含义,典型的静默步骤保留主张如下: + +$$ c \longrightarrow c' \quad \Longrightarrow \quad \operatorname{meaning}(c) = \operatorname{meaning}(c') $$ + +具体关系也可以改用观察等价、轨迹或双模拟。关键在于,机器必须对预期含义负责。 + +指称设计不会从循环中选出胜者,而是在循环之外建立稳定的权威来源: + +1. 定义语义域、操作、组合与定律。 +2. 根据这些含义编写程序。 +3. 针对具体使用者选择表示:直接执行、检查、编译、调度、序列化或分析。 +4. 将每种选定的表示与变换都关联回同一含义。 + +因此,高阶解释器与一阶程序可以共存。二者都不必成为语言定义。前者可以服务于直接执行;后者可以服务于需要结构的使用者。二者一致是一项语义义务,而非假定其机制相同。 + +```admonish note title="不存在最终的操作抽象" +每种操作表示都会显露某些结构并隐藏另一些结构。含义是稳定的出发点,我们据此选择恰当的表示并建立它们之间的联系。 +``` + +## 总结 {#summary} + +* 操作语义描述所选表示的求值或状态转换。 +* 自由单子提供指令语法与顺序组合,但其行为仍需要解释。 +* CPS 会显露延续;操作规则可以描述 CPS 程序如何传递值与控制权。 +* 去函数化可以将某个高阶程序转换为一阶机器,并以操作规则描述其状态转换。 +* 将其中任意一种编码视为通用方案,都会造成结构不断被具体化又被隐藏的循环。 +* 指称含义决定这些状态转换必须保留什么。 diff --git a/src/insights/referential-transparency.ar.md b/src/insights/referential-transparency.ar.md new file mode 100644 index 0000000..87c0c37 --- /dev/null +++ b/src/insights/referential-transparency.ar.md @@ -0,0 +1,118 @@ + + +# إعادة طرح الشفافية المرجعية {#referential-transparency-reloaded} + +```admonish tip title="ذات صلة" +الرؤية الدلالية: [الدلالات والتركيبية](../denotational-design/denotations.md)، [القوانين والتفسيرات](../denotational-design/laws-and-interpretations.md) +التصميم انطلاقًا من المعنى في Rust: [جبريات القدرات](../rust-dd/capability-algebras.md)، [المعنى المشتق والتركيب](../rust-dd/derived-meaning.md) +المفاهيم: [الشفافية المرجعية](../concepts/referential_transparency.md) +``` + +تعرض هذه الصفحة تفسير التصميم الدلالي لـ *الشفافية المرجعية*. وتتناول صفحة المفهوم التاريخ واستخدام المصطلح في اللغات السائدة. أما هنا فنركز على ما تعنيه الشفافية المرجعية بوصفها قيدًا تصميميًا. + +في التصميم الدلالي، ليست الشفافية المرجعية تسمية للنقاء. إنها قانون على الدلالات: يجب أن يحافظ الاستبدال على المعنى المحدد. + +## إعادة صياغة التصميم الدلالي للشفافية المرجعية {#denotational-design-restatement-of-rt} + +يعيد التصميم الدلالي صياغة الشفافية المرجعية بوصفها مطلبًا للمواصفات لا لأسلوب التنفيذ. يجب أن تحدد المواصفة المعنى التركيبي أولًا؛ ثم تُختار استراتيجية التنفيذ. + +لذا تُفحص الشفافية المرجعية عند الحد الدلالي: + +* المدخلات نفسها +* السياق المعلن نفسه +* الدلالة نفسها + +إذا تحققت هذه الشروط، صح الاستبدال وأصبح الاستدلال المعادلي متاحًا. ويظل ذلك صحيحًا حتى حين تنفذ المفسرات الملموسة إدخالًا وإخراجًا أو تزامنًا أو إعادة محاولات أو انتقالات حالة، لأن هذه التفاصيل مفوضة إلى ما وراء القدرات المحددة. + +بعبارة أخرى، لا يسأل التصميم الدلالي: «هل هذا التنفيذ نقي؟» بل يسأل: «هل المساويات الدلالية صريحة، وهل تحافظ عليها المفسرات؟» + +## النقاء والشفافية المرجعية {#purity-and-rt} + +الشفافية المرجعية والنقاء مترابطان لكنهما غير متطابقين. + +* **الشفافية المرجعية** قانون استبدال للمعنى. +* **النقاء** قيد تشغيلي: لا آثار خفية قابلة للملاحظة. + +النقاء طريقة شائعة لتحقيق الشفافية المرجعية في شيفرة التعبيرات. لكن الشفافية المرجعية تظل المعيار الدلالي: يجب أن يحافظ الاستبدال على الدلالة المحددة. + +لذلك يتجنب التصميم الدلالي تحويل الشفافية المرجعية إلى تسمية أسلوبية مثل «الشيفرة النقية فقط». المطلوب مساويات دلالية صريحة، مع عزل الآثار خلف حدود القدرات. + +إحدى أبسط القراءات الدلالية هي: + +```rust,noplayground +fn f(a: A, io: Io) -> (Result, Io) +``` + +للمدخل نفسه `a` و`io`، تعطي `f` الدلالة نفسها `(result, io')`. وهذه صيغة الاستدلال بالاستبدال المفهرسة بالسياق وفق أسلوب التصميم الدلالي. + +## لماذا يوضح هذا الشفافية المرجعية {#why-this-clarifies-rt} + +تخلط نقاشات كثيرة حول الشفافية المرجعية بين تمييز مفيد: + +* الشفافية الدلالية +* الآثار الجانبية التشغيلية + +يفصل التصميم الدلالي بين هاتين الطبقتين: + +* النواة الدلالية تحدد المعنى +* المفسرات تحقق استراتيجية التنفيذ + +يتيح هذا الفصل آثارًا عملية دون فقدان الاستدلال القائم على القوانين. + +## إخفاق النهج الذي يبدأ بالتمثيل {#representation-first-failure-mode} + +إذا التزمت مبكرًا بتمثيل ملموس، ينحرف نقاش الشفافية المرجعية إلى جدالات أسلوبية: + +* «هذا الأسلوب نقي» +* «ذلك الأسلوب غير نقي» +* «أغلفة IO تحل المشكلة» + +تتعلق هذه النقاشات في معظمها بالترميز. ويطرح التصميم الدلالي سؤالًا أبسط: ما المساويات الصحيحة في مواصفتك؟ + +## نمط عملي للتصميم الدلالي {#practical-dd-pattern} + +عرّف سمات قدرات صغيرة واكتب سلوك البرنامج بوصفه امتدادات فوقها. ثم وفر مفسرات ملموسة رقيقة. + +```rust,noplayground +trait FileSystem { + type Error; + + fn file_read(&self, name: &str) -> Result; +} + +trait GithubPublish { + type Error; + + fn github_publish(&self, repo: &str, files: Vec) -> Result<(), Self::Error>; +} + +trait Concurrent { + fn map_concurrent(&self, xs: &[A], f: F) -> Result, E> + where + A: Clone, + F: Fn(&A) -> Result; +} + +#[ext(name = PublishProjectExt)] +impl This +where + This: FileSystem + GithubPublish + Concurrent, +{ + fn publish_project(&self, files: &[&str], repo: &str) -> Result<(), String> { + let files = self.map_concurrent(files, |name| self.file_read(*name))?; + self.github_publish(repo, files) + } +} +``` + +`#[ext(...)]` ماكرو من الحزمة [`extend`، وتقلل الشيفرة النمطية بإنشاء أساليب امتداد من كتلة `impl`؛ وليست ميزة جديدة في لغة Rust.](https://docs.rs/extend/latest/extend/) + +في البرمجة الوظيفية بـ Scala، غالبًا ما تُعرض الشفافية المرجعية عبر قيم من النوع `F[A]` (مثل `IO[A]` أو `F[Either[E, A]]`). أما هنا، فيُعبَّر عنها في مستوى أعلى: بوصفها معنى برنامج مقيدًا بالقدرات. لذلك لا يخزن أسلوب Rust هذا قيمة شفافية مرجعية بالمعنى الترميزي نفسه الذي يخزنها به `F[A]`؛ بل هو سلوك شفاف مرجعيًا محدد عبر قدرات صريحة، مع تفويض الآثار الملموسة إلى التطبيقات. + +يحدد الامتداد السلوك الدلالي بالاعتماد على القدرات. وتقرر التطبيقات الملموسة استراتيجية التنفيذ: التجميع وإعادة المحاولة والنقل والتوازي وتفاصيل التخزين. + +## الرؤية الأخيرة {#final-insight} + +في التصميم الدلالي، الشفافية المرجعية خاصية للمواصفات الدلالية. وتظل خيارات التنفيذ ثانوية ما دامت تحافظ على القوانين الدلالية المحددة. + +حافظ على القانون. ولا تتعلق بالتسمية. diff --git a/src/insights/referential-transparency.de.md b/src/insights/referential-transparency.de.md new file mode 100644 index 0000000..8ab3502 --- /dev/null +++ b/src/insights/referential-transparency.de.md @@ -0,0 +1,118 @@ + + +# Referenzielle Transparenz neu betrachtet {#referential-transparency-reloaded} + +```admonish tip title="Verwandte Themen" +The Semantic View: [Denotationen und Kompositionalität](../denotational-design/denotations.md), [Gesetze und Interpretationen](../denotational-design/laws-and-interpretations.md) +Design by Meaning in Rust: [Capability-Algebren](../rust-dd/capability-algebras.md), [Abgeleitete Bedeutung und Komposition](../rust-dd/derived-meaning.md) +Concepts: [Referenzielle Transparenz](../concepts/referential_transparency.md) +``` + +Diese Seite stellt die Interpretation von *referenzieller Transparenz* im Denotational Design vor. Die Konzeptseite behandelt Geschichte und gebräuchliche Verwendung in Programmiersprachen. Hier geht es darum, was RT als Entwurfsbedingung bedeutet. + +Im DD ist RT keine Bezeichnung für Reinheit. Sie ist ein Gesetz über Denotationen: Substitution muss die spezifizierte Bedeutung bewahren. + +## RT im Denotational Design neu formuliert {#denotational-design-restatement-of-rt} + +Denotational Design formuliert RT als Anforderung an Spezifikationen statt an den Implementierungsstil. Zuerst muss die Spezifikation kompositionale Bedeutung festlegen; die Ausführungsstrategie wird später gewählt. + +RT wird also an der semantischen Grenze geprüft: + +* dieselben Eingaben +* derselbe deklarierte Kontext +* dieselbe Denotation + +Sind diese Bedingungen erfüllt, ist Substitution gültig und Schlussfolgern mit Gleichungen möglich. Das gilt auch dann, wenn konkrete Interpreter Ein-/Ausgabe, Nebenläufigkeit, Wiederholungsversuche oder Zustandsübergänge ausführen, denn diese Details sind hinter den spezifizierten Capabilities verborgen. + +Anders gesagt: DD fragt nicht: „Ist diese Implementierung rein?“ DD fragt: „Sind die denotationellen Gleichheiten explizit, und bewahren die Interpreter sie?“ + +## Reinheit und RT {#purity-and-rt} + +RT und Reinheit hängen zusammen, sind aber nicht identisch. + +* **RT** ist ein Substitutionsgesetz über Bedeutung. +* **Reinheit** ist eine operationale Einschränkung: keine verborgenen beobachtbaren Effekte. + +Reinheit ist ein gängiger Weg, RT für Code auf Ausdrucksebene zu erreichen. RT bleibt jedoch das semantische Kriterium: Die Substitution muss die spezifizierte Denotation bewahren. + +DD macht RT daher nicht zu einer Stilvorschrift wie „nur reinen Code verwenden“. Gefordert sind explizite semantische Gleichheiten; Effekte werden hinter Capability-Grenzen isoliert. + +Eine minimale semantische Lesart lautet: + +```rust,noplayground +fn f(a: A, io: Io) -> (Result, Io) +``` + +Wenn `a` und die Eingabe `io` gleich sind, liefert `f` dasselbe `(result, io')`. Dies ist die kontextindizierte Form des Substitutionsschlusses im Stil des DD. + +## Warum dies RT verdeutlicht {#why-this-clarifies-rt} + +Viele RT-Debatten verwischen eine nützliche Unterscheidung: + +* semantische Transparenz +* operationale Seiteneffekte + +DD trennt diese Ebenen: + +* Der semantische Kern legt die Bedeutung fest +* Interpreter realisieren die Ausführungsstrategie + +Diese Trennung ermöglicht praktische Effekte, ohne Schlussfolgern anhand von Gesetzen aufzugeben. + +## Fehlerbild bei repräsentationsorientiertem Entwurf {#representation-first-failure-mode} + +Legt man sich früh auf eine konkrete Repräsentation fest, verlagert sich die RT-Diskussion häufig auf Stilfragen: + +* „Dieser Stil ist rein.“ +* „Jener Stil ist unrein.“ +* „IO-Wrapper lösen das Problem.“ + +Dabei geht es meist um Kodierungen. DD stellt eine einfachere Frage: Welche Gleichheiten gelten in deiner Spezifikation? + +## Praktisches DD-Muster {#practical-dd-pattern} + +Kleine Capability-Traits definieren und Programmverhalten als Erweiterungen darüber formulieren. Anschließend schlanke konkrete Interpreter bereitstellen. + +```rust,noplayground +trait FileSystem { + type Error; + + fn file_read(&self, name: &str) -> Result; +} + +trait GithubPublish { + type Error; + + fn github_publish(&self, repo: &str, files: Vec) -> Result<(), Self::Error>; +} + +trait Concurrent { + fn map_concurrent(&self, xs: &[A], f: F) -> Result, E> + where + A: Clone, + F: Fn(&A) -> Result; +} + +#[ext(name = PublishProjectExt)] +impl This +where + This: FileSystem + GithubPublish + Concurrent, +{ + fn publish_project(&self, files: &[&str], repo: &str) -> Result<(), String> { + let files = self.map_concurrent(files, |name| self.file_read(*name))?; + self.github_publish(repo, files) + } +} +``` + +`#[ext(...)]` ist ein Makro aus dem [`extend`Crate](https://docs.rs/extend/latest/extend/), das Boilerplate reduziert, indem es Erweiterungsmethoden aus einem `impl`\-Block generiert. Es ist keine neue Sprachfunktion von Rust. + +In der funktionalen Scala-Praxis wird RT oft über Werte des Typs `F[A]` dargestellt (zum Beispiel `IO[A]` oder `F[Either[E, A]]`). Hier wird RT eine Ebene höher ausgedrückt: als durch Capabilities begrenzte Programmbedeutung. Diese Rust-Methode ist also kein RT-Wertcontainer in derselben Kodierungsform wie `F[A]`; sie beschreibt RT-Verhalten über explizite Capabilities und delegiert konkrete Effekte an Implementierungen. + +Die Erweiterung formuliert semantisches Verhalten über Capabilities. Konkrete Implementierungen bestimmen die Ausführungsstrategie: Batchverarbeitung, Wiederholungen, Transport, Parallelität und Speicherdetails. + +## Abschließende Erkenntnis {#final-insight} + +Im Denotational Design ist RT eine Eigenschaft semantischer Spezifikationen. Implementierungsentscheidungen sind nachgeordnet, solange sie die formulierten denotationellen Gesetze bewahren. + +Bewahre das Gesetz. Verliere dich nicht in der Bezeichnung. diff --git a/src/insights/referential-transparency.es.md b/src/insights/referential-transparency.es.md new file mode 100644 index 0000000..cb27c59 --- /dev/null +++ b/src/insights/referential-transparency.es.md @@ -0,0 +1,118 @@ + + +# Transparencia referencial, reexaminada {#referential-transparency-reloaded} + +```admonish tip title="Relacionado" +La perspectiva semántica: [Denotaciones y composicionalidad](../denotational-design/denotations.md), [Leyes e interpretaciones](../denotational-design/laws-and-interpretations.md) +Diseño basado en el significado en Rust: [Álgebras de capacidades](../rust-dd/capability-algebras.md), [Significado derivado y composición](../rust-dd/derived-meaning.md) +Conceptos: [Transparencia referencial](../concepts/referential_transparency.md) +``` + +Esta página presenta la interpretación de la *transparencia referencial* en el diseño denotacional. La página sobre el concepto abarca su historia y el uso habitual del término en los lenguajes. Aquí nos centramos en lo que significa la RT como restricción de diseño. + +En el diseño denotacional, la RT no es una etiqueta de pureza. Es una ley sobre denotaciones: la sustitución debe preservar el significado especificado. + +## Reformulación de la RT en el diseño denotacional {#denotational-design-restatement-of-rt} + +El diseño denotacional reformula la RT como un requisito de la especificación, no del estilo de implementación. La especificación debe definir primero el significado composicional; la estrategia de ejecución se elige después. + +Por tanto, la RT se comprueba en el límite semántico: + +* mismas entradas +* mismo contexto declarado +* misma denotación + +Si se cumplen estas condiciones, la sustitución es válida y se puede razonar mediante ecuaciones. Esto también se cumple cuando los intérpretes concretos realizan E/S, concurrencia, reintentos o transiciones de estado, porque esos detalles se delegan tras los límites de las capacidades especificadas. + +En otras palabras, el diseño denotacional no pregunta «¿esta implementación es pura?». Pregunta «¿son explícitas las igualdades denotacionales y las preservan los intérpretes?». + +## Pureza y RT {#purity-and-rt} + +La RT y la pureza están relacionadas, pero no son idénticas. + +* La **RT** es una ley de sustitución sobre el significado. +* La **pureza** es una restricción operacional: no hay efectos observables ocultos. + +La pureza es una forma habitual de obtener RT en el código a nivel de expresiones. Pero la RT sigue siendo el criterio semántico: la sustitución debe preservar la denotación especificada. + +Por eso, el diseño denotacional evita convertir la RT en una etiqueta de estilo como «solo código puro». El requisito son igualdades semánticas explícitas, con los efectos aislados tras límites de capacidades. + +Una lectura semántica mínima es: + +```rust,noplayground +fn f(a: A, io: Io) -> (Result, Io) +``` + +Para las mismas entradas `a` y `io`, `f` produce la misma `(result, io')`. Esta es una forma de razonar por sustitución indexada por contexto, al estilo del diseño denotacional. + +## Por qué esto aclara la RT {#why-this-clarifies-rt} + +Muchos debates sobre RT difuminan una distinción útil: + +* transparencia semántica +* efectos secundarios operacionales + +El diseño denotacional separa estas capas: + +* el núcleo semántico define el significado +* los intérpretes realizan la estrategia de ejecución + +Esta separación permite efectos prácticos sin perder el razonamiento basado en leyes. + +## Modo de fallo por priorizar la representación {#representation-first-failure-mode} + +Si se elige pronto una representación concreta, el debate sobre RT deriva hacia discusiones de estilo: + +* «este estilo es puro» +* «ese estilo es impuro» +* «los envoltorios de E/S lo solucionan» + +Son debates de codificación en su mayoría. El diseño denotacional plantea una pregunta más sencilla: ¿qué igualdades son válidas en tu especificación? + +## Patrón práctico del diseño denotacional {#practical-dd-pattern} + +Define rasgos de capacidades pequeños y escribe el comportamiento del programa como extensiones de ellos. Después proporciona intérpretes concretos y delgados. + +```rust,noplayground +trait FileSystem { + type Error; + + fn file_read(&self, name: &str) -> Result; +} + +trait GithubPublish { + type Error; + + fn github_publish(&self, repo: &str, files: Vec) -> Result<(), Self::Error>; +} + +trait Concurrent { + fn map_concurrent(&self, xs: &[A], f: F) -> Result, E> + where + A: Clone, + F: Fn(&A) -> Result; +} + +#[ext(name = PublishProjectExt)] +impl This +where + This: FileSystem + GithubPublish + Concurrent, +{ + fn publish_project(&self, files: &[&str], repo: &str) -> Result<(), String> { + let files = self.map_concurrent(files, |name| self.file_read(*name))?; + self.github_publish(repo, files) + } +} +``` + +`#[ext(...)]` es una macro de la biblioteca [`extend`](https://docs.rs/extend/latest/extend/) que reduce el código repetitivo generando métodos de extensión a partir de un bloque `impl`; no es una característica nueva del lenguaje Rust. + +En la programación funcional de Scala, la RT suele presentarse mediante valores de tipo `F[A]` (por ejemplo, `IO[A]` o `F[Either[E, A]]`). Aquí, la RT se expresa un nivel más arriba: como significado de programa limitado por capacidades. Por tanto, este método de Rust no es un contenedor de valores RT en el mismo sentido de codificación que `F[A]`; es comportamiento RT especificado sobre capacidades explícitas, cuyos efectos concretos se delegan a las implementaciones. + +La extensión establece el comportamiento semántico con respecto a las capacidades. Las implementaciones concretas deciden la estrategia de ejecución: agrupamiento, reintentos, transporte, paralelismo y detalles de almacenamiento. + +## Perspectiva final {#final-insight} + +En el diseño denotacional, la RT es una propiedad de las especificaciones semánticas. Las elecciones de implementación son secundarias, siempre que preserven las leyes denotacionales declaradas. + +Conserva la ley. No te quedes atascado en la etiqueta. diff --git a/src/insights/referential-transparency.ja.md b/src/insights/referential-transparency.ja.md new file mode 100644 index 0000000..b0d61f9 --- /dev/null +++ b/src/insights/referential-transparency.ja.md @@ -0,0 +1,118 @@ + + +# 参照透過性再考 {#referential-transparency-reloaded} + +```admonish tip title="関連項目" +意味論的な見方:[表示と合成性](../denotational-design/denotations.md)、[法則と解釈](../denotational-design/laws-and-interpretations.md) +Rustで意味から設計する:[ケイパビリティ代数](../rust-dd/capability-algebras.md)、[導出される意味と合成](../rust-dd/derived-meaning.md) +概念:[参照透過性](../concepts/referential_transparency.md) +``` + +このページでは*参照透過性*をDenotational Designの観点から解釈します。 概念の章では歴史と主要な言語での使い方を扱います。 ここでは、設計上の制約としてのRTの意味に焦点を当てます。 + +DDではRTは純粋性のラベルではありません。 表示に関する法則であり、置換によって指定された意味が保持されなければなりません。 + +## RTをDenotational Designで捉え直す {#denotational-design-restatement-of-rt} + +Denotational Designでは、RTを実装スタイルではなく仕様への要件として捉え直します。 まず仕様で合成可能な意味を定め、その後で実行戦略を選びます。 + +したがって、RTは意味論上の境界で検査します。 + +* 同じ入力 +* 同じ宣言済みコンテキスト +* 同じ表示 + +これらが成り立つなら、置換は妥当であり、等式に基づく推論が可能です。具体的なインタープリターがIO、並行性、再試行、状態遷移を行う場合も同様です。それらの詳細は宣言されたケイパビリティの背後に委譲されるためです。 + +つまりDDで問うのは「この実装は純粋か」ではありません。 DDで問うのは「表示の等式が明示され、インタープリターがそれを保持しているか」です。 + +## 純粋性とRT {#purity-and-rt} + +RTと純粋性は関連しますが、同一ではありません。 + +* **RT**は意味に関する置換法則です。 +* **純粋性**は、隠れた観測可能な副作用を認めないという操作上の制約です。 + +式レベルのコードでRTを得る一般的な方法は純粋性です。しかしRTは意味論上の基準として残ります。置換によって指定された表示が保たれなければなりません。 + +そのためDDはRTを「純粋なコードだけ」といったスタイル上のラベルに変えません。 必要なのは、明示的な意味論的等式と、ケイパビリティ境界の背後に隔離された副作用です。 + +最小限の意味論的な読み方は次のとおりです。 + +```rust,noplayground +fn f(a: A, io: Io) -> (Result, Io) +``` + +同じ`a`と同じ`io`入力のもとで、`f`は同じ`(result, io')`を与える。 これはDD形式で、コンテキストを添字にした置換推論です。 + +## RTを明確にする理由 {#why-this-clarifies-rt} + +RTをめぐる議論では、次の有用な区別が曖昧になることがよくあります。 + +* 意味論的な透明性 +* 操作上の副作用 + +DDではこれらの層を分けます。 + +* 意味論的な中核が意味を述べる +* インタープリターが実行戦略を実現する + +この分離により、法則に基づく推論を保ったまま実際の副作用を扱えます。 + +## 表現先行で設計する場合の失敗 {#representation-first-failure-mode} + +具体的な表現を早い段階で決めてしまうと、RTの議論がスタイル論にずれることがあります。 + +* 「このスタイルは純粋だ」 +* 「あのスタイルは不純だ」 +* 「IOラッパーで解決できる」 + +こうした議論の多くは符号化に関するものです。 DDでは、より単純な問いを立てます。 仕様で妥当な等式は何か。 + +## 実践的なDDのパターン {#practical-dd-pattern} + +小さなケイパビリティトレイトを定義し、それらに基づく拡張としてプログラムの振る舞いを記述します。 その後に薄い具体インタープリターを用意します。 + +```rust,noplayground +trait FileSystem { + type Error; + + fn file_read(&self, name: &str) -> Result; +} + +trait GithubPublish { + type Error; + + fn github_publish(&self, repo: &str, files: Vec) -> Result<(), Self::Error>; +} + +trait Concurrent { + fn map_concurrent(&self, xs: &[A], f: F) -> Result, E> + where + A: Clone, + F: Fn(&A) -> Result; +} + +#[ext(name = PublishProjectExt)] +impl This +where + This: FileSystem + GithubPublish + Concurrent, +{ + fn publish_project(&self, files: &[&str], repo: &str) -> Result<(), String> { + let files = self.map_concurrent(files, |name| self.file_read(*name))?; + self.github_publish(repo, files) + } +} +``` + +`#[ext(...)]`は[`extend`クレートのマクロ](https://docs.rs/extend/latest/extend/)で、`impl`ブロックから拡張メソッドを生成して定型コードを減らします。Rustの新しい言語機能ではありません。 + +Scalaの関数型プログラミングでは、RTを`F[A]`型の値(例:`IO[A]`または`F[Either[E, A]]`)で表すことがよくあります。 ここでは一段上のレベルで、ケイパビリティによって境界付けられたプログラムの意味としてRTを表します。 そのため、このRustのメソッドは`F[A]`と同じ符号化の意味でRTの値を格納するコンテナーではありません。明示的なケイパビリティに基づき仕様化されたRTの振る舞いであり、具体的な副作用は実装に委譲されます。 + +拡張はケイパビリティに対する意味論上の振る舞いを述べます。 具体的な実装が、バッチ処理、再試行、通信方式、並列性、格納の詳細などの実行戦略を決めます。 + +## 最後の洞察 {#final-insight} + +Denotational Designでは、RTは意味論的な仕様の性質です。 述べられた表示上の法則を守る限り、実装上の選択は二次的です。 + +法則を保つ。 ラベルにとらわれない。 diff --git a/src/insights/referential-transparency.ko.md b/src/insights/referential-transparency.ko.md new file mode 100644 index 0000000..d078d33 --- /dev/null +++ b/src/insights/referential-transparency.ko.md @@ -0,0 +1,118 @@ + + +# 참조 투명성 다시 보기 {#referential-transparency-reloaded} + +```admonish tip title="관련 항목" +의미론적 관점: [표시와 합성성](../denotational-design/denotations.md), [법칙과 해석](../denotational-design/laws-and-interpretations.md) +Rust에서 의미로 설계하기: [케이퍼빌리티 대수](../rust-dd/capability-algebras.md), [파생 의미와 합성](../rust-dd/derived-meaning.md) +개념: [참조 투명성](../concepts/referential_transparency.md) +``` + +이 페이지에서는 *참조 투명성*을 표시적 설계 관점에서 설명합니다. 개념 페이지에서는 역사와 주류 언어에서의 사용을 다룹니다. 여기서는 RT가 설계 제약으로서 무엇을 의미하는지 살펴봅니다. + +표시적 설계에서 RT는 순수성이라는 꼬리표가 아닙니다. 표시에 관한 법칙입니다. 치환해도 명세된 의미가 보존되어야 합니다. + +## RT를 표시적 설계 관점에서 다시 서술하기 {#denotational-design-restatement-of-rt} + +표시적 설계는 RT를 구현 스타일이 아니라 명세의 요구 사항으로 다시 서술합니다. 명세는 합성 의미를 먼저 정의해야 하며 실행 전략은 나중에 선택합니다. + +그러므로 RT는 의미론적 경계에서 확인합니다: + +* 같은 입력 +* 같다고 선언된 컨텍스트 +* 같은 표시 + +이 조건이 성립하면 치환이 유효하고 등식 추론이 가능합니다. 구체적 인터프리터가 IO, 동시성, 재시도, 상태 전이를 수행하더라도 명세된 케이퍼빌리티 뒤에 위임되므로 이 원칙은 그대로 적용됩니다. + +다시 말해 표시적 설계는 “이 구현이 순수한가?”라고 묻지 않습니다. 표시적 설계가 묻는 것은 “표시 등식이 명시되어 있고 인터프리터가 이를 보존하는가?”입니다. + +## 순수성과 RT {#purity-and-rt} + +RT와 순수성은 관련은 있지만 동일하지 않습니다. + +* **RT**는 의미에 관한 치환 법칙입니다. +* **순수성**은 숨겨진 관찰 가능 효과가 없어야 한다는 작동 제약입니다. + +표현식 수준 코드에서 RT를 얻는 흔한 방법이 순수성입니다. 그러나 RT는 여전히 의미론적 기준입니다. 치환해도 명세된 표시가 보존되어야 합니다. + +따라서 표시적 설계는 RT를 “순수 코드만” 같은 스타일 꼬리표로 만들지 않습니다. 효과를 케이퍼빌리티 경계 뒤에 분리하고 명시적인 의미 등식을 요구합니다. + +최소한의 의미론적 해석은 다음과 같습니다: + +```rust,noplayground +fn f(a: A, io: Io) -> (Result, Io) +``` + +같은 `a`와 같은 `io` 입력에 대해 `f`는 같은 `(result, io')`을 산출합니다. 이는 컨텍스트로 색인한 표시적 설계 방식의 치환 추론입니다. + +## 이 설명이 RT를 명확히 하는 이유 {#why-this-clarifies-rt} + +많은 RT 논의는 유용한 구분을 흐립니다: + +* 의미의 투명성 +* 작동상의 부작용 + +표시적 설계는 이 계층을 구분합니다: + +* 의미론적 핵심이 의미를 명시합니다 +* 인터프리터가 실행 전략을 실현합니다 + +이 분리 덕분에 법칙 기반 추론을 잃지 않고 실제 효과를 사용할 수 있습니다. + +## 표현 우선 설계의 실패 유형 {#representation-first-failure-mode} + +구체적인 표현을 일찍 확정하면 RT 논의가 스타일 논쟁으로 흐릅니다: + +* “이 스타일은 순수하다” +* “저 스타일은 불순하다” +* “IO 래퍼로 해결된다” + +이는 대부분 인코딩에 관한 논쟁입니다. 표시적 설계는 더 간단하게 묻습니다: 명세에서 어떤 등식이 유효한가요? + +## 실용적인 표시적 설계 패턴 {#practical-dd-pattern} + +작은 케이퍼빌리티 트레이트를 정의하고 프로그램 동작을 그 트레이트의 확장으로 작성합니다. 그런 다음 얇은 구체 인터프리터를 제공합니다. + +```rust,noplayground +trait FileSystem { + type Error; + + fn file_read(&self, name: &str) -> Result; +} + +trait GithubPublish { + type Error; + + fn github_publish(&self, repo: &str, files: Vec) -> Result<(), Self::Error>; +} + +trait Concurrent { + fn map_concurrent(&self, xs: &[A], f: F) -> Result, E> + where + A: Clone, + F: Fn(&A) -> Result; +} + +#[ext(name = PublishProjectExt)] +impl This +where + This: FileSystem + GithubPublish + Concurrent, +{ + fn publish_project(&self, files: &[&str], repo: &str) -> Result<(), String> { + let files = self.map_concurrent(files, |name| self.file_read(*name))?; + self.github_publish(repo, files) + } +} +``` + +`#[ext(...)]`는 [`extend` 크레이트의 매크로입니다](https://docs.rs/extend/latest/extend/). `impl` 블록에서 확장 메서드를 생성해 상용구를 줄이며, 새로운 Rust 언어 기능은 아닙니다. + +Scala 함수형 프로그래밍에서는 RT를 `F[A]` 타입의 값(예: `IO[A]` 또는 `F[Either[E, A]]`)을 통해 설명하는 경우가 많습니다. 여기서는 한 수준 위에서 케이퍼빌리티로 제한된 프로그램 의미로 RT를 표현합니다. 그러므로 이 Rust 메서드는 `F[A]`와 같은 인코딩 의미의 RT 값 컨테이너가 아닙니다. 명시적 케이퍼빌리티에 대해 명세된 RT 동작이며 구체 효과는 구현에 위임합니다. + +확장은 케이퍼빌리티에 따른 의미 동작을 명시합니다. 구체 구현은 일괄 처리, 재시도, 전송, 병렬성, 저장 세부 사항 등 실행 전략을 결정합니다. + +## 마지막 통찰 {#final-insight} + +표시적 설계에서 RT는 의미론적 명세의 속성입니다. 명시된 표시 법칙을 보존한다면 구현 선택은 부차적입니다. + +법칙을 유지하세요. 꼬리표에 매이지 마세요. diff --git a/src/insights/referential-transparency.ru.md b/src/insights/referential-transparency.ru.md new file mode 100644 index 0000000..81517a0 --- /dev/null +++ b/src/insights/referential-transparency.ru.md @@ -0,0 +1,118 @@ + + +# Референциальная прозрачность: новый взгляд {#referential-transparency-reloaded} + +```admonish tip title="Связанные материалы" +«Семантический взгляд»: [Денотации и композиционность](../denotational-design/denotations.md), [Законы и интерпретации](../denotational-design/laws-and-interpretations.md) +«Проектирование на основе смысла в Rust»: [Алгебры возможностей](../rust-dd/capability-algebras.md), [Производный смысл и композиция](../rust-dd/derived-meaning.md) +«Понятия»: [Референциальная прозрачность](../concepts/referential_transparency.md) +``` + +На этой странице референциальная прозрачность рассматривается *с точки зрения денотационного проектирования*. Страница «Понятия» рассказывает об истории и распространённом употреблении термина. Здесь речь пойдёт о том, что RT означает как проектное ограничение. + +В денотационном проектировании RT — не обозначение чистоты. Это закон для денотаций: подстановка должна сохранять заданный смысл. + +## Переформулировка RT в денотационном проектировании {#denotational-design-restatement-of-rt} + +Денотационное проектирование формулирует RT как требование к спецификациям, а не к стилю реализации. Сначала спецификация должна определить композиционный смысл; стратегию выполнения выбирают позднее. + +Поэтому RT проверяют на семантической границе: + +* одинаковые входные данные +* одинаковый объявленный контекст +* одинаковая денотация + +Если всё это выполняется, подстановка допустима и можно рассуждать через равенства. Это верно даже тогда, когда конкретные интерпретаторы выполняют ввод-вывод, параллельные задачи, повторы запросов или переходы состояния: такие детали делегированы возможностям, заданным спецификацией. + +Иными словами, денотационное проектирование не спрашивает: «чиста ли эта реализация?» Оно спрашивает: «явно ли заданы денотационные равенства и сохраняют ли их интерпретаторы?» + +## Чистота и RT {#purity-and-rt} + +RT и чистота связаны, но не тождественны. + +* **RT** — закон подстановки для смысла. +* **Чистота** — операционное ограничение: отсутствие скрытых наблюдаемых эффектов. + +Чистота часто позволяет добиться RT на уровне выражений. Однако RT остаётся семантическим критерием: подстановка должна сохранять заданную денотацию. + +Поэтому денотационное проектирование не превращает RT в стилевой ярлык вроде «только чистый код». Требование состоит в явных семантических равенствах и изоляции эффектов за границами возможностей. + +Минимальная семантическая трактовка: + +```rust,noplayground +fn f(a: A, io: Io) -> (Result, Io) +``` + +При одинаковых `a` и `io` входных данных `f` даёт одинаковое `(result, io')`. Это форма подстановочного рассуждения в стиле денотационного проектирования, индексированная контекстом. + +## Почему так RT становится понятнее {#why-this-clarifies-rt} + +Во многих спорах о RT смешиваются полезные различия: + +* семантическая прозрачность +* операционные побочные эффекты + +Денотационное проектирование разделяет эти слои: + +* семантическое ядро задаёт смысл +* интерпретаторы реализуют стратегию выполнения + +Такое разделение позволяет использовать практические эффекты, сохраняя рассуждения на основе законов. + +## Сбой проектирования от представления {#representation-first-failure-mode} + +Если рано зафиксировать конкретное представление, обсуждение RT уходит в споры о стиле: + +* «этот стиль чистый» +* «тот стиль нечистый» +* «обёртки IO всё исправляют» + +В основном это споры о кодировании. Денотационное проектирование задаёт более простой вопрос: какие равенства верны в вашей спецификации? + +## Практический паттерн денотационного проектирования {#practical-dd-pattern} + +Определите небольшие трейты возможностей и опишите поведение программы как расширения поверх них. Затем предоставьте тонкие конкретные интерпретаторы. + +```rust,noplayground +trait FileSystem { + type Error; + + fn file_read(&self, name: &str) -> Result; +} + +trait GithubPublish { + type Error; + + fn github_publish(&self, repo: &str, files: Vec) -> Result<(), Self::Error>; +} + +trait Concurrent { + fn map_concurrent(&self, xs: &[A], f: F) -> Result, E> + where + A: Clone, + F: Fn(&A) -> Result; +} + +#[ext(name = PublishProjectExt)] +impl This +where + This: FileSystem + GithubPublish + Concurrent, +{ + fn publish_project(&self, files: &[&str], repo: &str) -> Result<(), String> { + let files = self.map_concurrent(files, |name| self.file_read(*name))?; + self.github_publish(repo, files) + } +} +``` + +`#[ext(...)]` — макрос из крейта [`extend`crate](https://docs.rs/extend/latest/extend/), который уменьшает шаблонный код, генерируя методы-расширения из блока `impl`; это не новая возможность языка Rust. + +В функциональном программировании на Scala RT часто объясняют через значения типа `F[A]` (например, `IO[A]` или `F[Either[E, A]]`). Здесь RT выражена на уровень выше — как смысл программы, заданный через возможности. Поэтому этот метод Rust не является контейнером значений RT в том же смысле кодирования, что и `F[A]`; это поведение с RT, заданное через явные возможности, а конкретные эффекты делегируются реализациям. + +Расширение формулирует семантическое поведение через возможности. Конкретные реализации выбирают стратегию выполнения: пакетную обработку, повторы, транспорт, параллелизм и детали хранения. + +## Заключительная мысль {#final-insight} + +В денотационном проектировании RT — свойство семантических спецификаций. Выбор реализации вторичен, если он сохраняет сформулированные денотационные законы. + +Сохраняйте закон. Не зацикливайтесь на ярлыке. diff --git a/src/insights/referential-transparency.uk.md b/src/insights/referential-transparency.uk.md new file mode 100644 index 0000000..eaf0a36 --- /dev/null +++ b/src/insights/referential-transparency.uk.md @@ -0,0 +1,118 @@ + + +# Референційна прозорість: новий погляд {#referential-transparency-reloaded} + +```admonish tip title="Пов’язані матеріали" +Семантичний погляд: [Денотації та композиційність](../denotational-design/denotations.md), [Закони та інтерпретації](../denotational-design/laws-and-interpretations.md) +Проєктування від значення в Rust: [Алгебри можливостей](../rust-dd/capability-algebras.md), [Похідне значення та композиція](../rust-dd/derived-meaning.md) +Поняття: [Референційна прозорість](../concepts/referential_transparency.md) +``` + +На цій сторінці розглядається денотаційне тлумачення *референційної прозорості*. На сторінці поняття наведено історію та вживання у поширених мовах. Тут зосереджуємося на тому, що RT означає як проєктне обмеження. + +У денотаційному проєктуванні RT — це не мітка чистоти. Це закон для денотацій: підстановка має зберігати специфіковане значення. + +## Повторне формулювання RT у денотаційному проєктуванні {#denotational-design-restatement-of-rt} + +Денотаційне проєктування повторно формулює RT як вимогу до специфікацій, а не стилю реалізації. Спершу специфікація має визначити композиційне значення, а стратегію виконання вибирають пізніше. + +Отже, RT перевіряють на семантичній межі: + +* ті самі вхідні дані +* той самий заявлений контекст +* та сама денотація + +Якщо ці умови виконано, підстановка коректна й доступне рівняннєве міркування. Це залишається правильним, навіть якщо конкретні інтерпретатори виконують ввід-вивід, паралельну роботу, повторні спроби чи переходи станів, адже ці деталі делегуються за межі заявлених можливостей. + +Інакше кажучи, денотаційне проєктування не запитує: «чи чиста ця реалізація?» Воно запитує: «чи явні денотаційні рівності та чи зберігають їх інтерпретатори?» + +## Чистота й RT {#purity-and-rt} + +RT і чистота пов’язані, але не тотожні. + +* **RT** — це закон підстановки значень. +* **Чистота** — це операційне обмеження: жодних прихованих спостережуваних ефектів. + +Чистота — поширений спосіб досягти RT у виразах. Але RT залишається семантичним критерієм: підстановка має зберігати специфіковану денотацію. + +Тому денотаційне проєктування не перетворює RT на стильову мітку на кшталт «лише чистий код». Вимога полягає в явних семантичних рівностях та ізоляції ефектів за межами можливостей. + +Одне мінімальне семантичне тлумачення: + +```rust,noplayground +fn f(a: A, io: Io) -> (Result, Io) +``` + +Для тих самих вхідних значень `a` та `io`, `f` повертає те саме `(result, io')`. Це форма міркування про підстановку в стилі денотаційного проєктування, індексована контекстом. + +## Чому це прояснює RT {#why-this-clarifies-rt} + +У багатьох дискусіях про RT плутають важливе розрізнення: + +* семантична прозорість +* операційні побічні ефекти + +Денотаційне проєктування розділяє ці рівні: + +* семантичне ядро визначає значення +* інтерпретатори реалізують стратегію виконання + +Таке розділення дає змогу використовувати практичні ефекти й не втрачати міркування на основі законів. + +## Помилка проєктування, що виходить із представлення {#representation-first-failure-mode} + +Якщо зарано вибрати конкретне представлення, обговорення RT переходить у суперечки про стиль: + +* «цей стиль чистий» +* «той стиль нечистий» +* «обгортки IO все виправляють» + +Здебільшого це суперечки про кодування. Денотаційне проєктування ставить простіше запитання: які рівності є коректними у вашій специфікації? + +## Практичний підхід денотаційного проєктування {#practical-dd-pattern} + +Визначте невеликі трейти можливостей і запишіть поведінку програм як розширення над ними. Потім надайте тонкі конкретні інтерпретатори. + +```rust,noplayground +trait FileSystem { + type Error; + + fn file_read(&self, name: &str) -> Result; +} + +trait GithubPublish { + type Error; + + fn github_publish(&self, repo: &str, files: Vec) -> Result<(), Self::Error>; +} + +trait Concurrent { + fn map_concurrent(&self, xs: &[A], f: F) -> Result, E> + where + A: Clone, + F: Fn(&A) -> Result; +} + +#[ext(name = PublishProjectExt)] +impl This +where + This: FileSystem + GithubPublish + Concurrent, +{ + fn publish_project(&self, files: &[&str], repo: &str) -> Result<(), String> { + let files = self.map_concurrent(files, |name| self.file_read(*name))?; + self.github_publish(repo, files) + } +} +``` + +`#[ext(...)]` — це макрос із крейту [`extend`](https://docs.rs/extend/latest/extend/), який скорочує шаблонний код, генеруючи методи-розширення з блоку `impl`. Це не нова функція мови Rust. + +У функційному програмуванні на Scala RT часто пояснюють через значення типу `F[A]` (наприклад, `IO[A]` чи `F[Either[E, A]]`). Тут RT виражено на рівень вище — як значення програми, обмежене можливостями. Тому цей метод Rust — не контейнер значень RT у тому самому сенсі кодування, що й `F[A]`; це поведінка RT, специфікована через явні можливості, а конкретні ефекти делеговані реалізаціям. + +Розширення визначає семантичну поведінку через можливості. Конкретні реалізації вибирають стратегію виконання: пакетну обробку, повторні спроби, транспорт, паралелізм і деталі сховища. + +## Головне осяяння {#final-insight} + +У денотаційному проєктуванні RT — це властивість семантичних специфікацій. Рішення щодо реалізації другорядні, якщо зберігають задані денотаційні закони. + +Зберігайте закон. Не застрягайте на мітці. diff --git a/src/insights/referential-transparency.vi.md b/src/insights/referential-transparency.vi.md new file mode 100644 index 0000000..6e24f7c --- /dev/null +++ b/src/insights/referential-transparency.vi.md @@ -0,0 +1,118 @@ + + +# Nhìn lại tính minh bạch tham chiếu {#referential-transparency-reloaded} + +```admonish tip title="Liên quan" +Góc nhìn ngữ nghĩa: [Ngữ nghĩa và tính hợp thành](../denotational-design/denotations.md), [Định luật và cách diễn giải](../denotational-design/laws-and-interpretations.md) +Thiết kế theo ngữ nghĩa trong Rust: [Các đại số năng lực](../rust-dd/capability-algebras.md), [Ý nghĩa suy ra và phép hợp thành](../rust-dd/derived-meaning.md) +Khái niệm: [Tính minh bạch tham chiếu](../concepts/referential_transparency.md) +``` + +Trang này trình bày cách diễn giải tính minh bạch tham chiếu theo Thiết kế theo ngữ nghĩa.Trang khái niệm đề cập lịch sử và cách dùng phổ biến trong các ngôn ngữ.Ở đây ta tập trung vào ý nghĩa của RT như một ràng buộc thiết kế. + +Trong DD, RT không phải nhãn chỉ tính thuần. Đó là định luật về ngữ nghĩa chỉ định: phép thế phải bảo toàn ý nghĩa được đặc tả. + +## Cách diễn đạt lại RT theo Thiết kế theo ngữ nghĩa {#denotational-design-restatement-of-rt} + +Thiết kế theo ngữ nghĩa diễn đạt lại RT thành yêu cầu dành cho đặc tả, không phải phong cách triển khai. Trước hết, đặc tả phải định nghĩa ý nghĩa hợp thành; chiến lược thực thi được chọn sau. + +Vì vậy, RT được kiểm tra tại ranh giới ngữ nghĩa: + +* cùng đầu vào +* cùng ngữ cảnh đã khai báo +* cùng ngữ nghĩa chỉ định + +Nếu những điều này được giữ nguyên, phép thế hợp lệ và có thể lập luận bằng phương trình. Điều này vẫn đúng ngay cả khi các bộ diễn giải cụ thể thực hiện IO, đồng thời, thử lại hoặc chuyển trạng thái, vì các chi tiết đó được ủy quyền phía sau ranh giới năng lực đã đặc tả. + +Nói cách khác, DD không hỏi “cách triển khai này có thuần không?” DD hỏi “các đẳng thức ngữ nghĩa chỉ định có tường minh không, và các bộ diễn giải có bảo toàn chúng không?” + +## Tính thuần và RT {#purity-and-rt} + +RT và tính thuần có liên quan nhưng không đồng nhất. + +* **RT** là định luật phép thế về ý nghĩa. +* **Tính thuần** là ràng buộc vận hành: không có hiệu ứng quan sát được bị che giấu. + +Tính thuần là cách phổ biến để có RT ở cấp biểu thức. Nhưng RT vẫn là tiêu chí ngữ nghĩa: phép thế phải bảo toàn ngữ nghĩa chỉ định được đặc tả. + +Vì vậy, DD tránh biến RT thành nhãn phong cách như “chỉ dùng mã thuần”. Yêu cầu là các đẳng thức ngữ nghĩa tường minh, với hiệu ứng được cô lập phía sau ranh giới năng lực. + +Một cách đọc ngữ nghĩa tối thiểu là: + +```rust,noplayground +fn f(a: A, io: Io) -> (Result, Io) +``` + +Với cùng đầu vào `a` và cùng đầu vào `io`, `f` tạo ra cùng `(result, io')`. Đây là dạng lập luận phép thế theo ngữ cảnh, có đánh chỉ mục, theo phong cách DD. + +## Vì sao cách này làm rõ RT {#why-this-clarifies-rt} + +Nhiều tranh luận về RT làm mờ một khác biệt hữu ích: + +* tính minh bạch ngữ nghĩa +* hiệu ứng phụ vận hành + +DD tách biệt các lớp này: + +* lõi ngữ nghĩa nêu ý nghĩa +* bộ diễn giải hiện thực hóa chiến lược thực thi + +Sự phân tách này cho phép hiệu ứng thực tiễn mà không làm mất khả năng lập luận dựa trên định luật. + +## Kiểu thất bại của thiết kế ưu tiên biểu diễn {#representation-first-failure-mode} + +Nếu cam kết với cách biểu diễn cụ thể quá sớm, thảo luận RT sẽ trôi sang tranh luận phong cách: + +* “phong cách này thuần” +* “phong cách kia không thuần” +* “lớp bọc IO giải quyết được” + +Phần lớn đây chỉ là tranh luận về cách mã hóa. DD hỏi câu đơn giản hơn: đặc tả của bạn cho phép những đẳng thức nào? + +## Mẫu DD thực tiễn {#practical-dd-pattern} + +Định nghĩa các đặc trưng năng lực nhỏ và viết hành vi chương trình thành phần mở rộng dựa trên chúng. Sau đó cung cấp các bộ diễn giải cụ thể mỏng. + +```rust,noplayground +trait FileSystem { + type Error; + + fn file_read(&self, name: &str) -> Result; +} + +trait GithubPublish { + type Error; + + fn github_publish(&self, repo: &str, files: Vec) -> Result<(), Self::Error>; +} + +trait Concurrent { + fn map_concurrent(&self, xs: &[A], f: F) -> Result, E> + where + A: Clone, + F: Fn(&A) -> Result; +} + +#[ext(name = PublishProjectExt)] +impl This +where + This: FileSystem + GithubPublish + Concurrent, +{ + fn publish_project(&self, files: &[&str], repo: &str) -> Result<(), String> { + let files = self.map_concurrent(files, |name| self.file_read(*name))?; + self.github_publish(repo, files) + } +} +``` + +`#[ext(...)]` là macro từ crate [`extend`](https://docs.rs/extend/latest/extend/), dùng để giảm mã khuôn mẫu bằng cách tạo phương thức mở rộng từ khối `impl`; đây không phải tính năng mới của ngôn ngữ Rust. + +Trong FP Scala, RT thường được trình bày qua các giá trị kiểu `F[A]` (ví dụ `IO[A]` hoặc `F[Either[E, A]]`). Ở đây, RT được biểu đạt ở cấp cao hơn: như ý nghĩa chương trình bị ràng buộc bởi năng lực. Vì vậy, phương thức Rust này không phải vùng chứa giá trị RT theo cùng nghĩa mã hóa như `F[A]`; đây là hành vi RT được đặc tả dựa trên các năng lực tường minh, còn hiệu ứng cụ thể được ủy quyền cho cách triển khai. + +Phần mở rộng phát biểu hành vi ngữ nghĩa dựa trên các năng lực. Cách triển khai cụ thể quyết định chiến lược thực thi: gom lô, thử lại, truyền tải, song song và chi tiết lưu trữ. + +## Nhận định cuối {#final-insight} + +Trong Thiết kế theo ngữ nghĩa, RT là thuộc tính của đặc tả ngữ nghĩa. Lựa chọn triển khai là thứ yếu miễn là chúng bảo toàn các định luật ngữ nghĩa chỉ định đã nêu. + +Giữ lại định luật. Đừng mắc kẹt ở nhãn gọi. diff --git a/src/insights/referential-transparency.zh-hant.md b/src/insights/referential-transparency.zh-hant.md new file mode 100644 index 0000000..c50962b --- /dev/null +++ b/src/insights/referential-transparency.zh-hant.md @@ -0,0 +1,118 @@ + + +# 重新審視引用透明性 {#referential-transparency-reloaded} + +```admonish tip title="相關內容" +語義視角:[指稱與組合性](../denotational-design/denotations.md)、[定律與解釋](../denotational-design/laws-and-interpretations.md) +Rust 中的語義驅動設計:[能力代數](../rust-dd/capability-algebras.md)、[派生含義與組合](../rust-dd/derived-meaning.md) +概念:[引用透明性](../concepts/referential_transparency.md) +``` + +本頁介紹*引用透明性*的指稱設計解讀。 概念頁討論其歷史與主流語言中的用法。 本頁重點說明 RT 作為設計約束時的含義。 + +在指稱設計中,RT 並非純性標籤。 它是關於指稱的一條定律:替換必須保留指定含義。 + +## 以指稱設計重新表述 RT {#denotational-design-restatement-of-rt} + +指稱設計將 RT 重新表述為規範要求,而非實作風格。 規範必須先定義可組合含義;之後才選擇執行策略。 + +因此,應在語義邊界檢查 RT: + +* 相同輸入 +* 相同的已宣告上下文 +* 相同指稱 + +若這些條件成立,替換就是有效的,並且可以進行等式推理。 即使具體直譯器執行 I/O、併發、重試或狀態轉換,這一點仍然成立,因為這些細節都委託給規範能力邊界之後的實現。 + +換言之,指稱設計不會問“這個實作是否純?”。 它會問“指稱等式是否明確?直譯器是否保留了這些等式?” + +## 純性與 RT {#purity-and-rt} + +RT 與純性相關,但並不相同。 + +* **RT**是關於含義的一條替換定律。 +* **純性**是一項操作約束:不存在隱藏的可觀察效應。 + +純性是表示式級程式碼實現 RT 的常見方式。 但 RT 仍是語義標準:替換必須保留指定指稱。 + +因此,指稱設計不會把 RT 變成“只能寫純程式碼”這樣的風格標籤。 它要求指稱等式明確,並將效應隔離在能力邊界之後。 + +一種最簡語義解讀是: + +```rust,noplayground +fn f(a: A, io: Io) -> (Result, Io) +``` + +對於相同的`a`和相同的`io`輸入,`f`會得出相同的`(result, io')`。 這是指稱設計中按上下文索引的替換推理形式。 + +## RT 為何因此更清晰 {#why-this-clarifies-rt} + +許多關於 RT 的爭論混淆了一項有用區別: + +* 語義透明性 +* 操作性副作用 + +指稱設計將這些層次分開: + +* 語義核心陳述含義 +* 直譯器實現執行策略 + +這種區分既允許實際效應存在,也不會失去基於定律的推理。 + +## 表示優先設計的失誤模式 {#representation-first-failure-mode} + +如果過早確定具體表示,關於 RT 的討論就會偏離到風格爭論: + +* “這種風格是純的” +* “那種風格不純” +* “用 IO 包裝器就能解決” + +這些大多隻是編碼方式之爭。 指稱設計提出了一個更簡單的問題: 你的規範中哪些等式有效? + +## 指稱設計的實用模式 {#practical-dd-pattern} + +定義小型能力 trait,並將程式行為寫成其上的擴充。 隨後提供輕量級具體直譯器。 + +```rust,noplayground +trait FileSystem { + type Error; + + fn file_read(&self, name: &str) -> Result; +} + +trait GithubPublish { + type Error; + + fn github_publish(&self, repo: &str, files: Vec) -> Result<(), Self::Error>; +} + +trait Concurrent { + fn map_concurrent(&self, xs: &[A], f: F) -> Result, E> + where + A: Clone, + F: Fn(&A) -> Result; +} + +#[ext(name = PublishProjectExt)] +impl This +where + This: FileSystem + GithubPublish + Concurrent, +{ + fn publish_project(&self, files: &[&str], repo: &str) -> Result<(), String> { + let files = self.map_concurrent(files, |name| self.file_read(*name))?; + self.github_publish(repo, files) + } +} +``` + +`#[ext(...)]`是來自[`extend`crate 的宏](https://docs.rs/extend/latest/extend/),用於從`impl`塊中生成擴充方法以減少樣板程式碼;它不是新的 Rust 語言特性。 + +在 Scala 函數語言程式設計中,RT 常透過`F[A]`型別的值來介紹(例如`IO[A]`或`F[Either[E, A]]`)。 這裡的 RT 被表達在更高一層:作為受能力約束的程式含義。 因此,這種 Rust 方法並非以與`F[A]`相同的編碼方式實作的 RT 值容器;它是在明確能力之上規範 RT 行為,並將具體效應委託給實作。 + +擴充依據能力陳述語義行為。 具體實作負責決定執行策略,例如批次處理、重試、傳輸、並行與儲存細節。 + +## 最終洞見 {#final-insight} + +在指稱設計中,RT 是語義規範的性質。 只要保留已陳述的指稱定律,實作選擇就是次要的。 + +保留定律。 不要困在標籤之爭裡。 diff --git a/src/insights/referential-transparency.zh.md b/src/insights/referential-transparency.zh.md new file mode 100644 index 0000000..0d97df9 --- /dev/null +++ b/src/insights/referential-transparency.zh.md @@ -0,0 +1,118 @@ + + +# 重新审视引用透明性 {#referential-transparency-reloaded} + +```admonish tip title="相关内容" +语义视角:[指称与组合性](../denotational-design/denotations.md)、[定律与解释](../denotational-design/laws-and-interpretations.md) +Rust 中的语义驱动设计:[能力代数](../rust-dd/capability-algebras.md)、[派生含义与组合](../rust-dd/derived-meaning.md) +概念:[引用透明性](../concepts/referential_transparency.md) +``` + +本页介绍*引用透明性*的指称设计解读。 概念页讨论其历史与主流语言中的用法。 本页重点说明 RT 作为设计约束时的含义。 + +在指称设计中,RT 并非纯性标签。 它是关于指称的一条定律:替换必须保留指定含义。 + +## 以指称设计重新表述 RT {#denotational-design-restatement-of-rt} + +指称设计将 RT 重新表述为规范要求,而非实现风格。 规范必须先定义可组合含义;之后才选择执行策略。 + +因此,应在语义边界检查 RT: + +* 相同输入 +* 相同的已声明上下文 +* 相同指称 + +若这些条件成立,替换就是有效的,并且可以进行等式推理。 即使具体解释器执行 I/O、并发、重试或状态转换,这一点仍然成立,因为这些细节都委托给规范能力边界之后的实现。 + +换言之,指称设计不会问“这个实现是否纯?”。 它会问“指称等式是否明确?解释器是否保留了这些等式?” + +## 纯性与 RT {#purity-and-rt} + +RT 与纯性相关,但并不相同。 + +* **RT**是关于含义的一条替换定律。 +* **纯性**是一项操作约束:不存在隐藏的可观察效应。 + +纯性是表达式级代码实现 RT 的常见方式。 但 RT 仍是语义标准:替换必须保留指定指称。 + +因此,指称设计不会把 RT 变成“只能写纯代码”这样的风格标签。 它要求指称等式明确,并将效应隔离在能力边界之后。 + +一种最简语义解读是: + +```rust,noplayground +fn f(a: A, io: Io) -> (Result, Io) +``` + +对于相同的`a`和相同的`io`输入,`f`会得出相同的`(result, io')`。 这是指称设计中按上下文索引的替换推理形式。 + +## RT 为何因此更清晰 {#why-this-clarifies-rt} + +许多关于 RT 的争论混淆了一项有用区别: + +* 语义透明性 +* 操作性副作用 + +指称设计将这些层次分开: + +* 语义核心陈述含义 +* 解释器实现执行策略 + +这种区分既允许实际效应存在,也不会失去基于定律的推理。 + +## 表示优先设计的失误模式 {#representation-first-failure-mode} + +如果过早确定具体表示,关于 RT 的讨论就会偏离到风格争论: + +* “这种风格是纯的” +* “那种风格不纯” +* “用 IO 包装器就能解决” + +这些大多只是编码方式之争。 指称设计提出了一个更简单的问题: 你的规范中哪些等式有效? + +## 指称设计的实用模式 {#practical-dd-pattern} + +定义小型能力 trait,并将程序行为写成其上的扩展。 随后提供轻量级具体解释器。 + +```rust,noplayground +trait FileSystem { + type Error; + + fn file_read(&self, name: &str) -> Result; +} + +trait GithubPublish { + type Error; + + fn github_publish(&self, repo: &str, files: Vec) -> Result<(), Self::Error>; +} + +trait Concurrent { + fn map_concurrent(&self, xs: &[A], f: F) -> Result, E> + where + A: Clone, + F: Fn(&A) -> Result; +} + +#[ext(name = PublishProjectExt)] +impl This +where + This: FileSystem + GithubPublish + Concurrent, +{ + fn publish_project(&self, files: &[&str], repo: &str) -> Result<(), String> { + let files = self.map_concurrent(files, |name| self.file_read(*name))?; + self.github_publish(repo, files) + } +} +``` + +`#[ext(...)]`是来自[`extend`crate 的宏](https://docs.rs/extend/latest/extend/),用于从`impl`块中生成扩展方法以减少样板代码;它不是新的 Rust 语言特性。 + +在 Scala 函数式编程中,RT 常通过`F[A]`类型的值来介绍(例如`IO[A]`或`F[Either[E, A]]`)。 这里的 RT 被表达在更高一层:作为受能力约束的程序含义。 因此,这种 Rust 方法并非以与`F[A]`相同的编码方式实现的 RT 值容器;它是在明确能力之上规范 RT 行为,并将具体效应委托给实现。 + +扩展依据能力陈述语义行为。 具体实现负责决定执行策略,例如批处理、重试、传输、并行与存储细节。 + +## 最终洞见 {#final-insight} + +在指称设计中,RT 是语义规范的性质。 只要保留已陈述的指称定律,实现选择就是次要的。 + +保留定律。 不要困在标签之争里。 diff --git a/src/rust-dd/capability-algebras.ar.md b/src/rust-dd/capability-algebras.ar.md new file mode 100644 index 0000000..c89c49b --- /dev/null +++ b/src/rust-dd/capability-algebras.ar.md @@ -0,0 +1,184 @@ + + +# جبر القدرات {#capability-algebras} + +![Design by meaning in Rust — building software from small capability traits](../assets/design-by-meaning-rust.png) + +```admonish tip title="ذات صلة" +المنظور الدلالي: [التصميم الدلالي (Denotational Design)](../denotational-design/design.md)، [الدلالات والتركيبية](../denotational-design/denotations.md) +التصميم انطلاقًا من المعنى في Rust: [الأنواع الدلالية في Rust](semantic-types.md)، [المعنى المشتق والتركيب](derived-meaning.md) +المفاهيم: [Expression Problem](../concepts/expression-problem.md)، [التشعب والتلاقي](../concepts/branching.md) +``` + +```admonish note title="تمهيد" +سمة القدرة جبر صغير: تسمي الملاحظات والتحويلات الأولية التي يتطلبها معنى ما، وتترك التمثيل للمفسر. صمّم المفردات انطلاقًا من المعنى، لا من الحقول التي يصادف أن يحتفظ بها أول تنفيذ. +``` + +لا تتضمن Rust بنية مدمجة باسم «التصميم الدلالي». نرّمز المفردات الدلالية باستخدام ميزات اللغة العادية. والسمات الصغيرة للقدرات إحدى الترميزات المفيدة. + +تعني اللاحقة `Alg` في هذا الكتاب **جبرًا**: مجموعة متماسكة من العمليات الأولية على حوامل يختارها المفسر. + +## ابدأ بالمعنى {#start-from-meaning} + +يمكن التعبير عن معنى موضع الفرع من الجزء السابق هكذا: + +```rust,noplayground +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub enum Direction { + Left, + Right, +} + +pub trait BranchAlg { + type Branch; + + fn branch_root(&self) -> Self::Branch; + fn branch_grow(&self, branch: &Self::Branch, direction: Direction) -> Self::Branch; + fn branch_path(&self, ancestor: &Self::Branch, descendant: &Self::Branch) -> Option>; +} +``` + +تصرّح السمة بثلاثة معانٍ أولية: + +* إنشاء الجذر +* تمديد فرع في اتجاه واحد +* ملاحظة المسار النسبي عند وجوده + +ولا تكشف موضع تخزين الفروع أو طريقة ترميز المسارات. + +## القدرات ليست إسقاطات للحقول {#capabilities-are-not-field-projections} + +````admonish warning title="إسقاطات الحقول ليست قدرات دلالية" +قارن: + +```rust,noplayground +trait BranchContext { + fn branches(&self) -> &Vec>; + fn branches_mut(&mut self) -> &mut Vec>; +} +``` + +تخفي هذه السمة بنيةً خلف الأساليب، لكنها تظل تكشف تمثيلها. فيرتبط أي منطق مشتق بالمتجهات والقيم المنطقية والملكية واستراتيجية التعديل. +```` + +تكشف القدرة الدلالية الملاحظة أو التحويل الذي يتطلبه المعنى اللاحق. اسأل: + +```admonish question title="ما الذي ينبغي سؤاله عن كل قدرة" +لو استخدم التنفيذ قاعدة بيانات أو حدًا رمزيًا أو عددًا صحيحًا مدمجًا أو خدمة بعيدة، فهل تظل هذه العملية ذات معنى؟ +``` + +إن كان الجواب نعم، فقد تنتمي العملية إلى القدرة. أما إذا احتاج المستدعون إلى تخطيط الحقول الحالي، فالأرجح أنها لا تنتمي إليها. + +## معنى أولي واحد لكل سمة {#one-primitive-meaning-per-trait} + +تُظهر السمات الصغيرة التبعيات: + +```rust,noplayground +pub trait ClockAlg { + type Instant; + + fn clock_now(&self) -> Self::Instant; +} + +pub trait DeadlineAlg { + fn deadline_expired(&self, now: &Instant) -> bool; +} +``` + +يمكن لعملية مشتقة تحتاج إلى الوقت والموعد النهائي أن تتطلب السمتين معًا. ولا تحتاج إلى `ApplicationContext` يجمع التسجيل والتخزين والشبكات والإعداد والجدولة. + +لا يعني «صغير» الاقتصار آليًا على أسلوب واحد. اجمع العمليات عندما تكوّن بنية دلالية واحدة لا تنفصل. وافصلها عندما تعبّر عن معانٍ مستقلة أو تقبل مفسرات مستقلة. + +## تختار الأنواع المرتبطة الحوامل {#associated-types-select-carriers} + +استخدم الأنواع المرتبطة عندما يختار المفسر التمثيل: + +```rust,noplayground +pub trait SourceAlg { + type Source; + type Error; + + fn source_read(&self, name: &str) -> Result; +} +``` + +لا تشترط `String` أو `std::io::Error` أو شجرة صياغة ملموسة، إلا إذا كانت مفردات دلالية مستقرة عند هذا الحد. + +وعلى العكس، القيم الدلالية الملموسة مقبولة: + +```rust,noplayground +pub enum Severity { + Warning, + Error, +} +``` + +القاعدة ليست «اجعل كل نوع مجردًا»، بل «لا تخلط آليات المفسر بالمفردات الدلالية». + +## ضع الحدود حيث تُستخدم {#put-bounds-where-they-are-used} + +أبقِ العملية الأولية خالية من القيود التي لا تحتاجها: + +```rust,noplayground +pub trait CandidateAlg { + type Candidate; + + fn candidates(&self) -> impl Iterator; +} +``` + +````admonish warning title="لا تضف حدودًا استباقية" +لا تقيّد النوع المرتبط لمجرد أن خوارزمية مستقبلية قد تحتاج إليه: + +```rust,noplayground +pub trait CandidateAlg { + // not recommended: every interpreter now pays for bounds + // most operations never use + type Candidate: Clone + Ord + Hash + Send + Sync; + + fn candidates(&self) -> impl Iterator; +} +``` + +قد تتطلب عملية ترتيب المرشحين `Ord`، بينما قد تتطلب عملية وضعهم في مجموعة تجزئة `Hash`. +```` + +تحافظ الحدود عند موضع الاستخدام على قابلية إعادة استخدام المعاني الأولية، وتكشف العقد الحقيقي للسلوك المشتق. + +## قد تكون الآثار معنى أوليًا {#effects-can-be-primitive-meaning} + +لا تستلزم سمات القدرات تنفيذًا نقيًا: + +```rust,noplayground +pub trait PublishAlg { + type Document; + type Error; + + async fn publish(&self, document: Self::Document) -> Result<(), Self::Error>; +} +``` + +النشر أثر جانبي، لكنه قد يظل عملية دلالية أولية عند الحد الحالي. وقد يستخدم المفسر الملموس HTTP أو قائمة انتظار أو ملفًا أو مخزنًا مؤقتًا للاختبار. + +ينبغي ألا تفرض الطبقة الدلالية إعادة المحاولة أو ملكية المقبس أو إطلاق المهام أو مجمعات الاتصالات إلا إذا كانت تلك الفروق جزءًا من المعنى المقصود. + +## تسمية الحد {#naming-the-boundary} + +صُغ القدرات من المنظور الدلالي للمستهلك: + +| متمحور حول المعنى | متمحور حول التمثيل | +| --- | --- | +| `closed_outcome(slot)` | `get_runtime_map(slot)` | +| `source_read(name)` | `compiler_context().sources().lookup(name)` | +| `branch_path(ancestor, descendant)` | `raw_branch_bits(id)` | + +التسمية جزء من التصميم. والاسم الآلي يدعو إلى ارتباط آلي. + +## فحوص المراجعة {#review-checks} + +* هل تكشف السمة عن معنى أولي واحد متماسك؟ +* هل يستطيع مفسر مستقل تنفيذها دون نسخ التمثيل الأول؟ +* هل تكون الأنواع المرتبطة مجردة فقط حيث يختارها المفسر فعلًا؟ +* هل الأنواع الملموسة مفردات دلالية مستقرة؟ +* هل تبقى الحدود غائبة حتى تستخدمها عملية؟ +* هل تتجنب السمة إرجاع المديرين والسياقات والتخزين الخام؟ diff --git a/src/rust-dd/capability-algebras.de.md b/src/rust-dd/capability-algebras.de.md new file mode 100644 index 0000000..b4c60e7 --- /dev/null +++ b/src/rust-dd/capability-algebras.de.md @@ -0,0 +1,184 @@ + + +# Capability-Algebren {#capability-algebras} + +![Design by meaning in Rust — building software from small capability traits](../assets/design-by-meaning-rust.png) + +```admonish tip title="Verwandte Themen" +The Semantic View: [Denotational Design](../denotational-design/design.md), [Denotationen und Kompositionalität](../denotational-design/denotations.md) +Design by Meaning in Rust: [Semantische Typen in Rust](semantic-types.md), [Abgeleitete Bedeutung und Komposition](derived-meaning.md) +Concepts: [Expression Problem](../concepts/expression-problem.md), [Verzweigung und Konfluenz](../concepts/branching.md) +``` + +```admonish note title="Orientierung" +Ein Capability-Trait ist eine kleine Algebra: Es benennt die primitiven Beobachtungen und Transformationen, die eine Bedeutung erfordert, und überlässt die Repräsentation dem Interpreter. Das Vokabular wird aus der Bedeutung abgeleitet, nicht aus den Feldern, die eine erste Implementierung zufällig enthält. +``` + +Rust bietet kein eingebautes Konstrukt namens „Denotational Design“. Semantische Vokabulare kodieren wir mit gewöhnlichen Sprachmitteln. Kleine Capability-Traits sind eine nützliche Kodierung. + +Das Suffix `Alg` bedeutet in diesem Buch **Algebra**: eine zusammenhängende Menge primitiver Operationen über vom Interpreter gewählten Trägern. + +## Bei der Bedeutung beginnen {#start-from-meaning} + +Die Bedeutung der Verzweigungspositionen aus dem vorherigen Teil lässt sich so ausdrücken: + +```rust,noplayground +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub enum Direction { + Left, + Right, +} + +pub trait BranchAlg { + type Branch; + + fn branch_root(&self) -> Self::Branch; + fn branch_grow(&self, branch: &Self::Branch, direction: Direction) -> Self::Branch; + fn branch_path(&self, ancestor: &Self::Branch, descendant: &Self::Branch) -> Option>; +} +``` + +Das Trait formuliert drei primitive Bedeutungen: + +* die Wurzel konstruieren +* einen Zweig in eine Richtung erweitern +* den relativen Pfad beobachten, sofern er existiert + +Es legt weder offen, wo Zweige gespeichert werden, noch wie Pfade kodiert sind. + +## Capabilities sind keine Feldprojektionen {#capabilities-are-not-field-projections} + +````admonish warning title="Feldprojektionen sind keine semantischen Capabilities" +Vergleiche: + +```rust,noplayground +trait BranchContext { + fn branches(&self) -> &Vec>; + fn branches_mut(&mut self) -> &mut Vec>; +} +``` + +Dieses Trait verbirgt eine Struktur hinter Methoden, legt ihre Repräsentation aber weiterhin offen. Abgeleitete Logik wird dadurch an Vektoren, Booleans, Besitzverhältnisse und die Mutationsstrategie gekoppelt. +```` + +Eine semantische Capability stellt die Beobachtung oder Transformation bereit, die die nachgelagerte Bedeutung erfordert. Frage dich: + +```admonish question title="Zu jeder Capability fragen" +Wäre diese Operation noch sinnvoll, wenn die Implementierung eine Datenbank, einen symbolischen Term, eine kompakte Ganzzahl oder einen entfernten Dienst verwendete? +``` + +Falls ja, könnte die Operation zur Capability gehören. Benötigen Aufrufer hingegen das aktuelle Feldlayout, gehört sie wahrscheinlich nicht dazu. + +## Eine primitive Bedeutung pro Trait {#one-primitive-meaning-per-trait} + +Kleine Traits machen Abhängigkeiten sichtbar: + +```rust,noplayground +pub trait ClockAlg { + type Instant; + + fn clock_now(&self) -> Self::Instant; +} + +pub trait DeadlineAlg { + fn deadline_expired(&self, now: &Instant) -> bool; +} +``` + +Eine abgeleitete Operation, die Zeit und eine Frist benötigt, kann beide Traits voraussetzen. Sie benötigt kein `ApplicationContext` mit Protokollierung, Speicher, Netzwerkzugriff, Konfiguration und Ablaufplanung. + +„Klein“ bedeutet nicht mechanisch genau eine Methode. Fasse Operationen zusammen, wenn sie eine untrennbare semantische Struktur bilden. Teile sie auf, wenn sie unabhängige Bedeutungen ausdrücken oder unabhängig interpretiert werden können. + +## Assoziierte Typen wählen Träger {#associated-types-select-carriers} + +Verwende assoziierte Typen, wenn der Interpreter die Repräsentation auswählt: + +```rust,noplayground +pub trait SourceAlg { + type Source; + type Error; + + fn source_read(&self, name: &str) -> Result; +} +``` + +Verlange weder `String` noch `std::io::Error` oder einen konkreten Syntaxbaum, es sei denn, sie gehören an dieser Grenze zum stabilen semantischen Vokabular. + +Konkrete semantische Werte sind dagegen willkommen: + +```rust,noplayground +pub enum Severity { + Warning, + Error, +} +``` + +Die Regel lautet nicht: „Mache jeden Typ abstrakt.“ Sie lautet: „Verwechsle Interpretermechanik nicht mit semantischem Vokabular.“ + +## Bounds dort platzieren, wo sie gebraucht werden {#put-bounds-where-they-are-used} + +Halte primitive Operationen frei von nicht benötigten Einschränkungen: + +```rust,noplayground +pub trait CandidateAlg { + type Candidate; + + fn candidates(&self) -> impl Iterator; +} +``` + +````admonish warning title="Keine vorsorglichen Bounds hinzufügen" +Beschränke den assoziierten Typ nicht nur deshalb, weil ein möglicher zukünftiger Algorithmus diese Einschränkung brauchen könnte: + +```rust,noplayground +pub trait CandidateAlg { + // not recommended: every interpreter now pays for bounds + // most operations never use + type Candidate: Clone + Ord + Hash + Send + Sync; + + fn candidates(&self) -> impl Iterator; +} +``` + +Die Operation zum Sortieren von Kandidaten kann `Ord` voraussetzen; die Operation, die sie in eine Hash-Menge einfügt, kann `Hash` voraussetzen. +```` + +Bounds am Verwendungsort halten primitive Bedeutungen wiederverwendbar und machen den tatsächlichen Vertrag abgeleiteten Verhaltens sichtbar. + +## Effekte können primitive Bedeutungen sein {#effects-can-be-primitive-meaning} + +Capability-Traits setzen keine reine Ausführung voraus: + +```rust,noplayground +pub trait PublishAlg { + type Document; + type Error; + + async fn publish(&self, document: Self::Document) -> Result<(), Self::Error>; +} +``` + +Veröffentlichen ist ein Effekt. An der aktuellen Grenze kann es dennoch eine primitive semantische Operation sein. Der konkrete Interpreter kann HTTP, eine Warteschlange, eine Datei oder einen Testpuffer verwenden. + +Die semantische Ebene sollte weder Wiederholungsversuche noch Socket-Besitz, das Starten von Tasks oder Verbindungspools vorschreiben, sofern diese Unterschiede nicht zur beabsichtigten Bedeutung gehören. + +## Die Grenze benennen {#naming-the-boundary} + +Capabilities sollten aus der semantischen Sicht des Nutzers formuliert werden: + +| Bedeutungsorientiert | Repräsentationsorientiert | +| --- | --- | +| `closed_outcome(slot)` | `get_runtime_map(slot)` | +| `source_read(name)` | `compiler_context().sources().lookup(name)` | +| `branch_path(ancestor, descendant)` | `raw_branch_bits(id)` | + +Benennung ist Entwurf. Ein mechanischer Name lädt zu mechanischer Kopplung ein. + +## Prüfpunkte für das Review {#review-checks} + +* Legt das Trait eine zusammenhängende primitive Bedeutung offen? +* Könnte ein unabhängiger Interpreter es implementieren, ohne die erste Repräsentation zu kopieren? +* Sind assoziierte Typen nur dort abstrakt, wo der Interpreter tatsächlich eine Wahl trifft? +* Sind konkrete Typen stabiles semantisches Vokabular? +* Fehlen Bounds, bis eine Operation sie benötigt? +* Vermeidet das Trait die Rückgabe von Managern, Kontexten und unverarbeitetem Speicher? diff --git a/src/rust-dd/capability-algebras.es.md b/src/rust-dd/capability-algebras.es.md new file mode 100644 index 0000000..db65234 --- /dev/null +++ b/src/rust-dd/capability-algebras.es.md @@ -0,0 +1,184 @@ + + +# Álgebras de capacidades {#capability-algebras} + +![Design by meaning in Rust — building software from small capability traits](../assets/design-by-meaning-rust.png) + +```admonish tip title="Relacionado" +La perspectiva semántica: [Diseño denotacional](../denotational-design/design.md), [Denotaciones y composicionalidad](../denotational-design/denotations.md) +Diseño por significado en Rust: [Tipos semánticos en Rust](semantic-types.md), [Significado derivado y composición](derived-meaning.md) +Conceptos: [Bài toán expresión](../concepts/expression-problem.md), [Ramificación y confluencia](../concepts/branching.md) +``` + +```admonish note title="Orientación" +Un trait de capacidad es un álgebra pequeña: nombra las observaciones y transformaciones primitivas que requiere un significado y deja la representación en manos del intérprete. Diseña el vocabulario desde el significado, no desde los campos que casualmente guarda la primera implementación. +``` + +Rust no tiene una construcción integrada llamada «Diseño denotacional». Codificamos vocabularios semánticos con funciones ordinarias del lenguaje. Los traits de capacidad pequeños son una codificación útil. + +El sufijo `Alg` en este libro significa **álgebra**: un conjunto coherente de operaciones primitivas sobre portadores elegidos por el intérprete. + +## Empieza por el significado {#start-from-meaning} + +El significado de posición de ramificación de la parte anterior puede expresarse así: + +```rust,noplayground +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub enum Direction { + Left, + Right, +} + +pub trait BranchAlg { + type Branch; + + fn branch_root(&self) -> Self::Branch; + fn branch_grow(&self, branch: &Self::Branch, direction: Direction) -> Self::Branch; + fn branch_path(&self, ancestor: &Self::Branch, descendant: &Self::Branch) -> Option>; +} +``` + +El trait expresa tres significados primitivos: + +* construir la posición raíz +* extender una rama en una dirección +* observar el camino relativo cuando exista + +No revela dónde se almacenan las ramas ni cómo se codifican los caminos. + +## Las capacidades no son proyecciones de campos {#capabilities-are-not-field-projections} + +````admonish warning title="Las proyecciones de campos no son capacidades semánticas" +Compara: + +```rust,noplayground +trait BranchContext { + fn branches(&self) -> &Vec>; + fn branches_mut(&mut self) -> &mut Vec>; +} +``` + +Este trait oculta una estructura detrás de métodos, pero sigue exponiendo su representación. Cualquier lógica derivada queda acoplada a vectores, booleanos, propiedad y estrategia de mutación. +```` + +Una capacidad semántica expone la observación o transformación que requiere el significado posterior. Pregunta: + +```admonish question title="Qué preguntar sobre cada capacidad" +Si la implementación usara una base de datos, un término simbólico, un entero compacto o un servicio remoto, ¿seguiría teniendo sentido esta operación? +``` + +Si la respuesta es sí, la operación puede pertenecer a la capacidad. Si los llamadores necesitan la disposición actual de los campos, probablemente no. + +## Un significado primitivo por trait {#one-primitive-meaning-per-trait} + +Los traits pequeños hacen visibles las dependencias: + +```rust,noplayground +pub trait ClockAlg { + type Instant; + + fn clock_now(&self) -> Self::Instant; +} + +pub trait DeadlineAlg { + fn deadline_expired(&self, now: &Instant) -> bool; +} +``` + +Una operación derivada que necesite la hora y una fecha límite puede exigir ambos traits. No necesita un `ApplicationContext` que reúna registro, almacenamiento, redes, configuración y planificación. + +«Pequeño» no significa limitar mecánicamente a un método. Agrupa operaciones cuando formen una estructura semántica inseparable. Sepáralas si expresan significados independientes o admiten intérpretes independientes. + +## Los tipos asociados eligen portadores {#associated-types-select-carriers} + +Usa tipos asociados cuando el intérprete elige la representación: + +```rust,noplayground +pub trait SourceAlg { + type Source; + type Error; + + fn source_read(&self, name: &str) -> Result; +} +``` + +No exijas `String`, `std::io::Error` ni un árbol de sintaxis concreto, salvo que formen parte de un vocabulario semántico estable en este límite. + +A la inversa, los valores semánticos concretos son perfectamente válidos: + +```rust,noplayground +pub enum Severity { + Warning, + Error, +} +``` + +La regla no es «haz abstractos todos los tipos», sino «no confundas los mecanismos del intérprete con el vocabulario semántico». + +## Coloca las restricciones donde se usan {#put-bounds-where-they-are-used} + +Mantén una primitiva libre de restricciones que no necesita: + +```rust,noplayground +pub trait CandidateAlg { + type Candidate; + + fn candidates(&self) -> impl Iterator; +} +``` + +````admonish warning title="No añadas restricciones preventivas" +No restrinjas el tipo asociado solo porque un algoritmo futuro quizá lo necesite: + +```rust,noplayground +pub trait CandidateAlg { + // not recommended: every interpreter now pays for bounds + // most operations never use + type Candidate: Clone + Ord + Hash + Send + Sync; + + fn candidates(&self) -> impl Iterator; +} +``` + +La operación que ordena candidatos puede requerir `Ord`; la que los coloca en un conjunto hash puede requerir `Hash`. +```` + +Las restricciones en el sitio de uso mantienen reutilizables los significados primitivos y revelan el contrato real del comportamiento derivado. + +## Los efectos pueden ser significados primitivos {#effects-can-be-primitive-meaning} + +Los traits de capacidad no implican ejecución pura: + +```rust,noplayground +pub trait PublishAlg { + type Document; + type Error; + + async fn publish(&self, document: Self::Document) -> Result<(), Self::Error>; +} +``` + +Publicar es un efecto. Aun así, puede ser una operación semántica primitiva en el límite actual. El intérprete concreto puede usar HTTP, una cola, un archivo o un búfer de prueba. + +La capa semántica no debería prescribir reintentos, propiedad de sockets, creación de tareas o grupos de conexiones, a menos que esas distinciones formen parte del significado previsto. + +## Nombrar el límite {#naming-the-boundary} + +Las capacidades deben formularse desde la perspectiva semántica del consumidor: + +| Orientado al significado | Orientado a la representación | +| --- | --- | +| `closed_outcome(slot)` | `get_runtime_map(slot)` | +| `source_read(name)` | `compiler_context().sources().lookup(name)` | +| `branch_path(ancestor, descendant)` | `raw_branch_bits(id)` | + +Nombrar forma parte del diseño. Un nombre mecánico invita al acoplamiento mecánico. + +## Comprobaciones de revisión {#review-checks} + +* ¿El trait expone un significado primitivo coherente? +* ¿Podría implementarlo un intérprete independiente sin copiar la primera representación? +* ¿Los tipos asociados son abstractos solo cuando el intérprete realmente puede elegirlos? +* ¿Los tipos concretos forman un vocabulario semántico estable? +* ¿Las restricciones están ausentes hasta que una operación las utiliza? +* ¿El trait evita devolver gestores, contextos y almacenamiento sin procesar? diff --git a/src/rust-dd/capability-algebras.ja.md b/src/rust-dd/capability-algebras.ja.md new file mode 100644 index 0000000..ab71209 --- /dev/null +++ b/src/rust-dd/capability-algebras.ja.md @@ -0,0 +1,184 @@ + + +# ケイパビリティ代数 {#capability-algebras} + +![Design by meaning in Rust — building software from small capability traits](../assets/design-by-meaning-rust.png) + +```admonish tip title="関連項目" +意味論的な見方:[Denotational Design](../denotational-design/design.md)、[表示と合成性](../denotational-design/denotations.md) +Rustで意味から設計する:[Rustの意味論的型](semantic-types.md)、[導出される意味と合成](derived-meaning.md) +概念:[Expression Problem](../concepts/expression-problem.md)、[分岐と合流性](../concepts/branching.md) +``` + +```admonish note title="概要" +ケイパビリティのトレイトは小さな代数です。必要な意味を表す基本的な観測と変換に名前を付け、表現の選択をインタープリターに委ねます。最初の実装がたまたま持つフィールドではなく、意味から語彙を設計します。 +``` + +Rustには「Denotational Design」という組み込み構文はありません。通常の言語機能で意味論上の語彙を符号化します。小さなケイパビリティのトレイトは、その有用な符号化の一つです。 + +本書で接尾辞`Alg`は**代数**を意味します。すなわち、インタープリターが選ぶ担体に対する、一貫した基本操作の集合です。 + +## 意味から始める {#start-from-meaning} + +前のパートで扱った分岐位置の意味は、次のように表現できます。 + +```rust,noplayground +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub enum Direction { + Left, + Right, +} + +pub trait BranchAlg { + type Branch; + + fn branch_root(&self) -> Self::Branch; + fn branch_grow(&self, branch: &Self::Branch, direction: Direction) -> Self::Branch; + fn branch_path(&self, ancestor: &Self::Branch, descendant: &Self::Branch) -> Option>; +} +``` + +このトレイトは三つの基本的な意味を述べます。 + +* 根を構成する +* 一つの方向へ分岐を伸ばす +* 経路が存在する場合に相対経路を観測する + +分岐をどこに格納するかや経路をどう符号化するかは明かしません。 + +## ケイパビリティはフィールド参照ではない {#capabilities-are-not-field-projections} + +````admonish warning title="フィールド参照は意味論的ケイパビリティではない" +次を比べてください。 + +```rust,noplayground +trait BranchContext { + fn branches(&self) -> &Vec>; + fn branches_mut(&mut self) -> &mut Vec>; +} +``` + +このトレイトは構造体をメソッドの背後に隠していますが、表現を公開したままです。導出ロジックはベクトル、真偽値、所有権、変更方式に結び付いてしまいます。 +```` + +意味論的ケイパビリティは、下流の意味が必要とする観測や変換を公開します。次を考えてください。 + +```admonish question title="各ケイパビリティについて問う" +実装がデータベース、記号項、コンパクトな整数、リモートサービスのどれを使っていても、この操作には意味があるか。 +``` + +あるなら、その操作はケイパビリティに含められるかもしれません。呼び出し側が現在のフィールド配置を必要とするなら、含めないほうがよいでしょう。 + +## 一つのトレイトにつき基本的な意味を一つ {#one-primitive-meaning-per-trait} + +小さなトレイトは依存関係を見えるようにします。 + +```rust,noplayground +pub trait ClockAlg { + type Instant; + + fn clock_now(&self) -> Self::Instant; +} + +pub trait DeadlineAlg { + fn deadline_expired(&self, now: &Instant) -> bool; +} +``` + +時間と期限を必要とする導出操作は、両方のトレイトを要求できます。ログ、格納、ネットワーク、設定、スケジューリングを含む`ApplicationContext`を必要としません。 + +「小さい」とは機械的にメソッドを一つだけにすることではありません。操作が分かちがたい一つの意味論的構造を成す場合はまとめます。独立した意味を表す場合や、別々に解釈できる場合は分けます。 + +## 関連型で担体を選ぶ {#associated-types-select-carriers} + +インタープリターが表現を選ぶときは関連型を使います。 + +```rust,noplayground +pub trait SourceAlg { + type Source; + type Error; + + fn source_read(&self, name: &str) -> Result; +} +``` + +この境界で`String`、`std::io::Error`、具体的な構文木が安定した意味論的語彙でない限り、それらを要求しないでください。 + +一方、具体的な意味論的値を使うのは問題ありません。 + +```rust,noplayground +pub enum Severity { + Warning, + Error, +} +``` + +規則は「すべての型を抽象化する」ことではありません。「インタープリターの仕組みと意味論的語彙を混同しない」ことです。 + +## 境界は使う場所に置く {#put-bounds-where-they-are-used} + +基本操作には、必要のない制約を加えないでください。 + +```rust,noplayground +pub trait CandidateAlg { + type Candidate; + + fn candidates(&self) -> impl Iterator; +} +``` + +````admonish warning title="先回りして境界を追加しない" +将来のあるアルゴリズムが必要とするかもしれないというだけで、関連型に制約を加えないでください。 + +```rust,noplayground +pub trait CandidateAlg { + // not recommended: every interpreter now pays for bounds + // most operations never use + type Candidate: Clone + Ord + Hash + Send + Sync; + + fn candidates(&self) -> impl Iterator; +} +``` + +候補を並べ替える操作では`Ord`が必要で、ハッシュ集合に入れる操作では`Hash`が必要になります。 +```` + +使用箇所に境界を置けば、基本的な意味を再利用しやすくなり、導出された振る舞いの実際の契約も明確になります。 + +## 副作用も基本的な意味になり得る {#effects-can-be-primitive-meaning} + +ケイパビリティのトレイトは純粋な実行を意味しません。 + +```rust,noplayground +pub trait PublishAlg { + type Document; + type Error; + + async fn publish(&self, document: Self::Document) -> Result<(), Self::Error>; +} +``` + +公開処理は副作用です。それでも現在の境界では、基本的な意味論上の操作になり得ます。具体的なインタープリターはHTTP、キュー、ファイル、テスト用バッファーを使うかもしれません。 + +意図された意味に含まれない限り、意味論的な層で再試行、ソケットの所有、タスクの起動、接続プールを規定すべきではありません。 + +## 境界に名前を付ける {#naming-the-boundary} + +ケイパビリティは、利用側の意味論的な視点から表現します。 + +| 意味を中心にした名前 | 表現を中心にした名前 | +| --- | --- | +| `closed_outcome(slot)` | `get_runtime_map(slot)` | +| `source_read(name)` | `compiler_context().sources().lookup(name)` | +| `branch_path(ancestor, descendant)` | `raw_branch_bits(id)` | + +命名も設計の一部です。機械的な名前は、機械的な結合を招きます。 + +## レビュー時の確認 {#review-checks} + +* このトレイトは一貫した基本的な意味を一つ公開しているか。 +* 独立したインタープリターが、最初の表現を複製せずに実装できるか。 +* インタープリターが実際に選ぶ場合に限って、関連型を抽象化しているか。 +* 具体型は安定した意味論的語彙か。 +* 操作が使うまで境界を加えていないか。 +* マネージャー、コンテキスト、生の格納領域を返していないか。 diff --git a/src/rust-dd/capability-algebras.ko.md b/src/rust-dd/capability-algebras.ko.md new file mode 100644 index 0000000..e05955b --- /dev/null +++ b/src/rust-dd/capability-algebras.ko.md @@ -0,0 +1,184 @@ + + +# 케이퍼빌리티 대수 {#capability-algebras} + +![Design by meaning in Rust — building software from small capability traits](../assets/design-by-meaning-rust.png) + +```admonish tip title="관련 항목" +의미론적 관점: [표시적 설계](../denotational-design/design.md), [표시와 합성성](../denotational-design/denotations.md) +Rust에서 의미로 설계하기: [Rust의 의미 타입](semantic-types.md), [파생 의미와 합성](derived-meaning.md) +개념: [표현식 문제](../concepts/expression-problem.md), [분기와 합류성](../concepts/branching.md) +``` + +```admonish note title="개요" +케이퍼빌리티 트레이트는 작은 대수입니다. 의미가 필요로 하는 기본 관찰과 변환을 이름으로 나타내고, 표현 선택은 인터프리터에 맡깁니다. 첫 구현에 우연히 들어 있는 필드가 아니라 의미에서 어휘를 설계하세요. +``` + +Rust에는 “표시적 설계”라는 내장 구문이 없습니다. 일반적인 언어 기능으로 의미 어휘를 인코딩하며, 작은 케이퍼빌리티 트레이트는 그 유용한 인코딩 방법 중 하나입니다. + +이 책에서 접미사 `Alg`는 **대수**를 뜻합니다. 인터프리터가 선택한 기반 집합에서 일관성을 이루는 기본 연산의 집합입니다. + +## 의미에서 시작하기 {#start-from-meaning} + +앞부분에서 다룬 분기 위치의 의미는 다음과 같이 표현할 수 있습니다: + +```rust,noplayground +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub enum Direction { + Left, + Right, +} + +pub trait BranchAlg { + type Branch; + + fn branch_root(&self) -> Self::Branch; + fn branch_grow(&self, branch: &Self::Branch, direction: Direction) -> Self::Branch; + fn branch_path(&self, ancestor: &Self::Branch, descendant: &Self::Branch) -> Option>; +} +``` + +트레이트는 세 가지 기본 의미를 명시합니다: + +* 루트 구성 +* 한 방향으로 분기 확장 +* 가능할 때 상대 경로 관찰 + +분기를 어디에 저장하는지, 경로를 어떻게 인코딩하는지는 드러내지 않습니다. + +## 케이퍼빌리티는 필드 투영이 아닙니다 {#capabilities-are-not-field-projections} + +````admonish warning title="필드 투영은 의미론적 케이퍼빌리티가 아닙니다" +비교해 보세요: + +```rust,noplayground +trait BranchContext { + fn branches(&self) -> &Vec>; + fn branches_mut(&mut self) -> &mut Vec>; +} +``` + +이 트레이트는 구조체를 메서드 뒤에 감추지만 여전히 표현을 노출합니다. 파생 로직은 벡터, 불리언, 소유권, 변경 전략과 결합됩니다. +```` + +의미론적 케이퍼빌리티는 후속 의미에 필요한 관찰이나 변환을 노출합니다. 다음을 물어보세요: + +```admonish question title="모든 케이퍼빌리티에 물어볼 것" +구현이 데이터베이스, 기호 항, 압축 정수, 원격 서비스를 사용하더라도 이 연산이 여전히 타당한가요? +``` + +그렇다면 해당 연산은 케이퍼빌리티에 들어갈 수 있습니다. 호출자가 현재 필드 배치를 알아야 한다면 아마 적절하지 않습니다. + +## 트레이트마다 기본 의미 하나 {#one-primitive-meaning-per-trait} + +작은 트레이트는 의존 관계를 드러냅니다: + +```rust,noplayground +pub trait ClockAlg { + type Instant; + + fn clock_now(&self) -> Self::Instant; +} + +pub trait DeadlineAlg { + fn deadline_expired(&self, now: &Instant) -> bool; +} +``` + +시간과 기한이 필요한 파생 연산은 두 트레이트를 모두 요구할 수 있습니다. 로깅, 저장, 네트워크, 설정, 스케줄링을 담은 `ApplicationContext`까지 필요하지는 않습니다. + +“작다”는 것을 기계적으로 메서드 하나로 제한하라는 뜻은 아닙니다. 분리할 수 없는 의미 구조를 이루는 연산은 묶으세요. 서로 독립된 의미를 표현하거나 별도 인터프리터를 허용한다면 나누세요. + +## 연관 타입으로 기반 집합 선택하기 {#associated-types-select-carriers} + +표현을 인터프리터가 선택할 때는 연관 타입을 사용하세요: + +```rust,noplayground +pub trait SourceAlg { + type Source; + type Error; + + fn source_read(&self, name: &str) -> Result; +} +``` + +이 경계에서 안정된 의미 어휘가 아니라면 `String`, `std::io::Error` 또는 구체적인 구문 트리를 요구하지 마세요. + +반대로 구체적인 의미 값은 사용할 수 있습니다: + +```rust,noplayground +pub enum Severity { + Warning, + Error, +} +``` + +모든 타입을 추상화하라는 뜻이 아닙니다. 인터프리터의 구현 장치와 의미 어휘를 혼동하지 말라는 뜻입니다. + +## 바운드는 실제 사용하는 곳에 두세요 {#put-bounds-where-they-are-used} + +필요하지 않은 제약으로 기본 연산을 제한하지 마세요: + +```rust,noplayground +pub trait CandidateAlg { + type Candidate; + + fn candidates(&self) -> impl Iterator; +} +``` + +````admonish warning title="선제적으로 바운드를 추가하지 마세요" +미래의 어떤 알고리즘이 연관 타입을 필요로 할 수 있다는 이유만으로 타입을 제약하지 마세요: + +```rust,noplayground +pub trait CandidateAlg { + // not recommended: every interpreter now pays for bounds + // most operations never use + type Candidate: Clone + Ord + Hash + Send + Sync; + + fn candidates(&self) -> impl Iterator; +} +``` + +후보를 정렬하는 연산은 `Ord`을 요구할 수 있고, 후보를 해시 집합에 넣는 연산은 `Hash`을 요구할 수 있습니다. +```` + +사용 지점에 둔 바운드는 기본 의미를 재사용할 수 있게 하고 파생 동작의 실제 계약을 드러냅니다. + +## 효과도 기본 의미가 될 수 있습니다 {#effects-can-be-primitive-meaning} + +케이퍼빌리티 트레이트가 순수 실행을 뜻하지는 않습니다: + +```rust,noplayground +pub trait PublishAlg { + type Document; + type Error; + + async fn publish(&self, document: Self::Document) -> Result<(), Self::Error>; +} +``` + +게시에는 효과가 있습니다. 그래도 현재 경계에서는 기본 의미 연산일 수 있습니다. 구체적인 인터프리터는 HTTP, 큐, 파일, 테스트 버퍼를 사용할 수 있습니다. + +의미 계층은 재시도, 소켓 소유권, 태스크 생성, 연결 풀을 의도한 의미에 포함되는 구분이 아닌 한 규정하지 않아야 합니다. + +## 경계에 이름 붙이기 {#naming-the-boundary} + +케이퍼빌리티는 사용하는 쪽의 의미론적 관점에서 표현해야 합니다: + +| 의미 중심 | 표현 중심 | +| --- | --- | +| `closed_outcome(slot)` | `get_runtime_map(slot)` | +| `source_read(name)` | `compiler_context().sources().lookup(name)` | +| `branch_path(ancestor, descendant)` | `raw_branch_bits(id)` | + +이름 붙이기도 설계입니다. 기계적인 이름은 기계적 결합을 부추깁니다. + +## 검토 항목 {#review-checks} + +* 트레이트가 일관된 기본 의미 하나를 노출하나요? +* 독립적인 인터프리터가 첫 표현을 복사하지 않고 구현할 수 있나요? +* 인터프리터가 실제로 선택하는 경우에만 연관 타입을 추상화했나요? +* 구체 타입이 안정적인 의미 어휘인가요? +* 연산에서 필요로 하기 전까지 바운드를 두지 않았나요? +* 트레이트가 관리자, 컨텍스트, 원시 저장소를 반환하지 않나요? diff --git a/src/rust-dd/capability-algebras.ru.md b/src/rust-dd/capability-algebras.ru.md new file mode 100644 index 0000000..f23c599 --- /dev/null +++ b/src/rust-dd/capability-algebras.ru.md @@ -0,0 +1,184 @@ + + +# Алгебры возможностей {#capability-algebras} + +![Design by meaning in Rust — building software from small capability traits](../assets/design-by-meaning-rust.png) + +```admonish tip title="Связанные материалы" +«Семантический взгляд»: [Денотационное проектирование](../denotational-design/design.md), [Денотации и композиционность](../denotational-design/denotations.md) +«Проектирование на основе смысла в Rust»: [Семантические типы в Rust](semantic-types.md), [Производный смысл и композиция](derived-meaning.md) +«Понятия»: [Проблема выражения](../concepts/expression-problem.md), [Ветвление и конфлюэнтность](../concepts/branching.md) +``` + +```admonish note title="Обзор" +Трейт возможностей — это небольшая алгебра: он называет примитивные наблюдения и преобразования, необходимые для заданного смысла, и оставляет выбор представления интерпретатору. Словарь следует проектировать от смысла, а не от полей, которые случайно оказались в первой реализации. +``` + +В Rust нет встроенной конструкции под названием «денотационное проектирование». Семантические словари кодируются обычными средствами языка. Один из полезных способов — небольшие трейты возможностей. + +Суффикс `Alg` в этой книге означает **алгебру**: связный набор примитивных операций над носителями, выбранными интерпретатором. + +## Начните со смысла {#start-from-meaning} + +Смысл позиции ветвления из предыдущей части можно выразить так: + +```rust,noplayground +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub enum Direction { + Left, + Right, +} + +pub trait BranchAlg { + type Branch; + + fn branch_root(&self) -> Self::Branch; + fn branch_grow(&self, branch: &Self::Branch, direction: Direction) -> Self::Branch; + fn branch_path(&self, ancestor: &Self::Branch, descendant: &Self::Branch) -> Option>; +} +``` + +Трейт задаёт три примитивных смысла: + +* создать корень +* продолжить ветвь в одном из направлений +* наблюдать относительный путь, если он существует + +Трейт не раскрывает, где хранятся ветви и как кодируются пути. + +## Возможности — не проекции полей {#capabilities-are-not-field-projections} + +````admonish warning title="Проекции полей — не семантические возможности" +Сравните: + +```rust,noplayground +trait BranchContext { + fn branches(&self) -> &Vec>; + fn branches_mut(&mut self) -> &mut Vec>; +} +``` + +Этот трейт скрывает структуру за методами, но по-прежнему раскрывает её представление. Любая производная логика будет зависеть от векторов, логических значений, владения и стратегии мутаций. +```` + +Семантическая возможность открывает наблюдение или преобразование, необходимое для последующего смысла. Спросите: + +```admonish question title="Что спросить о каждой возможности" +Имела бы эта операция смысл, если бы реализация использовала базу данных, символьный терм, компактное целое число или удалённый сервис? +``` + +Если да, операция может относиться к этой возможности. Если же вызывающему коду нужна нынешняя схема полей, вероятно, она не относится. + +## Один примитивный смысл на трейт {#one-primitive-meaning-per-trait} + +Небольшие трейты делают зависимости явными: + +```rust,noplayground +pub trait ClockAlg { + type Instant; + + fn clock_now(&self) -> Self::Instant; +} + +pub trait DeadlineAlg { + fn deadline_expired(&self, now: &Instant) -> bool; +} +``` + +Производная операция, которой нужны время и крайний срок, может требовать оба трейта. Ей не нужен `ApplicationContext`, объединяющий журналирование, хранение, сеть, конфигурацию и планирование. + +«Небольшой» не значит механически «один метод». Группируйте операции, когда они образуют единую неразделимую семантическую структуру. Разделяйте, когда они выражают независимые смыслы или допускают независимые интерпретаторы. + +## Ассоциированные типы выбирают носители {#associated-types-select-carriers} + +Используйте ассоциированные типы, когда представление выбирает интерпретатор: + +```rust,noplayground +pub trait SourceAlg { + type Source; + type Error; + + fn source_read(&self, name: &str) -> Result; +} +``` + +Не требуйте `String`, `std::io::Error` или конкретное синтаксическое дерево, если они не являются устойчивой частью семантического словаря на этой границе. + +При этом конкретные семантические значения вполне уместны: + +```rust,noplayground +pub enum Severity { + Warning, + Error, +} +``` + +Правило не в том, чтобы «сделать абстрактным каждый тип», а в том, чтобы «не путать механизмы интерпретатора с семантическим словарём». + +## Добавляйте ограничения там, где они используются {#put-bounds-where-they-are-used} + +Не ограничивайте примитив без необходимости: + +```rust,noplayground +pub trait CandidateAlg { + type Candidate; + + fn candidates(&self) -> impl Iterator; +} +``` + +````admonish warning title="Не добавляйте ограничения заранее" +Не ограничивайте ассоциированный тип лишь потому, что это может понадобиться какому-нибудь будущему алгоритму: + +```rust,noplayground +pub trait CandidateAlg { + // not recommended: every interpreter now pays for bounds + // most operations never use + type Candidate: Clone + Ord + Hash + Send + Sync; + + fn candidates(&self) -> impl Iterator; +} +``` + +Операция сортировки кандидатов может требовать `Ord`; операции помещения в хеш-множество может требовать `Hash`. +```` + +Ограничения в месте использования сохраняют повторное применение примитивных смыслов и выявляют настоящий контракт производного поведения. + +## Эффекты могут быть примитивным смыслом {#effects-can-be-primitive-meaning} + +Трейты возможностей не подразумевают чистое выполнение: + +```rust,noplayground +pub trait PublishAlg { + type Document; + type Error; + + async fn publish(&self, document: Self::Document) -> Result<(), Self::Error>; +} +``` + +Публикация — это эффект. На текущей границе она всё же может быть примитивной семантической операцией. Конкретный интерпретатор может использовать HTTP, очередь, файл или тестовый буфер. + +Семантический слой не должен предписывать повторные попытки, владение сокетами, запуск задач или пулы соединений, если эти различия не входят в предполагаемый смысл. + +## Обозначение границы {#naming-the-boundary} + +Формулируйте возможности с точки зрения смысла для потребителя: + +| Ориентированное на смысл | Ориентированное на представление | +| --- | --- | +| `closed_outcome(slot)` | `get_runtime_map(slot)` | +| `source_read(name)` | `compiler_context().sources().lookup(name)` | +| `branch_path(ancestor, descendant)` | `raw_branch_bits(id)` | + +Именование — часть проектирования. Механическое имя провоцирует механическую связанность. + +## Проверочные вопросы {#review-checks} + +* Выражает ли трейт один связный примитивный смысл? +* Сможет ли независимый интерпретатор реализовать его, не копируя первое представление? +* Используются ли ассоциированные типы как абстрактные только там, где выбор действительно за интерпретатором? +* Являются ли конкретные типы устойчивой частью семантического словаря? +* Отсутствуют ли ограничения до тех пор, пока они не нужны операции? +* Избегает ли трейт возврата управляющих объектов, контекстов и сырого хранилища? diff --git a/src/rust-dd/capability-algebras.uk.md b/src/rust-dd/capability-algebras.uk.md new file mode 100644 index 0000000..48d6f39 --- /dev/null +++ b/src/rust-dd/capability-algebras.uk.md @@ -0,0 +1,184 @@ + + +# Алгебри можливостей {#capability-algebras} + +![Design by meaning in Rust — building software from small capability traits](../assets/design-by-meaning-rust.png) + +```admonish tip title="Пов’язані матеріали" +Семантичний погляд: [Денотаційне проєктування](../denotational-design/design.md), [Денотації та композиційність](../denotational-design/denotations.md) +Проєктування від значення в Rust: [Семантичні типи в Rust](semantic-types.md), [Похідне значення та композиція](derived-meaning.md) +Поняття: [Проблема виразів](../concepts/expression-problem.md), [Розгалуження та конфлюентність](../concepts/branching.md) +``` + +```admonish note title="Вступний огляд" +Трейт можливостей — це невелика алгебра: він називає примітивні спостереження й перетворення, потрібні для певного значення, а вибір представлення залишає інтерпретатору. Термінологію слід виводити зі значення, а не з полів, які випадково є в першій реалізації. +``` + +У Rust немає вбудованої конструкції під назвою «денотаційне проєктування». Ми кодуємо семантичну термінологію звичайними засобами мови. Невеликі трейти можливостей — один із корисних способів це зробити. + +Суфікс `Alg` у цій книжці означає **алгебру**: цілісний набір примітивних операцій над носіями, які вибирає інтерпретатор. + +## Почніть зі значення {#start-from-meaning} + +Значення позиції в розгалуженні, розглянуте в попередній частині, можна виразити так: + +```rust,noplayground +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub enum Direction { + Left, + Right, +} + +pub trait BranchAlg { + type Branch; + + fn branch_root(&self) -> Self::Branch; + fn branch_grow(&self, branch: &Self::Branch, direction: Direction) -> Self::Branch; + fn branch_path(&self, ancestor: &Self::Branch, descendant: &Self::Branch) -> Option>; +} +``` + +Трейт задає три примітивні значення: + +* побудувати корінь +* розширити гілку в одному напрямку +* спостерігати відносний шлях, якщо він існує + +Він не визначає, де зберігаються гілки й у який спосіб закодовано шляхи. + +## Можливості — це не проєкції полів {#capabilities-are-not-field-projections} + +````admonish warning title="Проєкції полів не є семантичними можливостями" +Порівняймо: + +```rust,noplayground +trait BranchContext { + fn branches(&self) -> &Vec>; + fn branches_mut(&mut self) -> &mut Vec>; +} +``` + +Цей трейт приховує структуру за методами, але все одно відкриває її представлення. Будь-яка похідна логіка стає залежною від векторів, булевих значень, володіння та стратегії мутацій. +```` + +Семантична можливість відкриває спостереження чи перетворення, потрібне для подальшого значення. Запитайте себе: + +```admonish question title="Запитання до кожної можливості" +Чи мала б ця операція сенс, якби реалізація використовувала базу даних, символьний терм, компактне ціле число або віддалену службу? +``` + +Якщо так, операція може належати до можливості. Якщо ж клієнтам потрібне поточне розташування полів, їй, імовірно, там не місце. + +## Одне примітивне значення на трейт {#one-primitive-meaning-per-trait} + +Невеликі трейти роблять залежності помітними: + +```rust,noplayground +pub trait ClockAlg { + type Instant; + + fn clock_now(&self) -> Self::Instant; +} + +pub trait DeadlineAlg { + fn deadline_expired(&self, now: &Instant) -> bool; +} +``` + +Похідна операція, якій потрібні час і граничний термін, може вимагати обох трейтів. Їй не потрібен `ApplicationContext`, що містить журналювання, сховище, мережу, конфігурацію та планування. + +«Невеликий» не означає механічно «з одним методом». Групуйте операції, якщо вони утворюють єдину нероздільну семантичну структуру. Розділяйте їх, якщо вони виражають незалежні значення або допускають незалежні інтерпретатори. + +## Асоційовані типи вибирають носії {#associated-types-select-carriers} + +Використовуйте асоційовані типи, коли представлення вибирає інтерпретатор: + +```rust,noplayground +pub trait SourceAlg { + type Source; + type Error; + + fn source_read(&self, name: &str) -> Result; +} +``` + +Не вимагайте `String`, `std::io::Error` чи конкретного синтаксичного дерева, якщо на цій межі вони не є сталою частиною семантичної термінології. + +Водночас конкретні семантичні значення цілком доречні: + +```rust,noplayground +pub enum Severity { + Warning, + Error, +} +``` + +Правило не в тому, щоб «зробити абстрактним кожен тип». Правило в тому, щоб «не плутати механізми інтерпретатора із семантичною термінологією». + +## Розміщуйте обмеження там, де їх використовують {#put-bounds-where-they-are-used} + +Не обтяжуйте примітив обмеженнями, яких він не потребує: + +```rust,noplayground +pub trait CandidateAlg { + type Candidate; + + fn candidates(&self) -> impl Iterator; +} +``` + +````admonish warning title="Не додавайте обмеження завчасно" +Не обмежуйте асоційований тип лише через те, що воно може знадобитися одному майбутньому алгоритму: + +```rust,noplayground +pub trait CandidateAlg { + // not recommended: every interpreter now pays for bounds + // most operations never use + type Candidate: Clone + Ord + Hash + Send + Sync; + + fn candidates(&self) -> impl Iterator; +} +``` + +Операція сортування кандидатів може вимагати `Ord`, а операція додавання їх до хеш-множини — `Hash`. +```` + +Обмеження в місцях використання дають змогу повторно застосовувати примітивні значення й виявляють справжній контракт похідної поведінки. + +## Ефекти можуть бути примітивним значенням {#effects-can-be-primitive-meaning} + +Трейти можливостей не передбачають чистого виконання: + +```rust,noplayground +pub trait PublishAlg { + type Document; + type Error; + + async fn publish(&self, document: Self::Document) -> Result<(), Self::Error>; +} +``` + +Публікація є ефектом. Вона все одно може бути примітивною семантичною операцією на поточній межі. Конкретний інтерпретатор може використовувати HTTP, чергу, файл чи тестовий буфер. + +Семантичний рівень не має визначати повторні спроби, володіння сокетами, запуск завдань чи пули з’єднань, якщо ці відмінності не є частиною задуму. + +## Назвіть межу {#naming-the-boundary} + +Формулюйте можливості з погляду семантики споживача: + +| Орієнтоване на значення | Орієнтоване на представлення | +| --- | --- | +| `closed_outcome(slot)` | `get_runtime_map(slot)` | +| `source_read(name)` | `compiler_context().sources().lookup(name)` | +| `branch_path(ancestor, descendant)` | `raw_branch_bits(id)` | + +Називання — частина проєктування. Механічна назва провокує механічну залежність. + +## Перевірка {#review-checks} + +* Чи відкриває трейт одне цілісне примітивне значення? +* Чи може незалежний інтерпретатор реалізувати його, не копіюючи перше представлення? +* Чи є асоційовані типи абстрактними лише там, де їх справді вибирає інтерпретатор? +* Чи є конкретні типи сталою семантичною термінологією? +* Чи не накладаються обмеження, доки їх не використовує певна операція? +* Чи уникає трейт повернення менеджерів, контекстів і необроблених даних сховища? diff --git a/src/rust-dd/capability-algebras.vi.md b/src/rust-dd/capability-algebras.vi.md new file mode 100644 index 0000000..c986cc1 --- /dev/null +++ b/src/rust-dd/capability-algebras.vi.md @@ -0,0 +1,184 @@ + + +# Các đại số năng lực {#capability-algebras} + +![Design by meaning in Rust — building software from small capability traits](../assets/design-by-meaning-rust.png) + +```admonish tip title="Liên quan" +Góc nhìn ngữ nghĩa: [Thiết kế theo ngữ nghĩa](../denotational-design/design.md), [Ngữ nghĩa và tính hợp thành](../denotational-design/denotations.md) +Thiết kế theo ngữ nghĩa trong Rust: [Kiểu ngữ nghĩa trong Rust](semantic-types.md), [Ý nghĩa suy ra và phép hợp thành](derived-meaning.md) +Khái niệm: [Bài toán biểu thức](../concepts/expression-problem.md), [Phân nhánh và hội tụ](../concepts/branching.md) +``` + +```admonish note title="Định hướng" +Đặc trưng năng lực là một đại số nhỏ: nó nêu tên các quan sát và phép biến đổi nguyên thủy mà ý nghĩa cần, đồng thời để bộ diễn giải quyết định cách biểu diễn. Hãy thiết kế từ vựng dựa trên ý nghĩa, không dựa vào các trường mà cách triển khai đầu tiên tình cờ lưu giữ. +``` + +Rust không có cấu trúc dựng sẵn tên là “Thiết kế theo ngữ nghĩa”. Ta mã hóa từ vựng ngữ nghĩa bằng các tính năng ngôn ngữ thông thường. Đặc trưng năng lực nhỏ là một cách mã hóa hữu ích. + +Hậu tố `Alg` trong cuốn sách này có nghĩa là **đại số**: một tập hợp phép toán nguyên thủy nhất quán trên các đối tượng mang do bộ diễn giải chọn. + +## Bắt đầu từ ý nghĩa {#start-from-meaning} + +Ý nghĩa vị trí nhánh từ phần trước có thể biểu đạt như sau: + +```rust,noplayground +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub enum Direction { + Left, + Right, +} + +pub trait BranchAlg { + type Branch; + + fn branch_root(&self) -> Self::Branch; + fn branch_grow(&self, branch: &Self::Branch, direction: Direction) -> Self::Branch; + fn branch_path(&self, ancestor: &Self::Branch, descendant: &Self::Branch) -> Option>; +} +``` + +Đặc trưng nêu ba ý nghĩa nguyên thủy: + +* tạo vị trí gốc +* mở rộng nhánh theo một hướng +* quan sát đường đi tương đối khi nó tồn tại + +Đặc trưng không tiết lộ nơi lưu trữ nhánh hay cách mã hóa đường đi. + +## Năng lực không phải phép chiếu trường {#capabilities-are-not-field-projections} + +````admonish warning title="Phép chiếu trường không phải năng lực ngữ nghĩa" +Hãy so sánh: + +```rust,noplayground +trait BranchContext { + fn branches(&self) -> &Vec>; + fn branches_mut(&mut self) -> &mut Vec>; +} +``` + +Đặc trưng này che giấu cấu trúc phía sau các phương thức nhưng vẫn phơi bày cách biểu diễn. Mọi logic suy ra sẽ bị gắn chặt với vectơ, giá trị boolean, quyền sở hữu và chiến lược biến đổi. +```` + +Năng lực ngữ nghĩa bộc lộ quan sát hoặc phép biến đổi mà ý nghĩa phía sau cần. Hãy tự hỏi: + +```admonish question title="Cần hỏi về mọi năng lực" +Nếu cách triển khai dùng cơ sở dữ liệu, số hạng ký hiệu, số nguyên gọn hoặc dịch vụ từ xa, phép toán này còn hợp lý không? +``` + +Nếu có, phép toán có thể thuộc về năng lực. Nếu bên gọi cần bố cục trường hiện tại thì có lẽ không. + +## Mỗi đặc trưng một ý nghĩa nguyên thủy {#one-primitive-meaning-per-trait} + +Đặc trưng nhỏ giúp nhìn rõ các phụ thuộc: + +```rust,noplayground +pub trait ClockAlg { + type Instant; + + fn clock_now(&self) -> Self::Instant; +} + +pub trait DeadlineAlg { + fn deadline_expired(&self, now: &Instant) -> bool; +} +``` + +Một phép toán suy ra cần thời điểm và hạn chót có thể yêu cầu cả hai đặc trưng. Nó không cần một `ApplicationContext` chứa ghi nhật ký, lưu trữ, mạng, cấu hình và lập lịch. + +“Nhỏ” không có nghĩa là máy móc giới hạn một phương thức. Hãy nhóm các phép toán khi chúng tạo thành một cấu trúc ngữ nghĩa không thể tách rời. Tách chúng khi chúng biểu đạt các ý nghĩa độc lập hoặc cho phép các bộ diễn giải độc lập. + +## Kiểu liên kết chọn đối tượng mang {#associated-types-select-carriers} + +Dùng kiểu liên kết khi bộ diễn giải quyết định cách biểu diễn: + +```rust,noplayground +pub trait SourceAlg { + type Source; + type Error; + + fn source_read(&self, name: &str) -> Result; +} +``` + +Đừng yêu cầu `String`, `std::io::Error` hay cây cú pháp cụ thể, trừ khi chúng là từ vựng ngữ nghĩa ổn định tại ranh giới này. + +Ngược lại, các giá trị ngữ nghĩa cụ thể hoàn toàn phù hợp: + +```rust,noplayground +pub enum Severity { + Warning, + Error, +} +``` + +Quy tắc không phải là “làm cho mọi kiểu đều trừu tượng”, mà là “đừng nhầm cơ chế của bộ diễn giải với từ vựng ngữ nghĩa”. + +## Đặt ràng buộc ở nơi sử dụng {#put-bounds-where-they-are-used} + +Giữ phép toán nguyên thủy không bị ràng buộc bởi những điều nó không cần: + +```rust,noplayground +pub trait CandidateAlg { + type Candidate; + + fn candidates(&self) -> impl Iterator; +} +``` + +````admonish warning title="Đừng thêm ràng buộc để phòng xa" +Đừng ràng buộc kiểu liên kết chỉ vì một thuật toán tương lai nào đó có thể cần: + +```rust,noplayground +pub trait CandidateAlg { + // not recommended: every interpreter now pays for bounds + // most operations never use + type Candidate: Clone + Ord + Hash + Send + Sync; + + fn candidates(&self) -> impl Iterator; +} +``` + +Phép toán sắp xếp ứng viên có thể yêu cầu `Ord`; phép toán đưa chúng vào tập băm có thể yêu cầu `Hash`. +```` + +Ràng buộc tại nơi sử dụng giúp ý nghĩa nguyên thủy tái sử dụng được và làm lộ hợp đồng thực sự của hành vi suy ra. + +## Hiệu ứng có thể là ý nghĩa nguyên thủy {#effects-can-be-primitive-meaning} + +Đặc trưng năng lực không đồng nghĩa với thực thi thuần: + +```rust,noplayground +pub trait PublishAlg { + type Document; + type Error; + + async fn publish(&self, document: Self::Document) -> Result<(), Self::Error>; +} +``` + +Xuất bản là một hiệu ứng. Nó vẫn có thể là phép toán ngữ nghĩa nguyên thủy ở ranh giới hiện tại. Bộ diễn giải cụ thể có thể dùng HTTP, hàng đợi, tệp hoặc bộ đệm kiểm thử. + +Lớp ngữ nghĩa không nên áp đặt thử lại, quyền sở hữu socket, tạo tác vụ hay nhóm kết nối, trừ khi những khác biệt đó thuộc ý nghĩa dự định. + +## Đặt tên cho ranh giới {#naming-the-boundary} + +Hãy diễn đạt năng lực từ góc nhìn ngữ nghĩa của bên sử dụng: + +| Định hướng theo ý nghĩa | Định hướng theo biểu diễn | +| --- | --- | +| `closed_outcome(slot)` | `get_runtime_map(slot)` | +| `source_read(name)` | `compiler_context().sources().lookup(name)` | +| `branch_path(ancestor, descendant)` | `raw_branch_bits(id)` | + +Đặt tên là một phần của thiết kế. Tên mang tính máy móc dễ kéo theo sự phụ thuộc máy móc. + +## Các câu hỏi khi duyệt {#review-checks} + +* Đặc trưng có bộc lộ một ý nghĩa nguyên thủy nhất quán không? +* Một bộ diễn giải độc lập có thể triển khai nó mà không sao chép cách biểu diễn đầu tiên không? +* Kiểu liên kết chỉ trừu tượng ở nơi bộ diễn giải thực sự được quyền lựa chọn chứ? +* Các kiểu cụ thể có phải từ vựng ngữ nghĩa ổn định không? +* Các ràng buộc chỉ xuất hiện khi một phép toán dùng đến chúng chứ? +* Đặc trưng có tránh trả về trình quản lý, ngữ cảnh và vùng lưu trữ thô không? diff --git a/src/rust-dd/capability-algebras.zh-hant.md b/src/rust-dd/capability-algebras.zh-hant.md new file mode 100644 index 0000000..2127e1a --- /dev/null +++ b/src/rust-dd/capability-algebras.zh-hant.md @@ -0,0 +1,184 @@ + + +# 能力代數 {#capability-algebras} + +![Design by meaning in Rust — building software from small capability traits](../assets/design-by-meaning-rust.png) + +```admonish tip title="相關內容" +語義視角:[指稱設計](../denotational-design/design.md)、[指稱與組合性](../denotational-design/denotations.md) +Rust 中的語義驅動設計:[Rust 中的語義型別](semantic-types.md)、[派生含義與組合](derived-meaning.md) +概念:[表示式問題](../concepts/expression-problem.md)、[分支與合流](../concepts/branching.md) +``` + +```admonish note title="導讀" +能力 trait 是一種小型代數:它為某種含義所需的基本觀察與變換命名,並將表示留給直譯器決定。應根據含義設計詞彙,而非根據首個實作恰好包含哪些欄位。 +``` + +Rust 沒有名為“指稱設計”的內建構造。我們用普通語言特性來編碼語義詞彙。小型能力 trait 是一種實用的編碼方式。 + +本書中的字尾`Alg`表示**代數**:一組作用於由直譯器選擇的載體之上的連貫基本操作。 + +## 從含義出發 {#start-from-meaning} + +前一部分中的分支位置含義可以表示為: + +```rust,noplayground +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub enum Direction { + Left, + Right, +} + +pub trait BranchAlg { + type Branch; + + fn branch_root(&self) -> Self::Branch; + fn branch_grow(&self, branch: &Self::Branch, direction: Direction) -> Self::Branch; + fn branch_path(&self, ancestor: &Self::Branch, descendant: &Self::Branch) -> Option>; +} +``` + +該 trait 陳述了三種基本含義: + +* 構造根位置 +* 沿一個方向延伸分支 +* 在路徑存在時觀察相對路徑 + +它不會暴露分支儲存在哪裡,也不會暴露路徑如何編碼。 + +## 能力不等於欄位投影 {#capabilities-are-not-field-projections} + +````admonish warning title="欄位投影不是語義能力" +比較: + +```rust,noplayground +trait BranchContext { + fn branches(&self) -> &Vec>; + fn branches_mut(&mut self) -> &mut Vec>; +} +``` + +這個 trait 用方法隱藏了結構體,卻仍然暴露其表示。任何派生邏輯都會與向量、布林值、所有權和修改策略耦合。 +```` + +語義能力暴露的是下游含義所需的觀察或變換。請思考: + +```admonish question title="審視每種能力" +如果實作改用資料庫、符號項、緊湊整數或遠端服務,這個操作是否仍然說得通? +``` + +如果答案是肯定的,該操作就可能屬於此能力。如果呼叫者必須依賴當前欄位佈局,那它很可能不該屬於此處。 + +## 每個 trait 表達一種基本含義 {#one-primitive-meaning-per-trait} + +小型 trait 能讓依賴一目瞭然: + +```rust,noplayground +pub trait ClockAlg { + type Instant; + + fn clock_now(&self) -> Self::Instant; +} + +pub trait DeadlineAlg { + fn deadline_expired(&self, now: &Instant) -> bool; +} +``` + +需要時間與截止時間的派生操作可以同時要求這兩種 trait。它不需要一個`ApplicationContext`囊括日誌、儲存、網路、配置和排程的上下文。 + +“小”不等於機械地只包含一個方法。當操作構成不可分割的語義結構時,應將它們放在一起;當它們表達彼此獨立的含義或允許獨立直譯器時,應將它們拆開。 + +## 關聯型別選擇載體 {#associated-types-select-carriers} + +當表示由直譯器選擇時,使用關聯型別: + +```rust,noplayground +pub trait SourceAlg { + type Source; + type Error; + + fn source_read(&self, name: &str) -> Result; +} +``` + +除非`String`、`std::io::Error`或具體語法樹在此邊界上屬於穩定的語義詞彙,否則不要要求它們。 + +反過來,具體語義值也完全可以使用: + +```rust,noplayground +pub enum Severity { + Warning, + Error, +} +``` + +規則不是“讓所有型別都抽象”,而是“不要混淆直譯器機制與語義詞彙”。 + +## 在使用處新增約束 {#put-bounds-where-they-are-used} + +讓基本操作不受它用不到的約束: + +```rust,noplayground +pub trait CandidateAlg { + type Candidate; + + fn candidates(&self) -> impl Iterator; +} +``` + +````admonish warning title="不要預先新增約束" +不要僅僅因為某個未來演算法可能需要某項能力,就限制關聯型別: + +```rust,noplayground +pub trait CandidateAlg { + // not recommended: every interpreter now pays for bounds + // most operations never use + type Candidate: Clone + Ord + Hash + Send + Sync; + + fn candidates(&self) -> impl Iterator; +} +``` + +對候選項排序的操作可以要求`Ord`;將它們放入雜湊集合的操作則可以要求`Hash`。 +```` + +在使用處新增約束,能讓基本含義便於複用,也能揭示派生行為真正的契約。 + +## 效應可以是基本含義 {#effects-can-be-primitive-meaning} + +能力 trait 並不意味著純執行: + +```rust,noplayground +pub trait PublishAlg { + type Document; + type Error; + + async fn publish(&self, document: Self::Document) -> Result<(), Self::Error>; +} +``` + +釋出是一種效應。它仍然可以是當前邊界上的基本語義操作。具體直譯器可以使用 HTTP、佇列、檔案或測試緩衝區。 + +除非重試、套接字所有權、任務生成或連線池屬於預期含義,否則語義層不應規定這些內容。 + +## 為邊界命名 {#naming-the-boundary} + +應從使用者的語義視角描述能力: + +| 面向含義 | 面向表示 | +| --- | --- | +| `closed_outcome(slot)` | `get_runtime_map(slot)` | +| `source_read(name)` | `compiler_context().sources().lookup(name)` | +| `branch_path(ancestor, descendant)` | `raw_branch_bits(id)` | + +命名本身就是設計。機械式名稱容易引入機械式耦合。 + +## 審查要點 {#review-checks} + +* 這個 trait 是否表達一種連貫的基本含義? +* 獨立直譯器能否在不復制首個表示的情況下實作它? +* 是否只在直譯器確實能選擇時才使用抽象關聯型別? +* 具體型別是否屬於穩定的語義詞彙? +* 是否等到某個操作確實用到約束時才新增? +* 這個 trait 是否避免返回管理器、上下文物件和原始儲存? diff --git a/src/rust-dd/capability-algebras.zh.md b/src/rust-dd/capability-algebras.zh.md new file mode 100644 index 0000000..9a64e50 --- /dev/null +++ b/src/rust-dd/capability-algebras.zh.md @@ -0,0 +1,184 @@ + + +# 能力代数 {#capability-algebras} + +![Design by meaning in Rust — building software from small capability traits](../assets/design-by-meaning-rust.png) + +```admonish tip title="相关内容" +语义视角:[指称设计](../denotational-design/design.md)、[指称与组合性](../denotational-design/denotations.md) +Rust 中的语义驱动设计:[Rust 中的语义类型](semantic-types.md)、[派生含义与组合](derived-meaning.md) +概念:[表达式问题](../concepts/expression-problem.md)、[分支与合流](../concepts/branching.md) +``` + +```admonish note title="导读" +能力 trait 是一种小型代数:它为某种含义所需的基本观察与变换命名,并将表示留给解释器决定。应根据含义设计词汇,而非根据首个实现恰好包含哪些字段。 +``` + +Rust 没有名为“指称设计”的内置构造。我们用普通语言特性来编码语义词汇。小型能力 trait 是一种实用的编码方式。 + +本书中的后缀`Alg`表示**代数**:一组作用于由解释器选择的载体之上的连贯基本操作。 + +## 从含义出发 {#start-from-meaning} + +前一部分中的分支位置含义可以表示为: + +```rust,noplayground +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub enum Direction { + Left, + Right, +} + +pub trait BranchAlg { + type Branch; + + fn branch_root(&self) -> Self::Branch; + fn branch_grow(&self, branch: &Self::Branch, direction: Direction) -> Self::Branch; + fn branch_path(&self, ancestor: &Self::Branch, descendant: &Self::Branch) -> Option>; +} +``` + +该 trait 陈述了三种基本含义: + +* 构造根位置 +* 沿一个方向延伸分支 +* 在路径存在时观察相对路径 + +它不会暴露分支存储在哪里,也不会暴露路径如何编码。 + +## 能力不等于字段投影 {#capabilities-are-not-field-projections} + +````admonish warning title="字段投影不是语义能力" +比较: + +```rust,noplayground +trait BranchContext { + fn branches(&self) -> &Vec>; + fn branches_mut(&mut self) -> &mut Vec>; +} +``` + +这个 trait 用方法隐藏了结构体,却仍然暴露其表示。任何派生逻辑都会与向量、布尔值、所有权和修改策略耦合。 +```` + +语义能力暴露的是下游含义所需的观察或变换。请思考: + +```admonish question title="审视每种能力" +如果实现改用数据库、符号项、紧凑整数或远程服务,这个操作是否仍然说得通? +``` + +如果答案是肯定的,该操作就可能属于此能力。如果调用者必须依赖当前字段布局,那它很可能不该属于此处。 + +## 每个 trait 表达一种基本含义 {#one-primitive-meaning-per-trait} + +小型 trait 能让依赖一目了然: + +```rust,noplayground +pub trait ClockAlg { + type Instant; + + fn clock_now(&self) -> Self::Instant; +} + +pub trait DeadlineAlg { + fn deadline_expired(&self, now: &Instant) -> bool; +} +``` + +需要时间与截止时间的派生操作可以同时要求这两种 trait。它不需要一个`ApplicationContext`囊括日志、存储、网络、配置和调度的上下文。 + +“小”不等于机械地只包含一个方法。当操作构成不可分割的语义结构时,应将它们放在一起;当它们表达彼此独立的含义或允许独立解释器时,应将它们拆开。 + +## 关联类型选择载体 {#associated-types-select-carriers} + +当表示由解释器选择时,使用关联类型: + +```rust,noplayground +pub trait SourceAlg { + type Source; + type Error; + + fn source_read(&self, name: &str) -> Result; +} +``` + +除非`String`、`std::io::Error`或具体语法树在此边界上属于稳定的语义词汇,否则不要要求它们。 + +反过来,具体语义值也完全可以使用: + +```rust,noplayground +pub enum Severity { + Warning, + Error, +} +``` + +规则不是“让所有类型都抽象”,而是“不要混淆解释器机制与语义词汇”。 + +## 在使用处添加约束 {#put-bounds-where-they-are-used} + +让基本操作不受它用不到的约束: + +```rust,noplayground +pub trait CandidateAlg { + type Candidate; + + fn candidates(&self) -> impl Iterator; +} +``` + +````admonish warning title="不要预先添加约束" +不要仅仅因为某个未来算法可能需要某项能力,就限制关联类型: + +```rust,noplayground +pub trait CandidateAlg { + // not recommended: every interpreter now pays for bounds + // most operations never use + type Candidate: Clone + Ord + Hash + Send + Sync; + + fn candidates(&self) -> impl Iterator; +} +``` + +对候选项排序的操作可以要求`Ord`;将它们放入哈希集合的操作则可以要求`Hash`。 +```` + +在使用处添加约束,能让基本含义便于复用,也能揭示派生行为真正的契约。 + +## 效应可以是基本含义 {#effects-can-be-primitive-meaning} + +能力 trait 并不意味着纯执行: + +```rust,noplayground +pub trait PublishAlg { + type Document; + type Error; + + async fn publish(&self, document: Self::Document) -> Result<(), Self::Error>; +} +``` + +发布是一种效应。它仍然可以是当前边界上的基本语义操作。具体解释器可以使用 HTTP、队列、文件或测试缓冲区。 + +除非重试、套接字所有权、任务生成或连接池属于预期含义,否则语义层不应规定这些内容。 + +## 为边界命名 {#naming-the-boundary} + +应从使用者的语义视角描述能力: + +| 面向含义 | 面向表示 | +| --- | --- | +| `closed_outcome(slot)` | `get_runtime_map(slot)` | +| `source_read(name)` | `compiler_context().sources().lookup(name)` | +| `branch_path(ancestor, descendant)` | `raw_branch_bits(id)` | + +命名本身就是设计。机械式名称容易引入机械式耦合。 + +## 审查要点 {#review-checks} + +* 这个 trait 是否表达一种连贯的基本含义? +* 独立解释器能否在不复制首个表示的情况下实现它? +* 是否只在解释器确实能选择时才使用抽象关联类型? +* 具体类型是否属于稳定的语义词汇? +* 是否等到某个操作确实用到约束时才添加? +* 这个 trait 是否避免返回管理器、上下文对象和原始存储? diff --git a/src/rust-dd/compiler-pipelines.ar.md b/src/rust-dd/compiler-pipelines.ar.md new file mode 100644 index 0000000..d948fbe --- /dev/null +++ b/src/rust-dd/compiler-pipelines.ar.md @@ -0,0 +1,196 @@ + + +# مسارات اللغة والمترجم {#language-and-compiler-pipelines} + +```admonish tip title="ذات صلة" +التصميم انطلاقًا من المعنى في Rust: [برامج من الرتبة الأولى](first-order-programs.md)، [المفسرات والآثار](interpreters.md) +المفاهيم: [الدلالات التشغيلية](../concepts/operational_semantics.md)، [إزالة الدوال](../concepts/defunctionalization.md) +الرؤى: [جبر EVM](../insights/evm-alg.md) +``` + +```admonish note title="المعنى ليس مسار المعالجة" +يتضح المترجم أكثر حين لا يُساوى معنى اللغة بأشجار المحلل أو مراحل المعالجة أو الشيفرة البايتية أو حلقة الآلة. والصحة قانون تبادلي واحد: تشغيل البرنامج المترجم يوافق الدلالة التي يحددها البرنامج. +``` + +يسهل الاستدلال على المترجم عندما لا يُساوى معنى اللغة بأشجار المحلل أو مراحل المترجم أو الشيفرة البايتية أو حلقة الآلة الافتراضية. + +يستخدم هذا الفصل لغة متزامنة مبسطة على نمط Tolang، مع إبقاء التركيز على البنية الدلالية. + +## أربع طبقات متميزة {#four-distinct-layers} + +أبقِ هذه الطبقات منفصلة: + +1. صياغة المصدر +2. اللغة المعيارية +3. التمثيل التنفيذي +4. تنفيذ الآلة + +مسار نموذجي: + +$$ \begin{aligned} \operatorname{Parse} &\colon \mathsf{Source} \to \mathsf{Syntax} \\ \operatorname{Normalize} &\colon \mathsf{Syntax} \to \operatorname{Result}(\mathsf{Core}, \mathsf{Diagnostics}) \\ \operatorname{CodeGen} &\colon \mathsf{Core} \to \operatorname{Result}(\mathsf{Executable}, \mathsf{Error}) \\ \operatorname{Run} &\colon \mathsf{Executable} \times \mathsf{RuntimeState} \to \mathsf{Observation} \end{aligned} $$ + +العملية المساعدة هي التركيب: + +$$ \operatorname{Compile} = \operatorname{Parse}\mathbin{;}\operatorname{Normalize}\mathbin{;}\operatorname{CodeGen} $$ + +المساعد المركّب ليس التعريف الدلالي لكل مرحلة. + +## الصياغة ليست المعنى بعد {#syntax-is-not-yet-meaning} + +يعكس خرج المحلل خيارات القواعد: + +* علامات الترقيم +* السكر النحوي +* الأسبقية +* مواضع المصدر +* التمثيل المولّد للمحلل + +تهم هذه الحقائق التشخيصات والأدوات، لكنها ليست مضطرة إلى تعريف اللغة الأساسية. + +يزيل التطبيع الاختلافات النحوية العرضية ويُدخل صيغة أصغر حاملة للمعنى. فمثلًا، يمكن تطبيع صيغ إسناد سطحية متعددة إلى عملية تقييد واحدة في النواة. + +**صيغ مصدر متعددة** → **مُنشئ معياري واحد** + +ينشئ هذا موضعًا واحدًا لصياغة قوانين المترجم ووقت التشغيل لاحقًا. + +## المعنى الدلالي ومعنى البرنامج المترجم {#denotational-and-compiled-meaning} + +لنعرّف: + +$$ \llbracket - \rrbracket : Core \to D $$ + +إسناد المعاني في المجال الدلالي `D`. + +ينتج التجميع قيمًا تنفيذية: + +$$ compile : Core \to Executable $$ + +ويلاحظ التنفيذ تلك القيم: + +$$ run : Executable \to D $$ + +التزام الصحة المركزي هو مخطط تبادلي: + +$$ \operatorname{run}(\operatorname{compile}(p)) = \llbracket p \rrbracket $$ + +في الأنظمة غير الحتمية أو المتزامنة، قد تكون المساواة تكافؤًا رصديًا أو مجموعة نتائج أو تكافؤًا للمسارات أو تشابهًا محاكى، بدلًا من مساواة القيم المعتادة. وعلى النموذج الدلالي أن يختار. + +## معنى العملية المتزامنة {#concurrent-process-meaning} + +يتضمن حساب الانعكاس الأساسي أفكارًا مثل: + +$$ \begin{array}{ll} \mathbf{0} & \text{inactive process} \\ P \mid Q & \text{parallel composition} \\ x!(v) & \text{send a value on a channel} \\ ?\,(y \leftarrow x)\ P & \text{receive a value and continue as }P \end{array} $$ + +يوسع Tolang الحساب الأساسي بصورة تركيبية. ويضيف أحد هذه التوسيعات الصيغة السطحية + +$$ \mathbf{let}\ x\ \mathbf{in}\ P \qquad \text{fresh channel binding scoped over }P. $$ + +ينشئ هذا الربط قناة جديدة ويجعل اسمها ضمن نطاق $P$؛ ويسمي أدب حساب العمليات هذه العملية *التقييد*. ولا تتضمن النواة الانعكاسية عامل تقييد بدائيًا. راجع مرِديث ورادستوك، [*A Reflective Higher-order Calculus*](https://doi.org/10.1016/j.entcs.2005.05.016). + +قد تنفذ الآلة التشغيلية هذه العناصر باستخدام فضاء صفوف، وطوابير، وفهارس مطابقة، وسجلات متابعة، ومهام متزامنة. لكن تلك الآليات ليست تعريف اللغة. + +تحدد الطبقة الدلالية سلوك العملية القابل للملاحظة والقوانين البنيوية. وتشمل القوانين المرشحة للتركيب المتوازي الأساسي ما يلي: + +$$ \begin{aligned} P \mid \mathbf{0} &\equiv P \\ P \mid Q &\equiv Q \mid P \\ (P \mid Q) \mid R &\equiv P \mid (Q \mid R) \end{aligned} $$ + +قوانين امتداد الربط الجديد هذا منفصلة. وتشمل المخططات المرشحة التقليدية إعادة التسمية ألفا، وتبادل روابط متميزة، وإخراج النطاق: + +$$ \begin{aligned} \mathbf{let}\ x\ \mathbf{in}\ P &\equiv \mathbf{let}\ y\ \mathbf{in}\ P\{y/x\} && (y \mathrel{\#} P) \\ \mathbf{let}\ x\ \mathbf{in}\ (\mathbf{let}\ y\ \mathbf{in}\ P) &\equiv \mathbf{let}\ y\ \mathbf{in}\ (\mathbf{let}\ x\ \mathbf{in}\ P) && (x \ne y) \\ \mathbf{let}\ x\ \mathbf{in}\ (P \mid Q) &\equiv P \mid (\mathbf{let}\ x\ \mathbf{in}\ Q) && (x \notin \operatorname{FN}(P)) \end{aligned} $$ + +تعني $y \mathrel{\#} P$ هنا أن $y$ جديد بالنسبة إلى $P$، و$P\{y/x\}$ إعادة تسمية تتجنب حجب المتغيرات، و$\operatorname{FN}(P)$ مجموعة أسماء القنوات الحرة في $P$. ولا تصبح هذه المخططات قوانين إلا إذا صححها التكافؤ الرصدي المختار؛ فلا يجوز افتراضها من الصياغة السطحية أو استنتاجها من تخطيط واحد للشيفرة البايتية. + +## التطبيع بوصفه تحويلًا حافظًا للمعنى {#normalization-as-a-meaning-preserving-map} + +إذا اختلف برنامجا المصدر `s₁` و`s₂` في السكر النحوي المقبول وحده، فينبغي للتطبيع أن يصرح بمعناهما المشترك: + +$$ s_1 \equiv_{\mathsf{sugar}} s_2 \implies \operatorname{normalize}(s_1) = \operatorname{normalize}(s_2) $$ + +تشمل الالتزامات المفيدة الأخرى: + +* تحافظ إعادة التسمية ألفا على المعنى المعياري +* يحسم النطاق المعجمي الربط المقصود +* تبقى مواضع المصدر حين تتطلبها التشخيصات +* تُمحى الثوابت وقت الترجمة من دون سلوك وقت التشغيل +* تجمع الصياغة المعيبة التشخيصات وفق عقد المرحلة + +تتطلب بعض المشاريع قيمًا معيارية مطبّعة. ولا تتطلب مشاريع أخرى سوى التكافؤ الدلالي. صرّح بأيّهما تعتمد. + +## قدرات المراحل {#stage-capabilities} + +```admonish warning title="لا كائن مترجم شامل" +لا تجعل كائن مترجم ضخمًا واحدًا الواجهة الوحيدة للمراحل. +``` + +قد يحتاج المطبع إلى قدرات مثل: + +* قراءة نطاق الربط وتوسيعه +* حل أسماء المصدر +* تجميع التشخيصات +* إنشاء الحدود المعيارية + +وقد يحتاج مولّد الشيفرة إلى: + +* تخصيص مراجع تنفيذية +* إصدار التعليمات +* حل المتغيرات المعيارية +* إنهاء البنية التنفيذية + +عبّر عن مداخل المراحل بوصفها امتدادات لهذه القدرات. تخزن البيئات الملموسة الخرائط والساحات والعدادات والتشخيصات، لكنها لا تملك معنى المرحلة. + +```rust,noplayground +#[ext(name = NormalizeEntryExt)] +pub impl This +where + This: BindingScopeAlg + DiagnosticAlg + NormalizeRecAlg, +{ + fn normalize(&mut self, syntax: &Syntax) -> Result { + // initialize the semantic stage and invoke recursive normalization + } +} +``` + +تختلف أسماء القدرات الدقيقة بين المترجمات. المهم هو شكل الاعتماد الصريح وخريطة المراحل المستقرة. + +## يمكن أن يظل المحلل ووقت التشغيل تشغيليين {#parser-and-runtime-can-remain-operational} + +لا ينبغي فرض ترميز واحد على كل نظام فرعي. + +قد تهيمن آليات القواعد المولدة على المحلل. وقد تهيمن كفاءة التغيير والجدولة على الآلة الافتراضية. ويمكن أن يظلا تشغيليي البنية مع تنفيذهما حدودًا محددة جيدًا: + +| المرحلة | العقد | +| --- | --- | +| المحلل | ينتج `Syntax` | +| المطبع | ينتج `Core` حاملة للمعنى | +| مولد الشيفرة | يحافظ على المعنى في الصيغة التنفيذية | +| وقت التشغيل | ينتج ملاحظات متوافقة مع نموذج اللغة | + +لا يزيل التصميم الدلالي الآلات، بل يمنعها من التحول إلى دلالات اللغة من دون تصريح. + +## قوانين المترجم واختباراته {#compiler-laws-and-tests} + +تأتي الأدلة القوية من اتجاهات متعددة: + +* قوانين التطبيع على صيغ مصدر متكافئة +* رحلات ذهاب وإياب للتحليل والطباعة الجميلة حين تكون مقصودة +* مقارنة التقييم الدلالي المباشر بالتنفيذ المترجم +* تكافؤ الشيفرة البايتية حين يُوعَد بمخرجات معيارية +* سيناريوهات مطابقة وقت التشغيل +* اختبارات تفاضلية بين المفسرات + +```admonish warning title="مساواة البايتات ليست مساواة دلالية" +لا تخلط بين التطابق بايتًا ببايت والمساواة الدلالية. فمساواة البايتات خاصية أقوى مفيدة فقط عندما يكون التجميع المعياري جزءًا من المواصفة. +``` + +## كيف يهيئ هذا القارئ {#how-this-prepares-the-reader} + +عند قراءة تنفيذ لغة يبدأ بالمعنى، ابحث عن: + +* صياغة دلالية أو سمات قدرات +* عمليات تطبيع مشتقة +* عقود مراحل صريحة +* برامج أساسية من الرتبة الأولى +* قوانين للاستبدال والنطاق والتركيب +* بيئات خفيفة تفسر قدرات المراحل +* آليات المحلل والمترجم والآلة الافتراضية التشغيلية عند الأطراف + +تصل هذه الرؤية التصميم الدلالي العام بـ Tolang، وتوضح كيف توجه الحدود الدلالية تصميم اللغة وتجميعها وتفسيرها وقت التشغيل. diff --git a/src/rust-dd/compiler-pipelines.de.md b/src/rust-dd/compiler-pipelines.de.md new file mode 100644 index 0000000..9a59534 --- /dev/null +++ b/src/rust-dd/compiler-pipelines.de.md @@ -0,0 +1,196 @@ + + +# Sprach- und Compiler-Pipelines {#language-and-compiler-pipelines} + +```admonish tip title="Verwandte Themen" +Design by Meaning in Rust: [Programme erster Ordnung](first-order-programs.md), [Interpreter und Effekte](interpreters.md) +Concepts: [Operationale Semantik](../concepts/operational_semantics.md), [Defunktionalisierung](../concepts/defunctionalization.md) +Insights: [EVM-Algebra](../insights/evm-alg.md) +``` + +```admonish note title="Bedeutung ist nicht die Pipeline" +Ein Compiler ist am klarsten, wenn die Sprachbedeutung nicht mit Parserbäumen, Durchläufen, Bytecode oder der Maschinenschleife gleichgesetzt wird. Korrektheit ist ein kommutierendes Gesetz: Die Ausführung des kompilierten Programms muss mit seiner Denotation übereinstimmen. +``` + +Ein Compiler lässt sich am leichtesten durchdenken, wenn die Sprachbedeutung nicht mit Parserbäumen, Compiler-Durchläufen, Bytecode oder einer Schleife der virtuellen Maschine gleichgesetzt wird. + +Dieses Kapitel verwendet eine vereinfachte nebenläufige Sprache nach dem Vorbild von Tolang und konzentriert sich auf die semantische Architektur. + +## Vier verschiedene Ebenen {#four-distinct-layers} + +Halte diese Ebenen auseinander: + +1. Quellsyntax +2. Normalisierte Sprache +3. Ausführbare Repräsentation +4. Maschinenausführung + +Eine typische Pipeline sieht so aus: + +$$ \begin{aligned} \operatorname{Parse} &\colon \mathsf{Source} \to \mathsf{Syntax} \\ \operatorname{Normalize} &\colon \mathsf{Syntax} \to \operatorname{Result}(\mathsf{Core}, \mathsf{Diagnostics}) \\ \operatorname{CodeGen} &\colon \mathsf{Core} \to \operatorname{Result}(\mathsf{Executable}, \mathsf{Error}) \\ \operatorname{Run} &\colon \mathsf{Executable} \times \mathsf{RuntimeState} \to \mathsf{Observation} \end{aligned} $$ + +Die praktische Operation ist die Komposition: + +$$ \operatorname{Compile} = \operatorname{Parse}\mathbin{;}\operatorname{Normalize}\mathbin{;}\operatorname{CodeGen} $$ + +Die zusammengesetzte Hilfsfunktion ist nicht die semantische Definition jeder Stufe. + +## Syntax ist noch keine Bedeutung {#syntax-is-not-yet-meaning} + +Die Ausgabe eines Parsers spiegelt Entscheidungen der Grammatik wider: + +* Zeichensetzung +* syntaktische Vereinfachungen +* Vorrangregeln +* Quelltextbereiche +* generierte Parserrepräsentation + +Diese Fakten sind für Diagnosen und Werkzeuge wichtig, müssen aber nicht die Kernsprache definieren. + +Die Normalisierung beseitigt zufällige syntaktische Variation und führt eine kleinere Form ein, die Bedeutung trägt. Beispielsweise können mehrere oberflächliche Bindungsformen auf eine einzige Kernoperation zur Einschränkung normalisiert werden. + +**Viele Quellformen** → **ein normalisierter Konstruktor** + +Dadurch entsteht ein einzelner Ort, an dem spätere Gesetze für Compiler und Laufzeit festgelegt werden können. + +## Denotationelle und kompilierte Bedeutung {#denotational-and-compiled-meaning} + +Sei: + +$$ \llbracket - \rrbracket : Core \to D $$ + +Bedeutungen im semantischen Bereich `D` zuweisen. + +Die Kompilierung erzeugt ausführbare Werte: + +$$ compile : Core \to Executable $$ + +und die Ausführung beobachtet sie: + +$$ run : Executable \to D $$ + +Die zentrale Korrektheitsverpflichtung ist ein kommutierendes Diagramm: + +$$ \operatorname{run}(\operatorname{compile}(p)) = \llbracket p \rrbracket $$ + +Bei nichtdeterministischen oder nebenläufigen Systemen kann die Gleichheit eine beobachtungsbezogene Äquivalenz, eine Ergebnismenge, Spuräquivalenz oder Bisimilarität statt gewöhnlicher Wertgleichheit sein. Das semantische Modell muss diese Wahl treffen. + +## Bedeutung nebenläufiger Prozesse {#concurrent-process-meaning} + +Der grundlegende reflektive Kalkül umfasst Ideen wie: + +$$ \begin{array}{ll} \mathbf{0} & \text{inactive process} \\ P \mid Q & \text{parallel composition} \\ x!(v) & \text{send a value on a channel} \\ ?\,(y \leftarrow x)\ P & \text{receive a value and continue as }P \end{array} $$ + +Tolang erweitert den grundlegenden Kalkül auf kompositionale Weise. Eine solche Erweiterung fügt die Oberflächenform hinzu + +$$ \mathbf{let}\ x\ \mathbf{in}\ P \qquad \text{fresh channel binding scoped over }P. $$ + +Diese Bindung erzeugt einen frischen Kanal und beschränkt seinen Namen auf den Gültigkeitsbereich von $P$. In der Prozesskalkül-Literatur heißt diese Operation *restriction*. Der reflektive Kern besitzt keinen primitiven Restriktionsoperator. Siehe [*A Reflective Higher-order Calculus*](https://doi.org/10.1016/j.entcs.2005.05.016) von Meredith und Radestock. + +Die operationale Maschine kann dies mit einem Tupelraum, Warteschlangen, Matching-Indizes, Fortsetzungsdatensätzen und nebenläufigen Tasks implementieren. Diese Mechanismen definieren nicht die Sprache. + +Die semantische Ebene bestimmt das beobachtbare Prozessverhalten und strukturelle Gesetze. Zu den möglichen Gesetzen der parallelen Kernkomposition gehören: + +$$ \begin{aligned} P \mid \mathbf{0} &\equiv P \\ P \mid Q &\equiv Q \mid P \\ (P \mid Q) \mid R &\equiv P \mid (Q \mid R) \end{aligned} $$ + +Gesetze für diese Erweiterung um frische Bindungen sind davon getrennt. Übliche mögliche Schemata sind Alpha-Umbenennung, Vertauschung verschiedener Bindungen und Scope Extrusion: + +$$ \begin{aligned} \mathbf{let}\ x\ \mathbf{in}\ P &\equiv \mathbf{let}\ y\ \mathbf{in}\ P\{y/x\} && (y \mathrel{\#} P) \\ \mathbf{let}\ x\ \mathbf{in}\ (\mathbf{let}\ y\ \mathbf{in}\ P) &\equiv \mathbf{let}\ y\ \mathbf{in}\ (\mathbf{let}\ x\ \mathbf{in}\ P) && (x \ne y) \\ \mathbf{let}\ x\ \mathbf{in}\ (P \mid Q) &\equiv P \mid (\mathbf{let}\ x\ \mathbf{in}\ Q) && (x \notin \operatorname{FN}(P)) \end{aligned} $$ + +Hier bedeutet $y \mathrel{\#} P$, dass $y$ frisch bezüglich $P$ ist; $P\{y/x\}$ steht für eine Umbenennung unter Vermeidung von Variablenfang, und $\operatorname{FN}(P)$ ist die Menge der freien Kanalnamen in $P$. Diese Schemata werden nur dann zu Gesetzen, wenn die gewählte beobachtungsbezogene Äquivalenz sie bestätigt. Sie dürfen weder aus der Oberflächensyntax abgeleitet noch aus einem einzelnen Bytecode-Layout geschlossen werden. + +## Normalisierung als bedeutungserhaltende Abbildung {#normalization-as-a-meaning-preserving-map} + +Unterscheiden sich Quellprogramme `s₁` und `s₂` nur durch zugelassene syntaktische Vereinfachungen, sollte die Normalisierung ihre gemeinsame Bedeutung explizit machen: + +$$ s_1 \equiv_{\mathsf{sugar}} s_2 \implies \operatorname{normalize}(s_1) = \operatorname{normalize}(s_2) $$ + +Weitere nützliche Verpflichtungen sind: + +* Alpha-Umbenennung bewahrt die normalisierte Bedeutung +* Der lexikalische Gültigkeitsbereich löst Namen zum vorgesehenen Binder auf +* Quelltextpositionen bleiben erhalten, wenn Diagnosen sie benötigen +* Kompilierzeitkonstanten werden ohne Laufzeitverhalten entfernt +* Fehlerhafte Syntax sammelt Diagnosen gemäß dem Vertrag der jeweiligen Stufe + +Manche Projekte benötigen kanonische normalisierte Werte. Andere verlangen nur semantische Gleichwertigkeit. Gib an, was zutrifft. + +## Stufen-Capabilities {#stage-capabilities} + +```admonish warning title="Kein Alleskönner-Compilerobjekt" +Mache nicht ein einziges riesiges Compilerobjekt zur alleinigen Schnittstelle aller Stufen. +``` + +Ein Normalisierer kann Capabilities benötigen wie: + +* Bindungsbereich lesen und erweitern +* Quellnamen auflösen +* Diagnosen sammeln +* Normalisierte Terme konstruieren + +Ein Codegenerator kann Folgendes benötigen: + +* Ausführbare Referenzen zuweisen +* Instruktionen ausgeben +* Normalisierte Variablen auflösen +* Ausführbare Struktur abschließen + +Formuliere Stufeneinstiege als Erweiterungen über diese Capabilities. Konkrete Umgebungen speichern Maps, Arenen, Zähler und Diagnosen, besitzen aber nicht die Bedeutung der jeweiligen Stufe. + +```rust,noplayground +#[ext(name = NormalizeEntryExt)] +pub impl This +where + This: BindingScopeAlg + DiagnosticAlg + NormalizeRecAlg, +{ + fn normalize(&mut self, syntax: &Syntax) -> Result { + // initialize the semantic stage and invoke recursive normalization + } +} +``` + +Die genauen Capability-Namen unterscheiden sich je nach Compiler. Entscheidend sind explizite Abhängigkeiten und stabile Stufenübergänge. + +## Parser und Laufzeit dürfen operational geprägt bleiben {#parser-and-runtime-can-remain-operational} + +Nicht jedes Teilsystem muss in dieselbe Kodierung gezwungen werden. + +Ein Parser kann stark von generierten Grammatikmechanismen geprägt sein. Eine virtuelle Maschine kann vor allem auf effiziente Mutation und Ablaufplanung ausgelegt sein. Beide können operational geformt bleiben und zugleich klar definierte Grenzen implementieren: + +| Stufe | Vertrag | +| --- | --- | +| Parser | Erzeugt `Syntax` | +| Normalisierer | Erzeugt `Core`, das Bedeutung trägt | +| Codegenerator | Bewahrt die Bedeutung in der ausführbaren Form | +| Laufzeit | Erzeugt Beobachtungen, die mit dem Sprachmodell übereinstimmen | + +Denotational Design schafft Maschinen nicht ab. Es verhindert, dass Maschinen unbemerkt zur Sprachsemantik werden. + +## Compiler-Gesetze und Tests {#compiler-laws-and-tests} + +Starke Nachweise ergeben sich aus mehreren Richtungen: + +* Normalisierungsgesetze für äquivalente Quellformen +* Rundlauftests für Parsing und Pretty-Printing, sofern dies vorgesehen ist +* direkter semantischer Vergleich zwischen Auswertung und kompilierter Ausführung +* Bytecode-Äquivalenz, wenn kanonische Ausgabe zugesichert wird +* Konformitätsszenarien für die Laufzeit +* Differentialtests zwischen Interpretern + +```admonish warning title="Bytegleichheit ist keine semantische Gleichheit" +Verwechsle Byte-für-Byte-Gleichheit nicht mit semantischer Gleichheit. Bytegleichheit ist nur dann eine nützliche, stärkere Eigenschaft, wenn eine kanonische Kompilierung zur Spezifikation gehört. +``` + +## Wie dies die Leser vorbereitet {#how-this-prepares-the-reader} + +Achte beim Lesen einer bedeutungsorientierten Sprachimplementierung auf: + +* semantische Syntax oder Capability-Traits +* abgeleitete Normalisierungsoperationen +* explizite Verträge für die einzelnen Stufen +* Programme des Kerns erster Ordnung +* Gesetze zu Substitution, Gültigkeitsbereich und Komposition +* schlanke Umgebungen, die Stufen-Capabilities interpretieren +* operationale Mechanismen für Parser, Compiler und VM an den Grenzen + +Diese Perspektive verbindet allgemeines Denotational Design mit Tolang und zeigt, wie semantische Grenzen Sprachentwurf, Kompilierung und Laufzeitinterpretation leiten. diff --git a/src/rust-dd/compiler-pipelines.es.md b/src/rust-dd/compiler-pipelines.es.md new file mode 100644 index 0000000..3229abe --- /dev/null +++ b/src/rust-dd/compiler-pipelines.es.md @@ -0,0 +1,196 @@ + + +# Canalizaciones de lenguaje y compilador {#language-and-compiler-pipelines} + +```admonish tip title="Relacionado" +Diseño por significado en Rust: [Programas de primer orden](first-order-programs.md), [Intérpretes y efectos](interpreters.md) +Conceptos: [Semántica operacional](../concepts/operational_semantics.md), [Defuncionalización](../concepts/defunctionalization.md) +Perspectivas: [Álgebra de EVM](../insights/evm-alg.md) +``` + +```admonish note title="El significado no es la canalización" +Un compilador es más claro cuando el significado del lenguaje no se identifica con árboles del analizador, pasadas, bytecode o el bucle de máquina. La corrección es una ley de conmutación: ejecutar el programa compilado concuerda con la denotación del programa. +``` + +Es más fácil razonar sobre un compilador cuando el significado del lenguaje no se identifica con los árboles del analizador, las pasadas del compilador, el bytecode ni el bucle de una máquina virtual. + +Este capítulo utiliza un lenguaje concurrente simplificado inspirado en Tolang para centrarse en la arquitectura semántica. + +## Cuatro capas distintas {#four-distinct-layers} + +Mantén separadas estas capas: + +1. Sintaxis fuente +2. Lenguaje normalizado +3. Representación ejecutable +4. Ejecución de máquina + +Una canalización típica es: + +$$ \begin{aligned} \operatorname{Parse} &\colon \mathsf{Source} \to \mathsf{Syntax} \\ \operatorname{Normalize} &\colon \mathsf{Syntax} \to \operatorname{Result}(\mathsf{Core}, \mathsf{Diagnostics}) \\ \operatorname{CodeGen} &\colon \mathsf{Core} \to \operatorname{Result}(\mathsf{Executable}, \mathsf{Error}) \\ \operatorname{Run} &\colon \mathsf{Executable} \times \mathsf{RuntimeState} \to \mathsf{Observation} \end{aligned} $$ + +La operación de conveniencia es la composición: + +$$ \operatorname{Compile} = \operatorname{Parse}\mathbin{;}\operatorname{Normalize}\mathbin{;}\operatorname{CodeGen} $$ + +El auxiliar compuesto no es la definición semántica de cada fase. + +## La sintaxis aún no es significado {#syntax-is-not-yet-meaning} + +La salida del analizador refleja las decisiones gramaticales: + +* puntuación +* azúcar sintáctico +* precedencia +* fragmentos de texto fuente +* representación generada del analizador + +Estos aspectos importan para el diagnóstico y las herramientas, pero no tienen por qué definir el lenguaje central. + +La normalización elimina variaciones sintácticas accidentales e introduce una forma menor que porta significado. Por ejemplo, varias formas superficiales de enlace pueden normalizarse a una sola operación central de restricción. + +**Muchas formas fuente** → **un único constructor normalizado** + +Esto crea un lugar donde enunciar las leyes posteriores del compilador y del entorno de ejecución. + +## Significado denotacional y compilado {#denotational-and-compiled-meaning} + +Sea: + +$$ \llbracket - \rrbracket : Core \to D $$ + +asigna significados en el dominio semántico `D`. + +La compilación produce valores ejecutables: + +$$ compile : Core \to Executable $$ + +y la ejecución los observa: + +$$ run : Executable \to D $$ + +La obligación central de corrección es un diagrama conmutativo: + +$$ \operatorname{run}(\operatorname{compile}(p)) = \llbracket p \rrbracket $$ + +En sistemas no deterministas o concurrentes, la igualdad puede ser equivalencia observacional, un conjunto de resultados, equivalencia de trazas o bisimilaridad, y no una igualdad ordinaria de valores. El modelo semántico debe elegir. + +## Significado de los procesos concurrentes {#concurrent-process-meaning} + +El cálculo reflexivo básico incluye ideas como: + +$$ \begin{array}{ll} \mathbf{0} & \text{inactive process} \\ P \mid Q & \text{parallel composition} \\ x!(v) & \text{send a value on a channel} \\ ?\,(y \leftarrow x)\ P & \text{receive a value and continue as }P \end{array} $$ + +Tolang amplía el cálculo básico de manera composicional. Una extensión de ese tipo añade la forma superficial + +$$ \mathbf{let}\ x\ \mathbf{in}\ P \qquad \text{fresh channel binding scoped over }P. $$ + +Este enlace crea un canal nuevo y limita su nombre al ámbito $P$; la literatura sobre cálculos de procesos llama *restricción* a esta operación. El núcleo reflexivo no tiene un operador de restricción primitivo. Véase [*A Reflective Higher-order Calculus*](https://doi.org/10.1016/j.entcs.2005.05.016) de Meredith y Radestock. + +La máquina operacional puede implementarlos mediante un espacio de tuplas, colas, índices de coincidencia, registros de continuación y tareas concurrentes. Esos mecanismos no definen el lenguaje. + +La capa semántica identifica el comportamiento observable de los procesos y las leyes estructurales. Algunas leyes candidatas para la composición paralela central son: + +$$ \begin{aligned} P \mid \mathbf{0} &\equiv P \\ P \mid Q &\equiv Q \mid P \\ (P \mid Q) \mid R &\equiv P \mid (Q \mid R) \end{aligned} $$ + +Las leyes para esta extensión de enlace nuevo son independientes. Algunos esquemas candidatos habituales son el renombrado alfa, la conmutación de enlaces distintos y la extrusión de alcance: + +$$ \begin{aligned} \mathbf{let}\ x\ \mathbf{in}\ P &\equiv \mathbf{let}\ y\ \mathbf{in}\ P\{y/x\} && (y \mathrel{\#} P) \\ \mathbf{let}\ x\ \mathbf{in}\ (\mathbf{let}\ y\ \mathbf{in}\ P) &\equiv \mathbf{let}\ y\ \mathbf{in}\ (\mathbf{let}\ x\ \mathbf{in}\ P) && (x \ne y) \\ \mathbf{let}\ x\ \mathbf{in}\ (P \mid Q) &\equiv P \mid (\mathbf{let}\ x\ \mathbf{in}\ Q) && (x \notin \operatorname{FN}(P)) \end{aligned} $$ + +Aquí, $y \mathrel{\#} P$ significa que $y$ es nuevo respecto de $P$; $P\{y/x\}$ es un renombrado que evita la captura, y $\operatorname{FN}(P)$ es el conjunto de nombres de canal libres en $P$. Estos esquemas solo son leyes cuando la equivalencia observacional elegida los valida; no deben suponerse a partir de la sintaxis superficial ni inferirse de una disposición concreta de bytecode. + +## La normalización como aplicación que preserva significado {#normalization-as-a-meaning-preserving-map} + +Si los programas fuente `s₁` y `s₂` solo difieren por azúcar aceptado, la normalización debería hacer explícito su significado común: + +$$ s_1 \equiv_{\mathsf{sugar}} s_2 \implies \operatorname{normalize}(s_1) = \operatorname{normalize}(s_2) $$ + +Otras obligaciones útiles son: + +* el renombrado alfa preserva el significado normalizado +* el ámbito léxico resuelve al enlace previsto +* las posiciones fuente se conservan cuando los diagnósticos las requieren +* las constantes de compilación se eliminan sin comportamiento en tiempo de ejecución +* la sintaxis mal formada acumula diagnósticos según el contrato de la fase + +Algunos proyectos requieren valores normalizados canónicos. Otros solo exigen equivalencia semántica. Indica cuál de los dos casos aplica. + +## Capacidades de las etapas {#stage-capabilities} + +```admonish warning title="Evita el compilador omnipotente" +No conviertas un único objeto de compilador gigantesco en la única interfaz de las etapas. +``` + +Un normalizador puede necesitar capacidades como: + +* Leer y ampliar el ámbito de vinculaciones +* Resolver nombres del código fuente +* Acumular diagnósticos +* Construir términos normalizados + +Un generador de código puede necesitar: + +* Asignar referencias ejecutables +* Emitir instrucciones +* Resolver variables normalizadas +* Finalizar la estructura ejecutable + +Expresa las entradas de cada etapa como extensiones de estas capacidades. Los entornos concretos almacenan mapas, arenas, contadores y diagnósticos, pero no son dueños del significado de la etapa. + +```rust,noplayground +#[ext(name = NormalizeEntryExt)] +pub impl This +where + This: BindingScopeAlg + DiagnosticAlg + NormalizeRecAlg, +{ + fn normalize(&mut self, syntax: &Syntax) -> Result { + // initialize the semantic stage and invoke recursive normalization + } +} +``` + +Los nombres precisos de las capacidades varían según el compilador. Lo importante es explicitar las dependencias y mantener un mapa estable de las etapas. + +## El analizador y el entorno de ejecución pueden conservar su forma operativa {#parser-and-runtime-can-remain-operational} + +No es necesario obligar a todos los subsistemas a usar la misma codificación. + +Un analizador puede depender principalmente de la maquinaria de gramática generada. Una máquina virtual puede depender de la mutación eficiente y la planificación. Pueden conservar su forma operativa y, aun así, implementar límites bien definidos: + +| Etapa | Contrato | +| --- | --- | +| Analizador | Produce `Syntax` | +| Normalizador | Produce `Core` portador de significado | +| Generador de código | Preserva el significado en la forma ejecutable | +| Entorno de ejecución | Produce observaciones coherentes con el modelo del lenguaje | + +El diseño denotacional no elimina las máquinas. Evita que las máquinas se conviertan silenciosamente en la semántica del lenguaje. + +## Leyes y pruebas del compilador {#compiler-laws-and-tests} + +Las pruebas más sólidas proceden de varias fuentes: + +* leyes de normalización para formas fuente equivalentes +* conversiones de ida y vuelta entre análisis y formato legible, cuando corresponda +* comparación de la evaluación semántica directa con la ejecución compilada +* equivalencia de bytecode cuando se promete una salida canónica +* escenarios de conformidad del entorno de ejecución +* pruebas diferenciales entre intérpretes + +```admonish warning title="La igualdad de bytes no es igualdad semántica" +No confundas la igualdad byte a byte con la igualdad semántica. La igualdad de bytes es una propiedad más estricta y útil solo cuando la compilación canónica forma parte de la especificación. +``` + +## Cómo prepara al lector {#how-this-prepares-the-reader} + +Al leer una implementación de lenguaje guiada por el significado, busca: + +* sintaxis semántica o rasgos de capacidades +* operaciones de normalización derivadas +* contratos explícitos para las etapas +* programas centrales de primer orden +* leyes de sustitución, ámbito y composición +* entornos delgados que interpretan capacidades de las etapas +* maquinaria operativa de análisis, compilador y máquina virtual en los extremos + +Esta perspectiva conecta el diseño denotacional con Tolang y muestra cómo los límites semánticos guían el diseño del lenguaje, la compilación y la interpretación durante la ejecución. diff --git a/src/rust-dd/compiler-pipelines.ja.md b/src/rust-dd/compiler-pipelines.ja.md new file mode 100644 index 0000000..be19597 --- /dev/null +++ b/src/rust-dd/compiler-pipelines.ja.md @@ -0,0 +1,196 @@ + + +# 言語とコンパイラーパイプライン {#language-and-compiler-pipelines} + +```admonish tip title="関連項目" +Rustで意味から設計する:[一階プログラム](first-order-programs.md)、[インタープリターと副作用](interpreters.md) +概念:[操作的意味論](../concepts/operational_semantics.md)、[関数のデファンクショナライズ](../concepts/defunctionalization.md) +洞察:[EVM代数](../insights/evm-alg.md) +``` + +```admonish note title="意味はパイプラインではない" +言語の意味をパーサー木、パス、バイトコード、機械ループと同一視しないほうが、コンパイラーは明確になります。正しさは、一つの可換法則で表せます。コンパイル済みプログラムを実行した結果が、そのプログラムの表示に一致することです。 +``` + +言語の意味をパーサー木、コンパイラーパス、バイトコード、仮想マシンループと同一視しないほうが、コンパイラーを推論しやすくなります。 + +この章では、Tolangに似せた簡略化した並行言語を使い、意味論的なアーキテクチャに焦点を当てます。 + +## 四つの異なる層 {#four-distinct-layers} + +これらの層を分けてください。 + +1. ソース構文 +2. 正規化された言語 +3. 実行可能な表現 +4. 機械での実行 + +典型的なパイプライン: + +$$ \begin{aligned} \operatorname{Parse} &\colon \mathsf{Source} \to \mathsf{Syntax} \\ \operatorname{Normalize} &\colon \mathsf{Syntax} \to \operatorname{Result}(\mathsf{Core}, \mathsf{Diagnostics}) \\ \operatorname{CodeGen} &\colon \mathsf{Core} \to \operatorname{Result}(\mathsf{Executable}, \mathsf{Error}) \\ \operatorname{Run} &\colon \mathsf{Executable} \times \mathsf{RuntimeState} \to \mathsf{Observation} \end{aligned} $$ + +利便性のための操作は合成です。 + +$$ \operatorname{Compile} = \operatorname{Parse}\mathbin{;}\operatorname{Normalize}\mathbin{;}\operatorname{CodeGen} $$ + +合成されたヘルパーが各段階の意味論的な定義になるわけではありません。 + +## 構文はまだ意味ではない {#syntax-is-not-yet-meaning} + +パーサーの出力は文法上の選択を反映します。 + +* 句読点 +* 糖衣構文 +* 優先順位 +* ソース位置 +* 生成されたパーサー表現 + +これらは診断やツールにとって重要ですが、中核言語を定義する必要はありません。 + +正規化では、偶発的な構文上の違いを取り除き、意味を担うより小さな形式を導入します。たとえば、表層での複数の束縛形式を一つの中核的な制約操作に正規化できます。 + +**多数のソース形式** → **正規化後の一つの構成子** + +こうすることで、後続するコンパイラーとランタイムの法則を述べる場所が一つに定まります。 + +## 表示上の意味とコンパイル後の意味 {#denotational-and-compiled-meaning} + +次のように置きます。 + +$$ \llbracket - \rrbracket : Core \to D $$ + +意味論的領域`D`で意味を割り当てる。 + +コンパイルで実行可能な値を生成する。 + +$$ compile : Core \to Executable $$ + +実行時にそれらを観測する。 + +$$ run : Executable \to D $$ + +中心となる正しさの責務は可換図式です。 + +$$ \operatorname{run}(\operatorname{compile}(p)) = \llbracket p \rrbracket $$ + +非決定的または並行システムでは、等値性に通常の値の一致ではなく、観測的等価性、結果集合、トレース等価性、双模倣性を使う場合があります。どれを使うかは意味論モデルで選びます。 + +## 並行プロセスの意味 {#concurrent-process-meaning} + +基本となる反射計算には、次のような考え方が含まれます。 + +$$ \begin{array}{ll} \mathbf{0} & \text{inactive process} \\ P \mid Q & \text{parallel composition} \\ x!(v) & \text{send a value on a channel} \\ ?\,(y \leftarrow x)\ P & \text{receive a value and continue as }P \end{array} $$ + +Tolangは基本計算を合成的に拡張します。その拡張の一つは、次の表層形式を追加します。 + +$$ \mathbf{let}\ x\ \mathbf{in}\ P \qquad \text{fresh channel binding scoped over }P. $$ + +この束縛は新しいチャネルを作成し、その名前の有効範囲を$P$内に定めます。プロセス計算の文献では、この操作を*制約*と呼びます。反射的な中核には基本的な制約演算子はありません。MeredithとRadestockの[*A Reflective Higher-order Calculus*](https://doi.org/10.1016/j.entcs.2005.05.016)を参照してください。 + +操作機械では、タプル空間、キュー、照合用インデックス、継続レコード、並行タスクなどで実装できます。そうした仕組みが言語の定義になるわけではありません。 + +意味論層では、観測可能なプロセスの振る舞いと構造法則を特定します。中核となる並列合成には、次の法則が候補となります。 + +$$ \begin{aligned} P \mid \mathbf{0} &\equiv P \\ P \mid Q &\equiv Q \mid P \\ (P \mid Q) \mid R &\equiv P \mid (Q \mid R) \end{aligned} $$ + +新規束縛の拡張に関する法則は別途扱います。標準的な候補スキーマとして、α変換、異なる束縛の交換、有効範囲の押し出しがあります。 + +$$ \begin{aligned} \mathbf{let}\ x\ \mathbf{in}\ P &\equiv \mathbf{let}\ y\ \mathbf{in}\ P\{y/x\} && (y \mathrel{\#} P) \\ \mathbf{let}\ x\ \mathbf{in}\ (\mathbf{let}\ y\ \mathbf{in}\ P) &\equiv \mathbf{let}\ y\ \mathbf{in}\ (\mathbf{let}\ x\ \mathbf{in}\ P) && (x \ne y) \\ \mathbf{let}\ x\ \mathbf{in}\ (P \mid Q) &\equiv P \mid (\mathbf{let}\ x\ \mathbf{in}\ Q) && (x \notin \operatorname{FN}(P)) \end{aligned} $$ + +ここで$y \mathrel{\#} P$は$P$に対して$y$が新鮮であること、$P\{y/x\}$は変数捕獲を避ける置換、$\operatorname{FN}(P)$は$P$に含まれる自由なチャネル名の集合を表します。これらのスキーマが法則になるのは、選択した観測的等価性で妥当と認められる場合だけです。表層構文から自動的に前提したり、一つのバイトコードレイアウトから推論したりしてはいけません。 + +## 意味を保持する写像としての正規化 {#normalization-as-a-meaning-preserving-map} + +二つのソースプログラム`s₁`と`s₂`が、認められた糖衣構文だけで異なるなら、正規化によって共通の意味を明示できるべきです。 + +$$ s_1 \equiv_{\mathsf{sugar}} s_2 \implies \operatorname{normalize}(s_1) = \operatorname{normalize}(s_2) $$ + +ほかにも、次の責務が有用です。 + +* α変換で正規化後の意味が保持される +* 字句スコープで意図した束縛子が解決される +* 診断に必要な場合にソース位置が保持される +* コンパイル時定数が実行時の振る舞いなしに消去される +* 不正な構文について、段階の契約に従って診断が蓄積される + +正規化後の値に正準形を求めるプロジェクトもあれば、意味論的等価性だけを求めるプロジェクトもあります。どちらかを明示します。 + +## 段階のケイパビリティ {#stage-capabilities} + +```admonish warning title="万能なコンパイラーオブジェクトを作らない" +巨大なコンパイラーオブジェクトを、唯一の段階インターフェースにしてはいけません。 +``` + +正規化器には、次のようなケイパビリティが必要かもしれません。 + +* 束縛スコープの読み取りと拡張 +* ソース名の解決 +* 診断の蓄積 +* 正規化された項の構築 + +コード生成器には、次のものが必要かもしれません。 + +* 実行可能参照の割り当て +* 命令の出力 +* 正規化された変数の解決 +* 実行可能構造の確定 + +各段階の入り口をケイパビリティ上の拡張として表します。具体的な環境はマップ、アリーナ、カウンター、診断を保持しますが、段階の意味を所有しません。 + +```rust,noplayground +#[ext(name = NormalizeEntryExt)] +pub impl This +where + This: BindingScopeAlg + DiagnosticAlg + NormalizeRecAlg, +{ + fn normalize(&mut self, syntax: &Syntax) -> Result { + // initialize the semantic stage and invoke recursive normalization + } +} +``` + +正確なケイパビリティ名はコンパイラーごとに異なります。重要なのは、依存関係が明示され、段階間の対応が安定していることです。 + +## パーサーとランタイムは操作的な設計のままでよい {#parser-and-runtime-can-remain-operational} + +すべてのサブシステムに同じ符号化を無理に適用する必要はありません。 + +パーサーは生成文法の仕組みが中心になることがあります。仮想マシンは効率的な変更とスケジューリングが中心になることがあります。十分に定義された境界を実装する限り、操作的な形のままで構いません。 + +| 段階 | 契約 | +| --- | --- | +| パーサー | `Syntax`を生成する | +| 正規化器 | 意味を担う`Core`を生成する | +| コード生成器 | 実行可能形式で意味を保持する | +| ランタイム | 言語モデルと一貫した観測を生成する | + +Denotational Designは機械を取り除くのではなく、機械が言語の意味論を暗黙に定めるのを防ぎます。 + +## コンパイラーの法則とテスト {#compiler-laws-and-tests} + +強い証拠は複数の方向から得られます。 + +* 同等なソース形式に対する正規化法則 +* 意図する場合の構文解析と整形表示の往復 +* 直接的な意味評価とコンパイル後の実行の比較 +* 正準出力を保証する場合のバイトコード等価性 +* ランタイム適合性シナリオ +* インタープリター間の差分テスト + +```admonish warning title="バイトの一致は意味の一致ではない" +バイト単位の一致と意味論的等価性を混同しないでください。正準コンパイルが仕様に含まれる場合に限り、バイト一致は有用な、より強い性質です。 +``` + +## この内容が読者に与える準備 {#how-this-prepares-the-reader} + +意味を第一に考える言語実装を読むときは、次の点に注目します。 + +* 意味論的構文またはケイパビリティトレイト +* 導出される正規化操作 +* 明示的な段階契約 +* 一階の中核プログラム +* 置換、スコープ、合成に関する法則 +* 段階のケイパビリティを解釈する薄い環境 +* 端に置かれた操作的なパーサー、コンパイラー、VMの仕組み + +この見方を使うと、一般的なDenotational DesignとTolangを結び付け、意味論上の境界が言語設計、コンパイル、ランタイム解釈をどう導くかを理解できます。 diff --git a/src/rust-dd/compiler-pipelines.ko.md b/src/rust-dd/compiler-pipelines.ko.md new file mode 100644 index 0000000..a2d1677 --- /dev/null +++ b/src/rust-dd/compiler-pipelines.ko.md @@ -0,0 +1,196 @@ + + +# 언어와 컴파일러 파이프라인 {#language-and-compiler-pipelines} + +```admonish tip title="관련 항목" +Rust에서 의미로 설계하기: [일차 프로그램](first-order-programs.md), [인터프리터와 효과](interpreters.md) +개념: [작동 의미론](../concepts/operational_semantics.md), [디펑셔널라이제이션](../concepts/defunctionalization.md) +통찰: [EVM 대수](../insights/evm-alg.md) +``` + +```admonish note title="의미는 파이프라인이 아닙니다" +언어의 의미를 파서 트리, 컴파일러 패스, 바이트코드, 기계 루프와 동일시하지 않으면 컴파일러를 더 명확하게 이해할 수 있습니다. 정확성은 하나의 가환 법칙입니다. 컴파일된 프로그램의 실행이 프로그램의 표시와 일치해야 합니다. +``` + +언어의 의미를 파서 트리, 컴파일러 패스, 바이트코드, 가상 머신 루프와 동일시하지 않을 때 컴파일러를 가장 쉽게 추론할 수 있습니다. + +이 장에서는 의미론적 구조에 초점을 맞추기 위해 Tolang과 유사한 단순화된 동시성 언어를 사용합니다. + +## 서로 다른 네 계층 {#four-distinct-layers} + +다음 계층을 구분하세요: + +1. 소스 구문 +2. 정규화 언어 +3. 실행 가능한 표현 +4. 기계 실행 + +일반적인 파이프라인은 다음과 같습니다: + +$$ \begin{aligned} \operatorname{Parse} &\colon \mathsf{Source} \to \mathsf{Syntax} \\ \operatorname{Normalize} &\colon \mathsf{Syntax} \to \operatorname{Result}(\mathsf{Core}, \mathsf{Diagnostics}) \\ \operatorname{CodeGen} &\colon \mathsf{Core} \to \operatorname{Result}(\mathsf{Executable}, \mathsf{Error}) \\ \operatorname{Run} &\colon \mathsf{Executable} \times \mathsf{RuntimeState} \to \mathsf{Observation} \end{aligned} $$ + +편의 연산은 합성입니다: + +$$ \operatorname{Compile} = \operatorname{Parse}\mathbin{;}\operatorname{Normalize}\mathbin{;}\operatorname{CodeGen} $$ + +합성된 헬퍼가 각 단계의 의미 정의는 아닙니다. + +## 구문은 아직 의미가 아닙니다 {#syntax-is-not-yet-meaning} + +파서 출력은 문법 선택을 반영합니다: + +* 구두점 +* 문법적 편의 구문 +* 우선순위 +* 소스 구간 +* 생성된 파서 표현 + +이 정보는 진단과 도구에 중요하지만 핵심 언어를 정의할 필요는 없습니다. + +정규화는 우연한 구문 차이를 없애고 의미를 담는 더 작은 형태를 도입합니다. 예를 들어 여러 표면 바인딩 형식이 하나의 핵심 제한 연산으로 정규화될 수 있습니다. + +**여러 소스 형식** → **정규화 생성자 하나** + +이를 통해 후속 컴파일러 및 런타임 법칙을 명시할 단일 지점이 생깁니다. + +## 표시적 의미와 컴파일된 의미 {#denotational-and-compiled-meaning} + +다음을 정의합시다: + +$$ \llbracket - \rrbracket : Core \to D $$ + +의미론적 영역 `D`에 의미를 부여합니다. + +컴파일은 실행 가능한 값을 생성합니다: + +$$ compile : Core \to Executable $$ + +실행은 그 값을 관찰합니다: + +$$ run : Executable \to D $$ + +핵심 정확성 의무는 가환 다이어그램입니다: + +$$ \operatorname{run}(\operatorname{compile}(p)) = \llbracket p \rrbracket $$ + +비결정적 또는 동시성 시스템에서는 일반 값 동등성이 아니라 관찰적 동치, 결과 집합, 실행 기록 동치, 쌍방향 시뮬레이션 동치가 사용될 수 있습니다. 무엇을 쓸지는 의미 모델이 정해야 합니다. + +## 동시 프로세스의 의미 {#concurrent-process-meaning} + +기본 반사 계산에는 다음과 같은 개념이 포함됩니다: + +$$ \begin{array}{ll} \mathbf{0} & \text{inactive process} \\ P \mid Q & \text{parallel composition} \\ x!(v) & \text{send a value on a channel} \\ ?\,(y \leftarrow x)\ P & \text{receive a value and continue as }P \end{array} $$ + +Tolang은 기본 계산을 합성적으로 확장합니다. 그 확장 중 하나는 다음 표면 형식을 추가합니다 + +$$ \mathbf{let}\ x\ \mathbf{in}\ P \qquad \text{fresh channel binding scoped over }P. $$ + +이 바인딩은 새로운 채널을 만들고 그 이름의 범위를 $P$ 위로 제한합니다. 프로세스 계산 문헌에서는 이 연산을 *제한*이라고 부릅니다. 반사형 핵심에는 기본 제한 연산자가 없습니다. Meredith와 Radestock의 [*A Reflective Higher-order Calculus*](https://doi.org/10.1016/j.entcs.2005.05.016)을 참고하세요. + +작동 기계는 튜플 공간, 큐, 매칭 인덱스, 연속 실행 기록, 동시 태스크로 이를 구현할 수 있습니다. 그런 기제가 언어의 정의는 아닙니다. + +의미 계층은 관찰 가능한 프로세스 동작과 구조 법칙을 식별합니다. 핵심 병렬 합성의 후보 법칙은 다음과 같습니다: + +$$ \begin{aligned} P \mid \mathbf{0} &\equiv P \\ P \mid Q &\equiv Q \mid P \\ (P \mid Q) \mid R &\equiv P \mid (Q \mid R) \end{aligned} $$ + +새 바인딩 확장의 법칙은 별도입니다. 전통적인 후보 스키마에는 알파 변환, 서로 다른 바인딩의 교환, 범위 확장이 포함됩니다: + +$$ \begin{aligned} \mathbf{let}\ x\ \mathbf{in}\ P &\equiv \mathbf{let}\ y\ \mathbf{in}\ P\{y/x\} && (y \mathrel{\#} P) \\ \mathbf{let}\ x\ \mathbf{in}\ (\mathbf{let}\ y\ \mathbf{in}\ P) &\equiv \mathbf{let}\ y\ \mathbf{in}\ (\mathbf{let}\ x\ \mathbf{in}\ P) && (x \ne y) \\ \mathbf{let}\ x\ \mathbf{in}\ (P \mid Q) &\equiv P \mid (\mathbf{let}\ x\ \mathbf{in}\ Q) && (x \notin \operatorname{FN}(P)) \end{aligned} $$ + +여기서 $y \mathrel{\#} P$는 $P$에 대해 $y$가 새로운 이름이라는 뜻이고, $P\{y/x\}$는 변수 포획을 피하는 이름 변경이며, $P$는 $\operatorname{FN}(P)$의 자유 채널 이름 집합입니다. 선택한 관찰적 동치가 검증할 때에만 이 스키마가 법칙이 됩니다. 표면 구문에서 당연시하거나 특정 바이트코드 배치에서 추론해서는 안 됩니다. + +## 의미를 보존하는 사상으로서의 정규화 {#normalization-as-a-meaning-preserving-map} + +소스 프로그램 `s₁`과 `s₂`이 허용된 문법적 편의 구문만 다르다면, 정규화는 공통 의미를 명확히 드러내야 합니다: + +$$ s_1 \equiv_{\mathsf{sugar}} s_2 \implies \operatorname{normalize}(s_1) = \operatorname{normalize}(s_2) $$ + +다른 유용한 의무는 다음과 같습니다: + +* 알파 변환이 정규화된 의미를 보존함 +* 어휘 범위가 의도된 바인더로 해석됨 +* 진단에 필요한 소스 위치가 보존됨 +* 컴파일 시간 상수가 런타임 동작 없이 제거됨 +* 잘못된 구문에서 단계 계약에 따라 진단이 누적됨 + +정규화된 값의 표준형이 필요한 프로젝트도 있고, 의미론적 동등성만 필요한 프로젝트도 있습니다. 어느 쪽인지 명시하세요. + +## 단계 케이퍼빌리티 {#stage-capabilities} + +```admonish warning title="만능 컴파일러 객체는 금물" +거대한 컴파일러 객체 하나만을 단계 인터페이스로 만들지 마세요. +``` + +정규화기에는 다음과 같은 케이퍼빌리티가 필요할 수 있습니다: + +* 바인딩 범위 읽기 및 확장 +* 소스 이름 확인 +* 진단 누적 +* 정규화된 항 구성 + +코드 생성기에는 다음이 필요할 수 있습니다: + +* 실행 가능 참조 할당 +* 명령어 출력 +* 정규화된 변수 확인 +* 실행 구조 확정 + +단계 진입점은 이러한 케이퍼빌리티에 대한 확장으로 표현하세요. 구체 환경은 맵, 아레나, 카운터, 진단을 저장하지만 단계 의미를 소유하지는 않습니다. + +```rust,noplayground +#[ext(name = NormalizeEntryExt)] +pub impl This +where + This: BindingScopeAlg + DiagnosticAlg + NormalizeRecAlg, +{ + fn normalize(&mut self, syntax: &Syntax) -> Result { + // initialize the semantic stage and invoke recursive normalization + } +} +``` + +정확한 케이퍼빌리티 이름은 컴파일러마다 다릅니다. 중요한 점은 의존성이 명시되고 단계 사상이 안정적이라는 것입니다. + +## 파서와 런타임은 작동 방식에 따라 구성할 수 있습니다 {#parser-and-runtime-can-remain-operational} + +모든 하위 시스템을 동일한 인코딩으로 강제할 필요는 없습니다. + +파서는 생성된 문법 장치가 중심일 수 있습니다. 가상 머신은 효율적인 변경과 스케줄링이 중심일 수 있습니다. 이들은 작동 방식에 맞춘 채로 다음과 같이 명확한 경계를 구현할 수 있습니다: + +| 단계 | 계약 | +| --- | --- | +| 파서 | `Syntax` 생성 | +| 정규화기 | 의미를 담는 `Core` 생성 | +| 코드 생성기 | 실행 형식에서도 의미를 보존 | +| 런타임 | 언어 모델과 일치하는 관찰을 생성 | + +표시적 설계가 기계를 없애는 것은 아닙니다. 기계가 소리 없이 언어 의미론이 되는 것을 막습니다. + +## 컴파일러 법칙과 테스트 {#compiler-laws-and-tests} + +강한 증거는 여러 방향에서 확보합니다: + +* 동등한 소스 형태 사이의 정규화 법칙 +* 의도된 경우 파싱과 예쁘게 출력하기 사이의 왕복 검사 +* 직접 의미 평가와 컴파일된 실행 비교 +* 표준 출력을 약속한 경우의 바이트코드 동등성 +* 런타임 적합성 시나리오 +* 인터프리터 간 차등 테스트 + +```admonish warning title="바이트 동등성은 의미 동등성이 아닙니다" +바이트 단위 동등성을 의미론적 동등성과 혼동하지 마세요. 정규 컴파일이 명세에 포함될 때만 바이트 동등성이 더 강한 유용한 속성입니다. +``` + +## 이 내용을 읽는 방법 {#how-this-prepares-the-reader} + +의미 우선 언어 구현을 읽을 때 다음을 살펴보세요: + +* 의미 구문 또는 케이퍼빌리티 트레이트 +* 파생 정규화 연산 +* 명시적 단계 계약 +* 일차 핵심 프로그램 +* 치환, 범위, 합성 법칙 +* 단계 케이퍼빌리티를 해석하는 얇은 환경 +* 가장자리에 있는 작동 파서, 컴파일러, 가상 머신 장치 + +이 관점은 일반적인 표시적 설계와 Tolang을 연결해 의미론적 경계가 언어 설계, 컴파일, 런타임 해석을 어떻게 이끄는지 보여 줍니다. diff --git a/src/rust-dd/compiler-pipelines.ru.md b/src/rust-dd/compiler-pipelines.ru.md new file mode 100644 index 0000000..ae51d78 --- /dev/null +++ b/src/rust-dd/compiler-pipelines.ru.md @@ -0,0 +1,196 @@ + + +# Язык и конвейеры компилятора {#language-and-compiler-pipelines} + +```admonish tip title="Связанные материалы" +«Проектирование на основе смысла в Rust»: [Программы первого порядка](first-order-programs.md), [Интерпретаторы и эффекты](interpreters.md) +«Понятия»: [Операционная семантика](../concepts/operational_semantics.md), [Дефункционализация](../concepts/defunctionalization.md) +«Идеи»: [Алгебра EVM](../insights/evm-alg.md) +``` + +```admonish note title="Смысл — не конвейер" +Компилятор проще понять, если не отождествлять смысл языка с деревьями разбора, проходами, байткодом или циклом машины. Корректность выражается одним коммутативным законом: выполнение скомпилированной программы должно соответствовать её денотации. +``` + +О языке проще рассуждать, если его смысл не отождествляется с деревьями разбора, проходами компилятора, байткодом или циклом виртуальной машины. + +В этой главе используется упрощённый параллельный язык на основе Tolang, чтобы сосредоточиться на семантической архитектуре. + +## Четыре отдельных слоя {#four-distinct-layers} + +Разделяйте эти слои: + +1. Синтаксис исходного языка +2. Нормализованный язык +3. Исполняемое представление +4. Выполнение машиной + +Типичный конвейер выглядит так: + +$$ \begin{aligned} \operatorname{Parse} &\colon \mathsf{Source} \to \mathsf{Syntax} \\ \operatorname{Normalize} &\colon \mathsf{Syntax} \to \operatorname{Result}(\mathsf{Core}, \mathsf{Diagnostics}) \\ \operatorname{CodeGen} &\colon \mathsf{Core} \to \operatorname{Result}(\mathsf{Executable}, \mathsf{Error}) \\ \operatorname{Run} &\colon \mathsf{Executable} \times \mathsf{RuntimeState} \to \mathsf{Observation} \end{aligned} $$ + +Составная операция — это композиция: + +$$ \operatorname{Compile} = \operatorname{Parse}\mathbin{;}\operatorname{Normalize}\mathbin{;}\operatorname{CodeGen} $$ + +Составной вспомогательный метод не является семантическим определением каждого этапа. + +## Синтаксис ещё не означает смысл {#syntax-is-not-yet-meaning} + +Результат разбора отражает решения грамматики: + +* пунктуацию +* синтаксический сахар +* приоритет операций +* позиции в исходном тексте +* представление, созданное генератором парсера + +Эти факты важны для диагностики и инструментов, но им не обязательно определять ядро языка. + +Нормализация устраняет случайные синтаксические различия и вводит более компактную форму, несущую смысл. Например, несколько поверхностных форм связывания можно нормализовать до одной базовой операции ограничения области действия. + +**Несколько форм исходного кода** → **одна нормализованная конструкция** + +Так появляется единое место для формулировки законов следующих этапов компилятора и среды выполнения. + +## Денотационный и скомпилированный смысл {#denotational-and-compiled-meaning} + +Обозначим: + +$$ \llbracket - \rrbracket : Core \to D $$ + +назначить смыслы в семантической области `D`. + +Компиляция создаёт исполняемые значения: + +$$ compile : Core \to Executable $$ + +а выполнение позволяет наблюдать их: + +$$ run : Executable \to D $$ + +Главное обязательство корректности — коммутативная диаграмма: + +$$ \operatorname{run}(\operatorname{compile}(p)) = \llbracket p \rrbracket $$ + +Для недетерминированных или параллельных систем вместо обычного равенства значений может потребоваться контекстная эквивалентность, множество результатов, эквивалентность трасс или бисимилярность. Это выбирает семантическая модель. + +## Смысл параллельного процесса {#concurrent-process-meaning} + +Базовое рефлексивное исчисление включает такие понятия, как: + +$$ \begin{array}{ll} \mathbf{0} & \text{inactive process} \\ P \mid Q & \text{parallel composition} \\ x!(v) & \text{send a value on a channel} \\ ?\,(y \leftarrow x)\ P & \text{receive a value and continue as }P \end{array} $$ + +Tolang композиционно расширяет базовое исчисление. Одно из расширений добавляет поверхностную форму + +$$ \mathbf{let}\ x\ \mathbf{in}\ P \qquad \text{fresh channel binding scoped over }P. $$ + +Это связывание создаёт новый канал и ограничивает областью $P$ его имени; в литературе по исчислению процессов эта операция называется *ограничением*. В рефлексивном ядре нет примитивного оператора ограничения. См. работу Мередита и Радестока [*«Рефлексивное исчисление высшего порядка»*](https://doi.org/10.1016/j.entcs.2005.05.016). + +Операционная машина может реализовать это с помощью пространства кортежей, очередей, индексов сопоставления, записей продолжений и параллельных задач. Эти механизмы не являются определением языка. + +Семантический слой определяет наблюдаемое поведение процесса и структурные законы. Возможные законы для базовой параллельной композиции: + +$$ \begin{aligned} P \mid \mathbf{0} &\equiv P \\ P \mid Q &\equiv Q \mid P \\ (P \mid Q) \mid R &\equiv P \mid (Q \mid R) \end{aligned} $$ + +Законы для расширения со свежим связыванием формулируются отдельно. Среди обычных схем-кандидатов — переименование альфа, перестановка различных связываний и вынесение области действия: + +$$ \begin{aligned} \mathbf{let}\ x\ \mathbf{in}\ P &\equiv \mathbf{let}\ y\ \mathbf{in}\ P\{y/x\} && (y \mathrel{\#} P) \\ \mathbf{let}\ x\ \mathbf{in}\ (\mathbf{let}\ y\ \mathbf{in}\ P) &\equiv \mathbf{let}\ y\ \mathbf{in}\ (\mathbf{let}\ x\ \mathbf{in}\ P) && (x \ne y) \\ \mathbf{let}\ x\ \mathbf{in}\ (P \mid Q) &\equiv P \mid (\mathbf{let}\ x\ \mathbf{in}\ Q) && (x \notin \operatorname{FN}(P)) \end{aligned} $$ + +Здесь $y \mathrel{\#} P$ означает, что $y$ не встречается в $P$, $P\{y/x\}$ — переименование, избежавшее захвата, а $\operatorname{FN}(P)$ — множество свободных имён каналов в $P$. Эти схемы становятся законами лишь тогда, когда выбранная контекстная эквивалентность их подтверждает. Их нельзя считать верными только на основании поверхностного синтаксиса или выводить из устройства одного представления байткода. + +## Нормализация как отображение, сохраняющее смысл {#normalization-as-a-meaning-preserving-map} + +Если исходные программы `s₁` и `s₂` различаются только допустимым синтаксическим сахаром, нормализация должна явно выразить их общий смысл: + +$$ s_1 \equiv_{\mathsf{sugar}} s_2 \implies \operatorname{normalize}(s_1) = \operatorname{normalize}(s_2) $$ + +Другие полезные обязательства: + +* переименование альфа сохраняет нормализованный смысл +* лексическая область видимости разрешает ссылки на предполагаемый связывающий элемент +* позиции в исходном коде сохраняются, если они нужны для диагностики +* константы времени компиляции удаляются без поведения во время выполнения +* синтаксические ошибки накапливаются в соответствии с контрактом этапа + +Некоторым проектам нужны канонические нормализованные значения, другим достаточно семантической эквивалентности. Явно укажите, какой вариант выбран. + +## Возможности этапов {#stage-capabilities} + +```admonish warning title="Без всемогущего объекта компилятора" +Не делайте один огромный объект компилятора единственным интерфейсом всех этапов. +``` + +Нормализатору могут понадобиться такие возможности: + +* Чтение и расширение области связывания +* Разрешение имён исходного кода +* Накопление диагностик +* Построение нормализованных термов + +Генератору кода могут понадобиться: + +* Выделение исполняемых ссылок +* Выдача инструкций +* Разрешение нормализованных переменных +* Завершение структуры исполняемого кода + +Выражайте входы этапа как расширения поверх этих возможностей. Конкретные среды хранят карты, арены, счётчики и диагностики, но не определяют смысл этапа. + +```rust,noplayground +#[ext(name = NormalizeEntryExt)] +pub impl This +where + This: BindingScopeAlg + DiagnosticAlg + NormalizeRecAlg, +{ + fn normalize(&mut self, syntax: &Syntax) -> Result { + // initialize the semantic stage and invoke recursive normalization + } +} +``` + +Точные названия возможностей зависят от компилятора. Важны явные зависимости и устойчивая карта этапов. + +## Парсер и среда выполнения могут оставаться операционными {#parser-and-runtime-can-remain-operational} + +Не все подсистемы нужно заставлять использовать одно и то же кодирование. + +В парсере могут преобладать механизмы сгенерированной грамматики, а в виртуальной машине — эффективные мутации и планирование. Они могут оставаться операционными по форме, реализуя при этом чётко заданные границы: + +| Этап | Контракт | +| --- | --- | +| Парсер | Создаёт `Syntax` | +| Нормализатор | Создаёт `Core`, несущие смысл | +| Генератор кода | Сохраняет смысл в исполняемой форме | +| Среда выполнения | Создаёт наблюдаемое поведение, согласованное с моделью языка | + +Денотационное проектирование не устраняет машины. Оно не позволяет машинам незаметно становиться семантикой языка. + +## Законы и тесты компилятора {#compiler-laws-and-tests} + +Сильные свидетельства приходят из нескольких источников: + +* законы нормализации для эквивалентных форм исходного кода +* обратные преобразования разбора и форматирования, если это предусмотрено +* сравнение прямого семантического вычисления с выполнением скомпилированного кода +* эквивалентность байткода, если обещан канонический результат +* сценарии соответствия среды выполнения +* дифференциальные тесты разных интерпретаторов + +```admonish warning title="Равенство байтов — не семантическое равенство" +Не смешивайте побайтовое совпадение с семантическим равенством. Равенство байтов — полезное более сильное свойство лишь тогда, когда каноническая компиляция входит в спецификацию. +``` + +## Как подготовиться к чтению {#how-this-prepares-the-reader} + +Читая реализацию языка, ориентированную на смысл, обратите внимание на: + +* семантический синтаксис или трейты возможностей +* производные операции нормализации +* явные контракты этапов +* программы ядра первого порядка +* законы подстановки, области видимости и композиции +* тонкие среды, интерпретирующие возможности этапов +* операционные механизмы парсера, компилятора и виртуальной машины на границах + +Этот подход связывает общие принципы денотационного проектирования с Tolang и показывает, как семантические границы направляют проектирование языка, компиляцию и интерпретацию среды выполнения. diff --git a/src/rust-dd/compiler-pipelines.uk.md b/src/rust-dd/compiler-pipelines.uk.md new file mode 100644 index 0000000..28b6d53 --- /dev/null +++ b/src/rust-dd/compiler-pipelines.uk.md @@ -0,0 +1,196 @@ + + +# Мова й конвеєри компілятора {#language-and-compiler-pipelines} + +```admonish tip title="Пов’язані матеріали" +Проєктування від значення в Rust: [Програми першого порядку](first-order-programs.md), [Інтерпретатори й ефекти](interpreters.md) +Поняття: [Операційна семантика](../concepts/operational_semantics.md), [Дефункціоналізація](../concepts/defunctionalization.md) +Інсайти: [Алгебра EVM](../insights/evm-alg.md) +``` + +```admonish note title="Значення — це не конвеєр" +Компілятор найпростіше зрозуміти, коли значення мови не ототожнюють із деревами синтаксичного розбору, проходами, байткодом чи циклом машини. Коректність визначає один комутативний закон: виконання скомпільованої програми має узгоджуватися з денотацією програми. +``` + +Про компілятор найлегше міркувати, коли значення мови не ототожнюють із деревами синтаксичного розбору, проходами компілятора, байткодом чи циклом віртуальної машини. + +У цьому розділі використано спрощену паралельну мову, побудовану за зразком Tolang, щоб зосередитися на семантичній архітектурі. + +## Чотири окремі рівні {#four-distinct-layers} + +Розрізняйте ці рівні: + +1. синтаксис вихідної мови +2. нормалізована мова +3. представлення виконуваного коду +4. виконання машиною + +Типовий конвеєр має такий вигляд: + +$$ \begin{aligned} \operatorname{Parse} &\colon \mathsf{Source} \to \mathsf{Syntax} \\ \operatorname{Normalize} &\colon \mathsf{Syntax} \to \operatorname{Result}(\mathsf{Core}, \mathsf{Diagnostics}) \\ \operatorname{CodeGen} &\colon \mathsf{Core} \to \operatorname{Result}(\mathsf{Executable}, \mathsf{Error}) \\ \operatorname{Run} &\colon \mathsf{Executable} \times \mathsf{RuntimeState} \to \mathsf{Observation} \end{aligned} $$ + +Зручна операція — це композиція: + +$$ \operatorname{Compile} = \operatorname{Parse}\mathbin{;}\operatorname{Normalize}\mathbin{;}\operatorname{CodeGen} $$ + +Складений допоміжний засіб не є семантичним визначенням кожного етапу. + +## Синтаксис — це ще не значення {#syntax-is-not-yet-meaning} + +Результат синтаксичного розбору відображає рішення граматики: + +* пунктуацію +* синтаксичний цукор +* пріоритет операторів +* діапазони у вихідному тексті +* згенероване представлення парсера + +Ці дані важливі для діагностики та інструментів, але не обов’язково мають визначати основну мову. + +Нормалізація усуває випадкові синтаксичні відмінності й вводить компактнішу форму, що містить значення. Наприклад, кілька поверхневих форм прив’язування можна нормалізувати до однієї основної операції обмеження. + +**Багато форм вихідного синтаксису** → **один нормалізований конструктор** + +Так з’являється єдине місце, де можна сформулювати подальші закони компілятора й середовища виконання. + +## Денотаційне та скомпільоване значення {#denotational-and-compiled-meaning} + +Нехай: + +$$ \llbracket - \rrbracket : Core \to D $$ + +призначає значенням семантичні області `D`. + +Компіляція створює виконувані значення: + +$$ compile : Core \to Executable $$ + +а виконання дає такі спостереження: + +$$ run : Executable \to D $$ + +Головне зобов’язання щодо коректності задає комутативна діаграма: + +$$ \operatorname{run}(\operatorname{compile}(p)) = \llbracket p \rrbracket $$ + +У недетермінованих чи паралельних системах рівністю може бути спостережувана еквівалентність, множина результатів, еквівалентність трас або бісимілярність, а не звичайна рівність значень. Це має визначити семантична модель. + +## Значення паралельного процесу {#concurrent-process-meaning} + +Базове рефлексивне числення охоплює такі поняття: + +$$ \begin{array}{ll} \mathbf{0} & \text{inactive process} \\ P \mid Q & \text{parallel composition} \\ x!(v) & \text{send a value on a channel} \\ ?\,(y \leftarrow x)\ P & \text{receive a value and continue as }P \end{array} $$ + +Tolang композиційно розширює базове числення. Одне з розширень додає таку поверхневу форму: + +$$ \mathbf{let}\ x\ \mathbf{in}\ P \qquad \text{fresh channel binding scoped over }P. $$ + +Це зв’язування створює новий канал і обмежує область видимості його назви фрагментом $P$; у літературі з числення процесів цю операцію називають *обмеженням*. У рефлексивному ядрі немає примітивного оператора обмеження. Див. працю Мередіта й Радестока [*«Рефлексивне числення вищого порядку»*](https://doi.org/10.1016/j.entcs.2005.05.016). + +Операційна машина може реалізовувати це за допомогою простору кортежів, черг, індексів зіставлення, записів продовження й паралельних завдань. Ці механізми не визначають мову. + +Семантичний рівень визначає спостережувану поведінку процесу й структурні закони. Можливі закони для базової композиції паралельних процесів: + +$$ \begin{aligned} P \mid \mathbf{0} &\equiv P \\ P \mid Q &\equiv Q \mid P \\ (P \mid Q) \mid R &\equiv P \mid (Q \mid R) \end{aligned} $$ + +Закони для розширення зі свіжим зв’язуванням окремі. Серед усталених можливих схем — перейменування альфа, перестановка різних зв’язувань і винесення області видимості: + +$$ \begin{aligned} \mathbf{let}\ x\ \mathbf{in}\ P &\equiv \mathbf{let}\ y\ \mathbf{in}\ P\{y/x\} && (y \mathrel{\#} P) \\ \mathbf{let}\ x\ \mathbf{in}\ (\mathbf{let}\ y\ \mathbf{in}\ P) &\equiv \mathbf{let}\ y\ \mathbf{in}\ (\mathbf{let}\ x\ \mathbf{in}\ P) && (x \ne y) \\ \mathbf{let}\ x\ \mathbf{in}\ (P \mid Q) &\equiv P \mid (\mathbf{let}\ x\ \mathbf{in}\ Q) && (x \notin \operatorname{FN}(P)) \end{aligned} $$ + +Тут $y \mathrel{\#} P$ означає, що $y$ є свіжим для $P$, $P\{y/x\}$ — це перейменування зі запобіганням захопленню, а $\operatorname{FN}(P)$ — множина вільних назв каналів у $P$. Ці схеми стають законами лише тоді, коли вибрана спостережувана еквівалентність підтверджує їх. Не можна вважати їх правильними лише на підставі поверхневого синтаксису чи виводити з одного розташування байткоду. + +## Нормалізація як перетворення, що зберігає значення {#normalization-as-a-meaning-preserving-map} + +Якщо вихідні програми `s₁` та `s₂` відрізняються лише дозволеним синтаксичним цукром, нормалізація має виявити їхнє спільне значення: + +$$ s_1 \equiv_{\mathsf{sugar}} s_2 \implies \operatorname{normalize}(s_1) = \operatorname{normalize}(s_2) $$ + +Стануть у пригоді й інші вимоги: + +* перейменування альфа зберігає нормалізоване значення +* лексична область видимості визначає потрібний зв’язувач +* позиції у вихідному тексті зберігаються там, де вони потрібні для діагностики +* константи часу компіляції усуваються без поведінки під час виконання +* помилки синтаксису накопичуються відповідно до контракту етапу + +Одним проєктам потрібні канонічні нормалізовані значення, іншим — лише семантична еквівалентність. Уточніть, який варіант потрібен. + +## Можливості етапів {#stage-capabilities} + +```admonish warning title="Жодного монолітного компілятора" +Не робіть один величезний об’єкт компілятора єдиним інтерфейсом усіх етапів. +``` + +Нормалізатору можуть знадобитися такі можливості: + +* читати й розширювати область видимості зв’язування +* розв’язувати назви вихідного тексту +* накопичувати діагностичні повідомлення +* створювати нормалізовані терми + +Генератору коду можуть знадобитися: + +* виділяти посилання на виконувані об’єкти +* створювати інструкції +* розв’язувати нормалізовані змінні +* завершувати структуру виконуваного коду + +Виражайте етапи як розширення цих можливостей. Конкретні середовища зберігають мапи, арени, лічильники й діагностичні повідомлення, але не визначають значення етапу. + +```rust,noplayground +#[ext(name = NormalizeEntryExt)] +pub impl This +where + This: BindingScopeAlg + DiagnosticAlg + NormalizeRecAlg, +{ + fn normalize(&mut self, syntax: &Syntax) -> Result { + // initialize the semantic stage and invoke recursive normalization + } +} +``` + +Точні назви можливостей залежать від компілятора. Важливо явно задавати залежності й мати стабільну відповідність етапам. + +## Парсер і середовище виконання можуть залишатися операційними {#parser-and-runtime-can-remain-operational} + +Не обов’язково змушувати кожну підсистему використовувати однакове кодування. + +У парсері можуть переважати механізми згенерованої граматики. У віртуальній машині — ефективні мутації й планування. Вони можуть залишатися операційними за формою, водночас реалізуючи чітко визначені межі: + +| Етап | Контракт | +| --- | --- | +| Парсер | Створює `Syntax` | +| Нормалізатор | Створює `Core`, що містять значення | +| Генератор коду | Зберігає значення у виконуваному представленні | +| Середовище виконання | Створює спостереження, узгоджені з моделлю мови | + +Денотаційне проєктування не усуває машини. Воно не дає машинам непомітно стати семантикою мови. + +## Закони й тести компілятора {#compiler-laws-and-tests} + +Сильні свідчення отримують різними способами: + +* закони нормалізації для еквівалентних форм вихідного тексту +* зворотні перетворення між синтаксичним розбором і форматуванням для тих випадків, де вони передбачені +* порівняння прямого семантичного обчислення з виконанням скомпільованого коду +* еквівалентність байткоду, якщо специфікація гарантує канонічний результат +* сценарії відповідності середовища виконання +* диференційні тести для різних інтерпретаторів + +```admonish warning title="Рівність байтів — не семантична рівність" +Не плутайте побайтову рівність із семантичною. Рівність байтів є корисною сильнішою властивістю лише тоді, коли канонічна компіляція належить до специфікації. +``` + +## Як це допоможе читачеві {#how-this-prepares-the-reader} + +Читаючи реалізацію мови, орієнтовану на значення, шукайте: + +* семантичний синтаксис або трейти можливостей +* операції нормалізації, виведені з примітивів +* явні контракти етапів +* основні програми першого порядку +* закони підстановки, області видимості й композиції +* тонкі середовища, що інтерпретують можливості етапів +* операційні механізми парсера, компілятора й віртуальної машини на зовнішніх рівнях + +Цей підхід пов’язує загальне денотаційне проєктування з Tolang і показує, як семантичні межі скеровують проєктування мови, компіляцію та інтерпретацію під час виконання. diff --git a/src/rust-dd/compiler-pipelines.vi.md b/src/rust-dd/compiler-pipelines.vi.md new file mode 100644 index 0000000..6f8f1a3 --- /dev/null +++ b/src/rust-dd/compiler-pipelines.vi.md @@ -0,0 +1,196 @@ + + +# Quy trình ngôn ngữ và trình biên dịch {#language-and-compiler-pipelines} + +```admonish tip title="Liên quan" +Thiết kế theo ngữ nghĩa trong Rust: [Chương trình bậc nhất](first-order-programs.md), [Bộ diễn giải và hiệu ứng](interpreters.md) +Khái niệm: [Ngữ nghĩa vận hành](../concepts/operational_semantics.md), [Phi chức năng hóa](../concepts/defunctionalization.md) +Nhận định: [Đại số EVM](../insights/evm-alg.md) +``` + +```admonish note title="Ý nghĩa không phải quy trình" +Trình biên dịch dễ hiểu nhất khi ý nghĩa ngôn ngữ không bị đồng nhất với cây phân tích, các lượt biến đổi, bytecode hay vòng lặp máy. Tính đúng đắn là một định luật giao hoán: chạy chương trình đã biên dịch cho kết quả phù hợp với ngữ nghĩa chỉ định của chương trình. +``` + +Lập luận về trình biên dịch dễ hơn khi ý nghĩa ngôn ngữ không bị đồng nhất với cây phân tích, các lượt trình biên dịch, bytecode hay vòng lặp máy ảo. + +Chương này dùng ngôn ngữ đồng thời giản lược theo hình mẫu Tolang, tập trung vào kiến trúc ngữ nghĩa. + +## Bốn lớp riêng biệt {#four-distinct-layers} + +Hãy giữ các lớp này tách biệt: + +1. Cú pháp nguồn +2. Ngôn ngữ chuẩn hóa +3. Cách biểu diễn thực thi được +4. Thực thi trên máy + +Quy trình điển hình là: + +$$ \begin{aligned} \operatorname{Parse} &\colon \mathsf{Source} \to \mathsf{Syntax} \\ \operatorname{Normalize} &\colon \mathsf{Syntax} \to \operatorname{Result}(\mathsf{Core}, \mathsf{Diagnostics}) \\ \operatorname{CodeGen} &\colon \mathsf{Core} \to \operatorname{Result}(\mathsf{Executable}, \mathsf{Error}) \\ \operatorname{Run} &\colon \mathsf{Executable} \times \mathsf{RuntimeState} \to \mathsf{Observation} \end{aligned} $$ + +Phép toán tiện ích là phép hợp thành: + +$$ \operatorname{Compile} = \operatorname{Parse}\mathbin{;}\operatorname{Normalize}\mathbin{;}\operatorname{CodeGen} $$ + +Trợ giúp được hợp thành không phải định nghĩa ngữ nghĩa của từng giai đoạn. + +## Cú pháp chưa phải ý nghĩa {#syntax-is-not-yet-meaning} + +Đầu ra bộ phân tích phản chiếu các lựa chọn ngữ pháp: + +* dấu câu +* cú pháp rút gọn +* độ ưu tiên +* đoạn văn bản nguồn +* cách biểu diễn bộ phân tích được tạo sinh + +Những điều này quan trọng với chẩn đoán và công cụ, nhưng không nhất thiết phải định nghĩa ngôn ngữ lõi. + +Chuẩn hóa loại bỏ biến thể cú pháp ngẫu nhiên và đưa vào dạng nhỏ hơn mang ý nghĩa. Chẳng hạn, nhiều dạng ràng buộc bề mặt có thể được chuẩn hóa thành một phép toán giới hạn lõi. + +**Nhiều dạng nguồn** → **một cấu trúc chuẩn hóa** + +Việc này tạo ra một nơi để phát biểu các định luật trình biên dịch và môi trường chạy ở bước sau. + +## Ý nghĩa chỉ định và ý nghĩa đã biên dịch {#denotational-and-compiled-meaning} + +Giả sử: + +$$ \llbracket - \rrbracket : Core \to D $$ + +gán ý nghĩa trong miền ngữ nghĩa `D`. + +Biên dịch tạo ra các giá trị thực thi được: + +$$ compile : Core \to Executable $$ + +và quá trình thực thi quan sát chúng: + +$$ run : Executable \to D $$ + +Nghĩa vụ trung tâm về tính đúng đắn là một biểu đồ giao hoán: + +$$ \operatorname{run}(\operatorname{compile}(p)) = \llbracket p \rrbracket $$ + +Với hệ thống không tất định hoặc đồng thời, đẳng thức có thể là tương đương quan sát, tập kết quả, tương đương vết hoặc mô phỏng song hành, chứ không phải đẳng thức giá trị thông thường. Mô hình ngữ nghĩa phải chọn. + +## Ý nghĩa tiến trình đồng thời {#concurrent-process-meaning} + +Phép tính phản chiếu nền tảng bao gồm các ý tưởng như: + +$$ \begin{array}{ll} \mathbf{0} & \text{inactive process} \\ P \mid Q & \text{parallel composition} \\ x!(v) & \text{send a value on a channel} \\ ?\,(y \leftarrow x)\ P & \text{receive a value and continue as }P \end{array} $$ + +Tolang mở rộng phép tính nền tảng theo tính hợp thành. Một phần mở rộng như vậy bổ sung dạng bề mặt + +$$ \mathbf{let}\ x\ \mathbf{in}\ P \qquad \text{fresh channel binding scoped over }P. $$ + +Ràng buộc này tạo kênh mới và giới hạn tên của nó trong phạm vi $P$; tài liệu về phép tính tiến trình gọi phép toán đó là *phép hạn định*. Lõi phản chiếu không có toán tử hạn định nguyên thủy. Xem [*Phép tính phản chiếu bậc cao*](https://doi.org/10.1016/j.entcs.2005.05.016) của Meredith và Radestock. + +Máy vận hành có thể hiện thực hóa các cấu trúc này bằng không gian bộ, hàng đợi, chỉ mục đối sánh, bản ghi tiếp nối và tác vụ đồng thời. Những cơ chế đó không phải định nghĩa của ngôn ngữ. + +Lớp ngữ nghĩa xác định hành vi tiến trình có thể quan sát và các định luật cấu trúc. Những định luật ứng viên cho phép hợp thành song song lõi bao gồm: + +$$ \begin{aligned} P \mid \mathbf{0} &\equiv P \\ P \mid Q &\equiv Q \mid P \\ (P \mid Q) \mid R &\equiv P \mid (Q \mid R) \end{aligned} $$ + +Các định luật cho phần mở rộng ràng buộc mới này là riêng biệt. Các dạng ứng viên thông thường gồm đổi tên alpha, hoán đổi các ràng buộc khác nhau và đẩy phạm vi ra ngoài: + +$$ \begin{aligned} \mathbf{let}\ x\ \mathbf{in}\ P &\equiv \mathbf{let}\ y\ \mathbf{in}\ P\{y/x\} && (y \mathrel{\#} P) \\ \mathbf{let}\ x\ \mathbf{in}\ (\mathbf{let}\ y\ \mathbf{in}\ P) &\equiv \mathbf{let}\ y\ \mathbf{in}\ (\mathbf{let}\ x\ \mathbf{in}\ P) && (x \ne y) \\ \mathbf{let}\ x\ \mathbf{in}\ (P \mid Q) &\equiv P \mid (\mathbf{let}\ x\ \mathbf{in}\ Q) && (x \notin \operatorname{FN}(P)) \end{aligned} $$ + +Ở đây, $y \mathrel{\#} P$ có nghĩa $y$ là mới đối với $P$; $P\{y/x\}$ là đổi tên tránh bắt giữ; còn $\operatorname{FN}(P)$ là tập tên kênh tự do trong $P$. Các dạng này chỉ trở thành định luật khi quan hệ tương đương quan sát được chọn xác nhận chúng; không được suy ra từ cú pháp bề mặt hay một bố cục bytecode. + +## Chuẩn hóa như ánh xạ bảo toàn ý nghĩa {#normalization-as-a-meaning-preserving-map} + +Nếu các chương trình nguồn `s₁` và `s₂` chỉ khác nhau ở cú pháp rút gọn được chấp nhận, thì phép chuẩn hóa cần làm lộ ý nghĩa chung: + +$$ s_1 \equiv_{\mathsf{sugar}} s_2 \implies \operatorname{normalize}(s_1) = \operatorname{normalize}(s_2) $$ + +Các nghĩa vụ hữu ích khác gồm: + +* đổi tên alpha bảo toàn ý nghĩa chuẩn hóa +* phạm vi từ vựng phân giải về đúng biến ràng buộc dự định +* vị trí nguồn được giữ lại khi chẩn đoán cần dùng +* hằng số thời điểm biên dịch bị loại bỏ mà không tạo hành vi lúc chạy +* cú pháp sai tích lũy chẩn đoán theo hợp đồng của giai đoạn + +Một số dự án yêu cầu giá trị chuẩn hóa chuẩn tắc. Dự án khác chỉ cần tương đương ngữ nghĩa. Hãy nêu rõ lựa chọn. + +## Năng lực theo giai đoạn {#stage-capabilities} + +```admonish warning title="Không tạo một đối tượng trình biên dịch toàn năng" +Đừng biến một đối tượng trình biên dịch khổng lồ thành giao diện duy nhất của mọi giai đoạn. +``` + +Bộ chuẩn hóa có thể cần các năng lực như: + +* Đọc và mở rộng phạm vi ràng buộc +* Phân giải tên nguồn +* Tích lũy chẩn đoán +* Kiến tạo các số hạng chuẩn hóa + +Bộ sinh mã có thể cần: + +* Cấp phát tham chiếu thực thi +* Phát ra lệnh +* Phân giải biến đã chuẩn hóa +* Hoàn tất cấu trúc thực thi + +Biểu đạt mục nhập từng giai đoạn như phần mở rộng dựa trên các năng lực này. Môi trường cụ thể lưu bản đồ, arena, bộ đếm và chẩn đoán, nhưng không sở hữu ý nghĩa của giai đoạn. + +```rust,noplayground +#[ext(name = NormalizeEntryExt)] +pub impl This +where + This: BindingScopeAlg + DiagnosticAlg + NormalizeRecAlg, +{ + fn normalize(&mut self, syntax: &Syntax) -> Result { + // initialize the semantic stage and invoke recursive normalization + } +} +``` + +Tên năng lực cụ thể thay đổi theo trình biên dịch. Điều quan trọng là có phụ thuộc tường minh và ánh xạ giai đoạn ổn định. + +## Bộ phân tích và môi trường chạy có thể giữ tính vận hành {#parser-and-runtime-can-remain-operational} + +Không cần ép mọi hệ thống con dùng cùng một cách mã hóa. + +Bộ phân tích có thể bị chi phối bởi cơ chế ngữ pháp được tạo sinh. Máy ảo có thể bị chi phối bởi việc biến đổi và lập lịch hiệu quả. Chúng có thể giữ hình dạng vận hành trong khi triển khai các ranh giới được xác định rõ: + +| Giai đoạn | Hợp đồng | +| --- | --- | +| Bộ phân tích | Tạo ra `Syntax` | +| Bộ chuẩn hóa | Tạo ra `Core` mang ý nghĩa | +| Bộ sinh mã | Bảo toàn ý nghĩa trong dạng thực thi được | +| Môi trường chạy | Tạo ra quan sát nhất quán với mô hình ngôn ngữ | + +Thiết kế theo ngữ nghĩa không loại bỏ máy móc. Nó ngăn máy móc âm thầm trở thành ngữ nghĩa ngôn ngữ. + +## Định luật và kiểm thử trình biên dịch {#compiler-laws-and-tests} + +Bằng chứng mạnh đến từ nhiều hướng: + +* định luật chuẩn hóa trên các dạng nguồn tương đương +* kiểm thử khứ hồi giữa phân tích cú pháp và in định dạng đẹp khi được dự định +* đối chiếu đánh giá ngữ nghĩa trực tiếp với thực thi đã biên dịch +* tương đương bytecode khi đầu ra chuẩn tắc được cam kết +* tình huống kiểm tra tính phù hợp của môi trường chạy +* kiểm thử vi sai giữa các bộ diễn giải + +```admonish warning title="Bằng nhau từng byte không phải bằng nhau về ngữ nghĩa" +Đừng nhầm lẫn sự bằng nhau từng byte với đẳng thức ngữ nghĩa. Đẳng thức byte là thuộc tính mạnh hơn hữu ích chỉ khi biên dịch chuẩn tắc là một phần của đặc tả. +``` + +## Cách này chuẩn bị cho người đọc {#how-this-prepares-the-reader} + +Khi đọc một cách triển khai ngôn ngữ lấy ý nghĩa làm trọng tâm, hãy tìm: + +* cú pháp ngữ nghĩa hoặc đặc trưng năng lực +* các phép chuẩn hóa được suy ra +* hợp đồng giai đoạn tường minh +* chương trình lõi bậc nhất +* định luật cho phép thế, phạm vi và hợp thành +* môi trường mỏng diễn giải các năng lực giai đoạn +* cơ chế vận hành của bộ phân tích, trình biên dịch và máy ảo ở các rìa + +Lăng kính này kết nối Thiết kế theo ngữ nghĩa nói chung với Tolang, cho thấy cách ranh giới ngữ nghĩa định hướng thiết kế ngôn ngữ, biên dịch và diễn giải lúc chạy. diff --git a/src/rust-dd/compiler-pipelines.zh-hant.md b/src/rust-dd/compiler-pipelines.zh-hant.md new file mode 100644 index 0000000..ebc3b89 --- /dev/null +++ b/src/rust-dd/compiler-pipelines.zh-hant.md @@ -0,0 +1,196 @@ + + +# 語言與編譯器流水線 {#language-and-compiler-pipelines} + +```admonish tip title="相關內容" +Rust 中的語義驅動設計:[一階程式](first-order-programs.md)、[直譯器與效應](interpreters.md) +概念:[操作語義](../concepts/operational_semantics.md)、[去函式化](../concepts/defunctionalization.md) +洞見:[EVM 代數](../insights/evm-alg.md) +``` + +```admonish note title="含義並非流水線本身" +當語言含義不與解析器語法樹、編譯過程、位元組碼或機器迴圈混為一談時,編譯器就更清晰。正確性可由一條交換律表達:執行編譯後的程式,應與該程式的指稱一致。 +``` + +如果語言含義不等同於解析器語法樹、編譯器過程、位元組碼或虛擬機器迴圈,推理編譯器就會容易得多。 + +本章採用一種類似 Tolang 的簡化併發語言,重點放在語義架構上。 + +## 四個不同層次 {#four-distinct-layers} + +請將以下層次分開: + +1. 源語言語法 +2. 正規化語言 +3. 可執行表示 +4. 機器執行 + +典型流水線如下: + +$$ \begin{aligned} \operatorname{Parse} &\colon \mathsf{Source} \to \mathsf{Syntax} \\ \operatorname{Normalize} &\colon \mathsf{Syntax} \to \operatorname{Result}(\mathsf{Core}, \mathsf{Diagnostics}) \\ \operatorname{CodeGen} &\colon \mathsf{Core} \to \operatorname{Result}(\mathsf{Executable}, \mathsf{Error}) \\ \operatorname{Run} &\colon \mathsf{Executable} \times \mathsf{RuntimeState} \to \mathsf{Observation} \end{aligned} $$ + +便捷操作就是組合: + +$$ \operatorname{Compile} = \operatorname{Parse}\mathbin{;}\operatorname{Normalize}\mathbin{;}\operatorname{CodeGen} $$ + +組合後的輔助函式並非每個階段的語義定義。 + +## 語法尚未成為含義 {#syntax-is-not-yet-meaning} + +解析器輸出會映照語法選擇: + +* 標點 +* 語法糖 +* 優先順序 +* 原始碼區間 +* 生成的解析器表示 + +這些資訊對診斷與工具很重要,但不必用來定義核心語言。 + +正規化會移除偶然的語法差異,並引入一種更精簡、承載含義的形式。例如,多種表層繫結形式可以正規化為同一個核心限制操作。 + +**多種源形式** → **一個正規化構造** + +這樣一來,編譯器後續階段與執行時定律便有了統一的陳述位置。 + +## 指稱含義與編譯含義 {#denotational-and-compiled-meaning} + +令: + +$$ \llbracket - \rrbracket : Core \to D $$ + +在語義域`D`中賦予含義。 + +編譯會生成可執行值: + +$$ compile : Core \to Executable $$ + +執行時會觀察這些值: + +$$ run : Executable \to D $$ + +核心正確性義務是一張交換圖: + +$$ \operatorname{run}(\operatorname{compile}(p)) = \llbracket p \rrbracket $$ + +對於非確定性或併發系統,等價關係可能是觀察等價、結果集合、軌跡等價或雙模擬,而非普通的值相等。必須由語義模型作出選擇。 + +## 併發過程含義 {#concurrent-process-meaning} + +基礎反射演算包含以下思想: + +$$ \begin{array}{ll} \mathbf{0} & \text{inactive process} \\ P \mid Q & \text{parallel composition} \\ x!(v) & \text{send a value on a channel} \\ ?\,(y \leftarrow x)\ P & \text{receive a value and continue as }P \end{array} $$ + +Tolang 以組合方式擴充基礎演算。其中一種擴充增加了表層形式 + +$$ \mathbf{let}\ x\ \mathbf{in}\ P \qquad \text{fresh channel binding scoped over }P. $$ + +這個繫結會建立一個新通道,並將其名稱的作用域限定在$P$之內;過程演算文獻將此操作稱為*限制*。反射核心沒有基本限制運算子。參見 Meredith 與 Radestock 的論文[*《反射式高階演算》*](https://doi.org/10.1016/j.entcs.2005.05.016)。 + +操作機器可以透過元組空間、佇列、匹配索引、延續記錄與併發任務來實作這些功能。這些機制並非語言定義。 + +語義層負責確定可觀察的過程行為與結構定律。核心並行組合可能遵循以下定律: + +$$ \begin{aligned} P \mid \mathbf{0} &\equiv P \\ P \mid Q &\equiv Q \mid P \\ (P \mid Q) \mid R &\equiv P \mid (Q \mid R) \end{aligned} $$ + +這種新鮮繫結擴充還具有獨立的定律。常見候選模式包括 α 重新命名、不同繫結的交換,以及作用域外提: + +$$ \begin{aligned} \mathbf{let}\ x\ \mathbf{in}\ P &\equiv \mathbf{let}\ y\ \mathbf{in}\ P\{y/x\} && (y \mathrel{\#} P) \\ \mathbf{let}\ x\ \mathbf{in}\ (\mathbf{let}\ y\ \mathbf{in}\ P) &\equiv \mathbf{let}\ y\ \mathbf{in}\ (\mathbf{let}\ x\ \mathbf{in}\ P) && (x \ne y) \\ \mathbf{let}\ x\ \mathbf{in}\ (P \mid Q) &\equiv P \mid (\mathbf{let}\ x\ \mathbf{in}\ Q) && (x \notin \operatorname{FN}(P)) \end{aligned} $$ + +這裡,$y \mathrel{\#} P$表示$y$對$P$來說是新鮮的;$P\{y/x\}$表示避免變數捕獲的重新命名;$\operatorname{FN}(P)$表示$P$中的自由通道名稱集合。只有在選定的觀察等價關係認可這些模式時,它們才成為定律;不能僅憑表層語法或某種位元組碼佈局就作此假設。 + +## 正規化是一種保持含義的映射 {#normalization-as-a-meaning-preserving-map} + +如果源程式`s₁`與`s₂`的區別僅在於所接受的語法糖,正規化就應顯式呈現它們共同的含義: + +$$ s_1 \equiv_{\mathsf{sugar}} s_2 \implies \operatorname{normalize}(s_1) = \operatorname{normalize}(s_2) $$ + +其他有用的義務包括: + +* α 重新命名保留正規化含義 +* 詞法作用域應繫結到預期的繫結項 +* 診斷所需的原始碼位置應予保留 +* 編譯期常量應被擦除,不產生執行時行為 +* 畸形語法應依階段契約累積診斷資訊 + +有些專案要求正規化值具有規範形式,有些專案只要求語義等價。應明確選擇哪一種。 + +## 階段能力 {#stage-capabilities} + +```admonish warning title="不要使用萬能編譯器物件" +不要讓一個巨型編譯器物件成為唯一的階段介面。 +``` + +正規化器可能需要以下能力: + +* 讀取並擴充繫結作用域 +* 解析原始碼名稱 +* 累積診斷資訊 +* 構造正規化項 + +程式碼生成器可能需要: + +* 分配可執行引用 +* 生成指令 +* 解析正規化變數 +* 完成可執行結構 + +將各階段入口表達為基於這些能力的擴充。具體環境可以儲存對映、區域分配器、計數器與診斷資訊,但它們並不擁有階段含義。 + +```rust,noplayground +#[ext(name = NormalizeEntryExt)] +pub impl This +where + This: BindingScopeAlg + DiagnosticAlg + NormalizeRecAlg, +{ + fn normalize(&mut self, syntax: &Syntax) -> Result { + // initialize the semantic stage and invoke recursive normalization + } +} +``` + +各編譯器的精確能力名稱會有所不同。重要的是依賴明確,階段對映穩定。 + +## 解析器與執行時可以保持操作式設計 {#parser-and-runtime-can-remain-operational} + +並非每個子系統都必須被強制納入同一種編碼。 + +解析器可能主要由生成式語法機制主導。虛擬機器可能主要依賴高效的狀態變更與排程。它們可以保留操作式設計,同時實作定義清晰的邊界: + +| 階段 | 契約 | +| --- | --- | +| 解析器 | 生成`Syntax` | +| 正規化器 | 生成承載含義的`Core` | +| 程式碼生成器 | 以可執行形式保留含義 | +| 執行時 | 生成符合語言模型的觀察 | + +指稱設計不會移除機器,而是防止機器悄然成為語言語義。 + +## 編譯器定律與測試 {#compiler-laws-and-tests} + +強有力的證據來自多個方面: + +* 針對等價源形式的正規化定律 +* 在預期情況下檢查解析與漂亮列印的往返性質 +* 比較直接語義求值與編譯後執行 +* 規範承諾規範輸出時檢查位元組碼等價 +* 執行時符合性場景 +* 跨直譯器差分測試 + +```admonish warning title="位元組相等不等於語義相等" +不要混淆逐位元組相等與語義相等。只有當規範要求編譯結果具有正規形式時,位元組相等才是一項有用的更強性質。 +``` + +## 這對讀者有何幫助 {#how-this-prepares-the-reader} + +閱讀語義優先的語言實作時,請留意: + +* 語義語法或能力 trait +* 派生的正規化操作 +* 明確的階段契約 +* 一階核心程式 +* 替換、作用域與組合定律 +* 解釋階段能力的輕量環境 +* 位於邊界處的操作式解析器、編譯器與虛擬機器機制 + +這個視角連線了一般的指稱設計與 Tolang,展示語義邊界如何引導語言設計、編譯與執行時解釋。 diff --git a/src/rust-dd/compiler-pipelines.zh.md b/src/rust-dd/compiler-pipelines.zh.md new file mode 100644 index 0000000..2538fc8 --- /dev/null +++ b/src/rust-dd/compiler-pipelines.zh.md @@ -0,0 +1,196 @@ + + +# 语言与编译器流水线 {#language-and-compiler-pipelines} + +```admonish tip title="相关内容" +Rust 中的语义驱动设计:[一阶程序](first-order-programs.md)、[解释器与效应](interpreters.md) +概念:[操作语义](../concepts/operational_semantics.md)、[去函数化](../concepts/defunctionalization.md) +洞见:[EVM 代数](../insights/evm-alg.md) +``` + +```admonish note title="含义并非流水线本身" +当语言含义不与解析器语法树、编译过程、字节码或机器循环混为一谈时,编译器就更清晰。正确性可由一条交换律表达:运行编译后的程序,应与该程序的指称一致。 +``` + +如果语言含义不等同于解析器语法树、编译器过程、字节码或虚拟机循环,推理编译器就会容易得多。 + +本章采用一种类似 Tolang 的简化并发语言,重点放在语义架构上。 + +## 四个不同层次 {#four-distinct-layers} + +请将以下层次分开: + +1. 源语言语法 +2. 规范化语言 +3. 可执行表示 +4. 机器执行 + +典型流水线如下: + +$$ \begin{aligned} \operatorname{Parse} &\colon \mathsf{Source} \to \mathsf{Syntax} \\ \operatorname{Normalize} &\colon \mathsf{Syntax} \to \operatorname{Result}(\mathsf{Core}, \mathsf{Diagnostics}) \\ \operatorname{CodeGen} &\colon \mathsf{Core} \to \operatorname{Result}(\mathsf{Executable}, \mathsf{Error}) \\ \operatorname{Run} &\colon \mathsf{Executable} \times \mathsf{RuntimeState} \to \mathsf{Observation} \end{aligned} $$ + +便捷操作就是组合: + +$$ \operatorname{Compile} = \operatorname{Parse}\mathbin{;}\operatorname{Normalize}\mathbin{;}\operatorname{CodeGen} $$ + +组合后的辅助函数并非每个阶段的语义定义。 + +## 语法尚未成为含义 {#syntax-is-not-yet-meaning} + +解析器输出会映照语法选择: + +* 标点 +* 语法糖 +* 优先级 +* 源代码区间 +* 生成的解析器表示 + +这些信息对诊断与工具很重要,但不必用来定义核心语言。 + +规范化会移除偶然的语法差异,并引入一种更精简、承载含义的形式。例如,多种表层绑定形式可以规范化为同一个核心限制操作。 + +**多种源形式** → **一个规范化构造** + +这样一来,编译器后续阶段与运行时定律便有了统一的陈述位置。 + +## 指称含义与编译含义 {#denotational-and-compiled-meaning} + +令: + +$$ \llbracket - \rrbracket : Core \to D $$ + +在语义域`D`中赋予含义。 + +编译会生成可执行值: + +$$ compile : Core \to Executable $$ + +执行时会观察这些值: + +$$ run : Executable \to D $$ + +核心正确性义务是一张交换图: + +$$ \operatorname{run}(\operatorname{compile}(p)) = \llbracket p \rrbracket $$ + +对于非确定性或并发系统,等价关系可能是观察等价、结果集合、轨迹等价或双模拟,而非普通的值相等。必须由语义模型作出选择。 + +## 并发过程含义 {#concurrent-process-meaning} + +基础反射演算包含以下思想: + +$$ \begin{array}{ll} \mathbf{0} & \text{inactive process} \\ P \mid Q & \text{parallel composition} \\ x!(v) & \text{send a value on a channel} \\ ?\,(y \leftarrow x)\ P & \text{receive a value and continue as }P \end{array} $$ + +Tolang 以组合方式扩展基础演算。其中一种扩展增加了表层形式 + +$$ \mathbf{let}\ x\ \mathbf{in}\ P \qquad \text{fresh channel binding scoped over }P. $$ + +这个绑定会创建一个新通道,并将其名称的作用域限定在$P$之内;过程演算文献将此操作称为*限制*。反射核心没有基本限制运算符。参见 Meredith 与 Radestock 的论文[*《反射式高阶演算》*](https://doi.org/10.1016/j.entcs.2005.05.016)。 + +操作机器可以通过元组空间、队列、匹配索引、延续记录与并发任务来实现这些功能。这些机制并非语言定义。 + +语义层负责确定可观察的过程行为与结构定律。核心并行组合可能遵循以下定律: + +$$ \begin{aligned} P \mid \mathbf{0} &\equiv P \\ P \mid Q &\equiv Q \mid P \\ (P \mid Q) \mid R &\equiv P \mid (Q \mid R) \end{aligned} $$ + +这种新鲜绑定扩展还具有独立的定律。常见候选模式包括α 重命名、不同绑定的交换,以及作用域外提: + +$$ \begin{aligned} \mathbf{let}\ x\ \mathbf{in}\ P &\equiv \mathbf{let}\ y\ \mathbf{in}\ P\{y/x\} && (y \mathrel{\#} P) \\ \mathbf{let}\ x\ \mathbf{in}\ (\mathbf{let}\ y\ \mathbf{in}\ P) &\equiv \mathbf{let}\ y\ \mathbf{in}\ (\mathbf{let}\ x\ \mathbf{in}\ P) && (x \ne y) \\ \mathbf{let}\ x\ \mathbf{in}\ (P \mid Q) &\equiv P \mid (\mathbf{let}\ x\ \mathbf{in}\ Q) && (x \notin \operatorname{FN}(P)) \end{aligned} $$ + +这里,$y \mathrel{\#} P$表示$y$对$P$来说是新鲜的;$P\{y/x\}$表示避免变量捕获的重命名;$\operatorname{FN}(P)$表示$P$中的自由通道名称集合。只有在选定的观察等价关系认可这些模式时,它们才成为定律;不能仅凭表层语法或某种字节码布局就作此假设。 + +## 规范化是一种保持含义的映射 {#normalization-as-a-meaning-preserving-map} + +如果源程序`s₁`与`s₂`的区别仅在于所接受的语法糖,规范化就应显式呈现它们共同的含义: + +$$ s_1 \equiv_{\mathsf{sugar}} s_2 \implies \operatorname{normalize}(s_1) = \operatorname{normalize}(s_2) $$ + +其他有用的义务包括: + +* α 重命名保留规范化含义 +* 词法作用域应绑定到预期的绑定项 +* 诊断所需的源代码位置应予保留 +* 编译期常量应被擦除,不产生运行时行为 +* 畸形语法应依阶段契约累积诊断信息 + +有些项目要求规范化值具有规范形式,有些项目只要求语义等价。应明确选择哪一种。 + +## 阶段能力 {#stage-capabilities} + +```admonish warning title="不要使用万能编译器对象" +不要让一个巨型编译器对象成为唯一的阶段接口。 +``` + +规范化器可能需要以下能力: + +* 读取并扩展绑定作用域 +* 解析源代码名称 +* 累积诊断信息 +* 构造规范化项 + +代码生成器可能需要: + +* 分配可执行引用 +* 生成指令 +* 解析规范化变量 +* 完成可执行结构 + +将各阶段入口表达为基于这些能力的扩展。具体环境可以存储映射、区域分配器、计数器与诊断信息,但它们并不拥有阶段含义。 + +```rust,noplayground +#[ext(name = NormalizeEntryExt)] +pub impl This +where + This: BindingScopeAlg + DiagnosticAlg + NormalizeRecAlg, +{ + fn normalize(&mut self, syntax: &Syntax) -> Result { + // initialize the semantic stage and invoke recursive normalization + } +} +``` + +各编译器的精确能力名称会有所不同。重要的是依赖明确,阶段映射稳定。 + +## 解析器与运行时可以保持操作式设计 {#parser-and-runtime-can-remain-operational} + +并非每个子系统都必须被强制纳入同一种编码。 + +解析器可能主要由生成式语法机制主导。虚拟机可能主要依赖高效的状态变更与调度。它们可以保留操作式设计,同时实现定义清晰的边界: + +| 阶段 | 契约 | +| --- | --- | +| 解析器 | 生成`Syntax` | +| 规范化器 | 生成承载含义的`Core` | +| 代码生成器 | 以可执行形式保留含义 | +| 运行时 | 生成符合语言模型的观察 | + +指称设计不会移除机器,而是防止机器悄然成为语言语义。 + +## 编译器定律与测试 {#compiler-laws-and-tests} + +强有力的证据来自多个方面: + +* 针对等价源形式的规范化定律 +* 在预期情况下检查解析与漂亮打印的往返性质 +* 比较直接语义求值与编译后执行 +* 规范承诺规范输出时检查字节码等价 +* 运行时符合性场景 +* 跨解释器差分测试 + +```admonish warning title="字节相等不等于语义相等" +不要混淆逐字节相等与语义相等。只有当规范要求编译结果具有规范形式时,字节相等才是一项有用的更强性质。 +``` + +## 这对读者有何帮助 {#how-this-prepares-the-reader} + +阅读语义优先的语言实现时,请留意: + +* 语义语法或能力 trait +* 派生的规范化操作 +* 明确的阶段契约 +* 一阶核心程序 +* 替换、作用域与组合定律 +* 解释阶段能力的轻量环境 +* 位于边界处的操作式解析器、编译器与虚拟机机制 + +这个视角连接了一般的指称设计与 Tolang,展示语义边界如何引导语言设计、编译与运行时解释。 diff --git a/src/rust-dd/derived-meaning.ar.md b/src/rust-dd/derived-meaning.ar.md new file mode 100644 index 0000000..d1f6747 --- /dev/null +++ b/src/rust-dd/derived-meaning.ar.md @@ -0,0 +1,204 @@ + + +# المعنى المشتق والتركيب {#derived-meaning-and-composition} + +```admonish tip title="ذات صلة" +المنظور الدلالي: [التصميم الدلالي (Denotational Design)](../denotational-design/design.md) +التصميم انطلاقًا من المعنى في Rust: [جبر القدرات](capability-algebras.md)، [المفسرات والآثار](interpreters.md) +المفاهيم: [Expression Problem](../concepts/expression-problem.md) +``` + +```admonish note title="تمهيد" +ينتمي السلوك المشتق إلى القدرات التي يستخدمها، ويُكتب مرة واحدة بوصفه امتدادًا فوق حدودها، لا إلى أي نوع ملموس يصادف أنه يطبقها. وجملة `where` هي التصريح الصادق عما يعتمد عليه الاشتقاق. +``` + +توفر القدرات الأولية المفردات. وينبغي اشتقاق معظم سلوك التطبيق منها مرة واحدة ومشاركته بين جميع المفسرات. + +## الامتدادات تملك الاشتقاقات {#extensions-own-derivations} + +باستخدام الحزمة [`extend`](https://docs.rs/extend/latest/extend/)، يمكن اشتقاق عمليات الفروع باستقلال عن التمثيل: + +```rust,noplayground +use extend::ext; + +#[ext(name = BranchExt)] +pub impl This +where + This: BranchAlg, +{ + fn branch_child(&self, branch: &This::Branch, direction: Direction) -> This::Branch { + self.branch_grow(branch, direction) + } + + fn branch_left(&self, branch: &This::Branch) -> This::Branch { + self.branch_child(branch, Direction::Left) + } + + fn branch_right(&self, branch: &This::Branch) -> This::Branch { + self.branch_child(branch, Direction::Right) + } + + fn branch_is_ancestor(&self, ancestor: &This::Branch, descendant: &This::Branch) -> bool { + self.branch_path(ancestor, descendant).is_some() + } +} +``` + +جملة `where` هي التصريح الكامل بالتبعية الدلالية: `BranchAlg`، ولا شيء سواها. لا يملك نوع فرع ملموس هذه التعريفات. + +لا تفعل الماكرو سوى إزالة الشيفرة النمطية للسمات والتنفيذات. ويمكن لسمة امتداد عادية التعبير عن التصميم نفسه. موضع التصميم الدلالي هو الحد الدلالي والاشتقاق، لا السمة التوضيحية. + +## لماذا لا نضعه على البنية؟ {#why-not-put-it-on-the-struct} + +````admonish warning title="لا تلحم المعنى المشتق بالبنية" +هذا تصميم يبدأ بالتمثيل. فإذا أُدخل حامل عددي للفروع، نُسخ الاشتقاق أو أعيد تنفيذه، وأصبح النوع الملموس الأول مواصفةً عن غير قصد. + +```rust,noplayground +impl BitBranchStore { + // not recommended: derived branch meaning welded to one bit representation + fn is_ancestor(&self, a: &BitBranch, b: &BitBranch) -> bool { + // derived branch meaning mixed with bit storage + } +} +``` +```` + +تعكس الامتدادات الملكية: + +| الطبقة | المسؤولية | +| --- | --- | +| القدرة الدلالية | تملك المعنى المشتق | +| النوع الملموس | يفسر المعنى الأولي | + +## ركّب باستخدام الحدود {#compose-with-bounds} + +عندما يفسر مستقبِل واحد عدة قدرات، استخدم حدودًا مباشرة: + +```rust,noplayground +#[ext(name = PublishCurrentExt)] +pub impl This +where + This: DocumentAlg + PublishAlg, +{ + async fn publish_current(&self) -> Result<(), Error> { + self.publish(self.document_current()).await + } +} +``` + +````admonish warning title="لا تجمع القدرات في حزمة" +لا تنشئ سمة فائقة لمجرد تقصير الحد: + +```rust,noplayground +trait AppContext: DocumentAlg + PublishAlg {} +``` + +تخفي الحزمة العملية التي تستهلك كل قدرة، وتنشئ واجهة أخرى يتعين على كل مفسر تحقيقها. +```` + +## خمسة معانٍ مختلفة للتركيب {#five-different-composition-meanings} + +اختر الصيغة التي تصف العلاقة بصدق. + +| الحالة | صيغة Rust | +| --- | --- | +| مستقبِل واحد يفسر عدة قدرات | حدود مباشرة | +| قيمة منفصلة تختار السلوك | معامل سياسة صريح | +| تركيب السياسات المستقلة ساكنًا | حاصل ضرب أو بنية عادية | +| بيئة تحمل مفسرًا آخر | إسقاط `HasX` صغير | +| غلاف يحل محل مفسر داخلي | التفويض | + +### سياسة صريحة {#explicit-policy} + +إذا اختيرت الاستراتيجية بصورة مستقلة، فمررها صراحةً إلى الامتداد: + +```rust,noplayground +#[ext(name = CandidateSelectExt)] +pub impl This +where + This: CandidateAlg, +{ + fn select_with(&self, policy: &Policy) -> This::Candidate + where + Policy: SelectionPolicyAlg, + { + policy.select(self.candidates()) + } +} +``` + +يملك الامتداد الاشتقاق المشترك، بينما تظل السياسة مدخلًا يُختار مستقلًا. فلا تُخفى داخل البيئة ولا يختارها `Default`. + +### حاصل ضرب السياسات {#product-of-policies} + +يمكن تركيب السياسات المستقلة من دون اختراع الوراثة: + +```rust,noplayground +struct CompilePolicy { + optimize: Optimize, + diagnostics: Diagnostics, +} +``` + +### الإسقاط {#projection} + +لا تقول السمة `HasClock` إلا إن البيئة تستطيع إسقاط قيمة ساعة منفصلة: + +```rust,noplayground +trait HasClock { + type Clock; + + fn clock(&self) -> &Self::Clock; +} +``` + +تضيف العملية التي تقرأ الوقت `This::Clock: ClockAlg` في جملة `where` الخاصة بها. يعبّر الإسقاط عن الاحتواء، بينما تصرح العملية المستهلكة بالقدرة التي تحتاج إليها. استخدم هذا النمط فقط عندما يكون الفصل حقيقيًا. ولا تُدخل `HasX` لمجرد تنظيم الحقول. + +### التفويض {#delegation} + +يعني التفويض أن الغلاف نفسه يمكن أن يحل محل المفسر الداخلي. ويناسب الأنواع الجديدة الشفافة والمؤشرات المشتركة والمهايئات التي تحافظ على عقد القدرة كاملًا. + +يقول الإسقاط «لديه»، ويقول التفويض «هو». ولا يمكن التبادل بينهما. + +## القيم الافتراضية قرارات دلالية أيضًا {#defaults-are-semantic-decisions-too} + +يمكن للحالات الفارغة الآلية أن تطبق `Default`. أما سياسة المجال فينبغي عادةً التصريح بها. + +غالبًا ما يكون للحالات المفيدة تفسير جبري: القيمة الافتراضية هي عنصر المحايد في التركيب الطبيعي للنوع. فإلحاق مخزن مؤقت فارغ أو الدمج مع خريطة فارغة أو تجميع صفر من التشخيصات لا يضيف شيئًا. وعندما يكون هذا التركيب تجميعيًا، يشكل النوع والعملية مونويدًا، ويمكن لـ `Default` تسمية عنصره المحايد بدلًا من اختيار سياسة. + +قيم افتراضية جيدة: + +* مخزن مؤقت فارغ +* خريطة فارغة +* صفر من التشخيصات المتراكمة + +قيم افتراضية مثيرة للريبة: + +* حد النصاب +* سياسة القائد +* دلالات إعادة المحاولة +* عمق التأكيد +* تنسيق الإخراج + +هذا هو الفرق المهم: لا يفرض العنصر المحايد قرارًا، بينما يختار النصاب أو استراتيجية القائد أو قاعدة إعادة المحاولة سلوك المجال. إذا غيّر تعديل القيمة الافتراضية معنى المجال، فركّب السياسة صراحةً. + +## أبقِ المعنى المشتق مغلقًا {#derived-meaning-should-stay-closed} + +يجب أن يستخدم الامتداد قدراته المعلنة ومدخلاته الصريحة فقط. يجعل الوصول المباشر إلى الحقول والحالة العامة والتحويل إلى نوع ملموس جملة `where` غير صادقة. + +راجع المتن كما لو كان برهانًا على تصريح التبعيات: + +```admonish question title="اختبر كل اشتقاق" +هل يمكن تبرير كل عملية في هذا المتن انطلاقًا من هذه الحدود؟ +``` + +إن لم يمكن ذلك، فالحدود غير مكتملة أو أن الشيفرة تنتمي إلى طبقة أخرى. + +## فحوص المراجعة {#review-checks} + +* هل يُعرّف السلوك المشتق مرة واحدة فوق القدرات؟ +* هل يتجنب الامتداد الحقول والأنواع السياقية الملموسة؟ +* هل تُستخدم حدود مباشرة لمفسر واحد؟ +* هل السياسات قيم صريحة عندما تُختار بصورة مستقلة؟ +* هل يصف الإسقاط والتفويض ما يحدث بصدق؟ +* هل تظهر القيم الافتراضية للمجال في التركيب؟ diff --git a/src/rust-dd/derived-meaning.de.md b/src/rust-dd/derived-meaning.de.md new file mode 100644 index 0000000..f67478b --- /dev/null +++ b/src/rust-dd/derived-meaning.de.md @@ -0,0 +1,204 @@ + + +# Abgeleitete Bedeutung und Komposition {#derived-meaning-and-composition} + +```admonish tip title="Verwandte Themen" +The Semantic View: [Denotational Design](../denotational-design/design.md) +Design by Meaning in Rust: [Capability-Algebren](capability-algebras.md), [Interpreter und Effekte](interpreters.md) +Concepts: [Expression Problem](../concepts/expression-problem.md) +``` + +```admonish note title="Orientierung" +Abgeleitetes Verhalten gehört zu den Capabilities, die es verwendet. Es wird einmal als Erweiterung über diesen Bounds formuliert und gehört keinem konkreten Typ, der sie zufällig implementiert. Die Klausel `where` benennt ehrlich, wovon eine Ableitung abhängt. +``` + +Primitive Capabilities liefern das Vokabular. Der Großteil des Anwendungsverhaltens sollte einmal daraus abgeleitet und von allen Interpretern gemeinsam genutzt werden. + +## Erweiterungen enthalten die Ableitungen {#extensions-own-derivations} + +Mit dem Crate [`extend`](https://docs.rs/extend/latest/extend/) lassen sich Verzweigungsoperationen unabhängig von ihrer Repräsentation ableiten: + +```rust,noplayground +use extend::ext; + +#[ext(name = BranchExt)] +pub impl This +where + This: BranchAlg, +{ + fn branch_child(&self, branch: &This::Branch, direction: Direction) -> This::Branch { + self.branch_grow(branch, direction) + } + + fn branch_left(&self, branch: &This::Branch) -> This::Branch { + self.branch_child(branch, Direction::Left) + } + + fn branch_right(&self, branch: &This::Branch) -> This::Branch { + self.branch_child(branch, Direction::Right) + } + + fn branch_is_ancestor(&self, ancestor: &This::Branch, descendant: &This::Branch) -> bool { + self.branch_path(ancestor, descendant).is_some() + } +} +``` + +Die Klausel `where` ist die vollständige Erklärung der semantischen Abhängigkeit: `BranchAlg` und nichts darüber hinaus. Kein konkreter Verzweigungstyp besitzt diese Definitionen. + +Das Makro erspart lediglich wiederholten Trait- und Implementierungscode. Ein gewöhnliches Erweiterungs-Trait drückt denselben Entwurf aus. Denotational Design liegt in der semantischen Grenze und der Ableitung, nicht im Attribut. + +## Warum nicht in die Struktur aufnehmen? {#why-not-put-it-on-the-struct} + +````admonish warning title="Abgeleitete Bedeutung nicht an die Struktur koppeln" +Das ist repräsentationsorientiert. Wird ein numerischer Träger für Verzweigungen eingeführt, muss die Ableitung kopiert oder neu implementiert werden. So wird der erste konkrete Typ versehentlich zur Spezifikation. + +```rust,noplayground +impl BitBranchStore { + // not recommended: derived branch meaning welded to one bit representation + fn is_ancestor(&self, a: &BitBranch, b: &BitBranch) -> bool { + // derived branch meaning mixed with bit storage + } +} +``` +```` + +Erweiterungen kehren diese Zuständigkeit um: + +| Ebene | Verantwortung | +| --- | --- | +| Semantische Capability | Besitzt die abgeleitete Bedeutung | +| Konkreter Typ | Interpretiert primitive Bedeutung | + +## Mit Bounds komponieren {#compose-with-bounds} + +Wenn ein Empfänger mehrere Capabilities interpretiert, verwende direkte Bounds: + +```rust,noplayground +#[ext(name = PublishCurrentExt)] +pub impl This +where + This: DocumentAlg + PublishAlg, +{ + async fn publish_current(&self) -> Result<(), Error> { + self.publish(self.document_current()).await + } +} +``` + +````admonish warning title="Capabilities nicht bündeln" +Erstelle kein Supertrait, nur um den Bound zu verkürzen: + +```rust,noplayground +trait AppContext: DocumentAlg + PublishAlg {} +``` + +Das Bündel verschleiert, welche Operation welche Capabilities benötigt, und schafft eine weitere Schnittstelle, die jeder Interpreter erfüllen muss. +```` + +## Fünf verschiedene Bedeutungen von Komposition {#five-different-composition-meanings} + +Wähle die Form, die die Beziehung zutreffend beschreibt. + +| Situation | Rust-Form | +| --- | --- | +| Ein Empfänger interpretiert mehrere Capabilities | Direkte Bounds | +| Ein separater Wert wählt das Verhalten | Expliziter Richtlinienparameter | +| Unabhängige Richtlinien werden statisch zusammengesetzt | Produkt oder gewöhnliche Struktur | +| Eine Umgebung enthält einen weiteren Interpreter | Kleine Projektion `HasX` | +| Ein Wrapper tritt an die Stelle eines inneren Interpreters | Delegation | + +### Explizite Richtlinie {#explicit-policy} + +Wenn eine Strategie unabhängig gewählt wird, übergib sie ausdrücklich an die Erweiterung: + +```rust,noplayground +#[ext(name = CandidateSelectExt)] +pub impl This +where + This: CandidateAlg, +{ + fn select_with(&self, policy: &Policy) -> This::Candidate + where + Policy: SelectionPolicyAlg, + { + policy.select(self.candidates()) + } +} +``` + +Die Erweiterung besitzt die gemeinsame Ableitung; die Richtlinie bleibt eine unabhängig gewählte Eingabe. Sie wird weder in der Umgebung versteckt noch von `Default` ausgewählt. + +### Produkt aus Richtlinien {#product-of-policies} + +Unabhängige Richtlinien lassen sich zusammensetzen, ohne Vererbung zu erfinden: + +```rust,noplayground +struct CompilePolicy { + optimize: Optimize, + diagnostics: Diagnostics, +} +``` + +### Projektion {#projection} + +Ein `HasClock`\-Trait besagt lediglich, dass eine Umgebung einen separaten Uhrwert bereitstellen kann: + +```rust,noplayground +trait HasClock { + type Clock; + + fn clock(&self) -> &Self::Clock; +} +``` + +Eine Operation, die die Zeit abfragt, ergänzt `This::Clock: ClockAlg` in ihrer eigenen `where`\-Klausel. Die Projektion bezieht sich weiterhin auf das Enthaltensein; die verwendende Operation nennt die benötigte Capability. Verwende dieses Muster nur, wenn die Trennung tatsächlich besteht. Führe `HasX` nicht bloß ein, um Felder zu ordnen. + +### Delegation {#delegation} + +Delegation bedeutet, dass ein Wrapper den inneren Interpreter selbst ersetzen kann. Das eignet sich für transparente Newtypes, gemeinsam genutzte Zeiger und Adapter, die den gesamten Capability-Vertrag bewahren. + +Projektion bedeutet „hat“. Delegation bedeutet „ist“. Diese Begriffe sind nicht austauschbar. + +## Auch Standardwerte sind semantische Entscheidungen {#defaults-are-semantic-decisions-too} + +Mechanisch leere Zustände können `Default` implementieren. Fachliche Richtlinien sollten normalerweise explizit sein. + +Nützliche Fälle haben oft eine algebraische Erklärung: Der Standardwert ist das neutrale Element bezüglich der natürlichen Komposition des Typs. Einen leeren Puffer anzuhängen, mit einer leeren Map zu verknüpfen oder null Diagnosen zu sammeln trägt nichts bei. Ist diese Komposition assoziativ, bilden Typ und Operation ein Monoid, und `Default` kann dessen neutrales Element benennen, statt eine Richtlinie auszuwählen. + +Gute Standardwerte: + +* Leerer Puffer +* Leere Map +* Keine gesammelten Diagnosen + +Fragwürdige Standardwerte: + +* Quorum-Schwelle +* Führungsrichtlinie +* Wiederholungssemantik +* Bestätigungstiefe +* Ausgabeformat + +Das ist der entscheidende Unterschied: Ein neutrales Element führt keine Entscheidung ein, ein Quorum, eine Führungsstrategie oder eine Wiederholungsregel wählt dagegen ein Verhalten im Fachbereich aus. Ändert ein anderer Standardwert die fachliche Bedeutung, komponiere die Richtlinie ausdrücklich. + +## Abgeleitete Bedeutung sollte abgeschlossen bleiben {#derived-meaning-should-stay-closed} + +Eine Erweiterung darf nur die deklarierten Capabilities und expliziten Eingaben verwenden. Direkter Feldzugriff, globaler Zustand und konkrete Downcasts machen die Klausel `where` unehrlich. + +Prüfe den Methodenrumpf so, als wäre er ein Beweis für die Abhängigkeitserklärung: + +```admonish question title="Jede Ableitung prüfen" +Lässt sich jede Operation in diesem Rumpf durch diese Bounds begründen? +``` + +Falls nicht, sind entweder die Bounds unvollständig oder der Code gehört auf eine andere Ebene. + +## Prüfpunkte für das Review {#review-checks} + +* Ist abgeleitetes Verhalten einmal für Capabilities definiert? +* Vermeidet die Erweiterung konkrete Felder und Kontexttypen? +* Werden für einen Interpreter direkte Bounds verwendet? +* Sind Richtlinien explizite Werte, wenn sie unabhängig gewählt werden? +* Formulieren Projektion und Delegation zutreffende Aussagen? +* Sind fachliche Standardwerte in der Komposition sichtbar? diff --git a/src/rust-dd/derived-meaning.es.md b/src/rust-dd/derived-meaning.es.md new file mode 100644 index 0000000..18b5494 --- /dev/null +++ b/src/rust-dd/derived-meaning.es.md @@ -0,0 +1,204 @@ + + +# Significado derivado y composición {#derived-meaning-and-composition} + +```admonish tip title="Relacionado" +La perspectiva semántica: [Diseño denotacional](../denotational-design/design.md) +Diseño por significado en Rust: [Álgebras de capacidades](capability-algebras.md), [Intérpretes y efectos](interpreters.md) +Conceptos: [Problema de las expresiones](../concepts/expression-problem.md) +``` + +```admonish note title="Orientación" +El comportamiento derivado pertenece a las capacidades que utiliza: se escribe una sola vez como extensión sobre esas restricciones, no en cualquier tipo concreto que las implemente. La cláusula `where` expresa honestamente de qué depende una derivación. +``` + +Las capacidades primitivas proporcionan el vocabulario. La mayor parte del comportamiento de la aplicación debería derivarse una vez de ese vocabulario y compartirse entre todos los intérpretes. + +## Las extensiones son dueñas de las derivaciones {#extensions-own-derivations} + +Con el crate [`extend`](https://docs.rs/extend/latest/extend/), las operaciones de ramificación pueden derivarse independientemente de la representación: + +```rust,noplayground +use extend::ext; + +#[ext(name = BranchExt)] +pub impl This +where + This: BranchAlg, +{ + fn branch_child(&self, branch: &This::Branch, direction: Direction) -> This::Branch { + self.branch_grow(branch, direction) + } + + fn branch_left(&self, branch: &This::Branch) -> This::Branch { + self.branch_child(branch, Direction::Left) + } + + fn branch_right(&self, branch: &This::Branch) -> This::Branch { + self.branch_child(branch, Direction::Right) + } + + fn branch_is_ancestor(&self, ancestor: &This::Branch, descendant: &This::Branch) -> bool { + self.branch_path(ancestor, descendant).is_some() + } +} +``` + +La cláusula `where` es la declaración completa de dependencia semántica: `BranchAlg`, y nada más. Ningún tipo de rama concreto es dueño de estas definiciones. + +El macro solo elimina el código repetitivo de trait e implementación. Un trait de extensión ordinario puede expresar el mismo diseño. El Diseño denotacional está en el límite semántico y en la derivación, no en el atributo. + +## ¿Por qué no colocarlo en la estructura? {#why-not-put-it-on-the-struct} + +````admonish warning title="No sueldes el significado derivado a la estructura" +Esto está centrado en la representación. Si se introduce un portador de ramificación numérico, la derivación se copia o se vuelve a implementar, y el primer tipo concreto se convierte accidentalmente en la especificación. + +```rust,noplayground +impl BitBranchStore { + // not recommended: derived branch meaning welded to one bit representation + fn is_ancestor(&self, a: &BitBranch, b: &BitBranch) -> bool { + // derived branch meaning mixed with bit storage + } +} +``` +```` + +Las extensiones invierten la propiedad: + +| Capa | Responsabilidad | +| --- | --- | +| Capacidad semántica | Es dueña del significado derivado | +| Tipo concreto | Interpreta el significado primitivo | + +## Componer con restricciones {#compose-with-bounds} + +Cuando un mismo receptor interpreta varias capacidades, usa restricciones directas: + +```rust,noplayground +#[ext(name = PublishCurrentExt)] +pub impl This +where + This: DocumentAlg + PublishAlg, +{ + async fn publish_current(&self) -> Result<(), Error> { + self.publish(self.document_current()).await + } +} +``` + +````admonish warning title="No agrupes las capacidades" +No crees un trait superior solo para acortar la restricción: + +```rust,noplayground +trait AppContext: DocumentAlg + PublishAlg {} +``` + +El grupo oculta qué operación consume qué capacidades y crea otra interfaz que todos los intérpretes deben satisfacer. +```` + +## Cinco significados de composición distintos {#five-different-composition-meanings} + +Elige la forma que describa fielmente la relación. + +| Situación | Forma en Rust | +| --- | --- | +| Un receptor interpreta varias capacidades | Restricciones directas | +| Un valor independiente elige el comportamiento | Parámetro de política explícito | +| Las políticas independientes se componen estáticamente | Producto o estructura ordinaria | +| Un entorno contiene otro intérprete | Proyección `HasX` reducida | +| Un envoltorio sustituye a un intérprete interno | Delegación | + +### Política explícita {#explicit-policy} + +Si se elige una estrategia de manera independiente, pásala explícitamente a la extensión: + +```rust,noplayground +#[ext(name = CandidateSelectExt)] +pub impl This +where + This: CandidateAlg, +{ + fn select_with(&self, policy: &Policy) -> This::Candidate + where + Policy: SelectionPolicyAlg, + { + policy.select(self.candidates()) + } +} +``` + +La extensión es dueña de la derivación compartida, mientras que la política sigue siendo una entrada elegida de forma independiente. No queda oculta en el entorno ni la elige `Default`. + +### Producto de políticas {#product-of-policies} + +Las políticas independientes pueden componerse sin inventar herencia: + +```rust,noplayground +struct CompilePolicy { + optimize: Optimize, + diagnostics: Diagnostics, +} +``` + +### Proyección {#projection} + +Un trait `HasClock` solo expresa que un entorno puede proyectar un valor de reloj separado: + +```rust,noplayground +trait HasClock { + type Clock; + + fn clock(&self) -> &Self::Clock; +} +``` + +Una operación que lee la hora añade `This::Clock: ClockAlg` en su propia cláusula `where`. La proyección sigue tratando de contención; la operación consumidora declara la capacidad que necesita. Usa este patrón solo cuando la separación sea real. No introduzcas `HasX` simplemente para organizar campos. + +### Delegación {#delegation} + +Delegar significa que el propio envoltorio puede sustituir al intérprete interno. Es apropiado para newtypes transparentes, punteros compartidos y adaptadores que preservan el contrato completo de capacidad. + +La proyección dice «tiene». La delegación dice «es». No son intercambiables. + +## Los valores predeterminados también son decisiones semánticas {#defaults-are-semantic-decisions-too} + +Los estados vacíos mecánicos pueden implementar `Default`. La política del dominio normalmente debería ser explícita. + +Los casos útiles suelen tener una explicación algebraica: el valor predeterminado es el elemento identidad de la composición natural del tipo. Añadir un búfer vacío, combinar con un mapa vacío o acumular cero diagnósticos no aporta nada. Cuando esa composición es asociativa, el tipo y la operación forman un monoide, y `Default` puede nombrar su elemento neutro en lugar de elegir una política. + +Buenos valores predeterminados: + +* Búfer vacío +* Mapa vacío +* Cero diagnósticos acumulados + +Valores predeterminados sospechosos: + +* Umbral de quórum +* Política de liderazgo +* Semántica de reintentos +* Profundidad de confirmación +* Formato de salida + +Esta es la distinción importante: un elemento neutro no introduce ninguna decisión, mientras que un quórum, una estrategia de liderazgo o una regla de reintento elige el comportamiento del dominio. Si cambiar un valor predeterminado cambia el significado del dominio, compón la política explícitamente. + +## El significado derivado debe mantenerse cerrado {#derived-meaning-should-stay-closed} + +Una extensión solo debe usar sus capacidades declaradas y entradas explícitas. El acceso directo a campos, el estado global y las conversiones descendentes a tipos concretos hacen deshonesta la cláusula `where`. + +Revisa el cuerpo como si fuera una prueba de la declaración de dependencias: + +```admonish question title="Prueba cada derivación" +¿Se puede justificar cada operación de este cuerpo a partir de estas restricciones? +``` + +Si no, las restricciones están incompletas o el código pertenece a otra capa. + +## Comprobaciones de revisión {#review-checks} + +* ¿Se define una sola vez el comportamiento derivado sobre las capacidades? +* ¿La extensión evita campos concretos y tipos de contexto? +* ¿Se usan restricciones directas para un intérprete? +* ¿Las políticas son valores explícitos cuando se eligen de forma independiente? +* ¿La proyección y la delegación hacen afirmaciones veraces? +* ¿Los valores predeterminados del dominio son visibles en la composición? diff --git a/src/rust-dd/derived-meaning.ja.md b/src/rust-dd/derived-meaning.ja.md new file mode 100644 index 0000000..bf2e2b4 --- /dev/null +++ b/src/rust-dd/derived-meaning.ja.md @@ -0,0 +1,204 @@ + + +# 導出される意味と合成 {#derived-meaning-and-composition} + +```admonish tip title="関連項目" +意味論的な見方:[Denotational Design](../denotational-design/design.md) +Rustで意味から設計する:[ケイパビリティ代数](capability-algebras.md)、[インタープリターと副作用](interpreters.md) +概念:[Expression Problem](../concepts/expression-problem.md) +``` + +```admonish note title="概要" +導出された振る舞いは、それが使うケイパビリティに属します。境界を満たす拡張として一度だけ記述し、たまたまそれらを実装する具体型に持たせません。`where`節は、導出が依存するものを正確に表します。 +``` + +基本ケイパビリティは語彙を提供します。アプリケーションの振る舞いの大半は、その語彙から導出して、すべてのインタープリターで共有するべきです。 + +## 導出は拡張に持たせる {#extensions-own-derivations} + +[`extend`](https://docs.rs/extend/latest/extend/)クレートを使うと、表現に依存せず分岐操作を導出できます。 + +```rust,noplayground +use extend::ext; + +#[ext(name = BranchExt)] +pub impl This +where + This: BranchAlg, +{ + fn branch_child(&self, branch: &This::Branch, direction: Direction) -> This::Branch { + self.branch_grow(branch, direction) + } + + fn branch_left(&self, branch: &This::Branch) -> This::Branch { + self.branch_child(branch, Direction::Left) + } + + fn branch_right(&self, branch: &This::Branch) -> This::Branch { + self.branch_child(branch, Direction::Right) + } + + fn branch_is_ancestor(&self, ancestor: &This::Branch, descendant: &This::Branch) -> bool { + self.branch_path(ancestor, descendant).is_some() + } +} +``` + +`where`節は意味論的な依存関係をすべて宣言します。`BranchAlg`だけで、それ以上はありません。これらの定義を所有する具体的な分岐型はありません。 + +マクロが取り除くのは、トレイトや実装の定型コードだけです。通常の拡張トレイトでも同じ設計を表現できます。Denotational Designの要点は属性ではなく、意味論上の境界と導出にあります。 + +## なぜ構造体に持たせないのか。 {#why-not-put-it-on-the-struct} + +````admonish warning title="導出された意味を構造体に固定しない" +これは表現先行の設計です。数値による分岐の担体を導入すると、導出をコピーするか再実装することになり、最初の具体型が意図せず仕様になってしまいます。 + +```rust,noplayground +impl BitBranchStore { + // not recommended: derived branch meaning welded to one bit representation + fn is_ancestor(&self, a: &BitBranch, b: &BitBranch) -> bool { + // derived branch meaning mixed with bit storage + } +} +``` +```` + +拡張では所有関係を逆転させます。 + +| 層 | 責務 | +| --- | --- | +| 意味論的ケイパビリティ | 導出される意味を所有する | +| 具体型 | 基本的な意味を解釈する | + +## 境界で合成する {#compose-with-bounds} + +一つのレシーバーが複数のケイパビリティを解釈するなら、直接境界を使います。 + +```rust,noplayground +#[ext(name = PublishCurrentExt)] +pub impl This +where + This: DocumentAlg + PublishAlg, +{ + async fn publish_current(&self) -> Result<(), Error> { + self.publish(self.document_current()).await + } +} +``` + +````admonish warning title="ケイパビリティをひとまとめにしない" +境界を短く書くためだけにスーパー トレイトを作らないでください。 + +```rust,noplayground +trait AppContext: DocumentAlg + PublishAlg {} +``` + +ひとまとめにすると、どの操作がどのケイパビリティを使うかが見えなくなり、すべてのインタープリターが満たすべき別のインターフェースを生み出します。 +```` + +## 五種類の異なる合成上の意味 {#five-different-composition-meanings} + +関係を正確に表す形式を選びます。 + +| 状況 | Rustでの形 | +| --- | --- | +| 一つのレシーバーが複数のケイパビリティを解釈する | 直接境界 | +| 別の値が振る舞いを選択する | 明示的なポリシー引数 | +| 独立したポリシーを静的に合成する | プロダクト型または通常の構造体 | +| 環境が別のインタープリターを保持する | 小さな`HasX`射影 | +| ラッパーが内部のインタープリターを代用する | 委譲 | + +### 明示的なポリシー {#explicit-policy} + +戦略を個別に選ぶなら、拡張に明示的に渡します。 + +```rust,noplayground +#[ext(name = CandidateSelectExt)] +pub impl This +where + This: CandidateAlg, +{ + fn select_with(&self, policy: &Policy) -> This::Candidate + where + Policy: SelectionPolicyAlg, + { + policy.select(self.candidates()) + } +} +``` + +拡張が共通の導出を所有し、ポリシーは個別に選択する入力として残ります。環境内に隠すものでも、`Default`が選ぶものでもありません。 + +### ポリシーの積 {#product-of-policies} + +継承を作り出さずに、独立したポリシーを合成できます。 + +```rust,noplayground +struct CompilePolicy { + optimize: Optimize, + diagnostics: Diagnostics, +} +``` + +### 射影 {#projection} + +`HasClock`トレイトは、環境から独立した時計の値を射影できることだけを示します。 + +```rust,noplayground +trait HasClock { + type Clock; + + fn clock(&self) -> &Self::Clock; +} +``` + +時間を読む操作は、それ自身の`This::Clock: ClockAlg`節に`where`を追加します。射影が表すのは包含関係であり、利用側の操作は必要なケイパビリティを明示します。この分離が実際に存在する場合に限り、このパターンを使います。フィールドを整理するためだけに`HasX`を導入してはいけません。 + +### 委譲 {#delegation} + +委譲とは、ラッパー自身が内部のインタープリターの代わりになれることです。透明なnewtype、共有ポインター、ケイパビリティの契約全体を保持するアダプターに適しています。 + +射影は「持つ」を表し、委譲は「である」を表します。互いに置き換えられません。 + +## デフォルトも意味論上の判断 {#defaults-are-semantic-decisions-too} + +機械的な空状態には`Default`を実装できます。領域上のポリシーは、通常は明示します。 + +有用なケースの多くは代数的に説明できます。デフォルトは、その型に自然な合成における単位元です。空バッファーの追加、空マップとの結合、診断のゼロ件の累積は、何も付け加えません。その合成が結合的なら、型と操作はモノイドを成し、`Default`はポリシーを選ぶのではなく中立元を表せます。 + +適切なデフォルト: + +* 空バッファー +* 空マップ +* 累積された診断のゼロ件 + +注意を要するデフォルト: + +* クォーラムの閾値 +* リーダーのポリシー +* 再試行の意味 +* 確認の深さ +* 出力形式 + +重要なのは、中立元は判断を持ち込まない一方、クォーラム、リーダー戦略、再試行規則は領域の振る舞いを選ぶという違いです。デフォルトを変えると領域の意味が変わる場合は、ポリシーを明示的に合成してください。 + +## 導出される意味は閉じたままにする {#derived-meaning-should-stay-closed} + +拡張は宣言されたケイパビリティと明示的な入力だけを使わなければなりません。フィールドへの直接アクセス、グローバル状態、具体型へのダウンキャストがあると、`where`節が実態を表さなくなります。 + +依存関係の宣言を証明するつもりで、本体を見直します。 + +```admonish question title="各導出を確認する" +この本体の各操作を、これらの境界から正当化できるか。 +``` + +できない場合は、境界が不足しているか、コードを別の層に置く必要があります。 + +## レビュー時の確認 {#review-checks} + +* 導出された振る舞いは、ケイパビリティに基づき一度だけ定義されているか。 +* 拡張は具体的なフィールドやコンテキスト型を避けているか。 +* 一つのインタープリターには直接境界を使っているか。 +* 個別に選ぶポリシーを、明示的な値として渡しているか。 +* 射影と委譲は正確な関係を主張しているか。 +* 領域のデフォルトを合成の中で見えるようにしているか。 diff --git a/src/rust-dd/derived-meaning.ko.md b/src/rust-dd/derived-meaning.ko.md new file mode 100644 index 0000000..c291c2c --- /dev/null +++ b/src/rust-dd/derived-meaning.ko.md @@ -0,0 +1,204 @@ + + +# 파생 의미와 합성 {#derived-meaning-and-composition} + +```admonish tip title="관련 항목" +의미론적 관점: [표시적 설계](../denotational-design/design.md) +Rust에서 의미로 설계하기: [케이퍼빌리티 대수](capability-algebras.md), [인터프리터와 효과](interpreters.md) +개념: [표현식 문제](../concepts/expression-problem.md) +``` + +```admonish note title="개요" +파생 동작은 사용하는 케이퍼빌리티에 속합니다. 그 경계를 구현한 특정 타입에 넣지 말고, 필요한 바운드에 대한 확장으로 한 번 작성해 모든 인터프리터가 공유하게 하세요. `where` 절은 도출이 의존하는 것을 정직하게 명시합니다. +``` + +기본 케이퍼빌리티는 어휘를 제공합니다. 애플리케이션 동작 대부분은 그 어휘에서 파생해 한 번 작성하고 모든 인터프리터가 공유해야 합니다. + +## 확장이 도출을 소유합니다 {#extensions-own-derivations} + +[`extend`](https://docs.rs/extend/latest/extend/) 크레이트를 사용하면 표현과 독립적으로 분기 연산을 도출할 수 있습니다: + +```rust,noplayground +use extend::ext; + +#[ext(name = BranchExt)] +pub impl This +where + This: BranchAlg, +{ + fn branch_child(&self, branch: &This::Branch, direction: Direction) -> This::Branch { + self.branch_grow(branch, direction) + } + + fn branch_left(&self, branch: &This::Branch) -> This::Branch { + self.branch_child(branch, Direction::Left) + } + + fn branch_right(&self, branch: &This::Branch) -> This::Branch { + self.branch_child(branch, Direction::Right) + } + + fn branch_is_ancestor(&self, ancestor: &This::Branch, descendant: &This::Branch) -> bool { + self.branch_path(ancestor, descendant).is_some() + } +} +``` + +`where` 절은 의미론적 의존성을 완전히 선언합니다. `BranchAlg`뿐이며 그 이상은 필요 없습니다. 구체적인 분기 타입은 이 정의를 소유하지 않습니다. + +매크로는 트레이트 및 구현의 상용구만 줄입니다. 일반 확장 트레이트로도 같은 설계를 표현할 수 있습니다. 표시적 설계의 핵심은 어트리뷰트가 아니라 의미론적 경계와 도출에 있습니다. + +## 왜 구조체에 넣지 않을까요? {#why-not-put-it-on-the-struct} + +````admonish warning title="파생 의미를 구조체에 묶지 마세요" +이것은 표현 우선 설계입니다. 수치형 분기 기반 집합을 추가하면 도출을 복사하거나 다시 구현해야 하고, 첫 구체 타입이 의도치 않게 명세가 됩니다. + +```rust,noplayground +impl BitBranchStore { + // not recommended: derived branch meaning welded to one bit representation + fn is_ancestor(&self, a: &BitBranch, b: &BitBranch) -> bool { + // derived branch meaning mixed with bit storage + } +} +``` +```` + +확장은 소유 관계를 뒤집습니다: + +| 계층 | 책임 | +| --- | --- | +| 의미론적 케이퍼빌리티 | 파생 의미를 소유합니다 | +| 구체 타입 | 기본 의미를 해석합니다 | + +## 바운드로 합성하기 {#compose-with-bounds} + +하나의 수신자가 여러 케이퍼빌리티를 해석하면 직접 바운드를 사용하세요: + +```rust,noplayground +#[ext(name = PublishCurrentExt)] +pub impl This +where + This: DocumentAlg + PublishAlg, +{ + async fn publish_current(&self) -> Result<(), Error> { + self.publish(self.document_current()).await + } +} +``` + +````admonish warning title="케이퍼빌리티를 한데 묶지 마세요" +바운드를 짧게 쓰려고 상위 트레이트를 만들지 마세요: + +```rust,noplayground +trait AppContext: DocumentAlg + PublishAlg {} +``` + +이 묶음은 어떤 연산이 어떤 케이퍼빌리티를 사용하는지 감추고, 모든 인터프리터가 만족해야 할 인터페이스를 하나 더 만듭니다. +```` + +## 서로 다른 다섯 가지 합성 의미 {#five-different-composition-meanings} + +관계를 정확히 설명하는 형태를 선택하세요. + +| 상황 | Rust 표현 | +| --- | --- | +| 하나의 수신자가 여러 케이퍼빌리티를 해석함 | 직접 바운드 | +| 별도 값이 동작을 선택함 | 명시적 정책 매개변수 | +| 독립 정책을 정적으로 합성함 | 곱 또는 일반 구조체 | +| 환경이 다른 인터프리터를 담음 | 작은 `HasX` 투영 | +| 래퍼가 내부 인터프리터를 대체함 | 위임 | + +### 명시적 정책 {#explicit-policy} + +전략을 독립적으로 선택한다면 확장에 명시적으로 전달하세요: + +```rust,noplayground +#[ext(name = CandidateSelectExt)] +pub impl This +where + This: CandidateAlg, +{ + fn select_with(&self, policy: &Policy) -> This::Candidate + where + Policy: SelectionPolicyAlg, + { + policy.select(self.candidates()) + } +} +``` + +확장은 공유되는 도출을 소유하고 정책은 독립적으로 선택되는 입력으로 남습니다. 환경 안에 숨기거나 `Default`로 선택하지 않습니다. + +### 정책의 곱 {#product-of-policies} + +상속을 만들어 내지 않고 독립 정책을 합성할 수 있습니다: + +```rust,noplayground +struct CompilePolicy { + optimize: Optimize, + diagnostics: Diagnostics, +} +``` + +### 투영 {#projection} + +`HasClock` 트레이트는 환경이 별도의 시계 값을 투영할 수 있다는 것만 말합니다: + +```rust,noplayground +trait HasClock { + type Clock; + + fn clock(&self) -> &Self::Clock; +} +``` + +시간을 읽는 연산은 자체 `where` 절에 `This::Clock: ClockAlg`을 추가합니다. 투영은 포함 관계에 관한 것이고, 값을 사용하는 연산은 필요한 케이퍼빌리티를 명시합니다. 실제로 분리가 있을 때만 이 패턴을 사용하세요. 필드 정리용으로 `HasX`를 만들지 마세요. + +### 위임 {#delegation} + +위임은 래퍼 자체가 내부 인터프리터를 대체할 수 있음을 뜻합니다. 투명한 뉴타입, 공유 포인터, 전체 케이퍼빌리티 계약을 보존하는 어댑터에 적합합니다. + +투영은 “가지고 있다”는 뜻이고, 위임은 “그 자체다”라는 뜻입니다. 서로 바꿔 쓸 수 없습니다. + +## 기본값도 의미론적 결정입니다 {#defaults-are-semantic-decisions-too} + +기계적인 빈 상태에는 `Default`를 구현할 수 있습니다. 도메인 정책은 대개 명시적이어야 합니다. + +유용한 경우에는 흔히 대수적 설명이 있습니다. 기본값이 타입의 자연스러운 합성에서 항등 원소인 것입니다. 빈 버퍼를 덧붙이거나 빈 맵을 결합하거나 진단 수 0을 누적해도 아무것도 더해지지 않습니다. 그 합성이 결합적이면 타입과 연산은 모노이드를 이루며, `Default`는 정책을 선택하는 대신 그 중립 원소를 나타낼 수 있습니다. + +좋은 기본값: + +* 빈 버퍼 +* 빈 맵 +* 누적된 진단 수 0 + +의심스러운 기본값: + +* 정족수 기준 +* 리더 정책 +* 재시도 의미 +* 확인 깊이 +* 출력 형식 + +핵심 구분은 다음과 같습니다. 중립 원소는 결정을 추가하지 않지만, 정족수, 리더 전략, 재시도 규칙은 도메인의 동작을 선택합니다. 기본값을 바꾸면 도메인의 의미가 바뀌는 경우 정책을 명시적으로 합성하세요. + +## 파생 의미는 닫힌 상태를 유지해야 합니다 {#derived-meaning-should-stay-closed} + +확장은 선언된 케이퍼빌리티와 명시적 입력만 사용해야 합니다. 필드 직접 접근, 전역 상태, 구체 타입으로의 다운캐스팅은 `where` 절을 부정확하게 만듭니다. + +의존성 선언을 증명하듯 메서드 본문을 검토하세요: + +```admonish question title="각 도출을 검사하세요" +이 본문에 있는 모든 연산을 이 바운드만으로 정당화할 수 있나요? +``` + +그렇지 않다면 바운드가 불완전하거나 코드가 다른 계층에 속하는 것입니다. + +## 검토 항목 {#review-checks} + +* 파생 동작을 케이퍼빌리티에 대해 한 번 정의했나요? +* 확장에서 구체 필드와 컨텍스트 타입을 피하나요? +* 인터프리터 하나를 위해 직접 바운드를 사용하나요? +* 독립 선택 정책은 명시적 값인가요? +* 투영과 위임이 각각 정확한 주장을 하나요? +* 도메인 기본값이 합성 과정에서 드러나나요? diff --git a/src/rust-dd/derived-meaning.ru.md b/src/rust-dd/derived-meaning.ru.md new file mode 100644 index 0000000..a46f5f5 --- /dev/null +++ b/src/rust-dd/derived-meaning.ru.md @@ -0,0 +1,204 @@ + + +# Производный смысл и композиция {#derived-meaning-and-composition} + +```admonish tip title="Связанные материалы" +«Семантический взгляд»: [Денотационное проектирование](../denotational-design/design.md) +«Проектирование на основе смысла в Rust»: [Алгебры возможностей](capability-algebras.md), [Интерпретаторы и эффекты](interpreters.md) +«Понятия»: [Проблема выражения](../concepts/expression-problem.md) +``` + +```admonish note title="Обзор" +Производное поведение относится к используемым им возможностям и один раз задаётся как расширение поверх соответствующих ограничений, а не привязывается к конкретному типу, который случайно их реализует. Условие `where` — точное описание зависимостей вывода. +``` + +Примитивные возможности задают словарь. Большая часть поведения приложения должна один раз выводиться из него и использоваться совместно всеми интерпретаторами. + +## Расширения отвечают за выводимые операции {#extensions-own-derivations} + +С помощью крейта [`extend`](https://docs.rs/extend/latest/extend/) операции над ветвями можно вывести независимо от представления: + +```rust,noplayground +use extend::ext; + +#[ext(name = BranchExt)] +pub impl This +where + This: BranchAlg, +{ + fn branch_child(&self, branch: &This::Branch, direction: Direction) -> This::Branch { + self.branch_grow(branch, direction) + } + + fn branch_left(&self, branch: &This::Branch) -> This::Branch { + self.branch_child(branch, Direction::Left) + } + + fn branch_right(&self, branch: &This::Branch) -> This::Branch { + self.branch_child(branch, Direction::Right) + } + + fn branch_is_ancestor(&self, ancestor: &This::Branch, descendant: &This::Branch) -> bool { + self.branch_path(ancestor, descendant).is_some() + } +} +``` + +Условие `where` — полное объявление семантических зависимостей: `BranchAlg` и ничего больше. Ни один конкретный тип ветви не владеет этими определениями. + +Макрос лишь устраняет шаблонный код трейта и его реализации. То же проектирование можно выразить обычным трейтом-расширением. Денотационное проектирование заключается в семантической границе и выводе операций, а не в атрибуте. + +## Почему бы не поместить это в структуру? {#why-not-put-it-on-the-struct} + +````admonish warning title="Не привязывайте производный смысл к структуре" +Это проектирование от представления. При добавлении числового носителя ветвления производный код придётся копировать или реализовывать заново, и первый конкретный тип случайно станет спецификацией. + +```rust,noplayground +impl BitBranchStore { + // not recommended: derived branch meaning welded to one bit representation + fn is_ancestor(&self, a: &BitBranch, b: &BitBranch) -> bool { + // derived branch meaning mixed with bit storage + } +} +``` +```` + +Расширения меняют направление владения: + +| Слой | Ответственность | +| --- | --- | +| Семантическая возможность | Владеет производным смыслом | +| Конкретный тип | Интерпретирует примитивный смысл | + +## Композиция с ограничениями {#compose-with-bounds} + +Если один получатель интерпретирует несколько возможностей, используйте прямые ограничения: + +```rust,noplayground +#[ext(name = PublishCurrentExt)] +pub impl This +where + This: DocumentAlg + PublishAlg, +{ + async fn publish_current(&self) -> Result<(), Error> { + self.publish(self.document_current()).await + } +} +``` + +````admonish warning title="Не объединяйте возможности в пакет" +Не создавайте супертрейт только ради сокращения списка ограничений: + +```rust,noplayground +trait AppContext: DocumentAlg + PublishAlg {} +``` + +Пакет скрывает, какие операции используют какие возможности, и создаёт ещё один интерфейс, которому должен соответствовать каждый интерпретатор. +```` + +## Пять разных смыслов композиции {#five-different-composition-meanings} + +Выберите форму, которая точно описывает отношение. + +| Ситуация | Форма Rust | +| --- | --- | +| Один получатель интерпретирует несколько возможностей | Прямые ограничения | +| Отдельное значение выбирает поведение | Явный параметр политики | +| Независимые политики статически объединяются | Произведение или обычная структура | +| Среда содержит другой интерпретатор | Небольшая проекция `HasX` | +| Обёртка подменяет внутренний интерпретатор | Делегирование | + +### Явная политика {#explicit-policy} + +Если стратегия выбирается независимо, явно передайте её расширению: + +```rust,noplayground +#[ext(name = CandidateSelectExt)] +pub impl This +where + This: CandidateAlg, +{ + fn select_with(&self, policy: &Policy) -> This::Candidate + where + Policy: SelectionPolicyAlg, + { + policy.select(self.candidates()) + } +} +``` + +Расширение владеет общей производной операцией, а политика остаётся независимо выбираемым входным значением. Она не скрыта в среде и не выбирается с помощью `Default`. + +### Произведение политик {#product-of-policies} + +Независимые политики можно объединять, не вводя наследование: + +```rust,noplayground +struct CompilePolicy { + optimize: Optimize, + diagnostics: Diagnostics, +} +``` + +### Проекция {#projection} + +Трейт `HasClock` лишь указывает, что среда может извлечь отдельное значение часов: + +```rust,noplayground +trait HasClock { + type Clock; + + fn clock(&self) -> &Self::Clock; +} +``` + +Операция, считывающая время, добавляет `This::Clock: ClockAlg` в собственное условие `where`. Проекция описывает только наличие компонента; потребляющая его операция указывает нужную возможность. Используйте этот подход, только если разделение действительно. Не вводите `HasX` лишь для упорядочивания полей. + +### Делегирование {#delegation} + +Делегирование означает, что обёртка сама может подменить внутренний интерпретатор. Это уместно для прозрачных новых типов, разделяемых указателей и адаптеров, сохраняющих весь контракт возможности. + +Проекция говорит «имеет», делегирование — «является». Это не взаимозаменяемые понятия. + +## Значения по умолчанию — тоже семантические решения {#defaults-are-semantic-decisions-too} + +Механические пустые состояния могут реализовывать `Default`. Политика предметной области обычно должна задаваться явно. + +У полезных случаев часто есть алгебраическое объяснение: значение по умолчанию — нейтральный элемент естественной композиции типа. Добавление пустого буфера, объединение с пустой картой или накопление нуля диагностик ничего не добавляет. Если композиция ассоциативна, тип вместе с операцией образует моноид, а `Default` обозначает его нейтральный элемент, а не выбирает политику. + +Хорошие значения по умолчанию: + +* Пустой буфер +* Пустая карта +* Нулевое число накопленных диагностик + +Подозрительные значения по умолчанию: + +* Порог кворума +* Политика выбора лидера +* Семантика повторных попыток +* Глубина подтверждения +* Формат вывода + +В этом и состоит различие: нейтральный элемент не вносит решения, а кворум, стратегия выбора лидера или правило повторных попыток задают поведение предметной области. Если изменение значения по умолчанию меняет смысл предметной области, явно включайте политику в композицию. + +## Производный смысл должен оставаться замкнутым {#derived-meaning-should-stay-closed} + +Расширение должно использовать только объявленные возможности и явные входы. Прямой доступ к полям, глобальное состояние и приведение к конкретному типу делают условие `where` нечестным. + +Проверяйте тело так, будто это доказательство объявления зависимостей: + +```admonish question title="Проверяйте каждое выведение" +Можно ли обосновать каждую операцию в этом теле заданными ограничениями? +``` + +Если нет, то либо ограничения неполны, либо код относится к другому слою. + +## Проверочные вопросы {#review-checks} + +* Задаётся ли производное поведение один раз поверх возможностей? +* Избегает ли расширение конкретных полей и типов контекста? +* Используются ли прямые ограничения для одного интерпретатора? +* Являются ли политики явными значениями, когда выбираются независимо? +* Правдиво ли проекция и делегирование описывают свои отношения? +* Видны ли в композиции значения предметной области по умолчанию? diff --git a/src/rust-dd/derived-meaning.uk.md b/src/rust-dd/derived-meaning.uk.md new file mode 100644 index 0000000..eee26ec --- /dev/null +++ b/src/rust-dd/derived-meaning.uk.md @@ -0,0 +1,204 @@ + + +# Похідне значення та композиція {#derived-meaning-and-composition} + +```admonish tip title="Пов’язані матеріали" +Семантичний погляд: [Денотаційне проєктування](../denotational-design/design.md) +Проєктування від значення в Rust: [Алгебри можливостей](capability-algebras.md), [Інтерпретатори й ефекти](interpreters.md) +Поняття: [Проблема виразів](../concepts/expression-problem.md) +``` + +```admonish note title="Вступний огляд" +Похідна поведінка належить можливостям, які вона використовує: її один раз визначають як розширення з відповідними обмеженнями, а не додають до конкретного типу, який випадково їх реалізує. Умова `where` чітко визначає всі залежності виведення. +``` + +Примітивні можливості надають термінологію. Більшість поведінки застосунку слід один раз вивести з цієї термінології, а тоді використовувати в кожному інтерпретаторі. + +## Розширення містять похідні визначення {#extensions-own-derivations} + +Завдяки крейту [`extend`](https://docs.rs/extend/latest/extend/) операції розгалуження можна виводити незалежно від представлення: + +```rust,noplayground +use extend::ext; + +#[ext(name = BranchExt)] +pub impl This +where + This: BranchAlg, +{ + fn branch_child(&self, branch: &This::Branch, direction: Direction) -> This::Branch { + self.branch_grow(branch, direction) + } + + fn branch_left(&self, branch: &This::Branch) -> This::Branch { + self.branch_child(branch, Direction::Left) + } + + fn branch_right(&self, branch: &This::Branch) -> This::Branch { + self.branch_child(branch, Direction::Right) + } + + fn branch_is_ancestor(&self, ancestor: &This::Branch, descendant: &This::Branch) -> bool { + self.branch_path(ancestor, descendant).is_some() + } +} +``` + +Умова `where` — це повне оголошення семантичних залежностей: лише `BranchAlg` й нічого більше. Жоден конкретний тип гілки не містить цих визначень. + +Макрос лише прибирає шаблонний код трейтів та реалізацій. Той самий задум можна виразити звичайним трейтом-розширенням. Денотаційне проєктування полягає в семантичній межі та виведенні операцій, а не в атрибуті. + +## Чому не додати це до структури? {#why-not-put-it-on-the-struct} + +````admonish warning title="Не прив’язуйте похідне значення до структури" +Це проєктування, що виходить із представлення. Якщо додати числовий носій гілок, визначення доведеться копіювати або реалізовувати заново, а перший конкретний тип непомітно стане специфікацією. + +```rust,noplayground +impl BitBranchStore { + // not recommended: derived branch meaning welded to one bit representation + fn is_ancestor(&self, a: &BitBranch, b: &BitBranch) -> bool { + // derived branch meaning mixed with bit storage + } +} +``` +```` + +Розширення змінюють розподіл відповідальності: + +| Рівень | Відповідальність | +| --- | --- | +| Семантична можливість | Містить похідне значення | +| Конкретний тип | Інтерпретує примітивне значення | + +## Комбінуйте за допомогою обмежень {#compose-with-bounds} + +Коли один приймач інтерпретує кілька можливостей, використовуйте прямі обмеження: + +```rust,noplayground +#[ext(name = PublishCurrentExt)] +pub impl This +where + This: DocumentAlg + PublishAlg, +{ + async fn publish_current(&self) -> Result<(), Error> { + self.publish(self.document_current()).await + } +} +``` + +````admonish warning title="Не об’єднуйте можливості в пакет" +Не створюйте супертрейт лише для скорочення обмеження: + +```rust,noplayground +trait AppContext: DocumentAlg + PublishAlg {} +``` + +Такий пакет приховує, яка операція використовує які можливості, і створює ще один інтерфейс, якому мають відповідати всі інтерпретатори. +```` + +## П’ять різних значень композиції {#five-different-composition-meanings} + +Вибирайте форму, яка правдиво описує зв’язок. + +| Ситуація | Форма Rust | +| --- | --- | +| Один приймач інтерпретує кілька можливостей | Прямі обмеження | +| Окреме значення вибирає поведінку | Явний параметр політики | +| Незалежні політики композиційно поєднуються під час компіляції | Добуток або звичайна структура | +| Середовище містить інший інтерпретатор | Невелика проєкція `HasX` | +| Обгортка замінює внутрішній інтерпретатор | Делегування | + +### Явна політика {#explicit-policy} + +Якщо стратегію вибирають окремо, явно передавайте її розширенню: + +```rust,noplayground +#[ext(name = CandidateSelectExt)] +pub impl This +where + This: CandidateAlg, +{ + fn select_with(&self, policy: &Policy) -> This::Candidate + where + Policy: SelectionPolicyAlg, + { + policy.select(self.candidates()) + } +} +``` + +Розширення містить спільне похідне визначення, а політика залишається незалежно вибраним вхідним значенням. Її не приховано в середовищі й не вибрано через `Default`. + +### Добуток політик {#product-of-policies} + +Незалежні політики можна поєднувати без вигадування успадкування: + +```rust,noplayground +struct CompilePolicy { + optimize: Optimize, + diagnostics: Diagnostics, +} +``` + +### Проєкція {#projection} + +Трейт `HasClock` лише стверджує, що середовище може отримати окреме значення годинника: + +```rust,noplayground +trait HasClock { + type Clock; + + fn clock(&self) -> &Self::Clock; +} +``` + +Операція, яка читає час, додає `This::Clock: ClockAlg` до власної умови `where`. Проєкція стосується наявності значення, а операція-споживач заявляє потрібну їй можливість. Використовуйте цей підхід лише за реального розділення. Не вводьте `HasX` лише для впорядкування полів. + +### Делегування {#delegation} + +Делегування означає, що сама обгортка може замінити внутрішній інтерпретатор. Воно доречне для прозорих нових типів, спільних вказівників і адаптерів, які зберігають увесь контракт можливостей. + +Проєкція означає «має». Делегування означає «є». Це різні поняття. + +## Значення визначають і значення за замовчуванням {#defaults-are-semantic-decisions-too} + +Механічні порожні стани можна реалізувати через `Default`. Політику предметної області зазвичай слід задавати явно. + +Часто корисні випадки мають алгебраїчне пояснення: значення за замовчуванням є нейтральним елементом природної композиції типу. Додавання порожнього буфера, об’єднання з порожньою мапою чи накопичення нуля діагностичних повідомлень нічого не додає. Коли така композиція асоціативна, тип і операція утворюють моноїд, а `Default` може назвати нейтральний елемент замість вибору політики. + +Вдалі значення за замовчуванням: + +* Порожній буфер +* Порожня мапа +* Нуль накопичених діагностичних повідомлень + +Сумнівні значення за замовчуванням: + +* Поріг кворуму +* Політика лідера +* Семантика повторних спроб +* Глибина підтвердження +* Формат виведення + +Важливо розрізняти нейтральний елемент, який не вимагає рішення, і кворум, стратегію лідера чи правило повторних спроб, які задають поведінку предметної області. Якщо зміна значення за замовчуванням змінює значення предметної області, явно композиційно поєднуйте політику. + +## Похідне значення має спиратися лише на оголошене {#derived-meaning-should-stay-closed} + +Розширення має використовувати лише заявлені можливості та явні вхідні значення. Прямий доступ до полів, глобальний стан і приведення до конкретних типів роблять умову `where` неправдивою. + +Перевіряйте тіло так, ніби це доведення оголошених залежностей: + +```admonish question title="Перевірте кожне виведення" +Чи можна обґрунтувати кожну операцію в цьому тілі наведеними обмеженнями? +``` + +Якщо ні, або обмежень бракує, або код належить до іншого рівня. + +## Перевірка {#review-checks} + +* Чи визначено похідну поведінку один раз на рівні можливостей? +* Чи уникає розширення конкретних полів і типів контексту? +* Чи використовуються прямі обмеження для одного інтерпретатора? +* Чи задано політики явними значеннями, якщо їх вибирають окремо? +* Чи правдиво описують проєкція й делегування свої зв’язки? +* Чи помітні політики предметної області під час композиції? diff --git a/src/rust-dd/derived-meaning.vi.md b/src/rust-dd/derived-meaning.vi.md new file mode 100644 index 0000000..e047807 --- /dev/null +++ b/src/rust-dd/derived-meaning.vi.md @@ -0,0 +1,204 @@ + + +# Ý nghĩa suy ra và phép hợp thành {#derived-meaning-and-composition} + +```admonish tip title="Liên quan" +Góc nhìn ngữ nghĩa: [Thiết kế theo ngữ nghĩa](../denotational-design/design.md) +Thiết kế theo ngữ nghĩa trong Rust: [Các đại số năng lực](capability-algebras.md), [Bộ diễn giải và hiệu ứng](interpreters.md) +Khái niệm: [Bài toán biểu thức](../concepts/expression-problem.md) +``` + +```admonish note title="Định hướng" +Hành vi suy ra thuộc về các năng lực mà nó sử dụng; hãy viết hành vi đó một lần như phần mở rộng dựa trên những ràng buộc ấy, thay vì gắn vào một kiểu cụ thể tình cờ triển khai chúng. Mệnh đề `where` nêu trung thực các phụ thuộc của phép suy ra. +``` + +Năng lực nguyên thủy cung cấp từ vựng. Phần lớn hành vi ứng dụng nên được suy ra từ từ vựng đó một lần và dùng chung cho mọi bộ diễn giải. + +## Phần mở rộng sở hữu phép suy ra {#extensions-own-derivations} + +Dùng crate [`extend`](https://docs.rs/extend/latest/extend/), có thể suy ra các phép toán nhánh độc lập với cách biểu diễn: + +```rust,noplayground +use extend::ext; + +#[ext(name = BranchExt)] +pub impl This +where + This: BranchAlg, +{ + fn branch_child(&self, branch: &This::Branch, direction: Direction) -> This::Branch { + self.branch_grow(branch, direction) + } + + fn branch_left(&self, branch: &This::Branch) -> This::Branch { + self.branch_child(branch, Direction::Left) + } + + fn branch_right(&self, branch: &This::Branch) -> This::Branch { + self.branch_child(branch, Direction::Right) + } + + fn branch_is_ancestor(&self, ancestor: &This::Branch, descendant: &This::Branch) -> bool { + self.branch_path(ancestor, descendant).is_some() + } +} +``` + +Mệnh đề `where` là khai báo đầy đủ các phụ thuộc ngữ nghĩa: `BranchAlg` và không gì hơn. Không có kiểu nhánh cụ thể nào sở hữu các định nghĩa này. + +Macro chỉ loại bỏ phần khuôn mẫu của đặc trưng và phần triển khai. Đặc trưng mở rộng thông thường cũng biểu đạt được cùng thiết kế. Thiết kế theo ngữ nghĩa nằm ở ranh giới ngữ nghĩa và phép suy ra, không nằm ở thuộc tính macro. + +## Vì sao không đặt nó lên cấu trúc? {#why-not-put-it-on-the-struct} + +````admonish warning title="Đừng hàn ý nghĩa suy ra vào cấu trúc" +Đây là cách tiếp cận ưu tiên biểu diễn. Nếu bổ sung đối tượng mang nhánh dạng số, phép suy ra sẽ bị sao chép hoặc triển khai lại, và kiểu cụ thể đầu tiên vô tình trở thành đặc tả. + +```rust,noplayground +impl BitBranchStore { + // not recommended: derived branch meaning welded to one bit representation + fn is_ancestor(&self, a: &BitBranch, b: &BitBranch) -> bool { + // derived branch meaning mixed with bit storage + } +} +``` +```` + +Phần mở rộng đảo ngược quyền sở hữu: + +| Lớp | Trách nhiệm | +| --- | --- | +| Năng lực ngữ nghĩa | Sở hữu ý nghĩa suy ra | +| Kiểu cụ thể | Diễn giải ý nghĩa nguyên thủy | + +## Hợp thành với ràng buộc {#compose-with-bounds} + +Khi một bên nhận diễn giải nhiều năng lực, hãy dùng các ràng buộc trực tiếp: + +```rust,noplayground +#[ext(name = PublishCurrentExt)] +pub impl This +where + This: DocumentAlg + PublishAlg, +{ + async fn publish_current(&self) -> Result<(), Error> { + self.publish(self.document_current()).await + } +} +``` + +````admonish warning title="Đừng gom nhóm năng lực" +Đừng tạo đặc trưng cha chỉ để viết ràng buộc ngắn hơn: + +```rust,noplayground +trait AppContext: DocumentAlg + PublishAlg {} +``` + +Nhóm này che giấu phép toán nào sử dụng năng lực nào và tạo thêm một giao diện mà mọi bộ diễn giải phải đáp ứng. +```` + +## Năm ý nghĩa hợp thành khác nhau {#five-different-composition-meanings} + +Hãy chọn dạng mô tả trung thực mối quan hệ. + +| Tình huống | Dạng Rust | +| --- | --- | +| Một bên nhận diễn giải nhiều năng lực | Ràng buộc trực tiếp | +| Một giá trị riêng chọn hành vi | Tham số chính sách tường minh | +| Các chính sách độc lập hợp thành tĩnh | Tích hoặc cấu trúc thông thường | +| Một môi trường mang theo bộ diễn giải khác | Phép chiếu `HasX` nhỏ | +| Một lớp bọc thay thế bộ diễn giải bên trong | Ủy quyền | + +### Chính sách tường minh {#explicit-policy} + +Nếu một chiến lược được lựa chọn độc lập, hãy truyền chiến lược đó một cách tường minh vào phần mở rộng: + +```rust,noplayground +#[ext(name = CandidateSelectExt)] +pub impl This +where + This: CandidateAlg, +{ + fn select_with(&self, policy: &Policy) -> This::Candidate + where + Policy: SelectionPolicyAlg, + { + policy.select(self.candidates()) + } +} +``` + +Phần mở rộng sở hữu phép suy ra dùng chung, còn chính sách vẫn là đầu vào được chọn độc lập. Nó không bị giấu trong môi trường hay được chọn bởi `Default`. + +### Tích các chính sách {#product-of-policies} + +Có thể hợp thành các chính sách độc lập mà không cần tạo ra kế thừa: + +```rust,noplayground +struct CompilePolicy { + optimize: Optimize, + diagnostics: Diagnostics, +} +``` + +### Phép chiếu {#projection} + +Một đặc trưng `HasClock` chỉ cho biết môi trường có thể chiếu ra một giá trị đồng hồ riêng: + +```rust,noplayground +trait HasClock { + type Clock; + + fn clock(&self) -> &Self::Clock; +} +``` + +Phép toán đọc thời gian thêm `This::Clock: ClockAlg` vào mệnh đề `where` của chính nó. Phép chiếu vẫn chỉ nói về việc chứa giá trị; phép toán sử dụng nêu năng lực cần có. Chỉ dùng mẫu này khi sự phân tách là thực sự cần thiết. Đừng thêm `HasX` chỉ để sắp xếp các trường. + +### Ủy quyền {#delegation} + +Ủy quyền nghĩa là bản thân lớp bọc có thể thay thế bộ diễn giải bên trong. Cách này phù hợp với newtype trong suốt, con trỏ dùng chung và bộ chuyển đổi bảo toàn toàn bộ hợp đồng năng lực. + +Phép chiếu nói “có”. Ủy quyền nói “là”. Hai cách này không thể thay thế cho nhau. + +## Giá trị mặc định cũng là quyết định ngữ nghĩa {#defaults-are-semantic-decisions-too} + +Các trạng thái rỗng mang tính cơ học có thể triển khai `Default`. Chính sách miền thường nên được nêu tường minh. + +Các trường hợp hữu ích thường có lời giải thích đại số: giá trị mặc định là phần tử đơn vị đối với phép hợp thành tự nhiên của kiểu. Nối bộ đệm rỗng, kết hợp với bản đồ rỗng hoặc cộng dồn không chẩn đoán nào đều không đóng góp gì. Khi phép hợp thành có tính kết hợp, kiểu và phép toán tạo thành một monoid, và `Default` có thể đặt tên cho phần tử trung hòa thay vì chọn một chính sách. + +Giá trị mặc định tốt: + +* Bộ đệm rỗng +* Bản đồ rỗng +* Không có chẩn đoán nào được tích lũy + +Giá trị mặc định đáng ngờ: + +* Ngưỡng túc số +* Chính sách chọn người lãnh đạo +* Ngữ nghĩa thử lại +* Độ sâu xác nhận +* Định dạng đầu ra + +Đây là điểm phân biệt quan trọng: phần tử trung hòa không đưa ra quyết định nào, còn túc số, chiến lược chọn người lãnh đạo hay quy tắc thử lại sẽ chọn hành vi miền. Nếu thay đổi mặc định làm đổi ý nghĩa miền, hãy hợp thành chính sách một cách tường minh. + +## Giữ ý nghĩa suy ra khép kín {#derived-meaning-should-stay-closed} + +Phần mở rộng chỉ được dùng các năng lực đã khai báo và đầu vào tường minh. Truy cập trực tiếp trường, trạng thái toàn cục và ép kiểu xuống cụ thể khiến mệnh đề `where` không trung thực. + +Hãy xem xét phần thân như thể đó là chứng minh cho khai báo phụ thuộc: + +```admonish question title="Kiểm tra từng phép suy ra" +Có thể biện minh cho mọi phép toán trong phần thân này từ các ràng buộc đó không? +``` + +Nếu không, hoặc ràng buộc chưa đầy đủ, hoặc mã cần thuộc về lớp khác. + +## Các câu hỏi khi duyệt {#review-checks} + +* Hành vi suy ra có được định nghĩa một lần dựa trên các năng lực không? +* Phần mở rộng có tránh dùng trường cụ thể và kiểu ngữ cảnh không? +* Có dùng ràng buộc trực tiếp cho một bộ diễn giải không? +* Chính sách có phải là các giá trị tường minh khi được chọn độc lập không? +* Phép chiếu và ủy quyền có đưa ra khẳng định trung thực không? +* Giá trị mặc định miền có hiển thị trong phép hợp thành không? diff --git a/src/rust-dd/derived-meaning.zh-hant.md b/src/rust-dd/derived-meaning.zh-hant.md new file mode 100644 index 0000000..7090b7d --- /dev/null +++ b/src/rust-dd/derived-meaning.zh-hant.md @@ -0,0 +1,204 @@ + + +# 派生含義與組合 {#derived-meaning-and-composition} + +```admonish tip title="相關內容" +語義視角:[指稱設計](../denotational-design/design.md) +Rust 中的語義驅動設計:[能力代數](capability-algebras.md)、[直譯器與效應](interpreters.md) +概念:[表示式問題](../concepts/expression-problem.md) +``` + +```admonish note title="導讀" +派生行為應歸屬於它所使用的能力,並在擴充中基於這些約束定義一次,供所有直譯器共享;它不應屬於某個碰巧實作這些能力的具體型別。`where`子句誠實地說明了該推導依賴什麼。 +``` + +基本能力提供詞彙。大多數應用行為都應從這些詞彙派生一次,並由所有直譯器共享。 + +## 擴充擁有派生定義 {#extensions-own-derivations} + +使用[`extend`](https://docs.rs/extend/latest/extend/) crate,可以獨立於表示派生分支操作: + +```rust,noplayground +use extend::ext; + +#[ext(name = BranchExt)] +pub impl This +where + This: BranchAlg, +{ + fn branch_child(&self, branch: &This::Branch, direction: Direction) -> This::Branch { + self.branch_grow(branch, direction) + } + + fn branch_left(&self, branch: &This::Branch) -> This::Branch { + self.branch_child(branch, Direction::Left) + } + + fn branch_right(&self, branch: &This::Branch) -> This::Branch { + self.branch_child(branch, Direction::Right) + } + + fn branch_is_ancestor(&self, ancestor: &This::Branch, descendant: &This::Branch) -> bool { + self.branch_path(ancestor, descendant).is_some() + } +} +``` + +`where`子句完整宣告瞭語義依賴:`BranchAlg`,除此之外別無其他。沒有任何具體分支型別擁有這些定義。 + +宏只是省去了 trait 與 impl 的樣板程式碼。普通擴充 trait 也能表達相同設計。指稱設計體現在語義邊界與派生定義中,而不在屬性宏裡。 + +## 為什麼不把它放進結構體? {#why-not-put-it-on-the-struct} + +````admonish warning title="不要把派生含義焊死在結構體上" +這屬於表示優先設計。如果引入數值分支載體,就必須複製或重新實作派生邏輯,首個具體型別也會意外變成規範本身。 + +```rust,noplayground +impl BitBranchStore { + // not recommended: derived branch meaning welded to one bit representation + fn is_ancestor(&self, a: &BitBranch, b: &BitBranch) -> bool { + // derived branch meaning mixed with bit storage + } +} +``` +```` + +擴充反轉了歸屬關係: + +| 層 | 職責 | +| --- | --- | +| 語義能力 | 擁有派生含義 | +| 具體型別 | 解釋基本含義 | + +## 基於約束組合 {#compose-with-bounds} + +當一個接收者解釋多種能力時,使用直接約束: + +```rust,noplayground +#[ext(name = PublishCurrentExt)] +pub impl This +where + This: DocumentAlg + PublishAlg, +{ + async fn publish_current(&self) -> Result<(), Error> { + self.publish(self.document_current()).await + } +} +``` + +````admonish warning title="不要捆綁能力" +不要僅僅為了縮短約束就建立超 trait: + +```rust,noplayground +trait AppContext: DocumentAlg + PublishAlg {} +``` + +能力捆綁會掩蓋哪個操作使用了哪些能力,還會額外建立一種所有直譯器都必須滿足的介面。 +```` + +## 五種不同的組合含義 {#five-different-composition-meanings} + +選擇能夠如實描述這種關係的形式。 + +| 情形 | Rust 結構 | +| --- | --- | +| 一個接收者解釋多種能力 | 直接約束 | +| 由單獨的值選擇行為 | 顯式策略引數 | +| 獨立策略靜態組合 | 乘積型別或普通結構體 | +| 環境承載另一個直譯器 | 小型`HasX`投影 | +| 包裝器替代內部直譯器 | 委託 | + +### 顯式策略 {#explicit-policy} + +如果某種策略獨立選擇,就將它顯式傳入擴充: + +```rust,noplayground +#[ext(name = CandidateSelectExt)] +pub impl This +where + This: CandidateAlg, +{ + fn select_with(&self, policy: &Policy) -> This::Candidate + where + Policy: SelectionPolicyAlg, + { + policy.select(self.candidates()) + } +} +``` + +擴充擁有共享的派生定義,而策略仍是獨立選擇的輸入。它不會隱藏在環境中,也不會由`Default`選擇。 + +### 策略乘積 {#product-of-policies} + +無需發明繼承機制,也能組合獨立策略: + +```rust,noplayground +struct CompilePolicy { + optimize: Optimize, + diagnostics: Diagnostics, +} +``` + +### 投影 {#projection} + +一個`HasClock` trait 僅表明環境可以投影出一個獨立的時鐘值: + +```rust,noplayground +trait HasClock { + type Clock; + + fn clock(&self) -> &Self::Clock; +} +``` + +讀取時間的操作會在自己的`This::Clock: ClockAlg`能力`where`子句中新增該能力。投影只說明包含關係;使用時間的操作則說明自己需要哪種能力。只有在這種分離確實存在時才採用該模式。不要僅僅為了整理欄位就引入`HasX`。 + +### 委託 {#delegation} + +委託意味著包裝器本身可以替代內部直譯器。這適用於透明新型別、共享指標,以及完整保留能力契約的介面卡。 + +投影表示“擁有”。委託表示“就是”。二者不能互換。 + +## 預設值也是語義決策 {#defaults-are-semantic-decisions-too} + +機械的空狀態可以實作`Default`。領域策略通常應當顯式給出。 + +有用的情形往往可以用代數解釋:預設值是該型別自然組合運算的單位元。追加空緩衝區、與空對映合併,或累積零條診斷資訊,都不會帶來額外貢獻。若這種組合滿足結合律,該型別與操作便構成么半群;此時`Default`可以命名其中的中性元,而非替使用者選擇策略。 + +合適的預設值: + +* 空緩衝區 +* 空對映 +* 累積的診斷數量為零 + +值得懷疑的預設值: + +* 法定人數閾值 +* 領導者策略 +* 重試語義 +* 確認深度 +* 輸出格式 + +關鍵區別在於:中性元不會引入決策,而法定人數、領導者策略或重試規則會選擇領域行為。如果更改預設值會改變領域含義,就應顯式組合該策略。 + +## 派生含義應保持封閉 {#derived-meaning-should-stay-closed} + +擴充只能使用已宣告的能力與顯式輸入。直接存取欄位、全域性狀態和具體型別向下轉型都會使`where`子句變得不誠實。 + +審查函式體時,應把它看作對依賴宣告的證明: + +```admonish question title="逐項檢查推導" +函式體中的每個操作,是否都能由這些約束證明合理? +``` + +如果不能,要麼約束不完整,要麼程式碼屬於其他層。 + +## 審查要點 {#review-checks} + +* 派生行為是否只在能力之上定義一次? +* 擴充是否避免依賴具體欄位與上下文型別? +* 單個直譯器是否使用直接約束? +* 獨立選擇的策略是否以顯式值傳入? +* 投影與委託所表達的關係是否準確? +* 領域預設值是否在組合中清晰可見? diff --git a/src/rust-dd/derived-meaning.zh.md b/src/rust-dd/derived-meaning.zh.md new file mode 100644 index 0000000..e2b9525 --- /dev/null +++ b/src/rust-dd/derived-meaning.zh.md @@ -0,0 +1,204 @@ + + +# 派生含义与组合 {#derived-meaning-and-composition} + +```admonish tip title="相关内容" +语义视角:[指称设计](../denotational-design/design.md) +Rust 中的语义驱动设计:[能力代数](capability-algebras.md)、[解释器与效应](interpreters.md) +概念:[表达式问题](../concepts/expression-problem.md) +``` + +```admonish note title="导读" +派生行为应归属于它所使用的能力,并在扩展中基于这些约束定义一次,供所有解释器共享;它不应属于某个碰巧实现这些能力的具体类型。`where`子句诚实地说明了该推导依赖什么。 +``` + +基本能力提供词汇。大多数应用行为都应从这些词汇派生一次,并由所有解释器共享。 + +## 扩展拥有派生定义 {#extensions-own-derivations} + +使用[`extend`](https://docs.rs/extend/latest/extend/) crate,可以独立于表示派生分支操作: + +```rust,noplayground +use extend::ext; + +#[ext(name = BranchExt)] +pub impl This +where + This: BranchAlg, +{ + fn branch_child(&self, branch: &This::Branch, direction: Direction) -> This::Branch { + self.branch_grow(branch, direction) + } + + fn branch_left(&self, branch: &This::Branch) -> This::Branch { + self.branch_child(branch, Direction::Left) + } + + fn branch_right(&self, branch: &This::Branch) -> This::Branch { + self.branch_child(branch, Direction::Right) + } + + fn branch_is_ancestor(&self, ancestor: &This::Branch, descendant: &This::Branch) -> bool { + self.branch_path(ancestor, descendant).is_some() + } +} +``` + +`where`子句完整声明了语义依赖:`BranchAlg`,除此之外别无其他。没有任何具体分支类型拥有这些定义。 + +宏只是省去了 trait 与 impl 的样板代码。普通扩展 trait 也能表达相同设计。指称设计体现在语义边界与派生定义中,而不在属性宏里。 + +## 为什么不把它放进结构体? {#why-not-put-it-on-the-struct} + +````admonish warning title="不要把派生含义焊死在结构体上" +这属于表示优先设计。如果引入数值分支载体,就必须复制或重新实现派生逻辑,首个具体类型也会意外变成规范本身。 + +```rust,noplayground +impl BitBranchStore { + // not recommended: derived branch meaning welded to one bit representation + fn is_ancestor(&self, a: &BitBranch, b: &BitBranch) -> bool { + // derived branch meaning mixed with bit storage + } +} +``` +```` + +扩展反转了归属关系: + +| 层 | 职责 | +| --- | --- | +| 语义能力 | 拥有派生含义 | +| 具体类型 | 解释基本含义 | + +## 基于约束组合 {#compose-with-bounds} + +当一个接收者解释多种能力时,使用直接约束: + +```rust,noplayground +#[ext(name = PublishCurrentExt)] +pub impl This +where + This: DocumentAlg + PublishAlg, +{ + async fn publish_current(&self) -> Result<(), Error> { + self.publish(self.document_current()).await + } +} +``` + +````admonish warning title="不要捆绑能力" +不要仅仅为了缩短约束就创建超 trait: + +```rust,noplayground +trait AppContext: DocumentAlg + PublishAlg {} +``` + +能力捆绑会掩盖哪个操作使用了哪些能力,还会额外创建一种所有解释器都必须满足的接口。 +```` + +## 五种不同的组合含义 {#five-different-composition-meanings} + +选择能够如实描述这种关系的形式。 + +| 情形 | Rust 结构 | +| --- | --- | +| 一个接收者解释多种能力 | 直接约束 | +| 由单独的值选择行为 | 显式策略参数 | +| 独立策略静态组合 | 乘积类型或普通结构体 | +| 环境承载另一个解释器 | 小型`HasX`投影 | +| 包装器替代内部解释器 | 委托 | + +### 显式策略 {#explicit-policy} + +如果某种策略独立选择,就将它显式传入扩展: + +```rust,noplayground +#[ext(name = CandidateSelectExt)] +pub impl This +where + This: CandidateAlg, +{ + fn select_with(&self, policy: &Policy) -> This::Candidate + where + Policy: SelectionPolicyAlg, + { + policy.select(self.candidates()) + } +} +``` + +扩展拥有共享的派生定义,而策略仍是独立选择的输入。它不会隐藏在环境中,也不会由`Default`选择。 + +### 策略乘积 {#product-of-policies} + +无需发明继承机制,也能组合独立策略: + +```rust,noplayground +struct CompilePolicy { + optimize: Optimize, + diagnostics: Diagnostics, +} +``` + +### 投影 {#projection} + +一个`HasClock` trait 仅表明环境可以投影出一个独立的时钟值: + +```rust,noplayground +trait HasClock { + type Clock; + + fn clock(&self) -> &Self::Clock; +} +``` + +读取时间的操作会在自己的`This::Clock: ClockAlg`能力`where`子句中添加该能力。投影只说明包含关系;使用时间的操作则说明自己需要哪种能力。只有在这种分离确实存在时才采用该模式。不要仅仅为了整理字段就引入`HasX`。 + +### 委托 {#delegation} + +委托意味着包装器本身可以替代内部解释器。这适用于透明新类型、共享指针,以及完整保留能力契约的适配器。 + +投影表示“拥有”。委托表示“就是”。二者不能互换。 + +## 默认值也是语义决策 {#defaults-are-semantic-decisions-too} + +机械的空状态可以实现`Default`。领域策略通常应当显式给出。 + +有用的情形往往可以用代数解释:默认值是该类型自然组合运算的单位元。追加空缓冲区、与空映射合并,或累积零条诊断信息,都不会带来额外贡献。若这种组合满足结合律,该类型与操作便构成幺半群;此时`Default`可以命名其中的中性元,而非替使用者选择策略。 + +合适的默认值: + +* 空缓冲区 +* 空映射 +* 累积的诊断数量为零 + +值得怀疑的默认值: + +* 法定人数阈值 +* 领导者策略 +* 重试语义 +* 确认深度 +* 输出格式 + +关键区别在于:中性元不会引入决策,而法定人数、领导者策略或重试规则会选择领域行为。如果更改默认值会改变领域含义,就应显式组合该策略。 + +## 派生含义应保持封闭 {#derived-meaning-should-stay-closed} + +扩展只能使用已声明的能力与显式输入。直接访问字段、全局状态和具体类型向下转型都会使`where`子句变得不诚实。 + +审查函数体时,应把它看作对依赖声明的证明: + +```admonish question title="逐项检查推导" +函数体中的每个操作,是否都能由这些约束证明合理? +``` + +如果不能,要么约束不完整,要么代码属于其他层。 + +## 审查要点 {#review-checks} + +* 派生行为是否只在能力之上定义一次? +* 扩展是否避免依赖具体字段与上下文类型? +* 单个解释器是否使用直接约束? +* 独立选择的策略是否以显式值传入? +* 投影与委托所表达的关系是否准确? +* 领域默认值是否在组合中清晰可见? diff --git a/src/rust-dd/first-order-programs.ar.md b/src/rust-dd/first-order-programs.ar.md new file mode 100644 index 0000000..46cb3a4 --- /dev/null +++ b/src/rust-dd/first-order-programs.ar.md @@ -0,0 +1,210 @@ + + +# برامج من الرتبة الأولى {#first-order-programs} + +```admonish tip title="ذات صلة" +التصميم انطلاقًا من المعنى في Rust: [المعنى المشتق والتركيب](derived-meaning.md)، [اللغة ومسارات المترجم](compiler-pipelines.md) +المفاهيم: [أسلوب تمرير الاستمرار](../concepts/cps.md)، [إزالة الدوال](../concepts/defunctionalization.md)، [الموناد الحر](../concepts/free_monad.md) +الرؤى: [إعادة النظر في Expression Problem](../insights/expression-problem.md) +``` + +```admonish note title="متى ينبغي تجسيد تطبيق الدالة؟" +تعبّر الدوال العادية والامتدادات عن السلوك المشتق بالفعل. حوّل تطبيق الدالة إلى بيانات من الرتبة الأولى فقط عندما يحتاج مفسر آخر إلى فحص البرنامج أو تركيبه أو تسلسله أو ترجمته قبل تشغيله. +``` + +تكون الدوال العادية وأساليب الامتداد عادةً أفضل طريقة للتعبير عن السلوك المشتق. وقد يحتاج مفسر آخر أحيانًا إلى فحص بنية برنامج أو دمجها أو توثيقها أو تسلسلها أو ترجمتها قبل تطبيقه. عندئذٍ يجب أن يصبح تطبيق الدالة نفسه بيانات من الرتبة الأولى. + +## يمحو التنفيذ البنية {#execution-erases-structure} + +تأمل: + +```rust,noplayground +#[ext(name = StatusExt)] +pub impl This +where + This: StatusAlg, +{ + async fn status_current(&self) -> This::Status { + self.status().await + } +} +``` + +يعيد استدعاء هذا الأسلوب حالةً. وبعد بدء الاستدعاء، لا يستطيع مفسر خارجي عمومًا استرداد: + +* نوع السياق الدلالي +* المعاملات المرتبة +* أسماء المعاملات في المصدر +* نوع النتيجة +* هوية العملية + +كانت تلك المعلومات موجودة في نوع الدالة على مستوى المصدر، لكن التنفيذ العادي يستهلكها. + +## إزالة دوالية تطبيق الدالة {#defunctionalizing-application} + +تستبدل إزالة الدوال عضوًا من عائلة معلومة من الدوال بوسم من الرتبة الأولى وعملية مشتركة لتطبيق الدوال. + +مفردات العمليات الدنيا هي: + +```rust,noplayground +trait OperationAlg { + type Context; + type Args; + + const ARG_NAMES: &'static [&'static str]; +} + +trait ApplyAlg { + type Output; + + async fn apply(&self, handle: Handle, args: Args) -> Self::Output; +} +``` + +يمكن لـ `CurrentStatusOperation` عديم الحجم أن يدل على تطبيق أسلوب الامتداد الأصلي. وينبغي له استدعاء ذلك الأسلوب، لا احتواء نسخة ثانية من جسمه. + +1. ابدأ بأسلوب الامتداد. +2. أعد تجسيده كنوع عملية. +3. حافظ على سياقه وحاصل ضرب معاملاته وأسمائها ومخرجاته. +4. فسّره عبر `ApplyAlg`. + +يظل الأسلوب مريحًا للاستدعاءات العادية. وتوجد قيمة العملية للسياقات التي تتطلب بنية من الرتبة الأولى. + +## لا تُعد التجسيد من دون مستهلك {#do-not-reify-without-a-consumer} + +تضيف البرامج من الرتبة الأولى آليات للأنواع. استخدمها عندما تتيح تفسيرًا ثانيًا حقيقيًا: + +* التسجيل في بيئة التشغيل +* إنشاء التوثيق أو المخططات +* الفحص الساكن +* تركيب البرامج قبل التنفيذ +* التسلسل +* الترجمة + +إذا كانت الشيفرة لا تحتاج إلا إلى استدعاء دالة، فأبقِها دالة. + +## برامج واجهات محمولة {#portable-interface-programs} + +لنفترض أن سطح HTTP يحتوي على: + +| الأسلوب | المسار | الإدخال | العملية | الإخراج | +| --- | --- | --- | --- | --- | +| `GET` | `/status` | — | `status_current` | JSON | +| `POST` | `/set_temperature` | المتن: `f32` | `adjust_status` | JSON | +| `GET` | `/download` | — | `current_file` | ملف متدفق | + +يجب على البرنامج المحمول الحفاظ على: + +* محددات الأسلوب والمسار +* أدوار الإدخال مثل المسار والاستعلام والمتن والترويسة والمصادقة +* قيمة العملية +* دور الإخراج مثل JSON أو الملف +* دمج المسارات وتعشيشها + +وينبغي ألا يحافظ على نوع طلب أو موجّه أو استجابة خاص بإطار بعينه. + +قد يكون أحد التدوينات المتسلسلة: + +```rust,noplayground +self.routes() + .get("/status", self.op(CurrentStatusOperation::::default()).json()) + .post("/set_temperature", self.op(AdjustStatusOperation::::default()).body::().json()) + .get("/download", self.op(CurrentFileOperation::::default()).file()) +``` + +تبني الاستدعاءات المتسلسلة برنامجًا مكتوب الأنواع. وليس عليها تسجيل مسار خادم فورًا. + +## برنامج واحد، وعمليات طي متعددة {#one-program-several-folds} + +يمكن للبرنامج نفسه من الرتبة الأولى دعم عدة تفسيرات: + +| البرنامج | التفسيرات | +| --- | --- | +| برنامج HTTP ذي أنواع محددة | توثيق نصي، ومسارات قابلة للتنفيذ، وبيانات OpenAPI الوصفية، وروابط العميل، واختبارات المطابقة | +| برنامج JSON-RPC ذي أنواع محددة | سجل الأساليب، والمخطط، والعميل، وإطار الاختبار | + +لا تحتفظ بقوائم منفصلة للمسارات أو الأساليب من أجل التنفيذ والتوثيق. فهذا ينشئ مواصفات متنافسة. + +## أدوار الإدخال والإخراج {#input-and-output-roles} + +تعرف العملية مسبقًا نوعي وسيطها ونتيجتها. وينبغي لتعريف النقل أن يضيف دلالة النقل فقط. + +```rust,noplayground +self.op(FindOperation::::default()) + .path::() + .query::() + .json() +``` + +تحدد `path` و`query` و`json` الأدوار. ولا ينبغي أن تجبر المؤلف على إعادة ذكر نوع المخرجات الذي تحدده `ApplyAlg` أصلًا. + +ينتمي تحويل المخرجات إلى مفسر النقل. يمكن للخادم تحويل نتيجة إلى JSON وأخرى إلى مرفق متدفق. وتظل العمليات الدلالية غير معنية بأي من التمثيلين. + +## التركيب هو معنى البرنامج {#composition-is-program-meaning} + +ينبغي للبرامج أن تحافظ على إمكان التركيب العام: + +* برنامج فارغ +* دمج البرامج +* تضمين برنامج تحت بادئة +* رفع نقطة نهاية إلى برنامج + +هذه أعمق من أساليب الموجّه الخاصة بإطار عمل واحد. ويمكن للأسماء المألوفة المتسلسلة مثل `get` و`post` و`merge` و`nest` أن تكون أسماء بديلة فوق الجبر المحايد. + +يمكن للمواصفات المستقلة نشر برامج صغيرة: + +| برامج الإدخال | التركيب | النتيجة | +| --- | --- | --- | +| برامج الحالة والتنزيل | دمج | برنامج الخدمة | +| برنامج الفهرس | تضمين | برنامج الخدمة | + +يختار التطبيق التركيب الناتج ويفسره. + +## يجب أن تخفض الماكرو إلى معنى عام معلن {#macros-must-lower-to-public-meaning} + +يمكن لماكرو Rust أن تجعل التعريفات من الرتبة الأولى سهلة الاستخدام: + +```rust,noplayground +#[ext(name = StatusApiExt, defunc(via = http))] +pub impl This +where + This: HttpApiAlg + JsonOutAlg, +{ + fn status_api(&self) + where + Alg: StatusAlg, + { + self.routes().get("/status", self.op(Alg::status_current).json()); + } +} +``` + +تكون الماكرو سليمة فقط عندما تخفض إلى برنامج من الرتبة الأولى معلن وقابل للإنشاء يدويًا. ويجب ألا تصبح الاستدعاءات الراجعة المولدة التعريف الوحيد للواجهة. + +اتجاه سليم: + +1. صياغة ملائمة +2. قيم العمليات والبرامج العامة +3. طي عام +4. إطار عمل ملموس + +اتجاه يبدأ بالتمثيل: + +1. تعليق إطار العمل +2. استدعاءات راجعة مولدة معتمة +3. توثيق مستنتج عكسيًا + +## علاقته بالمفاهيم القائمة {#relation-to-existing-concepts} + +تستند برامج الواجهات من الرتبة الأولى إلى تقنيات تناولتها فصول أخرى: إزالة الدوال هي التحويل العام، والصياغة القابلة للتوسيع والتفسيرات هما مسألة التعبير، والموناد الحر تمثيل واحد لصياغة مع تسلسل. تقود الروابط ذات الصلة في أعلى الصفحة إلى كل منها. + +لا تساوِ بين هذه التقنيات وبين التصميم الدلالي نفسه. يحدد التصميم الدلالي البنية المهمة؛ وتحافظ التمثيلات من الرتبة الأولى على تلك البنية حين تمحوها الاستدعاءات العادية. + +## فحوص المراجعة {#review-checks} + +* هل تتطلب حالة استخدام فعلية مفسرًا ثانيًا إعادة التمثيل؟ +* هل تستدعي العملية الأسلوب الذي ألّفه المستخدم بدلًا من تكراره؟ +* هل تُستنتج الوسائط والمخرجات من العملية؟ +* هل تضيف صياغة النقل أدوار النقل وحدها؟ +* هل يمكن إنشاء البرنامج من دون ماكرو التسهيل؟ +* هل يفسر وقت التشغيل والبيانات الوصفية البرنامج نفسه؟ diff --git a/src/rust-dd/first-order-programs.de.md b/src/rust-dd/first-order-programs.de.md new file mode 100644 index 0000000..3f2f9b9 --- /dev/null +++ b/src/rust-dd/first-order-programs.de.md @@ -0,0 +1,210 @@ + + +# Programme erster Ordnung {#first-order-programs} + +```admonish tip title="Verwandte Themen" +Design by Meaning in Rust: [Abgeleitete Bedeutung und Komposition](derived-meaning.md), [Sprach- und Compiler-Pipelines](compiler-pipelines.md) +Concepts: [Continuation-Passing Style](../concepts/cps.md), [Defunktionalisierung](../concepts/defunctionalization.md), [Freie Monade](../concepts/free_monad.md) +Insights: [Expression Problem reloaded](../insights/expression-problem.md) +``` + +```admonish note title="Wann Anwendung reifizieren?" +Gewöhnliche Funktionen und Erweiterungen drücken abgeleitetes Verhalten bereits aus. Wandle eine Anwendung nur dann in Daten erster Ordnung um, wenn ein anderer Interpreter ein Programm vor der Ausführung untersuchen, zusammensetzen, serialisieren oder kompilieren muss. +``` + +Gewöhnliche Funktionen und Erweiterungsmethoden sind normalerweise die beste Art, abgeleitetes Verhalten auszudrücken. Manchmal muss ein anderer Interpreter die Struktur eines Programms vor seiner Anwendung untersuchen, kombinieren, dokumentieren, serialisieren oder kompilieren. Dann muss die Anwendung selbst zu Daten erster Ordnung werden. + +## Ausführung löscht Struktur {#execution-erases-structure} + +Betrachte Folgendes: + +```rust,noplayground +#[ext(name = StatusExt)] +pub impl This +where + This: StatusAlg, +{ + async fn status_current(&self) -> This::Status { + self.status().await + } +} +``` + +Der Aufruf dieser Methode liefert einen Status. Sobald der Aufruf beginnt, kann ein externer Interpreter im Allgemeinen Folgendes nicht mehr ermitteln: + +* den Typ des semantischen Kontexts +* die Reihenfolge der Argumente +* die Namen der Quellargumente +* den Ergebnistyp +* die Identität der Operation + +Diese Informationen waren im Funktionstyp auf Quelltextebene vorhanden, werden bei der gewöhnlichen Ausführung jedoch verbraucht. + +## Anwendung defunktionalisieren {#defunctionalizing-application} + +Defunktionalisierung ersetzt ein Element aus einer bekannten Familie von Funktionen durch ein Tag erster Ordnung und eine gemeinsame Anwendungsoperation. + +Ein minimales Operationsvokabular lautet: + +```rust,noplayground +trait OperationAlg { + type Context; + type Args; + + const ARG_NAMES: &'static [&'static str]; +} + +trait ApplyAlg { + type Output; + + async fn apply(&self, handle: Handle, args: Args) -> Self::Output; +} +``` + +Ein größenloses `CurrentStatusOperation` kann die Anwendung der ursprünglichen Erweiterungsmethode bezeichnen. Es sollte diese Methode aufrufen, statt ihren Rumpf zu duplizieren. + +1. Mit der Erweiterungsmethode beginnen. +2. Sie als Operationstyp reifizieren. +3. Kontext, Argumentprodukt, Argumentnamen und Ausgabe bewahren. +4. Sie über `ApplyAlg` interpretieren. + +Für normale Aufrufe bleibt die Methode ergonomisch. Der Operationswert existiert für Kontexte, die eine Struktur erster Ordnung benötigen. + +## Nur für konkrete Nutzer reifizieren {#do-not-reify-without-a-consumer} + +Programme erster Ordnung bringen zusätzlichen Typmechanismus mit sich. Verwende sie nur, wenn sie eine echte zweite Interpretation ermöglichen: + +* Registrierung zur Laufzeit +* Generierung von Dokumentation oder Schemata +* statische Inspektion +* Komposition des Programms vor der Ausführung +* Serialisierung +* Kompilierung + +Muss der Code nur eine Funktion aufrufen, lass sie eine Funktion bleiben. + +## Portable Schnittstellenprogramme {#portable-interface-programs} + +Angenommen, eine HTTP-Oberfläche enthält: + +| Methode | Pfad | Eingabe | Operation | Ausgabe | +| --- | --- | --- | --- | --- | +| `GET` | `/status` | — | `status_current` | JSON | +| `POST` | `/set_temperature` | Textkörper: `f32` | `adjust_status` | JSON | +| `GET` | `/download` | — | `current_file` | Gestreamte Datei | + +Ein portables Programm muss Folgendes bewahren: + +* Auswahl von Methode und Pfad +* Eingaberollen wie Pfad, Abfrage, Textkörper, Header und Authentifizierung +* den Operationswert +* eine Ausgaberolle wie JSON oder Datei +* Zusammenführen und Verschachteln von Routen + +Es sollte keinen bestimmten Framework-Anfrage-, Router- oder Antworttyp bewahren. + +Eine flüssige Notation könnte so aussehen: + +```rust,noplayground +self.routes() + .get("/status", self.op(CurrentStatusOperation::::default()).json()) + .post("/set_temperature", self.op(AdjustStatusOperation::::default()).body::().json()) + .get("/download", self.op(CurrentFileOperation::::default()).file()) +``` + +Die flüssigen Aufrufe konstruieren ein typisiertes Programm. Sie müssen nicht sofort eine Serverroute registrieren. + +## Ein Programm, mehrere Faltungen {#one-program-several-folds} + +Dasselbe Programm erster Ordnung kann mehrere Interpretationen unterstützen: + +| Programm | Interpretationen | +| --- | --- | +| Typisiertes HTTP-Programm | Textdokumentation, ausführbare Routen, OpenAPI-Metadaten, Client-Bindings, Konformitätstests | +| Typisiertes JSON-RPC-Programm | Methodenregister, Schema, Client, Test-Harness | + +Pflege getrennte Routen- oder Methodenlisten für Ausführung und Dokumentation nicht parallel. Dadurch entstehen konkurrierende Spezifikationen. + +## Eingabe- und Ausgaberollen {#input-and-output-roles} + +Die Operation kennt ihre Argument- und Ergebnistypen bereits. Eine Transportdeklaration sollte lediglich Transportbedeutung hinzufügen. + +```rust,noplayground +self.op(FindOperation::::default()) + .path::() + .query::() + .json() +``` + +`path`, `query` und `json` kennzeichnen Rollen. Sie sollten den Autor nicht dazu zwingen, einen bereits von `ApplyAlg` bestimmten Ausgabetyp erneut anzugeben. + +Die Ausgabekonvertierung gehört zum Transport-Interpreter. Ein Server kann ein Ergebnis in JSON und ein anderes als gestreamten Anhang ausgeben. Die semantischen Operationen kennen keine der beiden Repräsentationen. + +## Komposition ist Programmbedeutung {#composition-is-program-meaning} + +Programme sollten allgemeine Komposition bewahren: + +* Leeres Programm +* Programme zusammenführen +* Ein Programm unter einem Präfix verschachteln +* Einen Endpunkt in ein Programm überführen + +Diese Operationen sind grundlegender als die Router-Methoden eines einzelnen Frameworks. Vertraute Fluent-Namen wie `get`, `post`, `merge` und `nest` können Aliase für die neutrale Algebra sein. + +Unabhängige Spezifikationen können kleine Programme bereitstellen: + +| Eingabeprogramme | Komposition | Ergebnis | +| --- | --- | --- | +| Status- und Downloadprogramme | Zusammenführen | Dienstprogramm | +| Katalogprogramm | Verschachteln | Dienstprogramm | + +Eine Anwendung wählt die resultierende Komposition aus und interpretiert sie. + +## Makros müssen auf öffentliche Bedeutung abbilden {#macros-must-lower-to-public-meaning} + +Rust-Makros können Deklarationen erster Ordnung angenehm lesbar machen: + +```rust,noplayground +#[ext(name = StatusApiExt, defunc(via = http))] +pub impl This +where + This: HttpApiAlg + JsonOutAlg, +{ + fn status_api(&self) + where + Alg: StatusAlg, + { + self.routes().get("/status", self.op(Alg::status_current).json()); + } +} +``` + +Ein Makro ist nur dann sinnvoll, wenn es auf ein öffentliches, von Hand konstruierbares Programm erster Ordnung abbildet. Generierte Callbacks dürfen nicht zur alleinigen Definition der Schnittstelle werden. + +Gute Richtung: + +1. Bequeme Syntax +2. Öffentliche Operations- und Programmwerte +3. Generische Faltung +4. Konkretes Framework + +Repräsentationsorientierte Richtung: + +1. Framework-Annotation +2. Undurchsichtige generierte Callbacks +3. Nachträglich rekonstruierte Dokumentation + +## Beziehung zu bestehenden Konzepten {#relation-to-existing-concepts} + +Programme erster Ordnung für Schnittstellen bauen auf Techniken anderer Kapitel auf: Defunktionalisierung ist die allgemeine Transformation, erweiterbare Syntax und Interpretationen behandeln das Expression Problem, und eine freie Monade ist eine spezielle Repräsentation aus Syntax und Sequenzierung. Die Links unter „Verwandte Themen“ oben auf der Seite führen zu den jeweiligen Kapiteln. + +Setze diese Techniken nicht mit DD selbst gleich. DD bestimmt, welche Struktur wichtig ist; Repräsentationen erster Ordnung bewahren diese Struktur, wenn gewöhnliche Aufrufe sie auslöschen würden. + +## Prüfpunkte für das Review {#review-checks} + +* Ist die Reifizierung durch einen echten zweiten Interpreter erforderlich? +* Ruft die Operation die verfasste Methode auf, statt sie zu duplizieren? +* Werden Argumente und Ausgabe aus der Operation abgeleitet? +* Fügt die Transportsyntax nur Transportrollen hinzu? +* Lässt sich das Programm ohne sein Komfortmakro konstruieren? +* Interpretieren Laufzeit und Metadaten dasselbe Programm? diff --git a/src/rust-dd/first-order-programs.es.md b/src/rust-dd/first-order-programs.es.md new file mode 100644 index 0000000..b114995 --- /dev/null +++ b/src/rust-dd/first-order-programs.es.md @@ -0,0 +1,210 @@ + + +# Programas de primer orden {#first-order-programs} + +```admonish tip title="Relacionado" +Diseño por significado en Rust: [Significado derivado y composición](derived-meaning.md), [Canalizaciones de lenguaje y compilador](compiler-pipelines.md) +Conceptos: [Estilo de paso de continuaciones](../concepts/cps.md), [Defuncionalización](../concepts/defunctionalization.md), [Mónada libre](../concepts/free_monad.md) +Perspectivas: [El problema de las expresiones, revisitado](../insights/expression-problem.md) +``` + +```admonish note title="Cuándo reificar la aplicación de funciones" +Las funciones ordinarias y las extensiones ya expresan el comportamiento derivado. Convierte la aplicación de una función en datos de primer orden solo cuando otro intérprete deba inspeccionar, componer, serializar o compilar un programa antes de ejecutarlo. +``` + +Las funciones ordinarias y los métodos de extensión suelen ser la mejor manera de expresar el comportamiento derivado. A veces otro intérprete debe inspeccionar, combinar, documentar, serializar o compilar la estructura de un programa antes de aplicarlo. En ese caso, la propia aplicación de funciones debe convertirse en datos de primer orden. + +## La ejecución borra la estructura {#execution-erases-structure} + +Considera: + +```rust,noplayground +#[ext(name = StatusExt)] +pub impl This +where + This: StatusAlg, +{ + async fn status_current(&self) -> This::Status { + self.status().await + } +} +``` + +Llamar a este método produce un estado. Una vez iniciada la llamada, un intérprete externo normalmente no puede recuperar: + +* el tipo de contexto semántico +* los argumentos ordenados +* los nombres de los argumentos de origen +* el tipo de resultado +* la identidad de la operación + +Esa información estaba presente en el tipo de función en el código fuente, pero la ejecución ordinaria la consume. + +## Defuncionalización de la aplicación de funciones {#defunctionalizing-application} + +La defuncionalización reemplaza un miembro de una familia conocida de funciones por una etiqueta de primer orden y una operación de aplicación compartida. + +Un vocabulario mínimo de operaciones es: + +```rust,noplayground +trait OperationAlg { + type Context; + type Args; + + const ARG_NAMES: &'static [&'static str]; +} + +trait ApplyAlg { + type Output; + + async fn apply(&self, handle: Handle, args: Args) -> Self::Output; +} +``` + +Un `CurrentStatusOperation` de tamaño cero puede denotar la aplicación del método de extensión original. Debe invocar ese método, no contener una segunda copia de su cuerpo. + +1. Empieza con el método de extensión. +2. Reifícalo como un tipo de operación. +3. Preserva su contexto, producto de argumentos, nombres de argumentos y salida. +4. Interprétalo mediante `ApplyAlg`. + +El método sigue siendo cómodo para llamadas normales. El valor de operación existe para contextos que requieren una estructura de primer orden. + +## No reifiques sin un consumidor {#do-not-reify-without-a-consumer} + +Los programas de primer orden añaden mecanismos de tipos. Úsalos cuando permitan una segunda interpretación real: + +* registro en tiempo de ejecución +* generación de documentación o esquemas +* inspección estática +* composición de programas antes de la ejecución +* serialización +* compilación + +Si el código solo necesita llamar a una función, conserva la función. + +## Programas de interfaz portables {#portable-interface-programs} + +Supongamos que una superficie HTTP contiene: + +| Método | Ruta | Entrada | Operación | Salida | +| --- | --- | --- | --- | --- | +| `GET` | `/status` | — | `status_current` | JSON | +| `POST` | `/set_temperature` | Cuerpo: `f32` | `adjust_status` | JSON | +| `GET` | `/download` | — | `current_file` | Archivo transmitido en flujo | + +Un programa portable debe preservar: + +* selectores de método y ruta +* roles de entrada como ruta, consulta, cuerpo, encabezado y autenticación +* el valor de la operación +* rol de salida como JSON o archivo +* combinación y anidamiento de rutas + +No debería preservar un tipo de solicitud, enrutador o respuesta de un framework específico. + +Una notación fluida podría ser: + +```rust,noplayground +self.routes() + .get("/status", self.op(CurrentStatusOperation::::default()).json()) + .post("/set_temperature", self.op(AdjustStatusOperation::::default()).body::().json()) + .get("/download", self.op(CurrentFileOperation::::default()).file()) +``` + +Las llamadas fluidas construyen un programa tipado. No tienen que registrar inmediatamente una ruta del servidor. + +## Un programa, varios pliegues {#one-program-several-folds} + +El mismo programa de primer orden puede admitir varias interpretaciones: + +| Programa | Interpretaciones | +| --- | --- | +| Programa HTTP tipado | Documentación textual, rutas ejecutables, metadatos de OpenAPI, enlaces de cliente y tests de conformidad | +| Programa JSON-RPC tipado | Registro de métodos, esquema, cliente y banco de pruebas | + +No mantengas listas separadas de rutas o métodos para la ejecución y la documentación. Eso crea especificaciones rivales. + +## Roles de entrada y salida {#input-and-output-roles} + +La operación ya conoce los tipos de sus argumentos y resultados. Una declaración de transporte solo debería añadir significado de transporte. + +```rust,noplayground +self.op(FindOperation::::default()) + .path::() + .query::() + .json() +``` + +`path`, `query` y `json` identifican roles. No deberían obligar al autor a volver a declarar un tipo de salida que `ApplyAlg` ya determina. + +La conversión de salida corresponde al intérprete de transporte. Un servidor puede convertir un resultado a JSON y otro a un adjunto transmitido en flujo. Las operaciones semánticas no necesitan conocer ninguna de esas representaciones. + +## La composición es significado de programa {#composition-is-program-meaning} + +Los programas deben preservar la composición general: + +* Programa vacío +* Combinar programas +* Anidar un programa bajo un prefijo +* Elevar un endpoint a programa + +Estas operaciones son más fundamentales que los métodos de enrutador de un framework. Nombres fluidos conocidos como `get`, `post`, `merge` y `nest` pueden ser alias del álgebra neutral. + +Las especificaciones independientes pueden publicar programas pequeños: + +| Programas de entrada | Composición | Resultado | +| --- | --- | --- | +| Programas de estado y descarga | Combinar | Programa de servicio | +| Programa de catálogo | Anidar | Programa de servicio | + +Una aplicación elige e interpreta la composición resultante. + +## Los macros deben rebajarse a significado público {#macros-must-lower-to-public-meaning} + +Los macros de Rust pueden hacer más cómodas las declaraciones de primer orden: + +```rust,noplayground +#[ext(name = StatusApiExt, defunc(via = http))] +pub impl This +where + This: HttpApiAlg + JsonOutAlg, +{ + fn status_api(&self) + where + Alg: StatusAlg, + { + self.routes().get("/status", self.op(Alg::status_current).json()); + } +} +``` + +El macro solo es saludable cuando se traduce a un programa público de primer orden que pueda construirse manualmente. Los callbacks generados no deben convertirse en la única definición de la interfaz. + +Dirección acertada: + +1. Sintaxis conveniente +2. Valores públicos de operación y programa +3. Pliegue genérico +4. Framework concreto + +Dirección centrada en la representación: + +1. Anotación del framework +2. Callbacks generados opacos +3. Documentación reconstruida mediante ingeniería inversa + +## Relación con conceptos existentes {#relation-to-existing-concepts} + +Los programas de interfaz de primer orden se basan en técnicas de otros capítulos: la defuncionalización es la transformación general, la sintaxis extensible y las interpretaciones conforman el problema de las expresiones, y una mónada libre es una representación concreta de sintaxis con secuenciación. Los enlaces relacionados al inicio de la página llevan a cada tema. + +No identifiques estas técnicas con DD. DD determina qué estructura importa; las representaciones de primer orden preservan esa estructura cuando las llamadas ordinarias podrían borrarla. + +## Comprobaciones de revisión {#review-checks} + +* ¿Una segunda interpretación real requiere reificación? +* ¿La operación invoca el método escrito por el autor en vez de duplicarlo? +* ¿Los argumentos y la salida se infieren a partir de la operación? +* ¿La sintaxis de transporte añade solo roles de transporte? +* ¿Se puede construir el programa sin su macro de conveniencia? +* ¿El entorno de ejecución y los metadatos interpretan el mismo programa? diff --git a/src/rust-dd/first-order-programs.ja.md b/src/rust-dd/first-order-programs.ja.md new file mode 100644 index 0000000..dc6f866 --- /dev/null +++ b/src/rust-dd/first-order-programs.ja.md @@ -0,0 +1,210 @@ + + +# 一階プログラム {#first-order-programs} + +```admonish tip title="関連項目" +Rustで意味から設計する:[導出される意味と合成](derived-meaning.md)、[言語とコンパイラーパイプライン](compiler-pipelines.md) +概念:[継続渡し形式](../concepts/cps.md)、[関数のデファンクショナライズ](../concepts/defunctionalization.md)、[自由モナド](../concepts/free_monad.md) +洞察:[Expression Problem再考](../insights/expression-problem.md) +``` + +```admonish note title="アプリケーションを再構化するとき" +通常の関数と拡張ですでに導出された振る舞いを表現できます。実行前に別のインタープリターがプログラムを検査、合成、シリアライズ、コンパイルする必要がある場合に限り、アプリケーションを一階データに変換します。 +``` + +通常の関数と拡張メソッドは、導出された振る舞いを表現するのに最適な方法です。プログラムを適用する前に、別のインタープリターがその構造を検査、結合、文書化、シリアライズ、コンパイルしなければならない場合もあります。そのときはアプリケーション自体を一階データにする必要があります。 + +## 実行すると構造が消える {#execution-erases-structure} + +次を考えてください。 + +```rust,noplayground +#[ext(name = StatusExt)] +pub impl This +where + This: StatusAlg, +{ + async fn status_current(&self) -> This::Status { + self.status().await + } +} +``` + +このメソッドを呼び出すと状態が返ります。呼び出しが始まると、外部のインタープリターは一般に次の情報を復元できません。 + +* 意味論的なコンテキスト型 +* 順序付きの引数 +* ソース上の引数名 +* 結果の型 +* 操作の識別情報 + +その情報はソースレベルの関数型に含まれていましたが、通常の実行によって消費されます。 + +## アプリケーションをデファンクショナライズする {#defunctionalizing-application} + +デファンクショナライズでは、既知の関数族の要素を一階のタグと共有の適用操作に置き換えます。 + +最小限の操作語彙は次のとおりです。 + +```rust,noplayground +trait OperationAlg { + type Context; + type Args; + + const ARG_NAMES: &'static [&'static str]; +} + +trait ApplyAlg { + type Output; + + async fn apply(&self, handle: Handle, args: Args) -> Self::Output; +} +``` + +サイズゼロの`CurrentStatusOperation`は、元の拡張メソッドの適用を表せます。メソッド本体を二重に持つのではなく、そのメソッドを呼び出すべきです。 + +1. 拡張メソッドから始める。 +2. それを操作型として再構化する。 +3. コンテキスト、引数の積、引数名、出力を保持する。 +4. `ApplyAlg`を通じて解釈する。 + +通常の呼び出しでは、引き続き使いやすいメソッドを使えます。一階の構造を必要とする場面では、操作値を使います。 + +## 利用側がないなら再構化しない {#do-not-reify-without-a-consumer} + +一階プログラムを使うと型の仕組みが増えます。次のように、実際に二つ目の解釈が可能になる場合に使います。 + +* ランタイム登録 +* ドキュメントまたはスキーマ生成 +* 静的検査 +* 実行前のプログラム合成 +* シリアライズ +* コンパイル + +コードが関数を呼び出すだけなら、その関数のままにします。 + +## 移植可能なインターフェースプログラム {#portable-interface-programs} + +HTTPの表面に次が含まれるとします。 + +| メソッド | パス | 入力 | 操作 | 出力 | +| --- | --- | --- | --- | --- | +| `GET` | `/status` | — | `status_current` | JSON | +| `POST` | `/set_temperature` | 本文:`f32` | `adjust_status` | JSON | +| `GET` | `/download` | — | `current_file` | ストリーミングファイル | + +移植可能なプログラムは次を保持しなければなりません。 + +* メソッドとパスの選択子 +* パス、クエリ、本文、ヘッダー、認証などの入力の役割 +* 操作値 +* JSONやファイルなどの出力の役割 +* ルートの結合とネスト + +特定のフレームワークのリクエスト、ルーター、レスポンス型は保持しないでください。 + +たとえば、次のような流れる記法を使えます。 + +```rust,noplayground +self.routes() + .get("/status", self.op(CurrentStatusOperation::::default()).json()) + .post("/set_temperature", self.op(AdjustStatusOperation::::default()).body::().json()) + .get("/download", self.op(CurrentFileOperation::::default()).file()) +``` + +流れるように連ねた呼び出しは、型付きプログラムを構築します。サーバールートをただちに登録する必要はありません。 + +## 一つのプログラムを複数のfoldで解釈する {#one-program-several-folds} + +同じ一階プログラムで複数の解釈を実現できます。 + +| プログラム | 解釈 | +| --- | --- | +| 型付きHTTPプログラム | テキスト形式のドキュメント、実行可能なルート、OpenAPIメタデータ、クライアントバインディング、適合性テスト | +| 型付きJSON-RPCプログラム | メソッド登録、スキーマ、クライアント、テストハーネス | + +実行とドキュメントで別々のルート一覧やメソッド一覧を管理しないでください。仕様が競合します。 + +## 入力と出力の役割 {#input-and-output-roles} + +操作はすでに引数型と結果型を認識しています。通信方式の宣言では、通信方式の意味だけを追加します。 + +```rust,noplayground +self.op(FindOperation::::default()) + .path::() + .query::() + .json() +``` + +`path`、`query`、`json`は役割を示します。`ApplyAlg`によってすでに決まっている出力型を、記述者に重ねて書かせるべきではありません。 + +出力変換は通信インタープリターに属します。サーバーは結果の一つをJSONに、別の結果をストリーミング添付ファイルに変換できます。意味論的な操作は、いずれの表現も意識しません。 + +## 合成もプログラムの意味 {#composition-is-program-meaning} + +プログラムでは汎用的な合成を保持するべきです。 + +* 空のプログラム +* プログラムを結合する +* プログラムを接頭辞の下にネストする +* エンドポイントをプログラムへ持ち上げる + +これらは一つのフレームワークのルーターメソッドより基礎的な操作です。`get`、`post`、`merge`、`nest`のような馴染みのある流れる形式の名前も、中立的な代数の別名にできます。 + +独立した仕様から、小さなプログラムを公開できます。 + +| 入力プログラム | 合成 | 結果 | +| --- | --- | --- | +| 状態取得とダウンロードのプログラム | 結合 | サービスプログラム | +| カタログプログラム | ネスト | サービスプログラム | + +アプリケーションが、結果の合成を選択して解釈します。 + +## マクロは公開された意味へ展開する {#macros-must-lower-to-public-meaning} + +Rustのマクロを使うと、一階宣言を簡潔に記述できます。 + +```rust,noplayground +#[ext(name = StatusApiExt, defunc(via = http))] +pub impl This +where + This: HttpApiAlg + JsonOutAlg, +{ + fn status_api(&self) + where + Alg: StatusAlg, + { + self.routes().get("/status", self.op(Alg::status_current).json()); + } +} +``` + +マクロが公開された手動構築可能な一階プログラムに展開される場合にのみ、適切に機能します。生成されたコールバックがインターフェースの唯一の定義になってはいけません。 + +望ましい流れ: + +1. 簡潔な構文 +2. 公開された操作値とプログラム値 +3. ジェネリックなfold +4. 具体的なフレームワーク + +表現先行の流れ: + +1. フレームワークの注釈 +2. 不透明な生成済みコールバック +3. リバースエンジニアリングによるドキュメント + +## 既存概念との関係 {#relation-to-existing-concepts} + +一階インターフェースプログラムは、ほかの章の技法を土台にしています。デファンクショナライズは一般的な変換であり、拡張可能な構文と解釈はExpression Problemに関わり、自由モナドは逐次合成を備えた構文表現の一種です。各項目はページ上部の関連リンクから参照できます。 + +これらの技法とDDそのものを同一視しないでください。DDが重要な構造を定め、通常の呼び出しでは消えてしまう場合に、一階表現がその構造を保持します。 + +## レビュー時の確認 {#review-checks} + +* 実際に二つ目のインタープリターが必要であり、そのために再構化するのか。 +* 操作は記述されたメソッドを重複実装せず呼び出しているか。 +* 引数と出力は操作から推論されるか。 +* 通信方式の構文は、通信方式上の役割だけを追加するか。 +* 便利なマクロがなくてもプログラムを構築できるか。 +* ランタイムとメタデータは同じプログラムを解釈しているか。 diff --git a/src/rust-dd/first-order-programs.ko.md b/src/rust-dd/first-order-programs.ko.md new file mode 100644 index 0000000..e15185b --- /dev/null +++ b/src/rust-dd/first-order-programs.ko.md @@ -0,0 +1,210 @@ + + +# 일차 프로그램 {#first-order-programs} + +```admonish tip title="관련 항목" +Rust에서 의미로 설계하기: [파생 의미와 합성](derived-meaning.md), [언어와 컴파일러 파이프라인](compiler-pipelines.md) +개념: [연속 전달 스타일](../concepts/cps.md), [디펑셔널라이제이션](../concepts/defunctionalization.md), [자유 모나드](../concepts/free_monad.md) +통찰: [표현식 문제 다시 보기](../insights/expression-problem.md) +``` + +```admonish note title="함수 적용을 재구화할 때" +일반 함수와 확장으로 이미 파생 동작을 표현할 수 있습니다. 다른 인터프리터가 실행 전에 프로그램을 살펴보거나 합성하거나 직렬화하거나 컴파일해야 할 때만 함수 적용을 일차 데이터로 바꾸세요. +``` + +일반 함수와 확장 메서드는 대개 파생 동작을 표현하는 가장 좋은 방법입니다. 그러나 실행 전에 다른 인터프리터가 프로그램 구조를 살펴보거나, 결합하거나, 문서화하거나, 직렬화하거나, 컴파일해야 할 때도 있습니다. 그러면 함수 적용 자체를 일차 데이터로 만들어야 합니다. + +## 실행은 구조를 지웁니다 {#execution-erases-structure} + +다음을 생각해 보세요: + +```rust,noplayground +#[ext(name = StatusExt)] +pub impl This +where + This: StatusAlg, +{ + async fn status_current(&self) -> This::Status { + self.status().await + } +} +``` + +이 메서드를 호출하면 상태가 반환됩니다. 호출이 시작되고 나면 외부 인터프리터는 일반적으로 다음 정보를 복구할 수 없습니다: + +* 의미론적 컨텍스트 타입 +* 순서가 있는 인수 +* 소스의 인수 이름 +* 결과 타입 +* 연산의 정체성 + +이 정보는 소스 수준 함수 타입에는 있었지만 일반적인 실행 과정에서 소비됩니다. + +## 함수 적용의 디펑셔널라이즈 {#defunctionalizing-application} + +디펑셔널라이제이션은 알려진 함수 계열의 원소를 일차 태그와 공유 함수 적용 연산으로 대체합니다. + +최소 연산 어휘는 다음과 같습니다: + +```rust,noplayground +trait OperationAlg { + type Context; + type Args; + + const ARG_NAMES: &'static [&'static str]; +} + +trait ApplyAlg { + type Output; + + async fn apply(&self, handle: Handle, args: Args) -> Self::Output; +} +``` + +크기가 0인 `CurrentStatusOperation`은 원래 확장 메서드의 함수 적용을 나타낼 수 있습니다. 메서드 본문을 한 번 더 복사하지 말고 그 메서드를 호출해야 합니다. + +1. 확장 메서드에서 시작합니다. +2. 이를 연산 타입으로 재구화합니다. +3. 컨텍스트, 인수 곱, 인수 이름, 출력을 보존합니다. +4. `ApplyAlg`를 통해 해석합니다. + +일반 호출에는 여전히 메서드가 편리합니다. 일차 구조가 필요한 컨텍스트에서는 연산 값을 사용합니다. + +## 사용처 없이 재구화하지 마세요 {#do-not-reify-without-a-consumer} + +일차 프로그램은 타입 수준 장치를 추가합니다. 실제로 두 번째 해석을 가능하게 할 때 사용하세요: + +* 런타임 등록 +* 문서 또는 스키마 생성 +* 정적 검사 +* 실행 전 프로그램 합성 +* 직렬화 +* 컴파일 + +코드가 함수 호출만 필요하다면 함수로 두세요. + +## 이식 가능한 인터페이스 프로그램 {#portable-interface-programs} + +HTTP 표면에 다음 요소가 있다고 가정해 봅시다: + +| 메서드 | 경로 | 입력 | 연산 | 출력 | +| --- | --- | --- | --- | --- | +| `GET` | `/status` | — | `status_current` | JSON | +| `POST` | `/set_temperature` | 본문: `f32` | `adjust_status` | JSON | +| `GET` | `/download` | — | `current_file` | 스트리밍 파일 | + +이식 가능한 프로그램은 다음을 보존해야 합니다: + +* 메서드 및 경로 선택자 +* 경로, 쿼리, 본문, 헤더, 인증 등의 입력 역할 +* 연산 값 +* JSON 또는 파일 등의 출력 역할 +* 경로의 병합과 중첩 + +특정 프레임워크의 요청, 라우터, 응답 타입을 보존해서는 안 됩니다. + +다음과 같은 유창한 표기법을 사용할 수 있습니다: + +```rust,noplayground +self.routes() + .get("/status", self.op(CurrentStatusOperation::::default()).json()) + .post("/set_temperature", self.op(AdjustStatusOperation::::default()).body::().json()) + .get("/download", self.op(CurrentFileOperation::::default()).file()) +``` + +유창한 호출은 타입이 지정된 프로그램을 구성합니다. 즉시 서버 경로를 등록할 필요는 없습니다. + +## 프로그램 하나, 여러 폴드 {#one-program-several-folds} + +같은 일차 프로그램을 여러 방식으로 해석할 수 있습니다: + +| 프로그램 | 해석 | +| --- | --- | +| 타입이 지정된 HTTP 프로그램 | 텍스트 문서, 실행 가능한 경로, OpenAPI 메타데이터, 클라이언트 바인딩, 적합성 테스트 | +| 타입이 지정된 JSON-RPC 프로그램 | 메서드 레지스트리, 스키마, 클라이언트, 테스트 하네스 | + +실행용 경로 목록과 문서용 메서드 목록을 따로 관리하지 마세요. 서로 경쟁하는 명세가 만들어집니다. + +## 입력 및 출력 역할 {#input-and-output-roles} + +연산은 이미 인수와 결과 타입을 알고 있습니다. 전송 선언은 전송 의미만 추가해야 합니다. + +```rust,noplayground +self.op(FindOperation::::default()) + .path::() + .query::() + .json() +``` + +`path`, `query`, `json`는 역할을 나타냅니다. `ApplyAlg`에서 이미 정해지는 출력 타입을 작성자에게 다시 명시하도록 요구해서는 안 됩니다. + +출력 변환은 전송 인터프리터의 책임입니다. 서버는 한 결과를 JSON으로, 다른 결과를 스트리밍 첨부 파일로 바꿀 수 있습니다. 의미론적 연산은 두 표현을 모두 알지 못합니다. + +## 합성은 프로그램의 의미입니다 {#composition-is-program-meaning} + +프로그램은 일반적인 합성을 보존해야 합니다: + +* 빈 프로그램 +* 프로그램 병합 +* 접두 경로 아래에 프로그램 중첩 +* 엔드포인트를 프로그램으로 올리기 + +이들은 특정 프레임워크의 라우터 메서드보다 근본적입니다. `get`, `post`, `merge`, `nest` 같은 익숙한 유창한 이름은 중립 대수의 별칭이 될 수 있습니다. + +독립적인 명세는 작은 프로그램을 제공할 수 있습니다: + +| 입력 프로그램 | 합성 | 결과 | +| --- | --- | --- | +| 상태 및 다운로드 프로그램 | 병합 | 서비스 프로그램 | +| 카탈로그 프로그램 | 중첩 | 서비스 프로그램 | + +애플리케이션이 결과 합성을 선택해 해석합니다. + +## 매크로는 공개 의미로 낮춰야 합니다 {#macros-must-lower-to-public-meaning} + +Rust 매크로를 사용하면 일차 선언을 편리하게 작성할 수 있습니다: + +```rust,noplayground +#[ext(name = StatusApiExt, defunc(via = http))] +pub impl This +where + This: HttpApiAlg + JsonOutAlg, +{ + fn status_api(&self) + where + Alg: StatusAlg, + { + self.routes().get("/status", self.op(Alg::status_current).json()); + } +} +``` + +매크로가 공개적으로 수동 구성 가능한 일차 프로그램으로 낮춰질 때에만 바람직합니다. 생성된 콜백이 인터페이스의 유일한 정의가 되어서는 안 됩니다. + +바람직한 방향: + +1. 편리한 구문 +2. 공개 연산 및 프로그램 값 +3. 제네릭 폴드 +4. 구체 프레임워크 + +표현 우선 방향: + +1. 프레임워크 어노테이션 +2. 불투명한 자동 생성 콜백 +3. 역공학한 문서 + +## 기존 개념과의 관계 {#relation-to-existing-concepts} + +일차 인터페이스 프로그램은 다른 장의 기법을 기반으로 합니다. 디펑셔널라이제이션은 일반적인 변환이고, 확장 가능한 구문과 해석은 표현식 문제이며, 자유 모나드는 시퀀싱이 있는 구문의 특정 표현입니다. 페이지 위쪽의 관련 링크에서 각각을 볼 수 있습니다. + +이 기법들을 표시적 설계 자체와 동일시하지 마세요. 표시적 설계는 어떤 구조가 중요한지 정하고, 일반 호출이 구조를 지우는 경우 일차 표현이 그 구조를 보존합니다. + +## 검토 항목 {#review-checks} + +* 실제 두 번째 인터프리터를 위해 재구화가 필요한가요? +* 연산이 작성된 메서드를 중복하지 않고 호출하나요? +* 인수와 출력 타입이 연산에서 추론되나요? +* 전송 구문이 전송 역할만 추가하나요? +* 편의 매크로 없이도 프로그램을 구성할 수 있나요? +* 런타임과 메타데이터가 같은 프로그램을 해석하나요? diff --git a/src/rust-dd/first-order-programs.ru.md b/src/rust-dd/first-order-programs.ru.md new file mode 100644 index 0000000..16f672e --- /dev/null +++ b/src/rust-dd/first-order-programs.ru.md @@ -0,0 +1,210 @@ + + +# Программы первого порядка {#first-order-programs} + +```admonish tip title="Связанные материалы" +«Проектирование на основе смысла в Rust»: [Производный смысл и композиция](derived-meaning.md), [Язык и конвейеры компилятора](compiler-pipelines.md) +«Понятия»: [Стиль передачи продолжений](../concepts/cps.md), [Дефункционализация](../concepts/defunctionalization.md), [Свободная монада](../concepts/free_monad.md) +«Идеи»: [Проблема выражения: новый взгляд](../insights/expression-problem.md) +``` + +```admonish note title="Когда реифицировать применение функции" +Обычные функции и методы-расширения уже позволяют выражать производное поведение. Представляйте применение функции данными первого порядка только тогда, когда другому интерпретатору нужно исследовать, компоновать, сериализовать или компилировать программу до её выполнения. +``` + +Обычные функции и методы-расширения обычно лучше всего выражают производное поведение. Иногда другому интерпретатору нужно исследовать, объединить, описать, сериализовать или скомпилировать структуру программы до применения функции. Тогда само применение функции должно стать данными первого порядка. + +## Выполнение стирает структуру {#execution-erases-structure} + +Рассмотрим следующий пример: + +```rust,noplayground +#[ext(name = StatusExt)] +pub impl This +where + This: StatusAlg, +{ + async fn status_current(&self) -> This::Status { + self.status().await + } +} +``` + +Вызов этого метода возвращает статус. После начала вызова внешний интерпретатор обычно уже не может восстановить: + +* тип семантического контекста +* порядок аргументов +* имена исходных аргументов +* тип результата +* идентичность операции + +Эта информация была в типе функции на уровне исходного кода, но обычное выполнение её поглощает. + +## Дефункционализация приложения {#defunctionalizing-application} + +Дефункционализация заменяет функцию из известного семейства функций данными первого порядка — меткой и общей операцией применения. + +Минимальный словарь операций: + +```rust,noplayground +trait OperationAlg { + type Context; + type Args; + + const ARG_NAMES: &'static [&'static str]; +} + +trait ApplyAlg { + type Output; + + async fn apply(&self, handle: Handle, args: Args) -> Self::Output; +} +``` + +Значение нулевого размера `CurrentStatusOperation` может обозначать применение исходного метода-расширения. Оно должно вызывать этот метод, а не содержать его вторую копию. + +1. Начните с метода-расширения. +2. Представьте его как тип операции. +3. Сохраните контекст, произведение аргументов, имена аргументов и результат. +4. Интерпретируйте его с помощью `ApplyAlg`. + +Метод остаётся удобным для обычных вызовов. Значение операции нужно тем контекстам, которым требуется структура первого порядка. + +## Не реифицируйте без потребителя {#do-not-reify-without-a-consumer} + +Программы первого порядка добавляют типовые механизмы. Используйте их, когда они обеспечивают реальную вторую интерпретацию: + +* регистрация во время выполнения +* генерация документации или схемы +* статический анализ +* композиция программ до выполнения +* сериализация +* компиляция + +Если коду нужно только вызвать функцию, оставьте её функцией. + +## Переносимые интерфейсные программы {#portable-interface-programs} + +Предположим, интерфейс HTTP содержит: + +| Метод | Путь | Входные данные | Операция | Выходные данные | +| --- | --- | --- | --- | --- | +| `GET` | `/status` | — | `status_current` | JSON | +| `POST` | `/set_temperature` | Тело: `f32` | `adjust_status` | JSON | +| `GET` | `/download` | — | `current_file` | Потоковый файл | + +Переносимая программа должна сохранять: + +* селекторы метода и пути +* роли входных данных: путь, запрос, тело, заголовок и аутентификация +* значение операции +* роль результата, например JSON или файл +* слияние и вложенность маршрутов + +Ей не следует сохранять типы запроса, маршрутизатора или ответа конкретного фреймворка. + +Например, можно использовать такую цепочку вызовов: + +```rust,noplayground +self.routes() + .get("/status", self.op(CurrentStatusOperation::::default()).json()) + .post("/set_temperature", self.op(AdjustStatusOperation::::default()).body::().json()) + .get("/download", self.op(CurrentFileOperation::::default()).file()) +``` + +Вызовы в цепочке строят типизированную программу. Они не обязаны сразу регистрировать маршрут сервера. + +## Одна программа, несколько свёрток {#one-program-several-folds} + +Одну и ту же программу первого порядка можно интерпретировать по-разному: + +| Программа | Интерпретации | +| --- | --- | +| Типизированная программа HTTP | Текстовая документация, исполняемые маршруты, метаданные OpenAPI, привязки клиента, тесты на соответствие | +| Типизированная программа JSON-RPC | Реестр методов, схема, клиент, тестовая среда | + +Не поддерживайте отдельные списки маршрутов или методов для выполнения и документации: это приводит к конкурирующим спецификациям. + +## Роли входных и выходных данных {#input-and-output-roles} + +Операция уже знает типы аргументов и результата. Объявление транспорта должно добавлять только смысл транспорта. + +```rust,noplayground +self.op(FindOperation::::default()) + .path::() + .query::() + .json() +``` + +`path`, `query` и `json` задают роли. Не заставляйте автора повторно указывать тип результата, который уже определяется через `ApplyAlg`. + +Преобразование результата относится к транспортному интерпретатору. Сервер может преобразовать один результат в JSON, а другой — в потоковое вложение. Семантические операции не должны знать ни о том, ни о другом представлении. + +## Композиция — часть смысла программы {#composition-is-program-meaning} + +Программы должны поддерживать общие операции композиции: + +* Пустая программа +* Слияние программ +* Вложение программы под префикс +* Добавление конечной точки в программу + +Это фундаментальнее методов маршрутизатора конкретного фреймворка. Привычные цепочечные имена, например `get`, `post`, `merge` и `nest`, могут быть псевдонимами для нейтральной алгебры. + +Независимые спецификации могут публиковать небольшие программы: + +| Входные программы | Композиция | Результат | +| --- | --- | --- | +| Программы статуса и загрузки | Слияние | Программа сервиса | +| Каталожная программа | Вложение | Программа сервиса | + +Приложение выбирает и интерпретирует полученную композицию. + +## Макросы должны сводиться к публичному смыслу {#macros-must-lower-to-public-meaning} + +Макросы Rust могут упростить объявления первого порядка: + +```rust,noplayground +#[ext(name = StatusApiExt, defunc(via = http))] +pub impl This +where + This: HttpApiAlg + JsonOutAlg, +{ + fn status_api(&self) + where + Alg: StatusAlg, + { + self.routes().get("/status", self.op(Alg::status_current).json()); + } +} +``` + +Макрос хорош только тогда, когда преобразует объявление в публичную программу первого порядка, которую можно создать вручную. Сгенерированные обратные вызовы не должны становиться единственным определением интерфейса. + +Предпочтительное направление: + +1. Удобный синтаксис +2. Публичные значения операций и программ +3. Обобщённая свёртка +4. Конкретный фреймворк + +Направление от представления: + +1. Аннотация фреймворка +2. Непрозрачные сгенерированные обратные вызовы +3. Документация, восстановленная обратным анализом + +## Связь с существующими понятиями {#relation-to-existing-concepts} + +Программы интерфейсов первого порядка опираются на методы из других глав: дефункционализация — это общее преобразование; расширяемый синтаксис и интерпретации относятся к проблеме выражения; свободная монада — лишь один конкретный вариант представления синтаксиса с последовательностью операций. Ссылки «Связанные материалы» вверху страницы ведут к каждому из этих разделов. + +Не отождествляйте эти методы с самим денотационным проектированием. Оно определяет важную структуру; представления первого порядка сохраняют её, когда обычные вызовы стирают её. + +## Проверочные вопросы {#review-checks} + +* Требует ли реальный второй интерпретатор реификации? +* Вызывает ли операция метод, заданный автором, вместо его дублирования? +* Выводятся ли типы аргументов и результата из операции? +* Добавляет ли транспортный синтаксис только транспортные роли? +* Можно ли создать программу без вспомогательного макроса? +* Интерпретируют ли среда выполнения и метаданные одну и ту же программу? diff --git a/src/rust-dd/first-order-programs.uk.md b/src/rust-dd/first-order-programs.uk.md new file mode 100644 index 0000000..8df63ee --- /dev/null +++ b/src/rust-dd/first-order-programs.uk.md @@ -0,0 +1,210 @@ + + +# Програми першого порядку {#first-order-programs} + +```admonish tip title="Пов’язані матеріали" +Проєктування від значення в Rust: [Похідне значення та композиція](derived-meaning.md), [Мова й конвеєри компілятора](compiler-pipelines.md) +Поняття: [Стиль передавання продовжень](../concepts/cps.md), [Дефункціоналізація](../concepts/defunctionalization.md), [Вільна монада](../concepts/free_monad.md) +Інсайти: [Проблема виразів: новий погляд](../insights/expression-problem.md) +``` + +```admonish note title="Коли варто реїфікувати застосування" +Звичайних функцій і розширень уже достатньо, щоб виражати похідну поведінку. Перетворюйте застосування на дані першого порядку лише тоді, коли інший інтерпретатор має оглянути, поєднати, серіалізувати чи скомпілювати програму до її запуску. +``` + +Звичайні функції й методи-розширення зазвичай найкраще виражають похідну поведінку. Іноді іншому інтерпретатору потрібно оглянути, поєднати, задокументувати, серіалізувати чи скомпілювати структуру програми до її застосування. Тоді саме застосування треба подати як дані першого порядку. + +## Виконання стирає структуру {#execution-erases-structure} + +Розгляньмо: + +```rust,noplayground +#[ext(name = StatusExt)] +pub impl This +where + This: StatusAlg, +{ + async fn status_current(&self) -> This::Status { + self.status().await + } +} +``` + +Виклик цього методу повертає стан. Після початку виклику зовнішній інтерпретатор зазвичай уже не може відновити: + +* семантичний тип контексту +* упорядковані аргументи +* назви аргументів у вихідному коді +* тип результату +* ідентичність операції + +Ця інформація була доступна у типі функції на рівні вихідного коду, але під час звичайного виконання вона споживається. + +## Дефункціоналізація застосунку {#defunctionalizing-application} + +Дефункціоналізація замінює елемент відомого сімейства функцій даними першого порядку — тегом і спільною операцією застосування. + +Мінімальний набір операцій: + +```rust,noplayground +trait OperationAlg { + type Context; + type Args; + + const ARG_NAMES: &'static [&'static str]; +} + +trait ApplyAlg { + type Output; + + async fn apply(&self, handle: Handle, args: Args) -> Self::Output; +} +``` + +Тип нульового розміру `CurrentStatusOperation` може позначати застосування початкового методу-розширення. Він має викликати цей метод, а не містити його тіло вдруге. + +1. Почніть із методу-розширення. +2. Перетворіть його на тип операції. +3. Збережіть його контекст, добуток аргументів, назви аргументів і вихідне значення. +4. Інтерпретуйте його через `ApplyAlg`. + +Метод лишається зручним для звичайних викликів. Значення операції потрібне лише контекстам, яким необхідна структура першого порядку. + +## Не реїфікуйте без споживача {#do-not-reify-without-a-consumer} + +Програми першого порядку додають механізми типів. Використовуйте їх, коли вони уможливлюють реальну другу інтерпретацію: + +* реєстрація під час виконання +* створення документації чи схем +* статичний аналіз +* композиція програми до виконання +* серіалізація +* компіляція + +Якщо коду потрібно лише викликати функцію, залиште її функцією. + +## Переносні програми інтерфейсу {#portable-interface-programs} + +Припустімо, поверхня HTTP містить: + +| Метод | Шлях | Вхідні дані | Операція | Вихідні дані | +| --- | --- | --- | --- | --- | +| `GET` | `/status` | — | `status_current` | JSON | +| `POST` | `/set_temperature` | Тіло: `f32` | `adjust_status` | JSON | +| `GET` | `/download` | — | `current_file` | Файл для потокового передавання | + +Переносна програма має зберігати: + +* селектори методу й шляху +* ролі вхідних даних, як-от шлях, запит, тіло, заголовок і автентифікація +* значення операції +* роль вихідних даних, наприклад JSON чи файл +* злиття маршрутів і вкладеність + +Вона не має зберігати конкретний тип запиту, маршрутизатора чи відповіді певного фреймворку. + +Можлива форма з ланцюжком викликів: + +```rust,noplayground +self.routes() + .get("/status", self.op(CurrentStatusOperation::::default()).json()) + .post("/set_temperature", self.op(AdjustStatusOperation::::default()).body::().json()) + .get("/download", self.op(CurrentFileOperation::::default()).file()) +``` + +Ланцюжок викликів створює типізовану програму. Він не зобов’язаний одразу реєструвати маршрут сервера. + +## Одна програма — кілька згортань {#one-program-several-folds} + +Ту саму програму першого порядку можна інтерпретувати кількома способами: + +| Програма | Інтерпретації | +| --- | --- | +| Типізована програма HTTP | Текстова документація, виконувані маршрути, метадані OpenAPI, прив’язки клієнта, тести на відповідність | +| Типізована програма JSON-RPC | Реєстр методів, схема, клієнт, тестовий каркас | + +Не підтримуйте окремі списки маршрутів чи методів для виконання й документації: так виникають конкуруючі специфікації. + +## Ролі вхідних і вихідних даних {#input-and-output-roles} + +Операція вже знає типи аргументів і результату. Оголошення транспорту має додавати лише транспортне значення. + +```rust,noplayground +self.op(FindOperation::::default()) + .path::() + .query::() + .json() +``` + +`path`, `query` та `json` визначають ролі. Вони не мають змушувати автора повторно вказувати тип виходу, уже визначений через `ApplyAlg`. + +Перетворення виходу належить транспортному інтерпретатору. Сервер може перетворити один результат на JSON, а інший — на вкладення для потокового передавання. Семантичні операції не залежать від жодного з цих представлень. + +## Композиція є значенням програми {#composition-is-program-meaning} + +Програми мають зберігати загальні операції композиції: + +* порожня програма +* об’єднання програм +* вкладення програми під префіксом +* підняття кінцевої точки до програми + +Це фундаментальніше за методи маршрутизатора одного фреймворку. Звичні ланцюжкові назви на кшталт `get`, `post`, `merge` та `nest` можуть бути псевдонімами операцій нейтральної алгебри. + +Незалежні специфікації можуть публікувати невеликі програми: + +| Вхідні програми | Композиція | Результат | +| --- | --- | --- | +| Програми стану й завантаження | Об’єднання | Програма служби | +| Програма каталогу | Вкладення | Програма служби | + +Застосунок вибирає та інтерпретує отриману композицію. + +## Макроси мають зводитися до публічного значення {#macros-must-lower-to-public-meaning} + +Макроси Rust можуть спростити читабельність оголошень першого порядку: + +```rust,noplayground +#[ext(name = StatusApiExt, defunc(via = http))] +pub impl This +where + This: HttpApiAlg + JsonOutAlg, +{ + fn status_api(&self) + where + Alg: StatusAlg, + { + self.routes().get("/status", self.op(Alg::status_current).json()); + } +} +``` + +Макрос прийнятний, лише якщо він зводиться до публічної, придатної для ручного конструювання програми першого порядку. Згенеровані зворотні виклики не мають ставати єдиним визначенням інтерфейсу. + +Правильний напрямок: + +1. Зручний синтаксис +2. Публічні значення операцій і програм +3. Узагальнене згортання +4. Конкретний фреймворк + +Напрямок, що виходить із представлення: + +1. Анотація фреймворку +2. Непрозорі згенеровані зворотні виклики +3. Документація, відновлена з реалізації + +## Зв’язок з наявними поняттями {#relation-to-existing-concepts} + +Програми інтерфейсу першого порядку спираються на методи з інших розділів: дефункціоналізація є загальним перетворенням, розширюваний синтаксис та інтерпретації стосуються проблеми виразів, а вільна монада — це один конкретний різновид представлення синтаксису з послідовністю. Посилання у верхній частині сторінки ведуть до кожного з цих понять. + +Не ототожнюйте ці методи з денотаційним проєктуванням. Воно визначає, яка структура важлива; представлення першого порядку зберігають цю структуру, коли звичайні виклики її стирають. + +## Перевірка {#review-checks} + +* Чи потрібна реїфікація справжньому другому інтерпретатору? +* Чи викликає операція авторський метод, а не дублює його? +* Чи визначаються аргументи й вихід із самої операції? +* Чи додає транспортний синтаксис лише транспортні ролі? +* Чи можна створити програму без допоміжного макросу? +* Чи інтерпретують середовище виконання й метадані ту саму програму? diff --git a/src/rust-dd/first-order-programs.vi.md b/src/rust-dd/first-order-programs.vi.md new file mode 100644 index 0000000..a5ba5df --- /dev/null +++ b/src/rust-dd/first-order-programs.vi.md @@ -0,0 +1,210 @@ + + +# Chương trình bậc nhất {#first-order-programs} + +```admonish tip title="Liên quan" +Thiết kế theo ngữ nghĩa trong Rust: [Ý nghĩa suy ra và phép hợp thành](derived-meaning.md), [Quy trình ngôn ngữ và trình biên dịch](compiler-pipelines.md) +Khái niệm: [Phong cách truyền tiếp nối](../concepts/cps.md), [Phi chức năng hóa](../concepts/defunctionalization.md), [Monad tự do](../concepts/free_monad.md) +Nhận định: [Bài toán biểu thức trở lại](../insights/expression-problem.md) +``` + +```admonish note title="Khi nào nên tái hiện phép áp dụng hàm" +Các hàm thông thường và phần mở rộng đã biểu đạt được hành vi suy ra. Chỉ chuyển phép áp dụng hàm thành dữ liệu bậc nhất khi một bộ diễn giải khác cần kiểm tra, hợp thành, tuần tự hóa hoặc biên dịch chương trình trước khi chạy. +``` + +Hàm thông thường và phương thức mở rộng thường là cách tốt nhất để biểu đạt hành vi suy ra. Đôi khi bộ diễn giải khác phải kiểm tra, kết hợp, lập tài liệu, tuần tự hóa hoặc biên dịch cấu trúc chương trình trước khi áp dụng nó. Khi đó, bản thân phép áp dụng hàm phải trở thành dữ liệu bậc nhất. + +## Thực thi xóa mất cấu trúc {#execution-erases-structure} + +Hãy xét: + +```rust,noplayground +#[ext(name = StatusExt)] +pub impl This +where + This: StatusAlg, +{ + async fn status_current(&self) -> This::Status { + self.status().await + } +} +``` + +Gọi phương thức này sẽ cho ra trạng thái. Sau khi lời gọi bắt đầu, bộ diễn giải bên ngoài thường không thể khôi phục: + +* kiểu ngữ cảnh ngữ nghĩa +* các đối số theo thứ tự +* tên đối số trong mã nguồn +* kiểu kết quả +* danh tính của phép toán + +Thông tin đó có trong kiểu hàm ở cấp nguồn, nhưng bị tiêu thụ trong quá trình thực thi thông thường. + +## Phi chức năng hóa phép áp dụng hàm {#defunctionalizing-application} + +Phi chức năng hóa thay một phần tử thuộc họ hàm đã biết bằng thẻ bậc nhất và một phép áp dụng dùng chung. + +Một tập từ vựng phép toán tối thiểu là: + +```rust,noplayground +trait OperationAlg { + type Context; + type Args; + + const ARG_NAMES: &'static [&'static str]; +} + +trait ApplyAlg { + type Output; + + async fn apply(&self, handle: Handle, args: Args) -> Self::Output; +} +``` + +`CurrentStatusOperation` kích thước bằng không có thể biểu thị việc áp dụng phương thức mở rộng gốc. Nó cần gọi phương thức đó, không chứa bản sao thứ hai của phần thân. + +1. Bắt đầu từ phương thức mở rộng. +2. Tái hóa nó thành một kiểu phép toán. +3. Bảo toàn ngữ cảnh, tích các đối số, tên đối số và đầu ra. +4. Diễn giải nó thông qua `ApplyAlg`. + +Phương thức vẫn thuận tiện cho các lời gọi thông thường. Giá trị phép toán dành cho những ngữ cảnh cần cấu trúc bậc nhất. + +## Đừng tái hóa khi chưa có bên sử dụng {#do-not-reify-without-a-consumer} + +Chương trình bậc nhất thêm cơ chế kiểu. Hãy dùng chúng khi chúng cho phép một cách diễn giải thứ hai thực sự: + +* đăng ký lúc chạy +* tạo tài liệu hoặc lược đồ +* kiểm tra tĩnh +* hợp thành chương trình trước khi thực thi +* tuần tự hóa +* biên dịch + +Nếu mã chỉ cần gọi một hàm, hãy giữ nguyên hàm đó. + +## Chương trình giao diện khả chuyển {#portable-interface-programs} + +Giả sử một bề mặt HTTP gồm: + +| Phương thức | Đường dẫn | Đầu vào | Phép toán | Đầu ra | +| --- | --- | --- | --- | --- | +| `GET` | `/status` | — | `status_current` | JSON | +| `POST` | `/set_temperature` | Thân: `f32` | `adjust_status` | JSON | +| `GET` | `/download` | — | `current_file` | Tệp truyền theo luồng | + +Chương trình khả chuyển phải bảo toàn: + +* bộ chọn phương thức và đường dẫn +* vai trò đầu vào như đường dẫn, truy vấn, thân, tiêu đề và xác thực +* giá trị phép toán +* vai trò đầu ra như JSON hoặc tệp +* phép gộp và lồng tuyến + +Nó không nên bảo toàn kiểu yêu cầu, bộ định tuyến hay phản hồi của một khung cụ thể. + +Một ký pháp chuỗi phương thức có thể là: + +```rust,noplayground +self.routes() + .get("/status", self.op(CurrentStatusOperation::::default()).json()) + .post("/set_temperature", self.op(AdjustStatusOperation::::default()).body::().json()) + .get("/download", self.op(CurrentFileOperation::::default()).file()) +``` + +Các lời gọi nối tiếp tạo ra một chương trình có kiểu. Chúng không nhất thiết phải đăng ký tuyến máy chủ ngay lập tức. + +## Một chương trình, nhiều phép gấp {#one-program-several-folds} + +Cùng chương trình bậc nhất có thể hỗ trợ nhiều cách diễn giải: + +| Chương trình | Các cách diễn giải | +| --- | --- | +| Chương trình HTTP có kiểu | Tài liệu văn bản, tuyến có thể thực thi, siêu dữ liệu OpenAPI, liên kết phía ứng dụng khách, kiểm thử tính phù hợp | +| Chương trình JSON-RPC có kiểu | Sổ đăng ký phương thức, lược đồ, ứng dụng khách, bộ khung kiểm thử | + +Đừng duy trì danh sách tuyến hoặc phương thức riêng cho thực thi và tài liệu. Việc đó tạo ra các đặc tả cạnh tranh. + +## Vai trò đầu vào và đầu ra {#input-and-output-roles} + +Phép toán đã biết kiểu đối số và kết quả. Khai báo truyền tải chỉ nên bổ sung ý nghĩa truyền tải. + +```rust,noplayground +self.op(FindOperation::::default()) + .path::() + .query::() + .json() +``` + +`path`, `query` và `json` xác định vai trò. Chúng không nên buộc tác giả nêu lại kiểu đầu ra vốn đã được xác định bởi `ApplyAlg`. + +Việc chuyển đổi đầu ra thuộc về bộ diễn giải truyền tải. Máy chủ có thể chuyển kết quả này thành JSON và kết quả khác thành tệp đính kèm truyền theo luồng. Các phép toán ngữ nghĩa không nhận biết các cách biểu diễn đó. + +## Phép hợp thành là ý nghĩa chương trình {#composition-is-program-meaning} + +Chương trình nên bảo toàn phép hợp thành tổng quát: + +* Chương trình rỗng +* Gộp các chương trình +* Lồng chương trình dưới một tiền tố +* Nâng một điểm cuối thành chương trình + +Các phép này căn bản hơn phương thức bộ định tuyến của một khung cụ thể. Các tên nối chuỗi quen thuộc như `get`, `post`, `merge` và `nest` có thể là bí danh trên đại số trung lập. + +Các đặc tả độc lập có thể công bố chương trình nhỏ: + +| Chương trình đầu vào | Phép hợp thành | Kết quả | +| --- | --- | --- | +| Chương trình trạng thái và tải xuống | Gộp | Chương trình dịch vụ | +| Chương trình danh mục | Lồng | Chương trình dịch vụ | + +Ứng dụng chọn và diễn giải phép hợp thành kết quả. + +## Macro phải hạ xuống ý nghĩa công khai {#macros-must-lower-to-public-meaning} + +Macro Rust có thể giúp khai báo bậc nhất dễ viết: + +```rust,noplayground +#[ext(name = StatusApiExt, defunc(via = http))] +pub impl This +where + This: HttpApiAlg + JsonOutAlg, +{ + fn status_api(&self) + where + Alg: StatusAlg, + { + self.routes().get("/status", self.op(Alg::status_current).json()); + } +} +``` + +Macro chỉ lành mạnh khi nó hạ xuống một chương trình bậc nhất công khai, có thể tự dựng thủ công. Callback được tạo sinh không được trở thành định nghĩa duy nhất của giao diện. + +Hướng đi tốt: + +1. Cú pháp thuận tiện +2. Giá trị phép toán và chương trình công khai +3. Phép gấp tổng quát +4. Khung cụ thể + +Hướng đi ưu tiên biểu diễn: + +1. Chú giải của khung +2. Callback được tạo sinh mờ đục +3. Tài liệu được suy ngược + +## Quan hệ với các khái niệm hiện có {#relation-to-existing-concepts} + +Chương trình giao diện bậc nhất xây dựng dựa trên các kỹ thuật ở chương khác: phi chức năng hóa là phép biến đổi tổng quát, cú pháp có thể mở rộng và cách diễn giải tạo thành Bài toán biểu thức, còn monad tự do là một dạng biểu diễn cú pháp kèm thứ tự hóa. Các liên kết liên quan ở đầu trang dẫn đến từng nội dung. + +Đừng đồng nhất những kỹ thuật này với DD. DD xác định cấu trúc nào quan trọng; biểu diễn bậc nhất bảo toàn cấu trúc ấy khi lời gọi thông thường có thể xóa mất nó. + +## Các câu hỏi khi duyệt {#review-checks} + +* Việc tái hóa có cần thiết cho một bộ diễn giải thứ hai thực sự không? +* Phép toán có gọi phương thức do tác giả viết thay vì sao chép phương thức đó không? +* Đối số và đầu ra có được suy ra từ phép toán không? +* Cú pháp truyền tải chỉ bổ sung các vai trò truyền tải chứ? +* Có thể dựng chương trình mà không cần macro tiện ích không? +* Môi trường chạy và siêu dữ liệu có diễn giải cùng chương trình không? diff --git a/src/rust-dd/first-order-programs.zh-hant.md b/src/rust-dd/first-order-programs.zh-hant.md new file mode 100644 index 0000000..f189365 --- /dev/null +++ b/src/rust-dd/first-order-programs.zh-hant.md @@ -0,0 +1,210 @@ + + +# 一階程式 {#first-order-programs} + +```admonish tip title="相關內容" +Rust 中的語義驅動設計:[派生含義與組合](derived-meaning.md)、[語言與編譯器流水線](compiler-pipelines.md) +概念:[延續傳遞風格](../concepts/cps.md)、[去函式化](../concepts/defunctionalization.md)、[自由單子](../concepts/free_monad.md) +洞見:[重新審視表示式問題](../insights/expression-problem.md) +``` + +```admonish note title="何時將應用具體化為資料" +普通函式與擴充已經可以表達派生行為。只有當另一個直譯器必須在執行前檢查、組合、序列化或編譯程式時,才應將應用轉換為一階資料。 +``` + +普通函式與擴充方法通常是表達派生行為的最佳方式。但有時另一個直譯器必須在執行程式之前,先檢查、組合、產生文件、序列化或編譯程式結構。這時,應用本身必須成為一階資料。 + +## 執行會抹去結構 {#execution-erases-structure} + +考慮: + +```rust,noplayground +#[ext(name = StatusExt)] +pub impl This +where + This: StatusAlg, +{ + async fn status_current(&self) -> This::Status { + self.status().await + } +} +``` + +呼叫此方法會得到一個狀態。呼叫開始後,外部直譯器通常無法再恢復以下資訊: + +* 語義上下文型別 +* 有序引數 +* 源引數名稱 +* 結果型別 +* 操作的身份 + +這些資訊原本存在於原始碼級別的函式型別中,但普通執行過程會消耗掉它們。 + +## 對應用進行去函式化 {#defunctionalizing-application} + +去函式化會將某個已知函式族中的成員替換為一階標籤,並提供一個共享的應用操作。 + +一組最小操作詞彙如下: + +```rust,noplayground +trait OperationAlg { + type Context; + type Args; + + const ARG_NAMES: &'static [&'static str]; +} + +trait ApplyAlg { + type Output; + + async fn apply(&self, handle: Handle, args: Args) -> Self::Output; +} +``` + +零大小的`CurrentStatusOperation`可以表示對原擴充方法的呼叫。它應當呼叫該方法,而不是包含一份重複的函式體。 + +1. 從擴充方法開始。 +2. 將其具體化為操作型別。 +3. 保留其上下文、引數乘積、引數名稱與輸出。 +4. 透過`ApplyAlg`對其進行解釋。 + +普通呼叫仍可使用原有便捷方法。只有需要一階結構的上下文才會用到操作值。 + +## 沒有使用者時,不要具體化為資料 {#do-not-reify-without-a-consumer} + +一階程式會增加型別機制。只有當它們能支援真正的第二種解釋時才使用: + +* 執行時註冊 +* 生成文件或模式 +* 靜態檢查 +* 執行前組合程式 +* 序列化 +* 編譯 + +如果程式碼只需呼叫函式,就保留函式即可。 + +## 可移植介面程式 {#portable-interface-programs} + +假設 HTTP 介面包含: + +| 方法 | 路徑 | 輸入 | 操作 | 輸出 | +| --- | --- | --- | --- | --- | +| `GET` | `/status` | — | `status_current` | JSON | +| `POST` | `/set_temperature` | 正文:`f32` | `adjust_status` | JSON | +| `GET` | `/download` | — | `current_file` | 流式檔案 | + +可移植程式必須保留: + +* 方法與路徑選擇器 +* 輸入角色,例如路徑、查詢引數、正文、請求頭與身份驗證 +* 操作值 +* 輸出角色,例如 JSON 或檔案 +* 路由合併與巢狀 + +不應保留某個特定框架的請求、路由器或響應型別。 + +一種流暢記法可以是: + +```rust,noplayground +self.routes() + .get("/status", self.op(CurrentStatusOperation::::default()).json()) + .post("/set_temperature", self.op(AdjustStatusOperation::::default()).body::().json()) + .get("/download", self.op(CurrentFileOperation::::default()).file()) +``` + +這些流暢呼叫會構造一個有型別的程式,不必立即註冊伺服器路由。 + +## 一個程式,多種摺疊解釋 {#one-program-several-folds} + +同一個一階程式可以支援多種解釋: + +| 程式 | 解釋 | +| --- | --- | +| 有型別的 HTTP 程式 | 文字文件、可執行路由、OpenAPI 後設資料、客戶端繫結、符合性測試 | +| 有型別的 JSON-RPC 程式 | 方法登錄檔、模式、客戶端、測試框架 | + +不要為執行與文件分別維護路由或方法清單,否則會產生彼此競爭的規範。 + +## 輸入與輸出角色 {#input-and-output-roles} + +操作已經知道自身的引數與結果型別。傳輸宣告只應新增傳輸含義。 + +```rust,noplayground +self.op(FindOperation::::default()) + .path::() + .query::() + .json() +``` + +`path`、`query`和`json`用於標識角色,不應要求作者重新宣告已經由`ApplyAlg`決定的輸出型別。 + +輸出轉換屬於傳輸直譯器。伺服器可以將一種結果轉換為 JSON,將另一種結果轉換為流式附件。語義操作無需瞭解任何一種表示。 + +## 組合本身就是程式含義 {#composition-is-program-meaning} + +程式應保留通用組合操作: + +* 空程式 +* 合併程式 +* 將程式巢狀在某個字首下 +* 將端點提升為程式 + +這些操作比某個框架的路由器方法更基礎。熟悉的流暢名稱,例如`get`、`post`、`merge`和`nest`,都可以作為中性代數的別名。 + +獨立規範可以釋出小型程式: + +| 輸入程式 | 組合 | 結果 | +| --- | --- | --- | +| 狀態與下載程式 | 合併 | 服務程式 | +| 目錄程式 | 巢狀 | 服務程式 | + +應用程式負責選擇並解釋最終的組合。 + +## 宏必須展開為公開的語義結構 {#macros-must-lower-to-public-meaning} + +Rust 宏可以讓一階宣告更加簡潔: + +```rust,noplayground +#[ext(name = StatusApiExt, defunc(via = http))] +pub impl This +where + This: HttpApiAlg + JsonOutAlg, +{ + fn status_api(&self) + where + Alg: StatusAlg, + { + self.routes().get("/status", self.op(Alg::status_current).json()); + } +} +``` + +只有當宏展開後得到公開且可手動構造的一階程式時,宏設計才算健全。生成的回呼不應成為介面的唯一規範定義。 + +良好方向: + +1. 便捷語法 +2. 公開的操作值與程式值 +3. 泛型摺疊解釋 +4. 具體框架 + +表示優先的方向: + +1. 框架註解 +2. 不透明的生成回撥 +3. 逆向整理的文件 + +## 與既有概念的關係 {#relation-to-existing-concepts} + +一階介面程式建立在其他章節介紹的技術之上:去函式化是通用變換;可擴充語法與解釋對應表示式問題;自由單子則是一種特定的“帶順序的語法”表示。頁面頂部的“相關內容”連結可以跳轉到各自章節。 + +不要把這些技術等同於指稱設計本身。指稱設計決定哪些結構很重要;當普通呼叫會抹去這些結構時,一階表示負責保留它們。 + +## 審查要點 {#review-checks} + +* 是否有真實的第二種直譯器需要將程式具體化? +* 操作是否呼叫作者定義的方法,而非複製其實現? +* 引數與輸出是否從操作中推斷得出? +* 傳輸語法是否只新增了傳輸角色? +* 程式是否可以在不使用便捷宏的情況下構造? +* 執行時與後設資料是否解釋同一個程式? diff --git a/src/rust-dd/first-order-programs.zh.md b/src/rust-dd/first-order-programs.zh.md new file mode 100644 index 0000000..2b4aabc --- /dev/null +++ b/src/rust-dd/first-order-programs.zh.md @@ -0,0 +1,210 @@ + + +# 一阶程序 {#first-order-programs} + +```admonish tip title="相关内容" +Rust 中的语义驱动设计:[派生含义与组合](derived-meaning.md)、[语言与编译器流水线](compiler-pipelines.md) +概念:[延续传递风格](../concepts/cps.md)、[去函数化](../concepts/defunctionalization.md)、[自由单子](../concepts/free_monad.md) +洞见:[重新审视表达式问题](../insights/expression-problem.md) +``` + +```admonish note title="何时将应用具体化为数据" +普通函数与扩展已经可以表达派生行为。只有当另一个解释器必须在运行前检查、组合、序列化或编译程序时,才应将应用转换为一阶数据。 +``` + +普通函数与扩展方法通常是表达派生行为的最佳方式。但有时另一个解释器必须在执行程序之前,先检查、组合、生成文档、序列化或编译程序结构。这时,应用本身必须成为一阶数据。 + +## 执行会抹去结构 {#execution-erases-structure} + +考虑: + +```rust,noplayground +#[ext(name = StatusExt)] +pub impl This +where + This: StatusAlg, +{ + async fn status_current(&self) -> This::Status { + self.status().await + } +} +``` + +调用此方法会得到一个状态。调用开始后,外部解释器通常无法再恢复以下信息: + +* 语义上下文类型 +* 有序参数 +* 源参数名称 +* 结果类型 +* 操作的身份 + +这些信息原本存在于源代码级别的函数类型中,但普通执行过程会消耗掉它们。 + +## 对应用进行去函数化 {#defunctionalizing-application} + +去函数化会将某个已知函数族中的成员替换为一阶标签,并提供一个共享的应用操作。 + +一组最小操作词汇如下: + +```rust,noplayground +trait OperationAlg { + type Context; + type Args; + + const ARG_NAMES: &'static [&'static str]; +} + +trait ApplyAlg { + type Output; + + async fn apply(&self, handle: Handle, args: Args) -> Self::Output; +} +``` + +零大小的`CurrentStatusOperation`可以表示对原扩展方法的调用。它应当调用该方法,而不是包含一份重复的函数体。 + +1. 从扩展方法开始。 +2. 将其具体化为操作类型。 +3. 保留其上下文、参数乘积、参数名称与输出。 +4. 通过`ApplyAlg`对其进行解释。 + +普通调用仍可使用原有便捷方法。只有需要一阶结构的上下文才会用到操作值。 + +## 没有使用者时,不要具体化为数据 {#do-not-reify-without-a-consumer} + +一阶程序会增加类型机制。只有当它们能支持真正的第二种解释时才使用: + +* 运行时注册 +* 生成文档或模式 +* 静态检查 +* 执行前组合程序 +* 序列化 +* 编译 + +如果代码只需调用函数,就保留函数即可。 + +## 可移植接口程序 {#portable-interface-programs} + +假设 HTTP 接口包含: + +| 方法 | 路径 | 输入 | 操作 | 输出 | +| --- | --- | --- | --- | --- | +| `GET` | `/status` | — | `status_current` | JSON | +| `POST` | `/set_temperature` | 正文:`f32` | `adjust_status` | JSON | +| `GET` | `/download` | — | `current_file` | 流式文件 | + +可移植程序必须保留: + +* 方法与路径选择器 +* 输入角色,例如路径、查询参数、正文、请求头与身份验证 +* 操作值 +* 输出角色,例如 JSON 或文件 +* 路由合并与嵌套 + +不应保留某个特定框架的请求、路由器或响应类型。 + +一种流畅记法可以是: + +```rust,noplayground +self.routes() + .get("/status", self.op(CurrentStatusOperation::::default()).json()) + .post("/set_temperature", self.op(AdjustStatusOperation::::default()).body::().json()) + .get("/download", self.op(CurrentFileOperation::::default()).file()) +``` + +这些流畅调用会构造一个有类型的程序,不必立即注册服务器路由。 + +## 一个程序,多种折叠解释 {#one-program-several-folds} + +同一个一阶程序可以支持多种解释: + +| 程序 | 解释 | +| --- | --- | +| 有类型的 HTTP 程序 | 文本文档、可执行路由、OpenAPI 元数据、客户端绑定、符合性测试 | +| 有类型的 JSON-RPC 程序 | 方法注册表、模式、客户端、测试框架 | + +不要为执行与文档分别维护路由或方法清单,否则会产生彼此竞争的规范。 + +## 输入与输出角色 {#input-and-output-roles} + +操作已经知道自身的参数与结果类型。传输声明只应添加传输含义。 + +```rust,noplayground +self.op(FindOperation::::default()) + .path::() + .query::() + .json() +``` + +`path`、`query`和`json`用于标识角色,不应要求作者重新声明已经由`ApplyAlg`决定的输出类型。 + +输出转换属于传输解释器。服务器可以将一种结果转换为 JSON,将另一种结果转换为流式附件。语义操作无需了解任何一种表示。 + +## 组合本身就是程序含义 {#composition-is-program-meaning} + +程序应保留通用组合操作: + +* 空程序 +* 合并程序 +* 将程序嵌套在某个前缀下 +* 将端点提升为程序 + +这些操作比某个框架的路由器方法更基础。熟悉的流畅名称,例如`get`、`post`、`merge`和`nest`,都可以作为中性代数的别名。 + +独立规范可以发布小型程序: + +| 输入程序 | 组合 | 结果 | +| --- | --- | --- | +| 状态与下载程序 | 合并 | 服务程序 | +| 目录程序 | 嵌套 | 服务程序 | + +应用程序负责选择并解释最终的组合。 + +## 宏必须展开为公开的语义结构 {#macros-must-lower-to-public-meaning} + +Rust 宏可以让一阶声明更加简洁: + +```rust,noplayground +#[ext(name = StatusApiExt, defunc(via = http))] +pub impl This +where + This: HttpApiAlg + JsonOutAlg, +{ + fn status_api(&self) + where + Alg: StatusAlg, + { + self.routes().get("/status", self.op(Alg::status_current).json()); + } +} +``` + +只有当宏展开后得到公开且可手动构造的一阶程序时,宏设计才算健全。生成的回调不应成为接口的唯一规范定义。 + +良好方向: + +1. 便捷语法 +2. 公开的操作值与程序值 +3. 泛型折叠解释 +4. 具体框架 + +表示优先的方向: + +1. 框架注解 +2. 不透明的生成回调 +3. 逆向整理的文档 + +## 与既有概念的关系 {#relation-to-existing-concepts} + +一阶接口程序建立在其他章节介绍的技术之上:去函数化是通用变换;可扩展语法与解释对应表达式问题;自由单子则是一种特定的“带顺序的语法”表示。页面顶部的“相关内容”链接可以跳转到各自章节。 + +不要把这些技术等同于指称设计本身。指称设计决定哪些结构很重要;当普通调用会抹去这些结构时,一阶表示负责保留它们。 + +## 审查要点 {#review-checks} + +* 是否有真实的第二种解释器需要将程序具体化? +* 操作是否调用作者定义的方法,而非复制其实现? +* 参数与输出是否从操作中推断得出? +* 传输语法是否只添加了传输角色? +* 程序是否可以在不使用便捷宏的情况下构造? +* 运行时与元数据是否解释同一个程序? diff --git a/src/rust-dd/interpreters.ar.md b/src/rust-dd/interpreters.ar.md new file mode 100644 index 0000000..8d90f1f --- /dev/null +++ b/src/rust-dd/interpreters.ar.md @@ -0,0 +1,193 @@ + + +# المفسرات والآثار {#interpreters-and-effects} + +```admonish tip title="ذات صلة" +المنظور الدلالي: [القوانين والتفسيرات](../denotational-design/laws-and-interpretations.md) +التصميم انطلاقًا من المعنى في Rust: [جبر القدرات](capability-algebras.md)، [القوانين والسيناريوهات والأدلة](laws.md) +المفاهيم: [الموناد الحر](../concepts/free_monad.md) +الرؤى: [جبر EVM](../insights/evm-alg.md) +``` + +```admonish note title="تمهيد" +يختار المفسر تمثيلًا أو أثرًا للقدرة. ويحقق العمليات الأولية من دون إعادة تعريف سلوك المجال المشتق فوقه، بحيث تصح القوانين نفسها عبر كل المفسرات. +``` + +يحقق المفسر قدرة دلالية بتمثيل ملموس أو أثر. وينبغي أن يختار الآليات من دون إعادة تعريف سلوك المجال. + +## مفسر خفيف {#a-thin-interpreter} + +قد يكون تمثيل الفروع بمسار من البتات كما يلي: + +```rust,noplayground +#[derive(Clone, Debug, PartialEq, Eq)] +struct BitBranch(Vec); + +struct BitBranchImpl; + +impl BranchAlg for BitBranchImpl { + type Branch = BitBranch; + + fn branch_root(&self) -> Self::Branch { + BitBranch(Vec::new()) + } + + fn branch_grow(&self, branch: &Self::Branch, direction: Direction) -> Self::Branch { + let mut grown = branch.0.clone(); + grown.push(direction); + BitBranch(grown) + } + + fn branch_path(&self, ancestor: &Self::Branch, descendant: &Self::Branch) -> Option> { + descendant.0.strip_prefix(&ancestor.0[..]).map(<[Direction]>::to_vec) + } +} +``` + +يخزن التنفيذ الوقائع الأولية ويلاحظها. وتبقى `branch_left` و`branch_right` و`branch_is_ancestor` ضمن الامتداد المشترك. + +## المفسرات نسبية إلى الحدود {#interpreters-are-boundary-relative} + +قد يكون النوع نفسه مفسرًا عند حد ومدخلًا دلاليًا عند حد آخر. + +| الحد | يستهلك | يفسر | +| --- | --- | --- | +| مهايئ نظام الملفات | الوصول إلى نظام الملفات | البحث عن المصدر | +| بيئة المُطبِّع | البحث عن المصدر بوصفه قدرة أولية | إنشاء اللغة المطبّعة | +| مسار المترجم | مصطلحات مطبّعة | إنشاء ملف تنفيذي | + +لا توجد «طبقة تنفيذ» عامة واحدة، بل حدود دلالية متداخلة. + +## الآثار عند الأطراف {#effects-at-the-edge} + +يملك المفسر الملموس خيارات من قبيل: + +* تخطيط قاعدة البيانات +* بيئة التشغيل غير المتزامنة +* ملكية المهام +* استراتيجية إعادة المحاولة +* أنواع إطار عمل HTTP أو RPC +* التسلسل +* الأقفال والقنوات +* التخزين المؤقت + +أبقِ هذه الخيارات خارج السمات الدلالية ما لم يحتج المستدعون إلى ملاحظتها. + +مثلًا، يمكن لقدرة مصدر دلالية أن تعيد قيمة مصدر وخطأً. وقد يخزّن مفسر الإنتاج الملفات مؤقتًا ويجري قراءات غير متزامنة. وقد يستخدم مفسر الاختبار خريطة غير قابلة للتعديل. ينبغي لمنطق التطبيع المشتق العمل مع كليهما. + +## ملكية بيئة التشغيل {#runtime-ownership} + +تتطلب معاودات الاتصال في الأطر غالبًا حالة مملوكة وقابلة للاستنساخ وآمنة للخيوط. وهذا قيد على المفسر وليس بالضرورة قيدًا على المجال. + +````admonish warning title="أبقِ حوامل الأطر خارج العمليات الأولية" +تجنب تلويث العملية الأولية بحوامل إطار العمل: + +```rust,noplayground +async fn status(data: FrameworkData>) -> FrameworkJson; +``` +```` + +فضّل التطبيق الدلالي: + +```rust,noplayground +trait StatusAlg { + type Status; + + async fn status(&self) -> Self::Status; +} +``` + +يمكن لمفسر الويب اختيار `Arc` واستخراج مدخلات الطلب واستدعاء `status` وتحويل النتيجة. ولا يحتاج مستدعو المجال إلى معرفة وجود خادم ويب. + +## مفسرات محايدة {#neutral-interpreters} + +لا يحتاج كل مفسر إلى تنفيذ الآثار. + +يمكن لمفسر نصي لبرنامج API تسجيل: + +| الأسلوب | المسار | المدخل | المخرج | +| --- | --- | --- | --- | +| `GET` | `/status` | — | JSON `Status` | +| `POST` | `/temperature` | JSON `f32` | JSON `Status` | + +يمكن لمفسر البيانات الوصفية إنشاء التوثيق. ويمكن لمفسر الاختبار جمع أسماء العمليات. ويمكن لمفسر الإنتاج بناء مسارات الخادم. + +تُظهر المفسرات المحايدة أن البرنامج يحمل معنى مستقلًا عن بيئة تشغيل واحدة. + +## تركيب المفسرات بالتفويض {#composing-interpreters-by-delegation} + +لأن المعنى يعيش في سمات قدرات صغيرة، يُ*ركَّب* المفسر عادةً بدلًا من كتابته كاملًا. ويكتسب الحامل قدرة بالتفويض إلى مكوّن يوفّرها مسبقًا، لذلك يُولَّد التمرير ولا يُكتب يدويًا. وتغطي صيغتان معظم الحالات. + +**مرّر القدرة إلى حقل.** يمرر `#[derive(Delegate)]` الخاص بمكتبة ambassador سمة كاملة إلى قيمة داخلية. ويفوض الحامل الذي يحتفظ بعدة مكونات كل قدرة إلى الحقل الذي يملكها، بلا أجسام تمرير: + +```rust,noplayground +#[derive(Delegate)] +#[delegate(Clock, target = "clock")] +#[delegate(Logger, target = "logger")] +struct Service { + clock: SystemClock, + logger: StdoutLogger, +} +``` + +**امنح قدرة عبر دالة getter.** أعطِ النوع دالة getter واحدة، ثم يوفر تنفيذ شامل القدرة كاملة لكل نوع يملك تلك الدالة: + +```rust,noplayground +trait Logger { + fn log(&self, message: &str); +} + +trait HasLogger { + type Logger; + + fn logger(&self) -> &Self::Logger; +} + +// Any carrier that can hand back a logger is itself a `Logger`. +impl Logger for T +where + T: HasLogger, + T::Logger: Logger, +{ + fn log(&self, message: &str) { + self.logger().log(message) + } +} +``` + +ونتيجة لذلك، لا تعود الحاجة قائمة إلى إنشاء كثير من البنى. يتحول كائن السياق أحادي البنية — سمة كبيرة تحمل عدة أنواع مرتبطة وعشرات الأساليب، إضافة إلى تنفيذها الملموس الوحيد — إلى حفنة من سمات القدرات الصغيرة وحامل خفيف يفوض كل قدرة إلى الحقل أو دالة getter التي توفرها. وتُكتب العمليات المشتقة، مثل التحقق مما إذا انقضى الموعد النهائي، مرة واحدة كامتدادات فوق العناصر الأولية بدلًا من إعادة تنفيذها في كل حامل. + +```admonish warning title="التفويض يمرر العمليات لا المعنى" +يزيل التفويض المولّد الشيفرة النمطية، لكنه لا يثبت قابلية الاستبدال الدلالي. فالماكرو `derive` مثل `#[derive(Delegate)]` في مكتبة ambassador يثبت أن التنفيذات تُترجم، لا أن الحامل يدل على المفسر نفسه. وإذا كان من المفترض أن يحل `Shared(Arc)` محل `T`، فتحقّق من القوانين على الحامل — فقد يمرر غلاف يغيّر المشاركة أو الهوية (`Arc` أو التجميع أو التخزين المؤقت) كل أسلوب على نحو صحيح، ومع ذلك يخرق قانون الجِدّة أو التفرد. وعندما لا يفعل الحامل سوى تخزين `T` بين خدمات لا صلة لها، يكون الإسقاط أصدق من التفويض. +``` + +## الأخطاء تنتمي إلى حد {#errors-belong-to-a-boundary} + +ينبغي للأخطاء أن تعبّر عن معنى الإخفاق عند الحد الذي يعالجه. + +| الخطأ | الترجمة عند الحد | +| --- | --- | +| خطأ المجال | يحوّله مفسر النقل إلى استجابة بروتوكول | +| خطأ التحليل | تحوّله واجهة المترجم الأمامية إلى تشخيص | +| خطأ التخزين | يحوّله مفسر المصدر إلى إخفاق دلالي للمصدر | + +لا تفرض رموز حالة HTTP أو كائنات أخطاء RPC أو أخطاء قاعدة البيانات على سمات المجال الأولية. ترجمها عند حدود المفسر. + +## الأداء شأن تفسيري ما لم يُلاحَظ {#performance-is-an-interpretation-concern-until-observed} + +تنتمي الدفعات والتوازي والتخزين المؤقت وتخطيط البيانات عادةً إلى المفسرات. ولا تصبح دلالية إلا عندما تضمن المواصفة ترتيبًا أو توقيتًا أو استخدامًا للموارد أو إنصافًا أو سلوك إخفاق قابلًا للملاحظة. + +يتيح هذا الفصل التحسين من دون انحراف دلالي: + +* القوانين نفسها +* الملاحظات المعلنة نفسها +* استراتيجية تشغيل مختلفة + +## فحوص المراجعة {#review-checks} + +* هل ينفذ المفسر العناصر الأولية بدلًا من تكرار الاشتقاقات؟ +* هل تُحصر قيود بيئة التشغيل وإطار العمل عند الحد المستهلك؟ +* هل يمكن لمفسر محايد أو مفسر اختبار تنفيذ القدرة نفسها؟ +* هل تُترجم أخطاء النقل والتخزين عند الطرف؟ +* هل التفويض صادق دلاليًا؟ +* هل فروق الأداء غير قابلة للملاحظة وفق الدلالة المعلنة؟ diff --git a/src/rust-dd/interpreters.de.md b/src/rust-dd/interpreters.de.md new file mode 100644 index 0000000..348c52e --- /dev/null +++ b/src/rust-dd/interpreters.de.md @@ -0,0 +1,193 @@ + + +# Interpreter und Effekte {#interpreters-and-effects} + +```admonish tip title="Verwandte Themen" +The Semantic View: [Gesetze und Interpretationen](../denotational-design/laws-and-interpretations.md) +Design by Meaning in Rust: [Capability-Algebren](capability-algebras.md), [Gesetze, Szenarien und Nachweise](laws.md) +Concepts: [Freie Monade](../concepts/free_monad.md) +Insights: [EVM-Algebra](../insights/evm-alg.md) +``` + +```admonish note title="Orientierung" +Ein Interpreter wählt eine Repräsentation oder einen Effekt für eine Capability. Er realisiert die primitiven Operationen, ohne das darüber abgeleitete Verhalten des Fachbereichs neu zu definieren, sodass dieselben Gesetze für alle Interpreter gelten. +``` + +Ein Interpreter realisiert eine semantische Capability mit einer konkreten Repräsentation oder einem Effekt. Er sollte die Mechanismen auswählen, ohne das Verhalten im Fachbereich neu zu definieren. + +## Ein schlanker Interpreter {#a-thin-interpreter} + +Eine Bitpfad-Repräsentation für Verzweigungen könnte so aussehen: + +```rust,noplayground +#[derive(Clone, Debug, PartialEq, Eq)] +struct BitBranch(Vec); + +struct BitBranchImpl; + +impl BranchAlg for BitBranchImpl { + type Branch = BitBranch; + + fn branch_root(&self) -> Self::Branch { + BitBranch(Vec::new()) + } + + fn branch_grow(&self, branch: &Self::Branch, direction: Direction) -> Self::Branch { + let mut grown = branch.0.clone(); + grown.push(direction); + BitBranch(grown) + } + + fn branch_path(&self, ancestor: &Self::Branch, descendant: &Self::Branch) -> Option> { + descendant.0.strip_prefix(&ancestor.0[..]).map(<[Direction]>::to_vec) + } +} +``` + +Die Implementierung speichert und beobachtet primitive Fakten. `branch_left`, `branch_right` und `branch_is_ancestor` bleiben in der gemeinsamen Erweiterung. + +## Interpreter gelten relativ zur Grenze {#interpreters-are-boundary-relative} + +Derselbe Typ kann an einer Grenze Interpreter und an einer anderen semantische Eingabe sein. + +| Grenze | Verbraucht | Interpretiert | +| --- | --- | --- | +| Dateisystemadapter | Dateisystemzugriff | Quelltextsuche | +| Umgebung des Normalisierers | Quelltextsuche als primitive Capability | Konstruktion der normalisierten Sprache | +| Compiler-Pipeline | Normalisierte Terme | Konstruktion des ausführbaren Programms | + +Es gibt keine einzige universelle „Implementierungsebene“. Semantische Grenzen sind ineinander verschachtelt. + +## Effekte am Rand {#effects-at-the-edge} + +Konkrete Interpreter treffen Entscheidungen über Dinge wie: + +* Datenbanklayout +* asynchrone Laufzeitumgebung +* Besitzverhältnisse von Tasks +* Wiederholungsstrategie +* Typen des HTTP- oder RPC-Frameworks +* Serialisierung +* Sperren und Kanäle +* Zwischenspeicherung + +Halte diese Entscheidungen aus semantischen Traits heraus, sofern Aufrufer sie nicht beobachten müssen. + +Eine semantische Quell-Capability kann beispielsweise einen Quellwert und einen Fehler zurückgeben. Ihr Produktionsinterpreter kann Dateien zwischenspeichern und asynchrone Lesezugriffe ausführen. Ein Testinterpreter kann eine unveränderliche Map verwenden. Abgeleitete Normalisierungslogik sollte mit beiden funktionieren. + +## Zuständigkeit der Laufzeitumgebung {#runtime-ownership} + +Framework-Callbacks benötigen oft eigenen, klonbaren und threadsicheren Zustand. Das ist eine Einschränkung des Interpreters, nicht zwingend des Fachbereichs. + +````admonish warning title="Framework-Träger aus primitiven Operationen heraushalten" +Vermeide Framework-Träger als Einschränkung einer primitiven Operation: + +```rust,noplayground +async fn status(data: FrameworkData>) -> FrameworkJson; +``` +```` + +Semantische Anwendung bevorzugen: + +```rust,noplayground +trait StatusAlg { + type Status; + + async fn status(&self) -> Self::Status; +} +``` + +Der Web-Interpreter kann `Arc` auswählen, Eingaben aus der Anfrage entnehmen, `status` aufrufen und das Ergebnis umwandeln. Nutzer des Fachbereichs müssen nichts von einem Webserver wissen. + +## Neutrale Interpreter {#neutral-interpreters} + +Nicht jeder Interpreter muss Effekte ausführen. + +Ein Text-Interpreter für ein API-Programm kann Folgendes festhalten: + +| Methode | Pfad | Eingabe | Ausgabe | +| --- | --- | --- | --- | +| `GET` | `/status` | — | JSON `Status` | +| `POST` | `/temperature` | JSON `f32` | JSON `Status` | + +Ein Metadaten-Interpreter kann Dokumentation erstellen. Ein Testinterpreter kann Operationsnamen sammeln. Ein Produktionsinterpreter kann Serverrouten aufbauen. + +Neutrale Interpreter zeigen, dass das Programm unabhängig von einer einzelnen Laufzeit Bedeutung trägt. + +## Interpreter durch Delegation zusammensetzen {#composing-interpreters-by-delegation} + +Da die Bedeutung in kleinen Capability-Traits liegt, wird ein Interpreter normalerweise *zusammengesetzt* statt vollständig ausgeschrieben. Ein Träger erhält eine Capability, indem er an einen bereits verfügbaren Anbieter delegiert. Die Weiterleitung wird also generiert und nicht von Hand geschrieben. Fast alle Fälle decken zwei Formen ab. + +**Eine Capability an ein Feld weiterleiten.** Das `#[derive(Delegate)]` von ambassador leitet ein ganzes Trait an einen inneren Wert weiter. Ein Träger mit mehreren Komponenten delegiert jede Capability an das Feld, dem sie gehört, ganz ohne eigens geschriebene Weiterleitungsmethoden: + +```rust,noplayground +#[derive(Delegate)] +#[delegate(Clock, target = "clock")] +#[delegate(Logger, target = "logger")] +struct Service { + clock: SystemClock, + logger: StdoutLogger, +} +``` + +**Eine Capability über einen Getter bereitstellen.** Gib einem Typ einen Getter, und eine pauschale Implementierung stellt allen Typen mit diesem Getter die gesamte Capability bereit: + +```rust,noplayground +trait Logger { + fn log(&self, message: &str); +} + +trait HasLogger { + type Logger; + + fn logger(&self) -> &Self::Logger; +} + +// Any carrier that can hand back a logger is itself a `Logger`. +impl Logger for T +where + T: HasLogger, + T::Logger: Logger, +{ + fn log(&self, message: &str) { + self.logger().log(message) + } +} +``` + +Dadurch müssen viele Strukturen gar nicht erst existieren. Ein monolithisches Kontextobjekt — ein großes Trait mit mehreren assoziierten Typen und einem Dutzend Methoden samt seiner einzigen konkreten Implementierung — wird durch eine Handvoll kleiner Capability-Traits und einen schlanken Träger ersetzt, der jede Capability an das zuständige Feld oder den Getter weiterleitet. Abgeleitete Operationen, etwa die Prüfung, ob eine Frist abgelaufen ist, werden einmal als Erweiterungen der primitiven Operationen formuliert, statt für jeden Träger neu implementiert zu werden. + +```admonish warning title="Delegation leitet Operationen, nicht Bedeutung weiter" +Generierte Delegation erspart Boilerplate, begründet aber keine semantische Ersetzbarkeit. Ein `derive`\-Makro wie `#[derive(Delegate)]` von ambassador beweist, dass die Implementierungen kompilieren, nicht dass der Träger denselben Interpreter bezeichnet. Soll `Shared(Arc)` für `T` stehen, prüfe die Gesetze für den Träger: Ein Wrapper, der Teilen oder Identität verändert (`Arc`, Pooling, Caching), kann jede Methode korrekt weiterleiten und trotzdem ein Frische- oder Eindeutigkeitsgesetz verletzen. Enthält der Träger lediglich `T` neben unabhängigen Diensten, ist Projektion ehrlicher als Delegation. +``` + +## Fehler gehören zu einer Grenze {#errors-belong-to-a-boundary} + +Fehler sollten die Bedeutung des Scheiterns an der Grenze vermitteln, an der es behandelt wird. + +| Fehler | Übersetzung an der Grenze | +| --- | --- | +| Fachlicher Fehler | Der Transport-Interpreter bildet ihn auf eine Protokollantwort ab | +| Parserfehler | Das Compiler-Frontend bildet ihn auf eine Diagnose ab | +| Speicherfehler | Der Quellinterpreter bildet ihn auf einen semantischen Quellfehler ab | + +Zwinge keine HTTP-Statuscodes, RPC-Fehlerobjekte oder Datenbankfehler in primitive Traits des Fachbereichs. Übersetze sie an den Interpretergrenzen. + +## Leistung ist Sache der Interpretation, solange sie nicht beobachtet wird {#performance-is-an-interpretation-concern-until-observed} + +Batchverarbeitung, Parallelität, Zwischenspeicherung und Datenlayout gehören normalerweise zu den Interpretern. Sie werden erst dann semantisch, wenn die Spezifikation beobachtbare Reihenfolge, Timing, Ressourcenverbrauch, Fairness oder Fehlerverhalten garantiert. + +Diese Trennung ermöglicht Optimierungen ohne semantische Abweichung: + +* Dieselben Gesetze +* Dieselben deklarierten Beobachtungen +* Andere operationale Strategie + +## Prüfpunkte für das Review {#review-checks} + +* Implementiert der Interpreter primitive Operationen, statt Ableitungen zu duplizieren? +* Sind Einschränkungen durch Laufzeit und Framework auf die verwendende Grenze beschränkt? +* Könnte ein neutraler oder Testinterpreter dieselbe Capability implementieren? +* Werden Transport- und Speicherfehler am Rand übersetzt? +* Ist die Delegation semantisch zutreffend? +* Sind Leistungsunterschiede unter der angegebenen Denotation unbeobachtbar? diff --git a/src/rust-dd/interpreters.es.md b/src/rust-dd/interpreters.es.md new file mode 100644 index 0000000..c51016c --- /dev/null +++ b/src/rust-dd/interpreters.es.md @@ -0,0 +1,193 @@ + + +# Intérpretes y efectos {#interpreters-and-effects} + +```admonish tip title="Relacionado" +La perspectiva semántica: [Leyes e interpretaciones](../denotational-design/laws-and-interpretations.md) +Diseño por significado en Rust: [Álgebras de capacidades](capability-algebras.md), [Leyes, escenarios y evidencia](laws.md) +Conceptos: [Mónada libre](../concepts/free_monad.md) +Perspectivas: [Álgebra de EVM](../insights/evm-alg.md) +``` + +```admonish note title="Orientación" +Un intérprete elige una representación o efecto para una capacidad. Realiza las operaciones primitivas sin redefinir el comportamiento del dominio derivado por encima de ella, de modo que se mantienen las mismas leyes en todos los intérpretes. +``` + +Un intérprete realiza una capacidad semántica mediante una representación o efecto concreto. Debe elegir los mecanismos sin redefinir el comportamiento del dominio. + +## Un intérprete ligero {#a-thin-interpreter} + +Una representación de ramas mediante rutas de bits podría ser: + +```rust,noplayground +#[derive(Clone, Debug, PartialEq, Eq)] +struct BitBranch(Vec); + +struct BitBranchImpl; + +impl BranchAlg for BitBranchImpl { + type Branch = BitBranch; + + fn branch_root(&self) -> Self::Branch { + BitBranch(Vec::new()) + } + + fn branch_grow(&self, branch: &Self::Branch, direction: Direction) -> Self::Branch { + let mut grown = branch.0.clone(); + grown.push(direction); + BitBranch(grown) + } + + fn branch_path(&self, ancestor: &Self::Branch, descendant: &Self::Branch) -> Option> { + descendant.0.strip_prefix(&ancestor.0[..]).map(<[Direction]>::to_vec) + } +} +``` + +La implementación almacena y observa hechos primitivos. `branch_left`, `branch_right` y `branch_is_ancestor` siguen en la extensión compartida. + +## Los intérpretes son relativos al límite {#interpreters-are-boundary-relative} + +El mismo tipo puede ser un intérprete en un límite y una entrada semántica en otro. + +| Límite | Consume | Interpreta | +| --- | --- | --- | +| Adaptador del sistema de archivos | Acceso al sistema de archivos | Búsqueda de código fuente | +| Entorno de normalización | Búsqueda de código fuente como capacidad primitiva | Construcción del lenguaje normalizado | +| Canalización del compilador | Términos normalizados | Construcción del ejecutable | + +No existe una única «capa de implementación» universal. Hay límites semánticos anidados. + +## Efectos en el borde {#effects-at-the-edge} + +Los intérpretes concretos son dueños de elecciones como: + +* disposición de base de datos +* entorno de ejecución asíncrono +* propiedad de tareas +* estrategia de reintentos +* tipos del framework HTTP o RPC +* serialización +* bloqueos y canales +* caché + +Mantén estas elecciones fuera de los traits semánticos, a menos que los llamadores necesiten observarlas. + +Por ejemplo, una capacidad semántica de fuente puede devolver un valor de código fuente y un error. Su intérprete de producción puede almacenar archivos en caché y realizar lecturas asíncronas. Un intérprete de pruebas puede usar un mapa inmutable. La lógica de normalización derivada debería funcionar con ambos. + +## Propiedad del entorno de ejecución {#runtime-ownership} + +Los callbacks de un framework suelen exigir un estado propio, clonable y seguro entre hilos. Esa es una restricción del intérprete, no necesariamente del dominio. + +````admonish warning title="Mantén los portadores del framework fuera de las primitivas" +Evita contaminar una operación primitiva con portadores del framework: + +```rust,noplayground +async fn status(data: FrameworkData>) -> FrameworkJson; +``` +```` + +Prefiere la aplicación semántica: + +```rust,noplayground +trait StatusAlg { + type Status; + + async fn status(&self) -> Self::Status; +} +``` + +El intérprete web puede elegir `Arc`, extraer las entradas de la petición, llamar a `status` y convertir el resultado. Los llamadores del dominio no necesitan saber que existe un servidor web. + +## Intérpretes neutrales {#neutral-interpreters} + +No todos los intérpretes necesitan ejecutar efectos. + +Un intérprete textual para un programa de API puede registrar: + +| Método | Ruta | Entrada | Salida | +| --- | --- | --- | --- | +| `GET` | `/status` | — | JSON `Status` | +| `POST` | `/temperature` | JSON `f32` | JSON `Status` | + +Un intérprete de metadatos puede generar documentación. Uno de pruebas puede recopilar nombres de operaciones. Uno de producción puede construir rutas de servidor. + +Los intérpretes neutrales demuestran que el programa porta significado independientemente de un entorno de ejecución concreto. + +## Componer intérpretes mediante delegación {#composing-interpreters-by-delegation} + +Como el significado reside en traits de capacidad pequeños, un intérprete suele *ensamblarse* en vez de escribirse por completo. Un portador adquiere una capacidad delegando en quien ya la proporciona; así, el reenvío se genera en lugar de escribirse a mano. Dos formas cubren casi todos los casos. + +**Reenvía una capacidad a un campo.** La macro `#[derive(Delegate)]` de ambassador reenvía un trait completo a un valor interno. Un portador que contiene varios componentes delega cada capacidad al campo que la posee, sin cuerpos de reenvío: + +```rust,noplayground +#[derive(Delegate)] +#[delegate(Clock, target = "clock")] +#[delegate(Logger, target = "logger")] +struct Service { + clock: SystemClock, + logger: StdoutLogger, +} +``` + +**Concede una capacidad mediante un getter.** Proporciona un getter a un tipo y una implementación general concederá toda la capacidad a cada tipo que tenga ese getter: + +```rust,noplayground +trait Logger { + fn log(&self, message: &str); +} + +trait HasLogger { + type Logger; + + fn logger(&self) -> &Self::Logger; +} + +// Any carrier that can hand back a logger is itself a `Logger`. +impl Logger for T +where + T: HasLogger, + T::Logger: Logger, +{ + fn log(&self, message: &str) { + self.logger().log(message) + } +} +``` + +La consecuencia es que muchos structs ni siquiera necesitan existir. Un objeto de contexto monolítico —un trait grande con varios tipos asociados y una docena de métodos, además de su única implementación concreta— se convierte en un puñado de traits de capacidad pequeños y un portador ligero que delega cada uno al campo o getter que lo proporciona. Las operaciones derivadas, como comprobar si ha vencido un plazo, se escriben una vez como extensiones de las primitivas, en lugar de volver a implementarse en cada portador. + +```admonish warning title="La delegación reenvía operaciones, no significado" +La delegación generada elimina código repetitivo, pero no establece la sustituibilidad semántica. Un macro `derive` como `#[derive(Delegate)]` de ambassador demuestra que las implementaciones compilan, no que el portador denote el mismo intérprete. Si `Shared(Arc)` debe sustituir a `T`, comprueba las leyes en el portador: un envoltorio que cambia la compartición o identidad (`Arc`, agrupación, caché) puede reenviar todos los métodos correctamente y aun así infringir una ley de frescura o unicidad. Si el portador solo almacena `T` junto a servicios no relacionados, la proyección es más honesta que la delegación. +``` + +## Los errores pertenecen a un límite {#errors-belong-to-a-boundary} + +Los errores deben comunicar el significado del fallo en el límite que los gestiona. + +| Error | Traducción en el límite | +| --- | --- | +| Error del dominio | El intérprete de transporte lo convierte en una respuesta del protocolo | +| Error de análisis sintáctico | El front-end del compilador lo convierte en un diagnóstico | +| Error de almacenamiento | El intérprete de fuente lo convierte en un fallo semántico de fuente | + +No fuerces códigos de estado HTTP, objetos de error RPC ni errores de base de datos dentro de traits primitivos del dominio. Tradúcelos en los límites de los intérpretes. + +## El rendimiento es una cuestión de interpretación hasta que se observa {#performance-is-an-interpretation-concern-until-observed} + +El procesamiento por lotes, el paralelismo, la caché y la disposición de datos suelen pertenecer a los intérpretes. Solo se vuelven semánticos cuando la especificación promete orden, temporización, uso de recursos, equidad o comportamiento ante fallos observables. + +Esta separación permite optimizar sin desviación semántica: + +* Mismas leyes +* Mismas observaciones declaradas +* Distinta estrategia operacional + +## Comprobaciones de revisión {#review-checks} + +* ¿El intérprete implementa las primitivas en lugar de duplicar las derivaciones? +* ¿Las restricciones del entorno de ejecución y del framework quedan confinadas al límite consumidor? +* ¿Podría un intérprete neutral o de pruebas implementar la misma capacidad? +* ¿Los errores de transporte y almacenamiento se traducen en el borde? +* ¿La delegación es veraz semánticamente? +* ¿Las diferencias de rendimiento son inobservables según la denotación declarada? diff --git a/src/rust-dd/interpreters.ja.md b/src/rust-dd/interpreters.ja.md new file mode 100644 index 0000000..84f32de --- /dev/null +++ b/src/rust-dd/interpreters.ja.md @@ -0,0 +1,193 @@ + + +# インタープリターと副作用 {#interpreters-and-effects} + +```admonish tip title="関連項目" +意味論的な見方:[法則と解釈](../denotational-design/laws-and-interpretations.md) +Rustで意味から設計する:[ケイパビリティ代数](capability-algebras.md)、[法則、シナリオ、証拠](laws.md) +概念:[自由モナド](../concepts/free_monad.md) +洞察:[EVM代数](../insights/evm-alg.md) +``` + +```admonish note title="概要" +インタープリターは、ケイパビリティに対する表現または副作用を選びます。領域の振る舞いを再定義せずに基本操作を実現するため、その上にある導出の法則はすべてのインタープリターで成り立ちます。 +``` + +インタープリターは、意味論的ケイパビリティを具体的な表現または副作用によって実現します。領域の振る舞いを再定義せずに仕組みを選ぶべきです。 + +## 薄いインタープリター {#a-thin-interpreter} + +分岐をビット経路で表現する例: + +```rust,noplayground +#[derive(Clone, Debug, PartialEq, Eq)] +struct BitBranch(Vec); + +struct BitBranchImpl; + +impl BranchAlg for BitBranchImpl { + type Branch = BitBranch; + + fn branch_root(&self) -> Self::Branch { + BitBranch(Vec::new()) + } + + fn branch_grow(&self, branch: &Self::Branch, direction: Direction) -> Self::Branch { + let mut grown = branch.0.clone(); + grown.push(direction); + BitBranch(grown) + } + + fn branch_path(&self, ancestor: &Self::Branch, descendant: &Self::Branch) -> Option> { + descendant.0.strip_prefix(&ancestor.0[..]).map(<[Direction]>::to_vec) + } +} +``` + +実装は基本的な事実を格納して観測します。`branch_left`、`branch_right`、`branch_is_ancestor`は引き続き共有拡張に置きます。 + +## インタープリターは境界によって変わる {#interpreters-are-boundary-relative} + +同じ型が、ある境界ではインタープリターになり、別の境界では意味論上の入力になることがあります。 + +| 境界 | 利用するもの | 解釈するもの | +| --- | --- | --- | +| ファイルシステムアダプター | ファイルシステムへのアクセス | ソース検索 | +| 正規化環境 | 基本的なケイパビリティとしてのソース検索 | 正規化された言語の構築 | +| コンパイラーパイプライン | 正規化された項 | 実行可能な形式の構築 | + +万能な「実装層」はありません。意味論上の境界が入れ子になっています。 + +## 境界で副作用を扱う {#effects-at-the-edge} + +具体的なインタープリターは、次のような選択を担います。 + +* データベースのレイアウト +* 非同期ランタイム +* タスクの所有関係 +* 再試行戦略 +* HTTPまたはRPCフレームワークの型 +* シリアライズ +* ロックとチャネル +* キャッシュ + +呼び出し側が観測する必要のない限り、これらの選択を意味論的なトレイトに含めないでください。 + +たとえば、意味論上のソースケイパビリティは、ソース値とエラーを返せます。本番インタープリターはファイルをキャッシュし、非同期に読み込むかもしれません。テスト用インタープリターは不変マップを使うかもしれません。導出された正規化ロジックは両方で動作するべきです。 + +## ランタイムの所有関係 {#runtime-ownership} + +フレームワークのコールバックでは、状態の所有、複製可能性、スレッド安全性が要求されることがよくあります。それはインタープリター上の制約であり、必ずしも領域上の制約ではありません。 + +````admonish warning title="基本操作にフレームワークの担体を混ぜない" +基本操作をフレームワークの担体で汚染しないでください。 + +```rust,noplayground +async fn status(data: FrameworkData>) -> FrameworkJson; +``` +```` + +意味論的なアプリケーション処理を優先する + +```rust,noplayground +trait StatusAlg { + type Status; + + async fn status(&self) -> Self::Status; +} +``` + +Webインタープリターは`Arc`を選び、リクエストの入力を取り出し、`status`を呼び出して結果を変換できます。領域の利用側は、Webサーバーの存在を知る必要がありません。 + +## 中立的なインタープリター {#neutral-interpreters} + +すべてのインタープリターが副作用を実行する必要はありません。 + +APIプログラム用のテキストインタープリターは、次を記録できます。 + +| メソッド | パス | 入力 | 出力 | +| --- | --- | --- | --- | +| `GET` | `/status` | — | JSON `Status` | +| `POST` | `/temperature` | JSON `f32` | JSON `Status` | + +メタデータインタープリターはドキュメントを構築できます。テスト用インタープリターは操作名を集められます。本番インタープリターはサーバールートを構築できます。 + +中立的なインタープリターを使うと、プログラムが一つのランタイムに依存せず意味を持つことを示せます。 + +## 委譲によるインタープリターの合成 {#composing-interpreters-by-delegation} + +意味が小さなケイパビリティトレイトに置かれているため、インタープリターは通常、*部品を組み立てて*作り、各部を個別に記述しません。担体は、すでにケイパビリティを提供するものへ委譲することで、そのケイパビリティを得ます。転送コードは手書きせず生成します。ほぼすべてのケースを二つの形式で扱えます。 + +**フィールドへケイパビリティを転送する。** ambassadorの`#[derive(Delegate)]`はトレイト全体を内部値へ転送します。複数のコンポーネントを保持する担体では、各ケイパビリティをそれを所有するフィールドへ委譲し、転送用の本体を一切書かずに済みます。 + +```rust,noplayground +#[derive(Delegate)] +#[delegate(Clock, target = "clock")] +#[delegate(Logger, target = "logger")] +struct Service { + clock: SystemClock, + logger: StdoutLogger, +} +``` + +getterを介してケイパビリティを与える。型にgetterを一つ持たせると、そのgetterを持つすべての型に包括実装でケイパビリティ全体を与えられます。 + +```rust,noplayground +trait Logger { + fn log(&self, message: &str); +} + +trait HasLogger { + type Logger; + + fn logger(&self) -> &Self::Logger; +} + +// Any carrier that can hand back a logger is itself a `Logger`. +impl Logger for T +where + T: HasLogger, + T::Logger: Logger, +{ + fn log(&self, message: &str) { + self.logger().log(message) + } +} +``` + +その結果、多くの構造体が不要になります。関連型と十数個のメソッドを持つ大きなトレイト一つと、その唯一の具体実装からなる一枚岩のコンテキストオブジェクトは、小さなケイパビリティトレイト群と、提供元のフィールドまたはgetterへ個別に委譲する薄い担体に置き換えられます。期限を過ぎたか調べるなどの導出操作は、担体ごとに再実装せず、基本操作を使う拡張として一度だけ記述します。 + +```admonish warning title="委譲は操作を転送するもので、意味を転送するのではない" +委譲を生成すれば定型コードをなくせますが、意味論的に代用可能であるとは限りません。ambassadorの`derive`のような`#[derive(Delegate)]`マクロが証明するのは、実装がコンパイルされることだけであり、その担体が同じインタープリターを表すことではありません。`Shared(Arc)`が`T`の代わりになるなら、担体上で法則を検査します。共有や同一性を変えるラッパー(`Arc`、プーリング、キャッシュ)は、すべてのメソッドを正しく転送していても、新鮮さや一意性に関する法則に違反することがあります。担体が無関係なサービスの一つとして`T`を格納するだけなら、委譲より射影のほうが実態に即しています。 +``` + +## エラーは境界に属する {#errors-belong-to-a-boundary} + +エラーは、それを処理する境界で失敗の意味を伝えるべきです。 + +| エラー | 境界での変換 | +| --- | --- | +| 領域エラー | 通信インタープリターがプロトコル応答に変換する | +| 解析エラー | コンパイラーのフロントエンドが診断に変換する | +| 格納エラー | ソースインタープリターが意味論上のソース取得失敗に変換する | + +HTTPステータスコード、RPCエラーオブジェクト、データベースエラーを基本領域トレイトに押し込まないでください。インタープリターの境界で変換します。 + +## 観測されない限り、性能は解釈上の課題 {#performance-is-an-interpretation-concern-until-observed} + +バッチ処理、並列化、キャッシュ、データレイアウトは通常、インタープリターに属します。仕様が順序、時間、リソース使用、公平性、失敗の振る舞いを観測可能な形で保証する場合に限り、意味論上の要件になります。 + +この分離により、意味を変えずに最適化できます。 + +* 同じ法則 +* 同じ宣言済みの観測 +* 異なる操作戦略 + +## レビュー時の確認 {#review-checks} + +* インタープリターは導出を重複させず基本操作を実装しているか。 +* ランタイムとフレームワークの制約を、利用する境界に限定しているか。 +* 中立的なインタープリターやテスト用インタープリターで、同じケイパビリティを実装できるか。 +* 通信と格納のエラーを境界で変換しているか。 +* 委譲は意味論上も正確か。 +* 述べられた表示のもとで、性能差は観測できないものか。 diff --git a/src/rust-dd/interpreters.ko.md b/src/rust-dd/interpreters.ko.md new file mode 100644 index 0000000..36509df --- /dev/null +++ b/src/rust-dd/interpreters.ko.md @@ -0,0 +1,193 @@ + + +# 인터프리터와 효과 {#interpreters-and-effects} + +```admonish tip title="관련 항목" +의미론적 관점: [법칙과 해석](../denotational-design/laws-and-interpretations.md) +Rust에서 의미로 설계하기: [케이퍼빌리티 대수](capability-algebras.md), [법칙, 시나리오, 증거](laws.md) +개념: [자유 모나드](../concepts/free_monad.md) +통찰: [EVM 대수](../insights/evm-alg.md) +``` + +```admonish note title="개요" +인터프리터는 케이퍼빌리티의 표현이나 효과를 선택합니다. 위에서 도출한 영역 동작을 다시 정의하지 않고 기본 연산을 실현하므로, 모든 인터프리터에서 같은 법칙이 성립합니다. +``` + +인터프리터는 구체적인 표현이나 효과로 의미론적 케이퍼빌리티를 실현합니다. 영역 동작을 다시 정의하지 않고 구현 장치를 선택해야 합니다. + +## 얇은 인터프리터 {#a-thin-interpreter} + +비트 경로 분기 표현은 다음과 같을 수 있습니다: + +```rust,noplayground +#[derive(Clone, Debug, PartialEq, Eq)] +struct BitBranch(Vec); + +struct BitBranchImpl; + +impl BranchAlg for BitBranchImpl { + type Branch = BitBranch; + + fn branch_root(&self) -> Self::Branch { + BitBranch(Vec::new()) + } + + fn branch_grow(&self, branch: &Self::Branch, direction: Direction) -> Self::Branch { + let mut grown = branch.0.clone(); + grown.push(direction); + BitBranch(grown) + } + + fn branch_path(&self, ancestor: &Self::Branch, descendant: &Self::Branch) -> Option> { + descendant.0.strip_prefix(&ancestor.0[..]).map(<[Direction]>::to_vec) + } +} +``` + +구현은 기본 사실을 저장하고 관찰합니다. `branch_left`, `branch_right`, `branch_is_ancestor`는 공유 확장에 남습니다. + +## 인터프리터의 경계는 상대적입니다 {#interpreters-are-boundary-relative} + +같은 타입이 한 경계에서는 인터프리터이고 다른 경계에서는 의미 입력일 수 있습니다. + +| 경계 | 사용하는 것 | 해석하는 것 | +| --- | --- | --- | +| 파일시스템 어댑터 | 파일시스템 접근 | 소스 조회 | +| 정규화기 환경 | 기본 케이퍼빌리티로서의 소스 조회 | 정규화 언어 구성 | +| 컴파일러 파이프라인 | 정규화된 항 | 실행 가능 구성 | + +보편적인 “구현 계층” 하나는 없습니다. 서로 중첩된 의미론적 경계가 있습니다. + +## 경계에서 처리하는 효과 {#effects-at-the-edge} + +구체 인터프리터는 다음과 같은 선택을 담당합니다: + +* 데이터베이스 레이아웃 +* 비동기 런타임 +* 태스크 소유권 +* 재시도 전략 +* HTTP 또는 RPC 프레임워크 타입 +* 직렬화 +* 락과 채널 +* 캐싱 + +호출자가 관찰해야 하는 구분이 아니라면 이런 선택은 의미론적 트레이트에 넣지 마세요. + +예를 들어 의미론적 소스 케이퍼빌리티는 소스 값과 오류를 반환할 수 있습니다. 운영 인터프리터는 파일을 캐시하고 비동기 읽기를 수행할 수 있고, 테스트 인터프리터는 변경 불가능한 맵을 사용할 수 있습니다. 파생된 정규화 로직은 둘 다에서 작동해야 합니다. + +## 런타임 소유권 {#runtime-ownership} + +프레임워크 콜백에는 소유 가능하고 복제할 수 있으며 스레드 안전한 상태가 필요한 경우가 많습니다. 이는 반드시 도메인 제약일 필요는 없으며 인터프리터 제약입니다. + +````admonish warning title="프레임워크 기반 집합은 기본 연산에 넣지 마세요" +기본 연산에 프레임워크 기반 집합이 섞이지 않게 하세요: + +```rust,noplayground +async fn status(data: FrameworkData>) -> FrameworkJson; +``` +```` + +의미론적 애플리케이션을 사용하세요: + +```rust,noplayground +trait StatusAlg { + type Status; + + async fn status(&self) -> Self::Status; +} +``` + +웹 인터프리터는 `Arc`를 선택하고 요청 입력을 추출해 `status`를 호출한 뒤 결과를 변환할 수 있습니다. 도메인 호출자는 웹 서버의 존재를 알 필요가 없습니다. + +## 중립적인 인터프리터 {#neutral-interpreters} + +모든 인터프리터가 효과를 실행해야 하는 것은 아닙니다. + +API 프로그램의 텍스트 인터프리터는 다음을 기록할 수 있습니다: + +| 메서드 | 경로 | 입력 | 출력 | +| --- | --- | --- | --- | +| `GET` | `/status` | — | JSON `Status` | +| `POST` | `/temperature` | JSON `f32` | JSON `Status` | + +메타데이터 인터프리터는 문서를 만들 수 있습니다. 테스트 인터프리터는 연산 이름을 모을 수 있고, 운영 인터프리터는 서버 경로를 만들 수 있습니다. + +중립적인 인터프리터는 프로그램이 특정 런타임과 독립적으로 의미를 담고 있음을 보여 줍니다. + +## 위임으로 인터프리터 합성하기 {#composing-interpreters-by-delegation} + +의미가 작은 케이퍼빌리티 트레이트에 있으므로 인터프리터는 보통 직접 *작성하기보다* 조립합니다. 이미 케이퍼빌리티를 제공하는 구성 요소에 위임해 기반 집합이 해당 케이퍼빌리티를 얻으므로 전달 코드가 자동 생성되고 직접 작성할 필요가 없습니다. 대부분의 경우 두 가지 형식이면 충분합니다. + +**케이퍼빌리티를 필드로 전달합니다.** ambassador의 `#[derive(Delegate)]`는 전체 트레이트를 내부 값에 전달합니다. 여러 구성 요소를 보유한 기반 타입은 전달 메서드를 직접 쓰지 않고 각 케이퍼빌리티를 담당 필드에 위임합니다: + +```rust,noplayground +#[derive(Delegate)] +#[delegate(Clock, target = "clock")] +#[delegate(Logger, target = "logger")] +struct Service { + clock: SystemClock, + logger: StdoutLogger, +} +``` + +**게터를 통해 케이퍼빌리티를 부여합니다.** 타입에 게터 하나를 제공하면 포괄 구현이 그 게터를 가진 모든 타입에 전체 케이퍼빌리티를 제공합니다: + +```rust,noplayground +trait Logger { + fn log(&self, message: &str); +} + +trait HasLogger { + type Logger; + + fn logger(&self) -> &Self::Logger; +} + +// Any carrier that can hand back a logger is itself a `Logger`. +impl Logger for T +where + T: HasLogger, + T::Logger: Logger, +{ + fn log(&self, message: &str) { + self.logger().log(message) + } +} +``` + +그 결과 많은 구조체를 만들 필요가 없어집니다. 연관 타입 여러 개와 메서드 십여 개가 있는 큰 트레이트 하나 및 이를 구현하는 구체 타입 하나로 이루어진 단일 컨텍스트 객체 대신, 작은 케이퍼빌리티 트레이트 몇 개와 각각을 제공하는 필드나 게터에 위임하는 얇은 기반 타입만 있으면 됩니다. 기한이 지났는지 확인하는 파생 연산은 각 기반 타입에서 다시 구현하지 않고 기본 연산을 확장해 한 번만 작성합니다. + +```admonish warning title="위임은 의미가 아니라 연산을 전달합니다" +자동 생성된 위임은 상용구를 없애지만 의미론적 대체 가능성을 보장하지 않습니다. ambassador의 `derive` 매크로 `#[derive(Delegate)]`는 구현이 컴파일됨을 확인할 뿐, 기반 타입이 같은 인터프리터를 나타내는지는 증명하지 않습니다. `Shared(Arc)`가 `T`을 대신하려면 기반 타입에서 법칙을 확인하세요. 공유 방식이나 정체성을 바꾸는 래퍼(`Arc`, 풀링, 캐싱)는 모든 메서드를 올바르게 전달하면서도 최신성 또는 유일성 법칙을 위반할 수 있습니다. 기반 타입이 관련 없는 서비스 중 `T`만 보유한다면 위임보다 투영이 더 정확합니다. +``` + +## 오류는 경계에 속합니다 {#errors-belong-to-a-boundary} + +오류는 이를 처리하는 경계의 실패 의미를 전달해야 합니다. + +| 오류 | 경계 간 변환 | +| --- | --- | +| 도메인 오류 | 전송 인터프리터가 이를 프로토콜 응답으로 변환합니다 | +| 파싱 오류 | 컴파일러 프런트엔드가 이를 진단 정보로 변환합니다 | +| 저장소 오류 | 소스 인터프리터가 이를 의미론적 소스 실패로 변환합니다 | + +HTTP 상태 코드, RPC 오류 객체, 데이터베이스 오류를 기본 도메인 트레이트에 억지로 넣지 마세요. 인터프리터 경계에서 변환하세요. + +## 관찰되기 전까지 성능은 해석의 문제입니다 {#performance-is-an-interpretation-concern-until-observed} + +일괄 처리, 병렬성, 캐싱, 데이터 배치는 대개 인터프리터에 속합니다. 명세가 관찰 가능한 순서, 시간, 자원 사용, 공정성, 실패 동작을 보장할 때에만 의미론적 요소가 됩니다. + +이 구분을 통해 의미가 변하지 않게 최적화할 수 있습니다: + +* 같은 법칙 +* 같은 선언된 관찰 +* 다른 작동 전략 + +## 검토 항목 {#review-checks} + +* 인터프리터가 파생을 중복하지 않고 기본 연산을 구현하나요? +* 런타임 및 프레임워크 제약이 사용하는 경계에만 머무르나요? +* 중립 인터프리터나 테스트 인터프리터도 같은 케이퍼빌리티를 구현할 수 있나요? +* 전송 및 저장소 오류를 경계에서 변환하나요? +* 위임이 의미론적으로 정확한가요? +* 명시된 표시에 따라 성능 차이를 관찰할 수 없나요? diff --git a/src/rust-dd/interpreters.md b/src/rust-dd/interpreters.md index e611032..0c2ab19 100644 --- a/src/rust-dd/interpreters.md +++ b/src/rust-dd/interpreters.md @@ -112,17 +112,52 @@ A metadata interpreter can construct documentation. A test interpreter can colle Neutral interpreters demonstrate that the program carries meaning independently of one runtime. -## Adapters and delegation +## Composing interpreters by delegation -Concrete wrappers often forward capabilities: +Because meaning lives in small capability traits, an interpreter is usually *assembled* rather than written out. A carrier gains a capability by delegating to whatever already provides it, so the forwarding is generated, not hand-written. Two forms cover almost everything. + +**Forward a capability to a field.** ambassador's `#[derive(Delegate)]` forwards a whole trait to an inner value. A carrier that holds several components delegates each capability to the field that owns it, with no forwarding bodies: ```rust,noplayground -struct Shared(Arc); +#[derive(Delegate)] +#[delegate(Clock, target = "clock")] +#[delegate(Logger, target = "logger")] +struct Service { + clock: SystemClock, + logger: StdoutLogger, +} +``` + +**Grant a capability through a getter.** Give a type one getter, and a blanket impl supplies the whole capability to every type that has that getter: + +```rust,noplayground +trait Logger { + fn log(&self, message: &str); +} + +trait HasLogger { + type Logger; + + fn logger(&self) -> &Self::Logger; +} + +// Any carrier that can hand back a logger is itself a `Logger`. +impl Logger for T +where + T: HasLogger, + T::Logger: Logger, +{ + fn log(&self, message: &str) { + self.logger().log(message) + } +} ``` -If `Shared` truthfully behaves as the same interpreter as `T`, delegation is appropriate. If a larger environment merely stores `T` among unrelated services, projection is more honest. +The consequence is that many structs never need to exist. A monolithic context object — one large trait carrying several associated types and a dozen methods, plus its single concrete implementation — becomes a handful of small capability traits and a thin carrier that delegates each to the field or getter that provides it. Derived operations, such as checking whether a deadline has passed, are written once as extensions over the primitives rather than re-implemented on each carrier. -Generated delegation removes boilerplate but does not establish semantic substitutability. Review the claim before applying the macro. +```admonish warning title="Delegation forwards operations, not meaning" +Generated delegation removes boilerplate but does not establish semantic substitutability. A `derive` macro such as ambassador's `#[derive(Delegate)]` proves the impls compile, not that the carrier denotes the same interpreter. If `Shared(Arc)` is to stand in for `T`, check the laws on the carrier — a wrapper that changes sharing or identity (`Arc`, pooling, caching) can forward every method correctly and still break a freshness or uniqueness law. When the carrier merely stores `T` among unrelated services, projection is more honest than delegation. +``` ## Errors belong to a boundary diff --git a/src/rust-dd/interpreters.ru.md b/src/rust-dd/interpreters.ru.md new file mode 100644 index 0000000..57af473 --- /dev/null +++ b/src/rust-dd/interpreters.ru.md @@ -0,0 +1,193 @@ + + +# Интерпретаторы и эффекты {#interpreters-and-effects} + +```admonish tip title="Связанные материалы" +«Семантический взгляд»: [Законы и интерпретации](../denotational-design/laws-and-interpretations.md) +«Проектирование на основе смысла в Rust»: [Алгебры возможностей](capability-algebras.md), [Законы, сценарии и свидетельства](laws.md) +«Понятия»: [Свободная монада](../concepts/free_monad.md) +«Идеи»: [Алгебра EVM](../insights/evm-alg.md) +``` + +```admonish note title="Обзор" +Интерпретатор выбирает представление или эффект для возможности. Он реализует примитивные операции, не переопределяя выведенное выше поведение предметной области, поэтому одни и те же законы выполняются во всех интерпретаторах. +``` + +Интерпретатор реализует семантическую возможность с помощью конкретного представления или эффекта. Он должен выбирать механизмы, не переопределяя поведение предметной области. + +## Тонкий интерпретатор {#a-thin-interpreter} + +Представление ветвей в виде битовых путей может выглядеть так: + +```rust,noplayground +#[derive(Clone, Debug, PartialEq, Eq)] +struct BitBranch(Vec); + +struct BitBranchImpl; + +impl BranchAlg for BitBranchImpl { + type Branch = BitBranch; + + fn branch_root(&self) -> Self::Branch { + BitBranch(Vec::new()) + } + + fn branch_grow(&self, branch: &Self::Branch, direction: Direction) -> Self::Branch { + let mut grown = branch.0.clone(); + grown.push(direction); + BitBranch(grown) + } + + fn branch_path(&self, ancestor: &Self::Branch, descendant: &Self::Branch) -> Option> { + descendant.0.strip_prefix(&ancestor.0[..]).map(<[Direction]>::to_vec) + } +} +``` + +Реализация хранит и наблюдает примитивные факты. `branch_left`, `branch_right` и `branch_is_ancestor` остаются в общем расширении. + +## Интерпретаторы зависят от границ {#interpreters-are-boundary-relative} + +Один и тот же тип на одной границе может быть интерпретатором, а на другой — семантическим входом. + +| Граница | Использует | Интерпретирует | +| --- | --- | --- | +| Адаптер файловой системы | Доступ к файловой системе | Поиск исходного текста | +| Среда нормализатора | Поиск исходного текста как примитивная возможность | Построение нормализованного языка | +| Конвейер компилятора | Нормализованные термы | Построение исполняемого файла | + +Универсального «слоя реализации» не существует. Есть вложенные семантические границы. + +## Эффекты на границе {#effects-at-the-edge} + +Конкретные интерпретаторы отвечают за такие решения, как: + +* структура базы данных +* асинхронная среда выполнения +* владение задачами +* стратегия повторных попыток +* типы фреймворка HTTP или RPC +* сериализация +* блокировки и каналы +* кэширование + +Не включайте эти решения в семантические трейты, если вызывающему коду не нужно их наблюдать. + +Например, семантическая возможность источника может возвращать исходное значение и ошибку. Промышленный интерпретатор может кэшировать файлы и читать их асинхронно. Тестовый интерпретатор может использовать неизменяемую карту. Производная логика нормализации должна работать с обоими. + +## Владение средой выполнения {#runtime-ownership} + +Обратные вызовы фреймворков часто требуют владеющего, клонируемого и потокобезопасного состояния. Это ограничение интерпретатора, но не обязательно предметной области. + +````admonish warning title="Не помещайте типы среды выполнения в примитивы" +Не загрязняйте примитивную операцию типами фреймворка: + +```rust,noplayground +async fn status(data: FrameworkData>) -> FrameworkJson; +``` +```` + +Предпочитайте семантическое применение: + +```rust,noplayground +trait StatusAlg { + type Status; + + async fn status(&self) -> Self::Status; +} +``` + +Веб-интерпретатор может выбрать `Arc`, извлечь входные данные запроса, вызвать `status` и преобразовать результат. Знание о существовании веб-сервера не требуется вызывающему коду предметной области. + +## Нейтральные интерпретаторы {#neutral-interpreters} + +Не каждому интерпретатору нужно выполнять эффекты. + +Текстовый интерпретатор программы API может записывать: + +| Метод | Путь | Входные данные | Выходные данные | +| --- | --- | --- | --- | +| `GET` | `/status` | — | JSON `Status` | +| `POST` | `/temperature` | JSON `f32` | JSON `Status` | + +Интерпретатор метаданных может создавать документацию. Тестовый интерпретатор может собирать имена операций. Промышленный интерпретатор может строить маршруты сервера. + +Нейтральные интерпретаторы показывают, что программа несёт смысл независимо от конкретной среды выполнения. + +## Композиция интерпретаторов через делегирование {#composing-interpreters-by-delegation} + +Поскольку смысл заключён в небольших трейтах возможностей, интерпретатор обычно *собирают* из компонентов, а не выписывают целиком. Носитель получает возможность, делегируя её тому, кто уже её предоставляет, поэтому перенаправление генерируется, а не пишется вручную. Почти все случаи охватывают два способа. + +**Передать возможность полю.** Макрос `#[derive(Delegate)]` из ambassador передаёт целый трейт внутреннему значению. Носитель с несколькими компонентами делегирует каждую возможность полю-владельцу без ручного кода перенаправления: + +```rust,noplayground +#[derive(Delegate)] +#[delegate(Clock, target = "clock")] +#[delegate(Logger, target = "logger")] +struct Service { + clock: SystemClock, + logger: StdoutLogger, +} +``` + +**Предоставить возможность через геттер.** Достаточно добавить типу один геттер — blanket-реализация предоставит всю возможность каждому типу с таким геттером: + +```rust,noplayground +trait Logger { + fn log(&self, message: &str); +} + +trait HasLogger { + type Logger; + + fn logger(&self) -> &Self::Logger; +} + +// Any carrier that can hand back a logger is itself a `Logger`. +impl Logger for T +where + T: HasLogger, + T::Logger: Logger, +{ + fn log(&self, message: &str) { + self.logger().log(message) + } +} +``` + +В результате часто можно обойтись без множества структур. Вместо монолитного объекта контекста — одного крупного трейта с несколькими ассоциированными типами и десятком методов и единственной конкретной реализации — остаётся несколько небольших трейтов возможностей и тонкий носитель, делегирующий каждую из них полю или геттеру. Производные операции, например проверка истечения срока, один раз задаются как расширения поверх примитивов, а не реализуются заново для каждого носителя. + +```admonish warning title="Делегирование передаёт операции, а не смысл" +Сгенерированное делегирование убирает шаблонный код, но не доказывает семантическую взаимозаменяемость. Макрос `derive`, например `#[derive(Delegate)]` из ambassador, подтверждает, что реализации компилируются, но не то, что носитель обозначает тот же интерпретатор. Если `Shared(Arc)` должен подменять `T`, проверьте законы для носителя: обёртка, меняющая совместное использование или идентичность (`Arc`, пулы, кэширование), может правильно перенаправлять каждый метод и всё же нарушать закон свежести или уникальности. Если носитель просто хранит `T` среди несвязанных служб, проекция честнее делегирования. +``` + +## Ошибки относятся к границе {#errors-belong-to-a-boundary} + +Ошибки должны сообщать о сбое на границе, которая его обрабатывает. + +| Ошибка | Преобразование на границе | +| --- | --- | +| Ошибка предметной области | Транспортный интерпретатор преобразует её в ответ протокола | +| Ошибка разбора | Интерфейс компилятора преобразует её в диагностическое сообщение | +| Ошибка хранилища | Интерпретатор источника преобразует её в семантический сбой источника | + +Не помещайте коды состояния HTTP, объекты ошибок RPC или ошибки базы данных в примитивные трейты предметной области. Преобразуйте их на границах интерпретатора. + +## Производительность относится к интерпретации, пока не становится наблюдаемой {#performance-is-an-interpretation-concern-until-observed} + +Пакетная обработка, параллелизм, кэширование и схема данных обычно относятся к интерпретаторам. Они становятся семантическими, только если спецификация гарантирует наблюдаемый порядок, время, расход ресурсов, справедливость или поведение при сбоях. + +Такое разделение позволяет оптимизировать реализацию без семантического дрейфа: + +* Те же законы +* Те же объявленные наблюдения +* Другая операционная стратегия + +## Проверочные вопросы {#review-checks} + +* Реализует ли интерпретатор примитивы, не дублируя производные операции? +* Ограничения среды выполнения и фреймворка остаются на потребляющей границе? +* Могут ли нейтральный или тестовый интерпретатор реализовать ту же возможность? +* Преобразуются ли ошибки транспорта и хранилища на границе? +* Семантически ли честно делегирование? +* Остаются ли различия в производительности ненаблюдаемыми согласно заданной денотации? diff --git a/src/rust-dd/interpreters.uk.md b/src/rust-dd/interpreters.uk.md new file mode 100644 index 0000000..39e7b94 --- /dev/null +++ b/src/rust-dd/interpreters.uk.md @@ -0,0 +1,193 @@ + + +# Інтерпретатори й ефекти {#interpreters-and-effects} + +```admonish tip title="Пов’язані матеріали" +Семантичний погляд: [Закони та інтерпретації](../denotational-design/laws-and-interpretations.md) +Проєктування від значення в Rust: [Алгебри можливостей](capability-algebras.md), [Закони, сценарії та свідчення](laws.md) +Поняття: [Вільна монада](../concepts/free_monad.md) +Інсайти: [Алгебра EVM](../insights/evm-alg.md) +``` + +```admonish note title="Вступний огляд" +Інтерпретатор вибирає представлення чи ефект для певної можливості. Він реалізує примітивні операції, не перевизначаючи поведінку предметної області, виведену на вищому рівні, тож ті самі закони виконуються в кожному інтерпретаторі. +``` + +Інтерпретатор втілює семантичну можливість у конкретному представленні чи ефекті. Він має вибирати механізми, не перевизначаючи поведінку предметної області. + +## Тонкий інтерпретатор {#a-thin-interpreter} + +Представлення гілок бітовими шляхами може виглядати так: + +```rust,noplayground +#[derive(Clone, Debug, PartialEq, Eq)] +struct BitBranch(Vec); + +struct BitBranchImpl; + +impl BranchAlg for BitBranchImpl { + type Branch = BitBranch; + + fn branch_root(&self) -> Self::Branch { + BitBranch(Vec::new()) + } + + fn branch_grow(&self, branch: &Self::Branch, direction: Direction) -> Self::Branch { + let mut grown = branch.0.clone(); + grown.push(direction); + BitBranch(grown) + } + + fn branch_path(&self, ancestor: &Self::Branch, descendant: &Self::Branch) -> Option> { + descendant.0.strip_prefix(&ancestor.0[..]).map(<[Direction]>::to_vec) + } +} +``` + +Реалізація зберігає й спостерігає примітивні факти. `branch_left`, `branch_right` та `branch_is_ancestor` залишаються у спільному розширенні. + +## Інтерпретатори залежать від межі {#interpreters-are-boundary-relative} + +Той самий тип може бути інтерпретатором на одній межі й семантичним вхідним значенням на іншій. + +| Межа | Споживає | Інтерпретує | +| --- | --- | --- | +| Адаптер файлової системи | Доступ до файлової системи | Пошук вихідного тексту | +| Середовище нормалізатора | Пошук вихідного тексту як примітивна можливість | Побудова нормалізованої мови | +| Конвеєр компілятора | Нормалізовані терми | Побудова виконуваного коду | + +Єдиного універсального «рівня реалізації» не існує. Семантичні межі вкладаються одна в одну. + +## Ефекти на зовнішньому рівні {#effects-at-the-edge} + +Конкретні інтерпретатори самостійно вибирають такі речі, як: + +* структура бази даних +* асинхронне середовище виконання +* володіння завданнями +* стратегія повторних спроб +* типи HTTP- чи RPC-фреймворку +* серіалізація +* блокування й канали +* кешування + +Не вносьте ці рішення до семантичних трейтів, якщо їх не потрібно спостерігати клієнтам. + +Наприклад, семантична можливість роботи з джерелом може повертати значення джерела та помилку. Промисловий інтерпретатор може кешувати файли й виконувати асинхронне читання. Тестовий інтерпретатор може використовувати незмінну мапу. Похідна логіка нормалізації має працювати з обома. + +## Володіння ресурсами під час виконання {#runtime-ownership} + +Зворотні виклики фреймворку часто вимагають стану з власником, який можна клонувати й безпечно використовувати в потоках. Це обмеження інтерпретатора, а не обов’язково предметної області. + +````admonish warning title="Не додавайте носії фреймворку до примітивів" +Не забруднюйте примітивну операцію носіями фреймворку: + +```rust,noplayground +async fn status(data: FrameworkData>) -> FrameworkJson; +``` +```` + +Віддавайте перевагу семантичному застосуванню: + +```rust,noplayground +trait StatusAlg { + type Status; + + async fn status(&self) -> Self::Status; +} +``` + +Вебінтерпретатор може вибрати `Arc`, отримати вхідні дані запиту, викликати `status` і перетворити результат. Клієнтам предметної логіки не потрібно знати про існування вебсервера. + +## Нейтральні інтерпретатори {#neutral-interpreters} + +Не кожен інтерпретатор має виконувати ефекти. + +Текстовий інтерпретатор програми API може записувати: + +| Метод | Шлях | Вхідні дані | Вихідні дані | +| --- | --- | --- | --- | +| `GET` | `/status` | — | JSON `Status` | +| `POST` | `/temperature` | JSON `f32` | JSON `Status` | + +Інтерпретатор метаданих може створювати документацію. Тестовий інтерпретатор може збирати назви операцій. Промисловий інтерпретатор може створювати маршрути сервера. + +Нейтральні інтерпретатори показують, що програма має значення незалежно від певного середовища виконання. + +## Композиція інтерпретаторів через делегування {#composing-interpreters-by-delegation} + +Оскільки значення міститься в невеликих трейтах можливостей, інтерпретатор зазвичай *збирають* з компонентів, а не пишуть суцільно. Носій отримує можливість, делегуючи її тому, хто вже її надає; отже, пересилання викликів генерується автоматично, а не пишеться вручну. Майже всі випадки покривають два підходи. + +**Переспрямуйте можливість до поля.** Макрос `#[derive(Delegate)]` з ambassador передає цілий трейт внутрішньому значенню. Носій із кількома компонентами делегує кожну можливість полю, яке за неї відповідає, без коду пересилання: + +```rust,noplayground +#[derive(Delegate)] +#[delegate(Clock, target = "clock")] +#[delegate(Logger, target = "logger")] +struct Service { + clock: SystemClock, + logger: StdoutLogger, +} +``` + +**Надайте можливість через гетер.** Додайте до типу один гетер — і загальна реалізація надасть повну можливість кожному типу, який має цей гетер: + +```rust,noplayground +trait Logger { + fn log(&self, message: &str); +} + +trait HasLogger { + type Logger; + + fn logger(&self) -> &Self::Logger; +} + +// Any carrier that can hand back a logger is itself a `Logger`. +impl Logger for T +where + T: HasLogger, + T::Logger: Logger, +{ + fn log(&self, message: &str) { + self.logger().log(message) + } +} +``` + +У результаті багатьох структур можна уникнути. Замість монолітного об’єкта контексту — одного великого трейту з кількома асоційованими типами й десятком методів та єдиною конкретною реалізацією — достатньо кількох невеликих трейтів можливостей і тонкого носія, який делегує кожну можливість полю чи гетеру, що її надає. Похідні операції, наприклад перевірка, чи минув крайній термін, визначаються один раз як розширення примітивів, а не реалізуються заново для кожного носія. + +```admonish warning title="Делегування пересилає операції, а не значення" +Згенероване делегування прибирає шаблонний код, але не встановлює семантичну взаємозамінність. Макрос `derive` на кшталт `#[derive(Delegate)]` від ambassador доводить, що реалізації компілюються, але не те, що носій позначає той самий інтерпретатор. Якщо `Shared(Arc)` має замінювати `T`, перевірте закони для носія: обгортка, яка змінює спільне використання чи ідентичність (`Arc`, пулінг, кешування), може правильно пересилати кожен метод і водночас порушувати закон свіжості чи унікальності. Якщо носій лише містить `T` серед інших служб, проєкція точніше описує цей зв’язок, ніж делегування. +``` + +## Помилки належать межі {#errors-belong-to-a-boundary} + +Помилки мають передавати значення збою на межі, де його обробляють. + +| Помилка | Переклад на межі | +| --- | --- | +| Помилка предметної області | Транспортний інтерпретатор перетворює її на відповідь протоколу | +| Помилка розбору | Зовнішній інтерфейс компілятора перетворює її на діагностичне повідомлення | +| Помилка сховища | Інтерпретатор джерела перетворює її на семантичний збій джерела | + +Не включайте коди стану HTTP, об’єкти помилок RPC чи помилки бази даних до примітивних трейтів предметної області. Перетворюйте їх на межах інтерпретатора. + +## Продуктивність стосується інтерпретації, доки її не спостерігають {#performance-is-an-interpretation-concern-until-observed} + +Пакетна обробка, паралелізм, кешування та розташування даних зазвичай належать до інтерпретаторів. Вони стають семантичними лише тоді, коли специфікація гарантує спостережуваний порядок, час, використання ресурсів, справедливість або поведінку у разі збою. + +Таке розділення дає змогу оптимізувати без семантичних відхилень: + +* Ті самі закони +* Ті самі заявлені спостереження +* Інша операційна стратегія + +## Перевірка {#review-checks} + +* Чи реалізує інтерпретатор примітиви, а не дублює похідні визначення? +* Чи обмежено вимоги середовища виконання та фреймворку тією межею, де їх використовують? +* Чи може нейтральний або тестовий інтерпретатор реалізувати ту саму можливість? +* Чи перетворюються транспортні помилки й помилки сховища на зовнішньому рівні? +* Чи відповідає делегування семантичному задуму? +* Чи є відмінності в продуктивності неспостережуваними згідно із заданою денотацією? diff --git a/src/rust-dd/interpreters.vi.md b/src/rust-dd/interpreters.vi.md new file mode 100644 index 0000000..f9d751e --- /dev/null +++ b/src/rust-dd/interpreters.vi.md @@ -0,0 +1,193 @@ + + +# Bộ diễn giải và hiệu ứng {#interpreters-and-effects} + +```admonish tip title="Liên quan" +Góc nhìn ngữ nghĩa: [Định luật và cách diễn giải](../denotational-design/laws-and-interpretations.md) +Thiết kế theo ngữ nghĩa trong Rust: [Các đại số năng lực](capability-algebras.md), [Định luật, tình huống và bằng chứng](laws.md) +Khái niệm: [Monad tự do](../concepts/free_monad.md) +Nhận định: [Đại số EVM](../insights/evm-alg.md) +``` + +```admonish note title="Định hướng" +Bộ diễn giải chọn cách biểu diễn hoặc hiệu ứng cho một năng lực. Nó hiện thực hóa các phép toán nguyên thủy mà không định nghĩa lại hành vi miền được suy ra ở lớp phía trên, nhờ vậy các định luật giữ nguyên với mọi bộ diễn giải. +``` + +Bộ diễn giải hiện thực hóa một năng lực ngữ nghĩa bằng cách biểu diễn hoặc hiệu ứng cụ thể. Nó cần chọn cơ chế mà không định nghĩa lại hành vi miền. + +## Bộ diễn giải mỏng {#a-thin-interpreter} + +Cách biểu diễn nhánh bằng đường đi bit có thể là: + +```rust,noplayground +#[derive(Clone, Debug, PartialEq, Eq)] +struct BitBranch(Vec); + +struct BitBranchImpl; + +impl BranchAlg for BitBranchImpl { + type Branch = BitBranch; + + fn branch_root(&self) -> Self::Branch { + BitBranch(Vec::new()) + } + + fn branch_grow(&self, branch: &Self::Branch, direction: Direction) -> Self::Branch { + let mut grown = branch.0.clone(); + grown.push(direction); + BitBranch(grown) + } + + fn branch_path(&self, ancestor: &Self::Branch, descendant: &Self::Branch) -> Option> { + descendant.0.strip_prefix(&ancestor.0[..]).map(<[Direction]>::to_vec) + } +} +``` + +Cách triển khai lưu trữ và quan sát các sự kiện nguyên thủy. `branch_left`, `branch_right` và `branch_is_ancestor` vẫn thuộc về phần mở rộng dùng chung. + +## Bộ diễn giải phụ thuộc vào ranh giới {#interpreters-are-boundary-relative} + +Cùng một kiểu có thể là bộ diễn giải ở ranh giới này và đầu vào ngữ nghĩa ở ranh giới khác. + +| Ranh giới | Sử dụng | Diễn giải | +| --- | --- | --- | +| Bộ chuyển đổi hệ thống tệp | Truy cập hệ thống tệp | Tra cứu nguồn | +| Môi trường chuẩn hóa | Tra cứu nguồn như năng lực nguyên thủy | Kiến tạo ngôn ngữ đã chuẩn hóa | +| Quy trình trình biên dịch | Các số hạng đã chuẩn hóa | Kiến tạo tệp thực thi | + +Không có một “lớp triển khai” phổ quát duy nhất. Có nhiều ranh giới ngữ nghĩa lồng nhau. + +## Hiệu ứng ở rìa {#effects-at-the-edge} + +Bộ diễn giải cụ thể sở hữu các lựa chọn như: + +* bố cục cơ sở dữ liệu +* môi trường chạy bất đồng bộ +* quyền sở hữu tác vụ +* chiến lược thử lại +* kiểu của khung HTTP hoặc RPC +* tuần tự hóa +* khóa và kênh +* bộ nhớ đệm + +Hãy loại các lựa chọn này khỏi đặc trưng ngữ nghĩa, trừ khi bên gọi cần quan sát chúng. + +Chẳng hạn, năng lực nguồn ngữ nghĩa có thể trả về giá trị nguồn và lỗi. Bộ diễn giải sản xuất có thể lưu đệm tệp và thực hiện các lần đọc bất đồng bộ. Bộ diễn giải kiểm thử có thể dùng bản đồ bất biến. Logic chuẩn hóa suy ra nên hoạt động với cả hai. + +## Quyền sở hữu ở môi trường chạy {#runtime-ownership} + +Callback của khung thường yêu cầu trạng thái có quyền sở hữu, có thể sao chép và an toàn giữa các luồng. Đó là ràng buộc của bộ diễn giải, không nhất thiết là ràng buộc miền. + +````admonish warning title="Đừng để đối tượng mang của khung xâm nhập phép toán nguyên thủy" +Tránh làm nhiễm phép toán nguyên thủy bằng đối tượng mang của khung: + +```rust,noplayground +async fn status(data: FrameworkData>) -> FrameworkJson; +``` +```` + +Ưu tiên ứng dụng ngữ nghĩa: + +```rust,noplayground +trait StatusAlg { + type Status; + + async fn status(&self) -> Self::Status; +} +``` + +Bộ diễn giải web có thể chọn `Arc`, trích xuất đầu vào yêu cầu, gọi `status` rồi chuyển đổi kết quả. Bên gọi trong miền không cần biết có máy chủ web. + +## Bộ diễn giải trung lập {#neutral-interpreters} + +Không phải bộ diễn giải nào cũng cần thực thi hiệu ứng. + +Bộ diễn giải văn bản cho chương trình API có thể ghi lại: + +| Phương thức | Đường dẫn | Đầu vào | Đầu ra | +| --- | --- | --- | --- | +| `GET` | `/status` | — | JSON `Status` | +| `POST` | `/temperature` | JSON `f32` | JSON `Status` | + +Bộ diễn giải siêu dữ liệu có thể tạo tài liệu. Bộ diễn giải kiểm thử có thể thu thập tên phép toán. Bộ diễn giải sản xuất có thể dựng các tuyến máy chủ. + +Bộ diễn giải trung lập chứng minh chương trình mang ý nghĩa độc lập với một môi trường chạy. + +## Hợp thành bộ diễn giải bằng ủy quyền {#composing-interpreters-by-delegation} + +Vì ý nghĩa nằm trong các đặc trưng năng lực nhỏ, bộ diễn giải thường được *lắp ghép* thay vì viết toàn bộ. Đối tượng mang có được một năng lực bằng cách ủy quyền cho thành phần vốn cung cấp nó, nên phần chuyển tiếp được tạo sinh chứ không phải viết thủ công. Hầu hết trường hợp được bao phủ bởi hai dạng. + +**Chuyển tiếp năng lực đến một trường.** macro ambassador `#[derive(Delegate)]` chuyển tiếp toàn bộ đặc trưng đến một giá trị bên trong. Đối tượng mang chứa nhiều thành phần sẽ ủy quyền mỗi năng lực cho trường sở hữu nó, không cần viết phần thân chuyển tiếp: + +```rust,noplayground +#[derive(Delegate)] +#[delegate(Clock, target = "clock")] +#[delegate(Logger, target = "logger")] +struct Service { + clock: SystemClock, + logger: StdoutLogger, +} +``` + +**Cấp năng lực qua getter.** Cung cấp cho một kiểu một getter, rồi một triển khai tổng quát sẽ cấp toàn bộ năng lực cho mọi kiểu có getter đó: + +```rust,noplayground +trait Logger { + fn log(&self, message: &str); +} + +trait HasLogger { + type Logger; + + fn logger(&self) -> &Self::Logger; +} + +// Any carrier that can hand back a logger is itself a `Logger`. +impl Logger for T +where + T: HasLogger, + T::Logger: Logger, +{ + fn log(&self, message: &str) { + self.logger().log(message) + } +} +``` + +Hệ quả là nhiều cấu trúc không cần tồn tại. Một đối tượng ngữ cảnh nguyên khối — một đặc trưng lớn mang theo nhiều kiểu liên kết và hàng chục phương thức, cùng một cách triển khai cụ thể duy nhất — được thay bằng một nhóm nhỏ đặc trưng năng lực và một đối tượng mang mỏng ủy quyền từng đặc trưng cho trường hoặc getter cung cấp nó. Các phép toán suy ra, chẳng hạn kiểm tra hạn chót đã qua chưa, được viết một lần dưới dạng phần mở rộng dựa trên các phép toán nguyên thủy thay vì triển khai lại trên từng đối tượng mang. + +```admonish warning title="Ủy quyền chuyển tiếp phép toán, không chuyển tiếp ý nghĩa" +Ủy quyền được tạo sinh loại bỏ mã khuôn mẫu nhưng không xác lập khả năng thay thế ngữ nghĩa. Macro `derive` như `#[derive(Delegate)]` của ambassador chỉ chứng minh các triển khai biên dịch được, chứ không chứng minh đối tượng mang biểu thị cùng bộ diễn giải. Nếu `Shared(Arc)` cần thay thế cho `T`, hãy kiểm tra các định luật trên đối tượng mang — lớp bọc thay đổi tính chia sẻ hoặc danh tính (`Arc`, gộp nhóm, lưu đệm) vẫn có thể chuyển tiếp mọi phương thức chính xác nhưng vi phạm định luật tính mới hoặc tính duy nhất. Khi đối tượng mang chỉ lưu giữ `T` giữa các dịch vụ không liên quan, phép chiếu trung thực hơn ủy quyền. +``` + +## Lỗi thuộc về một ranh giới {#errors-belong-to-a-boundary} + +Lỗi cần truyền đạt ý nghĩa thất bại ở ranh giới xử lý chúng. + +| Lỗi | Chuyển đổi ở ranh giới | +| --- | --- | +| Lỗi miền | Bộ diễn giải truyền tải ánh xạ lỗi thành phản hồi giao thức | +| Lỗi phân tích cú pháp | Giao diện đầu trình biên dịch ánh xạ lỗi thành chẩn đoán | +| Lỗi lưu trữ | Bộ diễn giải nguồn ánh xạ lỗi thành tình trạng nguồn ngữ nghĩa | + +Đừng ép mã trạng thái HTTP, đối tượng lỗi RPC hoặc lỗi cơ sở dữ liệu vào đặc trưng miền nguyên thủy. Hãy chuyển đổi chúng tại ranh giới bộ diễn giải. + +## Hiệu năng là mối quan tâm của cách diễn giải cho đến khi được quan sát {#performance-is-an-interpretation-concern-until-observed} + +Gom lô, song song hóa, lưu đệm và bố cục dữ liệu thường thuộc về bộ diễn giải. Chúng chỉ trở thành ngữ nghĩa khi đặc tả cam kết thứ tự, thời gian, mức dùng tài nguyên, tính công bằng hoặc hành vi lỗi có thể quan sát. + +Sự phân tách này cho phép tối ưu hóa mà không làm trôi lệch ngữ nghĩa: + +* Cùng các định luật +* Cùng các quan sát được khai báo +* Chiến lược vận hành khác nhau + +## Các câu hỏi khi duyệt {#review-checks} + +* Bộ diễn giải có triển khai các phép toán nguyên thủy thay vì lặp lại phép suy ra không? +* Các ràng buộc của môi trường chạy và khung có được giới hạn ở ranh giới sử dụng không? +* Bộ diễn giải trung lập hoặc kiểm thử có thể triển khai cùng năng lực không? +* Lỗi truyền tải và lưu trữ có được chuyển đổi ở rìa không? +* Ủy quyền có trung thực về mặt ngữ nghĩa không? +* Các khác biệt hiệu năng có không quan sát được theo ngữ nghĩa chỉ định đã nêu không? diff --git a/src/rust-dd/interpreters.zh-hant.md b/src/rust-dd/interpreters.zh-hant.md new file mode 100644 index 0000000..399f52d --- /dev/null +++ b/src/rust-dd/interpreters.zh-hant.md @@ -0,0 +1,193 @@ + + +# 直譯器與效應 {#interpreters-and-effects} + +```admonish tip title="相關內容" +語義視角:[定律與解釋](../denotational-design/laws-and-interpretations.md) +Rust 中的語義驅動設計:[能力代數](capability-algebras.md)、[定律、場景與證據](laws.md) +概念:[自由單子](../concepts/free_monad.md) +洞見:[EVM 代數](../insights/evm-alg.md) +``` + +```admonish note title="導讀" +直譯器為某種能力選擇表示或效應。它實現基本操作,但不會重新定義其上層派生出的領域行為,因此所有直譯器都遵循相同定律。 +``` + +直譯器使用具體表示或效應來實現語義能力。它應選擇實現機制,而不重新定義領域行為。 + +## 輕量級直譯器 {#a-thin-interpreter} + +分支的一種位路徑表示可以是: + +```rust,noplayground +#[derive(Clone, Debug, PartialEq, Eq)] +struct BitBranch(Vec); + +struct BitBranchImpl; + +impl BranchAlg for BitBranchImpl { + type Branch = BitBranch; + + fn branch_root(&self) -> Self::Branch { + BitBranch(Vec::new()) + } + + fn branch_grow(&self, branch: &Self::Branch, direction: Direction) -> Self::Branch { + let mut grown = branch.0.clone(); + grown.push(direction); + BitBranch(grown) + } + + fn branch_path(&self, ancestor: &Self::Branch, descendant: &Self::Branch) -> Option> { + descendant.0.strip_prefix(&ancestor.0[..]).map(<[Direction]>::to_vec) + } +} +``` + +實作負責儲存和觀察基本事實。`branch_left`、`branch_right`和`branch_is_ancestor`仍留在共享擴充中。 + +## 直譯器取決於邊界 {#interpreters-are-boundary-relative} + +同一種型別在一個邊界上可以是直譯器,在另一個邊界上則可以是語義輸入。 + +| 邊界 | 使用 | 解釋 | +| --- | --- | --- | +| 檔案系統介面卡 | 檔案系統存取 | 原始碼查詢 | +| 正規化器環境 | 將原始碼查詢作為基本能力 | 正規化語言構造 | +| 編譯器流水線 | 正規化項 | 可執行程式構造 | + +不存在唯一通用的“實作層”,而是存在巢狀的語義邊界。 + +## 邊界處的效應 {#effects-at-the-edge} + +具體直譯器負責選擇以下內容: + +* 資料庫佈局 +* 非同步執行時 +* 任務所有權 +* 重試策略 +* HTTP 或 RPC 框架型別 +* 序列化 +* 鎖與通道 +* 快取 + +除非呼叫者需要觀察這些選擇,否則應讓它們留在語義 trait 之外。 + +例如,語義原始碼能力可以返回原始碼值與錯誤。生產直譯器可以快取檔案並非同步讀取;測試直譯器則可以使用不可變對映。派生的正規化邏輯應能同時適用於二者。 + +## 執行時所有權 {#runtime-ownership} + +框架回撥通常要求狀態具備所有權、可克隆且執行緒安全。這是直譯器的約束,不一定是領域約束。 + +````admonish warning title="不要讓框架載體汙染基本操作" +避免在基本操作中混入框架載體: + +```rust,noplayground +async fn status(data: FrameworkData>) -> FrameworkJson; +``` +```` + +優先採用語義應用方式: + +```rust,noplayground +trait StatusAlg { + type Status; + + async fn status(&self) -> Self::Status; +} +``` + +Web 直譯器可以選擇`Arc`、提取請求輸入、呼叫`status`並轉換結果。領域呼叫方無需知道 Web 伺服器存在。 + +## 中性直譯器 {#neutral-interpreters} + +並非所有直譯器都需要執行效應。 + +API 程式的文字直譯器可以記錄: + +| 方法 | 路徑 | 輸入 | 輸出 | +| --- | --- | --- | --- | +| `GET` | `/status` | — | JSON `Status` | +| `POST` | `/temperature` | JSON `f32` | JSON `Status` | + +後設資料直譯器可以生成文件。測試直譯器可以收集操作名稱。生產直譯器可以構造伺服器路由。 + +中性直譯器能夠證明,程式的含義獨立於任何特定執行時。 + +## 透過委託組合直譯器 {#composing-interpreters-by-delegation} + +由於含義存在於小型能力 trait 中,直譯器通常是*組裝*而成,而非從頭寫出。載體透過委託給已有的能力來獲得新能力,因此轉發程式碼由工具生成,無需手寫。兩種形式幾乎就能覆蓋所有情況。 + +將能力轉發給欄位。ambassador 的`#[derive(Delegate)]`會把整個 trait 轉發給內部值。持有多個元件的載體可以將各項能力委託給擁有它的欄位,無需編寫轉發函式體: + +```rust,noplayground +#[derive(Delegate)] +#[delegate(Clock, target = "clock")] +#[delegate(Logger, target = "logger")] +struct Service { + clock: SystemClock, + logger: StdoutLogger, +} +``` + +透過 getter 授予能力。為型別提供一個 getter,再由整體實現為所有具有該 getter 的型別提供完整能力: + +```rust,noplayground +trait Logger { + fn log(&self, message: &str); +} + +trait HasLogger { + type Logger; + + fn logger(&self) -> &Self::Logger; +} + +// Any carrier that can hand back a logger is itself a `Logger`. +impl Logger for T +where + T: HasLogger, + T::Logger: Logger, +{ + fn log(&self, message: &str) { + self.logger().log(message) + } +} +``` + +這樣一來,許多結構體根本無需存在。龐大的上下文物件——一個攜帶多個關聯型別與十幾個方法的大型 trait,再加上唯一的具體實作——可以化為幾個小型能力 trait,以及一個精簡載體;載體將每種能力委託給提供該能力的欄位或 getter。檢查截止時間是否已過之類的派生操作,只需作為基本操作之上的擴充編寫一次,無需在每個載體上重新實作。 + +```admonish warning title="委託轉發的是操作,而非含義" +生成委託程式碼可以省去樣板工作,卻不能確立語義上的可替代性。`derive`諸如 ambassador 的`#[derive(Delegate)]`宏只能證明實現能夠編譯,不能證明該載體指稱相同的直譯器。如果`Shared(Arc)`要替代`T`,就應在載體上檢查定律——會改變共享性或身份的包裝器(`Arc`、池化、快取)可能正確轉發每個方法,卻仍違反新鮮度或唯一性定律。如果載體只是在其他服務之間存放了`T`,使用投影會比委託更誠實。 +``` + +## 錯誤屬於特定邊界 {#errors-belong-to-a-boundary} + +錯誤應當在負責處理它的邊界上傳達失敗的含義。 + +| 錯誤 | 邊界轉換 | +| --- | --- | +| 領域錯誤 | 傳輸直譯器將其對映為協議響應 | +| 解析錯誤 | 編譯器前端將其對映為診斷資訊 | +| 儲存錯誤 | 原始碼直譯器將其對映為語義層面的原始碼失敗 | + +不要把 HTTP 狀態碼、RPC 錯誤物件或資料庫錯誤強加給基本領域 trait。應在直譯器邊界處轉換它們。 + +## 在效能可觀察之前,它屬於解釋範疇 {#performance-is-an-interpretation-concern-until-observed} + +批次處理、並行、快取與資料佈局通常屬於直譯器。只有當規範承諾了可觀察的順序、時間、資源使用、公平性或失敗行為時,它們才成為語義的一部分。 + +這種區分能夠在避免語義漂移的同時進行最佳化: + +* 遵循相同定律 +* 宣告相同觀察 +* 採用不同操作策略 + +## 審查要點 {#review-checks} + +* 直譯器是否實作基本操作,而非重複派生邏輯? +* 執行時與框架約束是否限定在使用這些約束的邊界內? +* 中性直譯器或測試直譯器能否實作同一能力? +* 傳輸與儲存錯誤是否在邊界處轉換? +* 委託表達的語義關係是否準確? +* 根據所述指稱,效能差異是否不可觀察? diff --git a/src/rust-dd/interpreters.zh.md b/src/rust-dd/interpreters.zh.md new file mode 100644 index 0000000..779d68a --- /dev/null +++ b/src/rust-dd/interpreters.zh.md @@ -0,0 +1,193 @@ + + +# 解释器与效应 {#interpreters-and-effects} + +```admonish tip title="相关内容" +语义视角:[定律与解释](../denotational-design/laws-and-interpretations.md) +Rust 中的语义驱动设计:[能力代数](capability-algebras.md)、[定律、场景与证据](laws.md) +概念:[自由单子](../concepts/free_monad.md) +洞见:[EVM 代数](../insights/evm-alg.md) +``` + +```admonish note title="导读" +解释器为某种能力选择表示或效应。它实现基本操作,但不会重新定义其上层派生出的领域行为,因此所有解释器都遵循相同定律。 +``` + +解释器使用具体表示或效应来实现语义能力。它应选择实现机制,而不重新定义领域行为。 + +## 轻量级解释器 {#a-thin-interpreter} + +分支的一种位路径表示可以是: + +```rust,noplayground +#[derive(Clone, Debug, PartialEq, Eq)] +struct BitBranch(Vec); + +struct BitBranchImpl; + +impl BranchAlg for BitBranchImpl { + type Branch = BitBranch; + + fn branch_root(&self) -> Self::Branch { + BitBranch(Vec::new()) + } + + fn branch_grow(&self, branch: &Self::Branch, direction: Direction) -> Self::Branch { + let mut grown = branch.0.clone(); + grown.push(direction); + BitBranch(grown) + } + + fn branch_path(&self, ancestor: &Self::Branch, descendant: &Self::Branch) -> Option> { + descendant.0.strip_prefix(&ancestor.0[..]).map(<[Direction]>::to_vec) + } +} +``` + +实现负责存储和观察基本事实。`branch_left`、`branch_right`和`branch_is_ancestor`仍留在共享扩展中。 + +## 解释器取决于边界 {#interpreters-are-boundary-relative} + +同一种类型在一个边界上可以是解释器,在另一个边界上则可以是语义输入。 + +| 边界 | 使用 | 解释 | +| --- | --- | --- | +| 文件系统适配器 | 文件系统访问 | 源代码查找 | +| 规范化器环境 | 将源代码查找作为基本能力 | 规范化语言构造 | +| 编译器流水线 | 规范化项 | 可执行程序构造 | + +不存在唯一通用的“实现层”,而是存在嵌套的语义边界。 + +## 边界处的效应 {#effects-at-the-edge} + +具体解释器负责选择以下内容: + +* 数据库布局 +* 异步运行时 +* 任务所有权 +* 重试策略 +* HTTP 或 RPC 框架类型 +* 序列化 +* 锁与通道 +* 缓存 + +除非调用者需要观察这些选择,否则应让它们留在语义 trait 之外。 + +例如,语义源代码能力可以返回源代码值与错误。生产解释器可以缓存文件并异步读取;测试解释器则可以使用不可变映射。派生的规范化逻辑应能同时适用于二者。 + +## 运行时所有权 {#runtime-ownership} + +框架回调通常要求状态具备所有权、可克隆且线程安全。这是解释器的约束,不一定是领域约束。 + +````admonish warning title="不要让框架载体污染基本操作" +避免在基本操作中混入框架载体: + +```rust,noplayground +async fn status(data: FrameworkData>) -> FrameworkJson; +``` +```` + +优先采用语义应用方式: + +```rust,noplayground +trait StatusAlg { + type Status; + + async fn status(&self) -> Self::Status; +} +``` + +Web 解释器可以选择`Arc`、提取请求输入、调用`status`并转换结果。领域调用方无需知道 Web 服务器存在。 + +## 中性解释器 {#neutral-interpreters} + +并非所有解释器都需要执行效应。 + +API 程序的文本解释器可以记录: + +| 方法 | 路径 | 输入 | 输出 | +| --- | --- | --- | --- | +| `GET` | `/status` | — | JSON `Status` | +| `POST` | `/temperature` | JSON `f32` | JSON `Status` | + +元数据解释器可以生成文档。测试解释器可以收集操作名称。生产解释器可以构造服务器路由。 + +中性解释器能够证明,程序的含义独立于任何特定运行时。 + +## 通过委托组合解释器 {#composing-interpreters-by-delegation} + +由于含义存在于小型能力 trait 中,解释器通常是*组装*而成,而非从头写出。载体通过委托给已有的能力来获得新能力,因此转发代码由工具生成,无需手写。两种形式几乎就能覆盖所有情况。 + +将能力转发给字段。ambassador 的`#[derive(Delegate)]`会把整个 trait 转发给内部值。持有多个组件的载体可以将各项能力委托给拥有它的字段,无需编写转发函数体: + +```rust,noplayground +#[derive(Delegate)] +#[delegate(Clock, target = "clock")] +#[delegate(Logger, target = "logger")] +struct Service { + clock: SystemClock, + logger: StdoutLogger, +} +``` + +通过 getter 授予能力。为类型提供一个 getter,再由整体实现为所有具有该 getter 的类型提供完整能力: + +```rust,noplayground +trait Logger { + fn log(&self, message: &str); +} + +trait HasLogger { + type Logger; + + fn logger(&self) -> &Self::Logger; +} + +// Any carrier that can hand back a logger is itself a `Logger`. +impl Logger for T +where + T: HasLogger, + T::Logger: Logger, +{ + fn log(&self, message: &str) { + self.logger().log(message) + } +} +``` + +这样一来,许多结构体根本无需存在。庞大的上下文对象——一个携带多个关联类型与十几个方法的大型 trait,再加上唯一的具体实现——可以化为几个小型能力 trait,以及一个轻量载体;载体将每种能力委托给提供该能力的字段或 getter。检查截止时间是否已过之类的派生操作,只需作为基本操作之上的扩展编写一次,无需在每个载体上重新实现。 + +```admonish warning title="委托转发的是操作,而非含义" +生成委托代码可以省去样板工作,却不能确立语义上的可替代性。`derive`诸如 ambassador 的`#[derive(Delegate)]`宏只能证明实现能够编译,不能证明该载体指称相同的解释器。如果`Shared(Arc)`要替代`T`,就应在载体上检查定律——会改变共享性或身份的包装器(`Arc`、池化、缓存)可能正确转发每个方法,却仍违反新鲜度或唯一性定律。如果载体只是在其他服务之间存放了`T`,使用投影会比委托更诚实。 +``` + +## 错误属于特定边界 {#errors-belong-to-a-boundary} + +错误应当在负责处理它的边界上传达失败的含义。 + +| 错误 | 边界转换 | +| --- | --- | +| 领域错误 | 传输解释器将其映射为协议响应 | +| 解析错误 | 编译器前端将其映射为诊断信息 | +| 存储错误 | 源代码解释器将其映射为语义层面的源代码失败 | + +不要把 HTTP 状态码、RPC 错误对象或数据库错误强加给基本领域 trait。应在解释器边界处转换它们。 + +## 在性能可观察之前,它属于解释范畴 {#performance-is-an-interpretation-concern-until-observed} + +批处理、并行、缓存与数据布局通常属于解释器。只有当规范承诺了可观察的顺序、时间、资源使用、公平性或失败行为时,它们才成为语义的一部分。 + +这种区分能够在避免语义漂移的同时进行优化: + +* 遵循相同定律 +* 声明相同观察 +* 采用不同操作策略 + +## 审查要点 {#review-checks} + +* 解释器是否实现基本操作,而非重复派生逻辑? +* 运行时与框架约束是否限定在使用这些约束的边界内? +* 中性解释器或测试解释器能否实现同一能力? +* 传输与存储错误是否在边界处转换? +* 委托表达的语义关系是否准确? +* 根据所述指称,性能差异是否不可观察? diff --git a/src/rust-dd/laws.ar.md b/src/rust-dd/laws.ar.md new file mode 100644 index 0000000..fe91f4f --- /dev/null +++ b/src/rust-dd/laws.ar.md @@ -0,0 +1,187 @@ + + +# القوانين والسيناريوهات والأدلة {#laws-scenarios-and-evidence} + +```admonish tip title="ذات صلة" +المنظور الدلالي: [القوانين والتفسيرات](../denotational-design/laws-and-interpretations.md) +التصميم انطلاقًا من المعنى في Rust: [المفسرات والآثار](interpreters.md)، [جبر القدرات](capability-algebras.md) +المفاهيم: [التشعب والتلاقي](../concepts/branching.md)، [الشفافية المرجعية](../concepts/referential_transparency.md) +``` + +```admonish note title="تمهيد" +الاختبارات دليل على المواصفة. أكّد الملاحظات العامة والقوانين التي يدعمها المجال المختار، لا خطوات التنفيذ الخاصة، واجعل القوانين عامة بالنسبة إلى القدرة كي تُلزم كل المفسرات بها. +``` + +تحتاج الشيفرة التي تبدأ بالمعنى إلى اختبارات تبدأ بالمعنى. اختبر الملاحظات العامة والقوانين بدلًا من خطوات التنفيذ الخاصة. + +## اختبر سطح المواصفة {#test-the-specification-surface} + +````admonish warning title="اختبار مرتبط بالتمثيل" +يمتد هذا التأكيد إلى حقول حامل واحد، لذلك لا يستطيع أي مفسر آخر مشاركته: + +```rust,noplayground +// not recommended: asserts a bit layout, not a semantic observation +assert_eq!(branch.bits, vec![false, true]); +``` +```` + +اختبار دلالي: + +```rust,noplayground +let root = alg.branch_root(); +let left = alg.branch_left(&root); +let left_right = alg.branch_right(&left); + +assert_eq!(alg.branch_path(&root, &left_right), Some(vec![Direction::Left, Direction::Right])); +``` + +قد يكون الاختبار الأول مناسبًا لوحدة تسلسل يكون موضوعها ترميز البتات. لكنه دليل ضعيف على جبر الفروع لأن التمثيلات البديلة لا تستطيع مشاركته. + +## امتدادات قوانين قابلة لإعادة الاستخدام {#reusable-law-extensions} + +عندما تنطبق خاصية على كل مفسر متوافق، اكتبها مرة واحدة: + +```rust,noplayground +use anyhow::{Result, bail, ensure}; +use extend::ext; + +#[ext(name = BranchLawsExt)] +pub impl This +where + This: BranchAlg, + This::Branch: Clone + Eq, +{ + fn check_branch_root_round_trip(&self, directions: &[Direction]) -> Result<()> { + let root = self.branch_root(); + let branch = directions.iter().copied().fold(root.clone(), |branch, direction| self.branch_grow(&branch, direction)); + + let Some(path) = self.branch_path(&root, &branch) else { + bail!("grown branch has no path from root"); + }; + ensure!(path == directions, "root path did not round-trip"); + Ok(()) + } +} +``` + +يشغّل كل مفسر أداة التحقق نفسها. يحمل `anyhow::Result` النتيجة؛ ويبلّغ `bail!` عن الملاحظة المفقودة، بينما يتحقق `ensure!` من قانون الذهاب والإياب. وتميز الأداة بين الإخفاقين من دون الاعتماد على تمثيل فرع واحد. + +## عائلات قوانين مفيدة {#useful-law-families} + +ابحث عن الخصائص التي توحي بها البنية الدلالية: + +* الهوية +* التجميعية +* التبادلية، عندما تكون مقصودة فعلًا +* الإدمبوتية +* الذهاب والإياب +* التوحيد المعياري +* التنقيح +* الرتابة +* الاستبدال +* اتفاق التفسيرات + +```admonish warning title="لا تدّعِ سوى القوانين التي يدعمها المجال" +لا تضف مصطلحات جبرية مألوفة لمجرد أنها تبدو رياضية. اذكر القوانين التي يدعمها المجال المختار فقط. +``` + +## القوانين مقابل الثوابت التمثيلية {#laws-versus-representation-invariants} + +أبقِها متميزة: + +* **قانون دلالي:** إعادة بناء فرع من مسار جذره تدل على الفرع نفسه. + +* **ثابت تمثيلي:** البتات العليا غير المستخدمة تساوي صفرًا. + +* **قانون التسلسل:** + + $$ \operatorname{decode}(\operatorname{encode}(b)) = b $$ + +* **قانون التنسيق المعياري:** + + $$ \operatorname{encode}(\operatorname{decode}(x)) = x \qquad \text{for canonical byte sequences }x $$ + + +قد تكون جميعها مهمة، لكنها تنتمي إلى مواصفات مختلفة. + +## سيناريوهات مشتركة {#shared-scenarios} + +السيناريو تفاعل قابل لإعادة الاستخدام مكتوب على أساس القدرات العامة. ويمثل إطار اختبار ALUX السيناريوهات بهذه الطريقة: تبني شيفرة التأليف قيمة عبر قدرات `Scenario` و`DeployerIds` و`PlayAst` و`ScenarioSchedule` من دون تسمية مشغّل ملموس. + +```rust,noplayground +#[ext(name = HelloScenarioExt)] +pub impl This +where + This: StandaloneScenario, + This::Step: PlayAst, +{ + fn hello(self) -> This::Scenario { + self.scenario() + .under_comprehensive(100) + .step( + self.play_ast( + self.deployer(0), + tolang! { + let x in { + x ! "hello" | + ? (a <- x) a.log() + } + }, + ) + .expect_log(r#""hello""#), + ) + } +} +``` + +يصف كل استدعاء المعنى المؤلَّف لا آليات المشغّل. ويتطلب `under_comprehensive(100)` السجل المتوقع في تشغيل تسلسلي واحد، و100 تشغيل متزامن بحرية، وحتى 100 تشغيل بترتيبات مختلفة. يثبت السيناريو الملاحظة بينما يغيّر المشغّل ترتيب التنفيذ. + +ينطبق المبدأ نفسه بين المفسرات: عندما تنفذ عدة مشغلات القدرات التي يستخدمها سيناريو ما، يستطيع كل منها تفسير التفاعل المؤلَّف نفسه. ويبقى الإعداد الخاص بالمشغل وفحص الحدود خارج السيناريو. + +## الاتفاق بين المفسرات {#cross-interpreter-agreement} + +عندما يكشف مفسران الملاحظة نفسها، قارنهما: + +$$ \operatorname{interpret\_text}(p).\mathit{route\_names} = \operatorname{interpret\_server}(p).\mathit{registered\_route\_names} $$ + +يكشف هذا الانحراف الذي تفوته اللقطات المستقلة. وهو قيّم بوجه خاص لتعريفات API ومراحل المترجم وتمثيلات البيانات البديلة. + +## الدليل المحدود ليس برهانًا {#finite-evidence-is-not-proof} + +يثبت الاختبار الناجح السلوك للمدخلات والتنفيذات المختبرة، لكنه لا يثبت قانونًا لكل القيم. + +عزّز الثقة عمدًا: + +1. اختبارات الأمثلة +2. اختبارات سيناريو قابلة لإعادة الاستخدام +3. اختبارات خصائص مولّدة +4. فحوص شاملة على المجالات المنتهية +5. مقارنة النماذج +6. آثار البراهين + +اختر المستوى بحسب المخاطر وقوة الادعاء. + +## ينبغي لأسماء الاختبارات أن تصرح بالمعنى {#test-names-should-state-meaning} + +فضّل: + +* `reconstructs_every_generated_branch_from_its_root_path` +* `preserves_child_programs_when_routes_are_merged` +* `normalization_is_invariant_under_alpha_renaming` + +وتجنب الأسماء التي تسرد التنفيذ فحسب: + +* `pushes_three_bits` +* `calls_helper_twice` +* `visits_left_node_first` + +تظل الاختبارات التشغيلية صالحة عندما يكون ترتيب العمليات محددًا هو نفسه. سمِّ الملاحظة التي تجعل الترتيب ذا معنى. + +## فحوص المراجعة {#review-checks} + +* هل لكل عملية دلالية جديدة قانون أو تأكيد محدد الهدف؟ +* هل الالتزامات القابلة لإعادة الاستخدام عامة بالنسبة إلى القدرات العامة؟ +* هل السيناريوهات منفصلة عن المشغلات الملموسة؟ +* هل تُميّز القوانين الدلالية عن الثوابت التمثيلية؟ +* هل تُقارن مفسرات متعددة متى كان ذلك عمليًا؟ +* هل يتجنب التوثيق وصف الاختبارات المحدودة بأنها براهين؟ diff --git a/src/rust-dd/laws.de.md b/src/rust-dd/laws.de.md new file mode 100644 index 0000000..bac054e --- /dev/null +++ b/src/rust-dd/laws.de.md @@ -0,0 +1,187 @@ + + +# Gesetze, Szenarien und Nachweise {#laws-scenarios-and-evidence} + +```admonish tip title="Verwandte Themen" +The Semantic View: [Gesetze und Interpretationen](../denotational-design/laws-and-interpretations.md) +Design by Meaning in Rust: [Interpreter und Effekte](interpreters.md), [Capability-Algebren](capability-algebras.md) +Concepts: [Verzweigung und Konfluenz](../concepts/branching.md), [Referenzielle Transparenz](../concepts/referential_transparency.md) +``` + +```admonish note title="Orientierung" +Tests liefern Nachweise für eine Spezifikation. Prüfe die öffentlichen Beobachtungen und die Gesetze, die der gewählte Bereich unterstützt, nicht interne Ausführungsschritte. Formuliere diese Gesetze generisch über die Capability, damit sie für jeden Interpreter gelten. +``` + +Bedeutungsorientierter Code braucht bedeutungsorientierte Tests. Prüfe öffentliche Beobachtungen und Gesetze statt interner Ausführungsschritte. + +## Die Oberfläche der Spezifikation testen {#test-the-specification-surface} + +````admonish warning title="An die Repräsentation gekoppelter Test" +Diese Assertion greift auf die Felder eines Trägers zu, daher kann kein anderer Interpreter sie mitverwenden: + +```rust,noplayground +// not recommended: asserts a bit layout, not a semantic observation +assert_eq!(branch.bits, vec![false, true]); +``` +```` + +Semantischer Test: + +```rust,noplayground +let root = alg.branch_root(); +let left = alg.branch_left(&root); +let left_right = alg.branch_right(&left); + +assert_eq!(alg.branch_path(&root, &left_right), Some(vec![Direction::Left, Direction::Right])); +``` + +Der erste Test kann für ein Serialisierungsmodul passend sein, dessen Gegenstand die Bitkodierung ist. Als Nachweis für die Verzweigungsalgebra ist er schwach, da alternative Repräsentationen ihn nicht gemeinsam verwenden können. + +## Wiederverwendbare Gesetzeserweiterungen {#reusable-law-extensions} + +Gilt eine Eigenschaft für jeden kompatiblen Interpreter, formuliere sie einmal: + +```rust,noplayground +use anyhow::{Result, bail, ensure}; +use extend::ext; + +#[ext(name = BranchLawsExt)] +pub impl This +where + This: BranchAlg, + This::Branch: Clone + Eq, +{ + fn check_branch_root_round_trip(&self, directions: &[Direction]) -> Result<()> { + let root = self.branch_root(); + let branch = directions.iter().copied().fold(root.clone(), |branch, direction| self.branch_grow(&branch, direction)); + + let Some(path) = self.branch_path(&root, &branch) else { + bail!("grown branch has no path from root"); + }; + ensure!(path == directions, "root path did not round-trip"); + Ok(()) + } +} +``` + +Jeder Interpreter führt dieselbe Prüfung aus. `anyhow::Result` trägt das Ergebnis; `bail!` meldet die fehlende Beobachtung und `ensure!` prüft das Rundlaufgesetz. Die Prüfung unterscheidet die beiden Fehlerfälle, ohne von einer bestimmten Verzweigungsrepräsentation abzuhängen. + +## Nützliche Gesetzesfamilien {#useful-law-families} + +Suche nach Eigenschaften, die sich bereits aus der semantischen Struktur ergeben: + +* Identität +* Assoziativität +* Kommutativität, wenn sie tatsächlich beabsichtigt ist +* Idempotenz +* Rundlauf +* Kanonisierung +* Verfeinerung +* Monotonie +* Substitution +* Übereinstimmung der Interpretationen + +```admonish warning title="Nur Gesetze behaupten, die der Fachbereich trägt" +Füge keine vertrauten algebraischen Begriffe hinzu, nur weil sie mathematisch klingen. Formuliere nur Gesetze, die der gewählte Bereich unterstützt. +``` + +## Gesetze und Repräsentationsinvarianten {#laws-versus-representation-invariants} + +Halte diese Aussagen auseinander: + +* **Semantisches Gesetz:** Einen Zweig aus seinem Wurzelpfad zu rekonstruieren, bezeichnet denselben Zweig. + +* **Repräsentationsinvariante:** Ungenutzte hohe Bits sind null. + +* **Serialisierungsgesetz:** + + $$ \operatorname{decode}(\operatorname{encode}(b)) = b $$ + +* **Gesetz für kanonisches Format:** + + $$ \operatorname{encode}(\operatorname{decode}(x)) = x \qquad \text{for canonical byte sequences }x $$ + + +Alle können wichtig sein. Sie gehören jedoch zu unterschiedlichen Spezifikationen. + +## Gemeinsam genutzte Szenarien {#shared-scenarios} + +Ein Szenario ist eine wiederverwendbare Interaktion, formuliert über öffentliche Capabilities. Das ALUX-Testframework stellt Szenarien auf diese Weise dar: Der Szenariocode erstellt einen Wert über die Capabilities `Scenario`, `DeployerIds`, `PlayAst` und `ScenarioSchedule`, ohne einen konkreten Runner zu benennen. + +```rust,noplayground +#[ext(name = HelloScenarioExt)] +pub impl This +where + This: StandaloneScenario, + This::Step: PlayAst, +{ + fn hello(self) -> This::Scenario { + self.scenario() + .under_comprehensive(100) + .step( + self.play_ast( + self.deployer(0), + tolang! { + let x in { + x ! "hello" | + ? (a <- x) a.log() + } + }, + ) + .expect_log(r#""hello""#), + ) + } +} +``` + +Jeder Aufruf beschreibt die im Szenario festgelegte Bedeutung statt der Mechanik des Runners. `under_comprehensive(100)` verlangt das erwartete Protokoll bei einem sequenziellen Lauf, 100 frei nebenläufigen Läufen und bis zu 100 permutierten Läufen. Das Szenario legt die Beobachtung fest, während der Runner die Ausführungsreihenfolge variiert. + +Dasselbe Prinzip gilt über verschiedene Interpreter hinweg: Wenn mehrere Runner die in einem Szenario verwendeten Capabilities implementieren, kann jeder dieselbe vom Autor formulierte Interaktion interpretieren. Runner-spezifische Einrichtung und Prüfung der Grenzen bleiben außerhalb des Szenarios. + +## Übereinstimmung zwischen Interpretern {#cross-interpreter-agreement} + +Wenn zwei Interpreter dieselbe Beobachtung bereitstellen, vergleiche sie: + +$$ \operatorname{interpret\_text}(p).\mathit{route\_names} = \operatorname{interpret\_server}(p).\mathit{registered\_route\_names} $$ + +So wird eine Abweichung erkannt, die unabhängige Momentaufnahmen übersehen. Das ist besonders wertvoll für API-Definitionen, Compilerstufen und alternative Datenrepräsentationen. + +## Endliche Nachweise sind keine Beweise {#finite-evidence-is-not-proof} + +Ein erfolgreicher Test zeigt das Verhalten für die geprüften Eingaben und Implementierungen. Er beweist kein Gesetz für alle Werte. + +Erhöhe die Sicherheit gezielt: + +1. Beispieltests +2. wiederverwendbare Szenariotests +3. generierte Eigenschaftstests +4. erschöpfende Prüfungen über endliche Bereiche +5. Modellvergleiche +6. Beweisartefakte + +Wähle das Niveau entsprechend dem Risiko und der Stärke der Behauptung. + +## Testnamen sollten die Bedeutung nennen {#test-names-should-state-meaning} + +Bevorzuge: + +* `reconstructs_every_generated_branch_from_its_root_path` +* `preserves_child_programs_when_routes_are_merged` +* `normalization_is_invariant_under_alpha_renaming` + +Vermeide Namen, die nur die Implementierung beschreiben: + +* `pushes_three_bits` +* `calls_helper_twice` +* `visits_left_node_first` + +Operationale Tests bleiben gültig, wenn die Operationsreihenfolge selbst spezifiziert ist. Benenne die Beobachtung, durch die diese Reihenfolge relevant wird. + +## Prüfpunkte für das Review {#review-checks} + +* Hat jede neue semantische Operation ein gezieltes Gesetz oder eine Assertion? +* Sind wiederverwendbare Anforderungen generisch über öffentliche Capabilities formuliert? +* Sind Szenarien von konkreten Runnern getrennt? +* Sind semantische Gesetze von Repräsentationsinvarianten unterschieden? +* Werden mehrere Interpreter dort verglichen, wo es praktisch ist? +* Vermeidet die Dokumentation, endliche Tests als Beweise zu bezeichnen? diff --git a/src/rust-dd/laws.es.md b/src/rust-dd/laws.es.md new file mode 100644 index 0000000..2464768 --- /dev/null +++ b/src/rust-dd/laws.es.md @@ -0,0 +1,187 @@ + + +# Leyes, escenarios y evidencia {#laws-scenarios-and-evidence} + +```admonish tip title="Relacionado" +La perspectiva semántica: [Leyes e interpretaciones](../denotational-design/laws-and-interpretations.md) +Diseño por significado en Rust: [Intérpretes y efectos](interpreters.md), [Álgebras de capacidades](capability-algebras.md) +Conceptos: [Ramificación y confluencia](../concepts/branching.md), [Transparencia referencial](../concepts/referential_transparency.md) +``` + +```admonish note title="Orientación" +Los tests son evidencia para una especificación. Comprueba las observaciones públicas y las leyes que admite el dominio elegido, no los pasos privados de ejecución, y expresa esas leyes de forma genérica sobre la capacidad para que rijan todos los intérpretes. +``` + +El código centrado en el significado necesita tests centrados en el significado. Comprueba las observaciones públicas y las leyes, no los pasos privados de ejecución. + +## Prueba la superficie de la especificación {#test-the-specification-surface} + +````admonish warning title="Test acoplado a la representación" +Esta aserción accede a los campos de un portador, así que ningún otro intérprete puede reutilizarla: + +```rust,noplayground +// not recommended: asserts a bit layout, not a semantic observation +assert_eq!(branch.bits, vec![false, true]); +``` +```` + +Test semántico: + +```rust,noplayground +let root = alg.branch_root(); +let left = alg.branch_left(&root); +let left_right = alg.branch_right(&left); + +assert_eq!(alg.branch_path(&root, &left_right), Some(vec![Direction::Left, Direction::Right])); +``` + +El primer test puede ser apropiado para un módulo de serialización cuyo objeto sea la codificación de bits. Es evidencia débil para el álgebra de ramificación, porque las representaciones alternativas no pueden compartirlo. + +## Extensiones de leyes reutilizables {#reusable-law-extensions} + +Cuando una propiedad se aplica a todos los intérpretes compatibles, escríbela una sola vez: + +```rust,noplayground +use anyhow::{Result, bail, ensure}; +use extend::ext; + +#[ext(name = BranchLawsExt)] +pub impl This +where + This: BranchAlg, + This::Branch: Clone + Eq, +{ + fn check_branch_root_round_trip(&self, directions: &[Direction]) -> Result<()> { + let root = self.branch_root(); + let branch = directions.iter().copied().fold(root.clone(), |branch, direction| self.branch_grow(&branch, direction)); + + let Some(path) = self.branch_path(&root, &branch) else { + bail!("grown branch has no path from root"); + }; + ensure!(path == directions, "root path did not round-trip"); + Ok(()) + } +} +``` + +Todos los intérpretes ejecutan el mismo comprobador. `anyhow::Result` transporta el resultado; `bail!` informa de la observación ausente, mientras `ensure!` comprueba la ley de ida y vuelta. El comprobador distingue los dos fallos sin depender de una representación de ramificación concreta. + +## Familias de leyes útiles {#useful-law-families} + +Busca propiedades que ya sugiera la estructura semántica: + +* identidad +* asociatividad +* conmutatividad, cuando realmente se pretenda +* idempotencia +* ida y vuelta +* canonización +* refinamiento +* monotonía +* sustitución +* acuerdo entre interpretaciones + +```admonish warning title="Afirma solo las leyes que admite el dominio" +No añadas términos algebraicos conocidos solo porque suenen matemáticos. Enuncia únicamente las leyes que admite el dominio elegido. +``` + +## Leyes frente a invariantes de representación {#laws-versus-representation-invariants} + +Manténlos diferenciados: + +* **Ley semántica:** reconstruir una rama a partir de su camino desde la raíz denota la misma rama. + +* **Invariante de representación:** los bits altos no utilizados son cero. + +* **Ley de serialización:** + + $$ \operatorname{decode}(\operatorname{encode}(b)) = b $$ + +* **Ley de formato canónico:** + + $$ \operatorname{encode}(\operatorname{decode}(x)) = x \qquad \text{for canonical byte sequences }x $$ + + +Todas pueden ser importantes. Pertenecen a especificaciones distintas. + +## Escenarios compartidos {#shared-scenarios} + +Un escenario es una interacción reutilizable escrita contra capacidades públicas. El framework de pruebas de ALUX representa los escenarios así: el código autor construye un valor mediante las capacidades `Scenario`, `DeployerIds`, `PlayAst` y `ScenarioSchedule` sin nombrar un ejecutor concreto. + +```rust,noplayground +#[ext(name = HelloScenarioExt)] +pub impl This +where + This: StandaloneScenario, + This::Step: PlayAst, +{ + fn hello(self) -> This::Scenario { + self.scenario() + .under_comprehensive(100) + .step( + self.play_ast( + self.deployer(0), + tolang! { + let x in { + x ! "hello" | + ? (a <- x) a.log() + } + }, + ) + .expect_log(r#""hello""#), + ) + } +} +``` + +Cada llamada describe el significado definido por el autor, no los mecanismos del ejecutor. `under_comprehensive(100)` exige el registro esperado en una ejecución secuencial, 100 ejecuciones concurrentes sin restricciones y hasta 100 ejecuciones con permutaciones. El escenario fija la observación mientras el ejecutor varía el orden de ejecución. + +El mismo principio se aplica entre intérpretes: si varios ejecutores implementan las capacidades que usa un escenario, cada uno puede interpretar la misma interacción escrita. La configuración específica del ejecutor y la inspección de límites quedan fuera del escenario. + +## Concordancia entre intérpretes {#cross-interpreter-agreement} + +Cuando dos intérpretes exponen la misma observación, compáralos: + +$$ \operatorname{interpret\_text}(p).\mathit{route\_names} = \operatorname{interpret\_server}(p).\mathit{registered\_route\_names} $$ + +Esto detecta desviaciones que pasan inadvertidas en instantáneas independientes. Resulta especialmente valioso para definiciones de API, fases del compilador y representaciones de datos alternativas. + +## La evidencia finita no es una prueba {#finite-evidence-is-not-proof} + +Un test aprobado demuestra el comportamiento para las entradas y las implementaciones probadas. No demuestra una ley para todos los valores. + +Aumenta deliberadamente el nivel de garantía: + +1. tests de ejemplo +2. tests de escenarios reutilizables +3. tests de propiedades generados +4. comprobaciones exhaustivas sobre dominios finitos +5. comparación de modelos +6. artefactos de prueba formal + +Elige el nivel según el riesgo y la fuerza de la afirmación. + +## Los nombres de los tests deben expresar significado {#test-names-should-state-meaning} + +Prefiere: + +* `reconstructs_every_generated_branch_from_its_root_path` +* `preserves_child_programs_when_routes_are_merged` +* `normalization_is_invariant_under_alpha_renaming` + +Evita nombres que solo narren la implementación: + +* `pushes_three_bits` +* `calls_helper_twice` +* `visits_left_node_first` + +Los tests operacionales siguen siendo válidos cuando el orden de las operaciones está especificado. Nombra la observación que hace significativo ese orden. + +## Comprobaciones de revisión {#review-checks} + +* ¿Cada operación semántica nueva tiene una ley o aserción específica? +* ¿Las obligaciones reutilizables son genéricas respecto a las capacidades públicas? +* ¿Los escenarios están separados de los ejecutores concretos? +* ¿Se distinguen las leyes semánticas de los invariantes de representación? +* ¿Se comparan varios intérpretes cuando es práctico? +* ¿La documentación evita llamar pruebas a los tests finitos? diff --git a/src/rust-dd/laws.ja.md b/src/rust-dd/laws.ja.md new file mode 100644 index 0000000..283e41d --- /dev/null +++ b/src/rust-dd/laws.ja.md @@ -0,0 +1,187 @@ + + +# 法則、シナリオ、証拠 {#laws-scenarios-and-evidence} + +```admonish tip title="関連項目" +意味論的な見方:[法則と解釈](../denotational-design/laws-and-interpretations.md) +Rustで意味から設計する:[インタープリターと副作用](interpreters.md)、[ケイパビリティ代数](capability-algebras.md) +概念:[分岐と合流性](../concepts/branching.md)、[参照透過性](../concepts/referential_transparency.md) +``` + +```admonish note title="概要" +テストは仕様を裏付ける証拠です。非公開の実行手順ではなく、公開された観測と、選択した領域が支える法則を検査します。また、すべてのインタープリターに同じ要求を課せるよう、法則はケイパビリティに対してジェネリックに保ちます。 +``` + +意味を第一に考えるコードには、意味を第一に考えるテストが必要です。非公開の実行手順ではなく、公開された観測と法則をテストします。 + +## 仕様の表面をテストする {#test-the-specification-surface} + +````admonish warning title="表現に結び付いたテスト" +このアサーションは一つの担体のフィールドを調べるため、ほかのインタープリターと共有できません。 + +```rust,noplayground +// not recommended: asserts a bit layout, not a semantic observation +assert_eq!(branch.bits, vec![false, true]); +``` +```` + +意味論的なテスト: + +```rust,noplayground +let root = alg.branch_root(); +let left = alg.branch_left(&root); +let left_right = alg.branch_right(&left); + +assert_eq!(alg.branch_path(&root, &left_right), Some(vec![Direction::Left, Direction::Right])); +``` + +ビット符号化を対象とするシリアライズモジュールなら、最初のテストが適切な場合もあります。しかし別の表現と共有できないため、分岐代数を裏付ける証拠としては弱いものです。 + +## 再利用可能な法則拡張 {#reusable-law-extensions} + +すべての互換インタープリターに当てはまる性質は、一度だけ記述します。 + +```rust,noplayground +use anyhow::{Result, bail, ensure}; +use extend::ext; + +#[ext(name = BranchLawsExt)] +pub impl This +where + This: BranchAlg, + This::Branch: Clone + Eq, +{ + fn check_branch_root_round_trip(&self, directions: &[Direction]) -> Result<()> { + let root = self.branch_root(); + let branch = directions.iter().copied().fold(root.clone(), |branch, direction| self.branch_grow(&branch, direction)); + + let Some(path) = self.branch_path(&root, &branch) else { + bail!("grown branch has no path from root"); + }; + ensure!(path == directions, "root path did not round-trip"); + Ok(()) + } +} +``` + +すべてのインタープリターで同じチェッカーを実行します。`anyhow::Result`は結果を運び、`bail!`は不足している観測を報告し、`ensure!`は往復法則を検査します。チェッカーは分岐表現に依存せず、二種類の失敗を区別します。 + +## 有用な法則の類型 {#useful-law-families} + +意味論的な構造から導かれる性質を探します。 + +* 恒等性 +* 結合性 +* 意図が真にある場合の可換性 +* 冪等性 +* 往復性 +* 正準化 +* 精緻化 +* 単調性 +* 置換 +* 解釈の一致 + +```admonish warning title="領域が支える法則だけを主張する" +数学的に聞こえるからといって、馴染みのある代数用語を加えないでください。選択した領域が支える法則だけを述べます。 +``` + +## 法則と表現不変条件 {#laws-versus-representation-invariants} + +次のものを区別します。 + +* 意味論的法則:根からの経路を使って分岐を再構成すると、同じ分岐を表す。 + +* 表現不変条件:未使用の上位ビットはゼロである。 + +* **シリアライズ法則:** + + $$ \operatorname{decode}(\operatorname{encode}(b)) = b $$ + +* **正準形式の法則:** + + $$ \operatorname{encode}(\operatorname{decode}(x)) = x \qquad \text{for canonical byte sequences }x $$ + + +どれも重要な場合がありますが、別々の仕様に属します。 + +## 共有シナリオ {#shared-scenarios} + +シナリオは、公開ケイパビリティに対して記述した、再利用可能な相互作用です。ALUXのテストフレームワークでは、シナリオの記述コードが`Scenario`、`DeployerIds`、`PlayAst`、`ScenarioSchedule`のケイパビリティを使って値を構築し、具体的なランナー名を指定しません。 + +```rust,noplayground +#[ext(name = HelloScenarioExt)] +pub impl This +where + This: StandaloneScenario, + This::Step: PlayAst, +{ + fn hello(self) -> This::Scenario { + self.scenario() + .under_comprehensive(100) + .step( + self.play_ast( + self.deployer(0), + tolang! { + let x in { + x ! "hello" | + ? (a <- x) a.log() + } + }, + ) + .expect_log(r#""hello""#), + ) + } +} +``` + +各呼び出しは、ランナーの仕組みではなく記述された意味を表します。`under_comprehensive(100)`は、逐次実行100回、自由な並行実行100回、順列を変えた実行を最大100回行った場合に、期待するログが得られることを要求します。シナリオは観測内容を固定し、ランナーが実行順序を変えます。 + +同じ原則はインタープリター間にも当てはまります。シナリオが使うケイパビリティを複数のランナーが実装するなら、同じ記述上の相互作用をそれぞれ解釈できます。ランナー固有の準備や境界の検査は、シナリオの外に置きます。 + +## インタープリター間の一致 {#cross-interpreter-agreement} + +二つのインタープリターが同じ観測を公開するなら、比較します。 + +$$ \operatorname{interpret\_text}(p).\mathit{route\_names} = \operatorname{interpret\_server}(p).\mathit{registered\_route\_names} $$ + +こうすると、個別のスナップショットでは見つからないずれを検出できます。API定義、コンパイラーの各段階、代替データ表現で特に有用です。 + +## 有限の証拠は証明ではない {#finite-evidence-is-not-proof} + +テストに合格しても、試した入力と実装で振る舞いが示されたにすぎません。すべての値について法則を証明するものではありません。 + +意図的に確実性を高めます。 + +1. 例示テスト +2. 再利用可能なシナリオテスト +3. 生成データを使うプロパティテスト +4. 有限領域の網羅検査 +5. モデル比較 +6. 証明の成果物 + +リスクと主張の強さに応じて水準を選びます。 + +## テスト名で意味を示す {#test-names-should-state-meaning} + +次のような名前を優先します。 + +* `reconstructs_every_generated_branch_from_its_root_path` +* `preserves_child_programs_when_routes_are_merged` +* `normalization_is_invariant_under_alpha_renaming` + +実装手順を説明するだけの名前は避けます。 + +* `pushes_three_bits` +* `calls_helper_twice` +* `visits_left_node_first` + +操作順そのものが仕様である場合、操作上のテストは有効です。その順序に意味が生じる観測を名前で示します。 + +## レビュー時の確認 {#review-checks} + +* 新たな意味論的操作ごとに、焦点を絞った法則またはアサーションがあるか。 +* 再利用可能な責務を公開ケイパビリティに対してジェネリックにしているか。 +* シナリオと具体的なランナーを分けているか。 +* 意味論的法則と表現不変条件を区別しているか。 +* 実用的な範囲で複数のインタープリターを比較しているか。 +* 有限テストを証明と呼ばないよう、ドキュメントで注意しているか。 diff --git a/src/rust-dd/laws.ko.md b/src/rust-dd/laws.ko.md new file mode 100644 index 0000000..8bf99a6 --- /dev/null +++ b/src/rust-dd/laws.ko.md @@ -0,0 +1,187 @@ + + +# 법칙, 시나리오, 증거 {#laws-scenarios-and-evidence} + +```admonish tip title="관련 항목" +의미론적 관점: [법칙과 해석](../denotational-design/laws-and-interpretations.md) +Rust에서 의미로 설계하기: [인터프리터와 효과](interpreters.md), [케이퍼빌리티 대수](capability-algebras.md) +개념: [분기와 합류성](../concepts/branching.md), [참조 투명성](../concepts/referential_transparency.md) +``` + +```admonish note title="개요" +테스트는 명세를 뒷받침하는 증거입니다. 비공개 실행 단계를 검사하기보다 공개 관찰과 선택한 영역이 뒷받침하는 법칙을 단언하고, 모든 인터프리터에 같은 법칙을 적용할 수 있도록 케이퍼빌리티에 대해 제네릭하게 작성하세요. +``` + +의미 우선 코드에는 의미 우선 테스트가 필요합니다. 비공개 실행 단계가 아니라 공개 관찰과 법칙을 테스트하세요. + +## 명세의 표면을 테스트하기 {#test-the-specification-surface} + +````admonish warning title="표현에 결합된 테스트" +이 단언은 기반 집합 하나의 필드에 접근하므로 다른 인터프리터가 재사용할 수 없습니다: + +```rust,noplayground +// not recommended: asserts a bit layout, not a semantic observation +assert_eq!(branch.bits, vec![false, true]); +``` +```` + +의미론적 테스트: + +```rust,noplayground +let root = alg.branch_root(); +let left = alg.branch_left(&root); +let left_right = alg.branch_right(&left); + +assert_eq!(alg.branch_path(&root, &left_right), Some(vec![Direction::Left, Direction::Right])); +``` + +비트 인코딩을 대상으로 하는 직렬화 모듈이라면 첫 번째 테스트가 적절할 수 있습니다. 그러나 대안적 표현이 공유할 수 없으므로 분기 대수의 증거로는 약합니다. + +## 재사용 가능한 법칙 확장 {#reusable-law-extensions} + +호환되는 모든 인터프리터에 적용되는 속성이라면 한 번만 작성하세요: + +```rust,noplayground +use anyhow::{Result, bail, ensure}; +use extend::ext; + +#[ext(name = BranchLawsExt)] +pub impl This +where + This: BranchAlg, + This::Branch: Clone + Eq, +{ + fn check_branch_root_round_trip(&self, directions: &[Direction]) -> Result<()> { + let root = self.branch_root(); + let branch = directions.iter().copied().fold(root.clone(), |branch, direction| self.branch_grow(&branch, direction)); + + let Some(path) = self.branch_path(&root, &branch) else { + bail!("grown branch has no path from root"); + }; + ensure!(path == directions, "root path did not round-trip"); + Ok(()) + } +} +``` + +모든 인터프리터가 같은 검사기를 실행합니다. `anyhow::Result`는 결과를 전달하고, `bail!`는 누락된 관찰을 알리며, `ensure!`는 왕복 법칙을 확인합니다. 검사기는 특정 분기 표현에 의존하지 않고 두 오류를 구분합니다. + +## 유용한 법칙 계열 {#useful-law-families} + +의미 구조에서 이미 암시되는 속성을 찾아보세요: + +* 항등성 +* 결합성 +* 실제로 의도된 경우의 교환성 +* 멱등성 +* 왕복 법칙 +* 정규화 +* 세분화 +* 단조성 +* 치환 +* 해석의 일치 + +```admonish warning title="영역이 뒷받침하는 법칙만 주장하세요" +익숙하고 수학적으로 들린다는 이유로 흔한 대수 용어를 끼워 넣지 마세요. 선택한 영역이 뒷받침하는 법칙만 명시하세요. +``` + +## 법칙과 표현 불변량 {#laws-versus-representation-invariants} + +다음을 구분하세요: + +* **의미론적 법칙:** 루트 경로에서 분기를 재구성하면 같은 분기를 나타냅니다. + +* **표현 불변량:** 사용하지 않는 상위 비트는 0입니다. + +* **직렬화 법칙:** + + $$ \operatorname{decode}(\operatorname{encode}(b)) = b $$ + +* **정규 형식 법칙:** + + $$ \operatorname{encode}(\operatorname{decode}(x)) = x \qquad \text{for canonical byte sequences }x $$ + + +모두 중요할 수 있지만 서로 다른 명세에 속합니다. + +## 공유 시나리오 {#shared-scenarios} + +시나리오는 공개 케이퍼빌리티를 사용해 작성한 재사용 가능한 상호작용입니다. ALUX 테스트 프레임워크도 이러한 방식으로 시나리오를 표현합니다. 작성 코드는 구체적인 실행기를 지정하지 않고 `Scenario`, `DeployerIds`, `PlayAst`, `ScenarioSchedule` 케이퍼빌리티를 통해 값을 구성합니다. + +```rust,noplayground +#[ext(name = HelloScenarioExt)] +pub impl This +where + This: StandaloneScenario, + This::Step: PlayAst, +{ + fn hello(self) -> This::Scenario { + self.scenario() + .under_comprehensive(100) + .step( + self.play_ast( + self.deployer(0), + tolang! { + let x in { + x ! "hello" | + ? (a <- x) a.log() + } + }, + ) + .expect_log(r#""hello""#), + ) + } +} +``` + +호출할 때마다 실행기 장치가 아니라 작성된 의미를 나타냅니다. `under_comprehensive(100)`은 순차 실행 1회, 완전히 동시인 실행 100회, 순서를 섞은 실행 최대 100회에서 예상 로그를 요구합니다. 시나리오가 관찰을 고정하고 실행기는 실행 순서를 바꿉니다. + +같은 원칙은 인터프리터 간에도 적용됩니다. 시나리오에서 사용하는 케이퍼빌리티를 여러 실행기가 구현한다면 같은 작성 상호작용을 각각 해석할 수 있습니다. 실행기별 설정과 경계 검사는 시나리오 밖에 둡니다. + +## 인터프리터 간 일치 {#cross-interpreter-agreement} + +두 인터프리터가 같은 관찰을 제공할 때는 서로 비교하세요: + +$$ \operatorname{interpret\_text}(p).\mathit{route\_names} = \operatorname{interpret\_server}(p).\mathit{registered\_route\_names} $$ + +이 방식은 별도로 만든 스냅샷만으로는 찾지 못하는 차이를 포착합니다. API 정의, 컴파일러 단계, 대안 데이터 표현에서 특히 유용합니다. + +## 유한한 증거는 증명이 아닙니다 {#finite-evidence-is-not-proof} + +테스트 통과는 검사한 입력과 구현의 동작을 보여 줍니다. 모든 값에 대한 법칙을 증명하지는 않습니다. + +필요한 보증 수준을 의도적으로 높이세요: + +1. 예제 테스트 +2. 재사용 가능한 시나리오 테스트 +3. 생성 기반 속성 테스트 +4. 유한 영역 전수 검사 +5. 모델 비교 +6. 증명 산출물 + +위험과 주장의 강도에 따라 수준을 선택하세요. + +## 테스트 이름에 의미를 담으세요 {#test-names-should-state-meaning} + +다음과 같은 이름을 선호하세요: + +* `reconstructs_every_generated_branch_from_its_root_path` +* `preserves_child_programs_when_routes_are_merged` +* `normalization_is_invariant_under_alpha_renaming` + +구현만 설명하는 이름은 피하세요: + +* `pushes_three_bits` +* `calls_helper_twice` +* `visits_left_node_first` + +연산 순서 자체가 명세에 포함될 때는 작동 테스트도 유효합니다. 그 순서를 의미 있게 만드는 관찰에 이름을 붙이세요. + +## 검토 항목 {#review-checks} + +* 새 의미 연산마다 집중된 법칙이나 단언이 있나요? +* 재사용 가능한 의무를 공개 케이퍼빌리티에 대해 제네릭하게 표현했나요? +* 시나리오를 구체적인 실행기와 분리했나요? +* 의미론적 법칙과 표현 불변량을 구분했나요? +* 실용적인 경우 여러 인터프리터를 비교하나요? +* 문서에서 유한 테스트를 증명이라고 부르지 않나요? diff --git a/src/rust-dd/laws.ru.md b/src/rust-dd/laws.ru.md new file mode 100644 index 0000000..bf4d30e --- /dev/null +++ b/src/rust-dd/laws.ru.md @@ -0,0 +1,187 @@ + + +# Законы, сценарии и свидетельства {#laws-scenarios-and-evidence} + +```admonish tip title="Связанные материалы" +«Семантический взгляд»: [Законы и интерпретации](../denotational-design/laws-and-interpretations.md) +«Проектирование на основе смысла в Rust»: [Интерпретаторы и эффекты](interpreters.md), [Алгебры возможностей](capability-algebras.md) +«Понятия»: [Ветвление и конфлюэнтность](../concepts/branching.md), [Референциальная прозрачность](../concepts/referential_transparency.md) +``` + +```admonish note title="Обзор" +Тесты служат свидетельствами в поддержку спецификации. Проверяйте публично наблюдаемые свойства и законы выбранной предметной области, а не скрытые шаги выполнения; формулируйте законы обобщённо для возможности, чтобы они действовали для каждого интерпретатора. +``` + +Код, ставящий смысл на первое место, требует таких же тестов. Проверяйте публичные наблюдения и законы, а не скрытые шаги выполнения. + +## Тестируйте поверхность спецификации {#test-the-specification-surface} + +````admonish warning title="Тест, связанный с представлением" +Это утверждение обращается к полям одного носителя, поэтому его нельзя использовать с другими интерпретаторами: + +```rust,noplayground +// not recommended: asserts a bit layout, not a semantic observation +assert_eq!(branch.bits, vec![false, true]); +``` +```` + +Семантический тест: + +```rust,noplayground +let root = alg.branch_root(); +let left = alg.branch_left(&root); +let left_right = alg.branch_right(&left); + +assert_eq!(alg.branch_path(&root, &left_right), Some(vec![Direction::Left, Direction::Right])); +``` + +Первый тест может подойти модулю сериализации, проверяющему кодирование битов. Но для алгебры ветвления это слабое свидетельство, поскольку альтернативные представления не могут использовать такой тест. + +## Повторно используемые расширения с законами {#reusable-law-extensions} + +Если свойство применимо ко всем совместимым интерпретаторам, задайте его один раз: + +```rust,noplayground +use anyhow::{Result, bail, ensure}; +use extend::ext; + +#[ext(name = BranchLawsExt)] +pub impl This +where + This: BranchAlg, + This::Branch: Clone + Eq, +{ + fn check_branch_root_round_trip(&self, directions: &[Direction]) -> Result<()> { + let root = self.branch_root(); + let branch = directions.iter().copied().fold(root.clone(), |branch, direction| self.branch_grow(&branch, direction)); + + let Some(path) = self.branch_path(&root, &branch) else { + bail!("grown branch has no path from root"); + }; + ensure!(path == directions, "root path did not round-trip"); + Ok(()) + } +} +``` + +Каждый интерпретатор запускает одну и ту же проверку. `anyhow::Result` содержит результат; `bail!` сообщает об отсутствующем наблюдении, а `ensure!` проверяет закон обратного преобразования. Проверка различает два сбоя и не зависит от конкретного представления ветви. + +## Полезные семейства законов {#useful-law-families} + +Ищите свойства, уже подсказываемые семантической структурой: + +* тождественность +* ассоциативность +* коммутативность, если она действительно предполагается +* идемпотентность +* обратное преобразование +* канонизация +* уточнение +* монотонность +* подстановка +* согласование интерпретаций + +```admonish warning title="Утверждайте только те законы, которые допускает предметная область" +Не добавляйте привычные алгебраические термины только потому, что они звучат математически. Формулируйте только те законы, которые допускает выбранная предметная область. +``` + +## Законы и инварианты представления {#laws-versus-representation-invariants} + +Различайте следующие понятия: + +* **Семантический закон:** ветвь, восстановленная по пути от корня, обозначает ту же ветвь. + +* **Инвариант представления:** неиспользуемые старшие биты равны нулю. + +* **Закон сериализации:** + + $$ \operatorname{decode}(\operatorname{encode}(b)) = b $$ + +* **Закон канонического формата:** + + $$ \operatorname{encode}(\operatorname{decode}(x)) = x \qquad \text{for canonical byte sequences }x $$ + + +Все эти положения могут быть важны, но относятся к разным спецификациям. + +## Общие сценарии {#shared-scenarios} + +Сценарий — это повторно используемое взаимодействие, описанное через публичные возможности. Тестовая среда ALUX представляет сценарии именно так: код автора создаёт значение с помощью возможностей `Scenario`, `DeployerIds`, `PlayAst` и `ScenarioSchedule`, не указывая конкретный исполнитель. + +```rust,noplayground +#[ext(name = HelloScenarioExt)] +pub impl This +where + This: StandaloneScenario, + This::Step: PlayAst, +{ + fn hello(self) -> This::Scenario { + self.scenario() + .under_comprehensive(100) + .step( + self.play_ast( + self.deployer(0), + tolang! { + let x in { + x ! "hello" | + ? (a <- x) a.log() + } + }, + ) + .expect_log(r#""hello""#), + ) + } +} +``` + +Каждый вызов описывает смысл, заданный автором, а не механизмы исполнителя. `under_comprehensive(100)` требует ожидаемый журнал при одном последовательном запуске, 100 полностью параллельных запусках и до 100 запусков с перестановкой порядка. Сценарий фиксирует наблюдение, а исполнитель меняет порядок выполнения. + +Тот же принцип действует для разных интерпретаторов: если несколько исполнителей реализуют возможности, используемые сценарием, каждый может интерпретировать одно и то же заданное взаимодействие. Настройка конкретного исполнителя и проверка его границ остаются за пределами сценария. + +## Согласование разных интерпретаторов {#cross-interpreter-agreement} + +Если два интерпретатора предоставляют одно и то же наблюдение, сравните их: + +$$ \operatorname{interpret\_text}(p).\mathit{route\_names} = \operatorname{interpret\_server}(p).\mathit{registered\_route\_names} $$ + +Это выявляет дрейф, который не заметен при сравнении независимых снимков. Особенно полезно для определений API, этапов компилятора и альтернативных представлений данных. + +## Конечное свидетельство — не доказательство {#finite-evidence-is-not-proof} + +Успешный тест демонстрирует поведение на проверенных входах и реализациях, но не доказывает закон для всех значений. + +Повышайте уверенность осознанно: + +1. тесты на примерах +2. тесты на повторно используемых сценариях +3. генерируемые тесты свойств +4. исчерпывающие проверки конечных областей +5. сравнение моделей +6. артефакты доказательств + +Выбирайте уровень в соответствии с риском и силой утверждения. + +## Названия тестов должны выражать смысл {#test-names-should-state-meaning} + +Предпочитайте: + +* `reconstructs_every_generated_branch_from_its_root_path` +* `preserves_child_programs_when_routes_are_merged` +* `normalization_is_invariant_under_alpha_renaming` + +Избегайте названий, которые лишь описывают реализацию: + +* `pushes_three_bits` +* `calls_helper_twice` +* `visits_left_node_first` + +Операционные тесты уместны, если порядок операций сам задан спецификацией. Называйте наблюдение, которое делает этот порядок значимым. + +## Проверочные вопросы {#review-checks} + +* Для каждой новой семантической операции есть отдельный закон или утверждение? +* Сформулированы ли повторно используемые обязательства обобщённо через публичные возможности? +* Отделены ли сценарии от конкретных исполнителей? +* Отличаются ли семантические законы от инвариантов представления? +* Сравниваются ли несколько интерпретаторов, когда это практически возможно? +* Не называют ли документы конечные тесты доказательствами? diff --git a/src/rust-dd/laws.uk.md b/src/rust-dd/laws.uk.md new file mode 100644 index 0000000..c8ab924 --- /dev/null +++ b/src/rust-dd/laws.uk.md @@ -0,0 +1,187 @@ + + +# Закони, сценарії та свідчення {#laws-scenarios-and-evidence} + +```admonish tip title="Пов’язані матеріали" +Семантичний погляд: [Закони та інтерпретації](../denotational-design/laws-and-interpretations.md) +Проєктування від значення в Rust: [Інтерпретатори й ефекти](interpreters.md), [Алгебри можливостей](capability-algebras.md) +Поняття: [Розгалуження та конфлюентність](../concepts/branching.md), [Референційна прозорість](../concepts/referential_transparency.md) +``` + +```admonish note title="Вступний огляд" +Тести надають свідчення на підтримку специфікації. Перевіряйте публічні спостереження й закони, допустимі для вибраної предметної області, а не внутрішні кроки виконання; формулюйте закони узагальнено для можливості, щоб вони поширювалися на кожен інтерпретатор. +``` + +У коді, орієнтованому на значення, і тести мають бути орієнтовані на значення. Перевіряйте публічні спостереження й закони, а не внутрішні кроки виконання. + +## Тестуйте поверхню специфікації {#test-the-specification-surface} + +````admonish warning title="Тест, прив’язаний до представлення" +Це твердження звертається до полів одного носія, тому інший інтерпретатор не зможе його використати: + +```rust,noplayground +// not recommended: asserts a bit layout, not a semantic observation +assert_eq!(branch.bits, vec![false, true]); +``` +```` + +Семантичний тест: + +```rust,noplayground +let root = alg.branch_root(); +let left = alg.branch_left(&root); +let left_right = alg.branch_right(&left); + +assert_eq!(alg.branch_path(&root, &left_right), Some(vec![Direction::Left, Direction::Right])); +``` + +Перший тест може бути доречним для модуля серіалізації, що перевіряє кодування бітів. Але як свідчення для алгебри розгалужень він слабкий, адже альтернативні представлення не можуть використовувати його спільно. + +## Повторно використовувані розширення законів {#reusable-law-extensions} + +Якщо властивість стосується кожного сумісного інтерпретатора, визначте її один раз: + +```rust,noplayground +use anyhow::{Result, bail, ensure}; +use extend::ext; + +#[ext(name = BranchLawsExt)] +pub impl This +where + This: BranchAlg, + This::Branch: Clone + Eq, +{ + fn check_branch_root_round_trip(&self, directions: &[Direction]) -> Result<()> { + let root = self.branch_root(); + let branch = directions.iter().copied().fold(root.clone(), |branch, direction| self.branch_grow(&branch, direction)); + + let Some(path) = self.branch_path(&root, &branch) else { + bail!("grown branch has no path from root"); + }; + ensure!(path == directions, "root path did not round-trip"); + Ok(()) + } +} +``` + +Кожен інтерпретатор запускає той самий перевіряльник. `anyhow::Result` містить результат: `bail!` повідомляє про відсутнє спостереження, а `ensure!` перевіряє закон зворотного перетворення. Перевіряльник розрізняє ці два збої без залежності від конкретного представлення гілок. + +## Корисні групи законів {#useful-law-families} + +Шукайте властивості, на які вже вказує семантична структура: + +* тотожність +* асоціативність +* комутативність, якщо вона справді задумана +* ідемпотентність +* зворотне перетворення +* канонізація +* уточнення +* монотонність +* підстановка +* узгодженість інтерпретацій + +```admonish warning title="Заявляйте лише закони, допустимі для предметної області" +Не додавайте звичні алгебраїчні терміни лише тому, що вони звучать математично. Формулюйте тільки закони, допустимі для вибраної предметної області. +``` + +## Закони та інваріанти представлення {#laws-versus-representation-invariants} + +Чітко розрізняйте: + +* **Семантичний закон:** відновлення гілки за шляхом від її кореня позначає ту саму гілку. + +* **Інваріант представлення:** невикористані старші біти дорівнюють нулю. + +* **Закон серіалізації:** + + $$ \operatorname{decode}(\operatorname{encode}(b)) = b $$ + +* **Закон канонічного формату:** + + $$ \operatorname{encode}(\operatorname{decode}(x)) = x \qquad \text{for canonical byte sequences }x $$ + + +Усі вони можуть бути важливими, але належать до різних специфікацій. + +## Спільні сценарії {#shared-scenarios} + +Сценарій — це повторно використовувана взаємодія, сформульована через публічні можливості. Тестовий фреймворк ALUX саме так представляє сценарії: авторський код створює значення за допомогою можливостей `Scenario`, `DeployerIds`, `PlayAst` та `ScenarioSchedule`, не прив’язуючись до конкретного виконавця тестів. + +```rust,noplayground +#[ext(name = HelloScenarioExt)] +pub impl This +where + This: StandaloneScenario, + This::Step: PlayAst, +{ + fn hello(self) -> This::Scenario { + self.scenario() + .under_comprehensive(100) + .step( + self.play_ast( + self.deployer(0), + tolang! { + let x in { + x ! "hello" | + ? (a <- x) a.log() + } + }, + ) + .expect_log(r#""hello""#), + ) + } +} +``` + +Кожен виклик описує задумане значення, а не механізми виконавця. `under_comprehensive(100)` вимагає очікуваного журналу для одного послідовного запуску, 100 незалежно паралельних запусків і до 100 запусків у зміненому порядку. Сценарій фіксує спостереження, а виконавець змінює порядок виконання. + +Той самий принцип діє для різних інтерпретаторів: якщо кілька виконавців реалізують потрібні сценарію можливості, кожен може інтерпретувати ту саму описану взаємодію. Налаштування, специфічне для виконавця, та перевірка меж залишаються за межами сценарію. + +## Узгодженість між інтерпретаторами {#cross-interpreter-agreement} + +Якщо два інтерпретатори надають те саме спостереження, порівняйте їх: + +$$ \operatorname{interpret\_text}(p).\mathit{route\_names} = \operatorname{interpret\_server}(p).\mathit{registered\_route\_names} $$ + +Це виявляє відхилення, яких не помічає незалежне порівняння зі знімками. Такий підхід особливо цінний для визначень API, етапів компілятора й альтернативних представлень даних. + +## Скінченне свідчення — не доведення {#finite-evidence-is-not-proof} + +Тест, що пройшов, демонструє поведінку лише для перевірених вхідних даних і реалізацій. Він не доводить закон для всіх значень. + +Посилюйте впевненість цілеспрямовано: + +1. тести на прикладах +2. повторно використовувані тести сценаріїв +3. генеровані тести властивостей +4. вичерпні перевірки скінченних областей +5. порівняння моделей +6. артефакти доведень + +Вибирайте рівень перевірки відповідно до ризику й сили твердження. + +## Назви тестів мають виражати значення {#test-names-should-state-meaning} + +Надавайте перевагу назвам на кшталт: + +* `reconstructs_every_generated_branch_from_its_root_path` +* `preserves_child_programs_when_routes_are_merged` +* `normalization_is_invariant_under_alpha_renaming` + +Уникайте назв, які лише описують послідовність реалізації: + +* `pushes_three_bits` +* `calls_helper_twice` +* `visits_left_node_first` + +Операційні тести залишаються доречними, коли порядок операцій визначений специфікацією. У назві зазначайте спостереження, яке надає цьому порядку значення. + +## Перевірка {#review-checks} + +* Чи має кожна нова семантична операція цільовий закон або твердження? +* Чи сформульовано повторно використовувані вимоги узагальнено для публічних можливостей? +* Чи відокремлено сценарії від конкретних виконавців? +* Чи розрізнено семантичні закони та інваріанти представлення? +* Чи порівнюються кілька інтерпретаторів там, де це практично? +* Чи уникає документація називати скінченні тести доведеннями? diff --git a/src/rust-dd/laws.vi.md b/src/rust-dd/laws.vi.md new file mode 100644 index 0000000..2b0b181 --- /dev/null +++ b/src/rust-dd/laws.vi.md @@ -0,0 +1,187 @@ + + +# Định luật, tình huống và bằng chứng {#laws-scenarios-and-evidence} + +```admonish tip title="Liên quan" +Góc nhìn ngữ nghĩa: [Định luật và cách diễn giải](../denotational-design/laws-and-interpretations.md) +Thiết kế theo ngữ nghĩa trong Rust: [Bộ diễn giải và hiệu ứng](interpreters.md), [Các đại số năng lực](capability-algebras.md) +Khái niệm: [Phân nhánh và hội tụ](../concepts/branching.md), [Tính minh bạch tham chiếu](../concepts/referential_transparency.md) +``` + +```admonish note title="Định hướng" +Kiểm thử là bằng chứng cho đặc tả. Hãy khẳng định các quan sát công khai và định luật mà miền được chọn hỗ trợ, chứ không khẳng định các bước thực thi riêng tư; đồng thời viết các định luật đó tổng quát theo năng lực để chúng ràng buộc mọi bộ diễn giải. +``` + +Mã lấy ý nghĩa làm trọng tâm cần kiểm thử cũng lấy ý nghĩa làm trọng tâm. Hãy kiểm tra các quan sát công khai và định luật thay vì các bước thực thi riêng tư. + +## Kiểm thử bề mặt đặc tả {#test-the-specification-surface} + +````admonish warning title="Kiểm thử gắn với cách biểu diễn" +Khẳng định này truy cập các trường của một đối tượng mang nên bộ diễn giải khác không thể dùng chung: + +```rust,noplayground +// not recommended: asserts a bit layout, not a semantic observation +assert_eq!(branch.bits, vec![false, true]); +``` +```` + +Kiểm thử ngữ nghĩa: + +```rust,noplayground +let root = alg.branch_root(); +let left = alg.branch_left(&root); +let left_right = alg.branch_right(&left); + +assert_eq!(alg.branch_path(&root, &left_right), Some(vec![Direction::Left, Direction::Right])); +``` + +Kiểm thử đầu có thể phù hợp với mô-đun tuần tự hóa chuyên về mã hóa bit. Nhưng nó là bằng chứng yếu cho đại số nhánh, vì các cách biểu diễn thay thế không thể dùng chung. + +## Phần mở rộng định luật có thể tái sử dụng {#reusable-law-extensions} + +Khi một thuộc tính áp dụng cho mọi bộ diễn giải tương thích, hãy viết nó một lần: + +```rust,noplayground +use anyhow::{Result, bail, ensure}; +use extend::ext; + +#[ext(name = BranchLawsExt)] +pub impl This +where + This: BranchAlg, + This::Branch: Clone + Eq, +{ + fn check_branch_root_round_trip(&self, directions: &[Direction]) -> Result<()> { + let root = self.branch_root(); + let branch = directions.iter().copied().fold(root.clone(), |branch, direction| self.branch_grow(&branch, direction)); + + let Some(path) = self.branch_path(&root, &branch) else { + bail!("grown branch has no path from root"); + }; + ensure!(path == directions, "root path did not round-trip"); + Ok(()) + } +} +``` + +Mọi bộ diễn giải đều chạy cùng bộ kiểm tra. `anyhow::Result` mang kết quả; `bail!` báo quan sát còn thiếu, trong khi `ensure!` kiểm tra định luật khứ hồi. Bộ kiểm tra phân biệt hai lỗi mà không phụ thuộc một cách biểu diễn nhánh. + +## Các nhóm định luật hữu ích {#useful-law-families} + +Hãy tìm các thuộc tính đã được cấu trúc ngữ nghĩa gợi ý: + +* tính đơn vị +* tính kết hợp +* tính giao hoán khi thực sự được dự định +* tính lũy đẳng +* khứ hồi +* chuẩn hóa +* tinh chỉnh +* tính đơn điệu +* phép thế +* sự thống nhất giữa các cách diễn giải + +```admonish warning title="Chỉ khẳng định những định luật được miền hỗ trợ" +Đừng thêm các thuật ngữ đại số quen thuộc chỉ vì chúng nghe có vẻ toán học. Chỉ nêu các định luật mà miền đã chọn hỗ trợ. +``` + +## Định luật và bất biến biểu diễn {#laws-versus-representation-invariants} + +Hãy phân biệt chúng: + +* **Định luật ngữ nghĩa:** dựng nhánh từ đường đi gốc sẽ biểu thị cùng nhánh đó. + +* **Bất biến biểu diễn:** các bit cao không dùng đến bằng không. + +* **Định luật tuần tự hóa:** + + $$ \operatorname{decode}(\operatorname{encode}(b)) = b $$ + +* **Định luật định dạng chuẩn tắc:** + + $$ \operatorname{encode}(\operatorname{decode}(x)) = x \qquad \text{for canonical byte sequences }x $$ + + +Tất cả đều có thể quan trọng. Chúng thuộc về các đặc tả khác nhau. + +## Tình huống dùng chung {#shared-scenarios} + +Tình huống là tương tác có thể tái sử dụng, được viết dựa trên năng lực công khai. Khung kiểm thử ALUX biểu diễn tình huống theo cách này: mã tác giả dựng một giá trị thông qua các năng lực `Scenario`, `DeployerIds`, `PlayAst` và `ScenarioSchedule` mà không gọi tên trình chạy cụ thể. + +```rust,noplayground +#[ext(name = HelloScenarioExt)] +pub impl This +where + This: StandaloneScenario, + This::Step: PlayAst, +{ + fn hello(self) -> This::Scenario { + self.scenario() + .under_comprehensive(100) + .step( + self.play_ast( + self.deployer(0), + tolang! { + let x in { + x ! "hello" | + ? (a <- x) a.log() + } + }, + ) + .expect_log(r#""hello""#), + ) + } +} +``` + +Mỗi lời gọi mô tả ý nghĩa do tác giả định ra chứ không phải cơ chế của trình chạy. `under_comprehensive(100)` đòi hỏi nhật ký mong đợi trong một lượt chạy tuần tự, 100 lượt đồng thời tự do và tối đa 100 lượt có thứ tự hoán vị. Tình huống cố định quan sát, còn trình chạy thay đổi thứ tự thực thi. + +Nguyên lý tương tự áp dụng giữa các bộ diễn giải: khi nhiều trình chạy triển khai các năng lực mà một tình huống sử dụng, mỗi trình chạy đều có thể diễn giải cùng tương tác do tác giả viết. Phần thiết lập riêng của trình chạy và kiểm tra ranh giới vẫn nằm ngoài tình huống. + +## Sự thống nhất giữa các bộ diễn giải {#cross-interpreter-agreement} + +Khi hai bộ diễn giải bộc lộ cùng một quan sát, hãy so sánh chúng: + +$$ \operatorname{interpret\_text}(p).\mathit{route\_names} = \operatorname{interpret\_server}(p).\mathit{registered\_route\_names} $$ + +Cách này phát hiện sai lệch mà các bản chụp độc lập bỏ sót. Nó đặc biệt có giá trị với định nghĩa API, giai đoạn trình biên dịch và các cách biểu diễn dữ liệu thay thế. + +## Bằng chứng hữu hạn không phải chứng minh {#finite-evidence-is-not-proof} + +Kiểm thử đạt chứng minh hành vi với các đầu vào và cách triển khai đã được kiểm thử. Nó không chứng minh định luật đúng với mọi giá trị. + +Hãy chủ ý tăng mức bảo đảm: + +1. kiểm thử ví dụ +2. kiểm thử tình huống tái sử dụng +3. kiểm thử thuộc tính được tạo sinh +4. kiểm tra toàn diện trên các miền hữu hạn +5. so sánh mô hình +6. tạo phẩm chứng minh + +Chọn mức phù hợp với rủi ro và độ mạnh của khẳng định. + +## Tên kiểm thử cần nêu ý nghĩa {#test-names-should-state-meaning} + +Nên dùng: + +* `reconstructs_every_generated_branch_from_its_root_path` +* `preserves_child_programs_when_routes_are_merged` +* `normalization_is_invariant_under_alpha_renaming` + +Tránh tên chỉ thuật lại cách triển khai: + +* `pushes_three_bits` +* `calls_helper_twice` +* `visits_left_node_first` + +Kiểm thử vận hành vẫn hợp lệ khi thứ tự thao tác được đặc tả. Hãy gọi tên quan sát khiến thứ tự đó có ý nghĩa. + +## Các câu hỏi khi duyệt {#review-checks} + +* Mỗi phép toán ngữ nghĩa mới có định luật hoặc khẳng định tập trung không? +* Các nghĩa vụ tái sử dụng có được viết tổng quát theo năng lực công khai không? +* Tình huống có được tách khỏi trình chạy cụ thể không? +* Định luật ngữ nghĩa có được phân biệt với bất biến biểu diễn không? +* Có so sánh nhiều bộ diễn giải ở nơi thực tiễn cho phép không? +* Tài liệu có tránh gọi kiểm thử hữu hạn là chứng minh không? diff --git a/src/rust-dd/laws.zh-hant.md b/src/rust-dd/laws.zh-hant.md new file mode 100644 index 0000000..8f33d24 --- /dev/null +++ b/src/rust-dd/laws.zh-hant.md @@ -0,0 +1,187 @@ + + +# 定律、場景與證據 {#laws-scenarios-and-evidence} + +```admonish tip title="相關內容" +語義視角:[定律與解釋](../denotational-design/laws-and-interpretations.md) +Rust 中的語義驅動設計:[直譯器與效應](interpreters.md)、[能力代數](capability-algebras.md) +概念:[分支與合流](../concepts/branching.md)、[引用透明性](../concepts/referential_transparency.md) +``` + +```admonish note title="導讀" +測試為規範提供證據。應針對公開可觀察的結果,以及所選語義域支持的定律撰寫斷言,而非針對私有執行步驟;並將這些定律以針對該能力的泛型形式表述,讓每個直譯器都接受同樣的檢驗。 +``` + +語義優先的程式碼需要語義優先的測試。測試公開可觀察的結果與定律,而非私有執行步驟。 + +## 測試規範介面 {#test-the-specification-surface} + +````admonish warning title="與表示耦合的測試" +這個斷言深入存取某個載體的欄位,因此其他直譯器無法複用: + +```rust,noplayground +// not recommended: asserts a bit layout, not a semantic observation +assert_eq!(branch.bits, vec![false, true]); +``` +```` + +語義測試: + +```rust,noplayground +let root = alg.branch_root(); +let left = alg.branch_left(&root); +let left_right = alg.branch_right(&left); + +assert_eq!(alg.branch_path(&root, &left_right), Some(vec![Direction::Left, Direction::Right])); +``` + +如果測試物件是位編碼的序列化模組,第一個測試可能合適。但對於分支代數,它提供的證據較弱,因為替代表示無法複用它。 + +## 可複用的定律擴充 {#reusable-law-extensions} + +如果某項性質適用於所有相容直譯器,就把它寫一次: + +```rust,noplayground +use anyhow::{Result, bail, ensure}; +use extend::ext; + +#[ext(name = BranchLawsExt)] +pub impl This +where + This: BranchAlg, + This::Branch: Clone + Eq, +{ + fn check_branch_root_round_trip(&self, directions: &[Direction]) -> Result<()> { + let root = self.branch_root(); + let branch = directions.iter().copied().fold(root.clone(), |branch, direction| self.branch_grow(&branch, direction)); + + let Some(path) = self.branch_path(&root, &branch) else { + bail!("grown branch has no path from root"); + }; + ensure!(path == directions, "root path did not round-trip"); + Ok(()) + } +} +``` + +每個直譯器都執行同一個檢查器。`anyhow::Result`承載結果;`bail!`報告缺失的觀察,而`ensure!`檢查往返定律。該檢查器無需依賴某一種分支表示,就能區分這兩種失敗。 + +## 有用的定律類別 {#useful-law-families} + +尋找語義結構已經暗示的性質: + +* 單位元 +* 結合性 +* 確實有意要求時的交換性 +* 冪等性 +* 往返 +* 正規化 +* 細化 +* 單調性 +* 替換 +* 解釋一致性 + +```admonish warning title="只主張該領域支援的定律" +不要僅僅因為熟悉或聽起來很數學,就新增代數術語。只陳述所選領域支援的定律。 +``` + +## 定律與表示不變數 {#laws-versus-representation-invariants} + +請將以下內容區分開: + +* 語義定律:根據根路徑重構一個分支時,所指稱的仍是同一個分支。 + +* 表示不變數:未使用的高位為零。 + +* **序列化定律:** + + $$ \operatorname{decode}(\operatorname{encode}(b)) = b $$ + +* **規範格式定律:** + + $$ \operatorname{encode}(\operatorname{decode}(x)) = x \qquad \text{for canonical byte sequences }x $$ + + +這些都可能很重要,但各自屬於不同的規範。 + +## 共享場景 {#shared-scenarios} + +場景是針對公共能力編寫的可複用互動。ALUX 測試框架以這種方式表示場景:編寫場景的程式碼透過`Scenario`、`DeployerIds`、`PlayAst`和`ScenarioSchedule`能力構造一個值,無需點名具體執行器。 + +```rust,noplayground +#[ext(name = HelloScenarioExt)] +pub impl This +where + This: StandaloneScenario, + This::Step: PlayAst, +{ + fn hello(self) -> This::Scenario { + self.scenario() + .under_comprehensive(100) + .step( + self.play_ast( + self.deployer(0), + tolang! { + let x in { + x ! "hello" | + ? (a <- x) a.log() + } + }, + ) + .expect_log(r#""hello""#), + ) + } +} +``` + +每次呼叫都描述作者定義的含義,而不是執行器機制。`under_comprehensive(100)`要求在一次順序執行、100 次完全併發執行以及最多 100 次亂序執行中都得到預期日誌。場景固定所觀察的內容,執行器則改變執行順序。 + +同一原則也適用於不同直譯器:如果多個執行器都實作了場景所用的能力,它們就都可以解釋同一個編寫好的互動。執行器特有的設定與邊界檢查應留在場景之外。 + +## 跨直譯器一致性 {#cross-interpreter-agreement} + +當兩個直譯器提供相同觀察時,可以比較它們: + +$$ \operatorname{interpret\_text}(p).\mathit{route\_names} = \operatorname{interpret\_server}(p).\mathit{registered\_route\_names} $$ + +這可以捕捉獨立快照遺漏的漂移。對於 API 定義、編譯器階段與替代資料表示,這尤其有價值。 + +## 有限證據並非證明 {#finite-evidence-is-not-proof} + +測試透過,只能證明在受測輸入與實作下觀察到了相應行為,不能證明某條定律對所有值都成立。 + +有計劃地提升保證強度: + +1. 示例測試 +2. 可複用場景測試 +3. 生成式性質測試 +4. 對有限域進行窮舉檢查 +5. 模型比較 +6. 證明產物 + +根據風險與主張強度選擇層級。 + +## 讓測試名稱表達含義 {#test-names-should-state-meaning} + +優先使用: + +* `reconstructs_every_generated_branch_from_its_root_path` +* `preserves_child_programs_when_routes_are_merged` +* `normalization_is_invariant_under_alpha_renaming` + +避免只敘述實作過程的名稱: + +* `pushes_three_bits` +* `calls_helper_twice` +* `visits_left_node_first` + +如果操作順序本身有規範規定,操作測試仍然有效。此時應在名稱中指出讓該順序具有意義的觀察。 + +## 審查要點 {#review-checks} + +* 每個新增的語義操作是否都有針對性的定律或斷言? +* 可複用義務是否針對公共能力以泛型方式表達? +* 場景是否與具體執行器分離? +* 是否區分了語義定律與表示不變數? +* 在可行時是否比較了多個直譯器? +* 文件是否避免把有限測試稱作證明? diff --git a/src/rust-dd/laws.zh.md b/src/rust-dd/laws.zh.md new file mode 100644 index 0000000..e6981f0 --- /dev/null +++ b/src/rust-dd/laws.zh.md @@ -0,0 +1,187 @@ + + +# 定律、场景与证据 {#laws-scenarios-and-evidence} + +```admonish tip title="相关内容" +语义视角:[定律与解释](../denotational-design/laws-and-interpretations.md) +Rust 中的语义驱动设计:[解释器与效应](interpreters.md)、[能力代数](capability-algebras.md) +概念:[分支与合流](../concepts/branching.md)、[引用透明性](../concepts/referential_transparency.md) +``` + +```admonish note title="导读" +测试为规范提供证据。应针对公开可观察的结果以及所选语义域支持的定律编写断言,而不是针对私有执行步骤;并将这些定律写成针对该能力的泛型形式,使每个解释器都接受同样的检验。 +``` + +语义优先的代码需要语义优先的测试。测试公开可观察的结果与定律,而非私有执行步骤。 + +## 测试规范接口 {#test-the-specification-surface} + +````admonish warning title="与表示耦合的测试" +这个断言深入访问某个载体的字段,因此其他解释器无法复用: + +```rust,noplayground +// not recommended: asserts a bit layout, not a semantic observation +assert_eq!(branch.bits, vec![false, true]); +``` +```` + +语义测试: + +```rust,noplayground +let root = alg.branch_root(); +let left = alg.branch_left(&root); +let left_right = alg.branch_right(&left); + +assert_eq!(alg.branch_path(&root, &left_right), Some(vec![Direction::Left, Direction::Right])); +``` + +如果测试对象是位编码的序列化模块,第一个测试可能合适。但对于分支代数,它提供的证据较弱,因为替代表示无法复用它。 + +## 可复用的定律扩展 {#reusable-law-extensions} + +如果某项性质适用于所有兼容解释器,就把它写一次: + +```rust,noplayground +use anyhow::{Result, bail, ensure}; +use extend::ext; + +#[ext(name = BranchLawsExt)] +pub impl This +where + This: BranchAlg, + This::Branch: Clone + Eq, +{ + fn check_branch_root_round_trip(&self, directions: &[Direction]) -> Result<()> { + let root = self.branch_root(); + let branch = directions.iter().copied().fold(root.clone(), |branch, direction| self.branch_grow(&branch, direction)); + + let Some(path) = self.branch_path(&root, &branch) else { + bail!("grown branch has no path from root"); + }; + ensure!(path == directions, "root path did not round-trip"); + Ok(()) + } +} +``` + +每个解释器都运行同一个检查器。`anyhow::Result`承载结果;`bail!`报告缺失的观察,而`ensure!`检查往返定律。该检查器无需依赖某一种分支表示,就能区分这两种失败。 + +## 有用的定律类别 {#useful-law-families} + +寻找语义结构已经暗示的性质: + +* 单位元 +* 结合性 +* 确实有意要求时的交换性 +* 幂等性 +* 往返 +* 规范化 +* 细化 +* 单调性 +* 替换 +* 解释一致性 + +```admonish warning title="只主张该领域支持的定律" +不要仅仅因为熟悉或听起来很数学,就添加代数术语。只陈述所选领域支持的定律。 +``` + +## 定律与表示不变量 {#laws-versus-representation-invariants} + +请将以下内容区分开: + +* 语义定律:根据根路径重构一个分支时,所指称的仍是同一个分支。 + +* 表示不变量:未使用的高位为零。 + +* **序列化定律:** + + $$ \operatorname{decode}(\operatorname{encode}(b)) = b $$ + +* **规范格式定律:** + + $$ \operatorname{encode}(\operatorname{decode}(x)) = x \qquad \text{for canonical byte sequences }x $$ + + +这些都可能很重要,但各自属于不同的规范。 + +## 共享场景 {#shared-scenarios} + +场景是针对公共能力编写的可复用交互。ALUX 测试框架以这种方式表示场景:编写场景的代码通过`Scenario`、`DeployerIds`、`PlayAst`和`ScenarioSchedule`能力构造一个值,无需点名具体运行器。 + +```rust,noplayground +#[ext(name = HelloScenarioExt)] +pub impl This +where + This: StandaloneScenario, + This::Step: PlayAst, +{ + fn hello(self) -> This::Scenario { + self.scenario() + .under_comprehensive(100) + .step( + self.play_ast( + self.deployer(0), + tolang! { + let x in { + x ! "hello" | + ? (a <- x) a.log() + } + }, + ) + .expect_log(r#""hello""#), + ) + } +} +``` + +每次调用都描述作者定义的含义,而不是运行器机制。`under_comprehensive(100)`要求在一次顺序运行、100 次完全并发运行以及最多 100 次乱序运行中都得到预期日志。场景固定所观察的内容,运行器则改变执行顺序。 + +同一原则也适用于不同解释器:如果多个运行器都实现了场景所用的能力,它们就都可以解释同一个编写好的交互。运行器特有的设置与边界检查应留在场景之外。 + +## 跨解释器一致性 {#cross-interpreter-agreement} + +当两个解释器提供相同观察时,可以比较它们: + +$$ \operatorname{interpret\_text}(p).\mathit{route\_names} = \operatorname{interpret\_server}(p).\mathit{registered\_route\_names} $$ + +这可以捕捉独立快照遗漏的漂移。对于 API 定义、编译器阶段与替代数据表示,这尤其有价值。 + +## 有限证据并非证明 {#finite-evidence-is-not-proof} + +测试通过,只能证明在受测输入与实现下观察到了相应行为,不能证明某条定律对所有值都成立。 + +有计划地提升保证强度: + +1. 示例测试 +2. 可复用场景测试 +3. 生成式性质测试 +4. 对有限域进行穷举检查 +5. 模型比较 +6. 证明产物 + +根据风险与主张强度选择层级。 + +## 让测试名称表达含义 {#test-names-should-state-meaning} + +优先使用: + +* `reconstructs_every_generated_branch_from_its_root_path` +* `preserves_child_programs_when_routes_are_merged` +* `normalization_is_invariant_under_alpha_renaming` + +避免只叙述实现过程的名称: + +* `pushes_three_bits` +* `calls_helper_twice` +* `visits_left_node_first` + +如果操作顺序本身有规范规定,操作测试仍然有效。此时应在名称中指出让该顺序具有意义的观察。 + +## 审查要点 {#review-checks} + +* 每个新增的语义操作是否都有针对性的定律或断言? +* 可复用义务是否针对公共能力以泛型方式表达? +* 场景是否与具体运行器分离? +* 是否区分了语义定律与表示不变量? +* 在可行时是否比较了多个解释器? +* 文档是否避免把有限测试称作证明? diff --git a/src/rust-dd/semantic-types.ar.md b/src/rust-dd/semantic-types.ar.md new file mode 100644 index 0000000..0b0585c --- /dev/null +++ b/src/rust-dd/semantic-types.ar.md @@ -0,0 +1,163 @@ + + +# الأنواع الدلالية في Rust {#semantic-types-in-rust} + +```admonish tip title="ذات صلة" +المنظور الدلالي: [الأنواع التابعة والبراهين](../denotational-design/dependent-types.md)، [التصميم الدلالي (Denotational Design)](../denotational-design/design.md) +التصميم انطلاقًا من المعنى في Rust: [جبر القدرات](capability-algebras.md)، [برامج من الرتبة الأولى](first-order-programs.md)، [القوانين والسيناريوهات والأدلة](laws.md) +المفاهيم: [الشفافية المرجعية](../concepts/referential_transparency.md) +``` + +```admonish note title="تمهيد" +تستخدم Rust التي تبدأ بالمعنى الأنواع لإبقاء البنية الدلالية ظاهرة. تسمي الأنواع المرتبطة عائلات الحوامل، وتصرّح الحدود بالعلاقات بينها، وتشتق الامتدادات عمليات جديدة من مقدمات صريحة. وتظل القوانين هي ما يحدد ما يجب على كل تفسير الحفاظ عليه. +``` + +تُكتب أدوار مختلفة عديدة في Rust على الصورة `type`. ويمنع إبقاؤها متميزة انهيار المعنى إلى تمثيل. + +| الدور | مثال | ما الذي يصرح به | +| --- | --- | --- | +| نوع دلالي | `Direction` | فروق المجال المهمة | +| حامل يختاره المفسر | `BranchAlg::Branch` | التمثيل الذي يختاره المفسر | +| عملية مشتقة | `BranchExt::branch_child` | ما ينتج عن القدرات المعلنة | +| نوع مرحلة | `Syntax`, `CoreProgram`, `Executable` | التحويل الذي اجتازته القيمة | +| نوع تمثيل | `BitBranch` | كيفية تخزين مفسر واحد لمعنى الفرع | +| برنامج دليل | سيناريو أو امتداد قانون قابل لإعادة الاستخدام | الملاحظات التي يجب على المفسرات المتوافقة تحقيقها | + +## الأنواع الدلالية قبل التمثيل {#semantic-types-before-representation} + +لنفترض أن مجالًا متشعبًا يميّز اتجاهين: + +```rust,noplayground +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +enum Direction { + Left, + Right, +} +``` + +يسمي `Direction` هذا الفرق مباشرة. وقد يرمّز مفسر أحد المسارات بإيجاز: + +```rust,noplayground +struct BitBranch(Vec); +``` + +تنتمي القيم المنطقية إلى ذلك التمثيل. وليست تعريف اليسار واليمين، ولا يلزم مفسر آخر باستخدامها. + +```admonish warning title="الترميز المدمج ليس النوع الدلالي" +لا تعرّف سلوك المجال بمواضع البتات أو إزاحات البايتات أو تفرعات الآلة. يجب أن ترمّز هذه الآثار الفروق الدلالية، لا أن تملكها. +``` + +يتيح هذا الفصل تغيير تخطيطات التخزين والتنفيذ من دون تغيير المجال ضمنيًا. + +## تختار الأنواع المرتبطة الحوامل {#associated-types-choose-carriers} + +يمكن لجبر القدرات أن يترك لكل مفسر اختيار الحامل: + +```rust,noplayground +trait BranchAlg { + type Branch; + + fn branch_root(&self) -> Self::Branch; + fn branch_grow(&self, branch: &Self::Branch, direction: Direction) -> Self::Branch; + fn branch_path( + &self, + ancestor: &Self::Branch, + descendant: &Self::Branch, + ) -> Option>; +} +``` + +ليس `Self::Branch` نوع حقل مخفيًا، بل هو الحامل الذي يختاره تفسير معنى الفرع. ويمكن لمسار بتات أو موضع شجرة عددي أو حد رمزي أو تمثيل آخر تحقيق الجبر نفسه. + +يمكن قراءة التدوين `T::Branch` لدى المفسر `T` على أنه عائلة حوامل $\mathsf{Branch}(T)$. وقد يتغير الحامل بتغيير المفسر، مع بقاء كل عملية مفهرسة باتساق وفق الاختيار نفسه. + +## تشتق الامتدادات النتائج {#extensions-derive-consequences} + +يمكن للامتداد بناء عملية جديدة من المقدمات التي يحتاج إليها تحديدًا: + +```rust,noplayground +#[ext(name = BranchExt)] +pub impl This +where + This: BranchAlg, +{ + fn branch_child( + &self, + branch: &This::Branch, + direction: Direction, + ) -> This::Branch { + self.branch_grow(branch, direction) + } +} +``` + +جملة `where` هي المقدمة: يفسر `This` جبر الفروع. والأسلوب هو النتيجة: بالنسبة إلى حامل ذلك المفسر، يحدد الفرع والاتجاه الفرعَ الابن. + +$$ \bigl(T : \mathsf{BranchAlg}\bigr) \Longrightarrow \mathsf{branchChild}_T : \mathsf{Branch}(T) \times \mathsf{Direction} \to \mathsf{Branch}(T) $$ + +لا يختار شيء في الاشتقاق تمثيلًا ملموسًا للفرع. وتبقى النتيجة ضمن عائلة الحوامل التي اختارها المفسر. + +## تصرح حدود المساواة بالتوافق {#equality-bounds-state-compatibility} + +تحتاج قدرتان أحيانًا إلى الاتفاق على حامل. ويمكن لمساواة النوع المرتبط التصريح بهذا الشرط دون اختيار تمثيل ملموس: + +```rust,noplayground +Right: BranchAlg +``` + +اقرأ الحد بوصفه قضية محلية: يفسر `Left` و`Right` عمليات الفروع على الحامل نفسه. ضع هذه المساواة عند العملية التي تحتاج إلى التوافق بدلًا من فرضها عالميًا على أحد الجبرين. + +هذا الحد أقوى وأدق من قبول سياق ملموس لمجرد أنه يصادف أن يحتوي التنفيذين معًا. + +## تُظهر أنواع المراحل عقود المترجم {#stage-types-make-compiler-contracts-visible} + +ينبغي ألا يمرر مسار المترجم شجرة واحدة بلا تمييز عبر كل مرحلة. فأنواع المراحل المختلفة تحدد التحويل الذي حدث: + +| المرحلة | المدخل | المخرج | العقد | +| --- | --- | --- | --- | +| التحليل النحوي | نص المصدر | `Syntax` | يتعرف على القواعد السطحية | +| التطبيع | `Syntax` | `CoreProgram` | ينتج المعنى الأساسي المختار | +| توليد الشيفرة | `CoreProgram` | `Executable` | يحافظ على ملاحظات البرنامج في صيغة قابلة للتنفيذ | +| بيئة التشغيل | `Executable` | السلوك القابل للملاحظة | يفسر الملف التنفيذي بما يتسق مع نموذج اللغة | + +تمنع هذه الأنواع الخلط العرضي بين المراحل، لكن أسماءها وحدها لا تثبت الحفاظ. فما زالت التحويلات تحتاج إلى قوانين معلنة وسيناريوهات تمثيلية وأدلة بين المفسرات. + +## اقرأ العقد {#read-the-contract} + +تقبل البنية على مستوى الأنواع قراءة منطقية مفيدة: + +| صيغة Rust | القراءة | +| --- | --- | +| `This: BranchAlg` | يوفر `This` تفسيرًا لمعنى الفرع | +| `This::Branch` | يختار `This` حامل الفرع | +| `Right: BranchAlg` | يتفق تفسيران على حاملهما | +| `-> This::Branch` | تبقى النتيجة ضمن عائلة الحوامل المختارة | + +تشجع هذه القراءة واجهات API على إظهار ما يحدد النوع، والتساويات التي يتطلبها التركيب، والاستنتاجات الناتجة عن تلك المقدمات. ويمكن للأنواع المرتبطة والأنواع المرتبطة العامة والمعممات الثابتة وtypestate والشواهد عديمة الحجم التعبير عن أجزاء من هذه العقود عندما يكون الفرق الأساسي حقيقيًا. + +لا تصطنع آليات على مستوى الأنواع لمجرد إضفاء مظهر أكثر صورية على التنفيذ. ينبغي للنوع أن يكشف معنى أو يحافظ على علاقة لازمة، لا أن يزخرف التمثيل. + +## الأنواع لا تحل محل القوانين {#types-do-not-replace-laws} + +يقيّد توقيع النوع البرامج التي يمكن تكوينها، بينما تقيّد القوانين علاقة العمليات بعضها ببعض. وكلاهما مطلوب. + +على سبيل المثال، يقرر `BranchAlg::Branch` أن كل مفسر يختار حاملًا للفرع. لكنه لا يثبت وحده أن: + +* المسار من الفرع إلى نفسه فارغ +* إعادة تشغيل مسار الجذر تعيد بناء الفرع +* الابنين المتعاكسين متميزان + +هذه قوانين دلالية مشتركة بين المفسرات المتوافقة. أما الادعاءات الخاصة بالتمثيل، مثل كون البتات غير المستخدمة صفرًا، فتنتمي إلى المفسر الذي اختار ذلك التمثيل. + +```admonish quote title="اقرأ الأنواع بوصفها ادعاءات" +اسأل عما يدّعيه كل نوع، وما الذي يحدده، وما القوانين التي تكمله، وأي مفسر يحققه. +``` + +## فحوص المراجعة {#review-checks} + +* هل يظهر فرق المجال قبل ترميزه الآلي المدمج؟ +* هل النوع المرتبط حامل يختاره المفسر، لا حالة ملموسة متنكرة؟ +* هل تصرح حدود المساواة بالتوافق المطلوب عند موضع الاستخدام فقط؟ +* هل للمراحل المختلفة للمترجم أنواع مختلفة وعقود صريحة؟ +* هل تُفصل القضايا الدلالية عن الثوابت التمثيلية؟ +* هل تسند القوانين أو السيناريوهات القابلة لإعادة الاستخدام الادعاءات التي لا تستطيع Rust التعبير عنها؟ diff --git a/src/rust-dd/semantic-types.de.md b/src/rust-dd/semantic-types.de.md new file mode 100644 index 0000000..7f24a20 --- /dev/null +++ b/src/rust-dd/semantic-types.de.md @@ -0,0 +1,163 @@ + + +# Semantische Typen in Rust {#semantic-types-in-rust} + +```admonish tip title="Verwandte Themen" +The Semantic View: [Abhängige Typen und Beweise](../denotational-design/dependent-types.md), [Denotational Design](../denotational-design/design.md) +Design by Meaning in Rust: [Capability-Algebren](capability-algebras.md), [Programme erster Ordnung](first-order-programs.md), [Gesetze, Szenarien und Nachweise](laws.md) +Concepts: [Referenzielle Transparenz](../concepts/referential_transparency.md) +``` + +```admonish note title="Orientierung" +Bedeutungsorientiertes Rust verwendet Typen, um semantische Strukturen sichtbar zu halten. Assoziierte Typen benennen Trägerfamilien, Bounds legen Beziehungen zwischen ihnen fest, und Erweiterungen leiten neue Operationen aus expliziten Voraussetzungen ab. Die Gesetze bestimmen weiterhin, was jede Interpretation bewahren muss. +``` + +In Rust werden mehrere unterschiedliche Rollen mit `type` geschrieben. Sie auseinanderzuhalten verhindert, dass Bedeutung in Repräsentation aufgeht. + +| Rolle | Beispiel | Aussage | +| --- | --- | --- | +| Semantischer Typ | `Direction` | Welche Unterschiede im Fachbereich wichtig sind | +| Vom Interpreter gewählter Träger | `BranchAlg::Branch` | Welche Repräsentation ein Interpreter auswählt | +| Abgeleitete Operation | `BranchExt::branch_child` | Was aus den deklarierten Capabilities folgt | +| Stufentyp | `Syntax`, `CoreProgram`, `Executable` | Welche Transformation ein Wert durchlaufen hat | +| Repräsentationstyp | `BitBranch` | Wie ein Interpreter die Verzweigungsbedeutung speichert | +| Nachweisprogramm | Ein Szenario oder eine wiederverwendbare Gesetzeserweiterung | Welche Beobachtungen kompatible Interpreter erfüllen müssen | + +## Semantische Typen vor der Repräsentation {#semantic-types-before-representation} + +Angenommen, ein Verzweigungsbereich unterscheidet zwei Richtungen: + +```rust,noplayground +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +enum Direction { + Left, + Right, +} +``` + +`Direction` benennt die Unterscheidung direkt. Ein Interpreter kann einen Pfad kompakt kodieren: + +```rust,noplayground +struct BitBranch(Vec); +``` + +Die Booleans gehören zu dieser Repräsentation. Sie definieren nicht links und rechts, und ein anderer Interpreter muss sie nicht verwenden. + +```admonish warning title="Eine kompakte Kodierung ist nicht der semantische Typ" +Definiere Fachverhalten nicht anhand von Bitpositionen, Byteversätzen oder Maschinenverzweigungen. Diese Artefakte müssen die semantischen Unterschiede kodieren; sie bestimmen sie nicht. +``` + +Diese Trennung ermöglicht Änderungen an Speicher- und Ausführungslayouts, ohne den Fachbereich unbemerkt zu verändern. + +## Assoziierte Typen wählen Träger {#associated-types-choose-carriers} + +Eine Capability-Algebra kann den Träger jedem Interpreter überlassen: + +```rust,noplayground +trait BranchAlg { + type Branch; + + fn branch_root(&self) -> Self::Branch; + fn branch_grow(&self, branch: &Self::Branch, direction: Direction) -> Self::Branch; + fn branch_path( + &self, + ancestor: &Self::Branch, + descendant: &Self::Branch, + ) -> Option>; +} +``` + +`Self::Branch` ist kein verborgener Feldtyp. Es ist der Träger, den eine Interpretation der Verzweigungsbedeutung auswählt. Ein Bitpfad, eine numerische Baumposition, ein symbolischer Term oder eine andere Repräsentation können derselben Algebra genügen. + +Für einen Interpreter `T` lässt sich die Notation `T::Branch` als Trägerfamilie $\mathsf{Branch}(T)$ lesen. Ein Wechsel des Interpreters kann den Träger ändern, während jede Operation konsistent an dieselbe Auswahl gebunden bleibt. + +## Erweiterungen leiten Folgerungen ab {#extensions-derive-consequences} + +Eine Erweiterung kann aus genau den benötigten Voraussetzungen eine neue Operation konstruieren: + +```rust,noplayground +#[ext(name = BranchExt)] +pub impl This +where + This: BranchAlg, +{ + fn branch_child( + &self, + branch: &This::Branch, + direction: Direction, + ) -> This::Branch { + self.branch_grow(branch, direction) + } +} +``` + +Die Klausel `where` ist die Voraussetzung: `This` interpretiert die Verzweigungsalgebra. Die Methode ist die Folgerung: Für den Träger dieses Interpreters bestimmen ein Zweig und eine Richtung einen Kindzweig. + +$$ \bigl(T : \mathsf{BranchAlg}\bigr) \Longrightarrow \mathsf{branchChild}_T : \mathsf{Branch}(T) \times \mathsf{Direction} \to \mathsf{Branch}(T) $$ + +Die Ableitung wählt keine konkrete Repräsentation für den Zweig aus. Das Ergebnis bleibt in der vom Interpreter gewählten Trägerfamilie. + +## Gleichheits-Bounds legen Kompatibilität fest {#equality-bounds-state-compatibility} + +Zwei Capabilities müssen sich manchmal auf einen Träger einigen. Eine Gleichheit assoziierter Typen kann diese Anforderung ausdrücken, ohne eine konkrete Repräsentation festzulegen: + +```rust,noplayground +Right: BranchAlg +``` + +Lies den Bound als lokale Aussage: `Left` und `Right` interpretieren Verzweigungsoperationen über demselben Träger. Platziere diese Gleichheit bei der Operation, die die Übereinstimmung benötigt, statt sie beiden Algebren global aufzuerlegen. + +Ein solcher Bound ist stärker und präziser, als einen konkreten Kontext zu akzeptieren, nur weil er zufällig beide Implementierungen enthält. + +## Stufentypen machen Compilerverträge sichtbar {#stage-types-make-compiler-contracts-visible} + +Eine Compiler-Pipeline sollte nicht in jeder Phase denselben undifferenzierten Baum weiterreichen. Unterschiedliche Stufentypen geben an, welche Transformation stattgefunden hat: + +| Stufe | Eingabe | Ausgabe | Vertrag | +| --- | --- | --- | --- | +| Parsen | Quelltext | `Syntax` | Erkennt die Oberflächengrammatik | +| Normalisieren | `Syntax` | `CoreProgram` | Erzeugt die gewählte Kernbedeutung | +| Codegenerierung | `CoreProgram` | `Executable` | Bewahrt die Programmbeobachtungen in ausführbarer Form | +| Laufzeit | `Executable` | Beobachtbares Verhalten | Interpretiert das ausführbare Programm konsistent mit dem Sprachmodell | + +Diese Typen verhindern eine versehentliche Verwechslung von Stufen, doch ihre Namen allein beweisen keine Bewahrung. Für die Transformationen braucht es weiterhin formulierte Gesetze, repräsentative Szenarien und Nachweise über mehrere Interpreter hinweg. + +## Den Vertrag lesen {#read-the-contract} + +Die Struktur auf Typebene lässt sich aufschlussreich logisch lesen: + +| Rust-Form | Bedeutung | +| --- | --- | +| `This: BranchAlg` | `This` liefert eine Interpretation der Verzweigungsbedeutung | +| `This::Branch` | Der Verzweigungsträger wird von `This` ausgewählt | +| `Right: BranchAlg` | Zwei Interpretationen stimmen bei ihrem Träger überein | +| `-> This::Branch` | Das Ergebnis bleibt in der ausgewählten Trägerfamilie | + +Diese Lesart regt APIs dazu an offenzulegen, wovon ein Typ abhängt, welche Gleichheiten für Komposition erforderlich sind und welche Folgerungen aus den Voraussetzungen hervorgehen. Assoziierte Typen, generische assoziierte Typen, Const Generics, Typzustände und größenlose Zeugen können Teile solcher Verträge ausdrücken, wenn der zugrunde liegende Unterschied tatsächlich besteht. + +Führe keine Typmechanismen nur deshalb ein, damit eine Implementierung formaler wirkt. Ein Typ sollte Bedeutung sichtbar machen oder eine notwendige Beziehung bewahren, nicht bloß eine Repräsentation dekorieren. + +## Typen ersetzen keine Gesetze {#types-do-not-replace-laws} + +Eine Typsignatur schränkt ein, welche Programme gebildet werden können. Gesetze bestimmen, wie ihre Operationen zusammenhängen. Beides ist erforderlich. + +Zum Beispiel besagt `BranchAlg::Branch`, dass jeder Interpreter einen Träger für Verzweigungen auswählt. Daraus folgt nicht automatisch, dass: + +* der Pfad eines Zweigs zu sich selbst leer ist +* die erneute Wiedergabe eines Wurzelpfads den Zweig rekonstruiert +* entgegengesetzte Kindzweige verschieden sind + +Dies sind semantische Gesetze, die kompatible Interpreter teilen. Repräsentationsspezifische Aussagen — etwa dass ungenutzte Bits null sind — gehören zum Interpreter, der diese Repräsentation gewählt hat. + +```admonish quote title="Typen als Behauptungen lesen" +Frage, was jeder Typ behauptet, wodurch er bestimmt wird, welche Gesetze ihn vervollständigen und welcher Interpreter ihn realisiert. +``` + +## Prüfpunkte für das Review {#review-checks} + +* Wird ein Unterschied im Fachbereich benannt, bevor seine kompakte Maschinenkodierung gewählt wird? +* Ist ein assoziierter Typ ein vom Interpreter gewählter Träger und kein verschleierter konkreter Zustand? +* Legen Gleichheits-Bounds nur die Kompatibilität fest, die am jeweiligen Verwendungsort erforderlich ist? +* Haben unterschiedliche Compilerstufen eigene Typen und ausdrückliche Verträge? +* Sind semantische Aussagen von Repräsentationsinvarianten getrennt? +* Werden Aussagen, die Rust nicht ausdrücken kann, durch wiederverwendbare Gesetze oder Szenarien gestützt? diff --git a/src/rust-dd/semantic-types.es.md b/src/rust-dd/semantic-types.es.md new file mode 100644 index 0000000..3597f21 --- /dev/null +++ b/src/rust-dd/semantic-types.es.md @@ -0,0 +1,163 @@ + + +# Tipos semánticos en Rust {#semantic-types-in-rust} + +```admonish tip title="Relacionado" +La perspectiva semántica: [Tipos dependientes y pruebas](../denotational-design/dependent-types.md), [Diseño denotacional](../denotational-design/design.md) +Diseño por significado en Rust: [Álgebras de capacidades](capability-algebras.md), [Programas de primer orden](first-order-programs.md), [Leyes, escenarios y evidencia](laws.md) +Conceptos: [Transparencia referencial](../concepts/referential_transparency.md) +``` + +```admonish note title="Orientación" +Rust centrado en el significado usa tipos para mantener visible la estructura semántica. Los tipos asociados nombran familias de portadores, las restricciones expresan relaciones entre ellas y las extensiones derivan operaciones nuevas de premisas explícitas. Las leyes siguen determinando qué debe preservar toda interpretación. +``` + +En Rust, varios roles distintos se escriben igual: `type`. Mantenerlos diferenciados evita que el significado se reduzca a la representación. + +| Rol | Ejemplo | Qué expresa | +| --- | --- | --- | +| Tipo semántico | `Direction` | Qué distinciones del dominio importan | +| Portador elegido por el intérprete | `BranchAlg::Branch` | Qué representación elige el intérprete | +| Operación derivada | `BranchExt::branch_child` | Qué se deduce de las capacidades declaradas | +| Tipo de fase | `Syntax`, `CoreProgram`, `Executable` | Qué transformación ha atravesado un valor | +| Tipo de representación | `BitBranch` | Cómo almacena un intérprete el significado de ramificación | +| Programa de evidencia | Un escenario o una extensión de ley reutilizable | Qué observaciones deben satisfacer los intérpretes compatibles | + +## Tipos semánticos antes que representación {#semantic-types-before-representation} + +Supongamos que un dominio de ramificación distingue dos direcciones: + +```rust,noplayground +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +enum Direction { + Left, + Right, +} +``` + +`Direction` nombra directamente la distinción. Un intérprete puede codificar el camino de forma compacta: + +```rust,noplayground +struct BitBranch(Vec); +``` + +Los valores booleanos pertenecen a esa representación. No definen izquierda y derecha, y otro intérprete no tiene por qué usarlos. + +```admonish warning title="Una codificación compacta no es el tipo semántico" +No definas el comportamiento del dominio mediante posiciones de bits, desplazamientos de bytes o ramas de máquina. Esos artefactos deben codificar las distinciones semánticas, no apropiarse de ellas. +``` + +Esta separación permite cambiar la disposición del almacenamiento y la ejecución sin alterar silenciosamente el dominio. + +## Los tipos asociados eligen portadores {#associated-types-choose-carriers} + +Un álgebra de capacidades puede dejar el portador en manos de cada intérprete: + +```rust,noplayground +trait BranchAlg { + type Branch; + + fn branch_root(&self) -> Self::Branch; + fn branch_grow(&self, branch: &Self::Branch, direction: Direction) -> Self::Branch; + fn branch_path( + &self, + ancestor: &Self::Branch, + descendant: &Self::Branch, + ) -> Option>; +} +``` + +`Self::Branch` no es un tipo de campo oculto, sino el portador que elige una interpretación del significado de ramificación. Una ruta de bits, una posición numérica en un árbol, un término simbólico u otra representación pueden satisfacer la misma álgebra. + +Para un intérprete `T`, la notación `T::Branch` puede leerse como una familia de portadores $\mathsf{Branch}(T)$. Cambiar de intérprete puede cambiar el portador, mientras que todas las operaciones siguen indexadas coherentemente con la misma elección. + +## Las extensiones derivan consecuencias {#extensions-derive-consequences} + +Una extensión puede construir una operación nueva a partir de exactamente las premisas que necesita: + +```rust,noplayground +#[ext(name = BranchExt)] +pub impl This +where + This: BranchAlg, +{ + fn branch_child( + &self, + branch: &This::Branch, + direction: Direction, + ) -> This::Branch { + self.branch_grow(branch, direction) + } +} +``` + +La cláusula `where` es la premisa: `This` interpreta el álgebra de ramificación. El método es la consecuencia: para el portador de ese intérprete, una rama y una dirección determinan una rama hija. + +$$ \bigl(T : \mathsf{BranchAlg}\bigr) \Longrightarrow \mathsf{branchChild}_T : \mathsf{Branch}(T) \times \mathsf{Direction} \to \mathsf{Branch}(T) $$ + +La derivación no elige ninguna representación concreta de rama. El resultado permanece en la familia de portadores elegida por el intérprete. + +## Las restricciones de igualdad expresan compatibilidad {#equality-bounds-state-compatibility} + +A veces dos capacidades deben coincidir en un portador. Una igualdad de tipo asociado puede expresar ese requisito sin elegir una representación concreta: + +```rust,noplayground +Right: BranchAlg +``` + +Lee la restricción como una proposición local: `Left` y `Right` interpretan operaciones de ramificación sobre el mismo portador. Coloca esta igualdad en la operación que necesita la concordancia, en vez de imponerla globalmente a cualquiera de las dos álgebras. + +Esta restricción es más fuerte y precisa que aceptar un contexto concreto solo porque contiene ambas implementaciones. + +## Los tipos de fase hacen visibles los contratos del compilador {#stage-types-make-compiler-contracts-visible} + +Una canalización de compilación no debería pasar el mismo árbol indiferenciado por todas las fases. Los tipos de fase distintos indican qué transformación se ha producido: + +| Fase | Entrada | Salida | Contrato | +| --- | --- | --- | --- | +| Análisis sintáctico | Texto fuente | `Syntax` | Reconoce la gramática superficial | +| Normalización | `Syntax` | `CoreProgram` | Produce el significado central elegido | +| Generación de código | `CoreProgram` | `Executable` | Preserva las observaciones del programa en la forma ejecutable | +| Entorno de ejecución | `Executable` | Comportamiento observable | Interpreta el ejecutable de forma coherente con el modelo del lenguaje | + +Estos tipos evitan confusiones accidentales entre fases, pero sus nombres por sí solos no demuestran que se preserve el significado. Las transformaciones siguen necesitando leyes explícitas, escenarios representativos y evidencia entre intérpretes. + +## Lee el contrato {#read-the-contract} + +La estructura a nivel de tipos permite una lectura lógica útil: + +| Forma de Rust | Lectura | +| --- | --- | +| `This: BranchAlg` | `This` proporciona una interpretación del significado de ramificación | +| `This::Branch` | El portador de ramificación lo elige `This` | +| `Right: BranchAlg` | Dos interpretaciones coinciden en el portador | +| `-> This::Branch` | El resultado permanece en la familia de portadores seleccionada | + +Esta lectura anima a las API a exponer qué determina un tipo, qué igualdades requiere la composición y qué conclusiones se siguen de esas premisas. Los tipos asociados, los tipos asociados genéricos, los genéricos constantes, typestate y los testigos de tamaño cero pueden expresar partes de estos contratos cuando la distinción subyacente es real. + +No fabriques mecanismos a nivel de tipos solo para que una implementación parezca más formal. Un tipo debe exponer significado o preservar una relación necesaria, no adornar una representación. + +## Los tipos no sustituyen a las leyes {#types-do-not-replace-laws} + +Una firma de tipo restringe qué programas pueden formarse. Las leyes restringen cómo se relacionan sus operaciones. Se necesitan ambas cosas. + +Por ejemplo, `BranchAlg::Branch` indica que cada intérprete elige un portador de ramificación. Por sí solo no establece que: + +* el camino de una rama a sí misma esté vacío +* reproducir un camino desde la raíz reconstruya la rama +* los hijos opuestos sean distintos + +Esas son leyes semánticas compartidas por los intérpretes compatibles. Las afirmaciones específicas de una representación —como que los bits no utilizados sean cero— pertenecen al intérprete que eligió esa representación. + +```admonish quote title="Lee los tipos como afirmaciones" +Pregunta qué afirma cada tipo, qué lo determina, qué leyes lo completan y qué intérprete lo realiza. +``` + +## Comprobaciones de revisión {#review-checks} + +* ¿Aparece una distinción del dominio antes de su codificación compacta de máquina? +* ¿Es un tipo asociado un portador elegido por el intérprete, y no un estado concreto disfrazado? +* ¿Las restricciones de igualdad expresan solo la compatibilidad necesaria en ese sitio de uso? +* ¿Las fases distintas del compilador tienen tipos distintos y contratos explícitos? +* ¿Se separan las proposiciones semánticas de los invariantes de representación? +* ¿Las afirmaciones que Rust no puede expresar están respaldadas por leyes o escenarios reutilizables? diff --git a/src/rust-dd/semantic-types.ja.md b/src/rust-dd/semantic-types.ja.md new file mode 100644 index 0000000..7a9920b --- /dev/null +++ b/src/rust-dd/semantic-types.ja.md @@ -0,0 +1,163 @@ + + +# Rustの意味論的型 {#semantic-types-in-rust} + +```admonish tip title="関連項目" +意味論的な見方:[依存型と証明](../denotational-design/dependent-types.md)、[Denotational Design](../denotational-design/design.md) +Rustで意味から設計する:[ケイパビリティ代数](capability-algebras.md)、[一階プログラム](first-order-programs.md)、[法則、シナリオ、証拠](laws.md) +概念:[参照透過性](../concepts/referential_transparency.md) +``` + +```admonish note title="概要" +意味を第一に考えるRustでは、型を使って意味論的構造を見える状態に保ちます。関連型は担体の種類に名前を付け、境界は担体間の関係を述べ、拡張は明示した前提から新たな操作を導出します。すべての解釈で何を保持すべきかは、引き続き法則が定めます。 +``` + +Rustでは、役割の異なるものがいくつも同じ`type`と書かれます。区別を保つことで、意味が表現に還元されるのを防げます。 + +| 役割 | 例 | 表すもの | +| --- | --- | --- | +| 意味論的型 | `Direction` | どの領域上の区別が重要か | +| インタープリターが選ぶ担体 | `BranchAlg::Branch` | インタープリターが選択する表現 | +| 導出操作 | `BranchExt::branch_child` | 宣言されたケイパビリティから得られるもの | +| 段階型 | `Syntax`, `CoreProgram`, `Executable` | 値にどの変換が適用されたか | +| 表現型 | `BitBranch` | 一つのインタープリターが分岐の意味をどう格納するか | +| 証拠プログラム | シナリオまたは再利用可能な法則拡張 | 互換性のあるインタープリターが満たすべき観測 | + +## 表現より先に意味論的な型を定める {#semantic-types-before-representation} + +分岐を扱う領域で二つの方向を区別するとします。 + +```rust,noplayground +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +enum Direction { + Left, + Right, +} +``` + +`Direction`はその区別を直接表します。一つのインタープリターでは、経路をコンパクトに符号化できます。 + +```rust,noplayground +struct BitBranch(Vec); +``` + +真偽値はその表現に属します。左と右の定義ではなく、別のインタープリターが使う必要もありません。 + +```admonish warning title="コンパクトな符号化は意味論的な型ではない" +ビット位置、バイトオフセット、機械上の分岐で領域の振る舞いを定義しないでください。それらは意味論上の区別を符号化するものであり、その区別を所有するものではありません。 +``` + +この分離により、格納方法や実行レイアウトを変えても、領域の意味を暗黙に変更せずに済みます。 + +## 関連型で担体を選ぶ {#associated-types-choose-carriers} + +ケイパビリティ代数では、各インタープリターが担体を選べるようにします。 + +```rust,noplayground +trait BranchAlg { + type Branch; + + fn branch_root(&self) -> Self::Branch; + fn branch_grow(&self, branch: &Self::Branch, direction: Direction) -> Self::Branch; + fn branch_path( + &self, + ancestor: &Self::Branch, + descendant: &Self::Branch, + ) -> Option>; +} +``` + +`Self::Branch`は隠されたフィールド型ではありません。分岐の意味を解釈する際に選ばれる担体です。ビット経路、数値で表す木の位置、記号項、その他の表現で同じ代数を満たせます。 + +インタープリター`T`では、`T::Branch`の記法を担体族$\mathsf{Branch}(T)$として読めます。インタープリターを変えると担体も変わることがありますが、すべての操作は同じ選択に一貫して従います。 + +## 拡張から結果を導く {#extensions-derive-consequences} + +拡張では、必要な前提だけから新しい操作を構成できます。 + +```rust,noplayground +#[ext(name = BranchExt)] +pub impl This +where + This: BranchAlg, +{ + fn branch_child( + &self, + branch: &This::Branch, + direction: Direction, + ) -> This::Branch { + self.branch_grow(branch, direction) + } +} +``` + +`where`節が前提です。つまり、`This`が分岐代数を解釈します。メソッドはそこから得られる結果で、そのインタープリターの担体について、分岐と方向から子分岐を決定できます。 + +$$ \bigl(T : \mathsf{BranchAlg}\bigr) \Longrightarrow \mathsf{branchChild}_T : \mathsf{Branch}(T) \times \mathsf{Direction} \to \mathsf{Branch}(T) $$ + +この導出のどこにも、具体的な分岐表現を選ぶ処理はありません。結果は引き続きインタープリターが選んだ担体族に属します。 + +## 等値性の境界で互換性を表す {#equality-bounds-state-compatibility} + +二つのケイパビリティで担体を一致させる必要が生じることがあります。関連型の等値性を使えば、具体的な表現を選ばずに要件を記述できます。 + +```rust,noplayground +Right: BranchAlg +``` + +この境界は局所的な命題として読めます。`Left`と`Right`は同じ担体上の分岐操作を解釈します。どちらかの代数に全体で強制するのではなく、その一致が必要な操作にこの等値性を置きます。 + +こうした境界は、両方の実装をたまたま含むというだけで具体的なコンテキストを受け入れるよりも、強く正確です。 + +## 段階型でコンパイラーの契約を見えるようにする {#stage-types-make-compiler-contracts-visible} + +コンパイラーパイプラインでは、すべての段階に同じ区別のない木を渡すべきではありません。各段階の型で、どの変換が行われたかを示します。 + +| 段階 | 入力 | 出力 | 契約 | +| --- | --- | --- | --- | +| 構文解析 | ソーステキスト | `Syntax` | 表層文法を認識する | +| 正規化 | `Syntax` | `CoreProgram` | 選択した中核的な意味を生成する | +| コード生成 | `CoreProgram` | `Executable` | 実行可能な形式でプログラムの観測を保持する | +| ランタイム | `Executable` | 観測可能な振る舞い | 言語モデルに沿って実行可能コードを一貫して解釈する | + +こうした型は段階の取り違えを防ぎますが、名前だけでは保持を証明できません。変換には明示された法則、代表的なシナリオ、インタープリター間の証拠が必要です。 + +## 契約を読む {#read-the-contract} + +型レベルの構造は、論理的には次のように読めます。 + +| Rustでの形式 | 読み方 | +| --- | --- | +| `This: BranchAlg` | `This`は分岐の意味を解釈するものを与える | +| `This::Branch` | 分岐の担体は`This`によって選ばれる | +| `Right: BranchAlg` | 二つの解釈で担体が一致する | +| `-> This::Branch` | 結果は選択された担体族にとどまる | + +この読み方を使うと、型を決定するもの、合成に必要な等値性、前提から導かれる結論をAPIに明示しやすくなります。根底の区別が実在する場合、関連型、ジェネリック関連型、constジェネリクス、typestate、サイズゼロの証明値はいずれも契約の一部を表現できます。 + +実装を形式的に見せるだけの目的で、型レベルの仕組みを作り出さないでください。型が表すのは意味か、必要な関係であるべきであり、表現の飾りにしてはいけません。 + +## 型は法則を置き換えない {#types-do-not-replace-laws} + +型シグネチャは、どのプログラムを構成できるかを制約します。法則は、その操作同士がどのように関係するかを制約します。両方が必要です。 + +たとえば、`BranchAlg::Branch`は各インタープリターが分岐の担体を選ぶことを示します。それだけでは次のことは保証しません。 + +* 分岐から同じ分岐への経路が空である +* 根の経路を再生すると分岐が再構成される +* 反対方向の子は互いに異なる + +これらは互換性のあるインタープリターが共有する意味論的法則です。未使用ビットがゼロであることなど、表現固有の主張は、その表現を選んだインタープリターに属します。 + +```admonish quote title="型を主張として読む" +それぞれの型が何を主張し、何によって決まり、どの法則がその型を補い、どのインタープリターが実現するのかを確認します。 +``` + +## レビュー時の確認 {#review-checks} + +* 領域上の区別を、コンパクトな機械表現より先に定めているか。 +* 関連型は、具体的な状態を偽装したものではなく、インタープリターが選ぶ担体か。 +* 等値性の境界は、その使用箇所で必要な互換性だけを述べているか。 +* コンパイラーの各段階に別々の型と明示的な契約があるか。 +* 意味論的命題と表現不変条件を分けているか。 +* Rustで表せない主張を、再利用可能な法則やシナリオで裏付けているか。 diff --git a/src/rust-dd/semantic-types.ko.md b/src/rust-dd/semantic-types.ko.md new file mode 100644 index 0000000..d9ae13a --- /dev/null +++ b/src/rust-dd/semantic-types.ko.md @@ -0,0 +1,163 @@ + + +# Rust의 의미 타입 {#semantic-types-in-rust} + +```admonish tip title="관련 항목" +의미론적 관점: [종속 타입과 증명](../denotational-design/dependent-types.md), [표시적 설계](../denotational-design/design.md) +Rust에서 의미로 설계하기: [케이퍼빌리티 대수](capability-algebras.md), [일차 프로그램](first-order-programs.md), [법칙, 시나리오, 증거](laws.md) +개념: [참조 투명성](../concepts/referential_transparency.md) +``` + +```admonish note title="개요" +의미 우선 Rust는 타입으로 의미 구조를 명확히 드러냅니다. 연관 타입은 기반 집합 계열에 이름을 붙이고, 바운드는 그 사이의 관계를 명시하며, 확장은 명시된 전제에서 새 연산을 도출합니다. 모든 해석이 보존해야 하는 것은 여전히 법칙으로 정합니다. +``` + +Rust에서는 여러 역할이 모두 `type`로 표기됩니다. 이를 구분하면 의미가 표현으로 뭉개지는 일을 막을 수 있습니다. + +| 역할 | 예 | 설명하는 내용 | +| --- | --- | --- | +| 의미 타입 | `Direction` | 어떤 영역의 구분이 중요한지 | +| 인터프리터가 선택하는 기반 집합 | `BranchAlg::Branch` | 인터프리터가 선택하는 표현 | +| 파생 연산 | `BranchExt::branch_child` | 선언된 케이퍼빌리티에서 무엇이 따라오는지 | +| 단계 타입 | `Syntax`, `CoreProgram`, `Executable` | 값이 어떤 변환을 거쳤는지 | +| 표현 타입 | `BitBranch` | 인터프리터 하나가 분기의 의미를 저장하는 방식 | +| 증거 프로그램 | 시나리오 또는 재사용 가능한 법칙 확장 | 호환 인터프리터가 만족해야 하는 관찰 | + +## 표현보다 의미 타입을 먼저 {#semantic-types-before-representation} + +분기 영역이 두 방향을 구분한다고 가정해 봅시다: + +```rust,noplayground +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +enum Direction { + Left, + Right, +} +``` + +`Direction`은 그 구분을 직접 나타냅니다. 한 인터프리터는 경로를 간결하게 인코딩할 수 있습니다: + +```rust,noplayground +struct BitBranch(Vec); +``` + +불리언은 그 표현에 속합니다. 왼쪽과 오른쪽의 정의가 아니며, 다른 인터프리터는 불리언을 사용하지 않아도 됩니다. + +```admonish warning title="간결한 인코딩은 의미 타입이 아닙니다" +비트 위치, 바이트 오프셋, 기계 분기로 영역의 동작을 정의하지 마세요. 그런 산출물은 의미론적 구분을 인코딩해야 하지만, 그 구분의 주인이 되지는 않습니다. +``` + +이 분리 덕분에 저장 및 실행 배치를 바꾸더라도 영역의 의미가 소리 없이 바뀌지 않습니다. + +## 연관 타입으로 기반 집합 선택하기 {#associated-types-choose-carriers} + +케이퍼빌리티 대수는 기반 집합 선택을 인터프리터마다 다르게 둘 수 있습니다: + +```rust,noplayground +trait BranchAlg { + type Branch; + + fn branch_root(&self) -> Self::Branch; + fn branch_grow(&self, branch: &Self::Branch, direction: Direction) -> Self::Branch; + fn branch_path( + &self, + ancestor: &Self::Branch, + descendant: &Self::Branch, + ) -> Option>; +} +``` + +`Self::Branch`은 숨겨진 필드 타입이 아닙니다. 분기 의미를 해석하면서 선택한 기반 집합입니다. 비트 경로, 수치 트리 위치, 기호 항 등 어떤 표현도 같은 대수를 만족할 수 있습니다. + +인터프리터 `T`에 대해 표기 `T::Branch`을 기반 집합 계열 $\mathsf{Branch}(T)$로 읽을 수 있습니다. 인터프리터가 바뀌면 기반 집합은 달라질 수 있지만, 모든 연산은 같은 선택을 일관되게 따릅니다. + +## 확장으로 결과를 도출하기 {#extensions-derive-consequences} + +확장은 필요한 전제만으로 새 연산을 구성할 수 있습니다: + +```rust,noplayground +#[ext(name = BranchExt)] +pub impl This +where + This: BranchAlg, +{ + fn branch_child( + &self, + branch: &This::Branch, + direction: Direction, + ) -> This::Branch { + self.branch_grow(branch, direction) + } +} +``` + +`where` 절은 전제입니다. `This`가 분기 대수를 해석합니다. 메서드는 그 결과입니다. 해당 인터프리터의 기반 집합에서는 분기와 방향으로 자식 분기가 정해집니다. + +$$ \bigl(T : \mathsf{BranchAlg}\bigr) \Longrightarrow \mathsf{branchChild}_T : \mathsf{Branch}(T) \times \mathsf{Direction} \to \mathsf{Branch}(T) $$ + +도출 과정에서 구체적인 분기 표현을 선택하지 않습니다. 결과는 인터프리터가 선택한 기반 집합 계열에 그대로 남습니다. + +## 동등성 바운드로 호환성을 명시하기 {#equality-bounds-state-compatibility} + +두 케이퍼빌리티가 같은 기반 집합을 사용해야 할 때가 있습니다. 연관 타입 동등성으로 구체 표현을 고르지 않고 그 요구를 명시할 수 있습니다: + +```rust,noplayground +Right: BranchAlg +``` + +이 바운드는 국소 명제처럼 읽으면 됩니다. `Left`과 `Right`은 같은 기반 집합에서 분기 연산을 해석합니다. 이 동등성은 두 대수 전체에 강제하지 말고, 일치가 필요한 연산에 두세요. + +이런 바운드는 두 구현을 우연히 담고 있다는 이유만으로 구체적인 컨텍스트를 받는 것보다 더 강하고 정확합니다. + +## 단계 타입으로 컴파일러 계약 드러내기 {#stage-types-make-compiler-contracts-visible} + +컴파일러 파이프라인이 모든 단계를 구분 없는 트리 하나로 처리해서는 안 됩니다. 서로 다른 단계 타입은 어떤 변환이 이루어졌는지 명시합니다: + +| 단계 | 입력 | 출력 | 계약 | +| --- | --- | --- | --- | +| 파싱 | 소스 텍스트 | `Syntax` | 표면 문법을 인식합니다 | +| 정규화 | `Syntax` | `CoreProgram` | 선택한 핵심 의미를 생성합니다 | +| 코드 생성 | `CoreProgram` | `Executable` | 실행 가능한 형식에서도 프로그램 관찰을 보존합니다 | +| 런타임 | `Executable` | 관찰 가능한 동작 | 언어 모델에 맞게 실행 코드를 일관되게 해석합니다 | + +이 타입들은 단계 혼동을 막지만, 타입 이름만으로 보존을 증명하지는 못합니다. 변환에는 여전히 명시적인 법칙, 대표 시나리오, 인터프리터 간 증거가 필요합니다. + +## 계약 읽기 {#read-the-contract} + +타입 수준 구조는 다음과 같은 논리적 해석을 허용합니다: + +| Rust 표현 | 해석 | +| --- | --- | +| `This: BranchAlg` | `This`가 분기 의미의 해석을 제공합니다 | +| `This::Branch` | 분기 기반 집합은 `This`가 선택합니다 | +| `Right: BranchAlg` | 두 해석이 기반 집합에서 일치합니다 | +| `-> This::Branch` | 결과는 선택된 기반 집합 계열에 남습니다 | + +이런 식으로 읽으면 타입을 결정하는 요소, 합성에 필요한 동등성, 전제에서 따라오는 결론을 API에 드러낼 수 있습니다. 기초 구분이 실제로 존재한다면 연관 타입, 제네릭 연관 타입, const 제네릭, 타입 상태, 크기가 0인 증거 타입으로 계약의 일부를 표현할 수 있습니다. + +구현을 더 형식적으로 보이게 하려고 타입 수준 장치를 만들어 내지 마세요. 타입은 표현을 장식하는 대신 의미나 필요한 관계를 드러내야 합니다. + +## 타입이 법칙을 대체하지 않습니다 {#types-do-not-replace-laws} + +타입 시그니처는 어떤 프로그램을 만들 수 있는지 제약합니다. 법칙은 그 연산들이 어떤 관계인지 제약합니다. 둘 다 필요합니다. + +예를 들어 `BranchAlg::Branch`은 각 인터프리터가 분기 기반 집합을 선택한다고 말합니다. 그것만으로 다음이 보장되지는 않습니다: + +* 분기에서 자기 자신으로 가는 경로는 비어 있습니다 +* 루트 경로를 다시 적용하면 해당 분기가 재구성됩니다 +* 서로 반대 방향의 자식은 서로 다릅니다 + +이는 호환 인터프리터가 공유하는 의미론적 법칙입니다. 사용하지 않는 비트가 0이라는 주장과 같은 표현별 주장은 해당 표현을 선택한 인터프리터에 속합니다. + +```admonish quote title="타입을 주장으로 읽기" +각 타입이 무엇을 주장하는지, 무엇이 그 타입을 결정하는지, 어떤 법칙으로 완성되는지, 어떤 인터프리터가 실현하는지 물으세요. +``` + +## 검토 항목 {#review-checks} + +* 영역의 구분을 간결한 기계 인코딩보다 먼저 정의했나요? +* 연관 타입이 위장된 구체 상태가 아니라 인터프리터가 선택하는 기반 집합인가요? +* 동등성 바운드가 사용 지점에 필요한 호환성만 명시하나요? +* 컴파일러의 각 단계에 별도 타입과 명시적 계약이 있나요? +* 의미론적 명제와 표현 불변량을 구분했나요? +* Rust로 표현할 수 없는 주장을 재사용 가능한 법칙이나 시나리오로 뒷받침하나요? diff --git a/src/rust-dd/semantic-types.ru.md b/src/rust-dd/semantic-types.ru.md new file mode 100644 index 0000000..27883c0 --- /dev/null +++ b/src/rust-dd/semantic-types.ru.md @@ -0,0 +1,163 @@ + + +# Семантические типы в Rust {#semantic-types-in-rust} + +```admonish tip title="Связанные материалы" +«Семантический взгляд»: [Зависимые типы и доказательства](../denotational-design/dependent-types.md), [Денотационное проектирование](../denotational-design/design.md) +«Проектирование на основе смысла в Rust»: [Алгебры возможностей](capability-algebras.md), [Программы первого порядка](first-order-programs.md), [Законы, сценарии и свидетельства](laws.md) +«Понятия»: [Референциальная прозрачность](../concepts/referential_transparency.md) +``` + +```admonish note title="Обзор" +В Rust, ориентированном на смысл, типы помогают сохранять видимость семантической структуры. Ассоциированные типы называют семейства носителей, ограничения задают отношения между ними, а методы-расширения выводят новые операции из явных предпосылок. Законы по-прежнему определяют, что обязана сохранять каждая интерпретация. +``` + +В Rust несколько разных понятий записываются как `type`. Если различать их роли, смысл не будет сводиться к представлению. + +| Роль | Пример | Что выражает | +| --- | --- | --- | +| Семантический тип | `Direction` | Какие различия предметной области важны | +| Носитель, выбранный интерпретатором | `BranchAlg::Branch` | Какое представление выбирает интерпретатор | +| Производная операция | `BranchExt::branch_child` | Что следует из объявленных возможностей | +| Тип этапа | `Syntax`, `CoreProgram`, `Executable` | Какие преобразования уже прошли значение | +| Тип представления | `BitBranch` | Как интерпретатор хранит смысл ветвления | +| Программа-свидетельство | Сценарий или повторно используемое расширение с законами | Каким наблюдениям должны соответствовать совместимые интерпретаторы | + +## Семантические типы — прежде представления {#semantic-types-before-representation} + +Предположим, предметная область ветвления различает два направления: + +```rust,noplayground +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +enum Direction { + Left, + Right, +} +``` + +`Direction` напрямую задаёт это различие. Один интерпретатор может компактно кодировать путь: + +```rust,noplayground +struct BitBranch(Vec); +``` + +Логические значения относятся к этому представлению. Они не определяют смысл направлений «влево» и «вправо» и не обязательны для других интерпретаторов. + +```admonish warning title="Компактное кодирование — не семантический тип" +Не определяйте поведение предметной области через позиции битов, смещения байтов или машинные переходы. Эти артефакты должны кодировать семантические различия, а не владеть ими. +``` + +Такое разделение позволяет менять схемы хранения и выполнения, не изменяя незаметно предметную область. + +## Ассоциированные типы выбирают носители {#associated-types-choose-carriers} + +Алгебра возможностей может оставить выбор носителя каждому интерпретатору: + +```rust,noplayground +trait BranchAlg { + type Branch; + + fn branch_root(&self) -> Self::Branch; + fn branch_grow(&self, branch: &Self::Branch, direction: Direction) -> Self::Branch; + fn branch_path( + &self, + ancestor: &Self::Branch, + descendant: &Self::Branch, + ) -> Option>; +} +``` + +`Self::Branch` — не скрытый тип поля. Это носитель, выбранный при интерпретации смысла ветвления. Одной и той же алгебре могут соответствовать путь из битов, числовая позиция в дереве, символьный терм или другое представление. + +Для интерпретатора `T` запись `T::Branch` можно читать как семейство носителей $\mathsf{Branch}(T)$. При смене интерпретатора носитель может измениться, но все операции последовательно используют один и тот же выбор. + +## Расширения выводят следствия {#extensions-derive-consequences} + +Расширение может построить новую операцию, используя ровно те предпосылки, которые ему нужны: + +```rust,noplayground +#[ext(name = BranchExt)] +pub impl This +where + This: BranchAlg, +{ + fn branch_child( + &self, + branch: &This::Branch, + direction: Direction, + ) -> This::Branch { + self.branch_grow(branch, direction) + } +} +``` + +Условие `where` — это предпосылка: `This` интерпретирует алгебру ветвления. Метод — следствие: для носителя этого интерпретатора ветвь и направление однозначно задают дочернюю ветвь. + +$$ \bigl(T : \mathsf{BranchAlg}\bigr) \Longrightarrow \mathsf{branchChild}_T : \mathsf{Branch}(T) \times \mathsf{Direction} \to \mathsf{Branch}(T) $$ + +Ни в одном шаге вывода не выбирается конкретное представление ветви. Результат остаётся в семействе носителей, выбранном интерпретатором. + +## Ограничения равенства задают совместимость {#equality-bounds-state-compatibility} + +Двум возможностям иногда требуется общий носитель. Равенство ассоциированных типов задаёт это требование, не выбирая конкретное представление: + +```rust,noplayground +Right: BranchAlg +``` + +Прочитайте ограничение как локальное утверждение: `Left` и `Right` интерпретируют операции ветвления над одним носителем. Указывайте это равенство при операции, которой нужно согласование, а не навязывайте его обеим алгебрам глобально. + +Такое ограничение точнее и сильнее, чем принятие конкретного контекста только потому, что он случайно содержит обе реализации. + +## Типы этапов делают контракты компилятора явными {#stage-types-make-compiler-contracts-visible} + +В конвейере компилятора нельзя передавать одно неразличимое дерево через все фазы. Отдельные типы этапов указывают, какое преобразование уже выполнено: + +| Этап | Вход | Выход | Контракт | +| --- | --- | --- | --- | +| Разбор | Исходный текст | `Syntax` | Распознаёт поверхностную грамматику | +| Нормализация | `Syntax` | `CoreProgram` | Формирует выбранный базовый смысл | +| Генерация кода | `CoreProgram` | `Executable` | Сохраняет наблюдения программы в исполняемой форме | +| Среда выполнения | `Executable` | Наблюдаемое поведение | Интерпретирует исполняемый файл в соответствии с моделью языка | + +Эти типы предотвращают случайную путаницу между этапами, но одних названий недостаточно, чтобы доказать сохранение смысла. Для преобразований по-прежнему нужны сформулированные законы, характерные сценарии и свидетельства на нескольких интерпретаторах. + +## Прочитайте контракт {#read-the-contract} + +Структуру типов можно полезно прочитать с логической точки зрения: + +| Конструкция Rust | Как её читать | +| --- | --- | +| `This: BranchAlg` | `This` предоставляет интерпретацию смысла ветвления | +| `This::Branch` | Носитель ветвления выбирает `This` | +| `Right: BranchAlg` | Две интерпретации согласованы относительно носителя | +| `-> This::Branch` | Результат остаётся в выбранном семействе носителей | + +Такое прочтение помогает проектировать API, раскрывающие, что определяет тип, какие равенства нужны для композиции и какие выводы следуют из предпосылок. Ассоциированные типы, обобщённые ассоциированные типы, обобщённые константные параметры, типовые состояния и свидетели нулевого размера могут выражать части таких контрактов, если лежащее в их основе различие действительно существует. + +Не создавайте типовые механизмы лишь для того, чтобы реализация выглядела формальнее. Тип должен выражать смысл или сохранять необходимое отношение, а не украшать представление. + +## Типы не заменяют законы {#types-do-not-replace-laws} + +Сигнатура типа ограничивает множество допустимых программ. Законы задают отношения между операциями. Нужны и то и другое. + +Например, `BranchAlg::Branch` указывает, что каждый интерпретатор выбирает носитель ветвления. Само по себе это не устанавливает, что: + +* путь от ветви к ней самой пуст +* повторное прохождение пути от корня восстанавливает ветвь +* противоположные дочерние ветви различны + +Это семантические законы, общие для совместимых интерпретаторов. Утверждения, зависящие от представления, например о нулевых неиспользуемых битах, относятся к интерпретатору, который выбрал это представление. + +```admonish quote title="Читайте типы как утверждения" +Спрашивайте, что утверждает каждый тип, что определяет его, какими законами он дополняется и какой интерпретатор его реализует. +``` + +## Проверочные вопросы {#review-checks} + +* Появляется ли различие предметной области до его компактного машинного кодирования? +* Является ли ассоциированный тип носителем, выбранным интерпретатором, а не замаскированным конкретным состоянием? +* Задают ли ограничения равенства только совместимость, нужную в месте их использования? +* Имеют ли разные этапы компилятора отдельные типы и явные контракты? +* Отделены ли семантические утверждения от инвариантов представления? +* Подкреплены ли повторно используемыми законами или сценариями утверждения, которые Rust не может выразить? diff --git a/src/rust-dd/semantic-types.uk.md b/src/rust-dd/semantic-types.uk.md new file mode 100644 index 0000000..f54220b --- /dev/null +++ b/src/rust-dd/semantic-types.uk.md @@ -0,0 +1,163 @@ + + +# Семантичні типи в Rust {#semantic-types-in-rust} + +```admonish tip title="Пов’язані матеріали" +Семантичний погляд: [Залежні типи та доведення](../denotational-design/dependent-types.md), [Денотаційне проєктування](../denotational-design/design.md) +Проєктування від значення в Rust: [Алгебри можливостей](capability-algebras.md), [Програми першого порядку](first-order-programs.md), [Закони, сценарії та свідчення](laws.md) +Поняття: [Референційна прозорість](../concepts/referential_transparency.md) +``` + +```admonish note title="Вступний огляд" +У Rust, орієнтованому на значення, типи допомагають зберігати видимість семантичної структури. Асоційовані типи називають сімейства носіїв, обмеження визначають зв’язки між ними, а розширення виводять нові операції з явних передумов. Закони й далі визначають, що має зберігати кожна інтерпретація. +``` + +У Rust кілька різних понять записуються однаково — `type`. Якщо чітко їх розрізняти, значення не зводитиметься до представлення. + +| Роль | Приклад | Що визначає | +| --- | --- | --- | +| Семантичний тип | `Direction` | Які відмінності предметної області важливі | +| Носій, вибраний інтерпретатором | `BranchAlg::Branch` | Яке представлення вибирає інтерпретатор | +| Похідна операція | `BranchExt::branch_child` | Що випливає із заявлених можливостей | +| Тип етапу | `Syntax`, `CoreProgram`, `Executable` | Яке перетворення пройшло значення | +| Тип представлення | `BitBranch` | Як один інтерпретатор зберігає значення розгалуження | +| Програма-свідчення | Сценарій або повторно використовуване розширення закону | Які спостереження мають виконувати сумісні інтерпретатори | + +## Спершу семантичні типи, потім представлення {#semantic-types-before-representation} + +Припустімо, область розгалуження розрізняє два напрямки: + +```rust,noplayground +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +enum Direction { + Left, + Right, +} +``` + +`Direction` безпосередньо називає цю відмінність. Один інтерпретатор може компактно закодувати шлях: + +```rust,noplayground +struct BitBranch(Vec); +``` + +Булеві значення належать до цього представлення. Вони не визначають поняття «ліворуч» і «праворуч», і інший інтерпретатор не зобов’язаний їх використовувати. + +```admonish warning title="Компактне кодування — це не семантичний тип" +Не визначайте поведінку предметної області позиціями бітів, зміщеннями байтів чи машинними переходами. Такі артефакти мають кодувати семантичні відмінності, а не визначати їх. +``` + +Таке розділення дає змогу змінювати сховища й структуру виконання, не змінюючи непомітно предметну область. + +## Асоційовані типи вибирають носії {#associated-types-choose-carriers} + +Алгебра можливостей може залишити вибір носія кожному інтерпретатору: + +```rust,noplayground +trait BranchAlg { + type Branch; + + fn branch_root(&self) -> Self::Branch; + fn branch_grow(&self, branch: &Self::Branch, direction: Direction) -> Self::Branch; + fn branch_path( + &self, + ancestor: &Self::Branch, + descendant: &Self::Branch, + ) -> Option>; +} +``` + +`Self::Branch` — не тип прихованого поля. Це носій, який вибирає інтерпретація значення розгалуження. Та сама алгебра допускає бітовий шлях, числову позицію в дереві, символьний терм або інше представлення. + +Для інтерпретатора `T` позначення `T::Branch` можна прочитати як сімейство носіїв $\mathsf{Branch}(T)$. Зміна інтерпретатора може змінити носій, але всі операції залишаються послідовно індексованими одним і тим самим вибором. + +## Розширення виводять наслідки {#extensions-derive-consequences} + +Розширення може побудувати нову операцію лише з потрібних передумов: + +```rust,noplayground +#[ext(name = BranchExt)] +pub impl This +where + This: BranchAlg, +{ + fn branch_child( + &self, + branch: &This::Branch, + direction: Direction, + ) -> This::Branch { + self.branch_grow(branch, direction) + } +} +``` + +Умова `where` є передумовою: `This` інтерпретує алгебру розгалуження. Метод є наслідком: для носія цього інтерпретатора гілка й напрямок визначають дочірню гілку. + +$$ \bigl(T : \mathsf{BranchAlg}\bigr) \Longrightarrow \mathsf{branchChild}_T : \mathsf{Branch}(T) \times \mathsf{Direction} \to \mathsf{Branch}(T) $$ + +Жоден крок виведення не вибирає конкретне представлення гілки. Результат залишається в сімействі носіїв, вибраному інтерпретатором. + +## Обмеження рівності типів визначають сумісність {#equality-bounds-state-compatibility} + +Іноді дві можливості мають використовувати спільний носій. Рівність асоційованих типів дає змогу сформулювати цю вимогу, не вибираючи конкретне представлення: + +```rust,noplayground +Right: BranchAlg +``` + +Читайте це обмеження як локальне твердження: `Left` та `Right` інтерпретують операції розгалуження з тим самим носієм. Додавайте цю рівність до операції, якій потрібна узгодженість, замість глобального обмеження обох алгебр. + +Таке обмеження сильніше й точніше, ніж вимагати конкретного спільного контексту лише тому, що він випадково містить обидві реалізації. + +## Типи етапів роблять контракти компілятора явними {#stage-types-make-compiler-contracts-visible} + +Конвеєр компілятора не має передавати одне нерозрізнене дерево через кожну фазу. Окремі типи етапів визначають, які перетворення вже виконано: + +| Етап | Вхід | Вихід | Контракт | +| --- | --- | --- | --- | +| Синтаксичний розбір | Вихідний текст | `Syntax` | Розпізнає синтаксис мови | +| Нормалізація | `Syntax` | `CoreProgram` | Виводить вибране основне значення | +| Генерація коду | `CoreProgram` | `Executable` | Зберігає спостереження програми у виконуваній формі | +| Середовище виконання | `Executable` | Спостережувана поведінка | Інтерпретує виконуваний код узгоджено з моделлю мови | + +Ці типи запобігають випадковій плутанині між етапами, але самі назви не доводять збереження значення. Для перетворень усе ще потрібні сформульовані закони, репрезентативні сценарії та свідчення, спільні для різних інтерпретаторів. + +## Прочитайте контракт {#read-the-contract} + +Структуру типів можна корисно тлумачити в логічних термінах: + +| Форма Rust | Тлумачення | +| --- | --- | +| `This: BranchAlg` | `This` задає інтерпретацію значення розгалуження | +| `This::Branch` | Носій гілки вибирається через `This` | +| `Right: BranchAlg` | Дві інтерпретації мають спільний носій | +| `-> This::Branch` | Результат лишається в вибраному сімействі носіїв | + +Таке тлумачення спонукає створювати API, які показують, що визначає тип, якої рівності вимагає композиція та які висновки випливають із передумов. Асоційовані типи, узагальнені асоційовані типи, константні узагальнення, типізація станів і нуль-розмірні свідки можуть виражати частини таких контрактів, якщо відповідне розрізнення справді існує. + +Не створюйте механізми на рівні типів лише для формальнішого вигляду реалізації. Тип має виражати значення або зберігати потрібний зв’язок, а не прикрашати представлення. + +## Типи не замінюють закони {#types-do-not-replace-laws} + +Сигнатура типу обмежує множину програм, які можна побудувати. Закони визначають взаємозв’язки між їхніми операціями. Потрібні обидва. + +Наприклад, `BranchAlg::Branch` визначає, що кожен інтерпретатор вибирає носій гілки. Але саме по собі це не встановлює, що: + +* шлях від гілки до неї самої є порожнім +* повторне проходження шляху від кореня відновлює гілку +* протилежні дочірні гілки є різними + +Це семантичні закони, спільні для сумісних інтерпретаторів. Твердження, що стосуються лише певного представлення, як-от нульові невикористані біти, належать до інтерпретатора, який вибрав це представлення. + +```admonish quote title="Сприймайте типи як твердження" +З’ясовуйте, що стверджує кожен тип, що його визначає, які закони доповнюють його та який інтерпретатор його втілює. +``` + +## Перевірка {#review-checks} + +* Чи визначено відмінність предметної області до її компактного машинного кодування? +* Чи є асоційований тип носієм, який вибирає інтерпретатор, а не замаскованим конкретним станом? +* Чи визначають обмеження рівності лише сумісність, потрібну в цьому місці використання? +* Чи мають окремі етапи компілятора власні типи й явні контракти? +* Чи розділено семантичні твердження та інваріанти представлення? +* Чи підкріплено повторно використовуваними законами або сценаріями твердження, які Rust не може виразити? diff --git a/src/rust-dd/semantic-types.vi.md b/src/rust-dd/semantic-types.vi.md new file mode 100644 index 0000000..a2be854 --- /dev/null +++ b/src/rust-dd/semantic-types.vi.md @@ -0,0 +1,163 @@ + + +# Kiểu ngữ nghĩa trong Rust {#semantic-types-in-rust} + +```admonish tip title="Liên quan" +Góc nhìn ngữ nghĩa: [Kiểu phụ thuộc và chứng minh](../denotational-design/dependent-types.md), [Thiết kế theo ngữ nghĩa](../denotational-design/design.md) +Thiết kế theo ngữ nghĩa trong Rust: [Các đại số năng lực](capability-algebras.md), [Chương trình bậc nhất](first-order-programs.md), [Định luật, tình huống và bằng chứng](laws.md) +Khái niệm: [Tính minh bạch tham chiếu](../concepts/referential_transparency.md) +``` + +```admonish note title="Định hướng" +Rust lấy ý nghĩa làm trọng tâm dùng kiểu để giữ cho cấu trúc ngữ nghĩa luôn hiển thị. Kiểu liên kết đặt tên cho các họ đối tượng mang, ràng buộc nêu quan hệ giữa chúng, còn phần mở rộng suy ra phép toán mới từ các tiền đề tường minh. Định luật vẫn xác định mọi cách diễn giải phải bảo toàn điều gì. +``` + +Trong Rust, nhiều vai trò khác nhau đều được viết là `type`. Phân biệt chúng giúp ý nghĩa không sụp đổ thành biểu diễn. + +| Vai trò | Ví dụ | Nội dung được phát biểu | +| --- | --- | --- | +| Kiểu ngữ nghĩa | `Direction` | Những khác biệt nào trong miền quan trọng | +| Đối tượng mang do bộ diễn giải chọn | `BranchAlg::Branch` | Bộ diễn giải chọn cách biểu diễn nào | +| Phép toán suy ra | `BranchExt::branch_child` | Điều gì được suy ra từ các năng lực đã khai báo | +| Kiểu giai đoạn | `Syntax`, `CoreProgram`, `Executable` | Giá trị đã trải qua phép biến đổi nào | +| Kiểu biểu diễn | `BitBranch` | Một bộ diễn giải lưu trữ ý nghĩa nhánh như thế nào | +| Chương trình bằng chứng | Một tình huống hoặc phần mở rộng định luật có thể tái sử dụng | Các quan sát mà bộ diễn giải tương thích phải thỏa mãn | + +## Kiểu ngữ nghĩa trước biểu diễn {#semantic-types-before-representation} + +Giả sử một miền phân nhánh phân biệt hai hướng: + +```rust,noplayground +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +enum Direction { + Left, + Right, +} +``` + +`Direction` nêu trực tiếp sự phân biệt đó. Một bộ diễn giải có thể mã hóa gọn đường đi: + +```rust,noplayground +struct BitBranch(Vec); +``` + +Các giá trị boolean thuộc về cách biểu diễn đó. Chúng không định nghĩa trái và phải, và bộ diễn giải khác không cần dùng đến chúng. + +```admonish warning title="Mã hóa gọn không phải kiểu ngữ nghĩa" +Đừng định nghĩa hành vi miền bằng vị trí bit, độ lệch byte hay nhánh máy. Những tạo phẩm đó phải mã hóa các khác biệt ngữ nghĩa, chứ không sở hữu chúng. +``` + +Sự phân tách này cho phép thay đổi bố cục lưu trữ và thực thi mà không âm thầm thay đổi miền. + +## Kiểu liên kết chọn đối tượng mang {#associated-types-choose-carriers} + +Đại số năng lực có thể để mỗi bộ diễn giải quyết định đối tượng mang: + +```rust,noplayground +trait BranchAlg { + type Branch; + + fn branch_root(&self) -> Self::Branch; + fn branch_grow(&self, branch: &Self::Branch, direction: Direction) -> Self::Branch; + fn branch_path( + &self, + ancestor: &Self::Branch, + descendant: &Self::Branch, + ) -> Option>; +} +``` + +`Self::Branch` không phải kiểu trường bị che giấu. Đây là đối tượng mang được cách diễn giải ý nghĩa nhánh chọn. Đường đi bit, vị trí cây số, số hạng ký hiệu hoặc cách biểu diễn khác đều có thể thỏa mãn cùng đại số. + +Với bộ diễn giải `T`, có thể đọc ký hiệu `T::Branch` như họ đối tượng mang $\mathsf{Branch}(T)$. Thay đổi bộ diễn giải có thể làm thay đổi đối tượng mang, trong khi mọi phép toán vẫn được đánh chỉ mục nhất quán theo cùng lựa chọn. + +## Phần mở rộng suy ra hệ quả {#extensions-derive-consequences} + +Phần mở rộng có thể tạo phép toán mới chỉ từ đúng các tiền đề cần thiết: + +```rust,noplayground +#[ext(name = BranchExt)] +pub impl This +where + This: BranchAlg, +{ + fn branch_child( + &self, + branch: &This::Branch, + direction: Direction, + ) -> This::Branch { + self.branch_grow(branch, direction) + } +} +``` + +Mệnh đề `where` là tiền đề: `This` diễn giải đại số nhánh. Phương thức là hệ quả: đối với đối tượng mang của bộ diễn giải đó, một nhánh và một hướng xác định nhánh con. + +$$ \bigl(T : \mathsf{BranchAlg}\bigr) \Longrightarrow \mathsf{branchChild}_T : \mathsf{Branch}(T) \times \mathsf{Direction} \to \mathsf{Branch}(T) $$ + +Không có gì trong phép suy ra này chọn cách biểu diễn nhánh cụ thể. Kết quả vẫn thuộc họ đối tượng mang do bộ diễn giải chọn. + +## Ràng buộc đẳng thức nêu tính tương thích {#equality-bounds-state-compatibility} + +Đôi khi hai năng lực cần thống nhất về một đối tượng mang. Đẳng thức kiểu liên kết có thể nêu yêu cầu đó mà không chọn cách biểu diễn cụ thể: + +```rust,noplayground +Right: BranchAlg +``` + +Hãy đọc ràng buộc như một mệnh đề cục bộ: `Left` và `Right` diễn giải các phép toán nhánh trên cùng đối tượng mang. Đặt đẳng thức ở phép toán cần sự thống nhất, thay vì ép áp dụng toàn cục lên một trong hai đại số. + +Ràng buộc như vậy mạnh và chính xác hơn việc nhận một ngữ cảnh cụ thể chỉ vì nó tình cờ chứa cả hai cách triển khai. + +## Kiểu giai đoạn làm lộ hợp đồng trình biên dịch {#stage-types-make-compiler-contracts-visible} + +Quy trình trình biên dịch không nên chuyển cùng một cây không phân biệt qua mọi giai đoạn. Các kiểu giai đoạn riêng biệt nêu rõ phép biến đổi nào đã diễn ra: + +| Giai đoạn | Đầu vào | Đầu ra | Hợp đồng | +| --- | --- | --- | --- | +| Phân tích cú pháp | Văn bản nguồn | `Syntax` | Nhận diện ngữ pháp bề mặt | +| Chuẩn hóa | `Syntax` | `CoreProgram` | Tạo ra ý nghĩa lõi đã chọn | +| Sinh mã | `CoreProgram` | `Executable` | Bảo toàn các quan sát chương trình trong dạng thực thi được | +| Môi trường chạy | `Executable` | Hành vi quan sát được | Diễn giải tệp thực thi nhất quán với mô hình ngôn ngữ | + +Các kiểu này ngăn nhầm lẫn giai đoạn ngoài ý muốn, nhưng chỉ tên gọi không chứng minh được tính bảo toàn. Các phép biến đổi vẫn cần định luật được nêu rõ, tình huống tiêu biểu và bằng chứng so sánh giữa các bộ diễn giải. + +## Đọc hợp đồng {#read-the-contract} + +Cấu trúc ở cấp kiểu cho phép một cách đọc logic hữu ích: + +| Dạng Rust | Cách đọc | +| --- | --- | +| `This: BranchAlg` | `This` cung cấp một cách diễn giải ý nghĩa nhánh | +| `This::Branch` | Đối tượng mang nhánh do `This` chọn | +| `Right: BranchAlg` | Hai cách diễn giải thống nhất về đối tượng mang | +| `-> This::Branch` | Kết quả vẫn thuộc họ đối tượng mang đã chọn | + +Cách đọc này khuyến khích API bộc lộ yếu tố quyết định một kiểu, các đẳng thức mà phép hợp thành cần và kết luận nào suy ra từ những tiền đề đó. Kiểu liên kết, kiểu liên kết tổng quát, generic hằng, typestate và các chứng nhân kích thước bằng không đều có thể biểu đạt một phần hợp đồng như vậy khi sự phân biệt nền tảng là có thật. + +Đừng tạo ra cơ chế cấp kiểu chỉ để làm cho cách triển khai trông hình thức hơn. Kiểu cần bộc lộ ý nghĩa hoặc bảo toàn quan hệ cần thiết, không phải tô điểm cách biểu diễn. + +## Kiểu không thay thế định luật {#types-do-not-replace-laws} + +Chữ ký kiểu giới hạn những chương trình có thể được tạo thành. Định luật ràng buộc quan hệ giữa các phép toán. Cần có cả hai. + +Chẳng hạn, `BranchAlg::Branch` cho biết mỗi bộ diễn giải chọn một đối tượng mang nhánh. Bản thân điều đó không xác lập rằng: + +* đường đi từ một nhánh đến chính nó là rỗng +* phát lại đường đi từ gốc sẽ dựng lại nhánh +* hai nhánh con ngược hướng là khác nhau + +Đó là các định luật ngữ nghĩa mà những bộ diễn giải tương thích cùng chia sẻ. Khẳng định riêng cho một cách biểu diễn — chẳng hạn các bit không dùng đến phải bằng không — thuộc về bộ diễn giải đã chọn cách biểu diễn đó. + +```admonish quote title="Đọc kiểu như các khẳng định" +Hãy hỏi mỗi kiểu khẳng định điều gì, yếu tố nào quyết định kiểu, định luật nào bổ sung cho nó và bộ diễn giải nào hiện thực hóa nó. +``` + +## Các câu hỏi khi duyệt {#review-checks} + +* Khác biệt trong miền có xuất hiện trước cách mã hóa máy gọn nhẹ không? +* Kiểu liên kết có phải là đối tượng mang do bộ diễn giải chọn thay vì trạng thái cụ thể được ngụy trang không? +* Ràng buộc đẳng thức có chỉ nêu tính tương thích cần thiết tại nơi sử dụng đó không? +* Các giai đoạn trình biên dịch khác nhau có kiểu riêng và hợp đồng tường minh không? +* Mệnh đề ngữ nghĩa có được tách khỏi bất biến biểu diễn không? +* Các khẳng định Rust không thể biểu đạt có được hỗ trợ bằng định luật hoặc tình huống tái sử dụng không? diff --git a/src/rust-dd/semantic-types.zh-hant.md b/src/rust-dd/semantic-types.zh-hant.md new file mode 100644 index 0000000..954bda3 --- /dev/null +++ b/src/rust-dd/semantic-types.zh-hant.md @@ -0,0 +1,163 @@ + + +# Rust 中的語義型別 {#semantic-types-in-rust} + +```admonish tip title="相關內容" +語義視角:[依賴型別與證明](../denotational-design/dependent-types.md)、[指稱設計](../denotational-design/design.md) +Rust 中的語義驅動設計:[能力代數](capability-algebras.md)、[一階程式](first-order-programs.md)、[定律、場景與證據](laws.md) +概念:[引用透明性](../concepts/referential_transparency.md) +``` + +```admonish note title="導讀" +依義設計優先的 Rust 使用型別來顯露語義結構。關聯型別為載體族命名,約束陳述它們之間的關係,擴充則從明確前提推導出新操作。定律仍然決定每種解釋都必須保留什麼。 +``` + +在 Rust 中,`type`一詞可以指代多種不同角色。將它們區分開,能避免含義坍縮為表示。 + +| 角色 | 示例 | 表達的內容 | +| --- | --- | --- | +| 語義型別 | `Direction` | 哪些領域區別很重要 | +| 由直譯器選擇的載體 | `BranchAlg::Branch` | 直譯器選擇哪種表示 | +| 派生操作 | `BranchExt::branch_child` | 根據已宣告能力可以推出什麼 | +| 階段型別 | `Syntax`, `CoreProgram`, `Executable` | 某個值經過了哪種變換 | +| 表示型別 | `BitBranch` | 某個直譯器如何儲存分支含義 | +| 證據程式 | 場景或可複用的定律擴充 | 相容直譯器必須滿足哪些觀察 | + +## 表示之前先確定語義型別 {#semantic-types-before-representation} + +假設某個分支領域區分兩個方向: + +```rust,noplayground +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +enum Direction { + Left, + Right, +} +``` + +`Direction`直接表達了這一區別。一種直譯器可以緊湊地編碼路徑: + +```rust,noplayground +struct BitBranch(Vec); +``` + +布林值屬於這種表示。它們並非左右方向的定義,其他直譯器也不必使用它們。 + +```admonish warning title="緊湊編碼不等於語義型別" +不要根據位位置、位元組偏移或機器分支來定義領域行為。這些產物應編碼語義區別,而不是擁有這些區別的定義權。 +``` + +這種區分讓儲存與執行佈局可以改變,而不悄然改變領域本身。 + +## 關聯型別選擇載體 {#associated-types-choose-carriers} + +能力代數可以把載體留給各個直譯器選擇: + +```rust,noplayground +trait BranchAlg { + type Branch; + + fn branch_root(&self) -> Self::Branch; + fn branch_grow(&self, branch: &Self::Branch, direction: Direction) -> Self::Branch; + fn branch_path( + &self, + ancestor: &Self::Branch, + descendant: &Self::Branch, + ) -> Option>; +} +``` + +`Self::Branch`不是隱藏的欄位型別,而是對分支含義作出解釋時所選的載體。位路徑、數值樹位置、符號項或其他表示都可以滿足同一個代數。 + +對於直譯器`T`而言,記法`T::Branch`可以理解為一個載體族$\mathsf{Branch}(T)$。切換直譯器可能改變載體,但每種操作仍會根據同一選擇保持一致索引。 + +## 擴充用於推導結論 {#extensions-derive-consequences} + +擴充可以根據它恰好需要的前提構造新操作: + +```rust,noplayground +#[ext(name = BranchExt)] +pub impl This +where + This: BranchAlg, +{ + fn branch_child( + &self, + branch: &This::Branch, + direction: Direction, + ) -> This::Branch { + self.branch_grow(branch, direction) + } +} +``` + +`where`子句是前提:`This`對分支代數作出解釋。方法則是結論:對於該直譯器的載體,分支與方向決定一個子分支。 + +$$ \bigl(T : \mathsf{BranchAlg}\bigr) \Longrightarrow \mathsf{branchChild}_T : \mathsf{Branch}(T) \times \mathsf{Direction} \to \mathsf{Branch}(T) $$ + +推導過程沒有選擇具體的分支表示。結果仍然屬於直譯器所選的載體族。 + +## 相等約束用於陳述相容性 {#equality-bounds-state-compatibility} + +兩種能力有時需要對載體達成一致。關聯型別相等約束可以陳述這一要求,而無須選擇具體表示: + +```rust,noplayground +Right: BranchAlg +``` + +可以把這個約束讀作一個區域性命題:`Left`和`Right`在同一載體上解釋分支操作。應將這一相等要求放在需要達成一致的操作上,而不是全域性強加給任一代數。 + +與僅僅因為某個具體上下文碰巧同時包含兩種實作就接受它相比,這種約束更強,也更精確。 + +## 階段型別讓編譯器契約一目瞭然 {#stage-types-make-compiler-contracts-visible} + +編譯器流水線不應讓一個無法區分階段的語法樹貫穿所有環節。不同階段型別可以說明已經發生了哪種變換: + +| 階段 | 輸入 | 輸出 | 契約 | +| --- | --- | --- | --- | +| 解析 | 源文字 | `Syntax` | 識別表層語法 | +| 正規化 | `Syntax` | `CoreProgram` | 生成所選的核心含義 | +| 程式碼生成 | `CoreProgram` | `Executable` | 以可執行形式保留程式觀察 | +| 執行時 | `Executable` | 可觀察行為 | 依據語言模型一致地解釋可執行程式 | + +這些型別可防止意外混淆階段,但僅憑名稱無法證明保留性。仍需陳述變換定律、設計代表性場景,並提供跨直譯器證據。 + +## 閱讀契約 {#read-the-contract} + +型別層面的結構可以作如下邏輯解讀: + +| Rust 形式 | 解讀 | +| --- | --- | +| `This: BranchAlg` | `This`提供了對分支含義的解釋 | +| `This::Branch` | 分支載體由`This`選擇 | +| `Right: BranchAlg` | 兩種解釋在載體上保持一致 | +| `-> This::Branch` | 結果仍屬於所選載體族 | + +這種解讀鼓勵 API 顯露決定型別的因素、組合所需的等式,以及這些前提能推出的結論。只要底層區別確實存在,關聯型別、泛型關聯型別、const 泛型、型別狀態與零大小見證都可以表達此類契約的一部分。 + +不要僅僅為了讓實作看起來更形式化,就憑空製造型別層面的機制。型別應當顯露含義或保留必要關係,而不是裝飾一種表示。 + +## 型別不能替代定律 {#types-do-not-replace-laws} + +型別簽名約束哪些程式能夠構造,定律則約束這些程式的操作之間如何關聯。二者缺一不可。 + +例如,`BranchAlg::Branch`說明每個直譯器都會選擇一種分支載體,但它本身並不能確立以下性質: + +* 從某個分支到其自身的路徑為空 +* 重放根路徑可以重構出該分支 +* 相反方向的子節點彼此不同 + +這些是相容直譯器共同遵循的語義定律。特定於表示的主張(例如未使用的位必須為零)則屬於選擇該表示的直譯器。 + +```admonish quote title="將型別視為主張" +詢問每種型別主張什麼、由什麼決定、需要哪些定律補全,以及由哪個直譯器實現。 +``` + +## 審查要點 {#review-checks} + +* 領域區別是否先於緊湊的機器編碼出現? +* 關聯型別是否是由直譯器選擇的載體,而非偽裝的具體狀態? +* 相等約束是否只陳述該使用位置所需的相容性? +* 不同編譯器階段是否採用不同型別並具有明確契約? +* 語義命題是否與表示不變數分開? +* Rust 無法表達的主張是否有可複用定律或場景作為依據? diff --git a/src/rust-dd/semantic-types.zh.md b/src/rust-dd/semantic-types.zh.md new file mode 100644 index 0000000..9a4a55d --- /dev/null +++ b/src/rust-dd/semantic-types.zh.md @@ -0,0 +1,163 @@ + + +# Rust 中的语义类型 {#semantic-types-in-rust} + +```admonish tip title="相关内容" +语义视角:[依赖类型与证明](../denotational-design/dependent-types.md)、[指称设计](../denotational-design/design.md) +Rust 中的语义驱动设计:[能力代数](capability-algebras.md)、[一阶程序](first-order-programs.md)、[定律、场景与证据](laws.md) +概念:[引用透明性](../concepts/referential_transparency.md) +``` + +```admonish note title="导读" +依义设计优先的 Rust 使用类型来显露语义结构。关联类型为载体族命名,约束陈述它们之间的关系,扩展则从明确前提推导出新操作。定律仍然决定每种解释都必须保留什么。 +``` + +在 Rust 中,`type`一词可以指代多种不同角色。将它们区分开,能避免含义坍缩为表示。 + +| 角色 | 示例 | 表达的内容 | +| --- | --- | --- | +| 语义类型 | `Direction` | 哪些领域区别很重要 | +| 由解释器选择的载体 | `BranchAlg::Branch` | 解释器选择哪种表示 | +| 派生操作 | `BranchExt::branch_child` | 根据已声明能力可以推出什么 | +| 阶段类型 | `Syntax`, `CoreProgram`, `Executable` | 某个值经过了哪种变换 | +| 表示类型 | `BitBranch` | 某个解释器如何存储分支含义 | +| 证据程序 | 场景或可复用的定律扩展 | 兼容解释器必须满足哪些观察 | + +## 表示之前先确定语义类型 {#semantic-types-before-representation} + +假设某个分支领域区分两个方向: + +```rust,noplayground +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +enum Direction { + Left, + Right, +} +``` + +`Direction`直接表达了这一区别。一种解释器可以紧凑地编码路径: + +```rust,noplayground +struct BitBranch(Vec); +``` + +布尔值属于这种表示。它们并非左右方向的定义,其他解释器也不必使用它们。 + +```admonish warning title="紧凑编码不等于语义类型" +不要根据位位置、字节偏移或机器分支来定义领域行为。这些产物应编码语义区别,而不是拥有这些区别的定义权。 +``` + +这种区分让存储与执行布局可以改变,而不悄然改变领域本身。 + +## 关联类型选择载体 {#associated-types-choose-carriers} + +能力代数可以把载体留给各个解释器选择: + +```rust,noplayground +trait BranchAlg { + type Branch; + + fn branch_root(&self) -> Self::Branch; + fn branch_grow(&self, branch: &Self::Branch, direction: Direction) -> Self::Branch; + fn branch_path( + &self, + ancestor: &Self::Branch, + descendant: &Self::Branch, + ) -> Option>; +} +``` + +`Self::Branch`不是隐藏的字段类型,而是对分支含义作出解释时所选的载体。位路径、数值树位置、符号项或其他表示都可以满足同一个代数。 + +对于解释器`T`而言,记法`T::Branch`可以理解为一个载体族$\mathsf{Branch}(T)$。切换解释器可能改变载体,但每种操作仍会根据同一选择保持一致索引。 + +## 扩展用于推导结论 {#extensions-derive-consequences} + +扩展可以根据它恰好需要的前提构造新操作: + +```rust,noplayground +#[ext(name = BranchExt)] +pub impl This +where + This: BranchAlg, +{ + fn branch_child( + &self, + branch: &This::Branch, + direction: Direction, + ) -> This::Branch { + self.branch_grow(branch, direction) + } +} +``` + +`where`子句是前提:`This`对分支代数作出解释。方法则是结论:对于该解释器的载体,分支与方向决定一个子分支。 + +$$ \bigl(T : \mathsf{BranchAlg}\bigr) \Longrightarrow \mathsf{branchChild}_T : \mathsf{Branch}(T) \times \mathsf{Direction} \to \mathsf{Branch}(T) $$ + +推导过程没有选择具体的分支表示。结果仍然属于解释器所选的载体族。 + +## 相等约束用于陈述兼容性 {#equality-bounds-state-compatibility} + +两种能力有时需要对载体达成一致。关联类型相等约束可以陈述这一要求,而无须选择具体表示: + +```rust,noplayground +Right: BranchAlg +``` + +可以把这个约束读作一个局部命题:`Left`和`Right`在同一载体上解释分支操作。应将这一相等要求放在需要达成一致的操作上,而不是全局强加给任一代数。 + +与仅仅因为某个具体上下文碰巧同时包含两种实现就接受它相比,这种约束更强,也更精确。 + +## 阶段类型让编译器契约一目了然 {#stage-types-make-compiler-contracts-visible} + +编译器流水线不应让一个无法区分阶段的语法树贯穿所有环节。不同阶段类型可以说明已经发生了哪种变换: + +| 阶段 | 输入 | 输出 | 契约 | +| --- | --- | --- | --- | +| 解析 | 源文本 | `Syntax` | 识别表层语法 | +| 规范化 | `Syntax` | `CoreProgram` | 生成所选的核心含义 | +| 代码生成 | `CoreProgram` | `Executable` | 以可执行形式保留程序观察 | +| 运行时 | `Executable` | 可观察行为 | 依据语言模型一致地解释可执行程序 | + +这些类型可防止意外混淆阶段,但仅凭名称无法证明保留性。仍需陈述变换定律、设计代表性场景,并提供跨解释器证据。 + +## 阅读契约 {#read-the-contract} + +类型层面的结构可以作如下逻辑解读: + +| Rust 形式 | 解读 | +| --- | --- | +| `This: BranchAlg` | `This`提供了对分支含义的解释 | +| `This::Branch` | 分支载体由`This`选择 | +| `Right: BranchAlg` | 两种解释在载体上保持一致 | +| `-> This::Branch` | 结果仍属于所选载体族 | + +这种解读鼓励 API 显露决定类型的因素、组合所需的等式,以及这些前提能推出的结论。只要底层区别确实存在,关联类型、泛型关联类型、const 泛型、类型状态与零大小见证都可以表达此类契约的一部分。 + +不要仅仅为了让实现看起来更形式化,就凭空制造类型层面的机制。类型应当显露含义或保留必要关系,而不是装饰一种表示。 + +## 类型不能替代定律 {#types-do-not-replace-laws} + +类型签名约束哪些程序能够构造,定律则约束这些程序的操作之间如何关联。二者缺一不可。 + +例如,`BranchAlg::Branch`说明每个解释器都会选择一种分支载体,但它本身并不能确立以下性质: + +* 从某个分支到其自身的路径为空 +* 重放根路径可以重构出该分支 +* 相反方向的子节点彼此不同 + +这些是兼容解释器共同遵循的语义定律。特定于表示的主张(例如未使用的位必须为零)则属于选择该表示的解释器。 + +```admonish quote title="将类型视为主张" +询问每种类型主张什么、由什么决定、需要哪些定律补全,以及由哪个解释器实现。 +``` + +## 审查要点 {#review-checks} + +* 领域区别是否先于紧凑的机器编码出现? +* 关联类型是否是由解释器选择的载体,而非伪装的具体状态? +* 相等约束是否只陈述该使用位置所需的兼容性? +* 不同编译器阶段是否采用不同类型并具有明确契约? +* 语义命题是否与表示不变量分开? +* Rust 无法表达的主张是否有可复用定律或场景作为依据? diff --git a/src/rust-dd/workflow.ar.md b/src/rust-dd/workflow.ar.md new file mode 100644 index 0000000..c3e93f4 --- /dev/null +++ b/src/rust-dd/workflow.ar.md @@ -0,0 +1,186 @@ + + +# سير عمل يبدأ بالمعنى {#a-meaning-first-workflow} + +```admonish tip title="ذات صلة" +الرؤية الدلالية: [لماذا يأتي المعنى أولًا](../denotational-design/semantic-view.md) +التصميم انطلاقًا من المعنى في Rust: [جبريات القدرات](capability-algebras.md)، [المعنى المشتق والتركيب](derived-meaning.md)، [القوانين والسيناريوهات والأدلة](laws.md) +``` + +```admonish note title="منهجية قابلة للتكرار" +التصميم الدلالي سير عمل، وليس مجرد شرح لشيفرة مكتملة: صرّح بالتغيير الدلالي، وحدد أصغر القدرات الأولية، وركّبها بصدق، ثم نفذ مفسرات رقيقة وتحقق من القوانين. +``` + +يفيد التصميم الدلالي أكثر بوصفه انضباطًا تطويريًا قابلًا للتكرار، لا مجرد شرح لشيفرة مكتملة. + +## سير العمل الأساسي {#the-core-workflow} + +لإضافة ميزة أو إعادة هيكلة جديدة: + +1. صرّح بالتغيير الدلالي في جملة واحدة. +2. حدد الحامل والمساواة القابلة للملاحظة. +3. اعثر على أصغر القدرات الأولية المطلوبة. +4. عرّف السلوك المشتق بالاعتماد على قدرات صريحة. +5. اختر صيغة التركيب الصادقة. +6. أعد تمثيل برنامج من الرتبة الأولى فقط إذا احتاجت البنية إلى تفسيرات متعددة. +7. نفّذ مفسرات ملموسة رقيقة. +8. أضف قوانين أو سيناريوهات مشتركة. +9. تحقق من التفسيرات البديلة. +10. وثّق المعنى قبل الآليات. + +## صرّح بالتغيير الدلالي {#state-the-semantic-change} + +صياغة ضعيفة: + +> أضف ذاكرة تخزين مؤقتة وأساليب للإدارة. + +صياغة موجهة بالمعنى: + +> يُحيل حل اسم مصدر ثابت إلى قيمة المصدر نفسها خلال عملية تجميع واحدة. + +تكشف الصياغة الثانية قانونًا مرشحًا. ويمكن اختيار التخزين المؤقت لاحقًا بوصفه تنفيذًا واحدًا. + +## اعثر على الحد الأولي {#find-the-primitive-boundary} + +اسأل: + +* ما الملاحظة أو التحويل الجديد المطلوب؟ +* هل هو أولي عند هذا الحد أم قابل للاشتقاق من المعنى القائم؟ +* هل يلزم حامل مرتبط جديد؟ +* هل الاعتماد المفترض مجرد موضع تخزين؟ +* أي الفروق ينبغي أن تظل غير مرئية؟ + +أضف قدرة فقط لمعنى أولي جديد فعلًا. + +## اختر التركيب بصدق {#choose-composition-truthfully} + +استخدم جدول القرار هذا: + +| السؤال | الخيار | +| --- | --- | +| هل يفسر مستقبِل واحد كل المعاني المطلوبة؟ | حدود مباشرة | +| هل يُختار السلوك مستقلًا؟ | قيمة سياسة صريحة | +| هل يمكن تركيب السياسات مستقلًا؟ | حاصل ضرب | +| هل تحتوي البيئة مفسرًا آخر؟ | إسقاط | +| هل يجب أن يحل الغلاف محل المفسر الداخلي؟ | تفويض | + +لا تجعل سمة سياق كبيرة هي الإجابة الافتراضية. + +## أعد هيكلة معنى واحد في كل مرة {#refactor-one-meaning-at-a-time} + +عندما يبدأ الكود القائم بالتمثيل: + +1. حدد ملاحظة دلالية واحدة. +2. عرّف قدرة صغيرة واحدة. +3. انقل اشتقاقًا واحدًا إلى امتداد. +4. أبقِ البنية الحالية مفسرًا لها. +5. أضف اختبارًا على نمط القوانين. + +```admonish warning title="التصميم الدلالي ليس تعظيمًا للتجريد" +تجنب إعادة كتابة نظام فرعي بأكمله ضمن تجريدات تخمينية. فالتصميم الدلالي ليس تعظيمًا للتجريد. +``` + +## راجع من المعنى إلى الآليات {#review-from-meaning-to-machinery} + +اقرأ الشيفرة بهذا الترتيب: + +1. سمات القدرات +2. أنواع القيم الدلالية +3. الامتدادات المشتقة +4. صياغة البرنامج من الرتبة الأولى، إن وجدت +5. القوانين والسيناريوهات المشتركة +6. المفسرات الملموسة +7. تنسيق وقت التشغيل + +البدء بأكبر بنية حالة يوجه المراجعة نحو تمثيلها. + +## أنماط الإخفاق الشائعة {#common-failure-modes} + +````admonish warning title="حالة ملموسة على هيئة سمة ليست تصميمًا دلاليًا" +```rust,noplayground +trait ContextAlg { + fn state(&self) -> &ConcreteState; +} +``` + +تغير السمة الصياغة لا ملكية المعنى. وما زالت النواة الدلالية تعتمد على التمثيل الملموس. +```` + +### المنطق المشتق في كل مفسر {#derived-logic-in-every-interpreter} + +إذا عرّف كل تنفيذ خوارزمية المجال نفسها بصورة مستقلة، فالمواصفة مكررة. + +### قدرة شاملة {#god-capability} + +تخفي السمة الفائقة التي تضم عمليات غير مترابطة صف الاعتمادات، وتمنع التفسير المستقل. + +### المواصفة مملوكة لإطار العمل {#framework-owned-specification} + +إذا كانت تعليقات المسارات أو تسجيل RPC هي التعريف الوحيد للواجهة، فقد ينحرف التوثيق والتنفيذ أحدهما عن الآخر. + +### المعنى مملوك للماكرو {#macro-owned-meaning} + +إذا لم يكن للشيفرة المولدة هدف عام من الرتبة الأولى، يصبح توسع الماكرو مواصفة عرضية. + +### السياسة مخفية في القيم الافتراضية {#policy-hidden-in-defaults} + +إذا كانت `Default` تختار ضمنيًا النصاب أو إعادة المحاولة أو الترتيب أو سياسة التجميع، لم يعد التركيب صريحًا. + +### اختبارات الخطوات الخاصة {#tests-of-private-steps} + +تثبط الاختبارات المرتبطة بتخطيط الحقول أو ترتيب الاجتياز المفسرات البديلة الصحيحة. + +## قائمة مراجعة طلب الدمج {#pull-request-checklist} + +### المعنى {#meaning} + +* هل صُرّح بالتغيير الدلالي؟ +* هل الحامل والمساواة واضحان؟ +* هل سُمّيت حالات الإغفال المقصودة؟ + +### القدرات {#capabilities} + +* هل تكشف كل سمة معنى أوليًا متماسكًا؟ +* هل وُضعت الحدود عند مواضع استخدام العمليات؟ +* هل يتجنب الكود المشتق الحقول الملموسة؟ + +### التركيب {#composition} + +* هل استُخدمت الحدود المباشرة والسياسات وحواصل الضرب والإسقاطات والتفويض بصدق؟ +* هل القيم الافتراضية الدلالية صريحة؟ + +### البرامج والمفسرات {#programs-and-interpreters} + +* هل أُدخلت البنية من الرتبة الأولى فقط حين يحتاج تفسير آخر إليها؟ +* هل يمكن للماكرو الميسّرة أن تخفض إلى قيم برامج عامة؟ +* هل المفسرات الملموسة رقيقة ومحددة بحدودها؟ + +### الأدلة {#evidence} + +* هل يوجد قانون أو تأكيد دلالي مركز؟ +* هل يمكن تشغيل السيناريو نفسه على مفسر آخر؟ +* هل وُصفت الاختبارات المحدودة بوصفها أدلة لا براهين؟ + +## قراءة شيفرة على نمط ALUX {#reading-alux-style-code} + +الشكل العام الذي يجدر تمييزه هو: + +1. سمات صغيرة جدًا للقدرات الأولية +2. امتدادات مشتقة فوق حدود صريحة +3. برامج من الرتبة الأولى عندما يتطلب الفحص أو التركيب ذلك +4. قوانين وسيناريوهات مشتركة +5. مفسرات ملموسة لوقت التشغيل أو المترجم أو HTTP أو RPC أو التخزين + +تظل في الأنظمة الكبيرة المتزامنة مناطق كثيفة التنسيق. لا تفترض أن كل واجهة قائمة هي بالفعل مواصفة دلالية مثالية. ابحث عن الحدود الدلالية واقرأ انطلاقًا منها إلى الخارج. + +يستخدم Tolang المنظور نفسه على نطاق اللغة: تُطبّع الصياغة إلى أشكال حاملة للمعنى، ويحافظ التجميع على ذلك المعنى، ويفسر وقت التشغيل المتزامن التمثيل التنفيذي. يظل الوصف التشغيلي أساسيًا، لكنه يأتي بعد العقد الدلالي. + +## المبدأ الختامي {#final-principle} + +عند الشك، عُد إلى سؤال واحد: + +```admonish quote title="السؤال الذي ينبغي العودة إليه" +ما المعنى الذي يُفترض بهذه الآليات الحفاظ عليه؟ +``` + +لا يحل هذا السؤال كل مشكلة هندسية، لكنه يجعل المشكلة ظاهرة في المستوى الصحيح. diff --git a/src/rust-dd/workflow.de.md b/src/rust-dd/workflow.de.md new file mode 100644 index 0000000..e7c0a38 --- /dev/null +++ b/src/rust-dd/workflow.de.md @@ -0,0 +1,186 @@ + + +# Ein bedeutungsorientierter Arbeitsablauf {#a-meaning-first-workflow} + +```admonish tip title="Verwandte Themen" +The Semantic View: [Warum Bedeutung an erster Stelle steht](../denotational-design/semantic-view.md) +Design by Meaning in Rust: [Capability-Algebren](capability-algebras.md), [Abgeleitete Bedeutung und Komposition](derived-meaning.md), [Gesetze, Szenarien und Nachweise](laws.md) +``` + +```admonish note title="Eine wiederholbare Disziplin" +Denotational Design ist ein Arbeitsablauf, nicht nur eine Erklärung für fertigen Code: Formuliere die semantische Änderung, finde die kleinsten primitiven Capabilities, komponiere sie zutreffend, implementiere anschließend schlanke Interpreter und prüfe die Gesetze. +``` + +Denotational Design ist besonders nützlich als wiederholbare Entwicklungsdisziplin und nicht nur als Erklärung für fertigen Code. + +## Der grundlegende Arbeitsablauf {#the-core-workflow} + +Für ein neues Feature oder Refactoring: + +1. Die semantische Änderung in einem Satz formulieren. +2. Träger und beobachtbare Gleichheit bestimmen. +3. Die kleinsten erforderlichen primitiven Capabilities finden. +4. Abgeleitetes Verhalten über explizite Capabilities definieren. +5. Die passende Kompositionsform auswählen. +6. Ein Programm erster Ordnung nur dann reifizieren, wenn seine Struktur mehrere Interpretationen benötigt. +7. Schlanke konkrete Interpreter implementieren. +8. Gesetze oder gemeinsam genutzte Szenarien ergänzen. +9. Alternative Interpretationen validieren. +10. Die Bedeutung vor den Mechanismen dokumentieren. + +## Die semantische Änderung formulieren {#state-the-semantic-change} + +Schwache Aussage: + +> Einen Cache und eine Manager-Methode hinzufügen. + +Bedeutungsorientierte Aussage: + +> Wird derselbe unveränderliche Quellname während einer Kompilierung aufgelöst, bezeichnet er denselben Quellwert. + +Die zweite Aussage legt ein mögliches Gesetz offen. Ein Cache kann später als eine Implementierung gewählt werden. + +## Die primitive Grenze finden {#find-the-primitive-boundary} + +Frage dich: + +* Welche neue Beobachtung oder Transformation ist erforderlich? +* Ist sie an dieser Grenze primitiv oder aus der bestehenden Bedeutung ableitbar? +* Wird ein neuer assoziierter Träger benötigt? +* Ist die vermeintliche Abhängigkeit lediglich ein Speicherort? +* Welche Unterschiede sollten unsichtbar bleiben? + +Füge nur für tatsächlich neue primitive Bedeutungen eine Capability hinzu. + +## Komposition zutreffend wählen {#choose-composition-truthfully} + +Verwende diese Entscheidungstabelle: + +| Frage | Auswahl | +| --- | --- | +| Interpretiert ein einzelner Empfänger alle benötigten Bedeutungen? | Direkte Bounds | +| Wird das Verhalten unabhängig ausgewählt? | Expliziter Richtlinienwert | +| Lassen sich Richtlinien unabhängig zusammensetzen? | Produkt | +| Enthält eine Umgebung einen weiteren Interpreter? | Projektion | +| Muss ein Wrapper den inneren Interpreter ersetzen können? | Delegation | + +Führe nicht standardmäßig ein großes Kontext-Trait ein. + +## Jeweils eine Bedeutung refaktorieren {#refactor-one-meaning-at-a-time} + +Wenn vorhandener Code repräsentationsorientiert ist: + +1. Eine semantische Beobachtung bestimmen. +2. Eine kleine Capability definieren. +3. Eine Ableitung in eine Erweiterung verschieben. +4. Die vorhandene Struktur als Interpreter beibehalten. +5. Einen Test in der Form eines Gesetzes hinzufügen. + +```admonish warning title="DD bedeutet nicht maximale Abstraktion" +Schreibe nicht ein ganzes Teilsystem in spekulative Abstraktionen um. DD bedeutet nicht maximale Abstraktion. +``` + +## Von der Bedeutung zu den Mechanismen reviewen {#review-from-meaning-to-machinery} + +Lies den Code in dieser Reihenfolge: + +1. Capability-Traits +2. semantische Werttypen +3. abgeleitete Erweiterungen +4. Syntax des Programms erster Ordnung, sofern vorhanden +5. gemeinsam genutzte Gesetze und Szenarien +6. konkrete Interpreter +7. Orchestrierung der Laufzeit + +Wer beim größten Zustandsobjekt beginnt, richtet die Prüfung auf dessen Repräsentation aus. + +## Häufige Fehlerquellen {#common-failure-modes} + +````admonish warning title="Ein Trait mit konkretem Zustand ist kein Denotational Design" +```rust,noplayground +trait ContextAlg { + fn state(&self) -> &ConcreteState; +} +``` + +Das Trait ändert die Syntax, nicht aber die Zuständigkeit für die Bedeutung. Der semantische Kern hängt weiterhin von der konkreten Repräsentation ab. +```` + +### Abgeleitete Logik in jedem Interpreter {#derived-logic-in-every-interpreter} + +Definiert jede Implementierung unabhängig denselben Fachalgorithmus, ist die Spezifikation dupliziert. + +### Alleskönner-Capability {#god-capability} + +Ein Supertrait mit unzusammenhängenden Operationen verbirgt die Abhängigkeiten und verhindert unabhängige Interpretationen. + +### Vom Framework besessene Spezifikation {#framework-owned-specification} + +Sind Routenannotationen oder RPC-Registrierung die einzige Schnittstellendefinition, können Dokumentation und Ausführung voneinander abweichen. + +### Vom Makro besessene Bedeutung {#macro-owned-meaning} + +Hat generierter Code kein öffentliches Ziel erster Ordnung, wird die Makroexpansion versehentlich zur Spezifikation. + +### Richtlinie in Standardwerten versteckt {#policy-hidden-in-defaults} + +Wählt `Default` unbemerkt Quorum-, Wiederholungs-, Sortierungs- oder Kompilierungsrichtlinien aus, ist die Komposition nicht mehr explizit. + +### Tests interner Schritte {#tests-of-private-steps} + +Tests, die an Feldlayout oder Durchlaufreihenfolge gekoppelt sind, erschweren gültige alternative Interpreter. + +## Checkliste für Pull Requests {#pull-request-checklist} + +### Bedeutung {#meaning} + +* Ist die semantische Änderung formuliert? +* Sind Träger und Gleichheit klar? +* Sind bewusste Auslassungen benannt? + +### Capabilities {#capabilities} + +* Legt jedes Trait eine zusammenhängende primitive Bedeutung offen? +* Sind Bounds dort platziert, wo sie von Operationen verwendet werden? +* Vermeidet abgeleiteter Code konkrete Felder? + +### Komposition {#composition} + +* Werden direkte Bounds, Richtlinien, Produkte, Projektionen und Delegation zutreffend eingesetzt? +* Sind semantische Standardwerte explizit? + +### Programme und Interpreter {#programs-and-interpreters} + +* Wird eine Struktur erster Ordnung nur dann eingeführt, wenn eine weitere Interpretation sie benötigt? +* Können Komfortmakros auf öffentliche Programmwerte abbilden? +* Sind konkrete Interpreter schlank und auf ihre Grenzen zugeschnitten? + +### Nachweise {#evidence} + +* Gibt es ein Gesetz oder eine gezielte semantische Assertion? +* Kann dasselbe Szenario auch mit einem anderen Interpreter ausgeführt werden? +* Werden endliche Tests als Nachweise statt als Beweise beschrieben? + +## Code im ALUX-Stil lesen {#reading-alux-style-code} + +Folgende Grundstruktur ist erkennbar: + +1. winzige primitive Capability-Traits +2. abgeleitete Erweiterungen mit expliziten Bounds +3. Programme erster Ordnung, wenn Inspektion oder Komposition sie erfordert +4. gemeinsam genutzte Gesetze und Szenarien +5. konkrete Interpreter für Laufzeit, Compiler, HTTP, RPC oder Speicher + +Auch große nebenläufige Systeme enthalten Bereiche mit hohem Orchestrierungsaufwand. Gehe nicht davon aus, dass jede bestehende Schnittstelle bereits eine ideale denotationelle Spezifikation ist. Suche nach semantischen Nahtstellen und lies von dort aus nach außen. + +Tolang nutzt dieselbe Perspektive auf Sprachebene: Syntax wird in bedeutungstragende Formen normalisiert, die Kompilierung bewahrt diese Bedeutung, und eine nebenläufige Laufzeit interpretiert die ausführbare Repräsentation. Der operationale Ablauf bleibt wichtig, folgt aber erst auf den semantischen Vertrag. + +## Abschließendes Prinzip {#final-principle} + +Wenn du unsicher bist, kehre zu einer Frage zurück: + +```admonish quote title="Die Frage, zu der du zurückkehren solltest" +Welche Bedeutung sollen diese Mechanismen bewahren? +``` + +Diese Frage löst nicht jedes technische Problem. Sie macht es auf der richtigen Ebene sichtbar. diff --git a/src/rust-dd/workflow.es.md b/src/rust-dd/workflow.es.md new file mode 100644 index 0000000..803dbd6 --- /dev/null +++ b/src/rust-dd/workflow.es.md @@ -0,0 +1,186 @@ + + +# Un flujo de trabajo guiado por el significado {#a-meaning-first-workflow} + +```admonish tip title="Relacionado" +La perspectiva semántica: [Por qué el significado va primero](../denotational-design/semantic-view.md) +Diseño basado en el significado en Rust: [Álgebras de capacidades](capability-algebras.md), [Significado derivado y composición](derived-meaning.md), [Leyes, escenarios y pruebas](laws.md) +``` + +```admonish note title="Una disciplina repetible" +El diseño denotacional es un flujo de trabajo, no solo una explicación del código terminado: formula el cambio semántico, identifica las capacidades primitivas mínimas, compónlas con fidelidad, implementa intérpretes delgados y comprueba las leyes. +``` + +El diseño denotacional resulta más útil como disciplina de desarrollo repetible que como simple explicación del código terminado. + +## El flujo de trabajo central {#the-core-workflow} + +Para una nueva funcionalidad o refactorización: + +1. Formula el cambio semántico en una frase. +2. Identifica el portador y la igualdad observable. +3. Encuentra las capacidades primitivas mínimas necesarias. +4. Define el comportamiento derivado a partir de capacidades explícitas. +5. Elige una forma de composición fiel al significado. +6. Reifica un programa de primer orden solo si su estructura necesita varias interpretaciones. +7. Implementa intérpretes concretos y delgados. +8. Añade leyes o escenarios compartidos. +9. Valida las interpretaciones alternativas. +10. Documenta el significado antes que la maquinaria. + +## Formula el cambio semántico {#state-the-semantic-change} + +Formulación débil: + +> Añadir una caché y un método al gestor. + +Formulación orientada al significado: + +> Resolver el mismo nombre de origen inmutable denota el mismo valor de origen durante una compilación. + +La segunda formulación plantea una posible ley. Más adelante, se puede elegir el almacenamiento en caché como una implementación. + +## Encuentra el límite primitivo {#find-the-primitive-boundary} + +Pregunta: + +* ¿Qué nueva observación o transformación hace falta? +* ¿Es primitiva en este límite o puede derivarse del significado existente? +* ¿Hace falta un nuevo portador asociado? +* ¿La supuesta dependencia es solo una ubicación de almacenamiento? +* ¿Qué distinciones deberían permanecer invisibles? + +Añade una capacidad solo cuando haya un significado primitivo realmente nuevo. + +## Elige la composición con fidelidad {#choose-composition-truthfully} + +Usa esta tabla de decisión: + +| Pregunta | Opción | +| --- | --- | +| ¿Un mismo receptor interpreta todos los significados requeridos? | Restricciones directas | +| ¿El comportamiento se elige de manera independiente? | Valor de política explícito | +| ¿Se pueden componer las políticas de forma independiente? | Producto | +| ¿Un entorno contiene otro intérprete? | Proyección | +| ¿Un envoltorio debe sustituir al intérprete interno? | Delegación | + +No introduzcas un rasgo de contexto grande como respuesta predeterminada. + +## Refactoriza un significado cada vez {#refactor-one-meaning-at-a-time} + +Cuando el código existente priorice la representación: + +1. Identifica una observación semántica. +2. Define una capacidad pequeña. +3. Traslada una derivación a una extensión. +4. Mantén la estructura actual como su intérprete. +5. Añade una prueba basada en una ley. + +```admonish warning title="El diseño denotacional no busca maximizar las abstracciones" +Evita reescribir todo un subsistema con abstracciones especulativas. El diseño denotacional no busca maximizar las abstracciones. +``` + +## Revisa desde el significado hasta la maquinaria {#review-from-meaning-to-machinery} + +Lee el código en este orden: + +1. rasgos de capacidades +2. tipos de valores semánticos +3. extensiones derivadas +4. sintaxis de programas de primer orden, si existe +5. leyes y escenarios compartidos +6. intérpretes concretos +7. orquestación del entorno de ejecución + +Empezar por la estructura más grande que contiene el estado inclina la revisión hacia su representación. + +## Modos de fallo habituales {#common-failure-modes} + +````admonish warning title="Un estado concreto con forma de rasgo no es diseño denotacional" +```rust,noplayground +trait ContextAlg { + fn state(&self) -> &ConcreteState; +} +``` + +El rasgo cambia la sintaxis, pero no quién es dueño del significado. El núcleo semántico sigue dependiendo de la representación concreta. +```` + +### Lógica derivada en cada intérprete {#derived-logic-in-every-interpreter} + +Si cada implementación define por separado el mismo algoritmo de dominio, la especificación está duplicada. + +### Capacidad omnipotente {#god-capability} + +Un superrasgo que reúne operaciones sin relación oculta las dependencias e impide la interpretación independiente. + +### Especificación propiedad del framework {#framework-owned-specification} + +Si las anotaciones de rutas o el registro de RPC son la única definición de interfaz, la documentación y la ejecución pueden divergir. + +### Significado propiedad de la macro {#macro-owned-meaning} + +Si el código generado carece de un destino público de primer orden, la expansión de la macro se convierte accidentalmente en la especificación. + +### Política oculta en valores predeterminados {#policy-hidden-in-defaults} + +Si `Default` elige silenciosamente una política de quórum, reintentos, ordenación o compilación, la composición deja de ser explícita. + +### Pruebas de pasos privados {#tests-of-private-steps} + +Las pruebas acopladas a la disposición de campos o al orden de recorrido desincentivan intérpretes alternativos válidos. + +## Lista de comprobación para la solicitud de integración {#pull-request-checklist} + +### Significado {#meaning} + +* ¿Se ha formulado el cambio semántico? +* ¿Están claros el portador y la igualdad? +* ¿Se han nombrado las omisiones intencionales? + +### Capacidades {#capabilities} + +* ¿Cada rasgo expone un significado primitivo coherente? +* ¿Las restricciones están donde se usan las operaciones? +* ¿El código derivado evita los campos concretos? + +### Composición {#composition} + +* ¿Se usan con fidelidad las restricciones directas, las políticas, los productos, las proyecciones y la delegación? +* ¿Los valores semánticos predeterminados son explícitos? + +### Programas e intérpretes {#programs-and-interpreters} + +* ¿Se introduce una estructura de primer orden solo cuando otra interpretación la necesita? +* ¿Pueden las macros de conveniencia traducirse a valores de programa públicos? +* ¿Los intérpretes concretos son delgados y específicos de cada límite? + +### Pruebas {#evidence} + +* ¿Se incluye una ley o una afirmación semántica específica? +* ¿Se puede ejecutar el mismo escenario con otro intérprete? +* ¿Se presentan las pruebas finitas como indicios y no como demostración? + +## Leer código al estilo de ALUX {#reading-alux-style-code} + +La forma general que conviene reconocer es: + +1. rasgos de capacidades primitivas pequeñas +2. extensiones derivadas sobre restricciones explícitas +3. programas de primer orden cuando se requiere inspección o composición +4. leyes y escenarios compartidos +5. intérpretes concretos para entornos de ejecución, compiladores, HTTP, RPC o almacenamiento + +Los grandes sistemas concurrentes aún contienen zonas dominadas por la orquestación. No des por sentado que todas las interfaces existentes ya son especificaciones denotacionales ideales. Busca los límites semánticos y lee desde ellos hacia afuera. + +Tolang aplica la misma perspectiva a escala de lenguaje: la sintaxis se normaliza en formas portadoras de significado, la compilación preserva ese significado y un entorno de ejecución concurrente interpreta la representación ejecutable. La explicación operativa sigue siendo esencial, pero viene después del contrato semántico. + +## Principio final {#final-principle} + +En caso de duda, vuelve a una sola pregunta: + +```admonish quote title="La pregunta a la que debes volver" +¿Qué significado debe preservar esta maquinaria? +``` + +Esa pregunta no resuelve todos los problemas de ingeniería. Hace visible el problema en el nivel correcto. diff --git a/src/rust-dd/workflow.ja.md b/src/rust-dd/workflow.ja.md new file mode 100644 index 0000000..9cd9b89 --- /dev/null +++ b/src/rust-dd/workflow.ja.md @@ -0,0 +1,186 @@ + + +# 意味から始めるワークフロー {#a-meaning-first-workflow} + +```admonish tip title="関連項目" +意味論的な見方:[なぜ意味を先に考えるのか](../denotational-design/semantic-view.md) +Rustで意味から設計する:[ケイパビリティ代数](capability-algebras.md)、[導出される意味と合成](derived-meaning.md)、[法則、シナリオ、証拠](laws.md) +``` + +```admonish note title="反復可能な規律" +Denotational Designは、完成したコードを説明するだけのものではなく、繰り返し実践できるワークフローです。意味論上の変更を述べ、最小限の基本ケイパビリティを見つけ、正確に合成し、薄いインタープリターを実装して法則を検査します。 +``` + +Denotational Designは、完成したコードを説明するだけでなく、繰り返し実践できる開発規律として最も有用です。 + +## 中核となるワークフロー {#the-core-workflow} + +新機能やリファクタリングでは、次のように進めます。 + +1. 意味論上の変更を一文で述べる。 +2. 担体と観測的等値性を特定する。 +3. 必要最小限の基本ケイパビリティを見つける。 +4. 明示したケイパビリティに基づいて導出された振る舞いを定義する。 +5. 実態に合った合成形式を選ぶ。 +6. 複数の解釈が必要な場合に限り、一階プログラムとして再構化する。 +7. 薄い具体インタープリターを実装する。 +8. 法則または共有シナリオを追加する。 +9. 代替解釈を検証する。 +10. 仕組みより先に意味を文書化する。 + +## 意味論上の変更を述べる {#state-the-semantic-change} + +弱い説明: + +> キャッシュとマネージャーメソッドを追加する。 + +意味を中心にした説明: + +> 一度のコンパイル中に同じ不変ソース名を解決すると、同じソース値が得られる。 + +二つ目の説明から、法則の候補が明らかになります。後でキャッシュを一つの実装として選ぶこともできます。 + +## 基本となる境界を見つける {#find-the-primitive-boundary} + +次を問います。 + +* どの新しい観測または変換が必要か。 +* この境界では基本操作なのか、既存の意味から導出できるのか。 +* 新しい関連担体が必要か。 +* 想定した依存関係は、単なる格納場所ではないか。 +* どの区別を見えないままにするか。 + +本当に新しい基本的な意味がある場合だけ、ケイパビリティを追加します。 + +## 実態に合わせて合成する {#choose-composition-truthfully} + +次の判断表を使います。 + +| 問い | 選択 | +| --- | --- | +| 一つのレシーバーが必要な意味をすべて解釈するか。 | 直接境界 | +| 振る舞いを個別に選ぶか。 | 明示的なポリシー値 | +| ポリシー同士は独立に合成できるか。 | 積 | +| 環境が別のインタープリターを含むか。 | 射影 | +| ラッパーは内部のインタープリターを代用しなければならないか。 | 委譲 | + +大きなコンテキストトレイトを既定の解決策として導入しないでください。 + +## 一度に一つの意味をリファクタリングする {#refactor-one-meaning-at-a-time} + +既存コードが表現先行の場合: + +1. 意味論上の観測を一つ特定する。 +2. 小さなケイパビリティを一つ定義する。 +3. 導出を一つ拡張に移す。 +4. 現在の構造体はインタープリターとして維持する。 +5. 法則形式のテストを一つ追加する。 + +```admonish warning title="DDは抽象化至上主義ではない" +推測上の抽象化を使ってサブシステム全体を書き直すことは避けます。DDは抽象化至上主義ではありません。 +``` + +## 意味から仕組みへ順にレビューする {#review-from-meaning-to-machinery} + +次の順にコードを読みます。 + +1. ケイパビリティトレイト +2. 意味論的な値の型 +3. 導出された拡張 +4. 存在する場合は一階プログラム構文 +5. 共有する法則とシナリオ +6. 具体的なインタープリター +7. ランタイムのオーケストレーション + +最大の状態構造体から読み始めると、表現に引きずられたレビューになります。 + +## よくある失敗 {#common-failure-modes} + +````admonish warning title="トレイトの形をした具体状態はDenotational Designではない" +```rust,noplayground +trait ContextAlg { + fn state(&self) -> &ConcreteState; +} +``` + +トレイトが構文を変えても、意味の所有関係は変わりません。意味論上の中核が、依然として具体的な表現に依存しています。 +```` + +### 各インタープリターに導出ロジックがある {#derived-logic-in-every-interpreter} + +すべての実装が同じ領域アルゴリズムを個別に定義するなら、仕様を重複させています。 + +### 万能ケイパビリティ {#god-capability} + +無関係な操作を含むスーパー トレイトは依存関係を隠し、独立した解釈を妨げます。 + +### フレームワークが所有する仕様 {#framework-owned-specification} + +ルートの注釈やRPC登録だけがインターフェース定義だと、ドキュメントと実行がずれることがあります。 + +### マクロが所有する意味 {#macro-owned-meaning} + +生成コードに公開された一階の受け皿がないなら、マクロの展開結果が意図せず仕様になってしまいます。 + +### デフォルトに隠れたポリシー {#policy-hidden-in-defaults} + +`Default`がクォーラム、再試行、順序、コンパイルのポリシーを暗黙に選ぶなら、合成が明示的ではなくなります。 + +### 非公開手順のテスト {#tests-of-private-steps} + +フィールド配置や走査順に結び付いたテストは、妥当な代替インタープリターを妨げます。 + +## Pull Requestの確認項目 {#pull-request-checklist} + +### 意味 {#meaning} + +* 意味論上の変更を述べているか。 +* 担体と等値性が明確か。 +* 意図的に省いた内容に名前を付けているか。 + +### ケイパビリティ {#capabilities} + +* 各トレイトが一貫した基本的な意味を公開しているか。 +* 操作が使う場所に境界を置いているか。 +* 導出コードが具体フィールドを避けているか。 + +### 合成 {#composition} + +* 直接境界、ポリシー、積、射影、委譲を実態に合わせて使っているか。 +* 領域のデフォルトを明示しているか。 + +### プログラムとインタープリター {#programs-and-interpreters} + +* 別の解釈が必要な場合に限って、一階構造を導入しているか。 +* 便利なマクロを公開されたプログラム値に展開できるか。 +* 具体的なインタープリターを薄くし、境界に限定しているか。 + +### 証拠 {#evidence} + +* 法則または焦点を絞った意味論的アサーションがあるか。 +* 同じシナリオを別のインタープリターで実行できるか。 +* 有限のテストを証明ではなく証拠として説明しているか。 + +## ALUX式コードを読む {#reading-alux-style-code} + +認識すべき全体像は次のとおりです。 + +1. 小さな基本ケイパビリティトレイト +2. 明示的な境界を使う導出拡張 +3. 検査や合成が必要な場合の一階プログラム +4. 共有する法則とシナリオ +5. 具体的なランタイム、コンパイラー、HTTP、RPC、格納用インタープリター + +大規模な並行システムにも、オーケストレーションが中心となる領域はあります。既存の各インターフェースがすでに理想的な表示仕様だと決め付けないでください。意味論上の継ぎ目を探し、そこから外側へ読み進めます。 + +Tolangは、言語規模で同じ視点を用います。構文を意味を担う形式に正規化し、コンパイルでその意味を保ち、並行ランタイムで実行可能な表現を解釈します。操作上の説明も不可欠ですが、意味論上の契約を定めた後に続きます。 + +## 最後の原則 {#final-principle} + +迷ったら、次の問いに立ち返ります。 + +```admonish quote title="立ち返る問い" +この仕組みは、どのような意味を保持するためのものか。 +``` + +この問いだけですべてのエンジニアリング上の問題を解決できるわけではありません。問題が適切な水準で見えるようになります。 diff --git a/src/rust-dd/workflow.ko.md b/src/rust-dd/workflow.ko.md new file mode 100644 index 0000000..48a96e5 --- /dev/null +++ b/src/rust-dd/workflow.ko.md @@ -0,0 +1,186 @@ + + +# 의미 우선 작업 흐름 {#a-meaning-first-workflow} + +```admonish tip title="관련 항목" +의미론적 관점: [왜 의미가 먼저인가](../denotational-design/semantic-view.md) +Rust에서 의미로 설계하기: [케이퍼빌리티 대수](capability-algebras.md), [파생 의미와 합성](derived-meaning.md), [법칙, 시나리오, 증거](laws.md) +``` + +```admonish note title="반복 가능한 규율" +표시적 설계는 완성된 코드를 설명하는 데 그치지 않고 작업 흐름으로 활용합니다. 의미론적 변화를 명시하고, 가장 작은 기본 케이퍼빌리티를 찾고, 이를 정확히 합성한 다음 얇은 인터프리터를 구현하고 법칙을 점검합니다. +``` + +표시적 설계는 완성된 코드를 설명하는 데만 쓰기보다 반복 가능한 개발 규율로 사용할 때 가장 유용합니다. + +## 핵심 작업 흐름 {#the-core-workflow} + +새 기능이나 리팩터링을 할 때: + +1. 의미론적 변화를 한 문장으로 명시합니다. +2. 기반 집합과 관찰 가능한 동등성을 파악합니다. +3. 필요한 기본 케이퍼빌리티를 최소한으로 찾습니다. +4. 명시적인 케이퍼빌리티를 바탕으로 파생 동작을 정의합니다. +5. 관계를 정확히 나타내는 합성 형태를 선택합니다. +6. 여러 해석이 구조를 필요로 하는 경우에만 일차 프로그램으로 재구화합니다. +7. 얇은 구체 인터프리터를 구현합니다. +8. 법칙이나 공유 시나리오를 추가합니다. +9. 대안적 해석을 검증합니다. +10. 구현 장치보다 의미를 먼저 문서화합니다. + +## 의미론적 변화를 명시하기 {#state-the-semantic-change} + +부정확한 설명: + +> 캐시와 매니저 메서드를 추가합니다. + +의미 중심 설명: + +> 한 번의 컴파일 동안 변경 불가능한 같은 소스 이름을 확인하면 항상 같은 소스 값이 나옵니다. + +두 번째 문장은 후보 법칙을 드러냅니다. 캐싱은 나중에 선택할 수 있는 구현 방법일 뿐입니다. + +## 기본 경계 찾기 {#find-the-primitive-boundary} + +다음 질문을 하세요: + +* 새로 필요한 관찰이나 변환은 무엇인가요? +* 이 경계에서 기본 연산인가요, 기존 의미에서 도출할 수 있나요? +* 새로운 연관 기반 집합이 필요한가요? +* 의존성이라고 여긴 것이 실제로는 저장 위치일 뿐인가요? +* 어떤 구분을 보이지 않게 해야 하나요? + +정말 새로운 기본 의미일 때만 케이퍼빌리티를 추가하세요. + +## 합성을 정확히 선택하기 {#choose-composition-truthfully} + +이 의사결정 표를 사용하세요: + +| 질문 | 선택 | +| --- | --- | +| 수신자 하나가 필요한 모든 의미를 해석하나요? | 직접 바운드 | +| 동작을 독립적으로 선택하나요? | 명시적 정책 값 | +| 정책들을 독립적으로 합성하나요? | 곱 | +| 환경이 다른 인터프리터를 포함하나요? | 투영 | +| 래퍼가 내부 인터프리터를 대체해야 하나요? | 위임 | + +큰 컨텍스트 트레이트를 기본 해법으로 도입하지 마세요. + +## 한 번에 의미 하나씩 리팩터링하기 {#refactor-one-meaning-at-a-time} + +기존 코드가 표현 우선 방식이라면: + +1. 의미론적 관찰 하나를 파악합니다. +2. 작은 케이퍼빌리티 하나를 정의합니다. +3. 도출 하나를 확장으로 옮깁니다. +4. 현재 구조체는 인터프리터로 유지합니다. +5. 법칙을 확인하는 테스트 하나를 추가합니다. + +```admonish warning title="표시적 설계는 추상화를 최대화하는 방법이 아닙니다" +추측에 기반한 추상화로 하위 시스템 전체를 다시 작성하지 마세요. 표시적 설계는 추상화를 최대화하는 방법이 아닙니다. +``` + +## 의미에서 구현 장치 방향으로 검토하기 {#review-from-meaning-to-machinery} + +다음 순서로 코드를 읽으세요: + +1. 케이퍼빌리티 트레이트 +2. 의미 타입 +3. 파생 확장 +4. 존재한다면 일차 프로그램 구문 +5. 공유 법칙과 시나리오 +6. 구체 인터프리터 +7. 런타임 오케스트레이션 + +가장 큰 상태 구조체부터 살펴보면 표현 방식에 치우쳐 검토하게 됩니다. + +## 흔한 실패 유형 {#common-failure-modes} + +````admonish warning title="트레이트 형태를 띤 구체 상태는 표시적 설계가 아닙니다" +```rust,noplayground +trait ContextAlg { + fn state(&self) -> &ConcreteState; +} +``` + +트레이트를 도입해 구문만 바꾸고 의미의 소유권은 바꾸지 않은 경우입니다. 의미론적 핵심은 여전히 구체 표현에 의존합니다. +```` + +### 인터프리터마다 파생 로직 구현 {#derived-logic-in-every-interpreter} + +모든 구현이 같은 도메인 알고리즘을 각자 정의한다면 명세가 중복된 것입니다. + +### 만능 케이퍼빌리티 {#god-capability} + +무관한 연산을 담은 상위 트레이트는 의존 관계를 감추고 독립적인 해석을 막습니다. + +### 프레임워크가 소유한 명세 {#framework-owned-specification} + +경로 어노테이션이나 RPC 등록이 유일한 인터페이스 정의라면 문서와 실행이 서로 달라질 수 있습니다. + +### 매크로가 소유한 의미 {#macro-owned-meaning} + +생성 코드에 공개된 일차 대상이 없으면 매크로 확장이 의도치 않게 명세가 됩니다. + +### 기본값에 숨긴 정책 {#policy-hidden-in-defaults} + +`Default`가 정족수, 재시도, 순서, 컴파일 정책을 소리 없이 선택한다면 합성이 더 이상 명시적이지 않습니다. + +### 비공개 단계 테스트 {#tests-of-private-steps} + +필드 배치나 순회 순서에 결합된 테스트는 유효한 대안 인터프리터를 막습니다. + +## Pull Request 점검표 {#pull-request-checklist} + +### 의미 {#meaning} + +* 의미론적 변화를 명시했나요? +* 기반 집합과 동등성이 명확한가요? +* 의도적인 생략을 밝혔나요? + +### 케이퍼빌리티 {#capabilities} + +* 각 트레이트가 일관된 기본 의미를 드러내나요? +* 연산이 사용하는 곳에 바운드를 두었나요? +* 파생 코드가 구체 필드를 피하나요? + +### 합성 {#composition} + +* 직접 바운드, 정책, 곱, 투영, 위임을 정확히 사용했나요? +* 의미론적 기본값을 명시했나요? + +### 프로그램과 인터프리터 {#programs-and-interpreters} + +* 다른 해석이 필요할 때만 일차 구조를 도입했나요? +* 편의 매크로가 공개 프로그램 값으로 낮춰지나요? +* 구체 인터프리터가 얇고 경계에 맞게 구성되었나요? + +### 증거 {#evidence} + +* 법칙이나 집중된 의미 단언이 있나요? +* 다른 인터프리터에서 같은 시나리오를 실행할 수 있나요? +* 유한 테스트를 증명이 아니라 증거로 기술했나요? + +## ALUX식 코드를 읽을 때 {#reading-alux-style-code} + +다음과 같은 큰 구조를 알아보세요: + +1. 작은 기본 케이퍼빌리티 트레이트 +2. 명시된 바운드를 사용하는 파생 확장 +3. 검사나 합성에 필요할 때 구성하는 일차 프로그램 +4. 공유 법칙과 시나리오 +5. 구체적인 런타임, 컴파일러, HTTP, RPC, 저장소 인터프리터 + +큰 동시성 시스템에는 오케스트레이션이 많은 영역도 있습니다. 기존 인터페이스가 모두 이상적인 표시적 명세라고 단정하지 마세요. 의미론적 접점을 찾고 거기서 바깥쪽으로 읽으세요. + +Tolang은 언어 규모에서 같은 관점을 사용합니다. 구문은 의미를 담는 형식으로 정규화되고, 컴파일은 그 의미를 보존하며, 동시성 런타임은 실행 가능한 표현을 해석합니다. 작동 방식도 여전히 중요하지만 의미론적 계약 다음에 옵니다. + +## 마지막 원칙 {#final-principle} + +확신이 서지 않을 때는 한 가지 질문으로 돌아가세요: + +```admonish quote title="돌아가서 물을 질문" +이 구현 장치는 어떤 의미를 보존해야 하나요? +``` + +이 질문이 모든 엔지니어링 문제를 해결하지는 않습니다. 다만 문제를 올바른 수준에서 드러냅니다. diff --git a/src/rust-dd/workflow.ru.md b/src/rust-dd/workflow.ru.md new file mode 100644 index 0000000..59d958a --- /dev/null +++ b/src/rust-dd/workflow.ru.md @@ -0,0 +1,186 @@ + + +# Рабочий процесс с приоритетом смысла {#a-meaning-first-workflow} + +```admonish tip title="Связанные материалы" +«Семантический взгляд»: [Почему начинать нужно со смысла](../denotational-design/semantic-view.md) +«Проектирование на основе смысла в Rust»: [Алгебры возможностей](capability-algebras.md), [Производный смысл и композиция](derived-meaning.md), [Законы, сценарии и свидетельства](laws.md) +``` + +```admonish note title="Повторяемая дисциплина" +Денотационное проектирование — это рабочий процесс, а не только объяснение уже готового кода: сформулируйте семантическое изменение, найдите минимальные примитивные возможности, объедините их честным образом, затем реализуйте тонкие интерпретаторы и проверьте законы. +``` + +Денотационное проектирование полезно прежде всего как повторяемая дисциплина разработки, а не только как объяснение готового кода. + +## Основной рабочий процесс {#the-core-workflow} + +Для новой функции или рефакторинга: + +1. Сформулируйте семантическое изменение одним предложением. +2. Определите носитель и наблюдаемое отношение равенства. +3. Найдите минимальные необходимые примитивные возможности. +4. Задайте производное поведение поверх явных возможностей. +5. Выберите форму композиции, точно описывающую отношение. +6. Реифицируйте программу первого порядка, только если структуру нужно интерпретировать несколькими способами. +7. Реализуйте тонкие конкретные интерпретаторы. +8. Добавьте законы или общие сценарии. +9. Проверьте альтернативные интерпретации. +10. Сначала опишите смысл, затем механизмы. + +## Сформулируйте семантическое изменение {#state-the-semantic-change} + +Слабая формулировка: + +> Добавить кэш и метод менеджера. + +Формулировка, ориентированная на смысл: + +> Разрешение одного и того же неизменяемого имени источника в рамках одной компиляции обозначает одно и то же значение источника. + +Во второй формулировке выражен предполагаемый закон. В дальнейшем кэширование можно выбрать как один из способов реализации. + +## Найдите примитивную границу {#find-the-primitive-boundary} + +Спросите себя: + +* Какое новое наблюдение или преобразование требуется? +* Является ли оно примитивом на этой границе или выводится из уже существующего смысла? +* Нужен ли новый ассоциированный носитель? +* Не является ли предполагаемая зависимость всего лишь местом хранения? +* Какие различия должны оставаться незаметными? + +Добавляйте возможность, только если появился действительно новый примитивный смысл. + +## Выберите честный способ композиции {#choose-composition-truthfully} + +Используйте эту таблицу решений: + +| Вопрос | Выбор | +| --- | --- | +| Интерпретирует ли один получатель все необходимые смыслы? | Прямые ограничения | +| Выбирается ли поведение независимо? | Явное значение политики | +| Можно ли независимо компоновать политики? | Произведение | +| Содержит ли среда другой интерпретатор? | Проекция | +| Должна ли обёртка подменять внутренний интерпретатор? | Делегирование | + +Не делайте крупный трейт контекста ответом по умолчанию. + +## Рефакторьте по одному смыслу {#refactor-one-meaning-at-a-time} + +Если существующий код построен от представления: + +1. Выделите одно семантическое наблюдение. +2. Определите небольшую возможность. +3. Перенесите один выводимый шаг в расширение. +4. Оставьте текущую структуру в роли её интерпретатора. +5. Добавьте один тест в форме закона. + +```admonish warning title="Денотационное проектирование — не абстракционизм ради абстракций" +Не переписывайте целую подсистему ради спекулятивных абстракций. Денотационное проектирование не стремится абстрагировать всё. +``` + +## Проверяйте путь от смысла к механизмам {#review-from-meaning-to-machinery} + +Читайте код в таком порядке: + +1. трейты возможностей +2. типы семантических значений +3. производные расширения +4. синтаксис программ первого порядка, если он есть +5. общие законы и сценарии +6. конкретные интерпретаторы +7. координация среды выполнения + +Начало с самой большой структуры состояния смещает обзор в сторону её представления. + +## Распространённые ошибки {#common-failure-modes} + +````admonish warning title="Конкретное состояние в форме трейта — ещё не денотационное проектирование" +```rust,noplayground +trait ContextAlg { + fn state(&self) -> &ConcreteState; +} +``` + +Трейт меняет синтаксис, но не владение смыслом. Семантическое ядро по-прежнему зависит от конкретного представления. +```` + +### Производная логика в каждом интерпретаторе {#derived-logic-in-every-interpreter} + +Если каждая реализация независимо задаёт один и тот же алгоритм предметной области, спецификация дублируется. + +### Всесильная возможность {#god-capability} + +Супертрейт, объединяющий несвязанные операции, скрывает их зависимости и не позволяет интерпретировать их независимо. + +### Спецификацией владеет фреймворк {#framework-owned-specification} + +Если единственным определением интерфейса служат аннотации маршрутов или регистрация RPC, документация и выполнение могут расходиться. + +### Смыслом владеет макрос {#macro-owned-meaning} + +Если у сгенерированного кода нет публичной цели первого порядка, раскрытие макроса случайно становится спецификацией. + +### Политика скрыта в значениях по умолчанию {#policy-hidden-in-defaults} + +Если `Default` незаметно выбирает кворум, повторы, порядок или политику компиляции, композиция перестаёт быть явной. + +### Тестирование скрытых шагов {#tests-of-private-steps} + +Тесты, привязанные к расположению полей или порядку обхода, мешают использовать допустимые альтернативные интерпретаторы. + +## Контрольный список для запроса на слияние {#pull-request-checklist} + +### Смысл {#meaning} + +* Сформулировано ли семантическое изменение? +* Ясны ли носитель и отношение равенства? +* Названы ли детали, намеренно оставленные за рамками? + +### Возможности {#capabilities} + +* Выражает ли каждый трейт связный примитивный смысл? +* Указываются ли ограничения там, где их используют операции? +* Избегает ли производный код конкретных полей? + +### Композиция {#composition} + +* Правдиво ли используются прямые ограничения, политики, произведения, проекции и делегирование? +* Явно ли заданы семантические значения по умолчанию? + +### Программы и интерпретаторы {#programs-and-interpreters} + +* Вводится ли структура первого порядка лишь тогда, когда она нужна другой интерпретации? +* Можно ли свести вспомогательные макросы к публичным значениям программ? +* Тонкие ли конкретные интерпретаторы и ограничены ли они нужной границей? + +### Свидетельства {#evidence} + +* Приведён ли закон или отдельное семантическое утверждение? +* Можно ли запустить тот же сценарий для другого интерпретатора? +* Называются ли конечные тесты свидетельствами, а не доказательствами? + +## Чтение кода в стиле ALUX {#reading-alux-style-code} + +Общая структура, на которую стоит обратить внимание: + +1. небольшие трейты примитивных возможностей +2. производные расширения с явными ограничениями +3. программы первого порядка, если нужны анализ или композиция +4. общие законы и сценарии +5. конкретные интерпретаторы среды выполнения, компилятора, HTTP, RPC или хранилища + +В крупных параллельных системах по-прежнему есть участки с интенсивной координацией. Не считайте каждый существующий интерфейс уже идеальной денотационной спецификацией. Ищите семантические стыки и рассматривайте окружающий код, отталкиваясь от них. + +Tolang использует тот же подход на уровне языка: синтаксис нормализуется в формы, несущие смысл; компиляция сохраняет этот смысл; параллельная среда выполнения интерпретирует исполняемое представление. Операционные детали остаются важными, но идут после семантического контракта. + +## Заключительный принцип {#final-principle} + +Если не уверены, вернитесь к одному вопросу: + +```admonish quote title="Вопрос, к которому нужно вернуться" +Какой смысл должны сохранять эти механизмы? +``` + +Этот вопрос не решит каждую инженерную задачу, но поможет увидеть её на правильном уровне. diff --git a/src/rust-dd/workflow.uk.md b/src/rust-dd/workflow.uk.md new file mode 100644 index 0000000..c840e25 --- /dev/null +++ b/src/rust-dd/workflow.uk.md @@ -0,0 +1,186 @@ + + +# Робочий процес, орієнтований на значення {#a-meaning-first-workflow} + +```admonish tip title="Пов’язані матеріали" +Семантичний погляд: [Чому значення має бути першим](../denotational-design/semantic-view.md) +Проєктування від значення в Rust: [Алгебри можливостей](capability-algebras.md), [Похідне значення та композиція](derived-meaning.md), [Закони, сценарії та свідчення](laws.md) +``` + +```admonish note title="Повторювана дисципліна" +Денотаційне проєктування — це робочий процес, а не лише пояснення готового коду: сформулюйте семантичну зміну, знайдіть найменший набір примітивних можливостей, чесно поєднайте їх, реалізуйте тонкі інтерпретатори й перевірте закони. +``` + +Денотаційне проєктування найкорисніше як повторювана практика розробки, а не лише як пояснення готового коду. + +## Основний робочий процес {#the-core-workflow} + +Для нової функції чи рефакторингу: + +1. Одним реченням сформулюйте семантичну зміну. +2. Визначте носій і спостережувану рівність. +3. Знайдіть найменший набір потрібних примітивних можливостей. +4. Визначте похідну поведінку через явні можливості. +5. Виберіть форму композиції, що правдиво описує зв’язок. +6. Реїфікуйте програму першого порядку лише тоді, коли структурі потрібні кілька інтерпретацій. +7. Реалізуйте тонкі конкретні інтерпретатори. +8. Додайте закони або спільні сценарії. +9. Перевірте альтернативні інтерпретації. +10. Спершу задокументуйте значення, потім механізми. + +## Сформулюйте семантичну зміну {#state-the-semantic-change} + +Нечітке формулювання: + +> Додати кеш і метод менеджера. + +Формулювання, орієнтоване на значення: + +> Під час однієї компіляції пошук одного й того самого незмінного джерела за назвою позначає те саме значення джерела. + +Друге формулювання виявляє можливий закон. Кешування згодом можна вибрати як один зі способів реалізації. + +## Знайдіть межу примітивів {#find-the-primitive-boundary} + +Запитайте себе: + +* Яке нове спостереження чи перетворення потрібне? +* Чи є воно примітивним на цій межі, чи його можна вивести з наявного значення? +* Чи потрібен новий асоційований носій? +* Чи є передбачена залежність лише місцем зберігання? +* Які відмінності мають залишатися невидимими? + +Додавайте можливість лише заради справді нового примітивного значення. + +## Правдиво вибирайте форму композиції {#choose-composition-truthfully} + +Користуйтеся цією таблицею рішень: + +| Запитання | Вибір | +| --- | --- | +| Один приймач інтерпретує всі потрібні значення? | Прямі обмеження | +| Поведінку вибирають окремо? | Явне значення політики | +| Чи можна незалежно композиційно поєднувати політики? | Добуток | +| Середовище містить інший інтерпретатор? | Проєкція | +| Обгортка має замінювати внутрішній інтерпретатор? | Делегування | + +Не використовуйте великий трейт контексту як рішення за замовчуванням. + +## Рефакторте по одному значенню {#refactor-one-meaning-at-a-time} + +Якщо наявний код виходить із представлення: + +1. Визначте одне семантичне спостереження. +2. Задайте одну невелику можливість. +3. Перенесіть одне виведення до розширення. +4. Залиште поточну структуру його інтерпретатором. +5. Додайте один тест закону. + +```admonish warning title="Денотаційне проєктування — не максималізм абстракцій" +Не переписуйте цілу підсистему спекулятивними абстракціями. Денотаційне проєктування — не максималізм абстракцій. +``` + +## Перевіряйте код від значення до механізмів {#review-from-meaning-to-machinery} + +Читайте код у такому порядку: + +1. трейти можливостей +2. типи семантичних значень +3. похідні розширення +4. синтаксис програми першого порядку, якщо є +5. спільні закони й сценарії +6. конкретні інтерпретатори +7. оркестрація середовища виконання + +Якщо почати з найбільшої структури стану, це схилятиме перевірку до її представлення. + +## Типові помилки {#common-failure-modes} + +````admonish warning title="Трейтова форма конкретного стану — це ще не денотаційне проєктування" +```rust,noplayground +trait ContextAlg { + fn state(&self) -> &ConcreteState; +} +``` + +Трейт змінює синтаксис, але не те, хто визначає значення. Семантичне ядро й далі залежить від конкретного представлення. +```` + +### Похідна логіка в кожному інтерпретаторі {#derived-logic-in-every-interpreter} + +Якщо кожна реалізація окремо визначає той самий алгоритм предметної області, специфікацію продубльовано. + +### Універсальна можливість {#god-capability} + +Супертрейт із не пов’язаними між собою операціями приховує таблицю залежностей і заважає незалежній інтерпретації. + +### Специфікація у власності фреймворку {#framework-owned-specification} + +Якщо анотації маршрутів чи реєстрація RPC є єдиним визначенням інтерфейсу, документація й виконання можуть розійтися. + +### Значення у власності макросу {#macro-owned-meaning} + +Якщо згенерований код не має публічного представлення першого порядку, розгортання макросу випадково стає специфікацією. + +### Політика прихована у значеннях за замовчуванням {#policy-hidden-in-defaults} + +Якщо `Default` непомітно вибирає кворум, повторні спроби, порядок чи політику компіляції, композиція вже не є явною. + +### Тести внутрішніх кроків {#tests-of-private-steps} + +Тести, залежні від розташування полів чи порядку обходу, стримують створення коректних альтернативних інтерпретаторів. + +## Контрольний список для запиту на злиття {#pull-request-checklist} + +### Значення {#meaning} + +* Чи сформульовано семантичну зміну? +* Чи визначено носій і рівність? +* Чи названо те, що навмисно опущено? + +### Можливості {#capabilities} + +* Чи виражає кожен трейт цілісне примітивне значення? +* Чи стоять обмеження в тих місцях, де їх використовують операції? +* Чи уникає похідний код конкретних полів? + +### Композиція {#composition} + +* Чи правдиво використовуються прямі обмеження, політики, добутки, проєкції й делегування? +* Чи явні семантичні значення за замовчуванням? + +### Програми й інтерпретатори {#programs-and-interpreters} + +* Чи вводиться структура першого порядку лише тоді, коли потрібна інша інтерпретація? +* Чи зводяться допоміжні макроси до публічних значень програми? +* Чи є конкретні інтерпретатори тонкими й прив’язаними до межі? + +### Свідчення {#evidence} + +* Чи наявний закон або цільове семантичне твердження? +* Чи може той самий сценарій виконатися для іншого інтерпретатора? +* Чи названо скінченні тести свідченнями, а не доведеннями? + +## Читання коду в стилі ALUX {#reading-alux-style-code} + +Загальна структура, на яку слід звернути увагу: + +1. невеликі трейти примітивних можливостей +2. похідні розширення з явними обмеженнями +3. програми першого порядку, коли потрібні огляд чи композиція +4. спільні закони й сценарії +5. конкретні інтерпретатори середовища виконання, компілятора, HTTP, RPC чи сховища + +У великих паралельних системах усе одно є ділянки з інтенсивною оркестрацією. Не припускайте, що кожен наявний інтерфейс уже є ідеальною денотаційною специфікацією. Шукайте семантичні стики й починайте читання з них, рухаючись назовні. + +Tolang застосовує той самий погляд до мови в цілому: синтаксис нормалізується до форм, що містять значення, компіляція зберігає це значення, а паралельне середовище виконання інтерпретує виконуване представлення. Операційний опис не менш важливий, але він іде після семантичного контракту. + +## Головний принцип {#final-principle} + +Якщо є сумніви, поверніться до одного запитання: + +```admonish quote title="Запитання, до якого слід повертатися" +Яке значення мають зберігати ці механізми? +``` + +Це запитання не розв’яже кожну інженерну проблему, але допоможе побачити її на правильному рівні. diff --git a/src/rust-dd/workflow.vi.md b/src/rust-dd/workflow.vi.md new file mode 100644 index 0000000..9cdbf67 --- /dev/null +++ b/src/rust-dd/workflow.vi.md @@ -0,0 +1,186 @@ + + +# Quy trình lấy ý nghĩa làm trọng tâm {#a-meaning-first-workflow} + +```admonish tip title="Liên quan" +Góc nhìn ngữ nghĩa: [Vì sao ý nghĩa được đặt lên trước](../denotational-design/semantic-view.md) +Thiết kế theo ngữ nghĩa trong Rust: [Các đại số năng lực](capability-algebras.md), [Ý nghĩa suy ra và phép hợp thành](derived-meaning.md), [Định luật, tình huống và bằng chứng](laws.md) +``` + +```admonish note title="Một quy trình có thể lặp lại" +Thiết kế theo ngữ nghĩa là quy trình làm việc, không chỉ là lời giải thích cho mã đã hoàn tất: phát biểu thay đổi ngữ nghĩa, tìm các năng lực nguyên thủy nhỏ nhất, hợp thành chúng một cách trung thực, rồi triển khai các bộ diễn giải mỏng và kiểm tra định luật. +``` + +Thiết kế theo ngữ nghĩa hữu ích nhất khi là một quy trình phát triển có thể lặp lại, chứ không chỉ là lời giải thích cho mã đã hoàn tất. + +## Quy trình cốt lõi {#the-core-workflow} + +Với tính năng mới hoặc đợt tái cấu trúc: + +1. Nêu thay đổi ngữ nghĩa trong một câu. +2. Xác định đối tượng mang và đẳng thức có thể quan sát. +3. Tìm các năng lực nguyên thủy nhỏ nhất cần thiết. +4. Định nghĩa hành vi suy ra dựa trên các năng lực tường minh. +5. Chọn hình thức hợp thành trung thực. +6. Chỉ tái hóa chương trình bậc nhất nếu cấu trúc cần nhiều cách diễn giải. +7. Triển khai các bộ diễn giải cụ thể mỏng. +8. Bổ sung định luật hoặc tình huống dùng chung. +9. Thẩm định các cách diễn giải thay thế. +10. Tài liệu hóa ý nghĩa trước cơ chế. + +## Phát biểu thay đổi ngữ nghĩa {#state-the-semantic-change} + +Phát biểu yếu: + +> Thêm bộ nhớ đệm và phương thức trình quản lý. + +Phát biểu định hướng theo ý nghĩa: + +> Việc phân giải cùng một tên nguồn bất biến sẽ biểu thị cùng một giá trị nguồn trong một lần biên dịch. + +Phát biểu thứ hai làm lộ một định luật ứng viên. Sau này có thể chọn lưu đệm như một cách triển khai. + +## Tìm ranh giới nguyên thủy {#find-the-primitive-boundary} + +Hãy hỏi: + +* Cần quan sát hoặc phép biến đổi mới nào? +* Nó là nguyên thủy ở ranh giới này hay có thể suy ra từ ý nghĩa hiện có? +* Có cần đối tượng mang liên kết mới không? +* Phụ thuộc được cho là cần thiết có chỉ là một vị trí lưu trữ không? +* Những khác biệt nào cần tiếp tục vô hình? + +Chỉ thêm năng lực khi có ý nghĩa nguyên thủy mới thực sự. + +## Chọn cách hợp thành trung thực {#choose-composition-truthfully} + +Dùng bảng quyết định này: + +| Câu hỏi | Lựa chọn | +| --- | --- | +| Một bên nhận có diễn giải mọi ý nghĩa cần thiết không? | Ràng buộc trực tiếp | +| Hành vi có được lựa chọn độc lập không? | Giá trị chính sách tường minh | +| Các chính sách có thể hợp thành độc lập không? | Tích | +| Môi trường có chứa bộ diễn giải khác không? | Phép chiếu | +| Lớp bọc có cần thay thế bộ diễn giải bên trong không? | Ủy quyền | + +Đừng mặc định câu trả lời là một đặc trưng ngữ cảnh lớn. + +## Tái cấu trúc từng ý nghĩa một {#refactor-one-meaning-at-a-time} + +Khi mã hiện có ưu tiên biểu diễn: + +1. Xác định một quan sát ngữ nghĩa. +2. Định nghĩa một năng lực nhỏ. +3. Chuyển một phép suy ra vào phần mở rộng. +4. Giữ cấu trúc hiện tại làm bộ diễn giải. +5. Thêm một kiểm thử dạng định luật. + +```admonish warning title="DD không phải chủ nghĩa trừu tượng tối đa" +Tránh viết lại toàn bộ hệ thống con thành các trừu tượng mang tính suy đoán. DD không phải chủ nghĩa trừu tượng tối đa. +``` + +## Duyệt từ ý nghĩa đến cơ chế {#review-from-meaning-to-machinery} + +Đọc mã theo thứ tự này: + +1. đặc trưng năng lực +2. kiểu giá trị ngữ nghĩa +3. các phần mở rộng suy ra +4. cú pháp chương trình bậc nhất nếu có +5. định luật và tình huống dùng chung +6. bộ diễn giải cụ thể +7. điều phối môi trường chạy + +Bắt đầu từ cấu trúc trạng thái lớn nhất khiến việc duyệt thiên về cách biểu diễn của nó. + +## Các kiểu thất bại thường gặp {#common-failure-modes} + +````admonish warning title="Trạng thái cụ thể mang hình dạng đặc trưng không phải Thiết kế theo ngữ nghĩa" +```rust,noplayground +trait ContextAlg { + fn state(&self) -> &ConcreteState; +} +``` + +Đặc trưng chỉ thay đổi cú pháp, không thay đổi quyền sở hữu ý nghĩa. Lõi ngữ nghĩa vẫn phụ thuộc vào cách biểu diễn cụ thể. +```` + +### Logic suy ra nằm trong mọi bộ diễn giải {#derived-logic-in-every-interpreter} + +Nếu từng cách triển khai tự định nghĩa cùng một thuật toán miền, đặc tả đã bị sao chép. + +### Năng lực toàn năng {#god-capability} + +Đặc trưng cha chứa các phép toán không liên quan sẽ che giấu hàng phụ thuộc và ngăn việc diễn giải độc lập. + +### Đặc tả thuộc sở hữu của khung {#framework-owned-specification} + +Nếu chú giải tuyến hoặc đăng ký RPC là định nghĩa giao diện duy nhất, tài liệu và thực thi có thể sai khác. + +### Ý nghĩa thuộc sở hữu của macro {#macro-owned-meaning} + +Nếu mã được tạo không có đích bậc nhất công khai, phần khai triển macro sẽ vô tình trở thành đặc tả. + +### Chính sách bị ẩn trong giá trị mặc định {#policy-hidden-in-defaults} + +Nếu `Default` âm thầm chọn túc số, thử lại, thứ tự hoặc chính sách biên dịch, phép hợp thành không còn tường minh. + +### Kiểm thử các bước riêng tư {#tests-of-private-steps} + +Kiểm thử gắn với bố cục trường hoặc thứ tự duyệt sẽ cản trở các bộ diễn giải thay thế hợp lệ. + +## Danh sách kiểm tra yêu cầu gộp {#pull-request-checklist} + +### Ý nghĩa {#meaning} + +* Thay đổi ngữ nghĩa đã được nêu rõ chưa? +* Đối tượng mang và đẳng thức có rõ ràng không? +* Các nội dung lược bỏ có chủ ý đã được nêu tên chưa? + +### Năng lực {#capabilities} + +* Mỗi đặc trưng có bộc lộ ý nghĩa nguyên thủy nhất quán không? +* Các ràng buộc có được đặt tại nơi phép toán sử dụng chúng không? +* Mã suy ra có tránh các trường cụ thể không? + +### Phép hợp thành {#composition} + +* Ràng buộc trực tiếp, chính sách, tích, phép chiếu và ủy quyền có được dùng trung thực không? +* Các giá trị mặc định ngữ nghĩa có được nêu tường minh không? + +### Chương trình và bộ diễn giải {#programs-and-interpreters} + +* Cấu trúc bậc nhất chỉ được đưa vào khi một cách diễn giải khác cần đến nó chứ? +* Macro tiện ích có thể hạ xuống các giá trị chương trình công khai không? +* Các bộ diễn giải cụ thể có mỏng và riêng cho từng ranh giới không? + +### Bằng chứng {#evidence} + +* Có định luật hoặc khẳng định ngữ nghĩa tập trung không? +* Có thể chạy cùng tình huống với bộ diễn giải khác không? +* Kiểm thử hữu hạn có được mô tả là bằng chứng thay vì chứng minh không? + +## Đọc mã theo phong cách ALUX {#reading-alux-style-code} + +Hình thái tổng quát cần nhận ra là: + +1. đặc trưng năng lực nguyên thủy nhỏ +2. phần mở rộng suy ra trên các ràng buộc tường minh +3. chương trình bậc nhất khi cần kiểm tra hoặc hợp thành +4. định luật và tình huống dùng chung +5. các bộ diễn giải cụ thể cho môi trường chạy, trình biên dịch, HTTP, RPC hoặc lưu trữ + +Các hệ thống đồng thời lớn vẫn có những vùng nặng về điều phối. Đừng cho rằng mọi giao diện hiện có đều đã là đặc tả ngữ nghĩa chỉ định lý tưởng. Hãy tìm các đường nối ngữ nghĩa và đọc từ đó ra ngoài. + +Tolang áp dụng cùng góc nhìn ở quy mô ngôn ngữ: cú pháp được chuẩn hóa thành dạng mang ý nghĩa, biên dịch bảo toàn ý nghĩa đó, còn môi trường chạy đồng thời diễn giải cách biểu diễn thực thi. Câu chuyện vận hành vẫn thiết yếu, nhưng chỉ đến sau hợp đồng ngữ nghĩa. + +## Nguyên lý cuối cùng {#final-principle} + +Khi chưa chắc chắn, hãy quay lại một câu hỏi: + +```admonish quote title="Câu hỏi cần quay lại" +Cơ chế này cần bảo toàn ý nghĩa nào? +``` + +Câu hỏi đó không giải quyết mọi vấn đề kỹ thuật. Nó giúp thấy vấn đề ở đúng cấp độ. diff --git a/src/rust-dd/workflow.zh-hant.md b/src/rust-dd/workflow.zh-hant.md new file mode 100644 index 0000000..5cba1bb --- /dev/null +++ b/src/rust-dd/workflow.zh-hant.md @@ -0,0 +1,186 @@ + + +# 語義優先的工作流程 {#a-meaning-first-workflow} + +```admonish tip title="相關內容" +語義視角:[為何含義優先](../denotational-design/semantic-view.md) +Rust 中的語義驅動設計:[能力代數](capability-algebras.md)、[派生含義與組合](derived-meaning.md)、[定律、場景與證據](laws.md) +``` + +```admonish note title="可重複的方法" +指稱設計是一套工作流程,而不只是對已完成程式碼的解釋:陳述語義變化,找出最小基本能力,如實組合它們,再實作輕量級直譯器並檢查定律。 +``` + +指稱設計作為一種可重複的開發方法最有用,而不只是對已完成程式碼作出解釋。 + +## 核心流程 {#the-core-workflow} + +開發新功能或重構時: + +1. 用一句話說明語義變化。 +2. 確定載體與可觀察等價關係。 +3. 找出所需的最小基本能力。 +4. 基於明確能力定義派生行為。 +5. 選擇能如實表達關係的組合形式。 +6. 只有當結構需要多種解釋時,才將程式具體化為一階資料。 +7. 實作輕量級具體直譯器。 +8. 新增定律或共享場景。 +9. 驗證不同解釋。 +10. 先記錄含義,再介紹機制。 + +## 陳述語義變化 {#state-the-semantic-change} + +較弱的表述: + +> 新增快取和管理器方法。 + +面向含義的表述: + +> 在一次編譯期間,解析同一個不可變源名稱應指稱相同的源值。 + +第二種表述提出了一條候選定律。之後可以選擇快取作為一種實作方式。 + +## 找到基本邊界 {#find-the-primitive-boundary} + +請思考: + +* 需要哪種新的觀察或變換? +* 它在此邊界上是基本操作,還是可以由現有含義派生? +* 是否需要新的關聯載體? +* 所謂依賴是否只是儲存位置? +* 哪些區別應當不可見? + +只有確實出現新的基本含義時,才新增能力。 + +## 如實選擇組合形式 {#choose-composition-truthfully} + +使用以下決策表: + +| 問題 | 選擇 | +| --- | --- | +| 一個接收者是否解釋了所有必需含義? | 直接約束 | +| 行為是否獨立選擇? | 顯式策略值 | +| 策略是否可以獨立組合? | 乘積型別 | +| 環境是否包含另一個直譯器? | 投影 | +| 包裝器是否必須替代內部直譯器? | 委託 | + +不要預設採用大型上下文 trait。 + +## 一次重構一種含義 {#refactor-one-meaning-at-a-time} + +當現有程式碼採用表示優先設計時: + +1. 確定一項語義觀察。 +2. 定義一種小型能力。 +3. 將一個派生操作移入擴充。 +4. 保留當前結構體,將其作為直譯器。 +5. 新增一項定律式測試。 + +```admonish warning title="指稱設計並非抽象至上" +避免將整個子系統重寫為缺乏依據的抽象。指稱設計並非抽象至上。 +``` + +## 從含義到機制進行審查 {#review-from-meaning-to-machinery} + +按以下順序閱讀程式碼: + +1. 能力 trait +2. 語義值型別 +3. 派生擴充 +4. 一階程式語法(如有) +5. 共享定律與場景 +6. 具體直譯器 +7. 執行時編排 + +從最大的狀態結構體開始審查,會使審查偏向其表示。 + +## 常見失敗模式 {#common-failure-modes} + +````admonish warning title="形似 trait 的具體狀態不等於指稱設計" +```rust,noplayground +trait ContextAlg { + fn state(&self) -> &ConcreteState; +} +``` + +trait 改變了語法,卻沒有改變含義的歸屬。語義核心仍然依賴具體表示。 +```` + +### 每個直譯器都重複派生邏輯 {#derived-logic-in-every-interpreter} + +如果每個實作都獨立定義相同的領域演算法,就說明規範被重複了。 + +### 萬能能力 {#god-capability} + +包含無關操作的超 trait 會掩蓋依賴關係,也會阻止獨立解釋。 + +### 規範由框架掌控 {#framework-owned-specification} + +如果路由註解或 RPC 註冊是唯一的介面定義方式,文件與執行就可能出現偏差。 + +### 含義由宏掌控 {#macro-owned-meaning} + +如果生成程式碼沒有公開的一階目標,宏展開就會意外成為規範。 + +### 策略隱藏在預設值中 {#policy-hidden-in-defaults} + +如果`Default`悄然選擇了法定人數、重試、順序或編譯策略,組合就不再是顯式的。 + +### 測試私有步驟 {#tests-of-private-steps} + +與欄位佈局或遍歷順序耦合的測試,會妨礙有效的替代直譯器。 + +## Pull Request 檢查清單 {#pull-request-checklist} + +### 含義 {#meaning} + +* 是否陳述了語義變化? +* 載體與等價關係是否明確? +* 是否指出了有意忽略的內容? + +### 能力 {#capabilities} + +* 每個 trait 是否都表達了連貫的基本含義? +* 約束是否放在操作實際使用它們的位置? +* 派生程式碼是否避免存取具體欄位? + +### 組合 {#composition} + +* 是否如實使用直接約束、策略、乘積型別、投影與委託? +* 語義預設值是否明確? + +### 程式與直譯器 {#programs-and-interpreters} + +* 是否只在另一種解釋確有需要時才引入一階結構? +* 便捷宏能否降解為公開的程式值? +* 具體直譯器是否足夠輕量且限定在特定邊界內? + +### 證據 {#evidence} + +* 是否提供了定律或針對性的語義斷言? +* 同一場景能否在另一個直譯器上執行? +* 是否將有限測試描述為證據,而非證明? + +## 閱讀 ALUX 風格的程式碼 {#reading-alux-style-code} + +需要識別的整體結構是: + +1. 小型基本能力 trait +2. 基於明確約束的派生擴充 +3. 僅在檢查或組合需要時引入一階程式 +4. 共享定律與場景 +5. 具體的執行時、編譯器、HTTP、RPC 或儲存直譯器 + +大型併發系統仍然包含許多需要編排的區域。不要假定所有現有介面都是理想的指稱規範。尋找語義上的銜接點,並從這些位置向外閱讀。 + +Tolang 在語言層面採用相同視角:語法會正規化為承載含義的形式,編譯會保留這些含義,併發執行時則會解釋可執行表示。操作層面的描述仍然至關重要,但它應當位於語義契約之後。 + +## 最終原則 {#final-principle} + +不確定時,回到一個問題: + +```admonish quote title="應當反覆思考的問題" +這些機制本應保留什麼含義? +``` + +這個問題不能解決所有工程難題,但能讓問題在正確的層次上顯現出來。 diff --git a/src/rust-dd/workflow.zh.md b/src/rust-dd/workflow.zh.md new file mode 100644 index 0000000..fea1f93 --- /dev/null +++ b/src/rust-dd/workflow.zh.md @@ -0,0 +1,186 @@ + + +# 语义优先的工作流程 {#a-meaning-first-workflow} + +```admonish tip title="相关内容" +语义视角:[为何含义优先](../denotational-design/semantic-view.md) +Rust 中的语义驱动设计:[能力代数](capability-algebras.md)、[派生含义与组合](derived-meaning.md)、[定律、场景与证据](laws.md) +``` + +```admonish note title="可重复的方法" +指称设计是一套工作流程,而不只是对已完成代码的解释:陈述语义变化,找出最小基本能力,如实组合它们,再实现轻量级解释器并检查定律。 +``` + +指称设计作为一种可重复的开发方法最有用,而不只是对已完成代码作出解释。 + +## 核心流程 {#the-core-workflow} + +开发新功能或重构时: + +1. 用一句话说明语义变化。 +2. 确定载体与可观察等价关系。 +3. 找出所需的最小基本能力。 +4. 基于明确能力定义派生行为。 +5. 选择能如实表达关系的组合形式。 +6. 只有当结构需要多种解释时,才将程序具体化为一阶数据。 +7. 实现轻量级具体解释器。 +8. 添加定律或共享场景。 +9. 验证不同解释。 +10. 先记录含义,再介绍机制。 + +## 陈述语义变化 {#state-the-semantic-change} + +较弱的表述: + +> 添加缓存和管理器方法。 + +面向含义的表述: + +> 在一次编译期间,解析同一个不可变源名称应指称相同的源值。 + +第二种表述提出了一条候选定律。之后可以选择缓存作为一种实现方式。 + +## 找到基本边界 {#find-the-primitive-boundary} + +请思考: + +* 需要哪种新的观察或变换? +* 它在此边界上是基本操作,还是可以由现有含义派生? +* 是否需要新的关联载体? +* 所谓依赖是否只是存储位置? +* 哪些区别应当不可见? + +只有确实出现新的基本含义时,才添加能力。 + +## 如实选择组合形式 {#choose-composition-truthfully} + +使用以下决策表: + +| 问题 | 选择 | +| --- | --- | +| 一个接收者是否解释了所有必需含义? | 直接约束 | +| 行为是否独立选择? | 显式策略值 | +| 策略是否可以独立组合? | 乘积类型 | +| 环境是否包含另一个解释器? | 投影 | +| 包装器是否必须替代内部解释器? | 委托 | + +不要默认采用大型上下文 trait。 + +## 一次重构一种含义 {#refactor-one-meaning-at-a-time} + +当现有代码采用表示优先设计时: + +1. 确定一项语义观察。 +2. 定义一种小型能力。 +3. 将一个派生操作移入扩展。 +4. 保留当前结构体,将其作为解释器。 +5. 添加一项定律式测试。 + +```admonish warning title="指称设计并非抽象至上" +避免将整个子系统重写为缺乏依据的抽象。指称设计并非抽象至上。 +``` + +## 从含义到机制进行审查 {#review-from-meaning-to-machinery} + +按以下顺序阅读代码: + +1. 能力 trait +2. 语义值类型 +3. 派生扩展 +4. 一阶程序语法(如有) +5. 共享定律与场景 +6. 具体解释器 +7. 运行时编排 + +从最大的状态结构体开始审查,会使审查偏向其表示。 + +## 常见失败模式 {#common-failure-modes} + +````admonish warning title="形似 trait 的具体状态不等于指称设计" +```rust,noplayground +trait ContextAlg { + fn state(&self) -> &ConcreteState; +} +``` + +trait 改变了语法,却没有改变含义的归属。语义核心仍然依赖具体表示。 +```` + +### 每个解释器都重复派生逻辑 {#derived-logic-in-every-interpreter} + +如果每个实现都独立定义相同的领域算法,就说明规范被重复了。 + +### 万能能力 {#god-capability} + +包含无关操作的超 trait 会掩盖依赖关系,也会阻止独立解释。 + +### 规范由框架掌控 {#framework-owned-specification} + +如果路由注解或 RPC 注册是唯一的接口定义方式,文档与执行就可能出现偏差。 + +### 含义由宏掌控 {#macro-owned-meaning} + +如果生成代码没有公开的一阶目标,宏展开就会意外成为规范。 + +### 策略隐藏在默认值中 {#policy-hidden-in-defaults} + +如果`Default`悄然选择了法定人数、重试、顺序或编译策略,组合就不再是显式的。 + +### 测试私有步骤 {#tests-of-private-steps} + +与字段布局或遍历顺序耦合的测试,会妨碍有效的替代解释器。 + +## Pull Request 检查清单 {#pull-request-checklist} + +### 含义 {#meaning} + +* 是否陈述了语义变化? +* 载体与等价关系是否明确? +* 是否指出了有意忽略的内容? + +### 能力 {#capabilities} + +* 每个 trait 是否都表达了连贯的基本含义? +* 约束是否放在操作实际使用它们的位置? +* 派生代码是否避免访问具体字段? + +### 组合 {#composition} + +* 是否如实使用直接约束、策略、乘积类型、投影与委托? +* 语义默认值是否明确? + +### 程序与解释器 {#programs-and-interpreters} + +* 是否只在另一种解释确有需要时才引入一阶结构? +* 便捷宏能否展开为公开的程序值? +* 具体解释器是否足够轻量且限定在特定边界内? + +### 证据 {#evidence} + +* 是否提供了定律或针对性的语义断言? +* 同一场景能否在另一个解释器上运行? +* 是否将有限测试描述为证据,而非证明? + +## 阅读 ALUX 风格的代码 {#reading-alux-style-code} + +需要识别的整体结构是: + +1. 小型基本能力 trait +2. 基于明确约束的派生扩展 +3. 仅在检查或组合需要时引入一阶程序 +4. 共享定律与场景 +5. 具体的运行时、编译器、HTTP、RPC 或存储解释器 + +大型并发系统仍然包含许多需要编排的区域。不要假定所有现有接口都是理想的指称规范。寻找语义上的衔接点,并从这些位置向外阅读。 + +Tolang 在语言层面采用相同视角:语法会规范化为承载含义的形式,编译会保留这些含义,并发运行时则会解释可执行表示。操作层面的描述仍然至关重要,但它应当位于语义契约之后。 + +## 最终原则 {#final-principle} + +不确定时,回到一个问题: + +```admonish quote title="应当反复思考的问题" +这些机制本应保留什么含义? +``` + +这个问题不能解决所有工程难题,但能让问题在正确的层次上显现出来。 diff --git a/web/AGENTS.md b/web/AGENTS.md new file mode 100644 index 0000000..87a29bf --- /dev/null +++ b/web/AGENTS.md @@ -0,0 +1,87 @@ +# ALUX Programming:后续内容与界面维护规范 + +本文面向维护此站的 Agent。新增章节、翻译、导航或控件时,应沿用现有结构与视觉层级;不要为单个新元素另建一套排版。工程说明、校对记录及内部检查结果留在工程文档中,不放进读者界面。 + +## 新增内容如何接入 + +1. 原始英文内容以 `src/` 的 Markdown 和唯一的 `src/SUMMARY.md` 为准。译文与英文源相邻,例如 `chapter.zh.md`;缺失译文时回退英文,不维护另一套目录或覆盖英文。新增章节须登记目录,保留原有章节、链接、标题锚点、代码和公式。不要直接编辑生成的 `web/public/content.json`、`web/public/content/` 或 `web/dist/`。 +2. 使用 Markdown 的一个一级标题作为章名,二级标题表示章节内分节,三级标题表示子节。不要为获得某个字号而跳过语义层级,不用加粗段落冒充标题。 +3. `scripts/mdbook-localization.ts` 在 mdBook 正常预处理前选择译文源;`scripts/book.ts` 从各语言的 mdBook JSON 获取结构,从原生 HTML 获取正文。`scripts/reader-presentation.ts` 只做展示适配,不另行编译 Markdown。`src/book.ts` 定义两种界面、搜索和静态路由共用的模型,浏览器按需加载 `content/.json`。界面文案单独放在 `locales/ui/`,组件使用明确的类型化键;不恢复正文词典、HTML token 对齐或 DOM 文本扫描。新增页面必须可在两个世界访问。 +4. 新控件复用现有工具栏、图标与交互方式。新增文案须覆盖当前全部语言;不要把新英文字符串直接留在其他语种界面,也不要只靠 CSS 改变文本含义。 + +## 排版、字号与对齐 + +- 正文基础字号由 `src/reading-preferences.ts` 统一决定:拉丁文和西里尔文 24px,中日韩 22px,阿拉伯文 26px。A−/A+ 必须同时调整正文和目录,两个世界共享设置。不要在单页写死字号覆盖用户偏好。 +- 魔法世界翻页与滚动的文字尺度由 `reader-presentation.css` 统一管理。正文、标题、代码、行内代码、提示框、表格和插图须逐项同号同字体;不得只给 `.folio-content` 添加字号而漏掉 `.continuous-prose`。代码正文约为正文的 82%,最低 16px;代码语言、复制及运行入口最低 16px。代码不得折断原始语法,长行横向滚动。 +- 字标保持两种世界同样的比例:ALUX 为 38px,“编程”及对应语言副标题为 20px,使用同一书名字体与首行对齐,侧栏标志画框为 62px。两者分清主副层级,不把副标题做成难以辨认的小字,也不把两个世界的颜色强行统一。 +- 浏览器标题、应用名称和分享站点名称只保留中英两套品牌名:简体“ALUX 编程”、繁体“ALUX 程式設計”,其余语言用“ALUX Programming”。页面标题统一为本地化页面或章节名称在前,后接一个 ` · ` 与对应品牌名;不得重复品牌名或丢失实际章节名称。世界选择入口的浏览器标题只显示对应品牌名。Open Graph 与 Twitter 标题在章节及内容页跟随页面标题;世界选择入口的分享标题保留本地化书名,应用名称与分享站点名称始终使用对应品牌名。静态 HTML、客户端运行时、应用名称及社交元数据按各自用途保持一致。页签图标使用官方图形的深墨绿底暖金版,维持官方交叠三角结构,并保留有效的 SVG、ICO、PNG 与触屏图标格式;图形宽度保持在画布约七成,四周保留留白,不让标志挤满底板;核对 16/32px 和高像素密度下的辨识度。 +- 魔法世界目录页、阅读侧栏和阅读工具栏的夜间字标使用同一暖金官方标志与浅象牙色文字(`#e1e4d6`);白天保留深墨绿文字。不能把白天字色留在夜间背景上,也不恢复偏暗的全金色文字。 +- 分卷标题应比章节条目醒目:当前为目录基础字号加 2px,章节名为基础字号减 2px。卷号与卷名对齐首行,子章节沿同一文字起始线排列;编号保留独立窄列。优先给卷名足够宽度,桌面中文侧栏让“Rust 中的语义驱动设计”自然保持一行。窄屏按可用宽度自然折行,不用均衡换行、截断或缩小标题来硬塞。 +- 分节标题前保留清楚的段间留白,标题行高约 1.35。分页中把标题与后文保持在一起时,也必须保留与前一节的间距;页首标题不额外添加空白。 +- 正文、列表、表格和提示框沿文章内容区对齐。新增区块使用现有内容宽度、段落间距及容器内边距,不以负边距、绝对定位或多个空格凑齐。 +- 中文正文自然流动,不手动逐句换行,不把每句话锁成一行。标题可按完整语义断行;代码、API 名称和公式按各自语法保留。长链接、长标识符和表格不得撑出手机屏幕。 +- 搜索结果以章节标题为主,分卷名为辅:章节标题在桌面约 27–32px、手机约 25–29px,分卷名约 17–18px;魔法世界沿用书籍衬线字体,现实世界保留中性界面字体与衬线章节标题。搜索未输入时只显示一句本地化标语“一个关键词,翻开下一页。”;输入后再显示匹配章节,摘要最多展示两行,避免说明文字淹没标题。不要恢复重复的搜索范围说明、“开始探索”及易混淆的“简介”推荐入口。新增结果条目必须与已有条目的文字起始边缘、分隔线和箭头位置一致。 +- 搜索输入只更新声明式结果组件,不扫描翻译阅读文档或刷新图标。搜索索引按本地化章节数组缓存;数组与内容保持不可变,语言或内容变化提供新数组,保留匹配、排序、摘要与跳转行为。正文翻译只来自 Markdown 构建流程,不恢复 HTML token 或 DOM 翻译索引。 +- 侧栏底部只保留 GitHub 项目入口,不恢复“小小积木。无限可能。”及对应语言的宣传标语。书页页眉、页脚和页码沿用已有层级,不与正文争抢视觉重点。 +- “导言”及对应语言的独立目录入口使用目录基础字号,书形图标为 22px,点击区至少 48px 高。章末“返回全书目录”和“阅读其他章节”使用正文字号、至少 48px 点击高度,不缩成装饰性小字。 +- 图片和文字以图片实际可见画面的边缘对齐,不只对齐外层盒子。完整显示产生留白时调整容器布局,不拉伸或裁掉已经确认的主体。插图、透明人物和标志保留完整轮廓。 + +## 英文大小写与多语言 + +- 品牌名称固定为 `ALUX Programming`,`ALUX` 保持全大写。英文界面导航、按钮和模式名称沿用 `locales/ui/en.json` 的约定,例如 `Magic World`、`Real World`、`Book View`。先复用现有文案键,不对所有字符串机械执行首字母大写。 +- 原文标题、正文句子、书目名称保持作者原有大小写。代码、类型、函数、变量、路径、命令、URL、锚点和数学符号不参与界面大小写转换,不翻译或改写受保护的技术标识符。 +- 翻译忠于原文的含义、逻辑、语气和技术边界,同时使用母语者自然的表达;不要按英文词序逐字硬译。术语与现有章节一致,同一概念不能在目录、正文和搜索结果中无故换名。 +- 中文署名用“光之十一”,英文署名用“Shixi Lin”;双语材料可同时出现。中文欢迎语中 ALUX 的读音按已经确认的“阿拉克斯”。 +- 当前支持英文、简体中文、繁体中文、日文、韩文、越南文、德文、西班牙文、俄文、乌克兰文和阿拉伯文。阿拉伯文布局按 RTL,代码和公式保持 LTR;图标、前后导航和对齐需按阅读方向检查。 + +## 工具栏与三端布局 + +- 音乐按钮放在顶部工具栏、紧接昼夜切换。字号和阅读外观控件形成一组,书签及阅读模式保留清晰的位置;不要把音乐开关变成另一个必须先打开的菜单。 +- 手机端按已有网格重排,点击区域至少 44px,欢迎语按钮至少 48px 高。不得通过隐藏字号、书签或音乐功能来掩盖拥挤。桌面、平板和手机都要检查真实文字长度,特别是德语、西里尔文及 RTL。 +- 提示贴近实际触发按钮,受视口边界约束,不压住正文的主要阅读区。阅读音乐提示默认 5 秒收起;悬停和调整音量时保留,离开后约 2 秒收起。键盘操作不能被倒计时打断,关闭按钮始终可用。音乐提示不显示重复的“阅读音乐”标题,直接呈现 20px 的开关说明和音量条;读屏名称仍保留。 + +## 材质、色彩与翻页 + +- 官方 ALUX 标志的几何结构必须保持一致。可按页面材质调整色调,不替换成近似图形。现实世界保持中性灰白或炭灰;魔法世界保留纸页与森林气质,不把整站改成同一种装饰风格。 +- 日夜模式分别检查文字对比度。不要靠发光、高亮整页或过度加粗解决可读性问题;也不要把辅助文字淡到难以辨认。 +- 白天的目录按钮使用浅暖橄榄底、深橄榄文字与细边框,避免作为强主按钮压过阅读内容;夜间保留深绿,不把白天按钮颜色直接套入夜间。 +- 魔法世界白天的代码块使用浅暖灰底和深色语法配色,避免大块深绿压住纸页;夜间保持深色代码块。每组语法文字相对代码底色至少达到 4.5:1 对比度,不能直接把夜间的浅色高亮移到浅底。 +- 章内和跨章翻页统一为 560ms 的纸页翻动,书框和中间书签保持固定。夜间纸页通过折痕、纸边和投影区分前后页,静止的阅读底色保持偏暗。新增样式不能覆盖 PageFlip 的位移、裁切或层叠关系。 +- 小主人于2026-10-27选择优先按需分页:打开章节只测量本章,不为全书总数在前台或后台分页其他章节。只有当前语言、字号和精确视口布局的全书计数已从实际访问中得到可靠缓存时,才显示连续全书页码;否则进度明确标为本章,不估算或冒充全书总数。页脚数字靠各自外侧,不补前导零、不拼接章号;RTL 数字区间保持 LTR。滚动模式不显示虚构页码,目录和书签继续按稳定章节身份及锚点定位。 +- 尊重系统减弱动画设置。切换章节、语言、阅读模式和窗口宽度后须清理旧动画,不留下遮罩、重叠纸页或阻挡点击的透明层。 +- 复用预览书页只能发生在同一章节数组、语言、字号与视口布局的计数缓存已经就绪时;未缓存布局仍须等待字体、图片并测量全书。不要以省略资源等待或沿用旧布局计数换取速度。 +- 滚动阅读的背景铺满整段阅读容器及其内边距,白天使用低纹理浅羊皮纸,夜间使用稳定深墨绿。`page-book` 在滚动模式下保持透明,不再叠一张旧纸纹形成矩形底板。日间侧栏滚动条使用暖灰橄榄色,夜间保留深绿;不要用夜间的深色轨道分割浅色页面。 +- 语言选择器的下拉箭头使用 `inset-inline-end` 等逻辑属性,RTL 时与文字、地球图标一起检查,不能与地球轮廓重叠。不要通过压扁或旋转地球图标掩盖布局问题。 + +## 插图与 GitHub 说明 + +- 章节插图的网页替换表统一放在 `scripts/reader-presentation.ts`,魔法、现实、滚动、翻页、静态回退及全部语言共用;不要只在某一个阅读器里替换。保留 `src/assets/` 原始图片及正文含义,新增网页素材放在 `public/art/`。详见 [ARTWORK.md](ARTWORK.md)。 +- 同一 YouTube 访谈可以引用不同片段,不能只凭相同封面删重。网页生成器保留原始 `clip`/`clipt` 来源,并按片段边界设置官方 `start`/`end` 秒数、显示时间范围。分页测量不加载嵌入播放器,只有实际阅读页恢复视频地址。 +- 插图以该章节的含义为依据,避免随机齿轮、辉光、无关符号和装饰堆砌。重画后检查透明 Alpha、完整轮廓、日夜底色、100% 边缘以及手机实际大小;压缩后也重新检查。工具不能锁定生成尺寸时如实记录实测尺寸,不把提示词里的 4K 当作实际结果。 +- GitHub 默认介绍为根目录英文 `README.md`,十种本地化介绍位于 `docs/README.<语言代码>.md`。各版本顶部使用同一语言顺序、语言本名和相对链接,当前语言以加粗标识;不用国旗代表语言。阿拉伯语说明使用 RTL,命令保持 LTR。GitHub 的语言切换是静态链接,不伪称按地区自动跳转。 +- 介绍先说明这本书讲什么,再提供目录、阅读和本地运行入口。保留作者、技术事实及原有许可说明,不增加宣传套话、AI 制作叙事或虚构的在线部署。网站初始语言与手动选择的行为仍由现有语言路由处理。 +- Telegram、X 和 GitHub 封面共用森林、暖金官方标志与浅象牙字色。按链接语言提供对应书名、简介与图片,通用根入口的静态元数据用英文兜底;不得用访客地区推测分享爬虫的语言。`src/site-meta.ts` 统一标题和简介,`scripts/share-card-design.ts` 维护十一语言封面。GitHub 各语言 README 使用同语种封面,保留原生排版;不伪称 GitHub 的侧栏 About 会自动切换语言。 +- `node scripts/share-preview.ts` 只生成 `previews/social.html` 和工程输出中的 TG、X、GitHub 分享示意,不覆盖 `previews/index.html` 阅读截图预览。检查每种语言的实际渲染、长文案、RTL 和浅深平台背景;本地示意与平台上线后的抓取、裁切及缓存验证分别报告。 + +## 声音行为 + +- 入口只有欢迎语,没有背景音乐。欢迎语进入时尝试自动播放一遍,支持停止和重播;浏览器拦截时,在首次有效页面手势中重试。用户主动停止后,不因随后的普通点击再次自动播放。 +- 魔法世界进入后默认播放阅读音乐,现实世界默认关闭。音符按钮单击直接开关;同一世界切换章节时不重复重置。离开阅读区停止音乐,切换后台暂停,恢复前台时遵守原来的开关状态。 +- 新访客音量默认为 100%,表示音频文件本身的电平,不额外放大,也不改变设备系统音量。用户调整后记住选择。手机使用 Web Audio 的增益控制;不得只修改在 iPhone 上可能无效的媒体元素音量。 +- 沿用已确认的配音角色和音频资产,不擅自替换音色、循环欢迎语或叠加入口背景音乐。欢迎文案改动时同步核对全部语种的实际音频。 + +## 修改后的必要检查与提交 + +本轮以 [合并验收记录](docs/merge-acceptance.md) 为准,只修可复现阻碍,不再重写架构。逐项标明 `PASS / FAIL / NOT TESTED`,附命令、浏览器/引擎版本、日志或测试证据。反复切换章节、阅读模式、语言和横竖屏后检查内容完整性、事件监听、观察器、定时器及脱离文档的节点;导航离开时翻页动画必须完成或取消。英文源变化要发出译文可能过期的非阻断警告,构建不能自动更新“已核对”指纹。 + +干净检出必须验证冻结依赖安装、严格类型、编译器 lint、构建及自动测试,并比较相同输入连续构建的生成内容哈希。检查内部资源、路由和片段,前端 CI 与原始 mdBook 发布分别验证。桌面 Chromium、Firefox 与移动模拟分别记录;小主人只有安卓,没有 iPhone/iPad,真实手机当前未连接。Android 配置的 Chromium 和 iPhone 配置的 WebKit 可报告模拟通过,不能冒充真机 Chrome 或 iOS Safari;真实设备未测的合并门槛保留 `NOT TESTED`。 + +1. 运行 `pnpm --dir web build`,确认翻译覆盖、技术标识符保护及静态路由生成通过。 + 首次打开、重复刷新与慢图片/字体加载时必须有可读书页,不能先显示空书框。本章资源未就绪前隐藏临时页号,资源就绪后按上述按需规则显示本章进度或可靠全书计数;重新排版保留当前内容,待新布局准备好后替换,并检查首帧交接。字体和图片并行准备,同一会话复用已解码图片;加载检查须记录首个可读内容和最终就绪时间,不能只检查最终 DOM。 +2. 根据变更范围检查桌面、平板和手机;至少覆盖 320px、768px 和 1440px,以及中英文、长文案和 RTL。涉及所有语言的共用样式或新文案时检查全部语种。查看真实渲染和实际交互,不以源码或截图尺寸代替运行效果。 + 涉及页面标题、语言路由或品牌元数据时,核对静态直达与刷新、客户端导航、语言切换,并覆盖两个阅读世界;检查页签标题、应用名称、Open Graph 与 Twitter 标题及分享站点名。确认每个内容页标题只含一次本地化品牌名,世界选择入口的浏览器标题和分享标题分别遵守上面的专用规则;分享标题的差异不应用于应用名称或分享站点名。 +3. 检查目录标题层级、正文边缘、长标题换行、可点击区域、弹层边界、横向溢出及日夜对比。涉及翻页须实际检查章内和跨章、前进与后退;涉及声音须检查播放、停止、重播、音量和后台恢复。 +4. 分享预览文件位于 `web/previews/`,中英文应同时可检查,并可直接进入对应语言的网站。更新分享构图后同步对应素材,不能用旧截图冒充新效果。 +5. 只提交本轮授权的差异,保留其他工作。当前这一轮继续更新 [PR #2](https://github.com/alux-network/alux-programming/pull/2),不另开 PR,不合并,不开启自动合并,不修改生产发布流程。后续独立任务遵从用户当轮指定的提交范围和 PR。 + +补充约定:侧栏搜索入口使用简短的“搜索 / Search”及各语言对应短标签,不恢复“搜索本书 / Search the Book”。提示框标题跟随正文字号,约为正文的九成且不低于 18px。魔法世界已移除底部“本章目录”;GitHub 项目入口单独放在侧栏底部,替换那里的星形装饰,不附加宣传标语。图标至少有 44px 点击区和本地化的读屏名称,链接到项目仓库。章末“返回全书目录”“阅读其他章节”及最后一页的目录操作必须真正导航到独立的 `/contents.html` 全书目录页,不能仅展开侧栏冒充跳转;现实世界的目录地址为 `/real/contents.html`。目录页沿用当前语言和日夜设置,章目直接进入对应世界的正文,分组标题不可链接到分卷过渡页。工具栏目录按钮继续开关侧栏。书页页脚、章末的星形装饰及页码保持原样,不在阅读工具栏或每张书页重复添加源码入口。手机工具栏需检查每两个按钮的可见区域是否重叠,不能只检查页面有没有横向滚动条。 diff --git a/web/ARTWORK.md b/web/ARTWORK.md new file mode 100644 index 0000000..afbd5b4 --- /dev/null +++ b/web/ARTWORK.md @@ -0,0 +1,20 @@ +# Reading illustrations + +The web reader uses a small family of brass, ivory and forest-green illustrations. The original Markdown and images in `src/assets/` remain intact for mdBook; the web content generator maps the four section images to this family before localization. Both reading worlds and their static fallbacks receive the same mapping. + +| Source image | Web asset | Meaning | +| --- | --- | --- | +| `semantic-view.png` | `art/semantic-view.webp` | A prism: one input, different interpretations. | +| `design-by-meaning-rust.png` | `art/capability-crab.webp` | The existing Rust crab and capability blocks. | +| `concepts.png` | `art/concepts.webp` | Connected mechanisms and their tools. | +| `insights.png` | `art/insights.webp` | Reading closely and finding connections. | + +The prism, mechanisms and book/lens images were redrawn for the web reader on 2026-10-23 using the existing images as subject references and the accepted crab as a material reference. Their saved masters are transparent 1254 × 1254 PNGs; all four runtime section illustrations are 512 × 512 WebP. The generation tool did not expose an exact output-size control. These are not native 4K assets. + +Keep complete objects and transparent margins. Check both PNG and WebP on the actual day and night backgrounds, at their rendered size and at full resolution. Unused PNG masters are kept outside the Git/public tree in the local visual asset library (`07_视觉设计/20261023_ALUX网页素材`), with verified identical copies before removal. Original mdBook assets in `src/assets/` remain unchanged. Do not regenerate the official ALUX mark, change chapter meaning, add text to decorative illustrations, or replace technical diagrams without checking their content. + +Size runtime assets for their rendered use, including high-density screens. The official marks are 256 × 239 WebP (62–72 CSS pixels); the ribbon is 256 × 704 WebP (85 CSS-pixel background width); section illustrations are at most 140 CSS pixels tall. These have more than 2× resolution at their current display sizes. Verify both a 3840 × 2160 viewport at DPR 1 and a 1920 × 1080 viewport at DPR 2 when changing them. Preserve full subjects, aspect ratios and alpha; do not reduce the forest, wizard or full-width surfaces to icon sizes. The forest stays at its native 1672 × 941 and the standing wizard at 1024 × 1536; a 4K display does not make these native 4K artwork. New native high-resolution sources would be needed for pixel-for-pixel full-screen 4K detail. Do not upscale and label them native 4K. + +Removing masters reduces the current checkout and static build, not blobs retained in earlier Git commits. Do not rewrite shared history to remove those blobs without explicit authorization. + +For a future replacement, add the asset here, update the single mapping in `scripts/reader-presentation.ts`, and check all four reading combinations: magic book, magic scroll, real day and real night. Preserve original alt text where its meaning still applies; otherwise update and localize it deliberately. diff --git a/web/README.md b/web/README.md new file mode 100644 index 0000000..9e7ae49 --- /dev/null +++ b/web/README.md @@ -0,0 +1,77 @@ +# ALUX Programming — local preview + +This independent web presentation preserves all 28 original chapters from `../src` and the existing mdBook publishing workflow. `/` opens the wizard chooser. Magic and Real world enter the same introduction directly, with a same-chapter world switch. The ALUX logo returns to the chooser. Full contents pages are available at `/contents.html` and `/real/contents.html`, with language prefixes where appropriate; chapter entries open the chosen reader directly. `/magic.html` remains a compatible entrance alias. + +The chooser places a complete standing wizard in a misty forest clearing, with warm and cool light distinguishing the two entrances. Its larger language control uses a high-contrast surface. The forest artwork is generated at 1672×941 native pixels and ordinarily encoded to WebP; it is not an upscaled 4K asset. Reader palettes remain independent. + +## Run locally + +Use Node 22.18 or later (acceptance uses Node 24) and the pinned pnpm 11.25.0. Start with `pnpm install --frozen-lockfile`. The content build requires `mdbook` 0.4.52, `mdbook-admonish` 1.20.0 and `mdbook-katex` 0.9.4 on PATH. They can be installed with Rust's `cargo install --version --locked`; KaTeX must retain its default pre-render feature. `MDBOOK_BINARY` can select another path to the pinned mdBook executable. + +Run `pnpm install`, then `pnpm dev` on `127.0.0.1:4173`. Development watches `src/` and `book.toml`. A translated Markdown edit rebuilds that edition; a canonical source/configuration edit rebuilds every edition. Reload follows a successful build. A compiler failure leaves existing reader JSON in place. `pnpm build` generates content, checks translations and strict TypeScript, builds Vite assets and writes direct static routes. `pnpm preview` serves that build on port 4174. `pnpm test` generates content and runs type checks plus focused unit and book integration tests. The original mdBook publishing configuration and workflow are unchanged. + +## Content architecture + +`scripts/mdbook.ts` derives a web-only configuration from the original `book.toml`. The custom renderer `scripts/mdbook-json.ts` serializes mdBook's processed Book, including part titles, separators, chapter order and nested children. Both readers receive one `ReaderBook` model defined in `src/book.ts`; neither parses `SUMMARY.md` or discovers chapters from filesystem order. + +The JSON backend contains Markdown, not an HTML syntax tree. The same build therefore uses mdBook's official HTML renderer for Markdown, links and heading IDs after the existing admonish and KaTeX preprocessors. `scripts/reader-presentation.ts` adapts that rendered HTML for the reader's code toolbar, syntax colors, image mapping and bounded video clips. Two small web-only preprocessors normalize Windows line endings before KaTeX and protect its TeX annotations from Markdown escape processing; they do not modify source files. + +English remains canonical in `src/chapter.md`. Optional translations live beside it as `chapter.zh.md`, `chapter.de.md`, etc. One `SUMMARY.md` supplies all editions. The web-only `scripts/mdbook-localization.ts` preprocessor substitutes a selected source before normal includes, admonitions and KaTeX; a missing translation uses English. Canonical chapter paths and explicit heading IDs stay unchanged. Optional leading metadata such as `` supplies navigation labels; translated `index..md` supplies part names. Do not add another language-specific SUMMARY or overwrite English during builds. + +`scripts/book.ts` writes an already-localized `public/content/.json` from each edition's native mdBook JSON and HTML. Both worlds, search and static routes consume those models. The browser requests only selected editions and caches successful requests. `public/content.json` is an English compatibility output, not a translation manifest. Four legacy heading fragments remain explicit aliases in `scripts/heading-aliases.ts`. Reading-time estimates retain the canonical edition's values instead of comparing whitespace counts across writing systems. + +SolidJS owns navigation, dialogs, bookmarks, language selection, theme and size controls in `src/reader-app.tsx`, `reader-ui.tsx`, `book-view.tsx`, `real-view.tsx` and `navigation-views.tsx`. Generated chapter HTML is opaque. `book-layout.ts` owns measurement, pagination and PageFlip lifecycle; `reader-audio.ts` owns media/Web Audio lifecycle, with declarative controls in `music-controls.tsx`. Small typed interface dictionaries live in `locales/ui/`; components use explicit message keys, and `ui-format.ts` handles variable labels. There is no prose dictionary, HTML-token alignment or DOM text translation pass. Node executes erasable build-script types; `tsc --noEmit` checks strict TypeScript and JSX. + +The one-time `scripts/migrate-translations.ts --baseline --output ` tool converts approved reader snapshots back to source Markdown. Turndown is used only by this migration tool, never to compile or render a book. See [the migration and review record](docs/source-localization-migration.md) for preservation scope and the one legacy heading-metadata discrepancy. + +After `pnpm build`, run `pnpm test:browser` for the production-build Chromium regression: all eleven languages at 320px, 768px and 1440px in both worlds and full contents, plus navigation/search/bookmark/language/mode/copy/music-control interactions. Install Playwright's Chromium with `pnpm exec playwright install chromium`, or point `PLAYWRIGHT_CHROMIUM_EXECUTABLE` to an existing compatible Chromium executable. It serves the build temporarily on port 4175 and writes its report/screenshots under the project `output/reader-regression/` directory. These browser checks do not prove physical-device audio playback or live hosting/cache behavior. + +## Reading + +Agents adding chapters or interface content must follow [AGENTS.md](AGENTS.md) for alignment, typography, capitalization, localization, responsive behavior and verification. + +The magic reader uses soft physical pages, visible chapter navigation, blank-paper clicks, touch swipes, keyboard turns and continuous reading. Text selection, links, code, tables and interactive regions do not trigger blank-paper turns. Arabic spreads begin on the right and advance in reading order. Long technical blocks remain complete in scroll regions; tables continue between whole rows. The toolbar keeps stable dimensions when navigation opens or closes. Book and scroll views share their text, code, caption and illustration sizes in `reader-presentation.css`. Scroll view has one continuous paper surface; its inner book container is transparent. + +The Real world uses a quiet technical-document layout with neutral gray-white day mode and neutral charcoal night mode. It has one day/night toggle. Both readers share their day/night and font-size preferences. Base reading sizes are 24px for Latin and Cyrillic languages, 22px for Chinese, Japanese and Korean, and 26px for Arabic. Contents group headings use the base plus 2px; chapter entries use the base minus 2px. Both font-size controls scale the body and navigation together and remain available on phones. Interface labels use consistent English title case; original prose, heading anchors and technical identifiers retain their spelling. Both chapter boundaries and turns within a chapter use a 560ms physical paper animation; the cover and cloth bookmark remain stationary. Reduced-motion preferences bypass the animation. + +My bookmarks is visible in each sidebar. Multiple saved chapters retain their world and reading position, can be opened or removed, and migrate the older single-bookmark setting. Bookmarks, reading preferences and manual language choices are stored on the current browser; no account or server-side reading collection is implied. + +Magic opens and measures only the selected chapter. Until exact counts for every chapter in the same language, font and viewport layout have been learned from actual visits, progress is explicitly labelled as chapter progress. Reliable complete cached counts allow continuous whole-book numbers; unseen chapters are never measured to obtain a total. Numbers sit at the outer edges, with a compact range/total below the book. Continuous scrolling does not invent page numbers. Chapter-end contents links navigate to a dedicated full contents page. Its chapter links enter the selected chapter directly; they do not pass through part-opening pages. The toolbar Contents button still toggles the reading sidebar. + +The current chapter appears immediately as readable sheets while its fonts and images prepare. Provisional page numbers stay hidden. Fonts and images load concurrently, and decoded images are reused across chapter navigation. Reflow keeps the previous content until its replacement is ready; a noninteractive copy bridges PageFlip's first paint without duplicating anchors or starting embedded players. + +Pagination tasks cancel on replacement or unmount. The pinned [page-flip lifecycle patch](patches/README.md) releases render frames, initialization timers and resize listeners on destroy. Source metadata carries a SHA-256 fingerprint of canonical English Markdown: builds warn when that baseline changes. Updating a fingerprint acknowledges a translation review; the build never updates it automatically. Initial hashes identify the migration baseline, not a new linguistic review. + +Run `pnpm lint` for strict compiler-backed unused/unreachable/fallthrough checks and `pnpm typecheck` for the normal strict check. `pnpm test:generated` audits all generated internal links/assets/fragments and inventories every dist file for repeat-build comparison. After installing Playwright's Chromium, Firefox and WebKit, `pnpm test:acceptance` checks lifecycle and four browser configurations. Android/iPhone profiles are simulations; physical-device status remains separate. See [measurable acceptance](docs/merge-acceptance.md) for commands, evidence and limits. The frontend CI is additional to the unchanged native publishing workflow. + +Embedded interview clips retain their original references and show their individual time ranges. The web generator supplies explicit YouTube playback start/end bounds; repeated thumbnails alone do not imply duplicate clips. + +## Languages + +The menu order is English, 简体中文, 繁體中文, 日本語, 한국어, Tiếng Việt, Deutsch, Español, Русский, Українська, العربية. English has no language prefix. The other paths use `/zh/`, `/zh-hant/`, `/ja/`, `/ko/`, `/vi/`, `/de/`, `/es/`, `/ru/`, `/uk/`, `/ar/`. The Real reader follows the language directory, e.g. `/zh/real/introduction.html`. HTML uses `zh-Hans` and `zh-Hant`. Old `?lang=` links and common Chinese locale aliases are canonicalized without losing the chapter or anchor. + +All ten translations contain 1,860 prose units and 138 interface labels. Code, API identifiers, formulas, diagrams and reference titles retain their original technical spelling. Each language has received a semantic review. The build checks key coverage, protected tokens and empty translated links/emphasis. Arabic prose is RTL; code and math remain LTR. Original English Markdown remains authoritative and unchanged. + +Resolution order is an explicit language path or legacy query, a saved manual choice, a session-cached IP-country result, then English. First visits use the public GeoJS country endpoint with a short timeout; only the resulting language is cached, not the returned IP address. A manual selection persists and takes precedence over later country detection. Unsupported countries and failed lookups fall back to English. Country detection does not infer a person's native language. + +## Brand and sharing + +`public/alux-black.png` and `public/alux-white.png` preserve the owner's official geometry. The favicon recolors the verified white mark to warm gold on a forest-green rounded square, with SVG, 16/32/48px ICO, 32px PNG and 180px touch-icon variants. It is designed for tab-size legibility rather than miniature bronze texture. Browser titles, app names and Open Graph site names use Chinese for the two Chinese editions and English for all other editions; chapter text, translated descriptions and sharing covers remain localized. `src/site-meta.ts` supplies this shared identity to runtime navigation and static routes. Magic mastheads retain the generated bronze material variants; the technical reader uses the original mark and a live typographic wordmark. The chapter illustrations share a brass/ivory/forest-green material family; original source illustrations remain intact in `src`. The common mapping in `scripts/reader-presentation.ts` applies to both readers and static fallbacks; see [ARTWORK.md](ARTWORK.md) for the assets and measured sizes. + +All static routes include localized Open Graph and X large-image card metadata, localized 1200×630 JPEG cards, canonical links and language alternates. `scripts/share-card-design.ts` contains the share-card composition. Set `ALUX_SITE_URL` only when preparing a separately authorized deployment; the local build defaults to `http://127.0.0.1:4174`. Telegram/X previews are checked locally; real crawler fetches and platform caches require a reachable public URL and have not been published or claimed verified here. + +The share cards use the accepted forest and complete standing wizard, with the same warm-gold official mark and ivory lettering as the night reader. Each language URL supplies its own localized title, description and 1200×630 cover; the unprefixed entry supplies English metadata. `src/site-meta.ts` holds the shared titles and descriptions, and `scripts/share-card-design.ts` holds the localized image composition. GitHub README introductions use the same language-specific cover images and retain their native GitHub layout. + +`node scripts/share-preview.ts` regenerates [the Telegram, X and GitHub preview](previews/social.html) and `../output/分享预览.html`. It supports all eleven languages and light/dark platform mockups; it does not overwrite the reader screenshot preview. The mockups show the prepared image and metadata, not a verified live platform result. Platform framing, cropping, metadata visibility and caching remain controlled by each service. + +The PR also includes [the Chinese/English preview](previews/index.html), current desktop/phone captures in `previews/assets`, and the eleven share cards. The preview covers day/night contents, book and scroll layouts, the technical reader and eleven welcome voices. It links to the local production preview on port 4174, with a field for another running server address. Open the HTML file directly after checkout; keep the local server running for reader links. The preview stays outside Vite's public output. + +Static chapter routes also provide localized no-JavaScript reading fallbacks. No original source chapter, formula, code example, media embed or publishing workflow is removed by the web layer. + +## Welcome voice and reading music + +The gateway uses the owner-approved Qwen3 Uncle Fu character voice. The Chinese clip reuses the accepted performance; Japanese, Korean and Russian speech use phonetic brand spelling for clear pronunciation. Vietnamese, Ukrainian and Arabic use local OmniVoice cloning from that approved synthetic reference. The owner specified noncommercial use; OmniVoice model attribution: https://huggingface.co/k2-fsa/OmniVoice (CC-BY-NC), with code at https://github.com/k2-fsa/OmniVoice. No private or third-party person was cloned. + +Eleven clips are mastered around -16 LUFS with true peaks below -2 dBTP; measured values and text are in public/audio/welcome/manifest.json. Welcome speech attempts playback on gateway entry and language change, plays once, has replay/stop controls, and stops when leaving. If autoplay is blocked, the first page click, touch or key retries playback; an explicit stop suppresses that retry. The gateway has no background music. + +Reading music uses the owner-provided 在森林的呼吸里, with one audio instance across chapter changes and a Web Audio gain control for phone volume. Each entry into a reading world shows a small dismissible hint beside the music button: Magic starts music automatically when permitted, while Real defaults off. The note button follows the day/night control and directly toggles playback. Its title-free 20px hint dismisses after five seconds; hovering or adjusting holds it open, and leaving dismisses it after two seconds. A new visitor starts at 100% (unity gain, the audio file’s own level); manual volume changes are remembered. If autoplay is blocked, a page gesture retries music. Pausing lasts through chapter navigation. A hidden page pauses music. No audio is mixed over the welcome. diff --git a/web/book-reader.css b/web/book-reader.css new file mode 100644 index 0000000..9cc72d8 --- /dev/null +++ b/web/book-reader.css @@ -0,0 +1,16 @@ +.bound-reading{background:#dfd0b3;color:#493a28;--ink:#3b3d2a;--text:#514331;--paper-light:#f2e7cb;--line:#b8a17a66;--copper:#986431;--muted:#827152;--page-tone:#eee0bd} +.bound-reader{min-height:100svh;background:radial-gradient(ellipse at 45% 25%,#fff5da 0,#ede1c3 50%,#d2bc9570 100%);padding:0 20px 12px}.bound-toolbar{height:110px;display:flex;align-items:center;justify-content:space-between;gap:30px;padding:12px 24px;position:relative;z-index:20}.bound-toolbar .brand-emblem{width:56px;height:60px;background:linear-gradient(145deg,#4f5d40,#253b31 65%,#152b23);border-color:#9b835d}.bound-toolbar .brand-emblem img{width:39px;height:39px}.bound-toolbar .brand>span{font-size:29px}.bound-toolbar .brand small{font-size:10px}.bound-location{display:flex;flex-direction:column;gap:7px;margin-right:auto;margin-left:35px}.bound-location>a{font:20px var(--serif);display:flex;align-items:center;gap:9px}.bound-location>a svg{width:18px}.bound-location>span{font:11px var(--mono);color:var(--muted)}.bound-tools{display:flex;gap:8px;align-items:center}.bound-tools .icon-button{width:42px;height:42px;font-size:16px}.bound-tools .icon-button svg{width:21px;height:21px}.bound-mode{background:transparent;border-left:1px solid var(--line);padding:10px 0 10px 17px;margin-left:6px;font:17px var(--serif);white-space:nowrap}.bound-stage{outline:none}.bound-volume{position:relative;height:calc(100svh - 205px);min-height:480px;padding:14px;background:linear-gradient(135deg,#5d6344,#263b2e 15%,#314231 70%,#192d22);border:1px solid #b59761;border-radius:10px 13px 15px 8px;box-shadow:0 0 0 2px #70633f,inset 0 0 0 5px #1d3025,inset 0 0 0 6px #ae8e51,0 10px 0 -5px #cfbe9d,0 13px 0 -6px #877758,0 25px 40px #553c2826;isolation:isolate}.bound-volume:before,.bound-volume:after{content:'';position:absolute;z-index:8;pointer-events:none;width:31px;height:31px;border:3px double #c2a264;filter:drop-shadow(0 1px 0 #0f2213);background:#6b623348}.bound-volume:before{left:3px;top:3px;border-right:0;border-bottom:0;border-top-left-radius:7px}.bound-volume:after{right:3px;bottom:3px;border-left:0;border-top:0;border-bottom-right-radius:7px}.page-book{height:100%;width:100%;position:relative}.folio-page{width:var(--sheet-w);height:var(--sheet-h);background-color:var(--page-tone);background-image:url('/art/paper.webp');background-size:cover;color:var(--text);padding:29px 48px 26px;overflow:hidden;box-shadow:inset 0 0 30px #8b6a2c12,inset 2px 0 5px #fdf6d9;position:relative}.folio-page:nth-child(odd){background-position:left center;box-shadow:inset -25px 0 30px -20px #81683975,inset 0 0 36px #92773f15;border-right:1px solid #b59d6a}.folio-page:nth-child(even){background-position:right center;box-shadow:inset 25px 0 35px -25px #81683980,inset 0 0 36px #92773f15}.folio-running-head{display:flex;align-items:center;justify-content:space-between;gap:15px;font:11px var(--mono);letter-spacing:.5px;color:#927b53;border-bottom:1px solid #a88a4e4d;padding:0 0 17px;height:34px}.folio-running-head>span:last-child{font-size:9px;white-space:nowrap}.folio-content{height:calc(100% - 77px);margin-top:20px;overflow:hidden;font-size:var(--reading-size);line-height:1.65}.folio-content>p:first-child{margin-top:0}.folio-content h1{font-size:63px;line-height:1.02;margin:12px 0 30px;font-weight:600;color:#41412b}.folio-content h2{font-size:40px;margin-top:20px}.folio-content h3{font-size:32px}.folio-content p{margin:16px 0}.folio-content ul,.folio-content ol{margin:17px 0;padding-left:27px}.folio-content li{margin:6px 0}.folio-content .admonition{margin:20px 0;padding:17px 20px;background:#dbc69a29;border-color:#a58d5855;border-left-color:#ac925e}.folio-content .admonition-title{font-size:11px;letter-spacing:1px}.folio-content .code-block{margin:20px 0;background:#2c392b;border-color:#4e5638}.folio-content .code-block pre{font-size:14px;line-height:1.75;max-height:calc(var(--sheet-h) - 175px)}.folio-content .code-toolbar{font-size:11px;padding:12px 16px}.folio-content .copy-code{font-size:11px}.folio-content table{font-size:.81em}.folio-content td,.folio-content th{padding:10px 12px}.folio-content .math-display{font-size:.9em}.folio-content .section-image{max-height:110px!important;margin:12px auto 18px!important}.folio-content .heading-anchor{font-size:15px}.folio-footer{position:absolute;bottom:19px;left:48px;right:48px;height:18px;display:flex;justify-content:space-between;align-items:center;color:#9d804b;font:12px var(--mono)}.folio-footer span:first-child{font-size:17px}.folio-overflow{overflow:auto;scrollbar-width:thin;scrollbar-color:#ae9468 #c5ad7955;padding-right:8px;overscroll-behavior:contain}.folio-overflow:focus-visible{outline:1px solid var(--copper);outline-offset:-1px}.folio-measure{position:fixed;left:-20000px;top:0;pointer-events:none;visibility:hidden}.folio-measure .folio-page{position:relative;width:100%;height:100%}.folio-chapter-end{text-align:center;padding:35px 10px;color:#8d7043}.folio-chapter-end>span{display:block;font-size:27px}.folio-chapter-end p{font:italic 27px var(--serif)}.folio-chapter-end a{font:600 28px var(--serif);display:inline-flex;gap:15px;align-items:center;color:var(--copper)}.folio-closing{display:flex;align-items:center;justify-content:center;flex-direction:column;height:100%;text-align:center;color:#9a8251}.folio-closing>span{font-size:38px}.folio-closing p{font:42px/1.35 var(--serif);margin-block:35px}.folio-closing a{font:18px var(--serif);display:flex;align-items:center;gap:12px}.bound-controls{display:flex;align-items:center;justify-content:space-between;gap:25px;padding:23px 18px 0}.sheet-control{display:flex;gap:13px;align-items:center;color:#84592f;background:transparent;font:21px var(--serif);padding:6px 10px}.sheet-control svg{width:30px;height:24px}.sheet-control:hover:enabled{transform:translateX(4px)}.sheet-control:first-child:hover:enabled{transform:translateX(-4px)}.bound-controls>div{text-align:center;display:flex;flex-direction:column;gap:7px}.current-chapter-title{font:18px var(--serif);color:#796748}.bound-controls #folio-position{font:11px var(--mono);color:#8f7953}.bound-outline{display:flex;align-items:flex-start;gap:30px;font:14px var(--serif);padding:8px 30px 0;justify-content:space-between;color:#90764d}.bound-outline details{position:relative}.bound-outline summary{cursor:pointer;list-style:none;display:flex;gap:9px;align-items:center}.bound-outline summary svg{width:13px;height:13px}.bound-outline nav{position:absolute;bottom:100%;left:0;min-width:260px;max-width:350px;max-height:420px;overflow:auto;background:#f3e5c9;border:1px solid #bba374;padding:12px 20px;box-shadow:0 15px 35px #3b2d2528;z-index:25}.bound-outline nav a{display:block;font:17px/1.4 var(--serif);padding:7px 0}.bound-outline>a svg{width:13px}.binding-ribbon{position:absolute;z-index:10;bottom:-22px;left:50.1%;width:18px;height:65px;background:linear-gradient(90deg,#8b4b28,#b4793c,#6e3e24);clip-path:polygon(0 0,100% 0,100% 100%,50% 85%,0 100%);filter:drop-shadow(2px 2px 2px #41291066);pointer-events:none}.bound-reading .book-sidebar{transform:translateX(-105%);width:340px;transition:transform .3s;z-index:70;padding:35px;background:#e9d8b5;color:#4b452d;border:1px solid #b39a65;box-shadow:12px 0 50px #231f1b33}.bound-reading .book-sidebar .brand>span{font-size:30px}.bound-reading .book-sidebar .brand small{font-size:10px}.bound-reading .book-sidebar a{color:#675e42}.bound-reading .sidebar-search{color:#5f603e;border-color:#b49b6555;background:#fff2}.bound-reading .sidebar-search kbd{color:#80714d}.bound-reading .back-to-world{font-size:15px}.bound-reading .intro-nav{font-size:21px}.bound-reading .sidebar-group{border-color:#bba57655}.bound-reading .sidebar-group h2{font-size:12px;color:#8f622e}.bound-reading .sidebar-group a{font-size:21px;padding:9px}.bound-reading .sidebar-group a>span{font-size:10px;color:#987b4c}.bound-reading .book-sidebar a.active{background:#cab08127;color:#725024;border-left-color:#9d6b34}.bound-reading .sidebar-bottom{font-size:10px}.bound-reading.menu-open{overflow:hidden}.bound-reading.menu-open .book-sidebar{transform:translateX(0)}.bound-reading.menu-open .sidebar-scrim{display:block;position:fixed;inset:0;background:#24352666;z-index:65;backdrop-filter:blur(4px)}.bound-reading .prose a{color:#986431}.bound-reading .prose strong{color:#45412b}.bound-reading .prose a.heading-anchor{color:#a88a51} +.continuous-reading .bound-volume{height:auto;min-height:70svh;padding:30px 8%;background-color:var(--page-tone);background-image:url('/art/paper.webp');background-size:cover}.continuous-reading .page-book{height:auto}.continuous-prose{font-size:var(--reading-size);line-height:1.8;max-width:1100px;margin:auto}.continuous-reading .bound-controls .sheet-control{visibility:hidden}.continuous-reading .binding-ribbon{display:none} +.bound-reading.night{--page-tone:#38402d;--text:#e2d5ae;--ink:#e8d7ae;--muted:#bdad83;background:#17251b}.bound-reading.night .bound-reader{background:#263321}.bound-reading.night .folio-page{background-image:linear-gradient(#263821dc,#263821dc),url('/art/paper.webp')}.bound-reading.night .folio-content h1,.bound-reading.night .folio-content h2,.bound-reading.night .folio-content h3,.bound-reading.night .prose strong{color:#eadbb1}.bound-reading.night .folio-content .admonition{background:#55644035}.bound-reading.night .prose a{color:#d4b176}.bound-reading.night .bound-toolbar,.bound-reading.night .sheet-control,.bound-reading.night .current-chapter-title{color:#d3c294}.bound-reading.night .bound-outline{color:#bba779}.bound-reading.night .continuous-prose{color:#e2d5ae} +@media(min-width:1800px){.bound-reader{padding-inline:28px}.bound-toolbar{height:130px;padding-inline:28px}.bound-volume{height:calc(100svh - 235px)}.bound-toolbar .brand-emblem{width:70px;height:75px}.bound-toolbar .brand-emblem img{width:48px;height:48px}.bound-toolbar .brand>span{font-size:38px}.bound-toolbar .brand small{font-size:12px}.bound-location>a{font-size:26px}.bound-location>span{font-size:14px}.bound-tools .icon-button{height:50px;width:50px;font-size:20px}.bound-tools .icon-button svg{width:25px;height:25px}.bound-mode{font-size:22px}.folio-page{padding:36px 64px 30px}.folio-content{line-height:1.75;height:calc(100% - 90px);margin-top:26px}.folio-content h1{font-size:84px;margin-bottom:35px}.folio-content h2{font-size:48px}.folio-content h3{font-size:38px}.folio-content .code-block pre{font-size:17px}.folio-running-head{font-size:14px;height:40px}.folio-running-head>span:last-child{font-size:11px}.folio-footer{left:64px;right:64px;font-size:15px;bottom:24px}.sheet-control{font-size:27px}.current-chapter-title{font-size:23px}.bound-controls #folio-position{font-size:13px}.bound-outline{font-size:17px}.bound-tools{gap:12px}} +@media(max-width:1200px){.bound-reader{padding-inline:12px}.bound-toolbar{height:95px;padding-inline:10px;gap:15px}.bound-toolbar .brand>span{font-size:23px}.bound-toolbar .brand small{font-size:8px}.bound-toolbar .brand-emblem{width:45px;height:49px}.bound-toolbar .brand-emblem img{width:32px;height:32px}.bound-location{margin-left:10px}.bound-location>a{font-size:18px}.bound-location>span{font-size:10px}.bound-tools{gap:2px}.bound-tools .icon-button{width:36px;height:38px;font-size:14px}.bound-tools .icon-button svg{width:18px}.bound-mode{font-size:16px;padding-left:10px}.bound-volume{height:calc(100svh - 190px)}.folio-page{padding:24px 34px 22px}.folio-running-head{font-size:10px}.folio-running-head>span:last-child{font-size:8px}.folio-footer{left:34px;right:34px}.folio-content h1{font-size:56px}.sheet-control{font-size:19px}.current-chapter-title{font-size:16px}.bound-outline{padding-inline:20px}} +@media(max-width:1000px){.bound-location{display:none}.bound-tools{margin-left:auto}.bound-volume{padding:12px}.folio-page{padding:30px 46px 28px}.folio-content h1{font-size:65px}.folio-content h2{font-size:42px}.folio-running-head{font-size:12px}.folio-running-head>span:last-child{font-size:9px}.folio-footer{left:46px;right:46px}.binding-ribbon{left:auto;right:35px}.bound-volume:before{z-index:30}.bound-volume:after{z-index:30}} +@media(max-width:760px){.bound-reader{padding-inline:7px;padding-bottom:12px}.bound-toolbar{height:83px;padding:10px 8px;gap:10px}.bound-toolbar .brand-emblem{width:38px;height:43px}.bound-toolbar .brand-emblem img{width:27px;height:27px}.bound-toolbar .brand>span{font-size:21px;letter-spacing:3px}.bound-toolbar .brand small{font-size:6px}.bound-tools{gap:0}.bound-tools .icon-button{width:33px;height:36px;font-size:13px}.bound-tools .icon-button svg{width:18px;height:18px}.bound-tools #bookmark{display:none}.bound-tools #smaller-text{display:none}.bound-mode{font-size:13px;padding-left:8px;margin-left:0}.bound-volume{height:calc(100svh - 180px);min-height:460px;padding:9px;border-radius:5px}.folio-page{padding:20px 23px 24px}.folio-content{line-height:1.65;margin-top:17px;height:calc(100% - 68px)}.folio-content h1{font-size:45px;line-height:1.06;margin:10px 0 24px}.folio-content h2{font-size:34px;margin:18px 0}.folio-content h3{font-size:29px}.folio-running-head{font-size:9px;height:27px;padding-bottom:10px}.folio-running-head>span:last-child{display:none}.folio-footer{left:23px;right:23px;bottom:15px;font-size:11px}.folio-content .section-image{max-height:85px!important}.folio-content .admonition{padding:13px 15px;margin:16px 0}.folio-content .admonition-title{font-size:9px}.folio-content .code-block pre{font-size:12px;padding:15px;max-height:calc(var(--sheet-h) - 130px)}.folio-content .code-toolbar,.folio-content .copy-code{font-size:10px}.bound-controls{gap:8px;padding:16px 4px 0}.sheet-control{gap:4px;font-size:17px;padding:4px}.sheet-control svg{width:21px;height:21px}.bound-controls>div{max-width:40%;gap:5px}.current-chapter-title{font-size:12px;overflow:hidden;text-overflow:ellipsis;white-space:nowrap;max-width:100%}.bound-controls #folio-position{font-size:10px}.sheet-control span{max-width:70px;line-height:1.1;text-align:center}.bound-outline{font-size:13px;padding:10px 9px 0}.bound-outline summary svg{width:12px}.bound-outline nav{max-width:300px}.folio-chapter-end{padding-top:20px}.folio-chapter-end p{font-size:23px}.folio-chapter-end a{font-size:25px}.folio-closing p{font-size:33px}.folio-closing a{font-size:16px}.continuous-reading .bound-volume{padding:25px 22px}.bound-reading .book-sidebar{width:300px;padding:25px}.bound-reading .sidebar-group a{font-size:20px}} +.folio-page{background-image:linear-gradient(#fff7e8b8,#fff7e8b8),url('/art/paper.webp')} +.bound-volume:before,.bound-volume:after{background:transparent} +.folio-content h1 img{background:#86633f;border:1px solid #bca16f;border-radius:9px;padding:7px;filter:none;box-shadow:inset 0 1px 1px #fff4cf5c,0 3px 5px #44331b26} +.code-toolbar>div{display:flex;align-items:center;gap:18px}.code-toolbar .rust-playground{font:11px var(--mono);color:#d4b781!important;text-transform:none;text-decoration:none}.code-toolbar .rust-playground:hover{text-decoration:underline} +.no-script-page{max-width:1150px;margin:40px auto;padding:30px;font-size:21px;line-height:1.8}.no-script-page>nav{font:20px var(--serif);padding-bottom:25px;border-bottom:1px solid var(--line)} +.folio-group>h1:first-child,.folio-group>h2:first-child,.folio-group>h3:first-child{margin-top:0} +.folio-group>p:first-child{margin-top:0} +@media(prefers-reduced-motion:reduce){.stf__parent,.stf__item{scroll-behavior:auto!important}} diff --git a/web/contents.css b/web/contents.css new file mode 100644 index 0000000..8776727 --- /dev/null +++ b/web/contents.css @@ -0,0 +1,18 @@ +.contents-main,.part-main{width:90%;margin:65px auto 85px;color:var(--ink)}.contents-heading{max-width:1100px;margin-bottom:55px}.contents-heading h1{font:500 92px/.98 var(--serif);margin:25px 0}.contents-heading h1 em{color:var(--copper)}.contents-heading>p{font:25px/1.5 var(--serif);max-width:730px;color:var(--text)}.contents-introduction{font:22px var(--serif);display:flex;align-items:center;gap:20px;color:var(--copper);width:fit-content;margin-top:24px}.contents-spread{display:grid;grid-template-columns:repeat(2,minmax(0,1fr));column-gap:7%;row-gap:65px;padding:55px 5%;background:linear-gradient(#fff9ea66,#fff9ea66),url('/art/paper.webp') center/cover;border:1px solid #c7b487;box-shadow:6px 7px 0 -1px #eee2c4,6px 7px 0 #b9a77e}.contents-part>header{display:flex;gap:23px;align-items:baseline;padding-bottom:17px}.contents-roman{font:48px var(--serif);color:var(--copper);min-width:35px}.contents-part h2{font-size:38px;line-height:1.06;margin:0 0 14px}.contents-part h2 a:hover{color:var(--copper)}.contents-part header p{font:21px/1.45 var(--serif);color:#7a6d52;margin:0 0 10px}.contents-part ol{margin:0;padding:0;list-style:none}.contents-part li a{display:flex;gap:18px;align-items:baseline;border-top:1px solid #baa57c55;padding:16px 0;color:#594f37}.contents-part li a:hover{color:var(--copper);padding-left:7px}.contents-part li a>span{font:12px var(--mono);color:#9f8559}.contents-part li strong{font:500 25px/1.25 var(--serif)}.contents-part li small{font:10px var(--mono);color:#948365;margin-left:auto;white-space:nowrap}.contents-part li svg{width:17px;height:17px;align-self:center}.part-breadcrumb{display:flex;gap:12px;align-items:center;font:17px var(--serif);color:var(--muted);margin-bottom:30px}.part-breadcrumb svg{height:14px;width:14px}.part-opening{display:grid;grid-template-columns:1fr 1fr;gap:7%;padding:45px 5% 55px;position:relative;background:linear-gradient(#fff9ea66,#fff9ea66),url('/art/paper.webp') center/cover;border:1px solid #c7b487;box-shadow:8px 8px 0 -1px #eee2c4,8px 8px 0 #b9a77e}.part-opening:after{content:'';position:absolute;left:50%;top:0;bottom:0;width:35px;transform:translateX(-50%);background:linear-gradient(90deg,transparent,#8b764324,transparent);pointer-events:none}.part-frontispiece{position:relative;display:flex;flex-direction:column;align-items:flex-start}.part-front-number{position:absolute;right:0;top:0;font:85px var(--serif);color:#baa16c48}.part-frontispiece h1{font:500 76px/1 var(--serif);margin:25px 0;max-width:620px}.part-frontispiece>p{font:25px/1.45 var(--serif);max-width:550px;color:#786b4d;margin:0}.part-frontispiece img{width:100%;height:330px;object-fit:contain;mix-blend-mode:multiply}.part-frontispiece .button{font-size:23px;margin-top:auto}.part-chapters>.section-label{padding-bottom:25px}.part-chapter{display:flex;gap:20px;align-items:baseline;border-top:1px solid #baa57c55;padding:23px 0}.part-chapter>span{font:13px var(--mono);color:#9c8151;min-width:24px}.part-chapter h2{font:500 34px/1.15 var(--serif);margin:0 0 8px;color:#49462f}.part-chapter p{font:12px var(--mono);color:#9b8966;margin:0}.part-chapter>svg{width:22px;margin-left:auto;align-self:center;color:var(--copper)}.part-chapter:hover{transform:translateX(5px)}.part-chapter:hover h2{color:var(--copper)}.part-pagination{display:flex;justify-content:space-between;gap:25px;border-top:1px solid #baa57c55;margin-top:15px;padding-top:25px;font:20px var(--serif);color:var(--copper)}.part-pagination a{display:flex;gap:12px;align-items:center}.part-pagination svg{width:22px} +@media(min-width:1800px){.contents-heading h1{font-size:115px}.contents-heading>p{font-size:29px}.contents-part h2{font-size:47px}.contents-part header p{font-size:25px}.contents-part li strong{font-size:30px}.contents-part li a{padding:20px 0}.contents-part li small{font-size:13px}.part-frontispiece h1{font-size:95px}.part-frontispiece>p{font-size:29px}.part-frontispiece img{height:430px}.part-chapter h2{font-size:41px}.part-chapter p{font-size:14px}.part-chapter{padding:28px 0}} +@media(max-width:1100px){.contents-heading h1{font-size:76px}.contents-spread{column-gap:6%;padding:40px 4%}.contents-part h2{font-size:33px}.contents-part header p{font-size:19px}.contents-part li strong{font-size:23px}.contents-part li small{display:none}.part-opening{gap:7%;padding-inline:4%}.part-frontispiece h1{font-size:61px}.part-frontispiece>p{font-size:22px}.part-chapter h2{font-size:29px}.part-frontispiece img{height:290px}} +@media(max-width:760px){.contents-main,.part-main{width:calc(100% - 40px);margin:35px auto 55px}.contents-heading h1{font-size:53px}.contents-heading>p{font-size:23px}.contents-introduction{font-size:21px}.contents-spread{display:block;padding:28px 20px}.contents-part{margin-bottom:40px}.contents-part:last-child{margin-bottom:0}.contents-part>header{gap:15px}.contents-roman{font-size:39px;min-width:25px}.contents-part h2{font-size:33px}.contents-part header p{font-size:20px}.contents-part li a{gap:13px;padding:15px 0}.contents-part li strong{font-size:24px}.contents-part li a>span{font-size:10px}.contents-part li svg{width:15px;flex-shrink:0;margin-left:auto}.part-breadcrumb{font-size:17px}.part-opening{display:block;padding:30px 23px}.part-opening:after{display:none}.part-frontispiece h1{font-size:55px;margin-top:24px}.part-frontispiece>p{font-size:23px}.part-frontispiece img{height:260px}.part-frontispiece .button{font-size:21px;margin:5px 0 38px}.part-front-number{font-size:75px}.part-chapter h2{font-size:29px}.part-chapter p{font-size:11px}.part-chapter{gap:13px;padding:20px 0}.part-chapter>span{font-size:11px}.part-chapter>svg{width:18px}.part-chapters>.section-label{line-height:1.5}.part-pagination{font-size:18px}.part-pagination svg{width:18px}} +/* A full contents destination; chapter entries go directly to either reader. */ +.contents-toolbar{width:90%;margin:0 auto;min-height:110px;display:flex;align-items:center;justify-content:space-between;gap:24px;border-bottom:1px solid var(--line)} +.contents-toolbar>div{display:flex;align-items:center;gap:20px}.contents-view .contents-toolbar .crafted-brand{--mark-size:62px;--brand-title:38px;--brand-caption:20px;--title-track:6px;--caption-track:1.2px;gap:14px} +.contents-view .contents-heading h1{font-size:clamp(38px,5vw,64px);line-height:1.2;margin:0 0 24px}.contents-view .contents-heading{margin-bottom:36px} +.contents-view .contents-part h2{font-size:32px;line-height:1.4;overflow-wrap:anywhere}.contents-view .contents-roman{font-size:32px;line-height:1.4;min-width:38px} +.contents-view .contents-part li a{min-height:52px;align-items:center;gap:16px}.contents-view .contents-part li strong{font-size:24px;line-height:1.5;overflow-wrap:anywhere;min-width:0}.contents-view .contents-part li a>span{font-size:15px;min-width:22px}.contents-view .contents-part li svg{margin-inline-start:auto;flex-shrink:0} +.contents-night{--paper:#18251f;--ink:#e1e4d6;--text:#c9cfbf;--muted:#b7bda9;--copper:#c9ae75;--line:#59634f} +.contents-night .contents-spread{background:#202d25;border-color:var(--line);box-shadow:none}.contents-night .contents-part li a{color:var(--ink);border-color:var(--line)}.contents-night .contents-part li a>span{color:var(--copper)} +.contents-night .contents-toolbar .crafted-brand .brand-letters{color:var(--ink)} +body.contents-night .contents-toolbar .brand-seal-day{display:none} +body.contents-night .contents-toolbar .brand-seal-night{display:block;opacity:1;filter:none} +.contents-real .contents-spread{background:var(--paper-light);box-shadow:none}.contents-real.contents-night{--paper:#1e1e1e;--paper-light:#252525;--ink:#e5e5e5;--text:#ccc;--copper:#cfb68b;--line:#565656} +@media(max-width:900px){.contents-view .contents-spread{display:block}.contents-view .contents-part{margin-bottom:36px}.contents-view .contents-part:last-child{margin-bottom:0}} +@media(max-width:480px){.contents-toolbar{width:calc(100% - 36px);min-height:92px;gap:12px}.contents-toolbar .crafted-brand{flex-shrink:0}body.contents-view .contents-toolbar .brand-letters{display:none}.contents-toolbar>div{gap:12px;min-width:0}.contents-toolbar .language-picker select{max-width:130px}.contents-view .contents-part>header{gap:12px}.contents-view .contents-part h2,.contents-view .contents-roman{font-size:26px}.contents-view .contents-part li strong{font-size:22px}.contents-view .contents-part li a{gap:10px}.contents-view .contents-roman{min-width:30px}} diff --git a/web/docs/merge-acceptance.md b/web/docs/merge-acceptance.md new file mode 100644 index 0000000..79c7a7d --- /dev/null +++ b/web/docs/merge-acceptance.md @@ -0,0 +1,71 @@ +# PR #2 measurable merge acceptance + +Review: [Tomislav, comment 6420843360](https://github.com/alux-network/alux-programming/pull/2#issuecomment-6420843360). Local evidence: 2026-10-27, Windows, Node 24.19.0, pnpm 11.25.0, Playwright 1.64.1. Baseline: `ba2274db4520be6d34d039ab0e49d04a8005b02d`. No further architecture rewrite, redesign, merge or production deployment is authorized. + +## Decisions and fixes + +- Owner selected **on-demand pagination**: measure only the viewed chapter and decode only its images. Show labelled chapter progress until exact-layout counts for every chapter have already been learned from actual visits. Never guess totals or measure unseen chapters, including background work, to obtain them. Language, dimensions, text size and font invalidation constrain reuse. +- Abort obsolete layout/navigation work; preserve canonical sections through font/size/orientation and scroll/book changes. History resolves unprefixed English correctly. +- Pinned page-flip 2.0.7 retained render frames and resize listeners after destroy; delayed initialization could survive immediate destruction. The checked-in pnpm patch fixes source and distributed bundles, retains its license, and needs no manual node_modules edits. +- World transitions commit synchronously. Awaiting rAF inside a View Transition update callback deadlocked mobile Chromium until timeout. Restore after the transition and check cancellation. +- Windows supports probes now terminate naturally: forced process.exit aborted Node handles and let mdBook skip localization. A subprocess regression and translated-source-title guard prevent localized UI from silently accompanying English chapters. +- `sourceHash` identifies normalized-line-ending SHA-256 of canonical English Markdown. Missing/mismatched hashes warn without blocking, changing prose or automatically acknowledging translations. All 280 initial hashes identify the migration baseline, not a new linguistic review. Git comparison confirmed metadata-only changes. + +## Local acceptance ledger + +These are local results. CI and physical devices are separate. Reproducible logs/JSON/screenshots: `output/merge-acceptance/` and `output/reader-regression/`. + +| Criterion | Status | Evidence | +| --- | --- | --- | +| Current-chapter-only pagination | PASS | Runtime User Timing records measured canonical IDs. Four-profile checks cover initial and subsequent routes; only selected language data requested. | +| Content/boundaries after size, orientation, language and mode changes | PASS | Exact normalized text comparisons, canonical section continuity, existing 99 language/viewport/route cases. | +| Lifecycle resource cleanup | PASS | Five destroyed PageFlip instances: baseline 5 active frames/5 resize listeners; patched 0 frames/0 listeners/0 hosts, no exceptions. Final four warmed round trips after GC each show 3 documents, 5602 nodes, 75 JS listeners; global counts stable. | +| Page-turn completion/cancellation | PASS | Normal-motion navigation, back interruption, forward restoration; no animation/measurement hosts left. Clipboard completion guards unmount. | +| Eleven-language structure and protected content | PASS | 11 native editions × 28 chapters; exact code/math/link/image/media checks and mutation tests retained; canonical hierarchy/anchors; 36 Node tests. Existing Chromium regression: 318 assertions, 99 route/viewport/language cases. | +| Missing translation English fallback | PASS | Build-level source-selection fixtures. Not a simulated missing network response. | +| English edit freshness warning | PASS | Matching hash silent, English edit warns, translation bytes unchanged, CRLF/LF equivalent. No unexpected baseline warnings in actual build. | +| Strict types and lint | PASS | pnpm typecheck; pnpm lint uses TypeScript unused/unreachable/fallthrough checks, not an ESLint claim. | +| Fresh frozen install/build/test | PASS | Isolated local Git checkout of signed tracked source, initially without dependencies/generated reader data. No manual generated files copied in. | +| Repeated build determinism | PASS | Sorted SHA-256 inventory of every dist file, including scripts/styles/fonts/media; no timestamp exclusions. | +| Internal routes/anchors/resources | PASS | 737 HTML pages, 11594 links, 5522 fragments, 3784 resource references, zero missing targets; browser captures internal failures. | +| Original mdBook publishing | NOT TESTED locally | Native web HTML/JSON passes with mdBook0.4.52/admonish1.20.0/KaTeX0.9.4. Local linkcheck absent. Unchanged publishing CI installs linkcheck0.7.7 and remains the full check. | +| Frontend CI | NOT TESTED in local snapshot | Separate reader.yml adds frozen install/lint/types/build/tests, repeat hashes, links and four engine/profile configurations on pinned Ubuntu24.04 with a 30-minute bound. The initial moving ubuntu-latest runner used Ubuntu26.04 and stalled downloading browser system packages; build/repeatability checks had passed. Live replacement CI result is reported in PR. Original deploy workflow unchanged. | +| Performance vs pinned baseline | PASS | Same Chrome/1440×960/reduced motion, five new contexts each: median ready 1445ms → 405ms; requests27 → 16; bytes1487727 → 944044. Local observation, not production SLA. | + +## Browser/device scope + +| Environment | Status | Scope | +| --- | --- | --- | +| Desktop Chromium156.0.8078.47 | PASS | Magic/Real, navigation/history, language, bookmark/search, code/math, resize, lifecycle and native audio clock/state. | +| Desktop Firefox157.0 | PASS | Same acceptance scenarios. | +| Pixel7 profile, Chromium156.0.8078.47 | PASS — simulation | Touch/mobile viewport/orientation. Desktop engine with profile, not Android hardware. | +| iPhone13 profile, WebKit27.2 | PASS — simulation | Playwright WebKit, not actual iOS Safari. | +| Physical Android Chrome | NOT TESTED | Owner has Android hardware; no phone connected to test environment. | +| Physical iOS Safari | NOT TESTED | Owner has **no iPhone or iPad** and requested simulation. Hardware merge gate unproven. | + +Native media-clock advancement and pause on Real entry/leaving readers are automated checks, not audible hardware proof. Third-party embedded playback is outside the internal-resource audit. An earlier intermittent WebKit `writeEmbed` error was not reproducible with a stack trace; investigation did find live iframe sources cloned into animation snapshots. Both snapshot paths now reuse the existing safe-copy helper, so copies cannot start duplicate players. The final four-profile run, including audio, has no uncaught exceptions or failed internal requests. This does not prove the earlier provider-looking exception came from that defect or guarantee third-party uptime; retain stack capture if it recurs. + +## Reproduce + +Pinned mdBook tools on PATH; from web/: + +```sh +pnpm install --frozen-lockfile +pnpm lint +pnpm typecheck +pnpm build +pnpm test +pnpm test:generated +# Save generated-inventory.json, build again, rerun test:generated, +# and compare the complete inventories byte-for-byte. +pnpm exec playwright install chromium firefox webkit +pnpm test:browser +pnpm test:acceptance +node scripts/measure-startup.ts /path/to/checked-out/web startup.json +``` + +Windows may use PLAYWRIGHT_CHROMIUM_EXECUTABLE for Chrome and PLAYWRIGHT_BROWSERS_PATH for downloaded engines. Temporary ports:4175/4176; benchmark4177. Commands do not publish or merge. + +Three independent read-only Frank/Tomislav/Yilu lens reviews are not approvals by those maintainers. Findings fixed: clipboard completion after unmount, aborted restoration, whole-dist hashes, explicit outer-host assertion and pagination observations across routes. No blocking code-review finding remains. The selected diagnostic chapters use normal .md→.html paths; expanding the fixture to index.md must use its introduction.html alias. + +The PR remains for maintainer review. Local/emulated success does not convert an untested physical-device criterion into PASS. diff --git a/web/docs/source-localization-migration.md b/web/docs/source-localization-migration.md new file mode 100644 index 0000000..c19719a --- /dev/null +++ b/web/docs/source-localization-migration.md @@ -0,0 +1,43 @@ +# Source localization and reader state migration + +Review source: [Tomislav's PR #2 comment, 2026-10-26](https://github.com/alux-network/alux-programming/pull/2#issuecomment-6415490467). + +## Implementation boundaries + +| Review point | Implementation | +| --- | --- | +| Source translations and one canonical structure | 280 adjacent Markdown files: 28 chapters in each of ten translated editions; English sources and SUMMARY are unchanged. Optional source metadata supplies localized navigation/part labels. | +| Native compiler and fallback | A web-only mdBook preprocessor selects translations before includes, admonitions and KaTeX. Missing files retain English. Existing native JSON and HTML renderers remain authoritative. | +| Shared localized data | Build-time `content/.json` models serve both readers and static routes. Browser requests are coalesced/cached per selected edition; failures can retry. | +| Remove old localization | Prose dictionaries, manifest/alignment code and runtime DOM translation are retired. Four public legacy anchors remain a small explicit compatibility map. | +| Explicit interface messages | Eleven small UI dictionaries, typed static keys and typed variable-message keys replace text matching. | +| Declarative state | Solid owns navigation, language, dialogs, bookmarks and preferences. Pagination/PageFlip and native audio remain scoped adapters with disposal. The source-generated chapter HTML stays opaque. | +| Publishing | Original `book.toml` and GitHub Pages workflow are unchanged. No merge or production deployment is part of this work. | + +## Preservation evidence + +The migration captured all eleven previous reader datasets before converting translated HTML to Markdown. Every translated chapter was rebuilt through mdBook and compared against its prior edition: exact fenced and inline code, TeX annotations, links, image references, iframe sources/titles, normalized visible text, displayed titles and canonical heading IDs. All 280 chapter bodies match those protected facts. + +One existing metadata defect was exposed: the Japanese `denotational-design/design.html` heading list contained `優れた抽象化とは#何か`, while its visible heading already read `優れた抽象化とは何か`. Native rendering now derives the latter consistently. The approved visible prose and canonical `what-counts-as-a-good-abstraction` ID are preserved; the discrepancy is recorded rather than inserted into the new source. + +The previous token-matching unit tests described a mechanism intentionally removed by this review. Their technical-preservation obligations remain in `book-integration.test.ts` and `check-locales.ts`, now checked against all generated localized models. `source-localization.test.ts` covers source selection, missing-file fallback, metadata/path rejection and editing one edition without affecting another. A controlled mutation that made translation selection return the canonical path was rejected by these tests, then restored byte-for-byte. + +## Validation status + +Strict TypeScript, the 32-test Node suite and the full web build pass. The reproducible `pnpm test:browser` run passed 318 assertions, including 99 language/viewport/route combinations (eleven languages × three widths × both readers and contents), plus navigation, mode switching, dialogs, search, bookmarks, canonical position, clipboard and music-volume controls. The run found no browser exceptions, page overflow or toolbar controls outside the viewport. + +With image/font requests deliberately delayed by 200ms, the 320/768/1440px startup probes recorded zero painted empty-book frames. First readable content appeared at 853/745/749ms; final readiness was 2079/1891/1890ms in this local headless Chrome run. These are local observations, not a production or physical-device performance claim. + +The untouched original publishing build was also attempted; its local full run is unavailable because `mdbook-linkcheck` is not installed here. The web build exercises native mdBook HTML and JSON with pinned admonish/KaTeX. The existing GitHub Pages workflow still installs pinned linkcheck and remains unchanged. Physical-device audio, production deployment and platform share caches are outside this local regression. + +Three independent read-only code reviews used the Frank, Tomislav and Yilu review lenses; these are not approvals by those maintainers. The source-contract, UI-state and behavior/preservation scopes were reviewed separately, with the migrated prose covered by the baseline comparisons rather than a claimed manual read of all 280 files. + +| Finding | Disposition and verification | +| --- | --- | +| iframe titles absent from the protected media facts | **Fixed in `aca4f04`**. Media tuples now cover titles and URLs; the reviewer confirmed the fix and mutation test. | +| Responsive images and video/audio/source/poster references missing from the guard | **Fixed in `aca4f04`**. A dedicated mutation fixture exercises these attributes; the behavior reviewer confirmed the fix. | +| Language state duplicated between i18n globals and the Solid app | **Fixed in `aca4f04`**. One Solid edition signal owns locale/book/messages; all helpers and the app derive from it. Targeted review found no remaining issue. | +| World entry resets audio to Magic on / Real off | **Kept**. This is the established product behavior; manual play/pause is retained across chapters within the same world. Changing world-entry defaults would alter the approved behavior. | +| Separate iframe/image `src` mutation cases absent | **Fixed** in the test follow-up alongside this record; both source changes now join the existing attribute mutation fixture. | + +All blocking findings are closed. The PR remains for maintainer review; no merge or production deployment is authorized. diff --git a/web/gateway.css b/web/gateway.css new file mode 100644 index 0000000..da94087 --- /dev/null +++ b/web/gateway.css @@ -0,0 +1,86 @@ +/* The chooser has its own atmosphere; reader day/night surfaces stay independent. */ +body.gateway-view{background:#101a17;color:#ede6d4} +.world-gateway{ + background:#101a17; + min-height:100svh; + padding:100px 0 54px; +} +.world-gateway:before{ + background:linear-gradient(180deg,#09141112 30%,#0b15172e 74%,#0b1517b3),url('/art/forest-gateway.webp') center/cover no-repeat; + opacity:1; +} +.world-gateway:after{ + content:'';position:absolute;inset:0;z-index:-1;pointer-events:none; + background:radial-gradient(ellipse at 16% 58%,#111c17a8,transparent 34%),radial-gradient(ellipse at 84% 58%,#0d1a23a8,transparent 34%); +} +.gateway-composition{ + --wizard-size:min(50svh,720px,48vw); + width:min(1760px,96vw); + max-width:none; + grid-template-columns:minmax(0,1fr) var(--wizard-size) minmax(0,1fr); +} +.gateway-wizard{mask-image:none;isolation:isolate} +.gateway-wizard:before{content:'';position:absolute;z-index:-1;left:16%;bottom:-1%;width:68%;height:7%;background:radial-gradient(ellipse,#020707b3,transparent 70%);filter:blur(5px);pointer-events:none} +.world-choice{ + max-width:370px;gap:22px;padding:24px 10px; + color:#efd6a2;text-shadow:0 2px 16px #050d0bd9; +} +.choice-real{color:#c8e1ee} +.world-choice strong{ + display:grid;align-items:center;min-height:2.7em; + font-size:clamp(28px,2.6vw,46px);letter-spacing:.045em;line-height:1.35; +} +html[lang=en] .world-choice strong{font-size:clamp(30px,3vw,50px);letter-spacing:.01em;min-height:1.35em;white-space:nowrap} +html[lang|=zh] .world-choice strong,html[lang=ja] .world-choice strong,html[lang=ko] .world-choice strong{min-height:1.35em} +.world-choice .choice-symbol{color:#e5c58b;display:grid;place-items:center;height:48px} +.world-choice .choice-symbol svg{width:44px;height:44px;stroke-width:1.5} +.choice-real .choice-symbol{color:#a5c5d9;font-size:29px} +.world-choice .choice-enter,html[lang=en] .world-choice .choice-enter{color:#f0dbb1;font-size:26px;font-weight:600;letter-spacing:.025em;padding-top:23px;line-height:1.5} +.choice-real .choice-enter{color:#b5d2e0} +.choice-enter:before{opacity:.48} +.world-choice:before{width:300px;height:300px;background:radial-gradient(#d9af4826,transparent 68%)} +.choice-real:before{background:radial-gradient(#7bb8d62b,transparent 68%)} +.world-gateway>.language-picker{ + top:28px;right:3.5vw;min-height:66px;min-width:248px; + padding:6px 18px;gap:13px;font-size:23px;color:#f0e7d4; + border:1px solid #c9b78d91;border-radius:6px; + background:#14221ee8;box-shadow:0 5px 24px #0003; + backdrop-filter:blur(14px);color-scheme:dark; + transition:background .2s,border-color .2s; +} +.world-gateway>.language-picker:hover{background:#23352ef5;border-color:#e2c68c} +.world-gateway>.language-picker:focus-within{outline:2px solid #e2c68c;outline-offset:4px} +.world-gateway>.language-picker svg{width:27px;height:27px;flex-shrink:0;color:#d8c59e} +.world-gateway>.language-picker select{max-width:230px;min-width:170px;min-height:52px;padding:10px 8px;border:0;outline:none} +.world-gateway>.language-picker:after{content:'';position:absolute;inset-inline-end:22px;top:calc(50% - 7px);width:12px;height:12px;border-right:2px solid currentColor;border-bottom:2px solid currentColor;transform:rotate(45deg);pointer-events:none} +.world-gateway>.language-picker select{appearance:none;padding-inline-end:37px} +.world-gateway>.language-picker option{background:#192923;color:#f0e7d4} +@media(max-width:900px){ + .world-gateway{padding:96px 0 30px} + .gateway-composition{ + --wizard-size:min(86vw,39svh,430px); + width:100%;padding:0 20px;gap:0 16px; + grid-template-columns:minmax(0,1fr) minmax(0,1fr); + } + .gateway-wizard{grid-column:1/-1;grid-row:1} + .world-choice{grid-row:2;transform:none;gap:13px;padding:8px 0 16px;max-width:320px} + .world-choice:hover,.world-choice:active{transform:none} + .world-choice strong,html[lang=en] .world-choice strong{font-size:29px;white-space:normal;letter-spacing:.025em;min-height:2.7em} + .world-choice .choice-enter,html[lang=en] .world-choice .choice-enter{font-size:21px;letter-spacing:.015em;padding-top:18px} + .world-choice .choice-symbol{height:40px}.world-choice .choice-symbol svg{width:36px;height:36px} + .world-gateway>.language-picker{top:20px;right:20px;min-width:225px;min-height:58px;font-size:19px;padding:4px 14px;gap:10px} + .world-gateway>.language-picker svg{width:24px;height:24px} + .world-gateway>.language-picker select{min-width:155px;min-height:48px;max-width:200px;padding:8px 34px 8px 5px} +} +@media(max-width:380px){ + .gateway-composition{padding-inline:14px;column-gap:12px} + .world-choice strong,html[lang=en] .world-choice strong{font-size:26px} + .world-choice .choice-enter,html[lang=en] .world-choice .choice-enter{font-size:20px} + .choice-enter-label{max-width:calc(100% - 26px)} + .choice-enter-arrow{inset-inline-start:calc(100% + 8px)} +} +@media(prefers-reduced-motion:reduce){.world-gateway>.language-picker{transition:none}} +.gateway-welcome{position:absolute;top:34px;left:32px;z-index:4;display:flex;align-items:center;gap:10px;max-width:calc(100% - 380px);min-height:52px;padding:10px 17px;color:#e5dac1;background:#14221dc9;border:1px solid #b6a17a77;border-radius:5px;font:500 22px/1.4 var(--serif);text-align:start;backdrop-filter:blur(8px)} +.gateway-welcome:hover{background:#24382de0;color:#f2e6c9} +.gateway-welcome:focus-visible{outline:2px solid #d1b77f;outline-offset:4px} +@media(max-width:900px){.gateway-welcome{top:auto;bottom:20px;left:50%;transform:translateX(-50%);max-width:calc(100% - 28px);min-height:48px;font-size:20px;white-space:normal;width:max-content}.world-gateway{padding-bottom:100px}} diff --git a/web/immersive.css b/web/immersive.css new file mode 100644 index 0000000..cdfc3f4 --- /dev/null +++ b/web/immersive.css @@ -0,0 +1,19 @@ +/* Immersive scale: use the actual reading window instead of a narrow landing-page frame. */ +.site-header{position:sticky;top:16px;z-index:40;width:calc(100% - 80px);max-width:none;height:116px;margin:16px auto 0;padding:0 30px;background:#f8f3e8ed;border:1px solid #d9c8a847;border-radius:14px;box-shadow:0 8px 25px #5b49320a;backdrop-filter:blur(16px)} +.brand .brand-emblem{width:64px;height:68px;position:relative;display:flex;align-items:center;justify-content:center;background:linear-gradient(140deg,#bf9a66,#8e633d 43%,#64472d);border:1px solid #aa8556;border-radius:12px;box-shadow:inset 0 1px 2px #fff5dbaa,inset 0 0 0 5px #fff9d00c,0 5px 0 #57412c15,0 7px 14px #4d34231a;flex-shrink:0;overflow:hidden} +.brand .brand-emblem:before{content:'';position:absolute;inset:6px;border:1px solid #e3c89755;border-radius:7px;pointer-events:none} +.brand .brand-emblem img{width:45px;height:45px;object-fit:contain;filter:drop-shadow(1px 2px 1px #352d23aa);position:relative} +.brand>span{font-size:34px;letter-spacing:7px}.brand small{font-size:12px;letter-spacing:2px;margin-top:7px} +.site-header nav{font-size:24px;gap:42px}.site-header nav svg{width:18px;height:18px}.search-button{font-size:15px}.search-button svg{width:22px;height:22px}.search-button kbd{font-size:11px} +.hero{max-width:none;width:100%;min-height:calc(100svh - 155px);padding:70px 0 60px;overflow:hidden}.hero-copy{padding-left:5%;width:47%}.hero h1{font-size:136px}.hero-copy>p{font-size:30px;line-height:1.35}.hero-copy>p.hero-description{font-size:17px;line-height:1.8;max-width:420px;margin-block:24px 35px}.hero .button{font-size:24px;padding:20px 30px;gap:34px}.explore-world{font-size:17px;margin-top:22px}.resume-link{font-size:14px;margin-top:20px}.hero-note>span:last-child{font-size:11px;letter-spacing:1.5px}.hero-note{margin-top:32px}.hero-world{width:79%;right:-2%;height:calc(100% - 55px);top:35px}.world-caption{font-size:10px;letter-spacing:1px;right:7%;bottom:6%;left:35%}.world-label{font-size:13px}.label-top{top:8%} +.chapters-section,.playground,.site-footer{width:90%;max-width:none}.chapters-section{padding-top:55px}.section-heading h2{font-size:56px}.section-heading>p{font-size:23px}.section-label{font-size:12px;letter-spacing:1.5px}.chapter-worlds{margin:40px 0 45px}.chapter-art{height:230px}.chapter-world h3{font-size:36px}.chapter-world p{font-size:16px;line-height:1.75;max-width:330px}.chapter-count{font-size:11px}.chapter-link{font-size:21px}.part-numeral{font-size:45px}.full-contents summary{font-size:23px;padding:27px 0}.playground{gap:90px;margin-block:110px}.playground-copy h2{font-size:64px}.playground-copy>p{font-size:26px}.playground-copy>a{font-size:15px}.workbench-head>span{font-size:12px}.workbench-hint{font-size:16px}.workbench .text-button{font-size:14px}.toy-brick{width:145px;height:105px}.toy-brick strong{font-size:35px}.toy-brick small{font-size:12px}.drop-zone>span{font-size:13px;max-width:170px}.composition-line label,.output-value>span{font-size:11px}.experiment-code pre{font-size:13px}.experiment-code>span{font-size:10px}.site-footer>div:nth-child(2){font-size:14px}.site-footer>span{font-size:12px}.site-footer p{font-size:19px}.site-footer .brand-emblem{width:45px;height:48px}.site-footer .brand-emblem img{width:32px;height:32px}.site-footer .brand>span{font-size:26px}.site-footer .brand small{font-size:9px} +@media(min-width:1800px){.site-header{height:128px}.hero h1{font-size:168px}.hero-copy>p{font-size:37px}.hero-copy>p.hero-description{font-size:20px;max-width:500px}.hero .button{font-size:28px;padding:23px 38px}.hero-world{width:83%;right:-3%}.hero-copy{padding-left:5%}.hero-note{margin-top:45px}.explore-world{font-size:20px}.section-heading h2{font-size:66px}.chapter-art{height:290px}.chapter-world h3{font-size:43px}.chapter-world p{font-size:19px}.part-numeral{font-size:55px}.chapter-link{font-size:24px}.chapter-count{font-size:13px}.section-heading>p{font-size:27px;max-width:450px}.full-contents summary{font-size:26px}.site-header nav{font-size:27px}} +@media(max-width:1200px){.site-header{width:calc(100% - 44px);padding:0 22px;height:100px;top:10px;margin-top:10px}.site-header nav{font-size:21px;gap:25px}.brand .brand-emblem{width:55px;height:59px}.brand .brand-emblem img{width:39px;height:39px}.brand>span{font-size:28px;letter-spacing:5px}.brand small{font-size:10px}.hero{min-height:760px}.hero h1{font-size:112px}.hero-copy>p{font-size:26px}.hero-copy>p.hero-description{font-size:15px;max-width:330px}.hero-world{width:79%;right:-3%}.hero .button{font-size:22px;padding:18px 25px}.world-caption{font-size:8px}.chapter-art{height:205px}.chapter-world h3{font-size:31px}.chapter-world p{font-size:14px}.playground{gap:45px}.playground-copy h2{font-size:53px}.playground-copy>p{font-size:23px}.section-heading h2{font-size:47px}.section-heading>p{font-size:21px}} +@media(max-width:760px){.site-header{width:calc(100% - 24px);height:85px;padding:0 14px;top:8px;margin-top:8px;border-radius:10px;gap:12px}.brand .brand-emblem{width:43px;height:47px;border-radius:8px}.brand .brand-emblem:before{inset:4px;border-radius:5px}.brand .brand-emblem img{width:31px;height:31px}.brand{gap:9px}.brand>span{font-size:24px;letter-spacing:3px}.brand small{font-size:7px;letter-spacing:1.5px}.site-header nav{font-size:17px;gap:18px}.site-header nav a:nth-child(3){display:none}.search-button{padding:6px}.hero{min-height:0;padding:35px 24px 28px}.hero h1{font-size:74px}.hero-copy{padding-left:0;width:100%}.hero-copy>p{font-size:23px}.hero-copy>p.hero-description{font-size:14px;max-width:335px;margin:18px 0 25px}.hero .button{font-size:21px;padding:16px 24px;min-height:54px}.hero-world{position:relative;inset:auto;width:calc(100% + 48px);height:280px;margin:10px -24px 0}.hero-note{display:none}.explore-world{font-size:16px;margin-top:17px}.resume-link{font-size:12px}.world-caption{left:24px;right:24px;bottom:0;font-size:7px}.chapters-section,.playground,.site-footer{width:calc(100% - 48px)}.section-heading h2{font-size:40px}.section-heading>p{font-size:20px}.section-label{font-size:10px}.chapters-section{padding-top:30px}.chapter-art{height:180px}.chapter-world h3{font-size:29px}.chapter-world p{font-size:13px}.chapter-link{font-size:17px;gap:9px}.chapter-count{font-size:9px}.part-numeral{font-size:37px}.chapter-worlds{margin-block:30px}.full-contents summary{font-size:20px;line-height:1.4;padding:22px 0;gap:15px}.playground{margin-block:55px;gap:24px}.playground-copy h2{font-size:48px}.playground-copy>p{font-size:22px}.playground-copy>a{font-size:13px;line-height:1.5}.workbench-head>span{font-size:9px}.workbench-hint{font-size:13px}.workbench .text-button{font-size:12px}.toy-brick{width:85px;height:80px}.toy-brick strong{font-size:28px}.toy-brick small{font-size:9px}.drop-zone>span{font-size:9px}.composition-line label,.output-value>span{font-size:8px}.experiment-code pre{font-size:9px}.experiment-code>span{font-size:7px}.site-footer>div:nth-child(2){font-size:12px}.site-footer>span{display:none}.site-footer p{font-size:15px}.site-footer .brand-emblem{width:36px;height:40px}.site-footer .brand-emblem img{width:25px;height:25px}.site-footer .brand>span{font-size:20px}.site-footer .brand small{font-size:6px}} +:root[data-transition="open-book"]::view-transition-group(root){perspective:2400px} +:root[data-transition="open-book"]::view-transition-old(root){animation:whole-sheet-turn .9s cubic-bezier(.32,.12,.2,1) both;transform-origin:0 50%;box-shadow:18px 0 45px #3f331f55;z-index:2;backface-visibility:hidden} +:root[data-transition="open-book"]::view-transition-new(root){animation:paper-reveal .9s ease both;z-index:1} +@keyframes whole-sheet-turn{0%{transform:perspective(2400px) rotateY(0);filter:brightness(1)}65%{opacity:1;filter:brightness(.8)}100%{transform:perspective(2400px) rotateY(-100deg);opacity:0;filter:brightness(.6)}} +@keyframes paper-reveal{0%{filter:brightness(.75)}100%{filter:brightness(1)}} +@media(max-width:380px){.site-header nav a:nth-child(2){display:inline-flex}.site-header nav{gap:0}.site-header{gap:10px}.hero h1{font-size:68px}} +@media(min-width:1800px){.atlas-main{width:90%;margin-top:60px}.atlas-heading h1{font-size:95px}.atlas-heading>p{font-size:28px}.atlas-list-link{font-size:21px}.atlas-experience{grid-template-columns:1.6fr 1fr;gap:75px}.atlas-map{height:870px}.atlas-node{width:285px;height:340px}.atlas-node-title{font-size:30px}.atlas-node-number{font-size:49px}.atlas-detail h2{font-size:62px}.atlas-detail>p{font-size:28px}.atlas-chapter-list a{font-size:27px;padding:18px 0}.atlas-chapter-list a>span{font-size:13px}.atlas-detail .button{font-size:25px;padding:22px 28px}.atlas-part{font-size:14px}.atlas-navigation>span{font-size:14px}.atlas-navigation .icon-button{width:50px;height:50px}.atlas-navigation svg{width:28px;height:28px}.atlas-map-note{font-size:13px}.star-a{font-size:48px}.star-b{font-size:30px}.node-3{right:25%}} diff --git a/web/index.html b/web/index.html new file mode 100644 index 0000000..48fc284 --- /dev/null +++ b/web/index.html @@ -0,0 +1,2 @@ + +ALUX Programming
diff --git a/web/locales/ui/ar.json b/web/locales/ui/ar.json new file mode 100644 index 0000000..409a62f --- /dev/null +++ b/web/locales/ui/ar.json @@ -0,0 +1,140 @@ +{ + "A visitor-based structure that allows:": "بنية قائمة على نمط الزائر تتيح:", + "Solutions are possible, but they tend to require either:": "توجد حلول، لكنها تتطلب عادةً أحد الأمرين:", + "Execution state includes:": "تتضمن حالة التنفيذ:", + "The semantic view — choosing what a program means before how it runs": "المنظور الدلالي: اختيار معنى البرنامج قبل كيفية تشغيله", + "Design by meaning in Rust — building software from small capability traits": "التصميم انطلاقًا من المعنى في Rust: بناء البرمجيات من سمات قدرات صغيرة", + "Concepts — the programming machinery": "المفاهيم: آليات البرمجة", + "Insights — connecting concepts back to the semantic view": "رؤى: ربط المفاهيم بالمنظور الدلالي", + "ALUX PROGRAMMING": "برمجة ALUX", + "Main navigation": "التنقل الرئيسي", + "ALUX Programming home": "الصفحة الرئيسية لبرمجة ALUX", + "Scrollable technical content": "محتوى تقني قابل للتمرير", + "The book could not load.": "تعذر تحميل الكتاب.", + "Please refresh the page to try again.": "حدّث الصفحة للمحاولة مجددًا.", + "Try again": "حاول مجددًا", + "This page is uncharted.": "هذه الصفحة غير موجودة.", + "Find your way back to the book.": "عد إلى الفهرس لمتابعة القراءة.", + "This language is unavailable. Please try again.": "تعذر تحميل هذه اللغة. حاول مجددًا.", + "Copy is unavailable. Select the code to copy it.": "تعذر النسخ. حدد الشيفرة لنسخها.", + "THE CHAPTER ATLAS": "خريطة الفصول", + "The chapter atlas": "خريطة الفصول", + "A world of ideas.": "عالم من الأفكار.", + "Choose a world.": "اختر عالمًا.", + "Follow an idea as far as it takes you.": "اتبع الفكرة إلى أبعد ما تقودك إليه.", + "Browse as a list": "عرض كقائمة", + "Interactive chapter map": "خريطة فصول تفاعلية", + "⟦ parts ⟧ → whole": "⟦ الأجزاء ⟧ ← الكل", + "Previous world": "العالم السابق", + "Next world": "العالم التالي", + "Enter this world": "ادخل هذا العالم", + "Start with what a program means. Explore denotations, compositionality, laws, and the relationship between meaning and representation.": "ابدأ بمعنى البرنامج، واستكشف الدلالات والتركيبية والقوانين والعلاقة بين المعنى والتمثيل.", + "Give meaning a concrete vocabulary. Explore capability traits, derived operations, interpreters, evidence, and compiler pipelines in Rust.": "امنح المعنى مفردات ملموسة، واستكشف سمات القدرات والعمليات المشتقة والمفسرات والأدلة ومسارات الترجمة في Rust.", + "Look beneath the surface of a program. Explore the structures and transformations that connect ideas to execution.": "تعمّق في بنية البرنامج، واستكشف التراكيب والتحويلات التي تربط الأفكار بالتنفيذ.", + "Return to familiar ideas with a new perspective. Follow the connections between the semantic view and real programming machinery.": "عُد إلى الأفكار المألوفة بمنظور جديد، وتتبع الصلات بين المنظور الدلالي وآليات البرمجة الفعلية.", + "Reading world": "عالم القراءة", + "Choose a world": "اختر عالمًا", + "Continue the journey": "واصل القراءة", + "Return to the table of contents": "العودة إلى جدول المحتويات", + "First the meaning.": "المعنى أولًا.", + "Then the machinery.": "ثم الآليات.", + "Explore another chapter": "استكشف فصلًا آخر", + "Magic world": "عالم السحر", + "Real world": "العالم الواقعي", + "Click to enter": "انقر للدخول", + "Choose your world": "اختر عالمك", + "Choose world": "اختر العالم", + "Language": "اللغة", + "Programming": "البرمجة", + "PROGRAMMING": "البرمجة", + "ALUX Programming": "برمجة ALUX", + "The book": "قراءة الكتاب", + "Chapters": "الفصول", + "Search": "بحث", + "Search the book": "بحث", + "Table of contents": "جدول المحتويات", + "Contents": "المحتويات", + "Introduction": "مقدمة", + "Welcome": "مرحبًا", + "The Semantic View": "المنظور الدلالي", + "THE SEMANTIC VIEW": "المنظور الدلالي", + "Design by Meaning in Rust": "التصميم انطلاقًا من المعنى في Rust", + "DESIGN BY MEANING IN RUST": "التصميم انطلاقًا من المعنى في Rust", + "Concepts": "المفاهيم", + "CONCEPTS": "المفاهيم", + "Insights": "رؤى", + "INSIGHTS": "رؤى", + "Contributing": "المساهمة", + "CONTRIBUTING": "المساهمة", + "Previous page": "الصفحة السابقة", + "Next page": "الصفحة التالية", + "Previous chapter": "الفصل السابق", + "Next chapter": "الفصل التالي", + "Back to contents": "العودة إلى المحتويات", + "In this chapter": "في هذا الفصل", + "Original source": "المصدر الأصلي", + "Scroll view": "عرض بالتمرير", + "Book view": "عرض الكتاب", + "Continuous reading": "قراءة متصلة", + "Preparing the pages…": "جارٍ إعداد الصفحات…", + "Open book navigation": "فتح فهرس الكتاب", + "Toggle table of contents": "إظهار أو إخفاء الفهرس", + "Close table of contents": "إغلاق الفهرس", + "Decrease text size": "تصغير النص", + "Increase text size": "تكبير النص", + "Toggle night reading": "تبديل القراءة الليلية", + "Bookmark this chapter": "وضع إشارة لهذا الفصل", + "Chapter bookmarked": "تم حفظ إشارة الفصل", + "Bookmark removed": "تمت إزالة الإشارة", + "Change reading theme": "تغيير سمة القراءة", + "Light": "فاتح", + "Rust": "Rust", + "Coal": "فحمي", + "Navy": "كحلي", + "Ayu": "Ayu", + "Copy code": "نسخ الشيفرة", + "Copied": "تم النسخ", + "Code copied": "تم نسخ الشيفرة", + "Select code to copy": "حدد الشيفرة لنسخها", + "Scrollable table": "جدول قابل للتمرير", + "Link to this section": "رابط هذا القسم", + "View source on GitHub": "عرض المصدر على GitHub", + "Skip to content": "انتقل إلى المحتوى", + "Search ideas, code, chapters…": "ابحث عن المفاهيم والشيفرة والفصول…", + "Search ideas, code, chapters": "البحث عن المفاهيم والشيفرة والفصول", + "Close search": "إغلاق البحث", + "Search the complete book": "البحث في الكتاب كاملًا", + "to close": "للإغلاق", + "A keyword opens a new page.": "كلمة مفتاحية تفتح صفحة جديدة.", + "Search every chapter, code example and idea.": "ابحث في جميع الفصول وأمثلة الشيفرة والمفاهيم.", + "YOUR BOOKMARK": "إشارتك المرجعية", + "START EXPLORING": "ابدأ الاستكشاف", + "Continue reading": "متابعة القراءة", + "No pages found.": "لم يتم العثور على صفحات.", + "Try a concept such as “capability”, “Rust” or “meaning”.": "جرّب مفاهيم مثل «القدرة» أو «Rust» أو «المعنى».", + "About the book": "عن الكتاب", + "Read the introduction": "قراءة المقدمة", + "The book of": "كتاب", + "small, powerful ideas.": "الأفكار الصغيرة المؤثرة.", + "The complete table of contents. Follow the chapters in order, or find the idea you came for.": "اتبع الفصول بالترتيب، أو ابحث عن الفكرة التي جئت من أجلها.", + "Begin with the meaning of a program. Explore denotations, compositionality, laws, interpretations, and the role of dependent types.": "ابدأ بمعنى البرنامج، واستكشف الدلالات والتركيبية والقوانين والتفسيرات ودور الأنواع التابعة.", + "Carry meaning-first design into Rust: capability algebras, semantic types, derived operations, interpreters, evidence, and language pipelines.": "طبّق التصميم القائم على المعنى في Rust: جبر القدرات والأنواع الدلالية والعمليات المشتقة والمفسرات والأدلة ومسارات اللغة.", + "Explore execution models and useful machinery: operational semantics, the expression problem, free monads, continuations, and branching.": "استكشف نماذج التنفيذ وآلياته: الدلالات التشغيلية ومشكلة التعبير والمونادات الحرة والاستمراريات والتفرع.", + "Connect the machinery back to meaning. Revisit semantics, the expression problem, referential transparency, and the EVM.": "اربط الآليات بالمعنى، وأعد النظر في الدلالات ومشكلة التعبير والشفافية المرجعية وEVM.", + "Clear ideas. Composable programs.": "أفكار واضحة وبرامج قابلة للتركيب.", + "Source on GitHub": "المصدر على GitHub", + "ALUX Network": "ALUX Network", + "Made of ideas.": "من الأفكار.", + "Built to be explored.": "صُمم للاستكشاف.", + "SMALL BUILDING BLOCKS.": "لبنات صغيرة.", + "WORLDS OF POSSIBILITY.": "عوالم من الإمكانات.", + "My bookmarks": "إشاراتي المرجعية", + "Remove bookmark": "حذف الإشارة المرجعية", + "Close bookmarks": "إغلاق الإشارات المرجعية", + "No bookmarks yet.": "لا توجد إشارات مرجعية بعد.", + "Save a chapter with the bookmark button to continue reading here.": "احفظ فصلًا بزر الإشارة المرجعية في شريط القراءة لتتمكن من متابعة القراءة من هنا.", + "Add bookmark": "إضافة إشارة مرجعية", + "Bookmarked": "تمت الإضافة", + "Hide contents": "إخفاء المحتويات", + "Show contents": "إظهار المحتويات" +} diff --git a/web/locales/ui/de.json b/web/locales/ui/de.json new file mode 100644 index 0000000..1853b20 --- /dev/null +++ b/web/locales/ui/de.json @@ -0,0 +1,140 @@ +{ + "A visitor-based structure that allows:": "Eine auf dem Visitor-Muster basierende Struktur, die Folgendes ermöglicht:", + "Solutions are possible, but they tend to require either:": "Lösungen sind möglich, erfordern jedoch meist eines von zwei Dingen:", + "Execution state includes:": "Der Ausführungszustand umfasst:", + "The semantic view — choosing what a program means before how it runs": "Die semantische Sicht — zuerst festlegen, was ein Programm bedeutet, dann entscheiden, wie es ausgeführt wird", + "Design by meaning in Rust — building software from small capability traits": "Design durch Bedeutung in Rust — Software aus kleinen Capability-Traits aufbauen", + "Concepts — the programming machinery": "Concepts — die Programmiermechanismen", + "Insights — connecting concepts back to the semantic view": "Insights — Konzepte wieder mit der semantischen Sicht verbinden", + "ALUX PROGRAMMING": "ALUX-PROGRAMMIERUNG", + "Main navigation": "Hauptnavigation", + "ALUX Programming home": "Startseite der ALUX-Programmierung", + "Scrollable technical content": "Scrollbarer technischer Inhalt", + "The book could not load.": "Das Buch konnte nicht geladen werden.", + "Please refresh the page to try again.": "Bitte lade die Seite neu und versuche es erneut.", + "Try again": "Erneut versuchen", + "This page is uncharted.": "Diese Seite ist noch unerforscht.", + "Find your way back to the book.": "Finde den Weg zurück zum Buch.", + "This language is unavailable. Please try again.": "Diese Sprache ist nicht verfügbar. Bitte versuche es erneut.", + "Copy is unavailable. Select the code to copy it.": "Kopieren ist nicht verfügbar. Markiere den Code, um ihn zu kopieren.", + "THE CHAPTER ATLAS": "DER KAPITELATLAS", + "The chapter atlas": "Der Kapitelatlas", + "A world of ideas.": "Eine Welt voller Ideen.", + "Choose a world.": "Wähle eine Welt.", + "Follow an idea as far as it takes you.": "Folge einer Idee, wohin sie dich auch führt.", + "Browse as a list": "Als Liste ansehen", + "Interactive chapter map": "Interaktive Kapitelkarte", + "⟦ parts ⟧ → whole": "⟦ Teile ⟧ → Ganzes", + "Previous world": "Vorherige Welt", + "Next world": "Nächste Welt", + "Enter this world": "Diese Welt betreten", + "Start with what a program means. Explore denotations, compositionality, laws, and the relationship between meaning and representation.": "Beginne mit der Bedeutung eines Programms. Entdecke Denotationen, Kompositionalität, Gesetze und den Zusammenhang zwischen Bedeutung und Repräsentation.", + "Give meaning a concrete vocabulary. Explore capability traits, derived operations, interpreters, evidence, and compiler pipelines in Rust.": "Gib der Bedeutung ein konkretes Vokabular. Entdecke Capability-Traits, abgeleitete Operationen, Interpreter, Nachweise und Compiler-Pipelines in Rust.", + "Look beneath the surface of a program. Explore the structures and transformations that connect ideas to execution.": "Blicke unter die Oberfläche eines Programms. Entdecke Strukturen und Transformationen, die Ideen mit ihrer Ausführung verbinden.", + "Return to familiar ideas with a new perspective. Follow the connections between the semantic view and real programming machinery.": "Sieh vertraute Ideen aus einer neuen Perspektive. Entdecke die Verbindungen zwischen der semantischen Sicht und konkreten Programmiermechanismen.", + "Reading world": "Lesewelt", + "Choose a world": "Welt auswählen", + "Continue the journey": "Weiter auf der Reise", + "Return to the table of contents": "Zum Inhaltsverzeichnis zurückkehren", + "First the meaning.": "Zuerst die Bedeutung.", + "Then the machinery.": "Dann die Mechanismen.", + "Explore another chapter": "Ein weiteres Kapitel entdecken", + "Magic world": "Magische Welt", + "Real world": "Reale Welt", + "Click to enter": "Zum Betreten klicken", + "Choose your world": "Wähle deine Welt", + "Choose world": "Welt auswählen", + "Language": "Sprache", + "Programming": "Programmierung", + "PROGRAMMING": "PROGRAMMIERUNG", + "ALUX Programming": "ALUX-Programmierung", + "The book": "Das Buch", + "Chapters": "Kapitel", + "Search": "Suchen", + "Search the book": "Suche", + "Table of contents": "Inhaltsverzeichnis", + "Contents": "Inhalt", + "Introduction": "Einführung", + "Welcome": "Willkommen", + "The Semantic View": "The Semantic View", + "THE SEMANTIC VIEW": "THE SEMANTIC VIEW", + "Design by Meaning in Rust": "Design by Meaning in Rust", + "DESIGN BY MEANING IN RUST": "DESIGN BY MEANING IN RUST", + "Concepts": "Concepts", + "CONCEPTS": "CONCEPTS", + "Insights": "Insights", + "INSIGHTS": "INSIGHTS", + "Contributing": "Mitwirken", + "CONTRIBUTING": "MITWIRKEN", + "Previous page": "Vorherige Seite", + "Next page": "Nächste Seite", + "Previous chapter": "Vorheriges Kapitel", + "Next chapter": "Nächstes Kapitel", + "Back to contents": "Zurück zum Inhaltsverzeichnis", + "In this chapter": "In diesem Kapitel", + "Original source": "Originalquelle", + "Scroll view": "Scrollansicht", + "Book view": "Buchansicht", + "Continuous reading": "Fortlaufendes Lesen", + "Preparing the pages…": "Seiten werden vorbereitet…", + "Open book navigation": "Buchnavigation öffnen", + "Toggle table of contents": "Inhaltsverzeichnis ein- oder ausblenden", + "Close table of contents": "Inhaltsverzeichnis schließen", + "Decrease text size": "Text verkleinern", + "Increase text size": "Text vergrößern", + "Toggle night reading": "Nachtmodus umschalten", + "Bookmark this chapter": "Dieses Kapitel als Lesezeichen speichern", + "Chapter bookmarked": "Kapitel als Lesezeichen gespeichert", + "Bookmark removed": "Lesezeichen entfernt", + "Change reading theme": "Lesethema ändern", + "Light": "Hell", + "Rust": "Rust", + "Coal": "Kohle", + "Navy": "Marineblau", + "Ayu": "Ayu", + "Copy code": "Code kopieren", + "Copied": "Kopiert", + "Code copied": "Code kopiert", + "Select code to copy": "Code zum Kopieren markieren", + "Scrollable table": "Scrollbare Tabelle", + "Link to this section": "Link zu diesem Abschnitt", + "View source on GitHub": "Quelltext auf GitHub ansehen", + "Skip to content": "Zum Inhalt springen", + "Search ideas, code, chapters…": "Ideen, Code und Kapitel durchsuchen…", + "Search ideas, code, chapters": "Ideen, Code und Kapitel durchsuchen", + "Close search": "Suche schließen", + "Search the complete book": "Das gesamte Buch durchsuchen", + "to close": "zum Schließen", + "A keyword opens a new page.": "Ein Stichwort öffnet eine neue Seite.", + "Search every chapter, code example and idea.": "Durchsuche alle Kapitel, Codebeispiele und Ideen.", + "YOUR BOOKMARK": "DEINE LESEZEICHEN", + "START EXPLORING": "MIT DEM ENTDECKEN BEGINNEN", + "Continue reading": "Weiterlesen", + "No pages found.": "Keine Seiten gefunden.", + "Try a concept such as “capability”, “Rust” or “meaning”.": "Probiere Begriffe wie „Capability“, „Rust“ oder „Bedeutung“ aus.", + "About the book": "Über das Buch", + "Read the introduction": "Einführung lesen", + "The book of": "Das Buch der", + "small, powerful ideas.": "kleinen, kraftvollen Ideen.", + "The complete table of contents. Follow the chapters in order, or find the idea you came for.": "Das vollständige Inhaltsverzeichnis. Folge den Kapiteln der Reihe nach oder suche direkt nach der Idee, die dich hergeführt hat.", + "Begin with the meaning of a program. Explore denotations, compositionality, laws, interpretations, and the role of dependent types.": "Beginne mit der Bedeutung eines Programms. Entdecke Denotationen, Kompositionalität, Gesetze, Interpretationen und die Rolle abhängiger Typen.", + "Carry meaning-first design into Rust: capability algebras, semantic types, derived operations, interpreters, evidence, and language pipelines.": "Übertrage bedeutungsorientierten Entwurf auf Rust: Capability-Algebren, semantische Typen, abgeleitete Operationen, Interpreter, Nachweise und Sprach-Pipelines.", + "Explore execution models and useful machinery: operational semantics, the expression problem, free monads, continuations, and branching.": "Entdecke Ausführungsmodelle und nützliche Mechanismen: operationale Semantik, das Expression Problem, freie Monaden, Fortsetzungen und Verzweigungen.", + "Connect the machinery back to meaning. Revisit semantics, the expression problem, referential transparency, and the EVM.": "Verbinde die Mechanismen wieder mit ihrer Bedeutung. Sieh dir Semantik, Expression Problem, referenzielle Transparenz und EVM erneut an.", + "Clear ideas. Composable programs.": "Klare Ideen. Zusammensetzbare Programme.", + "Source on GitHub": "Quelltext auf GitHub", + "ALUX Network": "ALUX Network", + "Made of ideas.": "Aus Ideen gemacht.", + "Built to be explored.": "Zum Entdecken gebaut.", + "SMALL BUILDING BLOCKS.": "KLEINE BAUSTEINE.", + "WORLDS OF POSSIBILITY.": "WELTEN VOLLER MÖGLICHKEITEN.", + "My bookmarks": "Meine Lesezeichen", + "Remove bookmark": "Lesezeichen entfernen", + "Close bookmarks": "Lesezeichen schließen", + "No bookmarks yet.": "Noch keine Lesezeichen.", + "Save a chapter with the bookmark button to continue reading here.": "Speichere ein Kapitel über die Lesezeichen-Schaltfläche, um hier weiterzulesen.", + "Add bookmark": "Lesezeichen setzen", + "Bookmarked": "Lesezeichen hinzugefügt", + "Hide contents": "Inhaltsverzeichnis ausblenden", + "Show contents": "Inhaltsverzeichnis anzeigen" +} diff --git a/web/locales/ui/en.json b/web/locales/ui/en.json new file mode 100644 index 0000000..dbe9ee6 --- /dev/null +++ b/web/locales/ui/en.json @@ -0,0 +1,140 @@ +{ + "A visitor-based structure that allows:": "A visitor-based structure that allows:", + "Solutions are possible, but they tend to require either:": "Solutions are possible, but they tend to require either:", + "Execution state includes:": "Execution state includes:", + "The semantic view — choosing what a program means before how it runs": "The semantic view — choosing what a program means before how it runs", + "Design by meaning in Rust — building software from small capability traits": "Design by meaning in Rust — building software from small capability traits", + "Concepts — the programming machinery": "Concepts — the programming machinery", + "Insights — connecting concepts back to the semantic view": "Insights — connecting concepts back to the semantic view", + "ALUX PROGRAMMING": "ALUX PROGRAMMING", + "Main navigation": "Main navigation", + "ALUX Programming home": "ALUX Programming home", + "Scrollable technical content": "Scrollable technical content", + "The book could not load.": "The book could not load.", + "Please refresh the page to try again.": "Please refresh the page to try again.", + "Try again": "Try Again", + "This page is uncharted.": "This page is uncharted.", + "Find your way back to the book.": "Find your way back to the book.", + "This language is unavailable. Please try again.": "This language is unavailable. Please try again.", + "Copy is unavailable. Select the code to copy it.": "Copy is unavailable. Select the code to copy it.", + "THE CHAPTER ATLAS": "THE CHAPTER ATLAS", + "The chapter atlas": "The Chapter Atlas", + "A world of ideas.": "A world of ideas.", + "Choose a world.": "Choose a world.", + "Follow an idea as far as it takes you.": "Follow an idea as far as it takes you.", + "Browse as a list": "Browse as a List", + "Interactive chapter map": "Interactive Chapter Map", + "⟦ parts ⟧ → whole": "⟦ parts ⟧ → whole", + "Previous world": "Previous World", + "Next world": "Next World", + "Enter this world": "Enter This World", + "Start with what a program means. Explore denotations, compositionality, laws, and the relationship between meaning and representation.": "Start with what a program means. Explore denotations, compositionality, laws, and the relationship between meaning and representation.", + "Give meaning a concrete vocabulary. Explore capability traits, derived operations, interpreters, evidence, and compiler pipelines in Rust.": "Give meaning a concrete vocabulary. Explore capability traits, derived operations, interpreters, evidence, and compiler pipelines in Rust.", + "Look beneath the surface of a program. Explore the structures and transformations that connect ideas to execution.": "Look beneath the surface of a program. Explore the structures and transformations that connect ideas to execution.", + "Return to familiar ideas with a new perspective. Follow the connections between the semantic view and real programming machinery.": "Return to familiar ideas with a new perspective. Follow the connections between the semantic view and real programming machinery.", + "Reading world": "Reading world", + "Choose a world": "Choose a World", + "Continue the journey": "Continue the Journey", + "Return to the table of contents": "Return to the Table of Contents", + "First the meaning.": "First the meaning.", + "Then the machinery.": "Then the machinery.", + "Explore another chapter": "Explore Another Chapter", + "Magic world": "Magic World", + "Real world": "Real World", + "Click to enter": "Click to Enter", + "Choose your world": "Choose Your World", + "Choose world": "Choose World", + "Language": "Language", + "Programming": "Programming", + "PROGRAMMING": "PROGRAMMING", + "ALUX Programming": "ALUX Programming", + "The book": "The Book", + "Chapters": "Chapters", + "Search": "Search", + "Search the book": "Search", + "Table of contents": "Table of Contents", + "Contents": "Contents", + "Introduction": "Introduction", + "Welcome": "Welcome", + "The Semantic View": "The Semantic View", + "THE SEMANTIC VIEW": "THE SEMANTIC VIEW", + "Design by Meaning in Rust": "Design by Meaning in Rust", + "DESIGN BY MEANING IN RUST": "DESIGN BY MEANING IN RUST", + "Concepts": "Concepts", + "CONCEPTS": "CONCEPTS", + "Insights": "Insights", + "INSIGHTS": "INSIGHTS", + "Contributing": "Contributing", + "CONTRIBUTING": "CONTRIBUTING", + "Previous page": "Previous Page", + "Next page": "Next Page", + "Previous chapter": "Previous Chapter", + "Next chapter": "Next Chapter", + "Back to contents": "Back to Contents", + "In this chapter": "In This Chapter", + "Original source": "Original Source", + "Scroll view": "Scroll View", + "Book view": "Book View", + "Continuous reading": "Continuous Reading", + "Preparing the pages…": "Preparing the pages…", + "Open book navigation": "Open book navigation", + "Toggle table of contents": "Toggle table of contents", + "Close table of contents": "Close table of contents", + "Decrease text size": "Decrease text size", + "Increase text size": "Increase text size", + "Toggle night reading": "Toggle night reading", + "Bookmark this chapter": "Bookmark this chapter", + "Chapter bookmarked": "Chapter bookmarked", + "Bookmark removed": "Bookmark removed", + "Change reading theme": "Change reading theme", + "Light": "Light", + "Rust": "Rust", + "Coal": "Coal", + "Navy": "Navy", + "Ayu": "Ayu", + "Copy code": "Copy Code", + "Copied": "Copied", + "Code copied": "Code copied", + "Select code to copy": "Select code to copy", + "Scrollable table": "Scrollable table", + "Link to this section": "Link to this section", + "View source on GitHub": "View source on GitHub", + "Skip to content": "Skip to content", + "Search ideas, code, chapters…": "Search ideas, code, chapters…", + "Search ideas, code, chapters": "Search ideas, code, chapters", + "Close search": "Close search", + "Search the complete book": "Search the complete book", + "to close": "to close", + "A keyword opens a new page.": "A keyword opens a new page.", + "Search every chapter, code example and idea.": "Search every chapter, code example and idea.", + "YOUR BOOKMARK": "YOUR BOOKMARK", + "START EXPLORING": "START EXPLORING", + "Continue reading": "Continue Reading", + "No pages found.": "No pages found.", + "Try a concept such as “capability”, “Rust” or “meaning”.": "Try a concept such as “capability”, “Rust” or “meaning”.", + "About the book": "About the Book", + "Read the introduction": "Read the Introduction", + "The book of": "The book of", + "small, powerful ideas.": "small, powerful ideas.", + "The complete table of contents. Follow the chapters in order, or find the idea you came for.": "The complete table of contents. Follow the chapters in order, or find the idea you came for.", + "Begin with the meaning of a program. Explore denotations, compositionality, laws, interpretations, and the role of dependent types.": "Begin with the meaning of a program. Explore denotations, compositionality, laws, interpretations, and the role of dependent types.", + "Carry meaning-first design into Rust: capability algebras, semantic types, derived operations, interpreters, evidence, and language pipelines.": "Carry meaning-first design into Rust: capability algebras, semantic types, derived operations, interpreters, evidence, and language pipelines.", + "Explore execution models and useful machinery: operational semantics, the expression problem, free monads, continuations, and branching.": "Explore execution models and useful machinery: operational semantics, the expression problem, free monads, continuations, and branching.", + "Connect the machinery back to meaning. Revisit semantics, the expression problem, referential transparency, and the EVM.": "Connect the machinery back to meaning. Revisit semantics, the expression problem, referential transparency, and the EVM.", + "Clear ideas. Composable programs.": "Clear ideas. Composable programs.", + "Source on GitHub": "Source on GitHub", + "ALUX Network": "ALUX Network", + "Made of ideas.": "Made of ideas.", + "Built to be explored.": "Built to be explored.", + "SMALL BUILDING BLOCKS.": "SMALL BUILDING BLOCKS.", + "WORLDS OF POSSIBILITY.": "WORLDS OF POSSIBILITY.", + "My bookmarks": "My Bookmarks", + "Remove bookmark": "Remove bookmark", + "Close bookmarks": "Close bookmarks", + "No bookmarks yet.": "No bookmarks yet.", + "Save a chapter with the bookmark button to continue reading here.": "Save a chapter with the bookmark button to continue reading here.", + "Add bookmark": "Add Bookmark", + "Bookmarked": "Bookmarked", + "Hide contents": "Hide Contents", + "Show contents": "Show Contents" +} diff --git a/web/locales/ui/es.json b/web/locales/ui/es.json new file mode 100644 index 0000000..63f4928 --- /dev/null +++ b/web/locales/ui/es.json @@ -0,0 +1,140 @@ +{ + "A visitor-based structure that allows:": "Una estructura basada en visitantes que permite:", + "Solutions are possible, but they tend to require either:": "Existen soluciones, pero suelen requerir:", + "Execution state includes:": "El estado de ejecución incluye:", + "The semantic view — choosing what a program means before how it runs": "Perspectiva semántica — decidir qué significa un programa antes de cómo se ejecuta", + "Design by meaning in Rust — building software from small capability traits": "Diseño basado en el significado en Rust — crear software a partir de pequeños rasgos de capacidades", + "Concepts — the programming machinery": "Conceptos — los mecanismos de programación", + "Insights — connecting concepts back to the semantic view": "Perspectivas — conectar los conceptos con la perspectiva semántica", + "ALUX PROGRAMMING": "PROGRAMACIÓN ALUX", + "Main navigation": "Navegación principal", + "ALUX Programming home": "Inicio de Programación ALUX", + "Scrollable technical content": "Contenido técnico desplazable", + "The book could not load.": "No se pudo cargar el libro.", + "Please refresh the page to try again.": "Actualiza la página para volver a intentarlo.", + "Try again": "Volver a intentarlo", + "This page is uncharted.": "Esta página aún no está explorada.", + "Find your way back to the book.": "Encuentra el camino de vuelta al libro.", + "This language is unavailable. Please try again.": "Este idioma no está disponible. Vuelve a intentarlo.", + "Copy is unavailable. Select the code to copy it.": "No se puede copiar. Selecciona el código para copiarlo.", + "THE CHAPTER ATLAS": "ATLAS DE CAPÍTULOS", + "The chapter atlas": "El atlas de capítulos", + "A world of ideas.": "Un mundo de ideas.", + "Choose a world.": "Elige un mundo.", + "Follow an idea as far as it takes you.": "Sigue una idea hasta donde te lleve.", + "Browse as a list": "Explorar como lista", + "Interactive chapter map": "Mapa interactivo de capítulos", + "⟦ parts ⟧ → whole": "⟦ partes ⟧ → todo", + "Previous world": "Mundo anterior", + "Next world": "Mundo siguiente", + "Enter this world": "Entrar en este mundo", + "Start with what a program means. Explore denotations, compositionality, laws, and the relationship between meaning and representation.": "Empieza por el significado de un programa. Explora denotaciones, composicionalidad, leyes y la relación entre significado y representación.", + "Give meaning a concrete vocabulary. Explore capability traits, derived operations, interpreters, evidence, and compiler pipelines in Rust.": "Dale al significado un vocabulario concreto. Explora rasgos de capacidades, operaciones derivadas, intérpretes, pruebas y procesos de compilación en Rust.", + "Look beneath the surface of a program. Explore the structures and transformations that connect ideas to execution.": "Mira bajo la superficie de un programa. Explora las estructuras y transformaciones que conectan las ideas con la ejecución.", + "Return to familiar ideas with a new perspective. Follow the connections between the semantic view and real programming machinery.": "Vuelve a ideas conocidas desde una nueva perspectiva. Sigue las conexiones entre la perspectiva semántica y los mecanismos reales de programación.", + "Reading world": "Mundo de lectura", + "Choose a world": "Elige un mundo", + "Continue the journey": "Continuar el viaje", + "Return to the table of contents": "Volver al índice", + "First the meaning.": "Primero, el significado.", + "Then the machinery.": "Después, los mecanismos.", + "Explore another chapter": "Explorar otro capítulo", + "Magic world": "Mundo mágico", + "Real world": "Mundo real", + "Click to enter": "Haz clic para entrar", + "Choose your world": "Elige tu mundo", + "Choose world": "Elegir mundo", + "Language": "Idioma", + "Programming": "Programación", + "PROGRAMMING": "PROGRAMACIÓN", + "ALUX Programming": "Programación ALUX", + "The book": "El libro", + "Chapters": "Capítulos", + "Search": "Buscar", + "Search the book": "Buscar", + "Table of contents": "Índice", + "Contents": "Contenido", + "Introduction": "Introducción", + "Welcome": "Bienvenida", + "The Semantic View": "La perspectiva semántica", + "THE SEMANTIC VIEW": "LA PERSPECTIVA SEMÁNTICA", + "Design by Meaning in Rust": "Diseño basado en el significado en Rust", + "DESIGN BY MEANING IN RUST": "DISEÑO BASADO EN EL SIGNIFICADO EN RUST", + "Concepts": "Conceptos", + "CONCEPTS": "CONCEPTOS", + "Insights": "Perspectivas", + "INSIGHTS": "PERSPECTIVAS", + "Contributing": "Contribuir", + "CONTRIBUTING": "CONTRIBUIR", + "Previous page": "Página anterior", + "Next page": "Página siguiente", + "Previous chapter": "Capítulo anterior", + "Next chapter": "Capítulo siguiente", + "Back to contents": "Volver al índice", + "In this chapter": "En este capítulo", + "Original source": "Fuente original", + "Scroll view": "Vista de desplazamiento", + "Book view": "Vista de libro", + "Continuous reading": "Lectura continua", + "Preparing the pages…": "Preparando las páginas…", + "Open book navigation": "Abrir navegación del libro", + "Toggle table of contents": "Mostrar u ocultar el índice", + "Close table of contents": "Cerrar el índice", + "Decrease text size": "Reducir el tamaño del texto", + "Increase text size": "Aumentar el tamaño del texto", + "Toggle night reading": "Activar o desactivar la lectura nocturna", + "Bookmark this chapter": "Añadir este capítulo a marcadores", + "Chapter bookmarked": "Capítulo añadido a marcadores", + "Bookmark removed": "Marcador eliminado", + "Change reading theme": "Cambiar el tema de lectura", + "Light": "Claro", + "Rust": "Rust", + "Coal": "Carbón", + "Navy": "Azul marino", + "Ayu": "Ayu", + "Copy code": "Copiar código", + "Copied": "Copiado", + "Code copied": "Código copiado", + "Select code to copy": "Selecciona el código que quieres copiar", + "Scrollable table": "Tabla desplazable", + "Link to this section": "Enlace a esta sección", + "View source on GitHub": "Ver el código fuente en GitHub", + "Skip to content": "Ir al contenido", + "Search ideas, code, chapters…": "Buscar ideas, código y capítulos…", + "Search ideas, code, chapters": "Buscar ideas, código y capítulos", + "Close search": "Cerrar búsqueda", + "Search the complete book": "Buscar en todo el libro", + "to close": "para cerrar", + "A keyword opens a new page.": "Una palabra clave abre una nueva página.", + "Search every chapter, code example and idea.": "Busca en todos los capítulos, ejemplos de código e ideas.", + "YOUR BOOKMARK": "TUS MARCADORES", + "START EXPLORING": "EMPIEZA A EXPLORAR", + "Continue reading": "Seguir leyendo", + "No pages found.": "No se encontraron páginas.", + "Try a concept such as “capability”, “Rust” or “meaning”.": "Prueba con conceptos como «capacidad», «Rust» o «significado».", + "About the book": "Acerca del libro", + "Read the introduction": "Leer la introducción", + "The book of": "Un libro de", + "small, powerful ideas.": "ideas pequeñas y poderosas.", + "The complete table of contents. Follow the chapters in order, or find the idea you came for.": "Consulta el índice completo. Sigue los capítulos en orden o busca la idea que te interesa.", + "Begin with the meaning of a program. Explore denotations, compositionality, laws, interpretations, and the role of dependent types.": "Empieza por el significado de un programa. Explora denotaciones, composicionalidad, leyes, interpretaciones y el papel de los tipos dependientes.", + "Carry meaning-first design into Rust: capability algebras, semantic types, derived operations, interpreters, evidence, and language pipelines.": "Lleva el diseño basado en el significado a Rust: álgebras de capacidades, tipos semánticos, operaciones derivadas, intérpretes, pruebas y procesos de lenguaje.", + "Explore execution models and useful machinery: operational semantics, the expression problem, free monads, continuations, and branching.": "Explora modelos de ejecución y mecanismos útiles: semántica operacional, problema de expresiones, mónadas libres, continuaciones y ramificación.", + "Connect the machinery back to meaning. Revisit semantics, the expression problem, referential transparency, and the EVM.": "Vuelve a conectar los mecanismos con el significado. Repasa la semántica, el problema de expresiones, la transparencia referencial y la EVM.", + "Clear ideas. Composable programs.": "Ideas claras. Programas componibles.", + "Source on GitHub": "Código fuente en GitHub", + "ALUX Network": "ALUX Network", + "Made of ideas.": "Hecho de ideas.", + "Built to be explored.": "Diseñado para explorar.", + "SMALL BUILDING BLOCKS.": "BLOQUES PEQUEÑOS.", + "WORLDS OF POSSIBILITY.": "MUNDOS DE POSIBILIDADES.", + "My bookmarks": "Mis marcadores", + "Remove bookmark": "Quitar marcador", + "Close bookmarks": "Cerrar marcadores", + "No bookmarks yet.": "Todavía no tienes marcadores.", + "Save a chapter with the bookmark button to continue reading here.": "Guarda un capítulo con el botón de marcadores para seguir leyéndolo desde aquí.", + "Add bookmark": "Añadir marcador", + "Bookmarked": "Guardado", + "Hide contents": "Ocultar índice", + "Show contents": "Mostrar índice" +} diff --git a/web/locales/ui/ja.json b/web/locales/ui/ja.json new file mode 100644 index 0000000..24f47cd --- /dev/null +++ b/web/locales/ui/ja.json @@ -0,0 +1,140 @@ +{ + "A visitor-based structure that allows:": "Visitorパターンに基づく構造で、次のことが可能です。", + "Solutions are possible, but they tend to require either:": "解決は可能ですが、通常はいずれかが必要になります。", + "Execution state includes:": "実行状態には次のものが含まれます。", + "The semantic view — choosing what a program means before how it runs": "意味論の視点:実行方法より先にプログラムの意味を選ぶ", + "Design by meaning in Rust — building software from small capability traits": "Rustで意味から設計する:小さなケイパビリティトレイトからソフトウェアを組み立てる", + "Concepts — the programming machinery": "概念:プログラミングの仕組み", + "Insights — connecting concepts back to the semantic view": "洞察:概念を意味論の視点に結び直す", + "ALUX PROGRAMMING": "ALUX プログラミング", + "Main navigation": "メインナビゲーション", + "ALUX Programming home": "ALUX プログラミングのホーム", + "Scrollable technical content": "スクロール可能な技術情報", + "The book could not load.": "本を読み込めませんでした。", + "Please refresh the page to try again.": "ページを再読み込みしてください。", + "Try again": "再試行", + "This page is uncharted.": "このページは見つかりません。", + "Find your way back to the book.": "目次に戻って読み進めてください。", + "This language is unavailable. Please try again.": "この言語を読み込めません。もう一度お試しください。", + "Copy is unavailable. Select the code to copy it.": "コピーできません。コードを選択してコピーしてください。", + "THE CHAPTER ATLAS": "章の地図", + "The chapter atlas": "章の地図", + "A world of ideas.": "アイデアの世界。", + "Choose a world.": "世界を選んでください。", + "Follow an idea as far as it takes you.": "ひとつのアイデアを、行き着く先までたどってみましょう。", + "Browse as a list": "一覧で見る", + "Interactive chapter map": "対話式の章の地図", + "⟦ parts ⟧ → whole": "⟦ 部分 ⟧ → 全体", + "Previous world": "前の世界", + "Next world": "次の世界", + "Enter this world": "この世界に入る", + "Start with what a program means. Explore denotations, compositionality, laws, and the relationship between meaning and representation.": "プログラムの意味から、表示・合成性・法則と意味と表現の関係を探ります。", + "Give meaning a concrete vocabulary. Explore capability traits, derived operations, interpreters, evidence, and compiler pipelines in Rust.": "意味に具体的な語彙を与え、Rustのケイパビリティトレイト・導出演算・インタープリター・根拠・コンパイラパイプラインを探ります。", + "Look beneath the surface of a program. Explore the structures and transformations that connect ideas to execution.": "プログラムの表面の下にある、アイデアと実行を結ぶ構造と変換を探ります。", + "Return to familiar ideas with a new perspective. Follow the connections between the semantic view and real programming machinery.": "新しい視点で馴染みある概念を見直し、意味論の視点と実際のプログラミングの仕組みとのつながりをたどります。", + "Reading world": "読書の世界", + "Choose a world": "世界を選ぶ", + "Continue the journey": "読み進める", + "Return to the table of contents": "全体の目次に戻る", + "First the meaning.": "まず意味を。", + "Then the machinery.": "仕組みはその後。", + "Explore another chapter": "ほかの章を読む", + "Magic world": "魔法の世界", + "Real world": "現実の世界", + "Click to enter": "クリックして入る", + "Choose your world": "世界を選んでください", + "Choose world": "世界を選ぶ", + "Language": "言語", + "Programming": "プログラミング", + "PROGRAMMING": "プログラミング", + "ALUX Programming": "ALUX プログラミング", + "The book": "本を読む", + "Chapters": "目次", + "Search": "検索", + "Search the book": "検索", + "Table of contents": "全体の目次", + "Contents": "目次", + "Introduction": "はじめに", + "Welcome": "ようこそ", + "The Semantic View": "意味論の視点", + "THE SEMANTIC VIEW": "意味論の視点", + "Design by Meaning in Rust": "Rustで意味から設計する", + "DESIGN BY MEANING IN RUST": "Rustで意味から設計する", + "Concepts": "概念", + "CONCEPTS": "概念", + "Insights": "洞察", + "INSIGHTS": "洞察", + "Contributing": "貢献する", + "CONTRIBUTING": "貢献する", + "Previous page": "前のページ", + "Next page": "次のページ", + "Previous chapter": "前の章", + "Next chapter": "次の章", + "Back to contents": "目次に戻る", + "In this chapter": "この章の目次", + "Original source": "原文ソース", + "Scroll view": "スクロール表示", + "Book view": "ページ表示", + "Continuous reading": "連続表示", + "Preparing the pages…": "ページを準備中…", + "Open book navigation": "全体の目次を開く", + "Toggle table of contents": "目次の表示を切り替え", + "Close table of contents": "目次を閉じる", + "Decrease text size": "文字を小さくする", + "Increase text size": "文字を大きくする", + "Toggle night reading": "夜間モードを切り替え", + "Bookmark this chapter": "この章をブックマーク", + "Chapter bookmarked": "章をブックマークしました", + "Bookmark removed": "ブックマークを削除しました", + "Change reading theme": "読書テーマを変更", + "Light": "ライト", + "Rust": "Rust", + "Coal": "コール", + "Navy": "ネイビー", + "Ayu": "Ayu", + "Copy code": "コードをコピー", + "Copied": "コピーしました", + "Code copied": "コードをコピーしました", + "Select code to copy": "コードを選択してコピー", + "Scrollable table": "横スクロール可能な表", + "Link to this section": "この節へのリンク", + "View source on GitHub": "GitHubでソースを表示", + "Skip to content": "本文へ移動", + "Search ideas, code, chapters…": "概念・コード・章を検索…", + "Search ideas, code, chapters": "概念・コード・章を検索", + "Close search": "検索を閉じる", + "Search the complete book": "本全体を検索", + "to close": "で閉じる", + "A keyword opens a new page.": "ひとつのキーワードで、新たなページへ。", + "Search every chapter, code example and idea.": "すべての章・コード例・概念を検索できます。", + "YOUR BOOKMARK": "ブックマーク", + "START EXPLORING": "探索を始める", + "Continue reading": "続きを読む", + "No pages found.": "ページが見つかりません。", + "Try a concept such as “capability”, “Rust” or “meaning”.": "「ケイパビリティ」「Rust」「意味」などを検索してください。", + "About the book": "本書について", + "Read the introduction": "はじめにを読む", + "The book of": "小さく力強い", + "small, powerful ideas.": "アイデアの本。", + "The complete table of contents. Follow the chapters in order, or find the idea you came for.": "目次に沿って読むことも、目的の概念を探すこともできます。", + "Begin with the meaning of a program. Explore denotations, compositionality, laws, interpretations, and the role of dependent types.": "プログラムの意味から、表示・合成性・法則・解釈・依存型の役割を探ります。", + "Carry meaning-first design into Rust: capability algebras, semantic types, derived operations, interpreters, evidence, and language pipelines.": "意味を起点とした設計をRustのケイパビリティ代数・意味型・導出演算・インタープリター・根拠・言語パイプラインへ展開します。", + "Explore execution models and useful machinery: operational semantics, the expression problem, free monads, continuations, and branching.": "操作的意味論・式問題・自由モナド・継続・分岐などの実行モデルと仕組みを探ります。", + "Connect the machinery back to meaning. Revisit semantics, the expression problem, referential transparency, and the EVM.": "仕組みを意味に結び直し、意味論・式問題・参照透過性・EVMを見直します。", + "Clear ideas. Composable programs.": "明確な発想、合成可能なプログラム。", + "Source on GitHub": "GitHubのソース", + "ALUX Network": "ALUX Network", + "Made of ideas.": "アイデアから生まれる。", + "Built to be explored.": "探究のためにつくられる。", + "SMALL BUILDING BLOCKS.": "小さなブロック。", + "WORLDS OF POSSIBILITY.": "可能性の世界。", + "My bookmarks": "ブックマーク", + "Remove bookmark": "ブックマークを削除", + "Close bookmarks": "ブックマークを閉じる", + "No bookmarks yet.": "ブックマークはまだありません。", + "Save a chapter with the bookmark button to continue reading here.": "読書ツールバーのブックマークボタンで章を保存すると、ここから読み続けられます。", + "Add bookmark": "ブックマークを追加", + "Bookmarked": "追加済み", + "Hide contents": "目次を閉じる", + "Show contents": "目次を開く" +} diff --git a/web/locales/ui/ko.json b/web/locales/ui/ko.json new file mode 100644 index 0000000..ac21c16 --- /dev/null +++ b/web/locales/ui/ko.json @@ -0,0 +1,140 @@ +{ + "A visitor-based structure that allows:": "방문자 패턴 기반 구조는 다음을 지원합니다:", + "Solutions are possible, but they tend to require either:": "해결은 가능하지만 대개 다음 중 하나가 필요합니다:", + "Execution state includes:": "실행 상태에는 다음이 포함됩니다:", + "The semantic view — choosing what a program means before how it runs": "의미론적 관점: 실행 방법보다 프로그램의 의미를 먼저 선택하기", + "Design by meaning in Rust — building software from small capability traits": "Rust에서 의미 중심 설계: 작은 케이퍼빌리티 트레이트로 소프트웨어 만들기", + "Concepts — the programming machinery": "개념: 프로그래밍 기법", + "Insights — connecting concepts back to the semantic view": "통찰: 개념을 의미론적 관점과 다시 연결하기", + "ALUX PROGRAMMING": "ALUX 프로그래밍", + "Main navigation": "주 탐색", + "ALUX Programming home": "ALUX 프로그래밍 홈", + "Scrollable technical content": "스크롤 가능한 기술 내용", + "The book could not load.": "책을 불러오지 못했습니다.", + "Please refresh the page to try again.": "페이지를 새로고침해 다시 시도하세요.", + "Try again": "다시 시도", + "This page is uncharted.": "페이지를 찾을 수 없습니다.", + "Find your way back to the book.": "목차로 돌아가 계속 읽어보세요.", + "This language is unavailable. Please try again.": "언어를 불러올 수 없습니다. 다시 시도하세요.", + "Copy is unavailable. Select the code to copy it.": "복사할 수 없습니다. 코드를 선택해 복사하세요.", + "THE CHAPTER ATLAS": "장 지도", + "The chapter atlas": "장 지도", + "A world of ideas.": "아이디어의 세계.", + "Choose a world.": "세계를 선택하세요.", + "Follow an idea as far as it takes you.": "하나의 아이디어를 따라 끝까지 탐색해 보세요.", + "Browse as a list": "목록으로 보기", + "Interactive chapter map": "대화형 장 지도", + "⟦ parts ⟧ → whole": "⟦ 부분 ⟧ → 전체", + "Previous world": "이전 세계", + "Next world": "다음 세계", + "Enter this world": "이 세계에 입장", + "Start with what a program means. Explore denotations, compositionality, laws, and the relationship between meaning and representation.": "프로그램의 의미에서 출발해 표시, 합성성, 법칙과 의미·표현의 관계를 살펴봅니다.", + "Give meaning a concrete vocabulary. Explore capability traits, derived operations, interpreters, evidence, and compiler pipelines in Rust.": "의미에 구체적인 어휘를 부여하고 Rust의 케이퍼빌리티 트레이트, 파생 연산, 인터프리터, 증거와 컴파일 파이프라인을 살펴봅니다.", + "Look beneath the surface of a program. Explore the structures and transformations that connect ideas to execution.": "프로그램의 표면 아래에서 아이디어와 실행을 잇는 구조와 변환을 살펴봅니다.", + "Return to familiar ideas with a new perspective. Follow the connections between the semantic view and real programming machinery.": "새로운 관점에서 익숙한 개념을 돌아보고 의미론적 관점과 실제 프로그래밍 기법의 연결을 살펴봅니다.", + "Reading world": "읽기 세계", + "Choose a world": "세계 선택", + "Continue the journey": "계속 읽기", + "Return to the table of contents": "전체 목차로 돌아가기", + "First the meaning.": "의미가 먼저.", + "Then the machinery.": "기법은 그 다음.", + "Explore another chapter": "다른 장 살펴보기", + "Magic world": "마법 세계", + "Real world": "현실 세계", + "Click to enter": "클릭하여 입장", + "Choose your world": "세계를 선택하세요", + "Choose world": "세계 선택", + "Language": "언어", + "Programming": "프로그래밍", + "PROGRAMMING": "프로그래밍", + "ALUX Programming": "ALUX 프로그래밍", + "The book": "책 읽기", + "Chapters": "목차", + "Search": "검색", + "Search the book": "검색", + "Table of contents": "전체 목차", + "Contents": "목차", + "Introduction": "소개", + "Welcome": "환영합니다", + "The Semantic View": "의미론적 관점", + "THE SEMANTIC VIEW": "의미론적 관점", + "Design by Meaning in Rust": "Rust에서 의미 중심 설계", + "DESIGN BY MEANING IN RUST": "Rust에서 의미 중심 설계", + "Concepts": "개념", + "CONCEPTS": "개념", + "Insights": "통찰", + "INSIGHTS": "통찰", + "Contributing": "기여하기", + "CONTRIBUTING": "기여하기", + "Previous page": "이전 페이지", + "Next page": "다음 페이지", + "Previous chapter": "이전 장", + "Next chapter": "다음 장", + "Back to contents": "목차로 돌아가기", + "In this chapter": "이 장의 목차", + "Original source": "원본 소스", + "Scroll view": "스크롤 보기", + "Book view": "책 보기", + "Continuous reading": "연속 읽기", + "Preparing the pages…": "페이지 준비 중…", + "Open book navigation": "책 목차 열기", + "Toggle table of contents": "목차 전환", + "Close table of contents": "목차 닫기", + "Decrease text size": "글자 축소", + "Increase text size": "글자 확대", + "Toggle night reading": "야간 모드 전환", + "Bookmark this chapter": "이 장 북마크", + "Chapter bookmarked": "장 북마크 저장됨", + "Bookmark removed": "북마크 삭제됨", + "Change reading theme": "읽기 테마 변경", + "Light": "밝게", + "Rust": "Rust", + "Coal": "차콜", + "Navy": "네이비", + "Ayu": "Ayu", + "Copy code": "코드 복사", + "Copied": "복사됨", + "Code copied": "코드 복사됨", + "Select code to copy": "코드를 선택해 복사하세요", + "Scrollable table": "가로 스크롤 표", + "Link to this section": "이 절 링크", + "View source on GitHub": "GitHub에서 소스 보기", + "Skip to content": "본문으로 건너뛰기", + "Search ideas, code, chapters…": "개념, 코드, 장 검색…", + "Search ideas, code, chapters": "개념, 코드, 장 검색", + "Close search": "검색 닫기", + "Search the complete book": "전체 책 검색", + "to close": "닫기", + "A keyword opens a new page.": "키워드 하나로 다음 페이지를 펼쳐 보세요.", + "Search every chapter, code example and idea.": "모든 장, 코드 예제, 개념을 검색하세요.", + "YOUR BOOKMARK": "내 북마크", + "START EXPLORING": "탐색 시작", + "Continue reading": "계속 읽기", + "No pages found.": "페이지를 찾을 수 없습니다.", + "Try a concept such as “capability”, “Rust” or “meaning”.": "“능력”, “Rust”, “의미” 등의 개념을 검색해 보세요.", + "About the book": "이 책에 대해", + "Read the introduction": "소개 읽기", + "The book of": "작지만 강력한", + "small, powerful ideas.": "아이디어의 책.", + "The complete table of contents. Follow the chapters in order, or find the idea you came for.": "목차 순서대로 읽거나 원하는 개념을 찾아보세요.", + "Begin with the meaning of a program. Explore denotations, compositionality, laws, interpretations, and the role of dependent types.": "프로그램의 의미에서 시작해 표시, 합성성, 법칙, 해석과 의존 타입의 역할을 살펴봅니다.", + "Carry meaning-first design into Rust: capability algebras, semantic types, derived operations, interpreters, evidence, and language pipelines.": "의미 우선 설계를 Rust의 능력 대수, 의미 타입, 파생 연산, 인터프리터, 증거와 언어 파이프라인에 적용합니다.", + "Explore execution models and useful machinery: operational semantics, the expression problem, free monads, continuations, and branching.": "조작적 의미론, 표현식 문제, 자유 모나드, 연속과 분기 등 실행 모델과 기법을 살펴봅니다.", + "Connect the machinery back to meaning. Revisit semantics, the expression problem, referential transparency, and the EVM.": "실행 기법을 의미와 연결하며 의미론, 표현식 문제, 참조 투명성과 EVM을 다시 살펴봅니다.", + "Clear ideas. Composable programs.": "명확한 생각, 합성 가능한 프로그램.", + "Source on GitHub": "GitHub 소스", + "ALUX Network": "ALUX Network", + "Made of ideas.": "아이디어로 만들어집니다.", + "Built to be explored.": "탐색을 위해 만들어집니다.", + "SMALL BUILDING BLOCKS.": "작은 블록.", + "WORLDS OF POSSIBILITY.": "가능성의 세계.", + "My bookmarks": "내 북마크", + "Remove bookmark": "북마크 삭제", + "Close bookmarks": "북마크 닫기", + "No bookmarks yet.": "아직 북마크가 없습니다.", + "Save a chapter with the bookmark button to continue reading here.": "읽기 도구 모음의 북마크 버튼으로 장을 저장하면 여기에서 이어서 읽을 수 있습니다.", + "Add bookmark": "북마크 추가", + "Bookmarked": "북마크 추가됨", + "Hide contents": "목차 닫기", + "Show contents": "목차 열기" +} diff --git a/web/locales/ui/ru.json b/web/locales/ui/ru.json new file mode 100644 index 0000000..d54f8f9 --- /dev/null +++ b/web/locales/ui/ru.json @@ -0,0 +1,140 @@ +{ + "A visitor-based structure that allows:": "Структура на основе паттерна Visitor, позволяющая:", + "Solutions are possible, but they tend to require either:": "Решения существуют, но обычно требуют одного из двух:", + "Execution state includes:": "Состояние выполнения включает:", + "The semantic view — choosing what a program means before how it runs": "Семантический взгляд — сначала определить смысл программы, затем решить, как она выполняется", + "Design by meaning in Rust — building software from small capability traits": "Проектирование на основе смысла в Rust — создание ПО из небольших трейтов возможностей", + "Concepts — the programming machinery": "Понятия — механизмы программирования", + "Insights — connecting concepts back to the semantic view": "Идеи — связь понятий с семантическим взглядом", + "ALUX PROGRAMMING": "ПРОГРАММИРОВАНИЕ ALUX", + "Main navigation": "Основная навигация", + "ALUX Programming home": "Главная страница программирования ALUX", + "Scrollable technical content": "Прокручиваемый технический материал", + "The book could not load.": "Не удалось загрузить книгу.", + "Please refresh the page to try again.": "Обновите страницу и попробуйте снова.", + "Try again": "Повторить попытку", + "This page is uncharted.": "Эта страница ещё не нанесена на карту.", + "Find your way back to the book.": "Вернитесь к книге.", + "This language is unavailable. Please try again.": "Этот язык сейчас недоступен. Попробуйте ещё раз.", + "Copy is unavailable. Select the code to copy it.": "Копирование недоступно. Выделите код и скопируйте его вручную.", + "THE CHAPTER ATLAS": "АТЛАС ГЛАВ", + "The chapter atlas": "Атлас глав", + "A world of ideas.": "Мир идей.", + "Choose a world.": "Выберите мир.", + "Follow an idea as far as it takes you.": "Следуйте за идеей туда, куда она вас приведёт.", + "Browse as a list": "Открыть список", + "Interactive chapter map": "Интерактивная карта глав", + "⟦ parts ⟧ → whole": "⟦ части ⟧ → целое", + "Previous world": "Предыдущий мир", + "Next world": "Следующий мир", + "Enter this world": "Перейти в этот мир", + "Start with what a program means. Explore denotations, compositionality, laws, and the relationship between meaning and representation.": "Начните со смысла программы. Изучите денотации, композиционность, законы и связь между смыслом и представлением.", + "Give meaning a concrete vocabulary. Explore capability traits, derived operations, interpreters, evidence, and compiler pipelines in Rust.": "Выразите смысл через конкретный словарь. Изучите трейты возможностей, производные операции, интерпретаторы, свидетельства и конвейеры компиляции в Rust.", + "Look beneath the surface of a program. Explore the structures and transformations that connect ideas to execution.": "Загляните под поверхность программы. Изучите структуры и преобразования, связывающие идеи с выполнением.", + "Return to familiar ideas with a new perspective. Follow the connections between the semantic view and real programming machinery.": "Вернитесь к знакомым идеям с новым взглядом. Проследите связи между семантическим подходом и реальными механизмами программирования.", + "Reading world": "Мир чтения", + "Choose a world": "Выберите мир", + "Continue the journey": "Продолжить путь", + "Return to the table of contents": "Вернуться к оглавлению", + "First the meaning.": "Сначала — смысл.", + "Then the machinery.": "Затем — механизмы.", + "Explore another chapter": "Перейти к другой главе", + "Magic world": "Волшебный мир", + "Real world": "Реальный мир", + "Click to enter": "Нажмите, чтобы войти", + "Choose your world": "Выберите свой мир", + "Choose world": "Выбрать мир", + "Language": "Язык", + "Programming": "Программирование", + "PROGRAMMING": "ПРОГРАММИРОВАНИЕ", + "ALUX Programming": "Программирование ALUX", + "The book": "Книга", + "Chapters": "Главы", + "Search": "Поиск", + "Search the book": "Поиск", + "Table of contents": "Оглавление", + "Contents": "Содержание", + "Introduction": "Введение", + "Welcome": "Добро пожаловать", + "The Semantic View": "Семантический взгляд", + "THE SEMANTIC VIEW": "СЕМАНТИЧЕСКИЙ ВЗГЛЯД", + "Design by Meaning in Rust": "Проектирование на основе смысла в Rust", + "DESIGN BY MEANING IN RUST": "ПРОЕКТИРОВАНИЕ НА ОСНОВЕ СМЫСЛА В RUST", + "Concepts": "Понятия", + "CONCEPTS": "ПОНЯТИЯ", + "Insights": "Идеи", + "INSIGHTS": "ИДЕИ", + "Contributing": "Участие в разработке", + "CONTRIBUTING": "УЧАСТИЕ В РАЗРАБОТКЕ", + "Previous page": "Предыдущая страница", + "Next page": "Следующая страница", + "Previous chapter": "Предыдущая глава", + "Next chapter": "Следующая глава", + "Back to contents": "Вернуться к содержанию", + "In this chapter": "В этой главе", + "Original source": "Исходный источник", + "Scroll view": "Режим прокрутки", + "Book view": "Постраничный просмотр", + "Continuous reading": "Непрерывное чтение", + "Preparing the pages…": "Подготавливаем страницы…", + "Open book navigation": "Открыть навигацию по книге", + "Toggle table of contents": "Показать или скрыть оглавление", + "Close table of contents": "Закрыть оглавление", + "Decrease text size": "Уменьшить размер текста", + "Increase text size": "Увеличить размер текста", + "Toggle night reading": "Включить или выключить ночной режим", + "Bookmark this chapter": "Добавить главу в закладки", + "Chapter bookmarked": "Глава добавлена в закладки", + "Bookmark removed": "Закладка удалена", + "Change reading theme": "Изменить тему чтения", + "Light": "Светлая", + "Rust": "Rust", + "Coal": "Угольная", + "Navy": "Тёмно-синяя", + "Ayu": "Ayu", + "Copy code": "Копировать код", + "Copied": "Скопировано", + "Code copied": "Код скопирован", + "Select code to copy": "Выделите код, чтобы скопировать", + "Scrollable table": "Прокручиваемая таблица", + "Link to this section": "Ссылка на этот раздел", + "View source on GitHub": "Посмотреть исходный код на GitHub", + "Skip to content": "Перейти к содержимому", + "Search ideas, code, chapters…": "Искать идеи, код, главы…", + "Search ideas, code, chapters": "Искать идеи, код, главы", + "Close search": "Закрыть поиск", + "Search the complete book": "Искать по всей книге", + "to close": "чтобы закрыть", + "A keyword opens a new page.": "Ключевое слово открывает новую страницу.", + "Search every chapter, code example and idea.": "Поиск по всем главам, примерам кода и идеям.", + "YOUR BOOKMARK": "ВАШИ ЗАКЛАДКИ", + "START EXPLORING": "НАЧАТЬ ЧТЕНИЕ", + "Continue reading": "Продолжить чтение", + "No pages found.": "Страницы не найдены.", + "Try a concept such as “capability”, “Rust” or “meaning”.": "Попробуйте поискать, например, «возможность», «Rust» или «смысл».", + "About the book": "О книге", + "Read the introduction": "Прочитать введение", + "The book of": "Книга о", + "small, powerful ideas.": "небольших, но сильных идеях.", + "The complete table of contents. Follow the chapters in order, or find the idea you came for.": "Полное оглавление. Читайте главы по порядку или найдите нужную идею.", + "Begin with the meaning of a program. Explore denotations, compositionality, laws, interpretations, and the role of dependent types.": "Начните со смысла программы. Изучите денотации, композиционность, законы, интерпретации и роль зависимых типов.", + "Carry meaning-first design into Rust: capability algebras, semantic types, derived operations, interpreters, evidence, and language pipelines.": "Примените проектирование с приоритетом смысла в Rust: алгебры возможностей, семантические типы, производные операции, интерпретаторы, свидетельства и языковые конвейеры.", + "Explore execution models and useful machinery: operational semantics, the expression problem, free monads, continuations, and branching.": "Изучите модели выполнения и полезные механизмы: операционную семантику, проблему выражения, свободные монады, продолжения и ветвление.", + "Connect the machinery back to meaning. Revisit semantics, the expression problem, referential transparency, and the EVM.": "Свяжите механизмы со смыслом. Вернитесь к семантике, проблеме выражения, референциальной прозрачности и EVM.", + "Clear ideas. Composable programs.": "Ясные идеи. Композиционные программы.", + "Source on GitHub": "Исходный код на GitHub", + "ALUX Network": "Сеть ALUX", + "Made of ideas.": "Создано из идей.", + "Built to be explored.": "Создано для исследования.", + "SMALL BUILDING BLOCKS.": "НЕБОЛЬШИЕ СТРОИТЕЛЬНЫЕ БЛОКИ.", + "WORLDS OF POSSIBILITY.": "МИРЫ ВОЗМОЖНОСТЕЙ.", + "My bookmarks": "Мои закладки", + "Remove bookmark": "Удалить закладку", + "Close bookmarks": "Закрыть закладки", + "No bookmarks yet.": "Закладок пока нет.", + "Save a chapter with the bookmark button to continue reading here.": "Добавьте главу в закладки, чтобы продолжить чтение отсюда.", + "Add bookmark": "Добавить закладку", + "Bookmarked": "В закладках", + "Hide contents": "Скрыть оглавление", + "Show contents": "Показать оглавление" +} diff --git a/web/locales/ui/uk.json b/web/locales/ui/uk.json new file mode 100644 index 0000000..f3b3382 --- /dev/null +++ b/web/locales/ui/uk.json @@ -0,0 +1,140 @@ +{ + "A visitor-based structure that allows:": "Структура на основі відвідувача, що дає змогу:", + "Solutions are possible, but they tend to require either:": "Рішення можливі, але зазвичай потребують одного з двох:", + "Execution state includes:": "Стан виконання містить:", + "The semantic view — choosing what a program means before how it runs": "Семантичний погляд — спершу визначити значення програми, а вже потім спосіб її виконання", + "Design by meaning in Rust — building software from small capability traits": "Проєктування від значення в Rust — створення програмного забезпечення з невеликих трейтів можливостей", + "Concepts — the programming machinery": "Поняття — механізми програмування", + "Insights — connecting concepts back to the semantic view": "Інсайти — повернення понять до семантичного погляду", + "ALUX PROGRAMMING": "ПРОГРАМУВАННЯ ALUX", + "Main navigation": "Головна навігація", + "ALUX Programming home": "Головна сторінка програмування ALUX", + "Scrollable technical content": "Прокручуваний технічний вміст", + "The book could not load.": "Не вдалося завантажити книжку.", + "Please refresh the page to try again.": "Оновіть сторінку, щоб спробувати ще раз.", + "Try again": "Спробувати ще раз", + "This page is uncharted.": "Ця сторінка ще не відкрита.", + "Find your way back to the book.": "Поверніться до книжки.", + "This language is unavailable. Please try again.": "Ця мова недоступна. Спробуйте ще раз.", + "Copy is unavailable. Select the code to copy it.": "Копіювання недоступне. Виділіть код, щоб скопіювати його.", + "THE CHAPTER ATLAS": "АТЛАС РОЗДІЛІВ", + "The chapter atlas": "Атлас розділів", + "A world of ideas.": "Світ ідей.", + "Choose a world.": "Виберіть світ.", + "Follow an idea as far as it takes you.": "Простежте за ідеєю, куди б вона вас не привела.", + "Browse as a list": "Переглянути списком", + "Interactive chapter map": "Інтерактивна мапа розділів", + "⟦ parts ⟧ → whole": "⟦ частини ⟧ → ціле", + "Previous world": "Попередній світ", + "Next world": "Наступний світ", + "Enter this world": "Увійти у цей світ", + "Start with what a program means. Explore denotations, compositionality, laws, and the relationship between meaning and representation.": "Почніть зі значення програми. Дослідіть денотації, композиційність, закони та зв’язок між значенням і представленням.", + "Give meaning a concrete vocabulary. Explore capability traits, derived operations, interpreters, evidence, and compiler pipelines in Rust.": "Надайте значенню конкретну термінологію. Дослідіть трейти можливостей, похідні операції, інтерпретатори, свідчення й конвеєри компіляції в Rust.", + "Look beneath the surface of a program. Explore the structures and transformations that connect ideas to execution.": "Зазирніть за поверхню програми. Дослідіть структури й перетворення, що поєднують ідеї з виконанням.", + "Return to familiar ideas with a new perspective. Follow the connections between the semantic view and real programming machinery.": "Погляньте на знайомі ідеї по-новому. Простежте зв’язки між семантичним поглядом і практичними механізмами програмування.", + "Reading world": "Світ читання", + "Choose a world": "Вибрати світ", + "Continue the journey": "Продовжити подорож", + "Return to the table of contents": "Повернутися до змісту", + "First the meaning.": "Спершу значення.", + "Then the machinery.": "Потім механізми.", + "Explore another chapter": "Дослідити інший розділ", + "Magic world": "Чарівний світ", + "Real world": "Реальний світ", + "Click to enter": "Натисніть, щоб увійти", + "Choose your world": "Виберіть свій світ", + "Choose world": "Вибрати світ", + "Language": "Мова", + "Programming": "Програмування", + "PROGRAMMING": "ПРОГРАМУВАННЯ", + "ALUX Programming": "Програмування ALUX", + "The book": "Книжка", + "Chapters": "Розділи", + "Search": "Пошук", + "Search the book": "Пошук", + "Table of contents": "Зміст", + "Contents": "Зміст книжки", + "Introduction": "Вступ", + "Welcome": "Вітаємо", + "The Semantic View": "Семантичний погляд", + "THE SEMANTIC VIEW": "СЕМАНТИЧНИЙ ПОГЛЯД", + "Design by Meaning in Rust": "Проєктування від значення в Rust", + "DESIGN BY MEANING IN RUST": "ПРОЄКТУВАННЯ ВІД ЗНАЧЕННЯ В RUST", + "Concepts": "Поняття", + "CONCEPTS": "ПОНЯТТЯ", + "Insights": "Інсайти", + "INSIGHTS": "ОСЯЯННЯ", + "Contributing": "Долучитися до розробки", + "CONTRIBUTING": "ДОЛУЧИТИСЯ ДО РОЗРОБКИ", + "Previous page": "Попередня сторінка", + "Next page": "Наступна сторінка", + "Previous chapter": "Попередній розділ", + "Next chapter": "Наступний розділ", + "Back to contents": "Назад до змісту", + "In this chapter": "У цьому розділі", + "Original source": "Першоджерело", + "Scroll view": "Режим прокручування", + "Book view": "Режим книжки", + "Continuous reading": "Безперервне читання", + "Preparing the pages…": "Готуємо сторінки…", + "Open book navigation": "Відкрити навігацію книжки", + "Toggle table of contents": "Перемкнути зміст", + "Close table of contents": "Закрити зміст", + "Decrease text size": "Зменшити розмір тексту", + "Increase text size": "Збільшити розмір тексту", + "Toggle night reading": "Перемкнути нічний режим читання", + "Bookmark this chapter": "Додати цей розділ до закладок", + "Chapter bookmarked": "Розділ додано до закладок", + "Bookmark removed": "Закладку видалено", + "Change reading theme": "Змінити тему читання", + "Light": "Світла", + "Rust": "Rust", + "Coal": "Вугільна", + "Navy": "Темно-синя", + "Ayu": "Ayu", + "Copy code": "Скопіювати код", + "Copied": "Скопійовано", + "Code copied": "Код скопійовано", + "Select code to copy": "Виділіть код, щоб скопіювати його", + "Scrollable table": "Таблиця з прокручуванням", + "Link to this section": "Посилання на цей розділ", + "View source on GitHub": "Переглянути вихідний код на GitHub", + "Skip to content": "Перейти до вмісту", + "Search ideas, code, chapters…": "Шукати ідеї, код і розділи…", + "Search ideas, code, chapters": "Шукати ідеї, код і розділи", + "Close search": "Закрити пошук", + "Search the complete book": "Шукати в усій книжці", + "to close": "щоб закрити", + "A keyword opens a new page.": "Ключове слово відкриває нову сторінку.", + "Search every chapter, code example and idea.": "Шукайте в усіх розділах, прикладах коду й ідеях.", + "YOUR BOOKMARK": "ВАШІ ЗАКЛАДКИ", + "START EXPLORING": "ПОЧАТИ ДОСЛІДЖЕННЯ", + "Continue reading": "Продовжити читання", + "No pages found.": "Сторінок не знайдено.", + "Try a concept such as “capability”, “Rust” or “meaning”.": "Спробуйте поняття, як-от «можливість», «Rust» чи «значення».", + "About the book": "Про книжку", + "Read the introduction": "Читати вступ", + "The book of": "Книжка про", + "small, powerful ideas.": "невеликі, але потужні ідеї.", + "The complete table of contents. Follow the chapters in order, or find the idea you came for.": "Повний зміст книжки. Читайте розділи по черзі або знайдіть потрібну ідею.", + "Begin with the meaning of a program. Explore denotations, compositionality, laws, interpretations, and the role of dependent types.": "Почніть зі значення програми. Дослідіть денотації, композиційність, закони, інтерпретації та роль залежних типів.", + "Carry meaning-first design into Rust: capability algebras, semantic types, derived operations, interpreters, evidence, and language pipelines.": "Перенесіть проєктування від значення в Rust: алгебри можливостей, семантичні типи, похідні операції, інтерпретатори, свідчення й конвеєри мов.", + "Explore execution models and useful machinery: operational semantics, the expression problem, free monads, continuations, and branching.": "Дослідіть моделі виконання й корисні механізми: операційну семантику, проблему виразів, вільні монади, продовження та розгалуження.", + "Connect the machinery back to meaning. Revisit semantics, the expression problem, referential transparency, and the EVM.": "Поверніть механізми до значення. Перегляньте семантику, проблему виразів, референційну прозорість і EVM.", + "Clear ideas. Composable programs.": "Чіткі ідеї. Композиційні програми.", + "Source on GitHub": "Вихідний код на GitHub", + "ALUX Network": "ALUX Network", + "Made of ideas.": "Створено з ідей.", + "Built to be explored.": "Створено для дослідження.", + "SMALL BUILDING BLOCKS.": "НЕВЕЛИКІ БУДІВЕЛЬНІ БЛОКИ.", + "WORLDS OF POSSIBILITY.": "СВІТИ МОЖЛИВОСТЕЙ.", + "My bookmarks": "Мої закладки", + "Remove bookmark": "Видалити закладку", + "Close bookmarks": "Закрити закладки", + "No bookmarks yet.": "Закладок поки немає.", + "Save a chapter with the bookmark button to continue reading here.": "Збережіть розділ кнопкою закладки, щоб продовжити читання тут.", + "Add bookmark": "Додати закладку", + "Bookmarked": "У закладках", + "Hide contents": "Сховати зміст", + "Show contents": "Показати зміст" +} diff --git a/web/locales/ui/vi.json b/web/locales/ui/vi.json new file mode 100644 index 0000000..5fb6a40 --- /dev/null +++ b/web/locales/ui/vi.json @@ -0,0 +1,140 @@ +{ + "A visitor-based structure that allows:": "Cấu trúc dựa trên visitor cho phép:", + "Solutions are possible, but they tend to require either:": "Có thể xây dựng giải pháp, nhưng thường cần một trong hai:", + "Execution state includes:": "Trạng thái thực thi bao gồm:", + "The semantic view — choosing what a program means before how it runs": "Góc nhìn ngữ nghĩa — xác định ý nghĩa chương trình trước khi chọn cách chạy", + "Design by meaning in Rust — building software from small capability traits": "Thiết kế theo ngữ nghĩa trong Rust — xây dựng phần mềm từ các đặc trưng năng lực nhỏ", + "Concepts — the programming machinery": "Khái niệm — cơ chế lập trình", + "Insights — connecting concepts back to the semantic view": "Nhận định — kết nối các khái niệm trở lại góc nhìn ngữ nghĩa", + "ALUX PROGRAMMING": "LẬP TRÌNH ALUX", + "Main navigation": "Điều hướng chính", + "ALUX Programming home": "Trang chủ Lập trình ALUX", + "Scrollable technical content": "Nội dung kỹ thuật có thể cuộn", + "The book could not load.": "Không thể tải sách.", + "Please refresh the page to try again.": "Vui lòng tải lại trang để thử lại.", + "Try again": "Thử lại", + "This page is uncharted.": "Trang này chưa được lập bản đồ.", + "Find your way back to the book.": "Hãy quay lại cuốn sách.", + "This language is unavailable. Please try again.": "Ngôn ngữ này hiện không khả dụng. Vui lòng thử lại.", + "Copy is unavailable. Select the code to copy it.": "Không thể sao chép. Hãy chọn đoạn mã để sao chép.", + "THE CHAPTER ATLAS": "BẢN ĐỒ CHƯƠNG", + "The chapter atlas": "Bản đồ chương", + "A world of ideas.": "Thế giới của những ý tưởng.", + "Choose a world.": "Hãy chọn một thế giới.", + "Follow an idea as far as it takes you.": "Theo đuổi một ý tưởng đến bất cứ nơi nào nó dẫn lối.", + "Browse as a list": "Duyệt dưới dạng danh sách", + "Interactive chapter map": "Bản đồ chương tương tác", + "⟦ parts ⟧ → whole": "⟦ phần ⟧ → toàn thể", + "Previous world": "Thế giới trước", + "Next world": "Thế giới tiếp theo", + "Enter this world": "Bước vào thế giới này", + "Start with what a program means. Explore denotations, compositionality, laws, and the relationship between meaning and representation.": "Bắt đầu từ ý nghĩa của chương trình. Khám phá ngữ nghĩa chỉ định, tính hợp thành, các định luật và mối quan hệ giữa ý nghĩa với biểu diễn.", + "Give meaning a concrete vocabulary. Explore capability traits, derived operations, interpreters, evidence, and compiler pipelines in Rust.": "Trao cho ý nghĩa một từ vựng cụ thể. Khám phá các đặc trưng năng lực, phép toán suy ra, bộ diễn giải, bằng chứng và quy trình biên dịch trong Rust.", + "Look beneath the surface of a program. Explore the structures and transformations that connect ideas to execution.": "Nhìn sâu hơn bề mặt chương trình. Khám phá các cấu trúc và phép biến đổi kết nối ý tưởng với thực thi.", + "Return to familiar ideas with a new perspective. Follow the connections between the semantic view and real programming machinery.": "Trở lại những ý tưởng quen thuộc với góc nhìn mới. Lần theo mối liên hệ giữa góc nhìn ngữ nghĩa và cơ chế lập trình thực tế.", + "Reading world": "Thế giới đọc sách", + "Choose a world": "Chọn một thế giới", + "Continue the journey": "Tiếp tục hành trình", + "Return to the table of contents": "Trở lại mục lục", + "First the meaning.": "Trước hết là ý nghĩa.", + "Then the machinery.": "Sau đó là cơ chế.", + "Explore another chapter": "Khám phá chương khác", + "Magic world": "Thế giới kỳ diệu", + "Real world": "Thế giới thực", + "Click to enter": "Nhấp để bước vào", + "Choose your world": "Chọn thế giới của bạn", + "Choose world": "Chọn thế giới", + "Language": "Ngôn ngữ", + "Programming": "Lập trình", + "PROGRAMMING": "LẬP TRÌNH", + "ALUX Programming": "Lập trình ALUX", + "The book": "Cuốn sách", + "Chapters": "Các chương", + "Search": "Tìm kiếm", + "Search the book": "Tìm kiếm", + "Table of contents": "Mục lục", + "Contents": "Nội dung", + "Introduction": "Giới thiệu", + "Welcome": "Chào mừng", + "The Semantic View": "Góc nhìn ngữ nghĩa", + "THE SEMANTIC VIEW": "GÓC NHÌN NGỮ NGHĨA", + "Design by Meaning in Rust": "Thiết kế theo ngữ nghĩa trong Rust", + "DESIGN BY MEANING IN RUST": "THIẾT KẾ THEO NGỮ NGHĨA TRONG RUST", + "Concepts": "Khái niệm", + "CONCEPTS": "KHÁI NIỆM", + "Insights": "Nhận định", + "INSIGHTS": "NHẬN ĐỊNH", + "Contributing": "Đóng góp", + "CONTRIBUTING": "ĐÓNG GÓP", + "Previous page": "Trang trước", + "Next page": "Trang tiếp", + "Previous chapter": "Chương trước", + "Next chapter": "Chương tiếp", + "Back to contents": "Trở lại mục lục", + "In this chapter": "Trong chương này", + "Original source": "Nguồn gốc", + "Scroll view": "Chế độ cuộn", + "Book view": "Chế độ đọc sách", + "Continuous reading": "Đọc liên tục", + "Preparing the pages…": "Đang chuẩn bị các trang…", + "Open book navigation": "Mở điều hướng sách", + "Toggle table of contents": "Bật/tắt mục lục", + "Close table of contents": "Đóng mục lục", + "Decrease text size": "Giảm cỡ chữ", + "Increase text size": "Tăng cỡ chữ", + "Toggle night reading": "Bật/tắt chế độ đọc ban đêm", + "Bookmark this chapter": "Đánh dấu chương này", + "Chapter bookmarked": "Đã đánh dấu chương", + "Bookmark removed": "Đã xóa dấu trang", + "Change reading theme": "Đổi giao diện đọc", + "Light": "Sáng", + "Rust": "Rust", + "Coal": "Than", + "Navy": "Xanh hải quân", + "Ayu": "Ayu", + "Copy code": "Sao chép mã", + "Copied": "Đã sao chép", + "Code copied": "Đã sao chép mã", + "Select code to copy": "Chọn mã để sao chép", + "Scrollable table": "Bảng có thể cuộn", + "Link to this section": "Liên kết đến mục này", + "View source on GitHub": "Xem mã nguồn trên GitHub", + "Skip to content": "Chuyển đến nội dung", + "Search ideas, code, chapters…": "Tìm ý tưởng, mã nguồn, chương…", + "Search ideas, code, chapters": "Tìm ý tưởng, mã nguồn, chương", + "Close search": "Đóng tìm kiếm", + "Search the complete book": "Tìm trong toàn bộ sách", + "to close": "để đóng", + "A keyword opens a new page.": "Một từ khóa mở ra trang mới.", + "Search every chapter, code example and idea.": "Tìm trong mọi chương, ví dụ mã và ý tưởng.", + "YOUR BOOKMARK": "DẤU TRANG CỦA BẠN", + "START EXPLORING": "BẮT ĐẦU KHÁM PHÁ", + "Continue reading": "Tiếp tục đọc", + "No pages found.": "Không tìm thấy trang nào.", + "Try a concept such as “capability”, “Rust” or “meaning”.": "Thử tìm khái niệm như “năng lực”, “Rust” hoặc “ý nghĩa”.", + "About the book": "Về cuốn sách", + "Read the introduction": "Đọc phần giới thiệu", + "The book of": "Cuốn sách về", + "small, powerful ideas.": "những ý tưởng nhỏ mà mạnh mẽ.", + "The complete table of contents. Follow the chapters in order, or find the idea you came for.": "Mục lục đầy đủ. Đọc lần lượt các chương hoặc tìm ý tưởng bạn cần.", + "Begin with the meaning of a program. Explore denotations, compositionality, laws, interpretations, and the role of dependent types.": "Bắt đầu từ ý nghĩa của chương trình. Khám phá ngữ nghĩa chỉ định, tính hợp thành, định luật, cách diễn giải và vai trò của kiểu phụ thuộc.", + "Carry meaning-first design into Rust: capability algebras, semantic types, derived operations, interpreters, evidence, and language pipelines.": "Đưa thiết kế lấy ý nghĩa làm trọng tâm vào Rust: đại số năng lực, kiểu ngữ nghĩa, phép toán suy ra, bộ diễn giải, bằng chứng và quy trình ngôn ngữ.", + "Explore execution models and useful machinery: operational semantics, the expression problem, free monads, continuations, and branching.": "Khám phá mô hình thực thi và cơ chế hữu ích: ngữ nghĩa vận hành, Bài toán biểu thức, monad tự do, tiếp nối và phân nhánh.", + "Connect the machinery back to meaning. Revisit semantics, the expression problem, referential transparency, and the EVM.": "Kết nối cơ chế trở lại ý nghĩa. Xem lại ngữ nghĩa, Bài toán biểu thức, tính minh bạch tham chiếu và EVM.", + "Clear ideas. Composable programs.": "Ý tưởng rõ ràng. Chương trình có thể hợp thành.", + "Source on GitHub": "Mã nguồn trên GitHub", + "ALUX Network": "ALUX Network", + "Made of ideas.": "Được tạo nên từ ý tưởng.", + "Built to be explored.": "Được xây dựng để khám phá.", + "SMALL BUILDING BLOCKS.": "NHỮNG KHỐI NỀN TẢNG NHỎ.", + "WORLDS OF POSSIBILITY.": "MUÔN VÀN KHẢ NĂNG.", + "My bookmarks": "Dấu trang của tôi", + "Remove bookmark": "Xóa dấu trang", + "Close bookmarks": "Đóng dấu trang", + "No bookmarks yet.": "Chưa có dấu trang nào.", + "Save a chapter with the bookmark button to continue reading here.": "Lưu chương bằng nút dấu trang để có thể tiếp tục đọc tại đây.", + "Add bookmark": "Thêm dấu trang", + "Bookmarked": "Đã đánh dấu", + "Hide contents": "Ẩn mục lục", + "Show contents": "Hiện mục lục" +} diff --git a/web/locales/ui/zh-hant.json b/web/locales/ui/zh-hant.json new file mode 100644 index 0000000..f23aaaf --- /dev/null +++ b/web/locales/ui/zh-hant.json @@ -0,0 +1,140 @@ +{ + "A visitor-based structure that allows:": "一種基於訪問者模式的結構,支援:", + "Solutions are possible, but they tend to require either:": "可以找到解決方案,但通常需要以下兩者之一:", + "Execution state includes:": "執行狀態包括:", + "The semantic view — choosing what a program means before how it runs": "語義視角:先選擇程式的意義,再決定它如何執行", + "Design by meaning in Rust — building software from small capability traits": "在 Rust 中以意義設計:從小型能力特徵構建軟體", + "Concepts — the programming machinery": "概念:程式設計機制", + "Insights — connecting concepts back to the semantic view": "洞見:把概念重新聯絡到語義視角", + "ALUX PROGRAMMING": "ALUX 程式設計", + "Main navigation": "主導航", + "ALUX Programming home": "ALUX 程式設計主頁", + "Scrollable technical content": "可滾動的技術內容", + "The book could not load.": "本書載入失敗。", + "Please refresh the page to try again.": "請重新整理頁面重試。", + "Try again": "重試", + "This page is uncharted.": "沒有找到這個頁面。", + "Find your way back to the book.": "請返回目錄繼續閱讀。", + "This language is unavailable. Please try again.": "暫時無法載入該語言,請重試。", + "Copy is unavailable. Select the code to copy it.": "暫時無法複製,請選中程式碼後手動複製。", + "THE CHAPTER ATLAS": "章節地圖", + "The chapter atlas": "章節地圖", + "A world of ideas.": "一個思想的世界。", + "Choose a world.": "選擇一個世界。", + "Follow an idea as far as it takes you.": "沿著一個想法,探索它能抵達的地方。", + "Browse as a list": "檢視目錄列表", + "Interactive chapter map": "互動式章節地圖", + "⟦ parts ⟧ → whole": "⟦ 部分 ⟧ → 整體", + "Previous world": "上一個世界", + "Next world": "下一個世界", + "Enter this world": "進入這個世界", + "Start with what a program means. Explore denotations, compositionality, laws, and the relationship between meaning and representation.": "從程式的意義出發,探索指稱、組合性、定律,以及意義與表示之間的關係。", + "Give meaning a concrete vocabulary. Explore capability traits, derived operations, interpreters, evidence, and compiler pipelines in Rust.": "賦予意義一套具體詞彙,探索 Rust 中的能力特徵、派生操作、直譯器、證據與編譯流水線。", + "Look beneath the surface of a program. Explore the structures and transformations that connect ideas to execution.": "深入程式表面之下,探索連線思想與執行的結構和變換。", + "Return to familiar ideas with a new perspective. Follow the connections between the semantic view and real programming machinery.": "以新的視角回看熟悉的概念,追尋語義視角與實際程式設計機制之間的聯絡。", + "Reading world": "閱讀世界", + "Choose a world": "選擇世界", + "Continue the journey": "繼續閱讀", + "Return to the table of contents": "返回全書目錄", + "First the meaning.": "先確定意義。", + "Then the machinery.": "再決定機制。", + "Explore another chapter": "閱讀其他章節", + "Magic world": "魔法世界", + "Real world": "現實世界", + "Click to enter": "點選進入", + "Choose your world": "選擇你的世界", + "Choose world": "選擇世界", + "Language": "語言", + "Programming": "程式設計", + "PROGRAMMING": "程式設計", + "ALUX Programming": "ALUX 程式設計", + "The book": "閱讀本書", + "Chapters": "章節", + "Search": "搜尋", + "Search the book": "搜尋", + "Table of contents": "全書目錄", + "Contents": "目錄", + "Introduction": "導言", + "Welcome": "歡迎", + "The Semantic View": "語義視角", + "THE SEMANTIC VIEW": "語義視角", + "Design by Meaning in Rust": "Rust 中的語義驅動設計", + "DESIGN BY MEANING IN RUST": "Rust 中的語義驅動設計", + "Concepts": "概念", + "CONCEPTS": "概念", + "Insights": "洞見", + "INSIGHTS": "洞見", + "Contributing": "參與貢獻", + "CONTRIBUTING": "參與貢獻", + "Previous page": "上一頁", + "Next page": "下一頁", + "Previous chapter": "上一章", + "Next chapter": "下一章", + "Back to contents": "返回目錄", + "In this chapter": "本章目錄", + "Original source": "原文原始碼", + "Scroll view": "滾動閱讀", + "Book view": "翻頁閱讀", + "Continuous reading": "連續閱讀", + "Preparing the pages…": "正在準備書頁…", + "Open book navigation": "開啟全書目錄", + "Toggle table of contents": "展開或收起目錄", + "Close table of contents": "關閉目錄", + "Decrease text size": "縮小字號", + "Increase text size": "放大字號", + "Toggle night reading": "切換夜間閱讀", + "Bookmark this chapter": "為本章新增書籤", + "Chapter bookmarked": "已新增章節書籤", + "Bookmark removed": "已移除書籤", + "Change reading theme": "切換閱讀主題", + "Light": "明亮", + "Rust": "Rust", + "Coal": "炭黑", + "Navy": "深藍", + "Ayu": "Ayu", + "Copy code": "複製程式碼", + "Copied": "已複製", + "Code copied": "程式碼已複製", + "Select code to copy": "請選擇程式碼後複製", + "Scrollable table": "可橫向滾動的表格", + "Link to this section": "本節連結", + "View source on GitHub": "在 GitHub 檢視原始碼", + "Skip to content": "跳到正文", + "Search ideas, code, chapters…": "搜尋概念、程式碼和章節…", + "Search ideas, code, chapters": "搜尋概念、程式碼和章節", + "Close search": "關閉搜尋", + "Search the complete book": "搜尋全書", + "to close": "關閉", + "A keyword opens a new page.": "一個關鍵詞,翻開下一頁。", + "Search every chapter, code example and idea.": "搜尋全書的章節、程式碼示例與概念。", + "YOUR BOOKMARK": "你的書籤", + "START EXPLORING": "開始探索", + "Continue reading": "繼續閱讀", + "No pages found.": "沒有找到相關頁面。", + "Try a concept such as “capability”, “Rust” or “meaning”.": "試試搜尋“能力”“Rust”或“意義”等概念。", + "About the book": "關於本書", + "Read the introduction": "閱讀導言", + "The book of": "一本匯聚", + "small, powerful ideas.": "小而有力思想的書。", + "The complete table of contents. Follow the chapters in order, or find the idea you came for.": "在完整目錄中按順序閱讀,或直接尋找你感興趣的概念。", + "Begin with the meaning of a program. Explore denotations, compositionality, laws, interpretations, and the role of dependent types.": "從程式的意義出發,探索指稱、組合性、定律、解釋,以及依賴型別的作用。", + "Carry meaning-first design into Rust: capability algebras, semantic types, derived operations, interpreters, evidence, and language pipelines.": "把意義優先的設計帶入 Rust:能力代數、語義型別、派生操作、直譯器、證據與語言流水線。", + "Explore execution models and useful machinery: operational semantics, the expression problem, free monads, continuations, and branching.": "探索執行模型與實用機制:操作語義、表示式問題、自由單子、續延與分支。", + "Connect the machinery back to meaning. Revisit semantics, the expression problem, referential transparency, and the EVM.": "把實現機制重新聯絡到意義,回看語義、表示式問題、引用透明性與 EVM。", + "Clear ideas. Composable programs.": "清楚的思想,可組合的程式。", + "Source on GitHub": "GitHub 原始碼", + "ALUX Network": "ALUX Network", + "Made of ideas.": "源於思想。", + "Built to be explored.": "為探索而構建。", + "SMALL BUILDING BLOCKS.": "小小積木。", + "WORLDS OF POSSIBILITY.": "無限可能。", + "My bookmarks": "我的書籤", + "Remove bookmark": "刪除書籤", + "Close bookmarks": "關閉書籤", + "No bookmarks yet.": "還沒有書籤。", + "Save a chapter with the bookmark button to continue reading here.": "點選閱讀工具欄的書籤按鈕,就能在這裡找到並繼續閱讀。", + "Add bookmark": "加入書籤", + "Bookmarked": "已加入書籤", + "Hide contents": "收起目錄", + "Show contents": "展開目錄" +} diff --git a/web/locales/ui/zh.json b/web/locales/ui/zh.json new file mode 100644 index 0000000..2b403a7 --- /dev/null +++ b/web/locales/ui/zh.json @@ -0,0 +1,140 @@ +{ + "A visitor-based structure that allows:": "一种基于访问者模式的结构,支持:", + "Solutions are possible, but they tend to require either:": "可以找到解决方案,但通常需要以下两者之一:", + "Execution state includes:": "执行状态包括:", + "The semantic view — choosing what a program means before how it runs": "语义视角:先选择程序的意义,再决定它如何运行", + "Design by meaning in Rust — building software from small capability traits": "Rust 中的语义驱动设计:从小型能力特征构建软件", + "Concepts — the programming machinery": "概念:编程机制", + "Insights — connecting concepts back to the semantic view": "洞见:把概念重新联系到语义视角", + "ALUX PROGRAMMING": "ALUX 编程", + "Main navigation": "主导航", + "ALUX Programming home": "ALUX 编程主页", + "Scrollable technical content": "可滚动的技术内容", + "The book could not load.": "本书加载失败。", + "Please refresh the page to try again.": "请刷新页面重试。", + "Try again": "重试", + "This page is uncharted.": "没有找到这个页面。", + "Find your way back to the book.": "请返回目录继续阅读。", + "This language is unavailable. Please try again.": "暂时无法加载该语言,请重试。", + "Copy is unavailable. Select the code to copy it.": "暂时无法复制,请选中代码后手动复制。", + "THE CHAPTER ATLAS": "章节地图", + "The chapter atlas": "章节地图", + "A world of ideas.": "一个思想的世界。", + "Choose a world.": "选择一个世界。", + "Follow an idea as far as it takes you.": "沿着一个想法,探索它能抵达的地方。", + "Browse as a list": "查看目录列表", + "Interactive chapter map": "交互式章节地图", + "⟦ parts ⟧ → whole": "⟦ 部分 ⟧ → 整体", + "Previous world": "上一个世界", + "Next world": "下一个世界", + "Enter this world": "进入这个世界", + "Start with what a program means. Explore denotations, compositionality, laws, and the relationship between meaning and representation.": "从程序的意义出发,探索指称、组合性、定律,以及意义与表示之间的关系。", + "Give meaning a concrete vocabulary. Explore capability traits, derived operations, interpreters, evidence, and compiler pipelines in Rust.": "赋予意义一套具体词汇,探索 Rust 中的能力特征、派生操作、解释器、证据与编译流水线。", + "Look beneath the surface of a program. Explore the structures and transformations that connect ideas to execution.": "深入程序表面之下,探索连接思想与执行的结构和变换。", + "Return to familiar ideas with a new perspective. Follow the connections between the semantic view and real programming machinery.": "以新的视角回看熟悉的概念,追寻语义视角与实际编程机制之间的联系。", + "Reading world": "阅读世界", + "Choose a world": "选择世界", + "Continue the journey": "继续阅读", + "Return to the table of contents": "返回全书目录", + "First the meaning.": "先确定意义。", + "Then the machinery.": "再决定机制。", + "Explore another chapter": "阅读其他章节", + "Magic world": "魔法世界", + "Real world": "现实世界", + "Click to enter": "点击进入", + "Choose your world": "选择你的世界", + "Choose world": "选择世界", + "Language": "语言", + "Programming": "编程", + "PROGRAMMING": "编程", + "ALUX Programming": "ALUX 编程", + "The book": "阅读本书", + "Chapters": "章节", + "Search": "搜索", + "Search the book": "搜索", + "Table of contents": "全书目录", + "Contents": "目录", + "Introduction": "导言", + "Welcome": "欢迎", + "The Semantic View": "语义视角", + "THE SEMANTIC VIEW": "语义视角", + "Design by Meaning in Rust": "Rust 中的语义驱动设计", + "DESIGN BY MEANING IN RUST": "Rust 中的语义驱动设计", + "Concepts": "概念", + "CONCEPTS": "概念", + "Insights": "洞见", + "INSIGHTS": "洞见", + "Contributing": "参与贡献", + "CONTRIBUTING": "参与贡献", + "Previous page": "上一页", + "Next page": "下一页", + "Previous chapter": "上一章", + "Next chapter": "下一章", + "Back to contents": "返回目录", + "In this chapter": "本章目录", + "Original source": "原文源码", + "Scroll view": "滚动阅读", + "Book view": "翻页阅读", + "Continuous reading": "连续阅读", + "Preparing the pages…": "正在准备书页…", + "Open book navigation": "打开全书目录", + "Toggle table of contents": "展开或收起目录", + "Close table of contents": "关闭目录", + "Decrease text size": "缩小字号", + "Increase text size": "放大字号", + "Toggle night reading": "切换夜间阅读", + "Bookmark this chapter": "为本章添加书签", + "Chapter bookmarked": "已添加章节书签", + "Bookmark removed": "已移除书签", + "Change reading theme": "切换阅读主题", + "Light": "明亮", + "Rust": "Rust", + "Coal": "炭黑", + "Navy": "深蓝", + "Ayu": "Ayu", + "Copy code": "复制代码", + "Copied": "已复制", + "Code copied": "代码已复制", + "Select code to copy": "请选择代码后复制", + "Scrollable table": "可横向滚动的表格", + "Link to this section": "本节链接", + "View source on GitHub": "在 GitHub 查看源码", + "Skip to content": "跳到正文", + "Search ideas, code, chapters…": "搜索概念、代码和章节…", + "Search ideas, code, chapters": "搜索概念、代码和章节", + "Close search": "关闭搜索", + "Search the complete book": "搜索全书", + "to close": "关闭", + "A keyword opens a new page.": "一个关键词,翻开下一页。", + "Search every chapter, code example and idea.": "搜索全书的章节、代码示例与概念。", + "YOUR BOOKMARK": "你的书签", + "START EXPLORING": "开始探索", + "Continue reading": "继续阅读", + "No pages found.": "没有找到相关页面。", + "Try a concept such as “capability”, “Rust” or “meaning”.": "试试搜索“能力”“Rust”或“意义”等概念。", + "About the book": "关于本书", + "Read the introduction": "阅读导言", + "The book of": "一本汇聚", + "small, powerful ideas.": "小而有力思想的书。", + "The complete table of contents. Follow the chapters in order, or find the idea you came for.": "在完整目录中按顺序阅读,或直接寻找你感兴趣的概念。", + "Begin with the meaning of a program. Explore denotations, compositionality, laws, interpretations, and the role of dependent types.": "从程序的意义出发,探索指称、组合性、定律、解释,以及依赖类型的作用。", + "Carry meaning-first design into Rust: capability algebras, semantic types, derived operations, interpreters, evidence, and language pipelines.": "把意义优先的设计带入 Rust:能力代数、语义类型、派生操作、解释器、证据与语言流水线。", + "Explore execution models and useful machinery: operational semantics, the expression problem, free monads, continuations, and branching.": "探索执行模型与实用机制:操作语义、表达式问题、自由单子、续延与分支。", + "Connect the machinery back to meaning. Revisit semantics, the expression problem, referential transparency, and the EVM.": "把实现机制重新联系到意义,回看语义、表达式问题、引用透明性与 EVM。", + "Clear ideas. Composable programs.": "清楚的思想,可组合的程序。", + "Source on GitHub": "GitHub 源码", + "ALUX Network": "ALUX Network", + "Made of ideas.": "源于思想。", + "Built to be explored.": "为探索而构建。", + "SMALL BUILDING BLOCKS.": "小小积木。", + "WORLDS OF POSSIBILITY.": "无限可能。", + "My bookmarks": "我的书签", + "Remove bookmark": "删除书签", + "Close bookmarks": "关闭书签", + "No bookmarks yet.": "还没有书签。", + "Save a chapter with the bookmark button to continue reading here.": "点击阅读工具栏的书签按钮,就能在这里找到并继续阅读。", + "Add bookmark": "添加书签", + "Bookmarked": "已加书签", + "Hide contents": "收起目录", + "Show contents": "展开目录" +} diff --git a/web/package.json b/web/package.json new file mode 100644 index 0000000..7350d4c --- /dev/null +++ b/web/package.json @@ -0,0 +1,43 @@ +{ + "name": "alux-programming-web", + "private": true, + "version": "0.1.0", + "type": "module", + "packageManager": "pnpm@11.25.0", + "scripts": { + "content": "node scripts/book.ts", + "dev": "pnpm content && vite", + "typecheck": "tsc --noEmit", + "lint": "tsc --noEmit --noUnusedLocals --noUnusedParameters --noFallthroughCasesInSwitch --allowUnreachableCode false --allowUnusedLabels false", + "build": "pnpm content && node scripts/check-locales.ts && pnpm typecheck && vite build && node scripts/routes.ts", + "preview": "vite preview", + "test": "pnpm content && pnpm typecheck && node --test tests/*.test.ts", + "test:browser": "node scripts/verify-reader.ts", + "test:acceptance": "node scripts/verify-page-flip.ts && node scripts/verify-acceptance.ts", + "test:generated": "node scripts/verify-generated.ts", + "share-preview": "node scripts/share-preview.ts" + }, + "dependencies": { + "@fontsource/cormorant-garamond": "^5.2.8", + "highlight.js": "^11.11.1", + "katex": "^0.16.22", + "lucide": "^0.468.0", + "page-flip": "^2.0.7", + "solid-js": "1.9.17", + "vite": "^7.1.0" + }, + "devDependencies": { + "@types/node": "^22.20.5", + "@types/turndown": "^5.0.6", + "linkedom": "^0.18.14", + "playwright": "1.64.1", + "smol-toml": "^1.9.1", + "turndown": "7.2.2", + "turndown-plugin-gfm": "1.0.2", + "typescript": "5.9.3", + "vite-plugin-solid": "2.11.14" + }, + "engines": { + "node": ">=22.18.0" + } +} diff --git a/web/patches/README.md b/web/patches/README.md new file mode 100644 index 0000000..f945e3e --- /dev/null +++ b/web/patches/README.md @@ -0,0 +1,17 @@ +# page-flip 2.0.7 lifecycle patch + +The reader owns and destroys one PageFlip instance per layout. Upstream 2.0.7 +continues its requestAnimationFrame loop after destroy and retains its resize +listener when useMouseEvents is false. Its delayed Safari init also survives +immediate destruction. This pinned pnpm patch stops the render loop, removes +handlers unconditionally, cancels init, and clears pages/event callbacks. +Readable upstream sources and both published bundles carry the same fix; the +upstream MIT license is retained. No global scheduling APIs are patched at runtime. + +`node scripts/verify-page-flip.ts` creates/destroys five actual instances, including +mid-turn and immediate destruction. Before: 5 active frames and 5 resize listeners; +after: 0 frames, 0 listeners, 0 hosts and no uncaught exceptions. Use a Playwright +Chromium installation or PLAYWRIGHT_CHROMIUM_EXECUTABLE. + +Remove this patch when a pinned upstream release fixes these defects and passes +the same regression. Do not edit node_modules as the delivery mechanism. diff --git a/web/patches/page-flip@2.0.7.patch b/web/patches/page-flip@2.0.7.patch new file mode 100644 index 0000000..c152ae3 --- /dev/null +++ b/web/patches/page-flip@2.0.7.patch @@ -0,0 +1,119 @@ +diff --git a/dist/js/page-flip.browser.js b/dist/js/page-flip.browser.js +index af350966b55c33936f3c4a9165efeefd3088eee3..5869c93761b35537dfeeee628e946ed9fb45edaa 100644 +--- a/dist/js/page-flip.browser.js ++++ b/dist/js/page-flip.browser.js +@@ -1 +1 @@ +-!function(t,e){"object"==typeof exports&&"undefined"!=typeof module?e(exports):"function"==typeof define&&define.amd?define(["exports"],e):e((t=t||self).St={})}(this,(function(t){"use strict";class e{constructor(t,e){this.state={angle:0,area:[],position:{x:0,y:0},hardAngle:0,hardDrawingAngle:0},this.createdDensity=e,this.nowDrawingDensity=this.createdDensity,this.render=t}setDensity(t){this.createdDensity=t,this.nowDrawingDensity=t}setDrawingDensity(t){this.nowDrawingDensity=t}setPosition(t){this.state.position=t}setAngle(t){this.state.angle=t}setArea(t){this.state.area=t}setHardDrawingAngle(t){this.state.hardDrawingAngle=t}setHardAngle(t){this.state.hardAngle=t,this.state.hardDrawingAngle=t}setOrientation(t){this.orientation=t}getDrawingDensity(){return this.nowDrawingDensity}getDensity(){return this.createdDensity}getHardAngle(){return this.state.hardAngle}}class i extends e{constructor(t,e,i){super(t,i),this.image=null,this.isLoad=!1,this.loadingAngle=0,this.image=new Image,this.image.src=e}draw(t){const e=this.render.getContext(),i=this.render.convertToGlobal(this.state.position),s=this.render.getRect().pageWidth,n=this.render.getRect().height;e.save(),e.translate(i.x,i.y),e.beginPath();for(let t of this.state.area)null!==t&&(t=this.render.convertToGlobal(t),e.lineTo(t.x-i.x,t.y-i.y));e.rotate(this.state.angle),e.clip(),this.isLoad?e.drawImage(this.image,0,0,s,n):this.drawLoader(e,{x:0,y:0},s,n),e.restore()}simpleDraw(t){const e=this.render.getRect(),i=this.render.getContext(),s=e.pageWidth,n=e.height,h=1===t?e.left+e.pageWidth:e.left,r=e.top;this.isLoad?i.drawImage(this.image,h,r,s,n):this.drawLoader(i,{x:h,y:r},s,n)}drawLoader(t,e,i,s){t.beginPath(),t.strokeStyle="rgb(200, 200, 200)",t.fillStyle="rgb(255, 255, 255)",t.lineWidth=1,t.rect(e.x+1,e.y+1,i-1,s-1),t.stroke(),t.fill();const n={x:e.x+i/2,y:e.y+s/2};t.beginPath(),t.lineWidth=10,t.arc(n.x,n.y,20,this.loadingAngle,3*Math.PI/2+this.loadingAngle),t.stroke(),t.closePath(),this.loadingAngle+=.07,this.loadingAngle>=2*Math.PI&&(this.loadingAngle=0)}load(){this.isLoad||(this.image.onload=()=>{this.isLoad=!0})}newTemporaryCopy(){return this}getTemporaryCopy(){return this}hideTemporaryCopy(){}}class s{constructor(t,e){this.pages=[],this.currentPageIndex=0,this.currentSpreadIndex=0,this.landscapeSpread=[],this.portraitSpread=[],this.render=e,this.app=t,this.currentPageIndex=0,this.isShowCover=this.app.getSettings().showCover}destroy(){this.pages=[]}createSpread(){this.landscapeSpread=[],this.portraitSpread=[];for(let t=0;t=0&&t0?this.pages[e-1]:null}getFlippingPage(t){const e=this.currentSpreadIndex;if("portrait"===this.render.getOrientation())return 0===t?this.pages[e].newTemporaryCopy():this.pages[e-1];{const i=0===t?this.getSpread()[e+1]:this.getSpread()[e-1];return 1===i.length||0===t?this.pages[i[0]]:this.pages[i[1]]}}getBottomPage(t){const e=this.currentSpreadIndex;if("portrait"===this.render.getOrientation())return 0===t?this.pages[e+1]:this.pages[e-1];{const i=0===t?this.getSpread()[e+1]:this.getSpread()[e-1];return 1===i.length?this.pages[i[0]]:0===t?this.pages[i[1]]:this.pages[i[0]]}}showNext(){this.currentSpreadIndex0&&(this.currentSpreadIndex--,this.showSpread())}getCurrentPageIndex(){return this.currentPageIndex}show(t=null){if(null===t&&(t=this.currentPageIndex),t<0||t>=this.pages.length)return;const e=this.getSpreadIndexByPage(t);null!==e&&(this.currentSpreadIndex=e,this.showSpread())}getCurrentSpreadIndex(){return this.currentSpreadIndex}setCurrentSpreadIndex(t){if(!(t>=0&&t=t.left&&e.x<=t.width+t.left&&e.y>=t.top&&e.y<=t.top+t.height?e:null}static GetRotatedPoint(t,e,i){return{x:t.x*Math.cos(i)+t.y*Math.sin(i)+e.x,y:t.y*Math.cos(i)-t.x*Math.sin(i)+e.y}}static LimitPointToCircle(t,e,i){if(h.GetDistanceBetweenTwoPoint(t,i)<=e)return i;const s=t.x,n=t.y,r=i.x,o=i.y;let a=Math.sqrt(Math.pow(e,2)*Math.pow(s-r,2)/(Math.pow(s-r,2)+Math.pow(n-o,2)))+s;i.x<0&&(a*=-1);let g=(a-s)*(n-o)/(s-r)+n;return s-r+n===0&&(g=e),{x:a,y:g}}static GetIntersectBetweenTwoSegment(t,e,i){return h.PointInRect(t,h.GetIntersectBeetwenTwoLine(e,i))}static GetIntersectBeetwenTwoLine(t,e){const i=t[0].y-t[1].y,s=e[0].y-e[1].y,n=t[1].x-t[0].x,h=e[1].x-e[0].x,r=t[0].x*t[1].y-t[1].x*t[0].y,o=e[0].x*e[1].y-e[1].x*e[0].y,a=i*o-s*r,g=n*o-h*r,l=-(r*h-o*n)/(i*h-s*n),d=-(i*o-s*r)/(i*h-s*n);if(isFinite(l)&&isFinite(d))return{x:l,y:d};if(Math.abs(a-g)<.1)throw new Error("Segment included");return null}static GetCordsFromTwoPoint(t,e){const i=Math.abs(t.x-e.x),s=Math.abs(t.y-e.y),n=Math.max(i,s),h=[t];function r(t,e,i,s,n){return e>t?t+n*(i/s):e=10&&t.push(this.sideIntersectPoint):"top"===this.corner&&t.push({x:this.pageWidth,y:this.pageHeight}),t.push(this.bottomIntersectPoint),t.push(this.topIntersectPoint),t}getAngle(){return 0===this.direction?-this.angle:this.angle}getRect(){return this.rect}getPosition(){return this.position}getActiveCorner(){return 0===this.direction?this.rect.topLeft:this.rect.topRight}getDirection(){return this.direction}getFlippingProgress(){return Math.abs((this.position.x-this.pageWidth)/(2*this.pageWidth)*100)}getCorner(){return this.corner}getBottomPagePosition(){return 1===this.direction?{x:this.pageWidth,y:0}:{x:0,y:0}}getShadowStartPoint(){return"top"===this.corner?this.topIntersectPoint:null!==this.sideIntersectPoint?this.sideIntersectPoint:this.topIntersectPoint}getShadowAngle(){const t=h.GetAngleBetweenTwoLine(this.getSegmentToShadowLine(),[{x:0,y:0},{x:this.pageWidth,y:0}]);return 0===this.direction?t:Math.PI-t}calcAngleAndPosition(t){let e=t;if(this.updateAngleAndGeometry(e),e="top"===this.corner?this.checkPositionAtCenterLine(e,{x:0,y:0},{x:0,y:this.pageHeight}):this.checkPositionAtCenterLine(e,{x:0,y:this.pageHeight},{x:0,y:0}),Math.abs(e.x-this.pageWidth)<1&&Math.abs(e.y)<1)throw new Error("Point is too small");return e}updateAngleAndGeometry(t){this.angle=this.calculateAngle(t),this.rect=this.getPageRect(t)}calculateAngle(t){const e=this.pageWidth-t.x+1,i="bottom"===this.corner?this.pageHeight-t.y:t.y;let s=2*Math.acos(e/Math.sqrt(i*i+e*e));i<0&&(s=-s);const n=Math.PI-s;if(!isFinite(s)||n>=0&&n<.003)throw new Error("The G point is too small");return"bottom"===this.corner&&(s=-s),s}getPageRect(t){return"top"===this.corner?this.getRectFromBasePoint([{x:0,y:0},{x:this.pageWidth,y:0},{x:0,y:this.pageHeight},{x:this.pageWidth,y:this.pageHeight}],t):this.getRectFromBasePoint([{x:0,y:-this.pageHeight},{x:this.pageWidth,y:-this.pageHeight},{x:0,y:0},{x:this.pageWidth,y:0}],t)}getRectFromBasePoint(t,e){return{topLeft:this.getRotatedPoint(t[0],e),topRight:this.getRotatedPoint(t[1],e),bottomLeft:this.getRotatedPoint(t[2],e),bottomRight:this.getRotatedPoint(t[3],e)}}getRotatedPoint(t,e){return{x:t.x*Math.cos(this.angle)+t.y*Math.sin(this.angle)+e.x,y:t.y*Math.cos(this.angle)-t.x*Math.sin(this.angle)+e.y}}calculateIntersectPoint(t){const e={left:-1,top:-1,width:this.pageWidth+2,height:this.pageHeight+2};"top"===this.corner?(this.topIntersectPoint=h.GetIntersectBetweenTwoSegment(e,[t,this.rect.topRight],[{x:0,y:0},{x:this.pageWidth,y:0}]),this.sideIntersectPoint=h.GetIntersectBetweenTwoSegment(e,[t,this.rect.bottomLeft],[{x:this.pageWidth,y:0},{x:this.pageWidth,y:this.pageHeight}]),this.bottomIntersectPoint=h.GetIntersectBetweenTwoSegment(e,[this.rect.bottomLeft,this.rect.bottomRight],[{x:0,y:this.pageHeight},{x:this.pageWidth,y:this.pageHeight}])):(this.topIntersectPoint=h.GetIntersectBetweenTwoSegment(e,[this.rect.topLeft,this.rect.topRight],[{x:0,y:0},{x:this.pageWidth,y:0}]),this.sideIntersectPoint=h.GetIntersectBetweenTwoSegment(e,[t,this.rect.topLeft],[{x:this.pageWidth,y:0},{x:this.pageWidth,y:this.pageHeight}]),this.bottomIntersectPoint=h.GetIntersectBetweenTwoSegment(e,[this.rect.bottomLeft,this.rect.bottomRight],[{x:0,y:this.pageHeight},{x:this.pageWidth,y:this.pageHeight}]))}checkPositionAtCenterLine(t,e,i){let s=t;const n=h.LimitPointToCircle(e,this.pageWidth,s);s!==n&&(s=n,this.updateAngleAndGeometry(s));const r=Math.sqrt(Math.pow(this.pageWidth,2)+Math.pow(this.pageHeight,2));let o=this.rect.bottomRight,a=this.rect.topLeft;if("bottom"===this.corner&&(o=this.rect.topRight,a=this.rect.bottomLeft),o.x<=0){const t=h.LimitPointToCircle(i,r,a);t!==s&&(s=t,this.updateAngleAndGeometry(s))}return s}getSegmentToShadowLine(){const t=this.getShadowStartPoint();return[t,t!==this.sideIntersectPoint&&null!==this.sideIntersectPoint?this.sideIntersectPoint:this.bottomIntersectPoint]}}class g{constructor(t,e){this.flippingPage=null,this.bottomPage=null,this.calc=null,this.state="read",this.render=t,this.app=e}fold(t){this.setState("user_fold"),null===this.calc&&this.start(t),this.do(this.render.convertToPage(t))}flip(t){if(this.app.getSettings().disableFlipByClick&&!this.isPointOnCorners(t))return;if(null!==this.calc&&this.render.finishAnimation(),!this.start(t))return;const e=this.getBoundsRect();this.setState("flipping");const i=e.height/10,s="bottom"===this.calc.getCorner()?e.height-i:i,n="bottom"===this.calc.getCorner()?e.height:0;this.calc.calc({x:e.pageWidth-i,y:s}),this.animateFlippingTo({x:e.pageWidth-i,y:s},{x:-e.pageWidth,y:n},!0)}start(t){this.reset();const e=this.render.convertToBook(t),i=this.getBoundsRect(),s=this.getDirectionByPoint(e),n=e.y>=i.height/2?"bottom":"top";if(!this.checkDirection(s))return!1;try{if(this.flippingPage=this.app.getPageCollection().getFlippingPage(s),this.bottomPage=this.app.getPageCollection().getBottomPage(s),"landscape"===this.render.getOrientation())if(1===s){const t=this.app.getPageCollection().nextBy(this.flippingPage);null!==t&&this.flippingPage.getDensity()!==t.getDensity()&&(this.flippingPage.setDrawingDensity("hard"),t.setDrawingDensity("hard"))}else{const t=this.app.getPageCollection().prevBy(this.flippingPage);null!==t&&this.flippingPage.getDensity()!==t.getDensity()&&(this.flippingPage.setDrawingDensity("hard"),t.setDrawingDensity("hard"))}return this.render.setDirection(s),this.calc=new a(s,n,i.pageWidth.toString(10),i.height.toString(10)),!0}catch(t){return!1}}do(t){if(null!==this.calc&&this.calc.calc(t)){const t=this.calc.getFlippingProgress();this.bottomPage.setArea(this.calc.getBottomClipArea()),this.bottomPage.setPosition(this.calc.getBottomPagePosition()),this.bottomPage.setAngle(0),this.bottomPage.setHardAngle(0),this.flippingPage.setArea(this.calc.getFlippingClipArea()),this.flippingPage.setPosition(this.calc.getActiveCorner()),this.flippingPage.setAngle(this.calc.getAngle()),0===this.calc.getDirection()?this.flippingPage.setHardAngle(90*(200-2*t)/100):this.flippingPage.setHardAngle(-90*(200-2*t)/100),this.render.setPageRect(this.calc.getRect()),this.render.setBottomPage(this.bottomPage),this.render.setFlippingPage(this.flippingPage),this.render.setShadowData(this.calc.getShadowStartPoint(),this.calc.getShadowAngle(),t,this.calc.getDirection())}}flipToPage(t,e){const i=this.app.getPageCollection().getCurrentSpreadIndex(),s=this.app.getPageCollection().getSpreadIndexByPage(t);try{s>i&&(this.app.getPageCollection().setCurrentSpreadIndex(s-1),this.flipNext(e)),sthis.do(t));const o=this.getAnimationDuration(n.length);this.render.startAnimation(r,o,()=>{this.calc&&(i&&(1===this.calc.getDirection()?this.app.turnToPrevPage():this.app.turnToNextPage()),s&&(this.render.setBottomPage(null),this.render.setFlippingPage(null),this.render.clearShadow(),this.setState("read"),this.reset()))})}getCalculation(){return this.calc}getState(){return this.state}setState(t){this.state!==t&&(this.app.updateState(t),this.state=t)}getDirectionByPoint(t){const e=this.getBoundsRect();if("portrait"===this.render.getOrientation()){if(t.x-e.pageWidth<=e.width/5)return 1}else if(t.x=1e3?e:t/1e3*e}checkDirection(t){return 0===t?this.app.getCurrentPageIndex()=1}reset(){this.calc=null,this.flippingPage=null,this.bottomPage=null}getBoundsRect(){return this.render.getRect()}checkState(...t){for(const e of t)if(this.state===e)return!0;return!1}isPointOnCorners(t){const e=this.getBoundsRect(),i=e.pageWidth,s=Math.sqrt(Math.pow(i,2)+Math.pow(e.height,2))/5,n=this.render.convertToBook(t);return n.x>0&&n.y>0&&n.xe.width-s)&&(n.ye.height-s)}}class l{constructor(t,e){this.leftPage=null,this.rightPage=null,this.flippingPage=null,this.bottomPage=null,this.direction=null,this.orientation=null,this.shadow=null,this.animation=null,this.pageRect=null,this.boundsRect=null,this.timer=0,this.safari=!1,this.setting=e,this.app=t;const i=new RegExp("Version\\/[\\d\\.]+.*Safari/");this.safari=null!==i.exec(window.navigator.userAgent)}render(t){if(null!==this.animation){const e=Math.round((t-this.animation.startedAt)/this.animation.durationFrame);e{this.render(e),requestAnimationFrame(t)};requestAnimationFrame(t)}startAnimation(t,e,i){this.finishAnimation(),this.animation={frames:t,duration:e,durationFrame:e/t.length,onAnimateEnd:i,startedAt:this.timer}}finishAnimation(){null!==this.animation&&(this.animation.frames[this.animation.frames.length-1](),null!==this.animation.onAnimateEnd&&this.animation.onAnimateEnd()),this.animation=null}update(){this.boundsRect=null;const t=this.calculateBoundsRect();this.orientation!==t&&(this.orientation=t,this.app.updateOrientation(t))}calculateBoundsRect(){let t="landscape";const e=this.getBlockWidth(),i=e/2,s=this.getBlockHeight()/2,n=this.setting.width/this.setting.height;let h=this.setting.width,r=this.setting.height,o=i-h;return"stretch"===this.setting.size?(e<2*this.setting.minWidth&&this.app.getSettings().usePortrait&&(t="portrait"),h="portrait"===t?this.getBlockWidth():this.getBlockWidth()/2,h>this.setting.maxWidth&&(h=this.setting.maxWidth),r=h/n,r>this.getBlockHeight()&&(r=this.getBlockHeight(),h=r*n),o="portrait"===t?i-h/2-h:i-h):e<2*h&&this.app.getSettings().usePortrait&&(t="portrait",o=i-h/2-h),this.boundsRect={left:o,top:s-r/2,width:2*h,height:r,pageWidth:h},t}setShadowData(t,e,i,s){if(!this.app.getSettings().drawShadow)return;const n=100*this.getSettings().maxShadowOpacity;this.shadow={pos:t,angle:e,width:3*this.getRect().pageWidth/4*i/100,opacity:(100-i)*n/100/100,direction:s,progress:2*i}}clearShadow(){this.shadow=null}getBlockWidth(){return this.app.getUI().getDistElement().offsetWidth}getBlockHeight(){return this.app.getUI().getDistElement().offsetHeight}getDirection(){return this.direction}getRect(){return null===this.boundsRect&&this.calculateBoundsRect(),this.boundsRect}getSettings(){return this.app.getSettings()}getOrientation(){return this.orientation}setPageRect(t){this.pageRect=t}setDirection(t){this.direction=t}setRightPage(t){null!==t&&t.setOrientation(1),this.rightPage=t}setLeftPage(t){null!==t&&t.setOrientation(0),this.leftPage=t}setBottomPage(t){null!==t&&t.setOrientation(1===this.direction?0:1),this.bottomPage=t}setFlippingPage(t){null!==t&&t.setOrientation(0===this.direction&&"portrait"!==this.orientation?0:1),this.flippingPage=t}convertToBook(t){const e=this.getRect();return{x:t.x-e.left,y:t.y-e.top}}isSafari(){return this.safari}convertToPage(t,e){e||(e=this.direction);const i=this.getRect();return{x:0===e?t.x-i.left-i.width/2:i.width/2-t.x+i.left,y:t.y-i.top}}convertToGlobal(t,e){if(e||(e=this.direction),null==t)return null;const i=this.getRect();return{x:0===e?t.x+i.left+i.width/2:i.width/2-t.x+i.left,y:t.y+i.top}}convertRectToGlobal(t,e){return e||(e=this.direction),{topLeft:this.convertToGlobal(t.topLeft,e),topRight:this.convertToGlobal(t.topRight,e),bottomLeft:this.convertToGlobal(t.bottomLeft,e),bottomRight:this.convertToGlobal(t.bottomRight,e)}}}class d extends l{constructor(t,e,i){super(t,e),this.canvas=i,this.ctx=i.getContext("2d")}getContext(){return this.ctx}reload(){}drawFrame(){this.clear(),"portrait"!==this.orientation&&null!=this.leftPage&&this.leftPage.simpleDraw(0),null!=this.rightPage&&this.rightPage.simpleDraw(1),null!=this.bottomPage&&this.bottomPage.draw(),this.drawBookShadow(),null!=this.flippingPage&&this.flippingPage.draw(),null!=this.shadow&&(this.drawOuterShadow(),this.drawInnerShadow());const t=this.getRect();"portrait"===this.orientation&&(this.ctx.beginPath(),this.ctx.rect(t.left+t.pageWidth,t.top,t.width,t.height),this.ctx.clip())}drawBookShadow(){const t=this.getRect();this.ctx.save(),this.ctx.beginPath();const e=t.width/20;this.ctx.rect(t.left,t.top,t.width,t.height);const i={x:t.left+t.width/2-e/2,y:0};this.ctx.translate(i.x,i.y);const s=this.ctx.createLinearGradient(0,0,e,0);s.addColorStop(0,"rgba(0, 0, 0, 0)"),s.addColorStop(.4,"rgba(0, 0, 0, 0.2)"),s.addColorStop(.49,"rgba(0, 0, 0, 0.1)"),s.addColorStop(.5,"rgba(0, 0, 0, 0.5)"),s.addColorStop(.51,"rgba(0, 0, 0, 0.4)"),s.addColorStop(1,"rgba(0, 0, 0, 0)"),this.ctx.clip(),this.ctx.fillStyle=s,this.ctx.fillRect(0,0,e,2*t.height),this.ctx.restore()}drawOuterShadow(){const t=this.getRect();this.ctx.save(),this.ctx.beginPath(),this.ctx.rect(t.left,t.top,t.width,t.height);const e=this.convertToGlobal({x:this.shadow.pos.x,y:this.shadow.pos.y});this.ctx.translate(e.x,e.y),this.ctx.rotate(Math.PI+this.shadow.angle+Math.PI/2);const i=this.ctx.createLinearGradient(0,0,this.shadow.width,0);0===this.shadow.direction?(this.ctx.translate(0,-100),i.addColorStop(0,"rgba(0, 0, 0, "+this.shadow.opacity+")"),i.addColorStop(1,"rgba(0, 0, 0, 0)")):(this.ctx.translate(-this.shadow.width,-100),i.addColorStop(0,"rgba(0, 0, 0, 0)"),i.addColorStop(1,"rgba(0, 0, 0, "+this.shadow.opacity+")")),this.ctx.clip(),this.ctx.fillStyle=i,this.ctx.fillRect(0,0,this.shadow.width,2*t.height),this.ctx.restore()}drawInnerShadow(){const t=this.getRect();this.ctx.save(),this.ctx.beginPath();const e=this.convertToGlobal({x:this.shadow.pos.x,y:this.shadow.pos.y}),i=this.convertRectToGlobal(this.pageRect);this.ctx.moveTo(i.topLeft.x,i.topLeft.y),this.ctx.lineTo(i.topRight.x,i.topRight.y),this.ctx.lineTo(i.bottomRight.x,i.bottomRight.y),this.ctx.lineTo(i.bottomLeft.x,i.bottomLeft.y),this.ctx.translate(e.x,e.y),this.ctx.rotate(Math.PI+this.shadow.angle+Math.PI/2);const s=3*this.shadow.width/4,n=this.ctx.createLinearGradient(0,0,s,0);0===this.shadow.direction?(this.ctx.translate(-s,-100),n.addColorStop(1,"rgba(0, 0, 0, "+this.shadow.opacity+")"),n.addColorStop(.9,"rgba(0, 0, 0, 0.05)"),n.addColorStop(.7,"rgba(0, 0, 0, "+this.shadow.opacity+")"),n.addColorStop(0,"rgba(0, 0, 0, 0)")):(this.ctx.translate(0,-100),n.addColorStop(0,"rgba(0, 0, 0, "+this.shadow.opacity+")"),n.addColorStop(.1,"rgba(0, 0, 0, 0.05)"),n.addColorStop(.3,"rgba(0, 0, 0, "+this.shadow.opacity+")"),n.addColorStop(1,"rgba(0, 0, 0, 0)")),this.ctx.clip(),this.ctx.fillStyle=n,this.ctx.fillRect(0,0,s,2*t.height),this.ctx.restore()}clear(){this.ctx.fillStyle="white",this.ctx.fillRect(0,0,this.canvas.width,this.canvas.height)}}class p{constructor(t,e,i){this.touchPoint=null,this.swipeTimeout=250,this.onResize=()=>{this.update()},this.onMouseDown=t=>{if(this.checkTarget(t.target)){const e=this.getMousePos(t.clientX,t.clientY);this.app.startUserTouch(e),t.preventDefault()}},this.onTouchStart=t=>{if(this.checkTarget(t.target)&&t.changedTouches.length>0){const e=t.changedTouches[0],i=this.getMousePos(e.clientX,e.clientY);this.touchPoint={point:i,time:Date.now()},setTimeout(()=>{null!==this.touchPoint&&this.app.startUserTouch(i)},this.swipeTimeout),this.app.getSettings().mobileScrollSupport||t.preventDefault()}},this.onMouseUp=t=>{const e=this.getMousePos(t.clientX,t.clientY);this.app.userStop(e)},this.onMouseMove=t=>{const e=this.getMousePos(t.clientX,t.clientY);this.app.userMove(e,!1)},this.onTouchMove=t=>{if(t.changedTouches.length>0){const e=t.changedTouches[0],i=this.getMousePos(e.clientX,e.clientY);this.app.getSettings().mobileScrollSupport?(null!==this.touchPoint&&(Math.abs(this.touchPoint.point.x-i.x)>10||"read"!==this.app.getState())&&t.cancelable&&this.app.userMove(i,!0),"read"!==this.app.getState()&&t.preventDefault()):this.app.userMove(i,!0)}},this.onTouchEnd=t=>{if(t.changedTouches.length>0){const e=t.changedTouches[0],i=this.getMousePos(e.clientX,e.clientY);let s=!1;if(null!==this.touchPoint){const t=i.x-this.touchPoint.point.x,e=Math.abs(i.y-this.touchPoint.point.y);Math.abs(t)>this.swipeDistance&&e<2*this.swipeDistance&&Date.now()-this.touchPoint.time0?this.app.flipPrev(this.touchPoint.point.y'),this.wrapper=t.querySelector(".stf__wrapper"),this.app=e;const s=this.app.getSettings().usePortrait?1:2;t.style.minWidth=i.minWidth*s+"px",t.style.minHeight=i.minHeight+"px","fixed"===i.size&&(t.style.minWidth=i.width*s+"px",t.style.minHeight=i.height+"px"),i.autoSize&&(t.style.width="100%",t.style.maxWidth=2*i.maxWidth+"px"),t.style.display="block",window.addEventListener("resize",this.onResize,!1),this.swipeDistance=i.swipeDistance}destroy(){this.app.getSettings().useMouseEvents&&this.removeHandlers(),this.distElement.remove(),this.wrapper.remove()}getDistElement(){return this.distElement}getWrapper(){return this.wrapper}setOrientationStyle(t){this.wrapper.classList.remove("--portrait","--landscape"),"portrait"===t?(this.app.getSettings().autoSize&&(this.wrapper.style.paddingBottom=this.app.getSettings().height/this.app.getSettings().width*100+"%"),this.wrapper.classList.add("--portrait")):(this.app.getSettings().autoSize&&(this.wrapper.style.paddingBottom=this.app.getSettings().height/(2*this.app.getSettings().width)*100+"%"),this.wrapper.classList.add("--landscape")),this.update()}removeHandlers(){window.removeEventListener("resize",this.onResize),this.distElement.removeEventListener("mousedown",this.onMouseDown),this.distElement.removeEventListener("touchstart",this.onTouchStart),window.removeEventListener("mousemove",this.onMouseMove),window.removeEventListener("touchmove",this.onTouchMove),window.removeEventListener("mouseup",this.onMouseUp),window.removeEventListener("touchend",this.onTouchEnd)}setHandlers(){window.addEventListener("resize",this.onResize,!1),this.app.getSettings().useMouseEvents&&(this.distElement.addEventListener("mousedown",this.onMouseDown),this.distElement.addEventListener("touchstart",this.onTouchStart),window.addEventListener("mousemove",this.onMouseMove),window.addEventListener("touchmove",this.onTouchMove,{passive:!this.app.getSettings().mobileScrollSupport}),window.addEventListener("mouseup",this.onMouseUp),window.addEventListener("touchend",this.onTouchEnd))}getMousePos(t,e){const i=this.distElement.getBoundingClientRect();return{x:t-i.left,y:e-i.top}}checkTarget(t){return!this.app.getSettings().clickEventForward||!["a","button"].includes(t.tagName.toLowerCase())}}class c extends p{constructor(t,e,i,s){super(t,e,i),this.wrapper.insertAdjacentHTML("afterbegin",'
'),this.distElement=t.querySelector(".stf__block"),this.items=s;for(const t of s)this.distElement.appendChild(t);this.setHandlers()}clear(){for(const t of this.items)this.parentElement.appendChild(t)}updateItems(t){this.removeHandlers(),this.distElement.innerHTML="";for(const e of t)this.distElement.appendChild(e);this.items=t,this.setHandlers()}update(){this.app.getRender().update()}}class u extends p{constructor(t,e,i){super(t,e,i),this.wrapper.innerHTML='',this.canvas=t.querySelectorAll("canvas")[0],this.distElement=this.canvas,this.resizeCanvas(),this.setHandlers()}resizeCanvas(){const t=getComputedStyle(this.canvas),e=parseInt(t.getPropertyValue("width"),10),i=parseInt(t.getPropertyValue("height"),10);this.canvas.width=e,this.canvas.height=i}getCanvas(){return this.canvas}update(){this.resizeCanvas(),this.app.getRender().update()}}class w extends l{constructor(t,e,i){super(t,e),this.outerShadow=null,this.innerShadow=null,this.hardShadow=null,this.hardInnerShadow=null,this.element=i,this.createShadows()}createShadows(){this.element.insertAdjacentHTML("beforeend",'
\n
\n
\n
'),this.outerShadow=this.element.querySelector(".stf__outerShadow"),this.innerShadow=this.element.querySelector(".stf__innerShadow"),this.hardShadow=this.element.querySelector(".stf__hardShadow"),this.hardInnerShadow=this.element.querySelector(".stf__hardInnerShadow")}clearShadow(){super.clearShadow(),this.outerShadow.style.cssText="display: none",this.innerShadow.style.cssText="display: none",this.hardShadow.style.cssText="display: none",this.hardInnerShadow.style.cssText="display: none"}reload(){this.element.querySelector(".stf__outerShadow")||this.createShadows()}drawHardInnerShadow(){const t=this.getRect(),e=this.shadow.progress>100?200-this.shadow.progress:this.shadow.progress;let i=(100-e)*(2.5*t.pageWidth)/100+20;i>t.pageWidth&&(i=t.pageWidth);let s=`\n display: block;\n z-index: ${(this.getSettings().startZIndex+5).toString(10)};\n width: ${i}px;\n height: ${t.height}px;\n background: linear-gradient(to right,\n rgba(0, 0, 0, ${this.shadow.opacity*e/100}) 5%,\n rgba(0, 0, 0, 0) 100%);\n left: ${t.left+t.width/2}px;\n transform-origin: 0 0;\n `;s+=0===this.getDirection()&&this.shadow.progress>100||1===this.getDirection()&&this.shadow.progress<=100?"transform: translate3d(0, 0, 0);":"transform: translate3d(0, 0, 0) rotateY(180deg);",this.hardInnerShadow.style.cssText=s}drawHardOuterShadow(){const t=this.getRect();let e=(100-(this.shadow.progress>100?200-this.shadow.progress:this.shadow.progress))*(2.5*t.pageWidth)/100+20;e>t.pageWidth&&(e=t.pageWidth);let i=`\n display: block;\n z-index: ${(this.getSettings().startZIndex+4).toString(10)};\n width: ${e}px;\n height: ${t.height}px;\n background: linear-gradient(to left, rgba(0, 0, 0, ${this.shadow.opacity}) 5%, rgba(0, 0, 0, 0) 100%);\n left: ${t.left+t.width/2}px;\n transform-origin: 0 0;\n `;i+=0===this.getDirection()&&this.shadow.progress>100||1===this.getDirection()&&this.shadow.progress<=100?"transform: translate3d(0, 0, 0) rotateY(180deg);":"transform: translate3d(0, 0, 0);",this.hardShadow.style.cssText=i}drawInnerShadow(){const t=this.getRect(),e=3*this.shadow.width/4,i=0===this.getDirection()?e:0,s=0===this.getDirection()?"to left":"to right",n=this.convertToGlobal(this.shadow.pos),r=this.shadow.angle+3*Math.PI/2,o=[this.pageRect.topLeft,this.pageRect.topRight,this.pageRect.bottomRight,this.pageRect.bottomLeft];let a="polygon( ";for(const t of o){let e=1===this.getDirection()?{x:-t.x+this.shadow.pos.x,y:t.y-this.shadow.pos.y}:{x:t.x-this.shadow.pos.x,y:t.y-this.shadow.pos.y};e=h.GetRotatedPoint(e,{x:i,y:100},r),a+=e.x+"px "+e.y+"px, "}a=a.slice(0,-2),a+=")";const g=`\n display: block;\n z-index: ${(this.getSettings().startZIndex+10).toString(10)};\n width: ${e}px;\n height: ${2*t.height}px;\n background: linear-gradient(${s},\n rgba(0, 0, 0, ${this.shadow.opacity}) 5%,\n rgba(0, 0, 0, 0.05) 15%,\n rgba(0, 0, 0, ${this.shadow.opacity}) 35%,\n rgba(0, 0, 0, 0) 100%);\n transform-origin: ${i}px 100px;\n transform: translate3d(${n.x-i}px, ${n.y-100}px, 0) rotate(${r}rad);\n clip-path: ${a};\n -webkit-clip-path: ${a};\n `;this.innerShadow.style.cssText=g}drawOuterShadow(){const t=this.getRect(),e=this.convertToGlobal({x:this.shadow.pos.x,y:this.shadow.pos.y}),i=this.shadow.angle+3*Math.PI/2,s=1===this.getDirection()?this.shadow.width:0,n=0===this.getDirection()?"to right":"to left",r=[{x:0,y:0},{x:t.pageWidth,y:0},{x:t.pageWidth,y:t.height},{x:0,y:t.height}];let o="polygon( ";for(const t of r)if(null!==t){let e=1===this.getDirection()?{x:-t.x+this.shadow.pos.x,y:t.y-this.shadow.pos.y}:{x:t.x-this.shadow.pos.x,y:t.y-this.shadow.pos.y};e=h.GetRotatedPoint(e,{x:s,y:100},i),o+=e.x+"px "+e.y+"px, "}o=o.slice(0,-2),o+=")";const a=`\n display: block;\n z-index: ${(this.getSettings().startZIndex+10).toString(10)};\n width: ${this.shadow.width}px;\n height: ${2*t.height}px;\n background: linear-gradient(${n}, rgba(0, 0, 0, ${this.shadow.opacity}), rgba(0, 0, 0, 0));\n transform-origin: ${s}px 100px;\n transform: translate3d(${e.x-s}px, ${e.y-100}px, 0) rotate(${i}rad);\n clip-path: ${o};\n -webkit-clip-path: ${o};\n `;this.outerShadow.style.cssText=a}drawLeftPage(){"portrait"!==this.orientation&&null!==this.leftPage&&(1===this.direction&&null!==this.flippingPage&&"hard"===this.flippingPage.getDrawingDensity()?(this.leftPage.getElement().style.zIndex=(this.getSettings().startZIndex+5).toString(10),this.leftPage.setHardDrawingAngle(180+this.flippingPage.getHardAngle()),this.leftPage.draw(this.flippingPage.getDrawingDensity())):this.leftPage.simpleDraw(0))}drawRightPage(){null!==this.rightPage&&(0===this.direction&&null!==this.flippingPage&&"hard"===this.flippingPage.getDrawingDensity()?(this.rightPage.getElement().style.zIndex=(this.getSettings().startZIndex+5).toString(10),this.rightPage.setHardDrawingAngle(180+this.flippingPage.getHardAngle()),this.rightPage.draw(this.flippingPage.getDrawingDensity())):this.rightPage.simpleDraw(1))}drawBottomPage(){if(null===this.bottomPage)return;const t=null!=this.flippingPage?this.flippingPage.getDrawingDensity():null;"portrait"===this.orientation&&1===this.direction||(this.bottomPage.getElement().style.zIndex=(this.getSettings().startZIndex+3).toString(10),this.bottomPage.draw(t))}drawFrame(){this.clear(),this.drawLeftPage(),this.drawRightPage(),this.drawBottomPage(),null!=this.flippingPage&&(this.flippingPage.getElement().style.zIndex=(this.getSettings().startZIndex+5).toString(10),this.flippingPage.draw()),null!=this.shadow&&null!==this.flippingPage&&("soft"===this.flippingPage.getDrawingDensity()?(this.drawOuterShadow(),this.drawInnerShadow()):(this.drawHardOuterShadow(),this.drawHardInnerShadow()))}clear(){for(const t of this.app.getPageCollection().getPages())t!==this.leftPage&&t!==this.rightPage&&t!==this.flippingPage&&t!==this.bottomPage&&(t.getElement().style.cssText="display: none"),t.getTemporaryCopy()!==this.flippingPage&&t.hideTemporaryCopy()}update(){super.update(),null!==this.rightPage&&this.rightPage.setOrientation(1),null!==this.leftPage&&this.leftPage.setOrientation(0)}}class x{constructor(){this._default={startPage:0,size:"fixed",width:0,height:0,minWidth:0,maxWidth:0,minHeight:0,maxHeight:0,drawShadow:!0,flippingTime:1e3,usePortrait:!0,startZIndex:0,autoSize:!0,maxShadowOpacity:1,showCover:!1,mobileScrollSupport:!0,swipeDistance:30,clickEventForward:!0,useMouseEvents:!0,showPageCorners:!0,disableFlipByClick:!1}}getSettings(t){const e=this._default;if(Object.assign(e,t),"stretch"!==e.size&&"fixed"!==e.size)throw new Error('Invalid size type. Available only "fixed" and "stretch" value');if(e.width<=0||e.height<=0)throw new Error("Invalid width or height");if(e.flippingTime<=0)throw new Error("Invalid flipping time");return"stretch"===e.size?(e.minWidth<=0&&(e.minWidth=100),e.maxWidth{this.ui.update(),this.trigger("init",this,{page:this.setting.startPage,mode:this.render.getOrientation()})},1)}loadFromHTML(t){this.ui=new c(this.block,this,this.setting,t),this.render=new w(this,this.setting,this.ui.getDistElement()),this.flipController=new g(this.render,this),this.pages=new o(this,this.render,this.ui.getDistElement(),t),this.pages.load(),this.render.start(),this.pages.show(this.setting.startPage),setTimeout(()=>{this.ui.update(),this.trigger("init",this,{page:this.setting.startPage,mode:this.render.getOrientation()})},1)}updateFromImages(t){const e=this.pages.getCurrentPageIndex();this.pages.destroy(),this.pages=new n(this,this.render,t),this.pages.load(),this.pages.show(e),this.trigger("update",this,{page:e,mode:this.render.getOrientation()})}updateFromHtml(t){const e=this.pages.getCurrentPageIndex();this.pages.destroy(),this.pages=new o(this,this.render,this.ui.getDistElement(),t),this.pages.load(),this.ui.updateItems(t),this.render.reload(),this.pages.show(e),this.trigger("update",this,{page:e,mode:this.render.getOrientation()})}clear(){this.pages.destroy(),this.ui.clear()}turnToPrevPage(){this.pages.showPrev()}turnToNextPage(){this.pages.showNext()}turnToPage(t){this.pages.show(t)}flipNext(t="top"){this.flipController.flipNext(t)}flipPrev(t="top"){this.flipController.flipPrev(t)}flip(t,e="top"){this.flipController.flipToPage(t,e)}updateState(t){this.trigger("changeState",this,t)}updatePageIndex(t){this.trigger("flip",this,t)}updateOrientation(t){this.ui.setOrientationStyle(t),this.update(),this.trigger("changeOrientation",this,t)}getPageCount(){return this.pages.getPageCount()}getCurrentPageIndex(){return this.pages.getCurrentPageIndex()}getPage(t){return this.pages.getPage(t)}getRender(){return this.render}getFlipController(){return this.flipController}getOrientation(){return this.render.getOrientation()}getBoundsRect(){return this.render.getRect()}getSettings(){return this.setting}getUI(){return this.ui}getState(){return this.flipController.getState()}getPageCollection(){return this.pages}startUserTouch(t){this.mousePosition=t,this.isUserTouch=!0,this.isUserMove=!1}userMove(t,e){this.isUserTouch||e||!this.setting.showPageCorners?this.isUserTouch&&h.GetDistanceBetweenTwoPoint(this.mousePosition,t)>5&&(this.isUserMove=!0,this.flipController.fold(t)):this.flipController.showCorner(t)}userStop(t,e=!1){this.isUserTouch&&(this.isUserTouch=!1,e||(this.isUserMove?this.flipController.stopMove():this.flipController.flip(t)))}},Object.defineProperty(t,"__esModule",{value:!0})})); ++!function(t,e){"object"==typeof exports&&"undefined"!=typeof module?e(exports):"function"==typeof define&&define.amd?define(["exports"],e):e((t=t||self).St={})}(this,(function(t){"use strict";class e{constructor(t,e){this.state={angle:0,area:[],position:{x:0,y:0},hardAngle:0,hardDrawingAngle:0},this.createdDensity=e,this.nowDrawingDensity=this.createdDensity,this.render=t}setDensity(t){this.createdDensity=t,this.nowDrawingDensity=t}setDrawingDensity(t){this.nowDrawingDensity=t}setPosition(t){this.state.position=t}setAngle(t){this.state.angle=t}setArea(t){this.state.area=t}setHardDrawingAngle(t){this.state.hardDrawingAngle=t}setHardAngle(t){this.state.hardAngle=t,this.state.hardDrawingAngle=t}setOrientation(t){this.orientation=t}getDrawingDensity(){return this.nowDrawingDensity}getDensity(){return this.createdDensity}getHardAngle(){return this.state.hardAngle}}class i extends e{constructor(t,e,i){super(t,i),this.image=null,this.isLoad=!1,this.loadingAngle=0,this.image=new Image,this.image.src=e}draw(t){const e=this.render.getContext(),i=this.render.convertToGlobal(this.state.position),s=this.render.getRect().pageWidth,n=this.render.getRect().height;e.save(),e.translate(i.x,i.y),e.beginPath();for(let t of this.state.area)null!==t&&(t=this.render.convertToGlobal(t),e.lineTo(t.x-i.x,t.y-i.y));e.rotate(this.state.angle),e.clip(),this.isLoad?e.drawImage(this.image,0,0,s,n):this.drawLoader(e,{x:0,y:0},s,n),e.restore()}simpleDraw(t){const e=this.render.getRect(),i=this.render.getContext(),s=e.pageWidth,n=e.height,h=1===t?e.left+e.pageWidth:e.left,r=e.top;this.isLoad?i.drawImage(this.image,h,r,s,n):this.drawLoader(i,{x:h,y:r},s,n)}drawLoader(t,e,i,s){t.beginPath(),t.strokeStyle="rgb(200, 200, 200)",t.fillStyle="rgb(255, 255, 255)",t.lineWidth=1,t.rect(e.x+1,e.y+1,i-1,s-1),t.stroke(),t.fill();const n={x:e.x+i/2,y:e.y+s/2};t.beginPath(),t.lineWidth=10,t.arc(n.x,n.y,20,this.loadingAngle,3*Math.PI/2+this.loadingAngle),t.stroke(),t.closePath(),this.loadingAngle+=.07,this.loadingAngle>=2*Math.PI&&(this.loadingAngle=0)}load(){this.isLoad||(this.image.onload=()=>{this.isLoad=!0})}newTemporaryCopy(){return this}getTemporaryCopy(){return this}hideTemporaryCopy(){}}class s{constructor(t,e){this.pages=[],this.currentPageIndex=0,this.currentSpreadIndex=0,this.landscapeSpread=[],this.portraitSpread=[],this.render=e,this.app=t,this.currentPageIndex=0,this.isShowCover=this.app.getSettings().showCover}destroy(){this.pages=[]}createSpread(){this.landscapeSpread=[],this.portraitSpread=[];for(let t=0;t=0&&t0?this.pages[e-1]:null}getFlippingPage(t){const e=this.currentSpreadIndex;if("portrait"===this.render.getOrientation())return 0===t?this.pages[e].newTemporaryCopy():this.pages[e-1];{const i=0===t?this.getSpread()[e+1]:this.getSpread()[e-1];return 1===i.length||0===t?this.pages[i[0]]:this.pages[i[1]]}}getBottomPage(t){const e=this.currentSpreadIndex;if("portrait"===this.render.getOrientation())return 0===t?this.pages[e+1]:this.pages[e-1];{const i=0===t?this.getSpread()[e+1]:this.getSpread()[e-1];return 1===i.length?this.pages[i[0]]:0===t?this.pages[i[1]]:this.pages[i[0]]}}showNext(){this.currentSpreadIndex0&&(this.currentSpreadIndex--,this.showSpread())}getCurrentPageIndex(){return this.currentPageIndex}show(t=null){if(null===t&&(t=this.currentPageIndex),t<0||t>=this.pages.length)return;const e=this.getSpreadIndexByPage(t);null!==e&&(this.currentSpreadIndex=e,this.showSpread())}getCurrentSpreadIndex(){return this.currentSpreadIndex}setCurrentSpreadIndex(t){if(!(t>=0&&t=t.left&&e.x<=t.width+t.left&&e.y>=t.top&&e.y<=t.top+t.height?e:null}static GetRotatedPoint(t,e,i){return{x:t.x*Math.cos(i)+t.y*Math.sin(i)+e.x,y:t.y*Math.cos(i)-t.x*Math.sin(i)+e.y}}static LimitPointToCircle(t,e,i){if(h.GetDistanceBetweenTwoPoint(t,i)<=e)return i;const s=t.x,n=t.y,r=i.x,o=i.y;let a=Math.sqrt(Math.pow(e,2)*Math.pow(s-r,2)/(Math.pow(s-r,2)+Math.pow(n-o,2)))+s;i.x<0&&(a*=-1);let g=(a-s)*(n-o)/(s-r)+n;return s-r+n===0&&(g=e),{x:a,y:g}}static GetIntersectBetweenTwoSegment(t,e,i){return h.PointInRect(t,h.GetIntersectBeetwenTwoLine(e,i))}static GetIntersectBeetwenTwoLine(t,e){const i=t[0].y-t[1].y,s=e[0].y-e[1].y,n=t[1].x-t[0].x,h=e[1].x-e[0].x,r=t[0].x*t[1].y-t[1].x*t[0].y,o=e[0].x*e[1].y-e[1].x*e[0].y,a=i*o-s*r,g=n*o-h*r,l=-(r*h-o*n)/(i*h-s*n),d=-(i*o-s*r)/(i*h-s*n);if(isFinite(l)&&isFinite(d))return{x:l,y:d};if(Math.abs(a-g)<.1)throw new Error("Segment included");return null}static GetCordsFromTwoPoint(t,e){const i=Math.abs(t.x-e.x),s=Math.abs(t.y-e.y),n=Math.max(i,s),h=[t];function r(t,e,i,s,n){return e>t?t+n*(i/s):e=10&&t.push(this.sideIntersectPoint):"top"===this.corner&&t.push({x:this.pageWidth,y:this.pageHeight}),t.push(this.bottomIntersectPoint),t.push(this.topIntersectPoint),t}getAngle(){return 0===this.direction?-this.angle:this.angle}getRect(){return this.rect}getPosition(){return this.position}getActiveCorner(){return 0===this.direction?this.rect.topLeft:this.rect.topRight}getDirection(){return this.direction}getFlippingProgress(){return Math.abs((this.position.x-this.pageWidth)/(2*this.pageWidth)*100)}getCorner(){return this.corner}getBottomPagePosition(){return 1===this.direction?{x:this.pageWidth,y:0}:{x:0,y:0}}getShadowStartPoint(){return"top"===this.corner?this.topIntersectPoint:null!==this.sideIntersectPoint?this.sideIntersectPoint:this.topIntersectPoint}getShadowAngle(){const t=h.GetAngleBetweenTwoLine(this.getSegmentToShadowLine(),[{x:0,y:0},{x:this.pageWidth,y:0}]);return 0===this.direction?t:Math.PI-t}calcAngleAndPosition(t){let e=t;if(this.updateAngleAndGeometry(e),e="top"===this.corner?this.checkPositionAtCenterLine(e,{x:0,y:0},{x:0,y:this.pageHeight}):this.checkPositionAtCenterLine(e,{x:0,y:this.pageHeight},{x:0,y:0}),Math.abs(e.x-this.pageWidth)<1&&Math.abs(e.y)<1)throw new Error("Point is too small");return e}updateAngleAndGeometry(t){this.angle=this.calculateAngle(t),this.rect=this.getPageRect(t)}calculateAngle(t){const e=this.pageWidth-t.x+1,i="bottom"===this.corner?this.pageHeight-t.y:t.y;let s=2*Math.acos(e/Math.sqrt(i*i+e*e));i<0&&(s=-s);const n=Math.PI-s;if(!isFinite(s)||n>=0&&n<.003)throw new Error("The G point is too small");return"bottom"===this.corner&&(s=-s),s}getPageRect(t){return"top"===this.corner?this.getRectFromBasePoint([{x:0,y:0},{x:this.pageWidth,y:0},{x:0,y:this.pageHeight},{x:this.pageWidth,y:this.pageHeight}],t):this.getRectFromBasePoint([{x:0,y:-this.pageHeight},{x:this.pageWidth,y:-this.pageHeight},{x:0,y:0},{x:this.pageWidth,y:0}],t)}getRectFromBasePoint(t,e){return{topLeft:this.getRotatedPoint(t[0],e),topRight:this.getRotatedPoint(t[1],e),bottomLeft:this.getRotatedPoint(t[2],e),bottomRight:this.getRotatedPoint(t[3],e)}}getRotatedPoint(t,e){return{x:t.x*Math.cos(this.angle)+t.y*Math.sin(this.angle)+e.x,y:t.y*Math.cos(this.angle)-t.x*Math.sin(this.angle)+e.y}}calculateIntersectPoint(t){const e={left:-1,top:-1,width:this.pageWidth+2,height:this.pageHeight+2};"top"===this.corner?(this.topIntersectPoint=h.GetIntersectBetweenTwoSegment(e,[t,this.rect.topRight],[{x:0,y:0},{x:this.pageWidth,y:0}]),this.sideIntersectPoint=h.GetIntersectBetweenTwoSegment(e,[t,this.rect.bottomLeft],[{x:this.pageWidth,y:0},{x:this.pageWidth,y:this.pageHeight}]),this.bottomIntersectPoint=h.GetIntersectBetweenTwoSegment(e,[this.rect.bottomLeft,this.rect.bottomRight],[{x:0,y:this.pageHeight},{x:this.pageWidth,y:this.pageHeight}])):(this.topIntersectPoint=h.GetIntersectBetweenTwoSegment(e,[this.rect.topLeft,this.rect.topRight],[{x:0,y:0},{x:this.pageWidth,y:0}]),this.sideIntersectPoint=h.GetIntersectBetweenTwoSegment(e,[t,this.rect.topLeft],[{x:this.pageWidth,y:0},{x:this.pageWidth,y:this.pageHeight}]),this.bottomIntersectPoint=h.GetIntersectBetweenTwoSegment(e,[this.rect.bottomLeft,this.rect.bottomRight],[{x:0,y:this.pageHeight},{x:this.pageWidth,y:this.pageHeight}]))}checkPositionAtCenterLine(t,e,i){let s=t;const n=h.LimitPointToCircle(e,this.pageWidth,s);s!==n&&(s=n,this.updateAngleAndGeometry(s));const r=Math.sqrt(Math.pow(this.pageWidth,2)+Math.pow(this.pageHeight,2));let o=this.rect.bottomRight,a=this.rect.topLeft;if("bottom"===this.corner&&(o=this.rect.topRight,a=this.rect.bottomLeft),o.x<=0){const t=h.LimitPointToCircle(i,r,a);t!==s&&(s=t,this.updateAngleAndGeometry(s))}return s}getSegmentToShadowLine(){const t=this.getShadowStartPoint();return[t,t!==this.sideIntersectPoint&&null!==this.sideIntersectPoint?this.sideIntersectPoint:this.bottomIntersectPoint]}}class g{constructor(t,e){this.flippingPage=null,this.bottomPage=null,this.calc=null,this.state="read",this.render=t,this.app=e}fold(t){this.setState("user_fold"),null===this.calc&&this.start(t),this.do(this.render.convertToPage(t))}flip(t){if(this.app.getSettings().disableFlipByClick&&!this.isPointOnCorners(t))return;if(null!==this.calc&&this.render.finishAnimation(),!this.start(t))return;const e=this.getBoundsRect();this.setState("flipping");const i=e.height/10,s="bottom"===this.calc.getCorner()?e.height-i:i,n="bottom"===this.calc.getCorner()?e.height:0;this.calc.calc({x:e.pageWidth-i,y:s}),this.animateFlippingTo({x:e.pageWidth-i,y:s},{x:-e.pageWidth,y:n},!0)}start(t){this.reset();const e=this.render.convertToBook(t),i=this.getBoundsRect(),s=this.getDirectionByPoint(e),n=e.y>=i.height/2?"bottom":"top";if(!this.checkDirection(s))return!1;try{if(this.flippingPage=this.app.getPageCollection().getFlippingPage(s),this.bottomPage=this.app.getPageCollection().getBottomPage(s),"landscape"===this.render.getOrientation())if(1===s){const t=this.app.getPageCollection().nextBy(this.flippingPage);null!==t&&this.flippingPage.getDensity()!==t.getDensity()&&(this.flippingPage.setDrawingDensity("hard"),t.setDrawingDensity("hard"))}else{const t=this.app.getPageCollection().prevBy(this.flippingPage);null!==t&&this.flippingPage.getDensity()!==t.getDensity()&&(this.flippingPage.setDrawingDensity("hard"),t.setDrawingDensity("hard"))}return this.render.setDirection(s),this.calc=new a(s,n,i.pageWidth.toString(10),i.height.toString(10)),!0}catch(t){return!1}}do(t){if(null!==this.calc&&this.calc.calc(t)){const t=this.calc.getFlippingProgress();this.bottomPage.setArea(this.calc.getBottomClipArea()),this.bottomPage.setPosition(this.calc.getBottomPagePosition()),this.bottomPage.setAngle(0),this.bottomPage.setHardAngle(0),this.flippingPage.setArea(this.calc.getFlippingClipArea()),this.flippingPage.setPosition(this.calc.getActiveCorner()),this.flippingPage.setAngle(this.calc.getAngle()),0===this.calc.getDirection()?this.flippingPage.setHardAngle(90*(200-2*t)/100):this.flippingPage.setHardAngle(-90*(200-2*t)/100),this.render.setPageRect(this.calc.getRect()),this.render.setBottomPage(this.bottomPage),this.render.setFlippingPage(this.flippingPage),this.render.setShadowData(this.calc.getShadowStartPoint(),this.calc.getShadowAngle(),t,this.calc.getDirection())}}flipToPage(t,e){const i=this.app.getPageCollection().getCurrentSpreadIndex(),s=this.app.getPageCollection().getSpreadIndexByPage(t);try{s>i&&(this.app.getPageCollection().setCurrentSpreadIndex(s-1),this.flipNext(e)),sthis.do(t));const o=this.getAnimationDuration(n.length);this.render.startAnimation(r,o,()=>{this.calc&&(i&&(1===this.calc.getDirection()?this.app.turnToPrevPage():this.app.turnToNextPage()),s&&(this.render.setBottomPage(null),this.render.setFlippingPage(null),this.render.clearShadow(),this.setState("read"),this.reset()))})}getCalculation(){return this.calc}getState(){return this.state}setState(t){this.state!==t&&(this.app.updateState(t),this.state=t)}getDirectionByPoint(t){const e=this.getBoundsRect();if("portrait"===this.render.getOrientation()){if(t.x-e.pageWidth<=e.width/5)return 1}else if(t.x=1e3?e:t/1e3*e}checkDirection(t){return 0===t?this.app.getCurrentPageIndex()=1}reset(){this.calc=null,this.flippingPage=null,this.bottomPage=null}getBoundsRect(){return this.render.getRect()}checkState(...t){for(const e of t)if(this.state===e)return!0;return!1}isPointOnCorners(t){const e=this.getBoundsRect(),i=e.pageWidth,s=Math.sqrt(Math.pow(i,2)+Math.pow(e.height,2))/5,n=this.render.convertToBook(t);return n.x>0&&n.y>0&&n.xe.width-s)&&(n.ye.height-s)}}class l{constructor(t,e){this.leftPage=null,this.rightPage=null,this.flippingPage=null,this.bottomPage=null,this.direction=null,this.orientation=null,this.shadow=null,this.animation=null,this.pageRect=null,this.boundsRect=null,this.timer=0,this.safari=!1,this.setting=e,this.app=t;const i=new RegExp("Version\\/[\\d\\.]+.*Safari/");this.safari=null!==i.exec(window.navigator.userAgent)}render(t){if(null!==this.animation){const e=Math.round((t-this.animation.startedAt)/this.animation.durationFrame);e{this.running&&(this.render(e),this.running&&(this.frame=requestAnimationFrame(t)))};this.frame=requestAnimationFrame(t)}stop(){this.running=!1,null!=this.frame&&cancelAnimationFrame(this.frame),this.frame=null,this.animation=null}startAnimation(t,e,i){this.finishAnimation(),this.animation={frames:t,duration:e,durationFrame:e/t.length,onAnimateEnd:i,startedAt:this.timer}}finishAnimation(){null!==this.animation&&(this.animation.frames[this.animation.frames.length-1](),null!==this.animation.onAnimateEnd&&this.animation.onAnimateEnd()),this.animation=null}update(){this.boundsRect=null;const t=this.calculateBoundsRect();this.orientation!==t&&(this.orientation=t,this.app.updateOrientation(t))}calculateBoundsRect(){let t="landscape";const e=this.getBlockWidth(),i=e/2,s=this.getBlockHeight()/2,n=this.setting.width/this.setting.height;let h=this.setting.width,r=this.setting.height,o=i-h;return"stretch"===this.setting.size?(e<2*this.setting.minWidth&&this.app.getSettings().usePortrait&&(t="portrait"),h="portrait"===t?this.getBlockWidth():this.getBlockWidth()/2,h>this.setting.maxWidth&&(h=this.setting.maxWidth),r=h/n,r>this.getBlockHeight()&&(r=this.getBlockHeight(),h=r*n),o="portrait"===t?i-h/2-h:i-h):e<2*h&&this.app.getSettings().usePortrait&&(t="portrait",o=i-h/2-h),this.boundsRect={left:o,top:s-r/2,width:2*h,height:r,pageWidth:h},t}setShadowData(t,e,i,s){if(!this.app.getSettings().drawShadow)return;const n=100*this.getSettings().maxShadowOpacity;this.shadow={pos:t,angle:e,width:3*this.getRect().pageWidth/4*i/100,opacity:(100-i)*n/100/100,direction:s,progress:2*i}}clearShadow(){this.shadow=null}getBlockWidth(){return this.app.getUI().getDistElement().offsetWidth}getBlockHeight(){return this.app.getUI().getDistElement().offsetHeight}getDirection(){return this.direction}getRect(){return null===this.boundsRect&&this.calculateBoundsRect(),this.boundsRect}getSettings(){return this.app.getSettings()}getOrientation(){return this.orientation}setPageRect(t){this.pageRect=t}setDirection(t){this.direction=t}setRightPage(t){null!==t&&t.setOrientation(1),this.rightPage=t}setLeftPage(t){null!==t&&t.setOrientation(0),this.leftPage=t}setBottomPage(t){null!==t&&t.setOrientation(1===this.direction?0:1),this.bottomPage=t}setFlippingPage(t){null!==t&&t.setOrientation(0===this.direction&&"portrait"!==this.orientation?0:1),this.flippingPage=t}convertToBook(t){const e=this.getRect();return{x:t.x-e.left,y:t.y-e.top}}isSafari(){return this.safari}convertToPage(t,e){e||(e=this.direction);const i=this.getRect();return{x:0===e?t.x-i.left-i.width/2:i.width/2-t.x+i.left,y:t.y-i.top}}convertToGlobal(t,e){if(e||(e=this.direction),null==t)return null;const i=this.getRect();return{x:0===e?t.x+i.left+i.width/2:i.width/2-t.x+i.left,y:t.y+i.top}}convertRectToGlobal(t,e){return e||(e=this.direction),{topLeft:this.convertToGlobal(t.topLeft,e),topRight:this.convertToGlobal(t.topRight,e),bottomLeft:this.convertToGlobal(t.bottomLeft,e),bottomRight:this.convertToGlobal(t.bottomRight,e)}}}class d extends l{constructor(t,e,i){super(t,e),this.canvas=i,this.ctx=i.getContext("2d")}getContext(){return this.ctx}reload(){}drawFrame(){this.clear(),"portrait"!==this.orientation&&null!=this.leftPage&&this.leftPage.simpleDraw(0),null!=this.rightPage&&this.rightPage.simpleDraw(1),null!=this.bottomPage&&this.bottomPage.draw(),this.drawBookShadow(),null!=this.flippingPage&&this.flippingPage.draw(),null!=this.shadow&&(this.drawOuterShadow(),this.drawInnerShadow());const t=this.getRect();"portrait"===this.orientation&&(this.ctx.beginPath(),this.ctx.rect(t.left+t.pageWidth,t.top,t.width,t.height),this.ctx.clip())}drawBookShadow(){const t=this.getRect();this.ctx.save(),this.ctx.beginPath();const e=t.width/20;this.ctx.rect(t.left,t.top,t.width,t.height);const i={x:t.left+t.width/2-e/2,y:0};this.ctx.translate(i.x,i.y);const s=this.ctx.createLinearGradient(0,0,e,0);s.addColorStop(0,"rgba(0, 0, 0, 0)"),s.addColorStop(.4,"rgba(0, 0, 0, 0.2)"),s.addColorStop(.49,"rgba(0, 0, 0, 0.1)"),s.addColorStop(.5,"rgba(0, 0, 0, 0.5)"),s.addColorStop(.51,"rgba(0, 0, 0, 0.4)"),s.addColorStop(1,"rgba(0, 0, 0, 0)"),this.ctx.clip(),this.ctx.fillStyle=s,this.ctx.fillRect(0,0,e,2*t.height),this.ctx.restore()}drawOuterShadow(){const t=this.getRect();this.ctx.save(),this.ctx.beginPath(),this.ctx.rect(t.left,t.top,t.width,t.height);const e=this.convertToGlobal({x:this.shadow.pos.x,y:this.shadow.pos.y});this.ctx.translate(e.x,e.y),this.ctx.rotate(Math.PI+this.shadow.angle+Math.PI/2);const i=this.ctx.createLinearGradient(0,0,this.shadow.width,0);0===this.shadow.direction?(this.ctx.translate(0,-100),i.addColorStop(0,"rgba(0, 0, 0, "+this.shadow.opacity+")"),i.addColorStop(1,"rgba(0, 0, 0, 0)")):(this.ctx.translate(-this.shadow.width,-100),i.addColorStop(0,"rgba(0, 0, 0, 0)"),i.addColorStop(1,"rgba(0, 0, 0, "+this.shadow.opacity+")")),this.ctx.clip(),this.ctx.fillStyle=i,this.ctx.fillRect(0,0,this.shadow.width,2*t.height),this.ctx.restore()}drawInnerShadow(){const t=this.getRect();this.ctx.save(),this.ctx.beginPath();const e=this.convertToGlobal({x:this.shadow.pos.x,y:this.shadow.pos.y}),i=this.convertRectToGlobal(this.pageRect);this.ctx.moveTo(i.topLeft.x,i.topLeft.y),this.ctx.lineTo(i.topRight.x,i.topRight.y),this.ctx.lineTo(i.bottomRight.x,i.bottomRight.y),this.ctx.lineTo(i.bottomLeft.x,i.bottomLeft.y),this.ctx.translate(e.x,e.y),this.ctx.rotate(Math.PI+this.shadow.angle+Math.PI/2);const s=3*this.shadow.width/4,n=this.ctx.createLinearGradient(0,0,s,0);0===this.shadow.direction?(this.ctx.translate(-s,-100),n.addColorStop(1,"rgba(0, 0, 0, "+this.shadow.opacity+")"),n.addColorStop(.9,"rgba(0, 0, 0, 0.05)"),n.addColorStop(.7,"rgba(0, 0, 0, "+this.shadow.opacity+")"),n.addColorStop(0,"rgba(0, 0, 0, 0)")):(this.ctx.translate(0,-100),n.addColorStop(0,"rgba(0, 0, 0, "+this.shadow.opacity+")"),n.addColorStop(.1,"rgba(0, 0, 0, 0.05)"),n.addColorStop(.3,"rgba(0, 0, 0, "+this.shadow.opacity+")"),n.addColorStop(1,"rgba(0, 0, 0, 0)")),this.ctx.clip(),this.ctx.fillStyle=n,this.ctx.fillRect(0,0,s,2*t.height),this.ctx.restore()}clear(){this.ctx.fillStyle="white",this.ctx.fillRect(0,0,this.canvas.width,this.canvas.height)}}class p{constructor(t,e,i){this.touchPoint=null,this.swipeTimeout=250,this.onResize=()=>{this.update()},this.onMouseDown=t=>{if(this.checkTarget(t.target)){const e=this.getMousePos(t.clientX,t.clientY);this.app.startUserTouch(e),t.preventDefault()}},this.onTouchStart=t=>{if(this.checkTarget(t.target)&&t.changedTouches.length>0){const e=t.changedTouches[0],i=this.getMousePos(e.clientX,e.clientY);this.touchPoint={point:i,time:Date.now()},setTimeout(()=>{null!==this.touchPoint&&this.app.startUserTouch(i)},this.swipeTimeout),this.app.getSettings().mobileScrollSupport||t.preventDefault()}},this.onMouseUp=t=>{const e=this.getMousePos(t.clientX,t.clientY);this.app.userStop(e)},this.onMouseMove=t=>{const e=this.getMousePos(t.clientX,t.clientY);this.app.userMove(e,!1)},this.onTouchMove=t=>{if(t.changedTouches.length>0){const e=t.changedTouches[0],i=this.getMousePos(e.clientX,e.clientY);this.app.getSettings().mobileScrollSupport?(null!==this.touchPoint&&(Math.abs(this.touchPoint.point.x-i.x)>10||"read"!==this.app.getState())&&t.cancelable&&this.app.userMove(i,!0),"read"!==this.app.getState()&&t.preventDefault()):this.app.userMove(i,!0)}},this.onTouchEnd=t=>{if(t.changedTouches.length>0){const e=t.changedTouches[0],i=this.getMousePos(e.clientX,e.clientY);let s=!1;if(null!==this.touchPoint){const t=i.x-this.touchPoint.point.x,e=Math.abs(i.y-this.touchPoint.point.y);Math.abs(t)>this.swipeDistance&&e<2*this.swipeDistance&&Date.now()-this.touchPoint.time0?this.app.flipPrev(this.touchPoint.point.y'),this.wrapper=t.querySelector(".stf__wrapper"),this.app=e;const s=this.app.getSettings().usePortrait?1:2;t.style.minWidth=i.minWidth*s+"px",t.style.minHeight=i.minHeight+"px","fixed"===i.size&&(t.style.minWidth=i.width*s+"px",t.style.minHeight=i.height+"px"),i.autoSize&&(t.style.width="100%",t.style.maxWidth=2*i.maxWidth+"px"),t.style.display="block",window.addEventListener("resize",this.onResize,!1),this.swipeDistance=i.swipeDistance}destroy(){this.removeHandlers(),this.distElement.remove(),this.wrapper.remove()}getDistElement(){return this.distElement}getWrapper(){return this.wrapper}setOrientationStyle(t){this.wrapper.classList.remove("--portrait","--landscape"),"portrait"===t?(this.app.getSettings().autoSize&&(this.wrapper.style.paddingBottom=this.app.getSettings().height/this.app.getSettings().width*100+"%"),this.wrapper.classList.add("--portrait")):(this.app.getSettings().autoSize&&(this.wrapper.style.paddingBottom=this.app.getSettings().height/(2*this.app.getSettings().width)*100+"%"),this.wrapper.classList.add("--landscape")),this.update()}removeHandlers(){window.removeEventListener("resize",this.onResize),this.distElement.removeEventListener("mousedown",this.onMouseDown),this.distElement.removeEventListener("touchstart",this.onTouchStart),window.removeEventListener("mousemove",this.onMouseMove),window.removeEventListener("touchmove",this.onTouchMove),window.removeEventListener("mouseup",this.onMouseUp),window.removeEventListener("touchend",this.onTouchEnd)}setHandlers(){window.addEventListener("resize",this.onResize,!1),this.app.getSettings().useMouseEvents&&(this.distElement.addEventListener("mousedown",this.onMouseDown),this.distElement.addEventListener("touchstart",this.onTouchStart),window.addEventListener("mousemove",this.onMouseMove),window.addEventListener("touchmove",this.onTouchMove,{passive:!this.app.getSettings().mobileScrollSupport}),window.addEventListener("mouseup",this.onMouseUp),window.addEventListener("touchend",this.onTouchEnd))}getMousePos(t,e){const i=this.distElement.getBoundingClientRect();return{x:t-i.left,y:e-i.top}}checkTarget(t){return!this.app.getSettings().clickEventForward||!["a","button"].includes(t.tagName.toLowerCase())}}class c extends p{constructor(t,e,i,s){super(t,e,i),this.wrapper.insertAdjacentHTML("afterbegin",'
'),this.distElement=t.querySelector(".stf__block"),this.items=s;for(const t of s)this.distElement.appendChild(t);this.setHandlers()}clear(){for(const t of this.items)this.parentElement.appendChild(t)}updateItems(t){this.removeHandlers(),this.distElement.innerHTML="";for(const e of t)this.distElement.appendChild(e);this.items=t,this.setHandlers()}update(){this.app.getRender().update()}}class u extends p{constructor(t,e,i){super(t,e,i),this.wrapper.innerHTML='',this.canvas=t.querySelectorAll("canvas")[0],this.distElement=this.canvas,this.resizeCanvas(),this.setHandlers()}resizeCanvas(){const t=getComputedStyle(this.canvas),e=parseInt(t.getPropertyValue("width"),10),i=parseInt(t.getPropertyValue("height"),10);this.canvas.width=e,this.canvas.height=i}getCanvas(){return this.canvas}update(){this.resizeCanvas(),this.app.getRender().update()}}class w extends l{constructor(t,e,i){super(t,e),this.outerShadow=null,this.innerShadow=null,this.hardShadow=null,this.hardInnerShadow=null,this.element=i,this.createShadows()}createShadows(){this.element.insertAdjacentHTML("beforeend",'
\n
\n
\n
'),this.outerShadow=this.element.querySelector(".stf__outerShadow"),this.innerShadow=this.element.querySelector(".stf__innerShadow"),this.hardShadow=this.element.querySelector(".stf__hardShadow"),this.hardInnerShadow=this.element.querySelector(".stf__hardInnerShadow")}clearShadow(){super.clearShadow(),this.outerShadow.style.cssText="display: none",this.innerShadow.style.cssText="display: none",this.hardShadow.style.cssText="display: none",this.hardInnerShadow.style.cssText="display: none"}reload(){this.element.querySelector(".stf__outerShadow")||this.createShadows()}drawHardInnerShadow(){const t=this.getRect(),e=this.shadow.progress>100?200-this.shadow.progress:this.shadow.progress;let i=(100-e)*(2.5*t.pageWidth)/100+20;i>t.pageWidth&&(i=t.pageWidth);let s=`\n display: block;\n z-index: ${(this.getSettings().startZIndex+5).toString(10)};\n width: ${i}px;\n height: ${t.height}px;\n background: linear-gradient(to right,\n rgba(0, 0, 0, ${this.shadow.opacity*e/100}) 5%,\n rgba(0, 0, 0, 0) 100%);\n left: ${t.left+t.width/2}px;\n transform-origin: 0 0;\n `;s+=0===this.getDirection()&&this.shadow.progress>100||1===this.getDirection()&&this.shadow.progress<=100?"transform: translate3d(0, 0, 0);":"transform: translate3d(0, 0, 0) rotateY(180deg);",this.hardInnerShadow.style.cssText=s}drawHardOuterShadow(){const t=this.getRect();let e=(100-(this.shadow.progress>100?200-this.shadow.progress:this.shadow.progress))*(2.5*t.pageWidth)/100+20;e>t.pageWidth&&(e=t.pageWidth);let i=`\n display: block;\n z-index: ${(this.getSettings().startZIndex+4).toString(10)};\n width: ${e}px;\n height: ${t.height}px;\n background: linear-gradient(to left, rgba(0, 0, 0, ${this.shadow.opacity}) 5%, rgba(0, 0, 0, 0) 100%);\n left: ${t.left+t.width/2}px;\n transform-origin: 0 0;\n `;i+=0===this.getDirection()&&this.shadow.progress>100||1===this.getDirection()&&this.shadow.progress<=100?"transform: translate3d(0, 0, 0) rotateY(180deg);":"transform: translate3d(0, 0, 0);",this.hardShadow.style.cssText=i}drawInnerShadow(){const t=this.getRect(),e=3*this.shadow.width/4,i=0===this.getDirection()?e:0,s=0===this.getDirection()?"to left":"to right",n=this.convertToGlobal(this.shadow.pos),r=this.shadow.angle+3*Math.PI/2,o=[this.pageRect.topLeft,this.pageRect.topRight,this.pageRect.bottomRight,this.pageRect.bottomLeft];let a="polygon( ";for(const t of o){let e=1===this.getDirection()?{x:-t.x+this.shadow.pos.x,y:t.y-this.shadow.pos.y}:{x:t.x-this.shadow.pos.x,y:t.y-this.shadow.pos.y};e=h.GetRotatedPoint(e,{x:i,y:100},r),a+=e.x+"px "+e.y+"px, "}a=a.slice(0,-2),a+=")";const g=`\n display: block;\n z-index: ${(this.getSettings().startZIndex+10).toString(10)};\n width: ${e}px;\n height: ${2*t.height}px;\n background: linear-gradient(${s},\n rgba(0, 0, 0, ${this.shadow.opacity}) 5%,\n rgba(0, 0, 0, 0.05) 15%,\n rgba(0, 0, 0, ${this.shadow.opacity}) 35%,\n rgba(0, 0, 0, 0) 100%);\n transform-origin: ${i}px 100px;\n transform: translate3d(${n.x-i}px, ${n.y-100}px, 0) rotate(${r}rad);\n clip-path: ${a};\n -webkit-clip-path: ${a};\n `;this.innerShadow.style.cssText=g}drawOuterShadow(){const t=this.getRect(),e=this.convertToGlobal({x:this.shadow.pos.x,y:this.shadow.pos.y}),i=this.shadow.angle+3*Math.PI/2,s=1===this.getDirection()?this.shadow.width:0,n=0===this.getDirection()?"to right":"to left",r=[{x:0,y:0},{x:t.pageWidth,y:0},{x:t.pageWidth,y:t.height},{x:0,y:t.height}];let o="polygon( ";for(const t of r)if(null!==t){let e=1===this.getDirection()?{x:-t.x+this.shadow.pos.x,y:t.y-this.shadow.pos.y}:{x:t.x-this.shadow.pos.x,y:t.y-this.shadow.pos.y};e=h.GetRotatedPoint(e,{x:s,y:100},i),o+=e.x+"px "+e.y+"px, "}o=o.slice(0,-2),o+=")";const a=`\n display: block;\n z-index: ${(this.getSettings().startZIndex+10).toString(10)};\n width: ${this.shadow.width}px;\n height: ${2*t.height}px;\n background: linear-gradient(${n}, rgba(0, 0, 0, ${this.shadow.opacity}), rgba(0, 0, 0, 0));\n transform-origin: ${s}px 100px;\n transform: translate3d(${e.x-s}px, ${e.y-100}px, 0) rotate(${i}rad);\n clip-path: ${o};\n -webkit-clip-path: ${o};\n `;this.outerShadow.style.cssText=a}drawLeftPage(){"portrait"!==this.orientation&&null!==this.leftPage&&(1===this.direction&&null!==this.flippingPage&&"hard"===this.flippingPage.getDrawingDensity()?(this.leftPage.getElement().style.zIndex=(this.getSettings().startZIndex+5).toString(10),this.leftPage.setHardDrawingAngle(180+this.flippingPage.getHardAngle()),this.leftPage.draw(this.flippingPage.getDrawingDensity())):this.leftPage.simpleDraw(0))}drawRightPage(){null!==this.rightPage&&(0===this.direction&&null!==this.flippingPage&&"hard"===this.flippingPage.getDrawingDensity()?(this.rightPage.getElement().style.zIndex=(this.getSettings().startZIndex+5).toString(10),this.rightPage.setHardDrawingAngle(180+this.flippingPage.getHardAngle()),this.rightPage.draw(this.flippingPage.getDrawingDensity())):this.rightPage.simpleDraw(1))}drawBottomPage(){if(null===this.bottomPage)return;const t=null!=this.flippingPage?this.flippingPage.getDrawingDensity():null;"portrait"===this.orientation&&1===this.direction||(this.bottomPage.getElement().style.zIndex=(this.getSettings().startZIndex+3).toString(10),this.bottomPage.draw(t))}drawFrame(){this.clear(),this.drawLeftPage(),this.drawRightPage(),this.drawBottomPage(),null!=this.flippingPage&&(this.flippingPage.getElement().style.zIndex=(this.getSettings().startZIndex+5).toString(10),this.flippingPage.draw()),null!=this.shadow&&null!==this.flippingPage&&("soft"===this.flippingPage.getDrawingDensity()?(this.drawOuterShadow(),this.drawInnerShadow()):(this.drawHardOuterShadow(),this.drawHardInnerShadow()))}clear(){for(const t of this.app.getPageCollection().getPages())t!==this.leftPage&&t!==this.rightPage&&t!==this.flippingPage&&t!==this.bottomPage&&(t.getElement().style.cssText="display: none"),t.getTemporaryCopy()!==this.flippingPage&&t.hideTemporaryCopy()}update(){super.update(),null!==this.rightPage&&this.rightPage.setOrientation(1),null!==this.leftPage&&this.leftPage.setOrientation(0)}}class x{constructor(){this._default={startPage:0,size:"fixed",width:0,height:0,minWidth:0,maxWidth:0,minHeight:0,maxHeight:0,drawShadow:!0,flippingTime:1e3,usePortrait:!0,startZIndex:0,autoSize:!0,maxShadowOpacity:1,showCover:!1,mobileScrollSupport:!0,swipeDistance:30,clickEventForward:!0,useMouseEvents:!0,showPageCorners:!0,disableFlipByClick:!1}}getSettings(t){const e=this._default;if(Object.assign(e,t),"stretch"!==e.size&&"fixed"!==e.size)throw new Error('Invalid size type. Available only "fixed" and "stretch" value');if(e.width<=0||e.height<=0)throw new Error("Invalid width or height");if(e.flippingTime<=0)throw new Error("Invalid flipping time");return"stretch"===e.size?(e.minWidth<=0&&(e.minWidth=100),e.maxWidth{this.ui.update(),this.trigger("init",this,{page:this.setting.startPage,mode:this.render.getOrientation()})},1)}loadFromHTML(t){this.ui=new c(this.block,this,this.setting,t),this.render=new w(this,this.setting,this.ui.getDistElement()),this.flipController=new g(this.render,this),this.pages=new o(this,this.render,this.ui.getDistElement(),t),this.pages.load(),this.render.start(),this.pages.show(this.setting.startPage),setTimeout(()=>{this.ui.update(),this.trigger("init",this,{page:this.setting.startPage,mode:this.render.getOrientation()})},1)}updateFromImages(t){const e=this.pages.getCurrentPageIndex();this.pages.destroy(),this.pages=new n(this,this.render,t),this.pages.load(),this.pages.show(e),this.trigger("update",this,{page:e,mode:this.render.getOrientation()})}updateFromHtml(t){const e=this.pages.getCurrentPageIndex();this.pages.destroy(),this.pages=new o(this,this.render,this.ui.getDistElement(),t),this.pages.load(),this.ui.updateItems(t),this.render.reload(),this.pages.show(e),this.trigger("update",this,{page:e,mode:this.render.getOrientation()})}clear(){this.pages.destroy(),this.ui.clear()}turnToPrevPage(){this.pages.showPrev()}turnToNextPage(){this.pages.showNext()}turnToPage(t){this.pages.show(t)}flipNext(t="top"){this.flipController.flipNext(t)}flipPrev(t="top"){this.flipController.flipPrev(t)}flip(t,e="top"){this.flipController.flipToPage(t,e)}updateState(t){this.trigger("changeState",this,t)}updatePageIndex(t){this.trigger("flip",this,t)}updateOrientation(t){this.ui.setOrientationStyle(t),this.update(),this.trigger("changeOrientation",this,t)}getPageCount(){return this.pages.getPageCount()}getCurrentPageIndex(){return this.pages.getCurrentPageIndex()}getPage(t){return this.pages.getPage(t)}getRender(){return this.render}getFlipController(){return this.flipController}getOrientation(){return this.render.getOrientation()}getBoundsRect(){return this.render.getRect()}getSettings(){return this.setting}getUI(){return this.ui}getState(){return this.flipController.getState()}getPageCollection(){return this.pages}startUserTouch(t){this.mousePosition=t,this.isUserTouch=!0,this.isUserMove=!1}userMove(t,e){this.isUserTouch||e||!this.setting.showPageCorners?this.isUserTouch&&h.GetDistanceBetweenTwoPoint(this.mousePosition,t)>5&&(this.isUserMove=!0,this.flipController.fold(t)):this.flipController.showCorner(t)}userStop(t,e=!1){this.isUserTouch&&(this.isUserTouch=!1,e||(this.isUserMove?this.flipController.stopMove():this.flipController.flip(t)))}},Object.defineProperty(t,"__esModule",{value:!0})})); +diff --git a/dist/js/page-flip.module.js b/dist/js/page-flip.module.js +index ea218ca34ebc8d1191f285ca0f7d5959b5c49edb..0b6fd6afcba2d13a00446e09a713ee7511a05e7c 100644 +--- a/dist/js/page-flip.module.js ++++ b/dist/js/page-flip.module.js +@@ -1 +1 @@ +-class t{constructor(t,e){this.state={angle:0,area:[],position:{x:0,y:0},hardAngle:0,hardDrawingAngle:0},this.createdDensity=e,this.nowDrawingDensity=this.createdDensity,this.render=t}setDensity(t){this.createdDensity=t,this.nowDrawingDensity=t}setDrawingDensity(t){this.nowDrawingDensity=t}setPosition(t){this.state.position=t}setAngle(t){this.state.angle=t}setArea(t){this.state.area=t}setHardDrawingAngle(t){this.state.hardDrawingAngle=t}setHardAngle(t){this.state.hardAngle=t,this.state.hardDrawingAngle=t}setOrientation(t){this.orientation=t}getDrawingDensity(){return this.nowDrawingDensity}getDensity(){return this.createdDensity}getHardAngle(){return this.state.hardAngle}}class e extends t{constructor(t,e,i){super(t,i),this.image=null,this.isLoad=!1,this.loadingAngle=0,this.image=new Image,this.image.src=e}draw(t){const e=this.render.getContext(),i=this.render.convertToGlobal(this.state.position),s=this.render.getRect().pageWidth,n=this.render.getRect().height;e.save(),e.translate(i.x,i.y),e.beginPath();for(let t of this.state.area)null!==t&&(t=this.render.convertToGlobal(t),e.lineTo(t.x-i.x,t.y-i.y));e.rotate(this.state.angle),e.clip(),this.isLoad?e.drawImage(this.image,0,0,s,n):this.drawLoader(e,{x:0,y:0},s,n),e.restore()}simpleDraw(t){const e=this.render.getRect(),i=this.render.getContext(),s=e.pageWidth,n=e.height,h=1===t?e.left+e.pageWidth:e.left,r=e.top;this.isLoad?i.drawImage(this.image,h,r,s,n):this.drawLoader(i,{x:h,y:r},s,n)}drawLoader(t,e,i,s){t.beginPath(),t.strokeStyle="rgb(200, 200, 200)",t.fillStyle="rgb(255, 255, 255)",t.lineWidth=1,t.rect(e.x+1,e.y+1,i-1,s-1),t.stroke(),t.fill();const n={x:e.x+i/2,y:e.y+s/2};t.beginPath(),t.lineWidth=10,t.arc(n.x,n.y,20,this.loadingAngle,3*Math.PI/2+this.loadingAngle),t.stroke(),t.closePath(),this.loadingAngle+=.07,this.loadingAngle>=2*Math.PI&&(this.loadingAngle=0)}load(){this.isLoad||(this.image.onload=()=>{this.isLoad=!0})}newTemporaryCopy(){return this}getTemporaryCopy(){return this}hideTemporaryCopy(){}}class i{constructor(t,e){this.pages=[],this.currentPageIndex=0,this.currentSpreadIndex=0,this.landscapeSpread=[],this.portraitSpread=[],this.render=e,this.app=t,this.currentPageIndex=0,this.isShowCover=this.app.getSettings().showCover}destroy(){this.pages=[]}createSpread(){this.landscapeSpread=[],this.portraitSpread=[];for(let t=0;t=0&&t0?this.pages[e-1]:null}getFlippingPage(t){const e=this.currentSpreadIndex;if("portrait"===this.render.getOrientation())return 0===t?this.pages[e].newTemporaryCopy():this.pages[e-1];{const i=0===t?this.getSpread()[e+1]:this.getSpread()[e-1];return 1===i.length||0===t?this.pages[i[0]]:this.pages[i[1]]}}getBottomPage(t){const e=this.currentSpreadIndex;if("portrait"===this.render.getOrientation())return 0===t?this.pages[e+1]:this.pages[e-1];{const i=0===t?this.getSpread()[e+1]:this.getSpread()[e-1];return 1===i.length?this.pages[i[0]]:0===t?this.pages[i[1]]:this.pages[i[0]]}}showNext(){this.currentSpreadIndex0&&(this.currentSpreadIndex--,this.showSpread())}getCurrentPageIndex(){return this.currentPageIndex}show(t=null){if(null===t&&(t=this.currentPageIndex),t<0||t>=this.pages.length)return;const e=this.getSpreadIndexByPage(t);null!==e&&(this.currentSpreadIndex=e,this.showSpread())}getCurrentSpreadIndex(){return this.currentSpreadIndex}setCurrentSpreadIndex(t){if(!(t>=0&&t=t.left&&e.x<=t.width+t.left&&e.y>=t.top&&e.y<=t.top+t.height?e:null}static GetRotatedPoint(t,e,i){return{x:t.x*Math.cos(i)+t.y*Math.sin(i)+e.x,y:t.y*Math.cos(i)-t.x*Math.sin(i)+e.y}}static LimitPointToCircle(t,e,i){if(n.GetDistanceBetweenTwoPoint(t,i)<=e)return i;const s=t.x,h=t.y,r=i.x,a=i.y;let o=Math.sqrt(Math.pow(e,2)*Math.pow(s-r,2)/(Math.pow(s-r,2)+Math.pow(h-a,2)))+s;i.x<0&&(o*=-1);let g=(o-s)*(h-a)/(s-r)+h;return s-r+h===0&&(g=e),{x:o,y:g}}static GetIntersectBetweenTwoSegment(t,e,i){return n.PointInRect(t,n.GetIntersectBeetwenTwoLine(e,i))}static GetIntersectBeetwenTwoLine(t,e){const i=t[0].y-t[1].y,s=e[0].y-e[1].y,n=t[1].x-t[0].x,h=e[1].x-e[0].x,r=t[0].x*t[1].y-t[1].x*t[0].y,a=e[0].x*e[1].y-e[1].x*e[0].y,o=i*a-s*r,g=n*a-h*r,l=-(r*h-a*n)/(i*h-s*n),d=-(i*a-s*r)/(i*h-s*n);if(isFinite(l)&&isFinite(d))return{x:l,y:d};if(Math.abs(o-g)<.1)throw new Error("Segment included");return null}static GetCordsFromTwoPoint(t,e){const i=Math.abs(t.x-e.x),s=Math.abs(t.y-e.y),n=Math.max(i,s),h=[t];function r(t,e,i,s,n){return e>t?t+n*(i/s):e=10&&t.push(this.sideIntersectPoint):"top"===this.corner&&t.push({x:this.pageWidth,y:this.pageHeight}),t.push(this.bottomIntersectPoint),t.push(this.topIntersectPoint),t}getAngle(){return 0===this.direction?-this.angle:this.angle}getRect(){return this.rect}getPosition(){return this.position}getActiveCorner(){return 0===this.direction?this.rect.topLeft:this.rect.topRight}getDirection(){return this.direction}getFlippingProgress(){return Math.abs((this.position.x-this.pageWidth)/(2*this.pageWidth)*100)}getCorner(){return this.corner}getBottomPagePosition(){return 1===this.direction?{x:this.pageWidth,y:0}:{x:0,y:0}}getShadowStartPoint(){return"top"===this.corner?this.topIntersectPoint:null!==this.sideIntersectPoint?this.sideIntersectPoint:this.topIntersectPoint}getShadowAngle(){const t=n.GetAngleBetweenTwoLine(this.getSegmentToShadowLine(),[{x:0,y:0},{x:this.pageWidth,y:0}]);return 0===this.direction?t:Math.PI-t}calcAngleAndPosition(t){let e=t;if(this.updateAngleAndGeometry(e),e="top"===this.corner?this.checkPositionAtCenterLine(e,{x:0,y:0},{x:0,y:this.pageHeight}):this.checkPositionAtCenterLine(e,{x:0,y:this.pageHeight},{x:0,y:0}),Math.abs(e.x-this.pageWidth)<1&&Math.abs(e.y)<1)throw new Error("Point is too small");return e}updateAngleAndGeometry(t){this.angle=this.calculateAngle(t),this.rect=this.getPageRect(t)}calculateAngle(t){const e=this.pageWidth-t.x+1,i="bottom"===this.corner?this.pageHeight-t.y:t.y;let s=2*Math.acos(e/Math.sqrt(i*i+e*e));i<0&&(s=-s);const n=Math.PI-s;if(!isFinite(s)||n>=0&&n<.003)throw new Error("The G point is too small");return"bottom"===this.corner&&(s=-s),s}getPageRect(t){return"top"===this.corner?this.getRectFromBasePoint([{x:0,y:0},{x:this.pageWidth,y:0},{x:0,y:this.pageHeight},{x:this.pageWidth,y:this.pageHeight}],t):this.getRectFromBasePoint([{x:0,y:-this.pageHeight},{x:this.pageWidth,y:-this.pageHeight},{x:0,y:0},{x:this.pageWidth,y:0}],t)}getRectFromBasePoint(t,e){return{topLeft:this.getRotatedPoint(t[0],e),topRight:this.getRotatedPoint(t[1],e),bottomLeft:this.getRotatedPoint(t[2],e),bottomRight:this.getRotatedPoint(t[3],e)}}getRotatedPoint(t,e){return{x:t.x*Math.cos(this.angle)+t.y*Math.sin(this.angle)+e.x,y:t.y*Math.cos(this.angle)-t.x*Math.sin(this.angle)+e.y}}calculateIntersectPoint(t){const e={left:-1,top:-1,width:this.pageWidth+2,height:this.pageHeight+2};"top"===this.corner?(this.topIntersectPoint=n.GetIntersectBetweenTwoSegment(e,[t,this.rect.topRight],[{x:0,y:0},{x:this.pageWidth,y:0}]),this.sideIntersectPoint=n.GetIntersectBetweenTwoSegment(e,[t,this.rect.bottomLeft],[{x:this.pageWidth,y:0},{x:this.pageWidth,y:this.pageHeight}]),this.bottomIntersectPoint=n.GetIntersectBetweenTwoSegment(e,[this.rect.bottomLeft,this.rect.bottomRight],[{x:0,y:this.pageHeight},{x:this.pageWidth,y:this.pageHeight}])):(this.topIntersectPoint=n.GetIntersectBetweenTwoSegment(e,[this.rect.topLeft,this.rect.topRight],[{x:0,y:0},{x:this.pageWidth,y:0}]),this.sideIntersectPoint=n.GetIntersectBetweenTwoSegment(e,[t,this.rect.topLeft],[{x:this.pageWidth,y:0},{x:this.pageWidth,y:this.pageHeight}]),this.bottomIntersectPoint=n.GetIntersectBetweenTwoSegment(e,[this.rect.bottomLeft,this.rect.bottomRight],[{x:0,y:this.pageHeight},{x:this.pageWidth,y:this.pageHeight}]))}checkPositionAtCenterLine(t,e,i){let s=t;const h=n.LimitPointToCircle(e,this.pageWidth,s);s!==h&&(s=h,this.updateAngleAndGeometry(s));const r=Math.sqrt(Math.pow(this.pageWidth,2)+Math.pow(this.pageHeight,2));let a=this.rect.bottomRight,o=this.rect.topLeft;if("bottom"===this.corner&&(a=this.rect.topRight,o=this.rect.bottomLeft),a.x<=0){const t=n.LimitPointToCircle(i,r,o);t!==s&&(s=t,this.updateAngleAndGeometry(s))}return s}getSegmentToShadowLine(){const t=this.getShadowStartPoint();return[t,t!==this.sideIntersectPoint&&null!==this.sideIntersectPoint?this.sideIntersectPoint:this.bottomIntersectPoint]}}class o{constructor(t,e){this.flippingPage=null,this.bottomPage=null,this.calc=null,this.state="read",this.render=t,this.app=e}fold(t){this.setState("user_fold"),null===this.calc&&this.start(t),this.do(this.render.convertToPage(t))}flip(t){if(this.app.getSettings().disableFlipByClick&&!this.isPointOnCorners(t))return;if(null!==this.calc&&this.render.finishAnimation(),!this.start(t))return;const e=this.getBoundsRect();this.setState("flipping");const i=e.height/10,s="bottom"===this.calc.getCorner()?e.height-i:i,n="bottom"===this.calc.getCorner()?e.height:0;this.calc.calc({x:e.pageWidth-i,y:s}),this.animateFlippingTo({x:e.pageWidth-i,y:s},{x:-e.pageWidth,y:n},!0)}start(t){this.reset();const e=this.render.convertToBook(t),i=this.getBoundsRect(),s=this.getDirectionByPoint(e),n=e.y>=i.height/2?"bottom":"top";if(!this.checkDirection(s))return!1;try{if(this.flippingPage=this.app.getPageCollection().getFlippingPage(s),this.bottomPage=this.app.getPageCollection().getBottomPage(s),"landscape"===this.render.getOrientation())if(1===s){const t=this.app.getPageCollection().nextBy(this.flippingPage);null!==t&&this.flippingPage.getDensity()!==t.getDensity()&&(this.flippingPage.setDrawingDensity("hard"),t.setDrawingDensity("hard"))}else{const t=this.app.getPageCollection().prevBy(this.flippingPage);null!==t&&this.flippingPage.getDensity()!==t.getDensity()&&(this.flippingPage.setDrawingDensity("hard"),t.setDrawingDensity("hard"))}return this.render.setDirection(s),this.calc=new a(s,n,i.pageWidth.toString(10),i.height.toString(10)),!0}catch(t){return!1}}do(t){if(null!==this.calc&&this.calc.calc(t)){const t=this.calc.getFlippingProgress();this.bottomPage.setArea(this.calc.getBottomClipArea()),this.bottomPage.setPosition(this.calc.getBottomPagePosition()),this.bottomPage.setAngle(0),this.bottomPage.setHardAngle(0),this.flippingPage.setArea(this.calc.getFlippingClipArea()),this.flippingPage.setPosition(this.calc.getActiveCorner()),this.flippingPage.setAngle(this.calc.getAngle()),0===this.calc.getDirection()?this.flippingPage.setHardAngle(90*(200-2*t)/100):this.flippingPage.setHardAngle(-90*(200-2*t)/100),this.render.setPageRect(this.calc.getRect()),this.render.setBottomPage(this.bottomPage),this.render.setFlippingPage(this.flippingPage),this.render.setShadowData(this.calc.getShadowStartPoint(),this.calc.getShadowAngle(),t,this.calc.getDirection())}}flipToPage(t,e){const i=this.app.getPageCollection().getCurrentSpreadIndex(),s=this.app.getPageCollection().getSpreadIndexByPage(t);try{s>i&&(this.app.getPageCollection().setCurrentSpreadIndex(s-1),this.flipNext(e)),sthis.do(t));const a=this.getAnimationDuration(h.length);this.render.startAnimation(r,a,()=>{this.calc&&(i&&(1===this.calc.getDirection()?this.app.turnToPrevPage():this.app.turnToNextPage()),s&&(this.render.setBottomPage(null),this.render.setFlippingPage(null),this.render.clearShadow(),this.setState("read"),this.reset()))})}getCalculation(){return this.calc}getState(){return this.state}setState(t){this.state!==t&&(this.app.updateState(t),this.state=t)}getDirectionByPoint(t){const e=this.getBoundsRect();if("portrait"===this.render.getOrientation()){if(t.x-e.pageWidth<=e.width/5)return 1}else if(t.x=1e3?e:t/1e3*e}checkDirection(t){return 0===t?this.app.getCurrentPageIndex()=1}reset(){this.calc=null,this.flippingPage=null,this.bottomPage=null}getBoundsRect(){return this.render.getRect()}checkState(...t){for(const e of t)if(this.state===e)return!0;return!1}isPointOnCorners(t){const e=this.getBoundsRect(),i=e.pageWidth,s=Math.sqrt(Math.pow(i,2)+Math.pow(e.height,2))/5,n=this.render.convertToBook(t);return n.x>0&&n.y>0&&n.xe.width-s)&&(n.ye.height-s)}}class g{constructor(t,e){this.leftPage=null,this.rightPage=null,this.flippingPage=null,this.bottomPage=null,this.direction=null,this.orientation=null,this.shadow=null,this.animation=null,this.pageRect=null,this.boundsRect=null,this.timer=0,this.safari=!1,this.setting=e,this.app=t;const i=new RegExp("Version\\/[\\d\\.]+.*Safari/");this.safari=null!==i.exec(window.navigator.userAgent)}render(t){if(null!==this.animation){const e=Math.round((t-this.animation.startedAt)/this.animation.durationFrame);e{this.render(e),requestAnimationFrame(t)};requestAnimationFrame(t)}startAnimation(t,e,i){this.finishAnimation(),this.animation={frames:t,duration:e,durationFrame:e/t.length,onAnimateEnd:i,startedAt:this.timer}}finishAnimation(){null!==this.animation&&(this.animation.frames[this.animation.frames.length-1](),null!==this.animation.onAnimateEnd&&this.animation.onAnimateEnd()),this.animation=null}update(){this.boundsRect=null;const t=this.calculateBoundsRect();this.orientation!==t&&(this.orientation=t,this.app.updateOrientation(t))}calculateBoundsRect(){let t="landscape";const e=this.getBlockWidth(),i=e/2,s=this.getBlockHeight()/2,n=this.setting.width/this.setting.height;let h=this.setting.width,r=this.setting.height,a=i-h;return"stretch"===this.setting.size?(e<2*this.setting.minWidth&&this.app.getSettings().usePortrait&&(t="portrait"),h="portrait"===t?this.getBlockWidth():this.getBlockWidth()/2,h>this.setting.maxWidth&&(h=this.setting.maxWidth),r=h/n,r>this.getBlockHeight()&&(r=this.getBlockHeight(),h=r*n),a="portrait"===t?i-h/2-h:i-h):e<2*h&&this.app.getSettings().usePortrait&&(t="portrait",a=i-h/2-h),this.boundsRect={left:a,top:s-r/2,width:2*h,height:r,pageWidth:h},t}setShadowData(t,e,i,s){if(!this.app.getSettings().drawShadow)return;const n=100*this.getSettings().maxShadowOpacity;this.shadow={pos:t,angle:e,width:3*this.getRect().pageWidth/4*i/100,opacity:(100-i)*n/100/100,direction:s,progress:2*i}}clearShadow(){this.shadow=null}getBlockWidth(){return this.app.getUI().getDistElement().offsetWidth}getBlockHeight(){return this.app.getUI().getDistElement().offsetHeight}getDirection(){return this.direction}getRect(){return null===this.boundsRect&&this.calculateBoundsRect(),this.boundsRect}getSettings(){return this.app.getSettings()}getOrientation(){return this.orientation}setPageRect(t){this.pageRect=t}setDirection(t){this.direction=t}setRightPage(t){null!==t&&t.setOrientation(1),this.rightPage=t}setLeftPage(t){null!==t&&t.setOrientation(0),this.leftPage=t}setBottomPage(t){null!==t&&t.setOrientation(1===this.direction?0:1),this.bottomPage=t}setFlippingPage(t){null!==t&&t.setOrientation(0===this.direction&&"portrait"!==this.orientation?0:1),this.flippingPage=t}convertToBook(t){const e=this.getRect();return{x:t.x-e.left,y:t.y-e.top}}isSafari(){return this.safari}convertToPage(t,e){e||(e=this.direction);const i=this.getRect();return{x:0===e?t.x-i.left-i.width/2:i.width/2-t.x+i.left,y:t.y-i.top}}convertToGlobal(t,e){if(e||(e=this.direction),null==t)return null;const i=this.getRect();return{x:0===e?t.x+i.left+i.width/2:i.width/2-t.x+i.left,y:t.y+i.top}}convertRectToGlobal(t,e){return e||(e=this.direction),{topLeft:this.convertToGlobal(t.topLeft,e),topRight:this.convertToGlobal(t.topRight,e),bottomLeft:this.convertToGlobal(t.bottomLeft,e),bottomRight:this.convertToGlobal(t.bottomRight,e)}}}class l extends g{constructor(t,e,i){super(t,e),this.canvas=i,this.ctx=i.getContext("2d")}getContext(){return this.ctx}reload(){}drawFrame(){this.clear(),"portrait"!==this.orientation&&null!=this.leftPage&&this.leftPage.simpleDraw(0),null!=this.rightPage&&this.rightPage.simpleDraw(1),null!=this.bottomPage&&this.bottomPage.draw(),this.drawBookShadow(),null!=this.flippingPage&&this.flippingPage.draw(),null!=this.shadow&&(this.drawOuterShadow(),this.drawInnerShadow());const t=this.getRect();"portrait"===this.orientation&&(this.ctx.beginPath(),this.ctx.rect(t.left+t.pageWidth,t.top,t.width,t.height),this.ctx.clip())}drawBookShadow(){const t=this.getRect();this.ctx.save(),this.ctx.beginPath();const e=t.width/20;this.ctx.rect(t.left,t.top,t.width,t.height);const i={x:t.left+t.width/2-e/2,y:0};this.ctx.translate(i.x,i.y);const s=this.ctx.createLinearGradient(0,0,e,0);s.addColorStop(0,"rgba(0, 0, 0, 0)"),s.addColorStop(.4,"rgba(0, 0, 0, 0.2)"),s.addColorStop(.49,"rgba(0, 0, 0, 0.1)"),s.addColorStop(.5,"rgba(0, 0, 0, 0.5)"),s.addColorStop(.51,"rgba(0, 0, 0, 0.4)"),s.addColorStop(1,"rgba(0, 0, 0, 0)"),this.ctx.clip(),this.ctx.fillStyle=s,this.ctx.fillRect(0,0,e,2*t.height),this.ctx.restore()}drawOuterShadow(){const t=this.getRect();this.ctx.save(),this.ctx.beginPath(),this.ctx.rect(t.left,t.top,t.width,t.height);const e=this.convertToGlobal({x:this.shadow.pos.x,y:this.shadow.pos.y});this.ctx.translate(e.x,e.y),this.ctx.rotate(Math.PI+this.shadow.angle+Math.PI/2);const i=this.ctx.createLinearGradient(0,0,this.shadow.width,0);0===this.shadow.direction?(this.ctx.translate(0,-100),i.addColorStop(0,"rgba(0, 0, 0, "+this.shadow.opacity+")"),i.addColorStop(1,"rgba(0, 0, 0, 0)")):(this.ctx.translate(-this.shadow.width,-100),i.addColorStop(0,"rgba(0, 0, 0, 0)"),i.addColorStop(1,"rgba(0, 0, 0, "+this.shadow.opacity+")")),this.ctx.clip(),this.ctx.fillStyle=i,this.ctx.fillRect(0,0,this.shadow.width,2*t.height),this.ctx.restore()}drawInnerShadow(){const t=this.getRect();this.ctx.save(),this.ctx.beginPath();const e=this.convertToGlobal({x:this.shadow.pos.x,y:this.shadow.pos.y}),i=this.convertRectToGlobal(this.pageRect);this.ctx.moveTo(i.topLeft.x,i.topLeft.y),this.ctx.lineTo(i.topRight.x,i.topRight.y),this.ctx.lineTo(i.bottomRight.x,i.bottomRight.y),this.ctx.lineTo(i.bottomLeft.x,i.bottomLeft.y),this.ctx.translate(e.x,e.y),this.ctx.rotate(Math.PI+this.shadow.angle+Math.PI/2);const s=3*this.shadow.width/4,n=this.ctx.createLinearGradient(0,0,s,0);0===this.shadow.direction?(this.ctx.translate(-s,-100),n.addColorStop(1,"rgba(0, 0, 0, "+this.shadow.opacity+")"),n.addColorStop(.9,"rgba(0, 0, 0, 0.05)"),n.addColorStop(.7,"rgba(0, 0, 0, "+this.shadow.opacity+")"),n.addColorStop(0,"rgba(0, 0, 0, 0)")):(this.ctx.translate(0,-100),n.addColorStop(0,"rgba(0, 0, 0, "+this.shadow.opacity+")"),n.addColorStop(.1,"rgba(0, 0, 0, 0.05)"),n.addColorStop(.3,"rgba(0, 0, 0, "+this.shadow.opacity+")"),n.addColorStop(1,"rgba(0, 0, 0, 0)")),this.ctx.clip(),this.ctx.fillStyle=n,this.ctx.fillRect(0,0,s,2*t.height),this.ctx.restore()}clear(){this.ctx.fillStyle="white",this.ctx.fillRect(0,0,this.canvas.width,this.canvas.height)}}class d{constructor(t,e,i){this.touchPoint=null,this.swipeTimeout=250,this.onResize=()=>{this.update()},this.onMouseDown=t=>{if(this.checkTarget(t.target)){const e=this.getMousePos(t.clientX,t.clientY);this.app.startUserTouch(e),t.preventDefault()}},this.onTouchStart=t=>{if(this.checkTarget(t.target)&&t.changedTouches.length>0){const e=t.changedTouches[0],i=this.getMousePos(e.clientX,e.clientY);this.touchPoint={point:i,time:Date.now()},setTimeout(()=>{null!==this.touchPoint&&this.app.startUserTouch(i)},this.swipeTimeout),this.app.getSettings().mobileScrollSupport||t.preventDefault()}},this.onMouseUp=t=>{const e=this.getMousePos(t.clientX,t.clientY);this.app.userStop(e)},this.onMouseMove=t=>{const e=this.getMousePos(t.clientX,t.clientY);this.app.userMove(e,!1)},this.onTouchMove=t=>{if(t.changedTouches.length>0){const e=t.changedTouches[0],i=this.getMousePos(e.clientX,e.clientY);this.app.getSettings().mobileScrollSupport?(null!==this.touchPoint&&(Math.abs(this.touchPoint.point.x-i.x)>10||"read"!==this.app.getState())&&t.cancelable&&this.app.userMove(i,!0),"read"!==this.app.getState()&&t.preventDefault()):this.app.userMove(i,!0)}},this.onTouchEnd=t=>{if(t.changedTouches.length>0){const e=t.changedTouches[0],i=this.getMousePos(e.clientX,e.clientY);let s=!1;if(null!==this.touchPoint){const t=i.x-this.touchPoint.point.x,e=Math.abs(i.y-this.touchPoint.point.y);Math.abs(t)>this.swipeDistance&&e<2*this.swipeDistance&&Date.now()-this.touchPoint.time0?this.app.flipPrev(this.touchPoint.point.y'),this.wrapper=t.querySelector(".stf__wrapper"),this.app=e;const s=this.app.getSettings().usePortrait?1:2;t.style.minWidth=i.minWidth*s+"px",t.style.minHeight=i.minHeight+"px","fixed"===i.size&&(t.style.minWidth=i.width*s+"px",t.style.minHeight=i.height+"px"),i.autoSize&&(t.style.width="100%",t.style.maxWidth=2*i.maxWidth+"px"),t.style.display="block",window.addEventListener("resize",this.onResize,!1),this.swipeDistance=i.swipeDistance}destroy(){this.app.getSettings().useMouseEvents&&this.removeHandlers(),this.distElement.remove(),this.wrapper.remove()}getDistElement(){return this.distElement}getWrapper(){return this.wrapper}setOrientationStyle(t){this.wrapper.classList.remove("--portrait","--landscape"),"portrait"===t?(this.app.getSettings().autoSize&&(this.wrapper.style.paddingBottom=this.app.getSettings().height/this.app.getSettings().width*100+"%"),this.wrapper.classList.add("--portrait")):(this.app.getSettings().autoSize&&(this.wrapper.style.paddingBottom=this.app.getSettings().height/(2*this.app.getSettings().width)*100+"%"),this.wrapper.classList.add("--landscape")),this.update()}removeHandlers(){window.removeEventListener("resize",this.onResize),this.distElement.removeEventListener("mousedown",this.onMouseDown),this.distElement.removeEventListener("touchstart",this.onTouchStart),window.removeEventListener("mousemove",this.onMouseMove),window.removeEventListener("touchmove",this.onTouchMove),window.removeEventListener("mouseup",this.onMouseUp),window.removeEventListener("touchend",this.onTouchEnd)}setHandlers(){window.addEventListener("resize",this.onResize,!1),this.app.getSettings().useMouseEvents&&(this.distElement.addEventListener("mousedown",this.onMouseDown),this.distElement.addEventListener("touchstart",this.onTouchStart),window.addEventListener("mousemove",this.onMouseMove),window.addEventListener("touchmove",this.onTouchMove,{passive:!this.app.getSettings().mobileScrollSupport}),window.addEventListener("mouseup",this.onMouseUp),window.addEventListener("touchend",this.onTouchEnd))}getMousePos(t,e){const i=this.distElement.getBoundingClientRect();return{x:t-i.left,y:e-i.top}}checkTarget(t){return!this.app.getSettings().clickEventForward||!["a","button"].includes(t.tagName.toLowerCase())}}class p extends d{constructor(t,e,i,s){super(t,e,i),this.wrapper.insertAdjacentHTML("afterbegin",'
'),this.distElement=t.querySelector(".stf__block"),this.items=s;for(const t of s)this.distElement.appendChild(t);this.setHandlers()}clear(){for(const t of this.items)this.parentElement.appendChild(t)}updateItems(t){this.removeHandlers(),this.distElement.innerHTML="";for(const e of t)this.distElement.appendChild(e);this.items=t,this.setHandlers()}update(){this.app.getRender().update()}}class c extends d{constructor(t,e,i){super(t,e,i),this.wrapper.innerHTML='',this.canvas=t.querySelectorAll("canvas")[0],this.distElement=this.canvas,this.resizeCanvas(),this.setHandlers()}resizeCanvas(){const t=getComputedStyle(this.canvas),e=parseInt(t.getPropertyValue("width"),10),i=parseInt(t.getPropertyValue("height"),10);this.canvas.width=e,this.canvas.height=i}getCanvas(){return this.canvas}update(){this.resizeCanvas(),this.app.getRender().update()}}class u extends g{constructor(t,e,i){super(t,e),this.outerShadow=null,this.innerShadow=null,this.hardShadow=null,this.hardInnerShadow=null,this.element=i,this.createShadows()}createShadows(){this.element.insertAdjacentHTML("beforeend",'
\n
\n
\n
'),this.outerShadow=this.element.querySelector(".stf__outerShadow"),this.innerShadow=this.element.querySelector(".stf__innerShadow"),this.hardShadow=this.element.querySelector(".stf__hardShadow"),this.hardInnerShadow=this.element.querySelector(".stf__hardInnerShadow")}clearShadow(){super.clearShadow(),this.outerShadow.style.cssText="display: none",this.innerShadow.style.cssText="display: none",this.hardShadow.style.cssText="display: none",this.hardInnerShadow.style.cssText="display: none"}reload(){this.element.querySelector(".stf__outerShadow")||this.createShadows()}drawHardInnerShadow(){const t=this.getRect(),e=this.shadow.progress>100?200-this.shadow.progress:this.shadow.progress;let i=(100-e)*(2.5*t.pageWidth)/100+20;i>t.pageWidth&&(i=t.pageWidth);let s=`\n display: block;\n z-index: ${(this.getSettings().startZIndex+5).toString(10)};\n width: ${i}px;\n height: ${t.height}px;\n background: linear-gradient(to right,\n rgba(0, 0, 0, ${this.shadow.opacity*e/100}) 5%,\n rgba(0, 0, 0, 0) 100%);\n left: ${t.left+t.width/2}px;\n transform-origin: 0 0;\n `;s+=0===this.getDirection()&&this.shadow.progress>100||1===this.getDirection()&&this.shadow.progress<=100?"transform: translate3d(0, 0, 0);":"transform: translate3d(0, 0, 0) rotateY(180deg);",this.hardInnerShadow.style.cssText=s}drawHardOuterShadow(){const t=this.getRect();let e=(100-(this.shadow.progress>100?200-this.shadow.progress:this.shadow.progress))*(2.5*t.pageWidth)/100+20;e>t.pageWidth&&(e=t.pageWidth);let i=`\n display: block;\n z-index: ${(this.getSettings().startZIndex+4).toString(10)};\n width: ${e}px;\n height: ${t.height}px;\n background: linear-gradient(to left, rgba(0, 0, 0, ${this.shadow.opacity}) 5%, rgba(0, 0, 0, 0) 100%);\n left: ${t.left+t.width/2}px;\n transform-origin: 0 0;\n `;i+=0===this.getDirection()&&this.shadow.progress>100||1===this.getDirection()&&this.shadow.progress<=100?"transform: translate3d(0, 0, 0) rotateY(180deg);":"transform: translate3d(0, 0, 0);",this.hardShadow.style.cssText=i}drawInnerShadow(){const t=this.getRect(),e=3*this.shadow.width/4,i=0===this.getDirection()?e:0,s=0===this.getDirection()?"to left":"to right",h=this.convertToGlobal(this.shadow.pos),r=this.shadow.angle+3*Math.PI/2,a=[this.pageRect.topLeft,this.pageRect.topRight,this.pageRect.bottomRight,this.pageRect.bottomLeft];let o="polygon( ";for(const t of a){let e=1===this.getDirection()?{x:-t.x+this.shadow.pos.x,y:t.y-this.shadow.pos.y}:{x:t.x-this.shadow.pos.x,y:t.y-this.shadow.pos.y};e=n.GetRotatedPoint(e,{x:i,y:100},r),o+=e.x+"px "+e.y+"px, "}o=o.slice(0,-2),o+=")";const g=`\n display: block;\n z-index: ${(this.getSettings().startZIndex+10).toString(10)};\n width: ${e}px;\n height: ${2*t.height}px;\n background: linear-gradient(${s},\n rgba(0, 0, 0, ${this.shadow.opacity}) 5%,\n rgba(0, 0, 0, 0.05) 15%,\n rgba(0, 0, 0, ${this.shadow.opacity}) 35%,\n rgba(0, 0, 0, 0) 100%);\n transform-origin: ${i}px 100px;\n transform: translate3d(${h.x-i}px, ${h.y-100}px, 0) rotate(${r}rad);\n clip-path: ${o};\n -webkit-clip-path: ${o};\n `;this.innerShadow.style.cssText=g}drawOuterShadow(){const t=this.getRect(),e=this.convertToGlobal({x:this.shadow.pos.x,y:this.shadow.pos.y}),i=this.shadow.angle+3*Math.PI/2,s=1===this.getDirection()?this.shadow.width:0,h=0===this.getDirection()?"to right":"to left",r=[{x:0,y:0},{x:t.pageWidth,y:0},{x:t.pageWidth,y:t.height},{x:0,y:t.height}];let a="polygon( ";for(const t of r)if(null!==t){let e=1===this.getDirection()?{x:-t.x+this.shadow.pos.x,y:t.y-this.shadow.pos.y}:{x:t.x-this.shadow.pos.x,y:t.y-this.shadow.pos.y};e=n.GetRotatedPoint(e,{x:s,y:100},i),a+=e.x+"px "+e.y+"px, "}a=a.slice(0,-2),a+=")";const o=`\n display: block;\n z-index: ${(this.getSettings().startZIndex+10).toString(10)};\n width: ${this.shadow.width}px;\n height: ${2*t.height}px;\n background: linear-gradient(${h}, rgba(0, 0, 0, ${this.shadow.opacity}), rgba(0, 0, 0, 0));\n transform-origin: ${s}px 100px;\n transform: translate3d(${e.x-s}px, ${e.y-100}px, 0) rotate(${i}rad);\n clip-path: ${a};\n -webkit-clip-path: ${a};\n `;this.outerShadow.style.cssText=o}drawLeftPage(){"portrait"!==this.orientation&&null!==this.leftPage&&(1===this.direction&&null!==this.flippingPage&&"hard"===this.flippingPage.getDrawingDensity()?(this.leftPage.getElement().style.zIndex=(this.getSettings().startZIndex+5).toString(10),this.leftPage.setHardDrawingAngle(180+this.flippingPage.getHardAngle()),this.leftPage.draw(this.flippingPage.getDrawingDensity())):this.leftPage.simpleDraw(0))}drawRightPage(){null!==this.rightPage&&(0===this.direction&&null!==this.flippingPage&&"hard"===this.flippingPage.getDrawingDensity()?(this.rightPage.getElement().style.zIndex=(this.getSettings().startZIndex+5).toString(10),this.rightPage.setHardDrawingAngle(180+this.flippingPage.getHardAngle()),this.rightPage.draw(this.flippingPage.getDrawingDensity())):this.rightPage.simpleDraw(1))}drawBottomPage(){if(null===this.bottomPage)return;const t=null!=this.flippingPage?this.flippingPage.getDrawingDensity():null;"portrait"===this.orientation&&1===this.direction||(this.bottomPage.getElement().style.zIndex=(this.getSettings().startZIndex+3).toString(10),this.bottomPage.draw(t))}drawFrame(){this.clear(),this.drawLeftPage(),this.drawRightPage(),this.drawBottomPage(),null!=this.flippingPage&&(this.flippingPage.getElement().style.zIndex=(this.getSettings().startZIndex+5).toString(10),this.flippingPage.draw()),null!=this.shadow&&null!==this.flippingPage&&("soft"===this.flippingPage.getDrawingDensity()?(this.drawOuterShadow(),this.drawInnerShadow()):(this.drawHardOuterShadow(),this.drawHardInnerShadow()))}clear(){for(const t of this.app.getPageCollection().getPages())t!==this.leftPage&&t!==this.rightPage&&t!==this.flippingPage&&t!==this.bottomPage&&(t.getElement().style.cssText="display: none"),t.getTemporaryCopy()!==this.flippingPage&&t.hideTemporaryCopy()}update(){super.update(),null!==this.rightPage&&this.rightPage.setOrientation(1),null!==this.leftPage&&this.leftPage.setOrientation(0)}}class w{constructor(){this._default={startPage:0,size:"fixed",width:0,height:0,minWidth:0,maxWidth:0,minHeight:0,maxHeight:0,drawShadow:!0,flippingTime:1e3,usePortrait:!0,startZIndex:0,autoSize:!0,maxShadowOpacity:1,showCover:!1,mobileScrollSupport:!0,swipeDistance:30,clickEventForward:!0,useMouseEvents:!0,showPageCorners:!0,disableFlipByClick:!1}}getSettings(t){const e=this._default;if(Object.assign(e,t),"stretch"!==e.size&&"fixed"!==e.size)throw new Error('Invalid size type. Available only "fixed" and "stretch" value');if(e.width<=0||e.height<=0)throw new Error("Invalid width or height");if(e.flippingTime<=0)throw new Error("Invalid flipping time");return"stretch"===e.size?(e.minWidth<=0&&(e.minWidth=100),e.maxWidth{this.ui.update(),this.trigger("init",this,{page:this.setting.startPage,mode:this.render.getOrientation()})},1)}loadFromHTML(t){this.ui=new p(this.block,this,this.setting,t),this.render=new u(this,this.setting,this.ui.getDistElement()),this.flipController=new o(this.render,this),this.pages=new r(this,this.render,this.ui.getDistElement(),t),this.pages.load(),this.render.start(),this.pages.show(this.setting.startPage),setTimeout(()=>{this.ui.update(),this.trigger("init",this,{page:this.setting.startPage,mode:this.render.getOrientation()})},1)}updateFromImages(t){const e=this.pages.getCurrentPageIndex();this.pages.destroy(),this.pages=new s(this,this.render,t),this.pages.load(),this.pages.show(e),this.trigger("update",this,{page:e,mode:this.render.getOrientation()})}updateFromHtml(t){const e=this.pages.getCurrentPageIndex();this.pages.destroy(),this.pages=new r(this,this.render,this.ui.getDistElement(),t),this.pages.load(),this.ui.updateItems(t),this.render.reload(),this.pages.show(e),this.trigger("update",this,{page:e,mode:this.render.getOrientation()})}clear(){this.pages.destroy(),this.ui.clear()}turnToPrevPage(){this.pages.showPrev()}turnToNextPage(){this.pages.showNext()}turnToPage(t){this.pages.show(t)}flipNext(t="top"){this.flipController.flipNext(t)}flipPrev(t="top"){this.flipController.flipPrev(t)}flip(t,e="top"){this.flipController.flipToPage(t,e)}updateState(t){this.trigger("changeState",this,t)}updatePageIndex(t){this.trigger("flip",this,t)}updateOrientation(t){this.ui.setOrientationStyle(t),this.update(),this.trigger("changeOrientation",this,t)}getPageCount(){return this.pages.getPageCount()}getCurrentPageIndex(){return this.pages.getCurrentPageIndex()}getPage(t){return this.pages.getPage(t)}getRender(){return this.render}getFlipController(){return this.flipController}getOrientation(){return this.render.getOrientation()}getBoundsRect(){return this.render.getRect()}getSettings(){return this.setting}getUI(){return this.ui}getState(){return this.flipController.getState()}getPageCollection(){return this.pages}startUserTouch(t){this.mousePosition=t,this.isUserTouch=!0,this.isUserMove=!1}userMove(t,e){this.isUserTouch||e||!this.setting.showPageCorners?this.isUserTouch&&n.GetDistanceBetweenTwoPoint(this.mousePosition,t)>5&&(this.isUserMove=!0,this.flipController.fold(t)):this.flipController.showCorner(t)}userStop(t,e=!1){this.isUserTouch&&(this.isUserTouch=!1,e||(this.isUserMove?this.flipController.stopMove():this.flipController.flip(t)))}}export{x as PageFlip}; ++class t{constructor(t,e){this.state={angle:0,area:[],position:{x:0,y:0},hardAngle:0,hardDrawingAngle:0},this.createdDensity=e,this.nowDrawingDensity=this.createdDensity,this.render=t}setDensity(t){this.createdDensity=t,this.nowDrawingDensity=t}setDrawingDensity(t){this.nowDrawingDensity=t}setPosition(t){this.state.position=t}setAngle(t){this.state.angle=t}setArea(t){this.state.area=t}setHardDrawingAngle(t){this.state.hardDrawingAngle=t}setHardAngle(t){this.state.hardAngle=t,this.state.hardDrawingAngle=t}setOrientation(t){this.orientation=t}getDrawingDensity(){return this.nowDrawingDensity}getDensity(){return this.createdDensity}getHardAngle(){return this.state.hardAngle}}class e extends t{constructor(t,e,i){super(t,i),this.image=null,this.isLoad=!1,this.loadingAngle=0,this.image=new Image,this.image.src=e}draw(t){const e=this.render.getContext(),i=this.render.convertToGlobal(this.state.position),s=this.render.getRect().pageWidth,n=this.render.getRect().height;e.save(),e.translate(i.x,i.y),e.beginPath();for(let t of this.state.area)null!==t&&(t=this.render.convertToGlobal(t),e.lineTo(t.x-i.x,t.y-i.y));e.rotate(this.state.angle),e.clip(),this.isLoad?e.drawImage(this.image,0,0,s,n):this.drawLoader(e,{x:0,y:0},s,n),e.restore()}simpleDraw(t){const e=this.render.getRect(),i=this.render.getContext(),s=e.pageWidth,n=e.height,h=1===t?e.left+e.pageWidth:e.left,r=e.top;this.isLoad?i.drawImage(this.image,h,r,s,n):this.drawLoader(i,{x:h,y:r},s,n)}drawLoader(t,e,i,s){t.beginPath(),t.strokeStyle="rgb(200, 200, 200)",t.fillStyle="rgb(255, 255, 255)",t.lineWidth=1,t.rect(e.x+1,e.y+1,i-1,s-1),t.stroke(),t.fill();const n={x:e.x+i/2,y:e.y+s/2};t.beginPath(),t.lineWidth=10,t.arc(n.x,n.y,20,this.loadingAngle,3*Math.PI/2+this.loadingAngle),t.stroke(),t.closePath(),this.loadingAngle+=.07,this.loadingAngle>=2*Math.PI&&(this.loadingAngle=0)}load(){this.isLoad||(this.image.onload=()=>{this.isLoad=!0})}newTemporaryCopy(){return this}getTemporaryCopy(){return this}hideTemporaryCopy(){}}class i{constructor(t,e){this.pages=[],this.currentPageIndex=0,this.currentSpreadIndex=0,this.landscapeSpread=[],this.portraitSpread=[],this.render=e,this.app=t,this.currentPageIndex=0,this.isShowCover=this.app.getSettings().showCover}destroy(){this.pages=[]}createSpread(){this.landscapeSpread=[],this.portraitSpread=[];for(let t=0;t=0&&t0?this.pages[e-1]:null}getFlippingPage(t){const e=this.currentSpreadIndex;if("portrait"===this.render.getOrientation())return 0===t?this.pages[e].newTemporaryCopy():this.pages[e-1];{const i=0===t?this.getSpread()[e+1]:this.getSpread()[e-1];return 1===i.length||0===t?this.pages[i[0]]:this.pages[i[1]]}}getBottomPage(t){const e=this.currentSpreadIndex;if("portrait"===this.render.getOrientation())return 0===t?this.pages[e+1]:this.pages[e-1];{const i=0===t?this.getSpread()[e+1]:this.getSpread()[e-1];return 1===i.length?this.pages[i[0]]:0===t?this.pages[i[1]]:this.pages[i[0]]}}showNext(){this.currentSpreadIndex0&&(this.currentSpreadIndex--,this.showSpread())}getCurrentPageIndex(){return this.currentPageIndex}show(t=null){if(null===t&&(t=this.currentPageIndex),t<0||t>=this.pages.length)return;const e=this.getSpreadIndexByPage(t);null!==e&&(this.currentSpreadIndex=e,this.showSpread())}getCurrentSpreadIndex(){return this.currentSpreadIndex}setCurrentSpreadIndex(t){if(!(t>=0&&t=t.left&&e.x<=t.width+t.left&&e.y>=t.top&&e.y<=t.top+t.height?e:null}static GetRotatedPoint(t,e,i){return{x:t.x*Math.cos(i)+t.y*Math.sin(i)+e.x,y:t.y*Math.cos(i)-t.x*Math.sin(i)+e.y}}static LimitPointToCircle(t,e,i){if(n.GetDistanceBetweenTwoPoint(t,i)<=e)return i;const s=t.x,h=t.y,r=i.x,a=i.y;let o=Math.sqrt(Math.pow(e,2)*Math.pow(s-r,2)/(Math.pow(s-r,2)+Math.pow(h-a,2)))+s;i.x<0&&(o*=-1);let g=(o-s)*(h-a)/(s-r)+h;return s-r+h===0&&(g=e),{x:o,y:g}}static GetIntersectBetweenTwoSegment(t,e,i){return n.PointInRect(t,n.GetIntersectBeetwenTwoLine(e,i))}static GetIntersectBeetwenTwoLine(t,e){const i=t[0].y-t[1].y,s=e[0].y-e[1].y,n=t[1].x-t[0].x,h=e[1].x-e[0].x,r=t[0].x*t[1].y-t[1].x*t[0].y,a=e[0].x*e[1].y-e[1].x*e[0].y,o=i*a-s*r,g=n*a-h*r,l=-(r*h-a*n)/(i*h-s*n),d=-(i*a-s*r)/(i*h-s*n);if(isFinite(l)&&isFinite(d))return{x:l,y:d};if(Math.abs(o-g)<.1)throw new Error("Segment included");return null}static GetCordsFromTwoPoint(t,e){const i=Math.abs(t.x-e.x),s=Math.abs(t.y-e.y),n=Math.max(i,s),h=[t];function r(t,e,i,s,n){return e>t?t+n*(i/s):e=10&&t.push(this.sideIntersectPoint):"top"===this.corner&&t.push({x:this.pageWidth,y:this.pageHeight}),t.push(this.bottomIntersectPoint),t.push(this.topIntersectPoint),t}getAngle(){return 0===this.direction?-this.angle:this.angle}getRect(){return this.rect}getPosition(){return this.position}getActiveCorner(){return 0===this.direction?this.rect.topLeft:this.rect.topRight}getDirection(){return this.direction}getFlippingProgress(){return Math.abs((this.position.x-this.pageWidth)/(2*this.pageWidth)*100)}getCorner(){return this.corner}getBottomPagePosition(){return 1===this.direction?{x:this.pageWidth,y:0}:{x:0,y:0}}getShadowStartPoint(){return"top"===this.corner?this.topIntersectPoint:null!==this.sideIntersectPoint?this.sideIntersectPoint:this.topIntersectPoint}getShadowAngle(){const t=n.GetAngleBetweenTwoLine(this.getSegmentToShadowLine(),[{x:0,y:0},{x:this.pageWidth,y:0}]);return 0===this.direction?t:Math.PI-t}calcAngleAndPosition(t){let e=t;if(this.updateAngleAndGeometry(e),e="top"===this.corner?this.checkPositionAtCenterLine(e,{x:0,y:0},{x:0,y:this.pageHeight}):this.checkPositionAtCenterLine(e,{x:0,y:this.pageHeight},{x:0,y:0}),Math.abs(e.x-this.pageWidth)<1&&Math.abs(e.y)<1)throw new Error("Point is too small");return e}updateAngleAndGeometry(t){this.angle=this.calculateAngle(t),this.rect=this.getPageRect(t)}calculateAngle(t){const e=this.pageWidth-t.x+1,i="bottom"===this.corner?this.pageHeight-t.y:t.y;let s=2*Math.acos(e/Math.sqrt(i*i+e*e));i<0&&(s=-s);const n=Math.PI-s;if(!isFinite(s)||n>=0&&n<.003)throw new Error("The G point is too small");return"bottom"===this.corner&&(s=-s),s}getPageRect(t){return"top"===this.corner?this.getRectFromBasePoint([{x:0,y:0},{x:this.pageWidth,y:0},{x:0,y:this.pageHeight},{x:this.pageWidth,y:this.pageHeight}],t):this.getRectFromBasePoint([{x:0,y:-this.pageHeight},{x:this.pageWidth,y:-this.pageHeight},{x:0,y:0},{x:this.pageWidth,y:0}],t)}getRectFromBasePoint(t,e){return{topLeft:this.getRotatedPoint(t[0],e),topRight:this.getRotatedPoint(t[1],e),bottomLeft:this.getRotatedPoint(t[2],e),bottomRight:this.getRotatedPoint(t[3],e)}}getRotatedPoint(t,e){return{x:t.x*Math.cos(this.angle)+t.y*Math.sin(this.angle)+e.x,y:t.y*Math.cos(this.angle)-t.x*Math.sin(this.angle)+e.y}}calculateIntersectPoint(t){const e={left:-1,top:-1,width:this.pageWidth+2,height:this.pageHeight+2};"top"===this.corner?(this.topIntersectPoint=n.GetIntersectBetweenTwoSegment(e,[t,this.rect.topRight],[{x:0,y:0},{x:this.pageWidth,y:0}]),this.sideIntersectPoint=n.GetIntersectBetweenTwoSegment(e,[t,this.rect.bottomLeft],[{x:this.pageWidth,y:0},{x:this.pageWidth,y:this.pageHeight}]),this.bottomIntersectPoint=n.GetIntersectBetweenTwoSegment(e,[this.rect.bottomLeft,this.rect.bottomRight],[{x:0,y:this.pageHeight},{x:this.pageWidth,y:this.pageHeight}])):(this.topIntersectPoint=n.GetIntersectBetweenTwoSegment(e,[this.rect.topLeft,this.rect.topRight],[{x:0,y:0},{x:this.pageWidth,y:0}]),this.sideIntersectPoint=n.GetIntersectBetweenTwoSegment(e,[t,this.rect.topLeft],[{x:this.pageWidth,y:0},{x:this.pageWidth,y:this.pageHeight}]),this.bottomIntersectPoint=n.GetIntersectBetweenTwoSegment(e,[this.rect.bottomLeft,this.rect.bottomRight],[{x:0,y:this.pageHeight},{x:this.pageWidth,y:this.pageHeight}]))}checkPositionAtCenterLine(t,e,i){let s=t;const h=n.LimitPointToCircle(e,this.pageWidth,s);s!==h&&(s=h,this.updateAngleAndGeometry(s));const r=Math.sqrt(Math.pow(this.pageWidth,2)+Math.pow(this.pageHeight,2));let a=this.rect.bottomRight,o=this.rect.topLeft;if("bottom"===this.corner&&(a=this.rect.topRight,o=this.rect.bottomLeft),a.x<=0){const t=n.LimitPointToCircle(i,r,o);t!==s&&(s=t,this.updateAngleAndGeometry(s))}return s}getSegmentToShadowLine(){const t=this.getShadowStartPoint();return[t,t!==this.sideIntersectPoint&&null!==this.sideIntersectPoint?this.sideIntersectPoint:this.bottomIntersectPoint]}}class o{constructor(t,e){this.flippingPage=null,this.bottomPage=null,this.calc=null,this.state="read",this.render=t,this.app=e}fold(t){this.setState("user_fold"),null===this.calc&&this.start(t),this.do(this.render.convertToPage(t))}flip(t){if(this.app.getSettings().disableFlipByClick&&!this.isPointOnCorners(t))return;if(null!==this.calc&&this.render.finishAnimation(),!this.start(t))return;const e=this.getBoundsRect();this.setState("flipping");const i=e.height/10,s="bottom"===this.calc.getCorner()?e.height-i:i,n="bottom"===this.calc.getCorner()?e.height:0;this.calc.calc({x:e.pageWidth-i,y:s}),this.animateFlippingTo({x:e.pageWidth-i,y:s},{x:-e.pageWidth,y:n},!0)}start(t){this.reset();const e=this.render.convertToBook(t),i=this.getBoundsRect(),s=this.getDirectionByPoint(e),n=e.y>=i.height/2?"bottom":"top";if(!this.checkDirection(s))return!1;try{if(this.flippingPage=this.app.getPageCollection().getFlippingPage(s),this.bottomPage=this.app.getPageCollection().getBottomPage(s),"landscape"===this.render.getOrientation())if(1===s){const t=this.app.getPageCollection().nextBy(this.flippingPage);null!==t&&this.flippingPage.getDensity()!==t.getDensity()&&(this.flippingPage.setDrawingDensity("hard"),t.setDrawingDensity("hard"))}else{const t=this.app.getPageCollection().prevBy(this.flippingPage);null!==t&&this.flippingPage.getDensity()!==t.getDensity()&&(this.flippingPage.setDrawingDensity("hard"),t.setDrawingDensity("hard"))}return this.render.setDirection(s),this.calc=new a(s,n,i.pageWidth.toString(10),i.height.toString(10)),!0}catch(t){return!1}}do(t){if(null!==this.calc&&this.calc.calc(t)){const t=this.calc.getFlippingProgress();this.bottomPage.setArea(this.calc.getBottomClipArea()),this.bottomPage.setPosition(this.calc.getBottomPagePosition()),this.bottomPage.setAngle(0),this.bottomPage.setHardAngle(0),this.flippingPage.setArea(this.calc.getFlippingClipArea()),this.flippingPage.setPosition(this.calc.getActiveCorner()),this.flippingPage.setAngle(this.calc.getAngle()),0===this.calc.getDirection()?this.flippingPage.setHardAngle(90*(200-2*t)/100):this.flippingPage.setHardAngle(-90*(200-2*t)/100),this.render.setPageRect(this.calc.getRect()),this.render.setBottomPage(this.bottomPage),this.render.setFlippingPage(this.flippingPage),this.render.setShadowData(this.calc.getShadowStartPoint(),this.calc.getShadowAngle(),t,this.calc.getDirection())}}flipToPage(t,e){const i=this.app.getPageCollection().getCurrentSpreadIndex(),s=this.app.getPageCollection().getSpreadIndexByPage(t);try{s>i&&(this.app.getPageCollection().setCurrentSpreadIndex(s-1),this.flipNext(e)),sthis.do(t));const a=this.getAnimationDuration(h.length);this.render.startAnimation(r,a,()=>{this.calc&&(i&&(1===this.calc.getDirection()?this.app.turnToPrevPage():this.app.turnToNextPage()),s&&(this.render.setBottomPage(null),this.render.setFlippingPage(null),this.render.clearShadow(),this.setState("read"),this.reset()))})}getCalculation(){return this.calc}getState(){return this.state}setState(t){this.state!==t&&(this.app.updateState(t),this.state=t)}getDirectionByPoint(t){const e=this.getBoundsRect();if("portrait"===this.render.getOrientation()){if(t.x-e.pageWidth<=e.width/5)return 1}else if(t.x=1e3?e:t/1e3*e}checkDirection(t){return 0===t?this.app.getCurrentPageIndex()=1}reset(){this.calc=null,this.flippingPage=null,this.bottomPage=null}getBoundsRect(){return this.render.getRect()}checkState(...t){for(const e of t)if(this.state===e)return!0;return!1}isPointOnCorners(t){const e=this.getBoundsRect(),i=e.pageWidth,s=Math.sqrt(Math.pow(i,2)+Math.pow(e.height,2))/5,n=this.render.convertToBook(t);return n.x>0&&n.y>0&&n.xe.width-s)&&(n.ye.height-s)}}class g{constructor(t,e){this.leftPage=null,this.rightPage=null,this.flippingPage=null,this.bottomPage=null,this.direction=null,this.orientation=null,this.shadow=null,this.animation=null,this.pageRect=null,this.boundsRect=null,this.timer=0,this.safari=!1,this.setting=e,this.app=t;const i=new RegExp("Version\\/[\\d\\.]+.*Safari/");this.safari=null!==i.exec(window.navigator.userAgent)}render(t){if(null!==this.animation){const e=Math.round((t-this.animation.startedAt)/this.animation.durationFrame);e{this.running&&(this.render(e),this.running&&(this.frame=requestAnimationFrame(t)))};this.frame=requestAnimationFrame(t)}stop(){this.running=!1,null!=this.frame&&cancelAnimationFrame(this.frame),this.frame=null,this.animation=null}startAnimation(t,e,i){this.finishAnimation(),this.animation={frames:t,duration:e,durationFrame:e/t.length,onAnimateEnd:i,startedAt:this.timer}}finishAnimation(){null!==this.animation&&(this.animation.frames[this.animation.frames.length-1](),null!==this.animation.onAnimateEnd&&this.animation.onAnimateEnd()),this.animation=null}update(){this.boundsRect=null;const t=this.calculateBoundsRect();this.orientation!==t&&(this.orientation=t,this.app.updateOrientation(t))}calculateBoundsRect(){let t="landscape";const e=this.getBlockWidth(),i=e/2,s=this.getBlockHeight()/2,n=this.setting.width/this.setting.height;let h=this.setting.width,r=this.setting.height,a=i-h;return"stretch"===this.setting.size?(e<2*this.setting.minWidth&&this.app.getSettings().usePortrait&&(t="portrait"),h="portrait"===t?this.getBlockWidth():this.getBlockWidth()/2,h>this.setting.maxWidth&&(h=this.setting.maxWidth),r=h/n,r>this.getBlockHeight()&&(r=this.getBlockHeight(),h=r*n),a="portrait"===t?i-h/2-h:i-h):e<2*h&&this.app.getSettings().usePortrait&&(t="portrait",a=i-h/2-h),this.boundsRect={left:a,top:s-r/2,width:2*h,height:r,pageWidth:h},t}setShadowData(t,e,i,s){if(!this.app.getSettings().drawShadow)return;const n=100*this.getSettings().maxShadowOpacity;this.shadow={pos:t,angle:e,width:3*this.getRect().pageWidth/4*i/100,opacity:(100-i)*n/100/100,direction:s,progress:2*i}}clearShadow(){this.shadow=null}getBlockWidth(){return this.app.getUI().getDistElement().offsetWidth}getBlockHeight(){return this.app.getUI().getDistElement().offsetHeight}getDirection(){return this.direction}getRect(){return null===this.boundsRect&&this.calculateBoundsRect(),this.boundsRect}getSettings(){return this.app.getSettings()}getOrientation(){return this.orientation}setPageRect(t){this.pageRect=t}setDirection(t){this.direction=t}setRightPage(t){null!==t&&t.setOrientation(1),this.rightPage=t}setLeftPage(t){null!==t&&t.setOrientation(0),this.leftPage=t}setBottomPage(t){null!==t&&t.setOrientation(1===this.direction?0:1),this.bottomPage=t}setFlippingPage(t){null!==t&&t.setOrientation(0===this.direction&&"portrait"!==this.orientation?0:1),this.flippingPage=t}convertToBook(t){const e=this.getRect();return{x:t.x-e.left,y:t.y-e.top}}isSafari(){return this.safari}convertToPage(t,e){e||(e=this.direction);const i=this.getRect();return{x:0===e?t.x-i.left-i.width/2:i.width/2-t.x+i.left,y:t.y-i.top}}convertToGlobal(t,e){if(e||(e=this.direction),null==t)return null;const i=this.getRect();return{x:0===e?t.x+i.left+i.width/2:i.width/2-t.x+i.left,y:t.y+i.top}}convertRectToGlobal(t,e){return e||(e=this.direction),{topLeft:this.convertToGlobal(t.topLeft,e),topRight:this.convertToGlobal(t.topRight,e),bottomLeft:this.convertToGlobal(t.bottomLeft,e),bottomRight:this.convertToGlobal(t.bottomRight,e)}}}class l extends g{constructor(t,e,i){super(t,e),this.canvas=i,this.ctx=i.getContext("2d")}getContext(){return this.ctx}reload(){}drawFrame(){this.clear(),"portrait"!==this.orientation&&null!=this.leftPage&&this.leftPage.simpleDraw(0),null!=this.rightPage&&this.rightPage.simpleDraw(1),null!=this.bottomPage&&this.bottomPage.draw(),this.drawBookShadow(),null!=this.flippingPage&&this.flippingPage.draw(),null!=this.shadow&&(this.drawOuterShadow(),this.drawInnerShadow());const t=this.getRect();"portrait"===this.orientation&&(this.ctx.beginPath(),this.ctx.rect(t.left+t.pageWidth,t.top,t.width,t.height),this.ctx.clip())}drawBookShadow(){const t=this.getRect();this.ctx.save(),this.ctx.beginPath();const e=t.width/20;this.ctx.rect(t.left,t.top,t.width,t.height);const i={x:t.left+t.width/2-e/2,y:0};this.ctx.translate(i.x,i.y);const s=this.ctx.createLinearGradient(0,0,e,0);s.addColorStop(0,"rgba(0, 0, 0, 0)"),s.addColorStop(.4,"rgba(0, 0, 0, 0.2)"),s.addColorStop(.49,"rgba(0, 0, 0, 0.1)"),s.addColorStop(.5,"rgba(0, 0, 0, 0.5)"),s.addColorStop(.51,"rgba(0, 0, 0, 0.4)"),s.addColorStop(1,"rgba(0, 0, 0, 0)"),this.ctx.clip(),this.ctx.fillStyle=s,this.ctx.fillRect(0,0,e,2*t.height),this.ctx.restore()}drawOuterShadow(){const t=this.getRect();this.ctx.save(),this.ctx.beginPath(),this.ctx.rect(t.left,t.top,t.width,t.height);const e=this.convertToGlobal({x:this.shadow.pos.x,y:this.shadow.pos.y});this.ctx.translate(e.x,e.y),this.ctx.rotate(Math.PI+this.shadow.angle+Math.PI/2);const i=this.ctx.createLinearGradient(0,0,this.shadow.width,0);0===this.shadow.direction?(this.ctx.translate(0,-100),i.addColorStop(0,"rgba(0, 0, 0, "+this.shadow.opacity+")"),i.addColorStop(1,"rgba(0, 0, 0, 0)")):(this.ctx.translate(-this.shadow.width,-100),i.addColorStop(0,"rgba(0, 0, 0, 0)"),i.addColorStop(1,"rgba(0, 0, 0, "+this.shadow.opacity+")")),this.ctx.clip(),this.ctx.fillStyle=i,this.ctx.fillRect(0,0,this.shadow.width,2*t.height),this.ctx.restore()}drawInnerShadow(){const t=this.getRect();this.ctx.save(),this.ctx.beginPath();const e=this.convertToGlobal({x:this.shadow.pos.x,y:this.shadow.pos.y}),i=this.convertRectToGlobal(this.pageRect);this.ctx.moveTo(i.topLeft.x,i.topLeft.y),this.ctx.lineTo(i.topRight.x,i.topRight.y),this.ctx.lineTo(i.bottomRight.x,i.bottomRight.y),this.ctx.lineTo(i.bottomLeft.x,i.bottomLeft.y),this.ctx.translate(e.x,e.y),this.ctx.rotate(Math.PI+this.shadow.angle+Math.PI/2);const s=3*this.shadow.width/4,n=this.ctx.createLinearGradient(0,0,s,0);0===this.shadow.direction?(this.ctx.translate(-s,-100),n.addColorStop(1,"rgba(0, 0, 0, "+this.shadow.opacity+")"),n.addColorStop(.9,"rgba(0, 0, 0, 0.05)"),n.addColorStop(.7,"rgba(0, 0, 0, "+this.shadow.opacity+")"),n.addColorStop(0,"rgba(0, 0, 0, 0)")):(this.ctx.translate(0,-100),n.addColorStop(0,"rgba(0, 0, 0, "+this.shadow.opacity+")"),n.addColorStop(.1,"rgba(0, 0, 0, 0.05)"),n.addColorStop(.3,"rgba(0, 0, 0, "+this.shadow.opacity+")"),n.addColorStop(1,"rgba(0, 0, 0, 0)")),this.ctx.clip(),this.ctx.fillStyle=n,this.ctx.fillRect(0,0,s,2*t.height),this.ctx.restore()}clear(){this.ctx.fillStyle="white",this.ctx.fillRect(0,0,this.canvas.width,this.canvas.height)}}class d{constructor(t,e,i){this.touchPoint=null,this.swipeTimeout=250,this.onResize=()=>{this.update()},this.onMouseDown=t=>{if(this.checkTarget(t.target)){const e=this.getMousePos(t.clientX,t.clientY);this.app.startUserTouch(e),t.preventDefault()}},this.onTouchStart=t=>{if(this.checkTarget(t.target)&&t.changedTouches.length>0){const e=t.changedTouches[0],i=this.getMousePos(e.clientX,e.clientY);this.touchPoint={point:i,time:Date.now()},setTimeout(()=>{null!==this.touchPoint&&this.app.startUserTouch(i)},this.swipeTimeout),this.app.getSettings().mobileScrollSupport||t.preventDefault()}},this.onMouseUp=t=>{const e=this.getMousePos(t.clientX,t.clientY);this.app.userStop(e)},this.onMouseMove=t=>{const e=this.getMousePos(t.clientX,t.clientY);this.app.userMove(e,!1)},this.onTouchMove=t=>{if(t.changedTouches.length>0){const e=t.changedTouches[0],i=this.getMousePos(e.clientX,e.clientY);this.app.getSettings().mobileScrollSupport?(null!==this.touchPoint&&(Math.abs(this.touchPoint.point.x-i.x)>10||"read"!==this.app.getState())&&t.cancelable&&this.app.userMove(i,!0),"read"!==this.app.getState()&&t.preventDefault()):this.app.userMove(i,!0)}},this.onTouchEnd=t=>{if(t.changedTouches.length>0){const e=t.changedTouches[0],i=this.getMousePos(e.clientX,e.clientY);let s=!1;if(null!==this.touchPoint){const t=i.x-this.touchPoint.point.x,e=Math.abs(i.y-this.touchPoint.point.y);Math.abs(t)>this.swipeDistance&&e<2*this.swipeDistance&&Date.now()-this.touchPoint.time0?this.app.flipPrev(this.touchPoint.point.y'),this.wrapper=t.querySelector(".stf__wrapper"),this.app=e;const s=this.app.getSettings().usePortrait?1:2;t.style.minWidth=i.minWidth*s+"px",t.style.minHeight=i.minHeight+"px","fixed"===i.size&&(t.style.minWidth=i.width*s+"px",t.style.minHeight=i.height+"px"),i.autoSize&&(t.style.width="100%",t.style.maxWidth=2*i.maxWidth+"px"),t.style.display="block",window.addEventListener("resize",this.onResize,!1),this.swipeDistance=i.swipeDistance}destroy(){this.removeHandlers(),this.distElement.remove(),this.wrapper.remove()}getDistElement(){return this.distElement}getWrapper(){return this.wrapper}setOrientationStyle(t){this.wrapper.classList.remove("--portrait","--landscape"),"portrait"===t?(this.app.getSettings().autoSize&&(this.wrapper.style.paddingBottom=this.app.getSettings().height/this.app.getSettings().width*100+"%"),this.wrapper.classList.add("--portrait")):(this.app.getSettings().autoSize&&(this.wrapper.style.paddingBottom=this.app.getSettings().height/(2*this.app.getSettings().width)*100+"%"),this.wrapper.classList.add("--landscape")),this.update()}removeHandlers(){window.removeEventListener("resize",this.onResize),this.distElement.removeEventListener("mousedown",this.onMouseDown),this.distElement.removeEventListener("touchstart",this.onTouchStart),window.removeEventListener("mousemove",this.onMouseMove),window.removeEventListener("touchmove",this.onTouchMove),window.removeEventListener("mouseup",this.onMouseUp),window.removeEventListener("touchend",this.onTouchEnd)}setHandlers(){window.addEventListener("resize",this.onResize,!1),this.app.getSettings().useMouseEvents&&(this.distElement.addEventListener("mousedown",this.onMouseDown),this.distElement.addEventListener("touchstart",this.onTouchStart),window.addEventListener("mousemove",this.onMouseMove),window.addEventListener("touchmove",this.onTouchMove,{passive:!this.app.getSettings().mobileScrollSupport}),window.addEventListener("mouseup",this.onMouseUp),window.addEventListener("touchend",this.onTouchEnd))}getMousePos(t,e){const i=this.distElement.getBoundingClientRect();return{x:t-i.left,y:e-i.top}}checkTarget(t){return!this.app.getSettings().clickEventForward||!["a","button"].includes(t.tagName.toLowerCase())}}class p extends d{constructor(t,e,i,s){super(t,e,i),this.wrapper.insertAdjacentHTML("afterbegin",'
'),this.distElement=t.querySelector(".stf__block"),this.items=s;for(const t of s)this.distElement.appendChild(t);this.setHandlers()}clear(){for(const t of this.items)this.parentElement.appendChild(t)}updateItems(t){this.removeHandlers(),this.distElement.innerHTML="";for(const e of t)this.distElement.appendChild(e);this.items=t,this.setHandlers()}update(){this.app.getRender().update()}}class c extends d{constructor(t,e,i){super(t,e,i),this.wrapper.innerHTML='',this.canvas=t.querySelectorAll("canvas")[0],this.distElement=this.canvas,this.resizeCanvas(),this.setHandlers()}resizeCanvas(){const t=getComputedStyle(this.canvas),e=parseInt(t.getPropertyValue("width"),10),i=parseInt(t.getPropertyValue("height"),10);this.canvas.width=e,this.canvas.height=i}getCanvas(){return this.canvas}update(){this.resizeCanvas(),this.app.getRender().update()}}class u extends g{constructor(t,e,i){super(t,e),this.outerShadow=null,this.innerShadow=null,this.hardShadow=null,this.hardInnerShadow=null,this.element=i,this.createShadows()}createShadows(){this.element.insertAdjacentHTML("beforeend",'
\n
\n
\n
'),this.outerShadow=this.element.querySelector(".stf__outerShadow"),this.innerShadow=this.element.querySelector(".stf__innerShadow"),this.hardShadow=this.element.querySelector(".stf__hardShadow"),this.hardInnerShadow=this.element.querySelector(".stf__hardInnerShadow")}clearShadow(){super.clearShadow(),this.outerShadow.style.cssText="display: none",this.innerShadow.style.cssText="display: none",this.hardShadow.style.cssText="display: none",this.hardInnerShadow.style.cssText="display: none"}reload(){this.element.querySelector(".stf__outerShadow")||this.createShadows()}drawHardInnerShadow(){const t=this.getRect(),e=this.shadow.progress>100?200-this.shadow.progress:this.shadow.progress;let i=(100-e)*(2.5*t.pageWidth)/100+20;i>t.pageWidth&&(i=t.pageWidth);let s=`\n display: block;\n z-index: ${(this.getSettings().startZIndex+5).toString(10)};\n width: ${i}px;\n height: ${t.height}px;\n background: linear-gradient(to right,\n rgba(0, 0, 0, ${this.shadow.opacity*e/100}) 5%,\n rgba(0, 0, 0, 0) 100%);\n left: ${t.left+t.width/2}px;\n transform-origin: 0 0;\n `;s+=0===this.getDirection()&&this.shadow.progress>100||1===this.getDirection()&&this.shadow.progress<=100?"transform: translate3d(0, 0, 0);":"transform: translate3d(0, 0, 0) rotateY(180deg);",this.hardInnerShadow.style.cssText=s}drawHardOuterShadow(){const t=this.getRect();let e=(100-(this.shadow.progress>100?200-this.shadow.progress:this.shadow.progress))*(2.5*t.pageWidth)/100+20;e>t.pageWidth&&(e=t.pageWidth);let i=`\n display: block;\n z-index: ${(this.getSettings().startZIndex+4).toString(10)};\n width: ${e}px;\n height: ${t.height}px;\n background: linear-gradient(to left, rgba(0, 0, 0, ${this.shadow.opacity}) 5%, rgba(0, 0, 0, 0) 100%);\n left: ${t.left+t.width/2}px;\n transform-origin: 0 0;\n `;i+=0===this.getDirection()&&this.shadow.progress>100||1===this.getDirection()&&this.shadow.progress<=100?"transform: translate3d(0, 0, 0) rotateY(180deg);":"transform: translate3d(0, 0, 0);",this.hardShadow.style.cssText=i}drawInnerShadow(){const t=this.getRect(),e=3*this.shadow.width/4,i=0===this.getDirection()?e:0,s=0===this.getDirection()?"to left":"to right",h=this.convertToGlobal(this.shadow.pos),r=this.shadow.angle+3*Math.PI/2,a=[this.pageRect.topLeft,this.pageRect.topRight,this.pageRect.bottomRight,this.pageRect.bottomLeft];let o="polygon( ";for(const t of a){let e=1===this.getDirection()?{x:-t.x+this.shadow.pos.x,y:t.y-this.shadow.pos.y}:{x:t.x-this.shadow.pos.x,y:t.y-this.shadow.pos.y};e=n.GetRotatedPoint(e,{x:i,y:100},r),o+=e.x+"px "+e.y+"px, "}o=o.slice(0,-2),o+=")";const g=`\n display: block;\n z-index: ${(this.getSettings().startZIndex+10).toString(10)};\n width: ${e}px;\n height: ${2*t.height}px;\n background: linear-gradient(${s},\n rgba(0, 0, 0, ${this.shadow.opacity}) 5%,\n rgba(0, 0, 0, 0.05) 15%,\n rgba(0, 0, 0, ${this.shadow.opacity}) 35%,\n rgba(0, 0, 0, 0) 100%);\n transform-origin: ${i}px 100px;\n transform: translate3d(${h.x-i}px, ${h.y-100}px, 0) rotate(${r}rad);\n clip-path: ${o};\n -webkit-clip-path: ${o};\n `;this.innerShadow.style.cssText=g}drawOuterShadow(){const t=this.getRect(),e=this.convertToGlobal({x:this.shadow.pos.x,y:this.shadow.pos.y}),i=this.shadow.angle+3*Math.PI/2,s=1===this.getDirection()?this.shadow.width:0,h=0===this.getDirection()?"to right":"to left",r=[{x:0,y:0},{x:t.pageWidth,y:0},{x:t.pageWidth,y:t.height},{x:0,y:t.height}];let a="polygon( ";for(const t of r)if(null!==t){let e=1===this.getDirection()?{x:-t.x+this.shadow.pos.x,y:t.y-this.shadow.pos.y}:{x:t.x-this.shadow.pos.x,y:t.y-this.shadow.pos.y};e=n.GetRotatedPoint(e,{x:s,y:100},i),a+=e.x+"px "+e.y+"px, "}a=a.slice(0,-2),a+=")";const o=`\n display: block;\n z-index: ${(this.getSettings().startZIndex+10).toString(10)};\n width: ${this.shadow.width}px;\n height: ${2*t.height}px;\n background: linear-gradient(${h}, rgba(0, 0, 0, ${this.shadow.opacity}), rgba(0, 0, 0, 0));\n transform-origin: ${s}px 100px;\n transform: translate3d(${e.x-s}px, ${e.y-100}px, 0) rotate(${i}rad);\n clip-path: ${a};\n -webkit-clip-path: ${a};\n `;this.outerShadow.style.cssText=o}drawLeftPage(){"portrait"!==this.orientation&&null!==this.leftPage&&(1===this.direction&&null!==this.flippingPage&&"hard"===this.flippingPage.getDrawingDensity()?(this.leftPage.getElement().style.zIndex=(this.getSettings().startZIndex+5).toString(10),this.leftPage.setHardDrawingAngle(180+this.flippingPage.getHardAngle()),this.leftPage.draw(this.flippingPage.getDrawingDensity())):this.leftPage.simpleDraw(0))}drawRightPage(){null!==this.rightPage&&(0===this.direction&&null!==this.flippingPage&&"hard"===this.flippingPage.getDrawingDensity()?(this.rightPage.getElement().style.zIndex=(this.getSettings().startZIndex+5).toString(10),this.rightPage.setHardDrawingAngle(180+this.flippingPage.getHardAngle()),this.rightPage.draw(this.flippingPage.getDrawingDensity())):this.rightPage.simpleDraw(1))}drawBottomPage(){if(null===this.bottomPage)return;const t=null!=this.flippingPage?this.flippingPage.getDrawingDensity():null;"portrait"===this.orientation&&1===this.direction||(this.bottomPage.getElement().style.zIndex=(this.getSettings().startZIndex+3).toString(10),this.bottomPage.draw(t))}drawFrame(){this.clear(),this.drawLeftPage(),this.drawRightPage(),this.drawBottomPage(),null!=this.flippingPage&&(this.flippingPage.getElement().style.zIndex=(this.getSettings().startZIndex+5).toString(10),this.flippingPage.draw()),null!=this.shadow&&null!==this.flippingPage&&("soft"===this.flippingPage.getDrawingDensity()?(this.drawOuterShadow(),this.drawInnerShadow()):(this.drawHardOuterShadow(),this.drawHardInnerShadow()))}clear(){for(const t of this.app.getPageCollection().getPages())t!==this.leftPage&&t!==this.rightPage&&t!==this.flippingPage&&t!==this.bottomPage&&(t.getElement().style.cssText="display: none"),t.getTemporaryCopy()!==this.flippingPage&&t.hideTemporaryCopy()}update(){super.update(),null!==this.rightPage&&this.rightPage.setOrientation(1),null!==this.leftPage&&this.leftPage.setOrientation(0)}}class w{constructor(){this._default={startPage:0,size:"fixed",width:0,height:0,minWidth:0,maxWidth:0,minHeight:0,maxHeight:0,drawShadow:!0,flippingTime:1e3,usePortrait:!0,startZIndex:0,autoSize:!0,maxShadowOpacity:1,showCover:!1,mobileScrollSupport:!0,swipeDistance:30,clickEventForward:!0,useMouseEvents:!0,showPageCorners:!0,disableFlipByClick:!1}}getSettings(t){const e=this._default;if(Object.assign(e,t),"stretch"!==e.size&&"fixed"!==e.size)throw new Error('Invalid size type. Available only "fixed" and "stretch" value');if(e.width<=0||e.height<=0)throw new Error("Invalid width or height");if(e.flippingTime<=0)throw new Error("Invalid flipping time");return"stretch"===e.size?(e.minWidth<=0&&(e.minWidth=100),e.maxWidth{this.ui.update(),this.trigger("init",this,{page:this.setting.startPage,mode:this.render.getOrientation()})},1)}loadFromHTML(t){this.ui=new p(this.block,this,this.setting,t),this.render=new u(this,this.setting,this.ui.getDistElement()),this.flipController=new o(this.render,this),this.pages=new r(this,this.render,this.ui.getDistElement(),t),this.pages.load(),this.render.start(),this.pages.show(this.setting.startPage),setTimeout(()=>{this.ui.update(),this.trigger("init",this,{page:this.setting.startPage,mode:this.render.getOrientation()})},1)}updateFromImages(t){const e=this.pages.getCurrentPageIndex();this.pages.destroy(),this.pages=new s(this,this.render,t),this.pages.load(),this.pages.show(e),this.trigger("update",this,{page:e,mode:this.render.getOrientation()})}updateFromHtml(t){const e=this.pages.getCurrentPageIndex();this.pages.destroy(),this.pages=new r(this,this.render,this.ui.getDistElement(),t),this.pages.load(),this.ui.updateItems(t),this.render.reload(),this.pages.show(e),this.trigger("update",this,{page:e,mode:this.render.getOrientation()})}clear(){this.pages.destroy(),this.ui.clear()}turnToPrevPage(){this.pages.showPrev()}turnToNextPage(){this.pages.showNext()}turnToPage(t){this.pages.show(t)}flipNext(t="top"){this.flipController.flipNext(t)}flipPrev(t="top"){this.flipController.flipPrev(t)}flip(t,e="top"){this.flipController.flipToPage(t,e)}updateState(t){this.trigger("changeState",this,t)}updatePageIndex(t){this.trigger("flip",this,t)}updateOrientation(t){this.ui.setOrientationStyle(t),this.update(),this.trigger("changeOrientation",this,t)}getPageCount(){return this.pages.getPageCount()}getCurrentPageIndex(){return this.pages.getCurrentPageIndex()}getPage(t){return this.pages.getPage(t)}getRender(){return this.render}getFlipController(){return this.flipController}getOrientation(){return this.render.getOrientation()}getBoundsRect(){return this.render.getRect()}getSettings(){return this.setting}getUI(){return this.ui}getState(){return this.flipController.getState()}getPageCollection(){return this.pages}startUserTouch(t){this.mousePosition=t,this.isUserTouch=!0,this.isUserMove=!1}userMove(t,e){this.isUserTouch||e||!this.setting.showPageCorners?this.isUserTouch&&n.GetDistanceBetweenTwoPoint(this.mousePosition,t)>5&&(this.isUserMove=!0,this.flipController.fold(t)):this.flipController.showCorner(t)}userStop(t,e=!1){this.isUserTouch&&(this.isUserTouch=!1,e||(this.isUserMove?this.flipController.stopMove():this.flipController.flip(t)))}}export{x as PageFlip}; +diff --git a/src/Event/EventObject.ts b/src/Event/EventObject.ts +index 40d98a13e2c8059f5876d7852acf4cc6de4cb507..fa7e173d38fef435d7f0009d898bc67b2b717d7d 100644 +--- a/src/Event/EventObject.ts ++++ b/src/Event/EventObject.ts +@@ -46,6 +46,10 @@ export abstract class EventObject { + this.events.delete(event); + } + ++ protected clearEvents(): void { ++ this.events.clear(); ++ } ++ + protected trigger(eventName: string, app: PageFlip, data: DataType = null): void { + if (!this.events.has(eventName)) return; + +diff --git a/src/PageFlip.ts b/src/PageFlip.ts +index 87fe9f22dc1801d2ad7cf4b369adee602b8dcb79..b0249c3418762a612cc3c26751e6f4b6268f455f 100644 +--- a/src/PageFlip.ts ++++ b/src/PageFlip.ts +@@ -34,6 +34,7 @@ export class PageFlip extends EventObject { + private render: Render; + + private ui: UI; ++ private initTimer: ReturnType; + + /** + * Create a new PageFlip instance +@@ -53,7 +54,11 @@ export class PageFlip extends EventObject { + * Destructor. Remove a root HTML element and all event handlers + */ + public destroy(): void { +- this.ui.destroy(); ++ clearTimeout(this.initTimer); ++ this.render?.stop(); ++ this.pages?.destroy(); ++ this.ui?.destroy(); ++ this.clearEvents(); + this.block.remove(); + } + +@@ -86,7 +91,7 @@ export class PageFlip extends EventObject { + this.pages.show(this.setting.startPage); + + // safari fix +- setTimeout(() => { ++ this.initTimer = setTimeout(() => { + this.ui.update(); + this.trigger('init', this, { + page: this.setting.startPage, +@@ -115,7 +120,7 @@ export class PageFlip extends EventObject { + this.pages.show(this.setting.startPage); + + // safari fix +- setTimeout(() => { ++ this.initTimer = setTimeout(() => { + this.ui.update(); + this.trigger('init', this, { + page: this.setting.startPage, +diff --git a/src/Render/Render.ts b/src/Render/Render.ts +index 927ee523bd093bde64870cbda728ad0ecd966921..75b0029275bce80524c67802f5c4e6ee89ef5edc 100644 +--- a/src/Render/Render.ts ++++ b/src/Render/Render.ts +@@ -136,15 +136,26 @@ export abstract class Render { + /** + * Running requestAnimationFrame, and rendering process + */ ++ private frame: number = null; ++ private running = false; ++ + public start(): void { ++ this.stop(); ++ this.running = true; + this.update(); +- + const loop = (timer: number): void => { ++ if (!this.running) return; + this.render(timer); +- requestAnimationFrame(loop); ++ if (this.running) this.frame = requestAnimationFrame(loop); + }; ++ this.frame = requestAnimationFrame(loop); ++ } + +- requestAnimationFrame(loop); ++ public stop(): void { ++ this.running = false; ++ if (this.frame !== null) cancelAnimationFrame(this.frame); ++ this.frame = null; ++ this.animation = null; + } + + /** +diff --git a/src/UI/UI.ts b/src/UI/UI.ts +index fd1629e39f3137a0d1c78afa0d0afa4478d74c69..3b306aed70f14de2c11a6e6d79f9547972f1fab6 100644 +--- a/src/UI/UI.ts ++++ b/src/UI/UI.ts +@@ -71,7 +71,7 @@ export abstract class UI { + * Destructor. Remove all HTML elements and all event handlers + */ + public destroy(): void { +- if (this.app.getSettings().useMouseEvents) this.removeHandlers(); ++ this.removeHandlers(); + + this.distElement.remove(); + this.wrapper.remove(); diff --git a/web/pnpm-lock.yaml b/web/pnpm-lock.yaml new file mode 100644 index 0000000..ff86750 --- /dev/null +++ b/web/pnpm-lock.yaml @@ -0,0 +1,1491 @@ +lockfileVersion: '9.0' + +settings: + autoInstallPeers: true + excludeLinksFromLockfile: false + +patchedDependencies: + page-flip@2.0.7: 7c9637358d2df31df3c007deea58f55b7c91b30400f9f92623d4aba9c9b9cfb6 + +importers: + + .: + dependencies: + '@fontsource/cormorant-garamond': + specifier: ^5.2.8 + version: 5.3.0 + highlight.js: + specifier: ^11.11.1 + version: 11.12.0 + katex: + specifier: ^0.16.22 + version: 0.16.47 + lucide: + specifier: ^0.468.0 + version: 0.468.0 + page-flip: + specifier: ^2.0.7 + version: 2.0.7(patch_hash=7c9637358d2df31df3c007deea58f55b7c91b30400f9f92623d4aba9c9b9cfb6) + solid-js: + specifier: 1.9.17 + version: 1.9.17 + vite: + specifier: ^7.1.0 + version: 7.3.7(@types/node@22.20.5) + devDependencies: + '@types/node': + specifier: ^22.20.5 + version: 22.20.5 + '@types/turndown': + specifier: ^5.0.6 + version: 5.0.6 + linkedom: + specifier: ^0.18.14 + version: 0.18.14 + playwright: + specifier: 1.64.1 + version: 1.64.1 + smol-toml: + specifier: ^1.9.1 + version: 1.9.1 + turndown: + specifier: 7.2.2 + version: 7.2.2 + turndown-plugin-gfm: + specifier: 1.0.2 + version: 1.0.2 + typescript: + specifier: 5.9.3 + version: 5.9.3 + vite-plugin-solid: + specifier: 2.11.14 + version: 2.11.14(solid-js@1.9.17)(vite@7.3.7(@types/node@22.20.5)) + +packages: + + '@acemir/cssom@0.9.32': + resolution: {integrity: sha512-OijrAUu7rrJhSIoHNg6LMPS5e344nwUHA+1EFYYjrh64D+GmytUsfBQjci45TjT+rd5Spsp8B5xsZDT+TgyXXQ==} + + '@babel/code-frame@7.29.7': + resolution: {integrity: sha512-Aup7aUOfpbAUg2ROOJN6Iw5f9DMBlzu0mIkm/malLQFN/YQgO48wCj0Kxa3sEHJvPVFg7siR+qRInwXd2qhQKw==} + engines: {node: '>=6.9.0'} + + '@babel/compat-data@7.29.7': + resolution: {integrity: sha512-locTkQyKvwIEgBzVrn8693ebc97F2U8ZHjbXwDXJ5Fn2TCpNwTlKcaKLkdHop5c/icOFE7qt7Q9JC5hnKNa6Gg==} + engines: {node: '>=6.9.0'} + + '@babel/core@7.29.7': + resolution: {integrity: sha512-RgHBCvtjbOK2gXSNBNIkNoEc9qoVEtau3hj8gEqKQuL3HZAibKarWFEI3Lfm6EYKkLalOh8eSrj9b+ch9H/VBA==} + engines: {node: '>=6.9.0'} + + '@babel/generator@7.29.8': + resolution: {integrity: sha512-gZbepsdh3WDtgZKWL+vTPh71LSBrm/Y4/QDZBVCcYfmeTEEuoOYwlSy+G1StfJg+/Zy550u/3TATbm7qDbbMtg==} + engines: {node: '>=6.9.0'} + + '@babel/helper-compilation-targets@7.29.7': + resolution: {integrity: sha512-wem6WaBj4NaVYVdNhLPPVacES6ZJ+KBBfSkTMD3YZxbP3rm3Di85tJU5ljaUNhaOynt+Aj0xruhYuzQBt8n71g==} + engines: {node: '>=6.9.0'} + + '@babel/helper-globals@7.29.7': + resolution: {integrity: sha512-3nQVUAtvkKH9zahfWgw96Jc/uFOmjACE1kQz82E2lqWmHBgjzbNlsC22nuQTfahmWeQtTq5nQ/4Nnd2A1wj4zA==} + engines: {node: '>=6.9.0'} + + '@babel/helper-module-imports@7.18.6': + resolution: {integrity: sha512-0NFvs3VkuSYbFi1x2Vd6tKrywq+z/cLeYC/RJNFrIX/30Bf5aiGYbtvGXolEktzJH8o5E5KJ3tT+nkxuuZFVlA==} + engines: {node: '>=6.9.0'} + + '@babel/helper-module-imports@7.29.7': + resolution: {integrity: sha512-ejHwrQQYcm9xnTivShn2IDOlIzInN34AXskvq9QicvCtEzq1Vzclu/tKF8Jq1Cg8JG2GL6/EmjgsCT7lXepE3g==} + engines: {node: '>=6.9.0'} + + '@babel/helper-module-transforms@7.29.7': + resolution: {integrity: sha512-UPUVSyXbOh627KiCIGQSgwWzGeBKLkaJ9PJEdrngIwMSzxLR4jS4+f1f1jb7VzBbg8nFLaYotvVPFCTqdrmTAg==} + engines: {node: '>=6.9.0'} + peerDependencies: + '@babel/core': ^7.0.0 + + '@babel/helper-plugin-utils@7.29.7': + resolution: {integrity: sha512-G7sHYigPY17oO5SYWnfD/0MTBwVR781S/JI643e/JhUYgVgWE/61SoW3NH9KWUKyKq5LVh3npif99Wkt6j86Jw==} + engines: {node: '>=6.9.0'} + + '@babel/helper-string-parser@7.29.11': + resolution: {integrity: sha512-snZbO7MEDOof+hvNa97EjEY7qD7h2kwvQr5AJC3ZhQudKW5dnej6k3kP9NQV88hJwaS8vDqRLFo9rivLEhle2g==} + engines: {node: '>=6.9.0'} + + '@babel/helper-validator-identifier@7.29.7': + resolution: {integrity: sha512-qehxGkRj55h/ff8EMaJ+cYhyaKlHIxqYDn682wQD7RNp9UujOQsHog2uS0r2vzr4pW+sXf90NeeayjcNaX3fFg==} + engines: {node: '>=6.9.0'} + + '@babel/helper-validator-option@7.29.7': + resolution: {integrity: sha512-N9ZErrD+yW5geCDtBqnOoxmR8+tNKiGuxKlDpuJxfsqpa2dFcexaziGAE/qoHLiDDreVNMupxGmSoNlyvsA3gw==} + engines: {node: '>=6.9.0'} + + '@babel/helpers@7.29.10': + resolution: {integrity: sha512-EMCx3AGZ3WfAl6ht7AyQoPm2Lh+BGYEMdc4Q6Hf7uSCDOZFuLq44qNwL+iaim8VlyYhRAo4X43+weadK8ZB4Yg==} + engines: {node: '>=6.9.0'} + + '@babel/parser@7.29.11': + resolution: {integrity: sha512-OZ6+oaK7GMyg3IfCpj8JOmn8n+w2rJbDT0LLfVDTLb1ZFeKDh3AiNELgCMUw175IJHSkLl74hG0M0VLsvx+gag==} + engines: {node: '>=6.0.0'} + hasBin: true + + '@babel/plugin-syntax-jsx@7.29.7': + resolution: {integrity: sha512-TSu8+mHCoEaaCDEZ0I3+6mvTBYR4PCxQwf2z9/r5Tbztv6NaLR3B9thGTTxX2WGuGHJqRiAbKPeGTJ5XWXVg6A==} + engines: {node: '>=6.9.0'} + peerDependencies: + '@babel/core': ^7.0.0-0 + + '@babel/template@7.29.7': + resolution: {integrity: sha512-puq+Gf35oI24FeN11LkoUQFqv9uwNeWpxXZi/Ji3rRIoKAzKnxRaZ+Gkj0vKS9ZCiTESfng1N9LyOyXvo+m+Gg==} + engines: {node: '>=6.9.0'} + + '@babel/traverse@7.29.10': + resolution: {integrity: sha512-B3lYAs2nkKskbgQ1nfy8Ma9ao9Q1rntTAQHrzzyDuj+TSO+X3le6PfWwqDvodsb+OumE10eMFfuMCTQSQ5iuIQ==} + engines: {node: '>=6.9.0'} + + '@babel/types@7.29.11': + resolution: {integrity: sha512-WCsemW40Cpc6gouC1SrY6PBaZ+oLRlEVY9XBvZBI7il/HyUrb2nJ505wE1MHEFyDZNnrWDEuy4jL50WVHfTTSQ==} + engines: {node: '>=6.9.0'} + + '@esbuild/aix-ppc64@0.28.2': + resolution: {integrity: sha512-XExcO+dvLKvVtNTibSTBej1NCAbaGhWn9Ww1ZPx80qsahhPFe/8jgWP0IchNe0F3HwkU7n8ejhH8bjonqht8mQ==} + engines: {node: '>=18'} + cpu: [ppc64] + os: [aix] + + '@esbuild/android-arm64@0.28.2': + resolution: {integrity: sha512-5YfKeeI8qWfBZIX+u2xZC3Zlb3Os/gLS2sbEKM+I4ZOcsWmHS2WLysCcQZDAFRslDUU5Oiq44gf6PYN1vGwG5A==} + engines: {node: '>=18'} + cpu: [arm64] + os: [android] + + '@esbuild/android-arm@0.28.2': + resolution: {integrity: sha512-kXXoiPVVGQcnIYGOeaovwOURpniDBpSq4A03qkQ+BMQqtGG6HYap3xne9C1O1yo4TR3qxlCX5IqqmX6fFo2Lqg==} + engines: {node: '>=18'} + cpu: [arm] + os: [android] + + '@esbuild/android-x64@0.28.2': + resolution: {integrity: sha512-O387ite7SzUyCcy3JQX4P4bLtEA7bLLkx+esve5JHnyYfNTxcVpXZo9jhdB0lTKN44gztELTdU7nS8Nr16Fs1Q==} + engines: {node: '>=18'} + cpu: [x64] + os: [android] + + '@esbuild/darwin-arm64@0.28.2': + resolution: {integrity: sha512-n4KqkOQrraxHJcgjM1RvwbigfQKIKJVpM7xp+KsxiyUSrRdIXnt73VhrPAx0fV44hgfmIVKjxMN9J1t5jySVkw==} + engines: {node: '>=18'} + cpu: [arm64] + os: [darwin] + + '@esbuild/darwin-x64@0.28.2': + resolution: {integrity: sha512-uq6suIWYP37qzGddBKPw5QEQPi6HiLGsO7UmkpfyaYNQ3D+rN6w6WfwH+nuqcGXWvawGwxOEroO4YGnFh95azw==} + engines: {node: '>=18'} + cpu: [x64] + os: [darwin] + + '@esbuild/freebsd-arm64@0.28.2': + resolution: {integrity: sha512-n+I0BTSRIoy+d6RPKnEVwql5UwBJolytvY4mAOIEJorKlqgPII8ix6slVVrfZ5Tnj7glIZvloylbB/EJPMWEXw==} + engines: {node: '>=18'} + cpu: [arm64] + os: [freebsd] + + '@esbuild/freebsd-x64@0.28.2': + resolution: {integrity: sha512-78XJTJkvPs0kz2w61301PJjXl4g7q3JqiYMZ/M/yVI73EHBrCRTgkhu9oqG7vPqq+a/yadEW8aD+agKlk5xrmg==} + engines: {node: '>=18'} + cpu: [x64] + os: [freebsd] + + '@esbuild/linux-arm64@0.28.2': + resolution: {integrity: sha512-pW4AC0P3it8c7do9MVM4p51FzHzdM/TZrerurgRcHJ2WTa1VQ1CIq18xncfpBJw4ojkiZZrKW2yIBWBP92j6Ug==} + engines: {node: '>=18'} + cpu: [arm64] + os: [linux] + + '@esbuild/linux-arm@0.28.2': + resolution: {integrity: sha512-XlDnu2q5yoqems+xay6wSAcg9DDD7K9RLKZEBOMZm3ckNpJBvOX20tSfby8KfrrhINDyv9V2YVZKY/SpoGJI8w==} + engines: {node: '>=18'} + cpu: [arm] + os: [linux] + + '@esbuild/linux-ia32@0.28.2': + resolution: {integrity: sha512-CYbnj78HsIeA+DhgUKgFCfvNsTHFhMMrinUrMZpDXJXKN8T3XViTZ/+wtHeVxEWY8ewSzTFN+nRmSwO2tZaLUQ==} + engines: {node: '>=18'} + cpu: [ia32] + os: [linux] + + '@esbuild/linux-loong64@0.28.2': + resolution: {integrity: sha512-buwkd8nsph4R+ajRvw0qM5Hja/TXQow3ptzWO2EbG/cqcIkHloRrdlBtQlshyYGTNFvfkfJ5tpPLVkY4DtsPfQ==} + engines: {node: '>=18'} + cpu: [loong64] + os: [linux] + + '@esbuild/linux-mips64el@0.28.2': + resolution: {integrity: sha512-ZVykbDyk7519VwiNb9Lcj9m8XM6v5V9uKPvrEMkkEedVewf+0itkhahp4HDpgERXhwLRpWFypsGbG/J8s0QjJA==} + engines: {node: '>=18'} + cpu: [mips64el] + os: [linux] + + '@esbuild/linux-ppc64@0.28.2': + resolution: {integrity: sha512-CAXl+Dtd9UUuJd8pKKdwh6MLm3MUMiqMPmhZ3tTSXPqfyQ3vDl6R5hZdZ/kYojK4ofXtdfSv1tFq8XzWx3heNQ==} + engines: {node: '>=18'} + cpu: [ppc64] + os: [linux] + + '@esbuild/linux-riscv64@0.28.2': + resolution: {integrity: sha512-GeXCej4IQtU1B+QlDV8W/RRvbzI3O/Stss+/bCXv4lZls5WGRtu2a+3JkA3i4qIUlMXpcHebWpF8AkJhATowuA==} + engines: {node: '>=18'} + cpu: [riscv64] + os: [linux] + + '@esbuild/linux-s390x@0.28.2': + resolution: {integrity: sha512-3H1weTYZPxt/WOhByszQZybS9w5lKzUn1FDMsgEChbHWQwHYQQRfBxgCcZvPhjHfKyJjIievvMmEUawJrdY9Dg==} + engines: {node: '>=18'} + cpu: [s390x] + os: [linux] + + '@esbuild/linux-x64@0.28.2': + resolution: {integrity: sha512-4xTZr1FUmSoQW4XIWmit3tzQrUTZM+N3P0XV8xROKYF50XfI7xeO90+1bZvNwxIufQ9hDQVRJH5YhgPVF8A/HQ==} + engines: {node: '>=18'} + cpu: [x64] + os: [linux] + + '@esbuild/netbsd-arm64@0.28.2': + resolution: {integrity: sha512-sSATRjPeDBg3pdgHoQfoYBob11Kk1FGa9lui5RIHZCoCkJa9QKlvl3/vKz2usCmYYjs7ymJR/2Nnsqe+Hjt5nw==} + engines: {node: '>=18'} + cpu: [arm64] + os: [netbsd] + + '@esbuild/netbsd-x64@0.28.2': + resolution: {integrity: sha512-lqnzCV+mM0gIADaKihiCg6ifgfU2L3h5E33rNQBN1Y4MaVGnzryzmvvf7UHxprpQdE8hpqLolJ9Rl+SkIRDpyw==} + engines: {node: '>=18'} + cpu: [x64] + os: [netbsd] + + '@esbuild/openbsd-arm64@0.28.2': + resolution: {integrity: sha512-AL2qJILH7lNjrDmCQDvdxMfAUIv8KMNZOvrwAQ8i8//ntL9FflhOyMJ8OZSMBb8/AWXe3/5v5S20y3zCoZWKoQ==} + engines: {node: '>=18'} + cpu: [arm64] + os: [openbsd] + + '@esbuild/openbsd-x64@0.28.2': + resolution: {integrity: sha512-QtiuPytchRyC4rwUKhexJdQKvDuZ6hWloi3igqPQNUJCS1/v9EiO3UTOXR6A3FoMo4fnAKbWJdqaIwhOzh8qEw==} + engines: {node: '>=18'} + cpu: [x64] + os: [openbsd] + + '@esbuild/openharmony-arm64@0.28.2': + resolution: {integrity: sha512-WkhYDmpTjLvGlScA1rwjRUmhl4k8oXR3cIbtqWmELgU/dFeHHlEllxDvdWcNJV9rbzCexB5vz8gtNewWLgCT7Q==} + engines: {node: '>=18'} + cpu: [arm64] + os: [openharmony] + + '@esbuild/sunos-x64@0.28.2': + resolution: {integrity: sha512-GPMSkTOtMnv2U2F8gxe4Io6qmVs+YKyp832Etqqxr0hFngmXQ3rzwytelm3GIn7T4VviRUlf3sOgBOiTdvaf7g==} + engines: {node: '>=18'} + cpu: [x64] + os: [sunos] + + '@esbuild/win32-arm64@0.28.2': + resolution: {integrity: sha512-PIhhEkE9uPBleRBrQEJpUn7MBnibZzbGzYWPmY3x+YoVg/95zbjB4CxPPOQ8l5tYYM4mMaCthF8/1DIfBQQyWQ==} + engines: {node: '>=18'} + cpu: [arm64] + os: [win32] + + '@esbuild/win32-ia32@0.28.2': + resolution: {integrity: sha512-YmJbfTlvU7Sdn9BB+4PRES4oB6pxgS37MAONj+hBr/cpXS1aBPKXxNnDbu+QCWPj0o9dgyxeq79g6c5P8KeuYA==} + engines: {node: '>=18'} + cpu: [ia32] + os: [win32] + + '@esbuild/win32-x64@0.28.2': + resolution: {integrity: sha512-5ebpxr3nWMzrL/rnUI755Jkuee0bHL/Gq0WTF9lvcpv73wAp5eu8MfBUgWK9bhWvZjj7yX8etf/8tI8Ney695g==} + engines: {node: '>=18'} + cpu: [x64] + os: [win32] + + '@fontsource/cormorant-garamond@5.3.0': + resolution: {integrity: sha512-weuGsCirGVWBWqpt6YUp0yLThTe4G8YO45noq8wxeJCRvEpq5lFrxNMFSTxcyOyV5k5otzJ8guDzYegdYlcLMQ==} + + '@jridgewell/gen-mapping@0.3.13': + resolution: {integrity: sha512-2kkt/7niJ6MgEPxF0bYdQ6etZaA+fQvDcLKckhy1yIQOzaoKjBBjSj63/aLVjYE3qhRt5dvM+uUyfCg6UKCBbA==} + + '@jridgewell/remapping@2.3.5': + resolution: {integrity: sha512-LI9u/+laYG4Ds1TDKSJW2YPrIlcVYOwi2fUC6xB43lueCjgxV4lffOCZCtYFiH6TNOX+tQKXx97T4IKHbhyHEQ==} + + '@jridgewell/resolve-uri@3.1.2': + resolution: {integrity: sha512-bRISgCIjP20/tbWSPWMEi54QVPRZExkuD9lJL+UIxUKtwVJA8wW1Trb1jMs1RFXo1CBTNZ/5hpC9QvmKWdopKw==} + engines: {node: '>=6.0.0'} + + '@jridgewell/sourcemap-codec@1.6.0': + resolution: {integrity: sha512-T7jf+5zgsZHwNJ4lvQ7/aezbyk0nNX+zJVWpmHA7VYsEx7a7qr5Rg5IbtJFqkgze5Y2sruq1RUY8Q837Od7iFw==} + + '@jridgewell/trace-mapping@0.3.31': + resolution: {integrity: sha512-zzNR+SdQSDJzc8joaeP8QQoCQr8NuYx2dIIytl1QeBEZHJ9uW6hebsrYgbz8hJwUQao3TWCMtmfV8Nu1twOLAw==} + + '@mixmark-io/domino@2.2.0': + resolution: {integrity: sha512-Y28PR25bHXUg88kCV7nivXrP2Nj2RueZ3/l/jdx6J9f8J4nsEGcgX0Qe6lt7Pa+J79+kPiJU3LguR6O/6zrLOw==} + + '@napi-rs/lzma-linux-x64-gnu@1.5.1': + resolution: {integrity: sha512-oTXEIha4SsuXdTA4Iyskj0kpdx2yVXdhd75c2v3xGrHFfVMsbhTPZU/nMPL4sWKo4pBHm3aucLaqGlF696dTyQ==} + engines: {node: ^22.20 || ^24.12 || >=25} + cpu: [x64] + os: [linux] + libc: [glibc] + + '@rollup/rollup-android-arm-eabi@4.64.12': + resolution: {integrity: sha512-Z8lz+5UOiCJLonjeqwJlhUtHA/Sr6R1AidkccQxdWF0nigNzP81aLoU+udgOaGfL5s1uzFXzcux/pCwGAMu0lw==} + cpu: [arm] + os: [android] + + '@rollup/rollup-android-arm64@4.64.12': + resolution: {integrity: sha512-+tKxNa2psFmiTb0KfXlXs4Yj7vkEhzAvZ0DrQ5+0gWHQJM10jSleQ3l1FIVm5uvD53YM8lHfM4mgCLDDN9f1Gg==} + cpu: [arm64] + os: [android] + + '@rollup/rollup-darwin-arm64@4.64.12': + resolution: {integrity: sha512-iiripdfvyRBugV55/Dk7GplNXQtN/PG85OcKeveU1z2UkTg0MofbBF1qk//qgPWiqJbVvQcXAVCfE56oDGO4EQ==} + cpu: [arm64] + os: [darwin] + + '@rollup/rollup-darwin-x64@4.64.12': + resolution: {integrity: sha512-BmATib8swSMAagWNIfDZMnb+k34RXR4bbGOUfZgK8lLlniuMyVoSDDXCOGkdhtUmBXL4aygDh7bhjQ+TmhTvIw==} + cpu: [x64] + os: [darwin] + + '@rollup/rollup-freebsd-arm64@4.64.12': + resolution: {integrity: sha512-GzrO0CiUq8vcAI/hYJuIcp6wNm3T3YhOpumYtf9Z3Fz+cfN1VESCVfy7EPcM3/m2K8l+Gn2U+4XtNZjwhUXctQ==} + cpu: [arm64] + os: [freebsd] + + '@rollup/rollup-freebsd-x64@4.64.12': + resolution: {integrity: sha512-Dpta6gigm4o6SYioXtTkZBlGLA/Sl6OpzgLqY+51uafJE2blPejAtR1w82CVLPN+F9cvo1+/em92x/zcOgY0uQ==} + cpu: [x64] + os: [freebsd] + + '@rollup/rollup-linux-arm-gnueabihf@4.64.12': + resolution: {integrity: sha512-YpeDwQ5uFaogRvytNC8RK0keDO65kI5wNEhGSs+4GiJc3KHhxj4j5cnQh2nCu9ybJj6RP0/ycB6bkN0yFJ9I+w==} + cpu: [arm] + os: [linux] + libc: [glibc] + + '@rollup/rollup-linux-arm-musleabihf@4.64.12': + resolution: {integrity: sha512-LQrB3/sImIr1ycrlEyaApOLH1rAy8JV4/dH4eoK817aWATdcs4fESXz53/w72NwDnwPM5zEUpoL7socH4ZDnwA==} + cpu: [arm] + os: [linux] + libc: [musl] + + '@rollup/rollup-linux-arm64-gnu@4.64.12': + resolution: {integrity: sha512-iAF2iYu9S4SBfNsb4k0ewNBjO83WxHEltIuKQBGMzEKFgrYfmJn+gatBDXR2t/0zJN0UW0kzR4rfvQ1UHzkZ1A==} + cpu: [arm64] + os: [linux] + libc: [glibc] + + '@rollup/rollup-linux-arm64-musl@4.64.12': + resolution: {integrity: sha512-0MQdRtdbirJCXPIVeW/hd/LXLR8Qz96pc+2EBptuuV5q/zSGOzND7SZt8gBTE58NC9cUG/8UxcUXQiKRZ2WzzA==} + cpu: [arm64] + os: [linux] + libc: [musl] + + '@rollup/rollup-linux-loong64-gnu@4.64.12': + resolution: {integrity: sha512-yGDEwn0AGnrY/KCz2oY8R9KKNiQnTcwNuCWXeSXF0VLxXzlqoCgaS5QHsf1lbQvKWwPuN2Czkjk1wXRCBONTOQ==} + cpu: [loong64] + os: [linux] + libc: [glibc] + + '@rollup/rollup-linux-loong64-musl@4.64.12': + resolution: {integrity: sha512-AjlbD0efZEhHaJ3bsNjxSFDoguNq6VZvC+FKGJGBCA+ZN7BrZq2TuuSWFa6AI8IpOeuvhp2LoYcP7jiZwmtU0Q==} + cpu: [loong64] + os: [linux] + libc: [musl] + + '@rollup/rollup-linux-ppc64-gnu@4.64.12': + resolution: {integrity: sha512-sDW0CiPoUCEEUV25uBG5sJ2gKe75DJqLpj91m1eK1vKffywyY7v4i6q1450ZuR6QW4NArXg7JpbMGgKU8di3HQ==} + cpu: [ppc64] + os: [linux] + libc: [glibc] + + '@rollup/rollup-linux-ppc64-musl@4.64.12': + resolution: {integrity: sha512-VTQYUhMjl8kv999VuYqScgv7P9cR9KuxI/6bkUsEa3bsswqG0+otFjuLZmJ1U+ffEP4IAz0jxOeV0DX6NRBhjg==} + cpu: [ppc64] + os: [linux] + libc: [musl] + + '@rollup/rollup-linux-riscv64-gnu@4.64.12': + resolution: {integrity: sha512-ppsKwpSjNrzJ8hge3Z3uiCcoRgAAQk2tU7auy3MFF348ffWRldFPnWIT/a/enK7huijlTfnwn4DYpDoapEb45A==} + cpu: [riscv64] + os: [linux] + libc: [glibc] + + '@rollup/rollup-linux-riscv64-musl@4.64.12': + resolution: {integrity: sha512-Gc3cVRC1trFH+GFWWTsJz6YuD4u75fzr/q99jqQGimonN/zvN6Wecck5WGzllOHj+XYXHcq0Ibor0tanGjfI6A==} + cpu: [riscv64] + os: [linux] + libc: [musl] + + '@rollup/rollup-linux-s390x-gnu@4.64.12': + resolution: {integrity: sha512-pjmDTFStvwFE3shTeUDvSDiSp8/qAf5bQXejcEUDDavWz4jEhTIpCdpS06G0PEwSCSNK0Lngjz2v9l4hk3Z74A==} + cpu: [s390x] + os: [linux] + libc: [glibc] + + '@rollup/rollup-linux-x64-gnu@4.64.12': + resolution: {integrity: sha512-mkbjxPqpR91u1JD7xY4aLZhr/Mqka4/RqGcG4WNGgN/lC1o7TzyCyqJoSJXp9qVVxMwpJGFlEF1VlERb+Ghw1Q==} + cpu: [x64] + os: [linux] + libc: [glibc] + + '@rollup/rollup-linux-x64-musl@4.64.12': + resolution: {integrity: sha512-vIeut2LkuVc3gcsawLJPahNAzvzBcFRhu2O+yVb//BuQKz7PIItMF0piXRbN/lIDO3d68TSDd368Vg6YwgTybw==} + cpu: [x64] + os: [linux] + libc: [musl] + + '@rollup/rollup-openbsd-x64@4.64.12': + resolution: {integrity: sha512-3Sx+D3r9oPkTdNUcPrIRM2Am+vzEV6VGWoImHG4ZVK2jJeOW+eDjLeTm6nvu/z/m0fiX2YmGLXIypblc336MXg==} + cpu: [x64] + os: [openbsd] + + '@rollup/rollup-openharmony-arm64@4.64.12': + resolution: {integrity: sha512-Nn2xh0teFnl71EiiUrKvECWcdGXtWF8q0uGclYwXGVw6QClGAcME0/bJSGdK+xIvd6MLEKYmjkTUvCBV+7m5Kw==} + cpu: [arm64] + os: [openharmony] + + '@rollup/rollup-win32-arm64-msvc@4.64.12': + resolution: {integrity: sha512-n1/0H9TS+kBa4xp6n9aV7yiynBNfmerjkj2nAMIfY0ZHv1zShWRXnsAuAPAH0sfEK4ZSMK+z24q2RjAPFLCN1w==} + cpu: [arm64] + os: [win32] + + '@rollup/rollup-win32-ia32-msvc@4.64.12': + resolution: {integrity: sha512-AdlDbQpsLfGlsHr1NfLZFtdnvxCKNp9TwlYVYExs8JJLWjLafUQEKJk0r9zUbmU57mw9nglMEvzqPHuLWYmaKw==} + cpu: [ia32] + os: [win32] + + '@rollup/rollup-win32-x64-gnu@4.64.12': + resolution: {integrity: sha512-u5SSUJBHod51UamjkigSr+JPre6xMy5vaWTTV2K0SnFG4RuKyYpf66dTSLFKX2cwaldpwyBurXPUCxq8riQMEg==} + cpu: [x64] + os: [win32] + + '@rollup/rollup-win32-x64-msvc@4.64.12': + resolution: {integrity: sha512-j5rXD4R/4DM5+V991AA9xOnG2Rwu2g3p5TPgu1Eu7apju0NUrLl+Bn/KpWc6wYJtlXqzwz1r+LNV1JeBU4VGvw==} + cpu: [x64] + os: [win32] + + '@types/babel__core@7.20.5': + resolution: {integrity: sha512-qoQprZvz5wQFJwMDqeseRXWv3rqMvhgpbXFfVyWhbx9X47POIA6i/+dXefEmZKoAgOaTdaIgNSMqMIU61yRyzA==} + + '@types/babel__generator@7.27.0': + resolution: {integrity: sha512-ufFd2Xi92OAVPYsy+P4n7/U7e68fex0+Ee8gSG9KX7eo084CWiQ4sdxktvdl0bOPupXtVJPY19zk6EwWqUQ8lg==} + + '@types/babel__template@7.4.4': + resolution: {integrity: sha512-h/NUaSyG5EyxBIp8YRxo4RMe2/qQgvyowRwVMzhYhBCONbW8PUsg4lkFMrhgZhUe5z3L3MiLDuvyJ/CaPa2A8A==} + + '@types/babel__traverse@7.28.0': + resolution: {integrity: sha512-8PvcXf70gTDZBgt9ptxJ8elBeBjcLOAcOtoO/mPJjtji1+CdGbHgm77om1GrsPxsiE+uXIpNSK64UYaIwQXd4Q==} + + '@types/estree@1.0.9': + resolution: {integrity: sha512-GhdPgy1el4/ImP05X05Uw4cw2/M93BCUmnEvWZNStlCzEKME4Fkk+YpoA5OiHNQmoS7Cafb8Xa3Pya8m1Qrzeg==} + + '@types/node@22.20.5': + resolution: {integrity: sha512-U2+DNr+wSjpsTS/wZGYHq7GcwfuSmKiKvoPvK22zwTlRhU91yOniN4qRR5KhIjvif7ysw/dz/hKmfDH0Ris4aA==} + + '@types/turndown@5.0.6': + resolution: {integrity: sha512-ru00MoyeeouE5BX4gRL+6m/BsDfbRayOskWqUvh7CLGW+UXxHQItqALa38kKnOiZPqJrtzJUgAC2+F0rL1S4Pg==} + + babel-plugin-jsx-dom-expressions@0.40.11: + resolution: {integrity: sha512-k7TkOv7uVYnrq/bYyVvG5cWOC9IObAGfmyW3aMkG8l2sq2qt/5THkUBja69PMLEGGi8G+fXB2Fh7eS4OwZRBoQ==} + peerDependencies: + '@babel/core': ^7.20.12 + + babel-preset-solid@1.9.16: + resolution: {integrity: sha512-+0h40Qk2oBfkQ4OGDBHIDtvq/XQiOnCfzjNHmMxriAr8MmdsaIbyJgqYglDs4d70sF8O08sSpx61TKdpUt3oRw==} + peerDependencies: + '@babel/core': ^7.0.0 + solid-js: ^1.9.16 + peerDependenciesMeta: + solid-js: + optional: true + + baseline-browser-mapping@2.11.32: + resolution: {integrity: sha512-UvuxFU9P3hM29LrQdwu0cD6w6/+SFr+UlB9s/knI7+O2rK9xFxKUwSDWxGdbbqQ9/V7BJ5s0NI5nQAE4uJp3gQ==} + engines: {node: '>=6.0.0'} + hasBin: true + + boolbase@2.0.0: + resolution: {integrity: sha512-DkVaaQHymRhpYEYo9x1oo7Q7B0Y6KJUsjm3c9eTyFDby4MHLBTwZ6ZDWBel5zrYxj1WsZgC5oLpiz+93MluXeA==} + engines: {node: '>=20.19.0'} + + browserslist@4.29.4: + resolution: {integrity: sha512-2TcbbiwXEq+N0kD36tykpCfyyQigUXmuwNQbnPp4Xk4PX9JOqVIKjJlIDjpH7uY6tmRGoAd+apeT1p60T8wsdA==} + engines: {node: ^6 || ^7 || ^8 || ^9 || ^10 || ^11 || ^12 || >=13.7} + hasBin: true + + caniuse-lite@1.0.30001819: + resolution: {integrity: sha512-LFUqIIAwpzsIuevnKnsR9qnStBcgzPShTX61lBwN9uFkkf8o8zLiebEjbW8AYtZiF+1YKDWfdt/pWDtMuG8Xwg==} + + commander@8.3.0: + resolution: {integrity: sha512-OkTL9umf+He2DZkUq8f8J9of7yL6RJKI24dVITBmNfZBmri9zYZQrKkuXiKhyfPSu8tUhnVBB1iKXevvnlR4Ww==} + engines: {node: '>= 12'} + + convert-source-map@2.0.0: + resolution: {integrity: sha512-Kvp459HrV2FEJ1CAsi1Ku+MY3kasH19TFykTz2xWmMeq6bk2NU3XXvfJ+Q61m0xktWwt+1HSYf3JZsTms3aRJg==} + + css-select@7.0.0: + resolution: {integrity: sha512-snmjEVXy+1LnwXdxhYvTMj1d9tOh4HxkA1YmoayVBeeyR2C14Pum7fcxJIm4SswYspVy866eYNwlH6xC3/VH5g==} + engines: {node: '>=20.19.0'} + + css-what@8.0.0: + resolution: {integrity: sha512-DH0Bqq3DNp5tdOReuNyAA+Ev4Y2GS5FMbZpeTLP6C4CDi0h5nL0BmUPChXw3o/qbHLDWHl49sbNqQVY7bMSDdw==} + engines: {node: '>=20.19.0'} + + csstype@3.2.3: + resolution: {integrity: sha512-z1HGKcYy2xA8AGQfwrn0PAy+PB7X/GSj3UVJW9qKyn43xWa+gl5nXmU4qqLMRzWVLFC8KusUX8T/0kCiOYpAIQ==} + + debug@4.4.3: + resolution: {integrity: sha512-RGwwWnwQvkVfavKVt22FGLw+xYSdzARwm0ru6DhTVA3umU5hZc28V3kO4stgYryrTlLpuvgI9GiijltAjNbcqA==} + engines: {node: '>=6.0'} + peerDependencies: + supports-color: '*' + peerDependenciesMeta: + supports-color: + optional: true + + dom-serializer@2.0.0: + resolution: {integrity: sha512-wIkAryiqt/nV5EQKqQpo3SToSOV9J0DnbJqwK7Wv/Trc92zIAYZ4FlMu+JPFW1DfGFt81ZTCGgDEabffXeLyJg==} + + dom-serializer@3.1.1: + resolution: {integrity: sha512-4MEa38/QexBob6gFNwu+EGdWvhJ1OKuNwdYY3Y3NyeWDQfnGeDYQUDfIRzWu5B5gsv03so2Uxd28YC6zrsx3Lw==} + engines: {node: '>=20.19.0'} + + domelementtype@2.3.0: + resolution: {integrity: sha512-OLETBj6w0OsagBwdXnPdN0cnMfF9opN69co+7ZrbfPGrdpPVNBUj02spi6B1N7wChLQiPn4CSH/zJvXw56gmHw==} + + domelementtype@3.0.0: + resolution: {integrity: sha512-umCQid3jKbDmVjx8jGaW7uUykm4DEUeyV21hPxNMo2nV955DhUThwqyOIDtreepP31hl84X7G5U9ZfsWvIB3Pg==} + engines: {node: '>=20.19.0'} + + domhandler@5.0.3: + resolution: {integrity: sha512-cgwlv/1iFQiFnU96XXgROh8xTeetsnJiDsTc7TYCLFd9+/WNkIqPTxiM/8pSd8VIrhXGTf1Ny1q1hquVqDJB5w==} + engines: {node: '>= 4'} + + domhandler@6.0.1: + resolution: {integrity: sha512-gYzvtM72ZtxQO0T048kd6HWSbbGCNOUwcnfQ01cqIJ4X2IYKFFHZ5mKvrQETcFXxsRObZulDaKmy//R7TPtsBg==} + engines: {node: '>=20.19.0'} + + domutils@3.2.2: + resolution: {integrity: sha512-6kZKyUajlDuqlHKVX1w7gyslj9MPIXzIFiz/rGu35uC1wMi+kMhQwGhl4lt9unC9Vb9INnY9Z3/ZA3+FhASLaw==} + + domutils@4.0.2: + resolution: {integrity: sha512-qI4JLRKnSzqFqr7hAlS5xQDusBCjKSEG4t4+7aNrIQMHBcsC2TGEhuyABJdYkgSewL57PNLYEiibY2iPKhKpaA==} + engines: {node: '>=20.19.0'} + + electron-to-chromium@1.5.464: + resolution: {integrity: sha512-nRa65aFge40viPAKxMKULIY8tcXKwKboJWNn4RoKwyWXJ6SP7BnrDGKUTzc64818jIciH0PK7LSF8QzZes19GA==} + + entities@4.5.0: + resolution: {integrity: sha512-V0hjH4dGPh9Ao5p0MoRY6BVqtwCjhz6vI5LT8AJ55H+4g9/4vbHx1I54fS0XuclLhDHArPQCiMjDxjaL8fPxhw==} + engines: {node: '>=0.12'} + + entities@6.0.1: + resolution: {integrity: sha512-aN97NXWF6AWBTahfVOIrB/NShkzi5H7F9r1s9mD3cDj4Ko5f2qhhVoYMibXF7GlLveb/D2ioWay8lxI97Ven3g==} + engines: {node: '>=0.12'} + + entities@7.0.1: + resolution: {integrity: sha512-TWrgLOFUQTH994YUyl1yT4uyavY5nNB5muff+RtWaqNVCAK408b5ZnnbNAUEWLTCpum9w6arT70i1XdQ4UeOPA==} + engines: {node: '>=0.12'} + + entities@8.1.0: + resolution: {integrity: sha512-kxL7msIffSuh9aaFAMD7rxAIuTRMAHMeBtgHW2yUdWw732ZNh4MehkF2gdjvtdmikkaIP9bFDDJOPlsvm7avrA==} + engines: {node: '>=20.19.0'} + + esbuild@0.28.2: + resolution: {integrity: sha512-HKVLS8dvII+xoKW9kmqxbRKrnWEXfJJr/FZhhJmiqIB0e053QNYFqOBouTMO/k5sID4MvCiUCvv8b9M4h32wIA==} + engines: {node: '>=18'} + hasBin: true + + escalade@3.2.0: + resolution: {integrity: sha512-WUj2qlxaQtO4g6Pq5c29GTcWGDyd8itL8zTlipgECz3JesAiiOKotd8JU6otB3PACgG6xkJUyVhboMS+bje/jA==} + engines: {node: '>=6'} + + fdir@6.5.0: + resolution: {integrity: sha512-tIbYtZbucOs0BRGqPJkshJUYdL+SDH7dVM8gjy+ERp3WAUjLEFJE+02kanyHtwjWOnwrKYBiwAmM0p4kLJAnXg==} + engines: {node: '>=12.0.0'} + peerDependencies: + picomatch: ^3 || ^4 + peerDependenciesMeta: + picomatch: + optional: true + + fsevents@2.3.3: + resolution: {integrity: sha512-5xoDfX+fL7faATnagmWPpbFtwh/R77WmMMqqHGS65C3vvB0YHrgF+B1YmZ3441tMj5n63k0212XNoJwzlhffQw==} + engines: {node: ^8.16.0 || ^10.6.0 || >=11.0.0} + os: [darwin] + + gensync@1.0.0-beta.2: + resolution: {integrity: sha512-3hN7NaskYvMDLQY55gnW3NQ+mesEAepTqlg+VEbj7zzqEMBVNhzcGYYeqFo/TlYz6eQiFcp1HcsCZO+nGgS8zg==} + engines: {node: '>=6.9.0'} + + highlight.js@11.12.0: + resolution: {integrity: sha512-nbfWpyRMcMrPMmDwJB+dhX/eiaPKtc2RB+0QZskqJ3WjRA/FDS0e9hZrx8EC/lbEv8gXy98FcDbNa/dspAaJMg==} + engines: {node: '>=12.0.0'} + + html-entities@2.3.3: + resolution: {integrity: sha512-DV5Ln36z34NNTDgnz0EWGBLZENelNAtkiFA4kyNOG2tDI6Mz1uSWiq1wAKdyjnJwyDiDO7Fa2SO1CTxPXL8VxA==} + + html-escaper@3.0.3: + resolution: {integrity: sha512-RuMffC89BOWQoY0WKGpIhn5gX3iI54O6nRA0yC124NYVtzjmFWBIiFd8M0x+ZdX0P9R4lADg1mgP8C7PxGOWuQ==} + + htmlparser2@10.1.0: + resolution: {integrity: sha512-VTZkM9GWRAtEpveh7MSF6SjjrpNVNNVJfFup7xTY3UpFtm67foy9HDVXneLtFVt4pMz5kZtgNcvCniNFb1hlEQ==} + + is-what@4.1.16: + resolution: {integrity: sha512-ZhMwEosbFJkA0YhFnNDgTM4ZxDRsS6HqTo7qsZM08fehyRYIYa0yHu5R6mgo1n/8MgaPBXiPimPD77baVFYg+A==} + engines: {node: '>=12.13'} + + js-tokens@4.0.0: + resolution: {integrity: sha512-RdJUflcE3cUzKiMqQgsCu06FPu9UdIJO0beYbPhHN4k6apgJtifcoCtT9bcxOpYBtpD2kCM6Sbzg4CausW/PKQ==} + + jsesc@3.1.0: + resolution: {integrity: sha512-/sM3dO2FOzXjKQhJuo0Q173wf2KOo8t4I8vHy6lF9poUp7bKT0/NHE8fPX23PwfhnykfqnC2xRxOnVw5XuGIaA==} + engines: {node: '>=6'} + hasBin: true + + json5@2.2.3: + resolution: {integrity: sha512-XmOWe7eyHYH14cLdVPoyg+GOH3rYX++KpzrylJwSW98t3Nk+U8XOl8FWKOgwtzdb8lXGf6zYwDUzeHMWfxasyg==} + engines: {node: '>=6'} + hasBin: true + + katex@0.16.47: + resolution: {integrity: sha512-Eeo8Ys1doU1z+x8AZsPpQu+p/QcZBI5PeOo7QGQdy2x2m0MU/hYagBbGOmXwr5KVbEfVuWv9LpnQWeehogurjg==} + hasBin: true + + linkedom@0.18.14: + resolution: {integrity: sha512-BRUnkOm4YR5vo+qI3j0EbungB0vZPSCue5AdnTQRaxAGSbsOZiBFRO0rh4zlo8qXUhli8pxvnpEXDklMnlq2Rg==} + engines: {node: '>=16'} + peerDependencies: + canvas: '>= 2' + peerDependenciesMeta: + canvas: + optional: true + + lru-cache@5.1.1: + resolution: {integrity: sha512-KpNARQA3Iwv+jTA0utUVVbrh+Jlrr1Fv0e56GGzAFOXN7dk/FviaDW8LHmK52DlcH4WP2n6gI8vN1aesBFgo9w==} + + lucide@0.468.0: + resolution: {integrity: sha512-UFbgwji/ZnAV7iTTE4jujyTV7J95AILKyATDUrqOJrMcUGfXvGjw3c1mcuHZUX2oJfkrAGU9KoxkrLQk2jjtiA==} + + merge-anything@5.1.7: + resolution: {integrity: sha512-eRtbOb1N5iyH0tkQDAoQ4Ipsp/5qSR79Dzrz8hEPxRX10RWWR/iQXdoKmBSRCThY1Fh5EhISDtpSc93fpxUniQ==} + engines: {node: '>=12.13'} + + ms@2.1.3: + resolution: {integrity: sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA==} + + nanoid@3.3.20: + resolution: {integrity: sha512-uKdg2G3GNCKQn9byYOpxbGqrT2fGO5KRt5J/8b3pok8rT6qxGWF6hxMyJiEYtAf+FVyYuD9hRaDqX5uPFYJ4ZQ==} + engines: {node: ^10 || ^12 || ^13.7 || ^14 || >=15.0.1} + hasBin: true + + node-releases@2.0.60: + resolution: {integrity: sha512-OmO8+GM1JUZqXET720VrJCwkjUCXmCMQm0Z3UDDRbfNLHS4NEAvY60j5jiFv0tkKw2PNNlqOLhahVmwJIOLDIQ==} + engines: {node: '>=18'} + + nth-check@3.0.1: + resolution: {integrity: sha512-GX0gsdbGVCgnRgbeGaubfjpBXyYRWOOCVeYh08bSQvDZqxz5ndXs1OTfAt/h36G1xvI94YIspsI0sVFqAV9+RQ==} + engines: {node: '>=20.19.0'} + + page-flip@2.0.7: + resolution: {integrity: sha512-96lQFUUz7r/LZzEUZJ3yBIMEKU9+m8HMFDzTvTdD6P7Ag/wXINjp9n0W7b4wanwnDbQETo4uNUoL3zMqpFxwGA==} + + parse5@7.3.0: + resolution: {integrity: sha512-IInvU7fabl34qmi9gY8XOVxhYyMyuH2xUNpb2q8/Y+7552KlejkRvqvD19nMoUW/uQGGbqNpA6Tufu5FL5BZgw==} + + picocolors@1.1.1: + resolution: {integrity: sha512-xceH2snhtb5M9liqDsmEw56le376mTZkEX/jEb/RxNFyegNul7eNslCXP9FDj/Lcu0X8KEyMceP2ntpaHrDEVA==} + + picomatch@4.0.7: + resolution: {integrity: sha512-qcJu88Q2IWqJsDD529JKMdwGm/dvInW4HvQnRwiH9JtihJvzGOscDtHE3x1pBKeUOTysQ8kVmLnJ2kJu7yhcGA==} + engines: {node: '>=12'} + + playwright-core@1.64.1: + resolution: {integrity: sha512-BC4s8y6SEVA6Q1rSxZTto8hI1KUI3xXlHGZgvGqP4IqPdI/a6FX9H29IDNz7vKo9l21b6LfYosScPL6M3xxyDQ==} + engines: {node: '>=20'} + hasBin: true + + playwright@1.64.1: + resolution: {integrity: sha512-HCrVhHr5QQuwYoswEUGTb7gGp522yflbv/ST8nF4sFWGuLjQCt17Q/EubpGGSNKYn1tsTCPZxqHhHCfVURu7UA==} + engines: {node: '>=20'} + hasBin: true + + postcss@8.5.31: + resolution: {integrity: sha512-YUbWYCgErwnMAVkjUnYa+KlMBzGpHwiIt/DE7f0G33AuX2LH9UcTk6KgWxd3zRU+pN3u/C+Xl3EnMLM4Hea7Sg==} + engines: {node: ^10 || ^12 || >=14} + + rollup@4.64.12: + resolution: {integrity: sha512-GhAu8ZglZ61VWSX/ZW3K/qkazgURBIQL0/Yy51QsS8DPyebR5Cf/Z2PANJFpTU0aVZ9byJcyqR6xvBbkXhdGYQ==} + engines: {node: '>=18.0.0', npm: '>=8.0.0'} + hasBin: true + + semver@6.3.1: + resolution: {integrity: sha512-BR7VvDCVHO+q2xBEWskxS6DJE1qRnb7DxzUrogb71CWoSficBxYsiAGd+Kl0mmq/MprG9yArRkyrQxTO6XjMzA==} + hasBin: true + + seroval-plugins@1.6.12: + resolution: {integrity: sha512-+reiwp/lYxiyctSrdvX7OQ1YLrcbWYgBiZrhSFL+V43b0/DGRLNVSDyZINbQe+tWplPOI2fw2dPrdv6hcc09kQ==} + engines: {node: '>=10'} + peerDependencies: + seroval: ^1.0 + + seroval@1.6.12: + resolution: {integrity: sha512-CqbIVfk/7GL3ITwZI55lcPbpQbjHZ2DD5cUj4iH7E9YsCfHNJV1mx7yNp86Z84w5IpmkZZS/2s5vPOWmVWSdQg==} + engines: {node: '>=10'} + + smol-toml@1.9.1: + resolution: {integrity: sha512-j7WyPdf0CJoutMzMoPLF/bVXHtKZIT9Rb4eGeEbWw8X2t5oirjPgpL+OpaENZrILYaXqYwnVH+qgUwVbl+pUJQ==} + engines: {node: '>= 18'} + + solid-js@1.9.17: + resolution: {integrity: sha512-4GAmLOWPfNV8H9Jfn2LSFTpNEG6jiOKPiwd5lnLGQtehHaX6l3TOLzJqQ7mqwB/3k1Yy3zyumFVopmc/tm34ow==} + + solid-refresh@0.6.3: + resolution: {integrity: sha512-F3aPsX6hVw9ttm5LYlth8Q15x6MlI/J3Dn+o3EQyRTtTxidepSTwAYdozt01/YA+7ObcciagGEyXIopGZzQtbA==} + peerDependencies: + solid-js: ^1.3 + + source-map-js@1.2.2: + resolution: {integrity: sha512-KGj/8Y43x35aZVDtt+J4mK1hoLGHULMYfSkODJNQjNDC3oW1PqPoxMwo0pLUsWM/UEGzON/NxeHywEfNXNP3Vw==} + engines: {node: '>=0.10.0'} + + tinyglobby@0.2.17: + resolution: {integrity: sha512-wXR/dYpcqKmfWpEdZjiKJOwCNFndD0DMnrW/cYjVGttEkBfVgcLFHoNrlj47mjOVic9yyNu65alsgF4NQyTa2g==} + engines: {node: '>=12.0.0'} + + turndown-plugin-gfm@1.0.2: + resolution: {integrity: sha512-vwz9tfvF7XN/jE0dGoBei3FXWuvll78ohzCZQuOb+ZjWrs3a0XhQVomJEb2Qh4VHTPNRO4GPZh0V7VRbiWwkRg==} + + turndown@7.2.2: + resolution: {integrity: sha512-1F7db8BiExOKxjSMU2b7if62D/XOyQyZbPKq/nUwopfgnHlqXHqQ0lvfUTeUIr1lZJzOPFn43dODyMSIfvWRKQ==} + + typescript@5.9.3: + resolution: {integrity: sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==} + engines: {node: '>=14.17'} + hasBin: true + + uhyphen@0.2.0: + resolution: {integrity: sha512-qz3o9CHXmJJPGBdqzab7qAYuW8kQGKNEuoHFYrBwV6hWIMcpAmxDLXojcHfFr9US1Pe6zUswEIJIbLI610fuqA==} + + undici-types@6.21.0: + resolution: {integrity: sha512-iwDZqg0QAGrg9Rav5H4n0M64c3mkR59cJ6wQp+7C4nI0gsmExaedaYLNO44eT4AtBBwjbTiGPMlt2Md0T9H9JQ==} + + update-browserslist-db@1.3.4: + resolution: {integrity: sha512-t8wonIOdQyOjtPd2VktlBu6QjTVTks6v8bSi7kd0r2Vll8TK1JYDZtRRdbmCHOAMphkZgrzK+L+vXK4pyZ8t4A==} + hasBin: true + peerDependencies: + browserslist: '>= 4.21.0' + + vite-plugin-solid@2.11.14: + resolution: {integrity: sha512-7ZVBt8rpoyqmlwin2kRIUveaHoF6/kulY7gsnD+qFh4nS29V4OPAnw+ojoAspXIjObiL9o1xh9a/nTuYHm02Rw==} + peerDependencies: + '@testing-library/jest-dom': ^5.16.6 || ^5.17.0 || ^6.0.0 || ^7.0.0 + solid-js: ^1.7.2 + vite: ^3.0.0 || ^4.0.0 || ^5.0.0 || ^6.0.0 || ^7.0.0 || ^8.0.0 || ^9.0.0 + peerDependenciesMeta: + '@testing-library/jest-dom': + optional: true + + vite@7.3.7: + resolution: {integrity: sha512-AHEzTORMbi7/7aXp7w7KZ5+DCUdSeLsJz0grY8xHpc9DHdYb0vQu6DqJfm2tOw3gDExNgPgnJTXxM6syYFHaCA==} + engines: {node: ^20.19.0 || >=22.12.0} + hasBin: true + peerDependencies: + '@types/node': ^20.19.0 || >=22.12.0 + jiti: '>=1.21.0' + less: ^4.0.0 + lightningcss: ^1.21.0 + sass: ^1.70.0 + sass-embedded: ^1.70.0 + stylus: '>=0.54.8' + sugarss: ^5.0.0 + terser: ^5.16.0 + tsx: ^4.8.1 + yaml: ^2.4.2 + peerDependenciesMeta: + '@types/node': + optional: true + jiti: + optional: true + less: + optional: true + lightningcss: + optional: true + sass: + optional: true + sass-embedded: + optional: true + stylus: + optional: true + sugarss: + optional: true + terser: + optional: true + tsx: + optional: true + yaml: + optional: true + + vitefu@1.1.3: + resolution: {integrity: sha512-ub4okH7Z5KLjb6hDyjqrGXqWtWvoYdU3IGm/NorpgHncKoLTCfRIbvlhBm7r0YstIaQRYlp4yEbFqDcKSzXSSg==} + peerDependencies: + vite: ^3.0.0 || ^4.0.0 || ^5.0.0 || ^6.0.0 || ^7.0.0 || ^8.0.0 + peerDependenciesMeta: + vite: + optional: true + + yallist@3.1.1: + resolution: {integrity: sha512-a4UGQaWPH59mOXUYnAG2ewncQS4i4F43Tv3JoAM+s2VDAmS9NsK8GpDMLrCHPksFT7h3K6TOoUNn2pb7RoXx4g==} + +snapshots: + + '@acemir/cssom@0.9.32': {} + + '@babel/code-frame@7.29.7': + dependencies: + '@babel/helper-validator-identifier': 7.29.7 + js-tokens: 4.0.0 + picocolors: 1.1.1 + + '@babel/compat-data@7.29.7': {} + + '@babel/core@7.29.7': + dependencies: + '@babel/code-frame': 7.29.7 + '@babel/generator': 7.29.8 + '@babel/helper-compilation-targets': 7.29.7 + '@babel/helper-module-transforms': 7.29.7(@babel/core@7.29.7) + '@babel/helpers': 7.29.10 + '@babel/parser': 7.29.11 + '@babel/template': 7.29.7 + '@babel/traverse': 7.29.10 + '@babel/types': 7.29.11 + '@jridgewell/remapping': 2.3.5 + convert-source-map: 2.0.0 + debug: 4.4.3 + gensync: 1.0.0-beta.2 + json5: 2.2.3 + semver: 6.3.1 + transitivePeerDependencies: + - supports-color + + '@babel/generator@7.29.8': + dependencies: + '@babel/parser': 7.29.11 + '@babel/types': 7.29.11 + '@jridgewell/gen-mapping': 0.3.13 + '@jridgewell/trace-mapping': 0.3.31 + jsesc: 3.1.0 + + '@babel/helper-compilation-targets@7.29.7': + dependencies: + '@babel/compat-data': 7.29.7 + '@babel/helper-validator-option': 7.29.7 + browserslist: 4.29.4 + lru-cache: 5.1.1 + semver: 6.3.1 + + '@babel/helper-globals@7.29.7': {} + + '@babel/helper-module-imports@7.18.6': + dependencies: + '@babel/types': 7.29.11 + + '@babel/helper-module-imports@7.29.7': + dependencies: + '@babel/traverse': 7.29.10 + '@babel/types': 7.29.11 + transitivePeerDependencies: + - supports-color + + '@babel/helper-module-transforms@7.29.7(@babel/core@7.29.7)': + dependencies: + '@babel/core': 7.29.7 + '@babel/helper-module-imports': 7.29.7 + '@babel/helper-validator-identifier': 7.29.7 + '@babel/traverse': 7.29.10 + transitivePeerDependencies: + - supports-color + + '@babel/helper-plugin-utils@7.29.7': {} + + '@babel/helper-string-parser@7.29.11': {} + + '@babel/helper-validator-identifier@7.29.7': {} + + '@babel/helper-validator-option@7.29.7': {} + + '@babel/helpers@7.29.10': + dependencies: + '@babel/template': 7.29.7 + '@babel/types': 7.29.11 + + '@babel/parser@7.29.11': + dependencies: + '@babel/types': 7.29.11 + + '@babel/plugin-syntax-jsx@7.29.7(@babel/core@7.29.7)': + dependencies: + '@babel/core': 7.29.7 + '@babel/helper-plugin-utils': 7.29.7 + + '@babel/template@7.29.7': + dependencies: + '@babel/code-frame': 7.29.7 + '@babel/parser': 7.29.11 + '@babel/types': 7.29.11 + + '@babel/traverse@7.29.10': + dependencies: + '@babel/code-frame': 7.29.7 + '@babel/generator': 7.29.8 + '@babel/helper-globals': 7.29.7 + '@babel/parser': 7.29.11 + '@babel/template': 7.29.7 + '@babel/types': 7.29.11 + debug: 4.4.3 + transitivePeerDependencies: + - supports-color + + '@babel/types@7.29.11': + dependencies: + '@babel/helper-string-parser': 7.29.11 + '@babel/helper-validator-identifier': 7.29.7 + + '@esbuild/aix-ppc64@0.28.2': + optional: true + + '@esbuild/android-arm64@0.28.2': + optional: true + + '@esbuild/android-arm@0.28.2': + optional: true + + '@esbuild/android-x64@0.28.2': + optional: true + + '@esbuild/darwin-arm64@0.28.2': + optional: true + + '@esbuild/darwin-x64@0.28.2': + optional: true + + '@esbuild/freebsd-arm64@0.28.2': + optional: true + + '@esbuild/freebsd-x64@0.28.2': + optional: true + + '@esbuild/linux-arm64@0.28.2': + optional: true + + '@esbuild/linux-arm@0.28.2': + optional: true + + '@esbuild/linux-ia32@0.28.2': + optional: true + + '@esbuild/linux-loong64@0.28.2': + optional: true + + '@esbuild/linux-mips64el@0.28.2': + optional: true + + '@esbuild/linux-ppc64@0.28.2': + optional: true + + '@esbuild/linux-riscv64@0.28.2': + optional: true + + '@esbuild/linux-s390x@0.28.2': + optional: true + + '@esbuild/linux-x64@0.28.2': + optional: true + + '@esbuild/netbsd-arm64@0.28.2': + optional: true + + '@esbuild/netbsd-x64@0.28.2': + optional: true + + '@esbuild/openbsd-arm64@0.28.2': + optional: true + + '@esbuild/openbsd-x64@0.28.2': + optional: true + + '@esbuild/openharmony-arm64@0.28.2': + optional: true + + '@esbuild/sunos-x64@0.28.2': + optional: true + + '@esbuild/win32-arm64@0.28.2': + optional: true + + '@esbuild/win32-ia32@0.28.2': + optional: true + + '@esbuild/win32-x64@0.28.2': + optional: true + + '@fontsource/cormorant-garamond@5.3.0': {} + + '@jridgewell/gen-mapping@0.3.13': + dependencies: + '@jridgewell/sourcemap-codec': 1.6.0 + '@jridgewell/trace-mapping': 0.3.31 + + '@jridgewell/remapping@2.3.5': + dependencies: + '@jridgewell/gen-mapping': 0.3.13 + '@jridgewell/trace-mapping': 0.3.31 + + '@jridgewell/resolve-uri@3.1.2': {} + + '@jridgewell/sourcemap-codec@1.6.0': {} + + '@jridgewell/trace-mapping@0.3.31': + dependencies: + '@jridgewell/resolve-uri': 3.1.2 + '@jridgewell/sourcemap-codec': 1.6.0 + + '@mixmark-io/domino@2.2.0': {} + + '@napi-rs/lzma-linux-x64-gnu@1.5.1': + optional: true + + '@rollup/rollup-android-arm-eabi@4.64.12': + optional: true + + '@rollup/rollup-android-arm64@4.64.12': + optional: true + + '@rollup/rollup-darwin-arm64@4.64.12': + optional: true + + '@rollup/rollup-darwin-x64@4.64.12': + optional: true + + '@rollup/rollup-freebsd-arm64@4.64.12': + optional: true + + '@rollup/rollup-freebsd-x64@4.64.12': + optional: true + + '@rollup/rollup-linux-arm-gnueabihf@4.64.12': + optional: true + + '@rollup/rollup-linux-arm-musleabihf@4.64.12': + optional: true + + '@rollup/rollup-linux-arm64-gnu@4.64.12': + optional: true + + '@rollup/rollup-linux-arm64-musl@4.64.12': + optional: true + + '@rollup/rollup-linux-loong64-gnu@4.64.12': + optional: true + + '@rollup/rollup-linux-loong64-musl@4.64.12': + optional: true + + '@rollup/rollup-linux-ppc64-gnu@4.64.12': + optional: true + + '@rollup/rollup-linux-ppc64-musl@4.64.12': + optional: true + + '@rollup/rollup-linux-riscv64-gnu@4.64.12': + optional: true + + '@rollup/rollup-linux-riscv64-musl@4.64.12': + optional: true + + '@rollup/rollup-linux-s390x-gnu@4.64.12': + optional: true + + '@rollup/rollup-linux-x64-gnu@4.64.12': + optional: true + + '@rollup/rollup-linux-x64-musl@4.64.12': + optional: true + + '@rollup/rollup-openbsd-x64@4.64.12': + optional: true + + '@rollup/rollup-openharmony-arm64@4.64.12': + optional: true + + '@rollup/rollup-win32-arm64-msvc@4.64.12': + optional: true + + '@rollup/rollup-win32-ia32-msvc@4.64.12': + optional: true + + '@rollup/rollup-win32-x64-gnu@4.64.12': + optional: true + + '@rollup/rollup-win32-x64-msvc@4.64.12': + optional: true + + '@types/babel__core@7.20.5': + dependencies: + '@babel/parser': 7.29.11 + '@babel/types': 7.29.11 + '@types/babel__generator': 7.27.0 + '@types/babel__template': 7.4.4 + '@types/babel__traverse': 7.28.0 + + '@types/babel__generator@7.27.0': + dependencies: + '@babel/types': 7.29.11 + + '@types/babel__template@7.4.4': + dependencies: + '@babel/parser': 7.29.11 + '@babel/types': 7.29.11 + + '@types/babel__traverse@7.28.0': + dependencies: + '@babel/types': 7.29.11 + + '@types/estree@1.0.9': {} + + '@types/node@22.20.5': + dependencies: + undici-types: 6.21.0 + + '@types/turndown@5.0.6': {} + + babel-plugin-jsx-dom-expressions@0.40.11(@babel/core@7.29.7): + dependencies: + '@babel/core': 7.29.7 + '@babel/helper-module-imports': 7.18.6 + '@babel/plugin-syntax-jsx': 7.29.7(@babel/core@7.29.7) + '@babel/types': 7.29.11 + html-entities: 2.3.3 + parse5: 7.3.0 + + babel-preset-solid@1.9.16(@babel/core@7.29.7)(solid-js@1.9.17): + dependencies: + '@babel/core': 7.29.7 + babel-plugin-jsx-dom-expressions: 0.40.11(@babel/core@7.29.7) + optionalDependencies: + solid-js: 1.9.17 + + baseline-browser-mapping@2.11.32: {} + + boolbase@2.0.0: {} + + browserslist@4.29.4: + dependencies: + baseline-browser-mapping: 2.11.32 + caniuse-lite: 1.0.30001819 + electron-to-chromium: 1.5.464 + node-releases: 2.0.60 + update-browserslist-db: 1.3.4(browserslist@4.29.4) + + caniuse-lite@1.0.30001819: {} + + commander@8.3.0: {} + + convert-source-map@2.0.0: {} + + css-select@7.0.0: + dependencies: + boolbase: 2.0.0 + css-what: 8.0.0 + domhandler: 6.0.1 + domutils: 4.0.2 + nth-check: 3.0.1 + + css-what@8.0.0: {} + + csstype@3.2.3: {} + + debug@4.4.3: + dependencies: + ms: 2.1.3 + + dom-serializer@2.0.0: + dependencies: + domelementtype: 2.3.0 + domhandler: 5.0.3 + entities: 4.5.0 + + dom-serializer@3.1.1: + dependencies: + domelementtype: 3.0.0 + domhandler: 6.0.1 + entities: 8.1.0 + + domelementtype@2.3.0: {} + + domelementtype@3.0.0: {} + + domhandler@5.0.3: + dependencies: + domelementtype: 2.3.0 + + domhandler@6.0.1: + dependencies: + domelementtype: 3.0.0 + + domutils@3.2.2: + dependencies: + dom-serializer: 2.0.0 + domelementtype: 2.3.0 + domhandler: 5.0.3 + + domutils@4.0.2: + dependencies: + dom-serializer: 3.1.1 + domelementtype: 3.0.0 + domhandler: 6.0.1 + + electron-to-chromium@1.5.464: {} + + entities@4.5.0: {} + + entities@6.0.1: {} + + entities@7.0.1: {} + + entities@8.1.0: {} + + esbuild@0.28.2: + optionalDependencies: + '@esbuild/aix-ppc64': 0.28.2 + '@esbuild/android-arm': 0.28.2 + '@esbuild/android-arm64': 0.28.2 + '@esbuild/android-x64': 0.28.2 + '@esbuild/darwin-arm64': 0.28.2 + '@esbuild/darwin-x64': 0.28.2 + '@esbuild/freebsd-arm64': 0.28.2 + '@esbuild/freebsd-x64': 0.28.2 + '@esbuild/linux-arm': 0.28.2 + '@esbuild/linux-arm64': 0.28.2 + '@esbuild/linux-ia32': 0.28.2 + '@esbuild/linux-loong64': 0.28.2 + '@esbuild/linux-mips64el': 0.28.2 + '@esbuild/linux-ppc64': 0.28.2 + '@esbuild/linux-riscv64': 0.28.2 + '@esbuild/linux-s390x': 0.28.2 + '@esbuild/linux-x64': 0.28.2 + '@esbuild/netbsd-arm64': 0.28.2 + '@esbuild/netbsd-x64': 0.28.2 + '@esbuild/openbsd-arm64': 0.28.2 + '@esbuild/openbsd-x64': 0.28.2 + '@esbuild/openharmony-arm64': 0.28.2 + '@esbuild/sunos-x64': 0.28.2 + '@esbuild/win32-arm64': 0.28.2 + '@esbuild/win32-ia32': 0.28.2 + '@esbuild/win32-x64': 0.28.2 + + escalade@3.2.0: {} + + fdir@6.5.0(picomatch@4.0.7): + optionalDependencies: + picomatch: 4.0.7 + + fsevents@2.3.3: + optional: true + + gensync@1.0.0-beta.2: {} + + highlight.js@11.12.0: {} + + html-entities@2.3.3: {} + + html-escaper@3.0.3: {} + + htmlparser2@10.1.0: + dependencies: + domelementtype: 2.3.0 + domhandler: 5.0.3 + domutils: 3.2.2 + entities: 7.0.1 + + is-what@4.1.16: {} + + js-tokens@4.0.0: {} + + jsesc@3.1.0: {} + + json5@2.2.3: {} + + katex@0.16.47: + dependencies: + commander: 8.3.0 + + linkedom@0.18.14: + dependencies: + '@acemir/cssom': 0.9.32 + css-select: 7.0.0 + html-escaper: 3.0.3 + htmlparser2: 10.1.0 + uhyphen: 0.2.0 + + lru-cache@5.1.1: + dependencies: + yallist: 3.1.1 + + lucide@0.468.0: {} + + merge-anything@5.1.7: + dependencies: + is-what: 4.1.16 + + ms@2.1.3: {} + + nanoid@3.3.20: {} + + node-releases@2.0.60: {} + + nth-check@3.0.1: + dependencies: + boolbase: 2.0.0 + + page-flip@2.0.7(patch_hash=7c9637358d2df31df3c007deea58f55b7c91b30400f9f92623d4aba9c9b9cfb6): {} + + parse5@7.3.0: + dependencies: + entities: 6.0.1 + + picocolors@1.1.1: {} + + picomatch@4.0.7: {} + + playwright-core@1.64.1: {} + + playwright@1.64.1: + dependencies: + playwright-core: 1.64.1 + + postcss@8.5.31: + dependencies: + nanoid: 3.3.20 + picocolors: 1.1.1 + source-map-js: 1.2.2 + + rollup@4.64.12: + dependencies: + '@types/estree': 1.0.9 + optionalDependencies: + '@napi-rs/lzma-linux-x64-gnu': 1.5.1 + '@rollup/rollup-android-arm-eabi': 4.64.12 + '@rollup/rollup-android-arm64': 4.64.12 + '@rollup/rollup-darwin-arm64': 4.64.12 + '@rollup/rollup-darwin-x64': 4.64.12 + '@rollup/rollup-freebsd-arm64': 4.64.12 + '@rollup/rollup-freebsd-x64': 4.64.12 + '@rollup/rollup-linux-arm-gnueabihf': 4.64.12 + '@rollup/rollup-linux-arm-musleabihf': 4.64.12 + '@rollup/rollup-linux-arm64-gnu': 4.64.12 + '@rollup/rollup-linux-arm64-musl': 4.64.12 + '@rollup/rollup-linux-loong64-gnu': 4.64.12 + '@rollup/rollup-linux-loong64-musl': 4.64.12 + '@rollup/rollup-linux-ppc64-gnu': 4.64.12 + '@rollup/rollup-linux-ppc64-musl': 4.64.12 + '@rollup/rollup-linux-riscv64-gnu': 4.64.12 + '@rollup/rollup-linux-riscv64-musl': 4.64.12 + '@rollup/rollup-linux-s390x-gnu': 4.64.12 + '@rollup/rollup-linux-x64-gnu': 4.64.12 + '@rollup/rollup-linux-x64-musl': 4.64.12 + '@rollup/rollup-openbsd-x64': 4.64.12 + '@rollup/rollup-openharmony-arm64': 4.64.12 + '@rollup/rollup-win32-arm64-msvc': 4.64.12 + '@rollup/rollup-win32-ia32-msvc': 4.64.12 + '@rollup/rollup-win32-x64-gnu': 4.64.12 + '@rollup/rollup-win32-x64-msvc': 4.64.12 + fsevents: 2.3.3 + + semver@6.3.1: {} + + seroval-plugins@1.6.12(seroval@1.6.12): + dependencies: + seroval: 1.6.12 + + seroval@1.6.12: {} + + smol-toml@1.9.1: {} + + solid-js@1.9.17: + dependencies: + csstype: 3.2.3 + seroval: 1.6.12 + seroval-plugins: 1.6.12(seroval@1.6.12) + + solid-refresh@0.6.3(solid-js@1.9.17): + dependencies: + '@babel/generator': 7.29.8 + '@babel/helper-module-imports': 7.29.7 + '@babel/types': 7.29.11 + solid-js: 1.9.17 + transitivePeerDependencies: + - supports-color + + source-map-js@1.2.2: {} + + tinyglobby@0.2.17: + dependencies: + fdir: 6.5.0(picomatch@4.0.7) + picomatch: 4.0.7 + + turndown-plugin-gfm@1.0.2: {} + + turndown@7.2.2: + dependencies: + '@mixmark-io/domino': 2.2.0 + + typescript@5.9.3: {} + + uhyphen@0.2.0: {} + + undici-types@6.21.0: {} + + update-browserslist-db@1.3.4(browserslist@4.29.4): + dependencies: + browserslist: 4.29.4 + escalade: 3.2.0 + picocolors: 1.1.1 + + vite-plugin-solid@2.11.14(solid-js@1.9.17)(vite@7.3.7(@types/node@22.20.5)): + dependencies: + '@babel/core': 7.29.7 + '@types/babel__core': 7.20.5 + babel-preset-solid: 1.9.16(@babel/core@7.29.7)(solid-js@1.9.17) + merge-anything: 5.1.7 + solid-js: 1.9.17 + solid-refresh: 0.6.3(solid-js@1.9.17) + vite: 7.3.7(@types/node@22.20.5) + vitefu: 1.1.3(vite@7.3.7(@types/node@22.20.5)) + transitivePeerDependencies: + - supports-color + + vite@7.3.7(@types/node@22.20.5): + dependencies: + esbuild: 0.28.2 + fdir: 6.5.0(picomatch@4.0.7) + picomatch: 4.0.7 + postcss: 8.5.31 + rollup: 4.64.12 + tinyglobby: 0.2.17 + optionalDependencies: + '@types/node': 22.20.5 + fsevents: 2.3.3 + + vitefu@1.1.3(vite@7.3.7(@types/node@22.20.5)): + optionalDependencies: + vite: 7.3.7(@types/node@22.20.5) + + yallist@3.1.1: {} diff --git a/web/pnpm-workspace.yaml b/web/pnpm-workspace.yaml new file mode 100644 index 0000000..21961cb --- /dev/null +++ b/web/pnpm-workspace.yaml @@ -0,0 +1,4 @@ +allowBuilds: + esbuild: true +patchedDependencies: + page-flip@2.0.7: patches/page-flip@2.0.7.patch diff --git a/web/previews/assets/contents-dark.jpg b/web/previews/assets/contents-dark.jpg new file mode 100644 index 0000000..1694243 Binary files /dev/null and b/web/previews/assets/contents-dark.jpg differ diff --git a/web/previews/assets/contents-light.jpg b/web/previews/assets/contents-light.jpg new file mode 100644 index 0000000..1c04685 Binary files /dev/null and b/web/previews/assets/contents-light.jpg differ diff --git a/web/previews/assets/entrance.jpg b/web/previews/assets/entrance.jpg new file mode 100644 index 0000000..8cfa263 Binary files /dev/null and b/web/previews/assets/entrance.jpg differ diff --git a/web/previews/assets/magic-night.jpg b/web/previews/assets/magic-night.jpg new file mode 100644 index 0000000..46d8326 Binary files /dev/null and b/web/previews/assets/magic-night.jpg differ diff --git a/web/previews/assets/magic.jpg b/web/previews/assets/magic.jpg new file mode 100644 index 0000000..0d0a4e0 Binary files /dev/null and b/web/previews/assets/magic.jpg differ diff --git a/web/previews/assets/mobile.jpg b/web/previews/assets/mobile.jpg new file mode 100644 index 0000000..67166b9 Binary files /dev/null and b/web/previews/assets/mobile.jpg differ diff --git a/web/previews/assets/real-night.jpg b/web/previews/assets/real-night.jpg new file mode 100644 index 0000000..3d18b8e Binary files /dev/null and b/web/previews/assets/real-night.jpg differ diff --git a/web/previews/assets/real.jpg b/web/previews/assets/real.jpg new file mode 100644 index 0000000..7702381 Binary files /dev/null and b/web/previews/assets/real.jpg differ diff --git a/web/previews/assets/scroll-dark.jpg b/web/previews/assets/scroll-dark.jpg new file mode 100644 index 0000000..c14881a Binary files /dev/null and b/web/previews/assets/scroll-dark.jpg differ diff --git a/web/previews/assets/scroll-light.jpg b/web/previews/assets/scroll-light.jpg new file mode 100644 index 0000000..7d763d0 Binary files /dev/null and b/web/previews/assets/scroll-light.jpg differ diff --git a/web/previews/index.html b/web/previews/index.html new file mode 100644 index 0000000..23a7c53 --- /dev/null +++ b/web/previews/index.html @@ -0,0 +1,6 @@ +ALUX Programming · 中英预览 / Chinese & English Preview
ALUX编程 · Programming
阅读导言 / Introduction ↗

ALUX 编程预览ALUX Programming reader preview

从程序的含义出发,阅读指称设计、组合性与 Rust。
Program meaning, denotational design, composition and Rust.

全书目录Full contents

章节直接进入正文,沿用当前语言与昼夜设置。
Open a chapter directly, keeping the selected language and theme.

白天目录 / Day contents
白天目录Day contents

打开阅读 / Open reader ↗

夜间目录 / Night contents
夜间目录Night contents

打开阅读 / Open reader ↗

翻页阅读Book view

全书连续页码;字号、语言与窗口改变后重新分页。
Continuous page numbers, recalculated for text size, language and window.

白天翻页 / Day book view
白天翻页Day book view

打开阅读 / Open reader ↗

夜间翻页 / Night book view
夜间翻页Night book view

打开阅读 / Open reader ↗

滚动阅读Continuous reading

正文、代码、提示框和插图沿用翻页阅读的尺度。
Text, code, callouts and illustrations share the book-view scale.

白天滚动 / Day scrolling
白天滚动Day scrolling

打开阅读 / Open reader ↗

夜间滚动 / Night scrolling
夜间滚动Night scrolling

打开阅读 / Open reader ↗

现实世界Real World

白天阅读 / Day reading
白天阅读Day reading

打开阅读 / Open reader ↗

夜间阅读 / Night reading
夜间阅读Night reading

打开阅读 / Open reader ↗

分享卡片Share cards

中文1200 × 630
中文分享卡片

先定义程序的含义,再选择执行方式。通过 Rust 示例理解指称设计、组合性、定律与解释器。

进入中文网站 ↗
English1200 × 630
English share card

Define what programs mean before choosing how they run. Denotational design, composition, laws and interpreters, with Rust examples.

Explore the English website ↗

欢迎来到阿拉克斯Welcome to ALUX

森林入口The forest gateway

森林入口 / Forest gateway
查看手机效果 / View the mobile layout手机入口 / Mobile gateway

截图展示对应的昼夜与阅读模式,直达链接沿用浏览器中已保存的设置。
Screenshots show the labeled modes; reader links keep your saved preferences.

分享卡片的实际显示和平台缓存需在上线后核对。
Live social previews and platform caches can be checked after deployment.

\ No newline at end of file diff --git a/web/previews/social.html b/web/previews/social.html new file mode 100644 index 0000000..b577933 --- /dev/null +++ b/web/previews/social.html @@ -0,0 +1,8 @@ +Telegram · X · GitHub — ALUX Programming
ALUX

Telegram

ALUX Programming

X / Twitter

GitHub · README

\ No newline at end of file diff --git a/web/public/alux-black.png b/web/public/alux-black.png new file mode 100644 index 0000000..e5aaf26 Binary files /dev/null and b/web/public/alux-black.png differ diff --git a/web/public/alux-white.png b/web/public/alux-white.png new file mode 100644 index 0000000..76fd619 Binary files /dev/null and b/web/public/alux-white.png differ diff --git a/web/public/apple-touch-icon.png b/web/public/apple-touch-icon.png new file mode 100644 index 0000000..ca95e09 Binary files /dev/null and b/web/public/apple-touch-icon.png differ diff --git a/web/public/art/alux-bronze-night.webp b/web/public/art/alux-bronze-night.webp new file mode 100644 index 0000000..88cfd0d Binary files /dev/null and b/web/public/art/alux-bronze-night.webp differ diff --git a/web/public/art/alux-bronze.webp b/web/public/art/alux-bronze.webp new file mode 100644 index 0000000..5fa72e2 Binary files /dev/null and b/web/public/art/alux-bronze.webp differ diff --git a/web/public/art/book-ribbon.webp b/web/public/art/book-ribbon.webp new file mode 100644 index 0000000..9a26ff2 Binary files /dev/null and b/web/public/art/book-ribbon.webp differ diff --git a/web/public/art/book.webp b/web/public/art/book.webp new file mode 100644 index 0000000..f6bd7b7 Binary files /dev/null and b/web/public/art/book.webp differ diff --git a/web/public/art/capability-crab.webp b/web/public/art/capability-crab.webp new file mode 100644 index 0000000..992a34f Binary files /dev/null and b/web/public/art/capability-crab.webp differ diff --git a/web/public/art/concepts.webp b/web/public/art/concepts.webp new file mode 100644 index 0000000..5ff19be Binary files /dev/null and b/web/public/art/concepts.webp differ diff --git a/web/public/art/forest-gateway.webp b/web/public/art/forest-gateway.webp new file mode 100644 index 0000000..9b838ec Binary files /dev/null and b/web/public/art/forest-gateway.webp differ diff --git a/web/public/art/insights.webp b/web/public/art/insights.webp new file mode 100644 index 0000000..c5a236e Binary files /dev/null and b/web/public/art/insights.webp differ diff --git a/web/public/art/ivory-paper.webp b/web/public/art/ivory-paper.webp new file mode 100644 index 0000000..e985217 Binary files /dev/null and b/web/public/art/ivory-paper.webp differ diff --git a/web/public/art/paper.webp b/web/public/art/paper.webp new file mode 100644 index 0000000..6b397a4 Binary files /dev/null and b/web/public/art/paper.webp differ diff --git a/web/public/art/semantic-view.webp b/web/public/art/semantic-view.webp new file mode 100644 index 0000000..839d8b4 Binary files /dev/null and b/web/public/art/semantic-view.webp differ diff --git a/web/public/art/wizard-standing.webp b/web/public/art/wizard-standing.webp new file mode 100644 index 0000000..8678aa1 Binary files /dev/null and b/web/public/art/wizard-standing.webp differ diff --git a/web/public/art/world-0.webp b/web/public/art/world-0.webp new file mode 100644 index 0000000..6daeadd Binary files /dev/null and b/web/public/art/world-0.webp differ diff --git a/web/public/art/world-1.webp b/web/public/art/world-1.webp new file mode 100644 index 0000000..c0f664f Binary files /dev/null and b/web/public/art/world-1.webp differ diff --git a/web/public/art/world-2.webp b/web/public/art/world-2.webp new file mode 100644 index 0000000..3d0b327 Binary files /dev/null and b/web/public/art/world-2.webp differ diff --git a/web/public/art/world-3.webp b/web/public/art/world-3.webp new file mode 100644 index 0000000..c6aea43 Binary files /dev/null and b/web/public/art/world-3.webp differ diff --git a/web/public/art/world-wizard.webp b/web/public/art/world-wizard.webp new file mode 100644 index 0000000..958b3a3 Binary files /dev/null and b/web/public/art/world-wizard.webp differ diff --git a/web/public/art/worlds.webp b/web/public/art/worlds.webp new file mode 100644 index 0000000..848e4c1 Binary files /dev/null and b/web/public/art/worlds.webp differ diff --git a/web/public/audio/forest-breath.mp3 b/web/public/audio/forest-breath.mp3 new file mode 100644 index 0000000..4cd704b Binary files /dev/null and b/web/public/audio/forest-breath.mp3 differ diff --git a/web/public/audio/welcome/ar.mp3 b/web/public/audio/welcome/ar.mp3 new file mode 100644 index 0000000..2ad6227 Binary files /dev/null and b/web/public/audio/welcome/ar.mp3 differ diff --git a/web/public/audio/welcome/de.mp3 b/web/public/audio/welcome/de.mp3 new file mode 100644 index 0000000..3202b90 Binary files /dev/null and b/web/public/audio/welcome/de.mp3 differ diff --git a/web/public/audio/welcome/en.mp3 b/web/public/audio/welcome/en.mp3 new file mode 100644 index 0000000..25a632f Binary files /dev/null and b/web/public/audio/welcome/en.mp3 differ diff --git a/web/public/audio/welcome/es.mp3 b/web/public/audio/welcome/es.mp3 new file mode 100644 index 0000000..194ab94 Binary files /dev/null and b/web/public/audio/welcome/es.mp3 differ diff --git a/web/public/audio/welcome/ja.mp3 b/web/public/audio/welcome/ja.mp3 new file mode 100644 index 0000000..4714965 Binary files /dev/null and b/web/public/audio/welcome/ja.mp3 differ diff --git a/web/public/audio/welcome/ko.mp3 b/web/public/audio/welcome/ko.mp3 new file mode 100644 index 0000000..56d92d9 Binary files /dev/null and b/web/public/audio/welcome/ko.mp3 differ diff --git a/web/public/audio/welcome/manifest.json b/web/public/audio/welcome/manifest.json new file mode 100644 index 0000000..c85bdbb --- /dev/null +++ b/web/public/audio/welcome/manifest.json @@ -0,0 +1,131 @@ +{ + "purpose": "ALUX Programming gateway welcome narration; no background music", + "target_loudness_lufs": -16, + "true_peak_max_dbtp": -2, + "assets": [ + { + "language": "en", + "text": "Welcome to ALUX Programming. Define meaning first, then create a world. Choose your path, and let's begin.", + "engine": "qwen_custom_voice_1.7B_uncle_fu", + "duration_seconds": 7.76, + "integrated_loudness_lufs": -17.1, + "true_peak_dbtp": -2.2, + "sourcefile": "en.wav", + "mp3": "audio/welcome/en.mp3", + "full_decode": "passed" + }, + { + "language": "zh", + "text": "欢迎来到阿拉克斯编程。先定义意义,再创造世界。选择你的道路,我们从这里开始。", + "engine": "accepted_qwen3_uncle_fu_wav_reused", + "duration_seconds": 10.48, + "integrated_loudness_lufs": -16.6, + "true_peak_dbtp": -2.2, + "sourcefile": "zh.wav", + "mp3": "audio/welcome/zh.mp3", + "full_decode": "passed" + }, + { + "language": "zh-hant", + "text": "歡迎來到阿拉克斯編程。先定義意義,再創造世界。選擇你的道路,我們從這裡開始。", + "engine": "accepted_qwen3_uncle_fu_wav_reused", + "duration_seconds": 10.48, + "integrated_loudness_lufs": -16.6, + "true_peak_dbtp": -2.2, + "sourcefile": "zh-hant.wav", + "mp3": "audio/welcome/zh-hant.mp3", + "full_decode": "passed" + }, + { + "language": "ja", + "text": "ALUX Programmingへようこそ。まず意味を定め、世界を創りましょう。あなたの道を選んで、ここから始めましょう。", + "engine": "qwen_custom_voice_1.7B_uncle_fu", + "duration_seconds": 8.64, + "integrated_loudness_lufs": -16.9, + "true_peak_dbtp": -2.2, + "sourcefile": "ja.wav", + "mp3": "audio/welcome/ja.mp3", + "full_decode": "passed", + "spoken_text": "アラクス・プログラミングへようこそ。まず意味を定め、世界を創りましょう。あなたの道を選んで、ここから始めましょう。" + }, + { + "language": "ko", + "text": "ALUX Programming에 오신 것을 환영합니다. 먼저 의미를 정하고, 그다음 세계를 만들어 보세요. 원하는 길을 고르고, 함께 시작해 봅시다.", + "engine": "qwen_custom_voice_1.7B_uncle_fu", + "duration_seconds": 12.48, + "integrated_loudness_lufs": -16.5, + "true_peak_dbtp": -2.2, + "sourcefile": "ko.wav", + "mp3": "audio/welcome/ko.mp3", + "full_decode": "passed", + "spoken_text": "아라크스 프로그래밍에 오신 것을 환영합니다. 먼저 의미를 정하고, 그다음 세계를 만들어 보세요. 원하는 길을 고르고, 함께 시작해 봅시다." + }, + { + "language": "vi", + "text": "Chào mừng bạn đến với ALUX Programming. Hãy xác định ý nghĩa trước, rồi kiến tạo một thế giới. Chọn con đường của bạn, và chúng ta bắt đầu.", + "engine": "omnivoice_local_clone_from_accepted_uncle_fu_sample", + "duration_seconds": 11.62, + "integrated_loudness_lufs": -17.1, + "true_peak_dbtp": -2.3, + "sourcefile": "vi.wav", + "mp3": "audio/welcome/vi.mp3", + "full_decode": "passed" + }, + { + "language": "de", + "text": "Willkommen bei ALUX Programming. Definiere zuerst die Bedeutung, dann erschaffe eine Welt. Wähle deinen Weg, und wir beginnen.", + "engine": "qwen_custom_voice_1.7B_uncle_fu", + "duration_seconds": 9.36, + "integrated_loudness_lufs": -17.1, + "true_peak_dbtp": -2.2, + "sourcefile": "de.wav", + "mp3": "audio/welcome/de.mp3", + "full_decode": "passed" + }, + { + "language": "es", + "text": "Te damos la bienvenida a ALUX Programming. Primero define el significado y luego crea un mundo. Elige tu camino. Empecemos.", + "engine": "qwen_custom_voice_1.7B_uncle_fu", + "duration_seconds": 10.24, + "integrated_loudness_lufs": -16.7, + "true_peak_dbtp": -2.3, + "sourcefile": "es.wav", + "mp3": "audio/welcome/es.mp3", + "full_decode": "passed" + }, + { + "language": "ru", + "text": "Добро пожаловать в ALUX Programming. Сначала определите смысл, затем создайте мир. Выберите свой путь — и начнём.", + "engine": "qwen_custom_voice_1.7B_uncle_fu", + "duration_seconds": 9.92, + "integrated_loudness_lufs": -16.3, + "true_peak_dbtp": -2.3, + "sourcefile": "ru.wav", + "mp3": "audio/welcome/ru.mp3", + "full_decode": "passed", + "spoken_text": "Добро пожаловать в Алакс Программинг. Сначала определите смысл, затем создайте мир. Выберите свой путь — и начнём." + }, + { + "language": "uk", + "text": "Ласкаво просимо до ALUX Programming. Спершу визначте значення, а потім створіть світ. Оберіть свій шлях — і почнімо.", + "engine": "omnivoice_local_clone_from_accepted_uncle_fu_sample", + "duration_seconds": 10.24, + "integrated_loudness_lufs": -16.5, + "true_peak_dbtp": -2.2, + "sourcefile": "uk.wav", + "mp3": "audio/welcome/uk.mp3", + "full_decode": "passed" + }, + { + "language": "ar", + "text": "مرحبا بك في ALUX Programming. حدّد المعنى أولا، ثم ابتكر عالما. اختر طريقك، ولنبدأ من هنا.", + "engine": "omnivoice_local_clone_from_accepted_uncle_fu_sample", + "duration_seconds": 10.44, + "integrated_loudness_lufs": -17.0, + "true_peak_dbtp": -2.3, + "sourcefile": "ar.wav", + "mp3": "audio/welcome/ar.mp3", + "full_decode": "passed" + } + ] +} diff --git a/web/public/audio/welcome/ru.mp3 b/web/public/audio/welcome/ru.mp3 new file mode 100644 index 0000000..d56dd5f Binary files /dev/null and b/web/public/audio/welcome/ru.mp3 differ diff --git a/web/public/audio/welcome/uk.mp3 b/web/public/audio/welcome/uk.mp3 new file mode 100644 index 0000000..8ce6e8a Binary files /dev/null and b/web/public/audio/welcome/uk.mp3 differ diff --git a/web/public/audio/welcome/vi.mp3 b/web/public/audio/welcome/vi.mp3 new file mode 100644 index 0000000..99b3cca Binary files /dev/null and b/web/public/audio/welcome/vi.mp3 differ diff --git a/web/public/audio/welcome/zh-hant.mp3 b/web/public/audio/welcome/zh-hant.mp3 new file mode 100644 index 0000000..b89c08a Binary files /dev/null and b/web/public/audio/welcome/zh-hant.mp3 differ diff --git a/web/public/audio/welcome/zh.mp3 b/web/public/audio/welcome/zh.mp3 new file mode 100644 index 0000000..b89c08a Binary files /dev/null and b/web/public/audio/welcome/zh.mp3 differ diff --git a/web/public/favicon-32.png b/web/public/favicon-32.png new file mode 100644 index 0000000..da678a0 Binary files /dev/null and b/web/public/favicon-32.png differ diff --git a/web/public/favicon.ico b/web/public/favicon.ico new file mode 100644 index 0000000..b89cdb5 Binary files /dev/null and b/web/public/favicon.ico differ diff --git a/web/public/favicon.svg b/web/public/favicon.svg new file mode 100644 index 0000000..2a3ab39 --- /dev/null +++ b/web/public/favicon.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/web/public/fonts/Cormorant-Garamond-OFL.txt b/web/public/fonts/Cormorant-Garamond-OFL.txt new file mode 100644 index 0000000..ddb0b85 --- /dev/null +++ b/web/public/fonts/Cormorant-Garamond-OFL.txt @@ -0,0 +1,93 @@ +Copyright 2015 The Cormorant Project Authors (github.com/CatharsisFonts/Cormorant) CormorantGaramond-Italic[wght].ttf: Copyright 2015 The Cormorant Project Authors (github.com/CatharsisFonts/Cormorant) + +This Font Software is licensed under the SIL Open Font License, Version 1.1. +This license is copied below, and is also available with a FAQ at: +http://scripts.sil.org/OFL + + +----------------------------------------------------------- +SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007 +----------------------------------------------------------- + +PREAMBLE +The goals of the Open Font License (OFL) are to stimulate worldwide +development of collaborative font projects, to support the font creation +efforts of academic and linguistic communities, and to provide a free and +open framework in which fonts may be shared and improved in partnership +with others. + +The OFL allows the licensed fonts to be used, studied, modified and +redistributed freely as long as they are not sold by themselves. The +fonts, including any derivative works, can be bundled, embedded, +redistributed and/or sold with any software provided that any reserved +names are not used by derivative works. The fonts and derivatives, +however, cannot be released under any other type of license. The +requirement for fonts to remain under this license does not apply +to any document created using the fonts or their derivatives. + +DEFINITIONS +"Font Software" refers to the set of files released by the Copyright +Holder(s) under this license and clearly marked as such. This may +include source files, build scripts and documentation. + +"Reserved Font Name" refers to any names specified as such after the +copyright statement(s). + +"Original Version" refers to the collection of Font Software components as +distributed by the Copyright Holder(s). + +"Modified Version" refers to any derivative made by adding to, deleting, +or substituting -- in part or in whole -- any of the components of the +Original Version, by changing formats or by porting the Font Software to a +new environment. + +"Author" refers to any designer, engineer, programmer, technical +writer or other person who contributed to the Font Software. + +PERMISSION & CONDITIONS +Permission is hereby granted, free of charge, to any person obtaining +a copy of the Font Software, to use, study, copy, merge, embed, modify, +redistribute, and sell modified and unmodified copies of the Font +Software, subject to the following conditions: + +1) Neither the Font Software nor any of its individual components, +in Original or Modified Versions, may be sold by itself. + +2) Original or Modified Versions of the Font Software may be bundled, +redistributed and/or sold with any software, provided that each copy +contains the above copyright notice and this license. These can be +included either as stand-alone text files, human-readable headers or +in the appropriate machine-readable metadata fields within text or +binary files as long as those fields can be easily viewed by the user. + +3) No Modified Version of the Font Software may use the Reserved Font +Name(s) unless explicit written permission is granted by the corresponding +Copyright Holder. This restriction only applies to the primary font name as +presented to the users. + +4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font +Software shall not be used to promote, endorse or advertise any +Modified Version, except to acknowledge the contribution(s) of the +Copyright Holder(s) and the Author(s) or with their explicit written +permission. + +5) The Font Software, modified or unmodified, in part or in whole, +must be distributed entirely under this license, and must not be +distributed under any other license. The requirement for fonts to +remain under this license does not apply to any document created +using the Font Software. + +TERMINATION +This license becomes null and void if any of the above conditions are +not met. + +DISCLAIMER +THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, +EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF +MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT +OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE +COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, +INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL +DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING +FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM +OTHER DEALINGS IN THE FONT SOFTWARE. diff --git a/web/public/fonts/IBM-Plex-Mono-OFL.txt b/web/public/fonts/IBM-Plex-Mono-OFL.txt new file mode 100644 index 0000000..670c6c0 --- /dev/null +++ b/web/public/fonts/IBM-Plex-Mono-OFL.txt @@ -0,0 +1,93 @@ +Copyright © 2017 IBM Corp. with Reserved Font Name "Plex" + +This Font Software is licensed under the SIL Open Font License, Version 1.1. + +This license is copied below, and is also available with a FAQ at: http://scripts.sil.org/OFL + + +----------------------------------------------------------- +SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007 +----------------------------------------------------------- + +PREAMBLE +The goals of the Open Font License (OFL) are to stimulate worldwide +development of collaborative font projects, to support the font creation +efforts of academic and linguistic communities, and to provide a free and +open framework in which fonts may be shared and improved in partnership +with others. + +The OFL allows the licensed fonts to be used, studied, modified and +redistributed freely as long as they are not sold by themselves. The +fonts, including any derivative works, can be bundled, embedded, +redistributed and/or sold with any software provided that any reserved +names are not used by derivative works. The fonts and derivatives, +however, cannot be released under any other type of license. The +requirement for fonts to remain under this license does not apply +to any document created using the fonts or their derivatives. + +DEFINITIONS +"Font Software" refers to the set of files released by the Copyright +Holder(s) under this license and clearly marked as such. This may +include source files, build scripts and documentation. + +"Reserved Font Name" refers to any names specified as such after the +copyright statement(s). + +"Original Version" refers to the collection of Font Software components as +distributed by the Copyright Holder(s). + +"Modified Version" refers to any derivative made by adding to, deleting, +or substituting -- in part or in whole -- any of the components of the +Original Version, by changing formats or by porting the Font Software to a +new environment. + +"Author" refers to any designer, engineer, programmer, technical +writer or other person who contributed to the Font Software. + +PERMISSION & CONDITIONS +Permission is hereby granted, free of charge, to any person obtaining +a copy of the Font Software, to use, study, copy, merge, embed, modify, +redistribute, and sell modified and unmodified copies of the Font +Software, subject to the following conditions: + +1) Neither the Font Software nor any of its individual components, +in Original or Modified Versions, may be sold by itself. + +2) Original or Modified Versions of the Font Software may be bundled, +redistributed and/or sold with any software, provided that each copy +contains the above copyright notice and this license. These can be +included either as stand-alone text files, human-readable headers or +in the appropriate machine-readable metadata fields within text or +binary files as long as those fields can be easily viewed by the user. + +3) No Modified Version of the Font Software may use the Reserved Font +Name(s) unless explicit written permission is granted by the corresponding +Copyright Holder. This restriction only applies to the primary font name as +presented to the users. + +4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font +Software shall not be used to promote, endorse or advertise any +Modified Version, except to acknowledge the contribution(s) of the +Copyright Holder(s) and the Author(s) or with their explicit written +permission. + +5) The Font Software, modified or unmodified, in part or in whole, +must be distributed entirely under this license, and must not be +distributed under any other license. The requirement for fonts to +remain under this license does not apply to any document created +using the Font Software. + +TERMINATION +This license becomes null and void if any of the above conditions are +not met. + +DISCLAIMER +THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, +EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF +MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT +OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE +COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, +INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL +DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING +FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM +OTHER DEALINGS IN THE FONT SOFTWARE. diff --git a/web/public/fonts/Inter-OFL.txt b/web/public/fonts/Inter-OFL.txt new file mode 100644 index 0000000..909a6bf --- /dev/null +++ b/web/public/fonts/Inter-OFL.txt @@ -0,0 +1,93 @@ +Copyright 2020 The Inter Project Authors (https://github.com/rsms/inter) + +This Font Software is licensed under the SIL Open Font License, Version 1.1. +This license is copied below, and is also available with a FAQ at: +https://scripts.sil.org/OFL + + +----------------------------------------------------------- +SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007 +----------------------------------------------------------- + +PREAMBLE +The goals of the Open Font License (OFL) are to stimulate worldwide +development of collaborative font projects, to support the font creation +efforts of academic and linguistic communities, and to provide a free and +open framework in which fonts may be shared and improved in partnership +with others. + +The OFL allows the licensed fonts to be used, studied, modified and +redistributed freely as long as they are not sold by themselves. The +fonts, including any derivative works, can be bundled, embedded, +redistributed and/or sold with any software provided that any reserved +names are not used by derivative works. The fonts and derivatives, +however, cannot be released under any other type of license. The +requirement for fonts to remain under this license does not apply +to any document created using the fonts or their derivatives. + +DEFINITIONS +"Font Software" refers to the set of files released by the Copyright +Holder(s) under this license and clearly marked as such. This may +include source files, build scripts and documentation. + +"Reserved Font Name" refers to any names specified as such after the +copyright statement(s). + +"Original Version" refers to the collection of Font Software components as +distributed by the Copyright Holder(s). + +"Modified Version" refers to any derivative made by adding to, deleting, +or substituting -- in part or in whole -- any of the components of the +Original Version, by changing formats or by porting the Font Software to a +new environment. + +"Author" refers to any designer, engineer, programmer, technical +writer or other person who contributed to the Font Software. + +PERMISSION & CONDITIONS +Permission is hereby granted, free of charge, to any person obtaining +a copy of the Font Software, to use, study, copy, merge, embed, modify, +redistribute, and sell modified and unmodified copies of the Font +Software, subject to the following conditions: + +1) Neither the Font Software nor any of its individual components, +in Original or Modified Versions, may be sold by itself. + +2) Original or Modified Versions of the Font Software may be bundled, +redistributed and/or sold with any software, provided that each copy +contains the above copyright notice and this license. These can be +included either as stand-alone text files, human-readable headers or +in the appropriate machine-readable metadata fields within text or +binary files as long as those fields can be easily viewed by the user. + +3) No Modified Version of the Font Software may use the Reserved Font +Name(s) unless explicit written permission is granted by the corresponding +Copyright Holder. This restriction only applies to the primary font name as +presented to the users. + +4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font +Software shall not be used to promote, endorse or advertise any +Modified Version, except to acknowledge the contribution(s) of the +Copyright Holder(s) and the Author(s) or with their explicit written +permission. + +5) The Font Software, modified or unmodified, in part or in whole, +must be distributed entirely under this license, and must not be +distributed under any other license. The requirement for fonts to +remain under this license does not apply to any document created +using the Font Software. + +TERMINATION +This license becomes null and void if any of the above conditions are +not met. + +DISCLAIMER +THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, +EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF +MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT +OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE +COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, +INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL +DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING +FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM +OTHER DEALINGS IN THE FONT SOFTWARE. diff --git a/web/public/fonts/ibm-plex-mono.woff2 b/web/public/fonts/ibm-plex-mono.woff2 new file mode 100644 index 0000000..0804aaf Binary files /dev/null and b/web/public/fonts/ibm-plex-mono.woff2 differ diff --git a/web/public/fonts/inter.woff2 b/web/public/fonts/inter.woff2 new file mode 100644 index 0000000..d15208d Binary files /dev/null and b/web/public/fonts/inter.woff2 differ diff --git a/web/public/social/alux-programming-ar.jpg b/web/public/social/alux-programming-ar.jpg new file mode 100644 index 0000000..8f36628 Binary files /dev/null and b/web/public/social/alux-programming-ar.jpg differ diff --git a/web/public/social/alux-programming-de.jpg b/web/public/social/alux-programming-de.jpg new file mode 100644 index 0000000..f466823 Binary files /dev/null and b/web/public/social/alux-programming-de.jpg differ diff --git a/web/public/social/alux-programming-en.jpg b/web/public/social/alux-programming-en.jpg new file mode 100644 index 0000000..c4076cc Binary files /dev/null and b/web/public/social/alux-programming-en.jpg differ diff --git a/web/public/social/alux-programming-es.jpg b/web/public/social/alux-programming-es.jpg new file mode 100644 index 0000000..0145c55 Binary files /dev/null and b/web/public/social/alux-programming-es.jpg differ diff --git a/web/public/social/alux-programming-ja.jpg b/web/public/social/alux-programming-ja.jpg new file mode 100644 index 0000000..0ecbd6e Binary files /dev/null and b/web/public/social/alux-programming-ja.jpg differ diff --git a/web/public/social/alux-programming-ko.jpg b/web/public/social/alux-programming-ko.jpg new file mode 100644 index 0000000..93836b1 Binary files /dev/null and b/web/public/social/alux-programming-ko.jpg differ diff --git a/web/public/social/alux-programming-ru.jpg b/web/public/social/alux-programming-ru.jpg new file mode 100644 index 0000000..8aea228 Binary files /dev/null and b/web/public/social/alux-programming-ru.jpg differ diff --git a/web/public/social/alux-programming-uk.jpg b/web/public/social/alux-programming-uk.jpg new file mode 100644 index 0000000..2cb3e8b Binary files /dev/null and b/web/public/social/alux-programming-uk.jpg differ diff --git a/web/public/social/alux-programming-vi.jpg b/web/public/social/alux-programming-vi.jpg new file mode 100644 index 0000000..e260e69 Binary files /dev/null and b/web/public/social/alux-programming-vi.jpg differ diff --git a/web/public/social/alux-programming-zh-hant.jpg b/web/public/social/alux-programming-zh-hant.jpg new file mode 100644 index 0000000..f362a4c Binary files /dev/null and b/web/public/social/alux-programming-zh-hant.jpg differ diff --git a/web/public/social/alux-programming-zh.jpg b/web/public/social/alux-programming-zh.jpg new file mode 100644 index 0000000..40dc697 Binary files /dev/null and b/web/public/social/alux-programming-zh.jpg differ diff --git a/web/reader-dialogs.css b/web/reader-dialogs.css new file mode 100644 index 0000000..73920be --- /dev/null +++ b/web/reader-dialogs.css @@ -0,0 +1,64 @@ +/* Search is a readable chapter list, with independent light/dark semantic colors. */ +#search-dialog{ + --search-bg:#f5efe2;--search-fg:#3b3f32;--search-muted:#686b5c;--search-line:#c9beaa;--search-accent:#835b30;--search-hover:#e9e0d0; + width:min(900px,calc(100vw - 48px));max-width:calc(100vw - 24px);max-height:86dvh;margin:auto;inset:0;grid-template-columns:minmax(0,1fr); + padding:0;border:1px solid var(--search-line);border-radius:9px; + background:var(--search-bg);color:var(--search-fg);box-shadow:0 24px 80px #0004; + font-family:var(--sans);overflow:hidden; +} +#search-dialog[open]{display:grid;grid-template-rows:auto minmax(0,1fr) auto} +#search-dialog::backdrop{background:#070b0dcc;backdrop-filter:blur(4px)} +body.reality-view #search-dialog{--search-bg:var(--real-bg);--search-fg:var(--real-fg);--search-muted:var(--real-muted);--search-line:var(--real-line);--search-accent:var(--real-link);--search-hover:var(--real-code);background:var(--search-bg);color:var(--search-fg)} +body.night #search-dialog{--search-bg:#202a23;--search-fg:#deded0;--search-muted:#b2b9ac;--search-line:#53614e;--search-accent:#d8c18d;--search-hover:#303b31} +body.real-theme-coal #search-dialog{--search-bg:#202020;--search-fg:#dedede;--search-muted:#b5b5b5;--search-line:#454545;--search-accent:#b4cde2;--search-hover:#2b2b2b} +body.real-theme-light #search-dialog{--search-bg:#f2f1ed;--search-fg:#343434;--search-muted:#656565;--search-line:#c8c8c4;--search-accent:#4c697c;--search-hover:#e6e6e2} +#search-dialog .search-top{min-width:0;padding:20px 24px;gap:16px;border-color:var(--search-line)} +#search-dialog .search-top>svg{width:26px;height:26px;color:var(--search-muted);flex-shrink:0} +#search-dialog #search-input{min-width:0;font:24px/1.5 var(--sans);padding:8px 0;color:var(--search-fg)} +#search-dialog #search-input::placeholder{font:inherit;color:var(--search-muted);opacity:1} +#search-dialog .search-top button{width:48px;min-width:48px;height:48px;color:var(--search-fg)} +#search-dialog .search-top button svg{width:25px;height:25px} +#search-dialog #search-results{padding:16px 24px 24px;max-height:none;min-height:0;overflow:auto;overscroll-behavior:contain} +#search-dialog .search-hint{display:grid;align-content:center;min-height:120px;text-align:center;font:20px/1.65 var(--sans);color:var(--search-muted);padding:16px 0;margin:0} +#search-dialog .search-group-label{font:500 20px/1.5 var(--sans);letter-spacing:.025em;color:var(--search-muted);padding:14px 0 8px} +#search-dialog .search-result{padding:18px 0;gap:22px;border:0;border-bottom:1px solid var(--search-line);border-radius:0;color:var(--search-fg);text-decoration:none} +#search-dialog .search-result:last-child{border-bottom:0} +#search-dialog .search-result>span{min-width:0} +#search-dialog .search-result small{font:18px/1.5 var(--sans);color:var(--search-muted);margin-bottom:8px} +#search-dialog .search-result strong{font:500 28px/1.4 var(--sans);color:var(--search-fg);overflow-wrap:break-word} +#search-dialog .search-result p{display:-webkit-box;-webkit-line-clamp:2;-webkit-box-orient:vertical;overflow:hidden;font:20px/1.65 var(--sans);color:var(--search-muted);margin:9px 0 0} +#search-dialog .search-result svg{width:25px;height:25px;flex-shrink:0;color:var(--search-accent)} +#search-dialog .search-result:hover,#search-dialog .search-result:focus-visible{background:var(--search-hover);outline:0} +#search-dialog .search-result:focus-visible{box-shadow:inset 3px 0 var(--search-accent);padding-inline-start:14px} +#search-dialog .search-footer{font:18px/1.5 var(--sans);color:var(--search-muted);border-color:var(--search-line);padding:15px 24px;gap:10px;flex-wrap:wrap} +#search-dialog .search-footer kbd{font:14px/1.5 var(--sans);padding:3px 8px;color:var(--search-fg);border:1px solid var(--search-line)} +#search-dialog .no-results h3{font:600 25px/1.4 var(--sans);color:var(--search-fg)} +#search-dialog .no-results p{font:18px/1.65 var(--sans);color:var(--search-muted)} +#bookmarks-dialog .saved-chapter small{font-size:16px;line-height:1.5} +#bookmarks-dialog .saved-chapter a>span{font-size:18px} +body.bound-reading #search-dialog{font-family:var(--serif)} +body.bound-reading #search-dialog :is(#search-input,.search-hint,.search-group-label,.search-result small,.search-result strong,.search-result p,.search-footer){font-family:var(--serif)} +html[lang|=zh] body.bound-reading #search-dialog,html[lang=ja] body.bound-reading #search-dialog{--search-font:'Noto Serif SC','Songti SC','SimSun',serif} +html[lang|=zh] body.bound-reading #search-dialog :is(#search-input,.search-hint,.search-group-label,.search-result small,.search-result strong,.search-result p,.search-footer),html[lang=ja] body.bound-reading #search-dialog :is(#search-input,.search-hint,.search-group-label,.search-result small,.search-result strong,.search-result p,.search-footer){font-family:var(--search-font)} +html[dir=rtl] #search-dialog{text-align:right}html[dir=rtl] #search-dialog .search-result svg{transform:scaleX(-1)} +@media(max-width:760px){ + #search-dialog{width:calc(100vw - 24px);margin:auto;max-height:92dvh;border-radius:6px} + #search-dialog .search-top{padding:12px 14px;gap:10px} + #search-dialog #search-input{font-size:22px} + #search-dialog .search-top>svg{width:23px;height:23px} + #search-dialog .search-top button{width:44px;min-width:44px;height:44px} + #search-dialog #search-results{padding:14px 18px 20px} + #search-dialog .search-result{padding:16px 0;gap:12px} + #search-dialog .search-result strong{font-size:25px} + #search-dialog .search-result small{font-size:17px} + #search-dialog .search-group-label{font-size:18px} + #search-dialog .search-result p,#search-dialog .search-hint{font-size:19px} + #search-dialog .search-footer{font-size:17px;padding:12px 18px;justify-content:flex-start} +} + +/* Chapter names keep the book's editorial type, while input and helper copy stay quiet. */ +#search-dialog .search-group-label{text-transform:none;font-weight:400;letter-spacing:0} +#search-dialog .search-result strong{font-family:var(--serif,Georgia,serif);font-size:32px;line-height:1.25;font-weight:600;letter-spacing:0} +html[lang|=zh] #search-dialog .search-result strong,html[lang=ja] #search-dialog .search-result strong{font-family:'Noto Serif SC','Songti SC','SimSun',serif;font-size:27px;font-weight:400;line-height:1.5} +#search-dialog .search-result small{font-weight:400} +@media(max-width:760px){#search-dialog .search-result strong{font-size:29px}html[lang|=zh] #search-dialog .search-result strong,html[lang=ja] #search-dialog .search-result strong{font-size:25px}} diff --git a/web/reader-materials.css b/web/reader-materials.css new file mode 100644 index 0000000..6b50bad --- /dev/null +++ b/web/reader-materials.css @@ -0,0 +1,47 @@ +/* Quiet vellum and aged metal: decorative light stays below reading contrast. */ +.bound-reading:not(.night) :is(.folio-content,.continuous-prose) .code-block{background:#e8e0cf;border-color:#b3a68d;color:#374337} +.bound-reading:not(.night) :is(.folio-content,.continuous-prose) .code-toolbar{color:#6f583b;border-color:#b3a68d66} +.bound-reading:not(.night) :is(.folio-content,.continuous-prose) .copy-code{color:#505c4b} +.bound-reading:not(.night) :is(.folio-content,.continuous-prose) .code-toolbar .rust-playground{color:#76512d!important} +.bound-reading:not(.night) :is(.folio-content,.continuous-prose) .copy-code:hover{color:#71421d!important} +.bound-reading:not(.night) :is(.folio-content,.continuous-prose) .code-block pre{scrollbar-color:#969a84 #d6cdbb} +.bound-reading:not(.night) :is(.folio-content,.continuous-prose) :is(.hljs-keyword,.hljs-selector-tag,.hljs-literal){color:#85451c} +.bound-reading:not(.night) :is(.folio-content,.continuous-prose) :is(.hljs-string,.hljs-regexp){color:#435e34} +.bound-reading:not(.night) :is(.folio-content,.continuous-prose) :is(.hljs-title,.hljs-type,.hljs-built_in){color:#2e5d61} +.bound-reading:not(.night) :is(.folio-content,.continuous-prose) .hljs-comment{color:#5e634f} +.bound-reading:not(.night) :is(.folio-content,.continuous-prose) :is(.hljs-number,.hljs-meta){color:#705229} +.bound-reading:not(.night) :is(.folio-content,.continuous-prose) .hljs-params{color:#374337} +.bound-reading .folio-page{background-color:#f1e8d4;background-image:linear-gradient(#f2eadc99,#f2eadc99),url('/art/ivory-paper.webp');background-size:626px 626px} +.bound-reading.continuous-reading .bound-volume{background-color:#f1e8d4;background-image:linear-gradient(#f2eadcbb,#f2eadcbb),url('/art/ivory-paper.webp');background-size:626px 626px} +body.bound-reading.night{--copper:#b9a172;--text:#bdc1b6;--ink:#c7c9bc;--muted:#a0aa9b;--line:#8b816047} +body.bound-reading.night .bound-reader{background:#18211c} +body.bound-reading.night .bound-toolbar{background:#18211c} +body.bound-reading.night .folio-page,body.bound-reading.night.continuous-reading .bound-volume{background:#202820;color:#bdc1b6} +body.bound-reading.night .folio-page:nth-child(odd){box-shadow:inset -19px 0 27px -23px #080d0a;border-right:1px solid #60604755} +body.bound-reading.night .folio-page:nth-child(even){box-shadow:inset 19px 0 27px -23px #080d0a} +body.bound-reading.night .folio-page :is(h1,h2,h3,h4){color:#c7c9bc} +body.bound-reading.night .folio-page .admonition{background:#b3b59a09;border-color:#8c8b6740} +body.bound-reading.night .continuous-prose{color:#bdc1b6} +body.bound-reading.night .bound-volume{border-color:#81734e;background:#28372b;box-shadow:0 0 0 1px #5e583e,inset 0 0 0 5px #1c2a20,inset 0 0 0 6px #7b704c,0 5px 0 -2px #77715a,0 7px 0 -3px #444a39,0 16px 28px #0003} +body.bound-reading.night .bound-volume:before,body.bound-reading.night .bound-volume:after{border-color:#8b7c50;background:transparent;filter:none} +body.bound-reading.night .crafted-brand .brand-seal-night{filter:saturate(.85) brightness(.88) contrast(1.02)} +body.bound-reading.night .crafted-brand :is(.brand-name,.brand-subtitle){color:#c9b486!important} +.bound-reading .bound-toolbar{position:relative;top:auto;backdrop-filter:none} +.bound-reading .folio-content h1{font-size:54px;line-height:1.12} +html[lang|=zh] .bound-reading .folio-content h1,html[lang=ja] .bound-reading .folio-content h1,html[lang=ko] .bound-reading .folio-content h1{font-size:44px;line-height:1.3;word-break:keep-all;overflow-wrap:break-word} +.bound-reading .admonition-continuation{margin-top:0} +.bound-reading .continuous-prose{max-width:78ch} +.bound-reading .folio-running-head{font-size:18px;color:#7e6c4e;letter-spacing:.03em} +.bound-reading .folio-running-head>span:last-child{font-size:16px} +.bound-reading .folio-footer{font-size:17px;color:#806c4a} +.bound-reading.night :is(.folio-running-head,.folio-footer){color:#a99c7c} +#announcement{font:500 19px/1.5 var(--sans);max-width:min(420px,calc(100vw - 24px));padding:12px 18px;border:1px solid #a595754d;border-radius:7px;background:#f3ead8;color:#494636;box-shadow:0 6px 20px #25211320;transition:opacity .16s;z-index:150} +#announcement.anchored{bottom:auto;right:auto;transform:none;margin:0;position:fixed} +body.night #announcement{background:#303a2d;color:#e0ddce;border-color:#8f957766;box-shadow:0 6px 20px #0004} +body.reality-view #announcement{background:#f1f0ed;color:#333;border-color:#bcbcbc} +body.real-theme-coal #announcement{background:#303030;color:#e1e1e1;border-color:#656565} +@media(max-width:760px){.bound-reading .folio-running-head{font-size:15px}.bound-reading .folio-running-head>span:last-child{font-size:14px}.bound-reading .folio-footer{font-size:15px}#announcement{font-size:18px}} + +/* A lifted night leaf catches a little light, while the resting spread stays dim. */ +body.bound-reading.night .paper-turning .folio-page.--soft:not(.--simple){background:linear-gradient(105deg,#344134 0%,#2a362b 22%,#202820 66%,#111a14 100%);box-shadow:inset 2px 0 0 #aaa07b70,inset -2px 0 0 #070c09b3,0 8px 24px #0008} +body.bound-reading.night .paper-turning :is(.stf__innerShadow,.stf__outerShadow){filter:contrast(1.15)} diff --git a/web/reader-music.css b/web/reader-music.css new file mode 100644 index 0000000..b2942fc --- /dev/null +++ b/web/reader-music.css @@ -0,0 +1,24 @@ + +.reader-music-dock{position:relative;display:flex;flex-shrink:0;z-index:40} +.reader-music-dock[hidden],.reader-music-popover[hidden]{display:none} +.reader-music-button{display:grid;place-items:center;width:48px;height:48px;min-width:44px;padding:0;border:1px solid #bcbcbc;border-radius:4px;background:#f1f0ed;color:#444;font-size:28px;cursor:pointer;touch-action:manipulation} +.reader-music-button.is-playing{background:#e1e5e1;color:#253d31;border-color:#849489} +.reader-music-button:focus-visible,.reader-music-popover button:focus-visible,.reader-music-volume input:focus-visible{outline:2px solid currentColor;outline-offset:3px} +.reader-music-popover{position:fixed;z-index:140;width:min(420px,calc(100vw - 24px));max-height:calc(100svh - 24px);overflow:auto;padding:18px;border:1px solid #c4c1b9;border-radius:8px;background:#f6f3eb;color:#3d4037;box-shadow:0 8px 30px #1113;font:18px/1.5 var(--sans,system-ui,sans-serif)} +.reader-music-heading{display:flex;align-items:flex-start;justify-content:space-between;gap:8px;margin-bottom:12px;font-weight:500} +.reader-music-heading button{display:grid;place-items:center;flex-shrink:0;width:44px;height:44px;margin:-7px -10px 0 0;border:0;background:transparent;color:inherit;font:26px/1 sans-serif;cursor:pointer} +.reader-music-popover [data-music-hint]{margin:0;font-size:20px;line-height:1.6;color:inherit} +.reader-music-volume{display:grid;grid-template-columns:auto minmax(0,1fr) auto;align-items:center;gap:12px;font-size:16px} +.reader-music-volume input{min-width:0;width:100%;min-height:44px;accent-color:#827153} +.reader-music-volume output{font:14px var(--sans,system-ui,sans-serif);min-width:38px;text-align:end} +.reader-music-error{font-size:16px;line-height:1.5;margin:10px 0 0}.reader-music-error[hidden]{display:none} +audio[aria-hidden="true"]{position:fixed;width:1px;height:1px;opacity:0;pointer-events:none} +body.reading-view:not(.reality-view) .reader-music-button{background:transparent;border-color:var(--line);color:var(--ink)} +body.reading-view:not(.reality-view) .reader-music-button.is-playing{background:#a68e5420;border-color:#a18b5b} +body.night .reader-music-popover{background:#252d25;color:#d3d1c1;border-color:#626650} +body.reality-view .reader-music-popover{background:#f3f2ef;color:#333;border-color:#bbb} +body.real-theme-coal .reader-music-popover,body.real-theme-coal .reader-music-button{background:#252525;color:#ddd;border-color:#646464} +body.real-theme-coal .reader-music-button.is-playing{background:#383838;color:#eee} +@media(max-width:760px){.bound-tools .reader-music-dock{grid-row:2;grid-column:2}.reader-music-button{width:44px;height:44px}.real-toolbar-left{grid-template-columns:repeat(6,minmax(44px,1fr))}.real-toolbar-left .reader-music-dock{grid-row:1;grid-column:6;justify-self:center}} + +@media(max-width:760px){.real-toolbar-left #real-menu{grid-column:1;grid-row:1}.real-toolbar-left [data-search]{grid-column:2;grid-row:1}.real-toolbar-left .real-font[data-real-size="-1"]{grid-column:3;grid-row:1}.real-toolbar-left .real-font[data-real-size="1"]{grid-column:4;grid-row:1}.real-toolbar-left #real-night{grid-column:5;grid-row:1}.real-toolbar-left .reader-music-dock{grid-column:6;grid-row:1}} diff --git a/web/reader-presentation.css b/web/reader-presentation.css new file mode 100644 index 0000000..f2291cf --- /dev/null +++ b/web/reader-presentation.css @@ -0,0 +1,49 @@ +/* Both magic reading modes use one type scale; pagination only changes layout. */ +body.bound-reading.night .crafted-brand :is(.brand-name,.brand-subtitle){color:#e1e4d6!important} +.video-clip-range{font-size:.8em;line-height:1.5;text-align:center;font-variant-numeric:tabular-nums;opacity:.85;margin-top:.25em} +.bound-reading{--book-body-font:Georgia,'Times New Roman',serif;--book-line:1.8;--book-title:54px;--book-title-line:1.12} +html[lang|=zh] .bound-reading,html[lang=ja] .bound-reading{--book-body-font:'Noto Serif SC','Songti SC','SimSun',serif;--book-line:1.9;--book-title:44px;--book-title-line:1.3} +html[lang=ko] .bound-reading{--book-body-font:'Malgun Gothic',sans-serif;--book-line:1.85;--book-title:44px;--book-title-line:1.3} +html[lang=ar] .bound-reading{--book-body-font:'Noto Naskh Arabic','Traditional Arabic',serif;--book-line:1.9} +body.bound-reading :is(.folio-content,.continuous-prose){font-family:var(--book-body-font);line-height:var(--book-line)} +body.bound-reading :is(.folio-content,.continuous-prose) :is(h1,h2,h3,h4){font-family:var(--serif);text-wrap:wrap;overflow-wrap:break-word} +body.bound-reading :is(.folio-content,.continuous-prose) h1{font-size:var(--book-title);line-height:var(--book-title-line)} +body.bound-reading :is(.folio-content,.continuous-prose) h2{font-size:40px;line-height:1.35} +body.bound-reading :is(.folio-content,.continuous-prose) h3{font-size:32px;line-height:1.35} +body.bound-reading :is(.folio-content,.continuous-prose) h4{font-size:24px;line-height:1.35} +body.bound-reading :is(.folio-content,.continuous-prose) p{margin-block:16px} +body.bound-reading :is(.folio-content,.continuous-prose) table{font-size:.81em;line-height:1.6} +body.bound-reading :is(.folio-content,.continuous-prose) :is(td,th){padding:10px 12px} +body.bound-reading :is(.folio-content,.continuous-prose) .code-block pre{font-size:max(16px,calc(var(--reading-size)*.82));line-height:1.75} +body.bound-reading :is(.folio-content,.continuous-prose) .code-toolbar{padding:8px 16px;font-size:max(16px,calc(var(--reading-size)*.72));line-height:1.5} +body.bound-reading :is(.folio-content,.continuous-prose) :is(.copy-code,.rust-playground){font-size:max(16px,calc(var(--reading-size)*.72));line-height:1.5;letter-spacing:0} +body.bound-reading :is(.folio-content,.continuous-prose) .copy-code{min-height:44px;padding:6px 8px} +body.bound-reading :is(.folio-content,.continuous-prose) .code-toolbar>div{gap:10px;flex-wrap:wrap;justify-content:flex-end} +body.bound-reading :is(.folio-content,.continuous-prose) .admonition{font-size:.91em;padding:17px 20px} +body.bound-reading :is(.folio-content,.continuous-prose) .admonition p:first-of-type{margin-top:0} +body.bound-reading :is(.folio-content,.continuous-prose) .admonition p:last-child{margin-bottom:0} +body.bound-reading :is(.folio-content,.continuous-prose) .section-image{width:140px;height:140px!important;max-width:100%;max-height:140px!important;object-fit:contain;margin:12px auto 18px!important} +body.bound-reading.night :is(.folio-content,.continuous-prose) .code-block{background:#2c392b;border-color:#4e5638} +body.bound-reading.night :is(.folio-content,.continuous-prose) .admonition{background:#b3b59a09;border-color:#8c8b6740} +body.bound-reading.night :is(.folio-content,.continuous-prose) :is(h1,h2,h3,h4){color:#c7c9bc} + +/* A single paper surface spans the full scrolling document, including its margins. */ +body.bound-reading.continuous-reading .page-book{background:none;box-shadow:none} +body.bound-reading.continuous-reading .bound-volume{padding:36px clamp(20px,5vw,64px);background-color:#f1e8d4;background-image:linear-gradient(#f2eadcdd,#f2eadcdd),url('/art/ivory-paper.webp');background-size:626px 626px;background-repeat:repeat} +body.bound-reading.night.continuous-reading .bound-volume{background:#202820} +body.bound-reading .book-sidebar{scrollbar-color:#9b9478 #e3d6b8} +body.bound-reading.night .book-sidebar{scrollbar-color:#78866a #1c2a22} + +/* The two worlds share wordmark proportions, while retaining their own material. */ +.page-book.reader-preview{display:flex!important;overflow:hidden} +.page-book.reader-preview>.folio-page{position:relative;display:block;flex:none;width:var(--sheet-w);height:var(--sheet-h)} +.page-book.reader-preview .folio-footer{visibility:hidden} +.bound-reading .book-sidebar .crafted-brand,.bound-toolbar>.crafted-brand{--brand-title:38px;--brand-caption:20px;--title-track:6px;--caption-track:1.2px;--word-gap:7px} +body.reality-view .real-sidebar .real-brand{font:500 38px/1 var(--serif);letter-spacing:6px;gap:14px} +body.reality-view .real-sidebar .real-brand img{width:62px;height:62px} +body.reality-view .real-sidebar .real-brand small{font:600 20px/1.1 var(--serif);letter-spacing:1.2px;margin-top:7px;padding-inline-start:2px} +@media(max-width:760px){ + body.bound-reading.continuous-reading .bound-volume{padding:24px 16px} + body.bound-reading :is(.folio-content,.continuous-prose) .code-toolbar{padding-inline:10px;gap:8px;flex-wrap:wrap} + body.bound-reading :is(.folio-content,.continuous-prose) .section-image{width:110px;height:110px!important;max-height:110px!important} +} diff --git a/web/reader-typography.css b/web/reader-typography.css new file mode 100644 index 0000000..e8fd054 --- /dev/null +++ b/web/reader-typography.css @@ -0,0 +1,144 @@ +/* Shared reading sizes are set once per locale by reading-preferences.js. */ +html{scrollbar-gutter:stable} +.bound-reading .folio-content,.bound-reading .continuous-prose{font-size:var(--reading-size)!important} +.bound-reading .book-sidebar nav a,.reality-view .real-sidebar nav a{font-size:calc(var(--sidebar-size) - 2px)!important;line-height:1.6} +.bound-reading .book-sidebar .sidebar-group h2{font:600 calc(var(--sidebar-size) + 2px)/1.45 var(--serif);letter-spacing:0;text-transform:none;margin-bottom:12px;text-wrap:wrap;overflow-wrap:break-word} +.bound-reading .book-sidebar :is(.my-bookmarks,.sidebar-search),.reality-view .real-sidebar .my-bookmarks{font-size:var(--reader-ui-size);line-height:1.5} +.bound-reading .sidebar-group a>span{font-size:.64em;min-width:1.7em} +.bound-reading .book-sidebar .sidebar-bottom{padding-top:24px} +.bound-reading.night .book-sidebar .sidebar-bottom{color:#c5b994} +.bound-reading .book-sidebar .sidebar-bottom .sidebar-source{display:flex;align-items:center;justify-content:center;width:48px;height:48px;margin:0 auto;color:#9b783e;border-radius:4px} +.bound-reading.night .book-sidebar .sidebar-bottom .sidebar-source{color:#c5b17d} +.bound-reading .sidebar-source svg{width:28px;height:28px} +.bound-reading .sidebar-source:hover{background:#9d804b12} +.bound-reading .sidebar-source:focus-visible{outline:2px solid currentColor;outline-offset:2px} +body.bound-reading .book-sidebar nav .intro-nav,body.reality-view .real-sidebar nav .real-intro{font-size:var(--sidebar-size)!important;line-height:1.5;min-height:48px;display:flex;align-items:center;gap:12px} +.bound-reading .intro-nav svg{width:22px;height:22px;flex-shrink:0} +.bound-reading :is(.folio-chapter-end,.folio-closing) a[data-open-contents]{font:500 var(--reading-size)/1.5 var(--serif);min-height:48px;padding:8px 12px;justify-content:center;max-width:100%;overflow-wrap:anywhere} +.bound-reading [data-open-contents] svg{flex-shrink:0} +.bound-controls #folio-position{font-size:14px;white-space:nowrap} +.folio-page.folio-verso .folio-footer{flex-direction:row-reverse} +.bound-reading .sidebar-search{min-height:48px;gap:9px}.bound-reading .sidebar-search kbd{font-size:11px} +body.bound-reading .book-sidebar .sidebar-search{font-size:calc(var(--sidebar-size) + 2px);min-height:60px;padding:13px 14px;gap:12px} +body.bound-reading .book-sidebar .sidebar-search svg{width:26px;height:26px} +body.bound-reading .book-sidebar .sidebar-search kbd{font-size:14px} +.bound-reading .my-bookmarks svg,.bound-reading .sidebar-search svg{width:22px;height:22px;flex-shrink:0} +.bound-reading .my-bookmarks small{font-size:15px} +body.bound-reading .book-sidebar .my-bookmarks,body.reality-view .real-sidebar .my-bookmarks{font-size:calc(var(--sidebar-size) + 2px);font-weight:500;min-height:60px;padding-block:14px;gap:12px} +body.bound-reading .book-sidebar .my-bookmarks svg,body.reality-view .real-sidebar .my-bookmarks svg{width:26px;height:26px} +body.bound-reading .book-sidebar .my-bookmarks small,body.reality-view .real-sidebar .my-bookmarks small{font-size:18px;opacity:.85} +.bound-world-nav .realm-switch,.bound-world-nav .language-picker,.real-toolbar .realm-switch,.real-toolbar .language-picker{font-size:var(--reader-ui-size)} +.bound-world-nav .language-picker select,.real-toolbar .language-picker select{min-height:48px;max-width:190px;font-size:inherit} +.bound-world-nav .language-picker svg,.real-toolbar .language-picker svg{width:23px;height:23px} +.bound-toolbar{height:136px;min-height:136px;grid-template-rows:48px 48px;row-gap:8px} +.bound-toolbar>.bound-tools{height:48px} +.bound-reading .bound-tools .icon-button{width:48px;min-width:48px;height:48px;font-size:22px} +.bound-reading .bound-tools .icon-button svg{width:27px;height:27px} +.bound-tools .contents-toggle{font-size:24px;min-height:48px;height:48px;padding:8px 14px} +.bound-tools .contents-toggle svg{width:25px;height:25px} +.bound-reading .bound-tools .contents-toggle{color:#454c33;background:#ddd5bc;border:1px solid #9e9675;box-shadow:none} +.bound-reading .bound-tools .contents-toggle:hover{background:#d2caac} +.bound-reading.night .bound-tools .contents-toggle{color:#d8d8c6;background:#354637;border-color:#66765d} +.bound-reading .bound-tools .bound-mode{display:inline-flex;align-items:center;justify-content:center;gap:9px;font:600 23px/1.3 var(--serif);border:1px solid var(--line);border-radius:3px;padding:10px 13px;margin-inline-start:6px;white-space:normal;text-wrap:balance} +.bound-tools .bound-mode svg{width:25px;height:25px;flex-shrink:0} +.bound-toolbar .bound-mode{font-size:var(--reader-ui-size);min-height:48px;line-height:1.35} +.bound-location>a{font-size:24px}.bound-location>span{font-size:16px;line-height:1.4} +.bound-location .location-chapter{font:500 24px/1.3 var(--serif);display:-webkit-box;-webkit-line-clamp:2;-webkit-box-orient:vertical;overflow:hidden;overflow-wrap:break-word} +.bound-toolbar>.crafted-brand{--mark-size:62px!important;--brand-title:38px;--brand-caption:15px;--title-track:6px;--caption-track:1.7px;gap:14px;grid-row:1/3;align-self:center;max-height:none} +.bound-toolbar>.crafted-brand .brand-seal{width:62px!important;height:62px!important} +.bound-volume{display:flex;align-items:center;justify-content:center;height:calc(100svh - 240px)} +.bound-reading .page-book{flex:none;max-width:100%;margin-inline:auto} +.continuous-reading .page-book{width:100%!important;height:auto!important} +.bound-controls .current-chapter-title{font-size:24px;line-height:1.3} +.bound-controls #folio-position{font-size:15px} +.bound-outline{font-size:18px;line-height:1.5}.bound-controls .sheet-control{font-size:26px} +.real-toolbar{min-height:76px;height:auto;padding-block:10px;flex-wrap:wrap} +.real-toolbar .real-tool{width:48px;min-width:48px;height:48px;font-size:22px;padding:10px} +.real-toolbar .real-tool svg{width:27px;height:27px}.real-book-title{font-size:20px} +.real-toolbar .real-bookmark{width:auto;min-width:148px;gap:9px;padding:9px 12px;border:1px solid var(--real-line);font-size:18px;white-space:nowrap} +.real-toolbar .real-bookmark[aria-pressed=true]{background:var(--real-code);color:var(--real-link)!important;border-color:var(--real-link)} +.real-toolbar-left{flex-wrap:wrap} +.real-pagination{font-size:var(--reader-ui-size)}.real-pagination small{font-size:17px} +.real-pagination{min-width:0}.real-pagination a{min-width:0;flex:1}.real-pagination a>span{min-width:0;overflow-wrap:anywhere;hyphens:auto} +.real-prose :is(h1,h2,h3,h4){overflow-wrap:anywhere;hyphens:auto} +.real-prose :not(pre)>code{overflow-wrap:anywhere;white-space:normal} +.real-sidebar nav h2{font-size:calc(var(--sidebar-size) + 2px);line-height:1.45;margin-bottom:12px;text-wrap:wrap;overflow-wrap:break-word} +.reality-view .real-main{max-width:1000px;font-size:var(--real-size)!important} +.bound-reading .folio-content .code-block pre,.reality-view .real-prose pre{font-size:calc(var(--reading-size)*.8)} +.bound-reading .folio-content :is(.code-toolbar,.copy-code,.admonition-title),.reality-view .real-prose :is(.code-toolbar,.admonition-title){font-size:14px} +.folio-running-head{font-size:15px;height:40px;padding-bottom:12px}.folio-running-head>span:last-child{font-size:12px} +.folio-content{height:calc(100% - 83px)}.folio-footer{font-size:14px} +body.bound-reading.night .folio-page{background-color:#1c251f;color:#bcc2b5} +body.bound-reading.night .folio-page :is(h1,h2,h3,h4){color:#c7c9ba} +@media(min-width:1280px){ + .bound-reading .book-sidebar{width:320px;padding:30px 24px} + .bound-reading .bound-reader{margin-left:320px} + .bound-reading.contents-collapsed .bound-reader{margin-left:0} + .bound-reading .bound-tools{gap:7px} +} +@media(min-width:1800px){.bound-reading .book-sidebar{width:340px}.bound-reading .bound-reader{margin-left:340px}.bound-reading.contents-collapsed .bound-reader{margin-left:0}} +@media(min-width:1001px){.real-sidebar{width:320px}.real-body{margin-left:320px}.real-sidebar-hidden .real-body{margin-left:0}html[dir=rtl] .real-body{margin-right:320px;margin-left:0}html[dir=rtl] .real-sidebar-hidden .real-body{margin-right:0}} +@media(max-width:1279px){.bound-toolbar>.bound-tools{width:100%;justify-content:space-between}.bound-reading .book-sidebar{width:min(340px,calc(100vw - 28px))}.bound-toolbar>.bound-location{display:none}.bound-reading .bound-tools .contents-toggle{font-size:20px;max-width:31%;white-space:normal;overflow-wrap:anywhere}.bound-reading .bound-tools .bound-mode{font-size:20px;max-width:25%;padding:7px 10px}} +@media(min-width:761px) and (max-width:1279px){.bound-toolbar{height:152px;min-height:152px;grid-template-rows:72px 48px}.bound-toolbar>.crafted-brand{grid-row:1}.bound-toolbar>.bound-tools{grid-row:2;grid-column:1/-1}.bound-world-nav{grid-row:1;grid-column:2}.bound-volume{height:calc(100svh - 256px)}} +@media(max-width:1000px){.binding-ribbon{display:none!important}} +@media(max-width:760px){ + .bound-toolbar{height:176px;min-height:176px;grid-template-rows:48px 96px;padding:8px} + .bound-toolbar>.crafted-brand{display:flex;--mark-size:48px!important;grid-row:1;grid-column:1} + .bound-toolbar>.crafted-brand .brand-seal{width:48px!important;height:48px!important} + .bound-toolbar>.crafted-brand .brand-letters{display:none} + .bound-world-nav{grid-row:1;grid-column:2} + .bound-toolbar>.bound-tools{height:96px;grid-template-rows:44px 48px;grid-template-columns:minmax(0,1fr) repeat(3,44px);gap:4px} + .bound-reading .bound-tools .icon-button{width:44px;min-width:44px;height:44px;font-size:20px} + .bound-tools .contents-toggle{font-size:19px;height:44px;min-height:44px;padding:6px} + .bound-toolbar .bound-mode{font-size:18px;min-height:44px;height:44px} + .bound-reading .bound-tools .bound-mode{font-size:19px;max-width:none;width:100%;padding:5px 7px;margin:0;gap:6px;justify-content:flex-start} + .bound-reading .bound-tools .contents-toggle{max-width:none;width:100%;font-size:18px} + .bound-tools .bound-mode svg{width:23px;height:23px} + .bound-world-nav .realm-switch,.bound-world-nav .language-picker,.real-toolbar .realm-switch,.real-toolbar .language-picker{font-size:17px} + .bound-world-nav .language-picker select,.real-toolbar .language-picker select{max-width:148px;padding-inline:4px} + .bound-volume{height:calc(100svh - 265px)} + .folio-running-head{font-size:13px;height:30px;padding-bottom:8px}.folio-content{height:calc(100% - 74px)} + .bound-controls .current-chapter-title{font-size:18px;white-space:normal;text-wrap:balance} + .bound-controls .sheet-control,.sheet-control span{font-size:19px}.bound-controls #folio-position{font-size:13px}.bound-outline{font-size:16px} + .real-toolbar{padding:7px 10px;gap:6px} + .real-toolbar-left{display:grid;width:100%;grid-template-columns:repeat(5,minmax(44px,1fr));gap:4px}.real-toolbar-right{gap:4px;width:100%;justify-content:space-between} + .real-toolbar .real-font{display:inline-flex} + .real-toolbar .real-tool{width:44px;min-width:44px;height:44px;padding:9px;font-size:20px} + .real-toolbar .real-bookmark{width:auto;min-width:134px;font-size:17px;gap:7px;padding:7px 10px} + .real-toolbar .real-bookmark{grid-row:2;grid-column:1/-1;width:100%;justify-content:center} + .real-toolbar-left .real-tool:not(.real-bookmark){justify-self:center} + .real-pagination a{font-size:18px}.real-pagination small{font-size:15px} +} + +/* Short, readable search labels and article callout headings. */ +body.bound-reading .book-sidebar .sidebar-search{font-family:var(--serif);text-align:start} +body.bound-reading .book-sidebar .sidebar-search>span{flex:1;white-space:nowrap} +body.bound-reading .admonition .admonition-title,body.reality-view .admonition .admonition-title{font:500 max(18px,calc(var(--reading-size)*.9))/1.5 var(--serif);letter-spacing:0;text-transform:none;margin-bottom:12px;color:#76512d} +body.bound-reading.night .admonition-title{color:#c9b78b} +body.reality-view .admonition .admonition-title{font-family:var(--sans);color:var(--real-fg)} +/* Give section changes breathing room, including headings kept with their paragraphs. */ +.bound-reading .folio-content>.folio-heading-group:not(:first-child){padding-block-start:22px} +.bound-reading :is(.folio-content,.continuous-prose) :is(h2,h3,h4){line-height:1.35;text-wrap:wrap} +.bound-reading .folio-content>:is(h2,h3,h4){margin-block-start:36px} +.bound-reading .folio-content>:is(h2,h3,h4):first-child{margin-block-start:0} +.bound-reading .continuous-prose :is(h2,h3,h4){margin-block-start:36px} +/* The Chinese volume name fits naturally on one line when a full sidebar is available. */ +@media(min-width:1280px){ + html[lang|=zh] .bound-reading .book-sidebar{width:380px} + html[lang|=zh] .bound-reading .bound-reader{margin-left:380px} + html[lang|=zh] .bound-reading.contents-collapsed .bound-reader{margin-left:0} +} +@media(max-width:760px){ + .bound-toolbar{height:212px;min-height:212px;grid-template-rows:48px 140px} + .bound-toolbar>.bound-tools{height:140px;grid-template-rows:44px 44px 44px;grid-template-columns:repeat(5,minmax(44px,1fr));gap:4px} + .bound-tools .contents-toggle{grid-row:1;grid-column:1/5} + .bound-tools [data-search]{grid-row:1;grid-column:5} + .bound-tools #smaller-text{grid-row:2;grid-column:1} + .bound-tools #larger-text{grid-row:2;grid-column:2} + .bound-tools #toggle-night{grid-row:2;grid-column:3} + body.bound-reading .bound-tools .reader-music-dock{grid-row:2;grid-column:4;justify-self:center} + .bound-tools #bookmark{grid-row:2;grid-column:5} + .bound-tools .bound-mode{grid-row:3;grid-column:1/-1;width:100%;max-width:100%;justify-content:center} + .bound-tools>.icon-button{justify-self:center} + .bound-volume{height:calc(100svh - 301px)} +} diff --git a/web/real-reader.css b/web/real-reader.css new file mode 100644 index 0000000..d39cb6b --- /dev/null +++ b/web/real-reader.css @@ -0,0 +1,61 @@ +body.reality-view{--real-bg:#fff;--real-fg:#242424;--real-muted:#666;--real-sidebar:#f5f5f5;--real-line:#e5e5e5;--real-link:#20609b;--real-code:#f4f4f4;--real-inline:#efefef;background:var(--real-bg);color:var(--real-fg);font-family:Arial,'Microsoft YaHei',sans-serif;margin:0;line-height:1.6} +body.real-theme-rust{--real-bg:#f1e7d2;--real-fg:#262625;--real-muted:#706656;--real-sidebar:#e5d8bd;--real-line:#d4c7aa;--real-link:#924e27;--real-code:#e8ddc5;--real-inline:#e1d5bc} +body.real-theme-coal{--real-bg:#292c2f;--real-fg:#eee;--real-muted:#b1b1b1;--real-sidebar:#202326;--real-line:#43464b;--real-link:#70b9eb;--real-code:#202326;--real-inline:#393c40} +body.real-theme-navy{--real-bg:#161923;--real-fg:#c9cbd2;--real-muted:#a0a4b0;--real-sidebar:#10131c;--real-line:#303542;--real-link:#83b6e1;--real-code:#10131c;--real-inline:#282c3a} +body.real-theme-ayu{--real-bg:#0f1419;--real-fg:#c5c5c5;--real-muted:#a2a7ad;--real-sidebar:#14191f;--real-line:#343b44;--real-link:#ffb454;--real-code:#14191f;--real-inline:#252c34} +.reality-view #app{min-height:100svh}.reality-view *{box-sizing:border-box}.reality-view a{color:var(--real-link)} +.reality-view:after{display:none}.reality-view .real-prose .code-block{border:0;background:none;border-radius:0;margin:1.4em 0}.reality-view .real-prose .code-toolbar{background:var(--real-code);color:var(--real-muted);font:12px/1.4 Arial,sans-serif;border:0;padding:8px 16px 0;display:flex;justify-content:space-between}.reality-view .real-prose .code-block pre{margin:0}.reality-view .real-prose .code-toolbar a{color:var(--real-link);font-size:12px}.reality-view .real-prose .heading-anchor{font:inherit;opacity:0;margin-left:.4em}.reality-view .real-prose :is(h1,h2,h3,h4):hover .heading-anchor,.reality-view .real-prose .heading-anchor:focus-visible{opacity:.5} +.real-sidebar{width:290px;position:fixed;inset:0 auto 0 0;background:var(--real-sidebar);overflow-y:auto;padding:28px 22px 60px;color:var(--real-fg);z-index:31;border-right:1px solid var(--real-line);font-size:14px;scrollbar-width:thin;scrollbar-color:var(--real-line) transparent} +.real-brand{display:flex;align-items:center;gap:12px;color:var(--real-fg)!important;text-decoration:none;font-size:22px;font-weight:600;line-height:1.2;letter-spacing:.02em;margin-bottom:14px} +.real-brand img{width:36px;height:36px;object-fit:contain}.real-brand small{display:block;font-weight:400;font-size:13px;letter-spacing:.025em;margin-top:4px} +.real-theme-coal .real-brand img,.real-theme-navy .real-brand img,.real-theme-ayu .real-brand img{filter:invert(1)} +.real-choose{display:inline-block;font-size:13px;text-decoration:none;margin:2px 0 24px;color:var(--real-muted)!important} +.real-sidebar nav section{margin:25px 0}.real-sidebar nav h2{font:600 14px/1.5 Arial,sans-serif;margin:0 0 9px;color:var(--real-fg)} +.real-sidebar nav a{display:block;text-decoration:none;line-height:1.55;padding:7px 0;color:var(--real-fg)}.real-sidebar nav a span{font-weight:600}.real-sidebar nav a:hover,.real-sidebar nav a.active{color:var(--real-link)}.real-sidebar nav a.active{font-weight:600} +.real-body{margin-left:290px}.real-toolbar{height:64px;background:var(--real-bg);position:sticky;top:0;z-index:30;display:flex;align-items:center;justify-content:space-between;padding:0 24px;gap:16px;border-bottom:1px solid var(--real-line)} +.real-toolbar-left,.real-toolbar-right{display:flex;align-items:center;gap:6px}.real-book-title{font-size:17px;font-weight:400;color:var(--real-muted);white-space:nowrap}.real-tool{background:transparent;border:0;display:inline-flex;align-items:center;justify-content:center;width:38px;height:40px;padding:8px;color:var(--real-muted)!important;cursor:pointer;border-radius:3px;text-decoration:none;flex-shrink:0;font:14px/1 Arial,sans-serif}.real-tool svg{width:19px;height:19px}.real-tool:hover{background:var(--real-code);color:var(--real-fg)!important}.real-tool:focus-visible,.real-copy:focus-visible{outline:2px solid var(--real-link);outline-offset:2px}.real-toolbar .realm-switch{color:var(--real-muted);padding:8px;font:14px/1.5 Arial,'Microsoft YaHei',sans-serif}.real-toolbar .realm-switch svg{width:14px;height:14px} +.real-theme-menu{position:relative}.real-theme-menu summary{list-style:none}.real-theme-menu summary::-webkit-details-marker{display:none}.real-theme-menu>div{position:absolute;top:44px;left:0;width:130px;padding:5px;background:var(--real-bg);border:1px solid var(--real-line);box-shadow:0 5px 18px #0002;z-index:35}.real-theme-menu button{display:block;width:100%;text-align:left;border:0;background:transparent;color:var(--real-fg);padding:8px 12px;font:14px Arial,sans-serif;cursor:pointer}.real-theme-menu button[aria-pressed=true],.real-theme-menu button:hover{background:var(--real-code);color:var(--real-link)} +.real-main{width:min(900px,100%);margin:0 auto;padding:46px 40px 70px;font-size:var(--real-size)} +.real-prose{font-family:Arial,'Microsoft YaHei',sans-serif;line-height:1.75;overflow-wrap:break-word;color:var(--real-fg)} +.real-prose h1,.real-prose h2,.real-prose h3,.real-prose h4{font-family:inherit;font-style:normal;font-weight:600;color:var(--real-fg);letter-spacing:0;line-height:1.35;scroll-margin-top:90px} +.real-prose h1{font-size:2em;margin:0 0 1em}.real-prose h2{font-size:1.5em;margin:1.8em 0 .7em}.real-prose h3{font-size:1.2em;margin:1.5em 0 .5em}.real-prose p{margin:1em 0}.real-prose ol,.real-prose ul{padding-left:1.65em;margin:1em 0}.real-prose li{margin:.35em 0}.real-prose a{text-underline-offset:3px}.real-prose :is(h1,h2,h3,h4) a{color:inherit;text-decoration:none} +.reality-view .real-prose .admonition-title{font:600 13px/1.5 Arial,sans-serif;color:var(--real-muted);letter-spacing:.02em} +.real-prose img{max-width:100%;height:auto}.real-prose blockquote{border-left:4px solid var(--real-line);margin:1.4em 0;padding:.2em 1em;color:var(--real-muted);font-style:normal;background:transparent}.real-prose hr{border:0;border-top:1px solid var(--real-line);margin:2em 0} +.real-prose>.section-image{width:128px;height:auto;margin:8px auto 24px} +.reality-view .real-prose .heading-anchor{position:static;display:inline;font-size:.65em;bottom:auto;vertical-align:middle} +.real-prose pre{position:relative;background:var(--real-code);color:var(--real-fg);padding:20px 42px 20px 18px;overflow-x:auto;border:0;border-radius:2px;line-height:1.55;font:14px/1.6 'IBM Plex Mono',Consolas,monospace;margin:1.4em 0;tab-size:4}.real-prose pre code{font:inherit;color:inherit;background:none;padding:0;white-space:pre}.real-prose code{font: .86em/1.5 'IBM Plex Mono',Consolas,monospace;background:var(--real-inline);color:inherit;padding:.16em .3em;border-radius:3px} +.real-prose .hljs-keyword,.real-prose .hljs-selector-tag{color:#9d2555}.real-prose .hljs-title,.real-prose .hljs-type{color:#2769a2}.real-prose .hljs-string{color:#367548}.real-prose .hljs-comment{color:#6a737d}.real-prose .hljs-number,.real-prose .hljs-literal{color:#9a5b20} +:is(.real-theme-coal,.real-theme-navy,.real-theme-ayu) .real-prose .hljs-keyword{color:#d79eda}:is(.real-theme-coal,.real-theme-navy,.real-theme-ayu) .real-prose .hljs-title,:is(.real-theme-coal,.real-theme-navy,.real-theme-ayu) .real-prose .hljs-type{color:#81bce6}:is(.real-theme-coal,.real-theme-navy,.real-theme-ayu) .real-prose .hljs-string{color:#aad69e}:is(.real-theme-coal,.real-theme-navy,.real-theme-ayu) .real-prose .hljs-comment{color:#9ca4ae}:is(.real-theme-coal,.real-theme-navy,.real-theme-ayu) .real-prose .hljs-number{color:#e2ba82} +.real-copy{position:absolute;right:6px;top:8px;background:var(--real-code);color:var(--real-muted);border:0;padding:6px;cursor:pointer;display:flex}.real-copy svg{width:17px;height:17px} +.real-table-scroll{overflow:auto;max-width:100%;margin:1.5em 0}.real-prose table{border-collapse:collapse;min-width:100%;font-size:.9em}.real-prose th,.real-prose td{border:1px solid var(--real-line);padding:9px 12px;text-align:left}.real-prose th{background:var(--real-code);font-weight:600}.real-prose details{border:1px solid var(--real-line);padding:10px 15px;margin:1em 0}.real-prose summary{cursor:pointer}.real-prose .admonition{border:1px solid var(--real-line);border-left:4px solid var(--real-link);background:var(--real-code);padding:12px 20px;margin:1.5em 0}.real-prose .admonition-title{font-size:.9em;font-weight:600;margin-top:0}.real-prose .katex-display{overflow-x:auto;overflow-y:hidden;max-width:100%;padding:8px 0}.real-prose iframe{max-width:100%} +.real-pagination{display:flex;justify-content:space-between;gap:30px;border-top:1px solid var(--real-line);padding-top:28px;margin-top:56px;font-size:15px}.real-pagination a{display:flex;align-items:center;gap:14px;max-width:48%;text-decoration:none}.real-pagination a:last-child{text-align:right}.real-pagination small{display:block;font-size:12px;color:var(--real-muted);margin-bottom:4px}.real-pagination svg{width:22px;flex-shrink:0} +.real-sidebar-hidden .real-sidebar{display:none}.real-sidebar-hidden .real-body{margin-left:0}.real-scrim{position:fixed;inset:0;background:#0005;border:0;z-index:30}.real-scrim[hidden]{display:none} +.reality-view #search-dialog{font-family:Arial,sans-serif;color:var(--real-fg);background:var(--real-bg)}.reality-view #search-dialog input{color:var(--real-fg)}.reality-view .search-result strong{font-family:Arial,sans-serif;font-size:19px}.reality-view .search-result{color:var(--real-fg)}.reality-view .search-result p{color:var(--real-muted)}.reality-view .search-result:hover{background:var(--real-code)} +@media(max-width:1200px){.real-book-title{display:none}.real-sidebar{width:270px}.real-body{margin-left:270px}.real-main{padding:40px 32px}} +@media(max-width:1000px){.real-sidebar{display:none;width:min(310px,84vw)}.real-body{margin-left:0}.real-sidebar-open .real-sidebar{display:block}.real-toolbar{padding:0 16px}.real-main{width:min(900px,100%);padding:38px 28px 50px}} +@media(max-width:550px){.real-toolbar{padding:0 8px;gap:4px;height:60px}.real-toolbar-left,.real-toolbar-right{gap:0}.real-tool{width:33px;height:40px;padding:7px}.real-toolbar .realm-switch{font-size:13px;padding:6px;gap:2px}.real-toolbar .realm-switch svg{display:none}.real-main{padding:30px 22px 45px}.real-prose h1{font-size:1.8em}.real-prose pre{font-size:13px}.real-pagination{gap:15px}.real-pagination a{font-size:14px}.real-pagination svg{width:17px}} +body.reality-view.real-theme-light{--real-bg:#f7f6f2;--real-sidebar:#eeede8;--real-fg:#30332f;--real-muted:#656a63;--real-line:#dcded5;--real-code:#eeeee7;--real-inline:#e9eae3} +body.real-theme-coal{color-scheme:dark} +.reality-view .real-sidebar{font-size:var(--sidebar-size,18px)} +.real-sidebar section h2{font-size:.95em;line-height:1.5}.real-sidebar nav a{font-size:1em;line-height:1.55} +.real-prose pre{font-size:calc(var(--real-size,20px)*.78)} +.real-sidebar .my-bookmarks{font-size:1em} +.real-brand{gap:14px;font-size:28px;line-height:1.2;margin-bottom:24px}.real-brand img{width:52px;height:52px}.real-brand small{font-size:16px;line-height:1.4;margin-top:5px} +.real-toolbar .language-picker{font-size:16px}.real-toolbar .language-picker svg{display:block;width:19px;height:19px}.real-toolbar .language-picker select{min-height:44px;max-width:155px;padding:8px} +@media(max-width:760px){.real-toolbar .language-picker{font-size:14px}.real-toolbar .language-picker select{max-width:132px}.real-toolbar .language-picker svg{display:none}} +body.real-theme-coal{--real-bg:#252829;--real-fg:#c9ccc7;--real-muted:#a1aaa4;--real-sidebar:#1d2122;--real-line:#3c4541;--real-link:#98bfce;--real-code:#1d2122;--real-inline:#343c37} +.real-prose{hanging-punctuation:first last;word-break:normal}.real-prose :is(h1,h2,h3,h4){text-wrap:balance;overflow-wrap:anywhere}.real-prose p{orphans:3;widows:3} +html[lang|=zh] .real-prose,html[lang=ja] .real-prose{line-break:strict;word-break:normal;overflow-wrap:break-word} +html[lang=ko] .real-prose{word-break:keep-all;overflow-wrap:break-word} +html[lang=ar] .real-prose{line-height:1.95} +.real-toolbar .real-tool{width:44px;height:44px;min-width:44px;padding:10px;font-size:18px}.real-toolbar .real-tool svg{width:24px;height:24px}.real-toolbar-left{gap:6px}.real-toolbar .realm-switch{font-size:16px}.real-book-title{font-size:18px} +@media(max-width:760px){.real-toolbar .real-tool{width:42px;min-width:42px;height:44px;padding:9px}.real-toolbar-left{gap:3px}.real-toolbar .realm-switch{font-size:14px}.real-toolbar{padding:6px 10px}} +body.real-theme-coal{--real-bg:#202020;--real-fg:#c9c9c9;--real-muted:#a5a5a5;--real-sidebar:#181818;--real-line:#3b3b3b;--real-link:#9db8d2;--real-code:#181818;--real-inline:#333} +.real-theme-coal .real-prose :is(h1,h2,h3,h4){color:#d4d4d4} +body.reality-view.real-theme-light{--real-bg:#f5f5f5;--real-sidebar:#ebebeb;--real-fg:#303030;--real-muted:#666;--real-line:#d9d9d9;--real-code:#ededed;--real-inline:#e7e7e7} +.real-brand{font-family:var(--serif);font-size:34px;font-weight:600;letter-spacing:.13em;gap:15px;align-items:center}.real-brand>span{display:block;line-height:1}.real-brand small{font:13px/1.4 Arial,'Microsoft YaHei',sans-serif;letter-spacing:.1em;margin-top:7px}.real-brand img{width:54px;height:54px;flex:none} +html[lang|=zh] .real-brand small,html[lang=ja] .real-brand small,html[lang=ko] .real-brand small{font-size:16px;letter-spacing:.15em} +.real-prose :is(h1,h2,h3,h4){scroll-margin-top:calc(var(--real-toolbar-height,64px) + 20px)} +@media(max-width:760px){.real-toolbar .real-font{display:inline-flex}} +.real-brand small{font-size:14px} +html[lang=ar] .real-brand small{letter-spacing:0;font-family:Tahoma,Arial,sans-serif;font-size:16px} diff --git a/web/refinements.css b/web/refinements.css new file mode 100644 index 0000000..2a0bd75 --- /dev/null +++ b/web/refinements.css @@ -0,0 +1,52 @@ +/* Generated bronze and restrained book typography share explicit size roles. */ +#announcement:empty{display:none} +.site-header{top:0;width:90%;height:128px;margin:0 auto;padding:0;background:#f6f1e6ee;border:0;border-bottom:1px solid #c6b99e88;border-radius:0;box-shadow:none} +.brand.crafted-brand{--mark-size:72px;--brand-title:44px;--brand-caption:16px;--title-track:8px;--caption-track:2.7px;--word-gap:7px;width:max-content;max-width:100%;flex-shrink:0;display:flex;align-items:center;gap:19px} +.brand.crafted-brand .brand-seal{display:block;width:var(--mark-size);height:var(--mark-size);object-fit:contain;filter:none;flex-shrink:0} +.brand.crafted-brand .brand-seal-night{display:none} +.night .bound-toolbar .crafted-brand .brand-seal-day{display:none} +.night .bound-toolbar .crafted-brand .brand-seal-night{display:block} +.brand.crafted-brand .brand-letters{display:flex;flex-direction:column;font-family:var(--serif);color:#243c33;letter-spacing:normal;gap:var(--word-gap);line-height:1} +.brand.crafted-brand .brand-name{font-size:var(--brand-title);font-weight:500;letter-spacing:var(--title-track);line-height:1} +.brand.crafted-brand .brand-subtitle{font:600 var(--brand-caption)/1.1 var(--serif);letter-spacing:var(--caption-track);padding-left:2px;white-space:nowrap} +.bound-reading .book-sidebar .crafted-brand{--mark-size:62px;--brand-title:38px;--brand-caption:15px;--title-track:6px;--caption-track:1.7px;gap:14px;margin-bottom:22px} +.site-footer .crafted-brand{--mark-size:48px;--brand-title:32px;--brand-caption:13px;--title-track:5px;--caption-track:1.6px;gap:14px} +.bound-reading.night .bound-toolbar .brand-letters{color:#ebdbb6} +.bound-reading.night .bound-tools .icon-button,.bound-reading.night .bound-mode{color:#eddfbc} +.bound-reading.night .bound-outline,.bound-reading.night .bound-outline>a,.bound-reading.night .bound-outline summary{color:#d7c49c} +.bound-reading.night .folio-running-head,.bound-reading.night .folio-footer{color:#cdb98c} +.bound-reading.night .folio-content .admonition-title{color:#dbc393} +.bound-reading.night .sheet-control:enabled{color:#e6c792} +.contents-toggle{display:flex;align-items:center;gap:9px;background:#304637;color:#f4e5c4;padding:11px 16px;min-height:44px;font:20px var(--serif);border:1px solid #a38b58;border-radius:2px;white-space:nowrap} +.contents-toggle svg{width:21px;height:21px}.contents-toggle:hover{background:#43583e} +.route-book-turn{position:fixed;inset:0;z-index:500;overflow:hidden;pointer-events:none;background:transparent;isolation:isolate} +.route-flip-host{position:absolute!important;inset:0!important;width:100vw!important;height:100dvh!important;min-width:0!important} +.route-soft-sheet{overflow:hidden;background:#f6f0e4} +.route-soft-sheet.route-destination{background:transparent!important} +.route-sheet-surface{position:relative;overflow:hidden;background:#f6f0e4;pointer-events:none} +.route-sheet-surface.bound-reading{background:#dfd0b3} +.route-sheet-surface #app,.route-sheet-surface>div{width:100%} +.route-sheet-surface .site-header{position:relative;top:0} +.route-sheet-surface .book-sidebar{position:absolute} +.route-sheet-back{background:linear-gradient(100deg,#f8f0dc,#ead8b5 80%,#c7ad79);background-image:linear-gradient(#fff7e8b8,#fff7e8b8),url('/art/paper.webp');box-shadow:inset 35px 0 65px #8a663a35} +.route-soft-sheet.--left{background-image:linear-gradient(#fff7e8b8,#fff7e8b8),url('/art/paper.webp');box-shadow:inset -25px 0 50px #98704435} +.route-soft-sheet.--left>.route-sheet-surface{visibility:hidden} +.route-sheet-back>.route-sheet-surface{visibility:hidden} +@media(min-width:1280px){ + .bound-reading .book-sidebar{transform:none;width:285px;padding:30px 25px;box-shadow:none;border-width:0 1px 0 0;background:#eee2c7;z-index:30} + .bound-reading .bound-reader{margin-left:285px;padding-inline:18px} + + .bound-reading .sidebar-group a{font-size:19px;line-height:1.3;padding:9px 5px}.bound-reading .sidebar-group h2{font-size:12px;line-height:1.6;letter-spacing:1px}.bound-reading .back-to-world{font-size:15px} + .bound-toolbar{padding-inline:8px;gap:16px}.bound-toolbar>.brand{display:none}.bound-location{margin-left:0}.bound-location>a{font:21px var(--serif)} + .bound-reading .bound-tools{gap:5px}.bound-reading .bound-tools .icon-button{width:38px;font-size:16px}.bound-reading .bound-mode{font-size:17px} + .bound-reading.contents-collapsed .book-sidebar{transform:translateX(-105%)}.bound-reading.contents-collapsed .bound-reader{margin-left:0}.bound-reading.contents-collapsed .bound-toolbar>.brand{display:flex} + .bound-reading.menu-open .sidebar-scrim{display:none} +} +@media(min-width:1800px){.bound-reading .book-sidebar{width:310px;padding:35px 27px}.bound-reading .bound-reader{margin-left:310px}.bound-reading .sidebar-group a{font-size:22px}.bound-reading .sidebar-group h2{font-size:12px}.bound-reading .bound-tools{gap:9px}.bound-reading .bound-tools .icon-button{width:46px}.contents-toggle{font-size:25px;padding:12px 20px}.bound-location>a{font-size:25px}} +@media(max-width:1279px){.bound-toolbar{flex-wrap:wrap;height:126px;padding:10px 12px;gap:8px}.bound-toolbar>.brand{margin-right:auto}.bound-location{display:none}.bound-tools{width:100%;justify-content:space-between;margin:0}.bound-volume{height:calc(100svh - 225px)}.bound-tools .contents-toggle{font-size:18px;padding:8px 12px;min-height:40px}.bound-tools .icon-button{width:34px}.bound-tools{gap:0}.bound-mode{font-size:15px}} +@media(max-width:760px){.brand{gap:11px}.bound-toolbar{height:122px}.bound-tools .icon-button{width:30px}.bound-tools #smaller-text,.bound-tools #larger-text{display:inline-flex}.bound-tools .contents-toggle{font-size:18px;padding:8px 10px;gap:6px}.bound-volume{height:calc(100svh - 220px);min-height:440px}.bound-tools .bound-mode{font-size:14px}.folio-content h1 .manuscript-mark{width:56px!important;height:56px;margin-bottom:18px!important}} + + +@media(min-width:1800px){.site-header{height:136px}.site-header .crafted-brand{--mark-size:80px;--brand-title:48px;--brand-caption:18px;--title-track:9px}} +@media(max-width:1279px){.site-header{height:112px}.site-header .crafted-brand{--mark-size:62px;--brand-title:40px;--brand-caption:15px;--title-track:7px;--caption-track:2.4px;gap:16px}.bound-toolbar{height:145px}.bound-volume{height:calc(100svh - 244px)}.bound-toolbar .crafted-brand{--mark-size:58px;--brand-title:38px;--brand-caption:15px;--title-track:6px;--caption-track:1.7px;gap:14px}} +@media(max-width:760px){.site-header{width:calc(100% - 36px);height:102px;padding:0;top:0;margin-top:0}.site-header nav{gap:14px}.site-header .crafted-brand{--mark-size:48px;--brand-title:34px;--brand-caption:14px;--title-track:5px;--caption-track:1.2px;--word-gap:5px;gap:11px}.bound-toolbar{height:145px}.bound-volume{height:calc(100svh - 244px)}.bound-toolbar .crafted-brand{--mark-size:52px;--brand-title:36px;--brand-caption:14px;--title-track:6px;--caption-track:1.9px}.site-footer .crafted-brand{--mark-size:38px;--brand-title:26px;--brand-caption:12px;--title-track:3px;--caption-track:1px;gap:10px}} diff --git a/web/scripts/book-model.ts b/web/scripts/book-model.ts new file mode 100644 index 0000000..325aaa5 --- /dev/null +++ b/web/scripts/book-model.ts @@ -0,0 +1,119 @@ +import { createHash } from 'node:crypto'; +import type { + BookGroup, + BookNode, + ReaderBook, + ReaderPage +} from '../src/book.ts'; +import type { MdBook, MdBookChapter, MdBookItem } from './mdbook-model.ts'; +import { presentChapter } from './reader-presentation.ts'; +import { sourceMetadata } from './source-localization.ts'; +import { englishMessages } from '../src/ui-messages.ts'; +import type { UIMessages } from '../src/ui-messages.ts'; + +export function htmlPath(chapter: MdBookChapter): string | null { + return chapter.path?.replace(/\.md$/, '.html') || null; +} +export function readerSlug(chapter: MdBookChapter): string | null { + return (chapter.source_path || chapter.path) === 'index.md' + ? 'introduction.html' + : htmlPath(chapter); +} +export function chaptersOf(book: MdBook): MdBookChapter[] { + const chapters: MdBookChapter[] = []; + const visit = (items: MdBookItem[]): void => { + for (const item of items) + if (typeof item === 'object' && 'Chapter' in item) { + chapters.push(item.Chapter); + visit(item.Chapter.sub_items); + } + }; + visit(book.sections); + return chapters; +} + +/** Structure comes exclusively from the processed Book; rendered fragments come from mdBook HTML. */ +export function transformBook( + book: MdBook, + rendered: ReadonlyMap, + messages: UIMessages = englishMessages +): ReaderBook { + const chapters = chaptersOf(book); + const welcome = + sourceMetadata( + chapters.find((chapter) => chapter.source_path === 'index.md')?.content || + '' + ).parts?.Welcome || 'Welcome'; + const routes = new Map(); + for (const chapter of chapters) { + const native = htmlPath(chapter), + slug = readerSlug(chapter); + if (native && slug) { + if (routes.has(native)) + throw new Error('Duplicate mdBook chapter path: ' + native); + routes.set(native, slug); + } + } + const pages: ReaderPage[] = [], + groups: BookGroup[] = []; + let group: BookGroup | null = null; + const visit = ( + items: MdBookItem[], + parentId: string | null = null + ): BookNode[] => { + const nodes: BookNode[] = []; + for (const item of items) { + if (item === 'Separator') { + nodes.push({ kind: 'separator' }); + continue; + } + if ('PartTitle' in item) { + group = { title: item.PartTitle, pages: [] }; + groups.push(group); + nodes.push({ kind: 'part', title: item.PartTitle }); + continue; + } + const chapter = item.Chapter, + native = htmlPath(chapter), + slug = readerSlug(chapter); + const id = chapter.source_path || chapter.path; + if (!native || !slug || !id) { + nodes.push(...visit(chapter.sub_items, parentId)); + continue; + } + const html = rendered.get(native); + if (html === undefined) + throw new Error('Missing mdBook HTML for ' + native); + const presentation = presentChapter(html, native, routes, messages); + const page: ReaderPage = { + id, + title: chapter.name, + source: chapter.source_path || chapter.path || '', + group: group?.title || welcome, + slug, + hash: createHash('sha256').update(chapter.content).digest('hex'), + markdown: chapter.content, + ...presentation, + minutes: Math.max( + 1, + Math.ceil(presentation.text.split(/\s+/).length / 220) + ), + parentId, + children: [] + }; + pages.push(page); + group?.pages.push(slug); + const children = visit(chapter.sub_items, id); + page.children = children + .filter( + (node): node is Extract => + node.kind === 'chapter' + ) + .map((node) => node.id); + nodes.push({ kind: 'chapter', id, title: chapter.name, children }); + } + return nodes; + }; + const toc = visit(book.sections); + return { pages, groups, toc }; +} diff --git a/web/scripts/book-validation.ts b/web/scripts/book-validation.ts new file mode 100644 index 0000000..6f1882c --- /dev/null +++ b/web/scripts/book-validation.ts @@ -0,0 +1,107 @@ +import assert from 'node:assert/strict'; +import { parseHTML } from 'linkedom'; +import type { ReaderBook } from '../src/book.ts'; +import { englishMessages } from '../src/ui-messages.ts'; +import type { UIMessages } from '../src/ui-messages.ts'; +export function validateMessages( + value: unknown, + locale: string +): asserts value is UIMessages { + if (!value || typeof value !== 'object' || Array.isArray(value)) + throw Error(locale + ': invalid UI dictionary'); + assert.deepEqual( + Object.keys(value).sort(), + Object.keys(englishMessages).sort(), + locale + ': UI keys' + ); + if ( + Object.values(value).some( + (message) => typeof message !== 'string' || !message.trim() + ) + ) + throw Error(locale + ': empty interface message'); +} +function technicalFacts(html: string) { + const { document } = parseHTML('' + html + ''); + const texts = (selector: string) => + [...document.querySelectorAll(selector)] + .map((node) => node.textContent || '') + .sort(); + const attributes = (selector: string, name: string) => + [...document.querySelectorAll(selector)] + .map((node) => node.getAttribute(name) || '') + .sort(); + return { + code: texts('pre code'), + inline: texts('code:not(pre code)'), + math: texts('annotation[encoding="application/x-tex"]'), + links: attributes('a[href]', 'href'), + images: [...document.querySelectorAll('img')] + .map((node) => + JSON.stringify([ + node.getAttribute('src') || '', + node.getAttribute('srcset') || '' + ]) + ) + .sort(), + media: [...document.querySelectorAll('iframe,video,audio,source,track')] + .map((node) => + JSON.stringify([ + node.localName, + node.getAttribute('src') || '', + node.getAttribute('srcset') || '', + node.getAttribute('poster') || '', + node.localName === 'iframe' ? node.getAttribute('title') || '' : '' + ]) + ) + .sort() + }; +} +/** Validate the complete edition before replacing any published reader JSON. */ +export function validateReaderEdition( + book: ReaderBook, + canonical: ReaderBook, + locale: string +): void { + assert.ok(canonical.pages.length > 0, 'Canonical book is empty'); + assert.deepEqual( + book.pages.map((page) => [ + page.id, + page.slug, + page.source, + page.parentId, + page.children + ]), + canonical.pages.map((page) => [ + page.id, + page.slug, + page.source, + page.parentId, + page.children + ]), + locale + ': canonical identity/hierarchy' + ); + assert.deepEqual( + book.groups.map((group) => group.pages), + canonical.groups.map((group) => group.pages), + locale + ': part membership' + ); + for (const [index, page] of book.pages.entries()) { + const original = canonical.pages[index]!; + assert.deepEqual( + technicalFacts(page.html), + technicalFacts(original.html), + locale + ' ' + page.slug + ': protected technical content' + ); + assert.deepEqual( + page.headings.map((heading) => heading.id), + original.headings.map((heading) => heading.id), + locale + ' ' + page.slug + ': canonical heading IDs' + ); + assert.deepEqual( + page.anchorAliases, + original.anchorAliases, + locale + ' ' + page.slug + ': legacy anchors' + ); + } +} diff --git a/web/scripts/book.ts b/web/scripts/book.ts new file mode 100644 index 0000000..4aa521f --- /dev/null +++ b/web/scripts/book.ts @@ -0,0 +1,129 @@ +import fs from 'node:fs/promises'; +import path from 'node:path'; +import { buildMdBook, projectRoot } from './mdbook.ts'; +import { parseMdBookExport } from './mdbook-model.ts'; +import { chaptersOf, htmlPath, transformBook } from './book-model.ts'; +import { addHeadingAliases } from './heading-aliases.ts'; +import { languages } from '../src/locale-routing.ts'; +import type { LanguageCode } from '../src/locale-routing.ts'; +import type { MessageKey } from '../src/ui-messages.ts'; +import type { ReaderBook } from '../src/book.ts'; +import { validateReaderEdition, validateMessages } from './book-validation.ts'; +import {sourceMetadata,translatedSourcePath} from './source-localization.ts'; + +export async function compileReaderBook( + locale: LanguageCode +): Promise<{ reader: ReaderBook; assets: string }> { + const output = await buildMdBook(locale); + const { book } = parseMdBookExport( + JSON.parse(await fs.readFile(output.json, 'utf8')) as unknown + ); + const rendered = new Map(); + for (const chapter of chaptersOf(book)) { + const file = htmlPath(chapter); + if (file) + rendered.set( + file, + await fs.readFile(path.join(output.html, file), 'utf8') + ); + } + const messages: unknown = JSON.parse( + await fs.readFile( + path.join(projectRoot, 'web/locales/ui', locale + '.json'), + 'utf8' + ) + ); + validateMessages(messages, locale); + const reader = transformBook(book, rendered, messages); + // A failed mdBook support probe can otherwise silently yield English chapters + // alongside localized UI. Check the selected source's identity before publishing. + if(locale!=='en')for(const page of reader.pages){ + const filename=path.join(projectRoot,'src',translatedSourcePath(page.source,locale)); + let source:string; + try{source=await fs.readFile(filename,'utf8');}catch(error){if(error instanceof Error&&'code'in error&&error.code==='ENOENT')continue;throw error;} + const metadata=sourceMetadata(source); + if(metadata.title&&page.title!==metadata.title)throw Error(`${locale} ${page.source}: mdBook did not select the translated source`); + } + addHeadingAliases(reader); + if (locale === 'en') { + const displayTitle = (title: string): string => + Object.hasOwn(messages, title) ? messages[title as MessageKey] : title; + for (const page of reader.pages) page.title = displayTitle(page.title); + const visit = (nodes: ReaderBook['toc']): void => { + for (const node of nodes) + if (node.kind === 'chapter') { + node.title = displayTitle(node.title); + visit(node.children); + } + }; + visit(reader.toc); + } + return { reader, assets: path.join(output.html, 'assets') }; +} + +/** Finish compiling every requested locale before publishing reader data. */ +export async function buildReaderBook( + locales: readonly LanguageCode[] = languages.map((language) => language.code) +): Promise { + const results = new Map< + LanguageCode, + Awaited> + >(); + for (const locale of locales) + results.set(locale, await compileReaderBook(locale)); + const destination = path.join(projectRoot, 'web/public'); + // Keep the existing edition-independent estimates; whitespace counts are not comparable across scripts. + const canonical = + results.get('en')?.reader || + (JSON.parse( + await fs.readFile(path.join(destination, 'content/en.json'), 'utf8') + ) as ReaderBook); + for (const [locale, { reader }] of results) { + if ( + reader.pages.length !== canonical.pages.length || + reader.pages.some( + (page, index) => + page.id !== canonical.pages[index]?.id || + page.slug !== canonical.pages[index]?.slug + ) + ) + throw Error( + 'Localized chapter identity/order differs from canonical book' + ); + for (const [index, page] of reader.pages.entries()) + page.minutes = canonical.pages[index]?.minutes || page.minutes; + validateReaderEdition(reader, canonical, locale); + } + await fs.mkdir(path.join(destination, 'content'), { recursive: true }); + const pending: Array<{ temporary: string; filename: string }> = []; + try { + for (const [locale, { reader, assets }] of results) { + const filename = path.join(destination, 'content', locale + '.json'), + temporary = filename + '.tmp'; + pending.push({ temporary, filename }); + await fs.writeFile(temporary, JSON.stringify(reader)); + if (locale === 'en') { + const legacy = path.join(destination, 'content.json'); + pending.push({ temporary: legacy + '.tmp', filename: legacy }); + await fs.writeFile(legacy + '.tmp', JSON.stringify(reader)); + await fs.cp(assets, path.join(destination, 'book-assets/assets'), { + recursive: true + }); + } + } + for (const { temporary, filename } of pending) + await fs.rename(temporary, filename); + } finally { + await Promise.all( + pending.map(({ temporary }) => fs.rm(temporary, { force: true })) + ); + } + console.log( + `mdBook supplied ${results.size} localized reader models (${results.values().next().value?.reader.pages.length || 0} chapters each).` + ); +} +if ( + process.argv[1] && + path.resolve(process.argv[1]) === path.resolve(import.meta.filename) +) + await buildReaderBook(); diff --git a/web/scripts/check-locales.ts b/web/scripts/check-locales.ts new file mode 100644 index 0000000..286365d --- /dev/null +++ b/web/scripts/check-locales.ts @@ -0,0 +1,30 @@ +import fs from 'node:fs/promises'; +import path from 'node:path'; +import { languages } from '../src/locale-routing.ts'; +import type { ReaderBook } from '../src/book.ts'; +import { validateReaderEdition, validateMessages } from './book-validation.ts'; +const web = path.resolve(import.meta.dirname, '..'); +const load = async (locale: string): Promise => + JSON.parse( + await fs.readFile( + path.join(web, 'public/content', locale + '.json'), + 'utf8' + ) + ) as ReaderBook; +const canonical = await load('en'); +for (const { code } of languages) { + const messages: unknown = JSON.parse( + await fs.readFile(path.join(web, 'locales/ui', code + '.json'), 'utf8') + ); + validateMessages(messages, code); + const book = await load(code); + validateReaderEdition(book, canonical, code); + console.log( + code + + ': ' + + book.pages.length + + ' chapters with canonical identities, protected technical content and ' + + Object.keys(messages).length + + ' UI messages.' + ); +} diff --git a/web/scripts/heading-aliases.ts b/web/scripts/heading-aliases.ts new file mode 100644 index 0000000..6785f3b --- /dev/null +++ b/web/scripts/heading-aliases.ts @@ -0,0 +1,25 @@ +import type { ReaderBook } from '../src/book.ts'; +// Public links generated before the native mdBook anchor migration remain valid. +const aliases: Readonly>>> = { + 'concepts/expression-problem.html': { + 'haskell-functional-adt': 'haskell-functional--adt', + 'wadlers-proposed-solution-gj-virtual-types': + 'wadlers-proposed-solution-gj--virtual-types' + }, + 'concepts/referential_transparency.html': { + 'scala-cats-cats-effect': 'scala-cats--cats-effect' + }, + 'concepts/free_monad.html': { + 'why-free-monad-these-patterns': 'why-free-monad--these-patterns' + } +}; +export function addHeadingAliases(book: ReaderBook): void { + for (const [slug, entries] of Object.entries(aliases)) { + const page = book.pages.find((candidate) => candidate.slug === slug); + if (!page) throw Error('Missing compatibility chapter: ' + slug); + for (const target of Object.values(entries)) + if (!page.headings.some((heading) => heading.id === target)) + throw Error('Invalid compatibility heading: ' + target); + page.anchorAliases = { ...entries }; + } +} diff --git a/web/scripts/mdbook-json.ts b/web/scripts/mdbook-json.ts new file mode 100644 index 0000000..f591010 --- /dev/null +++ b/web/scripts/mdbook-json.ts @@ -0,0 +1,13 @@ +import fs from 'node:fs/promises'; +import path from 'node:path'; +import { parseMdBookExport, record } from './mdbook-model.ts'; + +// mdBook renderer protocol: a single RenderContext arrives on stdin. +process.stdin.setEncoding('utf8'); +let input = ''; +for await (const chunk of process.stdin) input += String(chunk); +const context = record(JSON.parse(input) as unknown, 'RenderContext'); +if (typeof context.destination !== 'string') throw new Error('RenderContext.destination is missing'); +const exported = parseMdBookExport({ version: context.version, book: context.book }); +await fs.mkdir(context.destination, { recursive: true }); +await fs.writeFile(path.join(context.destination, 'book.json'), JSON.stringify(exported)); diff --git a/web/scripts/mdbook-line-endings.ts b/web/scripts/mdbook-line-endings.ts new file mode 100644 index 0000000..80110ea --- /dev/null +++ b/web/scripts/mdbook-line-endings.ts @@ -0,0 +1,22 @@ +import path from 'node:path'; +import { parseMdBookExport, record } from './mdbook-model.ts'; +import type { MdBook, MdBookItem } from './mdbook-model.ts'; + +/** mdbook-katex 0.9.4 removes LF from generated MathML but leaves CR, breaking Markdown on Windows. */ +export function normalizeBookLineEndings(book: MdBook): MdBook { + const normalize = (items: MdBookItem[]): MdBookItem[] => items.map(item => typeof item === 'object' && 'Chapter' in item + ? { Chapter: { ...item.Chapter, content: item.Chapter.content.replace(/\r\n?/g, '\n'), sub_items: normalize(item.Chapter.sub_items) } } + : item); + return { ...book, sections: normalize(book.sections) }; +} +if (process.argv[1] && path.resolve(process.argv[1]) === path.resolve(import.meta.filename)) { + if (process.argv[2] !== 'supports') { + process.stdin.setEncoding('utf8'); let input = ''; + for await (const chunk of process.stdin) input += String(chunk); + const envelope = JSON.parse(input) as unknown; + if (!Array.isArray(envelope) || envelope.length !== 2) throw new Error('Expected mdBook preprocessor context and Book'); + const context = record(envelope[0], 'PreprocessorContext'); + const { book } = parseMdBookExport({ version: context.mdbook_version, book: envelope[1] }); + process.stdout.write(JSON.stringify(normalizeBookLineEndings(book))); + } +} diff --git a/web/scripts/mdbook-localization.ts b/web/scripts/mdbook-localization.ts new file mode 100644 index 0000000..4690d70 --- /dev/null +++ b/web/scripts/mdbook-localization.ts @@ -0,0 +1,43 @@ +import path from 'node:path'; +import { record, parseMdBookExport } from './mdbook-model.ts'; +import { localizeSources } from './source-localization.ts'; +import { normalizeLanguage } from '../src/locale-routing.ts'; + +if ( + process.argv[1] && + path.resolve(process.argv[1]) === path.resolve(import.meta.filename) +) { + if (process.argv[2] === 'supports') { + // Let Node close its Windows handles normally; forced process.exit can abort + // the support probe and make mdBook silently skip source localization. + process.exitCode=['html','reader-json'].includes(process.argv[3]||'')?0:1; + } else { + process.stdin.setEncoding('utf8'); + let input = ''; + for await (const chunk of process.stdin) input += String(chunk); + const envelope: unknown = JSON.parse(input); + if (!Array.isArray(envelope) || envelope.length !== 2) + throw Error('Expected mdBook preprocessor context and Book'); + const context = record(envelope[0], 'PreprocessorContext'), + config = record(context.config, 'mdBook configuration'), + settings = record(config.book, 'book configuration'); + const locale = normalizeLanguage(settings.language); + if (!locale) throw Error('Unsupported mdBook language'); + if (typeof settings.src !== 'string') + throw Error('Missing book source directory'); + const { book } = parseMdBookExport({ + version: context.mdbook_version, + book: envelope[1] + }); + process.stdout.write( + JSON.stringify( + await localizeSources( + book, + path.resolve(String(context.root), settings.src), + locale, + context.renderer==='reader-json'?message=>console.error(message):()=>{} + ) + ) + ); + } +} diff --git a/web/scripts/mdbook-math-annotations.ts b/web/scripts/mdbook-math-annotations.ts new file mode 100644 index 0000000..e42e546 --- /dev/null +++ b/web/scripts/mdbook-math-annotations.ts @@ -0,0 +1,31 @@ +import path from 'node:path'; +import { parseMdBookExport, record } from './mdbook-model.ts'; +import type { MdBook, MdBookItem } from './mdbook-model.ts'; +import { parseHTML } from 'linkedom'; + +/** Protect KaTeX's TeX annotation from a second Markdown escape pass. */ +export function protectMathAnnotations(book: MdBook): MdBook { + const protect = (items: MdBookItem[]): MdBookItem[] => items.map(item => typeof item === 'object' && 'Chapter' in item + ? { Chapter: { ...item.Chapter, content: item.Chapter.content.replace( + /(]*encoding=["']application\/x-tex["'][^>]*>)([\s\S]*?)(<\/annotation>)/gi, + (_match: string, open: string, tex: string, close: string) => { + const { document } = parseHTML('' + tex + ''); + const decoded = document.querySelector('span')?.textContent ?? ''; + return open + Array.from(decoded, character => '&#' + character.codePointAt(0) + ';').join('') + close; + }, + ), sub_items: protect(item.Chapter.sub_items) } } + : item); + return { ...book, sections: protect(book.sections) }; +} + +if (process.argv[1] && path.resolve(process.argv[1]) === path.resolve(import.meta.filename)) { + if (process.argv[2] !== 'supports') { + process.stdin.setEncoding('utf8'); let input = ''; + for await (const chunk of process.stdin) input += String(chunk); + const envelope = JSON.parse(input) as unknown; + if (!Array.isArray(envelope) || envelope.length !== 2) throw new Error('Expected mdBook preprocessor context and Book'); + const context = record(envelope[0], 'PreprocessorContext'); + const { book } = parseMdBookExport({ version: context.mdbook_version, book: envelope[1] }); + process.stdout.write(JSON.stringify(protectMathAnnotations(book))); + } +} diff --git a/web/scripts/mdbook-model.ts b/web/scripts/mdbook-model.ts new file mode 100644 index 0000000..d56050e --- /dev/null +++ b/web/scripts/mdbook-model.ts @@ -0,0 +1,38 @@ +/** mdBook's wire representation. Chapter content remains preprocessed Markdown. */ +export interface MdBookChapter { + name: string; + content: string; + number: number[] | null; + sub_items: MdBookItem[]; + path: string | null; + source_path: string | null; + parent_names: string[]; +} +export type MdBookItem = 'Separator' | { PartTitle: string } | { Chapter: MdBookChapter }; +export interface MdBook { sections: MdBookItem[]; __non_exhaustive?: null } +export interface MdBookExport { version: string; book: MdBook } +export function record(value: unknown, label: string): Record { + if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error(`${label}: expected an object`); + return value as Record; +} +export function parseMdBookExport(value: unknown): MdBookExport { + const root = record(value, 'mdBook export'); + if (typeof root.version !== 'string' || !root.version.startsWith('0.4.')) throw new Error('Expected mdBook 0.4.x output'); + const book = record(root.book, 'mdBook Book'); + const checkItems = (items: unknown): void => { + if (!Array.isArray(items)) throw new Error('mdBook sections/sub_items must be an array'); + for (const item of items as unknown[]) { + if (item === 'Separator') continue; + const node = record(item, 'BookItem'); + if (typeof node.PartTitle === 'string') continue; + const chapter = record(node.Chapter, 'Chapter'); + for (const key of ['name', 'content']) if (typeof chapter[key] !== 'string') throw new Error(`Chapter.${key} must be a string`); + for (const key of ['path', 'source_path']) if (chapter[key] !== null && typeof chapter[key] !== 'string') throw new Error(`Chapter.${key} must be a string or null`); + if (!Array.isArray(chapter.parent_names) || !chapter.parent_names.every(v => typeof v === 'string')) throw new Error('Chapter.parent_names must be strings'); + if (chapter.number !== null && (!Array.isArray(chapter.number) || !chapter.number.every(v => typeof v === 'number'))) throw new Error('Chapter.number must be numeric or null'); + checkItems(chapter.sub_items); + } + }; + checkItems(book.sections); + return value as MdBookExport; +} diff --git a/web/scripts/mdbook.ts b/web/scripts/mdbook.ts new file mode 100644 index 0000000..93ab1bb --- /dev/null +++ b/web/scripts/mdbook.ts @@ -0,0 +1,99 @@ +import fs from 'node:fs/promises'; +import path from 'node:path'; +import { spawnSync } from 'node:child_process'; +import { parse, stringify } from 'smol-toml'; +import { record } from './mdbook-model.ts'; +import type { LanguageCode } from '../src/locale-routing.ts'; + +export const projectRoot = path.resolve(import.meta.dirname, '../..'); +export const cacheRoot = path.resolve(projectRoot, 'web/.cache/mdbook'); + +/** Derive a web-only mdBook build without changing the original publishing config. */ +export async function buildMdBook( + locale: LanguageCode = 'en' +): Promise<{ json: string; html: string }> { + const directory = locale === 'en' ? cacheRoot : path.join(cacheRoot, locale); + const source = await fs.readFile(path.join(projectRoot, 'book.toml'), 'utf8'); + const config = parse(source); + const book = record(config.book, 'book.toml [book]'); + const sourceDirectory = typeof book.src === 'string' ? book.src : 'src'; + book.src = path.resolve(projectRoot, sourceDirectory); + book.language = locale; + const output = record(config.output ?? {}, 'book.toml [output]'); + const html = record(output.html ?? {}, '[output.html]'); + for (const key of ['additional-css', 'additional-js']) { + const files = html[key]; + if (Array.isArray(files)) + html[key] = files.map((file) => path.resolve(projectRoot, String(file))); + } + const preprocessors = record(config.preprocessor ?? {}, 'preprocessors'); + preprocessors['reader-source-translations'] = { + command: `"${process.execPath}" "${path.join(import.meta.dirname, 'mdbook-localization.ts')}"`, + before: ['links', 'index', 'reader-line-endings', 'admonish', 'katex'] + }; + preprocessors['reader-line-endings'] = { + command: `"${process.execPath}" "${path.join(import.meta.dirname, 'mdbook-line-endings.ts')}"`, + before: ['admonish', 'katex'] + }; + preprocessors['reader-math-annotations'] = { + command: `"${process.execPath}" "${path.join(import.meta.dirname, 'mdbook-math-annotations.ts')}"`, + after: ['katex'] + }; + for (const value of Object.values(preprocessors)) { + const settings = record(value, 'preprocessor settings'); + if ( + Array.isArray(settings.renderers) && + settings.renderers.includes('html') + ) + settings.renderers = [...settings.renderers, 'reader-json']; + } + const admonish = record(preprocessors.admonish, 'admonish preprocessor'); + const renderers = record( + admonish.renderer ?? {}, + 'admonish renderer settings' + ); + renderers['reader-json'] = { render_mode: 'html' }; + admonish.renderer = renderers; + const katex = record(preprocessors.katex, 'KaTeX preprocessor'); + katex['pre-render'] = true; + katex['no-css'] = true; + katex.output = 'htmlAndMathml'; + config.preprocessor = preprocessors as typeof config.preprocessor; + config.output = { + html, + 'reader-json': { + command: `"${process.execPath}" "${path.join(import.meta.dirname, 'mdbook-json.ts')}"` + } + } as typeof config.output; + config.build = { + ...record(config.build ?? {}, '[build]'), + 'build-dir': path.join(directory, 'build') + } as typeof config.build; + await fs.mkdir(directory, { recursive: true }); + await fs.writeFile(path.join(directory, 'book.toml'), stringify(config)); + const command = process.env.MDBOOK_BINARY || 'mdbook'; + const result = spawnSync(command, ['build', directory], { + cwd: projectRoot, + stdio: 'inherit', + windowsHide: true + }); + if (result.error) + throw new Error( + 'Cannot run mdbook. Install the pinned mdBook/admonish/KaTeX tools documented in web/README.md, or set MDBOOK_BINARY.', + { cause: result.error } + ); + if (result.status !== 0) + throw new Error( + `mdBook failed (${result.status}); reader data was not replaced` + ); + return { + json: path.join(directory, 'build/reader-json/book.json'), + html: path.join(directory, 'build/html') + }; +} + +if ( + process.argv[1] && + path.resolve(process.argv[1]) === path.resolve(import.meta.filename) +) + await buildMdBook(); diff --git a/web/scripts/measure-startup.ts b/web/scripts/measure-startup.ts new file mode 100644 index 0000000..494f94a --- /dev/null +++ b/web/scripts/measure-startup.ts @@ -0,0 +1,25 @@ +/** Same-engine local comparison; these measurements are not production SLAs. */ +import fs from 'node:fs/promises'; +import path from 'node:path'; +import {preview} from 'vite'; +import {chromium} from 'playwright'; +const root=path.resolve(process.argv[2]||path.resolve(import.meta.dirname,'..')); +const output=path.resolve(import.meta.dirname,'../../output/merge-acceptance',process.argv[3]||'startup.json'); +const server=await preview({root,preview:{host:'127.0.0.1',port:4177,strictPort:true}}); +const browser=await chromium.launch({headless:true,...(process.env.PLAYWRIGHT_CHROMIUM_EXECUTABLE?{executablePath:process.env.PLAYWRIGHT_CHROMIUM_EXECUTABLE}:{})}); +const samples:unknown[]=[]; +try{ + for(let i=0;i<5;i++){ + const context=await browser.newContext({viewport:{width:1440,height:960},reducedMotion:'reduce'}),page=await context.newPage(); + await page.addInitScript(()=>localStorage.setItem('alux-programming-language','en')); + const start=Date.now(); + await page.goto('http://127.0.0.1:4177/concepts/operational_semantics.html'); + await page.locator('#folio-position').filter({hasText:/\//}).waitFor({timeout:45000}); + const readyMs=Date.now()-start; + const resources=await page.evaluate(()=>performance.getEntriesByType('resource').map(entry=>({name:entry.name,bytes:(entry as PerformanceResourceTiming).transferSize}))); + samples.push({readyMs,requests:resources.length,bytes:resources.reduce((sum,r)=>sum+r.bytes,0)}); + await context.close(); + } + const report={root,browser:browser.version(),viewport:'1440x960',coldContext:true,reducedMotion:true,samples}; + await fs.writeFile(output,JSON.stringify(report,null,2));console.log(JSON.stringify(report)); +}finally{await browser.close();await new Promise((resolve,reject)=>server.httpServer.close(error=>error?reject(error):resolve()));} diff --git a/web/scripts/migrate-translations.ts b/web/scripts/migrate-translations.ts new file mode 100644 index 0000000..97feef6 --- /dev/null +++ b/web/scripts/migrate-translations.ts @@ -0,0 +1,372 @@ +/** One-time reverse conversion of a frozen reader snapshot; never used to compile a book. */ +import fs from 'node:fs/promises'; +import path from 'node:path'; +import TurndownService from 'turndown'; +import { gfm } from 'turndown-plugin-gfm'; +import { parseHTML } from 'linkedom'; +import { projectRoot } from './mdbook.ts'; +import { readingArt } from './reader-presentation.ts'; +import { languages } from '../src/locale-routing.ts'; +import type { ReaderBook, ReaderPage } from '../src/book.ts'; +import type { SourceMetadata } from './source-localization.ts'; + +interface CodeFence { + info: string; + code: string; +} +function codeFences(markdown: string): CodeFence[] { + const lines = markdown.replace(/\r\n?/g, '\n').split('\n'), + blocks: CodeFence[] = []; + for (let i = 0; i < lines.length; i++) { + const open = lines[i]?.match(/^([ \t]*)(`{3,}|~{3,})([^\n]*)$/); + if (!open) continue; + const indent = open[1] || '', + marker = open[2] || '```', + info = (open[3] || '').trim(), + body: string[] = []; + let end = i + 1; + for (; end < lines.length; end++) { + const line = lines[end] || ''; + if ( + new RegExp('^\\s*' + marker[0] + '{' + marker.length + ',}\\s*$').test( + line + ) + ) + break; + body.push(line.startsWith(indent) ? line.slice(indent.length) : line); + } + if (end === lines.length) + throw Error('Unterminated canonical source fence'); + if (info.startsWith('admonish')) + blocks.push(...codeFences(body.join('\n'))); + else blocks.push({ info, code: body.join('\n') }); + i = end; + } + return blocks; +} + +function cleanMigrationAttributes(node: HTMLElement): void { + for (const element of node.querySelectorAll( + '[data-source-code],[data-source-tex]' + )) { + element.removeAttribute('data-source-code'); + element.removeAttribute('data-source-tex'); + } +} + +export function markdownFromSnapshot( + page: ReaderPage, + canonicalMarkdown: string, + english: ReaderBook, + localized: ReaderBook +): string { + const blocks = codeFences(canonicalMarkdown), + seenCodes = new Set(); + const document = parseHTML( + '
' + page.html + '
' + ).document as unknown as Document; + const article = document.querySelector('article'); + if (!article) throw Error('Missing snapshot article'); + article + .querySelectorAll('.heading-anchor,.code-toolbar,.video-clip-range') + .forEach((node) => node.remove()); + const codes = [...article.querySelectorAll('pre code')]; + if (codes.length !== blocks.length) + throw Error( + page.slug + ': snapshot code count differs from canonical source' + ); + for (const [i, code] of codes.entries()) { + if (blocks[i]?.code !== code.textContent?.replace(/\n$/, '')) + throw Error(page.slug + ': canonical code differs at block ' + i); + code.parentElement?.setAttribute('data-source-code', String(i)); + } + const texSources: string[] = []; + for (const math of article.querySelectorAll( + '.math-display,.katex-display,.katex' + )) + if (!math.parentElement?.closest('.math-display,.katex-display,.katex')) { + const tex = math.querySelector( + 'annotation[encoding="application/x-tex"]' + )?.textContent; + if (tex === null || tex === undefined) + throw Error(page.slug + ': missing protected TeX'); + math.setAttribute('data-source-tex', String(texSources.push(tex) - 1)); + } + const relative = (target: string): string => + path.posix.relative(path.posix.dirname(page.source), target) || + path.posix.basename(target); + const originalArt = new Map( + Object.entries(readingArt).map(([source, runtime]) => [runtime, source]) + ); + for (const image of article.querySelectorAll('img[src]')) { + const src = image.getAttribute('src') || '', + original = originalArt.get(src); + if (original) image.setAttribute('src', relative(original)); + else if (src.startsWith('/book-assets/')) + image.setAttribute('src', relative(src.slice(13))); + } + for (const anchor of article.querySelectorAll('a[href]')) { + const href = anchor.getAttribute('href') || ''; + if (!href.startsWith('/')) continue; + const url = new URL(href, 'https://book.invalid'), + target = english.pages.find( + (candidate) => '/' + candidate.slug === url.pathname + ); + if (target) + anchor.setAttribute( + 'href', + relative(target.source) + url.search + url.hash + ); + } + const converter = new TurndownService({ + headingStyle: 'atx', + codeBlockStyle: 'fenced', + bulletListMarker: '*', + emDelimiter: '*', + strongDelimiter: '**' + }); + converter.use(gfm); + converter.addRule('canonical-heading', { + filter: ['h1', 'h2', 'h3', 'h4', 'h5', 'h6'], + replacement: (content, node) => + '\n\n' + + '#'.repeat(Number(node.nodeName.slice(1))) + + ' ' + + content.trim() + + (node.id ? ' {#' + node.id + '}' : '') + + '\n\n' + }); + converter.addRule('canonical-code', { + filter: (node) => + node.nodeName === 'PRE' && node.hasAttribute('data-source-code'), + replacement: (_content, node) => { + const i = Number(node.getAttribute('data-source-code')), + source = blocks[i]; + if (!source) throw Error(page.slug + ': invalid code identity'); + seenCodes.add(i); + const fence = '`'.repeat( + Math.max( + 3, + ...[...source.code.matchAll(/`+/g)].map( + (match) => match[0].length + 1 + ) + ) + ); + return ( + '\n\n' + + fence + + source.info + + '\n' + + source.code + + '\n' + + fence + + '\n\n' + ); + } + }); + const texFor = (node: HTMLElement): string => { + const index = node.getAttribute('data-source-tex'), + tex = index === null ? undefined : texSources[Number(index)]; + if (tex === undefined) throw Error(page.slug + ': missing math identity'); + return tex; + }; + converter.addRule('display-math', { + filter: (node) => + node.classList.contains('math-display') || + node.classList.contains('katex-display'), + replacement: (_content, node) => + node.hasAttribute('data-source-tex') + ? '\n\n$$' + texFor(node) + '$$\n\n' + : '' + }); + converter.addRule('inline-math', { + filter: (node) => + node.classList.contains('katex') && + !node.closest('.katex-display,.math-display'), + replacement: (_content, node) => '$' + texFor(node) + '$' + }); + converter.addRule('punctuation-emphasis', { + filter: ['strong', 'b', 'em', 'i'], + replacement: (content, node) => { + const first = content[0] || '', + last = content.at(-1) || '', + prev = node.previousSibling?.textContent?.at(-1) || ' ', + next = node.nextSibling?.textContent?.[0] || ' '; + const punct = (character: string): boolean => + /[\p{P}\p{S}]/u.test(character), + space = (character: string): boolean => /\s/u.test(character); + const tag = ['STRONG', 'B'].includes(node.nodeName) ? 'strong' : 'em', + marker = tag === 'strong' ? '**' : '*'; + // CommonMark cannot close punctuation-adjacent emphasis against a word. Keep inline HTML rather than inserting prose spaces. + return (punct(first) && !space(prev) && !punct(prev)) || + (punct(last) && !space(next) && !punct(next)) + ? '<' + tag + '>' + content + '' + : marker + content + marker; + } + }); + converter.addRule('admonition', { + filter: (node) => node.classList.contains('admonition'), + replacement: (_content, node) => { + const clone = node.cloneNode(true) as HTMLElement, + title = clone.querySelector('.admonition-title'), + label = title?.textContent || 'note'; + title?.remove(); + const kind = + node.className.split(/\s+/).find((name) => name !== 'admonition') || + 'note', + body = converter.turndown(clone.innerHTML); + const fence = '`'.repeat( + Math.max( + 3, + ...[...body.matchAll(/^`+/gm)].map((match) => match[0].length + 1) + ) + ); + return ( + '\n\n' + + fence + + 'admonish ' + + kind + + ' title=' + + JSON.stringify(label) + + '\n' + + body + + '\n' + + fence + + '\n\n' + ); + } + }); + converter.addRule('raw-media', { + filter: (node) => + ['IFRAME', 'FIGURE', 'SUMMARY'].includes(node.nodeName) || + (node.nodeName === 'IMG' && node.hasAttribute('style')), + replacement: (_content, node) => { + const clone = node.cloneNode(true) as HTMLElement; + cleanMigrationAttributes(clone); + return node.nodeName === 'IMG' + ? clone.outerHTML + : '\n\n' + clone.outerHTML + '\n\n'; + } + }); + converter.addRule('details', { + filter: ['details'], + replacement: (_content, node) => { + const clone = node.cloneNode(true) as HTMLElement, + summary = clone.querySelector('summary'); + summary?.remove(); + if (summary) cleanMigrationAttributes(summary as HTMLElement); + return ( + '\n\n
\n' + + (summary?.outerHTML || '') + + '\n\n' + + converter.turndown(clone.innerHTML) + + '\n\n
\n\n' + ); + } + }); + const body = converter.turndown(article.innerHTML); + if (seenCodes.size !== blocks.length) + throw Error(page.slug + ': omitted code block'); + const metadata: SourceMetadata = { title: page.title }; + if (page.source === 'index.md') + metadata.parts = Object.fromEntries([ + ['Welcome', page.group], + ...english.groups.map((group, i) => [ + group.title, + localized.groups[i]?.title || group.title + ]) + ]); + return '\n\n' + body + '\n'; +} + +export async function migrateTranslations( + baselineDirectory: string, + destination: string, + replace = false +): Promise { + const english = JSON.parse( + await fs.readFile(path.join(baselineDirectory, 'baseline-en.json'), 'utf8') + ) as ReaderBook; + const pending: Array<{ filename: string; markdown: string }> = [], + root = path.resolve(destination); + for (const { code } of languages) { + if (code === 'en') continue; + const localized = JSON.parse( + await fs.readFile( + path.join(baselineDirectory, `baseline-${code}.json`), + 'utf8' + ) + ) as ReaderBook; + if ( + localized.pages.length !== english.pages.length || + localized.pages.some( + (page, i) => + page.id !== english.pages[i]?.id || + page.source !== english.pages[i]?.source + ) + ) + throw Error(code + ': baseline chapter identity/order differs'); + for (const page of localized.pages) { + const filename = path.resolve( + root, + page.source.replace(/\.md$/, '.' + code + '.md') + ); + if (!page.source.endsWith('.md') || !filename.startsWith(root + path.sep)) + throw Error('Invalid canonical source path'); + if (!replace) { + try { + await fs.access(filename); + throw Error('Translation already exists: ' + filename); + } catch (error) { + if (!( + error instanceof Error && + 'code' in error && + error.code === 'ENOENT' + )) + throw error; + } + } + const source = await fs.readFile( + path.join(projectRoot, 'src', page.source), + 'utf8' + ); + pending.push({ + filename, + markdown: markdownFromSnapshot(page, source, english, localized) + }); + } + } + // Complete conversion and overwrite checks before touching any destination file. + for (const { filename, markdown } of pending) { + await fs.mkdir(path.dirname(filename), { recursive: true }); + await fs.writeFile(filename, markdown); + } + return pending.length; +} + +if ( + process.argv[1] && + path.resolve(process.argv[1]) === path.resolve(import.meta.filename) +) { + const args = process.argv.slice(2), + baseline = args[args.indexOf('--baseline') + 1], + destination = args[args.indexOf('--output') + 1]; + if ( + !args.includes('--baseline') || + !args.includes('--output') || + !baseline || + !destination + ) + throw Error( + 'Usage: node scripts/migrate-translations.ts --baseline --output [--replace]' + ); + console.log( + 'Migrated ' + + (await migrateTranslations( + path.resolve(baseline), + path.resolve(destination), + args.includes('--replace') + )) + + ' translated Markdown chapters.' + ); +} diff --git a/web/scripts/reader-presentation.ts b/web/scripts/reader-presentation.ts new file mode 100644 index 0000000..98a7e91 --- /dev/null +++ b/web/scripts/reader-presentation.ts @@ -0,0 +1,233 @@ +import { parseHTML } from 'linkedom'; +import hljs from 'highlight.js'; +import type { Heading } from '../src/book.ts'; +import { englishMessages, message } from '../src/ui-messages.ts'; +import type { UIMessages } from '../src/ui-messages.ts'; + +export const readingArt: Readonly> = { + 'assets/semantic-view.png': '/art/semantic-view.webp', + 'assets/design-by-meaning-rust.png': '/art/capability-crab.webp', + 'assets/concepts.png': '/art/concepts.webp', + 'assets/insights.png': '/art/insights.webp' +}; +export interface PresentedChapter { + html: string; + headings: Heading[]; + text: string; +} + +/** Presentation only: mdBook has already rendered Markdown, math and admonitions. */ +export function presentChapter( + nativeHTML: string, + nativePath: string, + routes: ReadonlyMap, + messages: UIMessages = englishMessages +): PresentedChapter { + const { document: nativeDocument } = parseHTML(nativeHTML); + const document = nativeDocument as unknown as Document; + const main = document.querySelector('main'); + if (!main) throw new Error(`${nativePath}: mdBook HTML has no main content`); + const root = document.createElement('article'); + root.innerHTML = main.innerHTML; + const base = new URL(nativePath, 'https://mdbook.invalid/'); + function address(value: string, image = false): string { + if (!value || /^(?:[a-z][a-z\d+.-]*:|\/\/|#)/i.test(value)) return value; + const url = new URL(value, base); + const resource = decodeURIComponent(url.pathname.slice(1)); + const route = routes.get(resource); + if (!image && route) return '/' + route + url.search + url.hash; + return ( + (readingArt[resource] || '/book-assets/' + resource) + + url.search + + url.hash + ); + } + for (const anchor of root.querySelectorAll('a[href]')) { + const href = anchor.getAttribute('href') || ''; + anchor.setAttribute('href', address(href)); + if (/^https?:/.test(href)) { + anchor.target = '_blank'; + anchor.rel = 'noopener noreferrer'; + } + } + for (const image of root.querySelectorAll('img[src]')) { + image.setAttribute('src', address(image.getAttribute('src') || '', true)); + // Reserve the exact square aspect ratio even in offscreen, lazy pagination probes. + if (Object.values(readingArt).includes(image.getAttribute('src') || '')) { + image.setAttribute('width', '512'); + image.setAttribute('height', '512'); + } + // Markdown images are lazy; inline raw-HTML marks preserve their original attributes. + if (!image.hasAttribute('style')) image.setAttribute('loading', 'lazy'); + } + for (const heading of root.querySelectorAll( + 'h1,h2,h3,h4,h5,h6' + )) { + const wrapper = heading.querySelector('a.header'); + if (wrapper) wrapper.replaceWith(...wrapper.childNodes); + const anchor = document.createElement('a'); + anchor.className = 'heading-anchor'; + anchor.href = '#' + heading.id; + anchor.setAttribute( + 'aria-label', + message(messages, 'Link to this section') + ); + anchor.textContent = '#'; + heading.append(anchor); + } + for (const original of root.querySelectorAll('.admonition')) { + const kind = + [...original.classList] + .find((name) => name.startsWith('admonish-')) + ?.slice(9) || 'note'; + const aside = document.createElement('aside'); + aside.className = 'admonition ' + kind; + for (const attribute of ['id', 'role', 'aria-labelledby']) + if (original.hasAttribute(attribute)) + aside.setAttribute(attribute, original.getAttribute(attribute) || ''); + const title = document.createElement('div'); + title.className = 'admonition-title'; + const nativeTitle = original.querySelector('.admonition-title'); + const titleParagraph = nativeTitle?.querySelector('p'); + title.innerHTML = titleParagraph?.innerHTML || kind; + if (title.textContent?.trim().toLowerCase() === kind) + title.textContent = kind; + const titleId = original.getAttribute('aria-labelledby'); + if (titleId) title.id = titleId; + aside.append(title); + for (const child of [...original.children]) + if (child !== nativeTitle) aside.append(...child.childNodes); + original.replaceWith(aside); + } + for (const display of root.querySelectorAll('.katex-display')) { + const wrapper = document.createElement('div'); + wrapper.className = 'math-display'; + const parent = display.parentElement; + if ( + parent?.tagName === 'P' && + parent.textContent?.trim() === display.textContent?.trim() + ) + parent.replaceWith(wrapper); + else display.before(wrapper); + wrapper.append(display); + } + for (const pre of root.querySelectorAll('pre')) { + const code = pre.querySelector('code'); + if (!code) continue; + const info = code.getAttribute('class') || ''; + const language = + [...code.classList] + .find((name) => name.startsWith('language-')) + ?.slice(9) || 'text'; + const text = (code.textContent || '').replace(/\n$/, ''); + code.textContent = text; + code.className = 'language-' + language; + if (hljs.getLanguage(language)) + code.innerHTML = hljs.highlight(text, { language }).value; + const block = document.createElement('div'); + block.className = 'code-block'; + const toolbar = document.createElement('div'); + toolbar.className = 'code-toolbar'; + const label = document.createElement('span'); + label.textContent = language; + toolbar.append(label); + const actions = document.createElement('div'); + if ( + language === 'rust' && + !/noplayground|ignore|compile_fail|no_run/.test(info) + ) { + const playground = document.createElement('a'); + playground.className = 'rust-playground'; + playground.href = + 'https://play.rust-lang.org/?version=stable&mode=debug&edition=2021&code=' + + encodeURIComponent(text); + playground.target = '_blank'; + playground.rel = 'noopener noreferrer'; + playground.textContent = 'Rust Playground ↗'; + actions.append(playground); + } + const copy = document.createElement('button'); + copy.className = 'copy-code'; + copy.textContent = message(messages, 'Copy code'); + copy.setAttribute('aria-label', message(messages, 'Copy code')); + actions.append(copy); + toolbar.append(actions); + pre.before(block); + block.append(toolbar, pre); + } + presentClips(root, document, nativePath); + const headings = [ + ...root.querySelectorAll('h1,h2,h3,h4,h5,h6') + ].map((heading) => ({ + level: Number(heading.tagName.slice(1)), + id: heading.id, + text: (heading.textContent || '').replace(/#$/, '').trim() + })); + const textRoot = root.cloneNode(true) as HTMLElement; + textRoot + .querySelectorAll( + '.heading-anchor,.code-toolbar,.katex-html,.video-clip-range' + ) + .forEach((node) => node.remove()); + return { + html: root.innerHTML, + headings, + text: (textRoot.textContent || '').replace(/\s+/g, ' ').trim() + }; +} + +function presentClips( + root: HTMLElement, + document: Document, + chapter: string +): void { + for (const frame of root.querySelectorAll('iframe[src]')) { + const src = frame.getAttribute('src') || ''; + let url: URL; + try { + url = new URL(src); + } catch { + continue; + } + const clip = url.searchParams.get('clipt'); + if ( + url.hostname !== 'www.youtube.com' || + !url.pathname.startsWith('/embed/') || + !clip + ) + continue; + const values: number[] = []; + let value = 0, + shift = 0; + for (const byte of Buffer.from(clip, 'base64url')) { + value += (byte & 127) * 2 ** shift; + if (byte & 128) shift += 7; + else { + values.push(value); + value = 0; + shift = 0; + } + } + if ( + values.length !== 4 || + values[0] !== 16 || + values[2] !== 24 || + values[3] <= values[1] + ) + throw new Error(chapter + ': invalid video clip range'); + const start = Math.floor(values[1] / 1000), + end = Math.ceil(values[3] / 1000); + url.searchParams.set('start', String(start)); + url.searchParams.set('end', String(end)); + frame.src = url.href; + const time = (seconds: number): string => + [Math.floor(seconds / 3600), Math.floor(seconds / 60) % 60, seconds % 60] + .map((n) => String(n).padStart(2, '0')) + .join(':'); + const range = document.createElement('div'); + range.className = 'video-clip-range'; + range.dir = 'ltr'; + range.textContent = time(start) + '–' + time(end); + frame.closest('figure')?.append(range); + } +} diff --git a/web/scripts/routes.ts b/web/scripts/routes.ts new file mode 100644 index 0000000..d3f84f8 --- /dev/null +++ b/web/scripts/routes.ts @@ -0,0 +1,220 @@ +import fs from 'node:fs/promises'; +import path from 'node:path'; +import { parseHTML } from 'linkedom'; +import type { ReaderBook } from '../src/book.ts'; +import type { UIMessages, MessageKey } from '../src/ui-messages.ts'; +import { + languages, + languagePath, + htmlLanguage +} from '../src/locale-routing.ts'; +import { + siteTitles, + siteDescriptions, + socialLocales, + siteBrandName, + brandedPageTitle +} from '../src/site-meta.ts'; +import { gatewayMarkup } from '../src/worlds.ts'; +import { contentsMarkup } from '../src/contents.ts'; + +const siteOrigin = ( + process.env.ALUX_SITE_URL || 'http://127.0.0.1:4174' +).replace(/\/$/, ''); +const dir = path.resolve(import.meta.dirname, '../dist'); +const content = JSON.parse( + await fs.readFile(path.join(dir, 'content.json'), 'utf8') +) as ReaderBook; +const { pages } = content; +const template = await fs.readFile(path.join(dir, 'index.html'), 'utf8'); +const known = new Set(pages.map((page) => page.slug)); +const extras: ReadonlyArray = [ + ['atlas.html', 'The chapter atlas'], + ['contents.html', 'Table of contents'], + ['parts/the-semantic-view.html', 'The Semantic View'], + ['parts/design-by-meaning-in-rust.html', 'Design by Meaning in Rust'], + ['parts/concepts.html', 'Concepts'], + ['parts/insights.html', 'Insights'] +]; + +for (const { code } of languages) { + const messages = JSON.parse( + await fs.readFile( + path.resolve(import.meta.dirname, '../locales/ui', code + '.json'), + 'utf8' + ) + ) as UIMessages; + const translate = (text: string): string => + messages[text as MessageKey] || text; + const localized = JSON.parse( + await fs.readFile(path.join(dir, 'content', code + '.json'), 'utf8') + ) as ReaderBook; + const localPages = localized.pages; + async function write( + route: string, + title: string, + description: string, + body = '', + realm = 'magic' + ): Promise { + const { document } = parseHTML(template); + document.documentElement.lang = htmlLanguage(code); + document.documentElement.dir = code === 'ar' ? 'rtl' : 'ltr'; + document + .querySelector('meta[name=description]') + ?.setAttribute('content', description); + const canonicalURL = + siteOrigin + languagePath('/' + route.replace(/index\.html$/, ''), code); + const chapterTitle = + route === 'introduction.html' || route === 'real/introduction.html' + ? translate('Introduction') + : title; + const shareTitle = + route === 'index.html' + ? siteTitles[code] + : brandedPageTitle(chapterTitle, code); + document.title = route === 'index.html' ? siteBrandName(code) : shareTitle; + const values: Record = { + 'application-name': siteBrandName(code), + 'apple-mobile-web-app-title': siteBrandName(code), + 'og:title': shareTitle, + 'og:description': siteDescriptions[code], + 'og:type': 'website', + 'og:site_name': siteBrandName(code), + 'og:locale': socialLocales[code], + 'og:url': canonicalURL, + 'og:image': siteOrigin + '/social/alux-programming-' + code + '.jpg', + 'og:image:width': '1200', + 'og:image:height': '630', + 'og:image:alt': siteTitles[code], + 'twitter:card': 'summary_large_image', + 'twitter:title': shareTitle, + 'twitter:description': siteDescriptions[code], + 'twitter:image': siteOrigin + '/social/alux-programming-' + code + '.jpg', + 'twitter:image:alt': siteTitles[code] + }; + for (const [name, value] of Object.entries(values)) { + const meta = document.createElement('meta'); + meta.setAttribute(name.startsWith('og:') ? 'property' : 'name', name); + meta.content = value; + document.head.append(meta); + } + const canonical = document.createElement('link'); + canonical.rel = 'canonical'; + canonical.href = canonicalURL; + document.head.append(canonical); + if (realm === 'real') + document.body.className = 'reality-view real-theme-light'; + if (body) { + const no = document.createElement('noscript'); + no.innerHTML = + realm === 'gateway' + ? body + : `
${body}
`; + for (const [legacyId, nativeId] of Object.entries( + localPages.find((page) => page.slug === route.replace(/^real\//, '')) + ?.anchorAliases ?? {} + )) { + const heading = [...no.querySelectorAll('[id]')].find( + (node) => node.id === nativeId + ); + if (heading) { + const alias = document.createElement('span'); + alias.id = legacyId; + alias.setAttribute('aria-hidden', 'true'); + heading.before(alias); + } + } + no.querySelectorAll('h1 img').forEach((element) => element.remove()); + if (no.querySelector('#alux-programming-guidelines')) + no.querySelector('.admonition.warning')?.remove(); + no.querySelectorAll('a[href]').forEach((anchor) => { + const href = anchor.getAttribute('href') ?? ''; + if (!href.startsWith('/') || href.startsWith('//')) return; + let [slug, hash] = href.slice(1).split('#'); + if (realm === 'real' && known.has(slug ?? '')) slug = 'real/' + slug; + anchor.setAttribute( + 'href', + languagePath('/' + (slug ?? ''), code) + (hash ? '#' + hash : '') + ); + }); + no.querySelectorAll('.copy-code').forEach((element) => element.remove()); + document.body.append(no); + } + for (const { code: other } of languages) { + const alternate = document.createElement('link'); + alternate.rel = 'alternate'; + alternate.hreflang = htmlLanguage(other); + alternate.href = + siteOrigin + + languagePath('/' + route.replace(/index\.html$/, ''), other); + document.head.append(alternate); + } + const destination = path.join(dir, languagePath('/' + route, code)); + await fs.mkdir(path.dirname(destination), { recursive: true }); + await fs.writeFile(destination, document.toString()); + } + for (const page of localPages) { + await write(page.slug, page.title, page.text.slice(0, 175), page.html); + await write( + 'real/' + page.slug, + page.title, + page.text.slice(0, 175), + page.html, + 'real' + ); + } + const contentsGroups = localized.groups; + const contentsBody = (real: boolean): string => + contentsMarkup({ + groups: contentsGroups, + pages: localPages, + icon: () => '', + real, + label: translate + }) + .replace(/^]*>/, '') + .replace(/<\/main>$/, ''); + for (const [route, title] of extras) + await write( + route, + translate(title), + translate(title), + route === 'contents.html' ? contentsBody(false) : '' + ); + await write( + 'real/contents.html', + translate('Table of contents'), + translate('Table of contents'), + contentsBody(true), + 'real' + ); + await write( + 'magic.html', + localPages[0]?.title ?? '', + localPages[0]?.text.slice(0, 175) ?? '', + localPages[0]?.html ?? '' + ); + await write( + 'real/index.html', + localPages[0]?.title ?? '', + localPages[0]?.text.slice(0, 175) ?? '', + localPages[0]?.html ?? '', + 'real' + ); + await write( + 'index.html', + translate('Choose your world'), + translate('ALUX Programming'), + gatewayMarkup({ t: translate }), + 'gateway' + ); + await write( + '404.html', + translate('This page is uncharted.'), + translate('Find your way back to the book.') + ); +} +console.log( + `Generated ${languages.length} language routes for ${pages.length} chapters in both worlds, chooser and legacy aliases.` +); diff --git a/web/scripts/share-card-design.ts b/web/scripts/share-card-design.ts new file mode 100644 index 0000000..ddd5d2b --- /dev/null +++ b/web/scripts/share-card-design.ts @@ -0,0 +1,92 @@ +import fs from 'node:fs/promises'; +import path from 'node:path'; +import { htmlLanguage } from '../src/locale-routing.ts'; +import type { LanguageCode } from '../src/locale-routing.ts'; +import { languages } from '../src/locale-routing.ts'; +import type { UIMessages } from '../src/ui-messages.ts'; + +const copy: Record = { + en: [ + 'Design programs|by meaning.', + 'Denotational design · Composition · Rust' + ], + zh: ['先定义含义,|再设计程序。', '指称设计 · 组合性 · Rust'], + 'zh-hant': ['先定義含義,|再設計程式。', '指稱設計 · 合成性 · Rust'], + ja: ['意味を定め、|プログラムを設計する。', '指示的設計 · 合成性 · Rust'], + ko: [ + '의미를 정의하고,|프로그램을 설계하세요.', + '지시적 설계 · 합성성 · Rust' + ], + vi: ['Thiết kế từ|ý nghĩa.', 'Ngữ nghĩa biểu thị · Phép hợp thành · Rust'], + de: [ + 'Nach Bedeutung|programmieren.', + 'Denotationeller Entwurf · Komposition · Rust' + ], + es: [ + 'Diseña programas|desde el significado.', + 'Diseño denotacional · Composición · Rust' + ], + ru: [ + 'Проектируйте,|исходя из смысла.', + 'Денотационное проектирование · Композиция · Rust' + ], + uk: [ + 'Проєктуйте,|виходячи зі змісту.', + 'Денотаційне проєктування · Композиція · Rust' + ], + ar: ['حدّد المعنى،|ثم صمّم البرنامج.', 'التصميم الدلالي · التركيب · Rust'] +}; + +async function programmingLabels(): Promise> { + const labels: Partial> = {}; + const directory = path.resolve(import.meta.dirname, '../locales/ui'); + for (const { code } of languages) { + const dictionary = JSON.parse( + await fs.readFile(path.join(directory, code + '.json'), 'utf8') + ) as UIMessages; + if (!dictionary.Programming) + throw Error('Missing Programming message for ' + code); + labels[code] = dictionary.Programming; + } + return labels as Record; +} + +const subtitles = await programmingLabels(); +export const shareCopy: Record< + LanguageCode, + readonly [string, string, string] +> = Object.fromEntries( + Object.entries(copy).map(([code, values]) => [ + code, + [subtitles[code as LanguageCode], ...values] + ]) +) as unknown as Record; + +export async function shareCardMarkup( + code: LanguageCode, + origin = 'http://127.0.0.1:4173' +): Promise { + const [subtitle, heading, caption] = shareCopy[code]; + const size: Record = { + en: 72, + zh: 76, + 'zh-hant': 76, + ja: 56, + ko: 57, + vi: 80, + de: 72, + es: 64, + ru: 66, + uk: 60, + ar: 82 + }; + const rtl = code === 'ar'; + return `
ALUX${subtitle}

${heading + .split('|') + .map((line) => `${line}`) + .join( + '' + )}

${caption}

`; +} diff --git a/web/scripts/share-preview.ts b/web/scripts/share-preview.ts new file mode 100644 index 0000000..257f0ca --- /dev/null +++ b/web/scripts/share-preview.ts @@ -0,0 +1,36 @@ +import fs from 'node:fs/promises'; +import {languages,htmlLanguage,languagePath} from '../src/locale-routing.ts'; +import type {LanguageCode} from '../src/locale-routing.ts'; +import {siteTitles,siteDescriptions,siteBrandName} from '../src/site-meta.ts'; +import {shareCopy} from './share-card-design.ts'; +const origin=(process.env.ALUX_PREVIEW_URL||'http://127.0.0.1:4174').replace(/\/$/,''); +const labels:Record={ + en:['Sharing preview','Language','Light','Dark','Open the English edition','Local illustration. Platform rendering and caches need checking after deployment.','One cover for Telegram, X and GitHub.'], + zh:['分享预览','语言','浅色','深色','打开中文版','本地示意,平台实际显示与缓存需上线后核对。','同一套封面,用于 Telegram、X 和 GitHub。'], + 'zh-hant':['分享預覽','語言','淺色','深色','開啟繁體中文版','本機示意,平台實際顯示與快取須上線後核對。','同一套封面,用於 Telegram、X 和 GitHub。'], + ja:['共有プレビュー','言語','ライト','ダーク','日本語版を開く','ローカルでの表示例です。公開後に各サービスの表示とキャッシュを確認する必要があります。','Telegram、X、GitHub で共通のカバーを使用します。'], + ko:['공유 미리보기','언어','라이트','다크','한국어판 열기','로컬 표시 예시입니다. 배포 후 각 플랫폼의 표시와 캐시를 확인해야 합니다.','Telegram, X, GitHub에 같은 표지를 사용합니다.'], + vi:['Xem trước khi chia sẻ','Ngôn ngữ','Sáng','Tối','Mở bản tiếng Việt','Đây là bản mô phỏng trên máy. Cần kiểm tra hiển thị và bộ nhớ đệm của nền tảng sau khi triển khai.','Dùng cùng một bộ ảnh bìa cho Telegram, X và GitHub.'], + de:['Vorschau beim Teilen','Sprache','Hell','Dunkel','Deutsche Ausgabe öffnen','Lokale Vorschau. Darstellung und Cache der Plattformen müssen nach der Veröffentlichung geprüft werden.','Ein gemeinsames Cover für Telegram, X und GitHub.'], + es:['Vista previa al compartir','Idioma','Claro','Oscuro','Abrir la edición en español','Simulación local. La visualización y la caché de cada plataforma deben comprobarse después de publicar.','Una misma portada para Telegram, X y GitHub.'], + ru:['Предпросмотр ссылки','Язык','Светлая','Тёмная','Открыть русскую версию','Локальный макет. Отображение и кеш платформ нужно проверить после публикации.','Одна обложка для Telegram, X и GitHub.'], + uk:['Попередній перегляд посилання','Мова','Світла','Темна','Відкрити українську версію','Локальний макет. Відображення й кеш платформ слід перевірити після публікації.','Одна обкладинка для Telegram, X і GitHub.'], + ar:['معاينة المشاركة','اللغة','فاتح','داكن','افتح النسخة العربية','هذه معاينة محلية. يجب التحقق من عرض المنصات وذاكرتها المؤقتة بعد النشر.','غلاف موحّد لـ Telegram وX وGitHub.'] +}; +interface ShareLocaleData { code:LanguageCode; name:string; htmlLanguage:string; title:string; brand:string; subtitle:string; description:string; readme:string; source:string; route:string; labels:readonly string[] } +const data:Record={} as Record; +for(const language of languages){const code=language.code;const source=code==='en'?'README.md':'docs/README.'+code+'.md';const md=await fs.readFile(new URL('../../'+source,import.meta.url),'utf8');const after=md.slice(md.indexOf('\n',md.indexOf('# '))+1);const paragraphs=after.split(/\r?\n\r?\n/).map((paragraph:string)=>paragraph.trim()).filter((paragraph:string)=>paragraph&&!/^(?:\[|\*\*|!\[|<|#|```)/.test(paragraph));data[code]={...language,htmlLanguage:htmlLanguage(code),title:siteTitles[code],brand:siteBrandName(code),subtitle:shareCopy[code][0],description:siteDescriptions[code],readme:paragraphs[0]??'',source,route:code==='en'?'/?lang=en':languagePath('/',code),labels:labels[code]};} +const escape=(value:string):string=>value.replace(/[&<>"']/g,char=>({'&':'&','<':'<','>':'>','"':'"',"'":'''}[char]??char)); +function markup(assets:string):string{return `Telegram · X · GitHub — ALUX Programming
ALUX

Telegram

ALUX Programming

X / Twitter

GitHub · README

`;} +await fs.mkdir(new URL('../previews/',import.meta.url),{recursive:true}); +await fs.writeFile(new URL('../previews/social.html',import.meta.url),markup('../public/')); +await fs.mkdir(new URL('../../output/',import.meta.url),{recursive:true}); +await fs.writeFile(new URL('../../output/分享预览.html',import.meta.url),markup('../web/public/')); +console.log('Generated Telegram, X and GitHub previews for eleven languages. Reader preview unchanged.'); diff --git a/web/scripts/source-localization.ts b/web/scripts/source-localization.ts new file mode 100644 index 0000000..787763d --- /dev/null +++ b/web/scripts/source-localization.ts @@ -0,0 +1,131 @@ +import fs from 'node:fs/promises'; +import path from 'node:path'; +import {createHash} from 'node:crypto'; +import type { MdBook, MdBookItem } from './mdbook-model.ts'; +import { languages } from '../src/locale-routing.ts'; +import type { LanguageCode } from '../src/locale-routing.ts'; + +export interface SourceMetadata { + title?: string; + parts?: Record; + sourceHash?:string; +} +/** Optional source-level navigation labels; chapter prose stays ordinary Markdown. */ +export function sourceMetadata(markdown: string): SourceMetadata { + const match = markdown.match(/^\s*/); + if (!match) return {}; + const value: unknown = JSON.parse(match[1] ?? ''); + if (!value || typeof value !== 'object' || Array.isArray(value)) + throw Error('Reader source metadata must be an object'); + const data = value as Record; + if (Object.keys(data).some((key) => !['title','parts','sourceHash'].includes(key))) + throw Error('Unknown reader source metadata field'); + if ( + data.title !== undefined && + (typeof data.title !== 'string' || !data.title.trim()) + ) + throw Error('Reader source title must be nonempty'); + if ( + data.parts !== undefined && + (!data.parts || + typeof data.parts !== 'object' || + Array.isArray(data.parts) || + Object.values(data.parts).some( + (title) => typeof title !== 'string' || !title.trim() + )) + ) + throw Error('Reader part titles must be nonempty strings'); + if(data.sourceHash!==undefined&&(typeof data.sourceHash!=='string'||!/^sha256:[a-f0-9]{64}$/.test(data.sourceHash)))throw Error('Invalid English source fingerprint'); + return data as SourceMetadata; +} + +export function sourceFingerprint(markdown:string):string{return 'sha256:'+createHash('sha256').update(markdown.replace(/\r\n?/g,'\n')).digest('hex');} + +export function translatedSourcePath( + canonical: string, + locale: LanguageCode +): string { + if (!canonical.endsWith('.md')) + throw Error('Expected a canonical Markdown source: ' + canonical); + return locale === 'en' + ? canonical + : canonical.slice(0, -3) + '.' + locale + '.md'; +} + +/** Receives mdBook's ordered tree; it does not discover chapters or compile Markdown. */ +export async function localizeSources( + book: MdBook, + sourceRoot: string, + locale: LanguageCode, + warn:(message:string)=>void=message=>console.error(message) +): Promise { + if (!languages.some((language) => language.code === locale)) + throw Error('Unsupported book language: ' + locale); + if (locale === 'en') return book; + const root = path.resolve(sourceRoot), + parts: Record = {}; + async function visit(items: MdBookItem[]): Promise { + const result: MdBookItem[] = []; + for (const item of items) { + if (typeof item !== 'object' || !('Chapter' in item)) { + result.push(item); + continue; + } + const original = item.Chapter, + canonical = original.source_path || original.path; + let chapter = { ...original }; + if (canonical) { + const filename = path.resolve( + root, + translatedSourcePath(canonical, locale) + ); + if (!filename.startsWith(root + path.sep)) + throw Error( + 'Chapter source escapes the book directory: ' + canonical + ); + try { + const content = await fs.readFile(filename, 'utf8'), + metadata = sourceMetadata(content); + const fingerprint=sourceFingerprint(original.content); + if(metadata.sourceHash!==fingerprint)warn(`[translation freshness] ${locale} ${canonical}: ${metadata.sourceHash?'English source changed; translation may be stale':'translation has no reviewed English fingerprint'}. Review the translation before setting sourceHash to ${fingerprint}.`); + const firstHeading = content.match( + /^#\s+(.+?)(?:\s+\{#[^}]+\})?\s*$/m + )?.[1]; + chapter = { + ...chapter, + content, + name: metadata.title || firstHeading || original.name + }; + if (canonical === 'index.md' && metadata.parts) + Object.assign(parts, metadata.parts); + } catch (error) { + if (!( + error instanceof Error && + 'code' in error && + error.code === 'ENOENT' + )) + throw error; + } + } + chapter.sub_items = await visit(original.sub_items); + result.push({ Chapter: chapter }); + } + return result; + } + const sections = await visit(book.sections); + function localizeParts(items: MdBookItem[]): MdBookItem[] { + return items.map((item) => + typeof item === 'object' && 'PartTitle' in item + ? { PartTitle: parts[item.PartTitle] || item.PartTitle } + : typeof item === 'object' && 'Chapter' in item + ? { + Chapter: { + ...item.Chapter, + sub_items: localizeParts(item.Chapter.sub_items) + } + } + : item + ); + } + return { ...book, sections: localizeParts(sections) }; +} diff --git a/web/scripts/turndown-plugin-gfm.d.ts b/web/scripts/turndown-plugin-gfm.d.ts new file mode 100644 index 0000000..75cf5b6 --- /dev/null +++ b/web/scripts/turndown-plugin-gfm.d.ts @@ -0,0 +1,4 @@ +declare module 'turndown-plugin-gfm' { + import type TurndownService from 'turndown'; + export const gfm: TurndownService.Plugin; +} diff --git a/web/scripts/verify-acceptance.ts b/web/scripts/verify-acceptance.ts new file mode 100644 index 0000000..2bfe7a1 --- /dev/null +++ b/web/scripts/verify-acceptance.ts @@ -0,0 +1,101 @@ +/** Production-build acceptance. Mobile profiles are simulations, never physical-device claims. */ +import fs from 'node:fs/promises'; +import path from 'node:path'; +import assert from 'node:assert/strict'; +import {preview} from 'vite'; +import {chromium,firefox,webkit,devices} from 'playwright'; +import type {BrowserType,BrowserContextOptions,Page} from 'playwright'; +import type {ReaderBook} from '../src/book.ts'; +const web=path.resolve(import.meta.dirname,'..'),output=path.resolve(web,'../output/merge-acceptance'); +await fs.mkdir(output,{recursive:true}); +const server=await preview({root:web,preview:{host:'127.0.0.1',port:4176,strictPort:true}}),origin='http://127.0.0.1:4176'; +const profiles:Array<{name:string;engine:BrowserType;options:BrowserContextOptions;simulation:boolean}>=[ + {name:'desktop-chromium',engine:chromium,options:{viewport:{width:1440,height:960}},simulation:false}, + {name:'desktop-firefox',engine:firefox,options:{viewport:{width:1440,height:960}},simulation:false}, + {name:'android-chromium-profile',engine:chromium,options:devices['Pixel 7']!,simulation:true}, + {name:'iphone-webkit-profile',engine:webkit,options:devices['iPhone 13']!,simulation:true} +]; +const reports:unknown[]=[]; +async function ready(page:Page){await page.locator('#folio-position[data-ready="true"]').waitFor({timeout:45000});} +async function closeMusic(page:Page){const close=page.locator('[data-music-close]');if(await close.isVisible())await close.click();} +async function settled(page:Page){await page.locator('.reader-app[aria-busy="false"]').waitFor();await ready(page);await page.locator('.chapter-flip-host,.folio-measure').waitFor({state:'detached'});await closeMusic(page);} +try{ + for(const profile of profiles.filter(p=>!process.env.ACCEPTANCE_PROFILE||p.name===process.env.ACCEPTANCE_PROFILE)){ + const browser=await profile.engine.launch({headless:true,...(profile.engine===chromium&&process.env.PLAYWRIGHT_CHROMIUM_EXECUTABLE?{executablePath:process.env.PLAYWRIGHT_CHROMIUM_EXECUTABLE}:{})}); + const context=await browser.newContext({...profile.options,reducedMotion:'no-preference'}),page=await context.newPage(); + const errors:string[]=[],failed:string[]=[],measured:string[]=[],contentRequests:string[]=[],checks:string[]=[]; + const check=(name:string,value:unknown)=>{assert.ok(value,profile.name+': '+name);checks.push(name);}; + page.on('pageerror',error=>errors.push(error.stack||error.message)); + page.on('response',response=>{if(response.url().startsWith(origin)&&response.status()>=400)failed.push(response.status()+' '+response.url());}); + page.on('requestfailed',request=>{if(request.url().startsWith(origin)&&request.failure()?.errorText!=='net::ERR_ABORTED'&&!request.failure()?.errorText.includes('CANCELLED'))failed.push(request.url()+': '+request.failure()?.errorText);}); + page.on('request',request=>{if(request.url().includes('/content/'))contentRequests.push(new URL(request.url()).pathname);}); + await page.exposeFunction('recordMeasured',(id:string,pathname:string)=>{measured.push(id);if(!pathname.endsWith('/'+id.replace(/\.md$/,'.html')))errors.push('Unrelated pagination: '+id+' on '+pathname);}); + await page.addInitScript(()=>{ + new PerformanceObserver(list=>{for(const entry of list.getEntries())if(entry.name==='alux:pagination')void(window as unknown as {recordMeasured:(id:string,pathname:string)=>Promise}).recordMeasured((entry as PerformanceMark).detail.chapter,location.pathname);}).observe({entryTypes:['mark']}); + }); + let failure:unknown; + try{ + const started=Date.now(); + await page.goto(origin+'/zh/concepts/operational_semantics.html');await settled(page); + const readyMs=Date.now()-started; + const book=JSON.parse(await fs.readFile(path.join(web,'dist/content/zh.json'),'utf8')) as ReaderBook,chapter=book.pages.find(p=>p.slug==='concepts/operational_semantics.html')!; + check('only viewed chapter measured',measured.length>0&&measured.every(id=>id===chapter.id)); + check('only selected edition requested',contentRequests.every(route=>route==='/content/zh.json')); + check('unknown whole-book count is labelled chapter progress',await page.locator('#folio-position').getAttribute('data-numbering')==='chapter'&&(await page.locator('#folio-position').textContent())?.includes('本章')); + const snapshot=()=>page.locator('#page-book .folio-content').evaluateAll(nodes=>nodes.map(n=>n.textContent||'').join('').replace(/\s/g,'')); + const before=await snapshot(); + check('math and admonitions rendered',await page.locator('#page-book .katex').count()>0&&await page.locator('#page-book .admonition').count()>0); + await page.locator('#larger-text').click();await settled(page);const after=await snapshot();if(before!==after)await fs.writeFile(path.join(output,profile.name+'-reflow.json'),JSON.stringify({before,after},null,2));check('font-size reflow retains every content character',before===after); + const size=page.viewportSize()!;await page.setViewportSize({width:size.height,height:size.width});await settled(page);check('orientation reflow retains content',before===await snapshot()); + await page.setViewportSize(size);await settled(page); + await page.locator('#bookmark').click();check('bookmark toggles',await page.locator('#bookmark').getAttribute('aria-pressed')==='true'); + await page.locator('#reading-mode').click();await page.locator('.continuous-prose').waitFor();await page.locator('#reading-mode').click();await settled(page);check('scroll/book round trip',before===await snapshot()); + await page.locator('select[data-language]').selectOption('en');await page.locator('html[lang="en"]').waitFor();await settled(page);check('language keeps canonical route and section',page.url().includes('/concepts/operational_semantics.html')&&new URL(page.url()).hash.length>1); + if(await page.locator('.reader-music-button').getAttribute('aria-pressed')!=='true')await page.locator('.reader-music-button').click(); + await page.waitForFunction(()=>{const media=document.querySelector('audio[src*="forest-breath"]');return media&&!media.paused&&media.currentTime>0;}); + check('native audio playback clock advances',true); + await page.locator('[data-realm-switch]').click();await page.locator('.real-prose h1').waitFor();await closeMusic(page); + check('world switch keeps chapter',page.url().includes('/real/concepts/operational_semantics.html')); + check('real-world entry interrupts music',await page.locator('audio[src*="forest-breath"]').evaluate((media:HTMLAudioElement)=>media.paused)); + await page.locator('[data-search]').first().click();await page.locator('#search-input').fill('semantics');await page.locator('.search-result').first().waitFor();check('selected-language search results',await page.locator('.search-result').count()>0);await page.keyboard.press('Escape'); + await page.locator('[data-realm-switch]').click();await settled(page);check('bookmark persists through language/world changes',await page.locator('#bookmark').getAttribute('aria-pressed')==='true'); + // Real internal link clicks exercise the router, not a direct state/test backdoor. + const follow=async(href:string)=>page.evaluate(href=>{const a=document.createElement('a');a.href=href;document.body.append(a);a.click();a.remove();},href); + await follow('/rust-dd/capability-algebras.html');await settled(page); + check('code survives route turn',await page.locator('#page-book pre code').count()>0); + await follow('/concepts/operational_semantics.html');await page.waitForURL('**/concepts/operational_semantics.html'); + check('animation copies never load duplicate embedded players',await page.locator('.reader-backdrop iframe[src],.chapter-flip-host iframe[src]').count()===0); + await page.waitForTimeout(60);await page.goBack();await settled(page); + check('history interrupts animation cleanly: '+page.url(),page.url().includes('capability-algebras.html')&&await page.locator('.chapter-flip-host').count()===0); + await page.goForward();await settled(page);check('forward restores destination',page.url().includes('operational_semantics.html')); + // Warm cycles must leave one active layout, no detached measurement/animation hosts. + const cdp=profile.name==='desktop-chromium'?await context.newCDPSession(page):null; + const lifecycle:unknown[]=[]; + for(let i=0;i<4;i++){ + await follow('/rust-dd/capability-algebras.html');await settled(page);await follow('/concepts/operational_semantics.html');await settled(page); + if(cdp){ + await cdp.send('HeapProfiler.collectGarbage'); + const globals=await cdp.send('Runtime.evaluate',{expression:'JSON.stringify([window,document,document.fonts].map(target=>Object.fromEntries(Object.entries(getEventListeners(target)).map(([name,list])=>[name,list.length]))))',includeCommandLineAPI:true,returnByValue:true}); + lifecycle.push({globals:JSON.parse(globals.result.value as string),dom:await cdp.send('Memory.getDOMCounters')}); + } + } + if(cdp){ + await fs.writeFile(path.join(output,'lifecycle-cycles.json'),JSON.stringify(lifecycle,null,2)); + const samples=lifecycle as Array<{globals:unknown;dom:{nodes:number;documents:number;jsEventListeners:number}}>; + check('global listeners do not accumulate',samples.every(s=>JSON.stringify(s.globals)===JSON.stringify(samples[0]!.globals))); + check('DOM and listener counts remain bounded after GC',samples.at(-1)!.dom.nodes<=samples[0]!.dom.nodes+100&&samples.at(-1)!.dom.jsEventListeners<=samples[0]!.dom.jsEventListeners+10); + await cdp.detach(); + } + check('no leftover animation or measurement hosts',await page.locator('.chapter-flip-host,.folio-measure').count()===0); + check('single active reader and audio element',await page.locator('#page-book').count()===1&&await page.locator('audio').count()<=1); + await page.screenshot({path:path.join(output,profile.name+'.png')}); + await follow('/');await page.locator('.world-choice').first().waitFor();await page.locator('.reader-app[aria-busy="false"]').waitFor(); + check('leaving readers pauses reading audio',await page.locator('audio[src*="forest-breath"]').evaluate((media:HTMLAudioElement)=>media.paused)); + check('no failed internal requests',failed.length===0);check('no uncaught exceptions',errors.length===0); + reports.push({profile:profile.name,browser:browser.version(),simulation:profile.simulation,status:'PASS',readyMs,checks,errors,failed,measured,contentRequests}); + }catch(error){failure=error;reports.push({profile:profile.name,browser:browser.version(),simulation:profile.simulation,status:'FAIL',checks,errors,failed,detail:String(error)});await page.screenshot({path:path.join(output,profile.name+'-failure.png')}).catch(()=>{});} + finally{await context.close();await browser.close();} + if(failure)console.error(profile.name+': '+String(failure));else console.log(profile.name+': PASS'); + } +}finally{await fs.writeFile(path.join(output,'browser-acceptance.json'),JSON.stringify(reports,null,2));await new Promise((resolve,reject)=>server.httpServer.close(error=>error?reject(error):resolve()));} +assert.ok(reports.length>0&&reports.every(report=>(report as {status:string}).status==='PASS'),'See browser-acceptance.json'); diff --git a/web/scripts/verify-generated.ts b/web/scripts/verify-generated.ts new file mode 100644 index 0000000..fbf4c74 --- /dev/null +++ b/web/scripts/verify-generated.ts @@ -0,0 +1,27 @@ +/** Offline internal routes/resources/fragments audit of the complete production tree. */ +import fs from 'node:fs/promises'; +import path from 'node:path'; +import assert from 'node:assert/strict'; +import {createHash} from 'node:crypto'; +import {parseHTML} from 'linkedom'; +const root=path.resolve(import.meta.dirname,'../dist'),output=path.resolve(root,'../../output/merge-acceptance'); +async function walk(dir:string):Promise{const items=await fs.readdir(dir,{withFileTypes:true});return(await Promise.all(items.map(item=>item.isDirectory()?walk(path.join(dir,item.name)):Promise.resolve([path.join(dir,item.name)])))).flat();} +const files=(await walk(root)).sort(),known=new Set(files.map(file=>path.relative(root,file).replaceAll('\\','/'))),failures:string[]=[],documents=new Map['document']>(); +let links=0,fragments=0,resources=0; +async function documentFor(file:string){let document=documents.get(file);if(!document){document=parseHTML(await fs.readFile(path.join(root,file),'utf8')).document;documents.set(file,document);}return document;} +for(const file of known){ + if(!file.endsWith('.html'))continue; + const document=await documentFor(file); + for(const element of document.querySelectorAll('a[href],img[src],script[src],link[href],audio[src],video[src],source[src],track[src]')){ + const attribute=element.hasAttribute('src')?'src':'href',raw=element.getAttribute(attribute)!; + const url=new URL(raw,'https://audit.invalid/'+file);if(url.origin!=='https://audit.invalid')continue; + const target=decodeURIComponent(url.pathname).slice(1)+(url.pathname.endsWith('/')?'index.html':''); + if(element.localName==='a')links++;else resources++; + if(!known.has(target)){failures.push(file+': '+raw+' (missing '+target+')');continue;} + if(url.hash&&target.endsWith('.html')){fragments++;const targetDocument=await documentFor(target),id=decodeURIComponent(url.hash.slice(1));if(!targetDocument.getElementById(id))failures.push(file+': '+raw+' (missing fragment)');} + } +} +// Content and every generated route are deterministic inputs to the delivery. +const hashes:Record={};for(const file of known)hashes[file]=createHash('sha256').update(await fs.readFile(path.join(root,file))).digest('hex'); +await fs.mkdir(output,{recursive:true});await fs.writeFile(path.join(output,'generated-inventory.json'),JSON.stringify(hashes,null,2));await fs.writeFile(path.join(output,'generated-audit.json'),JSON.stringify({html:documents.size,links,fragments,resources,failures},null,2)); +console.log(JSON.stringify({html:documents.size,links,fragments,resources,failures:failures.length,samples:failures.slice(0,12)}));assert.equal(failures.length,0,'See generated-audit.json'); diff --git a/web/scripts/verify-page-flip.ts b/web/scripts/verify-page-flip.ts new file mode 100644 index 0000000..15eb465 --- /dev/null +++ b/web/scripts/verify-page-flip.ts @@ -0,0 +1,35 @@ +import path from 'node:path'; +import fs from 'node:fs/promises'; +import assert from 'node:assert/strict'; +import {chromium} from 'playwright'; +const output=path.resolve(import.meta.dirname,'../../output/merge-acceptance');await fs.mkdir(output,{recursive:true}); +const browser=await chromium.launch({headless:true,...(process.env.PLAYWRIGHT_CHROMIUM_EXECUTABLE?{executablePath:process.env.PLAYWRIGHT_CHROMIUM_EXECUTABLE}:{})}); +const page=await browser.newPage(),errors:string[]=[];page.on('pageerror',error=>errors.push(error.message)); +try{ + await page.setContent(''); + await page.evaluate(()=>{ + const frames=new Set(),resize=new Set(); + const raf=requestAnimationFrame.bind(window),cancel=cancelAnimationFrame.bind(window),add=window.addEventListener.bind(window),remove=window.removeEventListener.bind(window); + window.requestAnimationFrame=callback=>{const id=raf(time=>{frames.delete(id);callback(time);});frames.add(id);return id;}; + window.cancelAnimationFrame=id=>{frames.delete(id);cancel(id);}; + window.addEventListener=((type:string,listener:EventListenerOrEventListenerObject,options?:boolean|AddEventListenerOptions)=>{if(type==='resize')resize.add(listener);add(type,listener,options);}) as typeof window.addEventListener; + window.removeEventListener=((type:string,listener:EventListenerOrEventListenerObject,options?:boolean|EventListenerOptions)=>{if(type==='resize')resize.delete(listener);remove(type,listener,options);}) as typeof window.removeEventListener; + (window as Window&{flipProbe?:unknown}).flipProbe={frames,resize,raf}; + }); + await page.addScriptTag({path:path.resolve(import.meta.dirname,'../node_modules/page-flip/dist/js/page-flip.browser.js')}); + const result=await page.evaluate(async()=>{ + type Flip={loadFromHTML(nodes:HTMLElement[]):void;flipNext(corner:string):void;destroy():void}; + const ctor=(window as Window&{St?:{PageFlip:new(element:HTMLElement,settings:Record)=>Flip}}).St?.PageFlip;if(!ctor)throw Error('PageFlip did not load'); + for(let i=0;i<5;i++){ + const host=document.createElement('div');host.dataset.flipProbeHost='true';host.style.width='360px';host.style.height='240px';document.body.append(host); + const sheets=Array.from({length:4},(_,n)=>{const sheet=document.createElement('section');sheet.textContent='Sheet '+n;host.append(sheet);return sheet;}); + const flip=new ctor(host,{width:180,height:240,useMouseEvents:false,usePortrait:false,autoSize:false,flippingTime:560});flip.loadFromHTML(sheets); + if(i%2)await new Promise(resolve=>setTimeout(resolve,25));flip.flipNext('bottom');flip.destroy(); + } + const probe=(window as Window&{flipProbe?:{frames:Set;resize:Set;raf:typeof requestAnimationFrame}}).flipProbe!; + await new Promise(resolve=>probe.raf(()=>probe.raf(()=>resolve()))); + return {activeFrames:probe.frames.size,resizeListeners:probe.resize.size,remainingHosts:document.querySelectorAll('[data-flip-probe-host],.stf__parent,.stf__wrapper').length}; + }); + await fs.writeFile(path.join(output,'page-flip-lifecycle.json'),JSON.stringify({browser:browser.version(),result,errors},null,2)); + console.log(JSON.stringify({browser:browser.version(),result,errors}));assert.deepEqual(result,{activeFrames:0,resizeListeners:0,remainingHosts:0});assert.deepEqual(errors,[]); +}finally{await browser.close();} diff --git a/web/scripts/verify-reader.ts b/web/scripts/verify-reader.ts new file mode 100644 index 0000000..ec93d2b --- /dev/null +++ b/web/scripts/verify-reader.ts @@ -0,0 +1,318 @@ +/** Optional real-Chromium regression against the production build. Run after pnpm build. */ +import fs from 'node:fs/promises'; +import path from 'node:path'; +import assert from 'node:assert/strict'; +import { preview } from 'vite'; +import { chromium } from 'playwright'; +import type { Page } from 'playwright'; +import { + languages, + languagePath, + htmlLanguage +} from '../src/locale-routing.ts'; + +const web = path.resolve(import.meta.dirname, '..'), + output = path.resolve(web, '../output/reader-regression'); +await fs.mkdir(output, { recursive: true }); +const server = await preview({ + root: web, + preview: { host: '127.0.0.1', port: 4175, strictPort: true } +}); +const browser = await chromium.launch({ + headless: true, + ...(process.env.PLAYWRIGHT_CHROMIUM_EXECUTABLE + ? { executablePath: process.env.PLAYWRIGHT_CHROMIUM_EXECUTABLE } + : {}) +}); +const errors: string[] = [], + checks: string[] = [], + startup: Array<{ + width: number; + firstReadableMs: number; + readyMs: number; + emptyFrames: number; + }> = [], + layouts: Array<{ + locale: string; + width: number; + route: string; + readyMs: number; + }> = []; +const origin = 'http://127.0.0.1:4175'; +function check(name: string, condition: boolean) { + assert.ok(condition, name); + checks.push(name); +} +function observe(page: Page) { + page.on('pageerror', (error) => errors.push(error.message)); +} +async function closeMusic(page: Page) { + const close = page.locator('[data-music-close]'); + if (await close.isVisible()) await close.click(); +} +async function ready(page: Page, route: string) { + if (route.includes('/real/')) await page.locator('.real-prose h1').waitFor(); + else if (route.endsWith('contents.html')) + await page.locator('.contents-part').first().waitFor(); + else if (route.endsWith('introduction.html')) + await page + .locator('#folio-position') + .filter({ hasText: /\// }) + .waitFor({ timeout: 45000 }); + else await page.locator('.world-choice').first().waitFor(); + await closeMusic(page); +} +try { + for (const width of [320, 768, 1440]) { + const context = await browser.newContext({ + viewport: { width, height: 960 }, + reducedMotion: 'reduce' + }), + page = await context.newPage(); + observe(page); + await context.route('**/*', async (route) => { + if (['image', 'font'].includes(route.request().resourceType())) + await new Promise((resolve) => setTimeout(resolve, 200)); + await route.continue(); + }); + await page.addInitScript(() => { + const frames: Array<{ at: number; readable: boolean; empty: boolean }> = + []; + (window as Window & { readerFrames?: typeof frames }).readerFrames = + frames; + function sample() { + const volume = document.querySelector('.bound-volume'); + frames.push({ + at: performance.now(), + readable: !!volume + ?.querySelector('.folio-content') + ?.textContent?.trim(), + empty: !!volume && !volume.textContent?.trim() + }); + if (frames.length < 600) requestAnimationFrame(sample); + } + requestAnimationFrame(sample); + }); + await page.goto(origin + '/zh/introduction.html'); + await ready(page, '/introduction.html'); + const frames = await page.evaluate( + () => + ( + window as Window & { + readerFrames?: Array<{ + at: number; + readable: boolean; + empty: boolean; + }>; + } + ).readerFrames || [] + ); + const readable = frames.find((frame) => frame.readable); + check(`slow assets/${width}: first readable pages`, !!readable); + check( + `slow assets/${width}: no painted empty book`, + frames.every((frame) => !frame.empty) + ); + startup.push({ + width, + firstReadableMs: Math.round(readable!.at), + readyMs: Math.round(await page.evaluate(() => performance.now())), + emptyFrames: frames.filter((frame) => frame.empty).length + }); + await context.close(); + } + for (const { code } of languages) { + const context = await browser.newContext({ + viewport: { width: 1440, height: 960 }, + reducedMotion: 'reduce' + }), + page = await context.newPage(); + observe(page); + for (const width of [320, 768, 1440]) { + await page.setViewportSize({ width, height: width === 1440 ? 960 : 900 }); + for (const route of [ + '/introduction.html', + '/real/introduction.html', + '/contents.html' + ]) { + const started = Date.now(); + await page.goto(origin + languagePath(route, code)); + await ready(page, route); + check( + `${code}/${width}/${route}: locale`, + (await page.locator('html').getAttribute('lang')) === + htmlLanguage(code) + ); + const geometry = await page.evaluate(() => ({ + overflow: document.documentElement.scrollWidth > innerWidth + 1, + outside: [ + ...document.querySelectorAll( + '.bound-tools button,.bound-world-nav select,.real-toolbar button,.real-toolbar select' + ) + ] + .filter((element) => { + const rect = element.getBoundingClientRect(); + return ( + rect.width > 0 && + (rect.left < -0.5 || rect.right > innerWidth + 0.5) + ); + }) + .map((element) => element.id || element.getAttribute('aria-label')) + })); + check( + `${code}/${width}/${route}: no horizontal overflow`, + !geometry.overflow + ); + check( + `${code}/${width}/${route}: controls inside viewport`, + geometry.outside.length === 0 + ); + layouts.push({ + locale: code, + width, + route, + readyMs: Date.now() - started + }); + if (code === 'zh' && width === 1440 && route === '/introduction.html') { + await page.screenshot({ path: path.join(output, 'zh-light.png') }); + await page.locator('#toggle-night').click(); + await page.screenshot({ path: path.join(output, 'zh-dark.png') }); + } + if (code === 'ar' && width === 320 && route === '/introduction.html') + await page.screenshot({ path: path.join(output, 'ar-mobile.png') }); + } + } + await context.close(); + } + const context = await browser.newContext({ + viewport: { width: 1440, height: 960 }, + reducedMotion: 'reduce', + permissions: ['clipboard-read', 'clipboard-write'] + }), + page = await context.newPage(); + observe(page); + const contentRequests: string[] = []; + page.on('request', (request) => { + if (new URL(request.url()).pathname.startsWith('/content/')) + contentRequests.push(new URL(request.url()).pathname); + }); + await page.goto(origin + '/zh/concepts/operational_semantics.html'); + await page + .locator('#folio-position') + .filter({ hasText: /\// }) + .waitFor({ timeout: 45000 }); + await closeMusic(page); + const position = await page.locator('#folio-position').innerText(); + await page.locator('#next-sheet').click(); + await page.waitForFunction( + (value) => document.querySelector('#folio-position')?.textContent !== value, + position + ); + check( + 'chapter-internal page turn', + page.url().includes('operational_semantics') + ); + await page.locator('#bookmark').click(); + check( + 'bookmark state', + (await page.locator('#bookmark').getAttribute('aria-pressed')) === 'true' + ); + await page.locator('[data-bookmarks]').click(); + await page.locator('#bookmarks-dialog[open]').waitFor(); + check( + 'bookmark dialog current chapter', + (await page.locator('.saved-chapter strong').innerText()) === '操作语义' + ); + await page.locator('[data-close-bookmarks]').click(); + await page.keyboard.press('Control+k'); + await page.locator('#search-input').fill('能力'); + await page.locator('.search-result').first().waitFor(); + check('localized search', (await page.locator('.search-result').count()) > 0); + await page.keyboard.press('Escape'); + await page + .locator('#search-dialog:not([open])') + .waitFor({ state: 'attached' }); + check('Escape closes search', true); + await page.locator('#reading-mode').click(); + await page.locator('.continuous-prose').waitFor(); + check( + 'book to scroll mode', + (await page.locator('#reading-mode').getAttribute('aria-pressed')) === + 'true' + ); + await page.locator('#reading-mode').click(); + await page.locator('#folio-position').filter({ hasText: /\// }).waitFor(); + await page.locator('select[data-language]').selectOption('en'); + await page.locator('html[lang="en"]').waitFor(); + await page.locator('#folio-position').filter({ hasText: /\// }).waitFor(); + check( + 'language preserves canonical section', + new URL(page.url()).hash.length > 1 + ); + check( + 'selected language data only', + JSON.stringify(contentRequests) === + JSON.stringify(['/content/zh.json', '/content/en.json']) + ); + check( + 'manual language preference', + (await page.evaluate(() => + localStorage.getItem('alux-programming-language') + )) === 'en' + ); + await page.locator('[data-realm-switch]').click(); + await page.locator('.real-prose').waitFor(); + await closeMusic(page); + check( + 'same-chapter world switch', + page.url().includes('/real/concepts/operational_semantics.html') + ); + await page.locator('select[data-language]').selectOption('ar'); + await page.locator('html[dir="rtl"]').waitFor(); + check('language switch retains real world', page.url().includes('/ar/real/')); + await page.locator('select[data-language]').selectOption('en'); + await page.locator('html[lang="en"]').waitFor(); + check( + 'English dialog messages restored', + (await page.locator('#search-input').getAttribute('placeholder')) === + 'Search ideas, code, chapters…' + ); + await page.goto(origin + '/real/rust-dd/capability-algebras.html'); + await page.locator('.real-copy').first().waitFor(); + await closeMusic(page); + const code = await page.locator('pre code').first().textContent(); + await page.locator('.real-copy').first().click(); + check( + 'clipboard exact code', + (await page.evaluate(() => navigator.clipboard.readText())).replaceAll( + '\r\n', + '\n' + ) === code + ); + check( + 'one music control', + (await page.locator('.reader-music-button').count()) === 1 + ); + await page.locator('.reader-music-button').click(); + await page.locator('[data-music-volume]').fill('0.4'); + check( + 'audio volume saved without amplification', + (await page.evaluate(() => + localStorage.getItem('alux-reader-music-volume') + )) === '0.4' + ); + await context.close(); + assert.deepEqual(errors, [], 'no browser exceptions'); +} finally { + await fs.writeFile( + path.join(output, 'report.json'), + JSON.stringify({ checks, layouts, startup, errors }, null, 2) + ); + await browser.close(); + await new Promise((resolve, reject) => + server.httpServer.close((error) => (error ? reject(error) : resolve())) + ); +} +console.log( + `${checks.length} browser assertions passed; ${layouts.length} localized viewport/route checks. Report: ${path.join(output, 'report.json')}` +); diff --git a/web/src/anchors.ts b/web/src/anchors.ts new file mode 100644 index 0000000..71e08bc --- /dev/null +++ b/web/src/anchors.ts @@ -0,0 +1,7 @@ +import type { ReaderPage } from './book.ts'; + +/** Old reader links keep working while new links use mdBook's canonical IDs. */ +export function resolveAnchor(page: ReaderPage, fragment: string): string { + const id = decodeURIComponent(fragment); + return page.anchorAliases?.[id] ?? id; +} diff --git a/web/src/book-data.ts b/web/src/book-data.ts new file mode 100644 index 0000000..046986d --- /dev/null +++ b/web/src/book-data.ts @@ -0,0 +1,92 @@ +import type { BookNode, ReaderBook, ReaderPage } from './book.ts'; +function record(value: unknown): value is Record { + return !!value && typeof value === 'object' && !Array.isArray(value); +} +function strings(value: unknown): value is string[] { + return ( + Array.isArray(value) && value.every((item) => typeof item === 'string') + ); +} +function node(value: unknown): value is BookNode { + if (!record(value)) return false; + if (value.kind === 'separator') return true; + if (value.kind === 'part') return typeof value.title === 'string'; + return ( + value.kind === 'chapter' && + typeof value.id === 'string' && + typeof value.title === 'string' && + Array.isArray(value.children) && + value.children.every(node) + ); +} +function page(value: unknown): value is ReaderPage { + if (!record(value)) return false; + return ( + [ + 'id', + 'title', + 'source', + 'group', + 'slug', + 'hash', + 'markdown', + 'html', + 'text' + ].every((key) => typeof value[key] === 'string') && + typeof value.minutes === 'number' && + Number.isFinite(value.minutes) && + value.minutes > 0 && + (value.parentId === null || typeof value.parentId === 'string') && + strings(value.children) && + Array.isArray(value.headings) && + value.headings.every( + (heading) => + record(heading) && + typeof heading.level === 'number' && + typeof heading.id === 'string' && + typeof heading.text === 'string' + ) && + (value.anchorAliases === undefined || + (record(value.anchorAliases) && + Object.values(value.anchorAliases).every( + (alias) => typeof alias === 'string' + ))) + ); +} +/** A successful HTTP response must still satisfy the shared reader boundary. */ +export function parseReaderBook(value: unknown): ReaderBook { + if ( + !record(value) || + !Array.isArray(value.pages) || + !value.pages.length || + !value.pages.every(page) || + !Array.isArray(value.groups) || + !Array.isArray(value.toc) || + !value.toc.every(node) + ) + throw Error('Invalid localized reader model'); + const pages = value.pages, + ids = new Set(pages.map((page) => page.id)), + slugs = new Set(pages.map((page) => page.slug)); + if (ids.size !== pages.length || slugs.size !== pages.length) + throw Error('Duplicate reader chapter identity'); + if ( + !value.groups.every( + (group) => + record(group) && + typeof group.title === 'string' && + strings(group.pages) && + group.pages.every((slug) => slugs.has(slug)) + ) + ) + throw Error('Invalid reader part membership'); + if ( + !pages.every( + (page) => + (page.parentId === null || ids.has(page.parentId)) && + page.children.every((id) => ids.has(id)) + ) + ) + throw Error('Invalid reader hierarchy'); + return value as unknown as ReaderBook; +} diff --git a/web/src/book-layout.ts b/web/src/book-layout.ts new file mode 100644 index 0000000..9a01639 --- /dev/null +++ b/web/src/book-layout.ts @@ -0,0 +1,607 @@ +import { resolveAnchor } from './anchors.ts'; +import { ui, language, fmt } from './i18n.ts'; +import { PageFlip } from 'page-flip'; +import {recordChapterCount,invalidateChapterCounts} from './chapter-counts.ts'; +import { prepareChapterSource, paginateChapter } from './pagination.ts'; +import { readingSize, applyReadingSize } from './reading-preferences.ts'; +import { query } from './dom.ts'; +import { copyBookSurface, ownedBookSurface } from './reader-surface.ts'; +import type { + ReaderController, + ReaderPage, + ReaderStorage, + Icon, + Navigate +} from './book.ts'; + +export interface BookLayoutState { + total: number; + folio: number; + layoutKey: string; + continuous: boolean; + size: number; + position: string; + previous: string; + next: string; + previousDisabled: boolean; + ready: boolean; + numbering: 'chapter'|'book'; +} +export interface BookLayout extends ReaderController { + turn(direction: number): void; + reflow(scale: number, continuous: boolean): void; + resize(): void; + getState(): BookLayoutState; +} +interface LayoutOptions { + app: HTMLElement; + page: ReaderPage; + pages: ReaderPage[]; + icon: Icon; + storage: ReaderStorage; + onNavigate: Navigate; + onState(state: BookLayoutState): void; + scale: number; + continuous: boolean; +} +const decodedImages = new Map>(); +function bookImagesReady(page: ReaderPage): Promise { + const sources=new Set([...page.html.matchAll(/]+src="([^"]+)"/g)].map(match=>match[1]!)); + return Promise.all( + [...sources].map((src) => { + let ready = decodedImages.get(src); + if (!ready) { + const image = new Image(); + image.src = src; + ready = image.decode().catch(() => { + decodedImages.delete(src); + }); + decodedImages.set(src, ready); + } + return ready; + }) + ); +} +/** Paginated HTML on full-size physical sheets. Source blocks are moved, never rewritten. */ +export function attachBookLayout({ + app, + page, + pages, + icon, + storage, + onNavigate, + onState, + scale, + continuous +}: LayoutOptions): BookLayout { + let flip: PageFlip | null = null, + disposed = false, + resizeTimer: ReturnType | undefined, + folio = 0, + portraitBook = innerWidth <= 1000; + const rtl = () => document.documentElement.dir === 'rtl'; + const physicalIndex = (n: number): number => + rtl() + ? Math.max( + 0, + total - (portraitBook ? 1 : 2) - (portraitBook ? n : n - (n % 2)) + ) + : n; + const currentPage = (): number => + flip + ? rtl() + ? Math.max( + 0, + total - (portraitBook ? 1 : 2) - flip.getCurrentPageIndex() + ) + : flip.getCurrentPageIndex() + : folio; + let size = readingSize(scale); + const idx = pages.indexOf(page); + applyReadingSize(size); + const volume = query('.bound-volume', app); + const isCurrent = (): boolean => !disposed && volume.isConnected; + const source = prepareChapterSource(page, ui, language()); + const originalHTML = source.innerHTML; + const restoreEmbeds = (root: ParentNode): void => + root + .querySelectorAll('iframe[data-embed-src]') + .forEach((frame) => { + frame.src = frame.dataset.embedSrc ?? ''; + delete frame.dataset.embedSrc; + }); + let total = 0, + layoutKey = '', + pageOffset = 0, + bookTotal = 0, + paginationRevision = 0, + ready = false; + let paginationTask:AbortController|null=null; + const copyTimers=new Set>(); + const frameIds=new Set(); + let imagesReady: Promise | null = null; + const reduced = (): boolean => + matchMedia('(prefers-reduced-motion:reduce)').matches; + function openContents() { + void onNavigate('/contents.html'); + } + function state(): BookLayoutState { + const p = currentPage(), + last = p + (innerWidth > 1000 ? 2 : 1) >= total; + return { + total, + folio: p, + layoutKey, + continuous, + size, + ready, + numbering:bookTotal?'book':'chapter', + position: continuous + ? ui('Continuous reading') + : ready + ? bookTotal ? `${pageOffset+p+1}${!portraitBook&&p+1${originalHTML}`; + restoreEmbeds(target); + total = 1; + ready = true; + footer(); + if(anchor)goToAnchor(anchor,false); + return; + } + const readyImages = (imagesReady ??= bookImagesReady(page)); + if(!flip)initialPages(keep); + onState(state()); + const {w,h,portrait}=sheetLayout(); + layoutKey=`${w}/${h}/${size}`; + const cacheKey=`${document.documentElement.lang}/${layoutKey}/${portrait}`; + const probe=document.createElement('div');probe.className='folio-measure';probe.style.width=w+'px';probe.style.height=h+'px'; + const probePage=document.createElement('section');probePage.className='folio-page'; + const probeContent=document.createElement('article');probeContent.className='folio-content prose';probeContent.innerHTML=originalHTML; + probeContent.querySelectorAll('[id]').forEach(element=>element.removeAttribute('id'));probePage.append(probeContent);probe.append(probePage);volume.append(probe); + let cancel:()=>void=()=>{}; + try{ + probeContent.getBoundingClientRect(); + const cancelled=new Promise(resolve=>{cancel=()=>resolve();task.signal.addEventListener('abort',cancel,{once:true});}); + await Promise.race([Promise.all([document.fonts.ready,readyImages]),cancelled]); + }finally{task.signal.removeEventListener('abort',cancel);probe.remove();} + if(!isCurrent()||task.signal.aborted||revision!==paginationRevision)return; + // Only this chapter is measured after its fonts/images settle. + const sheets=paginateChapter({page,pages,icon,host:volume,w,h,portrait,label:ui,locale:language()}); + const numbering=recordChapterCount(pages,cacheKey,page,sheets.length); + const previous = ownedBookSurface(volume); + const backdrop = previous?.textContent?.trim() + ? copyBookSurface(previous) + : null; + if (backdrop && previous) { + const r = previous.getBoundingClientRect(), + v = volume.getBoundingClientRect(); + Object.assign(backdrop.style, { + position: 'absolute', + left: `${r.left - v.left - volume.clientLeft}px`, + top: `${r.top - v.top - volume.clientTop}px`, + width: `${r.width}px`, + height: `${r.height}px`, + pointerEvents: 'none', + zIndex: '4' + }); + volume.append(backdrop); + } + const keepPage = flip ? currentPage() : keep; + const target = clearBook(); + if (!target) { + backdrop?.remove(); + return; + } + portraitBook = portrait; + target.style.width = (portrait ? w : 2 * w) + 'px'; + target.style.height = h + 'px'; + pageOffset=numbering?.offset||0; + bookTotal=numbering?.total||0; + target.dataset.pageOffset = String(pageOffset); + target.dataset.bookPages = String(bookTotal); + for (const sheet of sheets) { + const local = Number(sheet.dataset.folio); + sheet.classList.toggle( + 'folio-verso', + !portrait && (rtl() ? local % 2 === 1 : local % 2 === 0) + ); + const number = query( + '.folio-footer>span:last-child', + sheet + ); + number.textContent = String(pageOffset + local + 1); + number.dir = 'ltr'; + restoreEmbeds(sheet); + } + if (rtl()) sheets.reverse(); + sheets.forEach((s) => target.append(s)); + total = sheets.length; + flip = new PageFlip(target, { + width: w, + height: h, + size: 'fixed', + minWidth: w, + maxWidth: w, + minHeight: h, + maxHeight: h, + autoSize: false, + drawShadow: true, + flippingTime: 560, + maxShadowOpacity: document.body.classList.contains('night') ? 0.55 : 0.2, + usePortrait: portrait, + showCover: false, + startPage: physicalIndex(Math.max(0, Math.min(keepPage, total - 1))), + clickEventForward: true, + useMouseEvents: false, + disableFlipByClick: false, + mobileScrollSupport: false, + showPageCorners: false + }); + flip.on('flip', footer); + flip.on('changeState', (event) => + target.classList.toggle('paper-turning', event.data === 'flipping') + ); + flip.loadFromHTML(sheets); + ready = true; + // These are interior paper leaves, including an unpaired final sheet. + for (let i = 0; i < sheets.length; i++) { + flip.getPage(i).setDensity('soft'); + flip.getPage(i).setDrawingDensity('soft'); + } + const frame=requestAnimationFrame(() => { + frameIds.delete(frame); + backdrop?.remove(); + if (!isCurrent() || revision !== paginationRevision) return; + footer(); + if(anchor)goToAnchor(anchor,false); + }); + frameIds.add(frame); + } + function turn(direction: number): void { + if (!isCurrent() || !ready || continuous || !flip) return; + const p = currentPage(); + const last = p + (innerWidth > 1000 ? 2 : 1) >= total; + if (direction > 0 && last) { + if (idx + 1 < pages.length) onNavigate('/' + pages[idx + 1].slug); + else openContents(); + return; + } + if (direction < 0 && p === 0) { + if (idx > 0) onNavigate('/' + pages[idx - 1].slug); + return; + } + const physicalDirection = rtl() ? -direction : direction; + if (reduced()) { + physicalDirection > 0 ? flip.turnToNextPage() : flip.turnToPrevPage(); + } else + physicalDirection > 0 ? flip.flipNext('bottom') : flip.flipPrev('bottom'); + } + function goToAnchor(id: string, animate = true): void { + if (!isCurrent() || !id) return; + const el = volume.querySelector( + '#' + CSS.escape(resolveAnchor(page, id)) + ); + if (!el) return; + if (continuous) { + el.scrollIntoView({ behavior: animate&&!reduced()?'smooth':'instant' }); + return; + } + const s = el.closest('.folio-page'); + if (s && flip) { + const n = Number(s.dataset.folio); + if (animate && !reduced()) flip.flip(physicalIndex(n), 'bottom'); + else flip.turnToPage(physicalIndex(n)); + el.closest('.folio-overflow')?.scrollTo({ + top: Math.max(0, el.offsetTop - 20) + }); + } + } + const onHash = () => goToAnchor(location.hash.slice(1)); + addEventListener('hashchange', onHash); + const key = (e: KeyboardEvent) => { + if ( + !isCurrent() || + document.querySelector('dialog[open]') || + e.ctrlKey || + e.metaKey || + e.shiftKey || + e.altKey || + !(e.target instanceof Element) || + /INPUT|TEXTAREA|SELECT/.test(e.target.tagName) + ) + return; + if (document.body.classList.contains('menu-open')) return; + if (e.key === 'ArrowRight') { + e.preventDefault(); + turn(rtl() ? -1 : 1); + } + if (e.key === 'ArrowLeft') { + e.preventDefault(); + turn(rtl() ? 1 : -1); + } + }; + addEventListener('keydown', key); + let down: { x: number; y: number; type: string } | null = null, + lastSwipe = 0; + volume.addEventListener('pointerdown', (e: PointerEvent) => { + down = { x: e.clientX, y: e.clientY, type: e.pointerType }; + }); + volume.addEventListener('pointerup', (e: PointerEvent) => { + const target = e.target instanceof Element ? e.target : null; + if ( + down?.type === 'touch' && + !target?.closest( + 'a,button,input,pre,code,.folio-overflow,.table-scroll' + ) && + Math.abs(e.clientX - down.x) > 65 && + Math.abs(e.clientY - down.y) < 60 + ) { + turn((e.clientX < down.x ? 1 : -1) * (document.dir === 'rtl' ? -1 : 1)); + lastSwipe = Date.now(); + } + }); + function blankClick(e: MouseEvent): void { + const target = e.target instanceof Element ? e.target : null; + if ( + continuous || + !flip || + e.button !== 0 || + e.ctrlKey || + e.metaKey || + e.shiftKey || + e.altKey || + Date.now() - lastSwipe < 600 || + target?.closest( + 'a,button,input,select,summary,details,pre,code,table,.folio-overflow,.table-scroll' + ) || + !getSelection()?.isCollapsed + ) + return; + if (down && Math.hypot(e.clientX - down.x, e.clientY - down.y) > 8) return; + if (!target?.closest('.folio-page,.page-book,.stf__wrapper')) return; + const caret = document.caretRangeFromPoint?.(e.clientX, e.clientY); + if (caret?.startContainer.nodeType === Node.TEXT_NODE) { + const text = caret.startContainer as Text; + const value = text.textContent ?? ''; + const offset = caret.startOffset; + for (const at of [offset - 1, offset]) { + if (at < 0 || at >= text.length || !value[at]?.trim()) continue; + const r = document.createRange(); + r.setStart(text, at); + r.setEnd(text, at + 1); + if ( + [...r.getClientRects()].some( + (b) => + e.clientX >= b.left - 2 && + e.clientX <= b.right + 2 && + e.clientY >= b.top && + e.clientY <= b.bottom + ) + ) + return; + } + } + const rect = volume.getBoundingClientRect(); + turn( + (e.clientX < rect.left + rect.width / 2 ? -1 : 1) * + (document.dir === 'rtl' ? -1 : 1) + ); + } + volume.addEventListener('click', blankClick); + const contentsClick = (e: MouseEvent): void => { + if ( + e.target instanceof Element && + e.target.closest('[data-open-contents]') + ) { + e.preventDefault(); + openContents(); + } + }; + app.addEventListener('click', contentsClick); + app.addEventListener('click', copyCode); + const detailsToggle = (e: Event): void => { + const detail = e.target; + if ( + continuous || + !(detail instanceof HTMLDetailsElement) || + !detail.closest('.folio-content') || + !detail.open + ) + return; + const body = detail.closest('.folio-content'); + if (!body) return; + const remaining = + body.getBoundingClientRect().bottom - + detail.getBoundingClientRect().top - + 8; + detail.style.maxHeight = Math.max(56, remaining) + 'px'; + detail.style.overflowY = 'auto'; + detail.style.scrollbarWidth = 'thin'; + }; + app.addEventListener('toggle', detailsToggle, true); + async function copyCode(e: MouseEvent): Promise { + const target = e.target instanceof Element ? e.target : null; + const button = target?.closest('.copy-code'); + if (!button) return; + try { + const code = query( + 'code', + query('.code-block', button) + ); + await navigator.clipboard.writeText(code.textContent ?? ''); + if(disposed)return; + button.textContent = ui('Copied'); + const timer=setTimeout(()=>{copyTimers.delete(timer);if(button.isConnected)button.textContent=ui('Copy code');},1800);copyTimers.add(timer); + } catch { + if(disposed)return; + button.textContent = ui('Select code to copy'); + } + } + function resized(): void { + clearTimeout(resizeTimer); + resizeTimer = setTimeout(() => { + if (isCurrent()) void paginate(folio,getCurrentAnchor()); + }, 250); + } + const fontsChanged=()=>{invalidateChapterCounts(pages);if(ready)resized();}; + document.fonts.addEventListener('loadingdone',fontsChanged); + addEventListener('resize', resized); + const savedFolio = Number(storage.get('alux-folio-' + page.slug) || 0); + if (isCurrent()) void paginate(savedFolio,location.hash.slice(1)||undefined); + function getCurrentAnchor(): string | undefined { + const headings = [ + ...app.querySelectorAll( + '#page-book h1[id],#page-book h2[id],#page-book h3[id],#page-book h4[id]' + ) + ]; + if (continuous) + return ( + headings.filter((h) => h.getBoundingClientRect().top < 170).at(-1) || + headings[0] + )?.id; + headings.sort( + (a, b) => + Number(a.closest('.folio-page')?.dataset.folio || 0) - + Number(b.closest('.folio-page')?.dataset.folio || 0) + ); + const current = currentPage(); + return ( + headings + .filter( + (h) => + Number(h.closest('.folio-page')?.dataset.folio) <= + current + ) + .at(-1) || headings[0] + )?.id; + } + return { + goToAnchor, + getCurrentAnchor, + openContents, + turn, + resize: resized, + reflow(nextScale, nextContinuous) { + const anchor=getCurrentAnchor(); + scale = nextScale; + size = readingSize(scale); + continuous = nextContinuous; + void paginate(folio,anchor); + }, + dispose() { + disposed = true; + paginationRevision++; + paginationTask?.abort(); + for(const timer of copyTimers)clearTimeout(timer);copyTimers.clear(); + for(const frame of frameIds)cancelAnimationFrame(frame);frameIds.clear(); + document.fonts.removeEventListener('loadingdone',fontsChanged); + clearTimeout(resizeTimer); + removeEventListener('resize', resized); + removeEventListener('keydown', key); + removeEventListener('hashchange', onHash); + app.removeEventListener('click', copyCode); + app.removeEventListener('click', contentsClick); + volume.removeEventListener('click', blankClick); + app.removeEventListener('toggle', detailsToggle, true); + flip?.destroy(); + flip = null; + }, + getState: state + }; +} diff --git a/web/src/book-view.tsx b/web/src/book-view.tsx new file mode 100644 index 0000000..de13f63 --- /dev/null +++ b/web/src/book-view.tsx @@ -0,0 +1,275 @@ +import { createEffect, createSignal, onCleanup, onMount } from 'solid-js'; +import { attachBookLayout } from './book-layout.ts'; +import type { BookLayout, BookLayoutState } from './book-layout.ts'; +import { + Brand, + BookSidebar, + Icon, + LanguagePicker, + icon +} from './reader-ui.tsx'; +import { ui, languageURL } from './i18n.ts'; +import { hasBookmark, toggleBookmark } from './bookmarks.ts'; +import type { + ReaderBook, + ReaderPage, + ReaderStorage, + ReaderController, + Announce, + Navigate +} from './book.ts'; +import type { LanguageCode } from './locale-routing.ts'; + +export interface ReaderViewProps { + book: ReaderBook; + page: ReaderPage; + locale: LanguageCode; + storage: ReaderStorage; + count: number; + onSearch(): void; + onBookmarks(): void; + onLanguage(locale: LanguageCode): void; + onNavigate: Navigate; + announce: Announce; + onController(controller: ReaderController | null): void; + onMusicHost(host: HTMLElement | null): void; + dark: boolean; + onTheme(): void; + scale: number; + onScale(delta: number): void; +} +export function BookView(props: ReaderViewProps) { + let root!: HTMLDivElement, layout: BookLayout | undefined; + const [menu, setMenu] = createSignal(innerWidth >= 1280), + [continuous, setContinuous] = createSignal( + props.storage.get('alux-reader-mode') === 'scroll' + ); + const [state, setState] = createSignal({ + total: 0, + folio: 0, + layoutKey: '', + continuous: continuous(), + size: 0, + position: ui('Preparing the pages…'), + previous: ui('Previous page'), + next: ui('Next page'), + previousDisabled: true, + ready: false, + numbering:'chapter' + }); + const saved = () => { + props.count; + return hasBookmark(props.page.slug); + }; + const label = () => ui(menu() ? 'Hide contents' : 'Show contents'); + createEffect(() => { + document.body.className = + 'reading-view bound-reading' + + (props.dark ? ' night' : '') + + (innerWidth >= 1280 && !menu() ? ' contents-collapsed' : '') + + (innerWidth < 1280 && menu() ? ' menu-open' : '') + + (continuous() ? ' continuous-reading' : ''); + }); + createEffect(() => { + const nextScale = props.scale, + nextContinuous = continuous(); + layout?.reflow(nextScale, nextContinuous); + }); + function toggleMenu(open: boolean) { + setMenu(open); + layout?.resize(); + if (innerWidth < 1280) + (open + ? root.querySelector('.book-sidebar .active') + : root.querySelector('#toggle-menu') + )?.focus(); + } + function mark(event: MouseEvent) { + const added = toggleBookmark({ + slug: props.page.slug, + realm: 'magic', + anchor: layout?.getCurrentAnchor() || '', + folio: layout?.getState().folio || 0 + }); + props.announce( + ui(added ? 'Chapter bookmarked' : 'Bookmark removed'), + event.currentTarget as HTMLElement + ); + } + onMount(() => { + layout = attachBookLayout({ + app: root, + page: props.page, + pages: props.book.pages, + icon, + storage: props.storage, + onNavigate: props.onNavigate, + onState: setState, + scale: props.scale, + continuous: continuous() + }); + props.onController(layout); + const escape = (event: KeyboardEvent) => { + if (event.key === 'Escape' && menu() && innerWidth < 1280) + toggleMenu(false); + }; + const resize = () => { + setMenu(innerWidth >= 1280); + }; + addEventListener('keydown', escape); + addEventListener('resize', resize); + onCleanup(() => { + removeEventListener('keydown', escape); + removeEventListener('resize', resize); + layout?.dispose(); + props.onController(null); + props.onMusicHost(null); + }); + }); + return ( +
+ + + ); +} diff --git a/web/src/book.ts b/web/src/book.ts new file mode 100644 index 0000000..c304569 --- /dev/null +++ b/web/src/book.ts @@ -0,0 +1,52 @@ +/** The two readers consume this model; mdBook paths are a build-time concern. */ +export interface Heading { + level: number; + id: string; + text: string; +} +export interface ReaderPage { + id: string; + title: string; + source: string; + group: string; + slug: string; + hash: string; + markdown: string; + headings: Heading[]; + html: string; + text: string; + minutes: number; + parentId: string | null; + children: string[]; + anchorAliases?: Record; +} +export interface BookGroup { + title: string; + pages: string[]; +} +export type BookNode = + | { kind: 'chapter'; id: string; title: string; children: BookNode[] } + | { kind: 'part'; title: string } + | { kind: 'separator' }; +export interface ReaderBook { + groups: BookGroup[]; + pages: ReaderPage[]; + toc: BookNode[]; +} +export interface ReaderStorage { + get(key: string): string | null; + set(key: string, value: string | number | boolean): void; +} +export type Icon = (name: string) => string; +export type Navigate = (href: string) => void | Promise; +export type Announce = ( + message: string, + returnFocus?: HTMLElement | null +) => void; +export interface ReaderController { + getCurrentAnchor(): string | undefined; + goToAnchor(id: string, animate?: boolean): void; + restorePosition?(): void; + openContents?(): void; + dispose(): void; +} diff --git a/web/src/bookmarks.ts b/web/src/bookmarks.ts new file mode 100644 index 0000000..82a4bd7 --- /dev/null +++ b/web/src/bookmarks.ts @@ -0,0 +1,9 @@ +export interface BookmarkEntry { slug: string; realm: 'magic' | 'real'; anchor: string; folio?: number; scroll?: number; updatedAt?: number; title?: string } +const key='alux-bookmarks-v1'; +export function bookmarks(): BookmarkEntry[]{try{const value=localStorage.getItem(key);if(value!==null){const list:unknown=JSON.parse(value);return Array.isArray(list)?list.filter((x):x is BookmarkEntry=>typeof x==='object'&&x!==null&&'slug'in x&&typeof x.slug==='string'):[];}const old=localStorage.getItem('alux-bookmark');const list:BookmarkEntry[]=old?[{slug:old,realm:'magic',anchor:'',updatedAt:Date.now()}]:[];localStorage.setItem(key,JSON.stringify(list));return list;}catch{return[];}} +export const hasBookmark=(slug:string):boolean=>bookmarks().some(item=>item.slug===slug); +function save(list:BookmarkEntry[]):void{try{localStorage.setItem(key,JSON.stringify(list));}catch{}dispatchEvent(new Event('alux-bookmarks-changed'));} +export function toggleBookmark(entry:BookmarkEntry):boolean{const list=bookmarks();const exists=list.some(item=>item.slug===entry.slug);save(exists?list.filter(item=>item.slug!==entry.slug):[{...entry,updatedAt:Date.now()},...list]);return !exists;} +export function removeBookmark(slug:string):void{save(bookmarks().filter(item=>item.slug!==slug));} + +addEventListener('storage',event=>{if(event.key===key)dispatchEvent(new Event('alux-bookmarks-changed'));}); diff --git a/web/src/chapter-counts.ts b/web/src/chapter-counts.ts new file mode 100644 index 0000000..e2b6aac --- /dev/null +++ b/web/src/chapter-counts.ts @@ -0,0 +1,12 @@ +import type {ReaderPage} from './book.ts'; +const counts=new WeakMap>>(); +/** Counts are learned only from chapters the reader actually opened, never from prefetch measurements. */ +export function recordChapterCount(pages:ReaderPage[],layout:string,page:ReaderPage,count:number):{offset:number;total:number}|null{ + if(!pages.includes(page)||!Number.isInteger(count)||count<1)throw Error('Invalid visited chapter count'); + let layouts=counts.get(pages);if(!layouts){layouts=new Map();counts.set(pages,layouts);} + let visited=layouts.get(layout);if(!visited){visited=new Map();layouts.set(layout,visited);if(layouts.size>8)layouts.delete(layouts.keys().next().value!);} + visited.set(page.id,count); + const known=pages.map(chapter=>visited!.get(chapter.id));if(known.some(value=>value===undefined))return null; + return {offset:known.slice(0,pages.indexOf(page)).reduce((sum,value)=>sum+value!,0),total:known.reduce((sum,value)=>sum+value!,0)}; +} +export function invalidateChapterCounts(pages:ReaderPage[]):void{counts.delete(pages);} diff --git a/web/src/content-loader.ts b/web/src/content-loader.ts new file mode 100644 index 0000000..9a38645 --- /dev/null +++ b/web/src/content-loader.ts @@ -0,0 +1,27 @@ +import type { ReaderBook } from './book.ts'; +import type { LanguageCode } from './locale-routing.ts'; +import { parseReaderBook } from './book-data.ts'; + +/** Cache only requested editions; failures remain retryable. */ +export function createBookLoader( + fetchBook: typeof fetch = fetch +): (locale: LanguageCode) => Promise { + const loaded = new Map>(); + return (locale) => { + const cached = loaded.get(locale); + if (cached) return cached; + const pending = fetchBook('/content/' + locale + '.json') + .then(async (response) => { + if (!response.ok) throw Error('Book language unavailable: ' + locale); + const value: unknown = await response.json(); + return parseReaderBook(value); + }) + .catch((error: unknown) => { + loaded.delete(locale); + throw error; + }); + loaded.set(locale, pending); + return pending; + }; +} +export const loadBook = createBookLoader(); diff --git a/web/src/contents.ts b/web/src/contents.ts new file mode 100644 index 0000000..434380c --- /dev/null +++ b/web/src/contents.ts @@ -0,0 +1,37 @@ +export const partRoutes = [ + 'parts/the-semantic-view.html', + 'parts/design-by-meaning-in-rust.html', + 'parts/concepts.html', + 'parts/insights.html' +]; +import { englishMessages } from './ui-messages.ts'; +import type { MessageKey } from './ui-messages.ts'; +const roman = ['I', 'II', 'III', 'IV', 'V']; +export function contentsMarkup({ + groups, + pages, + icon, + real = false, + label = (key: MessageKey) => englishMessages[key] +}: { + groups: BookGroup[]; + pages: ReaderPage[]; + icon: Icon; + real?: boolean; + label?: (key: MessageKey) => string; +}): string { + const prefix = real ? '/real/' : '/'; + return `

${label('Table of contents')}

${label('Read the introduction')} ${icon('arrow-right')}
${groups + .map( + (g, i) => + `
${roman[i]}

${g.title}

    ${g.pages + .map((slug, j) => { + const p = pages.find((p) => p.slug === slug); + if (!p) throw new Error('Missing contents chapter: ' + slug); + return `
  1. ${String(j + 1).padStart(2, '0')}${p.title}${icon('arrow-up-right')}
  2. `; + }) + .join('')}
` + ) + .join('')}
`; +} +import type { BookGroup, Icon, ReaderPage } from './book.ts'; diff --git a/web/src/dom.ts b/web/src/dom.ts new file mode 100644 index 0000000..6a680da --- /dev/null +++ b/web/src/dom.ts @@ -0,0 +1,9 @@ +/** Required UI elements fail at their boundary rather than hiding a broken render. */ +export function query(selector: string, root: ParentNode = document): T { + const element = root.querySelector(selector); + if (!element) throw new Error(`Missing reader element: ${selector}`); + return element; +} +export function targetElement(event: Event): Element | null { + return event.target instanceof Element ? event.target : null; +} diff --git a/web/src/gateway-welcome.ts b/web/src/gateway-welcome.ts new file mode 100644 index 0000000..985dd1c --- /dev/null +++ b/web/src/gateway-welcome.ts @@ -0,0 +1,34 @@ +import {language} from './i18n.ts'; +import type {LanguageCode} from './locale-routing.ts'; + +const labels:Record={ + en:['Listen to the welcome','Replay welcome','Stop welcome'], + zh:['聆听欢迎语','重播欢迎语','停止播放'], + 'zh-hant':['聆聽歡迎語','重播歡迎語','停止播放'], + ja:['歓迎の言葉を聴く','もう一度聴く','再生を停止'], + ko:['환영 인사 듣기','다시 듣기','재생 중지'], + vi:['Nghe lời chào','Nghe lại lời chào','Dừng phát'], + de:['Begrüßung anhören','Erneut anhören','Wiedergabe stoppen'], + es:['Escuchar la bienvenida','Volver a escuchar','Detener reproducción'], + ru:['Послушать приветствие','Повторить приветствие','Остановить'], + uk:['Послухати привітання','Повторити привітання','Зупинити'], + ar:['استمع إلى الترحيب','أعد سماع الترحيب','إيقاف التشغيل'] +}; + +export function mountGatewayWelcome(root:HTMLElement):()=>void{ + const locale=language(),copy=labels[locale]||labels.en; + const audio=new Audio(`${import.meta.env.BASE_URL}audio/welcome/${locale}.mp3`); + audio.preload='auto';audio.loop=false;audio.volume=1;audio.hidden=true;audio.dataset.gatewayWelcome='';audio.setAttribute('aria-hidden','true');let disposed=false,played=false,stopped=false; + const button=document.createElement('button');button.type='button';button.className='gateway-welcome'; + const update=()=>{const playing=!audio.paused&&!audio.ended;button.textContent=playing?'◼ '+copy[2]:'▷ '+copy[played?1:0];button.setAttribute('aria-label',copy[playing?2:played?1:0]);button.dataset.playing=String(playing);}; + const play=()=>{if(disposed||document.hidden)return;audio.play().then(()=>{if(disposed||stopped){audio.pause();return;}played=true;update();}).catch(()=>update());}; + const unlock=(event:Event)=>{if(event.composedPath().includes(button)||played||stopped||disposed)return;play();}; + const gestures=['pointerdown','touchend','click','keydown']; + for(const type of gestures)document.addEventListener(type,unlock,{capture:true,passive:true}); + button.title=copy[2]+' / '+copy[1]; + button.addEventListener('click',()=>{if(audio.paused||audio.ended){stopped=false;audio.currentTime=0;play();}else{stopped=true;audio.pause();update();}}); + for(const event of ['playing','pause','ended','error'])audio.addEventListener(event,update); + const visibility=()=>{if(document.hidden)audio.pause();};document.addEventListener('visibilitychange',visibility); + root.append(audio,button);update();play(); + return ()=>{disposed=true;for(const type of gestures)document.removeEventListener(type,unlock,{capture:true});audio.pause();audio.removeAttribute('src');audio.load();button.remove();document.removeEventListener('visibilitychange',visibility);}; +} diff --git a/web/src/i18n.ts b/web/src/i18n.ts new file mode 100644 index 0000000..43f257d --- /dev/null +++ b/web/src/i18n.ts @@ -0,0 +1,158 @@ +import type { ReaderBook } from './book.ts'; +import { createSignal } from 'solid-js'; +import { loadBook } from './content-loader.ts'; +import { englishMessages } from './ui-messages.ts'; +import type { UIMessages, MessageKey } from './ui-messages.ts'; +import { formatMessage } from './ui-format.ts'; +import type { VariableMessage } from './ui-format.ts'; +import { + languages, + normalizeLanguage, + pathLanguage, + stripLanguage, + languagePath, + htmlLanguage +} from './locale-routing.ts'; +import type { LanguageCode } from './locale-routing.ts'; +export { languages, stripLanguage }; + +const codes: LanguageCode[] = languages.map((x) => x.code); +const dictionaries = import.meta.glob('../locales/ui/*.json', { + import: 'default' +}); +interface LocalizedEdition { + locale: LanguageCode; + book: ReaderBook; + messages: UIMessages; +} +const [edition, setEdition] = createSignal(); +export { edition }; +const get = (key: string, session = false): string | null => { + try { + return (session ? sessionStorage : localStorage).getItem(key); + } catch { + return null; + } +}; +const put = (key: string, value: string, session = false): void => { + try { + (session ? sessionStorage : localStorage).setItem(key, value); + } catch {} +}; +export const language = (): LanguageCode => edition()?.locale || 'en'; +export function fmt(message: VariableMessage): string { + return formatMessage(language(), message); +} +export function languageURL(href: string): string { + const url = new URL(href, location.origin); + if (url.origin !== location.origin) return href; + url.pathname = languagePath(url.pathname, language()); + url.searchParams.delete('lang'); + return url.pathname + url.search + url.hash; +} +export function countryLanguage(country: string): LanguageCode { + if (country === 'CN') return 'zh'; + if (['TW', 'HK', 'MO'].includes(country)) return 'zh-hant'; + if (['DE', 'AT', 'LI'].includes(country)) return 'de'; + if ( + [ + 'ES', + 'MX', + 'AR', + 'CL', + 'CO', + 'PE', + 'VE', + 'EC', + 'BO', + 'PY', + 'UY', + 'CR', + 'PA', + 'GT', + 'HN', + 'SV', + 'NI', + 'DO', + 'CU', + 'GQ' + ].includes(country) + ) + return 'es'; + if (country === 'VN') return 'vi'; + if (country === 'RU') return 'ru'; + if (country === 'UA') return 'uk'; + if (country === 'JP') return 'ja'; + if (['KR', 'KP'].includes(country)) return 'ko'; + if ( + [ + 'AE', + 'SA', + 'EG', + 'IQ', + 'JO', + 'KW', + 'QA', + 'BH', + 'OM', + 'YE', + 'LB', + 'SY', + 'PS', + 'DZ', + 'MA', + 'TN', + 'LY', + 'SD', + 'SO', + 'MR', + 'DJ', + 'KM' + ].includes(country) + ) + return 'ar'; + return 'en'; +} +export async function resolveLanguage() { + const explicit = + pathLanguage(location.pathname) || + normalizeLanguage(new URL(location.href).searchParams.get('lang')); + if (explicit) return explicit; + const saved = normalizeLanguage(get('alux-programming-language')); + if (saved) return saved; + const cached = normalizeLanguage(get('alux-programming-ip-language', true)); + if (cached) return cached; + try { + const r = await fetch('https://get.geojs.io/v1/ip/country.json', { + signal: AbortSignal.timeout(1800), + credentials: 'omit', + referrerPolicy: 'no-referrer' + }); + if (!r.ok) throw Error('Country unavailable'); + const { country } = await r.json(); + const result = countryLanguage(String(country).toUpperCase()); + put('alux-programming-ip-language', result, true); + return result; + } catch { + return 'en'; + } +} +export async function setLanguage( + next: LanguageCode, + manual = false, + signal?:AbortSignal +): Promise { + if (!codes.includes(next)) throw Error('Unsupported language'); + const load = dictionaries[`../locales/ui/${next}.json`]; + if (!load) throw Error('Interface language unavailable'); + const [book, ui] = await Promise.all([loadBook(next), load()]); + signal?.throwIfAborted(); + document.documentElement.lang = htmlLanguage(next); + document.documentElement.dir = next === 'ar' ? 'rtl' : 'ltr'; + document.documentElement.dataset.locale = next; + if (manual) put('alux-programming-language', next); + setEdition({ locale: next, book, messages: ui }); +} +export function ui(key: MessageKey): string { + return (edition()?.messages || englishMessages)[key]; +} diff --git a/web/src/locale-routing.ts b/web/src/locale-routing.ts new file mode 100644 index 0000000..629941e --- /dev/null +++ b/web/src/locale-routing.ts @@ -0,0 +1,12 @@ +export const languages=[{code:'en',name:'English'},{code:'zh',name:'简体中文'},{code:'zh-hant',name:'繁體中文'},{code:'ja',name:'日本語'},{code:'ko',name:'한국어'},{code:'vi',name:'Tiếng Việt'},{code:'de',name:'Deutsch'},{code:'es',name:'Español'},{code:'ru',name:'Русский'},{code:'uk',name:'Українська'},{code:'ar',name:'العربية'}] as const; +export type LanguageCode=(typeof languages)[number]['code']; +export function normalizeLanguage(value:unknown):LanguageCode|null{ + const code=String(value||'').toLowerCase().replaceAll('_','-'); + if(['zh-hans','zh-cn','zh-sg'].includes(code))return'zh'; + if(['zh-tw','zh-hk','zh-mo'].includes(code))return'zh-hant'; + return languages.some(language=>language.code===code)?code as LanguageCode:null; +} +export function pathLanguage(pathname:string):LanguageCode|null{return normalizeLanguage(pathname.split('/').filter(Boolean)[0]);} +export function stripLanguage(pathname:string):string{const pieces=pathname.split('/').filter(Boolean);if(normalizeLanguage(pieces[0]))pieces.shift();return'/'+pieces.join('/')+(pathname.endsWith('/')&&pieces.length?'/':'');} +export function languagePath(pathname:string,language:LanguageCode):string{const path=stripLanguage(pathname);return language==='en'?path:'/'+language+(path==='/'?'/':path);} +export const htmlLanguage=(code:LanguageCode):string=>code==='zh'?'zh-Hans':code==='zh-hant'?'zh-Hant':code; diff --git a/web/src/main.tsx b/web/src/main.tsx new file mode 100644 index 0000000..4e4c56e --- /dev/null +++ b/web/src/main.tsx @@ -0,0 +1,22 @@ +import '@fontsource/cormorant-garamond/500.css'; +import '@fontsource/cormorant-garamond/600.css'; +import '@fontsource/cormorant-garamond/500-italic.css'; +import 'katex/dist/katex.min.css'; +import '../style.css'; +import '../immersive.css'; +import '../book-reader.css'; +import '../contents.css'; +import '../refinements.css'; +import '../worlds.css'; +import '../real-reader.css'; +import '../gateway.css'; +import '../reader-typography.css'; +import '../reader-dialogs.css'; +import '../reader-materials.css'; +import '../reader-presentation.css'; +import '../reader-music.css'; +import { render } from 'solid-js/web'; +import { ReaderApp } from './reader-app.tsx'; +const root = document.getElementById('app'); +if (!root) throw Error('Missing reader root'); +render(() => , root); diff --git a/web/src/music-controls.tsx b/web/src/music-controls.tsx new file mode 100644 index 0000000..cd4f5bd --- /dev/null +++ b/web/src/music-controls.tsx @@ -0,0 +1,202 @@ +import { Show, createEffect, createSignal, onCleanup, onMount } from 'solid-js'; +import { Portal } from 'solid-js/web'; +import { musicCopy, musicHints } from './music-messages.ts'; +import { + readerAudioState, + subscribeReaderAudio, + toggleReaderAudio, + setReaderVolume +} from './reader-audio.ts'; +import type { LanguageCode } from './locale-routing.ts'; + +export function MusicControls(props: { + host: HTMLElement | null; + locale: LanguageCode; +}) { + const [state, setState] = createSignal(readerAudioState()), + [visible, setVisible] = createSignal(false), + [position, setPosition] = createSignal({ left: '12px', top: '12px' }); + let button: HTMLButtonElement | undefined, + panel: HTMLElement | undefined, + timer: ReturnType | undefined, + keyboard = false, + adjusting = false; + const copy = () => musicCopy[props.locale]; + const dismiss = () => { + clearTimeout(timer); + keyboard = false; + adjusting = false; + setVisible(false); + }; + function place() { + if (!button || !panel || !visible()) return; + const rect = button.getBoundingClientRect(), + bounds = panel.getBoundingClientRect(); + setPosition({ + left: + Math.max( + 12, + Math.min(innerWidth - bounds.width - 12, rect.right - bounds.width) + ) + 'px', + top: + Math.max( + 12, + Math.min(innerHeight - bounds.height - 12, rect.bottom + 8) + ) + 'px' + }); + } + function schedule(delay = 5000) { + clearTimeout(timer); + timer = setTimeout(() => { + if (!panel?.matches(':hover') && !keyboard && !adjusting) dismiss(); + }, delay); + } + function show() { + setVisible(true); + requestAnimationFrame(place); + schedule(); + } + let previous = state().hintRevision; + createEffect(() => { + const revision = state().hintRevision; + if (revision !== previous) { + previous = revision; + show(); + } + if (!state().realm) dismiss(); + }); + createEffect(() => { + props.host; + props.locale; + requestAnimationFrame(place); + }); + onMount(() => { + const unsubscribe = subscribeReaderAudio(setState); + const finish = () => { + if (adjusting) { + adjusting = false; + schedule(2000); + } + }; + const outside = (event: MouseEvent) => { + if ( + !(event.target instanceof Element) || + !event.target.closest('[data-reader-music]') + ) + dismiss(); + }; + const escape = (event: KeyboardEvent) => { + if (event.key === 'Escape') dismiss(); + }; + addEventListener('resize', place); + addEventListener('scroll', place, { passive: true }); + document.addEventListener('click', outside); + document.addEventListener('keydown', escape); + document.addEventListener('pointerup', finish, { passive: true }); + document.addEventListener('pointercancel', finish, { passive: true }); + onCleanup(() => { + unsubscribe(); + clearTimeout(timer); + removeEventListener('resize', place); + removeEventListener('scroll', place); + document.removeEventListener('click', outside); + document.removeEventListener('keydown', escape); + document.removeEventListener('pointerup', finish); + document.removeEventListener('pointercancel', finish); + }); + }); + return ( + <> + + {(host) => ( + + + + )} + + + + + + ); +} diff --git a/web/src/music-messages.ts b/web/src/music-messages.ts new file mode 100644 index 0000000..a25eb0c --- /dev/null +++ b/web/src/music-messages.ts @@ -0,0 +1,194 @@ +import type { LanguageCode } from './locale-routing.ts'; +export type MusicCopy = { + music: string; + on: string; + off: string; + volume: string; + close: string; + promptTitle: string; + promptBody: string; + withMusic: string; + withoutMusic: string; + unavailable: string; +}; +export const musicCopy: Record = { + en: { + music: 'Reading music', + on: 'Play music', + off: 'Pause music', + volume: 'Volume', + close: 'Close', + promptTitle: 'A little music for this world?', + promptBody: + 'Let the forest breathe softly in the background while you read.', + withMusic: 'Read with music', + withoutMusic: 'Read without music', + unavailable: 'Music could not start. Try again from the music button.' + }, + zh: { + music: '阅读音乐', + on: '播放音乐', + off: '暂停音乐', + volume: '音量', + close: '关闭', + promptTitle: '为这个世界添一点音乐?', + promptBody: '让森林的呼吸轻轻陪伴你的阅读。', + withMusic: '伴随音乐阅读', + withoutMusic: '不播放音乐', + unavailable: '音乐暂时无法播放,请点音乐按钮重试。' + }, + 'zh-hant': { + music: '閱讀音樂', + on: '播放音樂', + off: '暫停音樂', + volume: '音量', + close: '關閉', + promptTitle: '為這個世界添一點音樂?', + promptBody: '讓森林的呼吸輕輕陪伴你的閱讀。', + withMusic: '伴隨音樂閱讀', + withoutMusic: '不播放音樂', + unavailable: '音樂暫時無法播放,請點音樂按鈕重試。' + }, + ja: { + music: '読書の音楽', + on: '音楽を再生', + off: '音楽を一時停止', + volume: '音量', + close: '閉じる', + promptTitle: 'この世界に音楽を添えますか?', + promptBody: '森の息吹を背景に、ゆっくり読書をお楽しみください。', + withMusic: '音楽と読む', + withoutMusic: '音楽なしで読む', + unavailable: '音楽を再生できません。音楽ボタンから再試行してください。' + }, + ko: { + music: '읽기 음악', + on: '음악 재생', + off: '음악 일시 정지', + volume: '음량', + close: '닫기', + promptTitle: '이 세계에 음악을 더할까요?', + promptBody: '숲의 숨결을 배경으로 편안하게 읽어 보세요.', + withMusic: '음악과 함께 읽기', + withoutMusic: '음악 없이 읽기', + unavailable: '음악을 재생할 수 없습니다. 음악 버튼을 눌러 다시 시도하세요.' + }, + ar: { + music: 'موسيقى القراءة', + on: 'تشغيل الموسيقى', + off: 'إيقاف الموسيقى مؤقتًا', + volume: 'مستوى الصوت', + close: 'إغلاق', + promptTitle: 'هل ترغب في موسيقى لهذا العالم؟', + promptBody: 'دع أنفاس الغابة ترافق قراءتك بهدوء.', + withMusic: 'القراءة مع الموسيقى', + withoutMusic: 'القراءة دون موسيقى', + unavailable: 'تعذر تشغيل الموسيقى. حاول مجددًا من زر الموسيقى.' + }, + de: { + music: 'Lesemusik', + on: 'Musik abspielen', + off: 'Musik pausieren', + volume: 'Lautstärke', + close: 'Schließen', + promptTitle: 'Ein wenig Musik für diese Welt?', + promptBody: 'Lass den Atem des Waldes deine Lektüre sanft begleiten.', + withMusic: 'Mit Musik lesen', + withoutMusic: 'Ohne Musik lesen', + unavailable: + 'Die Musik konnte nicht starten. Versuche es über die Musiktaste erneut.' + }, + es: { + music: 'Música para leer', + on: 'Reproducir música', + off: 'Pausar música', + volume: 'Volumen', + close: 'Cerrar', + promptTitle: '¿Un poco de música para este mundo?', + promptBody: 'Deja que el aliento del bosque acompañe tu lectura.', + withMusic: 'Leer con música', + withoutMusic: 'Leer sin música', + unavailable: + 'No se pudo iniciar la música. Vuelve a intentarlo desde el botón.' + }, + vi: { + music: 'Nhạc đọc sách', + on: 'Phát nhạc', + off: 'Tạm dừng nhạc', + volume: 'Âm lượng', + close: 'Đóng', + promptTitle: 'Thêm chút nhạc cho thế giới này nhé?', + promptBody: 'Để hơi thở khu rừng dịu dàng đồng hành cùng bạn đọc.', + withMusic: 'Đọc cùng âm nhạc', + withoutMusic: 'Đọc không nhạc', + unavailable: 'Không thể phát nhạc. Hãy thử lại bằng nút âm nhạc.' + }, + ru: { + music: 'Музыка для чтения', + on: 'Включить музыку', + off: 'Приостановить музыку', + volume: 'Громкость', + close: 'Закрыть', + promptTitle: 'Добавить немного музыки в этот мир?', + promptBody: 'Пусть дыхание леса мягко сопровождает чтение.', + withMusic: 'Читать с музыкой', + withoutMusic: 'Читать без музыки', + unavailable: 'Не удалось запустить музыку. Попробуйте снова кнопкой музыки.' + }, + uk: { + music: 'Музика для читання', + on: 'Увімкнути музику', + off: 'Призупинити музику', + volume: 'Гучність', + close: 'Закрити', + promptTitle: 'Додати трохи музики до цього світу?', + promptBody: 'Нехай подих лісу тихо супроводжує читання.', + withMusic: 'Читати з музикою', + withoutMusic: 'Читати без музики', + unavailable: 'Не вдалося запустити музику. Спробуйте ще раз кнопкою музики.' + } +}; + +export const musicHints: Record = { + en: [ + 'Music is on. Click the note to pause.', + 'Music is off. Click the note to play.' + ], + zh: ['音乐已开启,点击音符即可关闭。', '音乐已关闭,点击音符即可开启。'], + 'zh-hant': [ + '音樂已開啟,點擊音符即可關閉。', + '音樂已關閉,點擊音符即可開啟。' + ], + ja: [ + '音楽を再生中。音符を押すと停止します。', + '音楽は停止中。音符を押すと再生します。' + ], + ko: [ + '음악이 켜져 있습니다. 음표를 누르면 꺼집니다.', + '음악이 꺼져 있습니다. 음표를 누르면 켜집니다.' + ], + vi: [ + 'Nhạc đang bật. Nhấn nốt nhạc để tắt.', + 'Nhạc đang tắt. Nhấn nốt nhạc để bật.' + ], + de: [ + 'Musik läuft. Zum Pausieren auf die Note klicken.', + 'Musik ist aus. Zum Abspielen auf die Note klicken.' + ], + es: [ + 'Música activada. Pulsa la nota para pausarla.', + 'Música desactivada. Pulsa la nota para reproducirla.' + ], + ru: [ + 'Музыка включена. Нажмите на ноту, чтобы выключить.', + 'Музыка выключена. Нажмите на ноту, чтобы включить.' + ], + uk: [ + 'Музику ввімкнено. Натисніть ноту, щоб вимкнути.', + 'Музику вимкнено. Натисніть ноту, щоб увімкнути.' + ], + ar: [ + 'الموسيقى تعمل. اضغط النوتة لإيقافها.', + 'الموسيقى متوقفة. اضغط النوتة لتشغيلها.' + ] +}; diff --git a/web/src/navigation-views.tsx b/web/src/navigation-views.tsx new file mode 100644 index 0000000..b190224 --- /dev/null +++ b/web/src/navigation-views.tsx @@ -0,0 +1,393 @@ +import { For, Show, createEffect, createSignal, onMount } from 'solid-js'; +import { Brand, Icon, LanguagePicker } from './reader-ui.tsx'; +import { ui, fmt, languageURL } from './i18n.ts'; +import { partRoutes } from './contents.ts'; +import type { ReaderBook } from './book.ts'; +import type { LanguageCode } from './locale-routing.ts'; +const roman = ['I', 'II', 'III', 'IV', 'V']; +interface NavigationProps { + locale: LanguageCode; + onLanguage(locale: LanguageCode): void; + onSearch(): void; +} +export function SiteHeader(props: NavigationProps) { + return ( + + ); +} +export function SiteFooter() { + return ( + + ); +} +export function ContentsView(props: { + book: ReaderBook; + real: boolean; + dark: boolean; + locale: LanguageCode; + onLanguage(locale: LanguageCode): void; + onSearch(): void; +}) { + const prefix = () => (props.real ? '/real/' : '/'); + createEffect(() => { + document.body.className = + 'contents-view' + + (props.dark ? ' contents-night' : '') + + (props.real ? ' contents-real' : ''); + }); + return ( + <> +
+ +
+ + +
+
+
+
+

{ui('Table of contents')}

+ + {ui('Read the introduction')} + +
+
+ + {(group, index) => ( +
+
+ {roman[index()]} +

{group.title}

+
+
    + + {(slug, number) => ( +
  1. + + {String(number() + 1).padStart(2, '0')} + + { + props.book.pages.find( + (page) => page.slug === slug + )?.title + } + + + +
  2. + )} +
    +
+
+ )} +
+
+
+ + ); +} +const atlasDescriptions = [ + 'Start with what a program means. Explore denotations, compositionality, laws, and the relationship between meaning and representation.', + 'Give meaning a concrete vocabulary. Explore capability traits, derived operations, interpreters, evidence, and compiler pipelines in Rust.', + 'Look beneath the surface of a program. Explore the structures and transformations that connect ideas to execution.', + 'Return to familiar ideas with a new perspective. Follow the connections between the semantic view and real programming machinery.' +] as const; +export function AtlasView(props: { book: ReaderBook }) { + const groups = () => props.book.groups.slice(0, 4), + [selected, setSelected] = createSignal(0); + let detail!: HTMLElement; + const select = (index: number) => + setSelected((index + groups().length) % groups().length); + onMount(() => { + document.body.className = 'atlas-view'; + }); + createEffect(() => { + selected(); + if (detail && !matchMedia('(prefers-reduced-motion:reduce)').matches) + detail.animate( + [ + { opacity: 0, transform: 'translateY(8px)' }, + { opacity: 1, transform: 'translateY(0)' } + ], + { duration: 320, easing: 'ease-out' } + ); + }); + return ( +
+
+
+ +

{ui('A world of ideas.')}

+
+

+ {ui('Choose a world.')} +
+ {ui('Follow an idea as far as it takes you.')} +

+ + {ui('Browse as a list')} + +
+
+
{ + if (event.key === 'ArrowRight' || event.key === 'ArrowLeft') { + event.preventDefault(); + select(selected() + (event.key === 'ArrowRight' ? 1 : -1)); + event.currentTarget + .querySelector( + '[data-world="' + selected() + '"]' + ) + ?.focus(); + } + }} + > + + + + + {ui('⟦ parts ⟧ → whole')} + + {(group, index) => ( + + )} + +
+ + 0{selected() + 1} / 04 + +
+
+
+ + {fmt({ key: 'part', value: roman[selected()]! })} + +

{groups()[selected()]?.title}

+

{ui(atlasDescriptions[selected()]!)}

+ + + {ui('Enter this world')} + +
+
+
+ ); +} +const partDescriptions = [ + 'Begin with the meaning of a program. Explore denotations, compositionality, laws, interpretations, and the role of dependent types.', + 'Carry meaning-first design into Rust: capability algebras, semantic types, derived operations, interpreters, evidence, and language pipelines.', + 'Explore execution models and useful machinery: operational semantics, the expression problem, free monads, continuations, and branching.', + 'Connect the machinery back to meaning. Revisit semantics, the expression problem, referential transparency, and the EVM.' +] as const; +export function PartView(props: { book: ReaderBook; index: number }) { + const group = () => props.book.groups[props.index]!; + onMount(() => { + document.body.className = 'part-view'; + }); + return ( +
+
+ {ui('Table of contents')} + + {fmt({ key: 'part', value: roman[props.index]! })} +
+
+
+ {roman[props.index]} + +

{group().title}

+

{ui(partDescriptions[props.index]!)}

+ + + {fmt({ key: 'part', value: roman[props.index]!, begin: true })}{' '} + + +
+
+ + + {(slug, index) => { + const page = props.book.pages.find((page) => page.slug === slug)!; + return ( + + {String(index() + 1).padStart(2, '0')} +
+

{page.title}

+

{fmt({ key: 'minutes', value: page.minutes })}

+
+ +
+ ); + }} +
+ +
+
+
+ ); +} diff --git a/web/src/page-flip.d.ts b/web/src/page-flip.d.ts new file mode 100644 index 0000000..562c564 --- /dev/null +++ b/web/src/page-flip.d.ts @@ -0,0 +1,47 @@ +declare module 'page-flip' { + export interface PageFlipSettings { + width: number; + height: number; + size?: 'fixed' | 'stretch'; + minWidth?: number; + maxWidth?: number; + minHeight?: number; + maxHeight?: number; + autoSize?: boolean; + drawShadow?: boolean; + flippingTime?: number; + maxShadowOpacity?: number; + usePortrait?: boolean; + showCover?: boolean; + startPage?: number; + clickEventForward?: boolean; + useMouseEvents?: boolean; + disableFlipByClick?: boolean; + mobileScrollSupport?: boolean; + showPageCorners?: boolean; + } + + export interface PageFlipEvent { + data: string | number; + } + + export interface PageFlipPage { + setDensity(density: 'soft' | 'hard'): void; + setDrawingDensity(density: 'soft' | 'hard'): void; + } + + export class PageFlip { + constructor(element: HTMLElement, settings: PageFlipSettings); + destroy(): void; + getCurrentPageIndex(): number; + turnToPage(page: number): void; + turnToNextPage(): void; + turnToPrevPage(): void; + flipNext(corner?: 'top' | 'bottom'): void; + flipPrev(corner?: 'top' | 'bottom'): void; + flip(page: number, corner?: 'top' | 'bottom'): void; + on(event: 'flip' | 'changeState', listener: (event: PageFlipEvent) => void): void; + loadFromHTML(elements: HTMLElement[]): void; + getPage(index: number): PageFlipPage; + } +} diff --git a/web/src/page-turn.ts b/web/src/page-turn.ts new file mode 100644 index 0000000..6a86579 --- /dev/null +++ b/web/src/page-turn.ts @@ -0,0 +1,102 @@ +import {PageFlip} from 'page-flip'; +import {copyBookSurface} from './reader-surface.ts'; + +function visibleSheets(book: HTMLElement): HTMLElement[] { + return [...book.querySelectorAll('.folio-page')] + .filter(element => getComputedStyle(element).display !== 'none' && element.getBoundingClientRect().width > 0) + .sort((a, b) => a.getBoundingClientRect().left - b.getBoundingClientRect().left) + .map(element => { + const copy = copyBookSurface(element); + copy.className = 'folio-page'; + copy.removeAttribute('style'); + return copy; + }); +} + +// Only paper turns. The cover and bookmark remain owned by the new reader. +export async function turnRoute(app: HTMLElement, update: () => Promise | unknown, direction = 1, signal?:AbortSignal): Promise { + if(signal?.aborted)return; + const old = app.querySelector('.page-book'); + if (!old || document.body.classList.contains('continuous-reading')) { + await update(); + return; + } + const before = visibleSheets(old); + const rect = old.getBoundingClientRect(); + if (!before.length) { + await update(); + return; + } + const veil = document.createElement('div'); + veil.inert = true; + veil.setAttribute('aria-hidden', 'true'); + Object.assign(veil.style, {position:'fixed',left:`${rect.left}px`,top:`${rect.top}px`,width:`${rect.width}px`,height:`${rect.height}px`,overflow:'hidden',pointerEvents:'none',zIndex:9}); + const snapshot = copyBookSurface(old); + veil.append(snapshot); + document.body.append(veil); + let flip: PageFlip | null = null; + let host: HTMLDivElement | null = null; + const frames=new Set(); + let timer:ReturnType|undefined; + let finish:()=>void=()=>{}; + const abort=()=>finish(); + signal?.addEventListener('abort',abort,{once:true}); + const frame=(callback:()=>void)=>{const id=requestAnimationFrame(()=>{frames.delete(id);if(!signal?.aborted)callback();});frames.add(id);}; + const paint=()=>new Promise(resolve=>{finish=resolve;if(signal?.aborted)resolve();else frame(()=>frame(resolve));}); + try { + await update(); + // PageFlip paints its initial spread on the next animation frame. + await paint(); + if(signal?.aborted)return; + const book = app.querySelector('.page-book'); + const volume = app.querySelector('.bound-volume'); + if (!book || !volume) return; + const after = visibleSheets(book); + const r = book.getBoundingClientRect(); + const v = volume.getBoundingClientRect(); + if (!after.length) return; + const portrait = after.length === 1; + const w = r.width / (portrait ? 1 : 2); + const h = r.height; + host = document.createElement('div'); + host.className = 'chapter-flip-host paper-turning'; + host.inert = true; + host.setAttribute('aria-hidden', 'true'); + Object.assign(host.style, {position:'absolute',left:`${r.left-v.left-volume.clientLeft}px`,top:`${r.top-v.top-volume.clientTop}px`,width:`${r.width}px`,height:`${h}px`,zIndex:9,pointerEvents:'none',overflow:'hidden'}); + const backward = (direction < 0) !== (document.dir === 'rtl'); + const sheets = backward ? [...after, ...before] : [...before, ...after]; + for (const sheet of sheets) { + sheet.style.width = `${w}px`; + sheet.style.height = `${h}px`; + host.append(sheet); + } + volume.append(host); + veil.remove(); + flip = new PageFlip(host, {width:w,height:h,size:'fixed',autoSize:false,usePortrait:portrait,showCover:false,startPage:backward?after.length:0,flippingTime:560,drawShadow:true,maxShadowOpacity:document.body.classList.contains('night')?.55:.2,useMouseEvents:false,disableFlipByClick:false,mobileScrollSupport:false,showPageCorners:false}); + flip.loadFromHTML(sheets); + await new Promise(resolve => { + finish=resolve; + if(signal?.aborted){resolve();return;} + let started = false; + timer = setTimeout(resolve, 1000); + flip?.on('changeState', event => { + if (event.data === 'flipping') started = true; + if (started && event.data === 'read') { + clearTimeout(timer); + resolve(); + } + }); + frame(() => frame(() => { + if (backward) flip?.flipPrev('bottom'); + else flip?.flipNext('bottom'); + })); + }); + } finally { + signal?.removeEventListener('abort',abort); + clearTimeout(timer); + for(const id of frames)cancelAnimationFrame(id); + veil.remove(); + flip?.destroy(); + host?.remove(); + } +} diff --git a/web/src/pagination.ts b/web/src/pagination.ts new file mode 100644 index 0000000..3676028 --- /dev/null +++ b/web/src/pagination.ts @@ -0,0 +1,269 @@ +import type { Icon, ReaderPage } from './book.ts'; +import { englishMessages } from './ui-messages.ts'; +import type { MessageKey } from './ui-messages.ts'; +import { languagePath } from './locale-routing.ts'; +import type { LanguageCode } from './locale-routing.ts'; + +interface PaginationOptions { + page: ReaderPage; + pages: ReaderPage[]; + icon: Icon; + host: HTMLElement; + w: number; + h: number; + portrait: boolean; + label?: (key: MessageKey) => string; + locale?: LanguageCode; +} + +// One layout algorithm measures the viewed chapter; other chapters are never measured for totals. +const escape = (value: string): string => + value.replace( + /[&<>"']/g, + (character) => + ({ + '&': '&', + '<': '<', + '>': '>', + '"': '"', + "'": ''' + })[character] ?? character + ); + +function content(sheet: HTMLElement): HTMLElement { + const element = sheet.querySelector('.folio-content'); + if (!element) throw new Error('Missing folio content element'); + return element; +} + +export function prepareChapterSource( + page: ReaderPage, + label: (key: MessageKey) => string = (key) => englishMessages[key], + locale: LanguageCode = 'en' +): HTMLDivElement { + const source = document.createElement('div'); + source.innerHTML = page.html; + if (page.slug === 'introduction.html') + source.querySelector('.admonition.warning')?.remove(); + source.querySelectorAll('table').forEach((table) => { + const wrap = document.createElement('div'); + wrap.className = 'table-scroll'; + wrap.tabIndex = 0; + wrap.setAttribute('role', 'region'); + wrap.setAttribute('aria-label', label('Scrollable table')); + table.before(wrap); + wrap.append(table); + }); + source.querySelectorAll('h1 img').forEach((image) => image.remove()); + for (const anchor of source.querySelectorAll( + 'a[href^="/"]' + )) { + const href = anchor.getAttribute('href') || ''; + if (href.startsWith('//')) continue; + const url = new URL(href, 'https://book.invalid'); + anchor.setAttribute( + 'href', + languagePath(url.pathname, locale) + url.search + url.hash + ); + } + // Measuring a clip must not start another embedded player. + source.querySelectorAll('iframe[src]').forEach((frame) => { + frame.dataset.embedSrc = frame.getAttribute('src') ?? ''; + frame.removeAttribute('src'); + }); + return source; +} + +export function paginateChapter({ + page, + pages, + icon, + host, + w, + h, + portrait, + label = (key) => englishMessages[key], + locale = 'en' +}: PaginationOptions): HTMLElement[] { + // A bounded User Timing entry makes eager measurement observable without retaining chapter DOM. + performance.clearMarks('alux:pagination'); + performance.mark('alux:pagination',{detail:{chapter:page.id}}); + const idx = pages.indexOf(page); + function pageElement(number: number): HTMLElement { + const sheet = document.createElement('section'); + sheet.className = 'folio-page'; + sheet.dataset.density = 'soft'; + sheet.dataset.folio = String(number); + sheet.innerHTML = `
${escape(page.group)}${escape(label('ALUX PROGRAMMING'))}
✦${String(number + 1).padStart(2, '0')}
`; + return sheet; + } + + const measure = document.createElement('div'); + measure.className = 'folio-measure'; + measure.style.width = `${w}px`; + measure.style.height = `${h}px`; + host.append(measure); + let sheet = pageElement(0); + measure.append(sheet); + let body = content(sheet); + const sheets: HTMLElement[] = [sheet]; + function next(): void { + sheet = pageElement(sheets.length); + sheets.push(sheet); + measure.replaceChildren(sheet); + body = content(sheet); + } + function fits(): boolean { + return body.scrollHeight <= body.clientHeight + 1; + } + + const parsed = document.createElement('div'); + parsed.innerHTML = prepareChapterSource(page, label, locale).innerHTML; + const blocks = Array.from(parsed.children) as HTMLElement[]; + const units: HTMLElement[] = []; + for (let n = 0; n < blocks.length; n++) { + const node = blocks[n]; + const nextNode = blocks[n + 1]; + if (!node) continue; + const keepWithNext = Boolean( + nextNode && + ((/^H[1-4]$/.test(node.tagName) && + !nextNode.matches('.admonition,.table-scroll')) || + (node.tagName === 'P' && + /:\s*$/.test(node.textContent ?? '') && + /^(UL|OL|DIV)$/.test(nextNode.tagName))) + ); + if (keepWithNext && nextNode) { + const group = document.createElement('div'); + group.className = /^H[1-4]$/.test(node.tagName) + ? 'folio-group folio-heading-group' + : 'folio-group'; + group.append(node, nextNode); + n++; + const following = blocks[n + 1]; + if ( + nextNode.tagName === 'P' && + /:\s*$/.test(nextNode.textContent ?? '') && + following && + /^(UL|OL)$/.test(following.tagName) + ) { + group.append(following); + n++; + } + units.push(group); + } else { + units.push(node); + } + } + + for (const node of units) { + // Prose notes may continue on a new sheet at paragraph boundaries. + if (node.matches('.admonition') && node.children.length > 2) { + const children = Array.from(node.children); + let fragment = node.cloneNode(false) as HTMLElement; + body.append(fragment); + for (const child of children) { + fragment.append(child); + if (!fits()) { + child.remove(); + if (!fragment.childElementCount) fragment.remove(); + next(); + fragment = node.cloneNode(false) as HTMLElement; + fragment.classList.add('admonition-continuation'); + body.append(fragment); + fragment.append(child); + if (!fits()) { + const region = document.createElement('div'); + region.className = 'folio-overflow'; + region.tabIndex = 0; + region.setAttribute('role', 'region'); + region.setAttribute('aria-label', 'Scrollable technical content'); + region.style.maxHeight = `${body.clientHeight}px`; + fragment.before(region); + region.append(fragment); + } + } + } + continue; + } + + // Tables continue between complete rows instead of leaving half a spread + // empty or making the reader scroll an entire table inside one page. + const table = node.matches('.table-scroll') + ? node.querySelector('table') + : null; + const firstBody = table?.tBodies[0]; + if (table && firstBody && firstBody.rows.length > 1) { + const rows = Array.from(firstBody.rows); + let fragment = node.cloneNode(false) as HTMLElement; + let tbody = document.createElement('tbody'); + let continuation = false; + const fragmentTable = (): void => { + fragment = node.cloneNode(false) as HTMLElement; + const clonedTable = table.cloneNode(false) as HTMLTableElement; + for (const child of Array.from(table.children)) { + if (child.tagName !== 'TBODY') { + const copy = child.cloneNode(true) as HTMLElement; + if (continuation) copy.dataset.repeatedTableHeader = 'true'; + clonedTable.append(copy); + } + } + tbody = document.createElement('tbody'); + clonedTable.append(tbody); + fragment.append(clonedTable); + body.append(fragment); + }; + fragmentTable(); + for (const row of rows) { + tbody.append(row); + if (!fits()) { + row.remove(); + if (!tbody.rows.length) fragment.remove(); + else continuation = true; + next(); + fragmentTable(); + tbody.append(row); + if (!fits()) { + fragment.classList.add('folio-overflow'); + fragment.style.maxHeight = `${body.clientHeight}px`; + } + } + } + continue; + } + + body.append(node); + if (!fits()) { + node.remove(); + if (body.childElementCount) next(); + body.append(node); + if (!fits()) { + // A long code example, table or note remains intact and fully reachable in its own scroll region. + const region = document.createElement('div'); + region.className = 'folio-overflow'; + region.tabIndex = 0; + region.setAttribute('role', 'region'); + region.setAttribute('aria-label', 'Scrollable technical content'); + region.style.maxHeight = `${body.clientHeight}px`; + node.before(region); + region.append(node); + } + } + } + + const end = document.createElement('nav'); + end.className = 'folio-chapter-end'; + end.innerHTML = `✦

${escape(label('Continue the journey'))}

${idx + 1 < pages.length ? `${escape(pages[idx + 1]?.title ?? '')} ${icon('arrow-right')}` : `${escape(label('Return to the table of contents'))}`}`; + body.append(end); + if (!fits()) { + end.remove(); + next(); + body.append(end); + } + if (!portrait && sheets.length % 2) { + next(); + body.innerHTML = `
✦

${escape(label('First the meaning.'))}
${escape(label('Then the machinery.'))}

${escape(label('Explore another chapter'))} ${icon('arrow-right')}
`; + } + measure.remove(); + return sheets; +} diff --git a/web/src/reader-app.tsx b/web/src/reader-app.tsx new file mode 100644 index 0000000..a56cd85 --- /dev/null +++ b/web/src/reader-app.tsx @@ -0,0 +1,864 @@ +import { + For, + Show, + createEffect, + createMemo, + createSignal, + onCleanup, + onMount +} from 'solid-js'; +import { BookView } from './book-view.tsx'; +import { RealView } from './real-view.tsx'; +import { Icon, LanguagePicker } from './reader-ui.tsx'; +import { + edition, + language, + languageURL, + resolveLanguage, + setLanguage, + stripLanguage, + ui, + fmt +} from './i18n.ts'; +import type { LanguageCode } from './locale-routing.ts'; +import { pathLanguage } from './locale-routing.ts'; +import { bookmarks, removeBookmark } from './bookmarks.ts'; +import { readingScale, readingSize } from './reading-preferences.ts'; +import { searchBook } from './search.ts'; +import { turnRoute } from './page-turn.ts'; +import { mountGatewayWelcome } from './gateway-welcome.ts'; +import { updateSiteMeta } from './site-meta.ts'; +import { startReaderAudio, setReaderRealm } from './reader-audio.ts'; +import { MusicControls } from './music-controls.tsx'; +import { + ContentsView, + AtlasView, + PartView, + SiteHeader, + SiteFooter +} from './navigation-views.tsx'; +import { partRoutes } from './contents.ts'; +import type { + ReaderBook, + ReaderController, + ReaderStorage, + Announce, + Navigate +} from './book.ts'; + +export const storage: ReaderStorage = { + get(key) { + try { + return localStorage.getItem(key); + } catch { + return null; + } + }, + set(key, value) { + try { + localStorage.setItem(key, String(value)); + } catch {} + } +}; +const reduced = () => matchMedia('(prefers-reduced-motion:reduce)').matches; +const nextFrame = () => + new Promise((resolve) => requestAnimationFrame(() => resolve())); +const decode = (value: string) => { + try { + return decodeURIComponent(value); + } catch { + return value; + } +}; + +export function ReaderApp() { + let host!: HTMLDivElement, + controller: ReaderController | null = null; + const [path, setPath] = createSignal(location.pathname), + [busy, setBusy] = createSignal(false), + [failure, setFailure] = createSignal(false); + const [musicHost, setMusicHost] = createSignal(null); + const [notice, setNotice] = createSignal(''); + let noticeTimer: ReturnType | undefined; + let navigation: AbortController|undefined; + const announce: Announce = (text, anchor) => { + setNotice(text); + clearTimeout(noticeTimer); + const box = document.getElementById('announcement'); + if (box) { + box.classList.toggle('anchored', !!anchor); + if (anchor) { + const rect = anchor.getBoundingClientRect(); + box.style.left = + Math.max( + 12, + Math.min( + innerWidth - box.offsetWidth - 12, + rect.right - box.offsetWidth + ) + ) + 'px'; + box.style.top = + Math.min(innerHeight - box.offsetHeight - 12, rect.bottom + 10) + + 'px'; + } else { + box.style.left = ''; + box.style.top = ''; + } + } + noticeTimer = setTimeout(() => setNotice(''), 2600); + }; + async function chooseLanguage(locale: LanguageCode, manual = true) { + if (busy()) return; + setBusy(true); + const task=navigation=new AbortController(); + setFailure(false); + const anchor = manual ? controller?.getCurrentAnchor() : undefined; + try { + await setLanguage(locale, manual,task.signal); + const href = + stripLanguage(location.pathname) === '/magic.html' + ? '/introduction.html' + location.search + location.hash + : location.href; + const target = new URL(languageURL(href), location.origin); + if (anchor) target.hash = anchor; + history.replaceState( + {}, + '', + target.pathname + target.search + target.hash + ); + setPath(location.pathname); + await nextFrame(); + if(task.signal.aborted)return; + restore(); + } catch { + if(task.signal.aborted)return; + if (edition()) + announce(ui('This language is unavailable. Please try again.')); + else setFailure(true); + } finally { + if(navigation===task)setBusy(false); + } + } + function restore(focus = false) { + if (location.hash) { + const id = decode(location.hash.slice(1)); + if (controller && id !== 'main') controller.goToAnchor(id, false); + else document.getElementById(id)?.scrollIntoView({ behavior: 'instant' }); + } else if (stripLanguage(location.pathname).startsWith('/real/')) + controller?.restorePosition?.(); + else scrollTo({ top: 0, behavior: 'instant' }); + if (focus) { + const main = document.getElementById('main'); + main?.setAttribute('tabindex', '-1'); + main?.focus({ preventScroll: true }); + } + } + const navigate: Navigate = async (href) => { + if (busy()) return; + setBusy(true); + const task=navigation=new AbortController(); + const target = new URL(languageURL(href), location.origin), + oldPath = stripLanguage(location.pathname), + newPath = stripLanguage(target.pathname); + const before = + edition()?.book.pages.findIndex( + (page) => '/' + page.slug === oldPath + ) ?? -1, + after = + edition()?.book.pages.findIndex( + (page) => '/' + page.slug === newPath + ) ?? -1; + const commit = () => { + history.pushState({}, '', target.pathname + target.search + target.hash); + setPath(target.pathname); + }; + const update = async () => { + commit(); + await nextFrame(); + if(task.signal.aborted)return; + restore(true); + }; + try { + if (!reduced() && before >= 0 && after >= 0) + await turnRoute(host, update, after < before ? -1 : 1,task.signal); + else if (!reduced() && document.startViewTransition) { + document.documentElement.dataset.transition = 'world'; + // Rendering is suppressed during the update callback. Waiting for rAF + // inside it deadlocks mobile Chromium until the transition times out. + const transition=document.startViewTransition(commit); + const cancel=()=>transition.skipTransition(); + task.signal.addEventListener('abort',cancel,{once:true}); + try{await transition.finished.catch(error=>{if(!task.signal.aborted&&!(error instanceof DOMException&&error.name==='AbortError'))throw error;});}finally{task.signal.removeEventListener('abort',cancel);} + if(!task.signal.aborted){await nextFrame();restore(true);} + } else await update(); + } finally { + delete document.documentElement.dataset.transition; + if(navigation===task)setBusy(false); + } + }; + onMount(() => { + const disposeAudio = startReaderAudio(); + void resolveLanguage().then((locale) => chooseLanguage(locale, false)); + const pop = () => { + navigation?.abort(); + navigation=undefined; + setBusy(false); + const code = pathLanguage(location.pathname)||'en'; + if ( + edition() && + code !== edition()?.locale + ) + void chooseLanguage(code as LanguageCode, false); + else { + setPath(location.pathname); + void nextFrame().then(() => restore()); + } + }; + const click = (event: MouseEvent) => { + if ( + event.defaultPrevented || + event.button !== 0 || + event.ctrlKey || + event.metaKey || + event.shiftKey || + event.altKey + ) + return; + const anchor = + event.target instanceof Element + ? event.target.closest('a[href]') + : null; + if ( + !anchor || + anchor.target === '_blank' || + anchor.hasAttribute('download') + ) + return; + const url = new URL(anchor.href, location.href); + if (url.origin !== location.origin) return; + event.preventDefault(); + if (anchor.hasAttribute('data-realm-switch')) + url.hash = controller?.getCurrentAnchor() || location.hash; + if (url.pathname === location.pathname && url.hash) { + history.pushState({}, '', url.pathname + url.search + url.hash); + const id = decode(url.hash.slice(1)); + if (controller && id !== 'main') controller.goToAnchor(id); + else { + const target = document.getElementById(id); + target?.setAttribute('tabindex', '-1'); + target?.focus(); + target?.scrollIntoView(); + } + return; + } + void navigate(url.pathname + url.search + url.hash); + }; + const neutralMediaMenu = (event: PointerEvent) => { + if ( + event.button !== 2 || + !(event.target instanceof Element) || + !event.target.closest('img,video,canvas,.chapter-art') + ) + return; + const shield = document.createElement('div'); + Object.assign(shield.style, { + position: 'fixed', + left: event.clientX - 5 + 'px', + top: event.clientY - 5 + 'px', + width: '12px', + height: '12px', + zIndex: '99999' + }); + document.body.append(shield); + setTimeout(() => shield.remove(), 1000); + }; + addEventListener('popstate', pop); + document.addEventListener('click', click); + document.addEventListener('pointerdown', neutralMediaMenu, true); + onCleanup(() => { + navigation?.abort(); + clearTimeout(noticeTimer); + removeEventListener('popstate', pop); + document.removeEventListener('click', click); + document.removeEventListener('pointerdown', neutralMediaMenu, true); + disposeAudio(); + }); + }); + return ( +
+ +

{ui('The book could not load.')}

+

{ui('Please refresh the page to try again.')}

+ + + } + > + + {ui('Preparing the pages…')} + + } + > + {}} /> + +
+ } + > + {(selected) => ( + void chooseLanguage(locale)} + onNavigate={navigate} + announce={announce} + onController={(value) => (controller = value)} + onMusicHost={(host) => setMusicHost(host)} + /> + )} + + +
+ {notice()} +
+
+ ); +} + +interface EditionProps { + book: ReaderBook; + locale: LanguageCode; + path: string; + busy: boolean; + onLanguage(locale: LanguageCode): void; + onNavigate: Navigate; + announce: Announce; + onController(controller: ReaderController | null): void; + onMusicHost(host: HTMLElement | null): void; +} +function Edition(props: EditionProps) { + const route = createMemo(() => { + let pathname = decode(stripLanguage(props.path)).replace(/^\//, ''); + if (pathname === 'magic.html') pathname = 'introduction.html'; + const real = pathname.startsWith('real/'), + slug = real ? pathname.slice(5) || 'introduction.html' : pathname; + return { + pathname, + real, + page: props.book.pages.find( + (page) => + page.slug === + (real && slug === 'index.html' ? 'introduction.html' : slug) + ), + gateway: !pathname || pathname === 'index.html' + }; + }); + const [saved, setSaved] = createSignal(bookmarks()), + [dark, setDark] = createSignal( + storage.get('alux-reading-theme') === 'dark' || + (!storage.get('alux-reading-theme') && + storage.get('alux-night') === 'true') + ), + [scale, setScale] = createSignal(readingScale(storage)); + const [searchOpen, setSearchOpen] = createSignal(false), + [bookmarksOpen, setBookmarksOpen] = createSignal(false), + [query, setQuery] = createSignal(''); + let searchDialog!: HTMLDialogElement, + savedDialog!: HTMLDialogElement, + input!: HTMLInputElement, + searchOrigin: HTMLElement | null = null, + savedOrigin: HTMLElement | null = null; + const openSearch = () => { + if (route().gateway) return; + searchOrigin = document.activeElement as HTMLElement; + setQuery(''); + setSearchOpen(true); + }; + const openBookmarks = () => { + savedOrigin = document.activeElement as HTMLElement; + setBookmarksOpen(true); + }; + const closeSearch = () => { + setSearchOpen(false); + searchOrigin?.focus(); + }; + const closeBookmarks = () => { + setBookmarksOpen(false); + savedOrigin?.focus(); + }; + createEffect(() => { + if (searchOpen()) { + if (!searchDialog.open) searchDialog.showModal(); + input.focus(); + } else searchDialog?.close(); + }); + createEffect(() => { + if (bookmarksOpen()) { + if (!savedDialog.open) savedDialog.showModal(); + savedDialog + .querySelector('[data-close-bookmarks]') + ?.focus(); + } else savedDialog?.close(); + }); + createEffect(() => { + const value = route(); + document.title = value.gateway + ? ui('Choose your world') + : value.page + ? value.page.slug === 'introduction.html' + ? ui('Introduction') + : value.page.title + : value.pathname.endsWith('contents.html') + ? ui('Table of contents') + : value.pathname === 'atlas.html' + ? ui('The chapter atlas') + : partRoutes.includes(value.pathname) + ? props.book.groups[partRoutes.indexOf(value.pathname)]!.title + : ui('This page is uncharted.'); + updateSiteMeta(props.locale); + setReaderRealm(value.gateway ? 'gateway' : value.real ? 'real' : 'magic'); + }); + const changeTheme = () => { + const value = !dark(); + setDark(value); + storage.set('alux-reading-theme', value ? 'dark' : 'light'); + storage.set('alux-night', value); + storage.set('alux-real-theme', value ? 'coal' : 'light'); + }; + const changeScale = (delta: number) => { + const value = Math.max(-4, Math.min(4, scale() + delta)); + setScale(value); + storage.set('alux-reading-scale', value); + props.announce(fmt({ key: 'readingSize', value: readingSize(value) })); + }; + const results = createMemo(() => + query().trim() + ? searchBook(props.book.pages, query().toLowerCase().trim()) + : [] + ); + const validSaved = () => + saved().filter((item) => + props.book.pages.some((page) => page.slug === item.slug) + ); + onMount(() => { + const changed = () => setSaved(bookmarks()); + const keyboard = (event: KeyboardEvent) => { + if (event.key === 'Escape' && searchOpen()) { + event.preventDefault(); + closeSearch(); + return; + } + if ((event.metaKey || event.ctrlKey) && event.key.toLowerCase() === 'k') { + event.preventDefault(); + openSearch(); + } + if ( + searchOpen() && + (event.key === 'ArrowDown' || event.key === 'ArrowUp') + ) { + const links = [ + ...searchDialog.querySelectorAll('.search-result') + ]; + if (!links.length) return; + event.preventDefault(); + const index = links.indexOf(document.activeElement as HTMLElement); + links[ + (index + (event.key === 'ArrowDown' ? 1 : -1) + links.length) % + links.length + ]?.focus(); + } + }; + addEventListener('alux-bookmarks-changed', changed); + document.addEventListener('keydown', keyboard); + onCleanup(() => { + removeEventListener('alux-bookmarks-changed', changed); + document.removeEventListener('keydown', keyboard); + searchDialog.close(); + savedDialog.close(); + }); + }); + function OtherRoute() { + createEffect(() => { + if ( + !route().gateway && + !route().pathname.endsWith('contents.html') && + route().pathname !== 'atlas.html' && + !partRoutes.includes(route().pathname) + ) + document.body.className = 'home-view'; + }); + return ( + + + + 404 +

{ui('This page is uncharted.')}

+

{ui('Find your way back to the book.')}

+ + {ui('Choose a world')} + + + } + > + +
+ } + > + +
+ + + } + > + + + } + > + + + ); + } + return ( + <> + + }> + {(page) => ( + + } + > + + + )} + + { + event.preventDefault(); + closeSearch(); + }} + onClick={(event) => { + if (event.target === event.currentTarget) closeSearch(); + }} + > +
+ + setQuery(event.currentTarget.value)} + placeholder={ui('Search ideas, code, chapters…')} + aria-label={ui('Search ideas, code, chapters')} + /> + +
+
+ {ui('A keyword opens a new page.')}

+ } + > +
+ {fmt({ key: 'results', value: results().length })} +
+ +

{ui('No pages found.')}

+

+ {ui( + 'Try a concept such as “capability”, “Rust” or “meaning”.' + )} +

+
+ } + > + + {({ p, at }) => ( + + + {p.group} + {p.title} +

+ {(at > 50 ? '…' : '') + + p.text.slice( + Math.max(0, at - 45), + Math.max(0, at - 45) + 150 + ) + + '…'} +

+
+ +
+ )} +
+ + +
+ + + { + event.preventDefault(); + closeBookmarks(); + }} + onClick={(event) => { + if (event.target === event.currentTarget) closeBookmarks(); + }} + > +
+

{ui('My bookmarks')}

+ +
+
+ +

{ui('No bookmarks yet.')}

+

+ {ui( + 'Save a chapter with the bookmark button to continue reading here.' + )} +

+
+ } + > + + {(item) => { + const page = props.book.pages.find( + (page) => page.slug === item.slug + )!; + return ( + + ); + }} + + + +
+ + ); +} + +function Gateway(props: { + locale: LanguageCode; + disabled?: boolean; + onLanguage(locale: LanguageCode): void; +}) { + let main!: HTMLElement; + onMount(() => { + document.body.className = 'gateway-view'; + const dispose = mountGatewayWelcome(main); + onCleanup(dispose); + }); + return ( +
+ +

{ui('Choose your world')}

+ +
+ ); +} diff --git a/web/src/reader-audio.ts b/web/src/reader-audio.ts new file mode 100644 index 0000000..0a956b3 --- /dev/null +++ b/web/src/reader-audio.ts @@ -0,0 +1,230 @@ +type Realm = 'magic' | 'real'; +export interface ReaderAudioState { + realm: Realm | null; + playing: boolean; + volume: number; + failed: boolean; + hintRevision: number; +} +const storage = { + get(key: string) { + try { + return localStorage.getItem(key); + } catch { + return null; + } + }, + set(key: string, value: string) { + try { + localStorage.setItem(key, value); + } catch {} + } +}; +let audio: HTMLAudioElement | null = null, + context: AudioContext | null = null, + gain: GainNode | null = null, + source: MediaElementAudioSourceNode | null = null; +let activeRealm: Realm | null = null, + contextCreatedAt = 0, + contextEverRunning = false, + hintRevision = 0; +const enabled: Record = { magic: true, real: false }, + listeners = new Set<(state: ReaderAudioState) => void>(); +const desired = () => (activeRealm ? enabled[activeRealm] : false); +const volume = () => { + const value = Number(storage.get('alux-reader-music-volume') ?? 1); + return Number.isFinite(value) ? Math.max(0, Math.min(1, value)) : 1; +}; +const playing = () => + Boolean( + audio && + !audio.paused && + !audio.ended && + (!context || context.state === 'running') + ); +export const readerAudioState = (): ReaderAudioState => ({ + realm: activeRealm, + playing: playing(), + volume: volume(), + failed: !!audio?.dataset.failed, + hintRevision +}); +function publish() { + const state = readerAudioState(); + for (const listener of listeners) listener(state); +} +export function subscribeReaderAudio( + listener: (state: ReaderAudioState) => void +): () => void { + listeners.add(listener); + listener(readerAudioState()); + return () => { + listeners.delete(listener); + }; +} +function bindAudio(): void { + const media = document.createElement('audio'); + media.loop = true; + media.preload = 'none'; + media.volume = 1; + media.src = new URL( + (import.meta.env.BASE_URL || '/') + 'audio/forest-breath.mp3', + location.href + ).href; + media.setAttribute('aria-hidden', 'true'); + media.tabIndex = -1; + for (const event of ['playing', 'pause', 'ended']) + media.addEventListener(event, publish); + media.addEventListener('error', () => { + media.dataset.failed = 'true'; + publish(); + }); + audio = media; + document.body.append(media); +} +function getGain(rebuild = false): void { + const media = audio; + if (!media) return; + if (context && context.state !== 'closed' && !rebuild) return; + if (rebuild && context) { + const position = media.currentTime; + try { + source?.disconnect(); + void context.close(); + } catch {} + media.remove(); + bindAudio(); + if (audio) audio.currentTime = position; + context = null; + source = null; + gain = null; + } + const Ctx = + window.AudioContext || + (window as Window & { webkitAudioContext?: typeof AudioContext }) + .webkitAudioContext; + if (!Ctx) return; + try { + const session = ( + navigator as Navigator & { audioSession?: { type: string } } + ).audioSession; + if (session) session.type = 'playback'; + } catch {} + const audioContext = new Ctx(); + context = audioContext; + contextCreatedAt = Date.now(); + contextEverRunning = false; + gain = audioContext.createGain(); + gain.gain.value = volume(); + gain.connect(audioContext.destination); + source = audioContext.createMediaElementSource(audio ?? media); + source.connect(gain); + audioContext.addEventListener('statechange', () => { + if (context?.state === 'running') { + contextEverRunning = true; + if (activeRealm && desired()) audio?.play().then(publish).catch(publish); + } + }); +} +function pause() { + audio?.pause(); + publish(); +} +function play() { + if (!audio || !activeRealm || !desired() || document.hidden) return; + delete audio.dataset.failed; + getGain(); + if (context?.state !== 'running') context?.resume().catch(() => {}); + const media = audio; + media + .play() + .then(() => { + if (!activeRealm || !desired() || document.hidden) media.pause(); + publish(); + }) + .catch(publish); +} +export function setReaderRealm(realm: string | null | undefined) { + const next = realm === 'magic' || realm === 'real' ? realm : null; + if (next === activeRealm) return; + if (next && !audio) bindAudio(); + activeRealm = next; + pause(); + if (next) { + enabled[next] = next === 'magic'; + hintRevision++; + if (desired()) play(); + } + publish(); +} +export function toggleReaderAudio() { + if (!activeRealm) return; + enabled[activeRealm] = !playing(); + if (desired()) play(); + else pause(); + hintRevision++; + publish(); +} +export function setReaderVolume(value: number) { + const clamped = Math.max(0, Math.min(1, value)); + if (!Number.isFinite(clamped)) return; + storage.set('alux-reader-music-volume', String(clamped)); + if (gain && context) + gain.gain.setTargetAtTime(clamped, context.currentTime, 0.025); + publish(); +} +export function startReaderAudio(): () => void { + const gesture = (event: Event) => { + if ( + !activeRealm && + document.body.classList.contains('gateway-view') && + event.target instanceof Element && + event.target.closest('.world-choice') + ) { + if (!audio) bindAudio(); + getGain(); + context?.resume().catch(() => {}); + return; + } + if ( + !activeRealm || + !desired() || + document.hidden || + (event.target instanceof Element && + event.target.closest('[data-reader-music]')) + ) + return; + if ( + context && + context.state !== 'running' && + contextEverRunning && + Date.now() - contextCreatedAt > 1000 + ) + getGain(true); + if (!playing()) play(); + }; + const visibility = () => { + if (document.hidden) pause(); + else if (activeRealm && desired()) play(); + }; + for (const type of ['pointerdown', 'touchend', 'click', 'keydown']) + document.addEventListener(type, gesture, { capture: true, passive: true }); + document.addEventListener('visibilitychange', visibility); + window.addEventListener('pagehide', pause); + return () => { + for (const type of ['pointerdown', 'touchend', 'click', 'keydown']) + document.removeEventListener(type, gesture, true); + document.removeEventListener('visibilitychange', visibility); + window.removeEventListener('pagehide', pause); + activeRealm = null; + pause(); + audio?.remove(); + try { + void context?.close(); + } catch {} + audio = null; + context = null; + gain = null; + source = null; + }; +} diff --git a/web/src/reader-surface.ts b/web/src/reader-surface.ts new file mode 100644 index 0000000..b383e1c --- /dev/null +++ b/web/src/reader-surface.ts @@ -0,0 +1,24 @@ +/** A pending reader must never borrow the next chapter's DOM after navigation. */ +export function ownedBookSurface(volume: HTMLElement): HTMLElement | null { + if (!volume.isConnected) return null; + let book = volume.querySelector('#page-book'); + if (!book) { + book = volume.ownerDocument.createElement('div'); + book.id = 'page-book'; + book.className = 'page-book'; + volume.prepend(book); + } + return book; +} + +/** A short-lived visual copy covers PageFlip's first, still-unpainted frame. */ +export function copyBookSurface(book: HTMLElement): HTMLElement { + const copy = book.cloneNode(true) as HTMLElement; + copy.removeAttribute('id'); + copy.querySelectorAll('[id]').forEach(element => element.removeAttribute('id')); + copy.querySelectorAll('iframe').forEach(frame => { frame.removeAttribute('src'); frame.removeAttribute('srcdoc'); }); + copy.inert = true; + copy.setAttribute('aria-hidden', 'true'); + copy.classList.add('reader-backdrop'); + return copy; +} diff --git a/web/src/reader-ui.tsx b/web/src/reader-ui.tsx new file mode 100644 index 0000000..950187c --- /dev/null +++ b/web/src/reader-ui.tsx @@ -0,0 +1,199 @@ +import { For } from 'solid-js'; +import { + createElement, + Search, + ArrowRight, + ArrowLeft, + Menu, + X, + Moon, + Sun, + BookOpen, + Github, + ArrowUpRight, + Copy, + Check, + Bookmark, + ChevronRight, + Map, + WandSparkles, + SquareCode, + ScrollText +} from 'lucide'; +import { ui, languageURL } from './i18n.ts'; +import { languages } from './locale-routing.ts'; +import type { LanguageCode } from './locale-routing.ts'; +import type { BookGroup, ReaderPage } from './book.ts'; + +const icons = { + Search, + ArrowRight, + ArrowLeft, + Menu, + X, + Moon, + Sun, + BookOpen, + Github, + ArrowUpRight, + Copy, + Check, + Bookmark, + ChevronRight, + Map, + WandSparkles, + SquareCode, + ScrollText +}; +export function icon(name: string): string { + const key = Object.keys(icons).find( + (key) => key.toLowerCase() === name.replaceAll('-', '').toLowerCase() + ) as keyof typeof icons | undefined; + const node = key ? icons[key] : undefined; + return node + ? createElement([ + node[0], + { ...node[1], 'stroke-width': 1.5, 'aria-hidden': 'true' }, + node[2] + ]).outerHTML + : ''; +} +export function Icon(props: { name: string }) { + return ; +} +export function LanguagePicker(props: { + locale: LanguageCode; + disabled?: boolean; + onChange(locale: LanguageCode): void; +}) { + return ( + + ); +} +export function Brand() { + return ( + + + + + ALUX + {ui('PROGRAMMING')} + + + ); +} +const romans = ['I', 'II', 'III', 'IV', 'V']; +export function BookSidebar(props: { + page: ReaderPage; + pages: ReaderPage[]; + groups: BookGroup[]; + count: number; + onBookmarks(): void; + onSearch(): void; +}) { + return ( + + ); +} diff --git a/web/src/reading-preferences.ts b/web/src/reading-preferences.ts new file mode 100644 index 0000000..c8b0c54 --- /dev/null +++ b/web/src/reading-preferences.ts @@ -0,0 +1,17 @@ +import {language} from './i18n.ts'; +import type {ReaderStorage} from './book.ts'; + +export function readingSize(scale=0):number{ + const locale=language(); + const base=locale==='ar'?26:['zh','zh-hant','ja','ko'].includes(locale)?22:24; + return base+scale; +} +export function readingScale(storage:ReaderStorage):number{ + const value=Number(storage.get('alux-reading-scale')||0); + return Number.isFinite(value)?Math.max(-4,Math.min(4,value)):0; +} +export function applyReadingSize(size:number):void{ + for(const name of ['--reading-size','--real-size','--sidebar-size'])document.body.style.setProperty(name,size+'px'); + document.documentElement.style.setProperty('--reading-size',size+'px'); + document.body.style.setProperty('--reader-ui-size',Math.max(18,size-2)+'px'); +} diff --git a/web/src/real-view.tsx b/web/src/real-view.tsx new file mode 100644 index 0000000..9c9bfd5 --- /dev/null +++ b/web/src/real-view.tsx @@ -0,0 +1,390 @@ +import { + For, + Show, + createEffect, + createSignal, + onCleanup, + onMount +} from 'solid-js'; +import { Icon, LanguagePicker, icon } from './reader-ui.tsx'; +import { ui, languageURL } from './i18n.ts'; +import { resolveAnchor } from './anchors.ts'; +import { mapRealLinks } from './worlds.ts'; +import { hasBookmark, toggleBookmark } from './bookmarks.ts'; +import { readingSize, applyReadingSize } from './reading-preferences.ts'; +import type { ReaderViewProps } from './book-view.tsx'; + +export function RealView(props: ReaderViewProps) { + let disposed=false; + const copyTimers=new Set>(); + onCleanup(()=>{disposed=true;for(const timer of copyTimers)clearTimeout(timer);copyTimers.clear();}); + let article!: HTMLElement, toolbar!: HTMLElement; + const [wide, setWide] = createSignal(innerWidth > 1000), + [menu, setMenu] = createSignal(innerWidth > 1000); + const index = props.book.pages.indexOf(props.page), + previous = props.book.pages[index - 1], + next = props.book.pages[index + 1]; + const saved = () => { + props.count; + return hasBookmark(props.page.slug); + }; + const fragment = document.createElement('article'); + fragment.innerHTML = props.page.html; + fragment + .querySelectorAll('h1 img,.copy-code') + .forEach((element) => element.remove()); + if (props.page.slug === 'introduction.html') + fragment.querySelector('.admonition.warning')?.remove(); + for (const table of fragment.querySelectorAll('table')) { + const wrap = document.createElement('div'); + wrap.className = 'real-table-scroll'; + wrap.tabIndex = 0; + wrap.setAttribute('role', 'region'); + wrap.setAttribute('aria-label', ui('Scrollable table')); + table.before(wrap); + wrap.append(table); + } + mapRealLinks(fragment, props.book.pages); + for (const anchor of fragment.querySelectorAll( + 'a[href^="/"]' + )) { + const href = anchor.getAttribute('href') || ''; + if (!href.startsWith('//')) anchor.setAttribute('href', languageURL(href)); + } + for (const pre of fragment.querySelectorAll('pre')) { + const button = document.createElement('button'); + button.className = 'real-copy'; + button.type = 'button'; + button.setAttribute('aria-label', ui('Copy code')); + button.innerHTML = icon('copy'); + pre.append(button); + } + createEffect(() => { + document.body.className = + 'reality-view real-theme-' + + (props.dark ? 'coal' : 'light') + + (wide() && !menu() ? ' real-sidebar-hidden' : '') + + (!wide() && menu() ? ' real-sidebar-open' : ''); + }); + createEffect(() => applyReadingSize(readingSize(props.scale))); + const anchor = () => { + const headings = [ + ...article.querySelectorAll('h1[id],h2[id],h3[id],h4[id]') + ]; + return ( + headings + .filter((heading) => heading.getBoundingClientRect().top < 150) + .at(-1) || headings[0] + )?.id; + }; + async function copy(event: MouseEvent) { + const button = + event.target instanceof Element + ? event.target.closest('.real-copy') + : null; + if (!button) return; + try { + await navigator.clipboard.writeText( + button.closest('pre')?.querySelector('code')?.textContent || '' + ); + if(disposed)return; + button.innerHTML = icon('check'); + button.setAttribute('aria-label', ui('Code copied')); + const timer=setTimeout(() => { + copyTimers.delete(timer); + if (button.isConnected) { + button.innerHTML = icon('copy'); + button.setAttribute('aria-label', ui('Copy code')); + } + }, 1800); + copyTimers.add(timer); + } catch { + if(disposed)return; + props.announce(ui('Copy is unavailable. Select the code to copy it.')); + } + } + function mark(event: MouseEvent) { + const added = toggleBookmark({ + slug: props.page.slug, + realm: 'real', + anchor: anchor() || '', + scroll: scrollY + }); + props.announce( + ui(added ? 'Chapter bookmarked' : 'Bookmark removed'), + event.currentTarget as HTMLElement + ); + } + onMount(() => { + const save = () => + props.storage.set('alux-real-scroll-' + props.page.slug, scrollY); + props.storage.set('alux-real-last-chapter', props.page.slug); + props.onController({ + getCurrentAnchor: anchor, + goToAnchor(id) { + article + .querySelector( + '#' + CSS.escape(resolveAnchor(props.page, id)) + ) + ?.scrollIntoView({ block: 'start', behavior: 'instant' }); + }, + restorePosition() { + scrollTo({ + top: Number( + props.storage.get('alux-real-scroll-' + props.page.slug) || 0 + ), + behavior: 'instant' + }); + }, + openContents: () => setMenu(true), + dispose: save + }); + const resize = () => { + const value = innerWidth > 1000; + setWide(value); + setMenu(value); + }; + const key = (event: KeyboardEvent) => { + if ( + event.ctrlKey || + event.metaKey || + event.altKey || + event.shiftKey || + document.querySelector('dialog[open]') + ) + return; + if (event.key === 'Escape' && !wide()) { + setMenu(false); + return; + } + if ( + !(event.target instanceof Element) || + event.target.closest( + 'input,textarea,select,button,summary,[contenteditable]' + ) + ) + return; + if ( + event.key === (document.dir === 'rtl' ? 'ArrowRight' : 'ArrowLeft') && + previous + ) { + event.preventDefault(); + void props.onNavigate('/real/' + previous.slug); + } else if ( + event.key === (document.dir === 'rtl' ? 'ArrowLeft' : 'ArrowRight') && + next + ) { + event.preventDefault(); + void props.onNavigate('/real/' + next.slug); + } else if (event.key === '/' || event.key.toLowerCase() === 's') { + event.preventDefault(); + props.onSearch(); + } + }; + const observer = new ResizeObserver(() => + document.body.style.setProperty( + '--real-toolbar-height', + toolbar.offsetHeight + 'px' + ) + ); + observer.observe(toolbar); + addEventListener('scroll', save, { passive: true }); + addEventListener('resize', resize); + addEventListener('keydown', key); + onCleanup(() => { + save(); + observer.disconnect(); + removeEventListener('scroll', save); + removeEventListener('resize', resize); + removeEventListener('keydown', key); + props.onController(null); + props.onMusicHost(null); + }); + }); + return ( + <> + + + + +
+ + + +
+ + +
+
+ + + ); +} diff --git a/web/src/search.ts b/web/src/search.ts new file mode 100644 index 0000000..fc30aae --- /dev/null +++ b/web/src/search.ts @@ -0,0 +1,14 @@ +import type {ReaderPage} from './book.ts'; + +interface SearchEntry {p:ReaderPage;title:string;text:string} +const indexes=new WeakMap(); + +/** A localized book is immutable for its lifetime; changing language supplies a new array. */ +export function searchBook(pages:ReaderPage[],query:string):{p:ReaderPage;score:number;at:number}[]{ + let index=indexes.get(pages); + if(!index){index=pages.map(p=>({p,title:p.title.toLowerCase(),text:p.text.toLowerCase()}));indexes.set(pages,index);} + const terms=query.toLowerCase().trim().split(/\s+/); + return index.filter(({title,text})=>terms.every(term=>text.includes(term)||title.includes(term))) + .map(({p,title,text})=>({p,score:terms.reduce((n,term)=>n+(title.includes(term)?15:0)+(text.includes(term)?1:0),0),at:text.indexOf(terms[0]??'')})) + .sort((a,b)=>b.score-a.score); +} diff --git a/web/src/site-meta.ts b/web/src/site-meta.ts new file mode 100644 index 0000000..44c1ca4 --- /dev/null +++ b/web/src/site-meta.ts @@ -0,0 +1,36 @@ +export const siteTitles={en:'ALUX Programming',zh:'ALUX 编程指南','zh-hant':'ALUX 程式設計指南',ja:'ALUX プログラミングガイド',ko:'ALUX 프로그래밍 가이드',vi:'Hướng dẫn lập trình ALUX',de:'ALUX-Programmierleitfaden',es:'Guía de programación de ALUX',ru:'Руководство по программированию ALUX',uk:'Посібник із програмування ALUX',ar:'دليل البرمجة في ALUX'}; +export const siteDescriptions={ + en:'Define what programs mean before choosing how they run. Denotational design, composition, laws and interpreters, with Rust examples.', + zh:'先定义程序的含义,再选择执行方式。通过 Rust 示例理解指称设计、组合性、定律与解释器。', + 'zh-hant':'先定義程式的含義,再選擇執行方式。透過 Rust 範例理解指稱設計、組合性、定律與解釋器。', + ja:'プログラムの意味を定めてから、実行方法を選ぶ。Rust の例を通じて、指示的設計、合成性、法則、インタープリターを学ぶ本です。', + ko:'프로그램의 의미를 먼저 정의한 뒤 실행 방법을 선택합니다. Rust 예제로 지시적 설계, 합성성, 법칙, 해석기를 설명합니다.', + vi:'Xác định ý nghĩa của chương trình trước khi chọn cách thực thi. Tìm hiểu thiết kế theo ngữ nghĩa biểu thị, phép hợp thành, các luật và bộ thông dịch qua ví dụ Rust.', + de:'Zuerst die Bedeutung eines Programms festlegen, dann seine Ausführung wählen. Denotationeller Entwurf, Komposition, Gesetze und Interpreter anhand von Rust-Beispielen.', + es:'Define primero el significado de un programa y después cómo ejecutarlo. Diseño denotacional, composición, leyes e intérpretes con ejemplos en Rust.', + ru:'Сначала определите смысл программы, затем выберите способ выполнения. Денотационное проектирование, композиция, законы и интерпретаторы на примерах Rust.', + uk:'Спочатку визначте зміст програми, потім оберіть спосіб виконання. Денотаційне проєктування, композиція, закони та інтерпретатори на прикладах Rust.', + ar:'حدّد معنى البرنامج أولًا، ثم اختر طريقة تنفيذه. تعرّف إلى التصميم الدلالي والتركيب والقوانين والمفسرات من خلال أمثلة بلغة Rust.' +}; +export const socialLocales={en:'en_US',zh:'zh_CN','zh-hant':'zh_TW',ja:'ja_JP',ko:'ko_KR',ar:'ar_AR',vi:'vi_VN',ru:'ru_RU',uk:'uk_UA',de:'de_DE',es:'es_ES'}; +import type {LanguageCode} from './locale-routing.ts'; +/** Browser/app/site identity has Chinese and English treatments; prose stays localized. */ +export function siteBrandName(code:LanguageCode):string { + return code==='zh'?'ALUX 编程':code==='zh-hant'?'ALUX 程式設計':'ALUX Programming'; +} +export function brandedPageTitle(title:string,code:LanguageCode):string { + let chapter=title.trim(); + for(const name of new Set([...Object.values(siteTitles),'ALUX 编程','ALUX 程式設計'])){ + if(chapter===name)return siteBrandName(code); + if(chapter.endsWith(' · '+name)){chapter=chapter.slice(0,-name.length-3);break;} + } + return chapter?chapter+' · '+siteBrandName(code):siteBrandName(code); +} +export function updateSiteMeta(code:LanguageCode):void{ + const entry=/^\/(?:en\/|zh\/|zh-hant\/|ja\/|ko\/|vi\/|de\/|es\/|ru\/|uk\/|ar\/)?$/.test(location.pathname); + document.title=entry?siteBrandName(code):brandedPageTitle(document.title,code); + const title=entry?(siteTitles[code]||siteTitles.en):document.title,description=siteDescriptions[code]||siteDescriptions.en; + const values={'application-name':siteBrandName(code),'apple-mobile-web-app-title':siteBrandName(code),'description':description,'og:title':title,'og:description':description,'og:type':'website','og:site_name':siteBrandName(code),'og:locale':socialLocales[code]||'en_US','og:url':location.origin+location.pathname,'og:image':location.origin+'/social/alux-programming-'+code+'.jpg','og:image:width':'1200','og:image:height':'630','og:image:alt':siteTitles[code],'twitter:card':'summary_large_image','twitter:title':title,'twitter:description':description,'twitter:image':location.origin+'/social/alux-programming-'+code+'.jpg','twitter:image:alt':siteTitles[code]}; + for(const [key,value]of Object.entries(values)){const attr=key.startsWith('og:')?'property':'name';let meta=document.head.querySelector(`meta[${attr}="${key}"]`);if(!meta){meta=document.createElement('meta');meta.setAttribute(attr,key);document.head.append(meta);}meta.content=value;} + let canonical=document.head.querySelector('link[rel="canonical"]');if(!canonical){canonical=document.createElement('link');canonical.rel='canonical';document.head.append(canonical);}canonical.href=location.origin+location.pathname; +} diff --git a/web/src/ui-format.ts b/web/src/ui-format.ts new file mode 100644 index 0000000..6747c7c --- /dev/null +++ b/web/src/ui-format.ts @@ -0,0 +1,158 @@ +import type { LanguageCode } from './locale-routing.ts'; +export type VariableMessage = + | {key:'chapterProgress';start:number;end:number;total:number} + | { + key: 'minutes' | 'results' | 'chapterCount' | 'readingSize'; + value: number; + } + | { key: 'part'; value: string; begin?: boolean } + | { key: 'explore'; value: string }; +const columns: Record = { + en: 0, + zh: 1, + ko: 2, + ja: 3, + ar: 4, + 'zh-hant': 5, + vi: 6, + ru: 7, + uk: 8, + de: 9, + es: 10 +}; +/** Variable labels use explicit keys and values, never regular expressions over rendered text. */ +export function formatMessage( + locale: LanguageCode, + message: VariableMessage +): string { + if(message.key==='chapterProgress'){ + const range=message.start===message.end?String(message.start):message.start+'–'+message.end; + const labels:Record={en:'Chapter',zh:'本章','zh-hant':'本章',ja:'この章',ko:'이 장',ar:'هذا الفصل',vi:'Chương này',ru:'Глава',uk:'Розділ',de:'Kapitel',es:'Capítulo'}; + return labels[locale]+' '+range+' / '+message.total; + } + const value = String(message.value), + column = columns[locale]; + const plural = (words: Record): string => + words[new Intl.PluralRules(locale).select(Number(value))] || + words.other || + ''; + switch (message.key) { + case 'minutes': + return ( + [ + value + ' min', + value + ' 分钟', + value + '분', + value + '分', + value + ' دقائق', + value + ' 分鐘', + value + ' phút', + value + ' мин', + value + ' хв', + value + ' Min.', + value + ' min' + ][column] || '' + ); + case 'results': + return { + en: value + ' ' + (value === '1' ? 'RESULT' : 'RESULTS'), + zh: value + ' 条结果', + 'zh-hant': value + ' 條結果', + ko: value + '개 결과', + ja: value + '件', + vi: value + ' kết quả', + de: value + ' ' + plural({ one: 'Ergebnis', other: 'Ergebnisse' }), + es: value + ' ' + plural({ one: 'resultado', other: 'resultados' }), + ru: + value + + ' ' + + plural({ + one: 'результат', + few: 'результата', + many: 'результатов', + other: 'результата' + }), + uk: + value + + ' ' + + plural({ + one: 'результат', + few: 'результати', + many: 'результатів', + other: 'результату' + }), + ar: plural({ + zero: value + ' نتيجة', + one: 'نتيجة واحدة', + two: 'نتيجتان', + few: value + ' نتائج', + many: value + ' نتيجة', + other: value + ' نتيجة' + }) + }[locale]; + case 'part': + return ( + [ + (message.begin ? 'Begin Part ' : 'Part ') + value, + '第 ' + value + ' 部', + value + '부', + value + '部', + 'الجزء ' + value, + '第 ' + value + ' 部', + 'Phần ' + value, + 'Часть ' + value, + 'Частина ' + value, + 'Teil ' + value, + 'Parte ' + value + ][column] || '' + ); + case 'chapterCount': + return ( + [ + value + ' CHAPTERS TO EXPLORE', + value + ' 个章节', + value + '개 장', + value + '章', + value + ' فصول', + value + ' 個章節', + value + ' chương', + value + ' глав', + value + ' розділів', + value + ' Kapitel', + value + ' capítulos' + ][column] || '' + ); + case 'readingSize': + return ( + [ + 'Reading size ' + value + ' pixels', + '字号为 ' + value + ' 像素', + '글자 크기 ' + value + '픽셀', + '文字サイズ ' + value + 'ピクセル', + 'حجم النص ' + value + ' بكسل', + '字級為 ' + value + ' 像素', + 'Cỡ chữ ' + value + ' pixel', + 'Размер текста: ' + value + ' пикс.', + 'Розмір тексту: ' + value + ' пікс.', + 'Schriftgröße: ' + value + ' Pixel', + 'Tamaño del texto: ' + value + ' píxeles' + ][column] || '' + ); + case 'explore': + return ( + [ + 'Explore ' + value, + '探索 ' + value, + value + ' 탐색', + value + 'を探る', + 'استكشف ' + value, + '探索 ' + value, + 'Khám phá ' + value, + 'Изучить ' + value, + 'Дослідити ' + value, + value + ' erkunden', + 'Explorar ' + value + ][column] || '' + ); + } +} diff --git a/web/src/ui-messages.ts b/web/src/ui-messages.ts new file mode 100644 index 0000000..906f70a --- /dev/null +++ b/web/src/ui-messages.ts @@ -0,0 +1,8 @@ +import english from '../locales/ui/en.json' with { type: 'json' }; +export type MessageKey = keyof typeof english; +export type UIMessages = Record; +export const englishMessages: UIMessages = english; +/** Keys are supplied explicitly, never inferred from book prose. */ +export function message(messages: UIMessages, key: MessageKey): string { + return messages[key]; +} diff --git a/web/src/worlds.ts b/web/src/worlds.ts new file mode 100644 index 0000000..6a174f3 --- /dev/null +++ b/web/src/worlds.ts @@ -0,0 +1,14 @@ +import type {ReaderPage} from './book.ts'; +export function gatewayMarkup({t=(s:string)=>s,languagePicker=()=>''}:{t?:(text:string)=>string;languagePicker?:()=>string}={}):string{ + return `
${languagePicker()}

${t('Choose your world')}

`; +} + +/** Only known chapter URLs change realm. Assets, external links and anchors keep their meaning. */ +export function mapRealLinks(root:ParentNode,pages:ReaderPage[]):void{ + const known=new Set(pages.map(p=>p.slug)); + root.querySelectorAll('a[href]').forEach(a=>{ + const raw=a.getAttribute('href');if(!raw||raw.startsWith('#'))return; + const url=new URL(raw,location.origin); + if(url.origin===location.origin&&known.has(url.pathname.slice(1)))a.setAttribute('href','/real'+url.pathname+url.search+url.hash); + }); +} diff --git a/web/style.css b/web/style.css new file mode 100644 index 0000000..4fe36ea --- /dev/null +++ b/web/style.css @@ -0,0 +1,28 @@ +@font-face{font-family:Inter;src:url('/fonts/inter.woff2') format('woff2');font-style:normal;font-weight:100 900;font-display:swap} +@font-face{font-family:'IBM Plex Mono';src:url('/fonts/ibm-plex-mono.woff2') format('woff2');font-style:normal;font-weight:400;font-display:swap} +:root{--paper:#f5f1e8;--paper-light:#fbf8f1;--ink:#223b34;--text:#4c4b41;--muted:#7c7b6e;--copper:#a0643e;--gold:#c39b5c;--line:#dcd4c5;--forest:#203a33;--serif:'Cormorant Garamond',Georgia,serif;--sans:Inter,Arial,sans-serif;--mono:'IBM Plex Mono',monospace;--reading-size:18px} +*{box-sizing:border-box}html{scroll-behavior:smooth;scroll-padding-top:96px}body{margin:0;background:var(--paper);color:var(--ink);font-family:var(--sans);font-size:14px;-webkit-font-smoothing:antialiased}body:after{content:'';position:fixed;inset:0;pointer-events:none;z-index:100;opacity:.035;background-image:url("data:image/svg+xml,%3Csvg viewBox='0 0 180 180' xmlns='http://www.w3.org/2000/svg'%3E%3Cfilter id='n'%3E%3CfeTurbulence type='fractalNoise' baseFrequency='.82' numOctaves='3' stitchTiles='stitch'/%3E%3C/filter%3E%3Cpath fill='%23000' filter='url(%23n)' opacity='.65' d='M0 0h180v180H0z'/%3E%3C/svg%3E")}a{color:inherit;text-decoration:none}button,input{font:inherit}button,a,input,summary{-webkit-tap-highlight-color:transparent}button{color:inherit;cursor:pointer}button{border:0}a,button{touch-action:manipulation}button:disabled{cursor:default;opacity:.4}img{max-width:100%;display:block}svg{width:19px;height:19px;flex-shrink:0}button svg,a svg{vertical-align:middle}a:focus-visible,button:focus-visible,summary:focus-visible{outline:2px solid var(--copper);outline-offset:6px}input:focus-visible{outline:2px solid var(--copper);outline-offset:2px}button,a{transition:color .2s,background .2s,box-shadow .2s,transform .2s}button:hover:enabled{color:var(--copper)}[hidden]{display:none!important}.skip-link{position:fixed;left:20px;top:-70px;z-index:300;background:var(--ink);color:white;padding:15px}.skip-link:focus{top:15px}.icon-button{display:inline-flex;align-items:center;justify-content:center;background:transparent;width:40px;height:40px;border-radius:4px}.icon-button:hover{background:#a0643e0e}.text-button{display:inline-flex;gap:8px;align-items:center;background:transparent;font-size:12px;padding:8px;color:var(--muted)}.text-button svg{width:15px}.site-header{height:110px;width:min(1320px,calc(100% - 112px));margin:auto;display:flex;align-items:center;border-bottom:1px solid var(--line);gap:42px}.brand{display:flex;align-items:center;gap:16px;flex-shrink:0}.brand img{width:46px;height:46px;object-fit:contain}.brand>span{font-family:var(--serif);font-size:26px;font-weight:600;letter-spacing:6px;line-height:1.15}.brand small{display:block;font-family:var(--mono);font-size:10px;letter-spacing:2.2px;margin-top:5px}.site-header nav{display:flex;gap:35px;margin-left:auto;align-items:center;font-family:var(--serif);font-weight:600;font-size:19px}.site-header nav a:hover{color:var(--copper)}.site-header nav svg{width:15px;height:15px;margin-left:2px}.search-button{background:transparent;display:flex;align-items:center;gap:9px;font-size:12px;padding:10px 0 10px 24px;border-left:1px solid var(--line)}kbd{font:10px var(--mono);border:1px solid currentColor;border-radius:3px;padding:3px 5px;color:var(--muted);opacity:.7}.search-button kbd{border:0;font-size:9px}.hero{position:relative;max-width:1440px;margin:auto;min-height:650px;display:flex;align-items:center;padding:55px 0 42px;isolation:isolate}.hero-copy{width:47%;padding-left:max(56px,calc((100% - 1320px)/2));position:relative;z-index:3;pointer-events:none}.hero-copy>*{pointer-events:auto}.hero h1{font-family:var(--serif);font-size:112px;font-weight:600;line-height:.91;margin:0 0 28px}.hero h1 em{font-weight:500;color:var(--copper)}.hero-copy>p{font-family:var(--serif);font-size:24px;line-height:1.33;margin:0 0 15px}.hero-copy>p.hero-description{font-family:var(--sans);font-size:13px;line-height:1.8;color:var(--muted);max-width:345px;margin:20px 0 29px}.button{display:inline-flex;align-items:center;justify-content:center;gap:28px;padding:17px 25px;font-family:var(--serif);font-size:20px;min-height:54px;border-radius:2px}.button.primary{background:var(--copper);color:#fff8e9;box-shadow:inset 0 1px #ffffff3b,0 4px 0 #7e4c2d18;border:1px solid #8c5335}.button.primary:hover{background:#865134;transform:translateY(-2px);box-shadow:0 7px 16px #63482c20}.button svg{width:22px}.hero-note{display:flex;align-items:center;gap:20px;margin-top:37px;pointer-events:none}.hero-note .star-mark{font-size:31px;color:var(--copper);position:relative}.star-mark:before,.star-mark:after{content:'';display:block;height:15px;width:1px;background:var(--copper);margin:auto}.hero-note>span:last-child{font:9px/1.9 var(--mono);letter-spacing:1.5px;color:var(--muted)}.resume-link{display:flex;gap:12px;align-items:center;font-size:11px;margin-top:18px;color:var(--copper)}.hero-world{position:absolute;right:6px;top:21px;width:75%;height:calc(100% - 38px);perspective:1100px;--tilt-x:0deg;--tilt-y:0deg}.book-art-button{position:absolute;inset:0;background:none;padding:0;display:flex;align-items:center;transform:rotateX(var(--tilt-x)) rotateY(var(--tilt-y));transition:transform .65s cubic-bezier(.18,.75,.25,1)}.hero-art{width:100%;height:auto;object-fit:contain;filter:drop-shadow(0 18px 16px #55402108);mask-image:linear-gradient(to right,transparent,black 5%,black 95%,transparent)}.book-art-button:hover{color:inherit}.world-label{position:absolute;font:10px var(--mono);letter-spacing:1px;color:#a88f69;pointer-events:none}.label-top{top:32px;right:36%;transform:rotate(-5deg)}.world-caption{position:absolute;right:50px;bottom:10px;left:38%;display:flex;justify-content:space-between;gap:20px;font:8px var(--mono);letter-spacing:1.5px;color:var(--muted)}.world-caption svg{height:12px;width:12px}.world-hotspot{position:absolute;z-index:4;display:flex;align-items:center;gap:10px;padding:12px}.world-hotspot>span{width:9px;height:9px;display:block;border-radius:50%;background:var(--gold);box-shadow:0 0 0 5px #c39b5c26;animation:beacon 3.5s infinite}.world-hotspot small{background:var(--paper-light);border:1px solid var(--line);color:var(--ink);padding:8px 12px;box-shadow:0 5px 16px #56472c14;opacity:0;transform:translateY(4px);transition:.25s;font:11px var(--sans);white-space:nowrap}.world-hotspot svg{width:12px;height:12px}.world-hotspot:hover small,.world-hotspot:focus-visible small{opacity:1;transform:translateY(0)}.hotspot-one{top:30%;left:59%}.hotspot-two{top:56%;left:69%}@keyframes beacon{50%{box-shadow:0 0 0 9px #c39b5c05}} +.chapters-section{max-width:1320px;width:calc(100% - 112px);margin:0 auto;padding:40px 0 20px;border-top:1px solid #bdb5a6}.section-heading{display:flex;justify-content:space-between;align-items:end;gap:35px}.section-label{font:9px var(--mono);letter-spacing:2px;color:var(--muted);display:flex;align-items:center;gap:12px}.section-label>span{height:1px;width:34px;background:var(--copper)}h2{font-family:var(--serif);font-size:46px;font-weight:500;line-height:1.1;margin:17px 0}.section-heading>p{font-family:var(--serif);font-size:18px;line-height:1.35;margin:0 0 16px;max-width:300px;color:var(--text)}.chapter-worlds{display:grid;grid-template-columns:repeat(4,minmax(0,1fr));margin:35px 0 35px;position:relative}.chapter-world{padding:0 30px 15px;border-right:1px solid var(--line);position:relative;display:flex;flex-direction:column;align-items:flex-start}.chapter-world:first-child{padding-left:0}.chapter-world:last-child{padding-right:0;border:0}.part-numeral{position:absolute;top:20px;left:25px;font-family:var(--serif);font-size:39px;color:var(--copper)}.chapter-world:first-child .part-numeral{left:0}.chapter-art{height:145px;width:100%;background-image:url('/art/worlds.webp');background-size:400% 100%;background-repeat:no-repeat;transition:transform .5s}.atlas-0{background-position:0 50%}.atlas-1{background-position:33.3333% 50%}.atlas-2{background-position:66.6666% 50%}.atlas-3{background-position:100% 50%}.chapter-world:hover .chapter-art{transform:translateY(-7px)}.chapter-count{font:8px var(--mono);letter-spacing:1.5px;color:var(--muted);margin:10px 0}.chapter-world h3{font:600 29px/1.1 var(--serif);margin:0 0 12px}.chapter-world p{font-size:12px;line-height:1.7;color:var(--muted);margin:0 0 24px;max-width:240px}.chapter-link{margin-top:auto;display:flex;align-items:center;gap:15px;color:var(--copper);font:600 16px var(--serif)}.chapter-link:before{content:'';width:26px;height:1px;background:var(--copper)}.chapter-link svg{width:18px}.full-contents{border-top:1px solid var(--line);border-bottom:1px solid var(--line);margin-top:0;padding:0}.full-contents summary{list-style:none;cursor:pointer;display:flex;align-items:center;justify-content:space-between;font:18px var(--serif);padding:23px 0}.full-contents summary::-webkit-details-marker{display:none}.full-contents[open] summary svg{transform:rotate(45deg)}.contents-grid{display:grid;grid-template-columns:repeat(3,minmax(0,1fr));gap:28px;padding:0 0 35px}.contents-grid h3{font:600 23px var(--serif);margin:18px 0}.contents-grid h3 span{color:var(--copper);margin-right:8px}.contents-grid a{display:flex;justify-content:space-between;align-items:center;gap:10px;padding:8px 0;font-size:12px;color:var(--text)}.contents-grid a:hover{color:var(--copper)}.contents-grid a svg{width:13px;height:13px} +.playground{max-width:1320px;width:calc(100% - 112px);margin:80px auto;display:grid;grid-template-columns:.85fr 1.3fr;gap:70px;align-items:center}.playground-copy h2{font-size:53px;margin:22px 0}.playground-copy h2 em{color:var(--copper)}.playground-copy>p{font-family:var(--serif);font-size:21px;line-height:1.5;color:var(--text)}.playground-copy>a{display:inline-flex;gap:10px;align-items:center;font-size:11px;color:var(--copper);margin-top:15px}.playground-copy>a svg{width:15px}.workbench{border:1px solid var(--line);background:#faf7ef;padding:25px 28px;box-shadow:5px 6px 0 -1px #f5f1e8,5px 6px 0 0 #dcd4c5}.workbench-head{display:flex;justify-content:space-between;align-items:center}.workbench-head>span{font:9px var(--mono);letter-spacing:1.5px}.workbench-hint{font-size:12px;color:var(--muted);margin:10px 0 28px}.block-palette{display:flex;gap:23px;justify-content:center;padding:15px 0 29px}.toy-brick{height:85px;width:115px;position:relative;border-radius:3px;display:flex;flex-direction:column;align-items:center;justify-content:center;color:#fffaf0!important;box-shadow:inset -7px -7px #00000013,inset 2px 2px #ffffff1a,0 7px 0 #00000018;transform:rotate(-4deg);transition:transform .25s,box-shadow .25s}.toy-brick:nth-child(2){transform:rotate(3deg)}.toy-brick:nth-child(3){transform:rotate(-2deg)}.toy-brick:hover{transform:translateY(-8px) rotate(0);box-shadow:inset -7px -7px #00000013,0 15px 15px #58482a15}.sage{--brick-color:#647c67;background:var(--brick-color)}.gold{--brick-color:#c49a4e;background:var(--brick-color)}.copper{--brick-color:#a56c4e;background:var(--brick-color)}.studs{display:flex;gap:24px;position:absolute;top:-10px}.studs b{width:22px;height:15px;border-radius:50%;background:var(--brick-color);box-shadow:inset 1px 3px #ffffff26,inset -2px -2px #00000018,0 3px 0 #00000012}.toy-brick strong{font:500 30px var(--serif)}.toy-brick small{font-size:9px;margin-top:4px}.composition-line{display:flex;align-items:center;gap:12px;border-block:1px solid var(--line);padding:22px 0}.composition-line>svg{width:16px;color:#ac9d85}.composition-line label{font:8px var(--mono);letter-spacing:1px;display:flex;flex-direction:column;gap:8px;align-items:center}.composition-line input{width:52px;border:1px solid var(--line);background:var(--paper-light);color:var(--ink);font:20px var(--serif);text-align:center;padding:5px 0}.drop-zone{display:flex;flex:1;min-height:66px;align-items:center;justify-content:center;flex-wrap:wrap;gap:7px;border:1px dashed #c9c0b0;padding:8px;transition:.2s}.drop-zone>span{font:10px/1.5 var(--mono);text-align:center;max-width:130px;color:#948b78}.drop-zone.drag-over{background:#dce8d7;border-color:#647c67}.mini-brick{color:#fff8e9;padding:10px 9px;border-radius:2px;font:15px var(--serif);box-shadow:inset -3px -3px #0002}.mini-brick small{display:inline-block;margin-left:7px;opacity:.65;font:11px var(--sans)}.output-value{min-width:42px;max-width:120px;overflow-wrap:anywhere;text-align:center}.output-value>span{font:8px var(--mono);letter-spacing:1px;display:block}.output-value output{display:block;font:600 31px var(--serif);color:var(--copper);margin-top:6px}.experiment-code{position:relative;padding-top:20px}.experiment-code>span{position:absolute;right:0;top:18px;font:8px var(--mono);letter-spacing:1px;color:var(--muted)}.experiment-code pre{font:10px/1.8 var(--mono);color:#65735f;margin:0;white-space:pre-wrap;overflow-wrap:anywhere}.experiment-code .text-button{position:absolute;right:-8px;bottom:-5px}.site-footer{border-top:1px solid var(--line);max-width:1320px;width:calc(100% - 112px);margin:auto;display:flex;align-items:center;justify-content:space-between;gap:25px;padding:40px 0 45px}.site-footer .brand img{width:34px;height:34px}.site-footer .brand>span{font-size:20px}.site-footer .brand small{font-size:7px}.site-footer p{font-family:var(--serif);font-size:16px;color:var(--muted)}.site-footer>div:nth-child(2){display:flex;gap:28px;font-size:11px}.site-footer a:hover{color:var(--copper)}.site-footer svg{width:13px;height:13px}.site-footer>span{font:9px/1.8 var(--mono);color:var(--muted)} +/* The reading room */ +.book-sidebar{position:fixed;inset:0 auto 0 0;width:275px;background:#203a33;color:#e8e5d4;padding:33px 25px 20px;overflow:auto;z-index:35;border-right:1px solid #ad94623b;scrollbar-width:thin;scrollbar-color:#63715e #203a33}.book-sidebar .brand{gap:14px;margin-bottom:27px}.book-sidebar .brand img{width:39px;height:39px}.book-sidebar .brand>span{font-size:24px}.book-sidebar .brand small{font-size:8px;letter-spacing:2px}.back-to-world{display:flex;align-items:center;gap:8px;color:#b9c3b5;font-size:11px;margin-bottom:24px}.back-to-world svg{width:15px}.sidebar-search{display:flex;align-items:center;gap:9px;border:1px solid #b9c3b52e;width:100%;background:#ffffff05;color:#d4d8ca;font-size:11px;padding:11px 10px;margin-bottom:23px}.sidebar-search svg{width:15px;height:15px}.sidebar-search kbd{margin-left:auto;color:#c5c9ba;white-space:nowrap;font-size:8px}.intro-nav{display:flex;align-items:center;gap:9px;font:17px var(--serif);padding:11px 9px}.intro-nav svg{width:15px}.sidebar-group{border-top:1px solid #c9bc932b;margin-top:22px;padding-top:21px}.sidebar-group h2{font:10px/1.6 var(--mono);color:#c8a46b;letter-spacing:1.2px;text-transform:uppercase;display:flex;gap:11px;margin:0 0 12px}.sidebar-group h2 span{font:24px/1 var(--serif);min-width:18px}.sidebar-group nav{display:block}.sidebar-group a{display:flex;gap:12px;align-items:baseline;font:16px/1.35 var(--serif);padding:7px 9px;margin-left:-9px;margin-right:-7px;border-left:2px solid transparent;color:#d6dbcb}.sidebar-group a>span{font:8px var(--mono);color:#a8ad96;min-width:15px}.sidebar-group a:hover{background:#ffffff07;color:#e9c38c}.book-sidebar a.active{border-left-color:#cfac70;background:#fff5cc0b;color:#ffdf9e}.sidebar-bottom{font:8px/2 var(--mono);letter-spacing:1.6px;color:#cab184;text-align:center;padding:40px 0 10px}.sidebar-bottom span{display:block;font-size:30px;line-height:1.4;margin-bottom:8px}.reader-shell{margin-left:275px;min-height:100vh;background:var(--paper-light);position:relative}.reader-shell:after{content:'';position:fixed;left:275px;top:0;bottom:0;width:18px;background:linear-gradient(90deg,#81725312,transparent);pointer-events:none;z-index:15}.reader-toolbar{height:75px;position:sticky;top:0;z-index:25;display:flex;align-items:center;justify-content:space-between;gap:15px;padding:0 43px;border-bottom:1px solid var(--line);background:var(--paper-light)}.reader-breadcrumb{display:flex;align-items:center;gap:10px;font:10px var(--mono);color:var(--muted);min-width:0}.reader-breadcrumb svg{width:13px}.reader-breadcrumb>span{overflow:hidden;text-overflow:ellipsis;white-space:nowrap;max-width:260px}.reader-tools{display:flex;gap:3px;flex-shrink:0}.reader-tools .icon-button{width:34px;height:36px;font:12px var(--sans)}.reader-tools svg{width:16px;height:16px}#bookmark[aria-pressed=true]{color:var(--copper);background:#c49a4e24}#bookmark[aria-pressed=true] svg{fill:#c49a4e66}.mobile-menu{display:none}.reading-progress{position:fixed;left:275px;right:0;top:74px;height:2px;z-index:28;pointer-events:none}.reading-progress span{display:block;height:100%;width:0;background:#ba8c51}.reader-layout{display:grid;grid-template-columns:minmax(0,780px) minmax(150px,195px);max-width:1100px;margin:auto;gap:55px;padding:43px 45px 0}.book-page{min-width:0;position:relative;padding-bottom:26px;outline:none}.page-ornament{display:flex;justify-content:space-between;align-items:center;gap:20px;border-bottom:1px solid var(--line);padding-bottom:18px;font:8px var(--mono);letter-spacing:1.7px;color:var(--muted)}.page-ornament>span:last-child{font-size:15px;color:var(--copper)}.page-meta{display:flex;justify-content:space-between;gap:20px;margin-top:26px;font:8px var(--mono);letter-spacing:1px;color:var(--muted)}.prose{font:var(--reading-size)/1.85 Georgia,'Times New Roman',serif;color:var(--text);overflow-wrap:break-word}.prose h1,.prose h2,.prose h3,.prose h4{color:var(--ink);font-family:var(--serif);font-weight:600;position:relative;scroll-margin-top:100px}.prose h1{font-size:66px;line-height:.98;margin:28px 0 35px}.prose h2{font-size:38px;line-height:1.15;margin:44px 0 20px}.prose h3{font-size:29px;line-height:1.2;margin:30px 0 14px}.prose h4{font-size:24px;line-height:1.3;margin:26px 0 14px}.prose p{margin:18px 0}.prose a{color:var(--copper);text-decoration:underline;text-decoration-color:#a0643e50;text-underline-offset:3px}.prose a:hover{text-decoration-color:var(--copper)}.heading-anchor{position:absolute;margin-left:8px;opacity:0;font-family:var(--mono);font-size:14px;bottom:3px;text-decoration:none!important}.prose :is(h1,h2,h3,h4):hover .heading-anchor,.heading-anchor:focus-visible{opacity:1}.prose ul,.prose ol{padding-left:26px}.prose li{padding-left:4px;margin:8px 0}.prose strong{color:var(--ink)}.prose blockquote{margin:30px 0;padding:6px 0 6px 23px;border-left:1px solid var(--copper);font-style:italic;color:var(--muted)}.prose blockquote p{margin:9px 0}.prose img{max-width:100%;height:auto;margin:25px auto}.prose img.section-image{max-height:360px;width:auto;max-width:100%;object-fit:contain;margin:18px auto 32px}.prose h1 img{display:inline-block!important;width:40px!important;margin:0 8px 0 0!important;vertical-align:middle;filter:brightness(.25)}.prose figure{margin:25px 0}.prose iframe{display:block;width:100%;min-height:350px;max-width:100%;border:0}.prose figcaption{font-size:.8em;text-align:center;color:var(--muted);line-height:1.5}.prose hr{border:0;border-top:1px solid var(--line);margin:35px 0}.admonition{font-size:.91em;border-block:1px solid var(--line);padding:16px 20px;margin:26px 0;background:#ede8da52;border-left:2px solid #a2926e}.admonition.tip{border-left-color:#778e78}.admonition.warning{border-left-color:#b38949}.admonition.quote{border:0;border-left:1px solid var(--copper);font-style:italic;background:none;padding-left:23px}.admonition-title{font:9px var(--mono);text-transform:uppercase;letter-spacing:1.4px;color:var(--copper);margin-bottom:11px}.admonition p:first-of-type{margin-top:0}.admonition p:last-child{margin-bottom:0}.code-block{background:#233733;border:1px solid #283d36;border-radius:3px;color:#e0dfcc;margin:27px 0;font-size:12px;overflow:hidden;position:relative}.code-toolbar{display:flex;justify-content:space-between;padding:10px 14px;border-bottom:1px solid #ffffff10;font:9px var(--mono);letter-spacing:1px;align-items:center;color:#c4ae7e;text-transform:uppercase}.copy-code{background:none;color:#b6c2b5;font:9px var(--mono);padding:3px 4px}.copy-code:hover{color:#f6d8aa!important}.code-block pre{margin:0;overflow:auto;padding:18px 19px 23px;tab-size:4;font:12px/1.85 var(--mono);scrollbar-width:thin;scrollbar-color:#6f8073 #233733}.prose code{font-family:var(--mono);font-size:.76em;color:#805c3f;background:#eae3d652;padding:3px 5px;border-radius:2px;overflow-wrap:anywhere}.prose pre code{background:none;color:inherit;padding:0;font-size:inherit;overflow-wrap:normal}.hljs-keyword,.hljs-selector-tag,.hljs-literal{color:#dfa655}.hljs-string,.hljs-regexp{color:#b5c998}.hljs-title,.hljs-type,.hljs-built_in{color:#a2c4c2}.hljs-comment{color:#8e9d88;font-style:italic}.hljs-number{color:#d2b77d}.hljs-meta{color:#b5a68e}.hljs-params{color:#cbd5c3}.table-scroll{overflow:auto;max-width:100%;margin:25px 0}.prose table{border-collapse:collapse;min-width:100%;font-size:.85em;line-height:1.6}.prose td,.prose th{border:1px solid var(--line);padding:11px 13px;text-align:left;min-width:110px}.prose th{background:#e8e2d452;font-weight:600;color:var(--ink)}.math-display{max-width:100%;overflow:auto;padding:12px 0;margin:16px 0;font-size:.9em}.katex-display{margin:.6em 0!important}.katex{font-size:1.05em!important}.prose details{border-block:1px solid var(--line);padding:15px 0;margin:24px 0}.prose summary{cursor:pointer;color:var(--copper);font-size:.9em}.page-outline{position:sticky;top:120px;align-self:start;padding-top:5px;max-height:calc(100vh - 150px);overflow:auto;scrollbar-width:thin}.page-outline .section-label{font-size:8px;letter-spacing:1.5px}.page-outline nav{margin-top:19px;padding-left:14px;border-left:1px solid var(--line)}.page-outline nav a{display:block;font:14px/1.4 var(--serif);color:var(--muted);padding:7px 0}.page-outline nav a.current,.page-outline nav a:hover{color:var(--copper)}.page-outline .outline-level-3{padding-left:10px;font-size:13px}.outline-note{border-top:1px solid var(--line);margin-top:30px;padding:22px 0 20px;font:20px/1.3 var(--serif);color:var(--muted)}.outline-note:before{content:'✦';color:var(--copper);font-size:18px;display:block;margin-bottom:17px}.source-link{display:flex;gap:5px;align-items:center;font-size:10px;color:var(--muted);margin:10px 0}.source-link svg{height:12px;width:12px}.page-outline .text-button{font-size:10px;padding-left:0}.page-navigation{display:grid;grid-template-columns:1fr auto 1fr;gap:20px;align-items:center;border-top:1px solid var(--line);margin-top:55px;padding:26px 0}.page-navigation a{font:18px/1.3 var(--serif);color:var(--copper);display:flex;gap:13px;align-items:center}.page-navigation a:last-child{justify-self:end;text-align:right}.page-navigation small{display:block;font:7px var(--mono);letter-spacing:1px;color:var(--muted);margin-bottom:8px}.page-navigation svg{width:23px}.folio{font:9px var(--mono);color:var(--muted);white-space:nowrap}.page-end{text-align:center;color:var(--copper);padding:5px 0;font-size:18px}.sidebar-scrim{display:none}.night{--paper-light:#202e29;--paper:#25352f;--ink:#e1d9bf;--text:#c9c7b7;--muted:#a6ae9b;--line:#4b5545;--copper:#d1a16a}.night .admonition{background:#29382e}.night .prose code{color:#e0b988;background:#ffffff07}.night .prose th{background:#ffffff06}.night .reader-shell:after{background:none} +/* Search is a book-wide command palette, with real full-text results. */ +#search-dialog{border:1px solid var(--line);border-radius:5px;background:var(--paper-light);color:var(--ink);padding:0;width:min(680px,calc(100% - 32px));max-height:min(750px,85dvh);margin:10vh auto 0;box-shadow:0 30px 100px #162b3155;overflow:hidden}#search-dialog::backdrop{background:#192a2266;backdrop-filter:blur(5px)}.search-top{display:flex;align-items:center;gap:16px;padding:19px 22px;border-bottom:1px solid var(--line)}#search-input{border:0;background:transparent;outline:none!important;min-width:0;flex:1;color:var(--ink);font-size:16px;padding:8px 0}#search-input::placeholder{color:var(--muted);font-family:var(--serif);font-size:21px}#search-results{overflow:auto;max-height:calc(min(750px,85dvh) - 140px);padding:10px 15px 20px}.search-hint{font-size:12px;color:var(--muted);padding:4px 8px}.search-group-label{font:8px var(--mono);letter-spacing:1px;color:var(--muted);padding:12px 10px}.search-result{display:flex;justify-content:space-between;align-items:center;gap:20px;padding:14px 12px;border-bottom:1px solid #dcd4c560;border-radius:3px}.search-result:hover,.search-result:focus{background:#ebe4d6}.search-result small{display:block;font:8px var(--mono);color:var(--copper);margin-bottom:7px}.search-result strong{font:600 25px var(--serif)}.search-result p{font-size:11px;line-height:1.6;color:var(--muted);margin:7px 0 0}.search-result svg{width:20px;color:var(--copper)}.search-footer{display:flex;gap:12px;justify-content:flex-end;padding:14px 24px;font:9px var(--mono);border-top:1px solid var(--line);align-items:center;color:var(--muted)}.no-results{padding:20px 15px 40px}.no-results h3{font:30px var(--serif)}.no-results p{font-size:12px;color:var(--muted)}#announcement{position:fixed;bottom:25px;left:50%;transform:translate(-50%,15px);opacity:0;pointer-events:none;z-index:200;background:var(--forest);color:#f7edce;padding:14px 22px;box-shadow:0 8px 25px #0002;font-size:12px;max-width:90%;transition:.2s}#announcement.show{opacity:1;transform:translate(-50%,0)} +/* A short, reversible book opening; the content never depends on it. */ +#opening{position:fixed;inset:0;z-index:110;pointer-events:none;display:none;align-items:center;justify-content:center;perspective:1400px;background:#f5f1e8ef}.opening-book #opening{display:flex}.opening-cover{position:absolute;width:300px;height:410px;background:#243c33;border:4px double #b4985c;box-shadow:0 30px 80px #203a3340,inset 0 0 0 12px #243c33,inset 0 0 0 13px #b4985c;display:flex;flex-direction:column;align-items:center;justify-content:center;gap:25px;transform-origin:left center;z-index:2;animation:open-cover .8s cubic-bezier(.25,.2,.2,1) both;color:#e3c487}.opening-cover img{width:65px;height:65px;object-fit:contain}.opening-cover>span{font:39px/1.15 var(--serif);text-align:center}.opening-cover small{font:8px var(--mono);letter-spacing:1.5px}.opening-paper{width:300px;height:410px;background:#fff8e8;border:1px solid #dac6a0;box-shadow:6px 4px 0 #d4c3a3,10px 7px 0 #eee3cc;transform:rotate(1deg)}@keyframes open-cover{0%,15%{transform:rotateY(0deg)}100%{transform:rotateY(-155deg);opacity:0}}::view-transition-old(root){animation:page-away .3s ease both}::view-transition-new(root){animation:page-arrive .4s ease both}@keyframes page-away{to{opacity:0;transform:translateX(-14px)}}@keyframes page-arrive{from{opacity:0;transform:translateX(14px)}}.not-found,.load-error{padding:100px 8%;min-height:65vh}.not-found>span{font:12px var(--mono);color:var(--copper)}.not-found h1,.load-error h1{font:64px var(--serif)} +@media(min-width:1600px){.hero{max-width:1540px;min-height:710px}.hero-copy{padding-left:110px}.hero-world{right:0;width:76%}.hero h1{font-size:125px}} +@media(max-width:1200px){.site-header,.chapters-section,.playground,.site-footer{width:calc(100% - 72px)}.hero-copy{padding-left:36px}.hero h1{font-size:96px}.hero{min-height:610px}.hero-world{width:76%;right:-10px}.hero-description{max-width:300px}.hero-copy>p{font-size:22px}.hero-world .label-top{top:50px}.world-caption{right:35px;left:37%;font-size:7px}.search-button kbd{display:none}.chapter-world{padding:0 20px 12px}.chapter-world h3{font-size:26px}.chapter-world p{font-size:11px}.playground{gap:35px}.playground-copy h2{font-size:46px}.workbench{padding:22px}.reader-layout{gap:32px;padding-inline:35px;grid-template-columns:minmax(0,1fr) 150px}.reader-toolbar{padding-inline:30px}.reader-breadcrumb>span{display:none}.book-sidebar{width:250px;padding-inline:21px}.reader-shell{margin-left:250px}.reader-shell:after,.reading-progress{left:250px}.prose h1{font-size:58px}.site-footer>div:nth-child(2){gap:15px}.toy-brick{width:96px}.block-palette{gap:19px}.composition-line{gap:7px}.drop-zone{gap:4px}.mini-brick{padding:8px 6px}} +@media(max-width:1000px){.hero{min-height:565px}.hero h1{font-size:84px}.hero-copy{width:44%}.hero-copy>p{font-size:20px}.hero-copy>p.hero-description{font-size:12px;max-width:270px}.hero-world{width:78%;right:-15px;top:32px;height:calc(100% - 35px)}.hero-note{margin-top:25px}.label-top{display:none}.world-caption{bottom:0;left:38%;right:35px;font-size:6px}.section-heading h2{font-size:38px}.section-heading>p{font-size:16px}.chapter-art{height:120px}.part-numeral{font-size:31px;left:15px}.chapter-world h3{font-size:23px}.playground{grid-template-columns:1fr;gap:27px;margin-block:60px}.playground-copy{display:grid;grid-template-columns:1fr 1fr;column-gap:40px}.playground-copy .section-label{grid-column:1/-1}.playground-copy h2{grid-row:2/4}.playground-copy>p{font-size:19px;margin-top:24px}.playground-copy>a{margin-top:0}.workbench{max-width:700px;width:100%;margin:auto}.toy-brick{width:120px}.composition-line{gap:15px}.page-outline{display:none}.reader-layout{display:block;max-width:800px;padding-inline:45px}.site-header nav{gap:22px}.site-header{gap:22px}.site-footer>span{display:none}.contents-grid{grid-template-columns:repeat(2,minmax(0,1fr))}} +@media(max-width:760px){.site-header{height:85px;width:calc(100% - 44px);gap:15px}.brand{gap:11px}.brand img{width:35px;height:35px}.brand>span{font-size:23px;letter-spacing:4px}.brand small{font-size:7px;letter-spacing:1.9px}.site-header nav{gap:20px;font-size:17px}.site-header nav a:first-child{display:none}.search-button{border:0;padding:10px;margin-left:0}.search-button span{display:none}.hero{min-height:780px;padding:42px 22px 24px;display:block;overflow:hidden}.hero-copy{width:100%;padding-left:0;pointer-events:auto}.hero h1{font-size:86px;margin-bottom:22px}.hero-copy>p{font-size:21px}.hero-copy>p.hero-description{font-size:12px;max-width:330px;margin-top:15px;line-height:1.8}.desktop-break{display:none}.hero-copy>p.hero-description .desktop-break{display:block}.hero .button{font-size:19px;padding:14px 22px;min-height:50px}.hero-note{display:none}.hero-world{left:0;top:auto;bottom:20px;right:0;width:100%;height:400px;z-index:2}.book-art-button{inset:0 -9%;width:118%;justify-content:center}.hero-art{width:100%}.world-caption{left:22px;right:22px;bottom:-4px;font-size:6px;letter-spacing:1px}.hotspot-one{top:24%;left:58%}.hotspot-two{top:57%;left:72%}.world-hotspot small{display:none}.chapters-section{width:calc(100% - 44px);padding-top:28px}.section-heading{display:block}.section-heading h2{font-size:38px;margin:16px 0}.section-heading>p{font-size:17px;margin-top:10px}.chapter-worlds{grid-template-columns:repeat(2,minmax(0,1fr));margin-top:28px;row-gap:32px}.chapter-world{padding:0 18px 12px}.chapter-world:nth-child(2){padding-right:0;border-right:0}.chapter-world:nth-child(3){padding-left:0}.chapter-world:nth-child(3) .part-numeral{left:0}.chapter-art{height:135px}.chapter-world h3{font-size:28px}.chapter-world p{font-size:11px}.part-numeral{font-size:33px}.chapter-link{font-size:15px;gap:10px}.chapter-link:before{width:16px}.chapter-link svg{width:15px}.contents-grid{grid-template-columns:1fr;gap:5px}.playground{width:calc(100% - 44px);margin:50px auto;gap:25px}.playground-copy{display:block}.playground-copy h2{font-size:45px;margin:19px 0}.playground-copy>p{font-size:18px;margin-top:14px}.workbench{padding:20px 15px}.workbench-head>span{font-size:8px}.block-palette{gap:18px;padding:12px 0 27px}.toy-brick{width:87px;height:76px}.studs{gap:18px}.studs b{width:18px;height:13px}.toy-brick strong{font-size:26px}.toy-brick small{font-size:8px}.composition-line{gap:6px}.composition-line>svg{width:13px}.composition-line input{width:43px}.output-value{min-width:35px;max-width:78px}.output-value output{font-size:26px}.drop-zone{padding:5px;min-height:70px}.drop-zone>span{font-size:8px}.mini-brick{font-size:14px;padding:7px}.mini-brick small{margin-left:4px}.experiment-code pre{font-size:8px}.experiment-code>span{font-size:6px}.site-footer{width:calc(100% - 44px);padding:30px 0;align-items:flex-start}.site-footer>div:nth-child(2){flex-direction:column;gap:13px;font-size:10px}.site-footer p{font-size:14px}.site-footer .brand>span{font-size:17px}.site-footer .brand img{width:28px;height:28px}.site-footer .brand small{font-size:6px}.book-sidebar{transform:translateX(-100%);width:280px;transition:transform .3s;z-index:60}.reader-shell{margin-left:0}.reader-shell:after{display:none}.reader-toolbar{height:65px;padding:0 15px;gap:5px}.mobile-menu{display:inline-flex;width:35px}.reader-breadcrumb{font-size:9px;margin-right:auto}.reader-tools{gap:0}.reader-tools .icon-button{width:32px}.reader-tools #bookmark{display:none}.reading-progress{left:0;top:64px}.reader-layout{padding:25px 25px 0}.prose h1{font-size:52px;line-height:1.02;margin:25px 0 29px}.prose h2{font-size:34px}.prose h3{font-size:27px}.prose{line-height:1.8}.page-ornament{font-size:7px;letter-spacing:1px;padding-bottom:14px}.page-meta{font-size:7px;margin-top:20px}.prose img.section-image{max-height:280px}.admonition{padding:14px 15px}.code-block pre{font-size:11px;padding:15px}.page-navigation{gap:13px;grid-template-columns:1fr 1fr;position:relative;padding-top:32px}.page-navigation a{font-size:17px;gap:10px}.page-navigation a:last-child{grid-column:2}.page-navigation .folio{position:absolute;right:0;top:10px;font-size:8px}.page-navigation small{font-size:6px}.page-navigation svg{width:19px}.menu-open{overflow:hidden}.menu-open .book-sidebar{transform:translateX(0)}.menu-open .sidebar-scrim{display:block;position:fixed;inset:0;background:#15292088;z-index:55;backdrop-filter:blur(3px)}#search-dialog{margin-top:5vh;max-height:85dvh}.search-top{padding:13px 15px;gap:10px}.search-footer{font-size:8px}.search-result strong{font-size:24px}.search-result p{font-size:10px}.search-result{padding:12px 9px}.search-top>svg{width:17px}.opening-cover,.opening-paper{width:240px;height:330px}} +@media(max-width:380px){.site-header nav a:nth-child(2){display:none}.site-header nav{margin-left:auto}.hero h1{font-size:78px}.hero{min-height:760px}.hero-world{height:365px;bottom:22px}.chapter-art{height:115px}.chapter-world h3{font-size:25px}.chapter-link{font-size:13px}.chapter-link:before{display:none}.reader-toolbar{padding-inline:10px}.reader-tools .icon-button{width:30px}.reader-breadcrumb{font-size:8px}.reader-layout{padding-inline:20px}} +.book-art-stage{display:block;width:100%;position:relative;line-height:0} +.explore-world{display:flex;align-items:center;gap:10px;width:fit-content;margin-top:17px;font:12px var(--serif);color:var(--copper)}.explore-world svg{width:14px;height:14px}.explore-world:hover{gap:15px} +.atlas-main{width:min(1320px,calc(100% - 112px));margin:45px auto 60px;outline:none}.atlas-heading{display:flex;gap:35px;align-items:end}.atlas-heading h1{font:500 70px/1 var(--serif);margin:17px 0 0}.atlas-heading>p{font:20px/1.4 var(--serif);color:var(--muted);margin:0 0 4px 20px}.atlas-list-link{display:flex;gap:10px;align-items:center;font:14px var(--serif);color:var(--copper);margin-left:auto;margin-bottom:10px}.atlas-list-link svg{width:16px}.atlas-experience{display:grid;grid-template-columns:minmax(0,1.8fr) minmax(280px,1fr);gap:50px;margin-top:24px}.atlas-map{height:570px;position:relative;perspective:1000px;isolation:isolate}.atlas-route{position:absolute;inset:0;width:100%;height:100%;fill:none;stroke:#c4ad87;stroke-width:1;stroke-dasharray:3 7;opacity:.6;pointer-events:none}.atlas-route ellipse{stroke-dasharray:none;stroke:#d9cfbb;stroke-width:.5}.atlas-node{position:absolute;background:none;width:200px;height:240px;padding:0;transform:rotateY(-7deg) scale(.9);transition:transform .65s cubic-bezier(.2,.8,.2,1),filter .5s,opacity .5s;opacity:.76;filter:saturate(.8)}.atlas-node img{width:100%;height:100%;object-fit:contain;pointer-events:none;mix-blend-mode:multiply}.atlas-node-number{font:32px var(--serif);color:var(--copper);position:absolute;top:18%;left:0}.atlas-node-title{font:600 20px/1.1 var(--serif);position:absolute;top:91%;left:-10px;right:-10px;text-align:center}.atlas-node-dot{position:absolute;width:7px;height:7px;background:var(--gold);border-radius:50%;bottom:-38px;left:calc(50% - 4px);box-shadow:0 0 0 4px #c39b5c15}.atlas-node.selected,.atlas-node:hover{opacity:1;filter:saturate(1);transform:rotateY(0) translateY(-10px) scale(1.07)}.atlas-node.selected .atlas-node-dot{box-shadow:0 0 0 8px #c39b5c16}.node-0{left:10%;top:2%}.node-1{right:2%;top:19%}.node-2{left:0;bottom:9%}.node-3{right:28%;bottom:0}.atlas-star{position:absolute;color:#b79965;pointer-events:none}.star-a{top:7%;right:17%;font-size:35px}.star-b{bottom:16%;left:37%;font-size:20px}.star-c{left:2%;top:39%;font-size:20px}.atlas-map-note{position:absolute;font:9px var(--mono);letter-spacing:1px;right:39%;top:40%;color:#a19174;transform:rotate(-10deg)}.atlas-navigation{position:absolute;bottom:-24px;left:15px;display:flex;align-items:center;gap:10px;color:var(--copper)}.atlas-navigation>span{font:9px var(--mono);color:var(--muted)}.atlas-detail{align-self:center;border-left:1px solid var(--line);padding:18px 0 18px 33px;min-height:420px}.atlas-part{font:9px var(--mono);letter-spacing:1.5px;color:var(--copper)}.atlas-detail h2{font-size:43px;line-height:1.02;margin:16px 0}.atlas-detail>p{font:14px/1.8 var(--serif);font-size:18px;color:var(--muted);margin:0 0 22px}.atlas-chapter-list{border-top:1px solid var(--line);margin-bottom:25px}.atlas-chapter-list a{display:flex;align-items:baseline;gap:12px;padding:11px 0;font:18px/1.2 var(--serif);border-bottom:1px solid #dcd4c570}.atlas-chapter-list a>span{font:8px var(--mono);color:var(--copper)}.atlas-chapter-list svg{width:13px;height:13px;margin-left:auto;align-self:center}.atlas-chapter-list a:hover{color:var(--copper);padding-left:6px}.atlas-detail .button{font-size:18px;padding:14px 18px;min-height:48px;gap:20px} +@media(max-width:1100px){.atlas-main{width:calc(100% - 72px)}.atlas-experience{gap:25px;grid-template-columns:1.5fr 1fr}.atlas-map{height:560px}.atlas-node{width:160px;height:220px}.atlas-node-title{font-size:18px}.node-3{right:22%;bottom:0}.atlas-detail{padding-left:22px}.atlas-heading h1{font-size:58px}.atlas-heading>p{font-size:17px;margin-left:0}.atlas-detail h2{font-size:37px}.atlas-detail>p{font-size:16px}} +@media(max-width:760px){.atlas-main{width:calc(100% - 44px);margin-top:30px}.atlas-heading{flex-wrap:wrap;gap:15px}.atlas-heading h1{font-size:48px}.atlas-heading>p{font-size:17px;margin:0}.atlas-list-link{font-size:12px;align-self:end;margin:0 0 3px auto;gap:5px}.atlas-experience{display:flex;flex-direction:column;gap:50px;margin-top:10px}.atlas-map{height:460px;width:100%;flex-shrink:0}.atlas-node{width:145px;height:180px}.atlas-node-title{font-size:17px}.node-0{left:5%;top:0}.node-1{right:-3%;top:22%}.node-2{left:-3%;bottom:12%}.node-3{right:8%;bottom:-1%}.atlas-map-note{font-size:6px;right:40%;top:43%}.star-a{font-size:24px;right:13%;top:1%}.atlas-detail{border-left:0;border-top:1px solid var(--line);padding:25px 0 0;min-height:0;align-self:stretch}.atlas-detail h2{font-size:43px;max-width:300px}.atlas-detail>p{font-size:18px}.atlas-chapter-list a{font-size:20px}.atlas-navigation{left:-10px;bottom:-30px}.atlas-route{transform:scale(1.1)}.atlas-node-dot{bottom:-27px}.atlas-node.selected{transform:translateY(-5px) scale(1.05)}.hero-world{margin-top:12px}} +.chapter-art{height:180px;background-size:contain;background-position:center} +.atlas-0{background-image:url('/art/world-0.webp')}.atlas-1{background-image:url('/art/world-1.webp')}.atlas-2{background-image:url('/art/world-2.webp')}.atlas-3{background-image:url('/art/world-3.webp')} +.prose img.section-image{max-height:155px;margin:18px auto 26px} +@media(max-width:760px){.hero{min-height:0;display:block;padding-top:38px;padding-bottom:28px;overflow:visible}.hero h1{font-size:74px;line-height:.95}.hero-copy>p.hero-description{max-width:320px;margin-bottom:23px}.hero-world{position:relative;inset:auto;width:calc(100% + 44px);height:260px;margin:24px -22px 0}.book-art-button{inset:0;width:100%;height:100%;justify-content:center}.hero-art{width:100%;mask-image:none}.world-caption{bottom:-3px}.chapter-art{height:165px}.hero-copy>p.hero-description .desktop-break{display:none}.reader-breadcrumb{max-width:145px;overflow:hidden;white-space:nowrap;text-overflow:ellipsis;display:block}.prose img.section-image{max-height:145px}.prose h1{font-size:48px}} +@media(max-width:380px){.hero h1{font-size:66px}.hero-world{height:240px}.chapter-art{height:150px}} +@media(prefers-reduced-motion:reduce){html{scroll-behavior:auto}*,*:before,*:after{animation:none!important;transition:none!important}.book-art-button{transform:none!important}::view-transition-group(root){animation:none!important}::view-transition-old(root),::view-transition-new(root){animation:none!important}} diff --git a/web/tests/book-integration.test.ts b/web/tests/book-integration.test.ts new file mode 100644 index 0000000..4db0a5e --- /dev/null +++ b/web/tests/book-integration.test.ts @@ -0,0 +1,197 @@ +import fs from 'node:fs/promises'; +import path from 'node:path'; +import test from 'node:test'; +import assert from 'node:assert/strict'; +import { parseHTML } from 'linkedom'; +import { parseMdBookExport } from '../scripts/mdbook-model.ts'; +import { chaptersOf, htmlPath, readerSlug } from '../scripts/book-model.ts'; +import type { ReaderBook } from '../src/book.ts'; +import { languages } from '../src/locale-routing.ts'; +import { resolveAnchor } from '../src/anchors.ts'; + +const web = path.resolve(import.meta.dirname, '..'); +const raw = parseMdBookExport( + JSON.parse( + await fs.readFile( + path.join(web, '.cache/mdbook/build/reader-json/book.json'), + 'utf8' + ) + ) as unknown +); +const reader = JSON.parse( + await fs.readFile(path.join(web, 'public/content.json'), 'utf8') +) as ReaderBook; +const markup = (html: string): Document => + parseHTML('
' + html + '
') + .document as unknown as Document; +const code = (document: Document): string[] => + [...document.querySelectorAll('pre code')].map((node) => + (node.textContent || '').replace(/\n$/, '') + ); +const math = (document: Document): string[] => + [ + ...document.querySelectorAll('annotation[encoding="application/x-tex"]') + ].map((node) => node.textContent || ''); + +test('real book hierarchy and ordering come from mdBook JSON, with no lost chapter', () => { + const chapters = chaptersOf(raw.book).filter((chapter) => chapter.path); + assert.equal(reader.pages.length, chapters.length); + assert.deepEqual( + reader.pages.map((page) => page.id), + chapters.map((chapter) => chapter.source_path || chapter.path) + ); + assert.deepEqual( + reader.pages.map((page) => page.slug), + chapters.map(readerSlug) + ); + assert.deepEqual( + reader.groups.map((group) => group.title), + raw.book.sections.flatMap((item) => + typeof item === 'object' && 'PartTitle' in item ? [item.PartTitle] : [] + ) + ); + assert.ok(reader.toc.some((node) => node.kind === 'separator')); + for (const page of reader.pages) + assert.ok( + page.children.every((id) => + reader.pages.some( + (child) => child.id === id && child.parentId === page.id + ) + ) + ); +}); + +test('canonical mdBook anchors, source code and every mathematical expression survive adaptation', async () => { + for (const chapter of chaptersOf(raw.book)) { + const nativePath = htmlPath(chapter); + if (!nativePath) continue; + const native = parseHTML( + await fs.readFile( + path.join(web, '.cache/mdbook/build/html', nativePath), + 'utf8' + ) + ).document as unknown as Document; + const page = reader.pages.find( + (candidate) => candidate.id === (chapter.source_path || chapter.path) + ); + assert.ok(page); + const presented = markup(page.html); + assert.deepEqual( + page.headings.map((heading) => heading.id), + [ + ...native.querySelectorAll( + 'main h1,main h2,main h3,main h4,main h5,main h6' + ) + ].map((heading) => heading.id), + page.slug + ' anchors' + ); + assert.deepEqual(code(presented), code(native), page.slug + ' code'); + assert.deepEqual(math(presented), math(native), page.slug + ' math'); + assert.equal(page.markdown, chapter.content); + } +}); + +test('rendered local chapter links and anchors resolve without source-file conventions', () => { + const bySlug = new Map( + reader.pages.map((page) => [page.slug, markup(page.html)]) + ); + for (const page of reader.pages) { + const document = bySlug.get(page.slug); + assert.ok(document); + for (const anchor of document.querySelectorAll( + 'a[href]' + )) { + const href = anchor.getAttribute('href') || ''; + if ( + !href || + /^(?:[a-z][a-z\d+.-]*:|\/\/)/i.test(href) || + href.startsWith('/book-assets/') + ) + continue; + const target = new URL(href, 'https://book.invalid/' + page.slug); + const slug = target.pathname.slice(1), + chapter = bySlug.get(slug); + assert.ok(chapter, `${page.slug}: ${href}`); + if (target.hash) { + const id = decodeURIComponent(target.hash.slice(1)); + assert.ok( + [...chapter.querySelectorAll('[id]')].some((node) => node.id === id), + `${page.slug}: missing ${href}` + ); + } + } + } +}); + +test('legacy deep links resolve to native headings through the same reader helper', () => { + let aliases = 0; + for (const page of reader.pages) + for (const [legacy, native] of Object.entries(page.anchorAliases ?? {})) { + aliases++; + assert.ok(page.headings.some((heading) => heading.id === native)); + assert.equal(resolveAnchor(page, encodeURIComponent(legacy)), native); + assert.equal(resolveAnchor(page, encodeURIComponent(native)), native); + } + assert.ok( + aliases > 0, + 'the existing catalog includes changed native punctuation rules' + ); +}); + +test('all approved translations retain identical identity, code, equations and source links', async () => { + assert.ok(reader.pages.length > 0); + for (const { code: language } of languages) { + const localized = JSON.parse( + await fs.readFile( + path.join(web, 'public/content', language + '.json'), + 'utf8' + ) + ) as ReaderBook; + assert.deepEqual( + localized.pages.map((page) => page.id), + reader.pages.map((page) => page.id) + ); + assert.ok( + !('translationManifest' in localized), + 'no runtime translation catalog' + ); + for (const [index, page] of localized.pages.entries()) { + const before = markup(reader.pages[index].html), + after = markup(page.html); + assert.deepEqual( + code(after), + code(before), + language + ' ' + page.slug + ' code' + ); + // Native word order can move inline tokens; their content and multiplicity remain exact. + assert.deepEqual( + math(after).sort(), + math(before).sort(), + language + ' ' + page.slug + ' math' + ); + assert.deepEqual( + [...after.querySelectorAll('a[href]')] + .map((a) => a.getAttribute('href')) + .sort(), + [...before.querySelectorAll('a[href]')] + .map((a) => a.getAttribute('href')) + .sort(), + language + ' ' + page.slug + ' links' + ); + assert.deepEqual( + page.headings.map((h) => h.id), + reader.pages[index].headings.map((h) => h.id) + ); + assert.equal(page.slug, reader.pages[index].slug); + assert.equal(page.source, reader.pages[index].source); + assert.equal(page.parentId, reader.pages[index].parentId); + assert.deepEqual(page.children, reader.pages[index].children); + assert.deepEqual(page.anchorAliases, reader.pages[index].anchorAliases); + assert.equal( + page.minutes, + reader.pages[index].minutes, + 'reading estimates stay edition-independent' + ); + } + } +}); diff --git a/web/tests/book-validation.test.ts b/web/tests/book-validation.test.ts new file mode 100644 index 0000000..c63b5c5 --- /dev/null +++ b/web/tests/book-validation.test.ts @@ -0,0 +1,76 @@ +import test from 'node:test'; +import assert from 'node:assert/strict'; +import { validateReaderEdition } from '../scripts/book-validation.ts'; +import type { ReaderBook } from '../src/book.ts'; +const book: ReaderBook = { + groups: [], + toc: [], + pages: [ + { + id: 'a.md', + source: 'a.md', + slug: 'a.html', + title: 'English', + group: 'Welcome', + hash: 'hash', + markdown: '# English', + html: '

English

xlink

let x = 1;
x^2', + text: 'English', + minutes: 1, + parentId: null, + children: [], + headings: [{ id: 'stable', level: 1, text: 'English' }] + } + ] +}; +test('editions can change prose but not protected code, formulae, links or canonical identity', () => { + const localized = structuredClone(book); + localized.pages[0]!.title = '中文'; + localized.pages[0]!.html = localized.pages[0]!.html.replaceAll( + 'English', + '中文' + ).replace('>link<', '>链接<'); + assert.doesNotThrow(() => validateReaderEdition(localized, book, 'zh')); + for (const [before, after] of [ + ['let x = 1;', 'let x = 2;'], + ['x^2', 'x^3'], + ['https://example.com/', 'https://other.example/'] + ]) { + const broken = structuredClone(localized); + broken.pages[0]!.html = broken.pages[0]!.html.replace(before!, after!); + assert.throws( + () => validateReaderEdition(broken, book, 'zh'), + /protected technical content/ + ); + } + const moved = structuredClone(localized); + moved.pages[0]!.slug = 'changed.html'; + assert.throws(() => validateReaderEdition(moved, book, 'zh'), /identity/); +}); + +test('media sources, responsive images, video posters and iframe titles are protected together', () => { + const canonical = structuredClone(book); + canonical.pages[0]!.html += + ''; + assert.doesNotThrow(() => + validateReaderEdition(structuredClone(canonical), canonical, 'zh') + ); + for (const original of [ + 'https://example.com/embed', + 'small.png', + 'Original clip', + 'poster.png', + 'movie.mp4', + 'recording.mp3', + 'large.png' + ]) { + const broken = structuredClone(canonical); + assert.ok(broken.pages[0]!.html.includes(original)); + broken.pages[0]!.html = broken.pages[0]!.html.replace(original, 'changed'); + assert.throws( + () => validateReaderEdition(broken, canonical, 'zh'), + /protected technical content/, + original + ); + } +}); diff --git a/web/tests/chapter-counts.test.ts b/web/tests/chapter-counts.test.ts new file mode 100644 index 0000000..1754d44 --- /dev/null +++ b/web/tests/chapter-counts.test.ts @@ -0,0 +1,20 @@ +import test from 'node:test'; +import assert from 'node:assert/strict'; +import {recordChapterCount,invalidateChapterCounts} from '../src/chapter-counts.ts'; +import type {ReaderPage} from '../src/book.ts'; +const edition=()=>[{id:'a.md'},{id:'b.md'},{id:'c.md'}] as ReaderPage[]; +test('global numbering is unavailable until every count was learned from that edition and exact layout',()=>{ + const pages=edition();assert.equal(recordChapterCount(pages,'layout',pages[1]!,4),null); + assert.equal(recordChapterCount(pages,'layout',pages[0]!,6),null); + assert.deepEqual(recordChapterCount(pages,'layout',pages[2]!,2),{offset:10,total:12}); + assert.deepEqual(recordChapterCount(pages,'layout',pages[1]!,5),{offset:6,total:13}); + assert.equal(recordChapterCount(pages,'other-size',pages[0]!,6),null); + const other=edition();assert.equal(recordChapterCount(other,'layout',other[0]!,6),null); +}); +test('font invalidation and bounded layout history cannot reuse stale counts',()=>{ + const pages=edition();for(const page of pages)recordChapterCount(pages,'old',page,2); + invalidateChapterCounts(pages);assert.equal(recordChapterCount(pages,'old',pages[0]!,2),null); + for(let i=0;i<9;i++)recordChapterCount(pages,'layout-'+i,pages[0]!,2); + assert.equal(recordChapterCount(pages,'layout-0',pages[1]!,2),null); + assert.throws(()=>recordChapterCount(pages,'x',pages[0]!,0),/Invalid/); +}); diff --git a/web/tests/content-loader.test.ts b/web/tests/content-loader.test.ts new file mode 100644 index 0000000..0d03527 --- /dev/null +++ b/web/tests/content-loader.test.ts @@ -0,0 +1,95 @@ +import test from 'node:test'; +import assert from 'node:assert/strict'; +import { createBookLoader } from '../src/content-loader.ts'; +import { parseReaderBook } from '../src/book-data.ts'; +const chapter = { + id: 'chapter.md', + title: 'Chapter', + source: 'chapter.md', + slug: 'chapter.html', + hash: 'source-hash', + group: 'Welcome', + markdown: '# Chapter', + html: '

Chapter

', + text: 'Chapter', + minutes: 1, + parentId: null, + children: [], + headings: [] +}; + +test('reader data fetches only the requested edition, coalesces requests, and retries failure', async () => { + const requested: string[] = []; + let unavailable = true; + const book = { pages: [chapter], groups: [], toc: [] }; + const load = createBookLoader((async (input) => { + requested.push(String(input)); + if (String(input).endsWith('ar.json') && unavailable) { + unavailable = false; + return new Response('', { status: 503 }); + } + return Response.json(book); + }) as typeof fetch); + const first = load('zh'); + assert.strictEqual(load('zh'), first); + assert.deepEqual(await first, book); + assert.deepEqual(requested, ['/content/zh.json']); + await assert.rejects(load('ar'), /unavailable/); + assert.deepEqual(await load('ar'), book); + assert.deepEqual(requested, [ + '/content/zh.json', + '/content/ar.json', + '/content/ar.json' + ]); + assert.strictEqual(load('zh'), first); +}); + +test('reader model boundary rejects malformed pages and broken references', () => { + assert.throws( + () => + parseReaderBook({ pages: [{ id: 'chapter.md' }], groups: [], toc: [] }), + /Invalid/ + ); + assert.throws( + () => parseReaderBook({ pages: [chapter, chapter], groups: [], toc: [] }), + /Duplicate/ + ); + assert.throws( + () => + parseReaderBook({ + pages: [chapter], + groups: [{ title: 'Part', pages: ['missing.html'] }], + toc: [] + }), + /membership/ + ); + assert.throws( + () => + parseReaderBook({ + pages: [{ ...chapter, parentId: 'missing.md' }], + groups: [], + toc: [] + }), + /hierarchy/ + ); + assert.throws( + () => + parseReaderBook({ + pages: [{ ...chapter, minutes: NaN }], + groups: [], + toc: [] + }), + /Invalid/ + ); +}); + +test('invalid or empty content fails visibly rather than caching an unusable edition', async () => { + let calls = 0; + const load = createBookLoader((async () => { + calls++; + return Response.json({ pages: [], groups: [], toc: [] }); + }) as typeof fetch); + await assert.rejects(load('en'), /Invalid/); + await assert.rejects(load('en'), /Invalid/); + assert.equal(calls, 2); +}); diff --git a/web/tests/locale-routing.test.ts b/web/tests/locale-routing.test.ts new file mode 100644 index 0000000..a171f69 --- /dev/null +++ b/web/tests/locale-routing.test.ts @@ -0,0 +1,63 @@ +import assert from 'node:assert/strict'; +import test from 'node:test'; +import {htmlLanguage,languagePath,languages,normalizeLanguage,pathLanguage,stripLanguage} from '../src/locale-routing.ts'; +import type {LanguageCode} from '../src/locale-routing.ts'; + +const languageCodes:LanguageCode[]=languages.map(language=>language.code); + +test('all supported languages resolve from explicit locale paths and retain the requested route',()=>{ + for(const code of languageCodes){ + const explicitPath='/'+code+'/parts/concepts.html'; + const canonicalPath=code==='en'?'/parts/concepts.html':explicitPath; + assert.equal(pathLanguage(explicitPath),code); + assert.equal(stripLanguage(explicitPath),'/parts/concepts.html'); + assert.equal(languagePath(explicitPath,code),canonicalPath); + } +}); + +test('locale aliases resolve to canonical language codes and canonical paths',()=>{ + const aliases:[string,LanguageCode,string][]=[ + ['zh-Hans','zh','/zh/contents.html'], + ['zh_CN','zh','/zh/contents.html'], + ['zh-CN','zh','/zh/contents.html'], + ['zh-SG','zh','/zh/contents.html'], + ['zh-TW','zh-hant','/zh-hant/contents.html'], + ['zh_HK','zh-hant','/zh-hant/contents.html'], + ['zh-MO','zh-hant','/zh-hant/contents.html'] + ]; + for(const [alias,canonical,expectedPath] of aliases){ + assert.equal(normalizeLanguage(alias),canonical); + const requestedPath=`/${alias}/contents.html`; + assert.equal(pathLanguage(requestedPath),canonical); + assert.equal(languagePath(requestedPath,canonical),expectedPath); + } +}); + +test('canonicalizing a localized URL preserves its query and chapter anchor',()=>{ + const origin='https://alux.example'; + const requested=new URL('/zh-CN/parts/concepts.html?from=search#composition',origin); + const language=pathLanguage(requested.pathname); + assert.ok(language); + const canonical=new URL(languagePath(requested.pathname,language)+requested.search+requested.hash,origin); + assert.equal(canonical.pathname,'/zh/parts/concepts.html'); + assert.equal(canonical.search,'?from=search'); + assert.equal(canonical.hash,'#composition'); +}); + +test('unlocalized paths stay intact, while locale prefixes are stripped with root slash semantics',()=>{ + assert.equal(pathLanguage('/'),null); + assert.equal(pathLanguage('/parts/concepts.html'),null); + assert.equal(stripLanguage('/parts/concepts.html'),'/parts/concepts.html'); + assert.equal(stripLanguage('/zh-hant/'),'/'); + assert.equal(stripLanguage('/zh/contents.html/'),'/contents.html/'); + assert.equal(languagePath('/zh/contents.html','en'),'/contents.html'); +}); + +test('language normalization and HTML language tags cover the full supported set',()=>{ + for(const code of languageCodes){ + assert.equal(normalizeLanguage(code.toUpperCase()),code); + assert.equal(htmlLanguage(code),code==='zh'?'zh-Hans':code==='zh-hant'?'zh-Hant':code); + } + assert.equal(normalizeLanguage('fr'),null); + assert.equal(normalizeLanguage(null),null); +}); diff --git a/web/tests/mdbook-protocol.test.ts b/web/tests/mdbook-protocol.test.ts new file mode 100644 index 0000000..fd5f9fc --- /dev/null +++ b/web/tests/mdbook-protocol.test.ts @@ -0,0 +1,12 @@ +import test from 'node:test'; +import assert from 'node:assert/strict'; +import {spawnSync} from 'node:child_process'; +import path from 'node:path'; + +test('localization support probes exit cleanly without reading stdin, including on Windows',()=>{ + const script=path.resolve(import.meta.dirname,'../scripts/mdbook-localization.ts'); + for(const [renderer,status] of [['html',0],['reader-json',0],['unknown-renderer',1]] as const){ + const result=spawnSync(process.execPath,[script,'supports',renderer],{encoding:'utf8',timeout:10000,windowsHide:true}); + assert.equal(result.error,undefined);assert.equal(result.status,status);assert.equal(result.stdout,'');assert.equal(result.stderr,''); + } +}); diff --git a/web/tests/mdbook.test.ts b/web/tests/mdbook.test.ts new file mode 100644 index 0000000..835599f --- /dev/null +++ b/web/tests/mdbook.test.ts @@ -0,0 +1,68 @@ +import test from 'node:test'; +import assert from 'node:assert/strict'; +import { parseMdBookExport } from '../scripts/mdbook-model.ts'; +import { transformBook } from '../scripts/book-model.ts'; +import type { MdBook, MdBookChapter } from '../scripts/mdbook-model.ts'; +import { presentChapter } from '../scripts/reader-presentation.ts'; +import { normalizeBookLineEndings } from '../scripts/mdbook-line-endings.ts'; +import { protectMathAnnotations } from '../scripts/mdbook-math-annotations.ts'; +import { parseHTML } from 'linkedom'; + +const chapter = (name: string, path: string, sub_items: {Chapter: MdBookChapter}[] = []): MdBookChapter => ({ name, content: '# ' + name, number: [1], path, source_path: path, parent_names: [], sub_items }); +const html = (content: string): string => '
' + content + '
'; + +test('Book JSON determines ordering, nested identity and parts without filesystem inference', () => { + const child = chapter('Child', 'deep/child.md'); + const parent = chapter('Parent', 'parent.md', [{Chapter:child}]); + const book: MdBook = { sections: [{ PartTitle: 'Part A' }, { Chapter: parent }, 'Separator', { PartTitle: 'Part B' }, { Chapter: chapter('Last', 'last.md') }] }; + const rendered = new Map([['parent.html',html('

Parent

')],['deep/child.html',html('

Child

')],['last.html',html('

Last

')]]); + const result = transformBook(book, rendered); + assert.deepEqual(result.pages.map(page => page.id), ['parent.md', 'deep/child.md', 'last.md']); + assert.equal(result.pages[1].parentId, 'parent.md'); + assert.deepEqual(result.pages[0].children, ['deep/child.md']); + assert.deepEqual(result.groups.map(group => group.pages), [['parent.html','deep/child.html'],['last.html']]); + assert.equal(result.toc[1].kind, 'chapter'); + assert.equal(result.pages[0].headings[0].id, 'canonical-parent'); +}); + +test('mdBook native heading IDs, links, code and math survive reader presentation', () => { + const source = html('

A heading?

target external x < y

fn main() { println!("a"); }\n

a^2+b^2=c^2rendered

'); + const result = presentChapter(source, 'nested/chapter.html', new Map([['target.html','target.html']])); + assert.equal(result.headings[0].id, 'native-punctuation'); + assert.match(result.html,/href="\/target.html#native-id"/); + assert.match(result.html,/https:\/\/example.com\/a.md/); + assert.match(result.html,/a\^2\+b\^2=c\^2/); + assert.match(result.html,/x < y/); + assert.doesNotMatch(result.html,/rust-playground/); +}); + +test('index route is an explicit compatibility alias and malformed Book JSON fails', () => { + const intro = chapter('Introduction','index.md'); + const result = transformBook({ sections:[{Chapter:intro}] },new Map([['index.html',html('

Introduction

')]])); + assert.equal(result.pages[0].slug,'introduction.html'); + assert.equal(result.pages[0].source,'index.md'); + assert.throws(()=>parseMdBookExport({version:'0.4.52',book:{sections:[{Chapter:{name:'bad'}}]}}),/Chapter.content/); + assert.throws(()=>transformBook({sections:[{Chapter:intro}]},new Map()),/Missing mdBook HTML/); +}); + +test('Windows line endings cannot leak into pre-rendered MathML while chapter identity stays intact',()=>{ + const original=chapter('Math','math.md');original.content='$$\r\nx\r\n=\r\ny\r\n$$\r\n'; + const normalized=normalizeBookLineEndings({sections:[{Chapter:original}]}); + const item=normalized.sections[0];assert.ok(typeof item==='object'&&'Chapter'in item); + assert.equal(item.Chapter.content,'$$\nx\n=\ny\n$$\n'); + assert.equal(item.Chapter.source_path,original.source_path); + assert.ok(original.content.includes('\r\n'),'input stays recoverable and untouched'); +}); + +test('TeX annotation escapes survive Markdown without changing rendered math or source code',()=>{ + const original=chapter('Math','math.md'); + const tex=String.raw`P\{y/x\} \mathrel{\#} Q \swarrow^{*} A_B`; + original.content=`P${tex}\n\n\`\`\`rust\nlet slash = "\\\\";\n\`\`\``; + const protectedBook=protectMathAnnotations({sections:[{Chapter:original}]}); + const item=protectedBook.sections[0];assert.ok(typeof item==='object'&&'Chapter'in item); + const {document}=parseHTML(''+item.Chapter.content+''); + assert.equal(document.querySelector('annotation')?.textContent,tex); + assert.match(item.Chapter.content,/P<\/mi><\/math>/); + assert.ok(item.Chapter.content.endsWith('```rust\nlet slash = "\\\\";\n```')); + assert.ok(original.content.includes(tex),'input remains untouched'); +}); diff --git a/web/tests/reader-surface.test.ts b/web/tests/reader-surface.test.ts new file mode 100644 index 0000000..f8e7a50 --- /dev/null +++ b/web/tests/reader-surface.test.ts @@ -0,0 +1,67 @@ +import test from 'node:test'; +import assert from 'node:assert/strict'; +import { parseHTML } from 'linkedom'; +import { copyBookSurface, ownedBookSurface } from '../src/reader-surface.ts'; + +const markup = (): Document => parseHTML('
First chapter
').document as unknown as Document; + +test('a delayed old reader cannot acquire or remove the new chapter surface', async () => { + const document = markup(); + const app = document.querySelector('#app')!; + const oldVolume = document.querySelector('.bound-volume')!; + let resume: (() => void) | undefined; + const imageReady = new Promise(resolve => { resume = resolve; }); + const obsoleteResize = imageReady.then(() => { + const surface = ownedBookSurface(oldVolume); + // A stale PageFlip instance would remove whichever element it acquired. + surface?.remove(); + return surface; + }); + app.innerHTML = '
Next chapter
'; + const newBook = document.querySelector('#page-book')!; + resume!(); + assert.equal(await obsoleteResize, null); + assert.ok(newBook.isConnected); + assert.equal(newBook.textContent, 'Next chapter'); +}); + +test('a connected reader reuses only the book inside its own volume', () => { + const document = markup(); + const volume = document.querySelector('.bound-volume')!; + const original = volume.querySelector('#page-book'); + assert.equal(ownedBookSurface(volume), original); +}); + +test('rebuilding a destroyed book creates its replacement in the same volume', () => { + const document = markup(); + const volume = document.querySelector('.bound-volume')!; + ownedBookSurface(volume)!.remove(); + const replacement = ownedBookSurface(volume); + assert.ok(replacement?.isConnected); + assert.equal(replacement.parentElement, volume); + assert.equal(volume.querySelectorAll('#page-book').length, 1); +}); + +test('a detached volume cannot create a new book', () => { + const document = markup(); + const volume = document.querySelector('.bound-volume')!; + volume.remove(); + assert.equal(ownedBookSurface(volume), null); + assert.equal(document.querySelector('#page-book'), null); +}); + +test('the first-frame backdrop has readable content without duplicate anchors or active players', () => { + const document = markup(); + const book = document.querySelector('#page-book')!; + book.innerHTML = '

Chapter text

'; + const copy = copyBookSurface(book); + assert.equal(copy.textContent, book.textContent); + assert.equal(copy.hasAttribute('id'), false); + assert.equal(copy.querySelectorAll('[id]').length, 0); + assert.equal(copy.querySelector('iframe')?.hasAttribute('src'), false); + assert.equal(copy.querySelector('iframe')?.hasAttribute('srcdoc'), false); + assert.equal(copy.getAttribute('aria-hidden'), 'true'); + assert.ok(copy.inert); + assert.equal(book.querySelector('h1')?.id, 'heading'); + assert.equal(book.querySelector('iframe')?.getAttribute('src'), 'https://example.com/player'); +}); diff --git a/web/tests/reading-art.test.ts b/web/tests/reading-art.test.ts new file mode 100644 index 0000000..083d428 --- /dev/null +++ b/web/tests/reading-art.test.ts @@ -0,0 +1,16 @@ +import assert from 'node:assert/strict'; +import test from 'node:test'; +import {parseHTML} from 'linkedom'; +import {presentChapter,readingArt} from '../scripts/reader-presentation.ts'; + +test('mapped illustrations reserve their intrinsic size before lazy loading',()=>{ + for(const [source,runtime] of Object.entries(readingArt)){ + const chapter=presentChapter(`

Chapter

Illustration

`,'chapter.html',new Map()); + const image=parseHTML(chapter.html).document.querySelector('img'); + assert.equal(image?.getAttribute('src'),runtime); + assert.equal(image?.getAttribute('width'),'512'); + assert.equal(image?.getAttribute('height'),'512'); + assert.equal(image?.getAttribute('loading'),'lazy'); + assert.equal(image?.getAttribute('alt'),'Illustration'); + } +}); diff --git a/web/tests/search.test.ts b/web/tests/search.test.ts new file mode 100644 index 0000000..1f638c9 --- /dev/null +++ b/web/tests/search.test.ts @@ -0,0 +1,21 @@ +import assert from 'node:assert/strict'; +import test from 'node:test'; +import {searchBook} from '../src/search.ts'; +import type {ReaderPage} from '../src/book.ts'; +const page=(title:string,text:string):ReaderPage=>({title,text} as ReaderPage); + +test('search retains title priority, all-term matching, stable ties and snippet offsets',()=>{ + const pages=[page('First','Rust type'),page('Rust','The type algebra'),page('Third','RUST type'),page('Other','Rust alone')]; + const hits=searchBook(pages,'RUST type'); + assert.deepEqual(hits.map(hit=>[hit.p.title,hit.score,hit.at]),[['Rust',16,-1],['First',2,0],['Third',2,0]]); + assert.deepEqual(searchBook(pages,'missing'),[]); +}); + +test('cached search indexes do not leak across localized book datasets',()=>{ + const english=[page('Meaning','A program')],chinese=[page('含义','程序')],arabic=[page('المعنى','برنامج')]; + assert.equal(searchBook(english,'program').length,1); + assert.equal(searchBook(chinese,'program').length,0); + assert.equal(searchBook(chinese,'程序')[0]?.p,chinese[0]); + assert.equal(searchBook(arabic,'برنامج')[0]?.p,arabic[0]); + assert.equal(searchBook(english,'含义').length,0); +}); diff --git a/web/tests/site-brand.test.ts b/web/tests/site-brand.test.ts new file mode 100644 index 0000000..e0d3fb4 --- /dev/null +++ b/web/tests/site-brand.test.ts @@ -0,0 +1,14 @@ +import assert from 'node:assert/strict'; +import test from 'node:test'; +import {languages} from '../src/locale-routing.ts'; +import {siteBrandName,brandedPageTitle} from '../src/site-meta.ts'; + +test('site identity uses Chinese for Chinese editions and English for other languages',()=>{ + for(const {code}of languages){ + const name=code==='zh'?'ALUX 编程':code==='zh-hant'?'ALUX 程式設計':'ALUX Programming'; + assert.equal(siteBrandName(code),name); + assert.equal(brandedPageTitle('',code),name); + assert.equal(brandedPageTitle('章节 · ALUX Programming',code),'章节 · '+name); + assert.equal(brandedPageTitle('章节 · '+name,code),'章节 · '+name); + } +}); diff --git a/web/tests/source-localization.test.ts b/web/tests/source-localization.test.ts new file mode 100644 index 0000000..9195abd --- /dev/null +++ b/web/tests/source-localization.test.ts @@ -0,0 +1,116 @@ +import fs from 'node:fs/promises'; +import os from 'node:os'; +import path from 'node:path'; +import test from 'node:test'; +import assert from 'node:assert/strict'; +import { + localizeSources, + sourceMetadata, + sourceFingerprint, + translatedSourcePath +} from '../scripts/source-localization.ts'; +import type { MdBook, MdBookChapter } from '../scripts/mdbook-model.ts'; + +const chapter = (source = 'chapter.md'): MdBookChapter => ({ + name: 'Canonical title', + content: '# Original {#stable}\n\nEnglish body', + path: source, + source_path: source, + number: [1], + parent_names: [], + sub_items: [] +}); + +test('English edits warn about stale translations without blocking or acknowledging them',async t=>{ + const directory=await fs.mkdtemp(path.join(os.tmpdir(),'alux-freshness-'));t.after(()=>fs.rm(directory,{recursive:true,force:true})); + const original=chapter(),input:MdBook={sections:[{Chapter:original}]},warnings:string[]=[]; + const translation='\n\n# 中文 {#stable}'; + const filename=path.join(directory,'chapter.zh.md');await fs.writeFile(filename,translation); + await localizeSources(input,directory,'zh',warning=>warnings.push(warning));assert.equal(warnings.length,0); + original.content+='\n\nNew English paragraph'; + const localized=await localizeSources(input,directory,'zh',warning=>warnings.push(warning));assert.equal(warnings.length,1);assert.match(warnings[0]!,/zh chapter.md.*may be stale/); + assert.equal(await fs.readFile(filename,'utf8'),translation,'builds never acknowledge the warning by modifying sources'); + const item=localized.sections[0];assert.ok(typeof item==='object'&&'Chapter'in item);assert.ok(item.Chapter.content.includes('中文')); + assert.equal(sourceFingerprint('a\r\nb\r\n'),sourceFingerprint('a\nb\n'),'line endings do not create false freshness warnings'); +}); + +test('source-level translations keep canonical identity and hierarchy with English fallback', async (t) => { + const directory = await fs.mkdtemp( + path.join(os.tmpdir(), 'alux-source-locales-') + ); + t.after(() => fs.rm(directory, { recursive: true, force: true })); + const original = chapter('index.md'), + child = chapter('child.md'); + original.sub_items = [{ Chapter: child }]; + const input: MdBook = { + sections: [{ PartTitle: 'Part One' }, { Chapter: original }, 'Separator'] + }; + await fs.writeFile( + path.join(directory, 'index.zh.md'), + '\n\n# 中文标题 {#stable}\n\n译文正文' + ); + const localized = await localizeSources(input, directory, 'zh'); + assert.deepEqual(localized.sections[0], { PartTitle: '第一部分' }); + const parent = localized.sections[1]; + assert.ok(typeof parent === 'object' && 'Chapter' in parent); + assert.equal(parent.Chapter.name, '导言'); + assert.equal(parent.Chapter.path, 'index.md'); + assert.equal(parent.Chapter.source_path, 'index.md'); + assert.deepEqual(parent.Chapter.number, [1]); + assert.ok(parent.Chapter.content.includes('译文正文')); + assert.deepEqual(parent.Chapter.sub_items, [{ Chapter: child }]); + assert.equal(localized.sections[2], 'Separator'); + assert.equal(original.content, '# Original {#stable}\n\nEnglish body'); + assert.equal(original.name, 'Canonical title'); +}); + +test('a new Markdown translation needs no manifest and only its selected locale changes', async (t) => { + const directory = await fs.mkdtemp( + path.join(os.tmpdir(), 'alux-source-edit-') + ); + t.after(() => fs.rm(directory, { recursive: true, force: true })); + const input: MdBook = { sections: [{ Chapter: chapter() }] }; + await fs.writeFile( + path.join(directory, 'chapter.zh.md'), + '# 第一个标题 {#stable}\n\n第一版' + ); + const before = await localizeSources(input, directory, 'zh'); + assert.deepEqual(await localizeSources(input, directory, 'de'), input); + assert.strictEqual(await localizeSources(input, directory, 'en'), input); + await fs.writeFile( + path.join(directory, 'chapter.zh.md'), + '# 第一个标题 {#stable}\n\n第二版' + ); + const after = await localizeSources(input, directory, 'zh'); + assert.notDeepEqual(after, before); + assert.deepEqual(await localizeSources(input, directory, 'de'), input); + const item = after.sections[0]; + assert.ok(typeof item === 'object' && 'Chapter' in item); + assert.equal(item.Chapter.name, '第一个标题'); + assert.equal(item.Chapter.path, 'chapter.md'); +}); + +test('invalid source metadata and escaping source paths fail rather than corrupting the book', async () => { + assert.throws(() => sourceMetadata(''), /title/); + assert.throws( + () => sourceMetadata(''), + /part/ + ); + assert.throws( + () => sourceMetadata(''), + /Unknown/ + ); + assert.equal( + translatedSourcePath('nested/chapter.md', 'zh-hant'), + 'nested/chapter.zh-hant.md' + ); + assert.throws(() => translatedSourcePath('chapter.html', 'zh'), /Markdown/); + await assert.rejects( + localizeSources( + { sections: [{ Chapter: chapter('../escape.md') }] }, + os.tmpdir(), + 'zh' + ), + /escapes/ + ); +}); diff --git a/web/tsconfig.json b/web/tsconfig.json new file mode 100644 index 0000000..a7bda4b --- /dev/null +++ b/web/tsconfig.json @@ -0,0 +1,20 @@ +{ + "compilerOptions": { + "target": "ES2023", + "lib": ["ES2023", "DOM", "DOM.Iterable"], + "module": "ESNext", + "moduleResolution": "Bundler", + "allowImportingTsExtensions": true, + "resolveJsonModule": true, + "verbatimModuleSyntax": true, + "isolatedModules": true, + "erasableSyntaxOnly": true, + "strict": true, + "jsx": "preserve", + "jsxImportSource": "solid-js", + "noEmit": true, + "skipLibCheck": true, + "types": ["node", "vite/client"] + }, + "include": ["src/**/*.ts", "src/**/*.tsx", "scripts/**/*.ts", "tests/**/*.ts", "vite.config.ts"] +} diff --git a/web/vite.config.ts b/web/vite.config.ts new file mode 100644 index 0000000..bb8fb88 --- /dev/null +++ b/web/vite.config.ts @@ -0,0 +1,70 @@ +import path from 'node:path'; +import { defineConfig } from 'vite'; +import { buildReaderBook } from './scripts/book.ts'; +import solid from 'vite-plugin-solid'; +import { languages } from './src/locale-routing.ts'; +import type { LanguageCode } from './src/locale-routing.ts'; + +export default defineConfig({ + server: { host: '127.0.0.1', port: 4173 }, + preview: { host: '127.0.0.1', port: 4174 }, + plugins: [ + solid(), + { + name: 'mdbook-content', + configureServer(server) { + const root = path.resolve(import.meta.dirname, '..'); + const sources = path.join(root, 'src'); + server.watcher.add([sources, path.join(root, 'book.toml')]); + let timer: ReturnType | undefined; + let queued = Promise.resolve(); + const pending = new Set(); + let rebuildAll = false; + const rebuild = (file: string): void => { + const changed = path.resolve(file); + if (!( + changed.startsWith(sources + path.sep) || + changed === path.join(root, 'book.toml') + )) + return; + const locale = languages.find( + (language) => + language.code !== 'en' && + changed.endsWith('.' + language.code + '.md') + )?.code; + if (locale) pending.add(locale); + else rebuildAll = true; + clearTimeout(timer); + timer = setTimeout(() => { + const selected = rebuildAll ? undefined : [...pending]; + pending.clear(); + rebuildAll = false; + queued = queued.then(async () => { + try { + await buildReaderBook(selected); + server.ws.send({ type: 'full-reload' }); + } catch (error) { + server.config.logger.error( + error instanceof Error + ? error.stack || error.message + : String(error) + ); + } + }); + }, 100); + }; + server.watcher + .on('change', rebuild) + .on('add', rebuild) + .on('unlink', rebuild); + server.httpServer?.once('close', () => { + clearTimeout(timer); + server.watcher + .off('change', rebuild) + .off('add', rebuild) + .off('unlink', rebuild); + }); + } + } + ] +}); diff --git a/web/worlds.css b/web/worlds.css new file mode 100644 index 0000000..d61a14d --- /dev/null +++ b/web/worlds.css @@ -0,0 +1,137 @@ +.visually-hidden{position:absolute;width:1px;height:1px;overflow:hidden;clip-path:inset(50%);white-space:nowrap} +body.gateway-view{background:#f5f1e8;color:#203b33;margin:0} +.world-gateway{min-height:100svh;display:grid;place-items:center;isolation:isolate;overflow:hidden;position:relative;background:radial-gradient(ellipse at 22% 59%,#f5dab04a,transparent 36%),radial-gradient(ellipse at 79% 59%,#c8dce34a,transparent 36%),#f5f1e8} +.world-gateway:before{content:"";position:absolute;inset:0;z-index:-1;background:url('/art/paper.webp') center/700px;opacity:.1;pointer-events:none} +.gateway-composition{--wizard-size:min(83svh,850px,60vw);width:min(1500px,96vw);display:grid;grid-template-columns:1fr var(--wizard-size) 1fr;align-items:center;gap:0;position:relative} +.gateway-wizard{width:var(--wizard-size);position:relative;pointer-events:none;mask-image:linear-gradient(#000 0 82%,transparent 100%)} +.gateway-wizard img{width:100%;height:auto;display:block} +.world-choice{display:flex;flex-direction:column;align-items:center;text-align:center;text-decoration:none!important;position:relative;z-index:1;gap:20px;padding:24px 12px;transform:translateY(calc(var(--wizard-size)*.03));color:#774c26;white-space:nowrap;font-family:'Noto Serif SC','Songti SC','SimSun',serif;transition:color .25s,transform .3s} +.world-choice strong{font-size:clamp(26px,2.65vw,42px);font-weight:500;letter-spacing:.13em;line-height:1.6} +.choice-magic{justify-self:end}.choice-real{justify-self:start;color:#2e4f66} +.choice-symbol{font-family:Georgia,serif;font-size:31px;line-height:1.2;color:#a7793e} +.choice-real .choice-symbol{color:#6b8194;font-size:26px} +.choice-enter{font-size:17px;letter-spacing:.15em;display:flex;gap:18px;align-items:center;border-top:1px solid #ad89565e;padding-top:16px;color:#79532b} +.choice-real .choice-enter{color:#567080;border-color:#7a91a362} +.world-choice:before{content:"";position:absolute;width:240px;height:240px;inset:50% auto auto 50%;transform:translate(-50%,-50%);background:radial-gradient(#dba85233,transparent 68%);opacity:0;z-index:-1;transition:opacity .35s;pointer-events:none} +.choice-real:before{background:radial-gradient(#7ab6d033,transparent 68%)} +.world-choice:hover:before,.world-choice:focus-visible:before{opacity:1}.world-choice:hover{transform:translateY(calc(var(--wizard-size)*.03 - 5px))} +.world-choice:focus-visible{outline:2px solid currentColor;outline-offset:8px}.world-choice:active{transform:translateY(calc(var(--wizard-size)*.03 + 1px))} +.realm-switch{font:14px/1.4 var(--sans);color:inherit;text-decoration:none;white-space:nowrap;display:inline-flex;align-items:center;gap:8px} +.language-picker{display:inline-flex;align-items:center;gap:6px;font:14px/1.4 var(--sans);white-space:nowrap;color:inherit}.language-picker svg{width:17px;height:17px}.language-picker select{font:inherit;background:transparent;color:inherit;border:0;border-bottom:1px solid #8c89784d;max-width:120px;padding:8px 3px;cursor:pointer}.language-picker option{background:#fff;color:#242424} +.world-gateway>.language-picker{position:absolute;top:26px;right:4vw;z-index:4;color:#52635b}.gateway-view[data-language=en] .world-choice{font-family:var(--serif)} +html[lang=en] .world-choice{font-family:var(--serif)}html[lang=en] .world-choice strong{font-size:clamp(30px,3.1vw,49px);letter-spacing:.015em}html[lang=en] .choice-enter{font-size:20px;letter-spacing:.03em} +.bound-toolbar{display:grid;grid-template-columns:minmax(0,1fr) auto;grid-template-rows:auto auto;gap:6px 20px;padding:12px 20px} +.bound-toolbar>.crafted-brand{grid-column:1;grid-row:1}.bound-toolbar>.bound-location{grid-column:1;grid-row:2;margin:0;gap:3px}.bound-toolbar>.bound-tools{grid-column:2;grid-row:2;margin:0;justify-content:flex-end}.bound-world-nav{grid-column:2;grid-row:1;display:flex;align-items:center;justify-content:flex-end;gap:24px}.bound-world-nav .language-picker{font-size:13px}.bound-world-nav .realm-switch{margin:0}.bound-world-nav .realm-switch svg{width:14px;height:14px}.bound-tools{gap:6px}.bound-location>a{font-size:21px}.bound-toolbar .bound-mode{font-size:17px} +@media(min-width:1280px){body:not(.contents-collapsed) .bound-toolbar>.bound-location{grid-row:1/3}.bound-toolbar{height:125px}.bound-volume{height:calc(100svh - 220px)}} +@media(max-width:1279px){.bound-toolbar>.bound-location{display:none}.bound-toolbar>.bound-tools{grid-column:1/-1;justify-content:center}.bound-toolbar{height:145px}.bound-world-nav{gap:14px}.bound-world-nav .language-picker select{max-width:88px}} +@media(max-width:760px){.bound-toolbar>.crafted-brand .brand-letters{display:none}.bound-toolbar>.crafted-brand{--mark-size:44px!important}.bound-toolbar{padding:8px 10px;column-gap:8px}.bound-world-nav{gap:11px}.bound-world-nav .realm-switch{font-size:12px}.bound-world-nav .language-picker{font-size:12px;gap:3px}.bound-world-nav .language-picker svg{display:none}.bound-world-nav .language-picker select{max-width:82px;padding-inline:0}.bound-tools .contents-toggle{font-size:17px;padding:9px 10px}.real-toolbar .language-picker{font-size:12px;gap:2px}.real-toolbar .language-picker svg{display:none}.real-toolbar .language-picker select{max-width:82px}.real-toolbar .real-font{display:none}.site-header>.language-picker{margin-left:0}.world-gateway>.language-picker{top:18px}.world-choice strong{white-space:normal}} +html[lang=zh] .folio-content,html[lang=ja] .folio-content{font-family:'Noto Serif SC','Songti SC','SimSun',serif;font-size:calc(var(--reading-size)*.86);line-height:1.9}html[lang=ko] .folio-content{font-family:'Malgun Gothic',sans-serif;font-size:calc(var(--reading-size)*.8);line-height:1.8} +html[dir=rtl] .folio-content{direction:rtl;text-align:right;font-family:'Noto Naskh Arabic','Traditional Arabic',serif}html[dir=rtl] :is(pre,code,.code-toolbar,.katex,.folio-running-head){direction:ltr;text-align:left;unicode-bidi:isolate}html[dir=rtl] .gateway-composition{direction:ltr}html[dir=rtl] .world-choice{direction:rtl}html[dir=rtl] .real-sidebar{left:auto;right:0;border-left:1px solid var(--real-line);border-right:0}html[dir=rtl] .real-body{margin-left:0;margin-right:290px}html[dir=rtl] .real-sidebar-hidden .real-body{margin-right:0}html[dir=rtl] .real-prose{text-align:right;font-family:Arial,'Tahoma',sans-serif}html[dir=rtl] .real-prose th,html[dir=rtl] .real-prose td{text-align:right}html[dir=rtl] .real-theme-menu>div{left:auto;right:0} +@media(max-width:1200px){html[dir=rtl] .real-body{margin-right:270px}}@media(max-width:1000px){html[dir=rtl] .real-body{margin-right:0}}@media(max-width:900px){html[lang=en] .world-choice strong{font-size:30px}html[lang=en] .choice-enter{font-size:18px}.gateway-composition{padding-top:50px}} +@media(max-width:760px){.site-header{display:grid;grid-template-columns:minmax(0,1fr) 34px auto;gap:10px}.site-header nav{display:none}.site-header>.language-picker{justify-self:end}.site-header>.language-picker svg{display:none}.site-header>.language-picker select{max-width:86px}.site-header .search-button{padding:0;width:34px}.real-toolbar{flex-wrap:wrap;height:auto;min-height:64px;padding-block:5px}.real-toolbar-right{margin-inline-start:auto;flex-wrap:wrap;justify-content:flex-end}.real-toolbar .real-choose-world{font-size:12px}} +@media(max-width:360px){.bound-toolbar>.crafted-brand{display:none}.bound-world-nav{grid-column:1/-1;justify-content:space-between}.bound-tools{gap:1px}.bound-tools .icon-button{width:29px;min-width:29px;height:34px;font-size:13px}.bound-tools .icon-button svg{width:17px}.bound-tools .contents-toggle{font-size:15px;padding:8px}.bound-toolbar .bound-mode{font-size:14px;padding-left:7px;margin-left:2px}.site-header .crafted-brand{--mark-size:38px;--brand-title:28px;--brand-caption:12px;--title-track:3px;--caption-track:.7px;gap:7px}.site-header{grid-template-columns:minmax(0,1fr) 28px auto;gap:6px}} +html[dir=rtl] .folio-content{font-size:calc(var(--reading-size)*1.22);line-height:1.8}html[dir=rtl] .real-main{font-size:calc(var(--real-size)*1.16)}html[dir=rtl] .real-sidebar{font-size:16px;line-height:1.8}html[dir=rtl] .book-sidebar nav a{font-family:Tahoma,Arial,sans-serif;font-size:16px;line-height:1.7}html[dir=rtl] :is(.admonition-title,.section-label,.brand-subtitle,.sidebar-group h2){letter-spacing:0!important}html[dir=rtl] .bound-controls #folio-position{direction:ltr;unicode-bidi:isolate}html[dir=rtl] .real-prose .admonition{border-left:1px solid var(--real-line);border-right:4px solid var(--real-link)} +.worlds-nav{font-family:var(--sans);font-size:14px} +@media(min-width:1600px){.gateway-composition{width:88vw;max-width:1800px;--wizard-size:min(84svh,1080px,62vw)}.world-choice strong{font-size:46px}} +@media(max-width:900px){.gateway-composition{--wizard-size:min(92vw,65svh,560px);width:100%;grid-template-columns:1fr 1fr;grid-template-rows:auto auto;padding:28px 24px 48px;gap:0 24px}.gateway-wizard{grid-column:1/-1;grid-row:1;justify-self:center}.world-choice{grid-row:2;transform:none;padding:4px 8px 12px;gap:10px;justify-self:center}.world-choice strong{font-size:29px}.choice-symbol{font-size:25px}.choice-real .choice-symbol{font-size:22px}.choice-enter{font-size:14px;padding-top:11px;gap:10px}.world-choice:hover,.world-choice:active{transform:none}.world-gateway{background:radial-gradient(ellipse at 25% 70%,#f5dab04a,transparent 40%),radial-gradient(ellipse at 75% 70%,#c8dce34a,transparent 40%),#f5f1e8}} +@media(max-width:600px){.bound-toolbar .realm-switch{font-size:13px}.gateway-composition{column-gap:12px}.world-choice strong{font-size:26px;letter-spacing:.08em}} +@media(prefers-reduced-motion:reduce){.world-choice,.world-choice:before{transition:none}} +html[data-transition=world]::view-transition-old(root){animation:world-fade-out .22s ease both}html[data-transition=world]::view-transition-new(root){animation:world-fade-in .32s ease both;mix-blend-mode:normal}@keyframes world-fade-out{to{opacity:0}}@keyframes world-fade-in{from{opacity:0}to{opacity:1}} +.bound-reading:not(.night) .page-book{background:#f3e5c6 url('/art/paper.webp') center/700px}.bound-reading.night .page-book{background:#292b24} +/* Balanced entrance: label and arrow share one centered axis. */ +.world-choice{justify-self:center;width:100%;max-width:320px;gap:22px} +.choice-enter{width:100%;justify-content:center;border:0;position:relative;padding-top:23px} +.choice-enter:before{content:'';position:absolute;width:92px;height:1px;left:50%;top:0;transform:translateX(-50%);background:currentColor;opacity:.35} +.world-gateway>.language-picker{font-size:18px;gap:10px;min-height:48px;padding:4px 12px;background:#f5f1e8b8;border:1px solid #b9ae9545;border-radius:3px} +.world-gateway>.language-picker svg{width:21px;height:21px} +.world-gateway>.language-picker select{max-width:160px;min-height:42px;padding:8px 10px;border:0} +/* Fixed rows prevent sidebar controls from changing the book's vertical position. */ +.bound-toolbar{grid-template-rows:44px 44px;align-content:center;row-gap:7px;min-height:119px} +.bound-toolbar>.crafted-brand{--mark-size:40px!important;--brand-title:26px;--brand-caption:10px;--title-track:4px;--caption-track:1px;gap:10px;max-height:44px} +.bound-toolbar>.crafted-brand .brand-seal{width:40px!important;height:40px!important} +.bound-toolbar .bound-tools{height:44px;align-items:center} +.bound-toolbar .bound-location{align-self:center} +.bound-toolbar .bound-location>span{font-size:12px;line-height:1.5} +.binding-ribbon{left:50%!important;right:auto!important;bottom:-17px!important;top:auto!important;transform:translateX(-50%);width:16px!important;height:48px!important;background:linear-gradient(90deg,#734d2e,#ab8050 38%,#92653a 77%,#674327)!important;box-shadow:1px 3px 3px #251a1640;clip-path:polygon(0 0,100% 0,100% 100%,50% 85%,0 100%);border:0!important;z-index:10} +.my-bookmarks{display:flex;align-items:center;gap:9px;width:100%;background:transparent;color:inherit;padding:12px 0;font:16px/1.4 var(--sans);text-align:start;cursor:pointer} +.my-bookmarks svg{width:18px;height:18px}.my-bookmarks small{margin-inline-start:auto;font-size:12px;opacity:.65} +.real-sidebar .my-bookmarks{font:14px/1.5 Arial,sans-serif;padding:12px 0 20px} +#bookmarks-dialog{width:min(650px,calc(100vw - 32px));max-height:80svh;padding:24px;background:#f5f0e4;color:#304038;border:1px solid #b0a184;border-radius:5px} +#bookmarks-dialog::backdrop{background:#15261e88;backdrop-filter:blur(3px)} +.bookmarks-heading{display:flex;align-items:center;justify-content:space-between;gap:16px;border-bottom:1px solid #aaa18b66;padding-bottom:12px}.bookmarks-heading h2{margin:0;font:32px/1.3 var(--serif)} +.saved-chapter{display:flex;align-items:center;border-bottom:1px solid #aaa18b55;gap:12px}.saved-chapter>a{flex:1;display:flex;flex-direction:column;gap:6px;padding:20px 0;color:inherit;text-decoration:none}.saved-chapter small{font:12px/1.4 var(--sans);opacity:.7}.saved-chapter strong{font:26px/1.3 var(--serif)}.saved-chapter a>span{font:14px/1.4 var(--sans);display:flex;align-items:center;gap:8px}.saved-chapter svg{width:18px}.bookmarks-empty{padding:30px 0;font:16px/1.8 var(--sans)} +html[lang|=zh] .folio-content{font-family:'Noto Serif SC','Songti SC','SimSun',serif;font-size:calc(var(--reading-size)*.86);line-height:1.9} +/* Night applies to the complete reading environment, including navigation. */ +body.bound-reading.night{--ink:#ded7c5;--text:#d4cdbc;--muted:#a4ad9f;--copper:#d5b87e;--line:#a89a6b44;--page-tone:#222b25;background:#161e19;color:#d4cdbc;color-scheme:dark} +.bound-reading.night .bound-reader{background:#1b241e} +.bound-reading.night .book-sidebar{background:#161f1b!important;color:#c9cebf!important;border-color:#57634c!important;--ink:#d6d8c8;--muted:#a8b29f;--text:#c9cebf;--copper:#c4ad7b} +.bound-reading.night .book-sidebar :is(a,h2,.sidebar-bottom){color:inherit} +.bound-reading.night .book-sidebar .sidebar-group h2{color:#bca77a} +.bound-reading.night .book-sidebar .active{background:#a9b48b15!important;color:#ead8aa!important;border-color:#b79e62} +.bound-reading.night .sidebar-search{background:#ffffff06!important;border-color:#7e8b694d;color:#c9cebf} +.bound-reading.night .crafted-brand .brand-seal-day{display:none!important}.bound-reading.night .crafted-brand .brand-seal-night{display:block!important} +.bound-reading.night .crafted-brand .brand-name,.bound-reading.night .crafted-brand .brand-subtitle{color:#dbd3ba!important} +.bound-reading.night .folio-page{background-color:#222b25;background-image:linear-gradient(#202922f5,#202922f5),url('/art/paper.webp');color:#d4cdbc} +.bound-reading.night .folio-page :is(h1,h2,h3,h4){color:#e0d9c6} +.bound-reading.night .folio-page .admonition{background:#8c9b6620;border-color:#b6a67d44} +.bound-reading.night .folio-page :is(.code-block,pre){background:#141e19} +.bound-reading.night :is(.folio-running-head,.folio-footer){color:#b8a77d} +.bound-reading.night .page-book{background:#222b25} +.bound-reading.night .contents-toggle{background:#48513c;color:#e2dbc7;border-color:#9d956544} +.bound-reading.night :is(.sheet-control,.folio-chapter-end,.folio-closing){color:#d2b883} +.bound-reading.night :is(#search-dialog,#bookmarks-dialog){background:#202a23;color:#ded7c5;border-color:#66705a} +.bound-reading.night .language-picker option{background:#202a23;color:#ded7c5} +body.real-theme-coal :is(#search-dialog,#bookmarks-dialog){background:#292c2f;color:#eee;border-color:#53565a} +body.real-theme-coal .language-picker option{background:#292c2f;color:#eee} +@media(max-width:760px){.world-gateway>.language-picker{font-size:16px;top:16px;right:20px;padding:0 8px}.world-choice{gap:12px;max-width:220px}.choice-enter{padding-top:18px;gap:10px}.bound-toolbar{min-height:119px}.bound-tools #bookmark{display:flex}.bound-tools{gap:1px}.bound-tools .icon-button{width:30px;min-width:30px}.real-toolbar-left{gap:0}.real-toolbar .real-tool{width:31px}.bookmarks-heading h2{font-size:27px}.saved-chapter strong{font-size:22px}} +@media(max-width:360px){.bound-toolbar>.crafted-brand{display:none}.bound-tools .icon-button{width:26px;min-width:26px}.bound-tools .contents-toggle{font-size:14px;padding:8px 5px}.bound-toolbar .bound-mode{font-size:13px;padding-inline-start:4px}.bound-toolbar .language-picker{font-size:12px}} +.bound-reading .book-sidebar nav a{font-size:var(--sidebar-size,18px)!important;line-height:1.55} +.bound-reading .book-sidebar .sidebar-group h2{font-size:calc(var(--sidebar-size,18px)*.7);line-height:1.5} +.bound-reading .book-sidebar .my-bookmarks,.bound-reading .book-sidebar .sidebar-search{font-size:calc(var(--sidebar-size,18px)*.84)} +html[dir=rtl] .real-sidebar{font-size:calc(var(--sidebar-size,18px)*1.05)} +.world-choice{font-family:var(--serif)}.world-choice strong{white-space:normal;line-height:1.35;text-wrap:balance} +html[lang|=zh] .world-choice,html[lang=ja] .world-choice{font-family:'Noto Serif SC','Songti SC','SimSun',serif} +html[lang=ko] .world-choice{font-family:'Malgun Gothic',sans-serif} +html[lang=ar] .world-choice{font-family:'Noto Naskh Arabic','Traditional Arabic',serif} +.bound-world-nav .language-picker{font-size:16px;gap:8px;min-height:44px}.bound-world-nav .language-picker svg{width:20px;height:20px}.bound-world-nav .language-picker select{padding:8px;max-width:155px;min-height:44px}.bound-world-nav .realm-switch{font-size:16px} +.bound-reading.night .folio-page :is(h1,h2,h3,h4){color:#d0d0be}.bound-reading.night{--text:#c7c9bb}.bound-reading.night .folio-page{color:#c7c9bb}.bound-reading.night .folio-running-head,.bound-reading.night .folio-footer{color:#b0a079} +@media(max-width:760px){.bound-world-nav .language-picker{font-size:14px;gap:4px}.bound-world-nav .language-picker select{max-width:132px;padding-inline:5px}.bound-world-nav .realm-switch{font-size:14px}} +.folio-content :is(h1,h2,h3,h4){text-wrap:balance;overflow-wrap:anywhere}.folio-content p{orphans:3;widows:3} +html[lang|=zh] .folio-content,html[lang=ja] .folio-content{line-break:strict;word-break:normal;overflow-wrap:break-word} +html[lang=ko] .folio-content{word-break:keep-all;overflow-wrap:break-word} +.folio-content img[src$="capability-crab.webp"]{max-height:140px!important;width:140px;object-fit:contain} +@media(max-width:760px){.folio-content img[src$="capability-crab.webp"]{max-height:110px!important;width:110px}} +.binding-ribbon{width:24px!important;height:65px!important;background:transparent url('/art/book-ribbon.webp') center bottom/85px auto no-repeat!important;clip-path:none!important;box-shadow:none!important;filter:drop-shadow(1px 2px 1px #24180f45)} +.bound-toolbar{position:sticky;top:0;background:#efe4c9f5;backdrop-filter:blur(8px)}.bound-reading.night .bound-toolbar{background:#1b241ef5} +/* On phones, give the reading-mode label its own row instead of squeezing tools. */ +@media(max-width:760px){ + .bound-toolbar{height:164px;min-height:164px;grid-template-rows:44px 80px;row-gap:7px;padding:8px 10px} + .bound-toolbar>.bound-tools{display:grid;grid-template-columns:minmax(0,1fr) repeat(4,32px);grid-template-rows:44px 32px;gap:4px;justify-content:stretch;height:80px;min-width:0;width:100%} + .bound-tools .contents-toggle{width:100%;min-width:0;justify-content:center;padding:7px 6px;font-size:16px;height:44px;gap:6px} + .bound-tools .contents-toggle span{white-space:normal;line-height:1.1} + .bound-tools .icon-button{width:32px;min-width:32px;height:44px} + .bound-tools #smaller-text{display:none}.bound-tools #bookmark{display:flex} + .bound-tools .bound-mode{grid-column:1/-1;grid-row:2;justify-self:end;border:0;margin:0;padding:4px 2px;font-size:16px;line-height:1.4;height:32px} + .bound-volume{height:calc(100svh - 255px)} + .sheet-control span{max-width:80px;font-size:16px;overflow-wrap:anywhere;text-wrap:balance} +} +.continuous-prose :is(h1,h2,h3,h4){scroll-margin-top:150px} +html[dir=rtl] :is(.sheet-control,.folio-chapter-end,.real-pagination) svg{transform:scaleX(-1)} +.night .folio-content .section-image{filter:brightness(.85) saturate(.9)} +@media(max-width:760px){ + .bound-toolbar{grid-template-rows:44px 92px} + .bound-toolbar>.bound-tools{grid-template-columns:minmax(0,1fr) repeat(3,44px);grid-template-rows:44px 44px;height:92px} + .bound-tools .contents-toggle{grid-row:1;grid-column:1} + .bound-tools [data-search]{grid-row:1;grid-column:2} + .bound-tools #toggle-night{grid-row:1;grid-column:3} + .bound-tools #bookmark{grid-row:1;grid-column:4} + .bound-tools #smaller-text{display:flex;grid-row:2;grid-column:3} + .bound-tools #larger-text{grid-row:2;grid-column:4} + .bound-tools .icon-button{width:44px;min-width:44px} + .bound-tools .bound-mode{grid-row:2;grid-column:1/3;justify-self:start;max-width:100%;white-space:normal;text-align:start;text-wrap:balance;height:44px} +} +@media(max-width:360px){.bound-tools .contents-toggle svg{display:none}.bound-tools .contents-toggle{font-size:15px}} +.folio-content .code-block pre{font-size:calc(var(--reading-size)*.7)} +@media(max-width:760px){.folio-content .code-block pre{font-size:calc(var(--reading-size)*.65)}} +.choice-enter-label{position:relative;display:inline-block;max-width:calc(100% - 32px);white-space:normal;line-height:1.4} +.choice-enter-arrow{position:absolute;inset-inline-start:calc(100% + 12px);top:0;line-height:inherit}