*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|
Extra syntax colors                 |julia-vim-extra-colors|
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-moveblock|).

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-blocks-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` would 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/public 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
<
                                                  *g:julia_set_indentation*
g:julia_set_indentation

                In Julia manual, it is recommended to use 4 spaces to indent
                Julia source files.
                By default, the 4-space indentation style is applied.
                Set `g:julia_set_indentation` to `0` to disable this feature.
==============================================================================
EXTRA SYNTAX COLORS                                *julia-vim-extra-colors*

Some syntax elements are recognized but not highlighted by default:

  juliaParDelim       parentheses
  juliaSemicolon      semicolons
  juliaComma          commas
  juliaFunctionCall   function calls

In order to highlight them, just use the |hi| command in your configuration
file. To use existing highlight groups (see |group-name|), you can do e.g.:
>
  hi link juliaParDelim Delimiter
  hi link juliaSemicolon Operator
  hi link juliaFunctionCall Identifier
<

The above will use the colors specified by your colorscheme, if defined.
If you want to define a color manually instead, you can use something like
this:
>
  hi juliaFunctionCall guifg=#AB5033 ctermfg=Red
<

==============================================================================
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: