Viml projects

This article describes viml project(plugin) file hierarchy. You may also want to see viml plugins.

Tutorials

steve losh plugin tutorial

https://learnvimscriptthehardway.stevelosh.com/chapters/41.html

Example

# Project Hierarchy
vim-myproject/
  doc/
    vim-myproject.txt
  plugin/
    vim-myproject.vim
  autoload/
    myproject/
      foo.vim
      bar.vim
  tests/
    test_foo.vader
    test_bar.vader

doc/vim-myproject.txt

The helpfile. You'll need to build the search index with :helptags doc/.
For more details, see vim helpfile syntax.

*vim-myproject.txt*                                  A Sample skeleton project.

Author   Mara Jade
License  MIT

================================================================================
CONTENTS                                                      *myproject-contents*
================================================================================

    1.Introduction.....................myproject-intro
        1.1.History
    2.Usage............................myproject-usage
        2.1.Default Key Bindings
    3.Commands.........................myproject-commands


1. INTRODUCTION                                                  *myproject-intro*
================================================================================

    A sample skeleton project, to use as a base for your own plugins.


2. KEY-BINDINGS                                            *myproject-keybindings*
================================================================================
>
    <leader>foo   " runs Foo
    <leader>bar   " runs Bar
<
================================================================================
vim:tw=78:et:ft=help:norl

plugin/vim-myproject.vim

Read on vim startup, this is generally the entrypoint for your plugin (unless it's syntax, indent, etc).

command Foo :call myproject#foo#do_foo()
command Bar :call myproject#bar#do_bar()

nnoremap <leader>foo :Foo<CR>
nnoremap <leader>bar :Bar<CR>

autoload/myproject/*.vim

These files are only read when referenced.
The functions are namespaced, and must match the directory hierarchy.

function! myproject#foo#do_foo()
    return 'foo'
endfunc

function! myproject#bar#do_bar()
    return 'bar'
endfunc

tests/test_*.vader

Your VimPlugin: vader unit tests.

Execute (test foo returns foo):
  AssertEqual my_function("foo"), "foo"

Execute (test bar returns bar):
  AssertEqual my_function("bar"), "bar"

Directories

Basics

viml does not have the concept of packages (like java, python, ...) but instead has plugins.

Plugin shares the same directory structure as your ~/.vim directory, are added to the vim runtime path, and loaded with vim. See /usr/share/vim/vim81 for an example.

example:

~/.vim/bundles/yourplugin/
    autoload/   # source called
    colors/     # colorschemes
    doc/        # vim help files
    ftplugin/   # sourced (into buffer) if filetype matches filename
    plugin/     # sourced on vim-startup
    syntax/     # syntax files
    tools/      # standalone cli tools (like bin/)

    after/{syntax,colors,autoload,...}   # load after vim

autoload/)

Autoload solves the same problem as packages/imports in java/python. These source files are not read until one of their commands is invoked. No sourcing required.

" ~/.vim/bundles/yourplugin/autoload/filesystem/unix.vim
"                                   {filesystem}#{unix}   <-- see

function! filesystem#unix#normalize_path(filepath)
    let normalized_filepath = substitute(a:filepath, '\\', '/', 'g')
    return normalized_filepath
endfunc

calling autoload functions simply refers to the file on the path.

call filesystem#unix#normalize_path('\\a\\b\\c')

ftplugin/

ftplugin files are sourced (locally to buffer) if

• their filename matches current buffer's filetype (ex: 'python.vim' is read when reading a '.py' file)
• they are in a directory whose name matches current buffer's filetype (ex: 'python/pymode.vim' is read when reading a '.py' file)

plugin/

This directory is loaded during vim startup.

You should skip reloading these files if they have already been loaded
otherwise some plugin managers may trip over them.

if exists('XXXXX_plugin_loaded') || &cp
    finish
endif
let XXXXX_plugin_loaded=1