diff options
Diffstat (limited to 'vim73/doc/if_mzsch.txt')
| -rw-r--r-- | vim73/doc/if_mzsch.txt | 259 |
1 files changed, 259 insertions, 0 deletions
diff --git a/vim73/doc/if_mzsch.txt b/vim73/doc/if_mzsch.txt new file mode 100644 index 0000000..52440b6 --- /dev/null +++ b/vim73/doc/if_mzsch.txt @@ -0,0 +1,259 @@ +*if_mzsch.txt* For Vim version 7.3. Last change: 2010 Feb 11 + + + VIM REFERENCE MANUAL by Sergey Khorev + + +The MzScheme Interface to Vim *mzscheme* *MzScheme* + +1. Commands |mzscheme-commands| +2. Examples |mzscheme-examples| +3. Threads |mzscheme-threads| +4. Vim access from MzScheme |mzscheme-vim| +5. mzeval() Vim function |mzscheme-mzeval| +6. Dynamic loading |mzscheme-dynamic| + +{Vi does not have any of these commands} + +The MzScheme interface is available only if Vim was compiled with the +|+mzscheme| feature. + +Based on the work of Brent Fulgham. +Dynamic loading added by Sergey Khorev + +For downloading MzScheme and other info: + http://www.plt-scheme.org/software/mzscheme/ + +Note: On FreeBSD you should use the "drscheme" port. + +============================================================================== +1. Commands *mzscheme-commands* + + *:mzscheme* *:mz* +:[range]mz[scheme] {stmt} + Execute MzScheme statement {stmt}. {not in Vi} + +:[range]mz[scheme] << {endmarker} +{script} +{endmarker} + Execute inlined MzScheme script {script}. + Note: This command doesn't work if the MzScheme + feature wasn't compiled in. To avoid errors, see + |script-here|. + + *:mzfile* *:mzf* +:[range]mzf[ile] {file} Execute the MzScheme script in {file}. {not in Vi} + +All of these commands do essentially the same thing - they execute a piece of +MzScheme code, with the "current range" set to the given line +range. + +In the case of :mzscheme, the code to execute is in the command-line. +In the case of :mzfile, the code to execute is the contents of the given file. + +MzScheme interface defines exception exn:vim, derived from exn. +It is raised for various Vim errors. + +During compilation, the MzScheme interface will remember the current MzScheme +collection path. If you want to specify additional paths use the +'current-library-collection-paths' parameter. E.g., to cons the user-local +MzScheme collection path: > + :mz << EOF + (current-library-collection-paths + (cons + (build-path (find-system-path 'addon-dir) (version) "collects") + (current-library-collection-paths))) + EOF +< + +All functionality is provided through module vimext. + +The exn:vim is available without explicit import. + +To avoid clashes with MzScheme, consider using prefix when requiring module, +e.g.: > + :mzscheme (require (prefix vim- vimext)) +< +All the examples below assume this naming scheme. + + *mzscheme-sandbox* +When executed in the |sandbox|, access to some filesystem and Vim interface +procedures is restricted. + +============================================================================== +2. Examples *mzscheme-examples* +> + :mzscheme (display "Hello") + :mz (display (string-append "Using MzScheme version " (version))) + :mzscheme (require (prefix vim- vimext)) ; for MzScheme < 4.x + :mzscheme (require (prefix-in vim- 'vimext)) ; MzScheme 4.x + :mzscheme (vim-set-buff-line 10 "This is line #10") +< +Inline script usage: > + function! <SID>SetFirstLine() + :mz << EOF + (display "!!!") + (require (prefix vim- vimext)) + ; for newer versions (require (prefix-in vim- 'vimext)) + (vim-set-buff-line 1 "This is line #1") + (vim-beep) + EOF + endfunction + + nmap <F9> :call <SID>SetFirstLine() <CR> +< +File execution: > + :mzfile supascript.scm +< +Vim exception handling: > + :mz << EOF + (require (prefix vim- vimext)) + ; for newer versions (require (prefix-in vim- 'vimext)) + (with-handlers + ([exn:vim? (lambda (e) (display (exn-message e)))]) + (vim-eval "nonsense-string")) + EOF +< +Auto-instantiation of vimext module (can be placed in your |vimrc|): > + function! MzRequire() + :redir => l:mzversion + :mz (version) + :redir END + if strpart(l:mzversion, 1, 1) < "4" + " MzScheme versions < 4.x: + :mz (require (prefix vim- vimext)) + else + " newer versions: + :mz (require (prefix-in vim- 'vimext)) + endif + endfunction + + if has("mzscheme") + silent call MzRequire() + endif +< +============================================================================== +3. Threads *mzscheme-threads* + +The MzScheme interface supports threads. They are independent from OS threads, +thus scheduling is required. The option 'mzquantum' determines how often +Vim should poll for available MzScheme threads. +NOTE +Thread scheduling in the console version of Vim is less reliable than in the +GUI version. + +============================================================================== +4. Vim access from MzScheme *mzscheme-vim* + + *mzscheme-vimext* +The 'vimext' module provides access to procedures defined in the MzScheme +interface. + +Common +------ + (command {command-string}) Perform the vim ":Ex" style command. + (eval {expr-string}) Evaluate the vim expression into + respective MzScheme object: |Lists| are + represented as Scheme lists, + |Dictionaries| as hash tables. + NOTE the name clashes with MzScheme eval + (range-start) Start/End of the range passed with + (range-end) the Scheme command. + (beep) beep + (get-option {option-name} [buffer-or-window]) Get Vim option value (either + local or global, see set-option). + (set-option {string} [buffer-or-window]) + Set a Vim option. String must have option + setting form (like optname=optval, or + optname+=optval, etc.) When called with + {buffer} or {window} the local option will + be set. The symbol 'global can be passed + as {buffer-or-window}. Then |:setglobal| + will be used. + +Buffers *mzscheme-buffer* +------- + (buff? {object}) Is object a buffer? + (buff-valid? {object}) Is object a valid buffer? (i.e. + corresponds to the real Vim buffer) + (get-buff-line {linenr} [buffer]) + Get line from a buffer. + (set-buff-line {linenr} {string} [buffer]) + Set a line in a buffer. If {string} is #f, + the line gets deleted. The [buffer] + argument is optional. If omitted, the + current buffer will be used. + (get-buff-line-list {start} {end} [buffer]) + Get a list of lines in a buffer. {Start} + and {end} are 1-based and inclusive. + (set-buff-line-list {start} {end} {string-list} [buffer]) + Set a list of lines in a buffer. If + string-list is #f or null, the lines get + deleted. If a list is shorter than + {end}-{start} the remaining lines will + be deleted. + (get-buff-name [buffer]) Get a buffer's text name. + (get-buff-num [buffer]) Get a buffer's number. + (get-buff-size [buffer]) Get buffer line count. + (insert-buff-line-list {linenr} {string/string-list} [buffer]) + Insert a list of lines into a buffer after + {linenr}. If {linenr} is 0, lines will be + inserted at start. + (curr-buff) Get the current buffer. Use other MzScheme + interface procedures to change it. + (buff-count) Get count of total buffers in the editor. + (get-next-buff [buffer]) Get next buffer. + (get-prev-buff [buffer]) Get previous buffer. Return #f when there + are no more buffers. + (open-buff {filename}) Open a new buffer (for file "name") + (get-buff-by-name {buffername}) Get a buffer by its filename or #f + if there is no such buffer. + (get-buff-by-num {buffernum}) Get a buffer by its number (return #f if + there is no buffer with this number). + +Windows *mzscheme-window* +------ + (win? {object}) Is object a window? + (win-valid? {object}) Is object a valid window (i.e. corresponds + to the real Vim window)? + (curr-win) Get the current window. + (win-count) Get count of windows. + (get-win-num [window]) Get window number. + (get-win-by-num {windownum}) Get window by its number. + (get-win-buffer [window]) Get the buffer for a given window. + (get-win-height [window]) + (set-win-height {height} [window]) Get/Set height of window. + (get-win-width [window]) + (set-win-width {width} [window])Get/Set width of window. + (get-win-list [buffer]) Get list of windows for a buffer. + (get-cursor [window]) Get cursor position in a window as + a pair (linenr . column). + (set-cursor (line . col) [window]) Set cursor position. + +============================================================================== +5. mzeval() Vim function *mzscheme-mzeval* + +To facilitate bi-directional interface, you can use |mzeval()| function to +evaluate MzScheme expressions and pass their values to VimL. + +============================================================================== +6. Dynamic loading *mzscheme-dynamic* *E815* + +On MS-Windows the MzScheme libraries can be loaded dynamically. The |:version| +output then includes |+mzscheme/dyn|. + +This means that Vim will search for the MzScheme DLL files only when needed. +When you don't use the MzScheme interface you don't need them, thus you can +use Vim without these DLL files. + +To use the MzScheme interface the MzScheme DLLs must be in your search path. +In a console window type "path" to see what directories are used. + +The names of the DLLs must match the MzScheme version Vim was compiled with. +For MzScheme version 209 they will be "libmzsch209_000.dll" and +"libmzgc209_000.dll". To know for sure look at the output of the ":version" +command, look for -DDYNAMIC_MZSCH_DLL="something" and +-DDYNAMIC_MZGC_DLL="something" in the "Compilation" info. + +====================================================================== + vim:tw=78:ts=8:sts=4:ft=help:norl: |