docs: add take_* & random sort (#102)

Co-authored-by: sxyazi <[email protected]>

docs/configuration/keymap.md

@@ -395,6 +395,7 @@ Move the cursor to the next or previous occurrence.
   - `"alphabetical"`: Sort alphabetically, e.g. `1.md` < `10.md` < `2.md`
   - `"natural"`: Sort naturally, e.g. `1.md` < `2.md` < `10.md`
   - `"size"`: Sort by file size.
+  - `"random"`: Sort randomly.
 - `--reverse`: Display files in reverse order. `--reverse` or `--reverse=yes` to reverse, `--reverse=no` to cancel.
 - `--dir-first`: Display directories first. `--dir-first` or `--dir-first=yes` to enable, `--dir-first=no` to cancel.
 - `--translit`: Transliterate filenames for sorting, see [sort_translit](/docs/configuration/yazi#manager.sort_translit) for details. `--translit` or `--translit=yes` to enable, `--translit=no` to cancel.

docs/configuration/yazi.md

@@ -28,6 +28,7 @@ File sorting method.
 - `"alphabetical"`: Sort alphabetically, e.g. `1.md` < `10.md` < `2.md`
 - `"natural"`: Sort naturally, e.g. `1.md` < `2.md` < `10.md`
 - `"size"`: Sort by file size.
+- `"random"`: Sort randomly.
 
 ### `sort_sensitive` {#manager.sort_sensitive}
 

docs/plugins/utils.md

@@ -674,6 +674,78 @@ Send a SIGTERM signal to the child process, returns `(ok, err)`:
 - `ok` - Whether the operation is successful, which is a boolean
 - `err` - The error code if the operation is failed, which is an integer if any
 
+### `take_stdin()` {#Child.take_stdin}
+
+```lua
+local stdin = child:take_stdin()
+```
+
+Take and return the stdin stream of the child process, which can only be called once and is only applicable to processes with [`stdin(Command.PIPED)`](/docs/plugins/utils#Command.stdin) set; otherwise, it returns `nil`.
+
+### `take_stdout()` {#Child.take_stdout}
+
+```lua
+local stderr = child:take_stdout()
+```
+
+Take and return the stdout stream of the child process, which can only be called once and is only applicable to processes with [`stdout(Command.PIPED)`](/docs/plugins/utils#Command.stdin) set; otherwise, it returns `nil`.
+
+This is useful when redirecting stdout to another process's stdin:
+
+```lua
+local echo = Command("echo"):arg("Hello"):stdout(Command.PIPED):spawn()
+
+local rev = Command("rev"):stdin(echo:take_stdout()):stdout(Command.PIPED):output()
+
+ya.err(rev.stdout) -- "olleH\n"
+```
+
+### `take_stderr()` {#Child.take_stderr}
+
+```lua
+local stderr = child:take_stderr()
+```
+
+Take and return the stderr stream of the child process, which can only be called once and is only applicable to processes with [`stderr(Command.PIPED)`](/docs/plugins/utils#Command.stdin) set; otherwise, it returns `nil`.
+
+See [`take_stdout()`](/docs/plugins/utils#Child.take_stdout) for an example.
+
+### `write_all(src)` {#Child.write_all}
+
+```lua
+local ok, err = child:write_all(src)
+```
+
+Writes all bytes from the string `src` to the stdin of the child process, returns:
+
+- `ok` - Whether the operation is successful, which is a boolean
+- `err` - The error code if the operation is failed, which is an integer if any
+
+Please ensure that the child's stdin is available when calling this method, specifically:
+
+1. [`stdin(Command.PIPED)`](/docs/plugins/utils#Command.stdin) is set
+2. [`take_stdin()`](/docs/plugins/utils#Child.take_stdin) has never been called
+
+otherwise, an error will be thrown.
+
+### `flush()` {#Child.flush}
+
+```lua
+local ok, err = child:flush()
+```
+
+Flushes any buffered data to the stdin of the child process, returns:
+
+- `ok` - Whether the operation is successful, which is a boolean
+- `err` - The error code if the operation is failed, which is an integer if any
+
+Please ensure that the child's stdin is available when calling this method, specifically:
+
+1. [`stdin(Command.PIPED)`](/docs/plugins/utils#Command.stdin) is set
+2. [`take_stdin()`](/docs/plugins/utils#Child.take_stdin) has never been called
+
+otherwise, an error will be thrown.
+
 ## Output
 
 Properties: