1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
//! **The two coordinate systems, as types.**
//!
//! A file is a sequence of bytes. A **view** of it may be of a **rendering** — the file with its directives resolved
//! and its macros expanded, which is what a compiler's parser is handed — and then the same text has two numberings:
//! the **file's**, which is the only one a client speaks, and the **reading's**, which is what every query in this
//! crate reads.
//!
//! They coincide exactly when nothing was replaced, and they differ **silently**:
//!
//! ```text
//! a file offset used against the reading's tree a panic inside rowan —
//! `Bad offset: range 0..106 offset 126`
//! a reading offset converted with the file's lines a three-line file described by two-line coordinates
//! `view.source` where the written text was meant `textDocument/foldingRange` answering `[]`
//! a comment looked for in the reading no documentation, ever
//! ```
//!
//! Not one of those failed loudly. Each produced an answer that *looked* like an answer, because nothing at the
//! boundary knew it had been handed the wrong ruler. A `usize` cannot say which ruler it is, and this crate has nine
//! queries and twenty-odd handlers that all pass one of them around. Two newtypes say it, and the compiler then
//! refuses the mixtures above.
//!
//! # How to cross
//!
//! Only through a [`FileView`](crate::FileView), in the two directions it offers:
//! [`reading_offset_of`](crate::FileView::reading_offset_of) for what a client sent, and
//! [`file_offset_of`](crate::FileView::file_offset_of) for what a client is shown. A view that is not of a rendering
//! crosses both as the identity, which is why a caller never has to ask whether there is one.
//!
//! There is deliberately **no `From<usize>`**: a conversion that happens by accident is the defect this module exists
//! to prevent, so every crossing is a call that says which way it goes. `new` and `get` are for the edges — a byte
//! offset that arrived from outside, a number handed to a lexer or a protocol — and using them in the middle of a
//! query is a decision that has to be readable in the diff.
use fmt;
/// **A byte offset in the file** — the numbering a client's positions resolve to, and the one an editor's text has.
;
/// **A byte offset in the reading** — the numbering of the text a compiler is handed, and the one every query in this
/// crate reads: `&view.root` is the rendering's tree, and so are the scope tree and every fact derived from it.
;