EQWatcher Evolution > Scripting  > Ini Files


Introduction

EQWatcher Evolution has built-in support for Ini files.  There are several ways to use this functionality, ranging from idiot proof to "what the hell is an iterator".  The format of the files may look SLIGHTLY different than, say, Windows or EQ would use, but mostly the same.  In fact, the routines found here could directly modify basically ANY Ini file from Windows, EQ, etc -- of course, that would require file access to NOT be protected.

The simplest way to retrieve/execute information from an Ini file section is through the ReadINI command.  This is a simplified single command form. 

The most flexible way to work with an Ini file is to use LoadINI (or NewINI).  This loads the Ini file into memory, allowing the data to be used and manipulated and even the ability to write a modified Ini file -- all functions except for ReadINI are for use with this method.  When using this method, multiple Ini files may be used at the same time -- use the correct filename for each function call to tell EQWatcher which Ini file you wish to use at any given time.

Some of the commands are directed toward manually parsing a section line by line, and manipulating that section or line.  To begin this method, use EachINILine -- then to retrieve the next line, use NextINILine.  The current line in use can be modified using SetCurINILine, or deleted using DelCurINILine.  Lines can be inserted before or after using InsertINILineBefore and InsertINILineAfter.

Other commands allow you to check if a section exists (IsINISection), create a new section (NewINISection), remove a section (RemoveINISection), add a new line to the end of a particular section (NewINILine), retrieve a specific variable from a particular section (GetINIVariable), or execute a section (RunINISection).

When changing Ini file data, please note that it is NOT automatically saved -- you must use WriteINI.

List of commands


DelCurINILine, EachINILine, GetINIVariable, InsertINILineAfter, InsertINILineBefore, IsINISection, LoadINI, NewINI, NewINILine, NewINISection, NextINILine, ReadINI, RemoveINISection, RunINISection, SetCurINILine, UnloadINI, WriteINI



The "DelCurINILine" Command

This command deletes the current line of a particular section.  The "current line" is the last line that was returned by either EachINILine or NextINILine.

Syntax:

DelCurINILine([Filename])


Filename: The filename of the file to use


Return Value:

This command returns true if the line was deleted, or false if the line (or the file itself) did not exist.


The "EachINILine" Command

This command begins the "current line" iterator.  Basically it retrieves the first line of a section, and allows usage of functions that manipulate the "current line" or do line insertion.

Syntax:

EachINILine([Filename],[Section],[Variable])


Filename: The filename of the file to use

Section: The name of the section to use

Variable: The string variable to store the line read


Return Value:

This command returns true if the line was retrieved, or false if the filename, section, or line (i.e. the section has no lines) does not exist.


The "GetINISectionList" Command

This command creates a list of sections in an ini file.

Syntax:

GetINISectionList([Filename])


Filename: The filename of the file to use


Return Value:

This command returns a string containing a dynarray formatted list of sections of the given ini file.


The "GetINIVariable" Command

This command retrieves the value of a particular variable expected to be in a certain section.

Syntax:

GetINIVariable([Filename],[Section],[Ini Variable Name],[Variable])


Filename: The filename of the file to use

Section: The name of the section to use

Ini Variable Name: The variable name to look for

Variable: The variable to store the value


Return Value:

This command returns true if the value was retrieved, or false if the filename, section, or variable does not exist.


The "InsertINILineAfter" Command

This command inserts a line AFTER the "current line" in the iteration.  The "current line" is the last line that was returned by either EachINILine or NextINILine.  Obviously since this line is being inserted directly after the current line, it will be the next line returned by NextINILine.

Syntax:

InsertINILineAfter([Filename],[Line])


Filename: The filename of the file to use

Line: The data meant to be the next line


Return Value:

This command returns true if the line was inserted, or false if the filename, section, or current line does not exist.


The "InsertINILineBefore" Command

This command inserts a line BEFORE the "current line" in the iteration.  The "current line" is the last line that was returned by either EachINILine or NextINILine.

Syntax:

InsertINILineBefore([Filename],[Line])


