carve-lang 0.1.4 → 0.1.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 8f7b8390c9d7d5e50b0f5272a47fad61194cfdb9f62a231a8087676aaa13feb5
4
- data.tar.gz: b5dad730b6e6c6b7244cdd4b8080b4d23927f2c323055b0240c603e3c6230c6f
3
+ metadata.gz: 7fa1a68f65aa5ecd3b0ca6554071fa31a2db0b9f57789a65ee5e2f3d8af8b77f
4
+ data.tar.gz: 2d9cec2f07553546dcecaac2f603db42b559512dafa0d183e5a5c297561b4e25
5
5
  SHA512:
6
- metadata.gz: f746efa34e732f4b0a855d60b61db5c8d13f767d4beeb4d0ec7d0a736daac5164b6c74941a30cba9472437e67734ed2d98d7837eac5a6ef4c7279169cc0b17e7
7
- data.tar.gz: 587da609dfce7bab98b8333aba463ec784f5da814ec80b9624ed61c622e92c903586abeb33e3af3f33c2d387753a755cecaa82d3d9620b378b3533a337b900ad
6
+ metadata.gz: bd2a0359ee4083b50daf8da92144cdcb02f72a3edc7d67b79d52b3e37ced9a73443b229170e7758e610db406bee5065a3e9c449da4494601c963b087c44e4b06
7
+ data.tar.gz: 81355dccbf314c449d49fc64ffc41344d193ad28c51e1707249e7128b1dae2689cbef4f553460e2e20a0bf8afca42cdf52849709753a84dab55e8d8f20397743
data/CHANGELOG.md CHANGED
@@ -7,6 +7,44 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
7
7
 
8
8
  ## [Unreleased]
9
9
 
