From 2222991a925ee289be859cb2538fe017c79204a4 Mon Sep 17 00:00:00 2001
From: Jonathan Turner <jonathandturner@users.noreply.github.com>
Date: Wed, 2 Mar 2016 14:40:07 -0500
Subject: [PATCH] Update README.md

---
 README.md | 81 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 81 insertions(+)

diff --git a/README.md b/README.md
index bd1c10fc..bfd0467b 100644
--- a/README.md
+++ b/README.md
@@ -4,4 +4,85 @@ Rhai is a simple embedded scripting language for Rust that doesn't use any addit
 
 Currently, it's pre-0.1, and is likely to change a bit before it stabilizes enough for a crates.io release.
 
+# Example 1: Hello world
 
+```Rust
+let mut engine = Engine::new();
+
+if let Ok(result) = engine.eval("40 + 2".to_string()).unwrap().downcast::<i32>() {
+    println!("Answer: {}", *result);  // prints 42
+}
+```
+
+# Example 2: Working with Rust
+
+Here's an example of working with Rust.  First, the full example, and then we'll break it down:
+```Rust
+#[derive(Debug, Clone)]
+struct TestStruct {
+    x: i32
+}
+
+impl TestStruct {
+    fn update(&mut self) {
+        self.x += 1000;
+    }
+
+    fn new() -> TestStruct {
+        TestStruct { x: 1 }
+    }
+}
+
+let mut engine = Engine::new();
+
+engine.register_type::<TestStruct>();
+
+&(TestStruct::update as fn(&mut TestStruct)->()).register(&mut engine, "update");
+&(TestStruct::new as fn()->TestStruct).register(&mut engine, "new_ts");
+
+if let Ok(result) = engine.eval("var x = new_ts(); x.update(); x".to_string()).unwrap().downcast::<TestStruct>() {
+    println!("result: {}", result.x); // prints 1001
+}
+```
+
+First, for each type we use with the engine, we need to be able to Clone.  This allows the engine to pass by value and still keep its own state.
+
+```Rust
+#[derive(Debug, Clone)]
+struct TestStruct {
+    x: i32
+}
+```
+
+Next, we create a few methods that we'll later use in our scripts.  Notice that we register our custom type with the engine.
+```
+impl TestStruct {
+    fn update(&mut self) {
+        self.x += 1000;
+    }
+
+    fn new() -> TestStruct {
+        TestStruct { x: 1 }
+    }
+}
+
+let mut engine = Engine::new();
+
+engine.register_type::<TestStruct>();
+```
+
+To use methods and functions with the engine, we need to register them.  There are some convenience functions to help with this.  Below I register update and new with the engine.
+
+Note: the engine follows the convention that functions take ownership of all their parameters and methods take ownership of all but their first parameter (which is a &mut). 
+
+```
+&(TestStruct::update as fn(&mut TestStruct)->()).register(&mut engine, "update");
+&(TestStruct::new as fn()->TestStruct).register(&mut engine, "new_ts");
+```
+
+Finally, we call our script.  The script can see the function and method we registered earlier.  We need to get the result back out from script land just as before, this time casting to our custom struct type.
+```
+if let Ok(result) = engine.eval("var x = new_ts(); x.update(); x".to_string()).unwrap().downcast::<TestStruct>() {
+    println!("result: {}", result.x); // prints 1001
+}
+```