## What is 'newLISP in a web browser'

newLISP can be compiled to JavaScript and then run in a web browser like any other JavaScript program. `newlisp-js-lib.js` is newLISP compiled to a JavaScript library using the Emscripten SDK tool chain:

> http://kripken.github.io/emscripten-site/

This application implements an editor and development environment (IDE) for newLISP, HTML and JavaScript code. Any other Application could be built this way. To run newLISP code from JavaSript a `newlispEvalStr(string)` JavaScript function is available after loading the `newlisp-js-lib.js` library and using a line of JavaScript to import this function.

Likewise newLISP can call back into JavaScript code using the `(eval-string-js string)` function. Both languages can be hosted by an HTML page.

The app.html demo file shows how to do this. Everything necessary to write your own application is contained in a 3k part of this file. Only `app.html` and the `newlisp-js-lib.js` library are required to run this newLISP application client-side in a web browser.

For a tutorial in to the basics of newLISP type `(load "newlisp-js/tutorial.lsp")` in to the editor then click the `eval` button. This tutorial is best used in two-column layout and copies some material from the WikiBooks tutorial: Introduction to newLISP.

The editor control with syntax highlighting and themes is from the CodeMirror project at: codemirror.net/.

An alternative simple editor without synytax highlighting, but with parenthesis matching, has no external dependencies.

## Installation

Download and unzip the newlisp-js-10.6.1.zip package in the document directory of a web server or do a serverless installation on an individual computer and load the `index.html` file directly into your web browser. This file contains the editor.

When running on a webserver, the `newlisp-js-lib.js` library can be compressed to a `.gz` file for faster delivery. Compress using the Unix `gzip` or other zip compression utilities. Full HTTP 1.1 webserver installations can serve these files and they are automatically decompressed by most web browsers. The compressed `newlisp-js-lib.js.gz` is only about 200K in size. When using a compressed library, the library name in `index.html` and `app.html` has to be changed to reflect the name change of `newlisp-js-lib.js`. There is only one place at the end of the file where `.gz` has to be appended to the library name.

The CodeMirror editor library `codemirror/lib/codemirror.js` can also be compressed and is only referenced at the beginning of `index.html`.

## How to use 'newLISP in a web browser'

Wait for "Downloading ..." to finish. newLISP expressions can now be entered in the editor input window and be evaluated pushing the red `eval` button. Output is shown in the log window.

The editor can also be used to edit JavaScript content or HTML content. The red `JS` button will evaluate JavaScript content and the red `HTML` button will open a page in a new browser tab containing the rendered HTML. Code from all three languages can be mixed on the same oage and interact with each other.

#### Buttons on top and keyboard short-cuts:

- `eval` - evaluates newLISP source in edit box (Ctrl-enter)
- `silent` - evaluates newLISP source in edit box silently (Shift-Ctrl-enter)
- `JS` - evaluates JavaScript in edit box
- `htlml` - opens a new tab with HTML from the editor
- `x-edit` - clears the editor box (Ctrl-L)
- `x-log` - clears log box (Shift-Ctrl-L)
- `layout` - switches between three layouts
- `#` - toggle line numbers on / off - (Ctrl-1)
- `theme` - switches between seven color themes
- `info` - shows this page in a new browser tab
- `doc` - shows and searches the reference manual
- `↻` - reload newLISP and local browser storage (Ctrl-R)

The `eval` button will show all top-level return values in the log window. The `silent` button only shows text output by `print` or `println` or other functions writing to standard out.

