From 9731eb8c5b060069cfd81d2800ec7dd7630c2e1c Mon Sep 17 00:00:00 2001
From: Felix Roos <flix91@gmail.com>
Date: Thu, 19 Jan 2023 12:25:12 +0100
Subject: [PATCH] add ribbon + test + docs

---
 packages/core/pattern.mjs                  | 10 ++++++++++
 packages/core/test/pattern.test.mjs        |  7 +++++++
 test/__snapshots__/examples.test.mjs.snap  | 21 +++++++++++++++++++++
 website/src/pages/learn/time-modifiers.mdx |  4 ++++
 4 files changed, 42 insertions(+)

diff --git a/packages/core/pattern.mjs b/packages/core/pattern.mjs
index c12cf2b0..2d7a8f43 100644
--- a/packages/core/pattern.mjs
+++ b/packages/core/pattern.mjs
@@ -2028,6 +2028,16 @@ export const bypass = register('bypass', function (on, pat) {
   return on ? silence : pat;
 });
 
+/**
+ * Loops the pattern inside at `offset` for `cycles`.
+ * @param {number} offset start point of loop in cycles
+ * @param {number} cycles loop length in cycles
+ * @example
+ * // Looping a portion of randomness
+ * note(irand(8).segment(4).scale('C3 minor')).ribbon(1337, 2)
+ */
+export const ribbon = register('ribbon', (offset, cycles, pat) => pat.early(offset).restart(pure(1).slow(cycles)));
+
 // sets absolute duration of haps
 // TODO - fix
 export const duration = register('duration', function (value, pat) {
diff --git a/packages/core/test/pattern.test.mjs b/packages/core/test/pattern.test.mjs
index a4c04e80..31b080b6 100644
--- a/packages/core/test/pattern.test.mjs
+++ b/packages/core/test/pattern.test.mjs
@@ -914,6 +914,13 @@ describe('Pattern', () => {
       expect(run(4).firstCycle()).toStrictEqual(sequence(0, 1, 2, 3).firstCycle());
     });
   });
+  describe('ribbon', () => {
+    it('Can ribbon', () => {
+      expect(cat(0, 1, 2, 3, 4, 5, 6, 7).ribbon(2, 4).fast(4).firstCycle()).toStrictEqual(
+        sequence(2, 3, 4, 5).firstCycle(),
+      );
+    });
+  });
   describe('linger', () => {
     it('Can linger on the first quarter of a cycle', () => {
       expect(sequence(0, 1, 2, 3, 4, 5, 6, 7).linger(0.25).firstCycle()).toStrictEqual(
diff --git a/test/__snapshots__/examples.test.mjs.snap b/test/__snapshots__/examples.test.mjs.snap
index f9156bc3..698d8209 100644
--- a/test/__snapshots__/examples.test.mjs.snap
+++ b/test/__snapshots__/examples.test.mjs.snap
@@ -3066,6 +3066,27 @@ exports[`runs examples > example "rev" example index 0 1`] = `
 ]
 `;
 
+exports[`runs examples > example "ribbon" example index 0 1`] = `
+[
+  "[ 0/1 → 1/4 | note:C3 ]",
+  "[ 1/4 → 1/2 | note:G3 ]",
+  "[ 1/2 → 3/4 | note:Eb3 ]",
+  "[ 3/4 → 1/1 | note:Bb3 ]",
+  "[ 1/1 → 5/4 | note:C3 ]",
+  "[ 5/4 → 3/2 | note:D3 ]",
+  "[ 3/2 → 7/4 | note:G3 ]",
+  "[ 7/4 → 2/1 | note:Eb3 ]",
+  "[ 2/1 → 9/4 | note:C3 ]",
+  "[ 9/4 → 5/2 | note:G3 ]",
+  "[ 5/2 → 11/4 | note:Eb3 ]",
+  "[ 11/4 → 3/1 | note:Bb3 ]",
+  "[ 3/1 → 13/4 | note:C3 ]",
+  "[ 13/4 → 7/2 | note:D3 ]",
+  "[ 7/2 → 15/4 | note:G3 ]",
+  "[ 15/4 → 4/1 | note:Eb3 ]",
+]
+`;
+
 exports[`runs examples > example "room" example index 0 1`] = `
 [
   "[ 0/1 → 1/2 | s:bd room:0 ]",
diff --git a/website/src/pages/learn/time-modifiers.mdx b/website/src/pages/learn/time-modifiers.mdx
index 8183a7df..41e87113 100644
--- a/website/src/pages/learn/time-modifiers.mdx
+++ b/website/src/pages/learn/time-modifiers.mdx
@@ -101,3 +101,7 @@ Some of these have equivalent operators in the Mini Notation:
 ## cpm
 
 <JsDoc client:idle name="cpm" h={0} />
+
+## ribbon
+
+<JsDoc client:idle name="ribbon" h={0} />