capabilities

Documentation

Overview

Package capabilities implements the algorithms for checking capabilities in a lingolang program. It is loosely modelled after the API of the standard go/types package, which implements type checking.

Index

• Variables
• type Borrowed
• type Checker
  • func NewChecker(conf *Config, info *Info, path string, fset *token.FileSet) *Checker
  • func (c *Checker) Files(files []*ast.File) (err error)
• type Config
  • func (conf *Config) Check(path string, fset *token.FileSet, files []*ast.File, info *Info) error
• type Info
• type Interpreter
  • func (i *Interpreter) Assert(node ast.Node, subject permission.Permission, has permission.BasePermission)
  • func (i *Interpreter) Error(node ast.Node, format string, args ...interface{}) (permission.Permission, Owner, []Borrowed, Store)
  • func (i *Interpreter) Release(node ast.Node, st Store, undo []Borrowed) Store
  • func (i *Interpreter) VisitExpr(st Store, e ast.Expr) (permission.Permission, Owner, []Borrowed, Store)
• type Owner
• type StmtExit
• type Store
  • func NewStore() Store
  • func (st Store) BeginBlock() Store
  • func (st Store) Define(name string, perm permission.Permission) (Store, error)
  • func (st Store) EndBlock() Store
  • func (st Store) Equal(ot Store) bool
  • func (st Store) GetEffective(name string) permission.Permission
  • func (st Store) GetMaximum(name string) permission.Permission
  • func (st Store) Merge(st2 Store) (Store, error)
  • func (st Store) SetEffective(name string, perm permission.Permission) (Store, error)
  • func (st Store) SetMaximum(name string, perm permission.Permission) (Store, error)

Variables

var NoOwner = Owner{}

NoOwner is the zero value for Owner.

Types

type Borrowed

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

Borrowed describes a variable that had to be borrowed from, along with it's associated original permission.

type Checker

type Checker struct {

	// Errors occured during capability checking.
	Errors []error
	// contains filtered or unexported fields
}

Checker is a type that keeps shared state from multiple check passes. It must be created by NewChecker().

func NewChecker

func NewChecker(conf *Config, info *Info, path string, fset *token.FileSet) *Checker

NewChecker returns a new checker with the specified settings.

func (*Checker) Files

func (c *Checker) Files(files []*ast.File) (err error)

Files performs the checks the checker was set up for.

Returns the first error, if any. More errors can be found in the Errors field.

type Config

type Config struct {
	// Parent value from the types package.
	Types types.Config
}

Config configures the capability checker.

func (*Config) Check

func (conf *Config) Check(path string, fset *token.FileSet, files []*ast.File, info *Info) error

Check performs a capability check on a package.

type Info

type Info struct {
	// Parent object from the types package.
	Types types.Info

	// Permissions associates nodes with permissions.
	Permissions map[ast.Node]permission.Permission

	// Errors occured during capability checking.
	Errors []error
}

Info stores the results of a capability check.

type Interpreter

type Interpreter struct {
	AnnotatedPermissions map[ast.Expr]permission.Permission
	// contains filtered or unexported fields
}

Interpreter interprets a given statement or expression.

func (*Interpreter) Assert

func (i *Interpreter) Assert(node ast.Node, subject permission.Permission, has permission.BasePermission)

func (*Interpreter) Error

func (i *Interpreter) Error(node ast.Node, format string, args ...interface{}) (permission.Permission, Owner, []Borrowed, Store)

Assert asserts that the base permissions of subject are a superset or the same as has.

func (*Interpreter) Release

func (i *Interpreter) Release(node ast.Node, st Store, undo []Borrowed) Store

Release Releases all borrowed objects, and restores their previous permissions.

func (*Interpreter) VisitExpr

func (i *Interpreter) VisitExpr(st Store, e ast.Expr) (permission.Permission, Owner, []Borrowed, Store)

VisitExpr abstractly interprets permission changes by the expression.

type Owner

type Owner Borrowed

Owner is an alias for Borrowed indicating that this is the owning object of the expression result.

type StmtExit

type StmtExit struct {
	Store
	// contains filtered or unexported fields
}

StmtExit is a store with an optional field specifying any early exit from a block, like a return, goto, or a continue. The idea is simple: Each block handler checks if it should handle such a branch, and do that or pass it up to the upper layer.

type Store

type Store []struct {
	// contains filtered or unexported fields
}

Store associates variables with permissions for the abstract interpreter.

Store essentially maps identifiers in the program to permissions; an effective, and a maximum one. As a special case, if ident is nil, the item acts marks the beginning of a new frame.

func NewStore

func NewStore() Store

NewStore returns a new, empty Store

func (Store) BeginBlock

func (st Store) BeginBlock() Store

BeginBlock copies the Store, prepending a frame marker at the beginning.

func (Store) Define

func (st Store) Define(name string, perm permission.Permission) (Store, error)

Define defines an identifier in the current block. If the current block already contains a variable of the same name, no new variable is created, but the existing one is assigned by calling SetEffective().

func (Store) EndBlock

func (st Store) EndBlock() Store

EndBlock returns a slice of the input describing the parent block.

func (Store) Equal

func (st Store) Equal(ot Store) bool

Equal checks if two Stores are equal

func (Store) GetEffective

func (st Store) GetEffective(name string) permission.Permission

GetEffective returns the effective permission for the identifier

func (Store) GetMaximum

func (st Store) GetMaximum(name string) permission.Permission

GetMaximum returns the maximum permission for the identifier

func (Store) Merge

func (st Store) Merge(st2 Store) (Store, error)

Merge merges two Stores describing two different branches in the code. The Stores must be defined in the same order.

func (Store) SetEffective

func (st Store) SetEffective(name string, perm permission.Permission) (Store, error)

SetEffective changes the permissions associated with an ident.

The effective permission is limited to the maximum permission that the variable can have.

func (Store) SetMaximum

func (st Store) SetMaximum(name string, perm permission.Permission) (Store, error)

SetMaximum changes the maximum permissions associated with an ident.

Lowering the maximum permission also lowers the effective permission if they would otherwise exceed the maximum.