Added chance operators to inline help

src/API.ts

@@ -823,85 +823,105 @@ export class UserAPI {
     return this.randomGen() > 0.5;
   };
 
-  public odds = (n: number, sec: number = 15): boolean => {
+  public odds = (n: number, beats: number = 1): boolean => {
     /**
      * Returns true n% of the time.
      *
      * @param n - The probability of returning true. 1/4 = 25% = 0.25, 80/127 = 62.9% = 0.6299212598425197, etc...
-     * @param sec - The time frame in seconds
+     * @param beats - The time frame in beats
      * @returns True n% of the time
      */
-    return this.randomGen() < (n * this.ppqn()) / (this.ppqn() * sec);
+    return this.randomGen() < (n * this.ppqn()) / (this.ppqn() * beats);
   };
 
-  public almostNever = (sec: number = 15): boolean => {
+  // @ts-ignore
+  public never = (beats: number = 1): boolean => {
+    /**
+     * Returns false
+     * @param beats - Doesn't give a * about beats
+     * @returns False
+     */
+    return false;
+  };
+
+  public almostNever = (beats: number = 1): boolean => {
     /**
      * Returns true 2.5% of the time in given time frame.
      *
-     * @param sec - The time frame in seconds
+     * @param beats - The time frame in beats
      * @returns True 2.5% of the time
      */
-    return this.randomGen() < (0.025 * this.ppqn()) / (this.ppqn() * sec);
+    return this.randomGen() < (0.025 * this.ppqn()) / (this.ppqn() * beats);
   };
 
-  public rarely = (sec: number = 15): boolean => {
+  public rarely = (beats: number = 1): boolean => {
     /**
      * Returns true 10% of the time.
      *
-     * @param sec - The time frame in seconds
+     * @param beats - The time frame in beats
      * @returns True 10% of the time.
      */
-    return this.randomGen() < (0.1 * this.ppqn()) / (this.ppqn() * sec);
+    return this.randomGen() < (0.1 * this.ppqn()) / (this.ppqn() * beats);
   };
 
-  public scarcely = (sec: number = 15): boolean => {
+  public scarcely = (beats: number = 1): boolean => {
     /**
      * Returns true 25% of the time.
      *
-     * @param sec - The time frame in seconds
+     * @param beats - The time frame in beats
      * @returns True 25% of the time
      */
-    return this.randomGen() < (0.25 * this.ppqn()) / (this.ppqn() * sec);
+    return this.randomGen() < (0.25 * this.ppqn()) / (this.ppqn() * beats);
   };
 
-  public sometimes = (sec: number = 15): boolean => {
+  public sometimes = (beats: number = 1): boolean => {
     /**
      * Returns true 50% of the time.
      *
-     * @param sec - The time frame in seconds
+     * @param beats - The time frame in beats
      * @returns True 50% of the time
      */
-    return this.randomGen() < (0.5 * this.ppqn()) / (this.ppqn() * sec);
+    return this.randomGen() < (0.5 * this.ppqn()) / (this.ppqn() * beats);
   };
 
-  public often = (sec: number = 15): boolean => {
+  public often = (beats: number = 1): boolean => {
     /**
      * Returns true 75% of the time.
      *
-     * @param sec - The time frame in seconds
+     * @param beats - The time frame in beats
      * @returns True 75% of the time
      */
-    return this.randomGen() < (0.75 * this.ppqn()) / (this.ppqn() * sec);
+    return this.randomGen() < (0.75 * this.ppqn()) / (this.ppqn() * beats);
   };
 
-  public frequently = (sec: number = 15): boolean => {
+  public frequently = (beats: number = 1): boolean => {
     /**
      * Returns true 90% of the time.
      *
-     * @param sec - The time frame in seconds
+     * @param beats - The time frame in beats
      * @returns True 90% of the time
      */
-    return this.randomGen() < (0.9 * this.ppqn()) / (this.ppqn() * sec);
+    return this.randomGen() < (0.9 * this.ppqn()) / (this.ppqn() * beats);
   };
 
-  public almostAlways = (sec: number = 15): boolean => {
+  public almostAlways = (beats: number = 1): boolean => {
     /**
      * Returns true 98.5% of the time.
      *
-     * @param sec - The time frame in seconds
+     * @param beats - The time frame in beats
      * @returns True 98.5% of the time
      */
-    return this.randomGen() < (0.985 * this.ppqn()) / (this.ppqn() * sec);
+    return this.randomGen() < (0.985 * this.ppqn()) / (this.ppqn() * beats);
+  };
+
+  // @ts-ignore
+  public always = (beats: number = 1): boolean => {
+    /**
+     * Returns true 100% of the time.
+     * @param beats - Doesn't give a * about beats
+     * @returns true
+     */
+    return true;
   };
 
   public dice = (sides: number): number => {

src/classes/AbstractEvents.ts

@@ -27,6 +27,11 @@ export abstract class Event {
     return this;
   };
 
+  // @ts-ignore
+  never = (func: Function): Event => {
+    return this;
+  };
+
   almostNever = (func: Function): Event => {
     return this.odds(0.025, func);
   };
@@ -55,6 +60,10 @@ export abstract class Event {
     return this.odds(0.985, func);
   };
 
+  always = (func: Function): Event => {
+    return this.modify(func);
+  };
+
   modify = (func: Function): Event => {
     return func(this);
   };

src/documentation/functions.ts

@@ -226,14 +226,57 @@ prob(80) :: script(toss() ? script(3) : script(4))
 
 Chance operators returning a boolean value are also available. They are super important because they also exist for another mechanism called **chaining**. Checkout the **Chaining** page to learn how to use them in different contexts!
 
-- <ic>odds(n: number, sec?: number)</ic>: returns true for every n (odds) (eg. 1/4 = 0.25) in given seconds (sec)
+By default chance operators will be evaluated 48 times within a beat. You can change this value by providing a number of beats as an argument. Default value is 1. Change operators can also be used to randomly apply other operators.
-- <ic>almostNever(sec?: number)</ic>: returns true 0.1% in given seconds (sec)
+
-- <ic>rarely(sec?: number)</ic>: returns true 1% in given seconds (sec)
+- <ic>odds(n: number, beats?: number)</ic>: returns true for every n (odds) (eg. 1/4 = 0.25) in given number of beats
-- <ic>scaresly(sec?: number)</ic>: returns true 10% in given seconds (sec)
+- <ic>never(beats?: number)</ic>: returns false. Can be handy when switching between different probabilities
-- <ic>sometimes(sec?: number)</ic>: returns true 50% in given seconds (sec)
+- <ic>almostNever(beats?: number)</ic>: returns true 0.1% of the time in given number of beats
-- <ic>often(sec?: number)</ic>: returns true 75% in given seconds (sec)
+- <ic>rarely(beats?: number)</ic>: returns true 1% of the time in given number of beats
-- <ic>frequently(sec?: number)</ic>: returns true 90% in given seconds (sec)
+- <ic>scarcely(beats?: number)</ic>: returns true 10% of the time in given number of beats
-- <ic>almostAlways(sec?: number)</ic>: returns true 99% in given seconds (sec)
+- <ic>sometimes(beats?: number)</ic>: returns true 50% of the time in given number of beats
+- <ic>often(beats?: number)</ic>: returns true 75% of the time in given number of beats
+- <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
+	
+Examples:
+
+${makeExample(
+  "Using chance operators",
+  `
+  rarely() :: sound('hh').out(); // Rarely 48 times is still a lot
+  rarely(4) :: sound('bd').out(); // Rarely in 4 beats is bit less
+  rarely(8) :: sound('east').out(); // Rarely in 8 beats is even less
+  `,
+  true
+)}
+
+${makeExample(
+  "Using chance with other operators",
+  `
+  frequently() :: mod(1) :: sound('kick').out();
+  often() :: mod(0.5) :: sound('hh').out();
+  sometimes() :: onbeat(1,3) :: sound('snare').out();
+  `,
+  true
+)}
+
+${makeExample(
+  "Using chance with chaining",
+  `
+  mod(0.5) && sound("bd")
+  .freq(100)
+  .sometimes(s=>s.crush(2.5))
+  .out()
+
+  mod(0.5) && sound('arp').freq(100)
+  .sometimes(n=>n.freq(200).delay(0.5))
+  .rarely(n=>n.freq(300).delay(2.5))
+  .almostNever(n=>n.freq(400))
+  .out()
+  `,
+  true
+)}
 
 ## Math functions
 	

src/documentation/inlineHelp.ts

@@ -377,6 +377,66 @@ const completionDatabase: CompletionDatabase = {
     description: "Pick a value in the given array",
     example: "[1,4,10].pick()",
   },
+  odds: {
+    name: "odds",
+    category: "randomness",
+    description: "Return true with a probability of <i>n</i> %",
+    example: "odds(1/2) // 50% probability"
+  },
+  never: {
+    name: "never",
+    category: "randomness",
+    description: "Return false",
+    example: "never() // false"
+  },
+  almostNever: {
+    name: "almostNever",
+    category: "randomness",
+    description: "Return true with a probability of 2.5%",
+    example: "almostNever() // 2.5% chance"
+  },
+  rarely: {
+    name: "rarely",
+    category: "randomness",
+    description: "Return true with a probability of 10%",
+    example: "rarely() // 10% chance"
+  },
+  scarcely: {
+    name: "scarcely",
+    category: "randomness",
+    description: "Return true with a probability of 25%",
+    example: "scarcely() // 25% chance"
+  },
+  sometimes: {
+    name: "sometimes",
+    category: "randomness",
+    description: "Return true with a probability of 50%",
+    example: "sometimes() // 50% chance"
+  },
+  often: {
+    name: "often",
+    category: "randomness",
+    description: "Return true with a probability of 75%",
+    example: "often() // 75% chance"
+  },
+  frequently: {
+    name: "frequently",
+    category: "randomness",
+    description: "Return true with a probability of 90%",
+    example: "frequently() // chance"
+  },
+  almostAlways: {
+    name: "almostAlways",
+    category: "randomness",
+    description: "Return true with a probability of 98.5%",
+    example: "almostAlways() // 98.5% chance"
+  },
+  always: {
+    name: "always",
+    category: "randomness",
+    description: "Return true",
+    example: "always() // true"
+  },
   sound: {
     name: "sound",
     category: "audio",
@@ -642,7 +702,7 @@ const completionDatabase: CompletionDatabase = {
     category: "patterns",
     description: "Divide each element of the given array by a value",
     example: "[0,1,2,3].division(2)",
-  },
+  }
 };
 
 export const inlineHoveringTips = hoverTooltip(