Update docs

Author: antonmedv

docs/Custom-Functions.md

@@ -1,9 +1,14 @@
 # Getting Started
 
-**Expr** provides a package for evaluating arbitrary expressions as well as type checking of such expression.
+**Expr** provides a package for evaluating arbitrary expressions as well as type
+checking of such expression.
 
 ## Evaluate
 
+For simple use cases with one execution of an expression, you can use the 
+`expr.Eval` function. It takes an expression and a map of variables and returns
+the result of the expression.
+
 ```go
 package main
 
@@ -29,7 +34,9 @@ func main() {
 
 ## Compile
 
-Usually we want to compile the code on save (For example, in [web user interface](https://antonmedv.github.io/expr/)).
+Usually we want to compile, type check and verify what the expression returns a 
+boolean (or another type). For example, if a user saves an expression from
+[web UI](https://antonmedv.github.io/expr/).
 
 ```go
 package main
@@ -44,13 +51,13 @@ func main() {
 	env := map[string]interface{}{
 		"greet":   "Hello, %v!",
 		"names":   []string{"world", "you"},
-		"sprintf": fmt.Sprintf, // You can pass any functions.
+		"sprintf": fmt.Sprintf, // Use any functions.
 	}
 
 	code := `sprintf(greet, names[0])`
 
-	// Compile code into bytecode. This step can be done once and program may be reused.
-	// Specify environment for type check.
+	// Compile the code into a bytecode. This step can be done once 
+	// and program may be reused. Specify an environment for type check.
 	program, err := expr.Compile(code, expr.Env(env))
 	if err != nil {
 		panic(err)
@@ -66,8 +73,7 @@ func main() {
 ```
 
 You may use existing types. For example, an environment can be a struct. The
-struct fields can be renamed by adding struct tags such as `expr:"timestamp"` in
-the example below:
+struct fields can be renamed by adding struct tags such as `expr:"name"`.
 
 ```go
 package main
@@ -83,16 +89,16 @@ type Env struct {
 	Tweets []Tweet
 }
 
-// Methods defined on such struct will be functions.
+// Methods defined on the struct become functions.
 func (Env) Format(t time.Time) string { return t.Format(time.RFC822) }
 
 type Tweet struct {
 	Text string
-	Date time.Time `expr:"Timestamp"`
+	Date time.Time `expr:"timestamp"`
 }
 
 func main() {
-	code := `map(filter(Tweets, {len(.Text) > 0}), {.Text + Format(.Timestamp)})`
+	code := `map(filter(Tweets, {len(.Text) > 0}), {.Text + Format(.timestamp)})`
 
 	// We can use an empty instance of the struct as an environment.
 	program, err := expr.Compile(code, expr.Env(Env{}))
@@ -101,7 +107,11 @@ func main() {
 	}
 
 	env := Env{
-		Tweets: []Tweet{{"Oh My God!", time.Now()}, {"How you doin?", time.Now()}, {"Could I be wearing any more clothes?", time.Now()}},
+		Tweets: []Tweet{
+			{"Oh My God!", time.Now()}, 
+			{"How you doin?", time.Now()}, 
+			{"Could I be wearing any more clothes?", time.Now()},
+		},
 	}
 
 	output, err := expr.Run(program, env)
@@ -113,5 +123,4 @@ func main() {
 }
 ```
 
-- [Contents](README.md)
-- Next: [Custom functions](Custom-Functions.md)
+* Next: [Operator Overloading](Operator-Overloading.md)

docs/Getting-Started.md

@@ -0,0 +1,79 @@
+# Internals
+
+Expr is a stack based virtual machine. It compiles expressions to bytecode and 
+runs it. 
+
+Compilation is done in a few steps:
+- Parse expression to AST
+- Type check AST
+  - Apply operator overloading
+  - Apply custom AST patching
+- Optimize AST
+- Compile AST to a bytecode
+
+Compiler has a bunch of optimization which will produce a more optimal program.
+
+## In array
+
+```js
+value in ['foo', 'bar', 'baz']
+```
+
+If Expr finds an `in` or `not in` expression with an array, it will be 
+transformed into:
+
+```js
+value in {"foo": true, "bar": true, "baz": true}
+```
+
+## Constant folding
+
+Arithmetic expressions with constants is computed on compile step and replaced 
+with the result.
+
+```js
+-(2-5)**3-2/(+4-3)+-2
+```
+
+Will be compiled to just single number:
+
+```js
+23
+```
+
+## In range
+
+```js
+user.Age in 18..32
+```
+
+Will be replaced with a binary operator:
+
+```js
+18 <= user.Age && user.Age <= 32
+```
+
+## Const range
+
+```js
+1..10_000
+```
+
+Ranges computed on compile stage, replaced with precreated slices.
+
+## Const expr
+
+If some function marked as constant expression with `expr.ConstExpr`. It will be
+replaced with result of the call, if all arguments are constants.
+
+```go
+expr.ConstExpt("fib")
+```
+
+```js
+fib(42)
+``` 
+
+Will be replaced with result of `fib(42)` on the compile step.
+
+[ConstExpr Example](https://pkg.go.dev/github.com/antonmedv/expr?tab=doc#ConstExpr)

docs/Internals.md

@@ -1,6 +1,7 @@
-# Operator Override
+# Operator Overloading
 
-**Expr** supports operator overriding. For example, you may rewrite such expression:
+**Expr** supports operator overloading. For example, you may rewrite a such 
+expression:
 
 ```js
 Now().Sub(CreatedAt) 
@@ -12,7 +13,8 @@ To use `-` operator:
 Now() - CreatedAt
 ```
 
-To override operator use [expr.Operator](https://pkg.go.dev/github.com/antonmedv/expr?tab=doc#Operator):
+To overloading the operator use 
+[expr.Operator](https://pkg.go.dev/github.com/antonmedv/expr?tab=doc#Operator):
 
 ```go
 package main
@@ -25,12 +27,12 @@ import (
 )
 
 func main() {
-	code := `(Now() - CreatedAt).Hours() / 24 / 365`
+	code := `Now() - CreatedAt`
 
 	// We can define options before compiling.
 	options := []expr.Option{
 		expr.Env(Env{}),
-		expr.Operator("-", "Sub"), // Override `-` with function `Sub`.
+		expr.Operator("-", "Sub"), // Replace `-` operator with function `Sub`.
 	}
 
 	program, err := expr.Compile(code, options...)
@@ -61,10 +63,8 @@ func (datetime) Now() time.Time                   { return time.Now() }
 func (datetime) Sub(a, b time.Time) time.Duration { return a.Sub(b) }
 ```
 
-**Expr** uses defined functions on `Env` for operator overloading. If types of operands match types of a function,
-the operator will be replaced with the function call.
+**Expr** uses functions from `Env` for operator overloading. If types of 
+operands match types of a function, the operator will be replaced with a 
+function call.
 
-Complete example can be found here: [dates_test.go](examples/dates_test.go).
-
-* [Contents](README.md)
 * Next: [Visitor and Patch](Visitor-and-Patch.md)