1 files changed, 115 insertions, 0 deletions
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..51a8608
--- /dev/null
+++ b/README.md
@@ -0,0 +1,115 @@
+# wmap-parser-rust
+
+A parser for `wmap` formatted Wardley Map files built in rust.
+
+## Features
+
+* No dependencies.
+* Free software.
+* Reasonably fast.
+
+## Installation
+
+Add it to your project with cargo add
+
+```bash
+cargo add wmap-parser
+```
+
+## Usage
+
+```rust
+use wmap_parser::parse;
+
+fn main() {
+    let wmap_source = r#"
+[I] 0.25
+[II] 0.5
+[III] 0.75
+[IV] 1.0
+
+Tea (0.9, 0.5) [Circle]
+Cup (0.8, 0.4)
+Hot Water (0.6, 0.2)
+
+Tea -> Cup
+Cup -> Hot Water
+
+[Note] (0.5, 0.5) Supply chain for tea
+[Group] Tea, Cup
+[Inertia] Cup
+[Evolution] Tea + 0.1
+"#;
+
+    let map = parse(wmap_source);
+
+    println!("{:?}", map.components);
+    // [
+    //   Component { label: "Tea", coordinates: (0.9, 0.5), shape: Circle },
+    //   Component { label: "Cup", coordinates: (0.8, 0.4), shape: Circle },
+    //   ...
+    // ]
+
+    println!("{:?}", map.dependencies);
+    // [
+    //   Dependency { from: "Tea", to: "Cup", is_directed: true },
+    //   ...
+    // ]
+}
+```
+
+## API
+
+### `parse(source: &str) -> Map`
+
+Parses a wmap formatted string and returns a Map object.
+
+**Parameters:**
+
+- `source` (&str): The wmap source code to parse
+
+**Returns:**
+
+- `Map`: A Map struct containing the parsed components, dependencies, notes,
+    stages, groups, inertias, and evolutions
+
+## Format Specification
+
+See [The map website](https://map.tranquil.systems) for more information on the
+format.
+
+## Reasonably Fast
+
+Benchmarked on an M1 Pro mac. A map with around 120 entities parses in 7µs.
+While a larger map with slightly under 2000 entities does so in 215µs.
+
+You can run the benchmarks by using:
+
+```bash
+make benchmark
+```
+
+## Development
+
+This project uses a Makefile to run all commands. This is to keep the
+commands uniform with the other wmap-parser projects.
+
+### Running Tests
+
+```bash
+make test
+```
+
+Or to see coverage
+
+```bash
+make coverage
+```
+
+## See Also
+
+- [wmap specification](doc/wmap-spec.ebnf) - Formal grammar
+- [wmap specification](https://git.sr.ht:~rbdr/wmap-parser-js) - Javascript wmap-parser
+- [wmap specification](https://git.sr.ht:~rbdr/wmap-parser-c) - ANSI C wmap-parser
+- [wmap specification](https://git.sr.ht:~rbdr/wmap-parser-swift) - Swift wmap-parser
+- [Wardley Maps](https://wardleymaps.com/) - Learn about Wardley Mapping