Racket

INI File Parser and Writer🔗ℹ

This module provides simple facilities for reading and writing INI-style configuration files. It supports strings, numbers, booleans, paths, and serializable Racket values, and allows the parsed configuration to be queried and modified.

1 Creating and Parsing INI Files🔗ℹ

procedure
(make-ini) → is-ini?

Creates a new, empty INI value. The representation of an INI value is private; use is-ini? to recognize it and the procedures in this module to inspect or modify it.

procedure
(file->ini file) → is-ini?
file : (or/c path-string? symbol?)

Reads an INI file from disk and returns an INI value. If the file does not exist, an empty INI value is returned. If file is a symbol, the path consists of the user’s preferences directory and the symbol’s name with an ".ini" suffix.

The parser supports:

Sections (e.g., [section-name])
Key-value pairs (e.g., key=value)
Comments (lines starting with ;)
Empty lines

An unrecognized non-empty line raises an exception that includes its line number and contents.

The keys are stored as symbols, and values are automatically interpreted as:

Numbers, if the value matches a number pattern
Booleans, if the value is #t, true, #f, or false (case-insensitive)
Paths written with the PATH: prefix
Explicit Racket-readable strings written with the VALUE: prefix, including strings containing newlines
Serializable Racket values written with the SER: prefix
Otherwise, as strings

