summaryrefslogtreecommitdiffstats
path: root/runtime/doc/if_mzsch.txt
diff options
context:
space:
mode:
Diffstat (limited to 'runtime/doc/if_mzsch.txt')
-rw-r--r--runtime/doc/if_mzsch.txt318
1 files changed, 318 insertions, 0 deletions
diff --git a/runtime/doc/if_mzsch.txt b/runtime/doc/if_mzsch.txt
new file mode 100644
index 0000000..9e9b252
--- /dev/null
+++ b/runtime/doc/if_mzsch.txt
@@ -0,0 +1,318 @@
+*if_mzsch.txt* For Vim version 9.0. Last change: 2020 Oct 14
+
+
+ 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. Using Function references |mzscheme-funcref|
+7. Dynamic loading |mzscheme-dynamic|
+8. MzScheme setup |mzscheme-setup|
+
+{only available when Vim was compiled with the |+mzscheme| feature}
+
+Based on the work of Brent Fulgham.
+Dynamic loading added by Sergey Khorev
+
+MzScheme and PLT Scheme names have been rebranded as Racket. For more
+information please check http://racket-lang.org
+
+Futures and places of Racket version 5.x up to and including 5.3.1 do not
+work correctly with processes created by Vim.
+The simplest solution is to build Racket on your own with these features
+disabled: >
+ ./configure --disable-futures --disable-places --prefix=your-install-prefix
+
+To speed up the process, you might also want to use --disable-gracket and
+--disable-docs
+
+==============================================================================
+1. Commands *mzscheme-commands*
+
+ *:mzscheme* *:mz*
+:[range]mz[scheme] {stmt}
+ Execute MzScheme statement {stmt}.
+
+:[range]mz[scheme] << [trim] [{endmarker}]
+{script}
+{endmarker}
+ Execute inlined MzScheme script {script}.
+ Note: This command doesn't work when the MzScheme
+ feature wasn't compiled in. To avoid errors, see
+ |script-here|.
+
+ If [endmarker] is omitted from after the "<<", a dot
+ '.' must be used after {script}, like for the
+ |:append| and |:insert| commands. Refer to
+ |:let-heredoc| for more information.
+
+
+ *:mzfile* *:mzf*
+:[range]mzf[ile] {file} Execute the MzScheme script in {file}.
+
+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")
+
+To see what version of MzScheme you have: >
+ :mzscheme (display (version))
+<
+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,
+ |Funcref|s as functions (see also
+ |mzscheme-funcref|)
+ NOTE the name clashes with MzScheme eval,
+ use module qualifiers to overcome this.
+ (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 Vim script.
+
+==============================================================================
+6. Using Function references *mzscheme-funcref*
+
+MzScheme interface allows use of |Funcref|s so you can call Vim functions
+directly from Scheme. For instance: >
+ function! MyAdd2(arg)
+ return a:arg + 2
+ endfunction
+ mz (define f2 (vim-eval "function(\"MyAdd2\")"))
+ mz (f2 7)
+< or : >
+ :mz (define indent (vim-eval "function('indent')"))
+ " return Vim indent for line 12
+ :mz (indent 12)
+<
+
+==============================================================================
+7. 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.
+NOTE: Newer version of MzScheme (Racket) require earlier (trampolined)
+initialisation via scheme_main_setup. So Vim always loads the MzScheme DLL at
+startup if possible. This may make Vim startup slower.
+
+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.
+
+On MS-Windows the options 'mzschemedll' and 'mzschemegcdll' are used for the
+name of the library to load. The initial value is specified at build time.
+
+The version of the DLL 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.
+
+For example, if MzScheme (Racket) is installed at C:\Racket63, you may need
+to set the environment variable as the following: >
+
+ PATH=%PATH%;C:\Racket63\lib
+ PLTCOLLECTS=C:\Racket63\collects
+ PLTCONFIGDIR=C:\Racket63\etc
+<
+==============================================================================
+8. MzScheme setup *mzscheme-setup* *E895*
+
+Vim requires "racket/base" module for if_mzsch core (fallback to "scheme/base"
+if it doesn't exist), "r5rs" module for test and "raco ctool" command for
+building Vim. If MzScheme did not have them, you can install them with
+MzScheme's raco command:
+>
+ raco pkg install scheme-lib # scheme/base module
+ raco pkg install r5rs-lib # r5rs module
+ raco pkg install cext-lib # raco ctool command
+<
+======================================================================
+ vim:tw=78:ts=8:noet:sts=4:ft=help:norl: