Skip to content

IniController

Jump to bottom Edit New page
子悦解说 edited this page Sep 16, 2024 · 2 revisions

IniController is a library for reading and writing .ini files.

Glossary

Buffers

IniController has a buffer for reading INI value quickly, called IniBuffer.

IniBuffer is suggested using for some demands that need to read a big INI file frequently, such as the localized file.

IniBuffer isn't an automatic system. You need to invoke the IniWriteBuffer function to write a buffer for the INI file.

IniBuffer's construct is like this:

  • IniBuffer
    • File1 (file buffer)
      • Section1 (section buffer)
        • Key1 (key buffer)
          • Value
        • Key2
          • Value
      • Section2
        • Key1
          • Value

IniBuffer also allows import and export buffers, and modifies manually.

Normally, IniController finds a buffer by the file to which the path is pointed. This process may take a lot of time and may cause a lack of performance in the code. For the best performance, you can choose Strict File Path Edition.

Strict File Path Edition

Strict File Path Edition finds the buffer by the file path itself, instead of finding the buffer by the file which path pointed. If the literal file paths are different but point to the same file, they will not be considered the same. Note that file paths are case-sensitive.

For example, in this edition, Data/Local.ini, Data\Local.ini, and data/local.ini have independent buffers.

Writing INI

IniController uses Windows API's WritePrivateProfileStringA function to write INI files.

Reading INI

IniController uses a custom read-file function so that values can be saved in buffers.

Keys and values will be trimmed. For example, foo = bar will equals foo=bar.

Comments

IniController identifies lines that begin with ; as comments. Lines that begin with #, or contain ; will not be identified as comments.

Converting INI files

IniController allows you to convert INI files to other file types. You can also export the buffer to an INI file by this.

IniController can export INI to .json, .html, .xml, and .INI. Some characters will be replaced with predefined entities.

Note that the sequence of key-values may be different from the original.

See further information

Export to JSON

IniExportJson and IniBufferExportJson functions can export INI to JSON.

Parameters

Parameter Description
path$ The path of the INI file.
json$ The path of exported JSON.
isMin% If equals True, then ignore all unnecessary spaces and newlines when exporting.
stringOnly% If equals False, then infer the type of value. For example, 123.456 will be inferred and saved with float, 123456 will be inferred and saved with integer, and others will be inferred and saved with string. If equals True, then save all values with string.
allowBuffer% If equals True, then get INI values from the buffer first.

Construct

The construct of JSON will be like this...

{
    "This is a section": {
        "This is a key": "This is a value",
        "This is a key with an integer value": 123456
    },
    "This is another section": {
        "This is a key with a float value": 123.456
    }
}

Export to HTML

IniExportHtml and IniBufferExportHtml functions can export INI to HTML.

There are two styles of HTML: the first is table-style and the second is list-style.

Parameters

Parameter Description
path$ The path of the INI file.
html$ The path of exported HTML.
isMin% If equals True, then ignore all unnecessary spaces and newlines when exporting.
isList% If equals True, then export with list-style.
allowBuffer% If equals True, then get INI values from the buffer first.

Table-Style

List-Style

Export to XML

IniExportXml and IniBufferExportXml functions can export INI to XML.

Parameters

Parameter Description
path$ The path of the INI file.
xml$ The path of exported XML.
isMin% If equals True, ignore unnecessary spaces and newlines when exporting.
allowBuffer% If equals True, get INI values from the buffer first.

Construct

The construct of XML will be like this...

<?xml version="1.0"?>
<file name="Name of INI file">
    <section>
        <name>This is a section</name>
        <key>
            <name>This is a key</name>
            <value>This is a value</value>
        </key>
        <key>
            <name>foo</name>
            <value>bar</value>
        </key>
    </section>
    <section>
        <name>This is another section</name>
        <key>
            <name>This is another key</name>
            <value>I&apos;m different...</value>
        </key>
    </section>
</file>

Functions List

