From 60b6cdf180d9087796a6d66b957a7849d39a0f6e Mon Sep 17 00:00:00 2001
From: Sebastian Schmidt <isibboi@gmail.com>
Date: Thu, 29 Aug 2019 10:47:58 +0300
Subject: [PATCH] Add documentation about context creation macro

Implements #48
---
 README.md  | 32 ++++++++++++++++++++++++++++++++
 src/lib.rs | 32 ++++++++++++++++++++++++++++++++
 2 files changed, 64 insertions(+)

diff --git a/README.md b/README.md
index 4724065..2779d8c 100644
--- a/README.md
+++ b/README.md
@@ -242,6 +242,38 @@ This means that assigning to `a` again with a different type yields an error as
 Type unsafe contexts may be implemented if requested.
 For reading `a`, it is enough to pass an immutable reference.
 
+Contexts can also be manipulated in code.
+Take a look at the following example:
+
+```rust
+use evalexpr::*;
+
+let mut context = HashMapContext::new();
+// We can set variables in code like this...
+context.set_value("a".into(), 5.into());
+// ...and read from them in expressions
+assert_eq!(eval_int_with_context("a", &context), Ok(5));
+// We can write or overwrite variables in expressions...
+assert_eq!(eval_with_context_mut("a = 10; b = 1.0;", &mut context), Ok(().into()));
+// ...and read the value in code like this
+assert_eq!(context.get_value("a"), Some(&Value::from(10)));
+assert_eq!(context.get_value("b"), Some(&Value::from(1.0)));
+```
+
+Contexts are also required for user-defined functions.
+Those can be passed one by one with the `set_function` method, but it might be more convenient to use the `context_map!` macro instead:
+
+```rust
+use evalexpr::*;
+
+let context = context_map!{
+    "f" => Function::new(Box::new(|args| Ok(Value::from(args.as_int()? + 5)))),
+};
+assert_eq!(eval_int_with_context("f 5", &context), Ok(10));
+```
+
+For more information about user-defined functions, refer to the respective [section](#user-defined-functions).
+
 ### Builtin Functions
 
 This crate offers a set of builtin functions.
diff --git a/src/lib.rs b/src/lib.rs
index ab7fc4d..3cc08e7 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -229,6 +229,38 @@
 //! Type unsafe contexts may be implemented if requested.
 //! For reading `a`, it is enough to pass an immutable reference.
 //!
+//! Contexts can also be manipulated in code.
+//! Take a look at the following example:
+//!
+//! ```rust
+//! use evalexpr::*;
+//!
+//! let mut context = HashMapContext::new();
+//! // We can set variables in code like this...
+//! context.set_value("a".into(), 5.into());
+//! // ...and read from them in expressions
+//! assert_eq!(eval_int_with_context("a", &context), Ok(5));
+//! // We can write or overwrite variables in expressions...
+//! assert_eq!(eval_with_context_mut("a = 10; b = 1.0;", &mut context), Ok(().into()));
+//! // ...and read the value in code like this
+//! assert_eq!(context.get_value("a"), Some(&Value::from(10)));
+//! assert_eq!(context.get_value("b"), Some(&Value::from(1.0)));
+//! ```
+//!
+//! Contexts are also required for user-defined functions.
+//! Those can be passed one by one with the `set_function` method, but it might be more convenient to use the `context_map!` macro instead:
+//!
+//! ```rust
+//! use evalexpr::*;
+//!
+//! let context = context_map!{
+//!     "f" => Function::new(Box::new(|args| Ok(Value::from(args.as_int()? + 5)))),
+//! };
+//! assert_eq!(eval_int_with_context("f 5", &context), Ok(10));
+//! ```
+//!
+//! For more information about user-defined functions, refer to the respective [section](#user-defined-functions).
+//!
 //! ### Builtin Functions
 //!
 //! This crate offers a set of builtin functions.