`htlml` is the preferred button for web development, as HTML, JavaScript and newLISP source can be mixed on the same page (see app.html demo as an example.

Different themes set by the `theme` button also change the way matching parentheses are shown.

The input box to the right of the `doc` button can be either filled manually using the keyboard or a text selection can be made anywhere in the editor or log box. On computer devicers with a mouse, the text gets put into the search box on mouse-up. On mobile touch devices the selecton must be copy/pasted manually.

#### Buttons at the bottom and keyboard short-cuts:

- `save` - save edit box content to browser local storage (Ctrl-S)
- `open` - load edit content from a file on the local file system (Ctrl-O)

The `save` button saves the current edit content to the local storage system of the browser. On startup this content will be restored automatically. This storage is owned by the inidividual browser (IE, Firefox, Chrome, Safari, Opera). There are no browser cookies set and no internet connection is necessary for this private storage. For saving files to the local file system copy and paste must be used to transfer files out of the browser.

The `save` button also saves the layout and color theme.

The `open file` button is disabled on mobile devices.

Note, that all browser local storage is tied to the domain from which the editor is loaded. Allthough storage is local to your device, the same content can only be accessed using the editor from the same internet domain location. If using Firefox, distinction is also made for different places on the local disk. Safari and Chrome don't forget local storage even if the browser gets shut down and the editor was loaded from a remote site. Firefox behavior is different in this respect depending on the platform it is running on.

Red buttons delete or replace existing content. Blue buttons act on content in the edit box. `x-edit`, `x-log` and `open` can be undone using `Ctrl-Z` or `Command-Z` on Mac OS X. `↻` cannot be undone.

#### Keyboard commands without buttons

In the editor `Alt-up/down` or `Option-up/down` moves the current line or all lines in a selection. Select with a mouse or `Shift-right/down`.

Fontsize can be adjusted on Mac OS X using the `command+` and `command-` keys. On Windows and Unix systems use `Ctrl+` and `Ctrl-`.

Changes of the editor content can be undone using `Command-Z` on Mac OS X or using `Ctrl-Z` on Windows and Linux.

On Mac OS X the `Ctrl-B,F,P,N,H,D` keys can be used for cursor movement in all for directions and deletion of characters before and after the caret.

## Performance considerations

In this sandboxed JavaScript environment, most File and network I/O functions will not work or work in different ways. Memory is also constrained for applications in a web browser. Bigger newLISP applications for the web should run server-side in native compiled newLISP to use all of its File, network and distributed and parallel processing functions.

The following functions are not available in newlisp-js-lib.js:

> `debug, trace, trace-highlight
> semaphore, share, signal, timer
> abort, exec, fork, process, receive, send, spawn, sync
> net-packet, net-ping, net-service
> get-url, put-url, post-url, delete-url
> net-accept, net-close, net-connect, net-error, net-eval
> net-interface, net-ipv, net-listen, net-local, net-lookup
> net-packet, net-peek, net-peer, net-ping, net-receive
> net-receive-from, net-receive-udp, net-select, net-send
> net-send-to, net-send-udp, net-sessions`

The following functions are available but will have limited functonality. `file://` and `http://` URLs cannot be used, as is possible on native compiled newLISP with the last line of functions below. All functions work on a session filesystem. All contents of this filesystem is forgotten when closing or reloading the browser page. Still, for learning purpose or testing code, it can be useful.

> `load, save`
> `directory, make-dir, change-dir, remove-dir`
> `open, close, read, write`
> `read-char, write-char, read-line, write-line, read-utf8`
> `read-file, write-file, append-file, delete-file, rename-file`

Some functions can work on `stdin`. E.g.: `(read-line)` will pop up two JavaScript `window.prompt()` dialogs one after the other to enter a string:

    (add (int (read-line)) (int (read-line)))

To write to `stdout` open the device `dev/stdout`:

    (set 'out (open "dev/stdout" "w"))
    (write out "hello\n")
    (close out)

This would add the two numbers entered in dialog windows and show the result in the log window.

## Re-defining existing built-in functions using JavaScript

The browser version of newLISP adds a function `eval-string-js` to call JavaScript int the host browser. This way libraries like jQuery or Bootstrap can be used to replace some of the web and network functions:

        (constant 'get-url (lambda (url)
            (eval-string-js (string "GetUrl('" url "')")) )
        )

`GetUrl()` would be a JavaScript function implementing the functionality of newLISP's `get-url`. The `constant` function allows to redefine protected symbols from built-in functions. Primitives redefined this way will still be `protected?` and `global?`.

## Replacing the editor page with a new page

Another new builtin function is `display-html`. The function can be used to replace the current page containing the editor with a new webpage. When evaluating the following snippet in the editor box, the new content will apear:

    (display-html "<html>Hello World</html>")

To get back to the newLISP environment, hit the back-key in the browser.

## Displaying an HTML page in a new browser tab

    (display-html "<html>Hello World</html>" true)

The `true` parameter causes a new tab to be opened. This is the same function as used by the `html` button.

## Developing HTML in the browser

Without using `display-html`, HTML can be written in the editor box, intermixed with JavaScript, if required. The `html` button will then open a page in a new tab of the web browser with HTML content of the editor box:

    <html>Hello World</html>

See also the app.html page.

## License

The JavaScript Emscripten library `newlisp-js-lib.js` is licensed under GNU General Public License Version 3, June 2007 - (GPL v.3).

§