Difference between revisions of "love.filesystem.load"

(Make it clear we're talking about lua files here)
m (Add LoadMode.)
 
(10 intermediate revisions by 6 users not shown)
Line 1: Line 1:
Load a lua file (but not run it)
+
{{newin|[[0.5.0]]|050|type=function}}
 +
Loads a Lua file (but does not run it).
 +
 
 +
This is equivalent to [https://www.lua.org/manual/5.1/manual.html#pdf-loadfile loadfile] except it operates on LÖVE filesystem paths.
 +
 
 
== Function ==
 
== Function ==
 
=== Synopsis ===
 
=== Synopsis ===
 
<source lang="lua">
 
<source lang="lua">
chunk = love.filesystem.load( name )
+
chunk, errormsg = love.filesystem.load( name, mode )
 
</source>
 
</source>
 
=== Arguments ===
 
=== Arguments ===
{{param|string|name|The name (and path) of the file}}
+
{{param|string|name|The name (and path) of the file.}}
 +
{{New feature|12.0|
 +
{{param|LoadMode|mode ("bt")|Controls to only allow precompiled chunk, plain text, or both.}}
 +
|120}}
 
=== Returns ===
 
=== Returns ===
{{param|function|chunk|The loaded chunk}}
+
{{param|function|chunk|The loaded chunk.}}
== Example ==
+
{{param|string|errormsg (nil)|The error message if file could not be opened.}}
 +
== Examples ==
 
It is important to note that love.filesystem.load does '''not''' invoke the code, it just creates a function (a 'chunk') that will contain the contents of the file inside it. In order to execute the chunk, you have to put () behind it.
 
It is important to note that love.filesystem.load does '''not''' invoke the code, it just creates a function (a 'chunk') that will contain the contents of the file inside it. In order to execute the chunk, you have to put () behind it.
  
 
Also, it is worth noting that loaded files can return values. For example, the following file:
 
Also, it is worth noting that loaded files can return values. For example, the following file:
 +
 
<source lang="lua">
 
<source lang="lua">
return 1+1
+
return 1+1, "foo"
 
</source>
 
</source>
  
Will return 2, when called like this:
+
Will return 2 and "foo", when called like this:
  
 
<source lang="lua">
 
<source lang="lua">
chunk = love.filesystem.load( name ) -- load the chunk
+
local chunk = love.filesystem.load("someFolder/myFile.lua") -- load the chunk
local result = chunk() -- execute the chunk
+
local result1, result2 = chunk() -- execute the chunk
print('result: ' .. tostring(result)) -- prints 'result: 2'
+
print("Results: "..tostring(result1)..", "..tostring(result2)) -- prints 'Results: 2, foo'
 
</source>
 
</source>
  
This bluescreens if there is a syntax error in the loaded file. If you want to continue your game if the file is not valid (for example if you expect it to be written by users), you can protect the calling of the chunk with '''pcall''':
+
This raises an error if there's a syntax error in the loaded file. If you want your game to continue if the file isn't valid (for example if you expect it to be written by users), you can protect the loading and calling of the file with [https://www.lua.org/manual/5.1/manual.html#pdf-pcall '''pcall''']:
  
 
<source lang="lua">
 
<source lang="lua">
local ok, chunk, result
+
-- success, valueOrErrormsg = runFile( name )
ok, chunk = pcall( love.filesystem.load, name ) -- load the chunk safely
+
local function runFile(name)
if not ok then
+
local ok, chunk, err = pcall(love.filesystem.load, name) -- load the chunk safely
  print('The following error happend: ' .. tostring(chunk))
+
if not ok   then return false, "Failed loading code: "..chunk end
else
+
if not chunk then  return false, "Failed reading file: "..err    end
  ok, result = pcall(chunk) -- execute the chunk safely
 
  
  if not ok then -- will be false if there is an error
+
local ok, value = pcall(chunk) -- execute the chunk safely
    print('The following error happened: ' .. tostring(result))
+
if not ok then return false, "Failed calling chunk: "..tostring(value) end
  else
+
 
    print('The result of loading is: ' .. tostring(result))
+
return true, value -- success!
  end
 
 
end
 
end
 +
 +
print(runFile("goodFile.lua"))
 +
print(runFile("fileWithRuntimeError.lua"))
 +
print(runFile("fileWithSyntaxError.lua"))
 +
print(runFile("nonexistentFile.lua"))
 
</source>
 
</source>
  
Line 46: Line 58:
 
* [[parent::love.filesystem]]
 
* [[parent::love.filesystem]]
 
[[Category:Functions]]
 
[[Category:Functions]]
{{#set:Description=Load a lua file (but not run it)}}
+
{{#set:Description=Loads a Lua file (but does not run it).}}
 
{{#set:Since=000}}
 
{{#set:Since=000}}
 
== Other Languages ==
 
== Other Languages ==
 
{{i18n|love.filesystem.load}}
 
{{i18n|love.filesystem.load}}

Latest revision as of 05:56, 14 April 2024

Available since LÖVE 0.5.0
This function is not supported in earlier versions.

Loads a Lua file (but does not run it).

This is equivalent to loadfile except it operates on LÖVE filesystem paths.

Function

Synopsis

chunk, errormsg = love.filesystem.load( name, mode )

Arguments

string name
The name (and path) of the file.
Available since LÖVE 12.0
LoadMode mode ("bt")
Controls to only allow precompiled chunk, plain text, or both.

Returns

function chunk
The loaded chunk.
string errormsg (nil)
The error message if file could not be opened.

Examples

It is important to note that love.filesystem.load does not invoke the code, it just creates a function (a 'chunk') that will contain the contents of the file inside it. In order to execute the chunk, you have to put () behind it.

Also, it is worth noting that loaded files can return values. For example, the following file:

return 1+1, "foo"

Will return 2 and "foo", when called like this:

local chunk = love.filesystem.load("someFolder/myFile.lua") -- load the chunk
local result1, result2 = chunk() -- execute the chunk
print("Results: "..tostring(result1)..", "..tostring(result2)) -- prints 'Results: 2, foo'

This raises an error if there's a syntax error in the loaded file. If you want your game to continue if the file isn't valid (for example if you expect it to be written by users), you can protect the loading and calling of the file with pcall:

-- success, valueOrErrormsg = runFile( name )
local function runFile(name)
	local ok, chunk, err = pcall(love.filesystem.load, name) -- load the chunk safely
	if not ok    then  return false, "Failed loading code: "..chunk  end
	if not chunk then  return false, "Failed reading file: "..err    end

	local ok, value = pcall(chunk) -- execute the chunk safely
	if not ok then  return false, "Failed calling chunk: "..tostring(value)  end

	return true, value -- success!
end

print(runFile("goodFile.lua"))
print(runFile("fileWithRuntimeError.lua"))
print(runFile("fileWithSyntaxError.lua"))
print(runFile("nonexistentFile.lua"))

See Also


Other Languages