1*if_mzsch.txt* For Vim version 8.2. Last change: 2020 Oct 14 2 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| 124. Vim access from MzScheme |mzscheme-vim| 135. mzeval() Vim function |mzscheme-mzeval| 146. Using Function references |mzscheme-funcref| 157. Dynamic loading |mzscheme-dynamic| 168. MzScheme setup |mzscheme-setup| 17 18{only available when Vim was compiled with the |+mzscheme| feature} 19 20Based on the work of Brent Fulgham. 21Dynamic loading added by Sergey Khorev 22 23MzScheme and PLT Scheme names have been rebranded as Racket. For more 24information please check http://racket-lang.org 25 26Futures 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 34 35============================================================================== 361. Commands *mzscheme-commands* 37 38 *:mzscheme* *:mz* 39:[range]mz[scheme] {stmt} 40 Execute MzScheme statement {stmt}. 41 42:[range]mz[scheme] << [trim] [{endmarker}] 43{script} 44{endmarker} 45 Execute inlined MzScheme script {script}. 46 Note: This command doesn't work when the MzScheme 47 feature wasn't compiled in. To avoid errors, see 48 |script-here|. 49 50 If [endmarker] is omitted from after the "<<", a dot 51 '.' must be used after {script}, like for the 52 |:append| and |:insert| commands. Refer to 53 |:let-heredoc| for more information. 54 55 56 *:mzfile* *:mzf* 57:[range]mzf[ile] {file} Execute the MzScheme script in {file}. 58 59All of these commands do essentially the same thing - they execute a piece of 60MzScheme code, with the "current range" set to the given line 61range. 62 63In the case of :mzscheme, the code to execute is in the command-line. 64In the case of :mzfile, the code to execute is the contents of the given file. 65 66MzScheme interface defines exception exn:vim, derived from exn. 67It is raised for various Vim errors. 68 69During compilation, the MzScheme interface will remember the current MzScheme 70collection path. If you want to specify additional paths use the 71'current-library-collection-paths' parameter. E.g., to cons the user-local 72MzScheme 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 81All functionality is provided through module vimext. 82 83The exn:vim is available without explicit import. 84 85To avoid clashes with MzScheme, consider using prefix when requiring module, 86e.g.: > 87 :mzscheme (require (prefix vim- vimext)) 88< 89All the examples below assume this naming scheme. 90 91 *mzscheme-sandbox* 92When executed in the |sandbox|, access to some filesystem and Vim interface 93procedures is restricted. 94 95============================================================================== 962. Examples *mzscheme-examples* 97> 98 :mzscheme (display "Hello") 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 102 :mzscheme (vim-set-buff-line 10 "This is line #10") 103 104To see what version of MzScheme you have: > 105 :mzscheme (display (version)) 106< 107Inline script usage: > 108 function! <SID>SetFirstLine() 109 :mz << EOF 110 (display "!!!") 111 (require (prefix vim- vimext)) 112 ; for newer versions (require (prefix-in vim- 'vimext)) 113 (vim-set-buff-line 1 "This is line #1") 114 (vim-beep) 115 EOF 116 endfunction 117 118 nmap <F9> :call <SID>SetFirstLine() <CR> 119< 120File execution: > 121 :mzfile supascript.scm 122< 123Vim 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 131< 132Auto-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 145 146 if has("mzscheme") 147 silent call MzRequire() 148 endif 149< 150============================================================================== 1513. Threads *mzscheme-threads* 152 153The MzScheme interface supports threads. They are independent from OS threads, 154thus scheduling is required. The option 'mzquantum' determines how often 155Vim should poll for available MzScheme threads. 156NOTE 157Thread scheduling in the console version of Vim is less reliable than in the 158GUI version. 159 160============================================================================== 1614. Vim access from MzScheme *mzscheme-vim* 162 163 *mzscheme-vimext* 164The 'vimext' module provides access to procedures defined in the MzScheme 165interface. 166 167Common 168------ 169 (command {command-string}) Perform the vim ":Ex" style command. 170 (eval {expr-string}) Evaluate the vim expression into 171 respective MzScheme object: |Lists| are 172 represented as Scheme lists, 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. 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 192Buffers *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] 202 argument is optional. If omitted, the 203 current buffer will be used. 204 (get-buff-line-list {start} {end} [buffer]) 205 Get a list of lines in a buffer. {Start} 206 and {end} are 1-based and inclusive. 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. 220 (curr-buff) Get the current buffer. Use other MzScheme 221 interface procedures to change it. 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 232Windows *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 251============================================================================== 2525. mzeval() Vim function *mzscheme-mzeval* 253 254To facilitate bi-directional interface, you can use |mzeval()| function to 255evaluate MzScheme expressions and pass their values to Vim script. 256 257============================================================================== 2586. Using Function references *mzscheme-funcref* 259 260MzScheme interface allows use of |Funcref|s so you can call Vim functions 261directly 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============================================================================== 2747. Dynamic loading *mzscheme-dynamic* *E815* 275 276On MS-Windows the MzScheme libraries can be loaded dynamically. The |:version| 277output then includes |+mzscheme/dyn|. 278 279This means that Vim will search for the MzScheme DLL files only when needed. 280When you don't use the MzScheme interface you don't need them, thus you can 281use Vim without these DLL files. 282NOTE: Newer version of MzScheme (Racket) require earlier (trampolined) 283initialisation via scheme_main_setup. So Vim always loads the MzScheme DLL at 284startup if possible. This may make Vim startup slower. 285 286To use the MzScheme interface the MzScheme DLLs must be in your search path. 287In a console window type "path" to see what directories are used. 288 289On MS-Windows the options 'mzschemedll' and 'mzschemegcdll' are used for the 290name of the library to load. The initial value is specified at build time. 291 292The version of the DLL must match the MzScheme version Vim was compiled with. 293For MzScheme version 209 they will be "libmzsch209_000.dll" and 294"libmzgc209_000.dll". To know for sure look at the output of the ":version" 295command, look for -DDYNAMIC_MZSCH_DLL="something" and 296-DDYNAMIC_MZGC_DLL="something" in the "Compilation" info. 297 298For example, if MzScheme (Racket) is installed at C:\Racket63, you may need 299to set the environment variable as the following: > 300 301 PATH=%PATH%;C:\Racket63\lib 302 PLTCOLLECTS=C:\Racket63\collects 303 PLTCONFIGDIR=C:\Racket63\etc 304< 305============================================================================== 3068. MzScheme setup *mzscheme-setup* *E895* 307 308Vim requires "racket/base" module for if_mzsch core (fallback to "scheme/base" 309if it doesn't exist), "r5rs" module for test and "raco ctool" command for 310building Vim. If MzScheme did not have them, you can install them with 311MzScheme's raco command: 312> 313 raco pkg install scheme-lib # scheme/base module 314 raco pkg install r5rs-lib # r5rs module 315 raco pkg install cext-lib # raco ctool command 316< 317====================================================================== 318 vim:tw=78:ts=8:noet:sts=4:ft=help:norl: 319