From: Javier Sagredo Date: Thu, 18 Jun 2026 22:54:03 +0000 (+0200) Subject: README: fix stale claims, drop fluff X-Git-Url: https://git.sagredo.dev/?a=commitdiff_plain;h=0a892cdc9d4e7c81b30b5c96769c4f05c39c6fc8;p=classgraph.git README: fix stale claims, drop fluff - Drop the invented '★ top mark' — leaf classes only get a gold border (matching the viewer legend); reword to 'leaf', laid out at the top. - Data-family constructors/field names ARE shown now: say so in the family view + extraction notes, and remove the stale 'no data-family RHS bodies' limitation. - Update the demo HTML size (~780 KB -> ~840 KB, typecore.js now embedded) and drop 'ready to be explored'. - Bump the example unit-ids 0.1.0.0 -> 0.2.1.0 and note the helper reads the id from the store as well as dist-newstyle. Co-Authored-By: Claude Opus 4.8 (1M context) --- diff --git a/README.md b/README.md index b39149c..3930793 100644 --- a/README.md +++ b/README.md @@ -42,9 +42,8 @@ When you point the plugin at a target package and run the viewer, you get: - An interactive **classes view**: every `class` in the program as a node, edges drawn for direct superclasses, with an extra dashed edge whenever the superclass is mediated by a type family - (`class Pretty (Norm a) => Foo a`-style). Top-level classes (those no - other class extends) get a gold border and a `★ top` mark, and are - rendered as the topmost classes. + (`class Pretty (Norm a) => Foo a`-style). Leaf classes — those no + other class extends — get a gold border and are laid out at the top. - An **instance view** per class, drilled into by double-clicking. Shows every instance of that class, the constraints in each instance's context, the superclass requirements (and the matching superclass @@ -54,9 +53,10 @@ When you point the plugin at a target package and run the viewer, you get: *focused-instance → family → concrete fam-instance → satisfying class-instance*. - A **family view** per type or data family. Shows every `type instance` - / `data instance` of that family. Open, closed, associated, and data - families are all distinguished — with `(data)` appended to the label - for data families. + / `data instance` of that family — including the data constructors and + field names of each `data instance`. Open, closed, associated, and data + families are distinguished, with `(data)` appended to the label for data + families. - Backwards navigation via the side panel: every class lists its *superclasses* and its *subclasses* (i.e. the classes that extend it in this program). Click any name to navigate. @@ -89,8 +89,8 @@ cabal run classgraph-view -- \ xdg-open classgraph-demo.html # or `open` on macOS ``` -That should produce a single HTML file ~780 KB containing 16 classes, -32 instances, 6 families, and 11 family instances, ready to be explored. +That produces a single self-contained HTML file (~840 KB) with 16 classes, +32 instances, 6 families, and 11 family instances. ## Using the plugin in your own project @@ -135,7 +135,7 @@ Concretely, in `cabal.project.local` of your target: ``` package my-app ghc-options: - -fplugin-library=/abs/path/to/libHSclassgraph-0.1.0.0-inplace-ghc9.14.1.so;classgraph-0.1.0.0-inplace;Classgraph.Plugin;"[\"dir=.classgraph\"]" + -fplugin-library=/abs/path/to/libHSclassgraph-0.2.1.0-inplace-ghc9.14.1.so;classgraph-0.2.1.0-inplace;Classgraph.Plugin;"[\"dir=.classgraph\"]" ``` Note: the args portion is wrapped in `"..."` and the inner quotes are @@ -204,9 +204,9 @@ For an `inplace` (local-checkout cabal-build) the path is `ghc-9.14.1` only loads in `ghc-9.14.1`. Mixing minor versions can silently fail or crash. - **Cabal hashes the unit-id.** A non-`inplace` install ends up with - `classgraph-0.1.0.0-1234abcd…`. The helper script always reads the - current id from `dist-newstyle/`. If you want a stable id for - scripting, add `ghc-options: -this-unit-id classgraph` to the plugin + `classgraph-0.2.1.0-1234abcd…`. The helper script always reads the + current id from the store / `dist-newstyle/`. If you want a stable id + for scripting, add `ghc-options: -this-unit-id classgraph` to the plugin library's stanza in `classgraph.cabal` and rebuild. - **The plugin must be built against the same RTS as the compiler.** Don't link the plugin library statically with the RTS — leave it @@ -492,9 +492,9 @@ Notable extraction details: filtered with `isFamilyTyCon`, plus the assoc families discovered via each class's `classATs`. Closed-family branches are recovered from the `CoAxiom Branched`. Data family instances are detected via - `fi_flavor`'s `DataFamilyInst`; the synthetic `R:…` data-constructor - TyCon on the RHS is hidden from rendering since it isn't usefully - inspectable. + `fi_flavor`'s `DataFamilyInst`; the synthetic `R:…` representation TyCon + on the RHS is hidden, but the `data instance`'s own constructors and + field names are extracted and shown. - Type-arg rendering uses `splitVisibleFunTy_maybe` for arrows and filters invisible kind binders via `tyConBinders` + `isInvisibleTyConBinder`. Without this, function and kind-poly @@ -527,13 +527,9 @@ Notable extraction details: node. Extract that package too and the chain will keep going. - **Pretty-printing is best-effort.** Anything that survives the structural converter (`Type` shapes we don't recognise) falls back to - GHC's `Outputable`, which is much friendlier than it used to be after - the `prettyCtx` overrides but isn't perfect. If you find a label that - reads like internal compiler noise, file an issue with a `repro.hs`. -- **No support for data-family RHS bodies.** We record that a - `data instance` exists and what types it's specialised to, but not - the constructors / field names. Adding that is mostly a Schema + - Render exercise if you need it. + GHC's `Outputable`. The `prettyCtx` overrides tidy this up but it isn't + perfect; if you find a label that reads like internal compiler noise, + file an issue with a `repro.hs`. ## Building from source