class_EasyIni:Native syntax-Ini.Section.Key:=val +Formatting

[Verdlin]

Download
(Originally posted here)

A big problem I have had will all other Ini libraries (including the old version of EasyIni) is that their syntax is too cumbersome. The point of this library is to make it as easy as possible to R/W inis; furthermore, I wanted to make the class itself easy to read and accessible to other developers. EasyIni is currently 389 LOC.

An unexpected positive consequence of this class is that it performs exponentially faster than IniWrite operations. I posted an example below where class_EasyIni is 1162% faster than IniWrite.

My design approach was, "How can I make this as easy as possible?" The result is, you can interface with ini's using class_EasyIni objects with great ease. Thanks to custom objects, this class allows you to use the familiar, native, Object syntax.

Code: Select all

; To create an ini object,
vIni := class_EasyIni("MyIni.ini")

; To interface with the object,
for section, aKeysAndVals in vIni
   for key, val in aKeysInVals
      vIni[Section][key] := 1

vIni[VariableWithSectionName][VariableWithKeyName] := val ; this is typically used when you are looping through sections and keys
vIni.NameOfSection.NameOfKey := val ; This syntax is the easiest, but you must know the literal section name and key name to do this.
   ; It is particularly useful for handling user-defined ini variables in your applications with relative ease.
vIni.NameOfSection[VariableWithKeyName] := val ; This is when you know the literal section name
vIni[VariableWithSectionName].key := val ; This is when you know the literal key name

This file is std lib compliant. Of course, you should make sure the file name is class_EasyIni.ahk in order for this to work.

Character limitations are mostly obvious:

• You cannot use newlines in section names.
• For any alphanumeric section, (i.e. "[A]") only one case is allowed. So if you tried to add section "[a]" AddSection() would fail. This is demonstrated in my 1500 sections example below.
• During my tests, I noticed that SOH (chr(1)) and A_Space (chr(32)) were written to the same section [SOH]. I am not sure why this is the case, but I don't imagine this will be a problem for most people, if any.
• I also noticed that quite a few odd character values were getting grouped together into the same sections. Whether this is a problem for anyone is doubtful, but I suspect it is possible for those who store BBCode in inis to have problems. Regardless, this class is just a fancy custom object. If there are certain problems with section names, this is likely a problem with AHK itself and not the class.
• You cannot have a section or key that starts with the text, EasyIni_ReservedFor_. I can't imagine this being a big problem.
  "=" are not supported in keynames.
• Do whatever you want with values

A couple of notes about ini data:

• Keys without values are supported
• Although it is not recommended if you plan on using your inis with other applications that access the same ini, "]" in section names are supported.
• EasyIni stores ini data in a custom object. Much credit for this custom object goes to Lexikos and Rbrtryn for their work with ordered arrays. For more information, see OrderedArray. Thanks to the pre-existing work with OrderedArrays, I was able to create an object that, without much trouble, enabled me to maintain the format of the ini file. If any comment or newline is removed from your file, or if any sections or keys are re-ordered in your file as a result of using class_EasyIni, then this is a bug and you should report it to me!

This rewrite of the library has increased the overall speed, as well. In fact, the Save() function is now as 3629% faster than the old EasyIni class!!

Below is a test where I add every possible character value (returned from chr()) to an ini. Writing to memory took < 1 second. Writing to a file took 17seconds (3629% faster than the old class).

Spoiler

Code: Select all

{
    iAhkPID := DllCall("GetCurrentProcessId")
    Process, Priority, iAhkPID, H

    vIni := class_EasyIni("test.ini") ; Create

    Loop 65533 ; This many number of characters can be returned from chr()
    {
        if (!vIni.AddSection(chr(A_Index), A_Index, A_Index, sError))
            sErrors .= sError "`n"
    } ; Takes ~2sec

    Msgbox Errors:`n%sErrors%

    vIni.Save() ; 17sec -- 3629% increase from old EasyIni!!
    return
}

This test shows what characters are readable by class_EasyIni. As I mentioned before, certain odd characters get grouped together into the same sections. If you care to know more about this, run the previous example first, and then run this example.

Spoiler

Code: Select all

{
        iAhkPID := DllCall("GetCurrentProcessId")
        Process, Priority, iAhkPID, H

        vIni := class_EasyIni("test.ini") ; Loaded in ~1.5Sec
        vIniCopy := new EasyIni()
        vIniCopy := vIniCopy.Copy(vIni, "test - copy.ini") ; Yes, this syntax is pretty odd/bad, but it is the only way I could get the copy function to work properly

        vIniCopy.Save() ; took ~8sec
        Msgbox saved!
        return
}

Adding 1500 sections, keys, and values takes < 1 sec total to write to memory and to an ini. This example shows how sections and keys are case-sensitive. It will produce errors for sections a-z because sections A-Z already existed in the ini.

Spoiler

Code: Select all

{
        ; Whole process takes ~1sec
        iAhkPID := DllCall("GetCurrentProcessId")
        Process, Priority, iAhkPID, H

        vIni := class_EasyIni("test1500.ini") ; Create

        Loop 1500
        {
               if (!vIni.AddSection(chr(A_Index), A_Index, A_Index, sError))
                       sErrors .= sError "`n"
        } ; Takes < 1sec

        vIni.Save()
        return
}

