Mercurial > vim
annotate runtime/doc/if_mzsch.txt @ 23427:8f2dcc0cfcf6
Added tag v8.2.2256 for changeset c3c690c8fcbfe65e17f5f99b8ffc007c8bb5ec89
author | Bram Moolenaar <Bram@vim.org> |
---|---|
date | Thu, 31 Dec 2020 18:30:04 +0100 |
parents | 5b7ea82bc18f |
children | f8116058ca76 |
rev | line source |
---|---|
22723 | 1 *if_mzsch.txt* For Vim version 8.2. Last change: 2020 Oct 14 |
14 | 2 |
3 | |
4 VIM REFERENCE MANUAL by Sergey Khorev | |
5 | |
6 | |
7 The MzScheme Interface to Vim *mzscheme* *MzScheme* | |
8 | |
9 1. Commands |mzscheme-commands| | |
10 2. Examples |mzscheme-examples| | |
11 3. Threads |mzscheme-threads| | |
2050
afcf9db31561
updated for version 7.2.336
Bram Moolenaar <bram@zimbu.org>
parents:
1919
diff
changeset
|
12 4. Vim access from MzScheme |mzscheme-vim| |
afcf9db31561
updated for version 7.2.336
Bram Moolenaar <bram@zimbu.org>
parents:
1919
diff
changeset
|
13 5. mzeval() Vim function |mzscheme-mzeval| |
4074 | 14 6. Using Function references |mzscheme-funcref| |
15 7. Dynamic loading |mzscheme-dynamic| | |
7609
77a14f3bc18b
commit https://github.com/vim/vim/commit/4e640bd930d133889dbc9f9a77e29bab902e3b7d
Christian Brabandt <cb@256bit.org>
parents:
5294
diff
changeset
|
16 8. MzScheme setup |mzscheme-setup| |
14 | 17 |
16553
0e473e9e70c2
patch 8.1.1280: remarks about functionality not in Vi clutters the help
Bram Moolenaar <Bram@vim.org>
parents:
14421
diff
changeset
|
18 {only available when Vim was compiled with the |+mzscheme| feature} |
14 | 19 |
20 Based on the work of Brent Fulgham. | |
128 | 21 Dynamic loading added by Sergey Khorev |
14 | 22 |
4074 | 23 MzScheme and PLT Scheme names have been rebranded as Racket. For more |
24 information please check http://racket-lang.org | |
14 | 25 |
4074 | 26 Futures and places of Racket version 5.x up to and including 5.3.1 do not |
27 work correctly with processes created by Vim. | |
28 The simplest solution is to build Racket on your own with these features | |
29 disabled: > | |
30 ./configure --disable-futures --disable-places --prefix=your-install-prefix | |
31 | |
32 To speed up the process, you might also want to use --disable-gracket and | |
33 --disable-docs | |
1121 | 34 |
14 | 35 ============================================================================== |
36 1. Commands *mzscheme-commands* | |
37 | |
38 *:mzscheme* *:mz* | |
39 :[range]mz[scheme] {stmt} | |
16553
0e473e9e70c2
patch 8.1.1280: remarks about functionality not in Vi clutters the help
Bram Moolenaar <Bram@vim.org>
parents:
14421
diff
changeset
|
40 Execute MzScheme statement {stmt}. |
14 | 41 |
20045
04ef2ccf2519
patch 8.2.0578: heredoc for interfaces does not support "trim"
Bram Moolenaar <Bram@vim.org>
parents:
18879
diff
changeset
|
42 :[range]mz[scheme] << [trim] [{endmarker}] |
14 | 43 {script} |
44 {endmarker} | |
45 Execute inlined MzScheme script {script}. | |
22723 | 46 Note: This command doesn't work when the MzScheme |
14 | 47 feature wasn't compiled in. To avoid errors, see |
48 |script-here|. | |
49 | |
17571 | 50 If [endmarker] is omitted from after the "<<", a dot |
51 '.' must be used after {script}, like for the | |
20045
04ef2ccf2519
patch 8.2.0578: heredoc for interfaces does not support "trim"
Bram Moolenaar <Bram@vim.org>
parents:
18879
diff
changeset
|
52 |:append| and |:insert| commands. Refer to |
04ef2ccf2519
patch 8.2.0578: heredoc for interfaces does not support "trim"
Bram Moolenaar <Bram@vim.org>
parents:
18879
diff
changeset
|
53 |:let-heredoc| for more information. |
04ef2ccf2519
patch 8.2.0578: heredoc for interfaces does not support "trim"
Bram Moolenaar <Bram@vim.org>
parents:
18879
diff
changeset
|
54 |
17571 | 55 |
14 | 56 *:mzfile* *:mzf* |
16553
0e473e9e70c2
patch 8.1.1280: remarks about functionality not in Vi clutters the help
Bram Moolenaar <Bram@vim.org>
parents:
14421
diff
changeset
|
57 :[range]mzf[ile] {file} Execute the MzScheme script in {file}. |
14 | 58 |
59 All of these commands do essentially the same thing - they execute a piece of | |
60 MzScheme code, with the "current range" set to the given line | |
61 range. | |
62 | |
63 In the case of :mzscheme, the code to execute is in the command-line. | |
64 In the case of :mzfile, the code to execute is the contents of the given file. | |
65 | |
66 MzScheme interface defines exception exn:vim, derived from exn. | |
67 It is raised for various Vim errors. | |
68 | |
69 During compilation, the MzScheme interface will remember the current MzScheme | |
70 collection path. If you want to specify additional paths use the | |
71 'current-library-collection-paths' parameter. E.g., to cons the user-local | |
72 MzScheme collection path: > | |
73 :mz << EOF | |
74 (current-library-collection-paths | |
75 (cons | |
76 (build-path (find-system-path 'addon-dir) (version) "collects") | |
77 (current-library-collection-paths))) | |
78 EOF | |
79 < | |
80 | |
81 All functionality is provided through module vimext. | |
82 | |
83 The exn:vim is available without explicit import. | |
84 | |
85 To avoid clashes with MzScheme, consider using prefix when requiring module, | |
86 e.g.: > | |
87 :mzscheme (require (prefix vim- vimext)) | |
88 < | |
18831 | 89 All the examples below assume this naming scheme. |
14 | 90 |
273 | 91 *mzscheme-sandbox* |
92 When executed in the |sandbox|, access to some filesystem and Vim interface | |
93 procedures is restricted. | |
14 | 94 |
95 ============================================================================== | |
96 2. Examples *mzscheme-examples* | |
97 > | |
98 :mzscheme (display "Hello") | |
1894 | 99 :mz (display (string-append "Using MzScheme version " (version))) |
100 :mzscheme (require (prefix vim- vimext)) ; for MzScheme < 4.x | |
101 :mzscheme (require (prefix-in vim- 'vimext)) ; MzScheme 4.x | |
14 | 102 :mzscheme (vim-set-buff-line 10 "This is line #10") |
10153
715d6c5707b8
commit https://github.com/vim/vim/commit/abd468ed0fbcba391e7833feeaa7de3ced841455
Christian Brabandt <cb@256bit.org>
parents:
7742
diff
changeset
|
103 |
715d6c5707b8
commit https://github.com/vim/vim/commit/abd468ed0fbcba391e7833feeaa7de3ced841455
Christian Brabandt <cb@256bit.org>
parents:
7742
diff
changeset
|
104 To see what version of MzScheme you have: > |
715d6c5707b8
commit https://github.com/vim/vim/commit/abd468ed0fbcba391e7833feeaa7de3ced841455
Christian Brabandt <cb@256bit.org>
parents:
7742
diff
changeset
|
105 :mzscheme (display (version)) |
14 | 106 < |
107 Inline script usage: > | |
108 function! <SID>SetFirstLine() | |
109 :mz << EOF | |
110 (display "!!!") | |
1894 | 111 (require (prefix vim- vimext)) |
112 ; for newer versions (require (prefix-in vim- 'vimext)) | |
14 | 113 (vim-set-buff-line 1 "This is line #1") |
114 (vim-beep) | |
1894 | 115 EOF |
14 | 116 endfunction |
117 | |
118 nmap <F9> :call <SID>SetFirstLine() <CR> | |
119 < | |
120 File execution: > | |
121 :mzfile supascript.scm | |
122 < | |
1894 | 123 Vim exception handling: > |
124 :mz << EOF | |
125 (require (prefix vim- vimext)) | |
126 ; for newer versions (require (prefix-in vim- 'vimext)) | |
127 (with-handlers | |
128 ([exn:vim? (lambda (e) (display (exn-message e)))]) | |
129 (vim-eval "nonsense-string")) | |
130 EOF | |
14 | 131 < |
1894 | 132 Auto-instantiation of vimext module (can be placed in your |vimrc|): > |
133 function! MzRequire() | |
134 :redir => l:mzversion | |
135 :mz (version) | |
136 :redir END | |
137 if strpart(l:mzversion, 1, 1) < "4" | |
138 " MzScheme versions < 4.x: | |
139 :mz (require (prefix vim- vimext)) | |
140 else | |
141 " newer versions: | |
142 :mz (require (prefix-in vim- 'vimext)) | |
143 endif | |
144 endfunction | |
14 | 145 |
1894 | 146 if has("mzscheme") |
147 silent call MzRequire() | |
148 endif | |
149 < | |
14 | 150 ============================================================================== |
151 3. Threads *mzscheme-threads* | |
152 | |
153 The MzScheme interface supports threads. They are independent from OS threads, | |
154 thus scheduling is required. The option 'mzquantum' determines how often | |
155 Vim should poll for available MzScheme threads. | |
156 NOTE | |
157 Thread scheduling in the console version of Vim is less reliable than in the | |
158 GUI version. | |
159 | |
160 ============================================================================== | |
2050
afcf9db31561
updated for version 7.2.336
Bram Moolenaar <bram@zimbu.org>
parents:
1919
diff
changeset
|
161 4. Vim access from MzScheme *mzscheme-vim* |
14 | 162 |
163 *mzscheme-vimext* | |
164 The 'vimext' module provides access to procedures defined in the MzScheme | |
165 interface. | |
166 | |
167 Common | |
168 ------ | |
169 (command {command-string}) Perform the vim ":Ex" style command. | |
1894 | 170 (eval {expr-string}) Evaluate the vim expression into |
171 respective MzScheme object: |Lists| are | |
172 represented as Scheme lists, | |
4074 | 173 |Dictionaries| as hash tables, |
174 |Funcref|s as functions (see also | |
175 |mzscheme-funcref|) | |
176 NOTE the name clashes with MzScheme eval, | |
177 use module qualifiers to overcome this. | |
14 | 178 (range-start) Start/End of the range passed with |
179 (range-end) the Scheme command. | |
180 (beep) beep | |
181 (get-option {option-name} [buffer-or-window]) Get Vim option value (either | |
182 local or global, see set-option). | |
183 (set-option {string} [buffer-or-window]) | |
184 Set a Vim option. String must have option | |
185 setting form (like optname=optval, or | |
186 optname+=optval, etc.) When called with | |
187 {buffer} or {window} the local option will | |
188 be set. The symbol 'global can be passed | |
189 as {buffer-or-window}. Then |:setglobal| | |
190 will be used. | |
191 | |
192 Buffers *mzscheme-buffer* | |
193 ------- | |
194 (buff? {object}) Is object a buffer? | |
195 (buff-valid? {object}) Is object a valid buffer? (i.e. | |
196 corresponds to the real Vim buffer) | |
197 (get-buff-line {linenr} [buffer]) | |
198 Get line from a buffer. | |
199 (set-buff-line {linenr} {string} [buffer]) | |
200 Set a line in a buffer. If {string} is #f, | |
201 the line gets deleted. The [buffer] | |
856 | 202 argument is optional. If omitted, the |
203 current buffer will be used. | |
14 | 204 (get-buff-line-list {start} {end} [buffer]) |
205 Get a list of lines in a buffer. {Start} | |
2098
3259c3923c1e
Updated runtime an documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
2050
diff
changeset
|
206 and {end} are 1-based and inclusive. |
14 | 207 (set-buff-line-list {start} {end} {string-list} [buffer]) |
208 Set a list of lines in a buffer. If | |
209 string-list is #f or null, the lines get | |
210 deleted. If a list is shorter than | |
211 {end}-{start} the remaining lines will | |
212 be deleted. | |
213 (get-buff-name [buffer]) Get a buffer's text name. | |
214 (get-buff-num [buffer]) Get a buffer's number. | |
215 (get-buff-size [buffer]) Get buffer line count. | |
216 (insert-buff-line-list {linenr} {string/string-list} [buffer]) | |
217 Insert a list of lines into a buffer after | |
218 {linenr}. If {linenr} is 0, lines will be | |
219 inserted at start. | |
2098
3259c3923c1e
Updated runtime an documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
2050
diff
changeset
|
220 (curr-buff) Get the current buffer. Use other MzScheme |
3259c3923c1e
Updated runtime an documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
2050
diff
changeset
|
221 interface procedures to change it. |
14 | 222 (buff-count) Get count of total buffers in the editor. |
223 (get-next-buff [buffer]) Get next buffer. | |
224 (get-prev-buff [buffer]) Get previous buffer. Return #f when there | |
225 are no more buffers. | |
226 (open-buff {filename}) Open a new buffer (for file "name") | |
227 (get-buff-by-name {buffername}) Get a buffer by its filename or #f | |
228 if there is no such buffer. | |
229 (get-buff-by-num {buffernum}) Get a buffer by its number (return #f if | |
230 there is no buffer with this number). | |
231 | |
232 Windows *mzscheme-window* | |
233 ------ | |
234 (win? {object}) Is object a window? | |
235 (win-valid? {object}) Is object a valid window (i.e. corresponds | |
236 to the real Vim window)? | |
237 (curr-win) Get the current window. | |
238 (win-count) Get count of windows. | |
239 (get-win-num [window]) Get window number. | |
240 (get-win-by-num {windownum}) Get window by its number. | |
241 (get-win-buffer [window]) Get the buffer for a given window. | |
242 (get-win-height [window]) | |
243 (set-win-height {height} [window]) Get/Set height of window. | |
244 (get-win-width [window]) | |
245 (set-win-width {width} [window])Get/Set width of window. | |
246 (get-win-list [buffer]) Get list of windows for a buffer. | |
247 (get-cursor [window]) Get cursor position in a window as | |
248 a pair (linenr . column). | |
249 (set-cursor (line . col) [window]) Set cursor position. | |
250 | |
625 | 251 ============================================================================== |
2050
afcf9db31561
updated for version 7.2.336
Bram Moolenaar <bram@zimbu.org>
parents:
1919
diff
changeset
|
252 5. mzeval() Vim function *mzscheme-mzeval* |
afcf9db31561
updated for version 7.2.336
Bram Moolenaar <bram@zimbu.org>
parents:
1919
diff
changeset
|
253 |
2249
6d3d35ff2c2b
Use full path in undofile(). Updated docs.
Bram Moolenaar <bram@vim.org>
parents:
2154
diff
changeset
|
254 To facilitate bi-directional interface, you can use |mzeval()| function to |
10942
e05695e59f6d
patch 8.0.0360: sometimes VimL is used instead of "Vim script"
Christian Brabandt <cb@256bit.org>
parents:
10198
diff
changeset
|
255 evaluate MzScheme expressions and pass their values to Vim script. |
2050
afcf9db31561
updated for version 7.2.336
Bram Moolenaar <bram@zimbu.org>
parents:
1919
diff
changeset
|
256 |
afcf9db31561
updated for version 7.2.336
Bram Moolenaar <bram@zimbu.org>
parents:
1919
diff
changeset
|
257 ============================================================================== |
4074 | 258 6. Using Function references *mzscheme-funcref* |
259 | |
260 MzScheme interface allows use of |Funcref|s so you can call Vim functions | |
261 directly from Scheme. For instance: > | |
262 function! MyAdd2(arg) | |
263 return a:arg + 2 | |
264 endfunction | |
265 mz (define f2 (vim-eval "function(\"MyAdd2\")")) | |
266 mz (f2 7) | |
267 < or : > | |
268 :mz (define indent (vim-eval "function('indent')")) | |
269 " return Vim indent for line 12 | |
270 :mz (indent 12) | |
271 < | |
272 | |
273 ============================================================================== | |
7742
5f6f35a3cb12
commit https://github.com/vim/vim/commit/705ada1aff27ecd9c47c690df817d043c2ceb5e2
Christian Brabandt <cb@256bit.org>
parents:
7659
diff
changeset
|
274 7. Dynamic loading *mzscheme-dynamic* *E815* |
625 | 275 |
276 On MS-Windows the MzScheme libraries can be loaded dynamically. The |:version| | |
277 output then includes |+mzscheme/dyn|. | |
278 | |
279 This means that Vim will search for the MzScheme DLL files only when needed. | |
280 When you don't use the MzScheme interface you don't need them, thus you can | |
281 use Vim without these DLL files. | |
7609
77a14f3bc18b
commit https://github.com/vim/vim/commit/4e640bd930d133889dbc9f9a77e29bab902e3b7d
Christian Brabandt <cb@256bit.org>
parents:
5294
diff
changeset
|
282 NOTE: Newer version of MzScheme (Racket) require earlier (trampolined) |
77a14f3bc18b
commit https://github.com/vim/vim/commit/4e640bd930d133889dbc9f9a77e29bab902e3b7d
Christian Brabandt <cb@256bit.org>
parents:
5294
diff
changeset
|
283 initialisation via scheme_main_setup. So Vim always loads the MzScheme DLL at |
12608
b390f5003e2f
patch 8.0.1182: cannot see or change mzscheme dll name
Christian Brabandt <cb@256bit.org>
parents:
10942
diff
changeset
|
284 startup if possible. This may make Vim startup slower. |
625 | 285 |
286 To use the MzScheme interface the MzScheme DLLs must be in your search path. | |
287 In a console window type "path" to see what directories are used. | |
288 | |
12608
b390f5003e2f
patch 8.0.1182: cannot see or change mzscheme dll name
Christian Brabandt <cb@256bit.org>
parents:
10942
diff
changeset
|
289 On MS-Windows the options 'mzschemedll' and 'mzschemegcdll' are used for the |
b390f5003e2f
patch 8.0.1182: cannot see or change mzscheme dll name
Christian Brabandt <cb@256bit.org>
parents:
10942
diff
changeset
|
290 name of the library to load. The initial value is specified at build time. |
b390f5003e2f
patch 8.0.1182: cannot see or change mzscheme dll name
Christian Brabandt <cb@256bit.org>
parents:
10942
diff
changeset
|
291 |
b390f5003e2f
patch 8.0.1182: cannot see or change mzscheme dll name
Christian Brabandt <cb@256bit.org>
parents:
10942
diff
changeset
|
292 The version of the DLL must match the MzScheme version Vim was compiled with. |
625 | 293 For MzScheme version 209 they will be "libmzsch209_000.dll" and |
1121 | 294 "libmzgc209_000.dll". To know for sure look at the output of the ":version" |
295 command, look for -DDYNAMIC_MZSCH_DLL="something" and | |
296 -DDYNAMIC_MZGC_DLL="something" in the "Compilation" info. | |
625 | 297 |
7609
77a14f3bc18b
commit https://github.com/vim/vim/commit/4e640bd930d133889dbc9f9a77e29bab902e3b7d
Christian Brabandt <cb@256bit.org>
parents:
5294
diff
changeset
|
298 For example, if MzScheme (Racket) is installed at C:\Racket63, you may need |
77a14f3bc18b
commit https://github.com/vim/vim/commit/4e640bd930d133889dbc9f9a77e29bab902e3b7d
Christian Brabandt <cb@256bit.org>
parents:
5294
diff
changeset
|
299 to set the environment variable as the following: > |
77a14f3bc18b
commit https://github.com/vim/vim/commit/4e640bd930d133889dbc9f9a77e29bab902e3b7d
Christian Brabandt <cb@256bit.org>
parents:
5294
diff
changeset
|
300 |
77a14f3bc18b
commit https://github.com/vim/vim/commit/4e640bd930d133889dbc9f9a77e29bab902e3b7d
Christian Brabandt <cb@256bit.org>
parents:
5294
diff
changeset
|
301 PATH=%PATH%;C:\Racket63\lib |
77a14f3bc18b
commit https://github.com/vim/vim/commit/4e640bd930d133889dbc9f9a77e29bab902e3b7d
Christian Brabandt <cb@256bit.org>
parents:
5294
diff
changeset
|
302 PLTCOLLECTS=C:\Racket63\collects |
77a14f3bc18b
commit https://github.com/vim/vim/commit/4e640bd930d133889dbc9f9a77e29bab902e3b7d
Christian Brabandt <cb@256bit.org>
parents:
5294
diff
changeset
|
303 PLTCONFIGDIR=C:\Racket63\etc |
77a14f3bc18b
commit https://github.com/vim/vim/commit/4e640bd930d133889dbc9f9a77e29bab902e3b7d
Christian Brabandt <cb@256bit.org>
parents:
5294
diff
changeset
|
304 < |
77a14f3bc18b
commit https://github.com/vim/vim/commit/4e640bd930d133889dbc9f9a77e29bab902e3b7d
Christian Brabandt <cb@256bit.org>
parents:
5294
diff
changeset
|
305 ============================================================================== |
7742
5f6f35a3cb12
commit https://github.com/vim/vim/commit/705ada1aff27ecd9c47c690df817d043c2ceb5e2
Christian Brabandt <cb@256bit.org>
parents:
7659
diff
changeset
|
306 8. MzScheme setup *mzscheme-setup* *E895* |
7609
77a14f3bc18b
commit https://github.com/vim/vim/commit/4e640bd930d133889dbc9f9a77e29bab902e3b7d
Christian Brabandt <cb@256bit.org>
parents:
5294
diff
changeset
|
307 |
77a14f3bc18b
commit https://github.com/vim/vim/commit/4e640bd930d133889dbc9f9a77e29bab902e3b7d
Christian Brabandt <cb@256bit.org>
parents:
5294
diff
changeset
|
308 Vim requires "racket/base" module for if_mzsch core (fallback to "scheme/base" |
77a14f3bc18b
commit https://github.com/vim/vim/commit/4e640bd930d133889dbc9f9a77e29bab902e3b7d
Christian Brabandt <cb@256bit.org>
parents:
5294
diff
changeset
|
309 if it doesn't exist), "r5rs" module for test and "raco ctool" command for |
77a14f3bc18b
commit https://github.com/vim/vim/commit/4e640bd930d133889dbc9f9a77e29bab902e3b7d
Christian Brabandt <cb@256bit.org>
parents:
5294
diff
changeset
|
310 building Vim. If MzScheme did not have them, you can install them with |
77a14f3bc18b
commit https://github.com/vim/vim/commit/4e640bd930d133889dbc9f9a77e29bab902e3b7d
Christian Brabandt <cb@256bit.org>
parents:
5294
diff
changeset
|
311 MzScheme's raco command: |
77a14f3bc18b
commit https://github.com/vim/vim/commit/4e640bd930d133889dbc9f9a77e29bab902e3b7d
Christian Brabandt <cb@256bit.org>
parents:
5294
diff
changeset
|
312 > |
77a14f3bc18b
commit https://github.com/vim/vim/commit/4e640bd930d133889dbc9f9a77e29bab902e3b7d
Christian Brabandt <cb@256bit.org>
parents:
5294
diff
changeset
|
313 raco pkg install scheme-lib # scheme/base module |
77a14f3bc18b
commit https://github.com/vim/vim/commit/4e640bd930d133889dbc9f9a77e29bab902e3b7d
Christian Brabandt <cb@256bit.org>
parents:
5294
diff
changeset
|
314 raco pkg install r5rs-lib # r5rs module |
77a14f3bc18b
commit https://github.com/vim/vim/commit/4e640bd930d133889dbc9f9a77e29bab902e3b7d
Christian Brabandt <cb@256bit.org>
parents:
5294
diff
changeset
|
315 raco pkg install cext-lib # raco ctool command |
77a14f3bc18b
commit https://github.com/vim/vim/commit/4e640bd930d133889dbc9f9a77e29bab902e3b7d
Christian Brabandt <cb@256bit.org>
parents:
5294
diff
changeset
|
316 < |
14 | 317 ====================================================================== |
14421 | 318 vim:tw=78:ts=8:noet:sts=4:ft=help:norl: |