Update docs

Author: antonmedv

docs/Getting-Started.md

@@ -1,108 +1,116 @@
 # Getting Started
 
 **Expr** provides a package for evaluating arbitrary expressions as well as type checking of such expression.
- For demonstration purpose, let's assume that we already have some types and structs describing our data. And we want to implement filtering of data flow, via providing our users to configure such filters via expressions.
- 
-```go
-type Request struct {
-	Location string
-	Date     time.Time
-	Ticket   Ticket
-}
-
-type Ticket struct {
-	Segments []Segment
-}
-
-type Segment struct {
-	Origin, Destination string
-	Date                time.Time
-} 
-```
 
-#### Compile step
-
-First what we need to do is to create a way users will be creating, editing (and maybe deleted) filter rules, but this is out of scope for this article. Let's assume that we have some kind of Web interface where users can do all or some of this. On creation or deletion of rules, we much check if rules are written correctly. And we want to give the user access to `Request` fields and only these fields. 
+## Evaluate
 
 ```go
+package main
+
 import (
+	"fmt"
 	"github.com/antonmedv/expr"
-	"github.com/antonmedv/expr/vm"
 )
 
-var program *vm.Program
+func main() {
+	env := map[string]interface{}{
+		"foo": 1,
+		"bar": 2,
+	}
 
-program, err = expr.Compile(rule, expr.Env(&Request{}))
+	out, err := expr.Eval("foo + bar", env)
+
+	if err != nil {
+		panic(err)
+	}
+	fmt.Print(out)
+}
 ```
 
-By passing `&Request{}` as env into compile method we turned on type checking, now if users make an error in field or compare strings with integers, he will get an error. Now users can save expressions.
+## Compile
 