Examples:
Creating an ini, adding and modifying sections, keys, and values, and saving.

Spoiler

Code: Select all

{
        vIni := class_EasyIni("MyIni.ini")

        if (!vIni.AddSection("Section", "Key", "Val"))
        {
               Msgbox An unexpected error occurred.  ; No errors expected for adding to a nearly blank ini. I just included this kind of handling in case there are any bugs.
               return
        }

        ; To modify areas later...
        if (!vIni.RenameSection("Section", "NewSection") || !vIni.RenameKey("NewSection", "Key", "NewKey"))
        {
               Msgbox An unexpected error occurred.
               return
        }
        ; if Newsection or Newkey are variables names, then
        NewKey := "NewKey"
        vIni[NewSection][NewKey] := "NewVal"
        ; or, in cases where you know the section name
        vIni.NewSection["NewKey"] := "NewVal"
        ; or, in cases where you know the section name and the key name
        vIni.NewSection.NewKey := "NewVal"

        vIni.Save() ; Write to ini
        return
}

Loading an ini from a string, and maintaining all formatting (including comments and newline) in an in file

Spoiler

Code: Select all

{
        sIni:="
               (LTrim
               ; One comment here...
               ; A comment here...
               [x]
               b=b
               a=a ; a comment there
               ; A second comment in [a]
               x=1
               y=2

               [[[a]]]
               a=a
               b=b
               ; A comment in this section
               ; A second comment in this section
               c=c
               ; A third comment in this section
               d=d

               [Section]
               ; and a comment here
               )"

        vIni := class_EasyIni("test.ini", sIni)

        for sSec, a in vIni
               for k, v in a
                       Msgbox %sSec%`n%k%=%v%
        vIni.Save()
        return
}

IniWrite vs EasyIni:

Spoiler

Code: Select all

{
	iAhkPID := DllCall("GetCurrentProcessId")
	Process, Priority, iAhkPID, H

	vIni := class_EasyIni("test.ini") ; Create

	Loop 50000
	{
		if (!vIni.AddSection(A_Index, A_Index, A_Index, sError))
			sErrors .= sError "`n"
	} ; Takes ~1sec

	vIni.Save() ; 20sec

	Loop 50000 ; This many number of characters can be returned from chr()
		IniWrite, %A_Index%, IniWrite.ini, %A_Index%, %A_Index%
	; Takes ~4min 4secs. 1162%
	return
}

I do appreciate any comments/input/criticism.

[joedf]

Very interesting... It makes me wonder if mcode would be faster....

[bobc119]

This library is awesome! I've used it for a long time now. Thank you Verdlin.

[Verdlin]

Very interesting... It makes me wonder if mcode would be faster....

As a general rule of thumb, I think MCode is always going to be faster than interpreted code.

This library is awesome! I've used it for a long time now. Thank you Verdlin.

You're welcome! Thanks for the support.

[highend]

Great class, Verdlin!

Do you still support it?

My problem with it:

Let's say you have 3 entries like

Code: Select all

[20150927234336]
test=1

[20150927234337]
test=2

[20150927234338]
test=3

Try to use:

Code: Select all

vCfg.DeleteSection("20150927234337")
vCfg.Save()

