diff options
Diffstat (limited to 'doc/julia-vim.txt')
| -rw-r--r-- | doc/julia-vim.txt | 484 |
1 files changed, 0 insertions, 484 deletions
diff --git a/doc/julia-vim.txt b/doc/julia-vim.txt deleted file mode 100644 index 5cf181d0..00000000 --- a/doc/julia-vim.txt +++ /dev/null @@ -1,484 +0,0 @@ -if !exists('g:polyglot_disabled') || index(g:polyglot_disabled, 'julia') == -1 - -*julia-vim.txt* Support for Julia in Vim - -Author: Carlo Baldassi <carlobaldassi@gmail.com> -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" : "<Leader>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). - - - *<Plug>(JuliaDocPrompt)* -<Plug>(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 <buffer> ? <Plug>(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 <Leader>fb :call julia#toggle_function_blockassign()<CR> -< - -============================================================================== -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`). - - *g:julia_indent_align_import* -g:julia_indent_align_import - - In a multi-line import/using/export statment, the lines after - the first one use some special alignment rules by default, - e.g.: -> - import X: one, - two, - three - export four, - five, - six -< - When `g:julia_indent_align_import` is `0` instead, the usual - indentation is used: -> - import X: one, - two, - three - export four, - five, - six - - *g:julia_indent_align_brackets* -g:julia_indent_align_brackets - - In a multi-line bracketed expression (except for function - arguments, see |g:julia_indent_align_funcargs|), the lines - after the first one use some special alignment rules by - default, e.g.: -> - matrix = [1 2 3; - 4 5 6] - tpl = ( - abc = Dict(a=>1, - b=>2), - def = [1 2; - 3 4], - xyz = SubArray{eltype(P), - N, P, I, - false} - ) -< - When `g:julia_indent_align_brackets` is `0` instead, an extra - indent is used: -> - matrix = [1 2 3; - 4 5 6] - tpl = ( - abc = Dict(a=>1, - b=>2), - def = [1 2; - 3 4], - xyz = SubArray{eltype(P), - N, P, I, - false} - ) -< - - *g:julia_indent_align_funcargs* -g:julia_indent_align_funcargs - - In a function definition, when the arguments span multiple - lines, the lines after the first one get an extra indentation - step by default, e.g.: -> - function functionanme( - arg1, arg2, - arg3, arg4 - ) - # function body - end -< - By setting `g:julia_indent_align_funcargs` to `1`, the - arguments are aligned to the bracket instead (they work as any - other bracket with the default value of - |g:julia_indent_align_brackets|): -> - function functionanme(arg1, arg2, - arg3, arg4 - ) - # function body - end -< - -============================================================================== -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 |