pick now accepts lookup tables, with alternate cycle squeezing behaviour as new inhabit function (#918)

- the args for `pick` are now reversed (breaking change!)
- `pick` is also now a method on the inhabited pattern
- `pick` now also accepts a lookup table
- `inhabit` added with same behaviour as `pick`, except cycles from source patterns are squeezed into events of inhabited patterns
- Also some general doc tidying, sorry for the noise..
- There is now also `pickmod` and `inhabitmod`, for wrapping indexes around rather than clamping them

packages/core/signal.mjs

@@ -7,7 +7,7 @@ This program is free software: you can redistribute it and/or modify it under th
 import { Hap } from './hap.mjs';
 import { Pattern, fastcat, reify, silence, stack, register } from './pattern.mjs';
 import Fraction from './fraction.mjs';
-import { id, _mod, clamp } from './util.mjs';
+import { id, _mod, clamp, objectMap } from './util.mjs';
 
 export function steady(value) {
   // A continuous value
@@ -156,31 +156,88 @@ export const _irand = (i) => rand.fmap((x) => Math.trunc(x * i));
  */
 export const irand = (ipat) => reify(ipat).fmap(_irand).innerJoin();
 
-/**
- * pick from the list of values (or patterns of values) via the index using the given
- * pattern of integers
+const _pick = function (lookup, pat, modulo = true) {
+  const array = Array.isArray(lookup);
+  const len = Object.keys(lookup).length;
+
+  lookup = objectMap(lookup, reify);
+
+  if (len === 0) {
+    return silence;
+  }
+  return pat.fmap((i) => {
+    let key = i;
+    if (array) {
+      key = modulo ? Math.round(key) % len : clamp(Math.round(key), 0, lookup.length - 1);
+    }
+    return lookup[key];
+  });
+};
+
+/** * Picks patterns (or plain values) either from a list (by index) or a lookup table (by name).
+ * Similar to `inhabit`, but maintains the structure of the original patterns.
  * @param {Pattern} pat
  * @param {*} xs
  * @returns {Pattern}
  * @example
- * note(pick("<0 1 [2!2] 3>", ["g a", "e f", "f g f g" , "g a c d"]))
+ * note("<0 1 2!2 3>".pick(["g a", "e f", "f g f g" , "g c d"]))
+ * @example
+ * sound("<0 1 [2,0]>".pick(["bd sd", "cp cp", "hh hh"]))
+ * @example
+ * sound("<0!2 [0,1] 1>".pick(["bd(3,8)", "sd sd"]))
+ * @example
+ * s("<a!2 [a,b] b>".pick({a: "bd(3,8)", b: "sd sd"}))
  */
 
-export const pick = (pat, xs) => {
-  xs = xs.map(reify);
-  if (xs.length == 0) {
-    return silence;
-  }
-  return pat
-    .fmap((i) => {
-      const key = clamp(Math.round(i), 0, xs.length - 1);
-      return xs[key];
-    })
-    .innerJoin();
-};
+export const pick = register('pick', function (lookup, pat) {
+  return _pick(lookup, pat, false).innerJoin();
+});
+
+/** * The same as `pick`, but if you pick a number greater than the size of the list,
+ * it wraps around, rather than sticking at the maximum value.
+ * For example, if you pick the fifth pattern of a list of three, you'll get the
+ * second one.
+ * @param {Pattern} pat
+ * @param {*} xs
+ * @returns {Pattern}
+ */
+
+export const pickmod = register('pickmod', function (lookup, pat) {
+  return _pick(lookup, pat, true).innerJoin();
+});
 
 /**
- * pick from the list of values (or patterns of values) via the index using the given
+/** * Picks patterns (or plain values) either from a list (by index) or a lookup table (by name).
+ * Similar to `pick`, but cycles are squeezed into the target ('inhabited') pattern.
+ * @param {Pattern} pat
+ * @param {*} xs
+ * @returns {Pattern}
+ * @example
+ * "<a b [a,b]>".inhabit({a: s("bd(3,8)"), 
+                          b: s("cp sd")
+                         })
+ * @example
+ * s("a@2 [a b] a".inhabit({a: "bd(3,8)", b: "sd sd"})).slow(4)
+ */
+export const inhabit = register('inhabit', function (lookup, pat) {
+  return _pick(lookup, pat, true).squeezeJoin();
+});
+
+/** * The same as `inhabit`, but if you pick a number greater than the size of the list,
+ * it wraps around, rather than sticking at the maximum value.
+ * For example, if you pick the fifth pattern of a list of three, you'll get the
+ * second one.
+ * @param {Pattern} pat
+ * @param {*} xs
+ * @returns {Pattern}
+ */
+
+export const inhabitmod = register('inhabit', function (lookup, pat) {
+  return _pick(lookup, pat, false).squeezeJoin();
+});
+
+/**
+ * Pick from the list of values (or patterns of values) via the index using the given
  * pattern of integers. The selected pattern will be compressed to fit the duration of the selecting event
  * @param {Pattern} pat
  * @param {*} xs
@@ -356,7 +413,7 @@ export const degradeBy = register('degradeBy', function (x, pat) {
 export const degrade = register('degrade', (pat) => pat._degradeBy(0.5));
 
 /**
- * Inverse of {@link Pattern#degradeBy}: Randomly removes events from the pattern by a given amount.
+ * Inverse of `degradeBy`: Randomly removes events from the pattern by a given amount.
  * 0 = 100% chance of removal
  * 1 = 0% chance of removal
  * Events that would be removed by degradeBy are let through by undegradeBy and vice versa (see second example).
@@ -380,7 +437,7 @@ export const undegrade = register('undegrade', (pat) => pat._undegradeBy(0.5));
 /**
  *
  * Randomly applies the given function by the given probability.
- * Similar to {@link Pattern#someCyclesBy}
+ * Similar to `someCyclesBy`
  *
  * @name sometimesBy
  * @memberof Pattern
@@ -415,7 +472,7 @@ export const sometimes = register('sometimes', function (func, pat) {
 /**
  *
  * Randomly applies the given function by the given probability on a cycle by cycle basis.
- * Similar to {@link Pattern#sometimesBy}
+ * Similar to `sometimesBy`
  *
  * @name someCyclesBy
  * @memberof Pattern