233: INI files

by John Cowan (text), Arvydas Silanskas (code)

Status

This SRFI is currently in draft 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.

Abstract

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.

Issues

None at present.

Rationale

Although INI files have been declared obsolete on several different occasions, their simplicity has kept them in use in many different 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.

Specification

An INI file is a simple line-based configuration format. There are many variations; this SRFI requires support for at least the following:

(make-ini-file-generator inport)

Returns a generator that reads one or more lines from inport and returns a list of three strings: the current section name, the key, and the value. If no section names have been read, the section name is the empty string. When the port returns an end of file object, it is closed and the generator returns an end of file object.

(make-ini-file-accumulator outport)

Returns an accumulator that writes to outport. If the argument passed to the accumulator is a list of three strings, a key-value line, preceded if necessary by a section line, is written. If the argument is a single string, it is prefixed by "; " and written out. In either case, the accumulator returns an unspecified value. If the argument is an end-of-file object, outport is closed and the end-of-file object is returned.

Example

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
as_admin_username=admin
as_instance=localhost
applicationusers=allusers
cadnode=businessabcdef
cadport=6410
clientauditingport=6420
clientlanguage=en
clustercms=false
databasedb=boe120
databasepwd_sqlanywhereroot=password1
databaseserver_audit=localhost
enablelogfile=true
enableservers=true
install.lp.en.selected=true
install.lp.fr.selected=true
installdbtype=sql
installmode=new
installswitch=server
install_db_type=sqlanywhere
mysqlport=3306
nsport=6400
privileged=true
username=business objects
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:

("" "last_modified_date", "2022-08-10")
("other" "quiet" "/qa")
("install" "allusers" "true")
("install" "as_admin_username" "admin")
("install" "as_instance" "localhost")
("install" "applicationusers" "allusers")
("install" "cadnode" "businessabcdef")
("install" "cadport" "6410")
("install" "clientauditingport" "6420")
("install" "clientlanguage" "en")
("install" "clustercms" "false")
("install" "databasedb" "boe120")
("install" "databasepwd_sqlanywhereroot" "password1")
("install" "databaseserver_audit" "localhost")
("install" "enablelogfile" "true")
("install" "enableservers" "true")
("install" "install.lp.en.selected" "true")
("install" "install.lp.fr.selected" "true")
("install" "installdbtype" "sql")
("install" "installmode" "new")
("install" "installswitch" "server")
("install" "install_db_type" "sqlanywhere")
("install" "mysqlport" "3306")
("install" "nsport" "6400")
("install" "privileged" "true")
("install" "username" "business objects")
("install" "website_metabase_number" "true")
("features" "remove" "wcadotnet,webapplicationcontainer")

Implementation

The sample implementation is in the SRFI 233 repository.

Acknowledgements

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.


Editor: Arthur A. Gleckler