Function Description
IniClearBuffer(path$) Clear a buffer.
IniClearAllBuffer() Clear all buffers.
IniSetBufferValue(path$, section$, key$, value$) Set a value in the buffer.
IniGetBuffer%(path$) Get a file buffer.
IniGetAllBuffer%() Get IniBuffer.
IniSetBuffer(path$, buffer%) Set a file buffer.
IniSetAllBuffer(buffer%) Set IniBuffer.
IniBufferSectionExist%(path$, section$) Check if that section exists in the buffer.
IniBufferKeyExist%(path$, section$, key$) Check if the key exists in the buffer.
IniWriteBuffer(path$, clearPrevious% = 1) Write an INI into IniBuffer. If clearPrevious% equals True, then clear the buffer before writing.
IniGetString$(path$, section$, key$, defaultValue$ = "", allowBuffer% = 1) Get string from the INI file. If allowBuffer% equals True, get the value from the buffer first.
IniGetInt%(path$, section$, key$, defaultValue% = 0, allowBuffer% = 1) Get integer from the INI file. If allowBuffer% equals True, get the value from the buffer first.
IniGetFloat#(path$, section$, key$, defaultValue# = 0.0, allowBuffer% = 1) Get float from the INI file. If allowBuffer% equals True, get the value from the buffer first.
IniGetBufferString$(path$, section$, key$, defaultValue$ = "") Get string from buffer.
IniGetBufferInt%(path$, section$, key$, defaultValue%) Get integer from buffer.
IniGetBufferFloat#(path$, section$, key$, defaultValue# = 0.0) Get float from buffer.
IniWriteString(path$, section$, key$, value$, updateBuffer% = 1) Write a string into the INI file. If updateBuffer% equals True, then update the buffer at the same time.
IniWriteInt(path$, section$, key$, value%, updateBuffer% = 1) Write an integer into the INI file. If updateBuffer% equals True, then update the buffer at the same time.
IniWriteFloat(path$, section$, key$, value#, updateBuffer% = 1) Write a float into the INI file. If updateBuffer% equals True, then update the buffer at the same time.
IniSectionExist%(path$, section$, allowBuffer% = 1) Check that the section exists in the INI file. If allowBuffer% equals True, then check if that exists in the buffer first.
IniKeyExist%(path$, section$, key$, allowBuffer% = 1) Check that the key exists in the INI file. If allowBuffer% equals True, then check if that exists in the buffer first.
IniExportJson(path$, json$, isMin% = 0, stringOnly% = 0, allowBuffer% = 1) See Export to JSON.
IniBufferExportJson(path$, json$, isMin% = 0, stringOnly% = 0) Export a buffer's values, see Export to JSON.
IniExportHtml(path$, html$, isMin% = 0, isList% = 0, allowBuffer% = 1) See Export to HTML.
IniBufferExportHtml(path$, html$, isMin% = 0, isList% = 0) Export a buffer's values, see Export to HTML.
IniExportXml(path$, xml$, isMin% = 0, allowBuffer% = 1) See Export to XML.
IniBufferExportXml(path$, xml$, isMin% = 0) Export a buffer's values, see Export to XML.
IniCreateSection(path$, section$) Create a section in the INI file.
IniRemoveSection(path$, section$, updateBuffer%) Remove a section in the INI file.
IniRemoveBufferSection(path$, section$) Remove a section from the buffer.
IniRemoveKey(path$, section$, key$, updateBuffer%) Remove a key from the buffer.
IniRemoveBufferKey(path$, section$, key$) Remove a key from the buffer.
IniSetExportBufferValue(buffer%, section$, key$, value$) Set a value of the exported buffer.
IniExportIni(path$, ini$, isMin%, allowBuffer%) Export an INI to another INI file.
IniBufferExportIni(path$, ini$, isMin%) Export a buffer to an INI file.

Changelogs

Version Changes
v1.08 Removed original map edition. Added Strict File Path Edition.
v1.07 Optimized the buffer. Now the buffer will normalize the path before writing.
v1.06 Added Unordered Map Edition.
v1.05 Added functions for removing sections and keys, and functions for exporting INI files.
v1.04 Added export INI file feature.
v1.03 Optimization for IniBuffer.
v1.02 Added functions for checking if section/key exists in the INI file.
v1.01 Added clearPrevious% parameter for IniWriteBuffer function, if equals True, then clear buffer before writing.

High Priority: IniController • RapidBson
Middle Priority: Blib • BlitzEncode
Low Priority: NetworkConnector • OpenCC • BlitzFormat

Add a custom sidebar
Clone this wiki locally