From 94568dbacb04f35b8f8c527d209edb3d2b19f1d6 Mon Sep 17 00:00:00 2001
From: Wang Shidong <wsdjeg@outlook.com>
Date: Fri, 21 Feb 2020 16:01:07 +0800
Subject: [PATCH] Improve tasks support (#3370)

---
 .SpaceVim.d/tasks.toml              |  4 +-
 autoload/SpaceVim/plugins/tasks.vim | 27 +++++-------
 docs/cn/documentation.md            | 64 ++++++++++++++++++++++++++---
 docs/documentation.md               |  6 +--
 4 files changed, 74 insertions(+), 27 deletions(-)

diff --git a/.SpaceVim.d/tasks.toml b/.SpaceVim.d/tasks.toml
index 5d67cf67f..28b563198 100644
--- a/.SpaceVim.d/tasks.toml
+++ b/.SpaceVim.d/tasks.toml
@@ -1,8 +1,8 @@
 [file-build]
-    command = 'gcc $(VIM_FILE) -o $(TARGET_DIR)/$(VIM_FILE_NOEXT)'
+    command = 'echo ${relativeFile}'
     isBackground = false
 [file-build.options]
-    cmd = '$(workspace)'
+    cmd = '${workspaceFolder}'
 [file-run]
     command = "echo"
     args = ['hello']
diff --git a/autoload/SpaceVim/plugins/tasks.vim b/autoload/SpaceVim/plugins/tasks.vim
index 7baed88f9..a8e097161 100644
--- a/autoload/SpaceVim/plugins/tasks.vim
+++ b/autoload/SpaceVim/plugins/tasks.vim
@@ -27,33 +27,28 @@ let s:variables = {}
 
 
 function! s:load() abort
-  let s:conf = s:TOML.parse_file('.SpaceVim.d/tasks.toml')
+  let [global_conf, local_conf] = [{}, {}]
+  if filereadable(expand('~/.SpaceVim.d/tasks.toml'))
+    let global_conf = s:TOML.parse_file(expand('~/.SpaceVim.d/tasks.toml'))
+  endif
+  if filereadable('.SpaceVim.d/tasks.toml')
+    let local_conf = s:TOML.parse_file('.SpaceVim.d/tasks.toml')
+  endif
+  let s:conf = extend(global_conf, local_conf)
 endfunction
 
 function! s:init_variables() abort
-  " ${workspaceFolder} - /home/your-username/your-project
-  let s:variables.workspaceFolder = SpaceVim#plugins#projectmanager#current_root()
-  " ${workspaceFolderBasename} - your-project
+  let s:variables.workspaceFolder = s:FILE.unify_path(SpaceVim#plugins#projectmanager#current_root())
   let s:variables.workspaceFolderBasename = fnamemodify(s:variables.workspaceFolder, ':t')
-  " ${file} - /home/your-username/your-project/folder/file.ext
   let s:variables.file = s:FILE.unify_path(expand('%:p'))
-  " ${relativeFile} - folder/file.ext
-  let s:variables.relativeFile = s:FILE.unify_path(expand('%'))
-  " ${relativeFileDirname} - folder
+  let s:variables.relativeFile = s:FILE.unify_path(expand('%'), ':.')
   let s:variables.relativeFileDirname = s:FILE.unify_path(expand('%'), ':h')
-  " ${fileBasename} - file.ext
   let s:variables.fileBasename = expand('%:t')
-  " ${fileBasenameNoExtension} - file
   let s:variables.fileBasenameNoExtension = expand('%:t:r')
-  " ${fileDirname} - /home/your-username/your-project/folder
   let s:variables.fileDirname = s:FILE.unify_path(expand('%:p:h'))
-  " ${fileExtname} - .ext
   let s:variables.fileExtname = expand('%:e')
-  " ${lineNumber} - line number of the cursor
   let s:variables.lineNumber = line('.')
-  " ${selectedText} - text selected in your code editor
   let s:variables.selectedText = ''
-  " ${execPath} - location of Code.exe
   let s:variables.execPath = ''
 endfunction
 
@@ -74,7 +69,7 @@ endfunction
 function! s:replace_variables(str) abort
   let str = a:str
   for key in keys(s:variables)
-    let str = substitute(str, '$(' . key . ')', s:variables[key], 'g')
+    let str = substitute(str, '${' . key . '}', s:variables[key], 'g')
   endfor
   return str
 endfunction
diff --git a/docs/cn/documentation.md b/docs/cn/documentation.md
index 43ba71674..208b3fc60 100644
--- a/docs/cn/documentation.md
+++ b/docs/cn/documentation.md
@@ -1684,13 +1684,65 @@ endfunction
 
 ### 任务管理
 
-构建、打包、测试等任务会涉及到多种外部命令，包括`make`、`mvn`等。
-可以通过任务集成外部工具这些外部命令。
+通过内置的任务管理系统，可以快速集成外部命令工具，类似于 vscode 的任务管理系统，
+支持项目局部配置文件(`.SpaceVim.d/tasks.toml`)和全局配置文件(`~/.SpaceVim.d/tasks.toml`)，项目局部配置文件具有更高的优先权：
 
-| 快捷键      | 功能描述         |
-| ----------- | ---------------- |
-| `SPC p t e` | 编辑任务配置文件 |
-| `SPC p t r` | 选择任务并执行   |
+| 快捷键 | 功能描述             |
+| ------------ | ----------------------------- |
+| `SPC p t e`  | 编辑任务配置文件 |
+| `SPC p t r`  | 选定任务并执行            |
+
+以下为一个简单的任务配置示例，异步运行 `echo hello world`，并将结果打印至输出窗口。
+
+```toml
+[my-task]
+    command = 'echo'
+    args = ['hello world']
+```
+
+![task hello world](https://user-images.githubusercontent.com/13142418/74582981-74049900-4ffd-11ea-9b38-7858042225b9.png)
+
+对于不需要打印输出结果，后台运行的任务，可以设置 `isBackground` 为 `true`:
+
+```toml
+[my-task]
+    command = 'echo'
+    args = ['hello world']
+    isBackground = true
+```
+
+任务的配置，可以设置如下关键字：
+
+- **command**: 需要运行的命令。
+- **args**: 传递给命令的参数，可以省略。
+- **options**: 设置命令运行的一些选项，比如 `cwd`,`env` 或者 `shell`。
+
+在编辑任务配置文件时，可以使用一些预设定的变量，以下列出目前已经支持的预设定变量：
+
+- **\${workspaceFolder}**: - 当前项目的根目录；
+- **\${workspaceFolderBasename}**: - 当前项目根目录所在父目录的文件夹名称；
+- **\${file}**: - 当前文件的绝对路径；
+- **\${relativeFile}**: - 当前文件相对项目根目录的相对路径；
+- **\${relativeFileDirname}**: - 当前文件所在的文件夹相对项目根目录的相对路径；
+- **\${fileBasename}**: - 当前文件的文件名
+- **\${fileBasenameNoExtension}**: - 当前文件的文件名，不包括后缀名
+- **\${fileDirname}**: - 当前文件所在的目录的绝对路径
+- **\${fileExtname}**: - 当前文件的后缀名
+- **\${lineNumber}**: - 光标所在行号
+
+例如：假定目前正在编辑文件 `/home/your-username/your-project/folder/file.ext` ，光标位于第十行；
+该文件所在的项目根目录为 `/home/your-username/your-project`，那么任务系统的预设定变量的值为：
+
+- **\${workspaceFolder}**: - `/home/your-username/your-project/`
+- **\${workspaceFolderBasename}**: - `your-project`
+- **\${file}**: - `/home/your-username/your-project/folder/file.ext`
+- **\${relativeFile}**: - `folder/file.ext`
+- **\${relativeFileDirname}**: - `folder/`
+- **\${fileBasename}**: - `file.ext`
+- **\${fileBasenameNoExtension}**: - `file`
+- **\${fileDirname}**: - `/home/your-username/your-project/folder/`
+- **\${fileExtname}**: - `.ext`
+- **\${lineNumber}**: - `10`
 
 ### Iedit 多光标编辑
 
diff --git a/docs/documentation.md b/docs/documentation.md
index c5dc48671..ac6b04b4b 100644
--- a/docs/documentation.md
+++ b/docs/documentation.md
@@ -1763,14 +1763,14 @@ A file located at `/home/your-username/your-project/folder/file.ext` opened in y
 The directory `/home/your-username/your-project` opened as your root workspace.
 So you will have the following values for each variable:
 
-- **\${workspaceFolder}**: - `/home/your-username/your-project`
+- **\${workspaceFolder}**: - `/home/your-username/your-project/`
 - **\${workspaceFolderBasename}**: - `your-project`
 - **\${file}**: - `/home/your-username/your-project/folder/file.ext`
 - **\${relativeFile}**: - `folder/file.ext`
-- **\${relativeFileDirname}**: - `folder`
+- **\${relativeFileDirname}**: - `folder/`
 - **\${fileBasename}**: - `file.ext`
 - **\${fileBasenameNoExtension}**: - `file`
-- **\${fileDirname}**: - `/home/your-username/your-project/folder`
+- **\${fileDirname}**: - `/home/your-username/your-project/folder/`
 - **\${fileExtname}**: - `.ext`
 - **\${lineNumber}**: - line number of the cursor