blob: d31815a291118249cdcaa4a21f5d36d7f455a289 [file] [log] [blame]
Bram Moolenaar325b7a22004-07-05 15:58:32 +00001*if_mzsch.txt* For Vim version 7.0aa. Last change: 2004 Jul 05
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. The Vim access procedures |mzscheme-vim|
13
14{Vi does not have any of these commands}
15
16The MzScheme interface is available only if Vim was compiled with the
17|+mzscheme| feature.
18
19Based on the work of Brent Fulgham.
20
21For downloading MzScheme and other info:
22 http://www.plt-scheme.org/software/mzscheme/
23
24==============================================================================
251. Commands *mzscheme-commands*
26
27 *:mzscheme* *:mz*
28:[range]mz[scheme] {stmt}
29 Execute MzScheme statement {stmt}. {not in Vi}
30
31:[range]mz[scheme] << {endmarker}
32{script}
33{endmarker}
34 Execute inlined MzScheme script {script}.
35 Note: This command doesn't work if the MzScheme
36 feature wasn't compiled in. To avoid errors, see
37 |script-here|.
38
39 *:mzfile* *:mzf*
40:[range]mzf[ile] {file} Execute the MzScheme script in {file}. {not in Vi}
41 All statements are executed in the namespace of the
42 buffer that was current during :mzfile start.
43 If you want to access other namespaces, use
44 'parameterize'.
45
46All of these commands do essentially the same thing - they execute a piece of
47MzScheme code, with the "current range" set to the given line
48range.
49
50In the case of :mzscheme, the code to execute is in the command-line.
51In the case of :mzfile, the code to execute is the contents of the given file.
52
53Each buffer has its own MzScheme namespace. Global namespace is bound to
54the `global-namespace' value from the 'vimext' module.
55MzScheme interface defines exception exn:vim, derived from exn.
56It is raised for various Vim errors.
57
58During compilation, the MzScheme interface will remember the current MzScheme
59collection path. If you want to specify additional paths use the
60'current-library-collection-paths' parameter. E.g., to cons the user-local
61MzScheme collection path: >
62 :mz << EOF
63 (current-library-collection-paths
64 (cons
65 (build-path (find-system-path 'addon-dir) (version) "collects")
66 (current-library-collection-paths)))
67 EOF
68<
69
70All functionality is provided through module vimext.
71
72The exn:vim is available without explicit import.
73
74To avoid clashes with MzScheme, consider using prefix when requiring module,
75e.g.: >
76 :mzscheme (require (prefix vim- vimext))
77<
78All the examples below assume this naming scheme. Note that you need to do
79this again for every buffer.
80
81The auto-instantiation can be achieved with autocommands, e.g. you can put
Bram Moolenaar3fdfa4a2004-10-07 21:02:47 +000082something like this in your .vimrc (EOFs should not have indentation): >
83 function s:MzRequire()
84 if has("mzscheme")
85 :mz << EOF
86 (require (prefix vim- vimext))
87 (let ((buf (vim-get-buff-by-name (vim-eval "expand(\"<afile>\")"))))
88 (when (and buf (not (eq? buf (vim-curr-buff))))
89 (parameterize ((current-namespace (vim-get-buff-namespace buf)))
90 (namespace-attach-module vim-global-namespace 'vimext)
91 (namespace-require '(prefix vim vimext)))))
92 EOF
93 endif
94 endfunction
95
96 function s:MzStartup()
97 if has("mzscheme")
98 au BufNew,BufNewFile,BufAdd,BufReadPre * :call s:MzRequire()
99 :mz << EOF
100 (current-library-collection-paths
101 (cons
102 (build-path (find-system-path 'addon-dir) (version) "collects")
103 (current-library-collection-paths)))
104 EOF
105 endif
106 endfunction
107
108 call s:MzStartup()
Bram Moolenaar325b7a22004-07-05 15:58:32 +0000109<
110
111The global namespace just instantiated this module with the prefix "vimext:".
112
113==============================================================================
1142. Examples *mzscheme-examples*
115>
116 :mzscheme (display "Hello")
117 :mzscheme (vim-set-buff-line 10 "This is line #10")
118<
119Inline script usage: >
120 function! <SID>SetFirstLine()
121 :mz << EOF
122 (display "!!!")
123 (vim-set-buff-line 1 "This is line #1")
124 (vim-beep)
125 EOF
126 endfunction
127
128 nmap <F9> :call <SID>SetFirstLine() <CR>
129<
130File execution: >
131 :mzfile supascript.scm
132<
133Accessing the current buffer namespace from an MzScheme program running in
134another buffer within |:mzfile|-executed script : >
135 ; Move to the window below
136 (vim-command "wincmd j")
137 ; execute in the context of buffer, to which window belongs
138 ; assume that buffer has 'textstring' defined
139 (parameterize ((current-namespace
140 (vim-get-buff-namespace (vim-curr-buff))))
141 (eval '(vim-set-buff-line 1 textstring)))
142<
143
144==============================================================================
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==============================================================================
1555. VIM Functions *mzscheme-vim*
156
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.
164 (eval {expr-string}) Evaluate the vim command string.
165 NOTE clashes with MzScheme eval
166 (range-start) Start/End of the range passed with
167 (range-end) the Scheme command.
168 (beep) beep
169 (get-option {option-name} [buffer-or-window]) Get Vim option value (either
170 local or global, see set-option).
171 (set-option {string} [buffer-or-window])
172 Set a Vim option. String must have option
173 setting form (like optname=optval, or
174 optname+=optval, etc.) When called with
175 {buffer} or {window} the local option will
176 be set. The symbol 'global can be passed
177 as {buffer-or-window}. Then |:setglobal|
178 will be used.
179 global-namespace The MzScheme main namespace.
180
181Buffers *mzscheme-buffer*
182-------
183 (buff? {object}) Is object a buffer?
184 (buff-valid? {object}) Is object a valid buffer? (i.e.
185 corresponds to the real Vim buffer)
186 (get-buff-line {linenr} [buffer])
187 Get line from a buffer.
188 (set-buff-line {linenr} {string} [buffer])
189 Set a line in a buffer. If {string} is #f,
190 the line gets deleted. The [buffer]
191 argument is optional. If omitted, the
192 current buffer will be used.
193 (get-buff-line-list {start} {end} [buffer])
194 Get a list of lines in a buffer. {Start}
195 and {end} are 1-based. {Start} is
196 inclusive, {end} - exclusive.
197 (set-buff-line-list {start} {end} {string-list} [buffer])
198 Set a list of lines in a buffer. If
199 string-list is #f or null, the lines get
200 deleted. If a list is shorter than
201 {end}-{start} the remaining lines will
202 be deleted.
203 (get-buff-name [buffer]) Get a buffer's text name.
204 (get-buff-num [buffer]) Get a buffer's number.
205 (get-buff-size [buffer]) Get buffer line count.
206 (insert-buff-line-list {linenr} {string/string-list} [buffer])
207 Insert a list of lines into a buffer after
208 {linenr}. If {linenr} is 0, lines will be
209 inserted at start.
210 (curr-buff) Get the current buffer. Use procedures
211 from `vimcmd' module to change it.
212 (buff-count) Get count of total buffers in the editor.
213 (get-next-buff [buffer]) Get next buffer.
214 (get-prev-buff [buffer]) Get previous buffer. Return #f when there
215 are no more buffers.
216 (open-buff {filename}) Open a new buffer (for file "name")
217 (get-buff-by-name {buffername}) Get a buffer by its filename or #f
218 if there is no such buffer.
219 (get-buff-by-num {buffernum}) Get a buffer by its number (return #f if
220 there is no buffer with this number).
221 (get-buff-namespace [buffer]) Get buffer namespace.
222
223Windows *mzscheme-window*
224------
225 (win? {object}) Is object a window?
226 (win-valid? {object}) Is object a valid window (i.e. corresponds
227 to the real Vim window)?
228 (curr-win) Get the current window.
229 (win-count) Get count of windows.
230 (get-win-num [window]) Get window number.
231 (get-win-by-num {windownum}) Get window by its number.
232 (get-win-buffer [window]) Get the buffer for a given window.
233 (get-win-height [window])
234 (set-win-height {height} [window]) Get/Set height of window.
235 (get-win-width [window])
236 (set-win-width {width} [window])Get/Set width of window.
237 (get-win-list [buffer]) Get list of windows for a buffer.
238 (get-cursor [window]) Get cursor position in a window as
239 a pair (linenr . column).
240 (set-cursor (line . col) [window]) Set cursor position.
241
242======================================================================
243 vim:tw=78:ts=8:sts=4:ft=help:norl: