Merge branch 'dev'

.vscode/launch.json

@@ -1,52 +1,17 @@
 {
     "configurations": [
-   {
-      "type": "firefox",
-      "request": "launch",
-      "reAttach": true,
-      "name": "Launch Examples firefox",
-      "file": "${workspaceFolder}/examples/index.html",
-      "firefoxArgs": [
-         "--enable-features=SharedArrayBuffers"
-       ]
-   },
-   {
-      "name": "Examples",
-      "type": "chrome",
-      "request": "launch",
-      "runtimeArgs": [
-            "--allow-file-access-from-files",
-            "--autoplay-policy=no-user-gesture-required",
-            "--enable-features=SharedArrayBuffer"
-      ],
-      "file": "${workspaceFolder}/examples/index.html",
-      "cwd": "${workspaceFolder}/examples/"
-   },
-   {
-      "name": "(gdb) Launch twr-wasm unit tests",
-      "type": "cppdbg",
-      "request": "launch",
-      "program": "${workspaceFolder}/source/unit-test/out/test.exe",
-      "args": [],
-      "stopAtEntry": false,
-      "cwd": "${workspaceFolder}/source/unit-test/out/",
-      "environment": [],
-      "externalConsole": false,
-      "MIMode": "gdb",
-      "miDebuggerPath": "gdb",
-      "setupCommands": [
-         {
-            "description": "Enable pretty-printing for gdb",
-            "text": "-enable-pretty-printing",
-            "ignoreFailures": true
-         },
-         {
-            "description": "Set Disassembly Flavor to Intel",
-            "text": "-gdb-set disassembly-flavor intel",
-            "ignoreFailures": true
-         }
-      ]
-   },
-    ],
+      {
+         "name": "Examples/Tests (Chrome)",
+         "type": "chrome",
+         "request": "launch",
+         "runtimeArgs": [
+               "--allow-file-access-from-files",
+               "--autoplay-policy=no-user-gesture-required",
+               "--enable-features=SharedArrayBuffer"
+         ],
+         "file": "${workspaceFolder}/examples/index.html",
+         "cwd": "${workspaceFolder}/examples/"
+      },
+   ],
     "version": "2.0.0"
 }

docs/api/api-ts-library.md

@@ -9,7 +9,7 @@ twr-wasm Libraries are used to expose TypeScript code to C/C++ as C APIs.  All o
 There are two kinds of Libraries:
 
 - Those that have only once instance (such as the math library)
