Merge pull request tidalcycles#1126 from tidalcycles/labeled-statemen…

…ts-doc

Labeled statements doc

test/runtime.mjs

@@ -191,6 +191,7 @@ evalScope(
   },
 );
 
+// TBD: use transpiler to support labeled statements
 export const queryCode = async (code, cycles = 1) => {
   const { pattern } = await evaluate(code);
   const haps = pattern.sortHapsByPart().queryArc(0, cycles);

website/src/docs/MiniRepl.jsx

@@ -81,7 +81,7 @@ export function MiniRepl({
       },
       onToggle: (playing) => {
         if (!playing) {
-          clearHydra();
+          // clearHydra(); // TBD: doesn't work with multiple MiniRepl's on a page
         }
       },
       beforeStart: () => audioReady,

website/src/pages/learn/hydra.mdx

@@ -90,11 +90,13 @@ src(s0).kaleid(H("<4 5 6>"))
   .modulateScale(osc(2,-0.25,1))
   .out()
 //
-stack(
-  s("bd*4,[hh:0:<.5 1>]*8,~ rim").bank("RolandTR909").speed(.9),
-  note("[<g1!3 <bb1 <f1 d1>>>]*3").s("sawtooth")
-  .room(.75).sometimes(add(note(12))).clip(.3)
-  .lpa(.05).lpenv(-4).lpf(2000).lpq(8).ftype('24db')
-).fft(4)
-  .scope({pos:0,smear:.95})`}
+
+$: s("bd*4,[hh:0:<.5 1>]*8,~ rim").bank("RolandTR909").speed(.9)
+
+$: note("[<g1!3 <bb1 <f1 d1>>>]\*3").s("sawtooth")
+
+.room(.75).sometimes(add(note(12))).clip(.3)
+.lpa(.05).lpenv(-4).lpf(2000).lpq(8).ftype('24db')
+
+all(x=>x.fft(4).scope({pos:0,smear:.95}))`}
 />

website/src/pages/learn/input-output.mdx

@@ -20,11 +20,7 @@ Strudel also supports midi via [webmidi](https://npmjs.com/package/webmidi).
 Either connect a midi device or use the IAC Driver (Mac) or Midi Through Port (Linux) for internal midi messages.
 If no outputName is given, it uses the first midi output it finds.
 
-<MiniRepl
-  client:idle
-  tune={`stack("<C^7 A7 Dm7 G7>".voicings('lefthand'), "<C3 A2 D3 G2>").note()
-  .midi()`}
-/>
+<MiniRepl client:idle tune={`chord("<C^7 A7 Dm7 G7>").voicing().midi()`} />
 
 In the console, you will see a log of the available MIDI devices as soon as you run the code, e.g. `Midi connected! Using "Midi Through Port-0".`
 
@@ -45,10 +41,8 @@ But you can also control cc messages separately like this:
 
 <MiniRepl
   client:idle
-  tune={`stack(
-  note("c a f e"),
-  ccv(sine.segment(16).slow(4)).ccn(74)
-).midi()`}
+  tune={`$: note("c a f e").midi()
+$: ccv(sine.segment(16).slow(4)).ccn(74).midi()`}
 />
 
 # SuperDirt API

website/src/pages/learn/samples.mdx

@@ -268,11 +268,10 @@ With it, you can enter any sample name(s) to query from [freesound.org](https://
 <MiniRepl
   client:idle
   tune={`samples('shabda:bass:4,hihat:4,rimshot:2')
-stack(
-  n("0 1 2 3 0 1 2 3").s('bass'),
-  n("0 1*2 2 3*2").s('hihat'),
-  n("~ 0 ~ 1 ~ 0 0 1").s('rimshot')
-).clip(1)`}
+
+$: n("0 1 2 3 0 1 2 3").s('bass')
+$: n("0 1*2 2 3*2").s('hihat').clip(1)
+$: n("~ 0 ~ 1 ~ 0 0 1").s('rimshot')`}
 />
 
 You can also generate artificial voice samples with any text, in multiple languages.
@@ -282,10 +281,9 @@ Note that the language code and the gender parameters are optional and default t
   client:idle
   tune={`samples('shabda/speech:the_drum,forever')
 samples('shabda/speech/fr-FR/m:magnifique')
-stack(
-  s("the_drum*2").chop(16).speed(rand.range(0.85,1.1)),
-  s("forever magnifique").slow(4).late(0.125)
-)`}
+
+$: s("the_drum*2").chop(16).speed(rand.range(0.85,1.1))
+$: s("forever magnifique").slow(4).late(0.125)`}
 />
 
 # Sampler Effects

website/src/pages/learn/strudel-vs-tidal.mdx

@@ -112,29 +112,14 @@ Also, samples are always loaded from a URL rather than from the disk, although [
 ## Evaluation
 
 The Strudel REPL does not support [block based evaluation](https://github.com/tidalcycles/strudel/issues/34) yet.
-You can use the following "workaround" to create multiple patterns that can be turned on and off:
+You can use labeled statements and `_` to mute:
 
-```
-let a = note("c a f e")
-
-let b = s("bd sd")
-
-stack(
-  a,
-  // b
-)
-```
-
-Alternatively, you could write everything as one `stack` and use `.hush()` to silence a pattern:
-
-```
-stack(
-  note("c a f e"),
-  s("bd sd").hush()
-)
-```
+<MiniRepl
+  client:visible
+tune={`$: n("[0 .. 8]*8/9").scale("C:minor:pentatonic")
 
-Note that strudel will always use the last statement in your code as the pattern for querying
+\_$: s("bd\*4").bank('RolandTR909')`}
+/>
 
 ## Tempo
 

website/src/pages/learn/tonal.mdx

@@ -55,20 +55,6 @@ Transposes notes inside the scale by the number of steps:
 .note()`}
 />
 
-### voicings(range?)
-
-Turns chord symbols into voicings, using the smoothest voice leading possible:
-
-<MiniRepl
-  client:only="react"
-  tune={`stack(
-  "<C^7 A7 Dm7 G7>".voicings('lefthand'), 
-  "<C3 A2 D3 G2>"
-).note()`}
-/>
-
-Note: This function might be removed, as `voicing` (without s) is a newer implementation.
-
 ### rootNotes(octave = 2)
 
 Turns chord symbols into root notes of chords in given octave.

website/src/pages/workshop/first-effects.mdx

@@ -60,11 +60,10 @@ We will learn how to automate with waves later...
 
 <MiniRepl
   client:visible
-  tune={`stack(
-  sound("hh*16").gain("[.25 1]*4"),
-  sound("bd*4,[~ sd:1]*2")
-) `}
-  punchcard
+  tune={`$: sound("hh*16").gain("[.25 1]*4")
+
+$: sound("bd*4,[~ sd:1]*2")`}
+punchcard
 />
 
 <Box>
@@ -76,30 +75,20 @@ Rhythm is all about dynamics!
 
 </Box>
 
-**stacks within stacks**
-
 Let's combine all of the above into a little tune:
 
 <MiniRepl
   client:visible
-  tune={`stack(
-stack(
-sound("hh*8").gain("[.25 1]*4"),
-sound("bd*4,[~ sd:1]*2")
-),
-note("<[c2 c3]*4 [bb1 bb2]*4 [f2 f3]*4 [eb2 eb3]*4>")
-.sound("sawtooth").lpf("200 1000 200 1000"),
-note("<[c3,g3,e4] [bb2,f3,d4] [a2,f3,c4] [bb2,g3,eb4]>")
-.sound("sawtooth").vowel("<a e i o>")
-)`}
-/>
+  tune={`$: sound("hh*8").gain("[.25 1]*4")
 
-<Box>
+$: sound("bd*4,[~ sd:1]*2")
 
-Try to identify the individual parts of the stacks, pay attention to where the commas are.
-The 3 parts (drums, bassline, chords) are exactly as earlier, just stacked together, separated by comma.
+$: note("<[c2 c3]*4 [bb1 bb2]*4 [f2 f3]*4 [eb2 eb3]*4>")
+.sound("sawtooth").lpf("200 1000 200 1000")
 
-</Box>
+$: note("<[c3,g3,e4] [bb2,f3,d4] [a2,f3,c4] [bb2,g3,eb4]>")
+.sound("sawtooth").vowel("<a e i o>")`}
+/>
 
 **shape the sound with an adsr envelope**
 
@@ -151,11 +140,10 @@ Can you guess what they do?
 
 <MiniRepl
   client:visible
-  tune={`stack(
-note("[~ [<[d3,a3,f4]!2 [d3,bb3,g4]!2> ~]]*2")
-.sound("gm_electric_guitar_muted"),
-sound("bd rim").bank("RolandTR707")
-).delay(".5")`}
+  tune={`$: note("[~ [<[d3,a3,f4]!2 [d3,bb3,g4]!2> ~]]*2")
+  .sound("gm_electric_guitar_muted").delay(.5)
+
+$: sound("bd rim").bank("RolandTR707").delay(".5")`}
 />
 
 <Box>
@@ -199,31 +187,32 @@ Add a delay too!
 
 <MiniRepl
   client:visible
-  tune={`stack(
-note("[~ [<[d3,a3,f4]!2 [d3,bb3,g4]!2> ~]]*2")
-.sound("gm_electric_guitar_muted").delay(.5),
-sound("bd rim").bank("RolandTR707").delay(.5),
-n("<4 [3@3 4] [<2 0> ~@16] ~>")
+  tune={`$: note("[~ [<[d3,a3,f4]!2 [d3,bb3,g4]!2> ~]]*2")
+.sound("gm_electric_guitar_muted").delay(.5)
+
+$: sound("bd rim").bank("RolandTR707").delay(.5)
+
+$: n("<4 [3@3 4] [<2 0> ~@16] ~>")
 .scale("D4:minor").sound("gm_accordion:2")
-.room(2).gain(.5)
-)`}
+.room(2).gain(.5)`}
 />
 
 Let's add a bass to make this complete:
 
 <MiniRepl
   client:visible
-  tune={`stack(
-note("[~ [<[d3,a3,f4]!2 [d3,bb3,g4]!2> ~]]*2")
-.sound("gm_electric_guitar_muted").delay(.5),
-sound("bd rim").bank("RolandTR707").delay(.5),
-n("<4 [3@3 4] [<2 0> ~@16] ~>")
+  tune={`$: note("[~ [<[d3,a3,f4]!2 [d3,bb3,g4]!2> ~]]*2")
+.sound("gm_electric_guitar_muted").delay(.5)
+
+$: sound("bd rim").bank("RolandTR707").delay(.5)
+
+$: n("<4 [3@3 4] [<2 0> ~@16] ~>")
 .scale("D4:minor").sound("gm_accordion:2")
-.room(2).gain(.4),
-n("[0 [~ 0] 4 [3 2] [0 ~] [0 ~] <0 2> ~]/2")
+.room(2).gain(.4)
+
+$: n("[0 [~ 0] 4 [3 2] [0 ~] [0 ~] <0 2> ~]/2")
 .scale("D2:minor")
-.sound("sawtooth,triangle").lpf(800)
-)`}
+.sound("sawtooth,triangle").lpf(800)`}
 />
 
 <Box>

website/src/pages/workshop/first-notes.mdx

@@ -314,11 +314,11 @@ Let's recap what we've learned in this chapter:
 
 New functions:
 
-| Name  | Description                         | Example                                                                           |
-| ----- | ----------------------------------- | --------------------------------------------------------------------------------- |
-| note  | set pitch as number or letter       | <MiniRepl client:visible tune={`note("b g e c").sound("piano")`} />               |
-| scale | interpret `n` as scale degree       | <MiniRepl client:visible tune={`n("6 4 2 0").scale("C:minor").sound("piano")`} /> |
-| stack | play patterns in parallel (read on) | <MiniRepl client:visible tune={`stack(s("bd sd"),note("c eb g"))`} />             |
+| Name  | Description                   | Example                                                                           |
+| ----- | ----------------------------- | --------------------------------------------------------------------------------- |
+| note  | set pitch as number or letter | <MiniRepl client:visible tune={`note("b g e c").sound("piano")`} />               |
+| scale | interpret `n` as scale degree | <MiniRepl client:visible tune={`n("6 4 2 0").scale("C:minor").sound("piano")`} /> |
+| $:    | play patterns in parallel     | <MiniRepl client:visible tune={'$: s("bd sd")\n$: note("c eb g")'} />             |
 
 ## Examples
 
@@ -356,25 +356,35 @@ New functions:
 
 <Box>
 
-It's called `stack` 😙
+You can use `$:` 😙
 
 </Box>
 
+## Playing multiple patterns
+
+If you want to play multiple patterns at the same time, make sure to write `$:` before each:
+
 <MiniRepl
   client:visible
-  tune={`stack(
-  note("<[c2 c3]*4 [bb1 bb2]*4 [f2 f3]*4 [eb2 eb3]*4>")
-  .sound("gm_synth_bass_1").lpf(800),
-  n(\`<
+  tune={`$: note("<[c2 c3]*4 [bb1 bb2]*4 [f2 f3]*4 [eb2 eb3]*4>")
+  .sound("gm_synth_bass_1").lpf(800)
+  
+$: n(\`<
   [~ 0] 2 [0 2] [~ 2]
   [~ 0] 1 [0 1] [~ 1]
   [~ 0] 3 [0 3] [~ 3]
   [~ 0] 2 [0 2] [~ 2]
   >*4\`).scale("C4:minor")
-  .sound("gm_synth_strings_1"),
-  sound("bd*4, [~ <sd cp>]*2, [~ hh]*4")
-  .bank("RolandTR909")
-)`}
+  .sound("gm_synth_strings_1")
+  
+$: sound("bd*4, [~ <sd cp>]*2, [~ hh]*4")
+.bank("RolandTR909")`}
 />
 
+<Box>
+
+Try changing `$` to `_$` to mute a part!
+
+</Box>
+
 This is starting to sound like actual music! We have sounds, we have notes, now the last piece of the puzzle is missing: [effects](/workshop/first-effects)