Cmdlet "Merge-INI", merging INI files

[RattleSN4K3]

Cmdlet "Merge-INI", utilizing MadMilkman.INI for ini merging

Note

Based on PR #260 (required for MadMilkman.INI) which is now merged.

This includes the following:

• Merging one ini into another
• Extract/remove INI section/keys

Use case

A specific use case I have in mind is a mod which patches the the game files' INI with specific properties. On uninstallation of the mod, the changes are reverted.

UT2004 and patch/mod to apply "Master-Server" changes

Game: UT2004
Mod: UT2004 MasterPatch

Install Script:

Merge-Ini -SourceFilePath "$InstallDirectory\System\UT2004.ini" -SourceSection "IpDrv.MasterServerLink" -DestinationFilePath "$InstallDirectory\System\MasterPatch.bak.ini" -Clear -PreserveKeys
Merge-Ini -SourceFilePath "$InstallDirectory\System\MasterPatch.ini" -DestinationFilePath "$InstallDirectory\System\UT2004.ini" -Clear -PreserveKeys

Uninstall Script:

Merge-Ini -SourceFilePath "$InstallDirectory\System\MasterPatch.bak.ini" -SourceSection "IpDrv.MasterServerLink" -DestinationFilePath "$InstallDirectory\System\UT2004.ini" -Extract -Clear -PreserveKeys

The mod has the System\MasterPatch.ini as archive. On installation it will merge the ini with creating a backup. On uninstallation the maser patch is reverted by applying the backup data.

Examples

The following example INI file is used for all examples.

config.ini

[URL]
Protocol=ut2004
ProtocolDescription=Unreal Protocol
Name=Player
; ...

[IpDrv.MasterServerLink]
LANPort=11777
LANServerPort=10777
MasterServerList=(Address="ut2004master1.epicgames.com",Port=28902)
MasterServerList=(Address="ut2004master2.epicgames.com",Port=28902)

[Engine.MaplistManager]
Games=(GameType="BonusPack.xLastManStandingGame",ActiveMaplist="Default LMS")
; ...

patch.ini

[IpDrv.MasterServerLink]
MasterServerList=(Address="utmaster.openspy.net",Port=28902)
MasterServerList=(Address="ut2004master.333networks.com",Port=28902)
MasterServerList=(Address="ut2004master.errorist.eu",Port=28902)

( click for examples )

Example 1: Simple Merge (Update Existing)

Merge-Ini -SourceFilePath "$InstallDirectory\System\patch.ini" -DestinationFilePath "$InstallDirectory\System\config.ini"

Result:
The cmdlet processes the entire source file and merges the [IpDrv.MasterServerLink] section. Since the destination already contains two MasterServerList entries, each patch entry updates the last matching entry. Multi-Value parameters need clearing and preserving. In the end, the destination section becomes:

[URL]
Protocol=ut2004
ProtocolDescription=Unreal Protocol
Name=Player
; ...

[IpDrv.MasterServerLink]
LANPort=11777
LANServerPort=10777
MasterServerList=(Address="ut2004master1.epicgames.com",Port=28902)
MasterServerList=(Address="ut2004master.errorist.eu",Port=28902)

[Engine.MaplistManager]
Games=(GameType="BonusPack.xLastManStandingGame",ActiveMaplist="Default LMS")

Note: Only the last patch value is visible because each patch line revised the same key entry.

Example 2: Merge with Appending (respectively perserving keys)

Merge-Ini -SourceFilePath "$InstallDirectory\System\patch.ini" -DestinationFilePath "$InstallDirectory\System\config.ini" -preserve

Result:
With the -PreserveKeys (short: -append) switch, each MasterServerList entry from the patch is appended. The destination section now contains its original entries plus all three patch entries:

[URL]
Protocol=ut2004
ProtocolDescription=Unreal Protocol
Name=Player
; ...

[IpDrv.MasterServerLink]
LANPort=11777
LANServerPort=10777
MasterServerList=(Address="ut2004master1.epicgames.com",Port=28902)
MasterServerList=(Address="ut2004master2.epicgames.com",Port=28902)
MasterServerList=(Address="utmaster.openspy.net",Port=28902)
MasterServerList=(Address="ut2004master.333networks.com",Port=28902)
MasterServerList=(Address="ut2004master.errorist.eu",Port=28902)

[Engine.MaplistManager]
Games=(GameType="BonusPack.xLastManStandingGame",ActiveMaplist="Default LMS")

Example 3: Merge with Clear

Merge-Ini -SourceFilePath "$InstallDirectory\System\patch.ini" -DestinationFilePath "$InstallDirectory\System\config.ini" -Clear -PreserveKeys

Result:
Introducing the -Clear switch first removes all existing MasterServerList entries in the destination. Then, with -PreserveKeys, the patch file's entries are added:

[URL]
Protocol=ut2004
ProtocolDescription=Unreal Protocol
Name=Player
; ...

[IpDrv.MasterServerLink]
LANPort=11777
LANServerPort=10777
MasterServerList=(Address="utmaster.openspy.net",Port=28902)
MasterServerList=(Address="ut2004master.333networks.com",Port=28902)
MasterServerList=(Address="ut2004master.errorist.eu",Port=28902)

[Engine.MaplistManager]
Games=(GameType="BonusPack.xLastManStandingGame",ActiveMaplist="Default LMS")

Example 4: Extract Entire Section

