From 6839a456aca1c685857fc6a15d43c0d1c666b8c7 Mon Sep 17 00:00:00 2001 From: Mughur Date: Fri, 24 Feb 2023 13:57:17 +0200 Subject: [PATCH] doc function updates and additions (#387) --- .../netscript/basicfunctions/closeTail.rst | 2 +- .../netscript/basicfunctions/deleteServer.rst | 2 +- doc/source/netscript/basicfunctions/exec.rst | 4 +-- .../netscript/basicfunctions/fileExists.rst | 6 ++-- .../netscript/basicfunctions/formatNumber.rst | 28 +++++++++++++++++++ .../basicfunctions/formatPercent.rst | 23 +++++++++++++++ .../netscript/basicfunctions/formatRam.rst | 26 +++++++++++++++++ .../netscript/basicfunctions/getScriptRam.rst | 2 +- .../basicfunctions/getSharePower.rst | 5 ++-- .../netscript/basicfunctions/isRunning.rst | 2 +- doc/source/netscript/basicfunctions/kill.rst | 3 +- .../netscript/basicfunctions/killall.rst | 2 +- .../netscript/basicfunctions/moveTail.rst | 2 +- doc/source/netscript/basicfunctions/mv.rst | 6 +++- .../netscript/basicfunctions/nFormat.rst | 6 +++- doc/source/netscript/basicfunctions/ps.rst | 2 +- .../basicfunctions/renamePurchasedServer.rst | 22 +++++++++++++++ .../netscript/basicfunctions/resizeTail.rst | 2 +- doc/source/netscript/basicfunctions/rm.rst | 19 +++++++++++++ doc/source/netscript/basicfunctions/run.rst | 4 +-- doc/source/netscript/basicfunctions/scan.rst | 2 +- doc/source/netscript/basicfunctions/scp.rst | 2 +- doc/source/netscript/basicfunctions/sleep.rst | 2 +- doc/source/netscript/basicfunctions/spawn.rst | 5 ++-- .../netscript/basicfunctions/tFormat.rst | 5 ++-- .../basicfunctions/upgradePurchasedServer.rst | 2 +- doc/source/netscript/netscriptfunctions.rst | 5 ++++ 27 files changed, 161 insertions(+), 30 deletions(-) create mode 100644 doc/source/netscript/basicfunctions/formatNumber.rst create mode 100644 doc/source/netscript/basicfunctions/formatPercent.rst create mode 100644 doc/source/netscript/basicfunctions/formatRam.rst create mode 100644 doc/source/netscript/basicfunctions/renamePurchasedServer.rst create mode 100644 doc/source/netscript/basicfunctions/rm.rst diff --git a/doc/source/netscript/basicfunctions/closeTail.rst b/doc/source/netscript/basicfunctions/closeTail.rst index 9013ce41a..f4fc77c64 100644 --- a/doc/source/netscript/basicfunctions/closeTail.rst +++ b/doc/source/netscript/basicfunctions/closeTail.rst @@ -1,7 +1,7 @@ closeTail() Netscript Function =============================== -.. js:function:: closeTail([scriptPid]) +.. js:function:: closeTail([scriptPid = current script]) :RAM cost: 0 GB diff --git a/doc/source/netscript/basicfunctions/deleteServer.rst b/doc/source/netscript/basicfunctions/deleteServer.rst index 59eda9492..33786f8e0 100644 --- a/doc/source/netscript/basicfunctions/deleteServer.rst +++ b/doc/source/netscript/basicfunctions/deleteServer.rst @@ -5,7 +5,7 @@ deleteServer() Netscript Function :RAM cost: 2.25 GB :param string hostname: Hostname of the server to delete. - :returns: ``true`` if successful, ``false`` otherwise. + :returns: ``true`` if successful. Deletes the specified purchased server. diff --git a/doc/source/netscript/basicfunctions/exec.rst b/doc/source/netscript/basicfunctions/exec.rst index 439e1df9a..a91a4abab 100644 --- a/doc/source/netscript/basicfunctions/exec.rst +++ b/doc/source/netscript/basicfunctions/exec.rst @@ -8,12 +8,12 @@ exec() Netscript Function :param string script: Filename of script to execute. :param string hostname: Hostname of the target server on which to execute the script. :param number numThreads: Optional thread count for new script. Set to 1 by - default. Will be rounded to nearest integer + default. Has to be an integer. :param args...: Additional arguments to pass into the new script that is being run. Note that if any arguments are being passed into the new script, then the third argument ``numThreads`` must be filled in with a value. - :returns: Newly created process id on success, 0 on failure. + :returns: Newly created process id (PID) on success, 0 on failure. Run a script as a separate process on a specified server. This is similar to the :doc:`run` function except that it can be used to run a script on any diff --git a/doc/source/netscript/basicfunctions/fileExists.rst b/doc/source/netscript/basicfunctions/fileExists.rst index d1ba92a28..2be373b17 100644 --- a/doc/source/netscript/basicfunctions/fileExists.rst +++ b/doc/source/netscript/basicfunctions/fileExists.rst @@ -1,7 +1,7 @@ fileExists() Netscript Function =============================== -.. js:function:: fileExists(filename[, hostname]) +.. js:function:: fileExists(filename[, hostname = current hostname]) :RAM cost: 0.1 GB @@ -9,9 +9,9 @@ fileExists() Netscript Function :param string hostname: Hostname of target server. This is optional. If it is not specified then the function will use the current server as the target server. - :returns: ``true`` if the file exists, ``false`` if it doesn't. + :returns: ``true`` if the file exists. - The filename for scripts is case-sensitive, but for other types of files it + The filename for scripts and .txt files is case-sensitive, but for other types of files it is not. For example, ``fileExists("brutessh.exe")`` will work fine, even though the actual program is named ``BruteSSH.exe``. diff --git a/doc/source/netscript/basicfunctions/formatNumber.rst b/doc/source/netscript/basicfunctions/formatNumber.rst new file mode 100644 index 000000000..766dcd06d --- /dev/null +++ b/doc/source/netscript/basicfunctions/formatNumber.rst @@ -0,0 +1,28 @@ +formatRam() Netscript Function +============================== + +.. js:function:: formatRam(number[, fractionalDigits = 3[, suffixStart = 1000[, isInteger = false]]]) + :RAM cost: 0 GB + + :param number number: Number to format. + :param number fractionalDigits: Number of digits to show in the fractional part of the decimal number. + :param number suffixStart: How high a number must be before a suffix will be added. + :param boolean isInteger: Whether the number represents an integer. Integers do not display fractional digits until a suffix is present. + + :returns: Formatted string. + + Converts a number into a string with ram formatting. + + The format depends on the Numeric Display settings (all options on the "Numeric Display" options page). + + Examples: + + .. code-block:: javascript + + const number = 1.23456789 + ns.print(ns.formatNumber(number)); //1.235 + ns.print(ns.formatNumber(number,4)); //1.2346 + ns.print(ns.formatNumber(number*1e9,3,1e10)); //1234567890 + ns.print(ns.formatNumber(number*1e10,5,1e6)); //12.34568b or 1.23457e9 + ns.print(ns.formatNumber(number,4,1000, true)); //1.235 + ns.print(ns.formatNumber(number,4,1000, false)); //1.2346 \ No newline at end of file diff --git a/doc/source/netscript/basicfunctions/formatPercent.rst b/doc/source/netscript/basicfunctions/formatPercent.rst new file mode 100644 index 000000000..b14d0a551 --- /dev/null +++ b/doc/source/netscript/basicfunctions/formatPercent.rst @@ -0,0 +1,23 @@ +formatPercent() Netscript Function +============================== + +.. js:function:: formatPercent(number[, fractionalDigits = 2]) + + :RAM cost: 0 GB + + :param number number: Number to format. + :param number fractionalDigits: Number of digits to show in the fractional part of the decimal number. + + :returns: Formatted string. + + Converts a number into a string with percent formatting. + + The format depends on the Numeric Display settings (all options on the "Numeric Display" options page). + + Examples: + + .. code-block:: javascript + + const number = 1.23456789 + ns.print(ns.formatPercent(number)); //123.46% + ns.print(ns.formatPercent(number,4)); //123.4568% \ No newline at end of file diff --git a/doc/source/netscript/basicfunctions/formatRam.rst b/doc/source/netscript/basicfunctions/formatRam.rst new file mode 100644 index 000000000..ce0036563 --- /dev/null +++ b/doc/source/netscript/basicfunctions/formatRam.rst @@ -0,0 +1,26 @@ +formatRam() Netscript Function +============================== + +.. js:function:: formatRam(number[, fractionalDigits = 2]) + + :RAM cost: 0 GB + + :param number number: Number to format. + :param number fractionalDigits: Number of digits to show in the fractional part of the decimal number. + + :returns: Formatted string. + + Converts a number into a string with ram formatting. + + The format depends on the Numeric Display settings (all options on the "Numeric Display" options page). + + Examples: + + .. code-block:: javascript + + const number = 1.23456789 + ns.print(ns.formatRam(number)); //1.23GB or 1.23GiB + ns.print(ns.formatRam(number,0)); //1GB or 1GiB + ns.print(ns.formatRam(number,3)); //1.235GB or 1.235GiB + ns.print(ns.formatRam(2**12,3)); //4.096tB or 4tiB + ns.print(ns.formatRam(2**20,3)); //1.049PB or 1PiB \ No newline at end of file diff --git a/doc/source/netscript/basicfunctions/getScriptRam.rst b/doc/source/netscript/basicfunctions/getScriptRam.rst index 5cba96424..ef02fe4f4 100644 --- a/doc/source/netscript/basicfunctions/getScriptRam.rst +++ b/doc/source/netscript/basicfunctions/getScriptRam.rst @@ -1,7 +1,7 @@ getScriptRam() Netscript Function ================================= -.. js:function:: getScriptRam(filename[, hostname]) +.. js:function:: getScriptRam(filename[, hostname = current hostname]) :RAM cost: 0.1 GB :param string filename: Filename of script. diff --git a/doc/source/netscript/basicfunctions/getSharePower.rst b/doc/source/netscript/basicfunctions/getSharePower.rst index 20a43bab6..ff6a46728 100644 --- a/doc/source/netscript/basicfunctions/getSharePower.rst +++ b/doc/source/netscript/basicfunctions/getSharePower.rst @@ -5,8 +5,9 @@ getSharePower() Netscript Function :RAM cost: 0.2 GB - Calculate your share power. Based on all the active share calls. - Returns the reputation gain rate multiplier, i.e. 1.5 means +50% rep gain rate. + :returns: Reputation gain rate multiplier from sharing. i.e. 1.5 means +50% rep gain rate. + + Calculate your share power, based on all the active share calls. Examples: diff --git a/doc/source/netscript/basicfunctions/isRunning.rst b/doc/source/netscript/basicfunctions/isRunning.rst index dea0a5f63..64d4d8d70 100644 --- a/doc/source/netscript/basicfunctions/isRunning.rst +++ b/doc/source/netscript/basicfunctions/isRunning.rst @@ -1,7 +1,7 @@ isRunning() Netscript Function ============================== -.. js:function:: isRunning(filename[, hostname=current hostname[, args...]]) +.. js:function:: isRunning(filename[, hostname = current hostname[, args...]]) .. js:function:: isRunning(PID) :RAM cost: 0.1 GB diff --git a/doc/source/netscript/basicfunctions/kill.rst b/doc/source/netscript/basicfunctions/kill.rst index 3ebe564d2..c6d00ab54 100644 --- a/doc/source/netscript/basicfunctions/kill.rst +++ b/doc/source/netscript/basicfunctions/kill.rst @@ -1,8 +1,7 @@ kill() Netscript Function ========================= -.. js:function:: kill(script, [hostname=current hostname, [args...]]) -.. js:function:: kill(PID) +.. js:function:: kill(script[, hostname=current hostname[, args...]]) :RAM cost: 0.5 GB :param string script: Filename of the script to kill. diff --git a/doc/source/netscript/basicfunctions/killall.rst b/doc/source/netscript/basicfunctions/killall.rst index e2d3a4873..182d957bc 100644 --- a/doc/source/netscript/basicfunctions/killall.rst +++ b/doc/source/netscript/basicfunctions/killall.rst @@ -1,7 +1,7 @@ killall() Netscript Function ============================ -.. js:function:: killall([hostname = current hostname,[safetyguard = true]]) +.. js:function:: killall([hostname = current hostname[, safetyguard = true]]) :RAM cost: 0.5 GB :param string hostname: Hostname of the server on which to kill all scripts. diff --git a/doc/source/netscript/basicfunctions/moveTail.rst b/doc/source/netscript/basicfunctions/moveTail.rst index 0a6ad21e5..9b64b250e 100644 --- a/doc/source/netscript/basicfunctions/moveTail.rst +++ b/doc/source/netscript/basicfunctions/moveTail.rst @@ -1,7 +1,7 @@ moveTail() Netscript Function =============================== -.. js:function:: moveTail(x , y[, pid]) +.. js:function:: moveTail(x , y[, pid = current script]) :RAM cost: 0 GB diff --git a/doc/source/netscript/basicfunctions/mv.rst b/doc/source/netscript/basicfunctions/mv.rst index 60589ee41..859037856 100644 --- a/doc/source/netscript/basicfunctions/mv.rst +++ b/doc/source/netscript/basicfunctions/mv.rst @@ -1,10 +1,14 @@ mv() Netscript Function ============================== -.. js:function:: mv(serverName, sourceFile, targetFile) +.. js:function:: mv(hostname, sourceFile, targetFile) :RAM cost: 0 GB + :param string hostname: Hostname of the target server. + :param string sourceFile: Name of the file to be moved/renamed. + :param string targetFile: Target name of the file. + Move the source file to target file on the given server. This command only works for scripts and text files (.txt). It cannot, however, be used to convert from script to text file, or vice versa. diff --git a/doc/source/netscript/basicfunctions/nFormat.rst b/doc/source/netscript/basicfunctions/nFormat.rst index f66214389..88d7c839e 100644 --- a/doc/source/netscript/basicfunctions/nFormat.rst +++ b/doc/source/netscript/basicfunctions/nFormat.rst @@ -7,8 +7,12 @@ nFormat() Netscript Function :param number number: Number to format. :param string format: Formatting to use. Read http://numeraljs.com/#format for specifics. + :returns: Formatted string. - onverts a number into a string with the specified formatter. + Deprecated, might be removed in 2.3 version of the game. Use :doc:`formatPercent` for formatting percentages, + :doc:`formatRam` for formatting ram amounts and :doc:`formatNumber` for formatting other numbers. + + Converts a number into a string with the specified formatter. This uses the numeral.js library, so the formatters must be compatible with that. Examples: diff --git a/doc/source/netscript/basicfunctions/ps.rst b/doc/source/netscript/basicfunctions/ps.rst index da5d42f47..acf57aa9a 100644 --- a/doc/source/netscript/basicfunctions/ps.rst +++ b/doc/source/netscript/basicfunctions/ps.rst @@ -6,7 +6,7 @@ ps() Netscript Function :RAM cost: 0.2 GB :param string hostname: Hostname address of the target server. If not specified, it will be the current server's IP by default. - :returns: array of object + :returns: array of objects Returns an array with general information about all scripts running on the specified target server. The information for each server is given in an diff --git a/doc/source/netscript/basicfunctions/renamePurchasedServer.rst b/doc/source/netscript/basicfunctions/renamePurchasedServer.rst new file mode 100644 index 000000000..1df3805b5 --- /dev/null +++ b/doc/source/netscript/basicfunctions/renamePurchasedServer.rst @@ -0,0 +1,22 @@ +renamePurchasedServer() Netscript Function +=================================== + +.. js:function:: renamePurchasedServer(hostname, newName) + + :RAM cost: 2 GB + :param string hostname: Hostname of the purchased server. + :param string newName: New name for the given server. + :returns: ``true`` if the renaming was succesful. + + Upgrades the purchased server with the specified hostname to have specified amount of RAM. + + The ``hostname`` argument can be any data type, but it will be converted to + a string and have whitespace removed. New RAM amount has to be higher than the current RAM + and a power of 2. Upgrading a server costs the difference of old RAM server cost and new RAM + server cost. + + Example: + + .. code-block:: javascript + + ns.renamePurchasedServer("server", "old_server"); diff --git a/doc/source/netscript/basicfunctions/resizeTail.rst b/doc/source/netscript/basicfunctions/resizeTail.rst index eaaf8e7b3..2a8a14698 100644 --- a/doc/source/netscript/basicfunctions/resizeTail.rst +++ b/doc/source/netscript/basicfunctions/resizeTail.rst @@ -1,7 +1,7 @@ resizeTail() Netscript Function =============================== -.. js:function:: resizeTail(width, heigth[, pid]) +.. js:function:: resizeTail(width, heigth[, pid = current script]) :RAM cost: 0 GB diff --git a/doc/source/netscript/basicfunctions/rm.rst b/doc/source/netscript/basicfunctions/rm.rst new file mode 100644 index 000000000..0bbe806e8 --- /dev/null +++ b/doc/source/netscript/basicfunctions/rm.rst @@ -0,0 +1,19 @@ +mv() Netscript Function +============================== + +.. js:function:: rm(Filename [,hostname = current hostname]) + + :RAM cost: 0 GB + + :param string Filename: Name of the file to be deleted. + :param string hostname: Hostname of the target server. + + Delete a file on the given server. + + .. warning!:: There is no safetychecks or recycling bins. Deleted files are lost. + + Examples: + + .. code-block:: javascript + + ns.rm("foo.js"); \ No newline at end of file diff --git a/doc/source/netscript/basicfunctions/run.rst b/doc/source/netscript/basicfunctions/run.rst index aa3a05c81..29d86f623 100644 --- a/doc/source/netscript/basicfunctions/run.rst +++ b/doc/source/netscript/basicfunctions/run.rst @@ -6,12 +6,12 @@ run() Netscript Function :RAM cost: 1 GB :param string script: Filename of script to run :param number numThreads: Optional thread count for new script. Set to 1 by - default. Will be rounded to nearest integer. + default. Has to be an integer. :param args...: Additional arguments to pass into the new script that is being run. Note that if any arguments are being passed into the new script, then the second argument ``numThreads`` must be filled in with a value. - :returns: The process id of the new process or 0 on failure. + :returns: The process id (PID) of the new process or 0 on failure. Run a script as a separate process. This function can only be used to run scripts located on the current server (the server running the script that diff --git a/doc/source/netscript/basicfunctions/scan.rst b/doc/source/netscript/basicfunctions/scan.rst index b3cc695f5..6284967e9 100644 --- a/doc/source/netscript/basicfunctions/scan.rst +++ b/doc/source/netscript/basicfunctions/scan.rst @@ -1,7 +1,7 @@ scan() Netscript Function ========================= -.. js:function:: scan(hostname=current hostname) +.. js:function:: scan(hostname = current hostname) :RAM cost: 0.2 GB :param string hostname: Hostname of the server to scan. diff --git a/doc/source/netscript/basicfunctions/scp.rst b/doc/source/netscript/basicfunctions/scp.rst index 88d170f3b..9e334ab98 100644 --- a/doc/source/netscript/basicfunctions/scp.rst +++ b/doc/source/netscript/basicfunctions/scp.rst @@ -1,7 +1,7 @@ scp() Netscript Function ======================== -.. js:function:: scp(files, destination [, source]) +.. js:function:: scp(files, destination [, source = current hostname]) :RAM cost: 0.6 GB :param string/array files: Filename or an array of filenames of script/literature files to copy diff --git a/doc/source/netscript/basicfunctions/sleep.rst b/doc/source/netscript/basicfunctions/sleep.rst index 3b6aa6ae6..6c06d2a8e 100644 --- a/doc/source/netscript/basicfunctions/sleep.rst +++ b/doc/source/netscript/basicfunctions/sleep.rst @@ -1,7 +1,7 @@ sleep() Netscript Function ========================== -.. js:function:: sleep(n) +.. js:function:: sleep([n = 0]) :RAM cost: 0 GB :param number n: Number of milliseconds to sleep diff --git a/doc/source/netscript/basicfunctions/spawn.rst b/doc/source/netscript/basicfunctions/spawn.rst index d04650e6e..ec3a1d4c4 100644 --- a/doc/source/netscript/basicfunctions/spawn.rst +++ b/doc/source/netscript/basicfunctions/spawn.rst @@ -1,12 +1,11 @@ spawn() Netscript Function ========================== -.. js:function:: spawn(script, numThreads[, args...]) +.. js:function:: spawn(script[, numThreads = 1[, args...]]) :RAM cost: 2 GB :param string script: Filename of script to execute - :param number numThreads: Number of threads to spawn new script with. Will - be rounded to nearest integer. + :param number numThreads: Number of threads to spawn new script with. Has to be an integer. :param args...: Additional arguments to pass into the new script that is being run. diff --git a/doc/source/netscript/basicfunctions/tFormat.rst b/doc/source/netscript/basicfunctions/tFormat.rst index 0c7436496..1085c5a0b 100644 --- a/doc/source/netscript/basicfunctions/tFormat.rst +++ b/doc/source/netscript/basicfunctions/tFormat.rst @@ -1,12 +1,13 @@ tFormat() Netscript Function ============================== -.. js:function:: tFormat(milliseconds[, milliPrecision]) +.. js:function:: tFormat(milliseconds[, milliPrecision = false]) :RAM cost: 0 GB :param string milliseconds: Number of millisecond to format. - :param boolean milliPrecision: Format time with subsecond precision. Defaults to false. + :param boolean milliPrecision: Format time with subsecond precision. + :returns: Formatted string. Format time to a readable string. diff --git a/doc/source/netscript/basicfunctions/upgradePurchasedServer.rst b/doc/source/netscript/basicfunctions/upgradePurchasedServer.rst index 61f761ef5..299ebbe0e 100644 --- a/doc/source/netscript/basicfunctions/upgradePurchasedServer.rst +++ b/doc/source/netscript/basicfunctions/upgradePurchasedServer.rst @@ -7,7 +7,7 @@ upgradePurchasedServer() Netscript Function :param string hostname: Hostname of the purchased server. :param number ram: Amount of RAM of the purchased server. Must be a power of 2. Maximum value of :doc:`getPurchasedServerMaxRam` - :returns: ``true`` if the upgrade succeeded, ``false`` otherwise + :returns: ``true`` if the upgrade succeeded. Upgrades the purchased server with the specified hostname to have specified amount of RAM. diff --git a/doc/source/netscript/netscriptfunctions.rst b/doc/source/netscript/netscriptfunctions.rst index 2e40a63c0..7d0525a6b 100644 --- a/doc/source/netscript/netscriptfunctions.rst +++ b/doc/source/netscript/netscriptfunctions.rst @@ -18,6 +18,9 @@ This includes information such as function signatures, what they do, and their r tprint() tFormat() nFormat() + formatNumber() + formatPercent() + formatRam() disableLog() enableLog() isLogEnabled() @@ -44,6 +47,7 @@ This includes information such as function signatures, what they do, and their r ls() ps() mv() + rm() hasRootAccess() getHostname() getHackingLevel() @@ -63,6 +67,7 @@ This includes information such as function signatures, what they do, and their r purchaseServer() deleteServer() upgradePurchasedServer() + renamePurchasedServer() getPurchasedServers() getPurchasedServerLimit() getPurchasedServerMaxRam()