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

Member	Description
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. Isnullif the section does not exist or has no comment.

Methods

Member	Description
static bool HasSection(string, string)	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)	Determines whether a section of a given name exists in the currently parsed configuration.
bool ContainsKey(string, string)	Determines whether a configuration key (section/key) exists in the currently parsed configuration.
bool ContainsKey(VRage.Game.ModAPI.Ingame.Utilities.MyIniKey)	Determines whether a configuration key (section/key) exists in the currently parsed configuration.
void GetKeys(string, List<VRage.Game.ModAPI.Ingame.Utilities.MyIniKey>)	Fills the provided list with the configuration keys within the given section.
void GetKeys(List<VRage.Game.ModAPI.Ingame.Utilities.MyIniKey>)	Fills the provided list with all configuration keys within the currently parsed configuration.
void GetSections(List<System.String>)	Fills the provided list with the names of all the sections in the currently parsed configuration.
void SetEndComment(string)	Sets a comment to be placed after the last section or item. Set the comment tonullto remove it.
string GetSectionComment(string)	Get any comment that might be associated with the given section. Returnsnullif the section does not exist or has no comment.
void SetSectionComment(string, string)	Sets a comment on a given section. The section must already exist. Set the comment tonullto remove it.
string GetComment(string, string)	Gets any comment that might be associated with the given key. Returnsnullif the key does not exist or has no comment.
string GetComment(VRage.Game.ModAPI.Ingame.Utilities.MyIniKey)	Gets any comment that might be associated with the given key. Returnsnullif the key does not exist or has no comment.
void SetComment(string, string, string)	Sets a comment on a given item. The item must already exist. Set the comment tonullto remove it.
void SetComment(VRage.Game.ModAPI.Ingame.Utilities.MyIniKey, string)	Sets a comment on a given item. The item must already exist. Set the comment tonullto remove it.
VRage.Game.ModAPI.Ingame.Utilities.MyIniValue Get(string, string)	Gets the MyIniValue of the given configuration key.
VRage.Game.ModAPI.Ingame.Utilities.MyIniValue Get(VRage.Game.ModAPI.Ingame.Utilities.MyIniKey)	Gets the MyIniValue of the given configuration key.
void Delete(string, string)	Deletes the given configuration key.
void Delete(VRage.Game.ModAPI.Ingame.Utilities.MyIniKey)	Deletes the given configuration key.
void Set(string, string, string)	Sets the value of the given configuration key.
void Set(VRage.Game.ModAPI.Ingame.Utilities.MyIniKey, string)	Sets the value of the given configuration key.
void Set(string, string, bool)	Sets the value of the given configuration key.
void Set(VRage.Game.ModAPI.Ingame.Utilities.MyIniKey, bool)	Sets the value of the given configuration key.
void Set(string, string, byte)	Sets the value of the given configuration key.
void Set(VRage.Game.ModAPI.Ingame.Utilities.MyIniKey, byte)	Sets the value of the given configuration key.
void Set(string, string, sbyte)	Sets the value of the given configuration key.
void Set(VRage.Game.ModAPI.Ingame.Utilities.MyIniKey, sbyte)	Sets the value of the given configuration key.
void Set(string, string, ushort)	Sets the value of the given configuration key.
void Set(VRage.Game.ModAPI.Ingame.Utilities.MyIniKey, ushort)	Sets the value of the given configuration key.
void Set(string, string, short)	Sets the value of the given configuration key.
void Set(VRage.Game.ModAPI.Ingame.Utilities.MyIniKey, short)	Sets the value of the given configuration key.
void Set(string, string, uint)	Sets the value of the given configuration key.
void Set(VRage.Game.ModAPI.Ingame.Utilities.MyIniKey, uint)	Sets the value of the given configuration key.
void Set(string, string, int)	Sets the value of the given configuration key.
void Set(VRage.Game.ModAPI.Ingame.Utilities.MyIniKey, int)	Sets the value of the given configuration key.
void Set(string, string, ulong)	Sets the value of the given configuration key.
void Set(VRage.Game.ModAPI.Ingame.Utilities.MyIniKey, ulong)	Sets the value of the given configuration key.
void Set(string, string, long)	Sets the value of the given configuration key.
void Set(VRage.Game.ModAPI.Ingame.Utilities.MyIniKey, long)	Sets the value of the given configuration key.
void Set(string, string, float)	Sets the value of the given configuration key.
void Set(VRage.Game.ModAPI.Ingame.Utilities.MyIniKey, float)	Sets the value of the given configuration key.
void Set(string, string, double)	Sets the value of the given configuration key.
void Set(VRage.Game.ModAPI.Ingame.Utilities.MyIniKey, double)	Sets the value of the given configuration key.
void Set(string, string, decimal)	Sets the value of the given configuration key.
void Set(VRage.Game.ModAPI.Ingame.Utilities.MyIniKey, decimal)	Sets the value of the given configuration key.
void Clear()	Empties this configuration
bool TryParse(string)	Attempts to parse the given content as a configuration file.
bool TryParse(string, ref VRage.Game.ModAPI.Ingame.Utilities.MyIniParseResult)	Attempts to parse the given content as a configuration file.
bool TryParse(string, string, ref VRage.Game.ModAPI.Ingame.Utilities.MyIniParseResult)	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() , you will only get the parsed section, the rest will be discarded.
bool TryParse(string, string)	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() , 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