Update docs

Author: pearmini

app/docs/animations-authoring.recho.js

@@ -8,8 +8,8 @@
  * =                         Animations Authoring                             =
  * ============================================================================
  *
- * Animations are very powerful tools making your notebooks more interactive 
- * and engaging. In Recho, there are at least two ways to author animations. 
+ * Animations are very powerful tools making your notebooks more interactive
+ * and engaging. In Recho, there are at least two ways to author animations.
  * You can choose either one which suits you best.
  *
  * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -69,11 +69,11 @@ const rocket = recho.interval(2);
 //➜                                    🚀💨
 {
   const x = (count) => 40 - (count % 40);
-  echo("🐌💨".padStart(x(snail)), {quote: false});
-  echo("🐢💨".padStart(x(turtle)), {quote: false});
-  echo("🚶‍♂️💨".padStart(x(human)), {quote: false});
-  echo("🚗💨".padStart(x(car)), {quote: false});
-  echo("🚀💨".padStart(x(rocket)), {quote: false});
+  echo("🐌💨".padStart(x(snail)));
+  echo("🐢💨".padStart(x(turtle)));
+  echo("🚶‍♂️💨".padStart(x(human)));
+  echo("🚗💨".padStart(x(car)));
+  echo("🚀💨".padStart(x(rocket)));
 }
 
 /**
@@ -94,7 +94,7 @@ echo(now);
 const x = echo(Math.abs(~~(Math.sin(now / 1000) * 22)));
 
 //➜ ~(๑•̀ㅂ•́)و✧
-echo("~".repeat(x) + "(๑•̀ㅂ•́)و✧", {quote: false});
+echo(recho.inspect("~".repeat(x) + "(๑•̀ㅂ•́)و✧", {quote: false}));
 
 /**
  * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

app/docs/api-reference.recho.js

@@ -13,36 +13,51 @@
 
 /**
  * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- *                         echo(value[, options])
+ *                         echo(...values)
  * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  *
- * Echos a value inline with your code as comments.
+ * Echos one or more values inline with your code as comments. If only one
+ * value is provided, return the value itself. If multiple values are provided,
+ * return all the values as an array.
  *
- * @param {any} value - The value to echo.
- * @param {Object} [options] - The options to format the output.
- * @param {string} [options.quote="double"] - The quote style of the output.
- * @param {number} [options.indent=null] - The indentation of the output.
- * @param {number} [options.limit=200] - The limit of the output.
- * @returns {any} The value.
+ * @param {...any} values - The values to echo.
+ * @returns {any} The values if multiple values are provided, or the single value.
  */
 
 //➜ "Hello, World!"
 echo("Hello, World!");
 
-//➜ 'Hello, World!'
-echo("Hello, World!", {quote: "single"});
+//➜ 1 2 3
+echo(1, 2, 3);
+
+//➜ Peter:  Age = 20
+//➜         Height = 180
+echo("Peter: ", "Age = 20\nHeight = 180");
+
+const a = echo(1 + 2);
 
-//➜ Hello, World!
-echo("Hello, World!", {quote: false});
+//➜ 3
+echo(a);
 
-//➜ {
-//➜   a: 1,
-//➜   b: 2
-//➜ }
-echo({a: 1, b: 2}, {indent: 2});
+const numbers = echo(1, 2, 3);
 
-//➜ [ 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, …
-echo(new Array(100).fill(0), {limit: 80});
+//➜ [ 1, 2, 3 ]
+echo(numbers);
+
+/**
+ * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ *                      recho.inspect(value[, options])
+ * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ *
+ * Formats a value for inspection with customizable options.
+ *
+ * @param {any} value - The value to inspect.
+ * @param {Object} [options] - The options to format the output.
+ * @param {string} [options.quote="double"] - The quote style of the output ("single", "double", or false).
+ * @param {number} [options.indent=null] - The indentation of the output (null, "\t", or a positive integer).
+ * @param {number} [options.limit=200] - The character limit of the output.
+ * @returns {string} The formatted string representation of the value.
+ */
 
 /**
  * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -138,7 +153,7 @@ const Noise = recho.require("perlin-noise-3d");
   for (let i = 0; i < 100; i++) {
     values.push(noise.get(i / 100, i / 100, i / 100));
   }
-  echo(values, {limit: 80});
+  echo(recho.inspect(values, {limit: 80}));
 }
 
 const d3 = recho.require("d3-array", "d3-random");
@@ -166,8 +181,8 @@ const isVisible = recho.toggle(false);
 //➜ "The button is enabled."
 //➜ "The button is hidden."
 {
-  echo(`The button is ${isEnabled ? 'enabled' : 'disabled'}.`);
-  echo(`The button is ${isVisible ? 'visible' : 'hidden'}.`);
+  echo(`The button is ${isEnabled ? "enabled" : "disabled"}.`);
+  echo(`The button is ${isVisible ? "visible" : "hidden"}.`);
 }
 
 /**
@@ -246,6 +261,6 @@ const temperature = recho.number(24, {min: -10, max: 40, step: 0.5});
 
 //➜ "The room temperature is 24 °C (75.2 °F)."
 {
-  const fahrenheit = (temperature * 9 / 5) + 32;
+  const fahrenheit = (temperature * 9) / 5 + 32;
   echo(`The room temperature is ${temperature} °C (${fahrenheit} °F).`);
 }

app/docs/inline-echoing.recho.js

@@ -26,7 +26,7 @@ const message = echo("Hello, World!");
 
 /**
  * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- *                              Instant Feedback
+ *                            Instant Feedback
  * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  *
  * `echo` allows you to quickly get feedback about the states of your code. You
@@ -147,23 +147,61 @@ const customDate = echo(new Date().toLocaleString());
 
 /**
  * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- *                             Formatting Outputs
+ *                           Echoing Multiple Values
+ * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ *
+ * You can pass multiple values to `echo` in a single call. The values will be
+ * merged horizontally.
+ */
+
+//➜ 1 2 3
+echo(1, 2, 3);
+
+//➜ Hello World
+echo("Hello", "World");
+
+//➜ Peter:  Age = 20
+//➜         Height = 180
+echo("Peter: ", "Age = 20\nHeight = 180");
+
+/**
+ * You can also call `echo` multiple times to echo multiple values in ForStatement,
+ * BlockStatement, and more. The values will be joined by a newline.
+ */
+
+//➜ 0
+//➜ 1
+//➜ 2
+for (let i = 0; i < 3; i++) echo(i);
+
+//➜ 1
+//➜ 2
+//➜ 3
+{
+  echo(1);
+  echo(2);
+  echo(3);
+}
+
+/**
  * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- * `echo` provides `options` to format the output. For example, you can format
- * the quote style of a string value using the `quote` option:
+ *                           Inspecting Options
+ * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ * You can use `recho.inspect()` with options to format the output. For example,
+ * you can format the quote style of a string value using the `quote` option:
  */
 
 //➜ "Hello, World!"
 const defaultQuotedString = echo("Hello, World!");
 
 //➜ 'Hello, World!'
