annotation

README

Type Comments

In a function:

function(a/*:type*/, b/*:type*/, c/*:type*/=null) /*:return*/

In an object definition:

{
    a: /*:type*/ null,
    b: /*:type*/ null,
    fn(a/*:type*/, b/*:type*/, c/*:type*/=null): /*:return*/
        null,
}

Examples

local joinStr(arr/*:array[string]*/, sep/*:string*/) /*:string*/ =
    std.join(arr, sep);

// If widget is used as a template, there will be a warning if a is not overridden
local Widget = {
    a: /*:number*/ null,
    a: /*:number | null*/ null,
};

local addWidget(w/*:Widget*/, x/*:number*/) /*:number*/ = 
    x + w.a + (if w.b == null then 0 else w.b);

Local variables are inferred from the result of their assignment.

• Caveat: extvars, maybe imports?

Type Format

ident
dotted-var := ident ( "." ident )+
type-atom := 
    bool-lit | 
    number-lit | 
    string-lit |
    any |
    null |
    boolean | 
    string | 
    number | 
    function | 
    array ( "[" type-decl "]") | 
    object ( "[" type-decl "]") |
    dotted-var
type-decl := type-atom ( "|" type-atom )+

• For array and object, they optionally can have an element type specified like array[string] or object[null | string].
• If a variable is referenced, it must:
  • Be a function, whose signature will be used as a function template.
  • Be an object, whose shape will be used as a struct signature.
• If a literal is specified, the inputs must match that value.

Type Parameters

function(a: A, b: array[B]) -> B

// Not allowed for now, no type params in unions
function(a: A | B) -> A

function(fn: function(agg: T, elem: E) -> T, arr: array[E], init: T) -> T

function(arr: array[E], keyFn: function(E) -> string) -> object[array[E]]

Rules

• No type parameters in unions (or types inside unions)
• Non-function parameters can only include one type parameter (same with return types)
• A type parameter in the return must also exist in the parameters

Evaluation

• Treat everything (including conditionals, binops, unops) as functions
• evaluate the typehints and inferred types in parallel
• lint warning if the typehints across values don't match
• lint warning if the inferred type and typehint on a single value don't match
• for refinement, add overlay on varmap that changes variable types

Documentation

Index

• type ArrayNode
  • func (n *ArrayNode) String() string
  • func (n *ArrayNode) TypeParameters() []string
• type BooleanNode
  • func (n *BooleanNode) String() string
  • func (*BooleanNode) TypeParameters() []string
• type DottedIdentNode
  • func (n *DottedIdentNode) String() string
  • func (*DottedIdentNode) TypeParameters() []string
• type FunctionNode
  • func (n *FunctionNode) String() string
  • func (n *FunctionNode) TypeParameters() []string
• type IdentNode
  • func (n *IdentNode) String() string
  • func (*IdentNode) TypeParameters() []string
• type Node
  • func Parse(text string) (Node, error)
• type NullNode
  • func (n *NullNode) String() string
  • func (*NullNode) TypeParameters() []string
• type NumberNode
  • func (n *NumberNode) String() string
  • func (*NumberNode) TypeParameters() []string
• type ObjectNode
  • func (n *ObjectNode) String() string
  • func (n *ObjectNode) TypeParameters() []string
• type ParamNode
  • func (n *ParamNode) String() string
  • func (n *ParamNode) TypeParameters() []string
• type StringNode
  • func (n *StringNode) String() string
  • func (*StringNode) TypeParameters() []string
• type Token
  • func (t Token) String() string
• type TypeParameterNode
  • func (n *TypeParameterNode) String() string
  • func (*TypeParameterNode) TypeParameters() []string
• type UnionNode
  • func (n *UnionNode) String() string
  • func (n *UnionNode) TypeParameters() []string

Types

type ArrayNode

type ArrayNode struct {
	ElementType Node
	// contains filtered or unexported fields
}

func (*ArrayNode) String

func (n *ArrayNode) String() string

func (*ArrayNode) TypeParameters

func (n *ArrayNode) TypeParameters() []string

type BooleanNode

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

func (*BooleanNode) String

func (n *BooleanNode) String() string

func (*BooleanNode) TypeParameters

func (*BooleanNode) TypeParameters() []string

type DottedIdentNode

type DottedIdentNode struct {
	Names []string
	// contains filtered or unexported fields
}

func (*DottedIdentNode) String

func (n *DottedIdentNode) String() string

func (*DottedIdentNode) TypeParameters

func (*DottedIdentNode) TypeParameters() []string

type FunctionNode

type FunctionNode struct {
	Params []ParamNode
	Return Node
	// contains filtered or unexported fields
}

func (*FunctionNode) String

func (n *FunctionNode) String() string

func (*FunctionNode) TypeParameters

func (n *FunctionNode) TypeParameters() []string

type IdentNode

type IdentNode struct {
	Name string
	// contains filtered or unexported fields
}

func (*IdentNode) String

func (n *IdentNode) String() string

func (*IdentNode) TypeParameters

func (*IdentNode) TypeParameters() []string

type Node

type Node interface {
	String() string
	TypeParameters() []string
	// contains filtered or unexported methods
}

func Parse

func Parse(text string) (Node, error)

type NullNode

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

func (*NullNode) String

func (n *NullNode) String() string

func (*NullNode) TypeParameters

func (*NullNode) TypeParameters() []string

type NumberNode

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

func (*NumberNode) String

func (n *NumberNode) String() string

func (*NumberNode) TypeParameters

func (*NumberNode) TypeParameters() []string

type ObjectNode

type ObjectNode struct {
	ElementType Node
	Fields      []ParamNode
	// contains filtered or unexported fields
}

func (*ObjectNode) String

func (n *ObjectNode) String() string

func (*ObjectNode) TypeParameters

func (n *ObjectNode) TypeParameters() []string

type ParamNode

type ParamNode struct {
	Name string
	Type Node
	// contains filtered or unexported fields
}

func (*ParamNode) String

func (n *ParamNode) String() string

func (*ParamNode) TypeParameters

func (n *ParamNode) TypeParameters() []string

type StringNode

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

func (*StringNode) String

func (n *StringNode) String() string

func (*StringNode) TypeParameters

func (*StringNode) TypeParameters() []string

type Token

type Token int

TokenType represents the type of a token.

const (
	ILLEGAL Token = iota
	EOF
	SPACE // whitespace
	IDENT // main, foo, bar, x, y, etc.
	// operators and delimiters
	DOT           // .
	COMMA         // ,
	BRACE_OPEN    // {
	BRACE_CLOSE   // }
	BRACKET_OPEN  // [
	BRACKET_CLOSE // ]
	PAREN_OPEN    // (
	PAREN_CLOSE   // )
	COLON         // :
	ARROW         // ->
	UNION         // |
	// keywords
	ARRAY
	OBJECT
	FUNCTION
)

func (Token) String

func (t Token) String() string

type TypeParameterNode

type TypeParameterNode struct {
	Name string
	// contains filtered or unexported fields
}

func (*TypeParameterNode) String

func (n *TypeParameterNode) String() string

func (*TypeParameterNode) TypeParameters

func (*TypeParameterNode) TypeParameters() []string

type UnionNode

type UnionNode struct {
	Types []Node
	// contains filtered or unexported fields
}

func (*UnionNode) String

func (n *UnionNode) String() string

func (*UnionNode) TypeParameters

func (n *UnionNode) TypeParameters() []string