The remote-js Reference Manual

Table of Contents

The remote-js Reference Manual

This is the remote-js Reference Manual, version 0.1, generated automatically by Declt version 3.0 "Montgomery Scott" on Mon Apr 19 17:37:51 2021 GMT+0.

1 Introduction

remote-js

Send JavaScript from Common Lisp to a browser.

Overview

Usage

Simple Example

First, we create a context object:

(defvar ctx (remote-js:make-context))

Then we start the WebSockets server:

(remote-js:start ctx)

Now, remote-js gives us a function that generates the HTML of a simple page that connects to this context and notifies it when it's connected. We write the HTML to ~/test.html:

(with-open-file (stream (merge-pathnames #p"test.html" (user-homedir-pathname))
                        :direction :output
                        :if-exists :supersede
                        :if-does-not-exist :create)
  (write-string (remote-js:html ctx) stream))

Open the file in your browser. Now you can do:

(remote-js:eval ctx "alert('hello!')")

And you will see the alert box pop up in your browser.

Talking to the server

remote-js defines a function in the generated HTML, RemoteJS.send, which takes a string and sends it to the server. You can specify a callback for receiving messages like this:

(defvar ctx (remote-js:make-context
              :callback #'(lambda (message) (format t "Received: ~A~%" message))))

Then, start everything and generate the HTML file again:

(remote-js:start ctx)
(with-open-file (stream (merge-pathnames #p"test.html" (user-homedir-pathname))
                        :direction :output
                        :if-exists :supersede
                        :if-does-not-exist :create)
  (write-string (remote-js:html ctx) stream))

And open test.html in your browser.

Now you can send messages to the server like this:

CL-USER> (remote-js:eval ctx "RemoteJS.send('hi!')")
Received: hi!

Note: when a client connects to the server, it sends the string remote-js:+connected-message+.

Tests

The tests use trivial-open-browser, and running them will open your default browser to a temporary file.

License

Copyright (c) 2016 Fernando Borretti

Licensed under the MIT License.

2 Systems

The main system appears first, followed by any subsystem dependency.

2.1 remote-js

Maintainer

Fernando Borretti <eudoxiahp@gmail.com>

Author

Fernando Borretti <eudoxiahp@gmail.com>

Home Page

https://github.com/ceramic/remote-js

Source Control

(:git "git@github.com:ceramic/remote-js.git")

Bug Tracker

https://github.com/ceramic/remote-js/issues

License

MIT

Description

Send JavaScript from Common Lisp to a browser.

Long Description

# remote-js

[](https://travis-ci.org/ceramic/remote-js)

Send JavaScript from Common Lisp to a browser.

# Overview

# Usage

## Simple Example

First, we create a context object:

“‘lisp
(defvar ctx (remote-js:make-context))
“‘

Then we start the WebSockets server:

“‘lisp
(remote-js:start ctx)
“‘

Now, remote-js gives us a function that generates the HTML of a simple page that
connects to this context and notifies it when it’s connected. We write the HTML
to ‘~/test.html‘:

“‘lisp
(with-open-file (stream (merge-pathnames #p"test.html" (user-homedir-pathname))
:direction :output
:if-exists :supersede
:if-does-not-exist :create)
(write-string (remote-js:html ctx) stream))
“‘

Open the file in your browser. Now you can do:

“‘lisp
(remote-js:eval ctx "alert(’hello!’)")
“‘

And you will see the alert box pop up in your browser.

## Talking to the server

remote-js defines a function in the generated HTML, ‘RemoteJS.send‘, which takes
a string and sends it to the server. You can specify a callback for receiving
messages like this:

“‘lisp
(defvar ctx (remote-js:make-context
:callback #’(lambda (message) (format t "Received: ~A~%" message))))
“‘

Then, start everything and generate the HTML file again:

“‘lisp
(remote-js:start ctx)
(with-open-file (stream (merge-pathnames #p"test.html" (user-homedir-pathname))
:direction :output
:if-exists :supersede
:if-does-not-exist :create)
(write-string (remote-js:html ctx) stream))
“‘

And open ‘test.html‘ in your browser.

Now you can send messages to the server like this:

“‘lisp
CL-USER> (remote-js:eval ctx "RemoteJS.send(’hi!’)")
Received: hi!
“‘

**Note:** when a client connects to the server, it sends the string
‘remote-js:+connected-message+‘.

# Tests

The tests use [trivial-open-browser][tob], and running them will open your
default browser to a temporary file.

# License

Copyright (c) 2016 Fernando Borretti

Licensed under the MIT License.

[tob]: http://quickdocs.org/trivial-open-browser/

Version

0.1

Dependencies

• trivial-ws
• cl-markup
• find-port

Source

remote-js.asd (file)

Component

src (module)

3 Modules

Modules are listed depth-first from the system components tree.

3.1 remote-js/src

Parent

remote-js (system)

Location

src/

Component

remote-js.lisp (file)

4 Files

Files are sorted by type and then listed depth-first from the systems components trees.

4.1 Lisp

4.1.1 remote-js.asd

Location

remote-js.asd

Systems

remote-js (system)

4.1.2 remote-js/src/remote-js.lisp

Parent

src (module)

Location

src/remote-js.lisp

Packages

remote-js

Exported Definitions

• +connected-message+ (special variable)
• buffered-context (class)
• context (class)
• context-address (method)
• context-connected-p (method)
• (setf context-connected-p) (method)
• context-port (method)
• context-running-p (method)
• (setf context-running-p) (method)
• context-server (method)
• (setf context-server) (method)
• eval (generic function)
• eval (method)
• eval (method)
• html (generic function)
• html (method)
• js (generic function)
• js (method)
• make-buffered-context (function)
• make-context (function)
• start (generic function)
• start (method)
• stop (generic function)
• stop (method)

Internal Definitions

• +default-callback+ (special variable)
• +script-template+ (special variable)
• context-buffer (method)
• (setf context-buffer) (method)
• context-callback (method)
• (setf context-callback) (method)
• context-handler (method)
• (setf context-handler) (method)
• context-record-p (method)
• (setf context-record-p) (method)
• context-timeout (method)
• server-for-context (function)

5 Packages

Packages are listed by definition order.

5.1 remote-js

The main package.

Source

remote-js.lisp (file)

Use List

common-lisp

Exported Definitions

• +connected-message+ (special variable)
• buffered-context (class)
• context (class)
• context-address (generic function)
• context-address (method)
• context-connected-p (generic function)
• context-connected-p (method)
• (setf context-connected-p) (method)
• (setf context-connected-p) (generic function)
• context-port (generic function)
• context-port (method)
• context-running-p (generic function)
• context-running-p (method)
• (setf context-running-p) (method)
• (setf context-running-p) (generic function)
• context-server (generic function)
• context-server (method)
• (setf context-server) (method)
• (setf context-server) (generic function)
• eval (generic function)
• eval (method)
• eval (method)
• html (generic function)
• html (method)
• js (generic function)
• js (method)
• make-buffered-context (function)
• make-context (function)
• start (generic function)
• start (method)
• stop (generic function)
• stop (method)

Internal Definitions

• +default-callback+ (special variable)
• +script-template+ (special variable)
• context-buffer (generic function)
• context-buffer (method)
• (setf context-buffer) (method)
• (setf context-buffer) (generic function)
• context-callback (generic function)
• context-callback (method)
• (setf context-callback) (method)
• (setf context-callback) (generic function)
• context-handler (generic function)
• context-handler (method)
• (setf context-handler) (method)
• (setf context-handler) (generic function)
• context-record-p (generic function)
• context-record-p (method)
• (setf context-record-p) (method)
• (setf context-record-p) (generic function)
• context-timeout (generic function)
• context-timeout (method)
• server-for-context (function)

6 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.

6.1 Exported definitions

6.1.1 Special variables

Special Variable: +connected-message+

Package

remote-js

Source

remote-js.lisp (file)

6.1.2 Functions

Function: make-buffered-context &key ADDRESS PORT CALLBACK TIMEOUT RECORDP

Create a buffered context object.

Package

remote-js

Source

remote-js.lisp (file)

Function: make-context &key ADDRESS PORT TIMEOUT CALLBACK RECORDP

Create a context object.

Package

remote-js

Source

remote-js.lisp (file)

6.1.3 Generic functions

Generic Function: context-address OBJECT

Package

remote-js

Methods

Method: context-address (CONTEXT context)

The address the WebSockets server will run on.

Source

remote-js.lisp (file)

Generic Function: context-connected-p OBJECT

Generic Function: (setf context-connected-p) NEW-VALUE OBJECT

Package

remote-js

Methods

Method: context-connected-p (BUFFERED-CONTEXT buffered-context)

Method: (setf context-connected-p) NEW-VALUE (BUFFERED-CONTEXT buffered-context)

Whether or not the client is connected.

Source

remote-js.lisp (file)

Generic Function: context-port OBJECT

Package

remote-js

Methods

Method: context-port (CONTEXT context)

The port the WebSockets server will run on.

Source

remote-js.lisp (file)

Generic Function: context-running-p OBJECT

Generic Function: (setf context-running-p) NEW-VALUE OBJECT

Package

remote-js

Methods

Method: context-running-p (CONTEXT context)

Method: (setf context-running-p) NEW-VALUE (CONTEXT context)

Whether the server is running.

Source

remote-js.lisp (file)

Generic Function: context-server OBJECT

Generic Function: (setf context-server) NEW-VALUE OBJECT

Package

remote-js

Methods

Method: context-server (CONTEXT context)

Method: (setf context-server) NEW-VALUE (CONTEXT context)

The trivial-websockets server.

Source

remote-js.lisp (file)

Generic Function: eval CONTEXT STRING

Send some JavaScript to evaluate remotely. Return the string.

Package

remote-js

Source

remote-js.lisp (file)

Methods

Method: eval (CONTEXT buffered-context) STRING

Send JavaScript to evaluate, if the buffer is connected. Otherwise, add the code to the buffer.

If there’s anything in the buffer and the client is connected, send it all in
order before evaluating the string.

Method: eval (CONTEXT context) STRING

Generic Function: html CONTEXT

Return the HTML for this context.

Package

remote-js

Source

remote-js.lisp (file)

Methods

Method: html (CONTEXT context)

Generic Function: js CONTEXT

Return the JS for this context.

Package

remote-js

Source

remote-js.lisp (file)

Methods

Method: js (CONTEXT context)

Generic Function: start CONTEXT

Start the WebSockets server.

Package

remote-js

Source

remote-js.lisp (file)

Methods

Method: start (CONTEXT context)

Generic Function: stop CONTEXT

Stop the WebSockets server.

Package

remote-js

Source

remote-js.lisp (file)

Methods

Method: stop (CONTEXT context)

6.1.4 Classes

Class: buffered-context ()

The buffered context stores evaluation commands in a buffer until a client connects, then sends all of them at once.

Package

remote-js

Source

remote-js.lisp (file)

Direct superclasses

context (class)

Direct methods

• eval (method)
• initialize-instance (method)
• context-buffer (method)
• context-buffer (method)
• context-connected-p (method)
• context-connected-p (method)

Direct slots

Slot: %callback

Slot: connected

Whether or not the client is connected.

Readers

context-connected-p (generic function)

Writers

(setf context-connected-p) (generic function)

Slot: buffer

A list of JavaScript strings to evaluate.

Type

list

Initargs

:buffer

Readers

context-buffer (generic function)

Writers

(setf context-buffer) (generic function)

Class: context ()

A context object.

Package

remote-js

Source

remote-js.lisp (file)

Direct superclasses

standard-object (class)

Direct subclasses

buffered-context (class)

Direct methods

• eval (method)
• html (method)
• js (method)
• stop (method)
• start (method)
• context-callback (method)
• context-callback (method)
• context-record-p (method)
• context-record-p (method)
• context-running-p (method)
• context-running-p (method)
• context-handler (method)
• context-handler (method)
• context-server (method)
• context-server (method)
• context-timeout (method)
• context-port (method)
• context-address (method)

Direct slots

Slot: address

The address the WebSockets server will run on.

Type

string

Initargs

:address

Initform

trivial-ws:+default-address+

Readers

context-address (generic function)

Slot: port

The port the WebSockets server will run on.

Type

integer

Initargs

:port

Initform

(find-port:find-port)

Readers

context-port (generic function)

Slot: timeout

The number of seconds after which the WebSockets server will disconnect an inactive client.

Type

integer

Initargs

:timeout

Initform

trivial-ws:+default-timeout+

Readers

context-timeout (generic function)

Slot: server

The trivial-websockets server.

Initargs

:server

Readers

context-server (generic function)

Writers

(setf context-server) (generic function)

Slot: handler

The server handler.

Initargs

:handler

Readers

context-handler (generic function)

Writers

(setf context-handler) (generic function)

Slot: runningp

Whether the server is running.

Readers

context-running-p (generic function)

Writers

(setf context-running-p) (generic function)

Slot: record

Whether or not to record sent HTML.

Type

boolean

Initargs

:recordp

Readers

context-record-p (generic function)

Writers

(setf context-record-p) (generic function)

Slot: callback

The function that is called when the client sends a message.

Initargs

:callback

Initform

remote-js::+default-callback+

Readers

context-callback (generic function)

Writers

(setf context-callback) (generic function)

6.2 Internal definitions

6.2.1 Special variables

Special Variable: +default-callback+

Package

remote-js

Source

remote-js.lisp (file)

Special Variable: +script-template+

Package

remote-js

Source

remote-js.lisp (file)

6.2.2 Functions

Function: server-for-context CONTEXT

Package

remote-js

Source

remote-js.lisp (file)

6.2.3 Generic functions

Generic Function: context-buffer OBJECT

Generic Function: (setf context-buffer) NEW-VALUE OBJECT

Package

remote-js

Methods

Method: context-buffer (BUFFERED-CONTEXT buffered-context)

Method: (setf context-buffer) NEW-VALUE (BUFFERED-CONTEXT buffered-context)

A list of JavaScript strings to evaluate.

Source

remote-js.lisp (file)

Generic Function: context-callback OBJECT

Generic Function: (setf context-callback) NEW-VALUE OBJECT

Package

remote-js

Methods

Method: context-callback (CONTEXT context)

Method: (setf context-callback) NEW-VALUE (CONTEXT context)

The function that is called when the client sends a message.

Source

remote-js.lisp (file)

Generic Function: context-handler OBJECT

Generic Function: (setf context-handler) NEW-VALUE OBJECT

Package

remote-js

Methods

Method: context-handler (CONTEXT context)

Method: (setf context-handler) NEW-VALUE (CONTEXT context)

The server handler.

Source

remote-js.lisp (file)

Generic Function: context-record-p OBJECT

Generic Function: (setf context-record-p) NEW-VALUE OBJECT

Package

remote-js

Methods

Method: context-record-p (CONTEXT context)

Method: (setf context-record-p) NEW-VALUE (CONTEXT context)

Whether or not to record sent HTML.

Source

remote-js.lisp (file)

Generic Function: context-timeout OBJECT

Package

remote-js

Methods

Method: context-timeout (CONTEXT context)

The number of seconds after which the WebSockets server will disconnect an inactive client.

Source

remote-js.lisp (file)

Appendix A Indexes

A.1 Concepts

A.2 Functions

A.3 Variables

A.4 Data types