and you'll notice that this section isn't deleted at all (but it's follower)...
Result:

Code: Select all

[20150927234336]
test=1

[20150927234337]
test=3

So the section is still there but the contents of the next following section is transferred into it.

So atm, it doesn't work with integer section names only. Can this be fixed?

[Verdlin]

Great class, Verdlin!

Do you still support it?
...
So the section is still there but the contents of the next following section is transferred into it.

So atm, it doesn't work with integer section names only. Can this be fixed?

Thanks, Highend! This is a known bug. I've not been able to fix the bug because the code has been too complex for me to figure out.

I don't know if this is a good workaround for you, but you can add ".0" to the end of all your sections to get around this bug. Let me know if that's good enough. I could write a script for you to do this, but I think it's as simple as using Find/Replace in Notepad++ and replacing "]" with ".0]"

Long term I'd like to code a solution to this bug, but it's tricky. I have a few ideas a may try in the next week or so.

Code: Select all

{
	sIni:="
		(LTrim
			[20150927234336.0]
			test=1
 
			[20150927234337.0]
			test=2

			[20150927234338.0]
			test=3
		)"
 
	vIni := class_EasyIni("test.ini", sIni)
	for sec, aData in vIni
		for k, v in aData
			s .= s == "" ? "[" sec "]`n" k "=" v : "`n[" sec "]`n" k "=" v

	vIni.DeleteSection("20150927234337.0")
	s :=

	for sec, aData in vIni
		for k, v in aData
			s .= s == "" ? "[" sec "]`n" k "=" v : "`n[" sec "]`n" k "=" v

	Msgbox % s

	return
}

Output:
[20150927234336.0]
test=1
[20150927234338.0]
test=3

[highend]

Hi Verdlin,

I don't know if this is a good workaround for you, but you can add ".0" to the end of all your sections to get around this bug. Let me know if that's good enough. I could write a script for you to do this, but I think it's as simple as using Find/Replace in Notepad++ and replacing "]" with ".0]"

That's just a simple regex replace in my editor. No script needed. I've switched to a different naming style for all sections in the meantime.
I'm just using an affixed "x" in front of the number. As long as a alphabetical character is used to make a string out of the integer, everything works fine.

Btw, using e.g. a "#" in front of it doesn't work as well. Wasn't able to find the reason for this behavior yet...

Let's see what you an achieve if you have some time for it next week

Regards and thanks for the fast answer!

[lexikos]

To fix the bug, replace .Remove() with .Delete(). Remove() is commonly misused in this way, hence the split into RemoveAt() and Delete().

There is probably a similar bug for keys.

There is another bug related to the behaviour of integer keys in objects: integer section names are reformatted as pure decimal. For example, [0x1] and [001] become [1]. The workaround is the same as for the deletion bug.

[evilC]

Nice work, although I have ditched INIs lately as they are only two levels deep. For situations where they are sufficient though, this is a nice, simple solution.

Lately have been using Coco's JSON parser and FileWrite - it seems to me that it may well be quite easy to apply your nice simple syntax to a system using that used JSON instead.

You could keep the syntax as
vIni[Section, key, you, can, keep, on, adding, levels...] := something

something could even be an object, not just a string

[hyaray]

thanks for your class_EasyIni!!!
there's may be a bug below

Code: Select all

o := class_EasyIni("t.ini")
o.t.RemoveAt(2)
;o.t.Remove(2)
o.save()
Return

change of "t.ini"
[t]　　　　　　[t]
1=1　　　　　1=1
2=2　　　　　2=3
3=3　　　　　3=4
4=4　　　　　4=

"4=" is the Bug? If I use Remove instead, "4=" disappeared.

[Verdlin]

thanks for your class_EasyIni!!!
there's may be a bug below

Code: Select all

o := class_EasyIni("t.ini")
o.t.RemoveAt(2)
;o.t.Remove(2)
o.save()
Return

change of "t.ini"
[t]　　　　　　[t]
1=1　　　　　1=1
2=2　　　　　2=3
3=3　　　　　3=4
4=4　　　　　4=

"4=" is the Bug? If I use Remove instead, "4=" disappeared.

Yes, this is a bug and it is documented in a few posts above (see post starting with, "Thanks, Highend! This is a known bug. I've not been able to fix the bug because the code has been too complex for me to figure out.").

Lexikos has given me a solution, but I've not been able to figure out how to implement it. Rbrtryn is the one who wrote the core code which contains the bug, and so I don't fully understand it and haven't taken adequate time to figure it out. If you can bug Rbrtryn, maybe he can fix it in his OrderedArray class...

In the meanwhile, remember you can add ".0" to the end of all your sections to get around this bug.

[highend]

Are there any license restrictions or could we use the class in a commercial project as well?

[Verdlin]

Are there any license restrictions or could we use the class in a commercial project as well?

Thanks for asking! Feel free to use it. I haven't attached a license, and if I do, it would only be one which asked for attribution. So I'd just ask you to give me attribution in the same place you'll give attribution to anyone else .

[highend]

Ok, thanks. So a link in the "About <application>" window would mention this class and provides a link to
a.) This thread
or
b.) Your user profile

What do you prefer, I guess a.)?

[Verdlin]

A. is great, thanks!

[highend]

Ok, I'll do that when the time comes

[YellowPeanuts]

I really appreciate your great work.
I have a simply question.
When I use obj.save() then after saved data remove in obj.save()?
Sorry, I am not a navite speaker in english.

[Verdlin]

I really appreciate your great work.
I have a simply question.
When I use obj.save() then after saved data remove in obj.save()?
Sorry, I am not a navite speaker in english.

Thank you, YellowPeanuts! Yes, our language barrier makes it a little difficult for me to understand your question, but I'll do my best to answer it.

obj.Save() will save it to a file. The data is not removed from the object itself. That will only happen when you invoke the destructor such as obj :=

[zcooler]

Hello!

Im having difficulties how to utilize the "Default" option in IniRead within this EasyIni syntax. For example I have this IniRead command with ternary operators setting defaults (when keys and values does not exist yet) I would like to get working, but EasyIni does (as tested so far) not like expressions within its syntax when enumerating the array. Anyone have any ideas?

Code: Select all

For Each, Key In IniKeys {
IniRead, Value, %SettingsIni%, %IniSec%, %Key%, % (Key = "AllFiles" ? 1 : (Key = "SortFilter") ? "|" : 0)
 Value := vTestIni[IniSec][(Key = "AllFiles" ? 1 : (Key = "SortFilter") ? "|" : 0)] ;% (Key = "AllFiles" ? 1 : (Key = "SortFilter") ? "|" : 0)
   msgbox % IniSec "`n" Key "=" Value
}

IniRead, OutputVar, Filename, Section, Key [, Default]
Default
The value to store in OutputVar if the requested key is not found. If omitted, it defaults to the word ERROR. To store a blank value (empty string), specify %A_Space%.
[v1.0.90+]: This parameter is not used if Key is omitted.

EasyIni class:

Spoiler

Code: Select all

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;---CLASS EASYINI------------------------------------------------------------------------------------------------
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
class_EasyIni(sFile="", sLoadFromStr="")
{
	return new EasyIni(sFile, sLoadFromStr)
}

class EasyIni
{
	__New(sFile="", sLoadFromStr="") ; Loads ths file into memory.
	{
		this := this.CreateIniObj("EasyIni_ReservedFor_m_sFile", sFile
			, "EasyIni_ReservedFor_TopComments", Object()) ; Top comments can be stored in linear array because order will simply be numeric

		if (sFile == A_Blank && sLoadFromStr == A_Blank)
			return this

		; Append ".ini" if it is not already there.
		if (SubStr(sFile, StrLen(sFile)-3, 4) != ".ini")
			this.EasyIni_ReservedFor_m_sFile := sFile := (sFile . ".ini")

		sIni := sLoadFromStr
		if (sIni == A_Blank)
			FileRead, sIni, %sFile%

/*
	Current design (not fully implemented):
	---------------------------------------------------------------------------------------------------------------------------------------------------
	Comments at the top of the section apply to the file as a whole. They are keyed off an internal section called "EasyIni_ReservedFor_TopComments."
	Comments above section headers apply to the the last key of the previous section.
	If a comment appears between two keys, then it will apply to the key above it -- this is consistent with the solution for comments above section headers.
	Newlines will be stored in similar fashion to comments.
	---------------------------------------------------------------------------------------------------------------------------------------------------

	---------------------------------------------------------------------------------------------------------------------------------------------------
	If full-support for comments needs to be added, then the design below should supersede the design above.
	By saying, "Full-support" I mean a way to directly access these comments based upon sections and keys.
	---------------------------------------------------------------------------------------------------------------------------------------------------

	---------------------------------------------------------------------------------------------------------------------------------------------------
	Comments at the top of the section apply to the file as a whole. They are keyed off an internal section called "EasyIni_ReservedFor_TopComments."
	Comments above section headers apply to the section header. If people dislike this, I may instead chose to make the comments apply to the last key of the previous section if there a newline in-between the comment in question and the next section. I may come up with some decent solution as I experiment
	If a comment appears between two keys, then it will apply to the key below it -- this is consistent with the solution for comments above section headers.
	Newlines will be stored in similar fashion to comments.
	---------------------------------------------------------------------------------------------------------------------------------------------------
*/
		Loop, Parse, sIni, `n, `r
		{
			sTrimmedLine := Trim(A_LoopField)

			; Comments or newlines within the ini
			if (SubStr(sTrimmedLine, 1, 1) == ";" || sTrimmedLine == A_Blank) ; A_Blank would be a newline
			{
				; Chr(14) is just the magical char to indicate that this line should only be a newline "`n"
				LoopField := A_LoopField == A_Blank ? Chr(14) : A_LoopField

				if (sCurSec == A_Blank)
					this.EasyIni_ReservedFor_TopComments.Insert(A_Index, LoopField) ; not using sTrimmedLine so as to keep comment formatting
				else
				{
					if (sPrevKeyForThisSec == A_Blank) ; This happens when there is a comment in the section before the first key, if any
						sPrevKeyForThisSec := "SectionComment"

					if (IsObject(this[sCurSec].EasyIni_ReservedFor_Comments))
					{
						if (this[sCurSec].EasyIni_ReservedFor_Comments.HasKey(sPrevKeyForThisSec))
							this[sCurSec].EasyIni_ReservedFor_Comments[sPrevKeyForThisSec] .= "`n" LoopField
						else this[sCurSec].EasyIni_ReservedFor_Comments.Insert(sPrevKeyForThisSec, LoopField)
					}
					else
					{
						if (IsObject(this[sCurSec]))
							this[sCurSec].EasyIni_ReservedFor_Comments := {(sPrevKeyForThisSec):LoopField}
						else this[sCurSec, "EasyIni_ReservedFor_Comments"] := {(sPrevKeyForThisSec):LoopField}
					}
				}
				continue
			}

			; [Section]
			if (SubStr(sTrimmedLine, 1, 1) = "[" && InStr(sTrimmedLine, "]")) ; need to be sure that this isn't just a key starting with "["
			{
				if (sCurSec != A_Blank && !this.HasKey(sCurSec))
					this[sCurSec] := EasyIni_CreateBaseObj()
				sCurSec := SubStr(sTrimmedLine, 2, InStr(sTrimmedLine, "]", false, 0) - 2) ; 0 search right to left. We want to trim the *last* occurence of "]"
				sPrevKeyForThisSec := ""
				continue
			}

			; key=val
			iPosOfEquals := InStr(sTrimmedLine, "=")
			if (iPosOfEquals)
			{
				sPrevKeyForThisSec := SubStr(sTrimmedLine, 1, iPosOfEquals - 1) ; so it's not the previous key yet...but it will be on next iteration :P
				val := SubStr(sTrimmedLine, iPosOfEquals + 1)
				StringReplace, val, val , `%A_ScriptDir`%, %A_ScriptDir%, All
				StringReplace, val, val , `%A_WorkingDir`%, %A_ScriptDir%, All
				this[sCurSec, sPrevKeyForThisSec] := val
			}
			else ; at this point, we know it isn't a comment, or newline, it isn't a section, and it isn't a conventional key-val pair. Treat this line as a key with no val
			{
				sPrevKeyForThisSec := sTrimmedLine
				this[sCurSec, sPrevKeyForThisSec] := ""
			}
		}
		; if there is a section with no keys and it is at the bottom of the file, then we missed it
		if (sCurSec != A_Blank && !this.HasKey(sCurSec))
			this[sCurSec] := EasyIni_CreateBaseObj()

		return this
	}

