Merge branch 'mc-1.14.x' into mc-1.15.x

src/main/resources/data/computercraft/lua/rom/apis/peripheral.lua

@@ -64,24 +64,33 @@ function isPresent(name)
     return false
 end
 
---- Get the type of the peripheral with the given name.
+--- Get the type of a wrapped peripheral, or a peripheral with the given name.
 --
--- @tparam string name The name of the peripheral to find.
+-- @tparam string|table peripheral The name of the peripheral to find, or a
+-- wrapped peripheral instance.
 -- @treturn string|nil The peripheral's type, or `nil` if it is not present.
-function getType(name)
-    expect(1, name, "string")
-    if native.isPresent(name) then
-        return native.getType(name)
-    end
-    for n = 1, #sides do
-        local side = sides[n]
-        if native.getType(side) == "modem" and not native.call(side, "isWireless") and
-            native.call(side, "isPresentRemote", name)
-        then
-            return native.call(side, "getTypeRemote", name)
+function getType(peripheral)
+    expect(1, peripheral, "string", "table")
+    if type(peripheral) == "string" then -- Peripheral name passed
+        if native.isPresent(peripheral) then
+            return native.getType(peripheral)
         end
+        for n = 1, #sides do
+            local side = sides[n]
+            if native.getType(side) == "modem" and not native.call(side, "isWireless") and
+                native.call(side, "isPresentRemote", peripheral)
+            then
+                return native.call(side, "getTypeRemote", peripheral)
+            end
+        end
+        return nil
+    else
+        local mt = getmetatable(peripheral)
+        if not mt or mt.__name ~= "peripheral" or type(mt.type) ~= "string" then
+            error("bad argument #1 (table is not a peripheral)", 2)
+        end
+        return mt.type
     end
-    return nil
 end
 
 --- Get all available methods for the peripheral with the given name.
@@ -105,6 +114,19 @@ function getMethods(name)
     return nil
 end
 
+--- Get the name of a peripheral wrapped with @{peripheral.wrap}.
+--
+-- @tparam table peripheral The peripheral to get the name of.
+-- @treturn string The name of the given peripheral.
+function getName(peripheral)
+    expect(1, peripheral, "table")
+    local mt = getmetatable(peripheral)
+    if not mt or mt.__name ~= "peripheral" or type(mt.name) ~= "string" then
+        error("bad argument #1 (table is not a peripheral)", 2)
+    end
+    return mt.name
+end
+
 --- Call a method on the peripheral with the given name.
 --
 -- @tparam string name The name of the peripheral to invoke the method on.
@@ -148,7 +170,11 @@ function wrap(name)
         return nil
     end
 
-    local result = {}
+    local result = setmetatable({}, {
+        __name = "peripheral",
+        name = name,
+        type = peripheral.getType(name),
+    })
     for _, method in ipairs(methods) do
         result[method] = function(...)
             return peripheral.call(name, method, ...)

src/main/resources/data/computercraft/lua/rom/apis/rednet.lua

@@ -29,7 +29,7 @@ local tReceivedMessageTimeouts = {}
 local tHostnames = {}
 
 --- Opens a modem with the given @{peripheral} name, allowing it to send and
---- receive messages over rednet.
+-- receive messages over rednet.
 --
 -- This will open the modem on two channels: one which has the same
 -- @{os.getComputerID|ID} as the computer, and another on
@@ -246,7 +246,7 @@ function host(sProtocol, sHostname)
 end
 
 --- Stop @{rednet.host|hosting} a specific protocol, meaning it will no longer
---- respond to @{rednet.lookup} requests.
+-- respond to @{rednet.lookup} requests.
 --
 -- @tparam string sProtocol The protocol to unregister your self from.
 function unhost(sProtocol)

src/main/resources/data/computercraft/lua/rom/help/peripheral.txt

@@ -3,6 +3,7 @@ The peripheral API is for interacting with external peripheral devices. Type "he
 Functions in the peripheral API:
 peripheral.getNames()
 peripheral.isPresent( name )
+peripheral.getName( peripheral )
 peripheral.getType( name )
 peripheral.getMethods( name )
 peripheral.call( name, methodName, param1, param2, etc )

src/main/resources/data/computercraft/lua/rom/programs/monitor.lua

@@ -28,7 +28,7 @@ local monitor = peripheral.wrap(sName)
 local previousTerm = term.redirect(monitor)
 
 local co = coroutine.create(function()
-    shell.run(sProgram, table.unpack(tArgs, 3))
+    (shell.execute or shell.run)(sProgram, table.unpack(tArgs, 3))
 end)
 
 local function resume(...)

src/main/resources/data/computercraft/lua/rom/programs/shell.lua

@@ -130,8 +130,25 @@ else
     bgColour = colours.black
 end
 
-local function run(_sCommand, ...)
-    local sPath = shell.resolveProgram(_sCommand)
+--- Run a program with the supplied arguments.
+--
+-- Unlike @{shell.run}, each argument is passed to the program verbatim. While
+-- `shell.run("echo", "b c")` runs `echo` with `b` and `c`,
+-- `shell.execute("echo", "b c")` runs `echo` with a single argument `b c`.
+--
+-- @tparam string command The program to execute.
+-- @tparam string ... Arguments to this program.
+-- @treturn boolean Whether the program exited successfully.
+-- @usage Run `paint my-image` from within your program:
+--
+--     shell.execute("paint", "my-image")
+function shell.execute(command, ...)
+    expect(1, command, "string")
+    for i = 1, select('#', ...) do
+        expect(i + 1, select(i, ...), "string")
+    end
+
+    local sPath = shell.resolveProgram(command)
     if sPath ~= nil then
         tProgramStack[#tProgramStack + 1] = sPath
         if multishell then
@@ -144,7 +161,7 @@ local function run(_sCommand, ...)
 
         local sDir = fs.getDir(sPath)
         local env = createShellEnv(sDir)
-        env.arg = { [0] = _sCommand, ... }
+        env.arg = { [0] = command, ... }
         local result = os.run(env, sPath, ...)
 
         tProgramStack[#tProgramStack] = nil
@@ -196,11 +213,12 @@ end
 -- @usage Run `paint my-image` from within your program:
 --
 --     shell.run("paint", "my-image")
+-- @see shell.execute Run a program directly without parsing the arguments.
 function shell.run(...)
     local tWords = tokenise(...)
     local sCommand = tWords[1]
     if sCommand then
-        return run(sCommand, table.unpack(tWords, 2))
+        return shell.execute(sCommand, table.unpack(tWords, 2))
     end
     return false
 end