Merge pull request #50893 from KoBeWi/how_to_config_file

Improve ConfigFile example

1 files changed, 62 insertions, 21 deletions

diff --git a/doc/classes/ConfigFile.xml b/doc/classes/ConfigFile.xml
index bcd4266f6c..f970be23a6 100644
--- a/doc/classes/ConfigFile.xml
+++ b/doc/classes/ConfigFile.xml
@@ -12,34 +12,75 @@
 		a_vector=Vector3(1, 0, 2)
 		[/codeblock]
 		The stored data can be saved to or parsed from a file, though ConfigFile objects can also be used directly without accessing the filesystem.
-		The following example shows how to parse an INI-style file from the system, read its contents and store new values in it:
+		The following example shows how to create a simple [ConfigFile] and save it on disc:
 		[codeblocks]
 		[gdscript]
+		# Create new ConfigFile object.
 		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 = config.get_value("display", "width", 1024)
-		    # Store a variable if and only if 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")
+
+		# Store some values.
+		config.set_value("Player1", "player_name", "Steve")
+		config.set_value("Player1", "best_score", 10)
+		config.set_value("Player2", "player_name", "V3geta")
+		config.set_value("Player2", "best_score", 9001)
+
+		# Save it to a file (overwrite if already exists).
+		config.save("user://scores.cfg")
 		[/gdscript]
 		[csharp]
+		// Create new ConfigFile object.
 		var config = new ConfigFile();
-		Error err = config.Load("user://settings.cfg");
-		if (err == Error.Ok) // If not, something went wrong with the file loading
+
+		// Store some values.
+		config.SetValue("Player1", "player_name", "Steve");
+		config.SetValue("Player1", "best_score", 10);
+		config.SetValue("Player2", "player_name", "V3geta");
+		config.SetValue("Player2", "best_score", 9001);
+
+		// Save it to a file (overwrite if already exists).
+		config.Save("user://scores.cfg");
+		[/csharp]
+		[/codeblocks]
+		This example shows how the above file could be loaded:
+		[codeblocks]
+		[gdscript]
+		var score_data = {}
+		var config = ConfigFile.new()
+
+		# Load data from a file.
+		var err = config.load("user://scores.cfg")
+
+		# If the file didn't load, ignore it.
+		if err != OK:
+		    return
+
+		# Iterate over all sections.
+		for player in config.get_sections():
+		    # Fetch the data for each section.
+		    var player_name = config.get_value(player, "player_name")
+		    var player_score = config.get_value(player, "best_score")
+		    score_data[player_name] = player_score
+		[/gdscript]
+		[csharp]
+		var score_data = new Godot.Collections.Dictionary();
+		var config = new ConfigFile();
+
+		// Load data from a file.
+		Error err = config.Load("user://scores.cfg");
+
+		// If the file didn't load, ignore it.
+		if (err != Error.Ok)
+		{
+		    return;
+		}
+
+		// Iterate over all sections.
+		foreach (String player in config.GetSections())
 		{
-		    // Look for the display/width pair, and default to 1024 if missing
-		    int screenWidth = (int)config.GetValue("display", "width", 1024);
-		    // Store a variable if and only if it hasn't been defined yet
-		    if (!config.HasSectionKey("audio", "mute"))
-		    {
-		        config.SetValue("audio", "mute", false);
-		    }
-		    // Save the changes by overwriting the previous file
-		    config.Save("user://settings.cfg");
+		    // Fetch the data for each section.
+		    var player_name = (String)config.GetValue(player, "player_name");
+		    var player_score = (int)config.GetValue(player, "best_score");
+		    score_data[player_name] = player_score;
 		}
 		[/csharp]
 		[/codeblocks]