Filename: The filename of the file to use

Line: The data meant to be the next line


Return Value:

This command returns true if the line was inserted, or false if the filename, section, or current line does not exist.


The "IsINISection" Command

This command checks if a particular section exists.

Syntax:

IsINISection([Filename],[Section])


Filename: The filename of the file to use

Section: The name of the section to check for


Return Value:

This command returns true if the section exists, or false if it does not exist.


The "LoadINI" Command

This command loads an Ini file into memory for use with the other Ini file manipulation commands.

Syntax:

LoadINI([Filename])


Filename: The filename of the file to use


Return Value:

This command returns true if the Ini file was successfully loaded, false if not.


The "NewINI" Command

This command creates an Ini file in memory for use with the other Ini file manipulation commands.  The file is not saved until the WriteINI command is used.

Syntax:

NewINI([Filename])


Filename: The filename to use


Return Value:

This command returns true if the new Ini file was successfully loaded, false if not.


The "NewINILine" Command

This command adds a new line to the end of a section.

Syntax:

NewINILine([Filename],[Section],[Line])


Filename: The filename of the file to use

Section: The name of the section to use

Line: The line to add to the end of that section


Return Value:

This command returns true if the operation was successful, otherwise false.


The "NewINISection" Command

This command adds a new section.

Syntax:

NewINISection([Filename],[Section])


Filename: The filename of the file to use

Section: The name to use for the new section


Return Value:

This command returns true if the operation was successful, otherwise false.


The "NextINILine" Command

This command continues "current line" iterator.  It retrieves the next line of a section, and allows usage of functions that manipulate the "current line" or do line insertion.

Syntax:

NextINILine([Filename],[Variable])


Filename: The filename of the file to use

Variable: The string variable to store the line read


Return Value:

This command returns true if the line was retrieved, or false if the filename, section, or line (i.e. the section has no more lines, or there is no current line) does not exist.


The "ReadINI" Command

This command reads a section of an Ini file.  Unlike the "LoadINI" command, this command immediately executes the section -- reading public variables and executing aliases.  Quick note, the setting names must be the exact name of a public variable when using ReadINI or RunINISection, or the variable will not be set.

Syntax:

ReadINI([Filename],[Section])


Filename: The filename of the file to use

Section: The name of the section to execute


Return Value:

This command returns true if the section was successfully read, false if not.


The "RemoveINISection" Command

This command deletes an entire section.

Syntax:

RemoveINISection([Filename],[Section])


Filename: The filename of the file to use

Section: The name of the section to remove


Return Value:

This command returns true if the section was deleted, or false if the section (or the file itself) did not exist.


The "RunINISection" Command

This command is similar to ReadINI -- it executes a section.  The difference is this works with loaded Ini files rather than opening the file and doing the reading itself.  For loaded Ini files, this is faster than using ReadINI (though if no other operations need to be done with the Ini file and it does not need to be used again, using ReadINI is more efficient).  Quick note, the setting names must be the exact name of a public variable when using ReadINI or RunINISection, or the variable will not be set.

Syntax:

RunINISection([Filename],[Section])


Filename: The filename of the file to use

Section: The name of the section to execute


Return Value:

This command returns true if the section was successfully executed, false if not.


The "SetCurINILine" Command

This command modifies the current line of a particular section.  The "current line" is the last line that was returned by either EachINILine or NextINILine.

Syntax:

SetCurINILine([Filename],[Line])


Filename: The filename of the file to use

Line: The data to replace the current line


Return Value:

This command returns true if the line was modified, or false if the line (or the file itself) did not exist.


The "UnloadINI" Command

This command unloads an  Ini file that has been loaded into memory for use with the other Ini file manipulation commands.

Syntax:

UnloadINI([Filename])


Filename: The filename of the file to use



The "WriteINI" Command

This command applies (saves, writes) changes to an Ini file loaded in memory.

Syntax:

WriteINI([Filename])


Filename: The filename of the file to use


Return Value:

This command returns true if the Ini file was successfully written, false if not.