dsl

package module
v0.3.22 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Dec 28, 2022 License: BSD-3-Clause Imports: 1 Imported by: 49

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func ImportRules 

func ImportRules(prefix string, bundle Bundle)

ImportRules imports all rules from the bundle and prefixes them with a specified string.

Empty string prefix is something like "dot import" in Go. Group name collisions will result in an error.

Only packages that have an exported Bundle variable can be imported.

Note: right now imported bundle can't import other bundles. This is not a fundamental limitation but rather a precaution measure before we understand how it should work better. If you need this feature, please open an issue at github.com/quasilyte/go-ruleguard.

Types

type Bundle 

type Bundle struct {
}

Bundle is a rules file export manifest.

type DoContext added in v0.3.17 

type DoContext struct{}

func (*DoContext) SetReport added in v0.3.17 

func (*DoContext) SetReport(report string)

func (*DoContext) SetSuggest added in v0.3.17 

func (*DoContext) SetSuggest(suggest string)

func (*DoContext) Var added in v0.3.17 

func (*DoContext) Var(varname string) *DoVar

type DoVar added in v0.3.17 

type DoVar struct{}

func (*DoVar) Text added in v0.3.17 

func (*DoVar) Text() string

func (*DoVar) Type added in v0.3.17 

func (*DoVar) Type() types.Type

type ExprType 

type ExprType struct {
	// Size represents expression type size in bytes.
	//
	// For expressions of unknown size, like type params in generics,
	// any filter using this operand will fail.
	Size int
}

ExprType describes a type of a matcher expr.

func (ExprType) AssignableTo 

func (ExprType) AssignableTo(typ string) bool

AssignableTo reports whether a type is assign-compatible with a given type. See https://golang.org/pkg/go/types/#AssignableTo.

func (ExprType) ConvertibleTo 

func (ExprType) ConvertibleTo(typ string) bool

ConvertibleTo reports whether a type is conversible to a given type. See https://golang.org/pkg/go/types/#ConvertibleTo.

func (ExprType) HasMethod added in v0.3.13 

func (ExprType) HasMethod(fn string) bool

HasMethod reports whether a type has a given method. Unlike Implements(), it will work for both value and pointer types.

fn argument is a function signature, like `WriteString(string) (int, error)`. It can also be in form of a method reference for importable types: `io.StringWriter.WriteString`.

To avoid confusion with Implements() method, here is a hint when to use which:

  • To check if it's possible to call F on x, use HasMethod(F)
  • To check if x can be passed as I interface, use Implements(I)

func (ExprType) HasPointers added in v0.3.12 

func (ExprType) HasPointers() bool

HasPointers reports whether a type contains at least one pointer.

We try to be as close to the Go sense of pointer-free objects as possible, therefore string type is not considered to be a pointer-free type.

This function may return "true" for some complicated cases as a conservative result. It never returns "false" for a type that actually contains a pointer.

So this function is mostly useful for !HasPointers() form.

func (ExprType) IdenticalTo added in v0.3.15 

func (ExprType) IdenticalTo(v Var) bool

IdenticalTo applies types.Identical(this, v.Type) operation. See https://golang.org/pkg/go/types/#Identical function documentation.

Experimental: this function is not part of the stable API.

func (ExprType) Implements 

func (ExprType) Implements(typ typeName) bool

Implements reports whether a type implements a given interface. See https://golang.org/pkg/go/types/#Implements.

func (ExprType) Is 

func (ExprType) Is(typ string) bool

Is reports whether a type is identical to a given type.

func (ExprType) OfKind added in v0.3.11 

func (ExprType) OfKind(kind string) bool

OfKind reports whether a matched expr type is compatible with the specified kind.