	CreateIniObj(parms*)
	{
		; Define prototype object for ini arrays:
		static base := {__Set: "EasyIni_Set", _NewEnum: "EasyIni_NewEnum", Delete: "Delete", Remove: "EasyIni_Remove", Insert: "EasyIni_Insert", InsertBefore: "EasyIni_InsertBefore", AddSection: "EasyIni.AddSection", RenameSection: "EasyIni.RenameSection", DeleteSection: "EasyIni.DeleteSection", GetSections: "EasyIni.GetSections", FindSecs: "EasyIni.FindSecs", AddKey: "EasyIni.AddKey", RenameKey: "EasyIni.RenameKey", DeleteKey: "EasyIni.DeleteKey", GetKeys: "EasyIni.GetKeys", FindKeys: "EasyIni.FindKeys", GetVals: "EasyIni.GetVals", FindVals: "EasyIni.FindVals", HasVal: "EasyIni.HasVal", Copy: "EasyIni.Copy", Merge: "EasyIni.Merge", GetFileName: "EasyIni.GetFileName", GetOnlyIniFileName:"EasyIni.GetOnlyIniFileName", IsEmpty:"EasyIni.IsEmpty", Reload: "EasyIni.Reload", GetIsSaved: "EasyIni.GetIsSaved", Save: "EasyIni.Save", ToVar: "EasyIni.ToVar"}
		; Create and return new object:
		return Object("_keys", Object(), "base", base, parms*)
	}

	AddSection(sec, key="", val="", ByRef rsError="")
	{
		if (this.HasKey(sec))
		{
			rsError := "Error! Cannot add new section [" sec "], because it already exists."
			return false
		}

		if (key == A_Blank)
			this[sec] := EasyIni_CreateBaseObj()
		else this[sec, key] := val

		return true
	}

	RenameSection(sOldSec, sNewSec, ByRef rsError="")
	{
		if (!this.HasKey(sOldSec))
		{
			rsError := "Error! Could not rename section [" sOldSec "], because it does not exist."
			return false
		}

		this[sNewSec] := this[sOldSec]
		this.DeleteSection(sOldSec)

		return true
	}

