From 1a672fd6704675bd33f2fb73017220f2cbd04b28 Mon Sep 17 00:00:00 2001
From: Lumi Pakkanen <lumi.pakkanen@gmail.com>
Date: Sun, 5 May 2024 13:26:22 +0300
Subject: [PATCH] Add couple of words about embedding

---
 documentation/package.md | 49 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 49 insertions(+)

diff --git a/documentation/package.md b/documentation/package.md
index 71a42830..1cfed5c2 100644
--- a/documentation/package.md
+++ b/documentation/package.md
@@ -97,3 +97,52 @@ The properties of `Val` are as follows:
 - `.value: TimeMonzo` the mapping entries as `.value.primeExponents`
 - `.equave: TimeMonzo` the equave of the equal temperament
 - `.node: IntervalLiteral | undefined` as virtual AST node used for string representation
+
+## Embedding SonicWeave
+Scale Workshop 3 embeds the `sonic-weave` package in order to execute source code written in SonicWeave. Here's how to do it in your application.
+
+### Parsing
+The first step is to parse text into an abstract syntax tree.
+```ts
+import {parseAST} from 'sonic-weave';
+
+// In practice the source code would come from the user of your application.
+const source = '5/4;P4 + P4;2';
+
+const program = parseAST(source);
+/*
+{
+  type: "Program",
+  body: [
+    {
+      type: "ExpressionStatement",
+      expression: [Object ...],
+    }, {
+      type: "ExpressionStatement",
+      expression: [Object ...],
+    }, {
+      type: "ExpressionStatement",
+      expression: [Object ...],
+    }
+  ],
+}
+*/
+```
+
+### Execution
+The next steps are to execute the program, collect the resulting scale consisting of `Interval` instances and convert the result to something usable by your application.
+```ts
+import {parseAST, getSourceVisitor} from 'sonic-weave';
+
+const source = '5/4;P4 + P4;2';
+
+const program = parseAST(source);
+
+const visitor = getSourceVisitor();
+visitor.executeProgram(program);
+
+const scale = visitor.currentScale;
+
+const scaleCents = scale.map(interval => interval.totalCents());
+// [ 386.3137138648349, 996.0899982692249, 1200 ]
+```