mirror of
https://github.com/bitburner-official/bitburner-src.git
synced 2026-04-16 06:18:42 +02:00
DOCS: Add docs for autocomplete (#1981)
This commit is contained in:
muesli4brekkies
GitHub
97
src/Documentation/doc/basic/autocomplete.md
Normal file
97
src/Documentation/doc/basic/autocomplete.md
Normal file
@@ -0,0 +1,97 @@
|
||||
# Autocomplete
|
||||
|
||||
The BitBurner terminal offers tab-completion, where pressing tab after typing a command offers suggestions for arguments to pass. You can customize this behavior for your scripts.
|
||||
|
||||
This relies on an exported function named "autocomplete" that is placed _outside_ of main, in the base scope of the script.
|
||||
|
||||
This function must return an array, the contents of which make up the autocomplete options.
|
||||
|
||||
A basic example as a complete script;
|
||||
|
||||
```javascript
|
||||
/**
|
||||
* @param {AutocompleteData} data - context about the game, useful when autocompleting
|
||||
* @param {string[]} args - current arguments, not including "run script.js"
|
||||
* @returns {string[]} - the array of possible autocomplete options
|
||||
*/
|
||||
export function autocomplete(data, args) {
|
||||
return ["argument0", "argument1", "argument2"];
|
||||
}
|
||||
|
||||
/** @param {NS} ns */
|
||||
export function main(ns) {
|
||||
const args = ns.args;
|
||||
ns.tprint(args[0], args[1], args[2]);
|
||||
}
|
||||
```
|
||||
|
||||
Running this script from the terminal like `run script.js` or `./script.js` and pressing tab, would offer "argument0", "argument1" and "argument2" as autocomplete options.
|
||||
|
||||
## AutocompleteData
|
||||
|
||||
To make this feature more useful, an [AutocompleteData](https://github.com/bitburner-official/bitburner-src/blob/stable/markdown/bitburner.autocompletedata.md) object is provided to the autocomplete function that holds information commonly passed as arguments to scripts, such as server names and filenames.
|
||||
|
||||
AutocompleteData is an object with the following properties;
|
||||
|
||||
```javascript
|
||||
{
|
||||
command: // the command being run, as seen on the terminal.
|
||||
enums: // the ns.enums object with various in-game strings.
|
||||
filename: // the name of the script file containing the autocomplete function.
|
||||
hostname: // the name of the host server the script would be running on.
|
||||
processes: // list of all processes running on the current server.
|
||||
servers: // list of all servers in the game.
|
||||
txts: // list of all text files on the current server.
|
||||
scripts: // list of all scripts on the current server.
|
||||
flags: // the same flags function as passed with ns. Calling this function adds all the flags as autocomplete arguments.
|
||||
}
|
||||
```
|
||||
|
||||
Here is a more complete example, utilising and returning information from the AutocompleteData object.
|
||||
|
||||
```javascript
|
||||
/**
|
||||
* @param {AutocompleteData} data - context about the game, useful when autocompleting
|
||||
* @param {string[]} args - current arguments, not including "run script.js"
|
||||
* @returns {string[]} - the array of possible autocomplete options
|
||||
*/
|
||||
export function autocomplete(data, args) {
|
||||
const scripts = data.scripts;
|
||||
const servers = data.servers;
|
||||
|
||||
const gymTypesObject = data.enums.GymType; // The data.enums holds the enum information as objects.
|
||||
const gymTypes = Object.values(gymTypesObject); // We are only interested in the string values from the enums object.
|
||||
|
||||
return [...scripts, ...servers, ...gymTypes]; // Offer a list of all servers, all scripts on the current server, and gym jobs ("str", "agi" etc) as autocomplete options.
|
||||
}
|
||||
```
|
||||
|
||||
## args
|
||||
|
||||
The args array is also passed to the autocomplete function as a second parameter. Similar to ns.args passed to `main` in normal scripts, this array contains the arguments currently inputted into the terminal.
|
||||
|
||||
This can be used to remove already passed arguments from the autocomplete suggestions.
|
||||
|
||||
For example;
|
||||
|
||||
```javascript
|
||||
/**
|
||||
* @param {AutocompleteData} data - context about the game, useful when autocompleting
|
||||
* @param {string[]} args - current arguments, not including "run script.js"
|
||||
* @returns {string[]} - the array of possible autocomplete options
|
||||
*/
|
||||
export function autocomplete(data, args) {
|
||||
const servers = data.servers;
|
||||
const serversWithArgsRemoved = servers.filter((server) => !args.includes(server));
|
||||
|
||||
return serversWithArgsRemoved;
|
||||
}
|
||||
```
|
||||
|
||||
In that example typing `run script.js` and pressing tab would initially suggest every server for autocomplete. Then if "n00dles" is added to the arguments and tab is pressed again, "n00dles" would no longer be suggested in subsequent autocomplete calls.
|
||||
|
||||
# Notes
|
||||
|
||||
- The autocomplete function in the file is called each time the tab key is pressed following `run file.js` or `./file.js` in the terminal.
|
||||
- The autocomplete function is separate from `main`, and does not receive an `ns` context as a parameter. This means no `ns` game commands will work in autocomplete functions.
|
||||
- If a multi-element array is returned then multiple options are displayed. If a single-element array is returned then that element is auto-filled to the terminal. This is handy for the "--tail" run argument, for example.
|
||||
@@ -23,6 +23,7 @@
|
||||
- [Stock market](basic/stockmarket.md)
|
||||
- [World](basic/world.md)
|
||||
- [Coding contracts](basic/codingcontracts.md)
|
||||
- [Autocomplete](basic/autocomplete.md)
|
||||
|
||||
## Advanced Mechanics
|
||||
|
||||
|
||||
@@ -29,38 +29,39 @@ import file26 from "./doc/advanced/sleeves.md?raw";
|
||||
import file27 from "./doc/advanced/sourcefiles.md?raw";
|
||||
import file28 from "./doc/advanced/stanek.md?raw";
|
||||
import file29 from "./doc/basic/augmentations.md?raw";
|
||||
import file30 from "./doc/basic/codingcontracts.md?raw";
|
||||
import file31 from "./doc/basic/companies.md?raw";
|
||||
import file32 from "./doc/basic/crimes.md?raw";
|
||||
import file33 from "./doc/basic/factions.md?raw";
|
||||
import file34 from "./doc/basic/hacking.md?raw";
|
||||
import file35 from "./doc/basic/hacknet_nodes.md?raw";
|
||||
import file36 from "./doc/basic/infiltration.md?raw";
|
||||
import file37 from "./doc/basic/programs.md?raw";
|
||||
import file38 from "./doc/basic/ram.md?raw";
|
||||
import file39 from "./doc/basic/reputation.md?raw";
|
||||
import file40 from "./doc/basic/scripts.md?raw";
|
||||
import file41 from "./doc/basic/servers.md?raw";
|
||||
import file42 from "./doc/basic/stats.md?raw";
|
||||
import file43 from "./doc/basic/stockmarket.md?raw";
|
||||
import file44 from "./doc/basic/terminal.md?raw";
|
||||
import file45 from "./doc/basic/world.md?raw";
|
||||
import file46 from "./doc/changelog-v0.md?raw";
|
||||
import file47 from "./doc/changelog-v1.md?raw";
|
||||
import file48 from "./doc/changelog.md?raw";
|
||||
import file49 from "./doc/help/bitnode_order.md?raw";
|
||||
import file50 from "./doc/help/getting_started.md?raw";
|
||||
import file51 from "./doc/help/tools_and_resources.md?raw";
|
||||
import file52 from "./doc/index.md?raw";
|
||||
import file53 from "./doc/migrations/ns2.md?raw";
|
||||
import file54 from "./doc/migrations/v1.md?raw";
|
||||
import file55 from "./doc/migrations/v2.md?raw";
|
||||
import file56 from "./doc/programming/game_frozen.md?raw";
|
||||
import file57 from "./doc/programming/go_algorithms.md?raw";
|
||||
import file58 from "./doc/programming/hackingalgorithms.md?raw";
|
||||
import file59 from "./doc/programming/learn.md?raw";
|
||||
import file60 from "./doc/programming/react.md?raw";
|
||||
import file61 from "./doc/programming/remote_api.md?raw";
|
||||
import file30 from "./doc/basic/autocomplete.md?raw";
|
||||
import file31 from "./doc/basic/codingcontracts.md?raw";
|
||||
import file32 from "./doc/basic/companies.md?raw";
|
||||
import file33 from "./doc/basic/crimes.md?raw";
|
||||
import file34 from "./doc/basic/factions.md?raw";
|
||||
import file35 from "./doc/basic/hacking.md?raw";
|
||||
import file36 from "./doc/basic/hacknet_nodes.md?raw";
|
||||
import file37 from "./doc/basic/infiltration.md?raw";
|
||||
import file38 from "./doc/basic/programs.md?raw";
|
||||
import file39 from "./doc/basic/ram.md?raw";
|
||||
import file40 from "./doc/basic/reputation.md?raw";
|
||||
import file41 from "./doc/basic/scripts.md?raw";
|
||||
import file42 from "./doc/basic/servers.md?raw";
|
||||
import file43 from "./doc/basic/stats.md?raw";
|
||||
import file44 from "./doc/basic/stockmarket.md?raw";
|
||||
import file45 from "./doc/basic/terminal.md?raw";
|
||||
import file46 from "./doc/basic/world.md?raw";
|
||||
import file47 from "./doc/changelog-v0.md?raw";
|
||||
import file48 from "./doc/changelog-v1.md?raw";
|
||||
import file49 from "./doc/changelog.md?raw";
|
||||
import file50 from "./doc/help/bitnode_order.md?raw";
|
||||
import file51 from "./doc/help/getting_started.md?raw";
|
||||
import file52 from "./doc/help/tools_and_resources.md?raw";
|
||||
import file53 from "./doc/index.md?raw";
|
||||
import file54 from "./doc/migrations/ns2.md?raw";
|
||||
import file55 from "./doc/migrations/v1.md?raw";
|
||||
import file56 from "./doc/migrations/v2.md?raw";
|
||||
import file57 from "./doc/programming/game_frozen.md?raw";
|
||||
import file58 from "./doc/programming/go_algorithms.md?raw";
|
||||
import file59 from "./doc/programming/hackingalgorithms.md?raw";
|
||||
import file60 from "./doc/programming/learn.md?raw";
|
||||
import file61 from "./doc/programming/react.md?raw";
|
||||
import file62 from "./doc/programming/remote_api.md?raw";
|
||||
|
||||
import type { Document } from "./root.ts";
|
||||
|
||||
@@ -95,35 +96,36 @@ AllPages["advanced/sleeves.md"] = file26;
|
||||
AllPages["advanced/sourcefiles.md"] = file27;
|
||||
AllPages["advanced/stanek.md"] = file28;
|
||||
AllPages["basic/augmentations.md"] = file29;
|
||||
AllPages["basic/codingcontracts.md"] = file30;
|
||||
AllPages["basic/companies.md"] = file31;
|
||||
AllPages["basic/crimes.md"] = file32;
|
||||
AllPages["basic/factions.md"] = file33;
|
||||
AllPages["basic/hacking.md"] = file34;
|
||||
AllPages["basic/hacknet_nodes.md"] = file35;
|
||||
AllPages["basic/infiltration.md"] = file36;
|
||||
AllPages["basic/programs.md"] = file37;
|
||||
AllPages["basic/ram.md"] = file38;
|
||||
AllPages["basic/reputation.md"] = file39;
|
||||
AllPages["basic/scripts.md"] = file40;
|
||||
AllPages["basic/servers.md"] = file41;
|
||||
AllPages["basic/stats.md"] = file42;
|
||||
AllPages["basic/stockmarket.md"] = file43;
|
||||
AllPages["basic/terminal.md"] = file44;
|
||||
AllPages["basic/world.md"] = file45;
|
||||
AllPages["changelog-v0.md"] = file46;
|
||||
AllPages["changelog-v1.md"] = file47;
|
||||
AllPages["changelog.md"] = file48;
|
||||
AllPages["help/bitnode_order.md"] = file49;
|
||||
AllPages["help/getting_started.md"] = file50;
|
||||
AllPages["help/tools_and_resources.md"] = file51;
|
||||
AllPages["index.md"] = file52;
|
||||
AllPages["migrations/ns2.md"] = file53;
|
||||
AllPages["migrations/v1.md"] = file54;
|
||||
AllPages["migrations/v2.md"] = file55;
|
||||
AllPages["programming/game_frozen.md"] = file56;
|
||||
AllPages["programming/go_algorithms.md"] = file57;
|
||||
AllPages["programming/hackingalgorithms.md"] = file58;
|
||||
AllPages["programming/learn.md"] = file59;
|
||||
AllPages["programming/react.md"] = file60;
|
||||
AllPages["programming/remote_api.md"] = file61;
|
||||
AllPages["basic/autocomplete.md"] = file30;
|
||||
AllPages["basic/codingcontracts.md"] = file31;
|
||||
AllPages["basic/companies.md"] = file32;
|
||||
AllPages["basic/crimes.md"] = file33;
|
||||
AllPages["basic/factions.md"] = file34;
|
||||
AllPages["basic/hacking.md"] = file35;
|
||||
AllPages["basic/hacknet_nodes.md"] = file36;
|
||||
AllPages["basic/infiltration.md"] = file37;
|
||||
AllPages["basic/programs.md"] = file38;
|
||||
AllPages["basic/ram.md"] = file39;
|
||||
AllPages["basic/reputation.md"] = file40;
|
||||
AllPages["basic/scripts.md"] = file41;
|
||||
AllPages["basic/servers.md"] = file42;
|
||||
AllPages["basic/stats.md"] = file43;
|
||||
AllPages["basic/stockmarket.md"] = file44;
|
||||
AllPages["basic/terminal.md"] = file45;
|
||||
AllPages["basic/world.md"] = file46;
|
||||
AllPages["changelog-v0.md"] = file47;
|
||||
AllPages["changelog-v1.md"] = file48;
|
||||
AllPages["changelog.md"] = file49;
|
||||
AllPages["help/bitnode_order.md"] = file50;
|
||||
AllPages["help/getting_started.md"] = file51;
|
||||
AllPages["help/tools_and_resources.md"] = file52;
|
||||
AllPages["index.md"] = file53;
|
||||
AllPages["migrations/ns2.md"] = file54;
|
||||
AllPages["migrations/v1.md"] = file55;
|
||||
AllPages["migrations/v2.md"] = file56;
|
||||
AllPages["programming/game_frozen.md"] = file57;
|
||||
AllPages["programming/go_algorithms.md"] = file58;
|
||||
AllPages["programming/hackingalgorithms.md"] = file59;
|
||||
AllPages["programming/learn.md"] = file60;
|
||||
AllPages["programming/react.md"] = file61;
|
||||
AllPages["programming/remote_api.md"] = file62;
|
||||
|
||||
Reference in New Issue
Block a user