Difference between revisions of "LuaAPI/filesystem"
(Document the new filesystem module) |
|||
| (8 intermediate revisions by 2 users not shown) | |||
| 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 9: | Line 11: | ||
=== filesystem.have_file === | === filesystem.have_file === | ||
| − | * '''filesystem.have_file'''(''file_path''[ | + | * '''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. | 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. | ||
| Line 17: | Line 19: | ||
* '''filesystem.canonical_path'''(''file_path'') → ''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. | + | 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(''filename'')''' → ''width'', ''height' | + | === filesystem.image_size === |
| + | |||
| + | * '''filesystem.image_size(''filename'')''' → ''width'', ''height'' | ||
Returns the width and height of an image. | Returns the width and height of an image. | ||
| − | < | + | <syntaxhighlight lang=lua> |
| − | local w, h = | + | local w, h = filesystem.image_size "units/transport/galleon.png" |
| − | </ | + | </syntaxhighlight> |
| + | |||
| + | === filesystem.have_asset === | ||
* '''filesystem.have_asset'''(''asset_type'', ''path'') → ''exists'' | * '''filesystem.have_asset'''(''asset_type'', ''path'') → ''exists'' | ||
| Line 37: | Line 43: | ||
However, it can be any arbitrary string. You could conceivably define a custom asset type in this way. | However, it can be any arbitrary string. You could conceivably define a custom asset type in this way. | ||
| + | |||
| + | === filesystem.resolve_asset === | ||
* '''filesystem.resolve_asset'''(''asset_type'', ''path'') → ''resolved path'' | * '''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. | + | 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]] | ||
Latest revision as of 18:04, 18 April 2024
This module contains functions for working with files on disk, providing read-only access to the data and userdata directories.
Contents
Functions
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.
filesystem.image_size
- filesystem.image_size(filename) → width, height
Returns the width and height of an image.
local w, h = filesystem.image_size "units/transport/galleon.png"
filesystem.have_asset
- 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
- 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 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.