Improve Spacevim api (#2250)

.SpaceVim.d/autoload/SpaceVim/dev/api.vim

@@ -49,12 +49,14 @@ endfunction
 function! s:generate_content() abort
   let content = ['', '## Available APIs', '', 'here is the list of all available APIs, and welcome to contribute to SpaceVim.', '']
   let content += s:layer_list()
+  let content += ['']
   return content
 endfunction
 
 function! s:generate_content_cn() abort
   let content = ['', '## 可用 APIs', '']
   let content += s:layer_list_cn()
+  let content += ['']
   return content
 endfunction
 

.SpaceVim.d/init.vim

@@ -11,3 +11,16 @@ call SpaceVim#custom#SPC('nnoremap', ['a', 'r'], 'call SpaceVim#dev#releases#ope
 call SpaceVim#custom#SPC('nnoremap', ['a', 'w'], 'call SpaceVim#dev#website#open()', 'Open SpaceVim local website', 1)
 call SpaceVim#custom#SPC('nnoremap', ['a', 't'], 'call SpaceVim#dev#website#terminal()', 'Close SpaceVim local website', 1)
 call SpaceVim#custom#SPC('nnoremap', ['a', 'o'], 'call SpaceVim#dev#todo#list()', 'Open todo manager', 1)
+
+" after run make test, the vader will be downloaded to ./build/vader/
+
+set rtp+=build/vader
+
+" vader language specific key bindings
+
+function! s:language_specified_mappings() abort
+  call SpaceVim#mapping#space#langSPC('nmap', ['l','r'],
+        \ 'Vader',
+        \ 'execute current file', 1)
+endfunction
+call SpaceVim#mapping#space#regesit_lang_mappings('vader', function('s:language_specified_mappings'))

autoload/SpaceVim/api.vim

@@ -8,17 +8,30 @@
 
 ""
 " @section API, api
-" SpaceVim contains a variety of public apis. here is a list of all the apis.
+" SpaceVim contains a variety of public apis. To using the api, you need to
+" make sure SpaceVim has been added to your &rtp. after that, you can use
+" |SpaceVim#api#import| to import the API you need.
+"
 " @subsection usage
+"
 " This is just an example, and it works well in old version vim.
 " >
 "   let s:json = SpaceVim#api#import('data#json')
 "   let rst = s:json.json_encode(onject)
 "   let rst = s:json.json_decode(string)
 " <
+" 
+" here is list of resources where SpaceVim comes from:
+"
+" - vital: https://github.com/vim-jp/vital.vim
 
 let s:apis = {}
 
+
+""
+"@public
+"Import API base the given {name}, and return the API object. for all
+"available APIs please check |spacevim-api|
 function! SpaceVim#api#import(name) abort
   if has_key(s:apis, a:name)
     return deepcopy(s:apis[a:name])

autoload/SpaceVim/api/data/dict.vim

@@ -6,6 +6,27 @@
 " License: GPLv3
 "=============================================================================
 
+""
+" @section data#dict, api-data-dict
+" @parentsection api
+" provides some functions to manipulate a dict.
+"
+" make({keys}, {values}[, {fill}])
+" 
+"   make a dictionary from two list, the {keys} and {values}.
+"
+" swap({dict})
+"
+"   swap the keys and values in a dictionary.
+"
+" make_index
+"
+"   make a dictionary from a list, use 
+
+
+
+
+
 function! SpaceVim#api#data#dict#get() abort
   return map({
         \ 'make' : '',

autoload/SpaceVim/api/data/list.vim

@@ -27,20 +27,34 @@ endfunction
 ""
 " @section data#list, api-data-list
 " @parentsection api
-" pop({list})
+" provides some functions to manipulate a list.
 "
-" Removes the last element from {list} and returns the element,
+" pop({list})
+" 
+"   Removes the last element from {list} and returns the element,
 " as if the {list} is a stack.
 "
 " push({list})
 "
-" Appends {val} to the end of {list} and returns the list itself,
+"   Appends {val} to the end of {list} and returns the list itself,
 " as if the {list} is a stack.
 "
 " listpart({list}, {start}[, {len}])
 " 
-" The result is a List, which is part of {list}, starting from
+"   The result is a List, which is part of {list}, starting from
 " index {start}, with the length {len}
+"
+" replace(list, begin, end, re_list)
+"
+"   replace {list} from {begin} to {end} with {re_list}
+"
+" shift({list})
+"
+"   remove first item in a {list}, and return the item
+"
+" unshift({list})
+"
+"  insert an item to the begin of the {list} 
 
 function! s:pop(list) abort
     return remove(a:list, -1)

autoload/SpaceVim/api/job.vim

@@ -1,3 +1,33 @@
+"=============================================================================
+" job.vim --- job api
+" Copyright (c) 2016-2017 Wang Shidong & Contributors
+" Author: Wang Shidong < wsdjeg at 163.com >
+" URL: https://spacevim.org
+" License: GPLv3
+"=============================================================================
+
+
+
+""
+" @section job, api-job
+" @parentsection api
+" provides some functions to manager job
+"
+" start({cmd}[, {opt}])
+" 
+"   spawns {cmd} as a job. {opts} is a dictionary with these keys:
+"
+"   on_stdout: stdout event handler (function name or Funcref)
+"
+"   on_stderr: stderr event handler (function name or Funcref)
+"   
+"   on_exit: exit event handler (function name or Funcref)
+"
+"   cwd: working directory of the job; defaults to current directory
+
+
+
+
 function! SpaceVim#api#job#get() abort
   return deepcopy(s:self)
 endfunction

autoload/SpaceVim/api/logger.vim

@@ -5,6 +5,18 @@
 " URL: https://spacevim.org
 " License: GPLv3
 "=============================================================================
+
+
+""
+" @section logger, api-logger
+" @parentsection api
+" provides some functions to manager logger
+"
+" set_silent({silent})
+"
+"   {silent} is a Boolean. by default it is false, and log will be print to
+"   screen.
+
 let s:self = {
       \ 'name' : '',
       \ 'silent' : 1,

autoload/SpaceVim/api/password.vim

@@ -5,6 +5,34 @@
 " URL: https://spacevim.org
 " License: GPLv3
 "=============================================================================
+
+""
+" @section password, api-password
+" @parentsection api
+" provides some functions to generate password
+"
+" generate_simple({len})
+"
+"   generate simple password
+"    
+" generate_strong({len})
+"
+"   generate strong password
+"
+" generate_paranoid({len})
+"
+"   generate paranoid password
+"
+" generate_numeric({len})
+" 
+"   generate numeric password
+"
+" generate_phonetic({len})
+"
+"   generate phonetic password
+
+
+
 let s:self = {}
 
 let s:NUMBER = SpaceVim#api#import('data#number')

autoload/SpaceVim/api/system.vim

@@ -5,6 +5,15 @@
 " URL: https://spacevim.org
 " License: GPLv3
 "=============================================================================
+
+""
+" @section system, api-system
+" @parentsection api
+" name()
+" 
+" Return the name of current os, availibel value is: linux, cygwin, windows
+" and mac.
+
 scriptencoding utf-8
 let s:system = {}
 

autoload/SpaceVim/api/vim/buffer.vim

@@ -6,6 +6,29 @@
 " License: GPLv3
 "=============================================================================
 
+""
+" @section vim#buffer, api-vim-buffer
+" @parentsection api
+" @subsection Functions
+"
+" is_cmdwin()
+" 
+" Check if current windows is command line windows.
+" 
+" open(opt)
+"
+" Open a new buffer with specifice options, return the buffer number, the {opt} 
+" is a dict with following keys:
+" 
+"     bufname : the buffer name of the new buffer
+"
+"     mode: how to open the new buffer, default is vertical topleft split
+"
+"     initfunc: the function which will be call after creating buffer
+"
+"     cmd: the ex command which will be run after the new buffer is created
+
+
 let s:self = {}
 
 

autoload/SpaceVim/api/vim/command.vim

@@ -6,11 +6,14 @@
 " License: GPLv3
 "=============================================================================
 
-let s:self = {}
+""
-
+" @section vim#command, api-vim-command
-let s:self.options = {}
+" @parentsection api
-
+" This api is for create complete function for custom vim command. This is
-" let s:options = {
+" example for create complete function for command TEST
+" >
+"   let s:CMD = SpaceVim#api#import('vim#command')
+"   let s:CMD.options = {
 "       \ '-f' : {
 "       \ 'description' : '',
 "       \ 'complete' : ['text'],
@@ -20,6 +23,17 @@ let s:self.options = {}
 "       \ 'complete' : 'file',
 "       \ },
 "       \ }
+"   function! CompleteTest(a, b, c)
+"     return s:CMD.complete(a:a, a:b, a:c)
+"   endfunction
+"   function! Test(...)
+"   endfunction
+"   command! -nargs=* -complete=custom,CompleteTest TEST :call Test(<f-args>)
+" <
+
+let s:self = {}
+
+let s:self.options = {}
 
 let s:self._message = []
 

autoload/SpaceVim/api/vim/compatible.vim

@@ -5,6 +5,29 @@
 " URL: https://spacevim.org
 " License: GPLv3
 "=============================================================================
+
+""
+" @section vim#compatible, api-vim-compatible
+" @parentsection api
+"
+" @subsection Functions
+"
+" execute(cmd)
+"
+"   run vim command, and return the output of such command.
+"
+" system(cmd)
+"
+"   like |system()| but can accept list as argv.
+"
+" systemlist(cmd)
+"
+"   like |systemlist()| but can accept list as argv.
+"
+" has(feature)
+"
+"   check if {feature} is supported in current version.
+
 function! SpaceVim#api#vim#compatible#get() abort
   return map({
         \ 'execute' : '',

autoload/zvim/util.vim

@@ -67,6 +67,7 @@ fu! s:findDirInParent(what, where) abort " {{{2
 endf " }}}2
 fu! zvim#util#CopyToClipboard(...) abort
   if a:0
+    echom 1
     if executable('git')
       let repo_home = fnamemodify(s:findDirInParent('.git', expand('%:p')), ':p:h:h')
       if repo_home !=# '' || !isdirectory(repo_home)

doc/SpaceVim.txt

@@ -76,10 +76,18 @@ CONTENTS                                                   *SpaceVim-contents*
       32. tools#dash...............................|SpaceVim-layer-tools-dash|
   7. API........................................................|SpaceVim-api|
       1. cmdlinemenu................................|SpaceVim-api-cmdlinemenu|
-      2. data#list....................................|SpaceVim-api-data-list|
+      2. data#dict....................................|SpaceVim-api-data-dict|
-      3. prompt..........................................|SpaceVim-api-prompt|
+      3. data#list....................................|SpaceVim-api-data-list|
-      4. sid............................................|SpaceVim-api-vim-sid|
+      4. job................................................|SpaceVim-api-job|
-      5. vim#message................................|SpaceVim-api-vim-message|
+      5. logger..........................................|SpaceVim-api-logger|
+      6. password......................................|SpaceVim-api-password|
+      7. prompt..........................................|SpaceVim-api-prompt|
+      8. sid............................................|SpaceVim-api-vim-sid|
+      9. system..........................................|SpaceVim-api-system|
+      10. vim#buffer.................................|SpaceVim-api-vim-buffer|
+      11. vim#command...............................|SpaceVim-api-vim-command|
+      12. vim#compatible.........................|SpaceVim-api-vim-compatible|
+      13. vim#message...............................|SpaceVim-api-vim-message|
   8. FAQ........................................................|SpaceVim-faq|
   9. Changelog............................................|SpaceVim-changelog|
 
@@ -744,6 +752,10 @@ COMMANDS                                                   *SpaceVim-commands*
 ==============================================================================
 FUNCTIONS                                                 *SpaceVim-functions*
 
+SpaceVim#api#import({name})                            *SpaceVim#api#import()*
+  Import API base the given {name}, and return the API object. for all
+  available APIs please check |spacevim-api|
+
 SpaceVim#layers#load({layer})                         *SpaceVim#layers#load()*
   Load the {layer} you want. For all the layers SpaceVim supports, see
   |SpaceVim-layers|. the second argv is the layer variable.
@@ -1302,8 +1314,12 @@ This layer provides Dash integration for SpaceVim
 ==============================================================================
 API                                                             *SpaceVim-api*
 
-SpaceVim contains a variety of public apis. here is a list of all the apis.
+SpaceVim contains a variety of public apis. To using the api, you need to make
+sure SpaceVim has been added to your &rtp. after that, you can use
+|SpaceVim#api#import| to import the API you need.
+
 USAGE
+
 This is just an example, and it works well in old version vim.
 >
   let s:json = SpaceVim#api#import('data#json')
@@ -1311,6 +1327,10 @@ This is just an example, and it works well in old version vim.
   let rst = s:json.json_decode(string)
 <
 
+here is list of resources where SpaceVim comes from:
+
+vital: https://github.com/vim-jp/vital.vim
+
 ==============================================================================
 CMDLINEMENU                                         *SpaceVim-api-cmdlinemenu*
 
@@ -1320,24 +1340,107 @@ Create a cmdline selection menu from a list of {items}, each item should be a
 list of two value in it, first one is the description, and the next one should
 be a funcrc.
 
+==============================================================================
+DATA#DICT                                             *SpaceVim-api-data-dict*
+
+provides some functions to manipulate a dict.
+
+make({keys}, {values}[, {fill}])
+
+  make a dictionary from two list, the {keys} and {values}.
+
+swap({dict})
+
+  swap the keys and values in a dictionary.
+
+make_index
+
+  make a dictionary from a list, use
+
 ==============================================================================
 DATA#LIST                                             *SpaceVim-api-data-list*
 
+provides some functions to manipulate a list.
+
 pop({list})
 
-Removes the last element from {list} and returns the element, as if the {list}
+  Removes the last element from {list} and returns the element, as if the
-is a stack.
+{list} is a stack.
 
 push({list})
 
-Appends {val} to the end of {list} and returns the list itself, as if the
+  Appends {val} to the end of {list} and returns the list itself, as if the
 {list} is a stack.
 
 listpart({list}, {start}[, {len}])
 
-The result is a List, which is part of {list}, starting from index {start},
+  The result is a List, which is part of {list}, starting from index {start},
 with the length {len}
 
+replace(list, begin, end, re_list)
+
+  replace {list} from {begin} to {end} with {re_list}
+
+shift({list})
+
+  remove first item in a {list}, and return the item
+
+unshift({list})
+
+ insert an item to the begin of the {list}
+
+==============================================================================
+JOB                                                         *SpaceVim-api-job*
+
+provides some functions to manager job
+
+start({cmd}[, {opt}])
+
+  spawns {cmd} as a job. {opts} is a dictionary with these keys:
+
+  on_stdout: stdout event handler (function name or Funcref)
+
+  on_stderr: stderr event handler (function name or Funcref)
+
+  on_exit: exit event handler (function name or Funcref)
+
+  cwd: working directory of the job; defaults to current directory
+
+==============================================================================
+LOGGER                                                   *SpaceVim-api-logger*
+
+provides some functions to manager logger
+
+set_silent({silent})
+
+  {silent} is a Boolean. by default it is false, and log will be print to
+screen.
+
+==============================================================================
+PASSWORD                                               *SpaceVim-api-password*
+
+provides some functions to generate password
+
+generate_simple({len})
+
+  generate simple password
+
+generate_strong({len})
+
+  generate strong password
+
+generate_paranoid({len})
+
+  generate paranoid password
+
+generate_numeric({len})
+
+  generate numeric password
+
+generate_phonetic({len})
+
+  generate phonetic password
+
 ==============================================================================
 PROMPT                                                   *SpaceVim-api-prompt*
 
@@ -1359,6 +1462,83 @@ SID                                                     *SpaceVim-api-vim-sid*
 
 " Capture command
 
+==============================================================================
+SYSTEM                                                   *SpaceVim-api-system*
+
+name()
+
+Return the name of current os, availibel value is: linux, cygwin, windows and
+mac.
+
+==============================================================================
+VIM#BUFFER                                           *SpaceVim-api-vim-buffer*
+
+FUNCTIONS
+
+is_cmdwin()
+
+Check if current windows is command line windows.
+
+open(opt)
+
+Open a new buffer with specifice options, return the buffer number, the {opt}
+is a dict with following keys:
+
+    bufname : the buffer name of the new buffer
+
+    mode: how to open the new buffer, default is vertical topleft split
+
+    initfunc: the function which will be call after creating buffer
+
+    cmd: the ex command which will be run after the new buffer is created
+
+==============================================================================
+VIM#COMMAND                                         *SpaceVim-api-vim-command*
+
+This api is for create complete function for custom vim command. This is
+example for create complete function for command TEST
+>
+  let s:CMD = SpaceVim#api#import('vim#command')
+  let s:CMD.options = {
+      \ '-f' : {
+      \ 'description' : '',
+      \ 'complete' : ['text'],
+      \ },
+      \ '-d' : {
+      \ 'description' : 'Root directory for sources',
+      \ 'complete' : 'file',
+      \ },
+      \ }
+  function! CompleteTest(a, b, c)
+    return s:CMD.complete(a:a, a:b, a:c)
+  endfunction
+  function! Test(...)
+  endfunction
+  command! -nargs=* -complete=custom,CompleteTest TEST :call Test(<f-args>)
+<
+
+==============================================================================
+VIM#COMPATIBLE                                   *SpaceVim-api-vim-compatible*
+
+
+FUNCTIONS
+
+execute(cmd)
+
+  run vim command, and return the output of such command.
+
+system(cmd)
+
+  like |system()| but can accept list as argv.
+
+systemlist(cmd)
+
+  like |systemlist()| but can accept list as argv.
+
+has(feature)
+
+  check if {feature} is supported in current version.
+
 ==============================================================================
 VIM#MESSAGE                                         *SpaceVim-api-vim-message*
 

docs/api.md

@@ -7,7 +7,7 @@ description: "A list of available APIs in SpaceVim, provide compatible functions
 
 <!-- vim-markdown-toc GFM -->
 
-    - [Introduction](#introduction)
+- [Introduction](#introduction)
 - [Available APIs](#available-apis)
 
 <!-- vim-markdown-toc -->
@@ -34,26 +34,26 @@ echom s:file.pathSeparator
 
 <!-- SpaceVim api list start -->
 
-## Available APIs
+#### Available APIs
 
 here is the list of all available APIs, and welcome to contribute to SpaceVim.
 
-| Name                                  | Description                                                                                        |
+| Name | Description |
-| ------------------------------------- | -------------------------------------------------------------------------------------------------- |
+| ---------- | ------------ |
-| [data#base64](data/base64/)           | data#base64 API provides base64 encode and decode functions                                        |
+| [data#base64](data/base64/)    |   data#base64 API provides base64 encode and decode functions | 
-| [data#dict](data/dict/)               | data#dict API provides some basic functions and values for dict.                                   |
+| [data#dict](data/dict/)    |   data#dict API provides some basic functions and values for dict. | 
-| [data#string](data/string/)           | data#string API provides some basic functions and values for string.                               |
+| [data#string](data/string/)    |   data#string API provides some basic functions and values for string. | 
-| [data#toml](data/toml/)               | data#toml API provides some basic functions and values for toml.                                   |
+| [data#toml](data/toml/)    |   data#toml API provides some basic functions and values for toml. | 
-| [file](file/)                         | file API provides some basic functions and values for current os.                                  |
+| [file](file/)    |   file API provides some basic functions and values for current os. | 
-| [job](job/)                           | job API provides some basic functions for running a job                                            |
+| [job](job/)    |   job API provides some basic functions for running a job | 
-| [logger](logger/)                     | logger API provides some basic functions for log message when create plugins                       |
+| [logger](logger/)    |   logger API provides some basic functions for log message when create plugins | 
-| [messletters](messletters/)           | messletters API provides some basic functions for generating messletters                           |
+| [messletters](messletters/)    |   messletters API provides some basic functions for generating messletters | 
-| [password](password/)                 | password API provides some basic functions for generating password                                 |
+| [password](password/)    |   password API provides some basic functions for generating password | 
-| [system](system/)                     | system API provides some basic functions and values for current os.                                |
+| [system](system/)    |   system API provides some basic functions and values for current os. | 
-| [unicode#spinners](unicode/spinners/) | unicode#spinners API provides some basic functions for starting spinners timer                     |
+| [unicode#spinners](unicode/spinners/)    |   unicode#spinners API provides some basic functions for starting spinners timer | 
-| [vim#highlight](vim/highlight/)       | vim#highlight API provides some basic functions and values for getting and setting highlight info. |
+| [vim#highlight](vim/highlight/)    |   vim#highlight API provides some basic functions and values for getting and setting highlight info. | 
-| [web#html](web/html/)                 | web#html API provides some basic functions and values for parser html file.                        |
+| [web#html](web/html/)    |   web#html API provides some basic functions and values for parser html file. | 
-| [web#http](web/http/)                 | web#http API provides some basic functions and values for http request                             |
+| [web#http](web/http/)    |   web#http API provides some basic functions and values for http request | 
-| [web#xml](web/xml/)                   | web#xml API provides some basic functions and values for parser xml file.                          |
+| [web#xml](web/xml/)    |   web#xml API provides some basic functions and values for parser xml file. | 
 
 <!-- SpaceVim api list end -->

docs/api/data/list.md

@@ -0,0 +1,28 @@
+---
+title: "data#list API"
+description: "data#list API provides some basic functions and values for list."
+---
+
+# [Available APIs](../../) >> data#list
+
+<!-- vim-markdown-toc GFM -->
+
+- [Intro](#intro)
+- [functions](#functions)
+
+<!-- vim-markdown-toc -->
+
+## Intro
+
+`data#list` API provides some functions to manipulate a list. Here is an example for using this api:
+
+```vim
+let s:DICT = SpaceVim#api#import('data#list')
+```
+
+## functions
+
+| name        | description                    |
+| ----------- | ------------------------------ |
+| `make(str)` | make list from keys and values |
+

docs/cn/api.md

@@ -8,18 +8,18 @@ lang: cn
 
 <!-- vim-markdown-toc GFM -->
 
-    - [简介](#简介)
+- [简介](#简介)
-    - [使用方法](#使用方法)
+- [使用方法](#使用方法)
 - [可用 APIs](#可用-apis)
 
 <!-- vim-markdown-toc -->
 
-#### 简介
+## 简介
 
 为了兼容不同版本的 Vim，避免使用重复的兼容函数，SpaceVim 提供了一套兼容的公共 API。开发插件时，
 可以在你的插件中使用这些公共 API，这一思想主要借鉴于 [vital.vim](https://github.com/vim-jp/vital.vim)。
 
-#### 使用方法
+## 使用方法
 
 可以通过 `SpaceVim#api#import()` 函数导入相关 API，参考以下示例：
 

docs/cn/api/data/dict.md

@@ -0,0 +1,27 @@
+---
+title: "data#dict api"
+description: "data#dict api 提供了一些处理字典变量的常用方法"
+---
+
+# [Available APIs](../../) >> data#dict
+
+<!-- vim-markdown-toc GFM -->
+
+- [简介](#简介)
+- [函数列表](#函数列表)
+
+<!-- vim-markdown-toc -->
+
+## 简介
+
+`data#dict` API 提供了一些处理字典类型变量的方法，包括基础的增删改查。
+
+```vim
+let s:DICT = SpaceVim#api#import('data#dict')
+```
+
+## 函数列表
+
+| 名称                         | 描述                                     |
+| ---------------------------- | ---------------------------------------- |
+| `make(keys, values[, fill])` | 通过两个键和值的列表一一匹配生成字典变量 |