LuaAPI/filesystem - Revision history

Laela at 18:04, 18 April 2024

2024-04-18T18:04:39Z

Celtic Minstrel: /* filesystem.resolve_asset */ It's possible for resolved paths to not begin with "data/"

2023-07-20T00:41:15Z

‎filesystem.resolve_asset: It's possible for resolved paths to not begin with "data/"

Celtic Minstrel: /* filesystem.image_size */ Fix syntax highlighting

2021-07-26T05:14:29Z

‎filesystem.image_size: Fix syntax highlighting

Celtic Minstrel: /* filesystem.image_size */ Fix formatting

2021-07-26T05:11:56Z

‎filesystem.image_size: Fix formatting

Celtic Minstrel: Move comma out of optional brackets

2021-07-04T22:20:09Z

Move comma out of optional brackets

Celtic Minstrel: Categorize

2021-06-30T02:33:38Z

Categorize

EliDupree at 23:59, 27 June 2021

2021-06-27T23:59:32Z

Celtic Minstrel: Fix more misformatting

2021-05-15T16:32:26Z

Fix more misformatting

Celtic Minstrel: Fix some misformatting and missing headers

2021-05-15T16:32:08Z

Fix some misformatting and missing headers

Celtic Minstrel: Document the new filesystem module

2021-05-15T16:31:13Z

Document the new filesystem module

New page

This module contains functions for working with files on disk, providing read-only access to the data and userdata directories.

=== filesystem.read_file ===

* '''filesystem.read_file'''(''file_path'') → ''file_contents''

Loads a file into memory and returns it as a string. The rules for locating the files are the same as for WML files, but with no requirements on file extension. If the path points to a directory, it instead returns a table containing a list of directory entries, sorted alphabetically with directories grouped at the beginning. In this case, there is also an '''ndirs''' member which contains the number of entries that are directories, allowing you to easily skip the directories if you wish.

=== filesystem.have_file ===

* '''filesystem.have_file'''(''file_path''[, ''only_as_regular_file'']) → ''boolean''

Checks if a file exists. The rules for locating the files are the same as for WML files. Using the second parameter, you can distinguish regular files from directories.

=== filesystem.canonical_path ===

* '''filesystem.canonical_path'''(''file_path'') → ''path''

Returns the path resolved relative to the current script and with any dotfiles stripped out. The returned path is still relative to the data or userdata directory.==== wesnoth.get_image_size ====

* '''filesystem.image_size(''filename'')''' → ''width'', ''height'

Returns the width and height of an image.

<syntax_highlight lang=lua>
local w, h = wesnoth.get_image_size "units/transport/galleon.png"
</syntax_highlight>

* '''filesystem.have_asset'''(''asset_type'', ''path'') → ''exists''

Tests whether an asset file exists in the current binary path. The ''asset_type'' will usually be one of the following constants in '''filesystem.asset_type''':

* '''IMAGE'''
* '''MUSIC'''
* '''MAP'''
* '''SOUND'''

However, it can be any arbitrary string. You could conceivably define a custom asset type in this way.

* '''filesystem.resolve_asset'''(''asset_type'', ''path'') → ''resolved path''

Resolves an asset path against the binary path, returning a new path that is independent of the binary path. The returned path will always begin with the string "data/". This makes it suitable to be assigned to anything that expects an image path, but if you wish to load the file with '''wesnoth.read_file''', this prefix must be stripped off.

← Older revision		Revision as of 18:04, 18 April 2024
Line 1:		Line 1:
	This module contains functions for working with files on disk, providing read-only access to the data and userdata directories.		This module contains functions for working with files on disk, providing read-only access to the data and userdata directories.
		+
		+	== Functions ==

	=== filesystem.read_file ===		=== filesystem.read_file ===

@@ Line 46: / Line 46: @@
 * '''filesystem.resolve_asset'''(''asset_type'', ''path'') &rarr; ''resolved path''
-Resolves an asset path against the binary path, returning a new path that is independent of the binary path. The returned path will always begin with the string "data/". This makes it suitable to be assigned to anything that expects an image path, but if you wish to load the file with '''wesnoth.read_file''', this prefix must be stripped off.
+Resolves an asset path against the binary path, returning a new path that is independent of the binary path. The returned path will almost always begin with the string "data/<asset_type>/". In the few cases where it doesn't (such as the built-in ellipse images), it still begins with "<asset_type>/". This makes it suitable to be assigned to anything that expects an image path, but if you wish to load the file with '''wesnoth.read_file''', this prefix must be stripped off.
 [[Category:Lua Reference]]

@@ Line 27: / Line 27: @@
 <syntaxhighlight lang=lua>
 local w, h = filesystem.image_size "units/transport/galleon.png"
-</syntax_highlight>
+</syntaxhighlight>
 === filesystem.have_asset ===

@@ Line 21: / Line 21: @@
 === filesystem.image_size ===
-* '''filesystem.image_size(''filename'')''' &rarr; ''width'', ''height'
+* '''filesystem.image_size(''filename'')''' &rarr; ''width'', ''height''
 Returns the width and height of an image.

@@ Line 9: / Line 9: @@
 === filesystem.have_file ===
-* '''filesystem.have_file'''(''file_path''[, ''only_as_regular_file'']) &rarr; ''boolean''
+* '''filesystem.have_file'''(''file_path'', [''only_as_regular_file'']) &rarr; ''boolean''
 Checks if a file exists. The rules for locating the files are the same as for WML files. Using the second parameter, you can distinguish regular files from directories.

← Older revision		Revision as of 02:33, 30 June 2021
Line 47:		Line 47:

	Resolves an asset path against the binary path, returning a new path that is independent of the binary path. The returned path will always begin with the string "data/". This makes it suitable to be assigned to anything that expects an image path, but if you wish to load the file with '''wesnoth.read_file''', this prefix must be stripped off.		Resolves an asset path against the binary path, returning a new path that is independent of the binary path. The returned path will always begin with the string "data/". This makes it suitable to be assigned to anything that expects an image path, but if you wish to load the file with '''wesnoth.read_file''', this prefix must be stripped off.
		+
		+	[[Category:Lua Reference]]

@@ Line 19: / Line 19: @@
 Returns the path resolved relative to the current script and with any dotfiles stripped out. The returned path is still relative to the data or userdata directory.
-=== filesystem.image_size ====
+=== filesystem.image_size ===
 * '''filesystem.image_size(''filename'')''' &rarr; ''width'', ''height'
@@ Line 29: / Line 29: @@
 </syntax_highlight>
-=== filesystem.have_asset ====
+=== filesystem.have_asset ===
 * '''filesystem.have_asset'''(''asset_type'', ''path'') &rarr; ''exists''
@@ Line 42: / Line 42: @@
 However, it can be any arbitrary string. You could conceivably define a custom asset type in this way.
-=== filesystem.resolve_asset ====
+=== filesystem.resolve_asset ===
 * '''filesystem.resolve_asset'''(''asset_type'', ''path'') &rarr; ''resolved path''
 Resolves an asset path against the binary path, returning a new path that is independent of the binary path. The returned path will always begin with the string "data/". This makes it suitable to be assigned to anything that expects an image path, but if you wish to load the file with '''wesnoth.read_file''', this prefix must be stripped off.