contracts

Documentation

Overview

Package contracts owns strict, versioned project semantic contracts.

Index

• Constants
• type Binding
• type Error
  • func (e *Error) Error() string
  • func (e *Error) Unwrap() error
• type File
• type Function
• type NilErrorRelation
• type NilState
• type Resolved
  • func Resolve(set Set, packages []*types.Package) (Resolved, error)
  • func (r Resolved) Bindings() []Binding
  • func (r Resolved) Len() int
  • func (r Resolved) Lookup(function *types.Func) (Function, bool)
• type ReturnAlias
• type Set
  • func ParseFiles(files []File) (Set, error)
  • func (s Set) CanonicalBytes() []byte
  • func (s Set) Empty() bool
  • func (s Set) Functions() []Function
• type Source

Constants

const (
	// Version is the only accepted semantic-contract schema version.
	Version = 1
	// MaxFiles bounds one project contract snapshot.
	MaxFiles = 32
	// MaxFunctions bounds declarations across one project contract snapshot.
	MaxFunctions = 4096
	// MaxIndices bounds one indexed effect list.
	MaxIndices = 64
	// MaxFileBytes bounds one contract file before decoding.
	MaxFileBytes = 1 << 20
	// MaxTotalBytes bounds all contract files before decoding.
	MaxTotalBytes = 4 << 20
)

Types

type Binding

type Binding struct {
	Function *types.Func
	Contract Function
}

Binding associates one loaded type object with its immutable contract.

type Error

type Error struct {
	Path    string
	Line    int
	Column  int
	Message string
	// contains filtered or unexported fields
}

Error is one contract-file diagnostic.

func (*Error) Error

func (e *Error) Error() string

func (*Error) Unwrap

func (e *Error) Unwrap() error

type File

type File struct {
	Path  string
	Bytes []byte
}

File is one exact contract-file version.

type Function

type Function struct {
	Symbol               string
	NoReturn             bool
	MustUse              []int
	Closes               []int
	TakesOwnership       []int
	CompletesTransaction []int
	InvokesCancellation  []int
	Blocking             bool
	NilError             []NilErrorRelation
	ReturnsAlias         []ReturnAlias
	Source               Source
}

Function describes configured semantics for one exact function or method.

type NilErrorRelation

type NilErrorRelation struct {
	Value           int
	Error           int
	WhenErrorNil    NilState
	WhenErrorNonNil NilState
}

NilErrorRelation describes a result state conditional on an error result.

type NilState

type NilState uint8

NilState is one explicitly configured nilness state.

const (
	NilStateUnknown NilState = iota
	NilStateNil
	NilStateNonNil
)

type Resolved

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

Resolved is an immutable lookup keyed by stable package-qualified identity.

func Resolve

func Resolve(set Set, packages []*types.Package) (Resolved, error)

Resolve binds declarations to exact functions available in a loaded type graph. Declarations for packages absent from the graph remain deferred. A declaration whose package is present but whose function or method is absent is invalid.

func (Resolved) Bindings

func (r Resolved) Bindings() []Binding

Bindings returns resolved functions in stable identity order.

func (Resolved) Len

func (r Resolved) Len() int

Len returns the number of contracts resolved against loaded packages.

func (Resolved) Lookup

func (r Resolved) Lookup(function *types.Func) (Function, bool)

Lookup returns an independently owned contract for one exact function.

type ReturnAlias

type ReturnAlias struct {
	Result   int
	Argument int
}

ReturnAlias states that one result aliases one argument.

type Set

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

Set is one immutable, canonical collection of project contracts.

func ParseFiles

func ParseFiles(files []File) (Set, error)

ParseFiles strictly decodes and canonicalizes one complete contract snapshot.

func (Set) CanonicalBytes

func (s Set) CanonicalBytes() []byte

CanonicalBytes returns a declaration-order and file-order independent identity.

func (Set) Empty

func (s Set) Empty() bool

Empty reports whether the snapshot contains no declarations.

func (Set) Functions

func (s Set) Functions() []Function

Functions returns independently owned declarations in symbol order.

type Source

type Source struct {
	Path     string
	Function int
	Line     int
	Column   int
}

Source identifies one declaration in a contract file.