Only a few "kinds" are recognized, the list is provided below. 

	"integer"  -- typ is *types.Basic, where typ.Info()&types.Integer != 0
	"unsigned" -- typ is *types.Basic, where typ.Info()&types.Unsigned != 0
	"float"    -- typ is *types.Basic, where typ.Info()&types.Float != 0
	"complex"  -- typ is *types.Basic, where typ.Info()&types.Complex != 0
	"untyped"  -- typ is *types.Basic, where typ.Info()&types.Untyped != 0
	"numeric"  -- typ is *types.Basic, where typ.Info()&types.Numeric != 0
 "signed"   -- identical to `OfKind("integer") && !OfKind("unsigned")`
 "int"      -- int, int8, int16, int32, int64
 "uint"     -- uint, uint8, uint16, uint32, uint64

Note: "int" will include "rune" as well, as it's an alias. In the same manner, "uint" includes the "byte" type.

Using OfKind("unsigned") is more efficient (and concise) than using a set of or-conditions with Is("uint8"), Is("uint16") and so on.

func (ExprType) Underlying 

func (ExprType) Underlying() ExprType

Underlying returns expression type underlying type. See https://golang.org/pkg/go/types/#Type Underlying() method documentation. Read https://golang.org/ref/spec#Types section to learn more about underlying types.

type ExprValue 

type ExprValue struct{}

ExprValue describes a compile-time computable value of a matched expr.

func (ExprValue) Int 

func (ExprValue) Int() int

Int returns compile-time computable int value of the expression. If value can't be computed, condition will fail.

type File 

type File struct {
	// Name is a file base name.
	Name String

	// PkgPath is a file package path.
	// Examples: "io/ioutil", "strings", "github.com/quasilyte/go-ruleguard/dsl".
	PkgPath String
}

File represents the current Go source file.

func (File) Imports 

func (File) Imports(path string) bool

Imports reports whether the current file imports the given path.

type GoVersion added in v0.3.8 

type GoVersion struct{}

GoVersion is an analysis target go language version. It can be compared to Go versions like "1.10", "1.16" using the associated methods.

func (GoVersion) Eq added in v0.3.8 

func (GoVersion) Eq(version string) bool

Eq asserts that target Go version is equal to (==) specified version.

func (GoVersion) GreaterEqThan added in v0.3.8 

func (GoVersion) GreaterEqThan(version string) bool

GreaterEqThan asserts that target Go version is greater or equal than (>=) specified version.

func (GoVersion) GreaterThan added in v0.3.8 

func (GoVersion) GreaterThan(version string) bool

GreaterThan asserts that target Go version is greater than (>) specified version.

func (GoVersion) LessEqThan added in v0.3.8 

func (GoVersion) LessEqThan(version string) bool

LessEqThan asserts that target Go version is less or equal than (<=) specified version.

func (GoVersion) LessThan added in v0.3.8 

func (GoVersion) LessThan(version string) bool

LessThan asserts that target Go version is less than (<) specified version.

type MatchedNode 

type MatchedNode struct{}

MatchedNode represents an AST node associated with a named submatch.

func (MatchedNode) Is 

func (MatchedNode) Is(typ string) bool

Is reports whether a matched node AST type is compatible with the specified type. A valid argument is a ast.Node implementing type name from the "go/ast" package. Examples: "BasicLit", "Expr", "Stmt", "Ident", "ParenExpr". See https://golang.org/pkg/go/ast/.

func (MatchedNode) Parent added in v0.3.7 

func (MatchedNode) Parent() Node

Parent returns a matched node parent.

type MatchedText 

type MatchedText string

MatchedText represents a source text associated with a matched node.

func (MatchedText) Matches 

func (MatchedText) Matches(pattern string) bool

Matches reports whether the text matches the given regexp pattern.

type Matcher 

type Matcher map[string]Var

Matcher is a main API group-level entry point. It's used to define and configure the group rules. It also represents a map of all rule-local variables.

func (Matcher) At 

func (m Matcher) At(v Var) Matcher

At binds the reported node to a named submatch. If no explicit location is given, the outermost node ($$) is used.

func (Matcher) Deadcode added in v0.3.9 

