233: INI files233: INI filesby John Cowan (text), Arvydas Silanskas (code)
This SRFI is currently in final status. Here is an explanation of each status that a SRFI can hold. To provide input on this SRFI, please send email to srfi-233@nospamsrfi.schemers.org. To subscribe to the list, follow these instructions. You can access previous messages via the mailing list archive.
#f for the section before the first
section name has been read, and for keys not delimited from
values. This was agreed upon during the discussion before
finalization, but the authors and editor somehow missed
making the necessary changes. In the process of fixing
this, the example was simplified slightly.)An INI file is a configuration file that consists of key-value
pairs for properties, and sections that group the properties. The
name of these configuration files comes from the filename extension
INI, short for initialization.
The format has become an informal standard in many contexts of configuration.
This SRFI provides access to the contents of an INI file.
Although INI files have been declared obsolete on several different occasions, their simplicity has kept them in use in many environments. Although the format is not well specified, it is also quite forgiving; it can readily be edited by hand, which is both an advantage and a disadvantage. This library does not impose any rules beyond the simplest ones: for example, there are a variety of conventions for nested sections in the wild, but it is up to users of the library to interpret a specific convention. Similarly, there is no enforcement of the convention that all keys within a section must be unique, or of case-sensitivity or insensitivity. Rather, the library attempts to extract as much information as possible from INI files that may be quite unconventionally formatted.
An INI file is a simple line-based configuration format. There are many variations; this SRFI provides support for at least the following:
Comments begin with ; and are removed from lines.
The comment delimiter can be overridden.
Blank lines and leading and trailing whitespace are ignored. For the purposes of this SRFI, "whitespace" means any sequence of spaces and/or tabs.
The beginning of a section is marked by a line beginning with [ and ending with ].
Sections do not nest. The name of a section is the characters between the brackets.
Other lines containing = are treated as key-value pairs within the current section or, if
they precede any section line, as key-value pairs belonging to a section
whose name is #f.
Whitespace immediately before or after the = is ignored.
If there is more than one key-value separator, all but the first are considered part of the value.
The key-value separator can be overridden.
Any other lines are treated as keys whose value is #f.
The following two procedures are provided:
(make-ini-file-generator inport [ key-value-sep [ comment-delim ] ])
Returns a generator that reads one or more lines from
the textual input port inport and returns a list of two symbols and a string:
the current section name, the key, and the value. If no section names have been read, the
section name is #f. When the port returns an end-of-file object,
the generator returns an end-of-file object.
It is an error to mutate any of the strings and lists returned.
The character key-value-sep, which defaults to #\=, specifies the separator
between a key and the corresponding value. The character comment-delim, which defaults
to #\;, specifies the delimiter before a comment.
It is an error if either of them is whitespace or a newline.
Note that it is the user's responsibility to close the port.
(make-ini-file-accumulator outport [ value-delim [ comment-delim ] ])
Returns an accumulator that writes to the textual output port outport.
If the argument passed to the accumulator is a list of three elements, a key-value line, preceded if necessary by a section line, is written.
If the argument is a single string, it is prefixed by the comment delimiter and a single space and written out.
In either case, the accumulator returns an unspecified value. It is an error if any of these strings contains a newline. If the argument is an end-of-file object, the end-of-file object is returned. It is an error to call the accumulator after that.
Note that it is the user's responsibility to close the port.
The key-value-sep and comment-delim are treated the same as in make-ini-file-generator.
The following is an example of an INI file:
; Be sure to update the following line last_modified_date=2022-08-10 [other] quiet=/qa [install] allusers=true applicationusers=allusers clientauditingport=6420 databasedb=boe120 enablelogfile=true install.lp.fr.selected=true installswitch=server nsport=6400 website_metabase_number=true [features] remove=wcadotnet,webapplicationcontainer
Calling make-ini-file-generator on
a character input stream containing this example will
return a generator which generates the following lists:
(#f last_modified_date 2022-08-10) (other quiet "/qa") (install allusers "true") (install applicationusers "allusers") (install clientauditingport "6420") (install databasedb "boe120") (install enablelogfile "true") (install install.lp.fr.selected "true") (install installswitch "server") (install nsport "6400") (install website_metabase_number "true") (features remove "wcadotnet,webapplicationcontainer")
The sample implementation is in the SRFI 233 repository.
Thanks to the participants on the SRFI 233 mailing list.
© 2022 John Cowan, Arvydas Silanskas.
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice (including the next paragraph) shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.