INI file

From Wiki

Jump to: navigation, search
 
(9 intermediate revisions by 2 users not shown)
Line 3: Line 3:
 
All [[Wikipedia:INI file|INI file]]s 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:
 
All [[Wikipedia:INI file|INI file]]s 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]
+
  [config]
 
  device=2
 
  device=2
 
  width=640
 
  width=640
Line 10: Line 10:
 
  analogMode=-2
 
  analogMode=-2
  
In addition to game settings, [[SOM file]]s work just like INI files, and the [[SomEx]] project and [[Excellector]] use INI files to to configure extensions.
+
In addition to game settings, [[SOM file]]s work just like INI files, and the [[SomEx]] project and [[Exselector]] use INI files to to configure extensions.
  
 
==Modern Sword of Moonlight INI specification==
 
==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 [[Wikipedia:API|API]]s provided by the [[Wikipedia:Microsoft Windows|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.
 
There is a lot of diversity in the wide world of INI files. Originally Sword of Moonlight used the INI file reading and writing [[Wikipedia:API|API]]s provided by the [[Wikipedia:Microsoft Windows|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 [[Wikipedia:Unicode|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)===
 
===Meta characters (including nonstandard uses)===
Line 25: Line 28:
 
====;====
 
====;====
 
A line beginning with ; is commentary. Within a multiple line assignment commentary should glue the lines together. Refer to [[#=]].
 
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.
  
 
==== = ====
 
==== = ====
Line 35: Line 43:
 
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 [[#%%]].
 
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 [[#^=]].
+
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.
 
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 [[#%%%]].
  
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 [[Wikipedia:MS-DOS|MS-DOS]] because Sword of Moonlight originated on the [[Wikipedia:Windows|Windows]] operating system. If expansion does not occur then nothing changes, the % and other % and everything in between remains in place.
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 case sensitive match for the name of an environment variable, the leading % and trailing % and everything in between is substituted for the value the was previously assigned to the environment variable. This substitution is called environment variable expansion.  
 
  
The use of % delimiters for expansion is adopted from [[Wikipedia:MS-DOS|MS-DOS]] because Sword of Moonlight originated on the [[Wikipedia:Windows|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.
  
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 [[#=]].
+
%% 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 [[#=]].
  
==== ^= and ^% escape sequences====
+
====%%%====
{{anchor|^=|^%}}
+
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.  
Because [[#=]] and [[#%]] have special meaning, it is not always possible to write them without unwelcome side effects. Like [[#%]] the ^ escape character is borrowed from [[Wikipedia:MS-DOS|MS-DOS]] of [[Wikipedia:Windows|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: 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.'''''
  
''''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.'''''
+
''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===
 
===Processing and preprocessing===
Line 68: Line 75:
 
''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.''
 
''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[http://svn.swordofmoonlight.net/lib/swordofmoonlight.h][http://svn.swordofmoonlight.net/lib/Swordofmoonlight.cpp] (refer to the ini and som sections)
 
[[Category:Sword of Moonlight]]
 
[[Category:Sword of Moonlight]]

Latest revision as of 16:01, 29 July 2014

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[edit]

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[edit]

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)[edit]

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

[][edit]

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.

;[edit]

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

#[edit]

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.

=[edit]

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

%[edit]

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.

%%[edit]

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

%%%[edit]

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[edit]

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[edit]

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