-const singleQuotedString = echo("Hello, World!", {quote: "single"});
+const singleQuotedString = echo(recho.inspect("Hello, World!", {quote: "single"}));
 
 //➜ "Hello, World!"
-const doubleQuotedString = echo("Hello, World!", {quote: "double"});
+const doubleQuotedString = echo(recho.inspect("Hello, World!", {quote: "double"}));
 
 //➜ Hello, World!
-const unquotedString = echo("Hello, World!", {quote: false});
+const unquotedString = echo(recho.inspect("Hello, World!", {quote: false}));
 
 /**
  * You can also format the indentation of the output using the `indent` option.
@@ -176,38 +214,15 @@ const unquotedString = echo("Hello, World!", {quote: false});
 //➜   b: 2,
 //➜   c: 3
 //➜ }
-const indentedObject = echo({a: 1, b: 2, c: 3}, {indent: 2});
+const indentedObject = echo(recho.inspect({a: 1, b: 2, c: 3}, {indent: 2}));
 
 /**
  * You can also limit the length of the output using the `limit` option. It
  * must be a positive integer, Infinity, defaults to 200.
  */
 
 //➜ [ 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, …
-const array1000 = echo(new Array(1000).fill(0), {limit: 80});
-
-/**
- * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- *                           Echoing Multiple Values
- * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- *
- * You can call `echo` multiple times to echo multiple values in ForStatement,
- * BlockStatement, and more. The values will be joined by a newline.
- */
-
-//➜ 0
-//➜ 1
-//➜ 2
-for (let i = 0; i < 3; i++) echo(i);
-
-//➜ 1
-//➜ 2
-//➜ 3
-{
-  echo(1);
-  echo(2);
-  echo(3);
-}
+const array1000 = echo(recho.inspect(new Array(1000).fill(0), {limit: 80}));
 
 /**
  * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

app/examples/pokemon.recho.js

@@ -55,10 +55,10 @@ const search = null;
 //➜
 //➜
 {
-  echo(`⚡ Type: ${pokemon.types[0].type.name.toUpperCase()}`, {quote: false});
-  echo(`⚖️ Weight: ${pokemon.weight}`, {quote: false});
-  echo(`📏 Height: ${pokemon.height}`, {quote: false});
-  echo("", {quote: false});
+  echo(recho.inspect(`⚡ Type: ${pokemon.types[0].type.name.toUpperCase()}`, {quote: false}));
+  echo(recho.inspect(`⚖️ Weight: ${pokemon.weight}`, {quote: false}));
+  echo(recho.inspect(`📏 Height: ${pokemon.height}`, {quote: false}));
+  echo(recho.inspect("", {quote: false}));
   img2ASCIIString(pokemon.sprites.front_default).then(echo);
 }
 

app/examples/running-race.recho.js

@@ -30,9 +30,9 @@ const rocket = recho.interval(2);
 //➜           🚀💨
 {
   const x = (count) => 40 - (count % 40);
-  echo("🐌💨".padStart(x(snail)), {quote: false});
-  echo("🐢💨".padStart(x(turtle)), {quote: false});
-  echo("🚶‍♂️💨".padStart(x(human)), {quote: false});
-  echo("🚗💨".padStart(x(car)), {quote: false});
-  echo("🚀💨".padStart(x(rocket)), {quote: false});
+  echo("🐌💨".padStart(x(snail)));
+  echo("🐢💨".padStart(x(turtle)));
+  echo("🚶‍♂️💨".padStart(x(human)));
+  echo("🚗💨".padStart(x(car)));
+  echo("🚀💨".padStart(x(rocket)));
 }