	DeleteSection(sec)
	{
		this.Remove(sec)
		return
	}

	GetSections(sDelim="`n", sSort="")
	{
		for sec in this
			secs .= (A_Index == 1 ? sec : sDelim sec)

		if (sSort)
			Sort, secs, D%sDelim% %sSort%

		return secs
	}

	FindSecs(sExp, iMaxSecs="")
	{
		aSecs := []
		for sec in this
		{
			if (RegExMatch(sec, sExp))
			{
				aSecs.Insert(sec)
				if (iMaxSecs&& aSecs.MaxIndex() == iMaxSecs)
					return aSecs
			}
		}
		return aSecs
	}

	AddKey(sec, key, val="", ByRef rsError="")
	{
		if (this.HasKey(sec))
		{
			if (this[sec].HasKey(key))
			{
				rsError := "Error! Could not add key, " key " because there is a key in the same section:`nSection: " sec "`nKey: " key
				return false
			}
		}
		else
		{
			rsError := "Error! Could not add key, " key " because Section, " sec " does not exist."
			return false
		}
		this[sec, key] := val
		return true
	}

	RenameKey(sec, OldKey, NewKey, ByRef rsError="")
	{
		if (!this[sec].HasKey(OldKey))
		{
			rsError := "Error! The specified key " OldKey " could not be modified because it does not exist."
			return false
		}

		ValCopy := this[sec][OldKey]
		this.DeleteKey(sec, OldKey)
		this.AddKey(sec, NewKey)
		this[sec][NewKey] := ValCopy
		return true
	}

	DeleteKey(sec, key)
	{
		this[sec].Delete(key)
		return
	}

	GetKeys(sec, sDelim="`n", sSort="")
	{
		for key in this[sec]
			keys .= A_Index == 1 ? key : sDelim key

		if (sSort)
			Sort, keys, D%sDelim% %sSort%

		return keys
	}

	FindKeys(sec, sExp, iMaxKeys="")
	{
		aKeys := []
		for key in this[sec]
		{
			if (RegExMatch(key, sExp))
			{
				aKeys.Insert(key)
				if (iMaxKeys && aKeys.MaxIndex() == iMaxKeys)
					return aKeys
			}
		}
		return aKeys
	}

	; Non-regex, exact match on key
	; returns key(s) and their assocationed section(s)
	FindExactKeys(key, iMaxKeys="")
	{
		aKeys := {}
		for sec, aData in this
		{
			if (aData.HasKey(key))
			{
				aKeys.Insert(sec, key)
				if (iMaxKeys && aKeys.MaxIndex() == iMaxKeys)
					return aKeys
			}
		}
		return aKeys
	}

	GetVals(sec, sDelim="`n", sSort="")
	{
		for key, val in this[sec]
			vals .= A_Index == 1 ? val : sDelim val

		if (sSort)
			Sort, vals, D%sDelim% %sSort%

		return vals
	}

	FindVals(sec, sExp, iMaxVals="")
	{
		aVals := []
		for key, val in this[sec]
		{
			if (RegExMatch(val, sExp))
			{
				aVals.Insert(val)
				if (iMaxVals && aVals.MaxIndex() == iMaxVals)
					break
			}
		}
		return aVals
	}

	HasVal(sec, FindVal)
	{
		for k, val in this[sec]
			if (FindVal = val)
				return true
		return false
	}

	; SourceIni: May be EasyIni object or simply a path to an ini file.
	; bCopyFileName = true: Allow copying of data without copying the file name.
	Copy(SourceIni, bCopyFileName = true)
	{
		; Get ini as string.
		if (IsObject(SourceIni))
			sIniString := SourceIni.ToVar()
		else FileRead, sIniString, %SourceIni%

		; Effectively make this function static by allowing calls via EasyIni.Copy.
		if (IsObject(this))
		{
			if (bCopyFileName)
				sOldFileName := this.GetFileName()
			this := A_Blank ; avoid any copy constructor issues.

			; ObjClone doesn't work consistently. It's likely a problem with the meta-function overrides,
			; but this is a nice, quick hack.
			this := class_EasyIni(SourceIni.GetFileName(), sIniString)

			; Restore file name.
			this.EasyIni_ReservedFor_m_sFile := sOldFileName
		}
		else
			return class_EasyIni(bCopyFileName ? SourceIni.GetFileName() : "", sIniString)

		return this
	}