-- Those that can have multiple instances across one more more library types, where each library type implements the same interface.  Consoles are an example of this (see [interfaceName](#interfacename)).
+- Those that can have multiple instances across one or more library types, where each library type implements the same interface.  Consoles are an example of this (see [interfaceName](#interfacename)).
 
 ## Basic Steps
 twr-wasm Libraries support both `twrWasmModule` and `twrWasmModuleAsync`.  That is, when you create a twrLibrary, it will function with either type of module.  In many cases no extra work is needed for the `twrWasmModuleAsync`, but in some cases, extra code is needed.
@@ -352,7 +352,7 @@ In a twrLibrary,
 
  - An "interface" refers to the set of functions that the library exposes to C. Ie, the functions in the `import` object.
  - The name of the interface is anonymous, unless `interfaceName` is set. 
- - An undefined interfaceName (anonymous interface) means that only one instance of that class is allowed (for example `twrLibMath`)
+ - An undefined interfaceName (anonymous interface) also means that only one instance of that class is allowed (for example `twrLibMath`)
  - Set `interfaceName` to a unique name when multiple instances that support the same interface are allowed (for example the twr-wasm Consoles).  
  - Multiple classes may have the same interfaceName (a class is identified by its libSourcePath). For example `twrConDiv`, `twrConDebug`, `twrConTerminal` all have the same interface.
 

docs/api/api-ts-modules.md

@@ -17,7 +17,7 @@ const mod = new twrWasmModule();
 ~~~
 
 ## About `twrWasmModuleAsync`
-`class twrWasmModuleAsync` allows you to integrate WebAssembly C/C++ code into your Web Page that uses a CLI pattern or code that blocks.  For example, with `twrWasmModuleAsync` your C/C++ code can call a synchronous function for keyboard input (that blocks until the user has entered the keyboard input).  Or your C/C++ code can `sleep` or otherwise block.   This is the pattern that is used by many standard C library functions - `fread`, etc.  
+`class twrWasmModuleAsync` allows you to integrate WebAssembly C/C++ code into your Web Page that uses a Read-Eval-Print Loop (REPL) pattern, a CLI pattern or code that blocks.  For example, with `twrWasmModuleAsync` your C/C++ code can call a synchronous function for keyboard input (that blocks until the user has entered the keyboard input).  Or your C/C++ code can `sleep` or otherwise block.   This is the pattern that is used by many standard C library functions - `fread`, etc.  
 
 `class twrWasmModuleAsync` creates a WorkerThread that runs in parallel to the JavaScript main thread.  This Worker thread executes your C/C++ code, and proxies functionality that needs to execute in the JavaScript main thread via remote procedure calls.  This allows the JavaScript main thread to `await` on a blocking `callC` in your JavaScript main thread.  
 

docs/examples/examples-divcon.md

@@ -1,10 +1,19 @@
 ---
 title:  Stdio Printf and Input Using a div Tag
-description: This C WebAssembly example shows how to printf and get characters to and from an HTML div tag using twr-wasm
+description: This C WebAssembly example shows how to implement a Read-Eval-Print Loop (REPL) in twr-wasm
 ---
 
-# divcon - Printf and Input Using a div Tag
-This simple WebAssembly C program demos inputting and printing characters with a `div` tag.
+# divcon - Printf and Input Using a `div` Tag
+## What It Does
+This example inputs a number, squares it, and prints the result using standard C library functions.
+
+The divcon example demos:
+
+* A Read-Eval-Print Loop (REPL) 
+* using twr-wasm `class twrWasmModuleAsync` to `await` on blocking C code
+* getting and print characters to a `div` tag using twr-wasm `class twrConsoleDiv`
+
+## Running Examples and Source:
 
 - [view divcon example running live](/examples/dist/divcon/index.html)
 - [View divcon source code](https://github.com/twiddlingbits/twr-wasm/tree/main/examples/divcon)

docs/examples/examples-multi-io.md

@@ -3,7 +3,7 @@ title: Multi-io - WebAssembly C++ Multiple Console Example
 description: This example demos 6 simultaneous consoles. 2 div as streams, 2 canvas as terminals, and 2 canvas as 2D draw surfaces.
 ---
 
-# Multi-io -Multiple Console Example
+# Multi-io Multiple Console Example
 ## What It Does
 This example demos six simultaneous consoles:
 

docs/examples/examples-overview.md

@@ -27,11 +27,11 @@ These examples are a good place to learn how to configure clang and wasm-ld to c
 | terminal |A simple C program demos writing and inputting from a `<canvas>` tag<br>that twr-wasm configures as a windowed "terminal" | [terminal](examples-terminal.md)|
 | multi-io | Demo 6 simultaneous consoles: stream i/o, terminal, and 2D Drawing. | [multi-io](examples-multi-io.md)|
 
-## Draw 2D Examples
+## Draw 2D and Audio Examples
 | Name | Description | Link |
 | -----| ----------- | ---- |
 | balls | These fun Bouncing Balls are written in C++ and demo the 2D drawing<br>APIs with a C++ Canvas wrapper class | [balls](examples-balls.md) |
-| pong | A simple game of Pong written in C++ to demo 2D drawing APIs with a<br>C++ canvas wrapper class and taking user input from JS | [pong](examples-pong.md)
+| pong | A simple game of Pong written in C++ to demo 2D drawing and Audio APIs with<br>a C++ canvas wrapper class and taking user input from JS | [pong](examples-pong.md)
 | maze | This is an old Win32 program ported to wasm and demos 2D Draw APIs | [maze](examples-maze.md) |
 
 ## Call Argument Examples
@@ -40,7 +40,7 @@ These examples are a good place to learn how to configure clang and wasm-ld to c
 | callC | A demo of passing and returning values between JavaScript and Wasm module | [callc](examples-callc.md) |
 | fft | A demo of calling a C library to perform an FFT that is graphed in TypeScript | [fft](examples-fft.md) |
 
-## twrLibrary examples
+## twrLibrary Examples
 | Name | Description | Link |
 | -----| ----------- | ---- |
 | lib | A demo of createing a twrLibrary (use TypeScript to create C/C++ APIs) | [library](examples-lib.md) |

docs/gettingstarted/installation.md

@@ -45,9 +45,15 @@ There is no real downside to this installation method, except possibly: (1) it d
  git clone https://github.com/twiddlingbits/twr-wasm
 ~~~
 
-This method of installation installs the complete code base, including source and built binaries.   
+This method of installation installs the complete code base, including source and built binaries.
 
-The primary downside to this method is that the JavaScript side of twr-wasm will not be placed in a node_modules folder. This will create a little extra work to configure a bundler, TypeScript or VS Code to find the location of imports.
+After twr-wasm is cloned, use VS Code `File | Open Folder`.
+
+[See here](https://github.com/twiddlingbits/twr-wasm/blob/main/examples/readme.md) for information on running the examples or building the examples.
+
+[See here](../more/building.md) for information on building the source.
+
+The primary downside to this method is that the JavaScript side of twr-wasm will not be placed in a node_modules folder. This will create a little extra work to configure a bundler, TypeScript or VS Code to find the location of the twr-wasm module imports.
 
 There are a few solutions to this.  For example, in the provided Hello World example, a `package.json` file with an `alias` entry is used.  This syntax is supported by the Parcel bundler:
 

docs/index.md

@@ -20,7 +20,8 @@ twr-wasm is a simple, lightweight and easy to use library for building C/C++ Web
 
 - the optional TypeScript `class twrWasmModuleAsync` can be used to:
 
-    - integrate CLI C/C++ code with JavaScript
+    - integrate a C/C++ Read-Eval-Print Loop (REPL) with JavaScript
+    - integrate a C/C++ CLI or Shell with JavaScript
     - In JavaScript `await` on blocking/synchronous C/C++ functions. 
 
 - 2D drawing API for C/C++ compatible with JavaScript Canvas
@@ -29,6 +30,7 @@ twr-wasm is a simple, lightweight and easy to use library for building C/C++ Web
 - standard C library optimized for WebAssembly
 - libc++ built for WebAssembly
 - comprehensive examples and documentation
+- TypeScript and JavaScript support
 
 ## Live WebAssembly Examples and Source
 

docs/more/building.md

@@ -48,7 +48,7 @@ mingw32-make
 
 ## To Build the Examples
 
-See examples/readme.md for more information.
+See [examples/readme.md](https://github.com/twiddlingbits/twr-wasm/blob/main/examples/readme.md) for more information.
 
 To build the examples, but not bundle them. 
 ~~~sh

examples/divcon/index.html

@@ -1,8 +1,8 @@
 <!doctype html>
 <html>
 <head>
-   <title>Div Console WebAssembly Example</title>
-   <meta name="description" content="Use a streaming character console with C/C++ WebAssembly that maps stdin and stdout to a div tag. Uses twr-wasm.">
+   <title>Div Console WebAssembly C/C++ Example</title>
+   <meta name="description" content="Map stdin and stdout to a div tag using twr-wasm class twrConsoleDiv. Implements a Read-Eval-Print Loop (REPL)">
 
    <!-- importmap used to find unbundled twr-wasm -->
    <!-- also see package.json 'alias' for parcel bundler example  -->
@@ -17,7 +17,7 @@
 </head>
 <body style="background-color:white;font-family: Arial">
    <h1>twrConsoleDiv Demo</h1>
-   This example shows how to map a simple streaming character twr-wasm Console onto a div tag as stdio.  
+   This example shows how to map a simple streaming character twr-wasm Console onto a div tag as stdio.  A Read-Eval-Print Loop (REPL) is also implemented.
    <br><br>
    <a href="/docsite/examples/examples-overview/">docs and more examples here</a>
    <br><br>

examples/readme.md

@@ -26,7 +26,7 @@ Note: Only the "unbundled" version of the examples are available if you don't bu
 Note: You must run `python` from the twr-wasm root.
 
 ## Execute Examples using Chrome without a local web server 
-An alternative and simple way to run the examples locally without using a local web server is to use the included VS Code `launch.json`.  This file is not included if you install with `npm`.  To access this file, you should [install using git clone](https://twiddlingbits.dev/docsite/gettingstarted/installation/). Then from VS Code, select "Run and Debug" in the left menu, and use the "start debugging" button at the top.
+An alternative and simple way to run the examples locally without using a local web server is to use the included VS Code `launch.json`.  This file is not included if you install with `npm`.  To access this file, you should [install using git clone](https://twiddlingbits.dev/docsite/gettingstarted/installation.md#git-install). Then from VS Code, select "Run and Debug" in the left menu, and use the "start debugging" button at the top.
 
 The examples will run without building using chrome and a file:// URL.  The file "index.html" can be loaded to provide links to each example.  If you are going to run Chrome yourself from a shell, see the section below on some of the Chrome flags you will need to set.
 

readme.md

@@ -11,15 +11,17 @@ twr-wasm is a simple, lightweight and easy to use library for building C/C++ Web
   - in C/C++, print and get characters to/from `<div>` tags in your HTML page
   - in C/C++, print and get characters to/from a `<canvas>` based "terminal"
   - localization support, UTF-8, and windows-1252 support
-- the optional TypeScript `class twrWasmModuleAsync` can be used to:
-  - integrate CLI C/C++ code with JavaScript
+- from JavaScript, use `class twrWasmModuleAsync` to:
+  - integrate a C/C++ Read-Eval-Print Loop (REPL) with JavaScript
+  - integrate a C/C++ CLI or Shell with JavaScript
   - In JavaScript `await` on blocking/synchronous C/C++ functions. 
 - 2D drawing API for C/C++ compatible with JavaScript Canvas
 - audio playback APIs for C/C++
 - create your own C/C++ APIs using TypeScript by extending `class twrLibrary`
 - standard C library optimized for WebAssembly
 - libc++ built for WebAssembly
 - comprehensive examples and documentation
+- TypeScript and JavaScript support
 
 ## Live WebAssembly Examples and Source