Merge-Ini -SourceFilePath "$InstallDirectory\System\config.ini" -DestinationFilePath "$InstallDirectory\System\backup.ini" -SourceSection "IpDrv.MasterServerLink" -Extract -PreserveKeys

Result:
Here, only the [IpDrv.MasterServerLink] section from the config is merged/extracted into the destination. After merging, that section is removed from config.ini.

The backup file becomes:

[IpDrv.MasterServerLink]
LANPort=11777
LANServerPort=10777
MasterServerList=(Address="ut2004master1.epicgames.com",Port=28902)
MasterServerList=(Address="ut2004master2.epicgames.com",Port=28902)

And the config file no longer contains the [IpDrv.MasterServerLink] section.

[URL]
Protocol=ut2004
ProtocolDescription=Unreal Protocol
Name=Player

[Engine.MaplistManager]
Games=(GameType="BonusPack.xLastManStandingGame",ActiveMaplist="Default LMS")

Example 5: Extract Specific Key

Merge-Ini -SourceFilePath "$InstallDirectory\System\config.ini" -DestinationFilePath "$InstallDirectory\System\config.ini" -SourceSection "IpDrv.MasterServerLink" -SourceKey "MasterServerList" -DestinationKey "MasterServerList_Backup" -Extract -PreserveKeys

Merge-Ini -SourceFilePath "$InstallDirectory\System\patch.ini" -DestinationFilePath "$InstallDirectory\System\config.ini" -SourceSection "IpDrv.MasterServerLink" -SourceKey "MasterServerList" -DestinationSection "IpDrv.MasterServerLink" -DestinationKey "MasterServerList" -Clear -PreserveKeys

Result:
Only the MasterServerList key is merged from the specified section. It is created as a Backup first in MasterServerList_Backup. The destination section becomes:

[URL]
Protocol=ut2004
ProtocolDescription=Unreal Protocol
Name=Player
; ...

[IpDrv.MasterServerLink]
LANPort=11777
LANServerPort=10777
MasterServerList_Backup=(Address="ut2004master1.epicgames.com",Port=28902)
MasterServerList_Backup=(Address="ut2004master2.epicgames.com",Port=28902)
MasterServerList=(Address="utmaster.openspy.net",Port=28902)
MasterServerList=(Address="ut2004master.333networks.com",Port=28902)
MasterServerList=(Address="ut2004master.errorist.eu",Port=28902)

[Engine.MaplistManager]
Games=(GameType="BonusPack.xLastManStandingGame",ActiveMaplist="Default LMS")

In the config file, the MasterServerList key is backupped and removed. The patch is applied and merged into the same section.

Example 6: Remove Section

Merge-Ini -SourceFilePath "$InstallDirectory\System\config.ini" -SourceSection "IpDrv.MasterServerLink" -SourceKey "MasterServerList" -Extract

Result:
Only the MasterServerList key is removed from the specified section. No additional file is created. The destination section becomes:

[URL]
Protocol=ut2004
ProtocolDescription=Unreal Protocol
Name=Player
; ...

[IpDrv.MasterServerLink]
LANPort=11777
LANServerPort=10777

[Engine.MaplistManager]
Games=(GameType="BonusPack.xLastManStandingGame",ActiveMaplist="Default LMS")

---

Wiki

Merge-Ini

Merge-Ini

Merges the sections and keys of one INI file into another INI file.

Syntax

Merge-Ini
    -src, -SourceFilePath <string>                  Path to the source INI file.
    -dest, -DestinationFilePath <string>            Path to the destination INI file. (optional if extracting)

    Optional (Extraction and Filters):
    -ss, -SourceSection <string>                    The source INI section to merge or extract. If omitted, the entire source file is merged.
    -sk, -SourceKey <string>                        The specific source key to merge or extract (used only when a section is specified).
    -ds, -DestinationSection <string>               The destination INI section to merge into. Defaults to the source section name if not provided.
    -dk, -DestinationKey <string>                   The destination key name for single key merges. Defaults to the source key name if not provided.
    -Extract                                        If set, extracts (removes) the merged section or key from the source INI file after merging.

    Optional (Merge Behavior):
    -wrap, -WrapValueInQuotes <bool>                Controls value quoting: true enforces quotes, false removes quotes, null preserves the destination's quoting style.
    -addkey, -UpdateOrAddKey <bool>                 Adds a new key if the destination setting is not found.
    -addsection, -UpdateOrAddKey <bool>             Adds a new section if the destination section is not found.
    -Clear                                          Clears all existing instances of a key in the destination before merging new values.
    -appendkey, -preserve, -PreserveKeys            Appends new key-value pairs instead of updating existing ones (useful for multi-value settings).
    -appendsection, -PreserveSections               Appends new seaction instead of updating existing ones
    -insert, -InsertIndex <int>                     Zero-based index at which to insert the new entry instead of adding it at the end.
    -keepkey, -KeepKeyDuplicates <bool>             Allows duplicate keys in the destination section if true.
    -nokey, -NoKeyDuplicates                        Prevents duplicate keys in the destination section.
    -keepsec, -KeepSectionDuplicates <bool>         Allows duplicate sections in the destination INI file if true.
    -nosec, -NoSectionDuplicates                    Prevents duplicate sections in the destination INI file.
    -enc, -Codepage <ENCODING>                      The codepage/encoding to use when reading and writing the INI files.

[RattleSN4K3]

Needs additional testing with different use cases. For now only a "draft"

[pathartl]

This is awesome! I created #164 with this sort of intention in mind, but of course it's not limited to just servers.