The remote-js Reference Manual

Table of Contents

Next: , Previous: , Up: (dir)   [Contents][Index]

The remote-js Reference Manual

This is the remote-js Reference Manual, version 0.1, generated automatically by Declt version 2.4 "Will Decker" on Wed Jun 20 12:30:52 2018 GMT+0.


Next: , Previous: , Up: Top   [Contents][Index]

1 Introduction

remote-js

Build Status

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.


Next: , Previous: , Up: Top   [Contents][Index]

2 Systems

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


Previous: , Up: Systems   [Contents][Index]

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

[![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
Source

remote-js.asd (file)

Component

src (module)


Next: , Previous: , Up: Top   [Contents][Index]

3 Modules

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


Previous: , Up: Modules   [Contents][Index]

3.1 remote-js/src

Parent

remote-js (system)

Location

src/

Component

remote-js.lisp (file)


Next: , Previous: , Up: Top   [Contents][Index]

4 Files

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


Previous: , Up: Files   [Contents][Index]

4.1 Lisp


Next: , Previous: , Up: Lisp files   [Contents][Index]

4.1.1 remote-js.asd

Location

remote-js.asd

Systems

remote-js (system)


Previous: , Up: Lisp files   [Contents][Index]

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

Parent

src (module)

Location

src/remote-js.lisp

Packages

remote-js

Exported Definitions
Internal Definitions

Next: , Previous: , Up: Top   [Contents][Index]

5 Packages

Packages are listed by definition order.


Previous: , Up: Packages   [Contents][Index]

5.1 remote-js

The main package.

Source

remote-js.lisp (file)

Use List

common-lisp

Exported Definitions
Internal Definitions

Next: , Previous: , Up: Top   [Contents][Index]

6 Definitions

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


Next: , Previous: , Up: Definitions   [Contents][Index]

6.1 Exported definitions


Next: , Previous: , Up: Exported definitions   [Contents][Index]

6.1.1 Special variables

Special Variable: +connected-message+
Package

remote-js

Source

remote-js.lisp (file)


Next: , Previous: , Up: Exported definitions   [Contents][Index]

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)


Next: , Previous: , Up: Exported definitions   [Contents][Index]

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)

Previous: , Up: Exported definitions   [Contents][Index]

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
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
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)


Previous: , Up: Definitions   [Contents][Index]

6.2 Internal definitions


Next: , Previous: , Up: Internal definitions   [Contents][Index]

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)


Next: , Previous: , Up: Internal definitions   [Contents][Index]

6.2.2 Functions

Function: server-for-context CONTEXT
Package

remote-js

Source

remote-js.lisp (file)


Previous: , Up: Internal definitions   [Contents][Index]

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)


Previous: , Up: Top   [Contents][Index]

Appendix A Indexes


Next: , Previous: , Up: Indexes   [Contents][Index]

A.1 Concepts

Jump to:   F   L   M   R  
Index Entry  Section

F
File, Lisp, remote-js.asd: The remote-js<dot>asd file
File, Lisp, remote-js/src/remote-js.lisp: The remote-js/src/remote-js<dot>lisp file

L
Lisp File, remote-js.asd: The remote-js<dot>asd file
Lisp File, remote-js/src/remote-js.lisp: The remote-js/src/remote-js<dot>lisp file

M
Module, remote-js/src: The remote-js/src module

R
remote-js.asd: The remote-js<dot>asd file
remote-js/src: The remote-js/src module
remote-js/src/remote-js.lisp: The remote-js/src/remote-js<dot>lisp file

Jump to:   F   L   M   R  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.2 Functions

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

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

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

E
eval: Exported generic functions
eval: Exported generic functions
eval: Exported generic functions

F
Function, make-buffered-context: Exported functions
Function, make-context: Exported functions
Function, server-for-context: Internal functions

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

H
html: Exported generic functions
html: Exported generic functions

J
js: Exported generic functions
js: Exported generic functions

M
make-buffered-context: Exported functions
make-context: Exported functions
Method, (setf context-buffer): Internal generic functions
Method, (setf context-callback): Internal generic functions
Method, (setf context-connected-p): Exported generic functions
Method, (setf context-handler): Internal generic functions
Method, (setf context-record-p): Internal generic functions
Method, (setf context-running-p): Exported generic functions
Method, (setf context-server): Exported generic functions
Method, context-address: Exported generic functions
Method, context-buffer: Internal generic functions
Method, context-callback: Internal generic functions
Method, context-connected-p: Exported generic functions
Method, context-handler: Internal generic functions
Method, context-port: Exported generic functions
Method, context-record-p: Internal generic functions
Method, context-running-p: Exported generic functions
Method, context-server: Exported generic functions
Method, context-timeout: Internal generic functions
Method, eval: Exported generic functions
Method, eval: Exported generic functions
Method, html: Exported generic functions
Method, js: Exported generic functions
Method, start: Exported generic functions
Method, stop: Exported generic functions

S
server-for-context: Internal functions
start: Exported generic functions
start: Exported generic functions
stop: Exported generic functions
stop: Exported generic functions

Jump to:   (  
C   E   F   G   H   J   M   S  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.3 Variables

Jump to:   %   +  
A   B   C   H   P   R   S   T  
Index Entry  Section

%
%callback: Exported classes

+
+connected-message+: Exported special variables
+default-callback+: Internal special variables
+script-template+: Internal special variables

A
address: Exported classes

B
buffer: Exported classes

C
callback: Exported classes
connected: Exported classes

H
handler: Exported classes

P
port: Exported classes

R
record: Exported classes
runningp: Exported classes

S
server: Exported classes
Slot, %callback: Exported classes
Slot, address: Exported classes
Slot, buffer: Exported classes
Slot, callback: Exported classes
Slot, connected: Exported classes
Slot, handler: Exported classes
Slot, port: Exported classes
Slot, record: Exported classes
Slot, runningp: Exported classes
Slot, server: Exported classes
Slot, timeout: Exported classes
Special Variable, +connected-message+: Exported special variables
Special Variable, +default-callback+: Internal special variables
Special Variable, +script-template+: Internal special variables

T
timeout: Exported classes

Jump to:   %   +  
A   B   C   H   P   R   S   T  

Previous: , Up: Indexes   [Contents][Index]

A.4 Data types

Jump to:   B   C   P   R   S  
Index Entry  Section

B
buffered-context: Exported classes

C
Class, buffered-context: Exported classes
Class, context: Exported classes
context: Exported classes

P
Package, remote-js: The remote-js package

R
remote-js: The remote-js system
remote-js: The remote-js package

S
System, remote-js: The remote-js system

Jump to:   B   C   P   R   S