Documentation
¶
Overview ¶
Package parse turns source files into language-neutral model.Facts using tree-sitter grammars and per-language extraction queries.
Languages self-register (see Register) from lang_<x>.go files that embed a queries/<x>.scm query. The query follows a capture convention documented in queries/go.scm; the generic extractor in extract.go interprets it, and optional hooks (hooks.go) refine the result per language.
Index ¶
- Constants
- Variables
- func AppendFacts(dst []byte, f *model.Facts) []byte
- func CSharpIsPartialSig(sig string) bool
- func DecodeFacts(data []byte) (f *model.Facts, err error)
- func DumpFacts(f *model.Facts) string
- func EncodeFacts(f *model.Facts) []byte
- func ForExt(ext string) (model.LanguageSpec, bool)
- func ForPath(p string) (model.LanguageSpec, bool)
- func IsTestPath(p string) bool
- func JavaExternalName(name string) bool
- func JavaPackageOf(src []byte) string
- func Langs() []model.Lang
- func Lookup(l model.Lang) (model.LanguageSpec, bool)
- func PHPNamespaceModule(ns string) string
- func PHPSplitFQN(fqn string) (qualifier, name string)
- func PythonBuiltin(name string) bool
- func Register(spec model.LanguageSpec)
- type Engine
- type Job
- type Output
- type PHPNameScope
- type Pool
- type Result
- type TestPathMatcher
Constants ¶
const CSharpPartialQual = "<partial>"
CSharpPartialQual is the qualifier of the synthetic embeds edge that links every part of a partial type to its sibling parts (see postProcess). It is not a valid C# identifier, so it never collides with a written qualifier.
Variables ¶
var ErrClosed = errors.New("parse: closed")
ErrClosed is returned when using a closed Engine or Pool.
var ErrCorruptFacts = errors.New("parse: corrupt facts encoding")
ErrCorruptFacts is wrapped by every DecodeFacts error.
Functions ¶
func AppendFacts ¶
AppendFacts appends the binary encoding of f to dst.
func CSharpIsPartialSig ¶
CSharpIsPartialSig reports whether a type signature carries the partial modifier ("public partial class X").
func DecodeFacts ¶
DecodeFacts decodes data produced by EncodeFacts. It never panics on malformed input; errors wrap ErrCorruptFacts. The result is not validated semantically (see model.Facts.Validate).
func DumpFacts ¶
DumpFacts renders facts as stable, human-readable text for golden tests and debugging. Definitions are shown with their qualified name; references and inheritance edges name their enclosing definition.
func EncodeFacts ¶
EncodeFacts returns the binary encoding of f.
func ForExt ¶
func ForExt(ext string) (model.LanguageSpec, bool)
ForExt returns the spec claiming ext (with leading dot). Exact case is tried first, then lowercase, mirroring model.LangFromExt.
func ForPath ¶
func ForPath(p string) (model.LanguageSpec, bool)
ForPath returns the spec for a file path by its extension.
func IsTestPath ¶
IsTestPath reports whether path is a test file by the naming convention of its language (see TestPathMatcher). Unknown languages return false.
func JavaExternalName ¶
JavaExternalName reports whether a qualified name belongs to the Java platform (java.*, javax.*, ...).
func JavaPackageOf ¶
JavaPackageOf scans the package declaration at the top of a Java source file without parsing it. It returns "" for the default package.
func Lookup ¶
func Lookup(l model.Lang) (model.LanguageSpec, bool)
Lookup returns the spec registered for l.
func PHPNamespaceModule ¶
PHPNamespaceModule converts a namespace ("App\Model", optionally with a leading backslash) to the dotted module identity ("App.Model").
func PHPSplitFQN ¶
PHPSplitFQN splits a fully qualified name into the qualifier form stored in facts ("\" + namespace, "\" for the global namespace) and the name.
func PythonBuiltin ¶
PythonBuiltin reports whether name is a Python builtin (function, type, exception or constant); unshadowed references to it never resolve to repository code.
func Register ¶
func Register(spec model.LanguageSpec)
Register adds spec to the registry. It panics on an invalid or duplicate language, a duplicate extension, or an extension without a leading dot, since all of these are programming errors caught at init time.
Types ¶
type Engine ¶
type Engine struct {
// contains filtered or unexported fields
}
Engine parses files. It owns one tree-sitter Parser and QueryCursor per language, created lazily, while the compiled Query is shared process-wide. An Engine is not safe for concurrent use; use a Pool for parallelism. Close must be called to release native memory.
func (*Engine) Close ¶
func (e *Engine) Close()
Close releases all parsers and cursors. It is idempotent.
type Job ¶
type Job struct {
Spec model.LanguageSpec
Src []byte
Tag any // caller data passed through to Output (e.g. a file id)
}
Job is one file to parse.
type PHPNameScope ¶
type PHPNameScope struct {
// Namespace is the current namespace without a leading backslash.
Namespace string
// contains filtered or unexported fields
}
PHPNameScope resolves PHP class and function names textually, as the language does: fully qualified names stand, a leading segment matching a use import is replaced by it, everything else is relative to the current namespace. Unqualified function names without a use import are left unresolved because PHP falls back to the global namespace at runtime. The zero value is the global namespace without imports.
func (*PHPNameScope) AddUse ¶
func (s *PHPNameScope) AddUse(kind, fqn, alias string)
AddUse records an import of fqn (leading backslash optional) under its alias or last segment. kind is "", "function" or "const".
type Pool ¶
type Pool struct {
// contains filtered or unexported fields
}
Pool is a fixed set of Engines, one per worker. Each Engine owns its parsers and query cursors, so workers never share mutable tree-sitter state; compiled queries are shared read-only. A Pool is safe for concurrent use.
func (*Pool) Close ¶
func (p *Pool) Close()
Close waits for borrowed engines to be returned and releases all native resources. Further use returns ErrClosed. It is idempotent.
type Result ¶
type Result struct {
Facts *model.Facts
// SyntaxErrors is set when the tree contains ERROR or MISSING nodes.
// Facts are still extracted best-effort (model.StatusParseErr).
SyntaxErrors bool
}
Result is the outcome of parsing one file.
type TestPathMatcher ¶
TestPathMatcher is implemented by specs whose test files are identified by path (e.g. Go's *_test.go). Facts are content-addressed and cached without the path, so the indexer combines this with Facts.TestFile.
Source Files