10
+ ## [0.1.6] - 2026-09-29
11
+
12
+ ### Changed
13
+
14
+ - The engine is the published `carve-lang` 0.1.7 crate, up from 0.1.6. It closes
15
+ every row `resources/spec-drift.txt` declared: the gem renders all 2134 corpus
16
+ documents spec main declares byte-identically, where 0.1.6 rendered 158 of them
17
+ by a superseded rule. The ledger is empty again, which is the only state a tag
18
+ may ship (#151).
19
+ - **Breaking for a `Carve.parse` consumer:** a footnote reference node spells its
20
+ target as `label`, where it spelled it `id`. PART 12 section 25 settles that
21
+ name on the definition, and every node also carries `attrs[:id]` for an
22
+ authored `{#x}`, so the old name stood for two unrelated values on one object.
23
+ `attrs[:id]` is untouched (markup-carve/carve-rs#1853).
24
+ - **Breaking for a `Carve.parse` consumer:** a code block's `content` is the literal
25
+ payload text, so `a`, `a\n` and `a\n\n` stay distinct in the tree where they
26
+ collapsed to one shape, and an empty fence holds no newline. Rendered HTML is
27
+ unchanged (markup-carve/carve-rs#2191, markup-carve/carve-rs#2195).
28
+ - `Carve.parse` publishes twelve further fields the tree gained: a fenced
29
+ blockquote, a loose definition list, a directive's kind and children, a line
30
+ block's attributes, an authored task state, a lone-image paragraph, a table's
31
+ columns and row groups, and a cell's colspan, rowspan and vertical alignment.
32
+ - **Breaking for a `Carve.to_markdown` consumer:** the Markdown target follows
33
+ PART 11 section 11 for a GFM reader. A heading takes no `{#id}` suffix, and a
34
+ resolved cross-reference is written with the heading's GFM slug, so
35
+ `lowercase_heading_ids` no longer changes that anchor - the slug is the one a
36
+ GFM reader computes for itself. `Carve.to_html` still answers to the option
37
+ (markup-carve/carve-rs#2014).
38
+
39
+ ## [0.1.5] - 2026-09-21
40
+
41
+ ### Changed
42
+
43
+ - The engine comes from the published `carve-lang` 0.1.6 crate on crates.io
44
+ instead of a carve-rs git revision. `gem install carve-lang` no longer
45
+ fetches from GitHub while it compiles the extension. The engine code is the
46
+ same carve-rs 0.1.6 the previous release pinned by revision (#136).
47
+
10
48
  ## [0.1.4] - 2026-09-19
11
49
 
12
50
  ### Added
@@ -278,7 +316,7 @@ are not listed, because no release ever shipped them.
278
316
  Frontmatter and footnote definitions are block nodes in `children` rather
279
317
  than root fields, which PART 12 §7 requires: a root field cannot carry the
280
318
  position §4 requires of every node, and both are source an editor navigates
281
- to (carve#411, carve#418). Frontmatter is the first child, carrying `format`
319
+ to (markup-carve/carve#411, markup-carve/carve#418). Frontmatter is the first child, carrying `format`
282
320
  and **raw** `content` - not parsed key/values, which could not represent a
283
321
  `---toml` block at all. Anything reading `ast[:frontmatter]` or
284
322
  `ast[:footnoteDefs]` breaks.
@@ -287,9 +325,9 @@ are not listed, because no release ever shipped them.
287
325
  backslash escape is `{"type":"escaped_text","value":"-"}` instead of being
288
326
  folded into surrounding text - the backslash carries intent the character does
289
327
  not, since an author writes `\-\-` precisely so a consumer will not render an
290
- en dash (carve#350). A `::: |` fence is `line_block` instead of a `div` with a
328
+ en dash (markup-carve/carve#350). A `::: |` fence is `line_block` instead of a `div` with a
291
329
  `.line-block` class, because inside it every newline is a hard break and a
292
- class alone could not say which one a node was (carve#359). A block
330
+ class alone could not say which one a node was (markup-carve/carve#359). A block
293
331
  extension's `summary` is a list of inline nodes rather than a plain string,
294
332
  matching the admonition `title` shape. Definition lists publish
295
333
  `definition_term` and `definition_description` nodes
@@ -363,7 +401,9 @@ are not listed, because no release ever shipped them.
363
401
  Arrays (every AST node type is covered), enabling custom renderers such as
364
402
  [carve-hexapdf](https://github.com/markup-carve/carve-hexapdf).
365
403
 
366
- [Unreleased]: https://github.com/markup-carve/carve-rb/compare/v0.1.4...HEAD
404
+ [Unreleased]: https://github.com/markup-carve/carve-rb/compare/v0.1.6...HEAD
405
+ [0.1.6]: https://github.com/markup-carve/carve-rb/compare/v0.1.5...v0.1.6
406
+ [0.1.5]: https://github.com/markup-carve/carve-rb/compare/v0.1.4...v0.1.5
367
407
  [0.1.4]: https://github.com/markup-carve/carve-rb/compare/v0.1.3...v0.1.4
368
408
  [0.1.3]: https://github.com/markup-carve/carve-rb/compare/v0.1.2...v0.1.3
369
409
  [0.1.2]: https://github.com/markup-carve/carve-rb/compare/v0.1.1...v0.1.2
data/README.md CHANGED
@@ -1,387 +1,87 @@
1
1
  # carve (Ruby)
2
2
 
3
- Native Ruby bindings for the [Carve](https://github.com/markup-carve/carve)
4
- markup language. This gem is a thin native extension built with
5
- [magnus](https://github.com/matsadler/magnus) + [rb-sys](https://github.com/oxidize-rb/rb-sys)
6
- over the [carve-rs](https://github.com/markup-carve/carve-rs) engine. The parser
7
- is not reimplemented in Ruby; it calls into the Rust crate directly, mirroring
8
- how Djot's `djotter` gem wraps the `jotdown` crate.
3
+ Native Ruby bindings for the
4
+ [Carve](https://github.com/markup-carve/carve) markup language. The gem wraps
5
+ the [carve-rs](https://github.com/markup-carve/carve-rs) engine through magnus
6
+ and rb-sys rather than reimplementing the parser.
9
7
 
10
8
  ## Install
11
9
 
12
10
  ```ruby
13
- # Gemfile
14
11
  gem "carve-lang"
15
12
  ```
16
13
 
17
- ```sh
14
+ ```bash
18
15
  bundle install
19
16
  ```
20
17
 
21
- Or install directly:
18
+ The distribution name is `carve-lang`, while the require path is `carve`.
19
+ Building from source requires Rust 1.75 or newer and Ruby development headers.
22
20
 
23
- ```sh
24
- gem install carve-lang
25
- ```
26
-
27
- Then `require "carve"` as normal - the gem distribution name is `carve-lang`
28
- but the require path stays `carve`.
29
-
30
- Building from source requires a **Rust toolchain** (`cargo`, Rust >= 1.75) and
31
- Ruby development headers. RubyGems compiles the native extension at install
32
- time via `rb_sys`.
33
-
34
- ## Usage
21
+ ## Render Carve
35
22
 
36
23
  ```ruby
37
24
  require "carve"
38
25
 
39
26
  Carve.to_html("# Hello *world*")
40
- # => "<section id=\"Hello-world\">\n <h1>Hello <strong>world</strong></h1>\n</section>"
41
-
42
- # Every core engine target is available from the binding.
43
27
  Carve.to_markdown(source)
44
28
  Carve.to_plain_text(source)
45
29
  Carve.to_ansi(source)
46
30
  Carve.to_carve(source)
47
- # Import reports use schema version 2, with fidelity and confidence per finding.
48
- # Markdown emits fidelity-unverified/dropped/fallback until its engine path
49
- # exposes construct-level fidelity.
50
- Carve.from_html('<p>Hello <strong>world</strong></p>')
51
- Carve.from_markdown('*em* and **strong**')
52
-
53
- # Carve syntax note: *...* is STRONG (bold), /.../ is EMPHASIS (italic).
54
- Carve.to_html("*bold* and /italic/")
55
-
56
- # Enable opt-in extensions (Symbols or Strings, snake_case or hyphenated):
57
- Carve.to_html(<<~CRV, extensions: [:math_block])
58
- ```math
59
- a^2 + b^2 = c^2
60
- ```
61
- CRV
62
-
63
- Carve.to_html(src, extensions: %w[math-block list-table])
64
31
  ```
65
32
 
66
- ### Recognized extensions
67
-
68
- `Carve::EXTENSIONS` is the list, and it comes from the engine rather than from
69
- a copy kept here that could fall behind it:
33
+ Options configure extensions, safe rendering, profiles, symbols, section
34
+ wrappers, and custom renderers:
70
35
 
71
36
  ```ruby
72
- Carve::EXTENSIONS
73
- # => [:autolink, :citations, :"code-callouts", :"code-group", ...]
37
+ Carve.to_html(
38
+ source,
39
+ extensions: %w[autolink list-table],
40
+ safe: true,
41
+ profile: "comment",
42
+ )
74
43
  ```
75
44
 
76
- The canonical names are kebab-case (`:"math-block"`, `:"table-of-contents"`).
77
- Snake_case spellings (`:math_block`) work as arguments, as do the short aliases
78
- this binding has always taken: `:math`, `:permalinks`, `:mermaid`, `:dot`,
79
- `:graphviz`, `:chart`, `:toc`.
80
-
81
- An unknown extension name raises `ArgumentError`.
45
+ `Carve::EXTENSIONS` reports the names accepted by the bundled engine. Unknown
46
+ names raise `ArgumentError`.
82
47
 
83
- ### File includes
48
+ ## Migration and AST access
84
49
 
85
- Includes are opt-in and require an absolute containment root plus the absolute
86
- path of the source document. The result carries the rendered value, warnings,
87
- and root-relative dependencies. Other render methods leave include directives
88
- literal.
50
+ `Carve.from_html` and `Carve.from_markdown` return canonical Carve with
51
+ structured fidelity reports. `Carve.parse` exposes a Ruby hash representation
52
+ of the AST, and static rendering produces self-contained output for documents
53
+ that do not load client-side renderers.
89
54
 
90
- ```ruby
91
- result = Carve.to_html_with_includes(
92
- File.read("book.crv"),
93
- root: File.expand_path("."),
94
- source_path: File.expand_path("book.crv"),
95
- max_depth: 16,
96
- )
97
- puts result[:value]
98
- ```
55
+ The [usage reference](docs/reference.md) documents AST fields, static
56
+ rendering, symbols, wrappers, profiles, and the main methods.
99
57
 
100
- Every render option `Carve.to_html` takes is accepted here and reaches the
101
- included children too, so a document renders the same way whether or not it
102
- went through the include path: `extensions:`, `symbols:`, `profile:`, `mode:`,
103
- `renderers:`, `safe:` and `sections:`.
58
+ ## Includes
104
59
 
105
- `Carve.parse_with_includes` gives the expanded document as an AST instead, in
106
- the shape `Carve.parse` returns, for a host that walks the tree rather than
107
- rendering HTML:
60
+ Includes are opt-in and require an absolute containment root plus the source
61
+ document's absolute path:
108
62
 
109
63
  ```ruby
110
- result = Carve.parse_with_includes(
64
+ result = Carve.to_html_with_includes(
111
65
  File.read("book.crv"),
112
66
  root: File.expand_path("."),
113
67
  source_path: File.expand_path("book.crv"),
114
68
  )
115
- result[:value][:children]
116
- ```
117
-
118
- Its nodes carry no `:pos`, unlike `Carve.parse`. Spec I4 leaves position
119
- remapping out of scope in every engine, so a span on an included node would name
120
- an offset in a document the caller never passed.
121
-
122
- `Carve.render_with_includes` takes the same arguments plus `target:`, one of
123
- `"html"`, `"markdown"`, `"plain"`, `"ansi"` or `"ast"`. There is no `"carve"`
124
- target: spec I15 excludes the Carve writer from expansion, because inlining a
125
- child into the formatter's output rewrites the author's document rather than
126
- formatting it.
127
-
128
- The budgets `max_depth:`, `max_bytes:`, `max_resolver_calls:` and
129
- `max_warnings:` pass through to the engine; omit one to keep its default. A
130
- target refused by the byte budget still reports `resolved: true`, because
131
- section 19 charges the budget for what the resolver handed back and a target is
132
- resolved before its size is known.
133
-
134
- ## Parsing to an AST
135
-
136
- `Carve.parse` returns the parsed document as a tree of Ruby Hashes and Arrays,
137
- for consumers that want to walk or transform the document rather than render
138
- HTML - for example a custom PDF renderer (see
139
- [`carve-hexapdf`](https://github.com/markup-carve/carve-hexapdf)).
140
-
141
- ```ruby
142
- Carve.parse("# Hello *world*")
143
- # => {type: "document", frontmatter: {}, footnote_defs: {},
144
- # children: [{type: "heading", level: 1,
145
- # children: [{type: "text", value: "Hello "},
146
- # {type: "emphasis", kind: "strong",
147
- # children: [{type: "text", value: "world"}], attrs: nil}],
148
- # attrs: nil}],
149
- # source_len: 15}
150
- ```
151
-
152
- Every node is a Hash with a `:type` key plus its fields; child collections are
153
- Arrays; `:attrs` is `nil` or a Hash of `{id:, classes:, key_values:}`. Keys are
154
- symbols. This is the raw parse tree (default profile, no extensions), so
155
- render-stage extension rewrites are not applied.
156
-
157
- ## Static render mode + renderers
158
-
159
- By default `Carve.to_html` renders **interactive** HTML: client-script
160
- constructs (Mermaid/Graphviz/Chart diagrams, math) emit hydration elements
161
- (`<pre class="mermaid">`, ...) and disclosure stays collapsed (`<details>`).
162
-
163
- Pass `mode: :static` to emit **self-contained** HTML for print, PDF, or
164
- archival. Static mode forces disclosure (`<details open>`) and pre-renders
165
- client-script constructs through the `renderers:` callables you supply.
166
-
167
- ```ruby
168
- Carve.to_html(<<~CRV, extensions: [:fenced_render], mode: :static,
169
- renderers: { mermaid: ->(src) { "<svg>#{src}</svg>" } })
170
- ```mermaid
171
- graph TD; A-->B
172
- ```
173
- CRV
174
69
  ```
175
70
 
176
- ### Renderer callable signatures
177
-
178
- The `renderers:` Hash is keyed by Symbol or String (see
179
- `Carve::RENDERER_KEYS`):
180
-
181
- | Key | Callable signature | Receives |
182
- | --- | ------------------ | -------- |
183
- | `:mermaid` | `(String) -> String` | the diagram source |
184
- | `:chart` | `(String) -> String` | the chart JSON source |
185
- | `:graphviz` | `(String) -> String` | the DOT / Graphviz source |
186
- | `:math` | `(String, display) -> String` | the TeX source and a `display` boolean (`true` for block / display math, `false` for inline) |
187
-
188
- Each callable returns a self-contained HTML string (an `<svg>` / `<img>` for a
189
- diagram, MathML / HTML for math) that the engine emits **verbatim** on the
190
- static path.
191
-
192
- ### Source fallback (graceful degradation)
193
-
194
- When the renderer a construct needs is **absent**, or a supplied renderer
195
- **raises** or returns a **non-String**, the construct degrades to its source -
196
- never blank, and never raw HTML. The fallback source is **HTML-escaped**, so a
197
- construct body containing markup (e.g. `<img onerror=...>`) can never inject raw
198
- HTML. This is part of the cross-implementation graceful-degradation rollout
199
- (spec carve #205; siblings carve-js #242, carve-php #240, carve-rs #143,
200
- carve-py #1).
71
+ The result contains the value, warnings, and root-relative dependencies.
72
+ Other render methods leave directives literal. See the
73
+ [include reference](docs/reference.md#file-includes) for budgets, AST expansion,
74
+ targets, and containment behavior.
201
75
 
202
- An unknown `mode:` value or an unknown `renderers:` key raises `ArgumentError`.
203
-
204
- ## Symbols
205
-
206
- A `:name:` symbol renders its literal `:name:` source unless the name is in the
207
- **symbols map** passed as `symbols:` (String or Symbol keys, String values):
208
-
209
- ```ruby
210
- Carve.to_html("Ship it :rocket: :shrug:", symbols: { "rocket" => "🚀" })
211
- # => "<p>Ship it 🚀 :shrug:</p>" (an unmapped name stays literal)
212
- ```
76
+ ## Security
213
77
 
214
- The leading word-boundary guard is unaffected by an active map: `a:b:c`,
215
- `10:30:` and `me@example.com` never become symbols. A non-String value raises
216
- `TypeError`.
78
+ Use `safe: true` and a restrictive profile for untrusted documents. Custom
79
+ renderer callbacks and symbol values are trusted output and may emit raw HTML.
80
+ The [untrusted-input reference](docs/reference.md#untrusted-input) describes
81
+ resource limits and URL handling.
217
82
 
218
- > **Security: symbol values are TRUSTED RAW output.**
219
- > A mapped value is inserted into the output **unescaped** - the same trust
220
- > class as a `renderers:` callable. `{ "b" => "<b>x</b>" }` emits a real `<b>`
221
- > element, not escaped text. This is deliberate (processor configuration is
222
- > trusted). **Never build a symbols map out of untrusted / user-supplied
223
- > input.**
83
+ ## Development
224
84
 
225
- ## Section wrappers
226
-
227
- A top-level heading is wrapped, along with the content following it up to the
228
- next same-or-shallower heading, in a `<section>` carrying the heading's id (spec
229
- PART 9 §13). Only the id moves - `{#install .featured}` gives
230
- `<section id="install"><h2 class="featured">` - and a heading inside a
231
- blockquote, div or list item is not wrapped at all.
232
-
233
- Pass `sections: false` to render headings flat, with the id back on the `<h*>`:
234
-
235
- ```ruby
236
- Carve.to_html("# A\n\np\n")
237
- # => "<section id=\"A\">\n <h1>A</h1>\n <p>p</p>\n</section>"
238
-
239
- Carve.to_html("# A\n\np\n", sections: false)
240
- # => "<h1 id=\"A\">A</h1>\n<p>p</p>"
241
- ```
242
-
243
- This is for a host whose CSS or JS assumes rendered blocks are direct children
244
- of the content container - the `.stack > * + *` spacing idiom, `:first-child`,
245
- `nth-child()` counting, DOM child walks - all of which stop matching once a
246
- wrapper sits in between. It is the one output change that breaks a document
247
- whose *source* migrated cleanly.
248
-
249
- Nothing else changes: ids, collision dedup, `</#id>` cross-references, implicit
250
- `[Heading][]` references and heading numbering all resolve against the slug
251
- rather than the element carrying it. The endnotes
252
- `<section role="doc-endnotes">` is a separate construct and is still emitted.
253
-
254
- ## Untrusted input
255
-
256
- Carve's normative hardening is always on and needs no option: dangerous URL
257
- schemes are blanked, event-handler attributes like `onclick` are dropped, and the
258
- bidi override/isolate characters behind Trojan Source are removed from rendered
259
- text.
260
-
261
- Raw passthrough is the deliberate exception. A ` ```=html ` block or a
262
- `` `…`{=html} `` span renders **verbatim** by design, so it is the one thing
263
- input you did not author has to switch off:
264
-
265
- ``` ruby
266
- Carve.to_html(user_input, safe: true, profile: :comment)
267
- ```
268
-
269
- `safe:` escapes those raw blocks and spans instead of emitting them. `profile:`
270
- restricts which constructs are allowed at all and caps input length -
271
- `:full`, `:article`, `:comment` or `:minimal`, String or Symbol. An unknown name
272
- raises `ArgumentError` rather than being ignored.
273
-
274
- A profile **rejection** raises too, rather than returning something that looks
275
- like output:
276
-
277
- ``` ruby
278
- Carve.to_html("x" * 20_000, profile: :minimal)
279
- # ArgumentError: Profile violations: 'document' is not allowed: max_length_exceeded (...)
280
- ```
281
-
282
- That matters for untrusted input: the engine's infallible entry point answers a
283
- rejection with an empty String, which a caller cannot tell from a document that
284
- legitimately rendered to nothing.
285
-
286
- Full recipe, defaults and threat model:
287
- [Security](https://markup-carve.github.io/carve/security).
288
-
289
- ## Stored documents and spec versions
290
-
291
- `carve fmt --stamp` (in any Carve engine) records the spec version a document was
292
- last processed under. This gem reads that marker back, so a repository of stored
293
- `.crv` files can be checked for documents predating a breaking spec change:
294
-
295
- ``` ruby
296
- Carve.read_stamp(source)
297
- # => {version: "0.1", generated_by: "carve-php 0.1.0"}
298
-
299
- Carve.needs_review?(source) # true when the document predates this engine
300
- ```
301
-
302
- An **unstamped** document answers `true`: its provenance is unknown, and assuming
303
- it is current is the unsafe direction. Both marker forms are read, and a marker
304
- written by any engine reads the same - the format is the contract, not any one
305
- API - so the answer matches carve-php, carve-js, carve-rs and carve-go on the
306
- same document.
307
-
308
- What a version difference means is the
309
- [versioning contract](https://markup-carve.github.io/carve/versioning): only
310
- `[behavior]` changelog entries between the stamped version and yours can require
311
- a document change.
312
-
313
- ## API
314
-
315
- | Method | Description |
316
- | ------ | ----------- |
317
- | `Carve.to_html(source)` | Render Carve source to HTML. |
318
- | `Carve.parse(source)` | Parse Carve source into an AST (tree of Ruby Hashes/Arrays). |
319
- | `Carve.to_html(source, extensions: [...])` | Render with the named extensions enabled. |
320
- | `Carve.to_html(source, mode: :static, renderers: {...})` | Render self-contained static HTML with build-time renderers. |
321
- | `Carve.to_html(source, symbols: {...})` | Render with a `:name:` -> value symbol map (values are raw, see above). |
322
- | `Carve.to_html(source, safe: true, profile: :comment)` | Render untrusted input: escape `=html` raw blocks/spans, restrict constructs. |
323
- | `Carve.to_html(source, sections: false)` | Render headings flat, with the id on the `<h*>` instead of a `<section>` wrapper. |
324
- | `Carve.to_html_with_includes(source, root:, source_path:)` | Render contained file includes and return warnings and dependencies. |
325
- | `Carve.parse_with_includes(source, root:, source_path:)` | The same expansion, published as an AST instead of HTML. |
326
- | `Carve.render_with_includes(source, root:, source_path:, target:)` | The expansion over any render target: html, markdown, plain, ansi or ast. |
327
- | `Carve.read_stamp(source)` | Read a document's provenance marker: `{version:, generated_by:}` or `nil`. |
328
- | `Carve.needs_review?(source)` | Whether a document predates this engine's spec version (unstamped counts as yes). |
329
- | `Carve.to_html_with_extensions(source, names_array)` | Native primitive (Array of Strings). |
330
- | `Carve.to_html_full(source, names_array, mode_string, renderers_hash)` | Native static-mode primitive. |
331
- | `Carve.to_html_full_with_symbols(source, names_array, mode_string, renderers_hash, symbols_hash)` | Native primitive, static mode + symbol map. |
332
- | `Carve::VERSION` | Gem version. |
333
- | `Carve::EXTENSIONS` | Array of recognized extension symbols. |
334
- | `Carve::MODES` | Array of recognized render modes (`:interactive`, `:static`). |
335
- | `Carve::RENDERER_KEYS` | Array of recognized `renderers:` keys. |
336
-
337
- ## Develop
338
-
339
- ```sh
340
- bundle install
341
- rake compile # builds the Rust extension into lib/carve/carve.so
342
- rake test # runs the minitest suite
343
- ```
344
-
345
- > [!NOTE]
346
- > The native build uses `rb_sys` + `bindgen` (libclang) to read Ruby's
347
- > headers. On systems where libclang cannot find its builtin C headers (the
348
- > `'stdarg.h' file not found` error), point it at the GCC builtin include dir:
349
- >
350
- > ```sh
351
- > export BINDGEN_EXTRA_CLANG_ARGS="-I/usr/lib/gcc/x86_64-linux-gnu/13/include"
352
- > ```
353
- >
354
- > (Adjust the GCC version directory to match your toolchain.)
355
-
356
- ## carve-rs dependency pin
357
-
358
- `ext/carve/Cargo.toml` pins a specific carve-rs commit for reproducible gem
359
- builds:
360
-
361
- ```toml
362
- carve_rs = { package = "carve-lang", git = "https://github.com/markup-carve/carve-rs", rev = "..." }
363
- ```
364
-
365
- Read the current revision out of `ext/carve/Cargo.toml` rather than from a copy
366
- here. This section used to quote one, and it drifted three bumps behind the
367
- manifest before anyone noticed - a duplicated value goes stale the first time
368
- someone edits the original, and a stale one here is worse than none because it
369
- reads as authoritative.
370
-
371
- The crate is imported under the alias `carve_rs`. It is published as `carve-lang`
372
- (carve-rs renamed it from `carve`), so a pin at any revision past that rename
373
- needs `package = "carve-lang"` as above.
374
-
375
- When bumping the `rev`, run `rake compile` and commit the resulting
376
- `ext/carve/Cargo.lock` in the same change. The lock records the resolved
377
- revision, so leaving it behind means every fresh clone gets a dirty working tree
378
- on its first build and the gem can resolve to a different engine than the one
379
- that was tested.
380
-
381
- Whether the pin is current is not a judgment call: CI runs the mandatory spec
382
- corpus through the compiled extension and requires byte-identical HTML, so a pin
383
- that has fallen behind fails a build. Locally:
384
-
385
- ```sh
386
- CARVE_SPEC_CORPUS=/path/to/carve/tests/corpus bundle exec rake test
387
- ```
85
+ Source builds, tests, and the carve-rs dependency pin are documented under
86
+ [Development](docs/reference.md#develop) and
87
+ [carve-rs dependency pin](docs/reference.md#carve-rs-dependency-pin).
data/ext/carve/Cargo.lock CHANGED
@@ -37,8 +37,9 @@ checksum = "b4388bee8683e3d04af747c73422af53102d2bd24d9eadb6cbc100baef4b43f8"
37
37
 
38
38
  [[package]]
39
39
  name = "carve-lang"
40
- version = "0.1.6"
41
- source = "git+https://github.com/markup-carve/carve-rs?rev=d7837249c64b88879b04cd71b8b5555ff246e16f#d7837249c64b88879b04cd71b8b5555ff246e16f"
40
+ version = "0.1.7"
41
+ source = "registry+https://github.com/rust-lang/crates.io-index"
42
+ checksum = "bade620457149d669d9e7b89c3952fa5c44fcbefac2d4de78b75f64792ef1774"
42
43
  dependencies = [
43
44
  "html5ever",
44
45
  "markup5ever_rcdom",
@@ -51,7 +52,7 @@ dependencies = [
51
52
 
52
53
  [[package]]
53
54
  name = "carve-rb"
54
- version = "0.1.4"
55
+ version = "0.1.6"
55
56
  dependencies = [
56
57
  "carve-lang",
57
58
  "magnus",
data/ext/carve/Cargo.toml CHANGED
@@ -1,6 +1,6 @@
1
1
  [package]
2
2
  name = "carve-rb"
3
- version = "0.1.4"
3
+ version = "0.1.6"
4
4
  edition = "2021"
5
5
  rust-version = "1.75"
6
6
  publish = false
@@ -22,4 +22,4 @@ serde_json = "1"
22
22
  # The Carve engine. Imported under the Rust crate alias `carve_rs` so the
23
23
  # binding's own crate name (`carve-rb`) does not collide with the engine's
24
24
  # package name (`carve`) in the Cargo lockfile.
25
- carve_rs = { package = "carve-lang", git = "https://github.com/markup-carve/carve-rs", rev = "d7837249c64b88879b04cd71b8b5555ff246e16f" }
25
+ carve_rs = { package = "carve-lang", version = "=0.1.7" }
data/lib/carve/version.rb CHANGED
@@ -8,5 +8,5 @@ module Carve
8
8
  # compares it against ext/carve/Cargo.toml and against the newest cut
9
9
  # CHANGELOG section on every run, and .github/workflows/release.yml refuses to
10
10
  # publish a gem whose version is not the tag being released.
11
- VERSION = "0.1.4"
11
+ VERSION = "0.1.6"
12
12
  end
metadata CHANGED
@@ -1,14 +1,14 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: carve-lang
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.1.4
4
+ version: 0.1.6
5
5
  platform: ruby
6
6
  authors:
7
7
  - markup-carve
8
8
  autorequire:
9
9
  bindir: bin
10
10
  cert_chain: []
11
- date: 2026-09-20 00:00:00.000000000 Z
11
+ date: 2026-09-30 00:00:00.000000000 Z
12
12
  dependencies:
13
13
  - !ruby/object:Gem::Dependency
14
14
  name: rb_sys