PIPE: Add pipe support for passing data into and out of terminal commands (#2395)

src/Documentation/doc/en/index.md

@@ -28,6 +28,9 @@
 ## Advanced Mechanics
 
 - [Hacking algorithms](programming/hackingalgorithms.md)
+- [IPvGO](programming/go_algorithms.md)
+- [Darkweb Network](programming/darknet.md)
+- [Terminal Pipes and Redirects](programming/terminal_pipes_and_redirects.md)
 - [List of factions and their requirements](advanced/faction_list.md)
 - [Offline scripts and bonus time](advanced/offlineandbonustime.md)
 - [BitNodes](advanced/bitnodes.md)
@@ -42,8 +45,6 @@
 - [Sleeves](advanced/sleeves.md)
 - [Grafting](advanced/grafting.md)
 - [Stanek's Gift](advanced/stanek.md)
-- [IPvGO](programming/go_algorithms.md)
-- [Darkweb Network](programming/darknet.md)
 
 ## Resources
 

src/Documentation/doc/en/programming/terminal_pipes_and_redirects.md

@@ -0,0 +1,60 @@
+# Terminal Pipes and Redirects - WIP
+
+The output of commands and scripts, that normally would be logged to the terminal, can instead be redirected and sent to another location.
+
+For example, `echo` logs whatever input it is given.
+
+```
+[home /]> echo test123
+test123
+```
+
+However, its output can instead be sent to a file using the output redirect `>` :
+
+```
+[home /]> echo test123 >> newFile.txt
+```
+
+After this, `newFile.txt` will be created (if it didn't exist) and will contain `test123`
+
+### Accessing stdin via script
+
+```js
+/** @param {NS} ns */
+async function read(ns) {
+  const stdin = ns.getStdin();
+  if (stdin.empty()) {
+    await stdin.nextWrite();
+  }
+  return stdin.read();
+}
+```
+
+### Creating your own command line utilities
+
+`cut.js` using `read()` from the snippet above
+
+```js
+/** @param {NS} ns */
+export async function main(ns) {
+  if (!ns.getStdin()) {
+    ns.tprint("ERROR: No piped input given");
+    return;
+  }
+
+  // The '-c' flag expects a range of characters like 2-4
+  // Other flags, such as '-b' bytes and '-d' delimeter, are left as an excercise for the reader
+  const flags = ns.flags([["c", "0"]]);
+  const charCountRange = flags.c.split("-");
+  const startCharCount = Number(charCountRange[0]?.trim());
+  const endCharCount = Number(charCountRange[1]?.trim() ?? startCharCount);
+
+  let data = await read(ns);
+  while (data != null) {
+    // slice the characters from the input data to specified range, and print them (aka send to stdout)
+    // tprintf is used to avoid printing the script's filename and line number before the message
+    ns.tprintf("%s", data.slice(startCharCount - 1, endCharCount));
+    data = await read(ns);
+  }
+}
+```

src/Documentation/pages.ts

@@ -65,7 +65,8 @@ import file62 from "./doc/en/programming/go_algorithms.md?raw";
 import file63 from "./doc/en/programming/hackingalgorithms.md?raw";
 import file64 from "./doc/en/programming/learn.md?raw";
 import file65 from "./doc/en/programming/remote_api.md?raw";
-import file66 from "./doc/en/programming/typescript_react.md?raw";
+import file66 from "./doc/en/programming/terminal_pipes_and_redirects.md?raw";
+import file67 from "./doc/en/programming/typescript_react.md?raw";
 
 import nsDoc_bitburner__valueof_md from "../../markdown/bitburner._valueof.md?raw";
 import nsDoc_bitburner_activefragment_highestcharge_md from "../../markdown/bitburner.activefragment.highestcharge.md?raw";
@@ -1047,6 +1048,7 @@ import nsDoc_bitburner_ns_getserverrequiredhackinglevel_md from "../../markdown/
 import nsDoc_bitburner_ns_getserversecuritylevel_md from "../../markdown/bitburner.ns.getserversecuritylevel.md?raw";
 import nsDoc_bitburner_ns_getserverusedram_md from "../../markdown/bitburner.ns.getserverusedram.md?raw";
 import nsDoc_bitburner_ns_getsharepower_md from "../../markdown/bitburner.ns.getsharepower.md?raw";
+import nsDoc_bitburner_ns_getstdin_md from "../../markdown/bitburner.ns.getstdin.md?raw";
 import nsDoc_bitburner_ns_gettotalscriptexpgain_md from "../../markdown/bitburner.ns.gettotalscriptexpgain.md?raw";
 import nsDoc_bitburner_ns_gettotalscriptincome_md from "../../markdown/bitburner.ns.gettotalscriptincome.md?raw";
 import nsDoc_bitburner_ns_getweakentime_md from "../../markdown/bitburner.ns.getweakentime.md?raw";
@@ -1656,7 +1658,8 @@ AllPages["en/programming/go_algorithms.md"] = file62;
 AllPages["en/programming/hackingalgorithms.md"] = file63;
 AllPages["en/programming/learn.md"] = file64;
 AllPages["en/programming/remote_api.md"] = file65;
-AllPages["en/programming/typescript_react.md"] = file66;
+AllPages["en/programming/terminal_pipes_and_redirects.md"] = file66;
+AllPages["en/programming/typescript_react.md"] = file67;
 
 AllPages["nsDoc/bitburner._valueof.md"] = nsDoc_bitburner__valueof_md;
 AllPages["nsDoc/bitburner.activefragment.highestcharge.md"] = nsDoc_bitburner_activefragment_highestcharge_md;
@@ -2638,6 +2641,7 @@ AllPages["nsDoc/bitburner.ns.getserverrequiredhackinglevel.md"] = nsDoc_bitburne
 AllPages["nsDoc/bitburner.ns.getserversecuritylevel.md"] = nsDoc_bitburner_ns_getserversecuritylevel_md;
 AllPages["nsDoc/bitburner.ns.getserverusedram.md"] = nsDoc_bitburner_ns_getserverusedram_md;
 AllPages["nsDoc/bitburner.ns.getsharepower.md"] = nsDoc_bitburner_ns_getsharepower_md;
+AllPages["nsDoc/bitburner.ns.getstdin.md"] = nsDoc_bitburner_ns_getstdin_md;
 AllPages["nsDoc/bitburner.ns.gettotalscriptexpgain.md"] = nsDoc_bitburner_ns_gettotalscriptexpgain_md;
 AllPages["nsDoc/bitburner.ns.gettotalscriptincome.md"] = nsDoc_bitburner_ns_gettotalscriptincome_md;
 AllPages["nsDoc/bitburner.ns.getweakentime.md"] = nsDoc_bitburner_ns_getweakentime_md;