Documentation
¶
Index ¶
- type Comment
- type Language
- func C() *Language
- func CSS() *Language
- func CSharp() *Language
- func Cpp() *Language
- func Elixir() *Language
- func GetLanguageFromExt(ext string) (*Language, error)
- func Go() *Language
- func Haskell() *Language
- func Java() *Language
- func JavaScript() *Language
- func Julia() *Language
- func Kotlin() *Language
- func Lua() *Language
- func PHP() *Language
- func Protobuf() *Language
- func Python() *Language
- func QML() *Language
- func R() *Language
- func Ruby() *Language
- func Rust() *Language
- func TOML() *Language
- func Tsx() *Language
- func TypeScript() *Language
- func YAML() *Language
- type Mask
- type QueryEngine
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Comment ¶
type Comment struct {
Text string
Source string
Line int
Offset int
Scope string
// Strip records, for each line of Text, how many bytes were taken off the
// front of the matching Source line: the opener, the dedent, and a line
// comment's own decoration. An alert's column is meaningful in Text;
// putting it back in Source means adding this.
//
// Not serialised: this is bookkeeping for putting an alert back where it
// came from, not part of what a comment is.
Strip []int `json:"-"`
// Format is the markup the comment is written in, from the query's
// `type`; empty for plain lines.
Format string `json:"-"`
// Doc is the name the comment is expected to open with, when it
// documents a declaration. See Language.DocName.
Doc string `json:"-"`
// Masks are the ranges of Text that hold no prose; an alert whose match
// lies inside one is dropped. See doc.go.
Masks []Mask `json:"-"`
}
Comment represents an in-code comment (line or block).
func GetComments ¶
GetComments returns all comments in the given source code.
func (Comment) Masked ¶ added in v3.23.0
Masked reports whether a match -- a 1-based line of the comment's text and a 1-based rune span within it, as an alert carries them -- lies wholly in one of the comment's masks. A match that only starts in one and runs on into the prose, a phrase opening with a `{@link}`, is prose.
type Language ¶
type Language struct {
Delims *regexp.Regexp
Parser *sitter.Language
// Prefix matches a block comment's per-line decoration -- the ` *` that
// starts each line of a JSDoc or Javadoc block.
//
// This is not the same thing as Cutset. Decoration is noise of a known
// width that has to come off for the body to be valid markup; indentation
// is meaningful and only its common part comes off. Conflating them is why
// a cutset of " *" cannot work: `*` is both the decoration and Markdown's
// list and emphasis marker, so a cutset wide enough to remove the noise
// also eats a list.
//
// The match is blanked rather than deleted, which keeps every column where
// it was and leaves the dedent below to remove the whitespace it becomes.
Prefix *regexp.Regexp
Queries []core.Scope
Cutset string
Padding padding
// Directive matches a comment addressed to a tool -- a build constraint,
// a linter suppression -- which is dropped rather than read. It is
// matched against the comment as written, delimiter included.
Directive *regexp.Regexp
// Doc masks what the language's documentation convention marks as code:
// the tags of Javadoc, the links of rustdoc. See doc.go.
Doc func(string) []Mask
// DocName is the name a documentation comment is expected to open with,
// read from the node it precedes; nil for a language with no such
// convention.
DocName func(*sitter.Node, []byte) string
}
Language represents a supported programming language.
NOTE: What about haskell, less, perl, php, powershell, r, sass, swift?
func CSharp ¶ added in v3.24.0
func CSharp() *Language
CSharp extracts `//` line comments, `///` XML documentation comments and `/* */` block comments, all of which the grammar parses as `comment`.
func Elixir ¶
func Elixir() *Language
Elixir extracts `#` comments and the prose held by the `@moduledoc`, `@doc`, `@typedoc` and `@shortdoc` attributes.
The attributes are the point. Elixir has no documentation comment syntax: its API documentation lives in module attributes holding a string or a heredoc, and that is what `mix docs` publishes and what a reader of the module reads first. A comment-only pass sees the asides and none of the documentation.
They are given a `doc` meta scope -- `text.comment.doc.line` and `text.comment.doc.block` -- so that published documentation can be held to a different standard than an implementation note, or excluded on its own.
The queries capture `quoted_content`, the body of the string, rather than the string itself. That leaves the delimiters out of the extracted text without a `Delims` pattern having to take them off, which matters for the single-quoted form: stripping its `"` with a regex would also strip any quote written inside the prose. `@doc false` and `@doc since: "1.0"` carry no prose, and neither matches a query that requires a string or sigil.
func GetLanguageFromExt ¶
GetLanguageFromExt returns a Language based on the given file extension.
The grammar is shared across calls: each call builds a fresh Language, whose queries a View may replace, but the grammar underneath is the same one, and a compiled query is cached against it (see compiledQuery). A fresh grammar handle per call made that cache miss every time.
func Haskell ¶
func Haskell() *Language
Haskell is parsed with the Elm grammar: the two languages share their comment syntax (`--`, `{- -}`), and comments are extras that survive error recovery, which is all comment extraction needs.
func JavaScript ¶
func JavaScript() *Language
func Kotlin ¶ added in v3.23.0
func Kotlin() *Language
Kotlin extracts `//` line comments and `/* */` block comments, including KDoc (`/** */`), which the grammar parses as an ordinary block comment.
func QML ¶
func QML() *Language
QML is parsed with the JavaScript grammar: QML's object syntax isn't valid JavaScript, but comments are extras and survive error recovery, which is all comment extraction needs.
func R ¶
func R() *Language
R (and Perl, which shares the normed extension) is parsed with the Bash grammar: all three languages use `#` line comments, and comments are extras that survive error recovery, which is all comment extraction needs.
func TOML ¶ added in v3.23.0
func TOML() *Language
TOML extracts `#` comments. A `#` inside a string is not one, which is what the grammar knows and a pattern does not.
func TypeScript ¶
func TypeScript() *Language
type Mask ¶ added in v3.23.0
type Mask [2]int
Mask is a byte range of a comment's text that holds no prose.
func JSDoc ¶ added in v3.23.0
JSDoc masks a JSDoc comment's inline tags, its block tags with their types and names, and the whole of an `@example` block.
func Javadoc ¶ added in v3.23.0
Javadoc masks a Javadoc comment's inline tags and the symbols its block tags name.
type QueryEngine ¶
type QueryEngine struct {
// contains filtered or unexported fields
}
func NewQueryEngine ¶
func NewQueryEngine(tree *sitter.Tree, lang *Language) *QueryEngine
Source Files