func (m Matcher) Deadcode() bool

Deadcode reports whether this match is contained inside a dead code path.

func (Matcher) Do added in v0.3.17 

func (m Matcher) Do(fn func(*DoContext)) Matcher

func (Matcher) File 

func (m Matcher) File() File

File returns the current file context.

func (Matcher) GoVersion added in v0.3.8 

func (m Matcher) GoVersion() GoVersion

GoVersion returns the analyzer associated target Go language version.

func (Matcher) Import 

func (m Matcher) Import(pkgPath string)

Import loads given package path into a rule group imports table.

That table is used during the rules compilation.

The table has the following effect on the rules:

  • For type expressions, it's used to resolve the full package paths of qualified types, like `foo.Bar`. If Import(`a/b/foo`) is called, `foo.Bar` will match `a/b/foo.Bar` type during the pattern execution.

func (Matcher) Match 

func (m Matcher) Match(pattern string, alternatives ...string) Matcher

Match specifies a set of patterns that match a rule being defined. Pattern matching succeeds if at least 1 pattern matches.

If none of the given patterns matched, rule execution stops.

func (Matcher) MatchComment added in v0.3.2 

func (m Matcher) MatchComment(pattern string, alternatives ...string) Matcher

MatchComment is like Match, but handles only comments and uses regexp patterns.

Multi-line /**/ comments are passed as a single string. Single-line // comments are passed line-by-line.

Hint: if you want to match a plain text and don't want to do meta char escaping, prepend `\Q` to your pattern. `\Qf(x)` will match `f(x)` as a plain text and there is no need to escape the `(` and `)` chars.

Named regexp capture groups can be accessed using the usual indexing notation.

Given this pattern: 

`(?P<first>\d+)\.(\d+).(?P<second>\d+)`

And this input comment: `// 14.6.600`

We'll get these submatches: 

m["$$"] => `14.6.600`
m["first"] => `14`
m["second"] => `600`

All usual filters can be applied: 

Where(!m["first"].Text.Matches(`foo`))

You can use this to reject some matches (allow-list behavior).

func (Matcher) Report 

func (m Matcher) Report(message string) Matcher

Report prints a message if associated rule match is successful.

A message is a string that can contain interpolated expressions. For every matched variable it's possible to interpolate their printed representation into the message text with $<name>. An entire match can be addressed with $$.

func (Matcher) Suggest 

func (m Matcher) Suggest(suggestion string) Matcher

Suggest assigns a quickfix suggestion for the matched code.

func (Matcher) Where 

func (m Matcher) Where(cond bool) Matcher

Where applies additional constraint to a match. If a given cond is not satisfied, a match is rejected and rule execution stops.

type Node added in v0.3.7 

type Node struct{}

Node represents an AST node somewhere inside a match. Unlike MatchedNode, it doesn't have to be associated with a named submatch.

func (Node) Is added in v0.3.7 

func (Node) Is(typ string) bool

Is reports whether a node AST type is compatible with the specified type. See `MatchedNode.Is` for the full reference.

type SinkType added in v0.3.19 

type SinkType struct{}

func (SinkType) Is added in v0.3.19 

func (SinkType) Is(typ string) bool

Is reports whether a type is identical to a given type. Works like ExprType.Is method.

type String 

type String string

String represents an arbitrary string-typed data.

func (String) Matches 

func (String) Matches(pattern string) bool

Matches reports whether a string matches the given regexp pattern.

type TypesObject added in v0.3.5 

type TypesObject struct{}

TypesObject is a types.Object mapping.

func (TypesObject) Is added in v0.3.5 

func (TypesObject) Is(typ string) bool

Is reports whether an associated types.Object is compatible with the specified type. A valid argument is a types.Object type name from the "go/types" package. Examples: "Func", "Var", "Const", "TypeName", "Label", "PkgName", "Builtin", "Nil" See https://golang.org/pkg/go/types/.

