Repository navigation
Adds an explanation of why the language is its own - #242
Merged
Merged
Conversation
A new explanation page, docs/explanation/why-a-predicate-language-of- its-own.md, sets out who writes a rule and who executes it, the alternatives turned down (rules in code, evaluating the text as Elixir, a tree walker calling host functions by name, a rule format of the application's own), what the language buys, why it compiles to instructions, and what it costs. Examples are in the library loan. The page is an extra in the Explanation group and ships in the package files; the README's Documentation map links it under Understand. No library code changes. Refs: px-wwd7
Codecov Report✅ All modified and coverable lines are covered by tests. 🚀 New features to boost your workflow:
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Adds an explanation page, "Why a predicate language of its own", and wires it into hexdocs and the README.
What changes
docs/explanation/why-a-predicate-language-of-its-own.md(new): who writes a rule and who executes it, the alternatives turned down (every rule written in code; evaluating the text as Elixir; a tree walker that calls host functions by name; a rule format of the application's own), what a language of its own buys, why it compiles to instructions rather than walking a tree, and what it costs. Examples are set in the library loan (renewals, holds, overdue copies). The page has no numbered steps, no instructions and no code blocks, so nothing on it needs executing to read it.mix.exs: the page is an extra, sits in the existing Explanation group after the architecture page, and is listed inpackage.files(the README links it relatively).README.md: one line under Understand in the Documentation map.No file under
lib/changes. No changelog fragment:changelog.d/README.mdexcludes documentation.Source material
The page started from the README's "Why a predicate language of its own" paragraph and was written out from the package's own records: the no-
evaldecision record (ADR-0004) for the threat model and the turned-down implementations, ADR-0001 for the compile-versus-tree-walker trade, ADR-0017 for the rule-format alternative, and the architecture page's design decisions. The docs audit's per-file next actions name no record for this subject.The README's Why paragraph stays where it is: the README layout requires a Why section (the README check reports
no_whywithout one), so the page deepens the paragraph rather than replacing it. No README text is replaced.Claims checked against the library at this branch: a missing value returns an
UndefinedVariableError; an unregistered function name returns an "Unknown function" error value; a raising host function is rescued into an error value (the evaluator's function dispatch);renewals < 3 AND NOT on_holdwith renewals at 3 returns false without readingon_hold.Checks
mix quality) green:mix.exsis a build path, so the docs-only exemption did not apply. Doc links: 54 links checked, 0 findings; Docs: no warnings.mix docs --warnings-as-errorsclean; the rendered page sits in the Explanation sidebar group and its relative links resolve to the rendered architecture, custom functions, embedding, simple subset and language pages.README.md: 113 lines, every part present.Provenance
The title is the bead's as given; an explanation title needs no "How to" prefix.