ADR: Handling quotes around values

[lipkau]

PR#42 was merged and released in v3.0 as a breaking change, as it changed the behaviour of the parsing of the value.
The PR introduced the interpretations of quotation marks (['"]) around values.

It turns out, that this behaviour is controversial, as seen in issues #50, #49 and PR#77.

Summary

This Architectural Decision Record analyses the handling of quotation marks (['"]) around values in INI files of this module.
It documents the history and the desired behaviour.

The research conducted shows that handling of quotes varies significantly across languages and libraries:

• Some implementations strip quotes (e.g., Windows API, Node.js, PHP, Go).
• Others preserve quotes (e.g., Python, Perl, Ruby, C++).

Given the lack of a universal INI specification and the inconsistencies across implementations,
the decision has been made to not support the interpretation or stripping of quotation marks.
Instead:

• Quotes will be preserved as-is when reading and writing INI files.
• Users will have full control over how quotes are handled using PowerShell's built-in tools.
• Examples for adding and removing quotes will be provided in the ./Examples directory.

This approach prioritizes simplicity and user control, avoiding unnecessary complexity while aligning with PowerShell's flexibility.

Behavioural examples

before #42

"[test]`nnoQuotes=`$HOME/.file`nwithQuotes=`"`$HOME/.file`"" > poc.ini
(Import-Ini poc.ini)["test"]

Name                           Value
----                           ----- 
noQuotes                       $HOME/.file
withQuotes                     "$HOME/.file"

after #42

"[test]`nnoQuotes=`$HOME/.file`nwithQuotes=`"`$HOME/.file`"" > poc.ini
(Import-Ini poc.ini)["test"]

Name                           Value
----                           ----- 
noQuotes                       $HOME/.file
withQuotes                     $HOME/.file

Observations

Spec

The INI specification is poorly defined—there isn’t a universal standard.
Each implementation handles things differently, leading to inconsistencies.

How do others do it

The table below summarizes how various languages and libraries handle quotes around values in INI files:

Language/Library	Quotes Handling
Windows API: GetPrivateProfileString	Stripped 🗑️
Python: configparser	Untouched ✋
Node.js: ini npm package	Stripped 🗑️
Perl: Config::IniFiles	Untouched ✋
Ruby: iniparse	Untouched ✋
PHP: parse_ini_file	Stripped 🗑️
Go: gopkg.in/ini.v1	Stripped 🗑️
C/C++: ini.h	Untouched ✋

Research is documented in Appendix A

Legend

• 🗑️ Stripped: Quotes are removed from the values.
• ✋ Untouched: Quotes are preserved in the values.

Argumentation

The handling of quotes is inconsistent across different languages and libraries (as seen in Observations);
some strip quotes, while others preserve them.

Additionally, most implementations focus on reading and parsing INI files to load configurations into memory,
rather than manipulating the files themselves, as is our case.
Stripping quotation marks make the creation of a INI file unreasonably complex.

Decision

Although this module offers a lot of flexibility, it never be able to please everyone.

⚠️ Take the examples of other languages into account,
I have decided to not support the interpretation/stripping of quotation marks.

Powershell make it simple enough for the user to manipulate the value.
There shall be an example for adding and removing quotes in the ./Examples directory.

Appendix A: Testing other languages

The findings in this chapter use the following INI file as input:

[test]
key1=foo
key2 = "bar"
key3 = ""baz""
key4 =       meh
key5 ="       meh      "

[array]
key1=foo
key1="bar"
key1=""baz""
key2[]=lorem
key2[]="       ipsum      "

Windows API GetPrivateProfileString

Finding: quotes are stripped.

If the string associated with lpKeyName is enclosed in single or double quotation marks, the marks are discarded when the GetPrivateProfileString function retrieves the string.
source: https://learn.microsoft.com/en-us/windows/win32/api/winbase/nf-winbase-getprivateprofilestringw

Python: configparser

Finding: quotes are untouched.

Code

import configparser
import json

config = configparser.ConfigParser()
config.read("poc.ini")

config_dict = {section: dict(config.items(section)) for section in config.sections()}

config_json = json.dumps(config_dict, indent=4)
print(config_json)

{
   "test": {
       "key1": "foo",
       "key2": "\"bar\"",
       "key3": "\"\"baz\"\"",
       "key4": "meh",
       "key5": "\"       meh      \""
   }
   "array": is broken
}

Node (js): ini npm package

Finding: quotes are stripped.

Code

import * as fs from "fs";
import * as ini from "ini";

const configFile = "poc.ini";
const configData = fs.readFileSync(configFile, "utf-8");
const parsedConfig = ini.parse(configData);

console.log(JSON.stringify(parsedConfig, null, 2));

{
   "test": {
       "key1": "foo",
       "key2": "bar",
       "key3": "\"\"baz\"\"",
       "key4": "meh",
       "key5": "       meh      "
   },
   "array": {
       "key1": "\"\"baz\"\"",
       "key2": [
           "lorem",
           "       ipsum      "
       ]
   }
}

Perl: Config::IniFiles

Finding: quotes are untouched.

Code

use strict;
use warnings;
use Config::IniFiles;
use JSON;

my $ini = Config::IniFiles->new(-file => "poc.ini");

my %config_hash;
foreach my $section ($ini->Sections) {
    foreach my $key ($ini->Parameters($section)) {
        $config_hash{$section}{$key} = $ini->val($section, $key);
    }
}

my $config_json = to_json(\%config_hash, { pretty => 1 });
print $config_json;

{
   "test" : {
      "key1" : "foo",
      "key2" : "\"bar\"",
      "key3" : "\"\"baz\"\"",
      "key4" : "meh",
      "key5" : "\"       meh      \""
   },
   "array" : {
      "key1" : "foo\n\"bar\"\n\"\"baz\"\"",
      "key2[]" : "lorem\n\"       ipsum      \""
   }
}

Ruby: iniparse

Finding: quotes are untouched.

Code

require 'json'
require 'iniparse'

ini_content = IniParse.parse(File.read('poc.ini'))

config_hash = ini_content.to_h

config_json = JSON.pretty_generate(config_hash)
puts config_json

{
    "test": {
        "key1": "foo",
        "key2": "\"bar\"",
        "key3": "\"\"baz\"\"",
        "key4": "meh",
        "key5": "\"       meh      \""
    },
    "array": {
        "key1": "\"\"baz\"\"",
        "key2[]": "\"       ipsum      \""
    }
}

PHP: parse_ini_file

Finding: quotes are stripped.

Code

<?php
$iniArray = parse_ini_file("poc.ini", true, INI_SCANNER_RAW);

$configJson = json_encode($iniArray, JSON_PRETTY_PRINT);

echo $configJson;

{
    "test": {
        "key1": "foo",
        "key2": "bar",
        "key3": "\"baz\"",
        "key4": "meh",
        "key5": "       meh      "
    },
    "array": {
        "key1": "\"baz\"",
        "key2": [
            "lorem",
            "       ipsum      "
        ]
    }
}

Go: gopkg.in/ini.v1

Finding: quotes are stripped.

Code

package main

import (
    "encoding/json"
    "fmt"
    "log"

    "gopkg.in/ini.v1"
)

func main() {
    cfg, err := ini.Load("poc.ini")
    if (err != nil) {
        log.Fatalf("Failed to read INI file: %v", err)
    }

    configMap := make(map[string]map[string]string)
    for _, section := range cfg.Sections() {
        sectionMap := make(map[string]string)
        for _, key := range section.Keys() {
            sectionMap[key.Name()] = key.Value()
        }
        configMap[section.Name()] = sectionMap
    }

    configJSON, err := json.MarshalIndent(configMap, "", "    ")
    if (err != nil) {
        log.Fatalf("Failed to convert to JSON: %v", err)
    }

    fmt.Println(string(configJSON))
}

{
    "DEFAULT": {},
    "array": {
        "key1": "\"\"baz\"\"",
        "key2[]": "       ipsum      "
    },
    "test": {
        "key1": "foo",
        "key2": "bar",
        "key3": "\"\"baz\"\"",
        "key4": "meh",
        "key5": "       meh      "
    }
}

C++: ini.h

Finding: quotes are untouched.

Code

#include <iostream>
#include <fstream>
#include <string>
#include <map>
#include <json/json.h>
#include <ini.h>

int handler(void* user, const char* section, const char* name, const char* value) {
    auto* root = static_cast<Json::Value*>(user);

    if (!(*root).isMember(section)) {
        (*root)[section] = Json::Value(Json::objectValue);
    }

    (*root)[section][name] = value ? value : "";
    return 1;
}

int main() {
    Json::Value root(Json::objectValue);

    if (ini_parse("poc.ini", handler, &root) < 0) {
        std::cerr << "Error: Cannot read INI file." << std::endl;
        return 1;
    }

    Json::StreamWriterBuilder writer;
    writer["indentation"] = "    "; // Pretty print with 4 spaces
    std::string json_str = Json::writeString(writer, root);
    std::cout << json_str << std::endl;

    return 0;
}

{
    "array" :
    {
        "key1" : "\"\"baz\"\"",
        "key2[]" : "\"       ipsum      \""
    },
    "test" :
    {
        "key1" : "foo",
        "key2" : "\"bar\"",
        "key3" : "\"\"baz\"\"",
        "key4" : "meh",
        "key5" : "\"       meh      \""
    }
}

[3guboff]

Hi @lipkau! First of all, thank you for your work! You're great!

1. Can you please say when you will do a new version that will preserve quotes around values?
2. Mb you know a workaround for keeping quotes with the 3.1.3 version?

[lipkau]

Hello @3guboff .

I will not release this change in v3.*, as it is a breaking change.
I have just merged the change to master in PR #100. So you can use the code from the repo (without the Powershell Gallery) for now.

Unfortunately, I can't say when I will release v4, as there are a couple more things which I want to get done before I release it.
And as I don't have as much free time as I would like, I can't predict when I will be done with it.

[3guboff]

Got it, thanks for your efforts and good luck in the next episode!