godot-docs/classes/class_configfile.rst

.. Generated automatically by doc/tools/makerst.py in Godot's source tree.
.. DO NOT EDIT THIS FILE, but the ConfigFile.xml source instead.
.. The source is found in doc/classes or modules/<name>/doc_classes.

.. _class_ConfigFile:

ConfigFile
==========

**Inherits:** :ref:`Reference<class_Reference>` **<** :ref:`Object<class_Object>`

**Category:** Core

Brief Description
-----------------

Helper class to handle INI-style files.

Methods
-------

+-----------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| void                                          | :ref:`erase_section<class_ConfigFile_method_erase_section>` **(** :ref:`String<class_String>` section **)**                                                                            |
+-----------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`PoolStringArray<class_PoolStringArray>` | :ref:`get_section_keys<class_ConfigFile_method_get_section_keys>` **(** :ref:`String<class_String>` section **)** const                                                                |
+-----------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`PoolStringArray<class_PoolStringArray>` | :ref:`get_sections<class_ConfigFile_method_get_sections>` **(** **)** const                                                                                                            |
+-----------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`Variant<class_Variant>`                 | :ref:`get_value<class_ConfigFile_method_get_value>` **(** :ref:`String<class_String>` section, :ref:`String<class_String>` key, :ref:`Variant<class_Variant>` default=null **)** const |
+-----------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`bool<class_bool>`                       | :ref:`has_section<class_ConfigFile_method_has_section>` **(** :ref:`String<class_String>` section **)** const                                                                          |
+-----------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`bool<class_bool>`                       | :ref:`has_section_key<class_ConfigFile_method_has_section_key>` **(** :ref:`String<class_String>` section, :ref:`String<class_String>` key **)** const                                 |
+-----------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`Error<enum_@GlobalScope_Error>`         | :ref:`load<class_ConfigFile_method_load>` **(** :ref:`String<class_String>` path **)**                                                                                                 |
+-----------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`Error<enum_@GlobalScope_Error>`         | :ref:`save<class_ConfigFile_method_save>` **(** :ref:`String<class_String>` path **)**                                                                                                 |
+-----------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| void                                          | :ref:`set_value<class_ConfigFile_method_set_value>` **(** :ref:`String<class_String>` section, :ref:`String<class_String>` key, :ref:`Variant<class_Variant>` value **)**              |
+-----------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+

Description
-----------

This helper class can be used to store :ref:`Variant<class_Variant>` values on the filesystem using INI-style formatting. The stored values are identified by a section and a key:

::

    [section]
    some_key=42
    string_example="Hello World!"
    a_vector=Vector3( 1, 0, 2 )

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:

::

    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")

Keep in mind that section and property names can't contain spaces. Anything after a space will be ignored on save and on load.

Method Descriptions
-------------------

.. _class_ConfigFile_method_erase_section:

- void **erase_section** **(** :ref:`String<class_String>` section **)**

Deletes the specified section along with all the key-value pairs inside.

.. _class_ConfigFile_method_get_section_keys:

- :ref:`PoolStringArray<class_PoolStringArray>` **get_section_keys** **(** :ref:`String<class_String>` section **)** const

Returns an array of all defined key identifiers in the specified section.

.. _class_ConfigFile_method_get_sections:

- :ref:`PoolStringArray<class_PoolStringArray>` **get_sections** **(** **)** const

Returns an array of all defined section identifiers.

.. _class_ConfigFile_method_get_value:

- :ref:`Variant<class_Variant>` **get_value** **(** :ref:`String<class_String>` section, :ref:`String<class_String>` key, :ref:`Variant<class_Variant>` default=null **)** const

Returns 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 ``default`` argument, or ``null`` if it is omitted.

.. _class_ConfigFile_method_has_section:

- :ref:`bool<class_bool>` **has_section** **(** :ref:`String<class_String>` section **)** const

Returns ``true`` if the specified section exists.

.. _class_ConfigFile_method_has_section_key:

- :ref:`bool<class_bool>` **has_section_key** **(** :ref:`String<class_String>` section, :ref:`String<class_String>` key **)** const

Returns ``true`` if the specified section-key pair exists.

.. _class_ConfigFile_method_load:

- :ref:`Error<enum_@GlobalScope_Error>` **load** **(** :ref:`String<class_String>` path **)**

Loads the config file specified as a parameter. The file's contents are parsed and loaded in the ConfigFile object which the method was called on. Returns one of the ``OK``, ``FAILED`` or ``ERR_*`` constants listed in :ref:`@GlobalScope<class_@GlobalScope>`. If the load was successful, the return value is ``OK``.

.. _class_ConfigFile_method_save:

- :ref:`Error<enum_@GlobalScope_Error>` **save** **(** :ref:`String<class_String>` path **)**

Saves the contents of the ConfigFile object to the file specified as a parameter. The output file uses an INI-style structure. Returns one of the ``OK``, ``FAILED`` or ``ERR_*`` constants listed in :ref:`@GlobalScope<class_@GlobalScope>`. If the load was successful, the return value is ``OK``.

.. _class_ConfigFile_method_set_value:

- void **set_value** **(** :ref:`String<class_String>` section, :ref:`String<class_String>` key, :ref:`Variant<class_Variant>` value **)**

Assigns a value to the specified key of the specified section. If the section and/or the key do not exist, they are created. Passing a ``null`` value deletes the specified key if it exists, and deletes the section if it ends up empty once the key has been removed.