vital.vim

A comprehensive Vim utility functions for Vim plugins.

Requirements

Modules in vital.vim basically support Vim 8.2 or later. We guarantee that the following versions of Vim are supported:

The latest major version (9.0.*)
The previous major version (8.2.*)

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
Color	color conversion library between RGB/HSL/terminal code
ConcurrentProcess	manages processes concurrently with vimproc
Data.Base64	base64 utilities library
Data.Base64.RFC4648	base64 RFC4648 utilities library
Data.Base64.URLSafe	base64 URLSafe utilities library
Data.Base32	base32 utilities library
Data.Base32.Crockford	base32 Crockford utilities library
Data.Base32.Hex	base32 Hex utilities library
Data.Base32.RFC4648	base32 RFC4648 utilities library
Data.Base16	base16 utilities library
Data.BigNum	multi precision integer library
Data.Closure	Provide Closure object
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.List.Byte	Data.List provider for Bytes-List and other bytes-list like data converter.
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.HMAC	Hash-based Message Authentication Code
Hash.MD5	MD5 encoding
Hash.SHA1	SHA1 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. Assuming your Vim plugin name is your_plugin_name and plugin directory is your_plugin_dir. 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 your_plugin_name. You can define your utility function set your_plugin_name#util just by

let s:Process = vital#your_plugin_name#import('System.Process')

function! your_plugin_name#util#system(...)
  return s:Process.execute(a:000)
endfunction
" run
" echo your_plugin_name#util#system('echo','abc')
" -> $ echo abc

and then you can call functions by your_plugin_name#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 Math and to call a function lcm() of the module.

" Recommended way
let s:M = vital#your_plugin_name#import('Math')
call s:M.lcm([2, 3, 4])
" -> 12

" Alternative way
let s:V = vital#your_plugin_name#new()
let s:M = s:V.import('Math')
call s:M.lcm([2, 3, 4])
" -> 12

" Alternative way only if you rarely use the module
let s:V = vital#your_plugin_name#new()
call s:V.load('Math')
call s:V.Math.lcm([2, 3, 4])
" -> 12

" Available, but we don't recommend this very much
let s:V = vital#your_plugin_name#new()
call s:V.import('Math', s:)
call s:lcm([2, 3, 4])
" -> 12

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

(Default)
by adding ?style=plastic
by adding ?style=flat
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 vim-jp#26 about the discussion.)

tsuyoshicho / vital.vim