blob: 7b7e6b1a5c448611dd715f75f3dc557a285f2c56 [file] [log] [blame]
Bram Moolenaar25c9c682019-05-05 18:13:34 +02001*if_mzsch.txt* For Vim version 8.1. Last change: 2019 May 05
Bram Moolenaar325b7a22004-07-05 15:58:32 +00002
3
4 VIM REFERENCE MANUAL by Sergey Khorev
5
6
7The MzScheme Interface to Vim *mzscheme* *MzScheme*
8
91. Commands |mzscheme-commands|
102. Examples |mzscheme-examples|
113. Threads |mzscheme-threads|
Bram Moolenaar7e506b62010-01-19 15:55:06 +0100124. Vim access from MzScheme |mzscheme-vim|
135. mzeval() Vim function |mzscheme-mzeval|
Bram Moolenaar75676462013-01-30 14:55:42 +0100146. Using Function references |mzscheme-funcref|
157. Dynamic loading |mzscheme-dynamic|
Bram Moolenaar4e640bd2016-01-16 16:20:38 +0100168. MzScheme setup |mzscheme-setup|
Bram Moolenaar325b7a22004-07-05 15:58:32 +000017
Bram Moolenaar25c9c682019-05-05 18:13:34 +020018{only available when Vim was compiled with the |+mzscheme| feature}
Bram Moolenaar325b7a22004-07-05 15:58:32 +000019
20Based on the work of Brent Fulgham.
Bram Moolenaar281bdce2005-01-25 21:53:18 +000021Dynamic loading added by Sergey Khorev
Bram Moolenaar325b7a22004-07-05 15:58:32 +000022
Bram Moolenaar75676462013-01-30 14:55:42 +010023MzScheme and PLT Scheme names have been rebranded as Racket. For more
24information please check http://racket-lang.org
Bram Moolenaar325b7a22004-07-05 15:58:32 +000025
Bram Moolenaar75676462013-01-30 14:55:42 +010026Futures and places of Racket version 5.x up to and including 5.3.1 do not
27work correctly with processes created by Vim.
28The simplest solution is to build Racket on your own with these features
29disabled: >
30 ./configure --disable-futures --disable-places --prefix=your-install-prefix
31
32To speed up the process, you might also want to use --disable-gracket and
33--disable-docs
Bram Moolenaar9964e462007-05-05 17:54:07 +000034
Bram Moolenaar325b7a22004-07-05 15:58:32 +000035==============================================================================
361. Commands *mzscheme-commands*
37
38 *:mzscheme* *:mz*
39:[range]mz[scheme] {stmt}
Bram Moolenaar25c9c682019-05-05 18:13:34 +020040 Execute MzScheme statement {stmt}.
Bram Moolenaar325b7a22004-07-05 15:58:32 +000041
42:[range]mz[scheme] << {endmarker}
43{script}
44{endmarker}
45 Execute inlined MzScheme script {script}.
46 Note: This command doesn't work if the MzScheme
47 feature wasn't compiled in. To avoid errors, see
48 |script-here|.
49
50 *:mzfile* *:mzf*
Bram Moolenaar25c9c682019-05-05 18:13:34 +020051:[range]mzf[ile] {file} Execute the MzScheme script in {file}.
Bram Moolenaar325b7a22004-07-05 15:58:32 +000052
53All of these commands do essentially the same thing - they execute a piece of
54MzScheme code, with the "current range" set to the given line
55range.
56
57In the case of :mzscheme, the code to execute is in the command-line.
58In the case of :mzfile, the code to execute is the contents of the given file.
59
Bram Moolenaar325b7a22004-07-05 15:58:32 +000060MzScheme interface defines exception exn:vim, derived from exn.
61It is raised for various Vim errors.
62
63During compilation, the MzScheme interface will remember the current MzScheme
64collection path. If you want to specify additional paths use the
65'current-library-collection-paths' parameter. E.g., to cons the user-local
66MzScheme collection path: >
67 :mz << EOF
68 (current-library-collection-paths
69 (cons
70 (build-path (find-system-path 'addon-dir) (version) "collects")
71 (current-library-collection-paths)))
72 EOF
73<
74
75All functionality is provided through module vimext.
76
77The exn:vim is available without explicit import.
78
79To avoid clashes with MzScheme, consider using prefix when requiring module,
80e.g.: >
81 :mzscheme (require (prefix vim- vimext))
82<
Bram Moolenaar9e70cf12009-05-26 20:59:55 +000083All the examples below assume this naming scheme.
Bram Moolenaar325b7a22004-07-05 15:58:32 +000084
Bram Moolenaar051b7822005-05-19 21:00:46 +000085 *mzscheme-sandbox*
86When executed in the |sandbox|, access to some filesystem and Vim interface
87procedures is restricted.
Bram Moolenaar325b7a22004-07-05 15:58:32 +000088
89==============================================================================
902. Examples *mzscheme-examples*
91>
92 :mzscheme (display "Hello")
Bram Moolenaar9e70cf12009-05-26 20:59:55 +000093 :mz (display (string-append "Using MzScheme version " (version)))
94 :mzscheme (require (prefix vim- vimext)) ; for MzScheme < 4.x
95 :mzscheme (require (prefix-in vim- 'vimext)) ; MzScheme 4.x
Bram Moolenaar325b7a22004-07-05 15:58:32 +000096 :mzscheme (vim-set-buff-line 10 "This is line #10")
Bram Moolenaarabd468e2016-09-08 22:22:43 +020097
98To see what version of MzScheme you have: >
99 :mzscheme (display (version))
Bram Moolenaar325b7a22004-07-05 15:58:32 +0000100<
101Inline script usage: >
102 function! <SID>SetFirstLine()
103 :mz << EOF
104 (display "!!!")
Bram Moolenaar9e70cf12009-05-26 20:59:55 +0000105 (require (prefix vim- vimext))
106 ; for newer versions (require (prefix-in vim- 'vimext))
Bram Moolenaar325b7a22004-07-05 15:58:32 +0000107 (vim-set-buff-line 1 "This is line #1")
108 (vim-beep)
Bram Moolenaar9e70cf12009-05-26 20:59:55 +0000109 EOF
Bram Moolenaar325b7a22004-07-05 15:58:32 +0000110 endfunction
111
112 nmap <F9> :call <SID>SetFirstLine() <CR>
113<
114File execution: >
115 :mzfile supascript.scm
116<
Bram Moolenaar9e70cf12009-05-26 20:59:55 +0000117Vim exception handling: >
118 :mz << EOF
119 (require (prefix vim- vimext))
120 ; for newer versions (require (prefix-in vim- 'vimext))
121 (with-handlers
122 ([exn:vim? (lambda (e) (display (exn-message e)))])
123 (vim-eval "nonsense-string"))
124 EOF
Bram Moolenaar325b7a22004-07-05 15:58:32 +0000125<
Bram Moolenaar9e70cf12009-05-26 20:59:55 +0000126Auto-instantiation of vimext module (can be placed in your |vimrc|): >
127 function! MzRequire()
128 :redir => l:mzversion
129 :mz (version)
130 :redir END
131 if strpart(l:mzversion, 1, 1) < "4"
132 " MzScheme versions < 4.x:
133 :mz (require (prefix vim- vimext))
134 else
135 " newer versions:
136 :mz (require (prefix-in vim- 'vimext))
137 endif
138 endfunction
Bram Moolenaar325b7a22004-07-05 15:58:32 +0000139
Bram Moolenaar9e70cf12009-05-26 20:59:55 +0000140 if has("mzscheme")
141 silent call MzRequire()
142 endif
143<
Bram Moolenaar325b7a22004-07-05 15:58:32 +0000144==============================================================================
1453. Threads *mzscheme-threads*
146
147The MzScheme interface supports threads. They are independent from OS threads,
148thus scheduling is required. The option 'mzquantum' determines how often
149Vim should poll for available MzScheme threads.
150NOTE
151Thread scheduling in the console version of Vim is less reliable than in the
152GUI version.
153
154==============================================================================
Bram Moolenaar7e506b62010-01-19 15:55:06 +01001554. Vim access from MzScheme *mzscheme-vim*
Bram Moolenaar325b7a22004-07-05 15:58:32 +0000156
157 *mzscheme-vimext*
158The 'vimext' module provides access to procedures defined in the MzScheme
159interface.
160
161Common
162------
163 (command {command-string}) Perform the vim ":Ex" style command.
Bram Moolenaar9e70cf12009-05-26 20:59:55 +0000164 (eval {expr-string}) Evaluate the vim expression into
165 respective MzScheme object: |Lists| are
166 represented as Scheme lists,
Bram Moolenaar75676462013-01-30 14:55:42 +0100167 |Dictionaries| as hash tables,
168 |Funcref|s as functions (see also
169 |mzscheme-funcref|)
170 NOTE the name clashes with MzScheme eval,
171 use module qualifiers to overcome this.
Bram Moolenaar325b7a22004-07-05 15:58:32 +0000172 (range-start) Start/End of the range passed with
173 (range-end) the Scheme command.
174 (beep) beep
175 (get-option {option-name} [buffer-or-window]) Get Vim option value (either
176 local or global, see set-option).
177 (set-option {string} [buffer-or-window])
178 Set a Vim option. String must have option
179 setting form (like optname=optval, or
180 optname+=optval, etc.) When called with
181 {buffer} or {window} the local option will
182 be set. The symbol 'global can be passed
183 as {buffer-or-window}. Then |:setglobal|
184 will be used.
Bram Moolenaar325b7a22004-07-05 15:58:32 +0000185
186Buffers *mzscheme-buffer*
187-------
188 (buff? {object}) Is object a buffer?
189 (buff-valid? {object}) Is object a valid buffer? (i.e.
190 corresponds to the real Vim buffer)
191 (get-buff-line {linenr} [buffer])
192 Get line from a buffer.
193 (set-buff-line {linenr} {string} [buffer])
194 Set a line in a buffer. If {string} is #f,
195 the line gets deleted. The [buffer]
Bram Moolenaarc9b4b052006-04-30 18:54:39 +0000196 argument is optional. If omitted, the
197 current buffer will be used.
Bram Moolenaar325b7a22004-07-05 15:58:32 +0000198 (get-buff-line-list {start} {end} [buffer])
199 Get a list of lines in a buffer. {Start}
Bram Moolenaar5e3dae82010-03-02 16:19:40 +0100200 and {end} are 1-based and inclusive.
Bram Moolenaar325b7a22004-07-05 15:58:32 +0000201 (set-buff-line-list {start} {end} {string-list} [buffer])
202 Set a list of lines in a buffer. If
203 string-list is #f or null, the lines get
204 deleted. If a list is shorter than
205 {end}-{start} the remaining lines will
206 be deleted.
207 (get-buff-name [buffer]) Get a buffer's text name.
208 (get-buff-num [buffer]) Get a buffer's number.
209 (get-buff-size [buffer]) Get buffer line count.
210 (insert-buff-line-list {linenr} {string/string-list} [buffer])
211 Insert a list of lines into a buffer after
212 {linenr}. If {linenr} is 0, lines will be
213 inserted at start.
Bram Moolenaar5e3dae82010-03-02 16:19:40 +0100214 (curr-buff) Get the current buffer. Use other MzScheme
215 interface procedures to change it.
Bram Moolenaar325b7a22004-07-05 15:58:32 +0000216 (buff-count) Get count of total buffers in the editor.
217 (get-next-buff [buffer]) Get next buffer.
218 (get-prev-buff [buffer]) Get previous buffer. Return #f when there
219 are no more buffers.
220 (open-buff {filename}) Open a new buffer (for file "name")
221 (get-buff-by-name {buffername}) Get a buffer by its filename or #f
222 if there is no such buffer.
223 (get-buff-by-num {buffernum}) Get a buffer by its number (return #f if
224 there is no buffer with this number).
Bram Moolenaar325b7a22004-07-05 15:58:32 +0000225
226Windows *mzscheme-window*
227------
228 (win? {object}) Is object a window?
229 (win-valid? {object}) Is object a valid window (i.e. corresponds
230 to the real Vim window)?
231 (curr-win) Get the current window.
232 (win-count) Get count of windows.
233 (get-win-num [window]) Get window number.
234 (get-win-by-num {windownum}) Get window by its number.
235 (get-win-buffer [window]) Get the buffer for a given window.
236 (get-win-height [window])
237 (set-win-height {height} [window]) Get/Set height of window.
238 (get-win-width [window])
239 (set-win-width {width} [window])Get/Set width of window.
240 (get-win-list [buffer]) Get list of windows for a buffer.
241 (get-cursor [window]) Get cursor position in a window as
242 a pair (linenr . column).
243 (set-cursor (line . col) [window]) Set cursor position.
244
Bram Moolenaar4770d092006-01-12 23:22:24 +0000245==============================================================================
Bram Moolenaar7e506b62010-01-19 15:55:06 +01002465. mzeval() Vim function *mzscheme-mzeval*
247
Bram Moolenaar945e2db2010-06-05 17:43:32 +0200248To facilitate bi-directional interface, you can use |mzeval()| function to
Bram Moolenaarb544f3c2017-02-23 19:03:28 +0100249evaluate MzScheme expressions and pass their values to Vim script.
Bram Moolenaar7e506b62010-01-19 15:55:06 +0100250
251==============================================================================
Bram Moolenaar75676462013-01-30 14:55:42 +01002526. Using Function references *mzscheme-funcref*
253
254MzScheme interface allows use of |Funcref|s so you can call Vim functions
255directly from Scheme. For instance: >
256 function! MyAdd2(arg)
257 return a:arg + 2
258 endfunction
259 mz (define f2 (vim-eval "function(\"MyAdd2\")"))
260 mz (f2 7)
261< or : >
262 :mz (define indent (vim-eval "function('indent')"))
263 " return Vim indent for line 12
264 :mz (indent 12)
265<
266
267==============================================================================
Bram Moolenaar705ada12016-01-24 17:56:50 +01002687. Dynamic loading *mzscheme-dynamic* *E815*
Bram Moolenaar4770d092006-01-12 23:22:24 +0000269
270On MS-Windows the MzScheme libraries can be loaded dynamically. The |:version|
271output then includes |+mzscheme/dyn|.
272
273This means that Vim will search for the MzScheme DLL files only when needed.
274When you don't use the MzScheme interface you don't need them, thus you can
275use Vim without these DLL files.
Bram Moolenaar4e640bd2016-01-16 16:20:38 +0100276NOTE: Newer version of MzScheme (Racket) require earlier (trampolined)
277initialisation via scheme_main_setup. So Vim always loads the MzScheme DLL at
Bram Moolenaar0ab35b22017-10-08 17:41:37 +0200278startup if possible. This may make Vim startup slower.
Bram Moolenaar4770d092006-01-12 23:22:24 +0000279
280To use the MzScheme interface the MzScheme DLLs must be in your search path.
281In a console window type "path" to see what directories are used.
282
Bram Moolenaar0ab35b22017-10-08 17:41:37 +0200283On MS-Windows the options 'mzschemedll' and 'mzschemegcdll' are used for the
284name of the library to load. The initial value is specified at build time.
285
286The version of the DLL must match the MzScheme version Vim was compiled with.
Bram Moolenaar4770d092006-01-12 23:22:24 +0000287For MzScheme version 209 they will be "libmzsch209_000.dll" and
Bram Moolenaar9964e462007-05-05 17:54:07 +0000288"libmzgc209_000.dll". To know for sure look at the output of the ":version"
289command, look for -DDYNAMIC_MZSCH_DLL="something" and
290-DDYNAMIC_MZGC_DLL="something" in the "Compilation" info.
Bram Moolenaar4770d092006-01-12 23:22:24 +0000291
Bram Moolenaar4e640bd2016-01-16 16:20:38 +0100292For example, if MzScheme (Racket) is installed at C:\Racket63, you may need
293to set the environment variable as the following: >
294
295 PATH=%PATH%;C:\Racket63\lib
296 PLTCOLLECTS=C:\Racket63\collects
297 PLTCONFIGDIR=C:\Racket63\etc
298<
299==============================================================================
Bram Moolenaar705ada12016-01-24 17:56:50 +01003008. MzScheme setup *mzscheme-setup* *E895*
Bram Moolenaar4e640bd2016-01-16 16:20:38 +0100301
302Vim requires "racket/base" module for if_mzsch core (fallback to "scheme/base"
303if it doesn't exist), "r5rs" module for test and "raco ctool" command for
304building Vim. If MzScheme did not have them, you can install them with
305MzScheme's raco command:
306>
307 raco pkg install scheme-lib # scheme/base module
308 raco pkg install r5rs-lib # r5rs module
309 raco pkg install cext-lib # raco ctool command
310<
Bram Moolenaar325b7a22004-07-05 15:58:32 +0000311======================================================================
Bram Moolenaar91f84f62018-07-29 15:07:52 +0200312 vim:tw=78:ts=8:noet:sts=4:ft=help:norl: