Functions

Summary

IDE side: Evaluate a Lisp form, call a function or set a variable, all on the client side.

Package

dbg

Signature

ide-eval-form-in-remote form &key encoded-result timeout connection output-stream force-simple => results

ide-funcall-in-remote func-and-args &key encoded-result timeout connection output-stream => results

ide-set-remote-symbol-value symbol value &key connection => value

Arguments

form

A Lisp form.

encoded-result

One of nil, t, :symbols or :not-cons.

timeout

A non-negative real or nil.

connection

An ide-remote-debugging or nil.

output-stream

An output stream.

force-simple

A boolean.

func-and-args

A list.

symbol

A symbol.

value

An object.

Values

results

The values returned by evaluating the form or calling the function, or the two values nil and :timeout-waiting-for-remote.

value

An object.

Description

The function ide-eval-form-in-remote evaluates form on the client side and returns the result(s). Evaluation is done by (eval form), unless either the evaluator has been eliminated (delivery with :keep-eval nil) or force-simple is non-nil, in which case a (very) simple evaluator is used. The simple evaluator recognizes symbols and conses, and returns all other objects. For a symbol, it returns the symbol-value (not recognizing symbol-macros). For a cons, if the car is one of quote, if or progn then it uses the Common Lisp semantics (using itself for recursion), otherwise it uses itself to evaluate all the elements of the cons's cdr and applies the car to those values.

The function ide-funcall-in-remote applies the car of func-and-args to the cdr of func-and-args and returns the result(s). Note that it does not do any evaluation of the elements of func-and-args.

The function ide-set-remote-symbol-value calls ide-funcall-in-remote to set the client side symbol to value as in:

(dbg:ide-funcall-in-remote '(set symbol
 value
)

                           :connection connection
)

encoded-result affects how the results are represented, where an "encoded" object is represented as a remote object handle and an "unencoded" object is represented as an normal object on the IDE side. Numbers, characters and strings are always unencoded, and all other objects except symbols and conses are always encoded. The value of encoded-result affects symbols and conses as follows:

nil (default)

The top-level conses are unencoded, which means that a result that is a list is returned as an unencoded list on the IDE side. Symbols that are in packages that exist on the IDE side are returned as unencoded symbols. Note that non top-level conses are encoded.

:symbols

The top-level conses are unencoded, but symbols and all other conses are encoded.

:not-cons

All conses, and symbols that are in packages that exist on the IDE side, are unencoded.

t

All conses and symbols are encoded.

timeout determines how long to wait for the result(s). If the client side does not return result(s) within timeout seconds, then ide-eval-form-in-remote and ide-funcall-in-remote return the two values nil and :timeout-waiting-for-remote.

connection can be used to specify which connection to use. If connection is nil, then ide-find-remote-debugging-connection is called to find a connection. See ide-find-remote-debugging-connection for more details about finding a connection.

output-stream must be an output stream, and defaults to the value of *standard-output*. During the evaluation or call on the client side, the variables *standard-output*, *error-output* and *trace-output* are bound to a stream that sends anything that is written to it back to the IDE side where is it written to output-stream. This is done using ide-attach-remote-output-stream to create a client side stream.

Notes

form, func-and-args, symbol and value are printed on the IDE side and read on the client side, and therefore must be objects that can be printed and read correctly. If the client is shaken (for example, delivered at level 2 or more), some symbols may not exist on the client side and will cause errors. If you want to ensure that specific symbols will work correctly with these functions, then use deliver-keep-symbols to keep them in the client.

Any remote object handle inside any of form, func-and-args, symbol or value is replaced by the object itself on the client side.

See also

ide-find-remote-debugging-connection
Remote debugging