1 files changed, 117 insertions, 0 deletions
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..eefb8d7
--- /dev/null
+++ b/README.md
@@ -0,0 +1,117 @@
+# wmap-parser-swift
+
+A parser for `wmap` formatted Wardley Map files built in Swift.
+
+## Features
+
+* No dependencies.
+* Free software.
+* Reasonably fast.
+
+## Installation
+
+Add it to your project using Swift Package Manager by adding the following to your `Package.swift`:
+
+```swift
+dependencies: [
+    .package(url: "https://git.sr.ht/~rbdr/wmap-parser-swift", from: "1.0.0")
+]
+```
+
+Or add it directly in Xcode using File > Add Packages...
+
+## Usage
+
+```swift
+import WmapParser
+
+let wmapSource = """
+[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(wmapSource)
+
+print(map.components)
+// [
+//   Component(label: "Tea", coordinates: (0.9, 0.5), shape: .circle),
+//   Component(label: "Cup", coordinates: (0.8, 0.4), shape: .circle),
+//   ...
+// ]
+
+print(map.dependencies)
+// [
+//   Dependency(from: "Tea", to: "Cup", isDirected: true),
+//   ...
+// ]
+```
+
+## API
+
+### `parse(_ source: String) -> Map`
+
+Parses a wmap formatted string and returns a Map object.
+
+**Parameters:**
+
+- `source` (String): 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 14µs.
+While a larger map with slightly under 2000 entities does so in 230µ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-rust) - Rust wmap-parser
+- [Wardley Maps](https://wardleymaps.com/) - Learn about Wardley Mapping