sly-1.0.43/doc/sly.texi

3 @setfilename sly.info
13 * SLY: (sly).    Common-Lisp IDE
253 @code{sly-mode}, which complements the standard major-mode
254 @code{lisp-mode} for editing Lisp source files.  @code{sly-mode}
289 @SLY{}'s @uref{https://github.com/joaotavora/sly/blob/master/NEWS.md,,NEWS.md}
362 choose @kbd{sly} and have it be downloaded and installed
370 git clone https://github.com/joaotavora/sly.git
375 @uref{https://github.com/joaotavora/sly/blob/master/CONTRIBUTING.md,,CONTRIBUTING.md} file first.
393 After evaluating this, you should be able to execute @kbd{M-x sly} and
400 (add-to-list 'load-path "~/dir/to/cloned/sly")
401 (require 'sly-autoloads)
411 started via @kbd{M-x sly}. The ``inferior'' Lisp process thus started
413 socket connection is established between Emacs and Lisp. Finally
417 The second alternative uses @kbd{M-x sly-connect}. This assumes that
419 listening on a given port. @kbd{M-x sly-connect} prompts the user for
420 these values, and upon connection the @REPL{} is established.
450 following snippet @kbd{M-h} is added to @code{sly-prefix-map} thus
452 the @code{sly-documentation-lookup} command.
455 (eval-after-load 'sly
456   `(define-key sly-prefix-map (kbd "M-h") 'sly-documentation-lookup))
462 By default, the command @kbd{M-x sly} starts the program specified
464 (@pxref{Defcustom variables}).  However, if you invoke @kbd{M-x sly}
465 with a @emph{prefix argument}, meaning you type @kbd{C-u M-x sly} then
470 the @code{sly-lisp-implementations} variable in your initialization file
474 (setq sly-lisp-implementations
480 @kbd{M-- M-x sly}, you can select a program from that list. When
482 @code{sly-default-lisp}, or the first item of the list will be used.
498 the coding system for the connection.  (@pxref{sly-net-coding-system})x
505 default, @code{sly-init-command} is used.  An example is shown in
509 the connection is established. (See also @ref{sly-connected-hook}.)
532 When you start @SLY{} with @kbd{M-x sly} (@pxref{Basic setup}) you are
535 multiple REPL sessions with @code{sly-mrepl-new}; copy objects from most
556 textual.  In @SLY{}, @code{sly-apropos} will use the @code{CL-PPCRE}
564 @kbd{C-c C-d C-z} (the shortcut for @kbd{M-x sly-apropos-all}) and
565 then type in ``sly.*flex'' at the prompt, followed by @kbd{enter}
606 @code{*sly-mrepl ...} buffer or typing @kbd{C-c C-z}. In the REPL, let’s try to
612 the @code{*sly-completions*} window, since  we wanted to test
734 called @code{*sly-stickers-replay*} which pops up.  There we can see the
756 @code{sly-editing-mode}, a minor-mode used in conjunction with Emacs's
785 @kbditem{C-x C-e, sly-eval-last-expression}
790 @kbditem{C-M-x, sly-eval-defun}
805 @kbditem{C-c :, sly-interactive-eval}
808 @kbditem{C-c C-r, sly-eval-region}
811 @kbditem{C-c C-p, sly-pprint-eval-last-expression}
815 @kbditem{C-c E, sly-edit-value}
820 @kbditem{C-c C-u, sly-undefine-function}
839 @kbditem{C-c C-c, sly-compile-defun}
854 @kbditem{C-c C-k, sly-compile-and-load-file}
867 @kbditem{C-c M-k, sly-compile-file}
870 @kbditem{C-c C-l, sly-load-file}
873 @cmditem{sly-compile-region}
885 @kbditem{M-n, sly-next-note}
888 @kbditem{M-p, sly-previous-note}
891 @kbditem{C-c M-c, sly-remove-notes}
911 @cmditem{sly-arglist NAME}
914 @cmditem{sly-autodoc-mode}
917 @cmditem{sly-autodoc-manually}
918 Like sly-autodoc, but when called twice,
919 or after sly-autodoc was already automatically called,
923 If @code{sly-autodoc-use-multiline-p} is set to non-nil,
954 just override the Elisp symbol's @code{sly-common-lisp-indent-function}
971 You can use @kbd{M-x sly-update-indentation} to force all symbols to
979 skipped for the current Lisp connection.
987 @kbditem{C-c C-m, sly-expand-1}
993 @cmditem{sly-macroexpand-1}
997 @kbditem{C-c M-m, sly-macroexpand-all}
1000 @cmditem{sly-compiler-macroexpand-1}
1003 @cmditem{sly-compiler-macroexpand}
1006 @cmditem{sly-format-string-expand}
1013 Within a sly macroexpansion buffer some extra commands are provided
1018 @kbditem{C-c C-m, sly-macroexpand-1-inplace}
1019 Just like sly-macroexpand-1 but the original form is replaced with
1022 @c @anchor{sly-macroexpand-1-inplace}
1023 @kbditem{g, sly-macroexpand-1-inplace}
1027 @kbditem{q, sly-temp-buffer-quit}
1030 @kbditem{C-_, sly-macroexpand-undo}
1043 @code{*sly-...*}, these commands and functionality will be available
1063 familiar @kbd{M-.} binding for @kbd{sly-edit-definition}.
1075 @kbditem{M-., sly-edit-definition}
1080 @itemx M-x sly-pop-find-definition-stack
1082 @findex sly-pop-find-definition-stack
1086 @kbditem{C-x 4 ., sly-edit-definition-other-window}
1087 Like @code{sly-edit-definition} but switches to the other window to
1090 @kbditem{C-x 5 ., sly-edit-definition-other-frame}
1091 Like @code{sly-edit-definition} but opens another frame to edit the
1107 results in separate window displaying a special @code{*sly-xref*}
1128 transient @code{*sly-xref*} buffer in a different window.
1131 @kbditem{M-?, sly-edit-uses}
1135 @kbditem{C-c C-w C-c, sly-who-calls}
1138 @kbditem{C-c C-w C-w, sly-calls-who}
1141 @kbditem{C-c C-w C-r, sly-who-references}
1144 @kbditem{C-c C-w C-b, sly-who-binds}
1147 @kbditem{C-c C-w C-s, sly-who-sets}
1150 @kbditem{C-c C-w C-m, sly-who-macroexpands}
1153 @cmditem{sly-who-specializes}
1165 @kbditem{C-c <, sly-list-callers}
1168 @kbditem{C-c >, sly-list-callees}
1173 In the resulting @code{*sly-xref*} buffer, these commands are
1177 @kbditem{RET, sly-show-xref}
1179 the @code{*sly-xref} buffer.
1181 @kbditem{Space, sly-goto-xref}
1183 the @code{*sly-xref} buffer.
1185 @kbditem{C-c C-c, sly-recompile-xref}
1187 @code{sly-compile-defun}.
1189 @kbditem{C-c C-k, sly-recompile-all-xrefs}
1191 @code{sly-compile-defun}.
1207 @pxref{sly-complete-symbol-function}, which can be set to two values,
1211 @item @code{sly-flex-completions}
1240 @item @code{sly-simple-completions}
1249 when the @code{*sly-completions*} buffer pops up, some keybindings are
1255 @itemx M-x sly-next-completion
1257 @findex sly-next-completion
1262 @itemx M-x sly-prev-completion
1264 @findex sly-prev-completion
1269 @itemx M-x sly-choose-completion
1271 @findex sly-choose-completion
1277 @code{*sly-completions*} buffer is closed.
1292 @c with @kbd{sly-button-forward} and @kbd{sly-button-backward}
1325 like @code{sly-pprint-eval-last-expression}.
1347 @cmditem{sly-info}
1351 @kbditem{C-c C-d C-d, sly-describe-symbol}
1354 @kbditem{C-c C-d C-f, sly-describe-function}
1357 @kbditem{C-c C-d C-a, sly-apropos}
1363 @kbditem{C-c C-d C-z, sly-apropos-all}
1364 Like @code{sly-apropos} but also includes internal symbols by default.
1366 @kbditem{C-c C-d C-p, sly-apropos-package}
1371 @kbditem{C-c C-d C-h, sly-hyperspec-lookup}
1392 time. The @kbd{M-x sly} command, when invoked with a prefix
1400 @code{*sly-<something> for <connection>*}, where @code{connection} is
1401 the name of the connection.
1403 Each Lisp connection has its own main @acronym{REPL} buffer
1405 in that buffer are sent to the associated connection. Other buffers
1412 Commands executed in other places, such as @code{sly-mode} source
1413 buffers, always use the ``default'' connection. Usually this is the
1414 most recently established connection, but this can be reassigned via
1415 the ``connection list'' buffer:
1418 @kbditem{C-c C-x c, sly-list-connections}
1421 @kbditem{C-c C-x n, sly-next-connection}
1422 Switch to the next Lisp connection by cycling through all connections.
1424 @kbditem{C-c C-x p, sly-prev-connection}
1425 Switch to the previous Lisp connection by cycling through all connections.
1429 The buffer displayed by @code{sly-list-connections} gives a one-line
1430 summary of each connection. The summary shows the connection's serial
1432 Lisp process. The current ``default'' connection is indicated with an
1435 The commands available in the connection-list buffer are:
1438 @kbditem{RET, sly-goto-connection}
1439 Pop to the @acronym{REPL} buffer of the connection at point.
1441 @kbditem{d, sly-connection-list-make-default}
1442 Make the connection at point the ``default'' connection. It will then
1443 be used for commands in @code{sly-mode} source buffers.
1445 @kbditem{g, sly-update-connection-list}
1446 Update the connection list in the buffer.
1448 @kbditem{q, sly-temp-buffer-quit}
1449 Quit the connection list (kill buffer, restore window configuration).
1451 @kbditem{R, sly-restart-connection-at-point}
1452 Restart the Lisp process for the connection at point.
1454 @cmditem{sly-connect}
1458 @cmditem{sly-disconnect}
1461 @cmditem{sly-abort-connection}
1471 @kbditem{C-c M-d, sly-disassemble-symbol}
1474 @kbditem{C-c C-t, sly-toggle-trace-fdefinition}
1479 @cmditem{sly-untrace-all}
1488 @kbditem{C-c C-b, sly-interrupt}
1491 @cmditem{sly-restart-inferior-lisp}
1494 @kbditem{C-c ~, sly-mrepl-sync}
1498 @cmditem{sly-cd}
1502 @cmditem{sly-pwd}
1527 Temporary buffers containing Lisp symbols use @code{sly-mode} in
1533 @code{sly-description-autofocus}. If @code{nil} (the default),
1546 You can see a listing of the threads for the current connection with
1547 the command @code{M-x sly-list-threads}, or @code{C-c C-x t}. This
1548 pops open a @code{*sly-threads*} buffer, where some keybindings to
1600 Multiple @REPL{}s are possible in the same Lisp connection. This is
1610 common task. One way to do it is to find the @code{*sly-mrepl...*}
1615 @kbditem{C-c C-z, sly-mrepl}
1618 @cmditem{sly-mrepl-new}
1621 @kbditem{C-c ~, sly-mrepl-sync}
1641 @kbditem{RET, sly-mrepl-return}
1645 @kbditem{TAB, sly-mrepl-indent-and-complete-symbol}
1652 @kbditem{M-p, sly-mrepl-previous-input-or-button}
1658 @kbditem{M-n, sly-mrepl-next-input-or-button}
1674 @kbditem{C-c C-b, sly-interrupt}
1680 @kbditem{C-M-p, sly-button-backward}
1684 @kbditem{C-M-n, sly-button-forward}
1688 @kbditem{C-c C-o, sly-mrepl-clear-recent-output}
1692 @kbditem{C-c M-o, sly-mrepl-clear-repl}
1753 redirection should only take place upon @code{M-x sly} invocations.
1755 @code{M-x sly-connect}, meaning output may be diverted from wherever
1767 @kbd{sly-mrepl-new}) don’t receive any redirected output.
1776 socket should only be established upon @code{M-x sly} invocations.  When
1778 sly-connect}.  When @code{NIL} usual protocol messages are used for
1784 sly-connect}, the default @code{:started-from-emacs} value should ensure
1897 @kbditem{C-c I, sly-inspect}
1906 @kbditem{RET, sly-inspector-operate-on-point}
1910 @kbditem{D, sly-inspector-describe-inspectee}
1913 @kbditem{e, sly-inspector-eval}
1917 @kbditem{v, sly-inspector-toggle-verbose}
1921 @kbditem{l, sly-inspector-pop}
1924 @kbditem{n, sly-inspector-next}
1927 @kbditem{g, sly-inspector-reinspect}
1930 @kbditem{h, sly-inspector-history}
1933 @kbditem{q, sly-inspector-quit}
1936 @kbditem{>, sly-inspector-fetch-all}
1939 @kbditem{M-RET, sly-mrepl-copy-part-to-repl}
1976 @kbditem{t, sly-db-toggle-details}
1979 @kbditem{v, sly-db-show-frame-source}
1983 @kbditem{e, sly-db-eval-in-frame}
1987 @kbditem{d, sly-db-pprint-eval-in-frame}
1991 @kbditem{D, sly-db-disassemble}
1995 @kbditem{i, sly-db-inspect-in-frame}
1998 @kbditem{C-c C-c, sly-db-recompile-frame-source}
2007 @kbditem{a, sly-db-abort}
2010 @anchor{sly-db-quit}
2011 @kbditem{q, sly-db-quit}
2016 @kbditem{c, sly-db-continue}
2019 @kbditem{0 ... 9, sly-db-invoke-restart-n}
2030 @kbditempair{n,p,sly-db-down,sly-db-up}
2033 @kbditempair{M-n, M-p, sly-db-details-down, sly-db-details-up}
2039 @kbditem{>, sly-db-end-of-backtrace}
2042 @kbditem{<, sly-db-beginning-of-backtrace}
2051 @kbditem{r, sly-db-restart-frame}
2056 @kbditem{R, sly-db-return-from-frame}
2061 @kbditem{B, sly-db-break-with-default-debugger}
2065 @kbditem{C, sly-db-inspect-condition}
2068 @kbditem{:, sly-interactive-eval}
2070 @kbditem{A, sly-db-break-with-system-debugger}
2078 The @SLY{} Trace Dialog, in package @code{sly-trace-dialog}, is a
2093 a @emph{Trace} menu in the menu-bar of any @code{sly-mode} buffer and
2097 @kbditem{C-c C-t, sly-trace-dialog-toggle-trace}
2108 @kbditem{C-c T, sly-trace-dialog}
2110 current connection (@pxref{Multiple connections}).
2151 @kbditem{g, sly-trace-dialog-fetch-status}
2153 @kbditem{G, sly-trace-dialog-fetch-traces}
2156 @kbditem{C-k, sly-trace-dialog-clear-fetched-traces}
2164 (@code{sly-trace-dialog-copy-down-to-repl}) returns them to the REPL
2170 @code{sly-trace-dialog-hide-details-mode} hides arguments and return
2172 @code{sly-trace-dialog-autofollow-mode} will automatically
2179 @SLY{} Stickers, implemented as the @code{sly-stickers} contrib
2192 sly-stickers-dwim} places a sticker on any Lisp form. Stickers can
2199 familiar @kbd{C-c C-c} (@code{M-x sly-compile-defun}) or @kbd{C-c C-k}
2200 (@code{M-x sly-compile-file}) commands. An armed sticker changes color from
2214 (or @code{M-x sly-stickers-replay}) interactively walks the user
2216 created @code{*sly-stickers-replay*} buffer, type @kbd{h} for a list
2224 sly-stickers-toggle-break-on-stickers}.  Whenever a sticker-covered
2235 @kbd{C-c C-s S} (@code{M-x sly-stickers-fetch}) populates the sticker
2246 same @code{sly-stickers-dwim} keybinding, by placing the cursor at the
2248 to @code{sly-stickers-dwim} increase its scope, so @kbd{C-u C-c C-s
2261 n} (@code{sly-stickers-prev-sticker} and
2262 @code{sly-stickers-next-sticker}).
2345 (eval-after-load 'sly
2346   `(define-key sly-prefix-map (kbd "M-h") 'sly-documentation-lookup))
2355 (eval-after-load 'sly-mrepl
2356    `(define-key sly-mrepl-mode-map (kbd "C-c C-k")
2357                 'sly-mrepl-clear-recent-output))
2371 @item sly-doc-map
2376 @item sly-who-map
2382 @item sly-selector-map
2387 @item sly-mode-map
2391 @item sly-editing-mode-map
2395 @item sly-popup-buffer-mode-map
2400 @item sly-apropos-mode-map
2405 @item sly-xref-mode-map
2411 @item sly-macroexpansion-minor-mode-map
2416 @item sly-db-mode-map
2421 @item sly-thread-control-mode-map
2426 @item sly-connection-list-mode-map
2431 @item sly-inspector-mode-map
2436 @item sly-mrepl-mode-map
2441 @item sly-trace-dialog-mode-map
2453 @code{customize} system, just use @kbd{M-x customize-group sly
2459 @item sly-truncate-lines
2465 @anchor{sly-complete-symbol-function}
2466 @item sly-complete-symbol-function
2468 styles are available: @code{sly-simple-completions}
2469 and @code{sly-flex-completions} (@pxref{Completion}).
2471 @item sly-filename-translations
2478 @anchor{sly-net-coding-system}
2484 @item sly-net-coding-system
2489 (setq sly-net-coding-system 'utf-8-unix)
2498 @item sly-keep-buffers-on-connection-close
2500 that should be kept around when a connection closes.  For example, if
2512 @item sly-mode-hook
2513 This hook is run each time a buffer enters @code{sly-mode}. It is
2515 buffers. An example use is to enable @code{sly-autodoc-mode}
2518 @anchor{sly-connected-hook}
2519 @item sly-connected-hook
2520 This hook is run when @SLY{} establishes a connection to a Lisp
2523 @item sly-db-hook
2526 is to add @code{sly-db-print-condition} to this hook, which makes all
2620 (@pxref{sly-db-quit}) in @SLY-DB{}. For @SLY{} evaluation requests this
2626 (setf slynk:*sly-db-quit-restart* 'sb-thread:terminate-thread)
2639 (push '(*print-pretty* . t) slynk:*sly-db-printer-bindings*).
2756 easily run the Emacs side (@code{sly.el} and friends) on one machine
2773 having @code{M-x sly} start a Lisp that is subsidiary to a particular
2781 (push #p"/path/to/sly/slynk/" ASDF:*CENTRAL-REGISTRY*)
2795 This creates a ``one-connection-only'' server on port 4005 using the
2817 Finally, since section we're going to be tunneling our connection via
2822 not use an extra connection for output, which it will do by default.
2850 Finally we start @SLY{} with @code{sly-connect} instead of the usual
2851 @code{sly}:
2854 M-x sly-connect RET RET
2867 things like @code{sly-compile-and-load-file} (@kbd{C-c C-k}) and
2868 @code{sly-edit-definition} (@kbd{M-.}) to work correctly we need to
2876 always feasible. Fortunately we have an ssh connection and Emacs'
2884 ``remote'' and we login as the user ``user'' we can use @code{sly-tramp}
2888 (add-to-list 'sly-filename-translations
2889              (sly-create-filename-translator
2914 * (save-lisp-and-die "sbcl.core-for-sly")
2921 (setq sly-lisp-implementations '((sbcl ("sbcl" "--core"
2922       "sbcl.core-for-sly"))))
2932 * (load ".../sly/slynk-loader.lisp")
2941 (setq sly-lisp-implementations
2955 (add-hook 'sly-mode-hook
2957             (unless (sly-connected-p)
2958               (save-excursion (sly)))))
3008 variable @code{sly-enable-evaluate-in-emacs} to non-nil.  As the name
3059 different code repositories. The @code{sly-macrostep} contrib
3060 (@uref{https://github.com/joaotavora/sly-macrostep}) is one such
3063 A special @code{sly-fancy} contrib package is the only one loaded by
3067 your setup a bit.  Generally, you set the variable @code{sly-contribs}
3069 setup to load only the @code{sly-scratch} and @code{sly-mrepl}
3074 (add-to-list 'load-path "~/dir/to/cloned/sly")
3075 (require 'sly-autoloads)
3079 (setq sly-contribs '(sly-scratch sly-mrepl))
3088 We recommend that you setup the @code{sly-contribs}
3089 variable @emph{before} starting @SLY{} via @kbd{M-x sly}, but if you
3091 new @code{sly-contribs} variable to another value and call @code{M-x
3092 sly-setup} or @code{M-x sly-enable-contrib}. Note this though:
3099 If you have more than one @SLY{} connection currently active, you must
3100 manually repeat the @code{sly-setup} step for each of them.
3106 wish to unload. So, to remove @code{sly-mrepl}, you must call
3107 @code{sly-mrepl-unload}. Because the unload function will only, if
3124 The package @code{sly-tramp} provides some functions to set up
3131 @anchor{sly-scratch}
3132 The @SLY{} scratch buffer, in contrib package @code{sly-scratch},
3134 If @code{sly-scratch-file} is set, it is used to back the scratch
3140 @kbditem{C-j, sly-eval-print-last-expression}
3144 @cmditem{sly-scratch}
3145 Create a @file{*sly-scratch*} buffer. In this
3165 Many people on the @code{sly-devel} mailing list have made non-code