procedure
(ini->file ini file [#:private? private?]) → void?
  ini : is-ini?
  file : path-string?
  private? : boolean? = #f

Writes an INI structure (as produced by file->ini or make-ini) to the specified file. Missing parent directories are created automatically. If private? is #t, Unix-like systems restrict the file to mode 0600 before the INI contents are written.

The output preserves:

Section headers
Key-value pairs
Comments (prefixed with ;)
Empty lines

Strings, paths, numbers, and booleans have dedicated encodings. Other values are written using serialize and must therefore be serializable.

procedure
(get-ini-file file) → path?
file : (or/c path-string? symbol?)

Resolves the file argument used by the API. A symbol is resolved in the user’s preferences directory and receives an ".ini" suffix; a path string is converted to a path without otherwise changing its location.

procedure
(is-ini? value) → boolean?
value : any/c

Returns #t when value is an INI value created by make-ini or file->ini, and #f otherwise.

2 Accessing and Modifying Values🔗ℹ

procedure
(ini-get ini section key def-val) → any/c
  ini : is-ini?
  section : (or/c symbol? string?)
  key : (or/c symbol? string?)
  def-val : any/c

Retrieves the value associated with the given key in the specified section. Section and key matching is case-insensitive. If the key is not found, returns def-val.

procedure
(ini-set! ini section key val) → is-ini?
  ini : is-ini?
  section : (or/c symbol? string?)
  key : (or/c symbol? string?)
  val : any/c

Sets the value of key in the specified section of the INI structure. If the section or key does not exist, it is created. Returns the modified INI structure.

3 Inspecting and Iterating over INI Values🔗ℹ

procedure
(ini-sections ini) → (listof symbol?)
ini : is-ini?

Returns the named sections in source order. Key-value pairs before the first section header belong to the internal top-level section and are not included in this result.

procedure
(ini-keys ini section) → (listof symbol?)
ini : is-ini?
section : symbol?

Returns the keys in section in source order. If the section does not exist, returns the empty list. Use 'nil to retrieve keys that occur before the first section header.

procedure
(ini-for-each proc ini) → void?
proc : procedure?
ini : is-ini?

Calls proc with three arguments—the section, key, and value—for every key-value pair, in source order. Key-value pairs before the first section header use 'nil as their section.

Examples:

> (define settings (make-ini))
> (ini-set! settings 'server 'port 8080)
#<ini-cfg>
> (ini-set! settings 'server 'tls #t)
#<ini-cfg>
> (ini-sections settings)
'(server)
> (ini-keys settings 'server)
'(port tls)
> (ini-for-each
   (lambda (section key value)
     (printf "~a.~a = ~v~n" section key value))
   settings)
server.port = 8080
server.tls = #t

4 The ini% Racket Class🔗ℹ

(require simple-ini/class)

package: simple-ini

Require this module for the OO implementation of this Simple INI implementation

class
ini% : class?

superclass: object%

An OO wrapper around the ini functions.

constructor
(new ini%
    [ [file file]
    [fail fail]
    [private? private?]]) → (is-a?/c ini%)
  file : (or/c symbol? string? path? boolean?) = #f
  fail : (or/c boolean?) = #f
  private? : (or/c boolean?) = #f
Creates the ini from the given file. * If (eq? file #f), an empty ini will be made. * if (symbol? file), an ini will be made or read in the users preferences folder with the given (format "~a.ini" file) as name. * Otherwise, the file will be made or read at the given location.
The fail flag determines if methods of the class will fail when some value in the ini file is written while there is no file to write to or if some non existing key is read.
method
(send an-ini get-file) → (or/c path? #f)
Gets the current ini file. See constructor for more information.
method
(send an-ini set-file! file) → this
  file : (or/c symbol? string? path?)
Sets the ini file to be used. See constructor for more information.
method
(send an-ini get-fail) → boolean?
Gets the value of the ’fail’ flag. See constructor for more information.
method
(send an-ini set-fail! fail) → this
  fail : boolean?
Sets the value of the ’fail’ flag. See constructor for more information.
method
(send an-ini get-private?) → boolean?
Returns whether private file permissions are enabled.
method
(send an-ini set-private! private?) → this
  private? : boolean?
Enables or disables private file permissions for subsequent writes.
method
(send an-ini sections) → (listof symbol?)
Returns the named sections in source order, as with ini-sections.
method
(send an-ini keys section) → (listof symbol?)
  section : symbol?
Returns the keys in section, as with ini-keys.
method
(send an-ini for-each proc) → void?
  proc : procedure?
Calls proc with the section, key, and value of each key-value pair, as with ini-for-each.
method
(send an-ini reload) → this
Reloads the ini file in memory, or empties the ini structure (eq? file #f).
method
(send an-ini set! section key value) → this
  section : (or/c symbol? string?)
  key : (or/c symbol? string?)
  value : any/c
Sets the value of the key in the given section. After the set! operation, the ini structure will be written to file. Note. Although ini files can be read from standard .ini formats, the simple-ini format will be enhanced. It wil store values in racket format, so that ’read’ can be used to read in the racket value.
method
(send an-ini get section key default-value) → any/c
  section : (or/c symbol? string?)
  key : (or/c symbol? string?)
  default-value : any/c
(send an-ini get section key) → any/c
  section : (or/c symbol? string?)
  key : (or/c symbol? string?)
Returns the value for the given section and key combination. If this combination does not exist in the ini structure, it will return the default-value. However, if default-value is not given, it will return #f.

; end class

5 The ini Roos Class🔗ℹ

(require simple-ini/roos)

package: simple-ini

Require this module for the OO implementation of this Simple INI implementation in the ROOS OO framework

Provides a Roos class that gives object-oriented access to INI files using the underlying file->ini parser system. The class offers methods to load, query, and update INI files using familiar object-style interactions.

procedure
(%-! ini or/c) → roos-object*
ini : roos-class*
or/c : path-string?

Creates an ini object. If a file path is provided and the file exists, it is loaded immediately. Otherwise, an empty INI structure is created.

If no file is provided, the object operates in-memory only. Subsequent set! operations will raise an error unless a file is later specified with (file!).

procedure
(file) → (or/c path-string? #f)

Returns the current filename associated with this INI object.

procedure
(file! f) → void?
f : path-string?

Sets the file to use as backing storage for the INI structure. Triggers a reload from disk.

procedure
(fail) → boolean?

Returns if an error will be thrown when a set! is done and no file has been set to write the contents to

procedure
(fail! yn) → boolean?
yn : boolean?

Sets fail to the given value.

procedure
(reload) → void?

Reloads the INI content from disk, using the current file path. If the file does not exist, the content is reset to an empty INI structure.

procedure
(sections) → (listof symbol?)

Returns the named sections in source order, as with ini-sections.

procedure
(keys section) → (listof symbol?)
section : symbol?

Returns the keys in section, as with ini-keys.

procedure
(for-each proc) → void?
proc : procedure?

Calls proc with the section, key, and value of each key-value pair, as with ini-for-each.

procedure
(set! section key val) → ini
  section : (or/c symbol? string?)
  key : (or/c symbol? string?)
  val : any/c

Sets the value in the INI structure for the given section and key to val.

If a file is associated with the object, the structure is saved to disk immediately. If no file is set and fail is enabled, an error is raised. Returns the INI object itself.

procedure
(get section key def-val ...) → any/c
  section : (or/c symbol? string?)
  key : (or/c symbol? string?)
  def-val : any/c

Retrieves the value associated with the given section and key.

If not found:

Returns #f if no default is given and fail is disabled
Returns def-val if one is provided
Raises an error if fail is enabled and no default is given

1	Creating and Parsing INI Files
2	Accessing and Modifying Values
3	Inspecting and Iterating over INI Values
4	The ini% Racket Class
5	The ini Roos Class