	;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
	/*
		Author: Verdlin
		STILL UNDER CONSTRUCTION. Need to handle comments, and then this will be complete.
		Function: Merge
			Purpose: Merge two EasyIni objects.
		Parameters
			vOtherIni: Other EasyIni object to merge with this.
			bRemoveNonMatching: If true, removes sections and keys that do not exist in both inis.
			bOverwriteMatching: If true, any key that exists in both objects will use the val from vOtherIni.
			vExceptionsIni: class_Easy ini object full of exceptions keys for secs. Any matching key will remain unchanged.
	*/
	Merge(vOtherIni, bRemoveNonMatching = false, bOverwriteMatching = false, vExceptionsIni = "")
	{
		; TODO: Perhaps just save one ini, read it back in, and then perform merging? I think this would help with formatting.
		; [Sections]
		for sec, aKeysToVals in vOtherIni
		{
			if (!this.HasKey(sec))
				if (bRemoveNonMatching)
					this.DeleteSection(sec)
				else this.AddSection(sec)

			; key=val
			for key, val in aKeysToVals
			{
				bMakeException := vExceptionsIni[sec].HasKey(key)

				if (this[sec].HasKey(key))
				{
					if (bOverwriteMatching && !bMakeException)
						this[sec, key] := val
				}
				else
				{
					if (bRemoveNonMatching && !bMakeException)
						this.DeleteKey(sec, key)
					else if (!bRemoveNonMatching)
						this.AddKey(sec, key, val)
				}
			}
		}
		return
	}
	;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

	;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
	/*
		Author: Verdlin
		Function: GetFileName
			Purpose: Wrapper to return the extremely long named member var, EasyIni_ReservedFor_m_sFile
		Parameters
			None
	*/
	GetFileName()
	{
		return this.EasyIni_ReservedFor_m_sFile
	}
	;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

