add docs directory and move some documents from Wiki

2019-01-23 15:39:05 -08:00 · 2019-01-23 15:39:05 -08:00 · 2a144dc497
commit 2a144dc497
parent 4fd883616a
9 changed files with 805 additions and 0 deletions
--- a/docs/README.md
+++ b/docs/README.md
@ -0,0 +1,9 @@
+# The Tengo Language Documentation
+
+## Reference
+
+- [Tengo Objects](https://github.com/d5/tengo/blob/master/docs/objects.md)
+- [Runtime Types](https://github.com/d5/tengo/blob/master/docs/runtime-types.md)
+- [Builtin Functions](https://github.com/d5/tengo/blob/master/docs/builtins.md)
+- [Interoperability](https://github.com/d5/tengo/blob/master/docs/interoperability.md)
+- [Standard Libary](https://github.com/d5/tengo/blob/master/docs/stdlib.md) _(experimental)_
--- a/docs/builtins.md
+++ b/docs/builtins.md
@ -0,0 +1,162 @@
+# Builtin Functions
+
+## print
+
+Prints a string representation of the given variable to the standard output.
+
+```golang
+v := [1, 2, 3]
+print(v)  // "[1, 2, 3]"
+```
+
+## len
+
+Returns the number of elements if the given variable is array, string, map, or module map.
+
+```golang
+v := [1, 2, 3]
+l := len(v) // l == 3
+```
+
+## copy
+
+Creates a copy of the given variable. `copy` function calls `Object.Copy` interface method, which is expected to return a deep-copy of the value it holds.
+
+```golang
+v1 := [1, 2, 3]
+v2 := v1
+v3 := copy(v1)
+v1[1] = 0
+print(v2[1]) // "0"; 'v1' and 'v2' referencing the same array
+print(v3[1]) // "2"; 'v3' not affected by 'v1'
+```
+
+## append
+
+Appends object(s) to an array (first argument) and returns a new array object. (Like Go's `append` builtin.) Currently, this function takes array type only.
+
+```golang
+v := [1]
+v = append(v, 2, 3) // v == [1, 2, 3]
+```
+
+## string
+
+Tries to convert an object to string object. See [this](https://github.com/d5/tengo/wiki/Variable-Types) for more details on type conversion.
+
+```golang
+x := string(123) //  v == "123"
+```
+
+Optionally it can take the second argument, which will be returned if the first argument cannot be converted to string. Note that the second argument does not have to be string.
+
+```golang
+v = string(undefined, "foo")  // v == "foo"
+v = string(undefined, false)  // v == false 
+```
+
+## int
+
+Tries to convert an object to int object. See [this](https://github.com/d5/tengo/blob/master/docs/runtime-types.md) for more details on type conversion.
+
+```golang
+v := int("123") //  v == 123
+```
+
+Optionally it can take the second argument, which will be returned if the first argument cannot be converted to int. Note that the second argument does not have to be int.
+
+```golang
+v = int(undefined, 10)    // v == 10
+v = int(undefined, false) // v == false 
+```
+
+## bool
+
+Tries to convert an object to bool object. See [this](https://github.com/d5/tengo/blob/master/docs/runtime-types.md) for more details on type conversion.
+
+```golang
+v := bool(1) //  v == true
+```
+
+## float
+
+Tries to convert an object to float object. See [this](https://github.com/d5/tengo/blob/master/docs/runtime-types.md) for more details on type conversion.
+
+```golang
+v := float("19.84") //  v == 19.84
+```
+
+Optionally it can take the second argument, which will be returned if the first argument cannot be converted to float. Note that the second argument does not have to be float.
+
+```golang
+v = float(undefined, 19.84)    // v == 19.84
+v = float(undefined, false)    // v == false 
+```
+
+## char
+
+Tries to convert an object to char object. See [this](https://github.com/d5/tengo/blob/master/docs/runtime-types.md) for more details on type conversion.
+
+```golang
+v := char(89) //  v == 'Y'
+```
+
+Optionally it can take the second argument, which will be returned if the first argument cannot be converted to float. Note that the second argument does not have to be float.
+
+```golang
+v = char(undefined, 'X')    // v == 'X'
+v = char(undefined, false)  // v == false 
+```
+
+## bytes
+
+Tries to convert an object to bytes object. See [this](https://github.com/d5/tengo/blob/master/docs/runtime-types.md) for more details on type conversion.
+
+```golang
+v := bytes("foo") //  v == [102 111 111]
+```
+
+Optionally it can take the second argument, which will be returned if the first argument cannot be converted to float. Note that the second argument does not have to be float.
+
+```golang
+v = bytes(undefined, bytes("foo"))    // v == bytes("foo")
+v = bytes(undefined, false)           // v == false 
+```
+
+If you pass an int to `bytes()` function, it will create a new byte object with the given size.
+
+```golang
+v := bytes(100)
+```
+
+## is_string
+
+Returns `true` if the object is string. Or it returns `false`.
+
+## is_int
+
+Returns `true` if the object is int. Or it returns `false`.
+
+## is_bool
+
+Returns `true` if the object is bool. Or it returns `false`.
+
+## is_float
+
+Returns `true` if the object is float. Or it returns `false`.
+
+## is_char
+
+Returns `true` if the object is char. Or it returns `false`.
+
+## is_bytes
+
+Returns `true` if the object is bytes. Or it returns `false`.
+
+## is_error
+
+Returns `true` if the object is error. Or it returns `false`.
+
+## is_undefined
+
+Returns `true` if the object is undefined. Or it returns `false`.
--- a/docs/interoperability.md
+++ b/docs/interoperability.md
@ -0,0 +1,27 @@
+# Interoperability
+
+There are couple different ways of embedding and executing the Tengo code in Go codebase. 
+
+## Table of Contents 
+
+- [Scripts](#scripts)
+- [Compiler and VM](#compiler-and-vm)
+- [Sandbox Environments](#sandbox-environments)
+- [Type Conversion](#type-conversion)
+
+
+## Scripts
+
+...
+
+## Compiler and VM
+
+...
+
+## Sandbox Environments
+
+...
+
+## Type Conversion
+
+...
--- a/docs/objects.md
+++ b/docs/objects.md
@ -0,0 +1,297 @@
+# Tengo Objects
+
+## Table of Contents
+
+- [Objects](#objects)
+  - [Runtime Object Types](#runtime-object-types)
+  - [User Object Types](#user-object-types)
+- [Callable Objects](#callable-objects)
+- [Indexable Objects](#indexable-objects)
+- [Index-Assignable Objects](#index-assignable-objects)
+- [Iterable Objects](#iterable-objects)
+  - [Iterator Interface](#iterator-interface)
+
+## Objects
+
+All object types in Tengo implement [Object](https://godoc.org/github.com/d5/tengo/objects#Object) interface. 
+
+```golang
+TypeName() string
+```
+
+TypeName method should return the name of the type. Type names are not directly used by the runtime _(except when it reports a run-time error)_, but, it is generally a good idea to keep it short but distinguishable from other types.
+
+```golang
+String() string
+```
+String method should return a string representation of the underlying value. The value returned by String method will be used whenever string formatting for the value is required, most commonly when being converted into String value.
+
+```golang
+BinaryOp(op token.Token, rhs Object) (res Object, err error)
+```
+
+In Tengo, a type can overload binary operators (`+`, `-`, `*`, `/`, `%`, `&`, `|`, `^`, `&^`, `>>`, `<<`, `>`, `>=`; _note that `<` and `<=` operators are not overloadable as they're simply implemented by switching left-hand side and right-hand side of `>`/`>=` operator_) by implementing BinaryOp method. BinaryOp method takes the operator `op` and the right-hand side object `rhs`, and, should return a resulting value `res`. 
+
+**Error value vs runtime error**
+
+If BinaryOp method returns an error `err` (the second return value), it will be treated as a run-time error, which will halt the execution (`VM.Run() error`) and will return the error to the user. All runtime type implementations, for example, will return an `ErrInvalidOperator` error when the given operator is not supported by the type. 
+
+Alternatively the method can return an `Error` value as its result `res` (the first return value), which will not halt the runtime and will be treated like any other values. As a dynamically typed language, the receiver (another expression or statement) can determine how to translate `Error` value returned from binary operator expression. 
+
+```golang
+IsFalsy() bool
+```
+
+IsFalsy method should return true if the underlying value is considered to be [falsy](https://github.com/d5/tengo/wiki/Variable-Types#objectisfalsy).
+
+```golang
+Equals(o Object) bool
+```
+
+Equals method should return true if the underlying value is considered to be equal to the underlying value of another object `o`. When comparing values of different types, the runtime does not guarantee or force anything, but, it's generally a good idea to make the result consistent. For example, a custom integer type may return true when comparing against String value, but, it should return the same result for the same inputs.
+
+```golang
+Copy() Object
+```
+
+Copy method should a _new_ copy of the same object. All primitive and composite value types implement this method to return a deep-copy of the value, which is recommended for other user types _(as `copy` builtin function uses this Copy method)_, but, it's not a strict requirement by the runtime.
+
+### Runtime Object Types 
+
+These are the Tengo runtime object types:
+
+- Primitive value types: [Int](https://godoc.org/github.com/d5/tengo/objects#Int), [String](https://godoc.org/github.com/d5/tengo/objects#String), [Float](https://godoc.org/github.com/d5/tengo/objects#Float), [Bool](https://godoc.org/github.com/d5/tengo/objects#ArrayIterator), [Char](https://godoc.org/github.com/d5/tengo/objects#Char), [Bytes](https://godoc.org/github.com/d5/tengo/objects#Bytes)
+- Composite value types: [Array](https://godoc.org/github.com/d5/tengo/objects#Array), [Map](https://godoc.org/github.com/d5/tengo/objects#Map), [ImmutableMap](https://godoc.org/github.com/d5/tengo/objects#ImmutableMap)
+- Functions: [CompiledFunction](https://godoc.org/github.com/d5/tengo/objects#CompiledFunction), [BuiltinFunction](https://godoc.org/github.com/d5/tengo/objects#BuiltinFunction), [UserFunction](https://godoc.org/github.com/d5/tengo/objects#UserFunction)
+- [Iterators](https://godoc.org/github.com/d5/tengo/objects#Iterator): [StringIterator](https://godoc.org/github.com/d5/tengo/objects#StringIterator), [ArrayIterator](https://godoc.org/github.com/d5/tengo/objects#ArrayIterator), [MapIterator](https://godoc.org/github.com/d5/tengo/objects#MapIterator), [ImmutableMapIterator](https://godoc.org/github.com/d5/tengo/objects#ImmutableMapIterator)
+- [Error](https://godoc.org/github.com/d5/tengo/objects#Error)
+- [Undefined](https://godoc.org/github.com/d5/tengo/objects#Undefined)
+- Other internal objects: [Closure](https://godoc.org/github.com/d5/tengo/objects#Closure), [CompiledModule](https://godoc.org/github.com/d5/tengo/objects#CompiledModule), [Break](https://godoc.org/github.com/d5/tengo/objects#Break), [Continue](https://godoc.org/github.com/d5/tengo/objects#Continue), [ReturnValue](https://godoc.org/github.com/d5/tengo/objects#ReturnValue)
+
+### User Object Types
+
+Basically Tengo runtime treats and manages both the runtime types and user types exactly the same way as long as they implement Object interface. You can add values of the custom user types (via either [Script.Add](https://godoc.org/github.com/d5/tengo/script#Script.Add) method or by directly manipulating the symbol table and the global variables), and, use them directly in Tengo code.
+
+Here's an example user type, `Time`:
+
+```golang
+type Time struct {
+	Value time.Time
+}
+
+func (t *Time) TypeName() string {
+	return "time"
+}
+
+func (t *Time) String() string {
+	return t.Value.Format(time.RFC3339)
+}
+
+func (t *Time) BinaryOp(op token.Token, rhs objects.Object) (objects.Object, error) {
+	switch rhs := rhs.(type) {
+	case *Time:
+		switch op {
+		case token.Sub:
+			return &objects.Int{
+				Value: t.Value.Sub(rhs.Value).Nanoseconds(),
+			}, nil
+		}
+	case *objects.Int:
+		switch op {
+		case token.Add:
+			return &Time{
+				Value: t.Value.Add(time.Duration(rhs.Value)),
+			}, nil
+		case token.Sub:
+			return &Time{
+				Value: t.Value.Add(-time.Duration(rhs.Value)),
+			}, nil
+		}
+	}
+
+	return nil, objects.ErrInvalidOperator
+}
+
+func (t *Time) IsFalsy() bool {
+	return t.Value.IsZero()
+}
+
+func (t *Time) Equals(o objects.Object) bool {
+	if o, ok := o.(*Time); ok {
+		return t.Value.Equal(o.Value)
+	}
+
+	return false
+}
+
+func (t *Time) Copy() objects.Object {
+	return &Time{Value: t.Value}
+}
+```
+
+Now the Tengo runtime recognizes `Time` type, and, any `Time` values can be used directly in the Tengo code:
+
+```golang
+s := script.New([]byte(`
+	a := currentTime + 10000  // Time + Int = Time
+	b := a - currentTime      // Time - Time = Int
+`))
+
+// add Time value 'currentTime'
+err := s.Add("currentTime", &Time{Value: time.Now()}) 
+if err != nil {
+	panic(err)
+}
+
+c, err := s.Run()
+if err != nil {
+	panic(err)
+}
+
+fmt.Println(c.Get("b")) // "10000"
+```
+
+## Callable Objects
+
+Any types that implement [Callable](https://godoc.org/github.com/d5/tengo/objects#Callable) interface (in addition to Object interface), values of such types can be used as if they are functions. 
+
+```golang
+type Callable interface {
+	Call(args ...Object) (ret Object, err error)
+}
+```
+
+To make `Time` a callable value, add Call method to the previous implementation:
+
+```golang
+func (t *Time) Call(args ...objects.Object) (ret objects.Object, err error) {
+	if len(args) != 1 {
+		return nil, objects.ErrWrongNumArguments
+	}
+
+	format, ok := objects.ToString(args[0])
+	if !ok {
+		return nil, objects.ErrInvalidTypeConversion
+	}
+
+	return &objects.String{Value: t.Value.Format(format)}, nil
+}
+```
+
+Now `Time` values can be "called" like this:
+
+```golang
+s := script.New([]byte(`
+	a := currentTime + 10000  // Time + Int = Time
+	b := a("15:04:05")        // call 'a'
+`))
+
+// add Time value 'currentTime'
+err := s.Add("currentTime", &Time{Value: time.Now()}) 
+if err != nil {
+	panic(err)
+}
+
+c, err := s.Run()
+if err != nil {
+	panic(err)
+}
+
+fmt.Println(c.Get("b")) // something like "21:15:27"
+```
+
+## Indexable Objects
+
+If the type implements [Indexable](https://godoc.org/github.com/d5/tengo/objects#Indexable) interface, it enables dot selector (`value = object.index`) or indexer (`value = object[index]`) syntax for its values.
+
+```golang
+type Indexable interface {
+	IndexGet(index Object) (value Object, err error)
+}
+```
+
+If the implementation returns an error (`err`), the VM will treat it as a run-time error. Many runtime types such as Map and Array also implement the same interface:
+
+```golang
+func (o *Map) IndexGet(index Object) (res Object, err error) {
+	strIdx, ok := index.(*String)
+	if !ok {
+		err = ErrInvalidIndexType
+		return
+	}
+
+	val, ok := o.Value[strIdx.Value]
+	if !ok {
+		val = UndefinedValue
+	}
+
+	return val, nil
+}
+```
+
+Array and Map implementation forces the type of index Object (Int and String respectively), but, it's not required behavior by the VM. It is completely okay to take various index types (or to do type coercion) as long as its result is consistent. 
+
+By convention, Array or Array-like types return `ErrIndexOutOfBounds` error (as a runtime error) when the index is invalid (out of the bounds), and, Map or Map-like types return `Undefined` value when the key does not exist. But, again this is not a requirement, and, the type can implement the behavior however it fits.
+
+## Index-Assignable Objects
+
+If the type implements [IndexAssignable](https://godoc.org/github.com/d5/tengo/objects#IndexAssignable) interface, the values of that type allow assignment using dot selector (`object.index = value`) or indexer (`object[index] = value`) in the assignment statements.
+
+```golang
+type IndexAssignable interface {
+	IndexSet(index, value Object) error
+}
+```
+
+Map, Array, and a couple of other runtime types also implement the same interface:
+
+```golang
+func (o *Map) IndexSet(index, value Object) (err error) {
+	strIdx, ok := ToString(index)
+	if !ok {
+		err = ErrInvalidTypeConversion
+		return
+	}
+
+	o.Value[strIdx] = value
+
+	return nil
+}
+```
+
+Array and Map implementation forces the type of index Object (Int and String respectively), but, it's not required behavior by the VM. It is completely okay to take various index types (or to do type coercion) as long as its result is consistent. 
+
+By convention, Array or Array-like types return `ErrIndexOutOfBounds` error (as a runtime error) when the index is invalid (out of the bounds). But, this is not a requirement, and, the type can implement the behavior however it fits.
+
+
+## Iterable Objects
+
+Values of the types that implement [Iterable](https://godoc.org/github.com/d5/tengo/objects#Iterable) interface can be used in `for-in` statements (`for key, value in object { ... }`).
+
+```golang
+type Iterable interface {
+	Iterate() Iterator
+}
+```
+
+This Iterate method should return another object that implements [Iterator](https://godoc.org/github.com/d5/tengo/objects#Iterator) interface.
+
+### Iterator Interface
+
+```golang
+Next() bool
+```
+
+Next method should return true if there are more elements to iterate. When used with `for-in` statements, the compiler uses Key and Value methods to populate the current element's key (or index) and value from the object that this iterator represents. The runtime will stop iterating in `for-in` statement when this method returns false. 
+
+```golang
+Key() Object
+```
+
+Key method should return a key (or an index) Object for the current element of the underlying object. It should return the same value until Next method is called again. By convention, iterators for the map or map-like objects returns the String key, and, iterators for array or array-like objects returns the Int index. But, it's not a requirement by the VM.
+
+```golang
+Value() Object
+```
+
+Value method should return a value Object for the current element of the underlying object. It should return the same value until Next method is called again.
--- a/docs/runtime-types.md
+++ b/docs/runtime-types.md
@ -0,0 +1,71 @@
+# Tengo Runtime Types
+
+- **Int**: signed 64bit integer
+- **String**: string
+- **Float**: 64bit floating point
+- **Bool**: boolean
+- **Char**: character (`rune` in Go)
+- **Bytes**: byte array (`[]byte` in Go)
+- **Array**: objects array (`[]Object` in Go)
+- **Map**: objects map with string keys (`map[string]Object` in Go)
+- **ImmutableMap**: immutable object map with string keys (`map[string]Object` in Go)
+- **Error**: an error with underlying Object value of any type
+- **Undefined**: undefined
+
+## Type Conversion/Coercion Table
+|src\dst  |Int      |String        |Float    |Bool      |Char   |Bytes  |Array  |Map    |IMap|Error  |Undefined|
+| :---:   | :---:   | :---:        | :---:   | :---:    | :---: | :---: | :---: | :---: | :---: | :---: | :---: |
+|Int      |   -     |_strconv_     |int(v)   |!IsFalsy()| rune(v)|**X**|**X**|**X**|**X**|**X**|**X**|
+|String   |_strconv_|   -          |_strconv_|!IsFalsy()|**X**|[]byte(s)|**X**|**X**|**X**|**X**|**X**|
+|Float    |int(f)   |_strconv_     | -       |!IsFalsy()|**X**|**X**|**X**|**X**|**X**|**X**|**X**|
+|Bool     |1 / 0    |"true" / "false"|**X**    |   -   |**X**|**X**|**X**|**X**|**X**|**X**|**X**|
+|Char     |int(c)   |string(c)     |**X**    |!IsFalsy()|   -   |**X**|**X**|**X**|**X**|**X**|**X**|
+|Bytes    |**X**    |string(y)|**X**    |!IsFalsy()|**X**|   -   |**X**|**X**|**X**|**X**|**X**|
+|Array    |**X**    |"[...]"       |**X**    |!IsFalsy()|**X**|**X**|   -   |**X**|**X**|**X**|**X**|
+|Map      |**X**    |"{...}"       |**X**    |!IsFalsy()|**X**|**X**|**X**|   -   |**X**|**X**|**X**|
+|IMap  |**X**    |"{...}"       |**X**    |!IsFalsy()|**X**|**X**|**X**|**X**|   -   |**X**|**X**|
+|Error    |**X**    |"error: ..."  |**X**    |false|**X**|**X**|**X**|**X**|**X**|   -   |**X**|
+|Undefined|**X**    |**X**|**X**    |false|**X**|**X**|**X**|**X**|**X**|**X**|   -    |
+
+_**X**: No conversion; Typed value functions for `script.Variable` will return zero values._
+
+_strconv: converted using Go's conversion functions from `strconv` package._
+
+_IsFalsy(): use [Object.IsFalsy()](#objectisfalsy) function_
+
+## Object.IsFalsy()
+
+`Object.IsFalsy()` interface method is used to determine if a given value should evaluate to `false` (e.g. for condition expression of `if` statement).
+
+- **Int**: `n == 0`
+- **String**: `len(s) == 0`
+- **Float**: `isNaN(f)`
+- **Bool**: `!b`
+- **Char**: `c == 0`
+- **Bytes**: `len(bytes) == 0`
+- **Array**: `len(arr) == 0`
+- **Map**: `len(map) == 0`
+- **ImmutableMap**: `len(map) == 0`
+- **Error**: `true` _(Error is always falsy)_
+- **Undefined**: `true` _(Undefined is always falsy)_
+
+## Type Conversion Builtin Functions
+
+- `string(x)`: tries to convert `x` into string; returns `undefined` if failed
+- `int(x)`: tries to convert `x` into int; returns `undefined` if failed
+- `bool(x)`: tries to convert `x` into bool; returns `undefined` if failed
+- `float(x)`: tries to convert `x` into float; returns `undefined` if failed
+- `char(x)`: tries to convert `x` into char; returns `undefined` if failed
+- `bytes(x)`: tries to convert `x` into bytes; returns `undefined` if failed
+  - `bytes(N)`: as a special case this will create a Bytes variable with the given size `N` (only if `N` is int)
+
+## Type Checking Builtin Functions
+
+- `is_string(x)`: returns `true` if `x` is string; `false` otherwise
+- `is_int(x)`: returns `true` if `x` is int; `false` otherwise
+- `is_bool(x)`: returns `true` if `x` is bool; `false` otherwise
+- `is_float(x)`: returns `true` if `x` is float; `false` otherwise
+- `is_char(x)`: returns `true` if `x` is char; `false` otherwise
+- `is_bytes(x)`: returns `true` if `x` is bytes; `false` otherwise
+- `is_error(x)`: returns `true` if `x` is error; `false` otherwise
+- `is_undefined(x)`: returns `true` if `x` is undefined; `false` otherwise
--- a/docs/stdlib-exec.md
+++ b/docs/stdlib-exec.md
@ -0,0 +1,28 @@
+# Module - "exec"
+
+```golang
+exec := import("exec")
+```
+
+## Module Functions
+
+- `look_path(file string) => string/error`: port of `exec.LookPath` function
+- `command(name string, args array(string)) => `Cmd/error`: port of `exec.Command` function
+
+## Cmd Functions
+
+```golang
+cmd := exec.command("echo", ["foo", "bar"])
+output := cmd.output()
+```
+
+- `combined_output() => bytes/error`: port of `exec.Cmd.CombinedOutput` function
+- `output() => bytes/error`: port of `exec.Cmd.Output` function
+- `combined_output() => bytes/error`: port of `exec.Cmd.CombinedOutput` function
+- `run() => error`: port of `exec.Cmd.Run` function
+- `start() => error`: port of `exec.Cmd.Start` function
+- `wait() => error`: port of `exec.Cmd.Wait` function
+- `set_path(path string)`: sets `Path` of `exec.Cmd`
+- `set_dir(dir string)`: sets `Dir` of `exec.Cmd`
+- `set_env(env array(string))`: sets `Env` of `exec.Cmd`
+- `process() => Process`: returns Process (`Process` of `exec.Cmd`)
--- a/docs/stdlib-math.md
+++ b/docs/stdlib-math.md
@ -0,0 +1,79 @@
+# Module - "math"
+
+```golang
+math := import("math")
+```
+
+## Variables
+
+- `e`: equivalent of Go's `math.E`
+- `pi`: equivalent of Go's `math.Pi`
+- `phi`: equivalent of Go's `math.Phi`
+- `sqrt2`: equivalent of Go's `math.Sqrt2`
+- `sqrtE`: equivalent of Go's `math.SqrtE`
+- `sprtPi`: equivalent of Go's `math.SqrtPi`
+- `sqrtPhi`: equivalent of Go's `math.SqrtPhi`
+- `ln2`: equivalent of Go's `math.Ln2`
+- `log2E`: equivalent of Go's `math.Log2E`
+- `ln10`: equivalent of Go's `math.Ln10`
+- `ln10E`: equivalent of Go's `math.Log10E`
+
+## Functions
+
+- `abs(float) => float`: port of Go's `math.Abs` function
+- `acos(float) => float`: port of Go's `math.Acos` function
+- `acosh(float) => float`: port of Go's `math.Acosh` function
+- `asin(float) => float`: port of Go's `math.Asin` function
+- `asinh(float) => float`: port of Go's `math.Asinh` function
+- `atan(float) => float`: port of Go's `math.Atan` function
+- `atan2(float, float) => float`: port of Go's `math.Atan2` function
+- `atanh(float) => float`: port of Go's `math.Atanh` function
+- `cbrt(float) => float`: port of Go's `math.Cbrt` function
+- `ceil(float) => float`: port of Go's `math.Ceil` function
+- `copysign(float, float) => float`: port of Go's `math.Copysign` function
+- `cos(float) => float`: port of Go's `math.Cos` function
+- `cosh(float) => float`: port of Go's `math.Cosh` function
+- `dim(float, float) => float`: port of Go's `math.Dim` function
+- `erf(float) => float`: port of Go's `math.Erf` function
+- `erfc(float) => float`: port of Go's `math.Erfc` function
+- `erfcinv(float) => float`: port of Go's `math.Erfcinv` function
+- `erfinv(float) => float`: port of Go's `math.Erfinv` function
+- `exp(float) => float`: port of Go's `math.Exp` function
+- `exp2(float) => float`: port of Go's `math.Exp2` function
+- `expm1(float) => float`: port of Go's `math.Expm1` function
+- `floor(float) => float`: port of Go's `math.Floor` function
+- `gamma(float) => float`: port of Go's `math.Gamma` function
+- `hypot(float, float) => float`: port of Go's `math.Hypot` function
+- `ilogb(float) => float`: port of Go's `math.Ilogb` function
+- `inf(int) => float`: port of Go's `math.Inf` function
+- `is_inf(float, int) => float`: port of Go's `math.IsInf` function
+- `is_nan(float) => float`: port of Go's `math.IsNaN` function
+- `j0(float) => float`: port of Go's `math.J0` function
+- `j1(float) => float`: port of Go's `math.J1` function
+- `jn(int, float) => float`: port of Go's `math.Jn` function
+- `ldexp(float, int) => float`: port of Go's `math.Ldexp` function
+- `log(float) => float`: port of Go's `math.Log` function
+- `log10(float) => float`: port of Go's `math.Log10` function
+- `log1p(float) => float`: port of Go's `math.Log1p` function
+- `log2(float) => float`: port of Go's `math.Log2` function
+- `logb(float) => float`: port of Go's `math.Logb` function
+- `max(float, float) => float`: port of Go's `math.Max` function
+- `min(float, float) => float`: port of Go's `math.Min` function
+- `mod(float, float) => float`: port of Go's `math.Mod` function
+- `nan() => float`: port of Go's `math.NaN` function
+- `nextafter(float, float) => float`: port of Go's `math.Nextafter` function
+- `pow(float, float) => float`: port of Go's `math.Pow` function
+- `pow10(int) => float`: port of Go's `math.Pow10` function
+- `remainder(float, float) => float`: port of Go's `math.Remainder` function
+- `round(float) => float`: port of Go's `math.Round` function
+- `round_to_even(float) => float`: port of Go's `math.RoundToEven` function
+- `signbit(float) => float`: port of Go's `math.Signbit` function
+- `sin(float) => float`: port of Go's `math.Sin` function
+- `sinh(float) => float`: port of Go's `math.Sinh` function
+- `sqrt(float) => float`: port of Go's `math.Sqrt` function
+- `tan(float) => float`: port of Go's `math.Tan` function
+- `tanh(float) => float`: port of Go's `math.Tanh` function
+- `runct(float) => float`: port of Go's `math.Trunc` function
+- `y0(float) => float`: port of Go's `math.Y0` function
+- `y1(float) => float`: port of Go's `math.Y1` function
+- `yn(int, float) => float`: port of Go's `math.Yn` function
--- a/docs/stdlib-os.md
+++ b/docs/stdlib-os.md
@ -0,0 +1,125 @@
+# Module - "os"
+
+```golang
+os := import("os")
+```
+
+## Module Variables
+
+- `o_rdonly`: equivalent of Go's `os.O_RDONLY`
+- `o_wronly`: equivalent of Go's `os.O_WRONLY`
+- `o_rdwr`: equivalent of Go's `os.O_RDWR`
+- `o_append`: equivalent of Go's `os.O_APPEND`
+- `o_create`: equivalent of Go's `os.O_CREATE`
+- `o_excl`: equivalent of Go's `os.O_EXCL`
+- `o_sync`: equivalent of Go's `os.O_SYNC`
+- `o_trunc`: equivalent of Go's `os.O_TRUNC`
+- `mode_dir`: equivalent of Go's `os.ModeDir`
+- `mode_append`: equivalent of Go's `os.ModeAppend`
+- `mode_exclusive`: equivalent of Go's `os.ModeExclusive`
+- `mode_temporary`: equivalent of Go's `os.ModeTemporary`
+- `mode_symlink`: equivalent of Go's `os.ModeSymlink`
+- `mode_device`: equivalent of Go's `os.ModeDevice`
+- `mode_named_pipe`: equivalent of Go's `os.ModeNamedPipe`
+- `mode_socket`: equivalent of Go's `os.ModeSocket`
+- `mode_setuid`: equivalent of Go's `os.ModeSetuid`
+- `mode_setgui`: equivalent of Go's `os.ModeSetgid`
+- `mode_char_device`: equivalent of Go's `os.ModeCharDevice`
+- `mode_sticky`: equivalent of Go's `os.ModeSticky`
+- `mode_irregular`: equivalent of Go's `os.ModeIrregular`
+- `mode_type`: equivalent of Go's `os.ModeType`
+- `mode_perm`: equivalent of Go's `os.ModePerm`
+- `seek_set`: equivalent of Go's `os.SEEK_SET`
+- `seek_cur`: equivalent of Go's `os.SEEK_CUR`
+- `seek_end`: equivalent of Go's `os.SEEK_END`
+- `path_separator`: equivalent of Go's `os.PathSeparator`
+- `path_list_separator`: equivalent of Go's `os.PathListSeparator`
+- `dev_null`: equivalent of Go's `os.DevNull`
+
+## Module Functions
+
+- `args() => array(string)`: returns `os.Args`
+- `chdir(dir string) => error`: port of `os.Chdir` function
+- `chmod(name string, mode int) => error `: port of Go's `os.Chmod` function
+- `chown(name string, uid int, gid int) => error `: port of Go's `os.Chown` function
+- `clearenv() `: port of Go's `os.Clearenv` function
+- `environ() => array(string) `: port of Go's `os.Environ` function
+- `executable() => string/error`: port of Go's `os.Executable()` function
+- `exit(code int) `: port of Go's `os.Exit` function
+- `expand_env(s string) => string `: port of Go's `os.ExpandEnv` function
+- `getegid() => int `: port of Go's `os.Getegid` function
+- `getenv(s string) => string `: port of Go's `os.Getenv` function
+- `geteuid() => int `: port of Go's `os.Geteuid` function
+- `getgid() => int `: port of Go's `os.Getgid` function
+- `getgroups() => array(string)/error `: port of Go's `os.Getgroups` function
+- `getpagesize() => int `: port of Go's `os.Getpagesize` function
+- `getpid() => int `: port of Go's `os.Getpid` function
+- `getppid() => int `: port of Go's `os.Getppid` function
+- `getuid() => int `: port of Go's `os.Getuid` function
+- `getwd() => string/error `: port of Go's `os.Getwd` function
+- `hostname() => string/error `: port of Go's `os.Hostname` function
+- `lchown(name string, uid int, gid int) => error `: port of Go's `os.Lchown` function
+- `link(oldname string, newname string) => error `: port of Go's `os.Link` function
+- `lookup_env(key string) => string/false`: port of Go's `os,LookupEnv` function
+- `mkdir(name string, perm int) => error `: port of Go's `os.Mkdir` function
+- `mkdir_all(name string, perm int) => error `: port of Go's `os.MkdirAll` function
+- `readlink(name string) => string/error `: port of Go's `os.Readlink` function
+- `remove(name string) => error `: port of Go's `os.Remove` function
+- `remove_all(name string) => error `: port of Go's `os.RemoveAll` function
+- `rename(oldpath string, newpath string) => error `: port of Go's `os.Rename` function
+- `setenv(key string, value string) => error `: port of Go's `os.Setenv` function
+- `symlink(oldname string newname string) => error `: port of Go's `os.Symlink` function
+- `temp_dir() => string `: port of Go's `os.TempDir` function
+- `truncate(name string, size int) => error `: port of Go's `os.Truncate` function
+- `unsetenv(key string) => error `: port of Go's `os.Unsetenv` function
+- `user_cache_dir() => string/error `: port of Go's `os.UserCacheDir` function
+- `create(name string) => File/error`: port of Go's `os.Create` function
+- `open(name string) => File/error`: port of Go's `os.Open` function
+- `open_file(name string, flag int, perm int) => File/error`: port of Go's `os.OpenFile` function
+- `find_process(pid int) => Process/error`: port of Go's `os.FindProcess` function
+- `start_process(name string, argv array(string), dir string, env array(string)) => Process/error`: port of Go's `os.StartProcess` function
+
+## File Functions
+
+```golang
+file := os.create("myfile")
+file.write_string("some data")
+file.close()
+```
+
+- `chdir() => true/error`: port of `os.File.Chdir` function
+- `chown(uid int, gid int) => true/error`: port of `os.File.Chown` function
+- `close() => error`: port of `os.File.Close` function
+- `name() => string`: port of `os.File.Name` function
+- `readdirnames() => array(string)/error`: port of `os.File.Readdirnames` function
+- `sync() => error`: port of `os.File.Sync` function
+- `write(bytes) => int/error`: port of `os.File.Write` function
+- `write_string(string) => int/error`: port of `os.File.WriteString` function
+- `read(bytes) => int/error`: port of `os.File.Read` function
+- `chmod(mode int) => error`: port of `os.File.Chmod` function
+- `seek(offset int, whence int) => int/error`: port of `os.File.Seek` function
+
+## Process Functions
+
+```golang
+proc := start_process("app", ["arg1", "arg2"], "dir", [])
+proc.wait()
+```
+
+- `kill() => error`: port of `os.Process.Kill` function
+- `release() => error`: port of `os.Process.Release` function
+- `signal(signal int) => error`: port of `os.Process.Signal` function
+- `wait() => ProcessState/error`: port of `os.Process.Wait` function
+
+## ProcessState Functions
+
+```golang
+proc := start_process("app", ["arg1", "arg2"], "dir", [])
+stat := proc.wait()
+pid := stat.pid()
+```
+
+- `exited() => bool`: port of `os.ProcessState.Exited` function
+- `pid() => int`: port of `os.ProcessState.Pid` function
+- `string() => string`: port of `os.ProcessState.String` function
+- `success() => bool`: port of `os.ProcessState.Success` function
--- a/docs/stdlib.md
+++ b/docs/stdlib.md
@ -0,0 +1,7 @@
+# Standard Library
+
+_NOTE: Implementation and the interface of these standard libraries are still **experimental** and there might be some breaking changes in the future releases._
+
+- [math](https://github.com/d5/tengo/blob/master/docs/stdlib-math.md)
+- [os](https://github.com/d5/tengo/blob/master/docs/stdlib-os.md)
+- [exec](https://github.com/d5/tengo/blob/master/docs/stdlib-exec.md)