VRS Manual

Running VRS

You can start the daemon with:

vrsd

In another terminal, run vrsctl to open a REPL. The daemon stays running between client connections. Services started by a client can continue after that client disconnects.

vrsd --init ./init.ll

# init.ll
(defn! hello () "Hello from VRS")
(spawn_srv! :greeting :interface '(hello))

Values

Values include numbers, strings, booleans, keywords, lists, and nil:

(list 42 "hello" true :ready nil)
# => (42 "hello" true :ready nil)

Keywords such as :ready are values used as labels or field names.

Strings

Strings use double quotes and escapes such as \n and \".

"""
  She said "hello".
  Then she left.
  """
# => "She said \"hello\".\nThen she left.\n"

Lists and records

Quote (') returns an expression without evaluating it. The list function builds a list from its arguments:

'(1 2 3)         # => (1 2 3)
(list 1 (+ 1 1)) # => (1 2)

get accesses elements by zero-based index. push returns a new list with an element appended:

(get '(1 2 3) 0)  # => 1
(first '(1 2 3))  # => 1
(push '(1 2 3) 4) # => (1 2 3 4)

(get '(:title "Notebook" :pages 80) :title)  # => "Notebook"
(get '(:title "Notebook" :pages 80) :author) # => nil

Bindings

A symbol such as title names a binding. def creates or replaces a binding in the current scope. set updates an existing binding.

(def title "First draft")
(set title "Second draft")
title # => "Second draft"

The symbol and keyword functions construct name values:

Constructing a symbol does not define a binding. Quote a symbol, as in 'title, to use its name as data instead of looking up its value.

let introduces local bindings.

(def amount 40)
(let ((amount 2) (original amount))
  (+ original amount)) # => 42
amount                # => 40

begin groups expressions, evaluates them in order, and returns the final value. It does not introduce a scope.

(begin
  (set amount (+ amount 1))
  (+ amount 1)) # => 42

(def (:point x y) '(:point 20 22))
(+ x y) # => 42

(def (:point x _) '(:point 20 22))
x # => 20

(def (:ok (a b)) '(:ok (20 22)))
(+ a b) # => 42

(def (:point x y) '(:size 20 22)) # Error: the :point tag does not match.

Functions

Define a named function with defn!. Lyric is expression-oriented: a function returns the value of its last expression.

(defn! double (x)
  (+ x x))
(double 21) # => 42

(defn! with_value (x f)
  (f x))
(with_value 21 double)          # => 42
(with_value 41 (fn (x) (+ x 1))) # => 42

(defn! make_counter (count)
  (fn ()
    (set count (+ count 1))
    count))
(def next (make_counter 0))
(next) # => 1
(next) # => 2

(map '(1 2 3) (fn (x) (+ x x))) # => (2 4 6)
(filter '(0 1 0 2) (fn (x) (not? (eq? x 0))))
# => (1 2)
(apply + '(10 20 12)) # => 42

Control flow

if evaluates a condition and only the selected branch:

(if (eq? 2 2) "equal" "different") # => "equal"
(if false "yes")                  # => nil

Falsy values are nil, false, 0, "", and the empty list. Truthy values include true, nonzero integers, and nonempty strings and lists.

These predicates return booleans:

cond selects the first clause with a true condition:

(cond ((eq? 3 1) :one)
      ((eq? 3 2) :two)
      (true :many)) # => :many

when! evaluates its body when the condition is true. and! and or! stop when their result is determined and return the last value evaluated.

(when! true (+ 20 22))       # => 42
(and! true "ready")         # => "ready"
(or! nil "Untitled")        # => "Untitled"

loop repeats its body.

(def result '(:ok (20 22)))
(match result
  ((:ok (a b)) (+ a b))
  ((:err reason) reason)
  (_ "unknown result")) # => 42

Errors

error raises an error and stops the current evaluation unless it is caught:

(error "Missing item")

try turns a raised error into an error value. A successful result passes through unchanged. Use err? or ok? to check the result:

(def result (try (error "Missing item")))
(err? result)   # => true
(try (+ 20 22)) # => 42

Code as data

Code can be stored and manipulated as data, then executed with eval.

(def code '(+ 20 22))
(first code) # => +
(eval code)  # => 42

(def base 20)
(def extra '(10 12))
(def code `(+ ,base ,@extra))
code        # => (+ 20 10 12)
(eval code) # => 42

(def item '(:title "Notebook" :pages 80))
(def code `(get ',item :title))
code # => (get '(:title "Notebook" :pages 80) :title)
(eval code) # => "Notebook"

(def code (read "(+ 20 22)"))
code        # => (+ 20 22)
(eval code) # => 42

Printing values

display returns a value's textual representation. pretty formats it as an s-expression, optionally using a target line width:

(display '(1 2 3)) # => "(1 2 3)"
(pretty '(:title "Notebook" :pages 80 :tags (work ideas)) 30)
# => "(:title \"Notebook\"\n :pages 80\n :tags (work ideas))"

Macros

A macro receives unevaluated expressions and returns code to run in the caller's scope. Define it with defmacro and add ! to its name when calling it.

(defmacro unless (condition & body)
  `(when! (not? ,condition) ,@body))

(unless! false (+ 20 22)) # => 42

& body collects the remaining expressions. Unlike a function, this macro can decide whether those expressions are evaluated.

macroexpand_1 shows one expansion. macroexpand continues while the result is another outer macro call.

(macroexpand_1 '(unless! false (+ 20 22)))
# => (when! (not? false) (+ 20 22))
(macroexpand '(unless! false (+ 20 22)))
# => (if (not? false) (begin (+ 20 22)) nil)

Macros expand when execution reaches the call, including inside functions and loops. Redefining a macro changes subsequent calls, including those in existing functions. Its body can use ordinary functions; the code it returns runs in the caller's scope.

(defmacro or_else (value fallback)
  (def temp (gensym "temp"))
  `(let ((,temp ,value))
     (if ,temp ,temp ,fallback)))

(let ((temp 42))
  (or_else! false temp)) # => 42

Evaluation and scope

When evaluating code stored as data, the environment determines which bindings its symbols refer to.

eval_global is useful when a helper must define something that remains accessible outside its own local scope.

For example, a local binding changes what eval sees, while eval_global still sees the top-level binding:

(def x 10)
(let ((x 42))
  (list :eval (eval 'x)
        :eval_global (eval_global 'x)))
# => (:eval 42 :eval_global 10)

A macro body uses the lexical environment where the macro was defined. eval_callsite instead evaluates an expression in the lexical environment of the call site where the macro is being expanded:

(defmacro inspect_here (expression)
  `(quote ,(eval expression)))
(defmacro inspect_at_call (expression)
  `(quote ,(eval_callsite expression)))

(let ((x 42))
  (list :inspect_here (inspect_here! x)
        :inspect_at_call (inspect_at_call! x)))
# => (:inspect_here 10 :inspect_at_call 42)

Most macros return code that will use the caller's bindings when executed; they do not need eval_callsite for that. Use it when the macro must inspect a caller's value during expansion to decide what code to generate. Calling it outside an active macro expansion raises an error.

A def evaluated through eval_callsite creates a binding in that call-site environment. Its visibility follows that scope; eval_global targets the process's top level.

(defmacro dispatch (message name)
  (def function (eval_callsite name))
  (def args (map (get (meta function) :args)
                (fn (arg) (get arg :name))))
  `(match ,message
     ((,(keyword name) ,@args) (,name ,@args))))

(let ()
  (defn! greet (name) (str "Hello, " name))
  (dispatch! '(:greet "Ada") greet)) # => "Hello, Ada"

(match '(:greet "Ada")
  ((:greet name) (greet name)))

Help and introspection

A function's leading string is its docstring. help returns that documentation; meta returns metadata, including argument names.

(defn! double (x)
  "Add a number to itself."
  (+ x x))
(help double)            # => "Add a number to itself."
(get (meta double) :args) # => ((:name x))

with_meta returns a function with supplied metadata:

(def labelled (with_meta double '(:category :math)))
(get (meta labelled) :category) # => :math
(labelled 21)                  # => 42

These queries describe the running environment. The runtime sections explain services and entities in more detail.

Processes

Each process has its own namespace of bindings, an ID, and a mailbox. A spawned process starts with the bindings available to its function. Expressions within a process run sequentially; other processes can run concurrently.

spawn starts a process from a function and returns its ID. The child can continue running independently of its parent:

(def worker (spawn (fn () (sleep 60))))
(kill worker)

Message passing

send delivers a value to another process's mailbox. recv waits for a message:

(def parent (self))
(spawn (fn () (send parent '(:greeting "hello"))))
(match (recv)
  ((:greeting message) message)) # => "hello"

recv can take a quoted pattern to wait for a matching message, leaving other messages in the mailbox. ls_msgs lists queued messages without consuming them:

(send (self) '(:status "busy"))
(send (self) '(:greeting "hello"))
(recv '(:greeting _)) # => (:greeting "hello")
(ls_msgs)            # => ((:status "busy"))

Services

A service is a named process with an interface of exported functions. Those functions run in the service process and can access its state across calls.

Define the state and functions, then use spawn_srv! to start the service. :interface lists the functions to export.

(def count 0)
(defn! add_count (amount)
  (set count (+ count amount)))
(defn! get_count () count)
(spawn_srv! :counter :interface '(add_count get_count))

(bind_srv :counter)
(add_count 2)
(get_count) # => 2

(info_srv :counter :interface)
# => ((:add_count amount) (:get_count))

(call_timeout 30)

Pubsub

VRS has built-in pubsub. A topic connects publishers to subscribers. Use subscribe to register the current process, and publish to send a value:

(subscribe :clock)
(publish :clock '(:tick 1))
(recv) # => (:topic_updated :clock (:tick 1))

Published values arrive in subscribers' mailboxes as :topic_updated messages. Publishing does not wait for subscribers to handle them. Events reach subscribers on connected nodes.

(def latest nil)
(defn! remember (value) (set latest value))
(defn! last_event () latest)
(spawn_srv! :latest_event
  :interface '(last_event)
  :topics '((:clock remember)))
(publish :clock '(:tick 2))

Interactive functions and entities

An interactive declaration records the types of values a function accepts as arguments. Here, note_title accepts a value tagged :note:

(defn! note_title (note)
  (interactive :note)
  (get note :title))

An entity is a value identified by a leading type tag. Given such a value, interactive_functions finds bound functions whose first argument declares that type:

(def note '(:note :title "Notebook"))
(interactive_functions note) # => (note_title)
(note_title note)            # => "Notebook"

The query returns function names. Each can be called with the original value.

(defn! get_notes ()
  '((:note :title "Notebook") (:note :title "Reading")))
(register_entity_source :note 'get_notes)
(entity_sources :note) # => (get_notes)
(entities :note) # Calls get_notes.
# => ((:note :title "Notebook") (:note :title "Reading"))

Files

fdump writes a Lyric value to a file. fread reads it back:

(fdump "notes.ll" '((:note :title "Notebook")))
(fread "notes.ll") # => ((:note :title "Notebook"))

fdump replaces the file's contents. Paths are resolved on the device running the code, including when it is evaluated from an editor on another device.

(run "./service.ll")

External programs

Use exec to run external programs:

(def result (exec "printf" "one\ntwo\n"))
result # => (:exit 0 :stdout "one\ntwo\n" :stderr "")

Decode the output with decode, which supports :lines, :json, and :tsv:

(decode :lines (get result :stdout)) # => ("one" "two")

Pass :stdin TEXT to supply input to the program:

(exec "cat" :stdin "hello") # => (:exit 0 :stdout "hello" :stderr "")

Multiple devices

Each running vrsd is a node. Nodes can be connected to discover services, call functions, and deliver pubsub events across devices.

vrsd --node home

(configure :nodes '("ssh://home"))

(remote! "home" (node_name)) # => "home"

(remote! "home"
  (defn! host_name () (node_name))
  (spawn_srv! :host :interface '(host_name)))
(bind_srv :host)
(host_name) # => "home"

vrsd --node one --socket /tmp/vrs-one.sock --node-port 8873

vrsd --node two --socket /tmp/vrs-two.sock --node-port 8874

vrsctl --socket /tmp/vrs-one.sock

(configure :nodes '("tcp://127.0.0.1:8874"))

Advanced runtime operations

For most services, spawn_srv! and bind_srv are sufficient to start a service and call its functions. For direct control over registration and request handling, you can use the same process registration and message-passing operations they build on: register names a process, send delivers a message, and call sends a request and waits for a reply.

(defn! greet (name) (str "Hello, " name))
(srv! :greeting :interface '(greet))

(call (find_srv :counter) '(:get_count))

(wait_srv :counter :timeout 10)
(bind_srv :counter)

REPL

Run vrsctl without arguments for a REPL:

vrsctl

Each REPL instance runs in a process with its own namespace. Definitions and service bindings remain available for that session.

Shell scripting

Use -c to evaluate an expression and print its result:

vrsctl -c '(+ 20 22)' # => 42

A file or standard input can contain several expressions. The result of the final expression is printed:

vrsctl ./service.ll
printf '(+ 20 22)\n' | vrsctl

Use --bind to bind a service before evaluating code, or --node to evaluate on a peered node:

vrsctl --bind counter -c '(get_count)'
vrsctl --node home -c '(node_name)'

vrsctl --raw -c '(str "Hello, " "VRS")'
# Hello, VRS

vrsctl --format pretty --width 30 -c "'(:title \"Notebook\" :pages 80 :tags (work ideas))"
# (:title "Notebook"
#  :pages 80
#  :tags (work ideas))

vrsctl --subscribe clock --follow

Setup

Load vrs-mode in Emacs, using the path to your checkout:

(add-to-list 'load-path "/path/to/vrs/emacs")
(require 'vrs-mode)

;; If vrsctl is not on Emacs's executable path:
;; (setq vrs-vrsctl-command "/path/to/vrsctl")

The editor session

The editor uses vrsctl to keep a process running for evaluations. Its definitions and service bindings are shared by buffers using the same vrs-vrsctl-command. Run M-x vrs-reset-session to start a fresh process with a new namespace.

Evaluate expressions and retain values

Enter these expressions in a file:

(def note '(:note :title "Read paper"))
(get note :title)

Press C-c C-c to evaluate the buffer. The result buffer shows Read paper.

To evaluate only (get note :title), place the cursor after its closing parenthesis and press C-c C-e. The result is displayed in the same way.

With the prefix C-u C-c C-e, the result replaces the expression in the source code:

# Before: (get note :title)
"Read paper"

An active region can be evaluated with C-c C-r, or replaced by its result with C-u C-c C-r. Retained lists and symbols are quoted so they remain data when the surrounding program is evaluated.

Introspecting the running environment

As a connected client, the editor can query registered services and function metadata. C-c C-s browses services and their exported functions, binding a selected service in the editor session. C-c C-b browses service functions already bound in that session.

Choosing a function inserts a call with argument names as placeholders. Use a C-u prefix to choose values for its arguments instead.

The earlier interactive metadata also supports starting from a value. Evaluate this definition:

(defn! note_title (note)
  (interactive :note)
  (get note :title))

Then put the cursor after this entire expression and press C-c C-a:

'(:note :title "Read paper")

Choose note_title. The editor replaces the value with a call:

(note_title '(:note :title "Read paper"))

This constructs code to inspect, edit, or evaluate. To choose and execute an action on a value instead, use M-x vrs-execute-action.

Commands