analysis

README

pawn-analysis

Shared Pawn preprocessing and semantic analysis for PawnKit tools.

The library provides original and expanded syntax, source-mapped symbols, tag and call checks, control flow, constant evaluation, and cached snapshots. Automaton checks cover invalid state transitions and conflicting state implementations.

result, err := analysis.AnalyzeContext(ctx, text, analysis.Options{
    URI: source.FileURI(path),
})

Use query.Snapshot for versioned editor documents. Set Options.Revision when API metadata or resolver state changes so cached results are invalidated. Use AnalyzeDocuments when the project host has already built a dependency closure.

See Diagnostics when an analysis code needs more context.

Run go test ./... for the offline suite. Tests use a sibling pawn-corpus checkout when present. Set PAWN_CORPUS_DIR to its absolute path when it lives elsewhere.

Contributing

Small parser, resolver, and analysis fixes are welcome. A reduced Pawn example is often the best place to start. See CONTRIBUTING.md.

Licence

MIT

Documentation

Overview

Package analysis wires PawnKit preprocessing, parsing, and semantics.

Index

• type Options
• type Result
  • func Analyze(text []byte, opts Options) *Result
  • func AnalyzeContext(ctx context.Context, text []byte, opts Options) (*Result, error)
  • func CompleteContext(ctx context.Context, prepared *Result, opts Options) (*Result, error)
• type ReuseStats
• type Stage
• type TraceEvent

Types

type Options

type Options struct {
	URI             source.URI
	Includes        preprocess.IncludeResolver
	Names           sema.Resolver
	Predefined      map[string]string
	Revision        string
	RetainExpanded  bool
	MaxOutputTokens int
	SkipSemantics   bool
	TokenCache      *preprocess.TokenCache
	Previous        *Result
	// ReuseCompatibleExpansion allows editor diagnostics to reuse an unchanged
	// dependency graph. Expanded source may describe the previous local body.
	ReuseCompatibleExpansion bool
	Trace                    func(TraceEvent)
}

Options configures one file analysis.

type Result

type Result struct {
	File            source.FileID
	Registry        *source.Registry
	Preprocess      *preprocess.Result
	Parse           *parser.CompactFile
	ExpandedParse   *parser.CompactFile
	Declarations    parser.DeclarationIndex
	Symbols         *symbol.Table
	ExpandedSymbols *symbol.Table
	Semantics       sema.Result
	ControlFlow     []sema.FunctionFlow
	Diagnostics     []diagnostic.Diagnostic
	Reuse           ReuseStats
	// contains filtered or unexported fields
}

Result is one immutable file analysis.

func Analyze

func Analyze(text []byte, opts Options) *Result

Analyze runs the shared per-file pipeline.

func AnalyzeContext

func AnalyzeContext(ctx context.Context, text []byte, opts Options) (*Result, error)

AnalyzeContext runs the shared per-file pipeline with cancellation.

func CompleteContext

func CompleteContext(ctx context.Context, prepared *Result, opts Options) (*Result, error)

CompleteContext runs semantics on an existing parse result.

type ReuseStats

type ReuseStats struct {
	ControlFlow         int
	Declarations        int
	Tags                int
	CompatibleExpansion bool
}

type Stage

type Stage string

Stage identifies one analysis step.

const (
	StagePreprocess      Stage = "preprocess"
	StageParseOriginal   Stage = "parser.original"
	StageSymbolsOriginal Stage = "symbols.original"
	StageParseExpanded   Stage = "parser.expanded"
	StageSymbolsExpanded Stage = "symbols.expanded"
	StageDeclarations    Stage = "declarations"
	StageSemanticNames   Stage = "semantic.names"
	StageSemanticTags    Stage = "semantic.tags"
	StageSemanticStates  Stage = "semantic.states"
	StageSemanticOrder   Stage = "semantic.constants"
	StageSemanticCFG     Stage = "semantic.cfg"
)

type TraceEvent

type TraceEvent struct {
	Stage     Stage
	Duration  time.Duration
	Reused    int
	Cancelled bool
}

TraceEvent records one completed stage.