Re: Final SRFI 233: INI files

John Cowan Wed, 26 Oct 2022 13:28:47 -0700

Here's the corrected SRFI document,  I have shortened the input and output
documents.


On Sat, Oct 22, 2022 at 11:30 PM Arthur A. Gleckler <[email protected]>
wrote:

> On Tue, Oct 18, 2022 at 12:50 PM Arthur A. Gleckler <[email protected]>
> wrote:
>
>
>> John and Arvydas, when I ran that code, I discovered that the sample
>> implementation returns symbols for section names and key names.  However,
>> the text of the SRFI still says that it returns strings.  John decided
>> <https://srfi-email.schemers.org/srfi-233/msg/20885314/> that section
>> names and values would be strings, so the implementation and the text
>> should be updated in that regard.
>>
>> Would you please send me a pull request for that?
>>
>> Also, I am considering shortening the example:
>>
>> (let* ((port (open-input-file "/tmp/example.ini"))
>>        (generator (make-ini-file-generator port)))
>>       (stream->list (generator->stream generator)))  ; Uses SRFIs 41 and
>> 221.
>>
>> Would that be reasonable?
>>
>
>  Hi, John and Arvydas.  This SRFI was finalized with bugs in the document
> that got past us all.  (See above.)  Would you please send me a full
> request with the fixes as soon as possible?
>

Title: SRFI 233: INI files

233: INI files

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

Status

Abstract

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.

Received: 2022-08-03
60-day deadline: 2022-10-09
Draft #1 published: 2022-08-10
Draft #2 published: 2022-09-26
John Cowan's personal Git repo for this SRFI for reference while the SRFI is in draft status (preview)

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 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 the empty string. Whitespace immediately before or after the = is ignored. If there is more than one key-value separator, alll 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 the empty string.

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 are 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")
(features remove "wcadotnet,webapplicationcontainer")
(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

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