From c734a508c3d2c17e15e5125110f6b2adce0f460c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?R=C3=A9mi=20Verschelde?= Date: Thu, 12 May 2016 08:41:43 +0200 Subject: [PATCH] classref: Directory and ConfigFile (cherry picked from commit 22d1385caf40badde869fb114b01f6f50ab608ab) --- core/bind/core_bind.cpp | 10 ++--- core/io/config_file.cpp | 2 +- doc/base/classes.xml | 94 +++++++++++++++++++++++++++++------------ 3 files changed, 74 insertions(+), 32 deletions(-) diff --git a/core/bind/core_bind.cpp b/core/bind/core_bind.cpp index 229640ba115..6f249a7e645 100644 --- a/core/bind/core_bind.cpp +++ b/core/bind/core_bind.cpp @@ -1669,15 +1669,15 @@ void _Directory::_bind_methods() { ObjectTypeDB::bind_method(_MD("get_drive","idx"),&_Directory::get_drive); ObjectTypeDB::bind_method(_MD("change_dir:Error","todir"),&_Directory::change_dir); ObjectTypeDB::bind_method(_MD("get_current_dir"),&_Directory::get_current_dir); - ObjectTypeDB::bind_method(_MD("make_dir:Error","name"),&_Directory::make_dir); - ObjectTypeDB::bind_method(_MD("make_dir_recursive:Error","name"),&_Directory::make_dir_recursive); - ObjectTypeDB::bind_method(_MD("file_exists","name"),&_Directory::file_exists); - ObjectTypeDB::bind_method(_MD("dir_exists","name"),&_Directory::dir_exists); + ObjectTypeDB::bind_method(_MD("make_dir:Error","path"),&_Directory::make_dir); + ObjectTypeDB::bind_method(_MD("make_dir_recursive:Error","path"),&_Directory::make_dir_recursive); + ObjectTypeDB::bind_method(_MD("file_exists","path"),&_Directory::file_exists); + ObjectTypeDB::bind_method(_MD("dir_exists","path"),&_Directory::dir_exists); // ObjectTypeDB::bind_method(_MD("get_modified_time","file"),&_Directory::get_modified_time); ObjectTypeDB::bind_method(_MD("get_space_left"),&_Directory::get_space_left); ObjectTypeDB::bind_method(_MD("copy:Error","from","to"),&_Directory::copy); ObjectTypeDB::bind_method(_MD("rename:Error","from","to"),&_Directory::rename); - ObjectTypeDB::bind_method(_MD("remove:Error","file"),&_Directory::remove); + ObjectTypeDB::bind_method(_MD("remove:Error","path"),&_Directory::remove); } diff --git a/core/io/config_file.cpp b/core/io/config_file.cpp index fd20ec94042..e0dc7ef9faf 100644 --- a/core/io/config_file.cpp +++ b/core/io/config_file.cpp @@ -207,7 +207,7 @@ Error ConfigFile::load(const String& p_path) { void ConfigFile::_bind_methods(){ ObjectTypeDB::bind_method(_MD("set_value","section","key","value"),&ConfigFile::set_value); - ObjectTypeDB::bind_method(_MD("get_value","section","key","default"),&ConfigFile::get_value,DEFVAL(Variant())); + ObjectTypeDB::bind_method(_MD("get_value:Variant","section","key","default"),&ConfigFile::get_value,DEFVAL(Variant())); ObjectTypeDB::bind_method(_MD("has_section","section"),&ConfigFile::has_section); ObjectTypeDB::bind_method(_MD("has_section_key","section","key"),&ConfigFile::has_section_key); diff --git a/doc/base/classes.xml b/doc/base/classes.xml index 608e90c9f48..eed50375868 100644 --- a/doc/base/classes.xml +++ b/doc/base/classes.xml @@ -8256,8 +8256,23 @@ + Helper class to handle INI-style files. + This helper class can be used to store [Variant] values on the filesystem using an INI-style formatting. The stored values as referenced by a section and a key. The stored data can be saved to or parsed from a file, though ConfigFile objects can also be used directly with accessing the filesystem. + The following example shows how to parse a INI-style file from the system, read its contents and store new values in it: + [codeblock] + var config = ConfigFile.new() + var err = config.load("user://settings.cfg") + if err == OK: # if not, something went wrong with the file loading + # Look for the display/width pair, and default to 1024 if missing + var screen_width = get_value("display", "width", 1024) + # Store a variable if and only it hasn't been defined yet + if not config.has_section_key("audio", "mute"): + config.set_value("audio", "mute", false) + # Save the changes by overwriting the previous file + config.save("user://settings.cfg") + [/codeblock] @@ -8268,9 +8283,12 @@ + Assign a value to the specified key of the the specified section. If the section and/or the key do not exist, they are created. Passing a [code]NULL[/code] value deletes the specified key if it exists (and deletes the section if it ends up empty once the key has been removed). + + @@ -8278,6 +8296,7 @@ + Return the current value for the specified section and key. If the section and/or the key do not exist, the method returns the value of the optional [i]default[/i] argument (and thus [code]NULL[/code] if not specified). @@ -8286,6 +8305,7 @@ + Check if the specified section exists. @@ -8296,12 +8316,14 @@ + Check if the specified section-key pair exists. + Return an array of all defined section identifiers. @@ -8310,6 +8332,7 @@ + Return an array of all defined key identifiers in the specified section. @@ -8318,6 +8341,7 @@ + Load the config file specified as a parameter. The file's contents are parsed and loaded in the ConfigFile object from which the method was called. The return value is one of the OK, FAILED or ERR_* constants listed in [@Global Scope] (if the load was successful, it returns OK). @@ -8326,6 +8350,8 @@ + Save the contents of the ConfigFile object to the file specified as a parameter. The output file uses an INI-style structure. + The return value is one of the OK, FAILED or ERR_* constants listed in [@Global Scope] (if the save was successful, it returns OK). @@ -9825,22 +9851,22 @@ This approximation makes straight segments between each point, then subdivides t Type used to handle the filesystem. - Directory type. Is used to manage directories and their content (not restricted to the project folder). - Example for how to iterate through the files of a directory: + Directory type. It is used to manage directories and their content (not restricted to the project folder). + Here is an example on how to iterate through the files of a directory: [codeblock] - func dir(path): - var d = Directory.new() - if d.open( path )==0: - d.list_dir_begin() - var file_name = d.get_next() - while(file_name!=""): - if d.current_is_dir(): + func dir_contents(path): + var dir = Directory.new() + if dir.open(path) == OK: + dir.list_dir_begin() + var file_name = dir.get_next() + while (file_name != ""): + if dir.current_is_dir(): print("Found directory: " + file_name) else: - print("Found file:" + file_name) - file_name = d.get_next() + print("Found file: " + file_name) + file_name = dir.get_next() else: - print("Some open Error, maybe directory not found?") + print("An error occurred when trying to access the path.") [/codeblock] @@ -9850,40 +9876,42 @@ This approximation makes straight segments between each point, then subdivides t - Opens a directory to work with. Needs a path, example "res://folder" + Open an existing directory of the filesystem. The [i]path[/i] argument can be within the project tree ([code]res://folder[/code]), the user directory ([code]user://folder[/code]) or an absolute path of the user filesystem (e.g. [code]/tmp/folder[/code] or [code]C:\tmp\folder[/code]). + The method returns one of the error code constants defined in [@Global Scope] (OK or ERR_*). - Loads all file names of the current directory (prepares the get_next() function). + Initialise the stream used to list all files and directories using the [method get_next] function, closing the current opened stream if needed. Once the stream has been processed, it should typically be closed with [method list_dir_end]. + Return false if the stream could not be initialised. - Is used to iterate through the files of the current directory. Returns the name(no path) of the current file/directory, it also contains "." and ".." . -Returns an empty String "" at the end of the list. + Return the next element (file or directory) in the current directory (including [code].[/code] and [code]..[/code]). The name of the file or directory is returned (and not its full path). Once the stream has been fully processed, the method returns an empty String and closes the stream automatically (i.e. [method list_dir_end] would not be mandatory in such a case). - Returns true if the current file you are looking at with get_next() is a directory or "." or ".." otherwise false. + Return whether the current item processed with the last [method get_next] call is a directory ([code].[/code] and [code]..[/code] are considered directories). - Run this to empty the list of remaining files in get_next(). You can use it to end the iteration, as soon as your goal is reached. + Close the current stream opened with [method list_dir_begin] (whether it has been fully processed with [method get_next] or not does not matter). + On Windows, return the number of drives (partitions) mounted on the current filesystem. On other platforms, the method returns 0. @@ -9892,6 +9920,7 @@ Returns an empty String "" at the end of the list. + On Windows, return the name of the drive (partition) passed as an argument (e.g. [code]C:[/code]). On other platforms, or if the requested drive does not existed, the method returns an empty String. @@ -9900,53 +9929,60 @@ Returns an empty String "" at the end of the list. - Needs a path or name to the next directory. When the target directory is in the current directory you can use "newfolder" otherwise you need the full path "res://currentfolder/newfolder" + Change the currently opened directory to the one passed as an argument. The argument can be relative to the current directory (e.g. [code]newdir[/code] or [code]../newdir[/code]), or an absolute path (e.g. [code]/tmp/newdir[/code] or [code]res://somedir/newdir[/code]). + The method returns one of the error code constants defined in [@Global Scope] (OK or ERR_*). - Returns a path to the current directory, example: "res://folder" + Return the absolute path to the currently opened directory (e.g. [code]res://folder[/code] or [code]C:\tmp\folder[/code]). - + + Create a directory. The argument can be relative to the current directory, or an absolute path. The target directory should be placed in an already existing directory (to create the full path recursively, see [method make_dir_recursive]). + The method returns one of the error code constants defined in [@Global Scope] (OK, FAILED or ERR_*). - + + Create a target directory and all necessary intermediate directories in its path, by calling [method make_dir] recursively. The argument can be relative to the current directory, or an absolute path. + Returns one of the error code constants defined in [@Global Scope] (OK, FAILED or ERR_*). - + + Return whether the target file exists. The argument can be relative to the current directory, or an absolute path. - + - Returns true if directory exists otherwise false. Needs a path, example: "res://folder" + Return whether the target directory exists. The argument can be relative to the current directory, or an absolute path. + On Unix desktop systems, return the available space on the current directory's disk. On other platforms, this information is not available and the method returns 0 or -1. @@ -9957,6 +9993,8 @@ Returns an empty String "" at the end of the list. + Copy the [i]from[/i] file to the [i]to[/i] destination. Both arguments should be paths to files, either relative or absolute. If the destination file exists and is not access-protected, it will be overwritten. + Returns one of the error code constants defined in [@Global Scope] (OK, FAILED or ERR_*). @@ -9967,14 +10005,18 @@ Returns an empty String "" at the end of the list. + Rename (move) the [i]from[/i] file to the [i]to[/i] destination. Both arguments should be paths to files, either relative or absolute. If the destination file exists and is not access-protected, it will be overwritten. + Returns one of the error code constants defined in [@Global Scope] (OK or FAILED). - + + Delete the target file or an empty directory. The argument can be relative to the current directory, or an absolute path. If the target directory is not empty, the operation will fail. + Returns one of the error code constants defined in [@Global Scope] (OK or FAILED).