From 4dab51c0153774e4395099623b95c502ae67d0f7 Mon Sep 17 00:00:00 2001
From: Wang Shidong <wsdjeg@outlook.com>
Date: Sat, 15 Feb 2020 15:15:58 +0800
Subject: [PATCH] Add backgroud task support (#3351)

---
 autoload/SpaceVim/plugins/runner.vim | 24 +++++++++--
 docs/documentation.md                | 62 +++++++++++++++++++++++++++-
 2 files changed, 81 insertions(+), 5 deletions(-)

diff --git a/autoload/SpaceVim/plugins/runner.vim b/autoload/SpaceVim/plugins/runner.vim
index e711afbd3..cb63e5a2c 100644
--- a/autoload/SpaceVim/plugins/runner.vim
+++ b/autoload/SpaceVim/plugins/runner.vim
@@ -247,7 +247,7 @@ if has('nvim') && exists('*chanclose')
       let lines = s:_out_data
     endif
     " if s:SYS.isWindows
-      " let lines = map(lines, 's:ICONV.iconv(v:val, "cp936", "utf-8")')
+    " let lines = map(lines, 's:ICONV.iconv(v:val, "cp936", "utf-8")')
     " endif
     if !empty(lines)
       let lines = map(lines, "substitute(v:val, '
$', '', 'g')")
@@ -387,12 +387,30 @@ endfunction
 
 function! SpaceVim#plugins#runner#run_task(task)
   let isBackground = get(a:task, 'isBackground', 0)
-  if !isBackground && !empty(a:task)
+  if isBackground && !empty(a:task)
     let cmd = get(a:task, 'command', '') 
     let args = get(a:task, 'args', [])
     if !empty(args) && !empty(cmd)
       let cmd = cmd . ' ' . join(args, ' ')
     endif
-    call SpaceVim#plugins#runner#open(cmd) 
+    if isBackground
+      call s:run_backgroud(cmd)
+    else
+      call SpaceVim#plugins#runner#open(cmd) 
+    endif
   endif
 endfunction
+
+function! s:on_backgroud_exit(job_id, data, event) abort
+  let s:end_time = reltime(s:start_time)
+  let exit_code = a:data
+  echo 'task finished with code=' . a:data . ' in ' . s:STRING.trim(reltimestr(s:end_time)) . ' seconds'
+endfunction
+
+function! s:run_backgroud(cmd) abort
+  echo "task running"
+  let s:start_time = reltime()
+  call s:JOB.start(a:cmd,{
+        \ 'on_exit' : function('s:on_backgroud_exit'),
+        \ })
+endfunction
diff --git a/docs/documentation.md b/docs/documentation.md
index 078f2cc34..de4369786 100644
--- a/docs/documentation.md
+++ b/docs/documentation.md
@@ -89,7 +89,7 @@ description: "General documentation about how to using SpaceVim, including the q
   - [Managing projects](#managing-projects)
     - [Searching files in project](#searching-files-in-project)
     - [Custom alternate file](#custom-alternate-file)
-  - [Tasks manager](#tasks-manager)
+- [Tasks](#tasks)
 - [EditorConfig](#editorconfig)
 - [Vim Server](#vim-server)
 - [Achievements](#achievements)
@@ -1916,7 +1916,7 @@ here is an example of `.project_alt.json`:
 }
 ```
 
-### Tasks manager
+## Tasks
 
 To integrate with external tools, SpaceVim introduce a task manager system,
 which is similar to vscode tasks-manager. There are two kinds of task configuration
@@ -1927,6 +1927,64 @@ file: global tasks configuration(`~/.SpaceVim.d/tasks.toml`) and local configura
 | `SPC p t e`  | edit tasks configuration file |
 | `SPC p t r`  | select task to run            |
 
+
+this is basic task configuration for running `echo hello world`, and print results to runner windows.
+
+```toml
+[my-task]
+    command = 'echo'
+    args = ['hello world']
+```
+
+![task hello world](https://user-images.githubusercontent.com/13142418/74582981-74049900-4ffd-11ea-9b38-7858042225b9.png)
+
+To run task in the background, you need to set `isBackground` to `true`:
+
+```toml
+[my-task]
+    command = 'echo'
+    args = ['hello world']
+    isBackground = true
+```
+
+The task's properties have the following semantic:
+
+- **command**: the actual command to execute.
+- **args**: the arguments passed to the command. can be omitted.
+- **options**: override the defaults for `cwd`,`env` or `shell`.
+
+SpaceVim supports variable substitution in task, The following predefined variables are supported:
+
+- **${workspaceFolder}**: - the project root directory
+- **${workspaceFolderBasename}**: - the parent directory name of current project root 
+- **${file}**: - the path of current file
+- **${relativeFile}**: - the current file relative to project root
+- **${relativeFileDirname}**: - the current file's dirname relative to workspaceFolder
+- **${fileBasename}**: - the current file's basename
+- **${fileBasenameNoExtension}**: - the current file's basename without file extension
+- **${fileDirname}**: - the current file's dirname
+- **${fileExtname}**: - the current file's extension
+- **${cwd}**: - the task runner's current working directory on startup
+- **${lineNumber}**: - the current selected line number in the active file
+
+
+for example: Supposing that you have the following requirements:
+
+A file located at `/home/your-username/your-project/folder/file.ext` opened in your editor;
+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`
+- **${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}**: - line number of the cursor
+
 ## EditorConfig
 
 SpaceVim has supported [EditorConfig](http://editorconfig.org/), a configuration file to “define and maintain consistent coding styles between different editors and IDEs.”