*vim-vue-plugin.txt*  Syntax and indent for Vue files

Author: leafOfTree
License: The Unlicense

==============================================================================
CONTENTS                                            *vim-vue-plugin-contents*

  1. Introduction ............................... |vim-vue-plugin-intro|
  2. Configuration .............................. |vim-vue-plugin-config|
  3. Functions .................................. |vim-vue-plugin-functions|
  4. Avoid overload ............................. |vim-vue-plugin-overload|

==============================================================================
1. Introduction                                        *vim-vue-plugin-intro*

Vim syntax and indent plugin for `.vue` files, also `.wpy` files. It loads
multiple syntax and indent files for `.vue` and enables them to work
together, with

- Blocks, both <template>/<script>/<style> and custom blocks, with any
  syntax by lang="...", like pug, typescript, coffee, scss, sass, less and
  stylus. Syntax plugins need to be installed if not provided by Vim.
- Attribute, directive and keyword highlight.
- emmet-vim html/javascript/css filetype detection.
- Functions to get the current tag or syntax, see
  |vim-vue-plugin-functions|.
- A builtin 'foldexpr'.

'filetype' is set to `vue`. Add this plugin to the start of 'runtimepath'
when installing manually, as Vim 9 and Neovim come with placeholder `vue`
syntax and indent files: >

  set rtp^=path/to/this_plugin
<
==============================================================================
2. Configuration                                      *vim-vue-plugin-config*

                                                    *g:vim_vue_plugin_config*
g:vim_vue_plugin_config is the only configuration, set before opening a vue
file. Its default value: >

  let g:vim_vue_plugin_config = {
        \'syntax': {
        \   'template': ['html'],
        \   'script': ['javascript'],
        \   'style': ['css'],
        \},
        \'full_syntax': [],
        \'initial_indent': [],
        \'attribute': 0,
        \'keyword': 0,
        \'foldexpr': 0,
        \'debug': 0,
        \}
<
syntax
  Block tag name to its syntax list. A string can be used for a list with
  one item.
  - lang="..." on the block tag decides the syntax, in double or single
    quotes or without quotes. `typescript` matches lang="ts" and
    lang="typescript".
  - Without lang="...", or if it's not in the list, the first syntax is
    used.
  - Syntax files are loaded only from $VIMRUNTIME/syntax, ~/.vim/syntax and
    $VIM/vimfiles/syntax, or from all of 'runtimepath', including plugins,
    if not found there.
  - Each key replaces the default of the same key, so >
      {'syntax': {'script': ['javascript', 'typescript']}}
<    keeps `template` as ['html'] and `style` as ['css']. Set a key to [] to
    remove the block.

full_syntax
  Syntax list whose files are always loaded from all of 'runtimepath'.

initial_indent
  Block tag, syntax or tag.syntax like `i18n.json` to indent one level
  initially. For `.wpy` files, it defaults to ['script', 'style'].

attribute
  1 to highlight attribute values as expression instead of string.

keyword
  1 to highlight keywords like `data` and `methods`.

foldexpr
  1 to use the builtin 'foldexpr' with 'foldmethod' set to `expr`.

debug
  1 to echo debug messages in |:messages|.

Example, only for demo. Set syntax as little as possible for performance: >

  let g:vim_vue_plugin_config = {
        \'syntax': {
        \   'template': ['html', 'pug'],
        \   'script': ['javascript', 'typescript', 'coffee'],
        \   'style': ['css', 'scss', 'sass', 'less', 'stylus'],
        \   'i18n': ['json', 'yaml'],
        \   'route': 'json',
        \},
        \'full_syntax': ['json'],
        \'initial_indent': ['i18n', 'i18n.json', 'yaml'],
        \'attribute': 1,
        \'keyword': 1,
        \'foldexpr': 1,
        \}
<
Options can be changed later like global variables: >

  let g:vim_vue_plugin_config.foldexpr = 0
<
==============================================================================
3. Functions                                       *vim-vue-plugin-functions*

As there is more than one language in a `.vue` file, different mappings,
completion and local options may be wanted by tags or syntax, the current
language.

                                                                *GetVueTag()*
GetVueTag([{lnum}])
  Return the block tag at line {lnum}, or the cursor line, like
  `'template'`, `'script'`, `'style'`, or `''`. Example: >

  autocmd FileType vue inoremap <buffer><expr> : InsertColon()

  function! InsertColon()
    let tag = GetVueTag()
    return tag == 'template' ? ':' : ': '
  endfunction
<
                                                             *GetVueSyntax()*
                                                            *GetVueSubtype()*
GetVueSyntax()
  Return the syntax at the cursor line, like `'html'`, `'javascript'`,
  `'css'`, `'scss'`. GetVueSubtype() is its previous name.

                                                        *OnChangeVueSyntax()*
                                                       *OnChangeVueSubtype()*
OnChangeVueSyntax({syntax})
  If defined in your vimrc, it is called whenever the syntax under the
  cursor changes. OnChangeVueSubtype() is its previous name. Example: >

  function! OnChangeVueSyntax(syntax)
    if a:syntax == 'html'
      setlocal commentstring=<!--%s-->
    elseif a:syntax =~ 'css'
      setlocal commentstring=/*%s*/
    else
      setlocal commentstring=//%s
    endif
  endfunction
<
==============================================================================
4. Avoid overload                                   *vim-vue-plugin-overload*

Most delays come from loading syntax files of many languages.
`b:current_loading_main_syntax` is set to `vue` while loading, which can be
used as a condition in syntax files that load others. For example, the
builtin sass.vim and less.vim load css.vim, which this plugin has loaded: >

  if !exists("b:current_loading_main_syntax")
    runtime! syntax/css.vim
  endif
<
 vim:tw=78:ts=8:ft=help:norl: