vim

Fork of vim, an acceptable text editor
git clone git://git.laack.co/vim.git
Log | Files | Refs | README | LICENSE

if_mzsch.txt (11966B)


      1 *if_mzsch.txt*	For Vim version 9.2.  Last change: 2026 Feb 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|
     12 4. Vim access from MzScheme		|mzscheme-vim|
     13 5. mzeval() Vim function		|mzscheme-mzeval|
     14 6. Using Function references		|mzscheme-funcref|
     15 7. Dynamic loading			|mzscheme-dynamic|
     16 8. MzScheme setup			|mzscheme-setup|
     17 
     18 {only available when Vim was compiled with the |+mzscheme| feature}
     19 
     20 Based on the work of Brent Fulgham.
     21 Dynamic loading added by Sergey Khorev
     22 
     23 MzScheme and PLT Scheme names have been rebranded as Racket.  For more
     24 information please check http://racket-lang.org
     25 
     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
     34 
     35 ==============================================================================
     36 1. 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 
     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 <
     89 All the examples below assume this naming scheme.
     90 
     91 							*mzscheme-sandbox*
     92 When executed in the |sandbox|, access to some filesystem and Vim interface
     93 procedures is restricted.
     94 
     95 ==============================================================================
     96 2. 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 
    104 To see what version of MzScheme you have: >
    105 	:mzscheme (display (version))
    106 <
    107 Inline 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 <
    120 File execution: >
    121 	:mzfile supascript.scm
    122 <
    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
    131 <
    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
    145 
    146     if has("mzscheme")
    147 	silent call MzRequire()
    148     endif
    149 <
    150 ==============================================================================
    151 3. Threads						*mzscheme-threads*
    152 
    153 The MzScheme interface supports threads.  They are independent from OS
    154 threads, thus scheduling is required.  The option 'mzquantum' determines how
    155 often 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 ==============================================================================
    161 4. Vim access from MzScheme				*mzscheme-vim*
    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.
    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 
    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
    201 				    #f, 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
    221 				    MzScheme interface procedures to change
    222 				    it.
    223     (buff-count)		    Get count of total buffers in the editor.
    224     (get-next-buff [buffer])	    Get next buffer.
    225     (get-prev-buff [buffer])	    Get previous buffer.  Return #f when there
    226 				    are no more buffers.
    227     (open-buff {filename})	    Open a new buffer (for file "name")
    228     (get-buff-by-name {buffername}) Get a buffer by its filename or #f
    229 					if there is no such buffer.
    230     (get-buff-by-num {buffernum})   Get a buffer by its number (return #f if
    231 				    there is no buffer with this number).
    232 
    233 Windows							    *mzscheme-window*
    234 ------
    235     (win? {object})		    Is object a window?
    236     (win-valid? {object})	    Is object a valid window (i.e. corresponds
    237 				    to the real Vim window)?
    238     (curr-win)			    Get the current window.
    239     (win-count)			    Get count of windows.
    240     (get-win-num [window])	    Get window number.
    241     (get-win-by-num {windownum})    Get window by its number.
    242     (get-win-buffer	[window])   Get the buffer for a given window.
    243     (get-win-height [window])
    244     (set-win-height {height} [window])  Get/Set height of window.
    245     (get-win-width [window])
    246     (set-win-width {width} [window])Get/Set width of window.
    247     (get-win-list [buffer])	    Get list of windows for a buffer.
    248     (get-cursor [window])	    Get cursor position in a window as
    249 				    a pair (linenr . column).
    250     (set-cursor (line . col) [window])  Set cursor position.
    251 
    252 ==============================================================================
    253 5. mzeval() Vim function				    *mzscheme-mzeval*
    254 
    255 To facilitate bi-directional interface, you can use |mzeval()| function to
    256 evaluate MzScheme expressions and pass their values to Vim script.
    257 
    258 ==============================================================================
    259 6. Using Function references				    *mzscheme-funcref*
    260 
    261 MzScheme interface allows use of |Funcref|s so you can call Vim functions
    262 directly from Scheme.  For instance: >
    263     function! MyAdd2(arg)
    264 	return a:arg + 2
    265     endfunction
    266     mz (define f2 (vim-eval "function(\"MyAdd2\")"))
    267     mz (f2 7)
    268 < or : >
    269     :mz (define indent (vim-eval "function('indent')"))
    270     " return Vim indent for line 12
    271     :mz (indent 12)
    272 <
    273 
    274 ==============================================================================
    275 7. Dynamic loading				*mzscheme-dynamic* *E815*
    276 
    277 On MS-Windows the MzScheme libraries can be loaded dynamically.  The |:version|
    278 output then includes |+mzscheme/dyn|.
    279 
    280 This means that Vim will search for the MzScheme DLL files only when needed.
    281 When you don't use the MzScheme interface you don't need them, thus you can
    282 use Vim without these DLL files.
    283 NOTE: Newer version of MzScheme (Racket) require earlier (trampolined)
    284 initialisation via scheme_main_setup.  So Vim always loads the MzScheme DLL at
    285 startup if possible.  This may make Vim startup slower.
    286 
    287 To use the MzScheme interface the MzScheme DLLs must be in your search path.
    288 In a console window type "path" to see what directories are used.
    289 
    290 On MS-Windows the options 'mzschemedll' and 'mzschemegcdll' are used for the
    291 name of the library to load.  The initial value is specified at build time.
    292 
    293 The version of the DLL must match the MzScheme version Vim was compiled with.
    294 For MzScheme version 209 they will be "libmzsch209_000.dll" and
    295 "libmzgc209_000.dll".  To know for sure look at the output of the ":version"
    296 command, look for -DDYNAMIC_MZSCH_DLL="something" and
    297 -DDYNAMIC_MZGC_DLL="something" in the "Compilation" info.
    298 
    299 For example, if MzScheme (Racket) is installed at C:\Racket63, you may need
    300 to set the environment variable as the following: >
    301 
    302   PATH=%PATH%;C:\Racket63\lib
    303   PLTCOLLECTS=C:\Racket63\collects
    304   PLTCONFIGDIR=C:\Racket63\etc
    305 <
    306 ==============================================================================
    307 8. MzScheme setup				    *mzscheme-setup* *E895*
    308 
    309 Vim requires "racket/base" module for if_mzsch core (fallback to "scheme/base"
    310 if it doesn't exist), "r5rs" module for test and "raco ctool" command for
    311 building Vim.  If MzScheme did not have them, you can install them with
    312 MzScheme's raco command:
    313 >
    314   raco pkg install scheme-lib       # scheme/base module
    315   raco pkg install r5rs-lib         # r5rs module
    316   raco pkg install cext-lib         # raco ctool command
    317 <
    318 ======================================================================
    319   vim:tw=78:ts=8:noet:sts=4:ft=help:norl: