Janet 1.39.1-e9c6678 Documentation
(Other Versions: 1.38.0 1.37.1 1.36.0 1.35.0 1.34.0 1.31.0 1.29.1 1.28.0 1.27.0 1.26.0 1.25.1 1.24.0 1.23.0 1.22.0 1.21.0 1.20.0 1.19.0 1.18.1 1.17.1 1.16.1 1.15.0 1.13.1 1.12.2 1.11.1 1.10.1 1.9.1 1.8.1 1.7.0 1.6.0 1.5.1 1.5.0 1.4.0 1.3.1 )

netrepl

msg path

A simple async networked repl (both client and server) with a remote debugger and the ability to repl into existing environments.

Specifying the Environment

Provide various ways to produce the environment to repl into.

  1. an environment factory function, called for each connection.
  2. an env (table value) - this means every connection will share the same environment
  3. default env, made via make-env with nice printing for each new connection.

NETREPL Protocol

Clients don't need to support steps 4. and 5. if they never send messages prefixed with 0xFF or 0xFE bytes. These bytes should not occur in normal Janet source code and are not even valid utf8.

Any message received by the client that begins with 0xFF should result in printing the message to a console, but not otherwise interrupt the flow of the protocol. This easily allows for partial results. A server should not send messages leading with 0xFF to the client unless the client is created with the :auto-flush connection setting.

Any message received by the client that begins with 0xFE will discard this first byte and continue processing as usual.

  1. server <- {connection settings, including client name} <- client
    1. If msg starts with 0xFF, parse message as (-> msg (slice 1) parse) and extract the :name key as the name. Other connection settings can be stored here.
    2. If msg does not start with 0xFF, the message is treated as the client name. Other options are considered nil.
  2. server -> {repl prompt (no newline)} -> client
  3. server <- {one chunk of input (msg)} <- client
  4. If (= (msg 0) 0xFF)
    1. (def result (-> msg (slice 1) parse eval protect))
    2. server -> result -> client
    3. goto 3.
  5. If (= (msg 0) 0xFE)
    1. Return msg as either:
      1. a keyword if the msg contains a command (e.g. :cancel)
      2. an array if the msg contains a command and arguments (e.g. @[:source "path/to/source"]
    2. goto 6b.
  6. Otherwise
    1. Send chunk to repl input stream
    2. Unless auto-flush is enabled, server -> {(dyn :out) and (dyn :err) (empty at first)} -> client
    3. goto 2.

Examples

Launch a networked REPL server on one machine and connect to it from another machine or process.

Server 

(import spork/netrepl)

(def some-def 10)

# Serve a repl into the current environment (@code`some-def` will be visible).
(netrepl/server "127.0.0.1" "9000" (fiber/getenv (fiber/current)))

Client 

(import spork/netrepl)

# Starts a nice terminal repl.
(netrepl/client "127.0.0.1" "9000" "bob")

Reference

netrepl/client netrepl/default-host netrepl/default-port netrepl/server netrepl/server-single

netrepl/client function source 
(client &opt host port name)

Connect to a repl server. The default host is "127.0.0.1" and the default port is "9365".
netrepl/default-host string source 
Default host to run server on and connect to.
netrepl/default-port string source 
Default port to run the net repl.
netrepl/server function source 
(server &opt host port env cleanup welcome-msg)

Start a repl server. The default host is "127.0.0.1" and the default port is "9365". Calling this will start a TCP server that exposes a repl into the given env. If no env is provided, a new env will be created per connection. If env is a function, that function will be invoked with the name and stream on each connection to generate an environment. `cleanup` is an optional function that will be called for each stream after closing if provided. `welcome-msg` is an optional string or function (welcome-msg client-name) to generate a message to print for the client on connection.
netrepl/server-single function source 
(server-single &opt host port env cleanup welcome-msg)

Short-hand for serving up a a repl that has a single environment table in it. `env` must be a proper env table, not a function as is possible in netrepl/server.
msg path