From 86e129d99829294aac59e7713956dd62891cc09d Mon Sep 17 00:00:00 2001
From: Ruben Ayrapetyan <r.ayrapetyan@samsung.com>
Date: Sun, 14 Jun 2015 22:40:16 +0300
Subject: [PATCH] Update development guide

---
 05.dev-guide.md | 132 +++++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 126 insertions(+), 6 deletions(-)

diff --git a/05.dev-guide.md b/05.dev-guide.md
index 85f4d3218..2ff8aed7b 100644
--- a/05.dev-guide.md
+++ b/05.dev-guide.md
@@ -17,12 +17,9 @@ int
 main (int argc, char * argv[]) {
   char script [] = "print ('Hello, World!');";
 
-  jerry_init (JERRY_FLAG_EMPTY);
-
-  jerry_parse (script, strlen (script));
-  jerry_run ();
-
-  jerry_cleanup ();
+  jerry_completion_code_t code = jerry_run_simple (script,
+                                                   strlen (script),
+                                                   JERRY_FLAG_EMPTY);
 }
 ```
 
@@ -32,8 +29,131 @@ The described application will generate the following output:
 Hello, World!
 ```
 
+## Adding more control over what's happening
+
+Here we perform the same actions, as `jerry_run_simple`, while splitting into several steps:
+
+- engine initialization
+- script code setup
+- script execution
+- engine free
+
+
+```cpp
+#include <string.h>
+#include "jerry.h"
+
+int
+main (int argc, char * argv[]) {
+  char script [] = "print ('Hello, World!');";
+
+  jerry_init (JERRY_FLAG_EMPTY);
+
+  jerry_parse (script, strlen (script));
+  jerry_run ();
+
+  jerry_cleanup ();
+}
+```
+
+While the code became a bit more complex, the change introduced possibilities to interact with JavaScript step by step, setup native objects and functions, etc.
+
+## 'eval'-mode execution
+
+```cpp
+#include <string.h>
+#include "jerry.h"
+
+int
+main (int argc, char * argv[]) {
+  char script1 [] = "var s = 'Hello, World!';";
+  char script2 [] = "print (s);";
+
+  jerry_init (JERRY_FLAG_EMPTY);
+
+  jerry_api_value_t eval_ret;
+
+  // Step 1
+  jerry_api_eval (script1, strlen (script1),
+                  false, false, &eval_ret);
+  jerry_api_release_value (&eval_ret);
+
+  // Step 2
+  jerry_api_eval (script2, strlen (script2),
+                  false, false, &eval_ret);
+  jerry_api_release_value (&eval_ret);
+
+  jerry_cleanup ();
+}
+```
+
+This way, we execute two independent script parts in one execution environment. The first part initializes string variable, and the second outputs the variable.
+
+## Interaction with JavaScript data
+
+```cpp
+#include <string.h>
+#include "jerry.h"
+
+int
+main (int argc, char * argv[]) {
+  char str [] = "Hello, World!";
+  char var_name [] = "s";
+  char script [] = "print (s);";
+
+  // Initializing JavaScript environment
+  jerry_init (JERRY_FLAG_EMPTY);
+
+  // Getting pointer to the Global object
+  jerry_api_object_t *obj_p = jerry_api_get_global_object ();
+
+  // Constructing string
+  jerry_api_string_t *str_val_p = jerry_api_create_string (str);
+
+  // Construction string value descriptor
+  jerry_api_value_t val;
+  val.type = JERRY_API_DATA_TYPE_STRING;
+  val.string_p = str_val_p;
+
+  // Setting the string value to field of the Global object
+  jerry_api_set_object_field_value (obj_p, var_name, &val);
+
+  // Releasing string value, as it is no longer necessary outside of engine
+  jerry_api_release_string (str_val_p);
+
+  // Same for pointer to the Global object
+  jerry_api_release_object (obj_p);
+
+  jerry_api_value_t eval_ret;
+
+  // Now starting script that would output value of just initialized field
+  jerry_api_eval (script, strlen (script),
+                  false, false, &eval_ret);
+  jerry_api_release_value (&eval_ret);
+
+  // Freeing engine
+  jerry_cleanup ();
+}
+```
+
+The sample would also output 'Hello, World!'.
+
+However, now we have base for some real application.
+
 ## Simple JavaScript shell
 
+Let's construct simple JavaScript shell.
+
+Shell operation can be described with following loop:
+
+- read command;
+- if command is 'quit'
+  - exit loop;
+- else
+  - eval (command);
+  - print result of eval;
+  - loop.
+
 ```cpp
 #include <assert.h>
 #include <stdio.h>