carve-lang 0.1.5 → 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 +4 -4
- data/CHANGELOG.md +34 -4
- data/README.md +42 -342
- data/ext/carve/Cargo.lock +3 -3
- data/ext/carve/Cargo.toml +2 -2
- data/lib/carve/version.rb +1 -1
- metadata +2 -2
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA256:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: 7fa1a68f65aa5ecd3b0ca6554071fa31a2db0b9f57789a65ee5e2f3d8af8b77f
|
|
4
|
+
data.tar.gz: 2d9cec2f07553546dcecaac2f603db42b559512dafa0d183e5a5c297561b4e25
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
6
|
+
metadata.gz: bd2a0359ee4083b50daf8da92144cdcb02f72a3edc7d67b79d52b3e37ced9a73443b229170e7758e610db406bee5065a3e9c449da4494601c963b087c44e4b06
|
|
7
|
+
data.tar.gz: 81355dccbf314c449d49fc64ffc41344d193ad28c51e1707249e7128b1dae2689cbef4f553460e2e20a0bf8afca42cdf52849709753a84dab55e8d8f20397743
|
data/CHANGELOG.md
CHANGED
|
@@ -7,6 +7,35 @@ 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
|
+
|
|
10
39
|
## [0.1.5] - 2026-09-21
|
|
11
40
|
|
|
12
41
|
### Changed
|
|
@@ -287,7 +316,7 @@ are not listed, because no release ever shipped them.
|
|
|
287
316
|
Frontmatter and footnote definitions are block nodes in `children` rather
|
|
288
317
|
than root fields, which PART 12 §7 requires: a root field cannot carry the
|
|
289
318
|
position §4 requires of every node, and both are source an editor navigates
|
|
290
|
-
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`
|
|
291
320
|
and **raw** `content` - not parsed key/values, which could not represent a
|
|
292
321
|
`---toml` block at all. Anything reading `ast[:frontmatter]` or
|
|
293
322
|
`ast[:footnoteDefs]` breaks.
|
|
@@ -296,9 +325,9 @@ are not listed, because no release ever shipped them.
|
|
|
296
325
|
backslash escape is `{"type":"escaped_text","value":"-"}` instead of being
|
|
297
326
|
folded into surrounding text - the backslash carries intent the character does
|
|
298
327
|
not, since an author writes `\-\-` precisely so a consumer will not render an
|
|
299
|
-
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
|
|
300
329
|
`.line-block` class, because inside it every newline is a hard break and a
|
|
301
|
-
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
|
|
302
331
|
extension's `summary` is a list of inline nodes rather than a plain string,
|
|
303
332
|
matching the admonition `title` shape. Definition lists publish
|
|
304
333
|
`definition_term` and `definition_description` nodes
|
|
@@ -372,7 +401,8 @@ are not listed, because no release ever shipped them.
|
|
|
372
401
|
Arrays (every AST node type is covered), enabling custom renderers such as
|
|
373
402
|
[carve-hexapdf](https://github.com/markup-carve/carve-hexapdf).
|
|
374
403
|
|
|
375
|
-
[Unreleased]: https://github.com/markup-carve/carve-rb/compare/v0.1.
|
|
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
|
|
376
406
|
[0.1.5]: https://github.com/markup-carve/carve-rb/compare/v0.1.4...v0.1.5
|
|
377
407
|
[0.1.4]: https://github.com/markup-carve/carve-rb/compare/v0.1.3...v0.1.4
|
|
378
408
|
[0.1.3]: https://github.com/markup-carve/carve-rb/compare/v0.1.2...v0.1.3
|
data/README.md
CHANGED
|
@@ -1,387 +1,87 @@
|
|
|
1
1
|
# carve (Ruby)
|
|
2
2
|
|
|
3
|
-
Native Ruby bindings for the
|
|
4
|
-
markup language.
|
|
5
|
-
|
|
6
|
-
|
|
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
|
-
```
|
|
14
|
+
```bash
|
|
18
15
|
bundle install
|
|
19
16
|
```
|
|
20
17
|
|
|
21
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
73
|
-
|
|
37
|
+
Carve.to_html(
|
|
38
|
+
source,
|
|
39
|
+
extensions: %w[autolink list-table],
|
|
40
|
+
safe: true,
|
|
41
|
+
profile: "comment",
|
|
42
|
+
)
|
|
74
43
|
```
|
|
75
44
|
|
|
76
|
-
|
|
77
|
-
|
|
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
|
-
|
|
48
|
+
## Migration and AST access
|
|
84
49
|
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
and
|
|
88
|
-
|
|
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
|
-
|
|
91
|
-
|
|
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
|
-
|
|
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
|
-
|
|
106
|
-
|
|
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.
|
|
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
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
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
|
-
|
|
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
|
-
|
|
215
|
-
|
|
216
|
-
|
|
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
|
-
|
|
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
|
-
|
|
226
|
-
|
|
227
|
-
|
|
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,9 +37,9 @@ checksum = "b4388bee8683e3d04af747c73422af53102d2bd24d9eadb6cbc100baef4b43f8"
|
|
|
37
37
|
|
|
38
38
|
[[package]]
|
|
39
39
|
name = "carve-lang"
|
|
40
|
-
version = "0.1.
|
|
40
|
+
version = "0.1.7"
|
|
41
41
|
source = "registry+https://github.com/rust-lang/crates.io-index"
|
|
42
|
-
checksum = "
|
|
42
|
+
checksum = "bade620457149d669d9e7b89c3952fa5c44fcbefac2d4de78b75f64792ef1774"
|
|
43
43
|
dependencies = [
|
|
44
44
|
"html5ever",
|
|
45
45
|
"markup5ever_rcdom",
|
|
@@ -52,7 +52,7 @@ dependencies = [
|
|
|
52
52
|
|
|
53
53
|
[[package]]
|
|
54
54
|
name = "carve-rb"
|
|
55
|
-
version = "0.1.
|
|
55
|
+
version = "0.1.6"
|
|
56
56
|
dependencies = [
|
|
57
57
|
"carve-lang",
|
|
58
58
|
"magnus",
|
data/ext/carve/Cargo.toml
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
[package]
|
|
2
2
|
name = "carve-rb"
|
|
3
|
-
version = "0.1.
|
|
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", version = "=0.1.
|
|
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.
|
|
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
|
+
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-
|
|
11
|
+
date: 2026-09-30 00:00:00.000000000 Z
|
|
12
12
|
dependencies:
|
|
13
13
|
- !ruby/object:Gem::Dependency
|
|
14
14
|
name: rb_sys
|