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 Exselector 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.

Character set

Sword of Moonlight INI files should be Unicode. If they do not appear to be in one of the widely used Unicode encoding schemes, the file should be considered to be UTF-8 Unicode. ANSI dominates the home computing landscape. Unless you are writing purely Basic Latin text documents, you should be careful to save your files as Unicode.

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 #=.

#

The ; symbol is often used to disable a setting temporarily, or to recommend a setting in the file to the reader without actually enacting it for them. But instead it is recommended that you use # for that—it is placed at the front of a line, just like #;. Most text editors that highlight INI files will also understand # as an alternative way to write a "comment" (and so highlight it.)

Here the # is treated specially however. It is used to disable a setting as explained above. And so when a setting that is spread out across multiple lines is encountered, when using # it is correct to only use it on the first line. In fact each time it is encountered it is assumed that a new disabled comment is beginning. Visual editors such as SOM_EDIT will even pull these settings out and treat them not as comments, but disabled settings.

=

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 (which can also be the end of the file's text) is reached, and does not include the blank line itself.

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.

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. Refer to #=.

%%%

It is usually safe to write % when you mean %. But because of #% in theory this may not always be possible. In those situations write %%% instead.

Tip: it's easy to remember how %% and %%% work, since you just take what's in the middle of the outer %s and that's what you get.

Note: this setup does not allow environment variables to be unset once set. However the following pattern: VAR=%%%VAR%%% is functionally equivalent to unsetting the variable since it causes the variable to behave as if it was never set in the first place. Is this ever useful? Probably not. But for completeness sake it is what it is.

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.

External links

• A reference implementation[1][2] (refer to the ini and som sections)