Usage documentation

README.md

@@ -30,6 +30,8 @@ RSC will not have any major changes to its syntax. It will remain to be consiste
 RSC is MIT licensed. RSC will always remain free to modify and use without attribution.
 
 # Example
+## Executable
+Using RSC as the actual program provides a simple interface for solving expressions. A right arrow shows where the user can input an expression, and upon pressing the Return key, the result of the entered expression is displayed on the next line.
 ```
 PS C:\Users\Luke> rsc
 >2+2
@@ -51,6 +53,32 @@ Compute error: UnrecognizedIdentifier("b")
 >abs -3
 3
 ```
+## Library
+RSC is very painless to use. For simple, one-off expression solving:
+```rs
+extern crate rsc;
+
+use rsc::eval;
+
+fn main() {
+    assert!(eval("5^2").unwrap() == 25.0);
+    assert!(eval("x = 5").unwrap() == 5.0);
+    assert!(eval("x").is_err()); // Previously assigned variables are discarded
+}
+```
+In order to keep variables, you must create a `Computer` instance:
+```rs
+extern crate rsc;
+
+use rsc::computer::Computer;
+
+fn main() {
+    let mut c = Computer::new();
+
+    assert!(c.eval("x = 5").unwrap() == 5.0);
+    assert!(c.eval("x^2").unwrap() == 25.0);
+}
+```
 ## Debug
 RSC can be run with the `ast` flag and show the internal expression that was created by the parser. This is most commonly used for entertainment purposes 😛.
 ```

src/bin/main.rs

@@ -1,5 +1,3 @@
-#![feature(test)]
-
 use std::io::prelude::*;
 
 use rsc::lexer::*;

src/computer.rs

@@ -15,9 +15,7 @@ pub enum ComputeError {
     UnrecognizedIdentifier(String),
 }
 
-/// A Computer object calculates expressions and has variables. One
-/// could also just create a temporary Computer object for calculation
-/// to disregard variable usage.
+/// A Computer object calculates expressions and has variables.
 /// ```
 /// let mut computer = Computer::new();
 /// assert_eq!(computer.eval("a = 2"), Ok(2.0));

src/lib.rs

@@ -4,6 +4,53 @@
 //! If you need a portion of the calculator changed or removed, please fork it, and make your
 //! changes. We encourage others to change RSC to their liking. You do not need to attribute
 //! anything to us. This is MIT licensed software.
+//! 
+//! Anyone can easily create a [Calculator](computer/struct.Computer.html) and begin working with expressions. Calculators
+//! also remember variables using a HashMap. You can create and begin using the Calculator like so:
+//! ```
+//! extern crate rsc;
+//! 
+//! use rsc::computer::Computer;
+//!
+//! fn main() {
+//!     let mut c = Computer::new();
+//!
+//!     assert!(c.eval("x = 5").unwrap() == 5.0);
+//!     assert!(c.eval("x^2").unwrap() == 25.0);
+//! }
+//! ```
+//! 
+//! In most cases a simple `eval` should be all you need, but just as many times you may need
+//! to directly access the tokens and AST. Some reasons may include:
+//! * For performance or caching; lexing and parsing an expression only once, to calculate it later hundreds
+//! of times in a loop.
+//! * Better error messages or visual information for what is happening.
+//! ```
+//! extern crate rsc;
+//! 
+//! use rsc::lexer::tokenize;
+//! use rsc::parser::{Expr, parse};
+//! use rsc::computer::Computer;
+//! 
+//! fn main() {
+//!     let expr = "x^2";
+//!     let tokens = tokenize(expr).unwrap();
+//!     let ast = parse(&tokens).unwrap();
+//!     let mut computer = Computer::new();
+//!     
+//!     for x in 2..=5 {
+//!         let mut ast = ast.clone();
+//!         ast.replace(&Expr::Identifier("x"), &Expr::Constant(x as f64), false);
+//!         println!("{}", computer.compute(&ast).unwrap());
+//!     }
+//! }
+//! 
+//! // Output:
+//! // 4
+//! // 9
+//! // 16
+//! // 25
+//! ```
 
 #![feature(test)]