A comprehensive Vim utility functions for Vim plugins
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
autoload Data.Optional: Expect functions as the alternative of .get_or Oct 14, 2018
benchmark Remove vital#of() from test Dec 16, 2017
data/vital
doc Data.Optional: Expect functions as the alternative of .get_or Oct 14, 2018
plugin vital: revert vital#import() syntax Mar 28, 2016
scripts
test Data.Optional: Expect functions as the alternative of .get_or Oct 14, 2018
.appveyor.yml
.codecov.yml
.coveragerc ci: fix default covimerage data filename Oct 10, 2018
.gitattributes add .gitattributes (ref #102) Aug 17, 2013
.gitignore CI: add drone.io config Oct 28, 2016
.travis.yml CI: Remove perl and Ruby dependencies on Travis CI Jun 11, 2018
Changes Data.Optional: Add the breaking changes to ./Changes Oct 14, 2018
README.md README: Delete authors Jul 30, 2018
reviewdog.yml Integrate spell checker to reviewdog Jun 10, 2017

README.md

vital.vim Build Status Build status codecov

Join the chat at https://gitter.im/vim-jp/vital.vim

A comprehensive Vim utility functions for Vim plugins.

Requirements

Modules in vital.vim basically support Vim 7.4 or later. And some modules have stricter requirements and additional dependencies. Please read the docs of each module before using them.

Handling libraries in Vim WAS hard

Since Vim script has no built-in module system, using external libraries had been troublesome.

  • If you decide to include the libraries in your plugin repository by copy&paste manually: You are responsible for updating the libraries by yourself. sigh You have to find backward-incompatible changes that can break your plugin from every changes between the previous version you installed in the past. super tedious
  • If you want the plugin users to install the dependent libraries: The users will receive additional steps to get it working with your plugin. not easy Even worse, they may fail to install the dependencies properly. a bad dream

What vital.vim does for the problems

vital.vim will embed libraries into your plugin repository and thus your plugin users don't need to install them separately. Additionally, vital.vim can also resolve the dependencies according to the declaration on vital modules.

Concretely, vital.vim resolves the dependencies among vital modules by the module bundler called vitalizer. vitalizer can bundle only necessary modules and can update an existing bundle. On updating the modules, vitalizer shows any breaking changes to help you migrate to the new version of vital modules.

What vital.vim provides

Module Description
Assertion assertion library
Async.Promise An asynchronous operation like ES6 Promise
Bitwise bitwise operators
ConcurrentProcess manages processes concurrently with vimproc
Data.Base64 base64 utilities library
Data.BigNum multi precision integer library
Data.Closure Provide Closure object
Data.Collection Utilities both for list and dict
Data.Counter Counter library to support convenient tallies
Data.Dict dictionary utilities library
Data.Either either value library
Data.LazyList lazy list including file io
Data.List list utilities library
Data.List.Closure Data.List provider for Data.Closure
Data.Optional optional value library
Data.OrderedSet ordered collection library
Data.Set set and frozenset data structure ported from python
Data.String string utilities library
Data.String.Interpolation build string with ${}
Data.Tree tree utilities library
Database.SQLite sqlite utilities library
DateTime date and time library
Experimental.Functor Utilities for functor
Hash.MD5 MD5 encoding
Interpreter.Brainf__k Brainf**k interpreter
Locale.Message very simple message localization library
Mapping Utilities for mapping
Math Mathematical functions
OptionParser Option parser library for Vim
Prelude crucial functions
Process Utilities for process
Random.Mt19937ar random number generator using mt19937ar
Random.Xor128 random number generator using xor128
Random Random utility frontend library
Stream A streaming library
System.Cache An unified cache system
System.File filesystem utilities library
System.Filepath path string utilities library
System.Process A cross-platform process utilities
Text.CSV CSV library
Text.INI INI file library
Text.LTSV LTSV library
Text.Lexer lexer library
Text.Parser parser library
Text.TOML TOML library
Text.Table Character table library
Vim.BufferManager buffer manager
Vim.Buffer Vim's buffer related stuff in general
Vim.Compat Vim compatibility wrapper functions
Vim.Guard Guard options/variables
Vim.Message Vim message functions
Vim.Python +python/+python3 compatibility functions
Vim.ScriptLocal Get script-local things
Vim.Search Vim's [I like function
Vim.ViewTracer Trace window and tabpage
Vim.WindowLayout lays out windows declaratively
Web.HTML HTML parser written in pure Vim script
Web.HTTP simple HTTP client library
Web.JSON JSON parser written in pure Vim script
Web.URI URI manipulation library
Web.XML XML parser written in pure Vim script

... and you can also create your own vital modules. Please see External vital modules for more information.

Let's get started

Install modules for your own plugin

Use :Vitalize to install modules. Please see the help for more details.

:Vitalize --name=your_plugin_name $HOME/.vim/bundle/your_plugin_dir/

You can also install only specified modules; recommended for making your repository size small, assuming you are going to upload it to a remote repository

:Vitalize --name=your_plugin_name $HOME/.vim/bundle/your_plugin_dir/ Data.String Data.List

Use vital functions

Assuming your Vim plugin name is ujihisa. You can define your utility function set ujihisa#util just by

let s:V = vital#ujihisa#new()
function! ujihisa#util#system(...)
  return call(s:V.system, a:000, s:V)
endfunction

and then you can call functions by ujihisa#util#system(), without taking care of vital.vim itself. It's all hidden.

Vital has module system. The below is an example to import/load a module Data.OrderedSet and to call a function f() of the module.

" Recommended way
let s:V = vital#ujihisa#new()
let s:O = s:V.import('Data.OrderedSet')
call s:O.f()

or

" Recommended way only if you rarely use the module
let s:V = vital#ujihisa#new()
call s:V.load('Data.OrderedSet')
call s:V.Data.OrderedSet.f()

or

" Available, but we don't recommend this very much
let s:V = vital#ujihisa#new()
call s:V.import('Data.OrderedSet', s:)
call s:f()

We recommend you to use a capital letter for a Vital module dictionary to assign.

Plugins Using vital.vim

A lot of vim plugins are using vital.vim

Badges

It is not necessary but we recommend to add a badge to your project README to make the vital.vim developers happy ;-) The following is a markdown snippet.

[![Powered by vital.vim](https://img.shields.io/badge/powered%20by-vital.vim-80273f.svg)](https://github.com/vim-jp/vital.vim)

The badge uses Shields.io so you can customize the looks as like:

  • Powered by vital.vim (Default)
  • Powered by vital.vim by adding ?style=plastic
  • Powered by vital.vim by adding ?style=flat
  • Powered by vital.vim by adding ?style=flat-square

If you want to become a vital developer

Become a vital.vim Developer

References

License

NYSL

Japanese original text: http://www.kmonos.net/nysl/

What's NYSL? and Why did we chose it?

NYSL is a very loose license like a Beer License, or more like WTFPL. See NYSL for details. (English and Japanese)

First, vital.vim is a bundling (static) library. We think everyone should be able to use it easily, without worrying about licensing stuff too much.

Second, In Japan, Strict Public Domain might be invalid. You outside Japan may interpret simply the license as Public Domain.

That's why we chose NYSL.

(See https://github.com/vim-jp/vital.vim/issues/26 about the discussion.)