From 331ddab544ecf685fe234f43238a2fc278d73af2 Mon Sep 17 00:00:00 2001
From: Miika Alonen <amiika@gmail.com>
Date: Mon, 18 Dec 2023 22:28:48 +0200
Subject: [PATCH] Added once() method

---
 src/API.ts                                        | 14 ++++++++++++++
 src/KeyActions.ts                                 |  2 ++
 src/documentation/learning/audio_engine/synths.ts | 12 +++++++-----
 src/documentation/patterns/probabilities.ts       |  1 +
 4 files changed, 24 insertions(+), 5 deletions(-)

diff --git a/src/API.ts b/src/API.ts
index f9542f2..9677c0b 100644
--- a/src/API.ts
+++ b/src/API.ts
@@ -128,6 +128,8 @@ export class UserAPI {
   public MidiConnection: MidiConnection;
   public scale_aid: string | number | undefined = undefined;
   public hydra: any;
+  public onceEvaluator: boolean = true;
+
   load: samples;
 
   constructor(public app: Editor) {
@@ -912,6 +914,18 @@ export class UserAPI {
   // Counter and iteration
   // =============================================================
 
+  public once = (): boolean => {
+    /**
+     * Returns true if the code is being evaluated for the first time.
+     *
+     * @returns True if the code is being evaluated for the first time
+     */
+    const firstTime = this.app.api.onceEvaluator; 
+    this.app.api.onceEvaluator = false;
+
+    return firstTime;
+  }
+
   public counter = (
     name: string | number,
     limit?: number,
diff --git a/src/KeyActions.ts b/src/KeyActions.ts
index 5b68a56..ad0603c 100644
--- a/src/KeyActions.ts
+++ b/src/KeyActions.ts
@@ -105,6 +105,7 @@ export const registerOnKeyDown = (app: Editor) => {
     if (event.key === "Enter" && event.shiftKey && event.ctrlKey) {
       event.preventDefault();
       app.currentFile().candidate = app.view.state.doc.toString();
+      app.api.onceEvaluator = true;
       tryEvaluate(app, app.currentFile());
       app.flashBackground("#404040", 200);
     }
@@ -114,6 +115,7 @@ export const registerOnKeyDown = (app: Editor) => {
       event.preventDefault();
       app.api.clearPatternCache();
       app.currentFile().candidate = app.view.state.doc.toString();
+      app.api.onceEvaluator = true;
       tryEvaluate(app, app.currentFile());
       app.flashBackground("#404040", 200);
     }
diff --git a/src/documentation/learning/audio_engine/synths.ts b/src/documentation/learning/audio_engine/synths.ts
index d821123..806d864 100644
--- a/src/documentation/learning/audio_engine/synths.ts
+++ b/src/documentation/learning/audio_engine/synths.ts
@@ -415,6 +415,8 @@ beat(2) :: sound('zzfx').zzfx([3.62,,452,.16,.1,.21,,2.5,,,403,.05,.29,,,,.17,.3
 
 Topos can also speak using the [Web Speech API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Speech_API). There are two ways to use speech synthesis:
 
+Speech synthesis API can crash your browser if you use it too much. To avoid crashing the calls should be limited using methods like beat() or run it only once using once().
+
 - <ic>speak(text: string, lang: string, voice: number, rate: number, pitch: number, volume: number)</ic>
   - <ic>text</ic>: the text you would like to synthesize (_e.g_ <ic>"Wow, Topos can speak!"</ic>).
   - <ic>lang</ic>: language code, for example <ic>en</ic> for English, <ic>fr</ic> for French or with the country code for example British English <ic>en-GB</ic>. See supported values from the [list](https://cloud.google.com/speech-to-text/docs/speech-to-text-supported-languages).
@@ -426,7 +428,7 @@ Topos can also speak using the [Web Speech API](https://developer.mozilla.org/en
 ${makeExample(
   "Hello world!",
   `
-beat(4) :: speak("Hello world!")
+once() && speak("Hello world!")
   `,
   true,
 )}
@@ -434,7 +436,7 @@ beat(4) :: speak("Hello world!")
 ${makeExample(
   "Let's hear people talking about Topos",
   `
-beat(2) :: speak("Topos!","fr",irand(0,5))
+beat(2) && speak("Topos!","fr",irand(0,5))
   `,
   true,
 )}
@@ -445,7 +447,7 @@ You can also use speech by chaining methods to a string:
 ${makeExample(
   "Foobaba is the real deal",
   `
-  onbeat(4) :: "Foobaba".voice(irand(0,10)).speak()
+  onbeat(4) && "Foobaba".voice(irand(0,10)).speak()
   `,
   true,
 )}
@@ -458,7 +460,7 @@ ${makeExample(
   const object = ["happy","sad","tired"].pick()
   const sentence = subject+" "+verb+" "+" "+object
     
-  beat(6) :: sentence.pitch(0).rate(0).voice([0,2].pick()).speak()
+  beat(6) && sentence.pitch(0).rate(0).voice([0,2].pick()).speak()
   `,
   true,
 )}
@@ -474,7 +476,7 @@ ${makeExample(
     "Flamboyant", "Cosmique", "Croissant!"
   ];
   
-  onbeat(4) :: croissant.bar()
+  onbeat(4) && croissant.bar()
       .lang("fr")
       .volume(rand(0.2,2.0))
       .rate(rand(.4,.6))
diff --git a/src/documentation/patterns/probabilities.ts b/src/documentation/patterns/probabilities.ts
index 0437f44..8cb5030 100644
--- a/src/documentation/patterns/probabilities.ts
+++ b/src/documentation/patterns/probabilities.ts
@@ -54,6 +54,7 @@ By default chance operators will be evaluated 48 times within a beat. You can ch
 - <ic>frequently(beats?: number)</ic>: returns true 90% of the time in given number of beats
 - <ic>almostAlways(beats?: number)</ic>: returns true 99% of the time in given number of beats
 - <ic>always(beats?: number)</ic>: returns true. Can be handy when switching between different probabilities
+- <ic>once()</ic>: returns true once, then false until the code is force evaluated (Shift+Ctrl+Enter)
 	
 Examples: