INI file

INI files are used to configure software. Sword of Moonlight uses INI files to track in game optional settings.

All INI files share a few things in common. Sections headings enclosed in square brackets, settings that are assigned values using an equal sign, and commentary identified by lines beginning with a semicolon:

[Config]
device=2
width=640
height=480
;dual analog with inverted look
analogMode=-2

In addition to game settings, SOM files work just like INI files, and the SomEx project and Excellector use INI files to to configure extensions.

Modern Sword of Moonlight INI specification

There is a lot of diversity in the wide world of INI files. Originally Sword of Moonlight used the INI file reading and writing APIs provided by the Microsoft Windows operating system, as they were sufficient for setting up very basic in game settings. Modern day extended Sword of Moonlight requires added and more consistent functionality in addition to a cross-platform implementation.

Meta characters (including nonstandard uses)

The code points and sequences gathered here have been attributed special meaning within particular contexts.

[]

A line beginning with [ and ending with ] after trimming any following spacing is interpreted as a section heading. Lines that follow up and to the next section heading or the end of the INI file are attributed meaning according to the name of the section.

The initial section is []. This is implicit. Sections should be reentrant. The contents of the brackets are taken to be the name of the current section. The contents should not be trimmed.

;

A line beginning with ; is commentary. Within a multiple line assignment commentary should glue the lines together. Refer to #=.

=

A line should not begin with =. If it were it would assign to #%% which is not permitted. Note that users may actually be tempted to try this because %% would be the shortest variable name possible, so most convenient to pepper throughout a file.

The first = on a line begins an assignment to a setting. The setting may be a configurable option, an extension, or an environment variable, depending on the context. Typically all settings in the SOM file are environment variables. All settings in the file indicated by the SOM file#INI variable are configurable options, and all settings in the file(s) indicated by the SOM file#EX variable are extensions.

The content to the left of the = make up the name of the setting. The content to the right, including the lines below in a multiple line assignment, is the value being assigned to the setting. Spacing in the name is trimmed. For environment variables this can include internal spacing since environment variables should not include punctuation. Spacing on the front and back of the assignment value is also trimmed.

Trimming in this context means that it is acceptable to have spacing, but that it will be removed from the assignment, or in other words is purely cosmetic. Refer to #%%.

If everything to the right of the = up to the end of the line is spacing, then the assignment is understood to be a multiple line assignment. The value to be assigned does not begin until the next line down, and ends when a blank line is reached, not including the blank line itself, or when the end of the file is reached, or when a new line including an = is reached, whichever comes first. Refer to #^=.

The first used line of a multiple line assignment should not be trimmed. It is understood that the block of text begins flush to the margin. The end of the final line however should be trimmed.

There is a slight ambiguity between the beginning of the multiple line assignment and an assignment that assigns a value of nothing, or in other words, all spacing, destined to be trimmed. To explicitly write a single line assignment to nothing, assign to #%%. However there is no harm in not writing %% as the first line in the multiple line assignment will still amount to nothing.

Lastly, it is not possible to remove, or unset, environment variable settings once set. However for purposes of expansion, it is possible to assign the variable such that it will behave as an unassigned variable otherwise would. Refer to #^%.

%

All content to the right of #= in an assignment is subject to expansion. Wherever % appears the content to the right is considered for expansion. Where and if another % appears, everything between the two % is a candidate for expansion. If the content is a match for the name of an environment variable, the leading % and trailing % and everything in between is replaced with the current value of the environment variable. This replacement or substitution is sometimes called environment variable expansion.

The use of % delimiters for expansion is borrowed from MS-DOS because Sword of Moonlight originated on the Windows operating system. If expansion does not occur then nothing changes, the % and other % and everything in between remains in place.

Environment variables are usually supplied by the SOM file, however there are built in environment variables on any system, including variables that users or programs may have setup for themselves. In addition to this a few environment variables are guaranteed to be predefined before the first line of the SOM file. The SOM file is first INI-like file in play. INI files that follow can expand environment variables but are unlikely to be in a position to assign to them.

Note: that officially all settings and environment variables are case-sensitive, however some systems may not be. To avoid problems always use the recommended names be they lowercase, uppercase, capitalized, or otherwise. And just on an aside, the same goes for computer file names.

%%

%% is a built in environment variable which should not be alterable. It should always expand to nothing. Refer to #%. It can be used to prevent trimming of spacing and write assignments to nothing more clearly. Refer to #=.

^= and ^% escape sequences

Because #= and #% have special meaning, it is not always possible to write them without unwelcome side effects. Like #% the ^ escape character is borrowed from MS-DOS of Windows on which Sword of Moonlight originated. However unlike MS-DOS the utility of ^ is limited to two basic cases: ^= which is replaced with = and ^% which is replaced with %.

Note that writing ^ produces ^ in any other combination; as does writing = and % where side effects would not otherwise occur. Further note that it is not necessarily always best practice to write ^= and ^%. Although it is best practice to keep them in mind and apply them wherever safety could predictably be an issue. Generally speaking, in multiple line assignments ^= should always be written so not to terminate the assignment prematurely. ^% should be used anywhere that a pair of % might be interpreted as an environment variable.

Tip: environment variables cannot be unset once set. However the following pattern: VAR=^%VAR^% is functionally equivalent to unsetting the variable because it causes the variable to behave as if it was never set in the first place. Note that while this is a "tip" it may very well be that there is no good reason to do so with respect to Sword of Moonlight.

Processing and preprocessing

The INI file should be read top to bottom omitting no duplicates. In general it is not necessary to flag a setting or section as a duplicate, as any duplicate settings should overwrite previously established settings, again from top to bottom, and any duplicate sections should simply determine the application of the settings therein.

Preprocessors, or readers, should strip out or separate commentary, expand existing environment variables, and trim spaces from the sides of equal signs and the end of lines, or in the case of assignments that span more than one line, trim spaces from the end of the last line.

Note: that trimming should be done prior to environment variable expansion so that the information content of the variables themselves is not inadvertently trimmed away.