added docs for job control

README.md

@@ -12,6 +12,7 @@ Cicada is a simple Unix shell written in Rust. It's ready for daily use.
 - [Completion](https://github.com/mitnk/cicada/tree/master/docs/completion.md)
 - [RC File](https://github.com/mitnk/cicada/tree/master/docs/rc-file.md)
 - [History](https://github.com/mitnk/cicada/tree/master/docs/history.md)
+- [Job Control](https://github.com/mitnk/cicada/tree/master/docs/jobc.md)
 
 ## Try out cicada with Docker
 
@@ -89,6 +90,30 @@ $ (1 + 2) * (3 - 4) / 8.0
 -0.375
 ```
 
+### job control
+
+```
+# run sleep in backgroup
+$ sleep 200 &
+[1] 89
+# listing jobs
+$ jobs
+[1] 89  Running    sleep 200 &
+# bring it as foreground
+$ fg 1
+sleep 200
+# now you can use `Ctrl-Z` to suspend it
+^Z
+[1] 89  Stopped    sleep 200
+
+$ jobs
+[1] 89  Stopped    sleep 200
+# run it again (in background) with bg
+$ bg
+$ jobs
+[1] 89  Running    sleep 200 &
+```
+
 ## Cicada is also a library (BETA)
 
 Read APIs here: [https://docs.rs/cicada/](https://docs.rs/cicada/).

docs/as-lib.md

@@ -1,4 +1,4 @@
-# Use cicada as a Library
+# Use cicada as a Library (BETA)
 
 See latest API Docs here: [https://docs.rs/cicada/](https://docs.rs/cicada/)
 

docs/built-in-cmd.md

@@ -1,5 +1,9 @@
 # Cicada Built-in Commands
 
+## bg
+
+Make stopped job runing in background. See also `fg`, `jobs`.
+
 ## cd
 
 Change your current work directory.
@@ -30,6 +34,10 @@ $ export RUST_BACKTRACE=full
 $ export PYTHONPATH=.
 ```
 
+## fg
+
+Bring background job into foreground. See also `bg`, `jobs`.
+
 ## history
 
 List your recent history:
@@ -51,6 +59,11 @@ $ history 'curl%hugo'
 0: curl -x http://127.0.0.1:1080 https://hugo.wang/http/ip/
 ```
 
+## jobs
+
+Listing all jobs in [job control](https://github.com/mitnk/cicada/blob/master/docs/jobc.md).
+See also `bg`, `fg`.
+
 ## vox
 
 First create your virtual envs under this directory:

docs/jobc.md

@@ -0,0 +1,64 @@
+# Job Control
+
+In a single cicada session, you can run commands in background, and bring them
+foreground when needed.
+
+For example when download a file with `wget`:
+
+```
+$ wget 'https://speed.hetzner.de/100MB.bin'
+```
+
+We found it is too slow, we want it run in background instead. With
+cicada (just like bash), you could achieve it like this:
+
+```
+# press `Ctrl-Z` to stop it
+$ wget 'https://speed.hetzner.de/100MB.bin'
+^Z
+[1] 38273  Stopped    wget 'https://speed.hetzner.de/100MB.bin'
+```
+
+Then let's continue it running in background with builtin command `bg`:
+
+```
+$ bg
+wget 'https://speed.hetzner.de/100MB.bin' &
+```
+
+You can check the job status with command `jobs`:
+
+```
+$ jobs
+[1] 38273  Running    wget 'https://speed.hetzner.de/100MB.bin' &
+```
+
+Now you can start another job while `wget` is downloading. Let's download a
+even bigger file in background directly:
+
+```
+$ wget 'https://speed.hetzner.de/1GB.bin' &
+[2] 38337
+
+$ jobs
+[2] 38337  Running    wget 'https://speed.hetzner.de/1GB.bin' &
+[1] 38273  Running    wget 'https://speed.hetzner.de/100MB.bin' &
+```
+
+If you want to stop the `100M` file downloading. You can bring it foreground
+and then use `Ctrl-C` to terminate it.
+
+```
+$ fg 1
+wget 'https://speed.hetzner.de/100MB.bin'
+^C
+
+$ jobs
+[2] 38337  Running    wget 'https://speed.hetzner.de/1GB.bin' &
+```
+
+The number `1` in `fg 1`, is the job id, which shows in `jobs` command,
+indicating which job we want to bring.
+
+The number `38273` is the process group id of the job. `fg 28273` is an
+alternative to `fg 1` here.

src/builtins/fg.rs

@@ -32,10 +32,6 @@ pub fn run(sh: &mut shell::Shell, tokens: &types::Tokens) -> i32 {
         println_stderr!("cicada: not job id found");
     }
 
-    if tokens.len() == 1 {
-        println_stderr!("fg {}", job_id);
-    }
-
     let gid: i32;
     let pid_list: Vec<i32>;