dsl
packagemodule
This package is not in the latest version of its module.
Details
Validgo.mod file
The Go module system was introduced in Go 1.11 and is the official dependency management solution for Go.
- Redistributable license
Redistributable licenses place minimal restrictions on how software can be used, modified, and redistributed.
- Tagged version
Modules with tagged versions give importers more predictable builds.
Stable versionWhen a project reaches major version v1 it is considered stable.
- Learn more about best practices
Repository
Links
Open Source Insights
Documentation¶
Index¶
- func ImportRules(prefix string, bundle Bundle)
- type Bundle
- type DoContext
- type DoVar
- type ExprType
- func (ExprType) AssignableTo(typ string) bool
- func (ExprType) ConvertibleTo(typ string) bool
- func (ExprType) HasMethod(fn string) bool
- func (ExprType) HasPointers() bool
- func (ExprType) IdenticalTo(v Var) bool
- func (ExprType) Implements(typ typeName) bool
- func (ExprType) Is(typ string) bool
- func (ExprType) OfKind(kind string) bool
- func (ExprType) Underlying() ExprType
- type ExprValue
- type File
- type GoVersion
- type MatchedNode
- type MatchedText
- type Matcher
- func (m Matcher) At(v Var) Matcher
- func (m Matcher) Deadcode() bool
- func (m Matcher) Do(fn func(*DoContext)) Matcher
- func (m Matcher) File() File
- func (m Matcher) GoVersion() GoVersion
- func (m Matcher) Import(pkgPath string)
- func (m Matcher) Match(pattern string, alternatives ...string) Matcher
- func (m Matcher) MatchComment(pattern string, alternatives ...string) Matcher
- func (m Matcher) Report(message string) Matcher
- func (m Matcher) Suggest(suggestion string) Matcher
- func (m Matcher) Where(cond bool) Matcher
- type Node
- type SinkType
- type String
- type TypesObject
- type Var
- type VarFilterContext
Constants¶
This section is empty.
Variables¶
This section is empty.
Functions¶
funcImportRules¶
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 precautionmeasure before we understand how it should work better.If you need this feature, please open an issue at github.com/quasilyte/go-ruleguard.
Types¶
typeExprType¶
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.Sizeint}ExprType describes a type of a matcher expr.
func (ExprType)AssignableTo¶
AssignableTo reports whether a type is assign-compatible with a given type.Seehttps://golang.org/pkg/go/types/#AssignableTo.
func (ExprType)ConvertibleTo¶
ConvertibleTo reports whether a type is conversible to a given type.Seehttps://golang.org/pkg/go/types/#ConvertibleTo.
func (ExprType)HasMethod¶added inv0.3.13
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 inv0.3.12
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 aconservative result. It never returns "false" for a type thatactually contains a pointer.
So this function is mostly useful for !HasPointers() form.
func (ExprType)IdenticalTo¶added inv0.3.15
IdenticalTo applies types.Identical(this, v.Type) operation.Seehttps://golang.org/pkg/go/types/#Identical function documentation.
Experimental: this function is not part of the stable API.
func (ExprType)Implements¶
Implements reports whether a type implements a given interface.Seehttps://golang.org/pkg/go/types/#Implements.
func (ExprType)OfKind¶added inv0.3.11
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, uint64Note: "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 setof or-conditions with Is("uint8"), Is("uint16") and so on.
func (ExprType)Underlying¶
Underlying returns expression type underlying type.Seehttps://golang.org/pkg/go/types/#Type Underlying() method documentation.Readhttps://golang.org/ref/spec#Types section to learn more about underlying types.
typeExprValue¶
type ExprValue struct{}ExprValue describes a compile-time computable value of a matched expr.
typeFile¶
type File struct {// Name is a file base name.NameString// PkgPath is a file package path.// Examples: "io/ioutil", "strings", "github.com/quasilyte/go-ruleguard/dsl".PkgPathString}File represents the current Go source file.
typeGoVersion¶added inv0.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" usingthe associated methods.
func (GoVersion)Eq¶added inv0.3.8
Eq asserts that target Go version is equal to (==) specified version.
func (GoVersion)GreaterEqThan¶added inv0.3.8
GreaterEqThan asserts that target Go version is greater or equal than (>=) specified version.
func (GoVersion)GreaterThan¶added inv0.3.8
GreaterThan asserts that target Go version is greater than (>) specified version.
func (GoVersion)LessEqThan¶added inv0.3.8
LessEqThan asserts that target Go version is less or equal than (<=) specified version.
typeMatchedNode¶
type MatchedNode struct{}MatchedNode represents an AST node associated with a named submatch.
func (MatchedNode)Is¶
func (MatchedNode) Is(typstring)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".Seehttps://golang.org/pkg/go/ast/.
func (MatchedNode)Parent¶added inv0.3.7
func (MatchedNode) Parent()Node
Parent returns a matched node parent.
typeMatchedText¶
type MatchedTextstring
MatchedText represents a source text associated with a matched node.
func (MatchedText)Matches¶
func (MatchedText) Matches(patternstring)bool
Matches reports whether the text matches the given regexp pattern.
typeMatcher¶
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¶
At binds the reported node to a named submatch.If no explicit location is given, the outermost node ($$) is used.
func (Matcher)Deadcode¶added inv0.3.9
Deadcode reports whether this match is contained inside a dead code path.
func (Matcher)GoVersion¶added inv0.3.8
GoVersion returns the analyzer associated target Go language version.
func (Matcher)Import¶
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 thefull 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¶
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 inv0.3.2
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 textand 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¶
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 interpolatetheir printed representation into the message text with $<name>.An entire match can be addressed with $$.
typeNode¶added inv0.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.
typeTypesObject¶added inv0.3.5
type TypesObject struct{}TypesObject is a types.Object mapping.
func (TypesObject)Is¶added inv0.3.5
func (TypesObject) Is(typstring)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"Seehttps://golang.org/pkg/go/types/.
func (TypesObject)IsGlobal¶added inv0.3.16
func (TypesObject) IsGlobal()bool
IsGlobal reports whether an associated types.Object is defined in global scope.
func (TypesObject)IsVariadicParam¶added inv0.3.22
func (TypesObject) IsVariadicParam()bool
IsVariadicParam reports whether this object represents a function variadic param.This property is not propagated between the assignments.
typeVar¶
type Var struct {// Pure reports whether expr matched by var is side-effect-free.Purebool// Const reports whether expr matched by var is a constant value.Constbool// 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 sliceConstSlicebool// Value is a compile-time computable value of the expression.ValueExprValue// Addressable reports whether the corresponding expression is addressable.// Seehttps://golang.org/ref/spec#Address_operators.Addressablebool// Comparable reports whether the corresponding expression value is comparable.// Seehttps://pkg.go.dev/go/types#Comparable.Comparablebool// 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 typeTypeExprTypeSinkTypeSinkType// Object is an associated "go/types" Object.ObjectTypesObject// Text is a captured node text as in the source code.TextMatchedText// Node is a captured AST node.NodeMatchedNode// Line is a source code line number that contains this match.// If this match is multi-line, this is the first line number.Lineint}Var is a pattern variable that describes a named submatch.
func (Var)Contains¶added inv0.3.14
Contains runs a sub-search from a given pattern using the capturedvars 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 theinformation that is usually accessed through Var.For example, `VarFilterContext.Type` is mapped to `Var.Type`.
typeVarFilterContext¶
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.
Source Files
Directories