The remote-js Reference Manual

This is the remote-js Reference Manual, version 0.1, generated automatically by Declt version 4.0 beta 2 "William Riker" on Wed May 15 06:46:38 2024 GMT+0.

Table of Contents


1 Introduction


2 Systems

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


2.1 remote-js

Send JavaScript from Common Lisp to a browser.

Maintainer

Fernando Borretti <>

Author

Fernando Borretti <>

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

Long Description

# remote-js

[![Build Status](https://travis-ci.org/ceramic/remote-js.svg?branch=master)](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 (system).
  • cl-markup (system).
  • find-port (system).
Source

remote-js.asd.

Child Component

src (module).


3 Modules

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


3.1 remote-js/src

Source

remote-js.asd.

Parent Component

remote-js (system).

Child 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/remote-js.asd

Source

remote-js.asd.

Parent Component

remote-js (system).

ASDF Systems

remote-js.


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

Source

remote-js.asd.

Parent Component

src (module).

Packages

remote-js.

Public Interface
Internals

5 Packages

Packages are listed by definition order.


5.1 remote-js

The main package.

Source

remote-js.lisp.

Use List

common-lisp.

Public Interface
Internals

6 Definitions

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


6.1 Public Interface


6.1.1 Special variables

Special Variable: +connected-message+
Package

remote-js.

Source

remote-js.lisp.


6.1.2 Ordinary functions

Function: make-buffered-context (&key address port callback timeout recordp)

Create a buffered context object.

Package

remote-js.

Source

remote-js.lisp.

Function: make-context (&key address port timeout callback recordp)

Create a context object.

Package

remote-js.

Source

remote-js.lisp.


6.1.3 Generic functions

Generic Reader: context-address (object)
Package

remote-js.

Methods
Reader Method: context-address ((context context))

The address the WebSockets server will run on.

Source

remote-js.lisp.

Target Slot

address.

Generic Reader: context-connected-p (object)
Generic Writer: (setf context-connected-p) (object)
Package

remote-js.

Methods
Reader Method: context-connected-p ((buffered-context buffered-context))
Writer Method: (setf context-connected-p) ((buffered-context buffered-context))

Whether or not the client is connected.

Source

remote-js.lisp.

Target Slot

connected.

Generic Reader: context-port (object)
Package

remote-js.

Methods
Reader Method: context-port ((context context))

The port the WebSockets server will run on.

Source

remote-js.lisp.

Target Slot

port.

Generic Reader: context-running-p (object)
Generic Writer: (setf context-running-p) (object)
Package

remote-js.

Methods
Reader Method: context-running-p ((context context))
Writer Method: (setf context-running-p) ((context context))

Whether the server is running.

Source

remote-js.lisp.

Target Slot

runningp.

Generic Reader: context-server (object)
Generic Writer: (setf context-server) (object)
Package

remote-js.

Methods
Reader Method: context-server ((context context))
Writer Method: (setf context-server) ((context context))

The trivial-websockets server.

Source

remote-js.lisp.

Target Slot

server.

Generic Function: eval (context string)

Send some JavaScript to evaluate remotely. Return the string.

Package

remote-js.

Source

remote-js.lisp.

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.

Methods
Method: html ((context context))
Generic Function: js (context)

Return the JS for this context.

Package

remote-js.

Source

remote-js.lisp.

Methods
Method: js ((context context))
Generic Function: start (context)

Start the WebSockets server.

Package

remote-js.

Source

remote-js.lisp.

Methods
Method: start ((context context))
Generic Function: stop (context)

Stop the WebSockets server.

Package

remote-js.

Source

remote-js.lisp.

Methods
Method: stop ((context context))

6.1.4 Standalone methods

Method: initialize-instance :after ((context buffered-context) &key)
Source

remote-js.lisp.


6.1.5 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.

Direct superclasses

context.

Direct methods
Direct slots
Slot: %callback
Slot: connected

Whether or not the client is connected.

Readers

context-connected-p.

Writers

(setf context-connected-p).

Slot: buffer

A list of JavaScript strings to evaluate.

Type

list

Initargs

:buffer

Readers

context-buffer.

Writers

(setf context-buffer).

Class: context

A context object.

Package

remote-js.

Source

remote-js.lisp.

Direct subclasses

buffered-context.

Direct methods
Direct slots
Slot: address

The address the WebSockets server will run on.

Type

string

Initform

trivial-ws:+default-address+

Initargs

:address

Readers

context-address.

Writers

This slot is read-only.

Slot: port

The port the WebSockets server will run on.

Type

integer

Initform

(find-port:find-port)

Initargs

:port

Readers

context-port.

Writers

This slot is read-only.

Slot: timeout

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

Type

integer

Initform

trivial-ws:+default-timeout+

Initargs

:timeout

Readers

context-timeout.

Writers

This slot is read-only.

Slot: server

The trivial-websockets server.

Initargs

:server

Readers

context-server.

Writers

(setf context-server).

Slot: handler

The server handler.

Initargs

:handler

Readers

context-handler.

Writers

(setf context-handler).

Slot: runningp

Whether the server is running.

Readers

context-running-p.

Writers

(setf context-running-p).

Slot: record

Whether or not to record sent HTML.

Type

boolean

Initargs

:recordp

Readers

context-record-p.

Writers

(setf context-record-p).

Slot: callback

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

Initform

remote-js::+default-callback+

Initargs

:callback

Readers

context-callback.

Writers

(setf context-callback).


6.2 Internals


6.2.1 Special variables

Special Variable: +default-callback+
Package

remote-js.

Source

remote-js.lisp.

Special Variable: +script-template+
Package

remote-js.

Source

remote-js.lisp.


6.2.2 Ordinary functions

Function: server-for-context (context)
Package

remote-js.

Source

remote-js.lisp.


6.2.3 Generic functions

Generic Reader: context-buffer (object)
Generic Writer: (setf context-buffer) (object)
Package

remote-js.

Methods
Reader Method: context-buffer ((buffered-context buffered-context))
Writer Method: (setf context-buffer) ((buffered-context buffered-context))

A list of JavaScript strings to evaluate.

Source

remote-js.lisp.

Target Slot

buffer.

Generic Reader: context-callback (object)
Generic Writer: (setf context-callback) (object)
Package

remote-js.

Methods
Reader Method: context-callback ((context context))
Writer Method: (setf context-callback) ((context context))

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

Source

remote-js.lisp.

Target Slot

callback.

Generic Reader: context-handler (object)
Generic Writer: (setf context-handler) (object)
Package

remote-js.

Methods
Reader Method: context-handler ((context context))
Writer Method: (setf context-handler) ((context context))

The server handler.

Source

remote-js.lisp.

Target Slot

handler.

Generic Reader: context-record-p (object)
Generic Writer: (setf context-record-p) (object)
Package

remote-js.

Methods
Reader Method: context-record-p ((context context))
Writer Method: (setf context-record-p) ((context context))

Whether or not to record sent HTML.

Source

remote-js.lisp.

Target Slot

record.

Generic Reader: context-timeout (object)
Package

remote-js.

Methods
Reader Method: context-timeout ((context context))

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

Source

remote-js.lisp.

Target Slot

timeout.


Appendix A Indexes


A.1 Concepts


A.2 Functions

Jump to:   (  
C   E   F   G   H   I   J   M   S  
Index Entry  Section

(
(setf context-buffer): Private generic functions
(setf context-buffer): Private generic functions
(setf context-callback): Private generic functions
(setf context-callback): Private generic functions
(setf context-connected-p): Public generic functions
(setf context-connected-p): Public generic functions
(setf context-handler): Private generic functions
(setf context-handler): Private generic functions
(setf context-record-p): Private generic functions
(setf context-record-p): Private generic functions
(setf context-running-p): Public generic functions
(setf context-running-p): Public generic functions
(setf context-server): Public generic functions
(setf context-server): Public generic functions

C
context-address: Public generic functions
context-address: Public generic functions
context-buffer: Private generic functions
context-buffer: Private generic functions
context-callback: Private generic functions
context-callback: Private generic functions
context-connected-p: Public generic functions
context-connected-p: Public generic functions
context-handler: Private generic functions
context-handler: Private generic functions
context-port: Public generic functions
context-port: Public generic functions
context-record-p: Private generic functions
context-record-p: Private generic functions
context-running-p: Public generic functions
context-running-p: Public generic functions
context-server: Public generic functions
context-server: Public generic functions
context-timeout: Private generic functions
context-timeout: Private generic functions

E
eval: Public generic functions
eval: Public generic functions
eval: Public generic functions

F
Function, make-buffered-context: Public ordinary functions
Function, make-context: Public ordinary functions
Function, server-for-context: Private ordinary functions

G
Generic Function, (setf context-buffer): Private generic functions
Generic Function, (setf context-callback): Private generic functions
Generic Function, (setf context-connected-p): Public generic functions
Generic Function, (setf context-handler): Private generic functions
Generic Function, (setf context-record-p): Private generic functions
Generic Function, (setf context-running-p): Public generic functions
Generic Function, (setf context-server): Public generic functions
Generic Function, context-address: Public generic functions
Generic Function, context-buffer: Private generic functions
Generic Function, context-callback: Private generic functions
Generic Function, context-connected-p: Public generic functions
Generic Function, context-handler: Private generic functions
Generic Function, context-port: Public generic functions
Generic Function, context-record-p: Private generic functions
Generic Function, context-running-p: Public generic functions
Generic Function, context-server: Public generic functions
Generic Function, context-timeout: Private generic functions
Generic Function, eval: Public generic functions
Generic Function, html: Public generic functions
Generic Function, js: Public generic functions
Generic Function, start: Public generic functions
Generic Function, stop: Public generic functions

H
html: Public generic functions
html: Public generic functions

I
initialize-instance: Public standalone methods

J
js: Public generic functions
js: Public generic functions

M
make-buffered-context: Public ordinary functions
make-context: Public ordinary functions
Method, (setf context-buffer): Private generic functions
Method, (setf context-callback): Private generic functions
Method, (setf context-connected-p): Public generic functions
Method, (setf context-handler): Private generic functions
Method, (setf context-record-p): Private generic functions
Method, (setf context-running-p): Public generic functions
Method, (setf context-server): Public generic functions
Method, context-address: Public generic functions
Method, context-buffer: Private generic functions
Method, context-callback: Private generic functions
Method, context-connected-p: Public generic functions
Method, context-handler: Private generic functions
Method, context-port: Public generic functions
Method, context-record-p: Private generic functions
Method, context-running-p: Public generic functions
Method, context-server: Public generic functions
Method, context-timeout: Private generic functions
Method, eval: Public generic functions
Method, eval: Public generic functions
Method, html: Public generic functions
Method, initialize-instance: Public standalone methods
Method, js: Public generic functions
Method, start: Public generic functions
Method, stop: Public generic functions

S
server-for-context: Private ordinary functions
start: Public generic functions
start: Public generic functions
stop: Public generic functions
stop: Public generic functions