if !exists('g:polyglot_disabled') || index(g:polyglot_disabled, 'julia') == -1 *julia-vim.txt* Support for Julia in Vim Author: Carlo Baldassi License: MIT license {{{ Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. }}} CONTENTS *julia-vim* Introduction |julia-vim-introduction| Block-wise movements/objects |julia-vim-blocks| Keyword-oriented movements |julia-vim-blocks-move| Block-oriented movements |julia-vim-blocks-moveblock| Block text objects |julia-vim-blocks-objects| Variables |julia-vim-blocks-variables| Referring to documents |julia-vim-doc| Extras |julia-vim-extras| Customizations |julia-vim-options| About |julia-vim-about| ============================================================================== INTRODUCTION *julia-vim-introduction* The julia-vim plug-in provides: - basic support for editing Julia files (automatic filetype detection, indentation, syntax highlighting) - support for the |matchit| plugin - support for Julia block-wise movements (i.e. jumping around between Julia blocks like if/end, function/end etc.) and block text-objects - facilities for conversion of LaTeX entries to Unicode symbols which mimic and extend what the Julia REPL and the IJulia notebook interface do. Optionally, this functionality can be used with all file types, not just Julia files. See |julia-vim-L2U|. - a keymapping |K| to refer julia documents. This help file documents: 1) the block-wise movements and objects, how they work and what variables can be used to enable/disable/tweak them; 2) The documentation lookup facility; 3) Some extra functions and customization options. The LaTeX-to-Unicode facilities are documented in |julia-vim-L2U|. ============================================================================== BLOCK-WISE MOVEMENTS AND BLOCK TEXT OBJECTS *julia-vim-blocks* In Julia, all blocks start with a keyword (`module`, `function`, `if`, `for`, `while`, `type`, etc.) and end with the `end` keyword. This plug-in adds support for the |matchit| plugin, such that pressing |%| while on a block keyword will jump to the other keywords pertaining to the same block. For example, if the cursor is at the beginning of the following code: > if a == 1 if b > 0 println("yes") end else println("no") end < then pressing |%| will jump to the `else` keyword, pressing it again will jump to `end`, and pressing it again will go back to the first `if`. Note that the matchit plugin is normally distributed with ViM, but it is disabled by default. To enable it, add this line to your |.vimrc| file: > runtime macros/matchit.vim < The julia-vim plug-in also adds commands to jump around block keywords in normal, operator-pending and visual modes (see |vim-modes|). These are somehow similar to the |]]| and |]m| mappings when used in C and Java files, respectively, but are more powerful. These commands also require that the matchit plugin is enabled. There are two families of block movements, keyword-oriented (see |julia-vim-blocks-move|) and block-oriented (see |julia-vim-blocks-blockmove|). Finally, this plug-in also adds block |text-objects| special mappings, so that whole blocks can be manipulated as a whole when in visual mode or operator-pending mode, see |julia-vim-block-objects|. The block movements and block objects mappings can be collectively disabled, see |g:julia_blocks|, and customized, see |g:julia_blocks_mappings|. NOTE: in all cases, macros at the beginning of a block are considered as part of the block itself. For example, in this code: > @inbounds for i = 1:5 s += v[i] end < the block begins at `@inbounds`. ------------------------------------------------------------------------------ KEYWORD-ORIENTED MOVEMENTS *julia-vim-blocks-move* These movements jump to the following/preceding block keyword, and they differentiate between begin keywords and end keywords. Some block keywords can also be used outside blocks (e.g. `for` in comprehensions, or `end` within indexing expressions): these instances are ignored by these commands. The following movements are provided: *julia_]j* *julia_]J* *julia_[j* *julia_[J* move_n : jumps to the next begin keyword. By default, it is mapped to `]j`. move_N : jumps to the next end keyword. By default, it is mapped to `]J`. move_p : jumps to the preceding begin keyword. By default, it is mapped to `[j`. move_P : jumps to the preceding end keyword. By default, it is mapped to `[J`. Use |g:julia_blocks_mappings| to customize the mappings. ------------------------------------------------------------------------------ BLOCK-ORIENTED MOVEMENTS *julia-vim-blocks-moveblock* These movements are like keyword-oriented movements (|julia-vim-blocks-move|), except that they ignore nested blocks within the block where the cursor is. For example, given the following code (with line annotations): > 1 while true 2 a += 1 3 if a > 5 4 break 5 end 6 end 7 if b == 2 8 return 9 end < if the cursor is on line 2, these movements will ignore the inner `if/end` block (lines 3 to 5). You would then be able to jump directly to lines 1 (with `[[`), 6 (with `][`), 7 (with `]]`), or 9 (with `2][`). The following movements are provided: *julia_]]* *julia_][* *julia_[[* *julia_[]* moveblock_n : gets out from the current block (if any) and jumps to the next begin keyword. (Similar to |w| for word movements.) By default, it is mapped to `]]`. moveblock_N : jumps to the end of the current block, if any. If the cursor is already at the end of a block, jumps to the end of the following block at the same level of the current one, or at the end of the enclosing block. (Similar to |e| for word movements.) By default, it is mapped to `][`. moveblock_p : jumps to the beginning of the current block, if any. If the cursor is already at the beginning of a block, jumps to the beginning of the preceding block at the same level of the current one, or at the beginning of the enclosing block. (Similar to |b| for word movements.) By default, it is mapped to `[[`. moveblock_P : gets out from the current block (if any) and jumps to the preceding end keyword. (Similar to |ge| for word movements.) By default, it is mapped to `[]`. Use |g:julia_blocks_mappings| to customize the mappings. ------------------------------------------------------------------------------ BLOCK TEXT OBJECTS *julia-vim-blocks-objects* The julia-vim plug-in extends the ViM |text-objects| by defining special mappings which allow to operate on blocks as a whole when in visual mode or operator-pending mode. The default mappings use `aj` and `ij` to refer to these objects. For example, given the following code (with line annotations): > 1 while true 2 a += 1 3 if a > 5 4 break 5 end 6 end < if the cursor is on `break` on line 4, pressing `vaj` will select the whole inner `if` block (lines 3 to 5), and pressing `aj` again will select the whole `while` block (lines 1 to 6). The same effect could have been obtained with a counter, i.e. using `v2aj`. If the cursor were initially on line 2, the whole `while` block would have been selected with the first `vaj`. Using `daj` would delete a block, `caj` would delete it and leave ViM in insert mode, `=aj` would indent it, etc. Starting from line 2, pressing `vij` wuold only select the inner part of the `while` block (lines 2 to 5). The following mappings are provided: *julia_aj* *julia_ij* select_a : the block which contains the cursor, including its delimiters. By default, this is mapped to `aj`. Repeated application (e.g. `vajaj`) selects the enclosing blocks. A counter can be used to the same effect as repetition (e.g. `v2aj`). select_i : same as select_a, but only selects the lines included between the delimiters. Thus, this does not work with single-line blocks. By default, this is mapped to `ij`. Repeated application (e.g. `vijij`) has no effect, but using a counter has the same effect as using "select_a" and then selecting the inner part of the outermost block. For example, with the default mappings, `v3ij` is the same as `v3ajij`, or `vajajajij`. Use |g:julia_blocks_mappings| to customize the mappings. The following auxiliary function is only mapped to normal mode: *julia_whereami* whereami : this mapping prints the first line of the current block on the command line. If invoked repeatedly, or if given a count, it prints the first line of the enclosing blocks, like `select_a`. If followed by `select_a`, the selection, or operation, will refer to the last block printed. By default, it is not mapped to any key, but a mapping can be easily provided in |g:julia_blocks_mappings|. It is possible to obtain the string, instead of having it printed, by calling the function `julia_blocks#whereami()`. In such case, use the function `julia_blocks#select_reset()` to reset the block nesting level. ------------------------------------------------------------------------------ VARIABLES *julia-vim-blocks-variables* *g:julia_blocks* g:julia_blocks Determines whether to map block-wise movements and objects. If unspecified, it is on. You can disable the feature by default by inserting the line > let g:julia_blocks = 0 < in your |.vimrc| file. *g:julia_blocks_mappings* g:julia_blocks_mappings Custom mapping for block-wise movements. This must be a |dict| associating movements to key combinations. Use empty strings to disable individual mappings. The following is equivalent to the default mappings (see |julia-vim-blocks-moveblock|, |julia-vim-blocks-move| and |julia-vim-blocks-objects|): > let g:julia_blocks_mappings = { \ "move_n" : "]j", \ "move_N" : "]J", \ "move_p" : "[j", \ "move_P" : "[J", \ \ "moveblock_n" : "]]", \ "moveblock_N" : "][", \ "moveblock_p" : "[[", \ "moveblock_P" : "[]", \ \ "select_a" : "aj", \ "select_i" : "ij", \ \ "whereami" : "", \ } < You can change individual mappings by writing something like this in your |.vimrc| file: > let g:julia_blocks_mappings = { \ "move_N" : "]n", \ "move_P" : "[n", \ "whereami" : "j", \ } < Or you can disable individual mappings by writing something like this in your |.vimrc| file: > let g:julia_blocks_mappings = { \ "moveblock_n" : "", \ "moveblock_p" : "", \ } < All unspecified entries keep their default value. ============================================================================== REFERRING TO DOCUMENTATION *julia-vim-doc* *julia-vim-K* K Look up documentation for the keyword under the cursor. If found, a preview window with the documentation is opened. This also works for keywords within the opened preview window, allowing effortless browsing of the documentation. (This is not really a key mapping, but uses the built-in |keywordprg|-mechanism in vim; see |K| if you're curious). *(JuliaDocPrompt)* (JuliaDocPrompt) Open a prompt for keyword documentation lookup. If you don't use |?| for backward search, you can use the following to make `?` work like in the Julia REPL: > autocmd FileType julia nmap ? (JuliaDocPrompt) < Apply |:augroup| as needed. *:JuliaDoc* :JuliaDoc {keyword} Look up documentation for {keyword}. ============================================================================== EXTRAS *julia-vim-extras* *julia#toggle_function_blockassign* *julia#function_block2assign* *julia#function_assign2block* julia#toggle_function_blockassign() julia#function_block2assign() julia#function_assign2block() These functions allow to transform function definitions between block format and assignment format. For example, these two definitions are equivalent: > function test(x, y) x + 2y end test(x, y) = x + 2y < You can use the function `julia#toggle_function_blockassign()` to switch between the two forms (the cursor needs to be on the first line of the block form). This functionality requires that the |matchit| plugin is loaded. Only three-line function blocks like the one in the example are recognized. When changing the block form into the assignment form, `return` statements are removed; if the result is empty, `nothing` is substituted. Leading macros (e.g. `@inline` or `@compat`) are recognized and preserved by the transformation. In order to make this functionality practical, it is advisable to map it to some key combination, e.g.: > noremap fb :call julia#toggle_function_blockassign() < ============================================================================== CUSTOMIZATIONS *julia-vim-options* The following options allows customizing some aspects of the plugin. *g:julia_spellcheck_docstrings* g:julia_spellcheck_docstrings Determines whether to enable spell-checking for docstrings, i.e. triple quoted strings that start in the first column. See |spell|. Default: on (set to `1`). *g:julia_spellcheck_strings* g:julia_spellcheck_strings Determines whether to enable spell-checking for all strings. See |spell|. Default: off (set to `0`). *g:julia_spellcheck_comments* g:julia_spellcheck_comments Determines whether to enable spell-checking for comments. See |spell|. Default: on (set to `1`). *g:julia_highlight_operators* g:julia_highlight_operators Determines whether to apply syntax highlighting to operators. Default: on (set to `1`). ============================================================================== ABOUT *julia-vim-about* Grab the latest version or report a bug on GitHub: http://github.com/JuliaEditorSupport/julia-vim vim:tw=78:et:ft=help:norl: endif