VRage.Game.ModAPI.Ingame.Utilities.MyIni

← Index

MyIni Class

Namespace: VRage.Game.ModAPI.Ingame.Utilities
Assembly: VRage.Game.dll

Summary

A configuration class to parse and create a text string resembling the old fashioned INI format, but with support for multiline values. Do not forget that parsing is a time-consuming task. Keep your parsing to a minimum.

Example

Using MyIni to deal with CustomData end-user configuration: The CustomData:

[kernel]
output=DebugTextPanel
bootText=
|-- HAL9000 --
|Good morning, Dave.

The code:

MyIni _ini = new MyIni();
IMyTextPanel _outputTextPanel;

public Program() 
{
    MyIniParseResult result;
    if (!_ini.TryParse(Me.CustomData, out result) 
    {
        Echo($"CustomData error:\nLine {result}");
    }

    // Get the kernel section's output value. If this value is set, the system attempts
    // to retrieve a text panel with the value set. Otherwise output is ignored.
    var name = _ini.Get("kernel", "output").ToString();
    if (name != null) 
    {
        _outputTextPanel = GridTerminalSystem.GetBlockWithName<IMyTextPanel>(name);
        if (_outputTextPanel == null)
            Echo($"No text panel named {name}");
    }

    // Get the kernel section's boottext value. If no value is given, a default value will be returned.
    var bootText = _ini.Get("kernel", "bootText").ToString("Kernel is starting up...");
    _outputTextPanel?.WritePublicText(bootText);
}

public void Main() {
    // Do your stuff. Only parse the configuration when you have to.
}

Using MyIni to deal with internal storage:

MyIni _storage = new MyIni();
Vector3D _startupPosition;
bool _hasTarget;
Vector3D _currentTarget;

public Program() 
{
    // You only need to parse here in the constructor.
    if (_ini.TryParse(Storage) 
    {
        var str = _ini.Get("state", "startupPosition").ToString();
        Vector3D.TryParse(str, out _startupPosition);
        str = _ini.Get("state", "currentTarget").ToString();
        Vector3D.TryParse(str, out _currentTarget);
        _hasTarget = _ini.Get("state", "hasTarget").ToBoolean();
    } 
    else 
    {
        // Set up defaults, the storage is nonexistent or corrupt
        _startupPosition = Me.CubeGrid.Position;
    }
}

public void Save()
{
    // You only need to update Storage when the Save method is called.
    _ini.Set("state", "startupPosition", _startupPosition);
    _ini.Set("state", "currentTarget", _currentTarget);
    Storage = _ini.ToString();
}

public void Main() {
    // Do your stuff
}

Remarks

This class is NOT THREAD SAFE as it's optimized for programmable block use.

Properties

_string EndContent_	You can terminate a configuration stream by entering "---" on a separate line. This property will contain all the content after this line.
_string EndComment_	Get or set a comment to be placed after the last section or item. Is`null`if the section does not exist or has no comment.

### Methods

static _bool HasSection(string config, string section)_	Determines if the given configuration contains what looks like the given section. It does not verify that the content is actually in a valid format, just if there's a line starting with [section].
_bool ContainsSection(string section)_	Determines whether a section of a given name exists in the currently parsed configuration.
_bool ContainsKey(string section, string name)_	Determines whether a configuration key (section/key) exists in the currently parsed configuration.
_bool ContainsKey(MyIniKey key)_	Determines whether a configuration key (section/key) exists in the currently parsed configuration.
_void GetKeys(string section, List keys)_	Fills the provided list with the configuration keys within the given section.
_void GetKeys(List keys)_	Fills the provided list with all configuration keys within the currently parsed configuration.
_void GetSections(List names)_	Fills the provided list with the names of all the sections in the currently parsed configuration.
_void SetEndComment(string comment)_	Sets a comment to be placed after the last section or item. Set the comment to`null`to remove it.
_string GetSectionComment(string section)_	Get any comment that might be associated with the given section. Returns`null`if the section does not exist or has no comment.
_void SetSectionComment(string section, string comment)_	Sets a comment on a given section. The section must already exist. Set the comment to`null`to remove it.
_string GetComment(string section, string name)_	Gets any comment that might be associated with the given key. Returns`null`if the key does not exist or has no comment.
_string GetComment(MyIniKey key)_	Gets any comment that might be associated with the given key. Returns`null`if the key does not exist or has no comment.
_void SetComment(string section, string name, string comment)_	Sets a comment on a given item. The item must already exist. Set the comment to`null`to remove it.
_void SetComment(MyIniKey key, string comment)_	Sets a comment on a given item. The item must already exist. Set the comment to`null`to remove it.
_MyIniValue Get(string section, string name)_	Gets the [MyIniValue](VRage.Game.ModAPI.Ingame.Utilities.MyIniValue) of the given configuration key.
_MyIniValue Get(MyIniKey key)_	Gets the [MyIniValue](VRage.Game.ModAPI.Ingame.Utilities.MyIniValue) of the given configuration key.
_void Delete(string section, string name)_	Deletes the given configuration key.
_void Delete(MyIniKey key)_	Deletes the given configuration key.
_void Set(string section, string name, string value)_	Sets the value of the given configuration key.
_void Set(MyIniKey key, string value)_	Sets the value of the given configuration key.
_void Set(string section, string name, bool value)_	Sets the value of the given configuration key.
_void Set(MyIniKey key, bool value)_	Sets the value of the given configuration key.
_void Set(string section, string name, byte value)_	Sets the value of the given configuration key.
_void Set(MyIniKey key, byte value)_	Sets the value of the given configuration key.
_void Set(string section, string name, sbyte value)_	Sets the value of the given configuration key.
_void Set(MyIniKey key, sbyte value)_	Sets the value of the given configuration key.
_void Set(string section, string name, ushort value)_	Sets the value of the given configuration key.
_void Set(MyIniKey key, ushort value)_	Sets the value of the given configuration key.
_void Set(string section, string name, short value)_	Sets the value of the given configuration key.
_void Set(MyIniKey key, short value)_	Sets the value of the given configuration key.
_void Set(string section, string name, uint value)_	Sets the value of the given configuration key.
_void Set(MyIniKey key, uint value)_	Sets the value of the given configuration key.
_void Set(string section, string name, int value)_	Sets the value of the given configuration key.
_void Set(MyIniKey key, int value)_	Sets the value of the given configuration key.
_void Set(string section, string name, ulong value)_	Sets the value of the given configuration key.
_void Set(MyIniKey key, ulong value)_	Sets the value of the given configuration key.
_void Set(string section, string name, long value)_	Sets the value of the given configuration key.
_void Set(MyIniKey key, long value)_	Sets the value of the given configuration key.
_void Set(string section, string name, float value)_	Sets the value of the given configuration key.
_void Set(MyIniKey key, float value)_	Sets the value of the given configuration key.
_void Set(string section, string name, double value)_	Sets the value of the given configuration key.
_void Set(MyIniKey key, double value)_	Sets the value of the given configuration key.
_void Set(string section, string name, decimal value)_	Sets the value of the given configuration key.
_void Set(MyIniKey key, decimal value)_	Sets the value of the given configuration key.
_void Clear()_	Empties this configuration
_bool TryParse(string content)_	Attempts to parse the given content as a configuration file.
_bool TryParse(string content, ref MyIniParseResult result)_	Attempts to parse the given content as a configuration file.
_bool TryParse(string content, string section, ref MyIniParseResult result)_	Attempts to parse the given content as a configuration file. OBSERVE: Use only for read-only operations. If you parse a single section and run [string ToString()](VRage.Game.ModAPI.Ingame.Utilities.ToString) , you will only get the parsed section, the rest will be discarded.
_bool TryParse(string content, string section)_	Attempts to parse the given content as a configuration file. OBSERVE: Use only for read-only operations. If you parse a single section and run [string ToString()](VRage.Game.ModAPI.Ingame.Utilities.ToString) , you will only get the parsed section, the rest will be discarded.
_void Invalidate()_	Forces regeneration of the ini content. Only really useful if you want to reformat the configuration file.
_string ToString()_	Generates a configuration file from the currently parsed configuration