## Title

INI files

## Author

John Cowan (text), Arvydas Silanskas (code)

## Status

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.

- Received: 2022-08-03
- Draft #1 published: 2022-08-10
- Draft #2 published: 2022-09-26
- Draft #3 published: 2022-10-04
- Finalized: 2022-10-13
- Revised to fix errata:
  - 2022-10-28 (Use symbols, not strings, for sections and keys, and `#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.)

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

## Rationale

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.

## Specification

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

## 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
    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")

## Implementation

The sample implementation is in the SRFI 233 repository.

## Acknowledgements

Thanks to the participants on the SRFI 233 mailing list.

## Copyright

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