Added tryWrite() as a native Netscript function. Updated documentation to reflect the fact that port handles no longer work in Netscript 1.0

doc/source/netscript.rst

@@ -3,9 +3,10 @@ Netscript Documentation
 Netscript is the programming language used in the world of Bitburner.
 
 When you write scripts in Bitburner, they are written in the Netscript language.
-Netscript is simply a tiny subset of Javascript. This means that Netscript's
-syntax is almost idental to Javascript's, but it does not implement many of the
-features that Javascript has.
+Netscript is simply a subset of `JavaScript <https://developer.mozilla.org/en-US/docs/Web/JavaScript>`_,.
+This means that Netscript's syntax is
+identical to that of JavaScript, but it does not implement some of the features
+that JavaScript has.
 
 If you have any requests or suggestions to improve the Netscript language, feel free
 to reach out to the developer!

doc/source/netscript1.rst

@@ -2,14 +2,18 @@
 
 Netscript 1.0
 =============
-Netscript 1.0 is implemented using modified version of Neil Fraser's
+Netscript 1.0 is implemented using a modified version of Neil Fraser's
 `JS-Interpreter <https://github.com/NeilFraser/JS-Interpreter>`_.
 
-This interpreter was created for ES5, which means that the code written
-for Netscript 1.0 must be compliant for that version. However, some additional
-ES6+ features are implemented through polyfills.
+This is an ES5 JavaScript interpreter. This means that (almost) any JavaScript feature
+that is available in ES5 is also available in Netscript 1.0. However, this also means
+that the interpreter does not natively support any JavaScript features introduced in versions
+ES6 or after.
 
-Netscript 1.0 scripts end with the ".script" extension.
+If you are confused by the ES5/ES6/etc. terminology, consider reading this:
+`WTF is ES6, ES8, ES2017, ECMAScript... <https://codeburst.io/javascript-wtf-is-es6-es8-es-2017-ecmascript-dca859e4821c>`_
+
+Netscript 1.0 scripts end with the ".script" extension in their filenames.
 
 Which ES6+ features are supported?
 ----------------------------------

doc/source/netscriptfunctions.rst

@@ -659,14 +659,14 @@ getNextHacknetNodeCost
 
 .. js:function:: getNextHacknetNodeCost()
 
-    Deprecated (no longer usable). See :doc:`netscripthacknetnodeapi` 
+    Deprecated (no longer usable). See :doc:`netscripthacknetnodeapi`
 
 purchaseHacknetNode
 ^^^^^^^^^^^^^^^^^^^
 
 .. js:function:: purchaseHacknetNode()
 
-    Deprecated (no longer usable). See :doc:`netscripthacknetnodeapi` 
+    Deprecated (no longer usable). See :doc:`netscripthacknetnodeapi`
 
 getPurchasedServerCost
 ^^^^^^^^^^^^^^^^^^^^^^
@@ -772,6 +772,18 @@ write
     is set to "w", then the data is written in "write" mode which means that it will overwrite all existing data on the text file. If *mode* is set to
     any other value then the data will be written in "append" mode which means that the data will be added at the end of the text file.
 
+tryWrite
+^^^^^^^^
+
+.. js:function:: tryWrite(port, data="")
+
+    :param number port: Port to be written to
+    :param string data: Data to try to write
+    :returns: True if the data is successfully written to the port, and false otherwise
+
+    Attempts to write data to the specified Netscript Port. If the port is full, the data will
+    not be written. Otherwise, the data will be written normally
+
 read
 ^^^^
 
@@ -813,6 +825,17 @@ clear
 
     If the *port/fn* argument is a string, then it specifies the name of a text file (.txt) and will delete all data from that text file.
 
+getPortHandle
+^^^^^^^^^^^^^
+
+.. js:function:: getPortHandle(port)
+
+    :param number port: Port number
+
+    Get a handle to a Netscript Port. See more details here: :ref:`netscript_ports`
+
+    **WARNING:** Port Handles only work in :ref:`netscriptjs`. They will not work in :ref:`netscript1`.
+
 rm
 ^^
 

doc/source/netscriptmisc.rst

