From 1e3bbc57cc45d71728ddf2cfbe4e55289c991d31 Mon Sep 17 00:00:00 2001 From: Alex McLean <alex@slab.org> Date: Sun, 29 Dec 2024 12:16:08 +0000 Subject: [PATCH] Documentation for all/each, and bugfix for each (#1233) * bugfix for each(), and documentation for each() and all() * had to hide each/all examples from tests --- packages/core/repl.mjs | 26 ++++++++++++++++++- .../src/repl/components/panel/Reference.jsx | 4 +-- 2 files changed, 27 insertions(+), 3 deletions(-) diff --git a/packages/core/repl.mjs b/packages/core/repl.mjs index 7d3215a99..e703909ff 100644 --- a/packages/core/repl.mjs +++ b/packages/core/repl.mjs @@ -86,10 +86,33 @@ export function repl({ const toggle = () => scheduler.toggle(); const setCps = (cps) => scheduler.setCps(cps); const setCpm = (cpm) => scheduler.setCps(cpm / 60); + + // TODO - not documented as jsdoc examples as the test framework doesn't simulate enough context for `each` and `all`.. + + /** Applies a function to all the running patterns. Note that the patterns are groups together into a single `stack` before the function is applied. This is probably what you want, but see `each` for + * a version that applies the function to each pattern separately. + * ``` + * $: sound("bd - cp sd") + * $: sound("hh*8") + * all(fast("<2 3>")) + * ``` + * ``` + * $: sound("bd - cp sd") + * $: sound("hh*8") + * all(x => x.pianoroll()) + * ``` + */ const all = function (transform) { allTransform = transform; return silence; }; + /** Applies a function to each of the running patterns separately. This is intended for future use with upcoming 'stepwise' features. See `all` for a version that applies the function to all the patterns stacked together into a single pattern. + * ``` + * $: sound("bd - cp sd") + * $: sound("hh*8") + * each(fast("<2 3>")) + * ``` + */ const each = function (transform) { eachTransform = transform; return silence; @@ -161,7 +184,8 @@ export function repl({ if (Object.keys(pPatterns).length) { let patterns = Object.values(pPatterns); if (eachTransform) { - patterns = patterns.map(eachTransform); + // Explicit lambda so only element (not index and array) are passed + patterns = patterns.map((x) => eachTransform(x)); } pattern = stack(...patterns); } else if (eachTransform) { diff --git a/website/src/repl/components/panel/Reference.jsx b/website/src/repl/components/panel/Reference.jsx index 078208071..fbbf0a08c 100644 --- a/website/src/repl/components/panel/Reference.jsx +++ b/website/src/repl/components/panel/Reference.jsx @@ -58,8 +58,8 @@ export function Reference() { <div className="prose dark:prose-invert min-w-full px-1 "> <h2>API Reference</h2> <p> - This is the long list functions you can use! Remember that you don't need to remember all of those and that - you can already make music with a small set of functions! + This is the long list of functions you can use. Remember that you don't need to remember all of those and + that you can already make music with a small set of functions! </p> {visibleFunctions.map((entry, i) => ( <section key={i}>