doc: update README, yaegi command doc (#245)

README.md

@@ -1,27 +1,113 @@
-# Go interpreter
+<p align="center">
+<img width="400" src="doc/images/yaegi.png" alt="Yaegi" title="Yaegi" />
+</p>
 
 [![Build Status](https://semaphoreci.com/api/v1/projects/8a9d3e41-0a4f-408e-a477-3c9c7418314d/2583906/badge.svg)](https://semaphoreci.com/containous/yaegi)
 
-A Go interpreter in go
+Yaegi is Another Elegant Go Interpreter. It powers executable Go scripts and plugins, in embedded interpreters or interactive shells, on top of the Go runtime.
 
-## Tests
+## Features
 
-Tests are simple standalone go programs to be run by `gi` executable.
+* Complete support of [Go specification][specs]
+* In pure Go, using only standard library
+* Simple interpreter API: `New()`, `Eval()`, `Use()`
+* works everywhere Go works
+* All Go & runtime resources accessible from script (with control)
+* Security: `unsafe` and `syscall` packages not used or exported by default
 
-Scripts are converted to go test examples for execution by `go test` as well.
-To create a new test, simply add a new .gi file, specifying expected output at end of program in a `// Output:` comment block like in the following example:
+## Install
+
+```console
+go get -u github.com/containous/yaegi
+```
+
+## Usage
+
+### As a command line interpreter
+
+The Yaegi command can run an interactive Read-Eval-Print-Loop:
+
+```console
+$ yaegi
+> 1 + 2
+3
+> import "fmt"
+> fmt.Println("Hello World")
+Hello World
+>
+```
+
+Or interpret Go files:
+
+```console
+$ yaegi cmd/yaegi/yaegi.go
+>
+```
+
+### As an embedded interpreter
+
+Create an interpreter with `New()`, run Go code with `Eval()`:
 
 ```go
 package main
 
-func main() {
-	println("Hello")
-}
+import (
+	"github.com/containous/yaegi/interp"
+	"github.com/containous/yaegi/stdlib"
+)
 
-// Output:
-// Hello
+func main() {
+	i := interp.New(interp.Options{})
+	i.Use(stdlib.Symbols)
+	i.Eval(`import "fmt"`)
+	i.Eval(`fmt.Println("hello")`)
+}
 ```
 
-Then in `_test/`, run `make` to re-generate `interp/eval_test.go`
+### As a dynamic extension framework
 
-When developing/debugging, I'm running `gi` on a single script, using `-a` and `-c` options to display AST and CFG graphs, and instrumenting code with temporary println statements to diagnose problems.
+The following program is compiled ahead of time, except `bar()` which is interpreted, with the following steps:
+
+1. use of `i.Eval(src)` to evaluate the script in the context of interpreter
+2. use of `v, _ := i.Eval("foo.Bar")` to get the symbol from the interpreter context,  as a `reflect.Value`
+3. application of `Interface()` method and type assertion to convert `v` into `bar`, as if it was compiled
+
+```go
+package main
+
+import "github.com/containous/yaegi/interp"
+
+const src = `package foo
+func Bar(s string) string { return s + "-Foo" }`
+
+func main() {
+	i := interp.New(interp.Options{})
+	i.Eval(src)
+	v, _ := i.Eval("foo.Bar")
+	bar := v.Interface().(func(string) string)
+
+	r := bar("Kung")
+	println(r)
+}
+```
+
+## Documentation
+
+Documentation about yaegi commands and libraries can be found at usual [godoc.org][docs].
+
+## Contributing
+
+Yaegi is an open source project, and your feedback and contributions are needed and always welcome.
+
+[Issues] and [pull requests] are opened at https://github.com/containous/yaegi
+
+## License
+
+[Apache 2.0][License].
+
+[specs]: https://golang.org/ref/spec
+[docs]: https://godoc.org/github.com/containous/yaegi
+[license]: https://github.com/containous/yaegi/blob/master/LICENSE
+[github]: https://github.com/containous/yaegi
+[Issues]: https://github.com/containous/yaegi/issues
+[pull requests]: https://github.com/containous/yaegi/issues

cmd/yaegi/yaegi.go

@@ -1,3 +1,31 @@
+/*
+Yaegi interprets Go programs.
+
+Yaegi reads Go language programs from its standard input or from a file
+and evaluates them.
+
+If invoked with no arguments, it processes the standard input
+in a Read-Eval-Print-Loop. A prompt is displayed if standard input
+is a terminal.
+
+Given a file, it operates on that file. if the first line starts with
+"#!/usr/bin/env yaegi", and the file has exec permission, then the file
+can be invoked directly from the shell.
+
+In file mode, as in standard Go, files are read entirely, then parsed,
+then evaluated. In REPL mode, each line is parsed and evaluated separately,
+at global level in an implicit main package.
+
+Options:
+    -i
+	   start an interactive REPL after file execution
+
+Debugging support (may be removed at any time):
+  YAEGI_AST_DOT=1
+    Generate and display graphviz dot of AST with dotty(1)
+  YAEGI_CFG_DOT=1
+    Generate and display graphviz dot of CFG with dotty(1)
+*/
 package main
 
 import (

interp/doc.go

@@ -0,0 +1,10 @@
+/*
+Package interp provides a complete Go interpreter
+
+For the Go language itself, refer to the official Go specification
+https://golang.org/ref/spec.
+
+*/
+package interp
+
+// BUG(marc): Type checking is not implemented yet