IF Commons GitHub

comment

The comments of SQL text (commons lang-sql 0001-sql-lang FR-009 to FR-012): a comment is kept, never dropped, with its kind, its marker, its span, the text between its markers and its place, so that a parser can attach it to a node and a later feature can read the documentation a person wrote. The lexer fills the columns; commentAt makes one comment an object, only when asked.

The place of a comment is what the attachment needs and no more: before is the number of tokens that precede it, ownLine says whether only white space stands between the start of its line and it, and blankAfter whether a blank line (or the end of the text) follows it. A comment that is ownLine and not blankAfter is, to a person, the comment of what follows; one that is not ownLine is the comment of what precedes it on its line.

const lexed = lex("-- the key\nid int", ansi.compiled);
commentAt(lexed.comments, lexed.text, 0)?.text; // " the key"

Spec: 0001-sql-lang FR-009, FR-010, FR-012

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

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

Commentinterface
interface Comment

A comment of a text.

MemberTypeWhat it is
kind"comment"
styleCommentStyle
markerstringWhat opens it: --, #, //, /*.
spanSpanFrom the first character of its marker to the end of its closing marker (or of the line, or of the text).
textstringWhat is between its markers, as written.
indexnumberIts place among the comments of the text, from 0.
beforenumberHow many tokens precede it: the token before it is before - 1, and the token after it is before.
ownLinebooleanWhether only white space stands between the start of its line and it.
blankAfterbooleanWhether a blank line, or the end of the text, follows it.
terminatedbooleanWhether it is closed: a line comment always is, a block comment that is not closed ends at the end of the text.

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

CommentFlagconstno test imports it
const CommentFlag: { readonly OwnLine: 1; readonly BlankAfter: 2; readonly Unterminated: 4; }

The bits of a comment's flags.

Commentsinterfaceno test imports it
interface Comments

The comments of a text, as columns, in the order of the text.

MemberTypeWhat it is
stylereadonly number[]
markerreadonly string[]
startreadonly number[]
endreadonly number[]
innerStartreadonly number[]
innerEndreadonly number[]
beforereadonly number[]
flagsreadonly number[]
CommentStyletypeno test imports it
type CommentStyle = "line" | "block" | "hint" | "conditional";

The kinds of comment: a line comment, a block comment, an optimizer hint (/*+ ... *\/) and a conditional comment (/*! ... *\/).

allCommentsfunction
function allComments(c: Comments, text: string): readonly Comment[]

Every comment of a text, in order, as objects.

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

commentAtfunctionno test imports it
function commentAt(c: Comments, text: string, i: number): Comment | undefined

One comment as an object.

ParameterWhat it is
cthe columns
textthe text they are of
ithe comment's place among them

Returns: the comment, or undefined where there is none at i

commentCountfunctionno test imports it
function commentCount(c: Comments): number

The comments of the columns, the number of them.

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