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/test/pattern.test.mjs

@@ -1057,4 +1057,55 @@ describe('Pattern', () => {
       expect(slowcat(0, 1).repeatCycles(2).fast(6).firstCycleValues).toStrictEqual([0, 0, 1, 1, 0, 0]);
     });
   });
+  describe('inhabit', () => {
+    it('Can pattern named patterns', () => {
+      expect(
+        sameFirst(
+          sequence('a', 'b', stack('a', 'b')).inhabit({ a: sequence(1, 2), b: sequence(10, 20, 30) }),
+          sequence([1, 2], [10, 20, 30], stack([1, 2], [10, 20, 30])),
+        ),
+      );
+    });
+    it('Can pattern indexed patterns', () => {
+      expect(
+        sameFirst(
+          sequence('0', '1', stack('0', '1')).inhabit([sequence(1, 2), sequence(10, 20, 30)]),
+          sequence([1, 2], [10, 20, 30], stack([1, 2], [10, 20, 30])),
+        ),
+      );
+    });
+  });
+  describe('pick', () => {
+    it('Can pattern named patterns', () => {
+      expect(
+        sameFirst(
+          sequence('a', 'b', 'a', stack('a', 'b')).pick({ a: sequence(1, 2, 3, 4), b: sequence(10, 20, 30, 40) }),
+          sequence(1, 20, 3, stack(4, 40)),
+        ),
+      );
+    });
+    it('Can pattern indexed patterns', () => {
+      expect(
+        sameFirst(
+          sequence(0, 1, 0, stack(0, 1)).pick([sequence(1, 2, 3, 4), sequence(10, 20, 30, 40)]),
+          sequence(1, 20, 3, stack(4, 40)),
+        ),
+      );
+    });
+    it('Clamps indexes', () => {
+      expect(
+        sameFirst(sequence(0, 1, 2, 3).pick([sequence(1, 2, 3, 4), sequence(10, 20, 30, 40)]), sequence(1, 20, 30, 40)),
+      );
+    });
+  });
+  describe('pickmod', () => {
+    it('Wraps indexes', () => {
+      expect(
+        sameFirst(
+          sequence(0, 1, 2, 3).pickmod([sequence(1, 2, 3, 4), sequence(10, 20, 30, 40)]),
+          sequence(1, 20, 3, 40),
+        ),
+      );
+    });
+  });
 });