Attachmenttypeno test imports ittype Attachment = AttachedTo<Node>;A comment, its node and its placement.
The attachment of comments to nodes (commons lang-sql 0002-sql-ast-parser FR-014, FR-015): one rule, the same in every dialect, gives each comment its node and its placement, so that the comment a person wrote above a table or beside a column is found with that table or column.
The rule: the smallest node that contains the comment is its enclosing node. A comment on a line of its own that is followed by a child of the enclosing node is that child's leading comment, unless a blank line follows it, when it is detached and the enclosing node's. A comment that shares its line with what precedes it is the trailing comment of the nearest child before it, or, where none precedes it, the leading comment of the child after it. A comment with no child near it is dangling on the enclosing node, and an own-line comment with no child after it is the trailing comment of the last child before it.
const { script, attachments } = parse("-- the people\nCREATE TABLE person (id INT)");
commentsOf(attachments, script.statements[0]!).leading[0]?.text; // " the people"Spec: 0002-sql-ast-parser FR-014, FR-015
Attachmenttypeno test imports ittype Attachment = AttachedTo<Node>;A comment, its node and its placement.
AttachedTointerfaceno test imports itinterface AttachedTo<N extends Ranged>A comment, its node and its placement, for any tree.
| Member | Type | What it is |
|---|---|---|
comment | Comment | |
placement | Placement | |
node | N | The node it is attached to. |
enclosing | N | The smallest node that contains it, which may be the node it is attached to or the one above. |
attachCommentsfunctionno test imports itfunction attachComments(script: Script, comments: readonly Comment[]): CommentTableAttaches the comments of a text to the nodes of its tree.
| Parameter | What it is |
|---|---|
script | the tree, whose range is the whole text |
comments | the comments of the text, in order |
Returns: the table
attachTreefunctionno test imports itfunction attachTree<N extends Ranged>(root: N, comments: readonly Comment[], children: (n: N) => readonly N[]): TableOf<N>Attaches the comments of a text to the nodes of any tree over it, by the same rule (0002-sql-ast-parser FR-014): the tree's root must contain every comment, and its nodes' children be given in the order of the text.
| Parameter | What it is |
|---|---|
root | the tree, whose range contains the comments |
comments | the comments, in order |
children | the children of a node, in the order of the text |
Returns: the table
Rangedinterfaceno test imports itinterface RangedAnything with a range of the text: a node of the tree, or of another tree made over the same text.
| Member | Type | What it is |
|---|---|---|
start | number | |
end | number |
TableOfinterfaceno test imports itinterface TableOf<N extends Ranged>Every comment's attachment, and the attachments of each node, for any tree.
| Member | Type | What it is |
|---|---|---|
all | readonly AttachedTo<N>[] | One attachment for each comment, in the order of the text. |
byNode | ReadonlyMap<N, readonly AttachedTo<N>[]> |
CommentTabletypeno test imports ittype CommentTable = TableOf<Node>;Every comment's attachment, and the attachments of each node.
commentsOffunctionfunction commentsOf<N extends Ranged>(table: TableOf<N>, node: N): NodeCommentsThe comments of a node by placement.
| Parameter | What it is |
|---|---|
table | the table of a parse |
node | a node of that parse's tree |
Returns: its comments; empty where it has none
NO_COMMENTSconstno test imports itconst NO_COMMENTS: CommentTableThe table of a text with no comments.
NodeCommentsinterfaceno test imports itinterface NodeCommentsThe comments of one node, by placement, in the order of the text.
| Member | Type | What it is |
|---|---|---|
leading | readonly Comment[] | |
trailing | readonly Comment[] | |
dangling | readonly Comment[] | |
detached | readonly Comment[] |
Placementtypeno test imports ittype Placement = "leading" | "trailing" | "dangling" | "detached";Where a comment is, relative to its node.