func (TypesObject) IsGlobal added in v0.3.16 

func (TypesObject) IsGlobal() bool

IsGlobal reports whether an associated types.Object is defined in global scope.

func (TypesObject) IsVariadicParam added in v0.3.22 

func (TypesObject) IsVariadicParam() bool

IsVariadicParam reports whether this object represents a function variadic param. This property is not propagated between the assignments.

type Var 

type Var struct {
	// Pure reports whether expr matched by var is side-effect-free.
	Pure bool

	// Const reports whether expr matched by var is a constant value.
	Const bool

	// ConstSlice reports whether expr matched by var is a slice literal
	// consisting of contant elements.
	//
	// We need a separate Const-like predicate here because Go doesn't
	// treat slices of const elements as constants, so including
	// them in Const would be incorrect.
	// Use `m["x"].Const || m["x"].ConstSlice` when you need
	// to have extended definition of "constant value".
	//
	// Some examples:
	//     []byte("foo") -- constant byte slice
	//     []byte{'f', 'o', 'o'} -- same constant byte slice
	//     []int{1, 2} -- constant int slice
	ConstSlice bool

	// Value is a compile-time computable value of the expression.
	Value ExprValue

	// Addressable reports whether the corresponding expression is addressable.
	// See https://golang.org/ref/spec#Address_operators.
	Addressable bool

	// Comparable reports whether the corresponding expression value is comparable.
	// See https://pkg.go.dev/go/types#Comparable.
	Comparable bool

	// Type is a type of a matched expr.
	//
	// For function call expressions, a type is a function result type,
	// but for a function expression itself it's a *types.Signature.
	//
	// Suppose we have a `a.b()` expression:
	//	`$x()` m["x"].Type is `a.b` function type
	//	`$x` m["x"].Type is `a.b()` function call result type
	Type ExprType

	SinkType SinkType

	// Object is an associated "go/types" Object.
	Object TypesObject

	// Text is a captured node text as in the source code.
	Text MatchedText

	// Node is a captured AST node.
	Node MatchedNode

	// Line is a source code line number that contains this match.
	// If this match is multi-line, this is the first line number.
	Line int
}

Var is a pattern variable that describes a named submatch.

func (Var) Contains added in v0.3.14 

func (Var) Contains(pattern string) bool

Contains runs a sub-search from a given pattern using the captured vars from the original pattern match.

For example, given the Match(`$lhs = append($lhs, $x)`) pattern, we can do m["lhs"].Contains(`$x`) and learn whether $lhs contains $x as its sub-expression.

Experimental: this function is not part of the stable API.

func (Var) Filter 

func (Var) Filter(pred func(*VarFilterContext) bool) bool

Filter applies a custom predicate function on a submatch.

The callback function should use VarFilterContext to access the information that is usually accessed through Var. For example, `VarFilterContext.Type` is mapped to `Var.Type`.

type VarFilterContext 

type VarFilterContext struct {
	// Type is mapped to Var.Type field.
	Type types.Type
}

VarFilterContext carries Var and environment information into the filter function. It's an input parameter type for the Var.Filter function callback.

func (*VarFilterContext) GetInterface 

func (*VarFilterContext) GetInterface(name typeName) *types.Interface

GetInterface finds a type value that represents an interface by a given name. Works like `types.AsInterface(ctx.GetType(name))`.

func (*VarFilterContext) GetType 

func (*VarFilterContext) GetType(name typeName) types.Type

GetType finds a type value by a given name. If a type can't be found (or a name is malformed), this function panics.

func (*VarFilterContext) SizeOf 

func (*VarFilterContext) SizeOf(x types.Type) int

SizeOf returns the size of the given type. It uses the ruleguard.Context.Sizes to calculate the result.

Source Files

View all Source files

Directories

Path Synopsis
fluent module
Package types mimics the https://golang.org/pkg/go/types/ package.
 Package types mimics the https://golang.org/pkg/go/types/ package.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.