Skip to content
Permalink
Browse files

Reformat Go comments for godoc

  • Loading branch information...
thesephist committed Aug 11, 2019
1 parent 2e02174 commit b7d33da4ddf6509c2fea6baa9ecab11709f16a46
Showing with 69 additions and 69 deletions.
  1. +2 −2 pkg/ink/error.go
  2. +36 −36 pkg/ink/eval.go
  3. +12 −12 pkg/ink/lexer.go
  4. +10 −10 pkg/ink/parser.go
  5. +9 −9 pkg/ink/runtime.go
@@ -1,7 +1,7 @@
package ink

// Error reasons are enumerated here to be used in the Err struct,
// the error type shared across all Ink APIs.
// the error type shared across all Ink APIs.
const (
ErrUnknown = 0
ErrSyntax = 1
@@ -11,7 +11,7 @@ const (
)

// Err constants represent possible errors that Ink interpreter
// binding functions may return.
// binding functions may return.
type Err struct {
reason int
message string
@@ -12,24 +12,24 @@ import (
)

// Value represents any value in the Ink programming language.
// Each value corresponds to some primitive or object value created
// during the execution of an Ink program.
// Each value corresponds to some primitive or object value created
// during the execution of an Ink program.
type Value interface {
String() string
// Equals reports whether the given value is deep-equal to the
// receiving value. It does not compare references.
// receiving value. It does not compare references.
Equals(Value) bool
}

func isIntable(n NumberValue) bool {
// XXX: not the most reliable check for int because of int64 range
// limitations, but works for now until we nail down Ink's number
// spec more rigorously
// limitations, but works for now until we nail down Ink's number
// spec more rigorously
return n == NumberValue(int64(n))
}

// Utility func to get a consistent, language spec-compliant
// string representation of numbers
// string representation of numbers
func nToS(f float64) string {
if i := int64(f); f == float64(i) {
return strconv.FormatInt(i, 10)
@@ -44,7 +44,7 @@ func nvToS(v NumberValue) string {
}

// EmptyValue is the value of the empty identifier.
// it is globally unique and matches everything in equality.
// it is globally unique and matches everything in equality.
type EmptyValue struct{}

func (v EmptyValue) String() string {
@@ -56,7 +56,7 @@ func (v EmptyValue) Equals(other Value) bool {
}

// NumberValue represents the number type (integer and floating point)
// in the Ink language.
// in the Ink language.
type NumberValue float64

func (v NumberValue) String() string {
@@ -120,7 +120,7 @@ func (v BooleanValue) Equals(other Value) bool {
}

// NullValue is a value that only exists at the type level,
// and is represented by the empty expression list `()`.
// and is represented by the empty expression list `()`.
type NullValue struct{}

func (v NullValue) String() string {
@@ -170,15 +170,15 @@ func (v CompositeValue) Equals(other Value) bool {
}

// FunctionValue is the value of any variables referencing functions
// defined in an Ink program.
// defined in an Ink program.
type FunctionValue struct {
defn *FunctionLiteralNode
parentFrame *StackFrame
}

func (v FunctionValue) String() string {
// ellipsize function body at a reasonable length,
// so as not to be too verbose in repl environments
// so as not to be too verbose in repl environments
fstr := v.defn.String()
if len(fstr) < 120 {
return fstr
@@ -194,15 +194,15 @@ func (v FunctionValue) Equals(other Value) bool {

if ov, ok := other.(FunctionValue); ok {
// to compare structs containing slices, we really want
// a pointer comparison, not a value comparison
// a pointer comparison, not a value comparison
return v.defn == ov.defn
} else {
return false
}
}

// FunctionCallThunkValue is an internal representation of a lazy
// function evaluation used to implement tail call optimization.
// function evaluation used to implement tail call optimization.
type FunctionCallThunkValue struct {
vt ValueTable
function FunctionValue
@@ -219,7 +219,7 @@ func (v FunctionCallThunkValue) Equals(other Value) bool {

if ov, ok := other.(FunctionCallThunkValue); ok {
// to compare structs containing slices, we really want
// a pointer comparison, not a value comparison
// a pointer comparison, not a value comparison
return &v.vt == &ov.vt && &v.function == &ov.function
} else {
return false
@@ -477,8 +477,8 @@ func (n BinaryExprNode) Eval(frame *StackFrame, allowThunk bool) (Value, error)
case StringValue:
if right, ok := rightValue.(StringValue); ok {
// In this context, strings are immutable. i.e. concatenating
// strings should produce a completely new string whose modifications
// won't be observable by the original strings.
// strings should produce a completely new string whose modifications
// won't be observable by the original strings.
base := make([]byte, 0, len(left)+len(right))
base = append(base, left...)
return StringValue(append(base, right...)), nil
@@ -703,8 +703,8 @@ func evalInkFunction(fn Value, allowThunk bool, args ...Value) (Value, error) {
}

// TCO: used for evaluating expressions that may be in tail positions
// at the end of Nodes whose evaluation allocates another StackFrame
// like ExpressionList and FunctionLiteral's body
// at the end of Nodes whose evaluation allocates another StackFrame
// like ExpressionList and FunctionLiteral's body
returnThunk := FunctionCallThunkValue{
vt: argValueTable,
function: fnt,
@@ -748,7 +748,7 @@ func (n MatchExprNode) Eval(frame *StackFrame, allowThunk bool) (Value, error) {
}

// match expression clauses are tail call optimized,
// so return a maybe ThunkValue
// so return a maybe ThunkValue
return rv, nil
}
}
@@ -775,7 +775,7 @@ func (n ExpressionListNode) Eval(frame *StackFrame, allowThunk bool) (Value, err
}

// return values of expression lists are tail call optimized,
// so return a maybe ThunkValue
// so return a maybe ThunkValue
return n.expressions[length-1].Eval(callFrame, allowThunk)
}

@@ -848,11 +848,11 @@ func (n FunctionLiteralNode) Eval(frame *StackFrame, allowThunk bool) (Value, er
}

// ValueTable is used anytime a map of names/labels to Ink Values is needed,
// and is notably used to represent stack frames / heaps and CompositeValue dictionaries.
// and is notably used to represent stack frames / heaps and CompositeValue dictionaries.
type ValueTable map[string]Value

// StackFrame represents the heap of variables local to a particular function call frame,
// and recursively references other parent StackFrames internally.
// and recursively references other parent StackFrames internally.
type StackFrame struct {
parent *StackFrame
vt ValueTable
@@ -903,15 +903,15 @@ func (frame *StackFrame) String() string {
// Engine is a single global context of Ink program execution.
//
// A single thread of execution may run within an Engine at any given moment,
// and this is ensured by an internal execution lock. An execution's Engine
// also holds all permission and debugging flags.
// and this is ensured by an internal execution lock. An execution's Engine
// also holds all permission and debugging flags.
//
// Within an Engine, there may exist multiple Contexts that each contain different
// execution environments, running concurrently under a single lock.
// execution environments, running concurrently under a single lock.
type Engine struct {
// Listeners keeps track of the concurrent threads of execution running
// in the Engine. Call `Engine.Listeners.Wait()` to block until all concurrent
// execution threads finish on an Engine.
// in the Engine. Call `Engine.Listeners.Wait()` to block until all concurrent
// execution threads finish on an Engine.
Listeners sync.WaitGroup

// If FatalError is true, an error will halt the interpreter
@@ -920,7 +920,7 @@ type Engine struct {
Debug DebugConfig

// only a single function may write to the stack frames
// at any moment.
// at any moment.
evalLock sync.Mutex
}

@@ -941,7 +941,7 @@ func (eng *Engine) CreateContext() *Context {
}

// Context represents a single, isolated execution context with its global heap,
// imports, call stack, and cwd (working directory).
// imports, call stack, and cwd (working directory).
type Context struct {
// Cwd is an always-absolute path to current working dir (of module system)
Cwd string
@@ -953,7 +953,7 @@ type Context struct {
}

// LogErr logs an Err (interpreter error) according to the configurations
// specified in the Context's Engine.
// specified in the Context's Engine.
func (ctx *Context) LogErr(e Err) {
msg := e.message
if ctx.File != "" {
@@ -968,7 +968,7 @@ func (ctx *Context) LogErr(e Err) {
}

// PermissionsConfig defines Context's permissions to
// operating system interfaces
// operating system interfaces
type PermissionsConfig struct {
Read bool
Write bool
@@ -999,8 +999,8 @@ func (ctx *Context) resetWd() {
}

// Eval takes a channel of Nodes to evaluate, and executes the Ink programs defined
// in the syntax tree. Eval returns the last value of the last expression in the AST,
// or an error if there was a runtime error.
// in the syntax tree. Eval returns the last value of the last expression in the AST,
// or an error if there was a runtime error.
func (ctx *Context) Eval(nodes <-chan Node, dumpFrame bool) (val Value, err error) {
ctx.Engine.evalLock.Lock()
defer ctx.Engine.evalLock.Unlock()
@@ -1023,7 +1023,7 @@ func (ctx *Context) Eval(nodes <-chan Node, dumpFrame bool) (val Value, err erro
}

// ExecListener queues an asynchronous callback task to the Engine behind the Context.
// Callbacks registered this way will also run with the Engine's execution lock.
// Callbacks registered this way will also run with the Engine's execution lock.
func (ctx *Context) ExecListener(callback func()) {
ctx.Engine.Listeners.Add(1)
go func() {
@@ -1037,8 +1037,8 @@ func (ctx *Context) ExecListener(callback func()) {
}

// Exec runs an Ink program defined by an io.Reader.
// This is the main way to invoke Ink programs from Go.
// Exec blocks until the Ink program exits.
// This is the main way to invoke Ink programs from Go.
// Exec blocks until the Ink program exits.
func (ctx *Context) Exec(input io.Reader) (Value, error) {
eng := ctx.Engine

@@ -79,12 +79,12 @@ func (p position) String() string {
}

// Tok is the monomorphic struct representing all Ink program tokens
// in the lexer.
// in the lexer.
type Tok struct {
kind Kind
// str and num are both present to implement Tok
// as a monomorphic type for all tokens; will be zero
// values often.
// as a monomorphic type for all tokens; will be zero
// values often.
str string
num float64
position
@@ -242,8 +242,8 @@ func Tokenize(
strbuf += string(char)
} else if char == '\\' {
// backslash escapes like in most other languages,
// so just consume whatever the next char is into
// the current string buffer
// so just consume whatever the next char is into
// the current string buffer
c, _, err := buffered.ReadRune()
if err != nil {
break
@@ -318,12 +318,12 @@ func Tokenize(
commitChar(Separator)
case char == '.':
// only non-AccessorOp case is [Number token] . [Number],
// so we commit and bail early if the buf is empty or contains
// a clearly non-numeric token. Note that this means all numbers
// must start with a digit. i.e. .5 is not 0.5 but a syntax error.
// This is the case since we don't know what the last token was,
// and I think streaming parse is worth the tradeoffs of losing
// that context.
// so we commit and bail early if the buf is empty or contains
// a clearly non-numeric token. Note that this means all numbers
// must start with a digit. i.e. .5 is not 0.5 but a syntax error.
// This is the case since we don't know what the last token was,
// and I think streaming parse is worth the tradeoffs of losing
// that context.
committed := false
for _, d := range buf {
if !unicode.IsDigit(d) {
@@ -352,7 +352,7 @@ func Tokenize(
commitChar(MatchColon)
} else {
// key is parsed as expression, so make sure
// we mark expression end (Separator)
// we mark expression end (Separator)
ensureSeparator()
commitChar(KeyValueSeparator)
buffered.UnreadRune()

0 comments on commit b7d33da

Please sign in to comment.
You can’t perform that action at this time.