gogrep

README

gogrep

This is an attempt to move a modified gogrep from the go-ruleguard project, so it can be used independently.

This repository contains two Go modules. One for the gogrep library and the second one for the command-line tool.

gogrep as a library

To get a gogrep library module, install the root Go module.

$ go get github.com/quasilyte/gogrep

gogrep as a command-line utility

To get a gogrep command-line tool, install the cmd/gogrep Go submodule.

$ go install github.com/quasilyte/gogrep/cmd/gogrep@latest

See docs/gogrep_cli.md to learn how to use it.

Used by

A gogrep library is used by:

• go-ruleguard
• gocorpus

Acknowledgements

The original gogrep is written by the Daniel Martí.

Documentation

Index

• func Compile(config CompileConfig) (*Pattern, PatternInfo, error)
• func IsEmptyNodeSlice(n ast.Node) bool
• func Walk(root ast.Node, fn func(n ast.Node) bool)
• type CapturedNode
• type CompileConfig
• type MatchData
  • func (data MatchData) CapturedByName(name string) (ast.Node, bool)
• type MatcherState
  • func NewMatcherState() MatcherState
• type NodeSlice
  • func (s *NodeSlice) At(i int) ast.Node
  • func (s *NodeSlice) End() token.Pos
  • func (s *NodeSlice) GetDeclSlice() []ast.Decl
  • func (s *NodeSlice) GetExprSlice() []ast.Expr
  • func (s *NodeSlice) GetFieldSlice() []*ast.Field
  • func (s *NodeSlice) GetIdentSlice() []*ast.Ident
  • func (s *NodeSlice) GetSpecSlice() []ast.Spec
  • func (s *NodeSlice) GetStmtSlice() []ast.Stmt
  • func (s *NodeSlice) Len() int
  • func (s *NodeSlice) Pos() token.Pos
  • func (s *NodeSlice) SliceInto(dst *NodeSlice, i, j int)
• type NodeSliceKind
• type PartialNode
  • func (p *PartialNode) End() token.Pos
  • func (p *PartialNode) Pos() token.Pos
• type Pattern
  • func (p *Pattern) Clone() *Pattern
  • func (p *Pattern) MatchNode(state *MatcherState, n ast.Node, cb func(MatchData))
  • func (p *Pattern) NodeTag() nodetag.Value
• type PatternInfo

Functions

func Compile

func Compile(config CompileConfig) (*Pattern, PatternInfo, error)

func IsEmptyNodeSlice

func IsEmptyNodeSlice(n ast.Node) bool

func Walk

func Walk(root ast.Node, fn func(n ast.Node) bool)

Types

type CapturedNode

type CapturedNode struct {
	Name string
	Node ast.Node
}

type CompileConfig

type CompileConfig struct {
	Fset *token.FileSet

	// Src is a gogrep pattern expression string.
	Src string

	// When strict is false, gogrep may consider 0xA and 10 to be identical.
	// If true, a compiled pattern will require a full syntax match.
	Strict bool

	// WithTypes controls whether gogrep would have types.Info during the pattern execution.
	// If set to true, it will compile a pattern to a potentially more precise form, where
	// fmt.Printf maps to the stdlib function call but not Printf method call on some
	// random fmt variable.
	WithTypes bool

	// Imports specifies packages that should be recognized for the type-aware matching.
	// It maps a package name to a package path.
	// Only used if WithTypes is true.
	Imports map[string]string
}

type MatchData

type MatchData struct {
	Node    ast.Node
	Capture []CapturedNode
}

MatchData describes a successful pattern match.

func (MatchData) CapturedByName

func (data MatchData) CapturedByName(name string) (ast.Node, bool)

type MatcherState

type MatcherState struct {
	Types *types.Info

	// CapturePreset is a key-value pairs to use in the next match calls
	// as predefined variables.
	// For example, if the pattern is `$x = f()` and CapturePreset contains
	// a pair with Name=x and value of `obj.x`, then the above mentioned
	// pattern will only match `obj.x = f()` statements.
	//
	// If nil, the default behavior will be used. A first syntax element
	// matching the matcher var will be captured.
	CapturePreset []CapturedNode
	// contains filtered or unexported fields
}

func NewMatcherState

func NewMatcherState() MatcherState

type NodeSlice

type NodeSlice struct {
	Kind NodeSliceKind
	// contains filtered or unexported fields
}

func (*NodeSlice) At

func (s *NodeSlice) At(i int) ast.Node

func (*NodeSlice) End

func (s *NodeSlice) End() token.Pos

func (*NodeSlice) GetDeclSlice

func (s *NodeSlice) GetDeclSlice() []ast.Decl

func (*NodeSlice) GetExprSlice

func (s *NodeSlice) GetExprSlice() []ast.Expr

func (*NodeSlice) GetFieldSlice

func (s *NodeSlice) GetFieldSlice() []*ast.Field

func (*NodeSlice) GetIdentSlice

func (s *NodeSlice) GetIdentSlice() []*ast.Ident

func (*NodeSlice) GetSpecSlice

func (s *NodeSlice) GetSpecSlice() []ast.Spec

func (*NodeSlice) GetStmtSlice

func (s *NodeSlice) GetStmtSlice() []ast.Stmt

func (*NodeSlice) Len

func (s *NodeSlice) Len() int

func (*NodeSlice) Pos

func (s *NodeSlice) Pos() token.Pos

func (*NodeSlice) SliceInto

func (s *NodeSlice) SliceInto(dst *NodeSlice, i, j int)

type NodeSliceKind

type NodeSliceKind uint32

const (
	ExprNodeSlice NodeSliceKind = iota
	StmtNodeSlice
	FieldNodeSlice
	IdentNodeSlice
	SpecNodeSlice
	DeclNodeSlice
)

type PartialNode

type PartialNode struct {
	X ast.Node
	// contains filtered or unexported fields
}

func (*PartialNode) End

func (p *PartialNode) End() token.Pos

func (*PartialNode) Pos

func (p *PartialNode) Pos() token.Pos

type Pattern

type Pattern struct {
	// contains filtered or unexported fields
}

func (*Pattern) Clone

func (p *Pattern) Clone() *Pattern

Clone creates a pattern copy.

func (*Pattern) MatchNode

func (p *Pattern) MatchNode(state *MatcherState, n ast.Node, cb func(MatchData))

MatchNode calls cb if n matches a pattern.

func (*Pattern) NodeTag

func (p *Pattern) NodeTag() nodetag.Value

type PatternInfo

type PatternInfo struct {
	Vars map[string]struct{}
}