	;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
	/*
		Author: Verdlin
		Function: GetFileName
			Purpose: Wrapper to return just the .ini name without the path.
		Parameters
			None
	*/
	GetOnlyIniFileName()
	{
		return SubStr(this.EasyIni_ReservedFor_m_sFile, InStr(this.EasyIni_ReservedFor_m_sFile,"\", false, -1)+1)
	}
	;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

	;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
	/*
		Author: Verdlin
		Function: IsEmpty
			Purpose: To indicate whether or not this ini has data
		Parameters
			None
	*/
	IsEmpty()
	{
		return (this.GetSections() == A_Blank ; No sections.
			&& !this.EasyIni_ReservedFor_TopComments.HasKey(1)) ; and no comments.
	}
	;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

	;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
	/*
		Author: Verdlin
		Function: Reload
			Purpose: Reloads object from ini file. This is necessary when other routines may be modifying the same ini file.
		Parameters
			None
	*/
	Reload()
	{
		if (FileExist(this.GetFileName()))
			this := class_EasyIni(this.GetFileName()) ; else nothing to reload.
		return this
	}
	;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

	; TODO: Add option to store load and save times in comment at bottom of ini?
	Save(sSaveAs="", bWarnIfExist=false)
	{
		if (sSaveAs == A_Blank)
			sFile := this.GetFileName()
		else
		{
			sFile := sSaveAs

			; Append ".ini" if it is not already there.
			if (SubStr(sFile, StrLen(sFile)-3, 4) != ".ini")
				sFile .= ".ini"

			if (bWarnIfExist && FileExist(sFile))
			{
				MsgBox, 4,, The file "%sFile%" already exists.`n`nAre you sure that you want to overwrite it?
				IfMsgBox, No
					return false
			}
		}

		; Formatting is preserved in ini object.
		FileDelete, %sFile%

		bIsFirstLine := true
		for k, v in this.EasyIni_ReservedFor_TopComments
		{
			FileAppend, % (A_Index == 1 ? "" : "`n") (v == Chr(14) ? "" : v), %sFile%
			bIsFirstLine := false
		}

		for section, aKeysToVals in this
		{
			FileAppend, % (bIsFirstLine ? "[" : "`n[") section "]", %sFile%
			bIsFirstLine := false

			bEmptySection := true
			for key, val in aKeysToVals
			{
				bEmptySection := false
				FileAppend, `n%key%=%val%, %sFile%

				; Add the comment(s) for this key
				sComments := this[section].EasyIni_ReservedFor_Comments[key]
				Loop, Parse, sComments, `n
					FileAppend, % "`n" (A_LoopField == Chr(14) ? "" : A_LoopField), %sFile%
			}
			if (bEmptySection)
			{
				; An empy section may contain comments...
				sComments := this[section].EasyIni_ReservedFor_Comments["SectionComment"]
				Loop, Parse, sComments, `n
					FileAppend, % "`n" (A_LoopField == Chr(14) ? "" : A_LoopField), %sFile%
			}
		}
		return true
	}

	ToVar()
	{
		sTmpFile := "$$$EasyIni_Temp.ini"
		this.Save(sTmpFile, !A_IsCompiled)
		FileRead, sIniAsVar, %sTmpFile%
		FileDelete, %sTmpFile%
		return sIniAsVar
	}
}

; For all of the EasyIni_* functions below, much credit is due to Lexikos and Rbrtryn for their work with ordered arrays
; See http://www.autohotkey.com/board/topic/61792-ahk-l-for-loop-in-order-of-key-value-pair-creation/?p=389662 for Lexikos's initial work with ordered arrays
; See http://www.autohotkey.com/board/topic/94043-ordered-array/#entry592333 for Rbrtryn's OrderedArray lib
EasyIni_CreateBaseObj(parms*)
{
	; Define prototype object for ordered arrays:
	static base := {__Set: "EasyIni_Set", _NewEnum: "EasyIni_NewEnum", Delete: "Delete", Remove: "EasyIni_Remove", Insert: "EasyIni_Insert", InsertBefore: "EasyIni_InsertBefore"}
	; Create and return new base object:
	return Object("_keys", Object(), "base", base, parms*)
}

EasyIni_Set(obj, parms*)
{
	; If this function is called, the key must not already exist.
	; Sub-class array if necessary then add this new key to the key list, if it doesn't begin with "EasyIni_ReservedFor_"
	if parms.maxindex() > 2
		ObjInsert(obj, parms[1], EasyIni_CreateBaseObj())

	; Skip over member variables
	if (SubStr(parms[1], 1, 20) <> "EasyIni_ReservedFor_")
		ObjInsert(obj._keys, parms[1])
	; Since we don't return a value, the default behaviour takes effect.
	; That is, a new key-value pair is created and stored in the object.
}

EasyIni_NewEnum(obj)
{
	; Define prototype object for custom enumerator:
	static base := Object("Next", "EasyIni_EnumNext")
	; Return an enumerator wrapping our _keys array's enumerator:
	return Object("obj", obj, "enum", obj._keys._NewEnum(), "base", base)
}

EasyIni_EnumNext(e, ByRef k, ByRef v="")
{
	; If Enum.Next() returns a "true" value, it has stored a key and
	; value in the provided variables. In this case, "i" receives the
	; current index in the _keys array and "k" receives the value at
	; that index, which is a key in the original object:
	if r := e.enum.Next(i,k)
		; We want it to appear as though the user is simply enumerating
		; the key-value pairs of the original object, so store the value
		; associated with this key in the second output variable:
		v := e.obj[k]
	return r
}

EasyIni_Remove(obj, parms*)
{
	r := ObjRemove(obj, parms*)         ; Remove keys from main object
	Removed := []                     
	for k, v in obj._keys             ; Get each index key pair
		if not ObjHasKey(obj, v)      ; if key is not in main object
			Removed.Insert(k)         ; Store that keys index to be removed later
	for k, v in Removed               ; For each key to be removed
		ObjRemove(obj._keys, v, "")   ; remove that key from key list

	return r
}

EasyIni_Insert(obj, parms*)
{
	r := ObjInsert(obj, parms*)            ; Insert keys into main object
	enum := ObjNewEnum(obj)              ; Can't use for-loop because it would invoke EasyIni_NewEnum
	while enum[k] {                      ; For each key in main object
		for i, kv in obj._keys           ; Search for key in obj._keys
			if (k = "_keys" || k = kv || SubStr(k, 1, 20) = "EasyIni_ReservedFor_" || SubStr(kv, 1, 20) = "EasyIni_ReservedFor_")   ; If found...
				continue 2               ; Get next key in main object
		ObjInsert(obj._keys, k)          ; Else insert key into obj._keys
	}

	return r
}

EasyIni_InsertBefore(obj, key, parms*)
{
	OldKeys := obj._keys                 ; Save key list
	obj._keys := []                      ; Clear key list
	for idx, k in OldKeys {              ; Put the keys before key
		if (k = key)                     ; back into key list
			break
		obj._keys.Insert(k)
	}

	r := ObjInsert(obj, parms*)            ; Insert keys into main object
	enum := ObjNewEnum(obj)              ; Can't use for-loop because it would invoke EasyIni_NewEnum
	while enum[k] {                      ; For each key in main object
		for i, kv in OldKeys             ; Search for key in OldKeys
			if (k = "_keys" || k = kv)   ; If found...
				continue 2               ; Get next key in main object
		ObjInsert(obj._keys, k)          ; Else insert key into obj._keys
	}

	for i, k in OldKeys {                ; Put the keys after key
		if (i < idx)                     ; back into key list
			continue
		obj._keys.Insert(k)
	}

	return r
}
;****************************************************************************************************************