Skip to main content

monochromatic_jsonc_edit/
lib.rs

1//! What:
2//!      `monochromatic-jsonc-edit` parses JSONC into a comment-bearing document model,
3//!  edits it
4//!           immutably,
5//!  and emits canonical JSONC.
6//!           A Rust crate is closest to a TypeScript package module:
7//!  it holds private implementation
8//!           files and one public API surface,
9//!  and the public items are re-exported here so callers
10//!           write `monochromatic_jsonc_edit::parse_jsonc` instead of reaching into modules.
11//! Why:
12//!       The maintained TypeScript package `@monochromatic-dev/jsonc-edit-core-ts` treats comments
13//!           as queryable data rather than discarded trivia,
14//!  compares numbers by exact mathematical
15//!           value while retaining unedited spelling,
16//!  and keeps escaped unpaired UTF-16 surrogates.
17//!           This crate carries the same supported behavior into native Rust with no dependencies and
18//!           no `unsafe` block,
19//!  as recorded in `doc/decision/jsonc-edit-rust-foundation.md`.
20//!
21//! In TS you'd write (pseudocode):
22//! ```ts
23//! import { parseJsonc, jsoncStringify } from '@monochromatic-dev/jsonc-edit-core-ts';
24//! ```
25
26/// What:
27///      The crate's public failure types.
28/// Why:
29///       Parse,
30///  number,
31///  address and shape failures answer different caller questions,
32///  so each has
33///           its own type.
34///
35/// In TS you'd write (pseudocode):
36/// ```ts
37/// export * from './errors';
38/// ```
39pub mod error;
40
41/// What:
42///      Decimal digit-string arithmetic for unbounded number exponents.
43/// Why:
44///       A JSON exponent may carry more digits than any machine integer holds,
45///  and this crate
46///           refuses to bound or materialize it.
47///
48/// In TS you'd write (pseudocode):
49/// ```ts
50/// // private module: decimal string addition and subtraction.
51/// ```
52mod number_scale;
53
54/// What:
55///      The exact mathematical identity of a JSON number literal.
56/// Why:
57///       `1`,
58///  `1.0` and `1e0` must compare equal while adjacent large integers stay distinct.
59///
60/// In TS you'd write (pseudocode):
61/// ```ts
62/// export { JsoncNumberIdentity } from './number';
63/// ```
64pub mod number;
65
66/// What:
67///      Document addresses used by the read and edit surface.
68/// Why:
69///       A key and an array index are different questions,
70///  and the type keeps them apart.
71///
72/// In TS you'd write (pseudocode):
73/// ```ts
74/// export type { JsoncPath } from './path';
75/// ```
76pub mod path;
77
78/// What:
79///      The parsed document model:
80///  values,
81///  members,
82///  keys,
83///  numbers and attached comments.
84/// Why:
85///       Every key and every value carries its own optional comment,
86///  which is what makes the
87///           comment surface queryable instead of merely preserved.
88///
89/// In TS you'd write (pseudocode):
90/// ```ts
91/// export type { JsoncValue } from './value';
92/// ```
93pub mod value;
94
95/// What:
96///      The byte scanner for JSONC tokens,
97///  strings,
98///  numbers and comment trivia.
99/// Why:
100///       Scanning is linear over borrowed source,
101///  with no regular expression and no recursion,
102///  so
103///           malformed input produces a positioned error instead of a stack or backtracking cost.
104///
105/// In TS you'd write (pseudocode):
106/// ```ts
107/// // private module: the scanner the parser drives.
108/// ```
109mod scan;
110
111/// What:
112///      Quoted-string conversion between JSON tokens and UTF-16 code units.
113/// Why:
114///       Escaped unpaired surrogates must survive parsing,
115///  and replacement values must be written
116///           back as legal JSON text.
117///
118/// In TS you'd write (pseudocode):
119/// ```ts
120/// export { decodeQuoted, encodeQuoted, unitsToString } from './textUnits';
121/// ```
122pub mod text_units;
123
124/// What:
125///      Comment attachment,
126///  merging and canonical rendering helpers.
127/// Why:
128///       Stacked comments merge into one normalized comment per key or value,
129///  and emission needs
130///           the same style rules the parser recorded.
131///
132/// In TS you'd write (pseudocode):
133/// ```ts
134/// export { mergeComments } from './mergeComments';
135/// ```
136mod comment_merge;
137
138/// What:
139///      The iterative,
140///  depth-bounded JSONC parser.
141/// Why:
142///       Valid 512-container documents must parse without exhausting the call stack,
143///  and a 513th
144///           opener must be rejected before deeper state exists.
145///
146/// In TS you'd write (pseudocode):
147/// ```ts
148/// export { parseJsonc } from './parse';
149/// ```
150mod parse;
151
152/// What:
153///      The canonical JSONC emitter.
154/// Why:
155///       Output is normalized rather than byte-preserving,
156///  so comments stay attached to the same
157///           key or value across an emit-and-reparse cycle.
158///
159/// In TS you'd write (pseudocode):
160/// ```ts
161/// export { emitJsoncValue } from './stringify';
162/// ```
163mod emit;
164
165/// What:
166///      Re-export the failure types at the crate root.
167/// Why:
168///       Callers name `monochromatic_jsonc_edit::JsoncParseError` in signatures without importing
169///           a module path.
170///
171/// In TS you'd write (pseudocode):
172/// ```ts
173/// export { JsoncParseError, JsoncPathNotFoundError, JsoncTypeError } from './errors';
174/// ```
175pub use error::{JsoncEditError, JsoncNumberError, JsoncParseError, JsoncPathNotFoundError, JsoncTypeError};
176/// What:
177///      Re-export the exact-number identity.
178/// Why:
179///       It appears inside the public value model,
180///  so it is part of the API surface.
181///
182/// In TS you'd write (pseudocode):
183/// ```ts
184/// export { JsoncNumberIdentity } from './number';
185/// ```
186pub use number::JsoncNumberIdentity;
187/// What:
188///      Re-export the address type and its key-path helper.
189/// Why:
190///       Read and edit calls take addresses,
191///  so callers need the type at the crate root.
192///
193/// In TS you'd write (pseudocode):
194/// ```ts
195/// export { jsoncKeyPath, type JsoncPathSegment } from './path';
196/// ```
197pub use path::{jsonc_key_path, JsoncPathSegment};
198/// What:
199///      Re-export the document model.
200/// Why:
201///       These are the types every caller holds,
202///  inspects and edits.
203///
204/// In TS you'd write (pseudocode):
205/// ```ts
206/// export type { JsoncValue, JsoncKind, JsoncEntry, JsoncKey, JsoncComment } from './value';
207/// ```
208pub use value::{JsoncComment, JsoncCommentKind, JsoncEntry, JsoncKey, JsoncKind, JsoncValue};
209
210/// What:
211///      Re-export comment merging and the parse and emit entry points.
212/// Why:
213///       These three functions are the whole document lifecycle a caller needs before the edit
214///           surface is added.
215///
216/// In TS you'd write (pseudocode):
217/// ```ts
218/// export { mergeComments, parseJsonc, emitJsoncValue } from './index';
219/// ```
220pub use comment_merge::attach as merge_comments;
221/// What:
222///      Re-export the canonical emitter.
223/// Why:
224///       Writing a document is half of the lifecycle,
225///  and callers should not name a private module.
226///
227/// In TS you'd write (pseudocode):
228/// ```ts
229/// export { emitJsoncValue } from './stringify';
230/// ```
231pub use emit::emit_jsonc_value;
232/// What:
233///      Re-export the JSONC parser entry point.
234/// Why:
235///       Parsing is the other half of the lifecycle and the only way to obtain a document value.
236///
237/// In TS you'd write (pseudocode):
238/// ```ts
239/// export { parseJsonc } from './parse';
240/// ```
241pub use parse::parse_jsonc;
242/// What:
243///      Re-export the quoted-string conversions.
244/// Why:
245///       Callers that hold a raw token or stored code units need the same decoding and encoding
246///           rules the parser and emitter use.
247///
248/// In TS you'd write (pseudocode):
249/// ```ts
250/// export { decodeQuoted, encodeQuoted, unitsToString } from './textUnits';
251/// ```
252pub use text_units::{decode_quoted, encode_quoted, units_to_string};
253
254/// What:
255///  Source positions (byte offset,
256/// line,
257/// column) for parsed values and object keys.
258/// Why:
259///  Callers that decode a document into their own types need `file:line:col` for a value they reject,
260///  and the document tree itself stays position-free so existing constructors and comparisons keep working.
261///
262/// In TS you'd write (pseudocode):
263/// ```ts
264/// export * from './span';
265/// ```
266mod span;
267/// What:
268///  Re-export the span types and the span-reporting parser entry point.
269/// Why:
270///  Positions are a parsing feature,
271/// so callers reach them from the crate root beside `parse_jsonc`.
272///
273/// In TS you'd write (pseudocode):
274/// ```ts
275/// export { parseJsoncWithSpans, jsoncPositionAt } from './span';
276/// export type { JsoncPosition, JsoncSpan, JsoncSpans, JsoncSpanned } from './span';
277/// ```
278pub use span::{JsoncPosition, JsoncSpan, JsoncSpanned, JsoncSpans, jsonc_position_at, parse_jsonc_with_spans};
279
280/// What:
281///      Parser and emitter conformance tests over the public crate interface.
282/// Why:
283///       Comment ownership,
284///  depth limits,
285///  UTF-16 escapes and exact numbers must survive a parse,
286///           emit and reparse cycle,
287///  which compilation alone cannot show.
288///
289/// In TS you'd write (pseudocode):
290/// ```ts
291/// import './parse.test';
292/// ```
293#[cfg(test)]
294mod parse_tests;
295
296/// What:
297///  Tests for the span-reporting parse entry point and the position rule.
298/// Why:
299///  Positions are only trustworthy if slicing the text between a span's offsets returns the node's own token,
300///  which compilation cannot show.
301///
302/// In TS you'd write (pseudocode):
303/// ```ts
304/// import './span.test';
305/// ```
306#[cfg(test)]
307mod span_tests;
308
309/// What:
310///      Exact-number identity tests,
311///  including an independent rational oracle.
312/// Why:
313///       Equality across spellings and rejection of malformed tokens are the crate's numeric
314///           contract,
315///  and an oracle cross-checks the normalizer rather than itself.
316///
317/// In TS you'd write (pseudocode):
318/// ```ts
319/// import './number.test';
320/// ```
321#[cfg(test)]
322mod number_tests;
323
324/// What:
325///      Quoted-string conversion tests.
326/// Why:
327///       Lone surrogates,
328///  control characters and escape spellings must survive decode,
329///  convert and
330///           re-encode without changing the code units.
331///
332/// In TS you'd write (pseudocode):
333/// ```ts
334/// import './textUnits.test';
335/// ```
336#[cfg(test)]
337mod text_units_tests;
338
339/// What:
340///      The immutable edit state plus its parse and serialize entry points.
341/// Why:
342///       A caller holds a state,
343///  derives new states from edits,
344///  and writes any of them out.
345///
346/// In TS you'd write (pseudocode):
347/// ```ts
348/// export { parseJsoncEdit, jsoncStringify, type JsoncEditState } from './editState';
349/// ```
350mod edit_state;
351
352/// What:
353///      Address resolution for reads,
354///  existence checks and key listing.
355/// Why:
356///       Every surface walks addresses with the same last-duplicate and bounds rules.
357///
358/// In TS you'd write (pseudocode):
359/// ```ts
360/// export { jsoncGetValue, jsoncHas, jsoncKeys } from './editNavigate';
361/// ```
362mod navigate;
363
364/// What:
365///      The iterative spine walk shared by every immutable edit.
366/// Why:
367///       A recursive rebuild overflows a debug test thread's stack at the accepted 512-container depth,
368///           so descent and rebuild keep their own explicit level stack.
369///
370/// In TS you'd write (pseudocode):
371/// ```ts
372/// // private module: descend(root, path) then rebuild(levels, value).
373/// ```
374mod edit_spine;
375
376/// What:
377///      Immutable value replacement,
378///  insertion and deletion.
379/// Why:
380///       Structural edits return a new document and leave the input state usable.
381///
382/// In TS you'd write (pseudocode):
383/// ```ts
384/// export { jsoncSet, jsoncDelete } from './editSet';
385/// ```
386mod edit_apply;
387
388/// What:
389///      The comment-as-data query and edit surface.
390/// Why:
391///       A value's comment and its key's comment are separate data,
392///  and both are editable.
393///
394/// In TS you'd write (pseudocode):
395/// ```ts
396/// export { jsoncGetComment, jsoncSetComment, jsoncGetKeyComment, jsoncSetKeyComment } from './editComment';
397/// ```
398mod edit_comment;
399
400/// What:
401///      Re-export the edit state and its lifecycle functions.
402/// Why:
403///       These are the entry points a consumer needs to hold and serialize a document.
404///
405/// In TS you'd write (pseudocode):
406/// ```ts
407/// export { parseJsoncEdit, jsoncStringify, type JsoncEditState } from './index';
408/// ```
409pub use edit_state::{jsonc_state_from_value, jsonc_stringify, parse_jsonc_edit, JsoncEditState};
410
411/// What:
412///      Re-export the read surface.
413/// Why:
414///       Reads answer what a document holds without deriving a new one.
415///
416/// In TS you'd write (pseudocode):
417/// ```ts
418/// export { jsoncGetValue, jsoncHas, jsoncKeys } from './index';
419/// ```
420pub use navigate::{jsonc_has, jsonc_keys, jsonc_lookup};
421
422/// What:
423///      Re-export the structural edit surface.
424/// Why:
425///       Setting and deleting are the two operations that change document shape.
426///
427/// In TS you'd write (pseudocode):
428/// ```ts
429/// export { jsoncSet, jsoncDelete } from './index';
430/// ```
431pub use edit_apply::{jsonc_delete, jsonc_set};
432
433/// What:
434///      Re-export the comment surface.
435/// Why:
436///       Comments are queryable and editable data,
437///  not output decoration.
438///
439/// In TS you'd write (pseudocode):
440/// ```ts
441/// export { jsoncGetComment, jsoncSetComment, jsoncGetKeyComment, jsoncSetKeyComment } from './index';
442/// ```
443pub use edit_comment::{jsonc_comment, jsonc_key_comment, jsonc_set_comment, jsonc_set_key_comment};
444
445/// What:
446///      Read and structural edit tests.
447/// Why:
448///       Immutability,
449///  insertion limits and the two failure kinds are the edit contract.
450///
451/// In TS you'd write (pseudocode):
452/// ```ts
453/// import './edit.test';
454/// ```
455#[cfg(test)]
456mod edit_tests;
457
458/// What:
459///      Comment query and edit tests.
460/// Why:
461///       Key and value comments are separate data and must keep their owner across emission.
462///
463/// In TS you'd write (pseudocode):
464/// ```ts
465/// import './editComment.test';
466/// ```
467#[cfg(test)]
468mod edit_comment_tests;
469
470/// What:
471///      Public-surface tests for address helpers,
472///  identity accessors,
473///  comment merging and errors.
474/// Why:
475///       Every exported item needs coverage before the crate can be called complete.
476///
477/// In TS you'd write (pseudocode):
478/// ```ts
479/// import './api.test';
480/// ```
481#[cfg(test)]
482mod api_tests;
483
484/// What:
485///      Shared-fixture tests read from the same corpus the TypeScript conformance suite uses.
486/// Why:
487///       One language-neutral contract keeps both maintained implementations from drifting.
488///
489/// In TS you'd write (pseudocode):
490/// ```ts
491/// import './fixtures.test';
492/// ```
493#[cfg(test)]
494mod fixture_tests;