@@ -1,9 +1,13 @@
+.. _netscript_misc:
+
 Netscript Miscellaneous
 =======================
 
+.. _netscript_ports:
+
 Netscript Ports
 ---------------
-Netscript ports are endpoints that can be used to communicate between scripts.
+Netscript Ports are endpoints that can be used to communicate between scripts.
 A port is implemented as a sort of serialized queue, where you can only write
 and read one element at a time from the port. When you read data from a port,
 the element that is read is removed from the port.
@@ -55,9 +59,11 @@ And the data in port 1 will look like::
 
 **Port Handles**
 
+WARNING: Port Handles only work in :ref:`netscriptjs`. They do not work in :ref:`netscript1`
+
 The :js:func:`getPortHandle` Netscript function can be used to get a handle to a Netscript Port.
 This handle allows you to access several new port-related functions and the
-port's underlying data structure, which is just a Javascript array. The functions are:
+port's underlying data structure, which is just a JavaScript array. The functions are:
 
 .. js:method:: NetscriptPort.write(data)
 

src/Constants.js

@@ -493,10 +493,12 @@ let CONSTANTS = {
                                "World Stock Exchange account and TIX API Access<br>",
 
     LatestUpdate:
-    "v0.40.3<br>" +
-    "* b1t_flum3.exe program can now be created immediately at Hacking level 1 (rather than hacking level 5)<br>"  +
-    "* UI improvements for the character overview panel and the left-hand menu (by mat-jaworski)<br>" +
-    "* Improved the introductory tutorial<br>"
+    `v0.40.3<br>
+     * b1t_flum3.exe program can now be created immediately at Hacking level 1 (rather than hacking level 5)
+     * UI improvements for the character overview panel and the left-hand menu (by mat-jaworski)
+     * Updated documentation to reflect the fact that Netscript port handles (getPortHandle()) only works in NetscriptJS (2.0), NOT Netscript 1.0
+     * Added tryWrite() Netscript function
+     * Improved the introductory tutorial`
 
 
 }

src/InteractiveTutorial.js

@@ -268,7 +268,7 @@ function iTutorialEvaluateStep() {
                          "written in the Netscript language, a programming language created for " +
                          "this game. <strong style='background-color:#444;'>There are details about the Netscript language in the documentation, which " +
                          "can be accessed in the 'Tutorial' tab on the main navigation menu. I highly suggest you check " +
-                         "it out after this tutorial. </strong> For now, just copy " +
+                         "it out after this tutorial.</strong> For now, just copy " +
                          "and paste the following code into the script editor: <br><br>" +
                          "while(true) { <br>" +
                          "&nbsp;&nbsp;hack('foodnstuff'); <br>" +

src/NetscriptFunctions.js

@@ -1847,6 +1847,25 @@ function NetscriptFunctions(workerScript) {
                 throw makeRuntimeRejectMsg(workerScript, "Invalid argument passed in for write: " + port);
             }
         },
+        tryWrite : function(port, data="") {
+            if (workerScript.checkingRam) {
+                return updateStaticRam("tryWrite", CONSTANTS.ScriptReadWriteRamCost);
+            }
+            updateDynamicRam("tryWrite", CONSTANTS.ScriptReadWriteRamCost);
+            if (!isNaN(port)) {
+                port = Math.round(port);
+                if (port < 1 || port > CONSTANTS.NumNetscriptPorts) {
+                    throw makeRuntimeRejectMsg(workerScript, "ERROR: tryWrite() called on invalid port: " + port + ". Only ports 1-" + CONSTANTS.NumNetscriptPorts + " are valid.");
+                }
+                var port = NetscriptPorts[port-1];
+                if (port == null || !(port instanceof NetscriptPort)) {
+                    throw makeRuntimeRejectMsg(workerScript, "Could not find port: " + port + ". This is a bug contact the game developer");
+                }
+                return port.tryWrite(data);
+            } else {
+                throw makeRuntimeRejectMsg(workerScript, "Invalid argument passed in for tryWrite: " + port);
+            }
+        },
         read : function(port) {
             if (workerScript.checkingRam) {
                 return updateStaticRam("read", CONSTANTS.ScriptReadWriteRamCost);