IF Commons GitHub

attach

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

Source: commons/lang-sql/src/attach.ts

1 of 11 exports are imported by a test of the run. A test that imports an export may not call it or check what it returns.

Attachmenttypeno test imports it
type Attachment = AttachedTo<Node>;

A comment, its node and its placement.

AttachedTointerfaceno test imports it
interface AttachedTo<N extends Ranged>

A comment, its node and its placement, for any tree.

MemberTypeWhat it is
commentComment
placementPlacement
nodeNThe node it is attached to.
enclosingNThe smallest node that contains it, which may be the node it is attached to or the one above.
attachCommentsfunctionno test imports it
function attachComments(script: Script, comments: readonly Comment[]): CommentTable

Attaches the comments of a text to the nodes of its tree.

ParameterWhat it is
scriptthe tree, whose range is the whole text
commentsthe comments of the text, in order

Returns: the table

attachTreefunctionno test imports it
function 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.

ParameterWhat it is
rootthe tree, whose range contains the comments
commentsthe comments, in order
childrenthe children of a node, in the order of the text

Returns: the table

Rangedinterfaceno test imports it
interface Ranged

Anything with a range of the text: a node of the tree, or of another tree made over the same text.

MemberTypeWhat it is
startnumber
endnumber
TableOfinterfaceno test imports it
interface TableOf<N extends Ranged>

Every comment's attachment, and the attachments of each node, for any tree.

MemberTypeWhat it is
allreadonly AttachedTo<N>[]One attachment for each comment, in the order of the text.
byNodeReadonlyMap<N, readonly AttachedTo<N>[]>
CommentTabletypeno test imports it
type CommentTable = TableOf<Node>;

Every comment's attachment, and the attachments of each node.

commentsOffunction
function commentsOf<N extends Ranged>(table: TableOf<N>, node: N): NodeComments

The comments of a node by placement.

ParameterWhat it is
tablethe table of a parse
nodea node of that parse's tree

Returns: its comments; empty where it has none

Imported by 11 tests of the run (11 passed, 0 failed): the library's results

NO_COMMENTSconstno test imports it
const NO_COMMENTS: CommentTable

The table of a text with no comments.

NodeCommentsinterfaceno test imports it
interface NodeComments

The comments of one node, by placement, in the order of the text.

MemberTypeWhat it is
leadingreadonly Comment[]
trailingreadonly Comment[]
danglingreadonly Comment[]
detachedreadonly Comment[]
Placementtypeno test imports it
type Placement = "leading" | "trailing" | "dangling" | "detached";

Where a comment is, relative to its node.

Titles, headings, exports, tables, columns and requirements. Esc closes.