annotations

Documentation

Index

• Constants
• type Annotation
  • func (a Annotation) IsMatchingAnnotation(kind AnnotationKind, tag string) bool
• type AnnotationKind
• type FunctionAnnotation
  • func (fa FunctionAnnotation) ContentKeys() map[string]bool
  • func (fa FunctionAnnotation) Mains() []Annotation
  • func (fa FunctionAnnotation) Params() map[*ssa.Parameter][]Annotation
• type LinePos
  • func NewLinePos(pos token.Position) LinePos
  • func (l LinePos) String() string
• type ProgramAnnotations
  • func LoadAnnotations(logger *config.LogGroup, packages []*ssa.Package) (ProgramAnnotations, error)
  • func (pa ProgramAnnotations) CompleteFromSyntax(logger *config.LogGroup, pkg *packages.Package)
  • func (pa ProgramAnnotations) Count() int
  • func (pa ProgramAnnotations) IsIgnoredPos(pos token.Position, tag string) bool
  • func (pa ProgramAnnotations) Iter(fx func(a Annotation))
• type TargetSpecifier

Constants

const AnyTag = "_"

AnyTag is the special tag used to match any other tag

Types

type Annotation

type Annotation struct {
	// Kind of the annotation
	Kind AnnotationKind
	// Tags of the annotation (usually parsed from a comma-separated list of strings)
	Tags []string
}

Annotation contains the parsed content from an annotation component: the kind of the annotation and its arguments The syntax of an annotation is usually <Kind>(<Comma separated contents>).

func (Annotation) IsMatchingAnnotation

func (a Annotation) IsMatchingAnnotation(kind AnnotationKind, tag string) bool

IsMatchingAnnotation returns true when the annotation matches the kind and tag provided. Returns true when the kinds are equal and either: - the tag provided is _ - the annotation has a tag _ - the annotation's tags contains the provided tag

type AnnotationKind

type AnnotationKind = int

AnnotationKind characterizes the kind of annotations that can be used in the program.

const (
	// Sink is the kind of Sink(...) annotations.
	Sink AnnotationKind = iota
	// Source is the kind of Source(...) annotations
	Source
	// Sanitizer is the kind of Sanitizer(...) annotations
	Sanitizer
	// SetOptions is the kind of SetOptions(...) annotations
	SetOptions
	// Ignore is an empty annotation for a line
	Ignore
)

type FunctionAnnotation

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

A FunctionAnnotation groups the annotations relative to a function into main annotations for the entire function and parameter annotations for each parameter

func (FunctionAnnotation) ContentKeys

func (fa FunctionAnnotation) ContentKeys() map[string]bool

ContentKeys returns the content keys in the annotations

func (FunctionAnnotation) Mains

func (fa FunctionAnnotation) Mains() []Annotation

Mains returns the main annotations of the function

func (FunctionAnnotation) Params

func (fa FunctionAnnotation) Params() map[*ssa.Parameter][]Annotation

Params returns the map of parameters to annotations in the function

type LinePos

type LinePos struct {
	Line int
	File string
}

LinePos is a simple line-file position indicator.

func NewLinePos

func NewLinePos(pos token.Position) LinePos

NewLinePos returns a LinePos from a token position. The column and offset are abstracted away.

func (LinePos) String

func (l LinePos) String() string

type ProgramAnnotations

type ProgramAnnotations struct {
	// Configs is the map of configuration annotations, mapping problem tags to config settings
	Configs map[string]map[string]string
	// Funcs is the map of function annotations
	Funcs map[*ssa.Function]FunctionAnnotation
	// Types is the map of type annotations (TODO: implementation)
	Types map[*ssa.Type][]Annotation
	// Consts is the map of named constant annotations (TODO: implementation)
	Consts map[*ssa.NamedConst][]Annotation
	// Globals is the map of global variable annotations (TODO: implementation)
	Globals map[*ssa.Global][]Annotation
	// Positional is the map of line-file location to annotations that are not attached to a specific construct.
	// There can be only one annotation per line.
	Positional map[LinePos]Annotation
}

ProgramAnnotations groups all the program annotations together. Members of packages can be annotated: - function annotations are in Funcs - type annotations are in Types - constants annotations are in Consts - global variable annotations are in Globals

func LoadAnnotations

func LoadAnnotations(logger *config.LogGroup, packages []*ssa.Package) (ProgramAnnotations, error)

LoadAnnotations loads annotations from a list of packages by inspecting the syntax of each element in the packages. If syntax is not provided, no annotation will be loaded (you should build the program with the syntax for the annotations to work). Returns an error when some annotation could not be loaded (instead of silently skipping). Those errors should be surfaced to the user, since it is the only way they can correct their annotations. The loading function will also print warnings when some syntactic components of the comments look like they should be an annotation.

func (ProgramAnnotations) CompleteFromSyntax

func (pa ProgramAnnotations) CompleteFromSyntax(logger *config.LogGroup, pkg *packages.Package)

CompleteFromSyntax takes a set of program annotations and adds additional non-ssa linked annotations to the annotations

func (ProgramAnnotations) Count

func (pa ProgramAnnotations) Count() int

Count returns the total number of annotations in the program

func (ProgramAnnotations) IsIgnoredPos

func (pa ProgramAnnotations) IsIgnoredPos(pos token.Position, tag string) bool

IsIgnoredPos returns true when the given position is on the same line as an //argot:ignore annotation.

func (ProgramAnnotations) Iter

func (pa ProgramAnnotations) Iter(fx func(a Annotation))

Iter iterates over all annotations in the program.

type TargetSpecifier

type TargetSpecifier = string

TargetSpecifier is the type of target specifiers in the annotations: an annotation is of the shape "//argot:<target specifier> <target specifier arguments>* <annotations>

const (
	// ParamTarget is the specifier for function parameter targets
	ParamTarget TargetSpecifier = "param"
	// FunctionTarget is the specifier for function targets
	FunctionTarget TargetSpecifier = "function"
	// IgnoreTarget is the specifier for ignore targets
	IgnoreTarget TargetSpecifier = "ignore"
	// ConfigTarget is the specifier for config targets
	ConfigTarget TargetSpecifier = "config"
)