Add Getting-Started.md

Author: antonmedv

README.md

@@ -55,7 +55,7 @@ go get github.com/antonmedv/expr
 
 ## Documentation
 
-* See [docs](docs) page for developer documentation.
+* See [Getting Started](docs/Getting-Started.md) page for developer documentation.
 * See [Language Definition](docs/Language-Definition.md) page to learn the syntax.
 
 ## Examples

docs/Getting-Started.md

@@ -0,0 +1,95 @@
+# 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 Requset struct {
+    Location string
+    Date     time.Time
+    Ticket   Ticket
+}
+
+type Ticket struct {
+	Segments []Segment
+}
+
+type Segment struct {
+	Origin, Destination string
+	Date                time.Time
+} 
+```
+
+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 of this task. 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. 
+
+```go
+import (
+	"github.com/antonmedv/expr"
+	"github.com/antonmedv/expr/vm"
+)
+
+var program *vm.Program
+
+program, err = expr.Compile(rule, expr.Env(&Request{}))
+```
+
+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. Why we used reverence type will be explained later, when we add functions. Now users can save expressions.
+
+```coffeescript
+all(Ticket.Segments, {.Origin == Location}) and Date.Before(Ticket.Segments[0].Date)
+``` 
+
+Now we need to implement the execution of our compiled program. On each request, we have some kind of filter loop.
+
+```go
+output, err := expr.Run(program, requset)
+if err != nil {
+	return err
+}
+
+if !output.(bool) {
+	continue
+}
+```
+
+Now let's some add a function for repetitive tasks. 
+
+```go
+func (r *Requset) SameLocation() bool {
+	same := false
+	for _, s := range r.Ticket.Segments {
+		same = same && s.Origin == r.Location
+	}
+	return same
+}
+```
+
+Now users can use functions inside expressions.
+
+```coffeescript
+SameLocation() and Date.Before(Ticket.Segments[0].Date)
+```
+
+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.
+
+```go
+func (*Requset) Before(a, b time.Time) bool {
+	return a.Before(b)
+}
+```
+
+Now, on compile time, override `<` operator.
+
+```go
+program, err = expr.Compile(rule, expr.Env(&Request{}), expr.Operator("<", "Before"))
+```
+
+That's it! Now users can write expressions in a more pleasant way. Other operators `>`, `===`, etc can be overridden if similar way.
+
+```coffeescript
+SameLocation() and Date < Ticket.Segments[0].Date
+```
+
+Next
+* [Language Definition](Language-Definition.md)
+* [Usage](Usage.md)

docs/README.md

@@ -1,4 +1,5 @@
 # Documentation
 
-* [Usage](Usage.md)
+* [Getting Started](Getting-Started.md)
 * [Language Definition](Language-Definition.md)
+* [Usage](Usage.md)

expr_test.go

@@ -230,6 +230,51 @@ func ExampleOperator() {
 	// Output: true
 }
 
+func ExampleOperator_time() {
+	type Segment struct {
+		Date time.Time
+	}
+	type Request struct {
+		Segments []Segment
+		Before   func(a, b time.Time) bool
+		Date     func(s string) time.Time
+	}
+
+	code := `Date("2001-01-01") < Segments[0].Date`
+
+	program, err := expr.Compile(code, expr.Env(&Request{}), expr.Operator("<", "Before"))
+	if err != nil {
+		fmt.Printf("%v", err)
+		return
+	}
+
+	request := &Request{
+		Segments: []Segment{
+			{Date: time.Date(2019, 7, 1, 0, 0, 0, 0, time.UTC)},
+		},
+		Before: func(a, b time.Time) bool {
+			return a.Before(b)
+		},
+		Date: func(s string) time.Time {
+			date, err := time.Parse("2006-01-02", s)
+			if err != nil {
+				panic(err)
+			}
+			return date
+		},
+	}
+
+	output, err := expr.Run(program, request)
+	if err != nil {
+		fmt.Printf("%v", err)
+		return
+	}
+
+	fmt.Printf("%v", output)
+
+	// Output: true
+}
+
 func ExampleEval_marshal() {
 	env := map[string]int{
 		"foo": 1,