From bd057811ba4a93032b48f6df5dae9845a131910f Mon Sep 17 00:00:00 2001 From: Lumi Pakkanen Date: Tue, 23 Apr 2024 09:50:09 +0300 Subject: [PATCH] Add a few words about the most commonly used helper functions Move built-in docs under documentation folder. --- README.md | 4 +- BUILTIN.md => documentation/BUILTIN.md | 0 documentation/dsl.md | 95 ++++++++++++++++++++++++++ package.json | 2 +- 4 files changed, 98 insertions(+), 3 deletions(-) rename BUILTIN.md => documentation/BUILTIN.md (100%) diff --git a/README.md b/README.md index f6058ba7..ce594384 100644 --- a/README.md +++ b/README.md @@ -728,10 +728,10 @@ SonicWeave comes with batteries included. | `TAU` | `6.283185307179586r` | The [superior circle constant](https://tauday.com/tau-manifesto) | ### Built-in functions -See [BUILTIN.md](https://github.com/xenharmonic-devs/sonic-weave/blob/main/BUILTIN.md#built-in-functions). +See [BUILTIN.md](https://github.com/xenharmonic-devs/sonic-weave/blob/main/documentation/BUILTIN.md#built-in-functions). ### Prelude functions -See [BUILTIN.md](https://github.com/xenharmonic-devs/sonic-weave/blob/main/BUILTIN.md#prelude-functions). +See [BUILTIN.md](https://github.com/xenharmonic-devs/sonic-weave/blob/main/documentation/BUILTIN.md#prelude-functions). ## Odds and ends Most of these features were implemented for their own sake. diff --git a/BUILTIN.md b/documentation/BUILTIN.md similarity index 100% rename from BUILTIN.md rename to documentation/BUILTIN.md diff --git a/documentation/dsl.md b/documentation/dsl.md index f845c331..b8c45bd3 100644 --- a/documentation/dsl.md +++ b/documentation/dsl.md @@ -548,3 +548,98 @@ C5 311@ ``` + +## Helper functions + +We already saw `mtof(60)` and `sort()` above. There are plenty more, but here's a table of commonly used ones. + +| Helper | Description | +| -------------- | ------------------------------------------------- | +| clear() | Replace the scale with an empty one | +| keepUnique() | Remove duplicate intervals from the scale | +| mtof(midiNote) | Get the frequency corresponding to the MIDI note | +| FJS | Convert fractions to Functional Just Systems | +| absoluteFJS | Convert fractions to absolute pitch notation with FJS inflections | +| reduce | Reduce pitches in the scale to lie between unison and the octave (or generic equave) | +| relin | Convert FJS to fractions. Converts anything to relative linear format | +| rotate(degree) | Rotate the scale to start on the given degree | +| simplify | Simplify fractions by reducing common factors | +| sort() | Sort the scale in ascending order | +| stack() | Stack intervals in the scale on top of each other | +| tet(N) | Generate one octave of N-tone equal temperament | + +Some helpers need to be called like `sort()` while other's like `simplify` are implicitly mapped over the current scale. Let's demonstrate with our major that has been code-golfed to obscurity: + +```c +1=262z +24:27:30:32:36:40:45:48 +``` + +The intervals will format as `27/24`, `30/24`, etc. but those are just `9/8` and `5/4` with a complicated denominator. Tagging a `simplify` at the end reduces the fractions: + +```c +1 = 262 Hz +24:27:30:32:36:40:45:48 +simplify +``` + +The result will format as `9/8`, `5/4`, `4/3`, etc. . + +With `FJS` tagged at the end + +```c +1 = 262 Hz +24:27:30:32:36:40:45:48 +FJS +``` + +we obtain `M2`, `M3^5`, `P4`, etc. . + +To go from (absolute) FJS to fractions we can use `relin`: + +```c +A4 = 440 Hz + +B4 +C5_5 +D5 +E5 +F5_5 +G5_5 +A5 + +relin +``` + +The result is the same as if we had entered: +```c +1/1 = 440 Hz + +9/8 +6/5 +4/3 +3/2 +8/5 +9/5 +2/1 +``` + +The `reduce` helper allows us to be imprecise with octaves. The above spelled sloppily is: + +```c +1 = 440 Hz + +9 +3/5 +1/3 +3 +1/5 +9/5 +2 + +reduce +``` + +These helpers can be freely combined. A common task is to reduce the scale and sort it only keeping unique intervals. The handy `organize()` helper does just that. + +There are plenty more helpers in SonicWeave: See [BUILTIN.md](https://github.com/xenharmonic-devs/sonic-weave/blob/main/documentation/BUILTIN.md). diff --git a/package.json b/package.json index faaa9eb9..7a414d0f 100644 --- a/package.json +++ b/package.json @@ -52,7 +52,7 @@ "bench": "vitest bench", "doc": "typedoc src/index.ts . --name sonic-weave", "preautodoc": "npm run precompile && tsc -p tsconfig-autodoc.json", - "autodoc": "node .temp/scripts/builtin-docs.js > BUILTIN.md", + "autodoc": "node .temp/scripts/builtin-docs.js > documentation/BUILTIN.md", "preinspect-grammar": "npm run compile-sonic-weave-parser", "inspect-grammar": "node scripts/inspect-printable-ascii.js", "preinspect-random": "npm run compile-sonic-weave-parser",