share/vim/vim72/doc/if_mzsch.txt

   1 *if_mzsch.txt*  For Vim version 7.2.  Last change: 2008 Jun 28
   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. The Vim access procedures            |mzscheme-vim|
  13 5. Dynamic loading                      |mzscheme-dynamic|
  14
  15 {Vi does not have any of these commands}
  16
  17 The MzScheme interface is available only if Vim was compiled with the
  18 |+mzscheme| feature.
  19
  20 Based on the work of Brent Fulgham.
  21 Dynamic loading added by Sergey Khorev
  22
  23 For downloading MzScheme and other info:
  24         http://www.plt-scheme.org/software/mzscheme/
  25
  26 Note: On FreeBSD you should use the "drscheme" port.
  27
  28 ==============================================================================
  29 1. Commands                                             *mzscheme-commands*
  30
  31                                                         *:mzscheme* *:mz*
  32 :[range]mz[scheme] {stmt}
  33                         Execute MzScheme statement {stmt}.  {not in Vi}
  34
  35 :[range]mz[scheme] << {endmarker}
  36 {script}
  37 {endmarker}
  38                         Execute inlined MzScheme script {script}.
  39                         Note: This command doesn't work if the MzScheme
  40                         feature wasn't compiled in.  To avoid errors, see
  41                         |script-here|.
  42
  43                                                         *:mzfile* *:mzf*
  44 :[range]mzf[ile] {file} Execute the MzScheme script in {file}.  {not in Vi}
  45                         All statements are executed in the namespace of the
  46                         buffer that was current during :mzfile start.
  47                         If you want to access other namespaces, use
  48                         'parameterize'.
  49
  50 All of these commands do essentially the same thing - they execute a piece of
  51 MzScheme code, with the "current range" set to the given line
  52 range.
  53
  54 In the case of :mzscheme, the code to execute is in the command-line.
  55 In the case of :mzfile, the code to execute is the contents of the given file.
  56
  57 Each buffer has its own MzScheme namespace. Global namespace is bound to
  58 the "global-namespace" value from the 'vimext' module.
  59 MzScheme interface defines exception exn:vim, derived from exn.
  60 It is raised for various Vim errors.
  61
  62 During compilation, the MzScheme interface will remember the current MzScheme
  63 collection path. If you want to specify additional paths use the
  64 'current-library-collection-paths' parameter. E.g., to cons the user-local
  65 MzScheme collection path: >
  66     :mz << EOF
  67     (current-library-collection-paths
  68         (cons
  69             (build-path (find-system-path 'addon-dir) (version) "collects")
  70             (current-library-collection-paths)))
  71     EOF
  72 <
  73
  74 All functionality is provided through module vimext.
  75
  76 The exn:vim is available without explicit import.
  77
  78 To avoid clashes with MzScheme, consider using prefix when requiring module,
  79 e.g.: >
  80         :mzscheme (require (prefix vim- vimext))
  81 <
  82 All the examples below assume this naming scheme.  Note that you need to do
  83 this again for every buffer.
  84
  85 The auto-instantiation can be achieved with autocommands, e.g. you can put
  86 something like this in your .vimrc (EOFs should not have indentation): >
  87     function s:MzRequire()
  88         if has("mzscheme")
  89             :mz << EOF
  90             (require (prefix vim- vimext))
  91             (let ((buf (vim-get-buff-by-name (vim-eval "expand(\"<afile>\")"))))
  92               (when (and buf (not (eq? buf (vim-curr-buff))))
  93                 (parameterize ((current-namespace (vim-get-buff-namespace buf)))
  94                   (namespace-attach-module vim-global-namespace 'vimext)
  95                   (namespace-require '(prefix vim vimext)))))
  96     EOF
  97         endif
  98     endfunction
  99
 100     function s:MzStartup()
 101         if has("mzscheme")
 102             au BufNew,BufNewFile,BufAdd,BufReadPre * :call s:MzRequire()
 103             :mz << EOF
 104             (current-library-collection-paths
 105                 (cons
 106                     (build-path (find-system-path 'addon-dir) (version) "collects")
 107                     (current-library-collection-paths)))
 108     EOF
 109         endif
 110     endfunction
 111
 112     call s:MzStartup()
 113 <
 114
 115 The global namespace just instantiated this module with the prefix "vimext:".
 116                                                         *mzscheme-sandbox*
 117 When executed in the |sandbox|, access to some filesystem and Vim interface
 118 procedures is restricted.
 119
 120 ==============================================================================
 121 2. Examples                                             *mzscheme-examples*
 122 >
 123         :mzscheme (display "Hello")
 124         :mzscheme (vim-set-buff-line 10 "This is line #10")
 125 <
 126 Inline script usage: >
 127         function! <SID>SetFirstLine()
 128             :mz << EOF
 129             (display "!!!")
 130             (vim-set-buff-line 1 "This is line #1")
 131             (vim-beep)
 132             EOF
 133         endfunction
 134
 135         nmap <F9> :call <SID>SetFirstLine() <CR>
 136 <
 137 File execution: >
 138         :mzfile supascript.scm
 139 <
 140 Accessing the current buffer namespace from an MzScheme program running in
 141 another buffer within |:mzfile|-executed script : >
 142         ; Move to the window below
 143         (vim-command "wincmd j")
 144         ; execute in the context of buffer, to which window belongs
 145         ; assume that buffer has 'textstring' defined
 146         (parameterize ((current-namespace
 147                         (vim-get-buff-namespace (vim-curr-buff))))
 148          (eval '(vim-set-buff-line 1 textstring)))
 149 <
 150
 151 ==============================================================================
 152 3. Threads                                              *mzscheme-threads*
 153
 154 The MzScheme interface supports threads. They are independent from OS threads,
 155 thus scheduling is required. The option 'mzquantum' determines how often
 156 Vim should poll for available MzScheme threads.
 157 NOTE
 158 Thread scheduling in the console version of Vim is less reliable than in the
 159 GUI version.
 160
 161 ==============================================================================
 162 5. VIM Functions                                        *mzscheme-vim*
 163
 164                                                         *mzscheme-vimext*
 165 The 'vimext' module provides access to procedures defined in the MzScheme
 166 interface.
 167
 168 Common
 169 ------
 170     (command {command-string})      Perform the vim ":Ex" style command.
 171     (eval {expr-string})            Evaluate the vim expression to a string.
 172                                     A |List| is turned into a string by
 173                                     joining the items and inserting line
 174                                     breaks.
 175                                     NOTE clashes with MzScheme eval
 176     (range-start)                   Start/End of the range passed with
 177     (range-end)                     the Scheme command.
 178     (beep)                          beep
 179     (get-option {option-name} [buffer-or-window]) Get Vim option value (either
 180                                     local or global, see set-option).
 181     (set-option {string} [buffer-or-window])
 182                                     Set a Vim option. String must have option
 183                                     setting form (like optname=optval, or
 184                                     optname+=optval, etc.) When called with
 185                                     {buffer} or {window} the local option will
 186                                     be set. The symbol 'global can be passed
 187                                     as {buffer-or-window}. Then |:setglobal|
 188                                     will be used.
 189     global-namespace                The MzScheme main namespace.
 190
 191 Buffers                                                  *mzscheme-buffer*
 192 -------
 193     (buff? {object})                Is object a buffer?
 194     (buff-valid? {object})          Is object a valid buffer? (i.e.
 195                                     corresponds to the real Vim buffer)
 196     (get-buff-line {linenr} [buffer])
 197                                     Get line from a buffer.
 198     (set-buff-line {linenr} {string} [buffer])
 199                                     Set a line in a buffer. If {string} is #f,
 200                                     the line gets deleted.  The [buffer]
 201                                     argument is optional. If omitted, the
 202                                     current buffer will be used.
 203     (get-buff-line-list {start} {end} [buffer])
 204                                     Get a list of lines in a buffer. {Start}
 205                                     and {end} are 1-based. {Start} is
 206                                     inclusive, {end} - exclusive.
 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 procedures
 221                                     from "vimcmd" module 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     (get-buff-namespace [buffer])   Get buffer namespace.
 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. Dynamic loading                                      *mzscheme-dynamic*
 254
 255 On MS-Windows the MzScheme libraries can be loaded dynamically. The |:version|
 256 output then includes |+mzscheme/dyn|.
 257
 258 This means that Vim will search for the MzScheme DLL files only when needed.
 259 When you don't use the MzScheme interface you don't need them, thus you can
 260 use Vim without these DLL files.
 261
 262 To use the MzScheme interface the MzScheme DLLs must be in your search path.
 263 In a console window type "path" to see what directories are used.
 264
 265 The names of the DLLs must match the MzScheme version Vim was compiled with.
 266 For MzScheme version 209 they will be "libmzsch209_000.dll" and
 267 "libmzgc209_000.dll". To know for sure look at the output of the ":version"
 268 command, look for -DDYNAMIC_MZSCH_DLL="something" and
 269 -DDYNAMIC_MZGC_DLL="something" in the "Compilation" info.
 270
 271 ======================================================================
 272   vim:tw=78:ts=8:sts=4:ft=help:norl: