Closes #125

Adds documentation for the new feature
Removes usages of  "sol::bond" in documentation, because that was supposed to be "sol::tie"
I really don't want to spend time trying to figure out how to slim down these templates...

docs/source/api/function.rst

@@ -41,7 +41,7 @@ The following C++ code will call this function from this file and retrieve the r
 
 The call ``woof(20)`` generates a :ref:`function_result<function-result>`, which is then implicitly converted to an ``double`` after being called. The intermediate temporary ``function_result`` is then destructed, popping the Lua function call results off the Lua stack. 
 
-You can also return multiple values by using std::tuple, or if you need to bind them to pre-existing variables use ``sol::bond``:
+You can also return multiple values by using ``std::tuple``, or if you need to bind them to pre-existing variables use ``sol::tie``:
 
 .. code-block:: cpp
 	:linenos:
@@ -54,9 +54,9 @@ You can also return multiple values by using std::tuple, or if you need to bind
 	std::tuple<int, int, int> abc = f(); // 10, 11, 12 from Lua
 	// or
 	int a, b, c;
-	sol::bond(a, b, c) = f(); // a = 10, b = 11, c = 12 from Lua
+	sol::tie(a, b, c) = f(); // a = 10, b = 11, c = 12 from Lua
 
-This makes it much easier to work with multiple return values. Using ``std::tie`` from the C++ standard will result in dangling references or bad behavior because of the very poor way in which C++ tuples were implemented: please use ``sol::bond( ... )`` instead to satisfy any multi-return needs.
+This makes it much easier to work with multiple return values. Using ``std::tie`` from the C++ standard will result in dangling references or bad behavior because of the very poor way in which C++ tuples/``std::tie`` were specified and implemented: please use ``sol::tie( ... )`` instead to satisfy any multi-return needs.
 
 .. _function-result-warning:
 

docs/source/api/state.rst

@@ -53,10 +53,12 @@ This function takes a number of :ref:`sol::lib<lib-enum>` as arguments and opens
 .. code-block:: cpp
 	:caption: function: script / script_file
 
-	void script(const std::string& code);
+	sol::function_result script(const std::string& code);
-	void script_file(const std::string& filename);
+	sol::function_result script_file(const std::string& filename);
 
-These functions run the desired blob of either code that is in a string, or code that comes from a filename, on the ``lua_State*``. It will not run isolated: any scripts or code run will affect code in the ``lua_State*`` the object uses as well. Code ran in this fashion is not isolated. If you need isolation, consider creating a new state or traditional Lua sandboxing techniques.
+These functions run the desired blob of either code that is in a string, or code that comes from a filename, on the ``lua_State*``. It will not run isolated: any scripts or code run will affect code in the ``lua_State*`` the object uses as well (unless ``local`` is applied to a variable declaration, as specified by the Lua language). Code ran in this fashion is not isolated. If you need isolation, consider creating a new state or traditional Lua sandboxing techniques.
+
+If your script returns a value, you can capture it from the returned :ref:`function_result<function-result>`.
 
 .. code-block:: cpp
 	:caption: function: require / require_file

sol/function_result.hpp

@@ -68,6 +68,14 @@ namespace sol {
 			return stack::get<T>(L, index);
 		}
 
+		call_status status() const noexcept {
+			return call_status::ok;
+		}
+
+		bool valid() const noexcept {
+			return status() == call_status::ok || status() == call_status::yielded;
+		}
+
 		lua_State* lua_state() const { return L; };
 		int stack_index() const { return index; };
 

sol/state_view.hpp

@@ -215,16 +215,24 @@ namespace sol {
 			return require_core(key, [this, &file]() {this->script_file(file); }, create_global);
 		}
 
-		void script(const std::string& code) {
+		function_result script(const std::string& code) {
+			int index = (::std::max)(lua_gettop(L), 1);
 			if (luaL_dostring(L, code.c_str())) {
 				lua_error(L);
+				// Rest of code will never be run because lua_error jumps out
 			}
+			int returns = lua_gettop(L) - (index - 1);
+			return function_result(L, index, returns);
 		}
 
-		void script_file(const std::string& filename) {
+		function_result script_file(const std::string& filename) {
+			int index = (::std::max)(lua_gettop(L), 1);
 			if (luaL_dofile(L, filename.c_str())) {
 				lua_error(L);
+				// Rest of code will never be run because lua_error jumps out
 			}
+			int returns = lua_gettop(L) - index;
+			return function_result(L, index, returns);
 		}
 
 		load_result load(const std::string& code) {