docs: clarify that singleton variants need () to be a value (#22) - #79
Merged
Merged
Conversation
A singleton variant name like `Score.ZeroZero` is the variant *type* (a `DataType`), not an instance. Users must call `Score.ZeroZero()` to get a value of `Score.Type`. This tripped up a user (#22) with two confusing errors: a failed `convert` when building a typed `Vector`, and a `no method matching +(::Type{...}, ...)` when dispatching. The docs only mentioned this in one terse sentence and repeatedly compared singletons to `Base.@enum`, which plants the wrong mental model (with `@enum` the bare name *is* the value). - data/syntax.mdx: rewrite the Singleton Variant section with a caution Aside, a REPL check, and both errors from #22 as WRONG/RIGHT examples - start/algebra-data-type.mdx: add a caution next to the `@enum` analogy - start/getting-started.md: note singletons need `()` where first introduced Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #79 +/- ##
=======================================
Coverage 91.41% 91.41%
=======================================
Files 42 42
Lines 1607 1607
=======================================
Hits 1469 1469
Misses 138 138 ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
Contributor
Benchmark Results (Julia v1)Time benchmarks
Memory benchmarks
|
PR #78 moved the benchmark comparison files from `benchmark/` into `benchmark/comparison/`, but `benchmark.mdx` still referenced the old `../benchmark/*.jl` paths. `RawCode` reads these at build time, so the docs build crashed with `ENOENT: ../benchmark/expronicon.jl` while rendering the benchmark page. Point all 7 RawCode paths at `../benchmark/comparison/`. `astro build` now completes (22 pages, 0 errors). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Roger-luo
added a commit
that referenced
this pull request
Jul 12, 2026
This branch is based on main, which still points the benchmark page's RawCode components at the old `../benchmark/*.jl` paths. PR #78 moved those files into `../benchmark/comparison/`, so the docs build (and the Vercel preview) crashes with `ENOENT: ../benchmark/expronicon.jl`. Point all 7 paths at `../benchmark/comparison/`. `astro build` now completes (22 pages, 0 errors). Same fix as #79; both converge to identical content. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Roger-luo
added a commit
that referenced
this pull request
Jul 12, 2026
…are form (#80) * feat(data): require explicit () for singleton variants; deprecate bare form Singleton variants were written as a bare identifier (`Quit`), which reinforced the false expectation that `Score.ZeroZero` is a *value*. It is not — it is the variant *type*; the value is `Score.ZeroZero()`. This tripped up users (#22) with confusing `convert`/dispatch MethodErrors. Julia has singleton *types* (an immutable no-field struct has one egal instance, `Base.issingletontype` == true), but the type and its instance are always distinct objects — there is no way to make a bare name be both a type and its value the way a Rust enum variant is. Moshi needs the variant name to stay a type (for dispatch/reflection/pattern matching), so the honest fix is to make the *syntax* explicit rather than to fake a value binding. Changes: - `@data` now accepts the explicit `Name()` singleton form (previously rejected with "missing fields") and treats it as the canonical spelling. - The bare `Name` form still parses to a Singleton but emits a `Base.depwarn(...; force=true)` at macro-expansion time. - Internal `Pattern` ADT (`Wildcard`) and all test/doc `@data` blocks migrated to the explicit `()` form so Moshi no longer uses its own deprecated syntax. - Docs updated to teach `Name()` and explain the type-vs-value point. - Added tests for the explicit form and the bare-form deprecation (guarded to skip under `--depwarn=error`, which escalates to a throw). Non-breaking (deprecation only): bumps 0.3.9 -> 0.3.10. Refs #22 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * docs: fix benchmark RawCode paths so Vercel build passes This branch is based on main, which still points the benchmark page's RawCode components at the old `../benchmark/*.jl` paths. PR #78 moved those files into `../benchmark/comparison/`, so the docs build (and the Vercel preview) crashes with `ENOENT: ../benchmark/expronicon.jl`. Point all 7 paths at `../benchmark/comparison/`. `astro build` now completes (22 pages, 0 errors). Same fix as #79; both converge to identical content. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * chore: revert manual version bump; let release-please handle it The repo uses release-please (release-type: julia), which bumps Project.toml + CHANGELOG.md from Conventional Commits on push to main. Manually bumping to 0.3.10 conflicts with the manifest (still 0.3.9), so revert to 0.3.9 and let the `feat:` commit drive the bump automatically. Also de-hardcode the version in the singleton deprecation note, since the exact release number is chosen by release-please. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * docs(agents): note release-please owns versioning; never hand-bump Records the lesson from this PR: manually bumping Project.toml in a feature PR fights release-please and, once that version is released, causes merge conflicts against main. Documents that release-please owns Project.toml/CHANGELOG.md/manifest and derives the bump from commit types. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This branch was successfully deployed
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
1 participant
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.
Summary
Fixes the documentation gap behind #22. A user hit two confusing
MethodErrors and the root cause is that a singleton variant name likeScore.ZeroZerois the variant type (aDataType), not a value — you must callScore.ZeroZero()to get an instance ofScore.Type.The existing docs mentioned this in only one terse sentence, and repeatedly compared
@datasingletons toBase.@enum, which plants the wrong mental model (with@enum, the bare name is the value).Changes
data/syntax.mdx(canonical reference): rewrote the Singleton Variant section withcautionAside — "A singleton name is a type, not a value" — plus a REPL check (Score.ZeroZero isa Score.Type→falsevsScore.ZeroZero()→true)Vectorconvertfailure and the+dispatch failure)@matchpatterns and clarifying when the bare type name is what you want (reflection)start/algebra-data-type.mdx: added acautionright after the "@datais like@enum" Aside — the spot where the wrong model formsstart/getting-started.md: short note where singletons are first introducedVerification
isa Score.Type, equality of constructed singletons) by running the current package.npx astro build: all MDX modules compile successfully. (The unrelateddata/benchmarkbuild error is pre-existing — that page'sRawCodereads../benchmark/*.jlfiles only generated by thegendocstep, whichbuild:fullruns first.)#singleton-variant,#default-pattern,/data/reflection) resolve.Closes #22
🤖 Generated with Claude Code