-#### Example of an expression
+Usually we want to compile the code on save (For example, in [web user interface](https://antonmedv.github.io/expr/)).  
 
-```coffeescript
-all(Ticket.Segments, {.Origin == Location}) and Date.Before(Ticket.Segments[0].Date)
-``` 
+```go
+package main
 
-<p align="center">👐</p>
+import (
+	"fmt"
+
+	"github.com/antonmedv/expr"
+)
 
-#### Runtime step
+func main() {
+	env := map[string]interface{}{
+		"greet":   "Hello, %v!",
+		"names":   []string{"world", "you"},
+		"sprintf": fmt.Sprintf, // You can pass any functions.
+	}
 
-Now we need to implement the execution of our compiled program. On each request, we have some kind of filter loop.
+	code := `sprintf(greet, names[0])`
 
-```go
-output, err := expr.Run(program, requset)
-if err != nil {
-	return err
-}
+	// Compile code into bytecode. This step can be done once and program may be reused.
+	// Specify environment for type check.
+	program, err := expr.Compile(code, expr.Env(env))
+	if err != nil {
+		panic(err)
+	}
 
-if !output.(bool) {
-	continue
+	output, err := expr.Run(program, env)
+	if err != nil {
+		panic(err)
+	}
+
+	fmt.Print(output)
 }
 ```
 
-#### Helpers
-
-Now let's some add a function for repetitive tasks. 
+You may use existing types. For example, an environment can be a struct.
 
 ```go
-func (r *Request) SameLocation() bool {
-	same := false
-	for _, s := range r.Ticket.Segments {
-		same = same && s.Origin == r.Location
-	}
-	return same
-}
-```
+package main
 
-Now users can use functions inside expressions.
+import (
+	"fmt"
+	"time"
 
-```coffeescript
-SameLocation() and Date.Before(Ticket.Segments[0].Date)
-```
+	"github.com/antonmedv/expr"
+)
 
-#### Operator override
+type Env struct {
+	Tweets []Tweet
+}
 
-Much better. But using time's package methods isn't pretty. What if we can override operators? And we can! Let's describe another function.
+// Methods defined on such struct will be functions.
+func (Env) Format(t time.Time) string { return t.Format(time.RFC822) }
 
-```go
-func (*Request) Before(a, b time.Time) bool {
-	return a.Before(b)
+type Tweet struct {
+	Text string
+	Date time.Time
 }
-```
 
-Now, on compile time, override `<` operator.
+func main() {
+	code := `all(Tweets, {len(.Text) > 0}) ? map(Tweets, {.Text + Format(.Date)}) : nil`
 
-```go
-program, err = expr.Compile(rule, expr.Env(&Request{}), expr.Operator("<", "Before"))
-```
+	// We can use an empty instance of the struct as an environment.
+
+	program, err := expr.Compile(code, expr.Env(Env{}))
+	if err != nil {
+		panic(err)
+	}
 
-That's it! Now users can write expressions in a more pleasant way. Other operators `+`, `>`, `==`, etc can be overridden in similar way.
+	env := Env{
+		Tweets: []Tweet{{"Oh My God!", time.Now()}, {"How you doin?", time.Now()}, {"Could I be wearing any more clothes?", time.Now()}},
+	}
 
-```coffeescript
-SameLocation() and Date < Ticket.Segments[0].Date
+	output, err := expr.Run(program, env)
+	if err != nil {
+		panic(err)
+	}
+
+	fmt.Print(output)
+}
 ```
 
-Next
-* [Language Definition](Language-Definition.md)
-* [Usage](Usage.md)
-* [Examples](https://godoc.org/github.com/antonmedv/expr#pkg-examples)
+* [Contents](README.md)
+* Next: [Operator Override](Operator-Override.md)

docs/Operator-Override.md

@@ -0,0 +1,70 @@
+# Operator Override
+
+**Expr** supports operator overriding. For example, you may rewrite such expression:
+
+```js
+Now().Sub(CreatedAt) 
+```
+
+To use `-` operator:
+ 
+```js
+Now() - CreatedAt
+```
+
+To override operator use [expr.Operator](https://pkg.go.dev/github.com/antonmedv/expr?tab=doc#Operator):
+
+```go
+package main
+
+import (
+	"fmt"
+	"time"
+
+	"github.com/antonmedv/expr"
+)
+
+func main() {
+	code := `(Now() - CreatedAt).Hours() / 24 / 365`
+
+	// We can define options before compiling.
+	options := []expr.Option{
+		expr.Env(Env{}),
+		expr.Operator("-", "Sub"), // Override `-` with function `Sub`.
+	}
+
+	program, err := expr.Compile(code, options...)
+	if err != nil {
+		panic(err)
+	}
+
+	env := Env{
+		CreatedAt: time.Date(1987, time.November, 24, 20, 0, 0, 0, time.UTC),
+	}
+
+	output, err := expr.Run(program, env)
+	if err != nil {
+		panic(err)
+	}
+	fmt.Print(output)
+}
+
+type Env struct {
+	datetime
+	CreatedAt time.Time
+}
+
+// Functions may be defined on embedded structs as well.
+type datetime struct{}
+
+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.
+
+Complete example can be found here: [dates_test.go](examples/dates_test.go).
+
+* [Contents](README.md)
+* Next: [Visitor And Patch](Visitor-And-Patch.md)

docs/Optimizations.md

@@ -76,3 +76,7 @@ fib(42)
 ``` 
 
 Will be replaced with result of `fib(42)` on compile step. No need to calculate it during runtime.
+
+[ConstExpr Example](https://pkg.go.dev/github.com/antonmedv/expr?tab=doc#ConstExpr)
+
+* [Contents](README.md)

docs/README.md

@@ -2,5 +2,6 @@
 
 * [Getting Started](Getting-Started.md)
 * [Language Definition](Language-Definition.md)
-* [Usage](Usage.md)
+* [Operator Override](Operator-Override.md)
+* [Visitor And Patch](Visitor-And-Patch.md)
 * [Optimizations](Optimizations.md)