From f5701f5459a1e91fb7f2216689f59fa976f783fd Mon Sep 17 00:00:00 2001 From: "Viral B. Shah" Date: Sat, 14 Nov 2026 12:20:38 -0500 Subject: [PATCH 1/2] Make multi-line values opt-in, add merged, define repeated keys multiline_values is a new Inifile option, false by default. When it is off, every line stands on its own and leading whitespace is ignored, as in IniFile 0.5, so indentation no longer changes the meaning of a file by default. write throws an ArgumentError naming the key and section for a value that contains a newline, since it could not be read back. The check runs before anything is written, so write(filename, ini) does not empty an existing file. Display does not throw. merged(ini) returns an OrderedDict{String,String} with the defaults and then each section's keys, in section order, where a later section overrides an earlier one. Sections are ordered by their first header, and a repeated header adds to the earlier section, as in Python 2's ConfigParser. Repeated keys and sections are now documented and tested: within a section the last value wins and the key keeps its first position, and a repeated section header adds to the earlier section. They are never an error, with or without strict. Co-Authored-By: Claude Opus 5.5 --- README.md | 97 +++++++++++++++++++++----- src/IniFile.jl | 162 ++++++++++++++++++++++++++++++++++++------- test/runtests.jl | 175 +++++++++++++++++++++++++++++++++++++++++++++-- 3 files changed, 384 insertions(+), 50 deletions(-) diff --git a/README.md b/README.md index 7a589d9..b51e81f 100644 --- a/README.md +++ b/README.md @@ -31,10 +31,8 @@ host = example.org port = 8080 debug = off -[paths] -search = - /usr/lib - /opt/lib +[logging] +level = info ``` ```julia @@ -51,10 +49,10 @@ get_int(ini, "server", "port") # 8080 get_bool(ini, "server", "debug") # false get_float(ini, "server", "timeout", 30.0) # 30.0 -split(strip(get(ini, "paths", "search")), '\n') # ["/usr/lib", "/opt/lib"] +merged(ini)["level"] # "info": all keys in one dictionary set(ini, "server", "port", 9090) -set(ini, "logging", "level", "debug") # creates the section +set(ini, "cache", "size", 100) # creates the section write("settings.ini", ini) ``` @@ -77,7 +75,8 @@ Options of `Inifile(...)` and `read(Inifile, ...)`: | --- | --- | --- | | `lowercase_keys` | `false` | Store and look up keys in lowercase, so `Key` and `key` are the same key, as Python's `configparser` does by default. Section names stay case-sensitive. | | `inline_comment_prefixes` | `()` | Prefixes such as `(";", "#")` that start a comment in the middle of a line, when they follow whitespace. Off by default, as in Python 3. | -| `strict` | `false` | Throw an `ArgumentError` for a malformed line instead of logging a warning and skipping it. | +| `multiline_values` | `false` | Allow values that span several lines, written as indented continuation lines (see [Multi-line values](#multi-line-values)). | +| `strict` | `false` | Throw an `ArgumentError` for a malformed line instead of logging a warning and skipping it. Repeated keys and sections are allowed either way. | ### Querying @@ -95,6 +94,7 @@ sections(ini) # OrderedDict of section name => OrderedDict of key => v section(ini, "section") # OrderedDict of key => value defaults(ini) # keys that appear before the first section header get(ini, "key") # a key in the defaults, or nothing +merged(ini) # OrderedDict of all keys: the defaults, then each section ``` A lookup in a section falls back to the defaults when the section does not have @@ -103,6 +103,30 @@ is given, and an `ArgumentError` naming the section, key and value when the valu cannot be parsed. In particular `get_bool` rejects values such as `Ture` instead of reading them as `false`. +### All keys in one dictionary + +`merged(ini)` returns a new `OrderedDict{String,String}` with the defaults and +then the keys of each section, in section order. A key in a later section +overrides the same key in the defaults or in an earlier section. This suits +programs that treat sections only as a way to group options: + +```ini +solver = cg+amg + +[Options for advanced mode] +solver = cholmod +mask_file = none + +[Output options] +write_cur_maps = True +``` + +```julia +opts = merged(read(Inifile, "job.ini")) +opts["solver"] # "cholmod" +collect(keys(opts)) # ["solver", "mask_file", "write_cur_maps"] +``` + ### Modifying and writing ```julia @@ -113,9 +137,11 @@ set(ini, "key", value) # set a key in the defaults write("file.ini", ini) # or write(io, ini) ``` -`write` keeps the order of sections and keys, writes `key = value`, puts a blank -line between sections, and writes multi-line values as indented continuation -lines. Comments in the original file are not kept. +`write` keeps the order of sections and keys, writes `key = value`, and puts a +blank line between sections. Comments in the original file are not kept. A value +that contains newlines can only be written with `multiline_values=true`; +otherwise `write` throws an `ArgumentError` before writing anything, because the +value could not be read back. ## File format @@ -131,26 +157,63 @@ key = value # The first `=` or `:` on a line separates the key and the value other_key: value empty = -# Lines indented further than the entry continue its value -long value = first line - second line ``` - Blank lines and lines starting with `#` or `;` are ignored. -- Whitespace around keys and values is removed. -- Continuation lines are joined with `"\n"`. +- Whitespace around keys and values is removed, including indentation. - Inline comments, as in `key = value ; note`, are only removed when enabled with `inline_comment_prefixes`; otherwise they are part of the value. - Malformed lines are skipped with a warning that gives the line number. +### Multi-line values + +With `multiline_values=true`, a line indented more than the line that started an +entry continues that entry's value, as in Python's `configparser`: + +```ini +[paths] +search = + /usr/lib + /opt/lib +``` + +```julia +ini = read(Inifile, "paths.ini"; multiline_values=true) +split(strip(get(ini, "paths", "search")), '\n') # ["/usr/lib", "/opt/lib"] +``` + +The lines are joined with `"\n"`. Blank lines inside a value are kept, and +comment lines are skipped. `write` puts each extra line on its own line, +indented with a tab, so the value reads back unchanged. + +Multi-line values are off by default, so indentation does not change the meaning +of a file: every line stands on its own, as in IniFile 0.5. + +### Repeated keys and sections + +- A key that appears again in the same section replaces the earlier value and + keeps its first position, so the last value wins. A line appended at the end + of a section overrides an earlier one. +- A section header that appears again adds its entries to the earlier section, + which keeps the position of its first header. +- In `merged(ini)`, a key in a later section overrides the same key in an + earlier one. Sections are ordered by their first header, so a key in a later + section wins even over a line further down the file in a repeated, earlier + section. +- Repeated keys and sections are never an error, even with `strict=true`, which + only concerns malformed lines. + ### Differences from Python's `configparser` - Entries before the first section header are allowed and become the defaults. A `[DEFAULT]` section is an ordinary section. - There is no value interpolation (`%(name)s` or `${name}`). - Keys without a value (`allow_no_value`) are malformed. +- Multi-line values must be enabled with `multiline_values=true`; + `configparser` always allows them. - Repeated sections are merged and repeated keys overwrite earlier ones, as in - `configparser` with `strict=False`. + `configparser` with `strict=False`. IniFile's `strict` option is unrelated: + it only makes malformed lines an error. - Python 2's `ConfigParser` always treated `;` after whitespace as a comment. To read such files the same way, use `inline_comment_prefixes=(";",)`. @@ -182,8 +245,6 @@ Version 0.6 has breaking changes: `Inifile(2 sections, 5 keys)`, which is also how an `Inifile` appears inside arrays and other containers. `print`, `string` and `write` still give the file contents. -- A line indented more than the previous entry is now a continuation of that - entry's value (previously it was read as a separate entry). - Malformed lines are reported with `@warn` instead of being printed to `stdout`. - `Inifile` is now an immutable struct created with keyword arguments. diff --git a/src/IniFile.jl b/src/IniFile.jl index 4dc9c63..9204ff6 100644 --- a/src/IniFile.jl +++ b/src/IniFile.jl @@ -5,9 +5,10 @@ Read, query, modify and write INI configuration files. The parser follows the conventions of Python's `configparser`: `key = value` or `key: value` entries grouped under `[section]` headers, full-line comments -starting with `#` or `;`, and multi-line values written as indented continuation -lines. Sections and keys keep the order in which they were read or added, so -files round-trip through `read` and `write`. +starting with `#` or `;`, and, when enabled with `multiline_values=true`, +multi-line values written as indented continuation lines. Sections and keys keep +the order in which they were read or added, so files round-trip through `read` +and `write`. See [`Inifile`](@ref) to get started. """ @@ -22,6 +23,7 @@ export Inifile, get_int, get_float, has_section, + merged, section, sections @@ -34,7 +36,7 @@ the order the keys were first added. const SectionDict = OrderedDict{String,String} """ - Inifile(; lowercase_keys=false, inline_comment_prefixes=(), strict=false) + Inifile(; lowercase_keys=false, inline_comment_prefixes=(), multiline_values=false, strict=false) An INI file held in memory: named sections, each mapping keys to string values, plus a set of default key/value pairs. Sections and keys keep their insertion @@ -60,10 +62,17 @@ when the section does not have the key. at the beginning of a line or after whitespace, so `a = b;c` keeps its `;`. Inline comments are off by default, as in Python 3's `configparser`, because values may legitimately contain `;` or `#`. +- `multiline_values::Bool = false`: allow values that span several lines. A + line indented more than the line that started an entry then continues that + entry's value, as in Python's `configparser`. When `false`, every line stands + on its own and leading whitespace is ignored, as in IniFile 0.5, and + [`write`](@ref) throws for a value that contains a newline, because it could + not be read back. - `strict::Bool = false`: throw an `ArgumentError` on a malformed line instead of logging a warning and skipping it. A line is malformed if it is not blank, - a comment, a `[section]` header, a `key = value` or `key: value` entry, or a - continuation line. + a comment, a `[section]` header, a `key = value` or `key: value` entry, or, + with `multiline_values=true`, a continuation line. `strict` does not affect + repeated keys or sections, which are always allowed (see [`read`](@ref)). # Examples ```julia-repl @@ -86,13 +95,16 @@ struct Inifile defaults::SectionDict lowercase_keys::Bool inline_comment_prefixes::Vector{String} + multiline_values::Bool strict::Bool end -function Inifile(; lowercase_keys::Bool=false, inline_comment_prefixes=(), strict::Bool=false) +function Inifile(; lowercase_keys::Bool=false, inline_comment_prefixes=(), + multiline_values::Bool=false, strict::Bool=false) prefixes = String[string(p) for p in inline_comment_prefixes] any(isempty, prefixes) && throw(ArgumentError("inline comment prefixes must not be empty")) - return Inifile(OrderedDict{String,SectionDict}(), SectionDict(), lowercase_keys, prefixes, strict) + return Inifile(OrderedDict{String,SectionDict}(), SectionDict(), lowercase_keys, prefixes, + multiline_values, strict) end # Normalize a key to the form in which it is stored. @@ -140,6 +152,53 @@ The returned dictionary is the one stored in `ini`, so modifying it modifies """ section(ini::Inifile, name::AbstractString) = ini.sections[name] +""" + merged(ini::Inifile) -> OrderedDict{String,String} + +Return the keys of `ini` from the defaults and from all sections in one +dictionary. The defaults come first, then the keys of each section, with the +sections in order. When a key appears in more than one place, the later one +wins: a key in a section overrides the same key in the defaults, and a key in a +later section overrides the same key in an earlier section. Each key keeps the +position where it first appeared. + +Sections are ordered by where their header first appears, and a header that +appears again adds to the earlier section (see [`read`](@ref)). So a key in a +later section wins even over a line further down the file that is in a repeated, +earlier section. For a file without a `[DEFAULT]` section, this gives the same +values as reading it with Python 2's `ConfigParser` (or Python 3's +`configparser` with `strict=False`) and collecting the items of each section, in +order, into one dictionary. + +The result is a new dictionary: changing it does not change `ini`. + +# Examples +```julia-repl +julia> ini = read(Inifile, IOBuffer(\"\"\" + solver = cg+amg + [options] + solver = cholmod + [output] + write_maps = true + \"\"\")); + +julia> merged(ini)["solver"] +"cholmod" + +julia> collect(keys(merged(ini))) +2-element Vector{String}: + "solver" + "write_maps" +``` +""" +function merged(ini::Inifile) + result = copy(ini.defaults) + for sec in values(ini.sections) + merge!(result, sec) + end + return result +end + """ haskey(ini::Inifile, section::AbstractString, key::AbstractString) -> Bool @@ -162,11 +221,11 @@ end Parse INI text from a stream or a file into `ini` and return `ini`. The last form creates a new [`Inifile`](@ref), passing the keyword arguments -(`lowercase_keys`, `inline_comment_prefixes`, `strict`) to its constructor. +(`lowercase_keys`, `inline_comment_prefixes`, `multiline_values`, `strict`) to +its constructor. -Reading into an `Inifile` that already has content merges the new content in: -sections that appear again are extended, and keys that appear again are -overwritten. +Reading into an `Inifile` that already has content merges the new content in, +in the same way as repeated sections and keys within one file (see below). # Syntax - Blank lines are ignored, except inside a multi-line value. @@ -176,10 +235,11 @@ overwritten. - `key = value` or `key: value` sets a key; the first `=` or `:` on the line is the delimiter. Whitespace around the key and the value is removed. The value may be empty, as in `key =`. -- A line indented more than the line that started the current entry continues - its value. The lines of a value are joined with `"\\n"`, blank lines inside the - value are kept, and trailing blank lines are dropped. Comment lines inside a - value are skipped. +- Leading whitespace is ignored, unless `ini` was created with + `multiline_values=true`. Then a line indented more than the line that started + the current entry continues its value. The lines of a value are joined with + `"\\n"`, blank lines inside the value are kept, and trailing blank lines are + dropped. Comment lines inside a value are skipped. - Inline comments are recognized only if `ini` was created with `inline_comment_prefixes`. - A UTF-8 byte order mark at the start of the input is ignored, and both `\\n` @@ -189,6 +249,17 @@ Any other line is malformed. It is skipped with a warning that gives its line number or, if `ini` was created with `strict=true`, an `ArgumentError` is thrown and `ini` is left partially read. +# Repeated keys and sections +- A key that appears again in the same section replaces the earlier value, and + keeps the position where it first appeared. The last value wins. +- A section header that appears again does not start a new section. The entries + that follow it are added to the earlier section, which keeps the position of + its first header. +- Repeated keys and sections are never an error, even with `strict=true`. + +[`merged`](@ref) combines the defaults and all sections into one dictionary, in +which a key in a later section overrides the same key in an earlier one. + # Examples ```julia-repl julia> ini = read(Inifile, IOBuffer(\"\"\" @@ -197,7 +268,7 @@ julia> ini = read(Inifile, IOBuffer(\"\"\" search = /usr/lib /opt/lib - \"\"\")); + \"\"\"); multiline_values=true); julia> get(ini, "paths", "data") "/srv/data" @@ -231,11 +302,11 @@ function _parse!(ini::Inifile, io::IO, source::Union{String,Nothing}) text = strip(_strip_inline_comment(line, ini.inline_comment_prefixes)) if isempty(text) # a blank line may be part of a multi-line value, a comment is not - key !== nothing && isempty(stripped) && push!(value, "") + ini.multiline_values && key !== nothing && isempty(stripped) && push!(value, "") continue end ind = something(findfirst(!isspace, line), 1) - if key !== nothing && ind > indent + if ini.multiline_values && key !== nothing && ind > indent push!(value, text) continue end @@ -300,14 +371,19 @@ end Write `ini` in INI format and return the number of bytes written. Defaults come first, then each section in order, separated by blank lines. Entries are written -as `key = value`. Multi-line values are written as continuation lines indented -with a tab, so that [`read`](@ref) restores them. +as `key = value`. + +If `ini` was created with `multiline_values=true`, a value that contains +newlines is written as continuation lines indented with a tab, so that +[`read`](@ref) restores it. Otherwise such a value could not be read back, so +`write` throws an `ArgumentError` that names its key and section, before +anything is written. `print(io, ini)` and `string(ini)` also give the file contents. # Examples ```julia-repl -julia> ini = Inifile(); +julia> ini = Inifile(multiline_values=true); julia> set(ini, "b", "x", 1); set(ini, "a", "y", "two\\nlines"); @@ -321,6 +397,38 @@ y = two ``` """ function Base.write(io::IO, ini::Inifile) + _check_writable(ini) + return write(io, _contents(ini)) +end + +# Check before opening the file, so that an error does not leave it empty. +function Base.write(filename::AbstractString, ini::Inifile) + _check_writable(ini) + return open(io -> write(io, _contents(ini)), filename, "w") +end + +# Throw if `ini` has a value that `read` could not restore from the written text. +function _check_writable(ini::Inifile) + ini.multiline_values && return nothing + _check_single_line(ini.defaults, nothing) + for (name, sec) in ini.sections + _check_single_line(sec, name) + end + return nothing +end + +function _check_single_line(sec::SectionDict, name::Union{String,Nothing}) + for (key, value) in sec + occursin('\n', value) || continue + where = name === nothing ? "the defaults" : "section $(repr(name))" + throw(ArgumentError( + "cannot write key $(repr(key)) in $where: its value spans several lines, " * + "which can only be written by an Inifile created with multiline_values=true")) + end +end + +# The INI text of `ini`, as bytes. +function _contents(ini::Inifile) buf = IOBuffer() _write_entries(buf, ini.defaults) for (name, sec) in ini.sections @@ -328,7 +436,7 @@ function Base.write(io::IO, ini::Inifile) println(buf, '[', name, ']') _write_entries(buf, sec) end - return write(io, take!(buf)) + return take!(buf) end function _write_entries(io::IO, sec::SectionDict) @@ -359,7 +467,8 @@ end # Full form, used by the REPL: a summary line followed by the file contents. function Base.show(io::IO, ::MIME"text/plain", ini::Inifile) show(io, ini) - text = sprint(write, ini) + # unlike `write`, display never throws, even for values that span several lines + text = String(_contents(ini)) isempty(text) || print(io, ":\n", chomp(text)) end @@ -412,7 +521,10 @@ Set `key` to `value` in `section`, creating the section if needed, and return so [`get`](@ref) always returns a `String`; read it back with [`get_int`](@ref), [`get_float`](@ref) or [`get_bool`](@ref) to get a number or a `Bool`. If `value` is `nothing`, the key is removed instead (and a missing -section is not created). +section is not created). Setting an existing key keeps its position. + +A value that contains newlines can be set, but only an `Inifile` created with +`multiline_values=true` can [`write`](@ref) it. """ function set(ini::Inifile, section::AbstractString, key::AbstractString, value::Union{AbstractString,Number,Nothing}) diff --git a/test/runtests.jl b/test/runtests.jl index ffbcb69..d6588f6 100644 --- a/test/runtests.jl +++ b/test/runtests.jl @@ -12,7 +12,7 @@ contents(ini) = (collect(defaults(ini)), [name => collect(sec) for (name, sec) i @testset "IniFile" begin @testset "test.ini" begin - ini = Inifile() + ini = Inifile(multiline_values=true) @test read(ini, TESTINI) === ini # section exists @@ -70,13 +70,17 @@ contents(ini) = (collect(defaults(ini)), [name => collect(sec) for (name, sec) i @test get(ini, "section 4", "multiline1") == "This is multiple\nlines of text" @test get(ini, "section 4", "multiline2") == "This is multiple\nlines of text that ; should be\nformed into a single value ; and a comment" - ini2 = read(Inifile, TESTINI; inline_comment_prefixes=(";",)) + ini2 = read(Inifile, TESTINI; inline_comment_prefixes=(";",), multiline_values=true) @test get(ini2, "section 4", "midline") == "value" @test get(ini2, "section 4", "multiline2") == "This is multiple\nlines of text that\nformed into a single value" + # without multiline_values, the continuation lines are malformed, as in 0.5 + ini2 = @test_logs (:warn, r"lines of text") (:warn, r"lines of text that") (:warn, r"formed into") read(Inifile, TESTINI) + @test get(ini2, "section 4", "multiline1") == "This is multiple" + # round trip through write - ini2 = parse_ini(ini_string(ini)) + ini2 = parse_ini(ini_string(ini); multiline_values=true) @test contents(ini2) == contents(ini) @test get(ini2, "section 3", "strname1") == "new string" @test get(ini2, "section 3", "intname1") == "1" @@ -299,6 +303,8 @@ end end @testset "multi-line values" begin + parse_ini(text; kwargs...) = read(Inifile, IOBuffer(text); multiline_values=true, kwargs...) + text = """ [s] key1 = first line @@ -345,7 +351,7 @@ end """ @test contents(parse_ini(ini_string(ini))) == contents(ini) - ini = Inifile() + ini = Inifile(multiline_values=true) set(ini, "s", "k", "x\ny\n\nz") @test get(parse_ini(ini_string(ini)), "s", "k") == "x\ny\n\nz" @@ -366,6 +372,161 @@ end @test_logs (:warn, r"line 2") parse_ini("[s]\n stray\n") end +@testset "multiline_values is off by default" begin + text = """ + [s] + a = 1 + b = 2 + c = first + + d = 4 + """ + # every line stands on its own, as in IniFile 0.5 + @test contents(parse_ini(text)) == + ([], ["s" => ["a" => "1", "b" => "2", "c" => "first", "d" => "4"]]) + # with the option, indented lines continue the value above them + @test contents(parse_ini(text; multiline_values=true)) == + ([], ["s" => ["a" => "1\nb = 2", "c" => "first\n\nd = 4"]]) + + # an indented line without a delimiter is malformed + text = "[s]\na = 1\n continued\n" + ini = @test_logs (:warn, r"line 3: \" continued\"") parse_ini(text) + @test get(ini, "s", "a") == "1" + @test_throws ArgumentError parse_ini(text; strict=true) + @test get(parse_ini(text; multiline_values=true, strict=true), "s", "a") == "1\ncontinued" +end + +@testset "write refuses values that span several lines" begin + ini = Inifile() + set(ini, "s", "k", "two\nlines") + err = @test_throws ArgumentError ini_string(ini) + @test occursin("key \"k\" in section \"s\"", err.value.msg) + @test occursin("multiline_values=true", err.value.msg) + @test_throws ArgumentError string(ini) + + # nothing is written, and an existing file is left as it was + io = IOBuffer() + @test_throws ArgumentError write(io, ini) + @test position(io) == 0 + path = joinpath(mktempdir(), "keep.ini") + write(path, "[s]\nk = old\n") + @test_throws ArgumentError write(path, ini) + @test read(path, String) == "[s]\nk = old\n" + + # display does not throw + @test repr("text/plain", ini) == "Inifile(1 section, 1 key):\n[s]\nk = two\n\tlines" + + # a value in the defaults + ini = Inifile() + set(ini, "top", "a\nb") + err = @test_throws ArgumentError ini_string(ini) + @test occursin("key \"top\" in the defaults", err.value.msg) + set(ini, "top", "a") + @test ini_string(ini) == "top = a\n" + + # with multiline_values=true the value is written and read back + ini = Inifile(multiline_values=true) + set(ini, "s", "k", "two\nlines") + @test ini_string(ini) == "[s]\nk = two\n\tlines\n" + @test get(parse_ini(ini_string(ini); multiline_values=true), "s", "k") == "two\nlines" +end + +@testset "repeated keys and sections" begin + text = """ + solver = cg+amg + solver = amg + [a] + x = 1 + y = 2 + x = 3 + [b] + x = 4 + [a] + y = 5 + z = 6 + """ + # the last value wins and keeps the key's first position; a repeated header + # adds to the first section, which keeps its place. strict does not change this. + for strict in (false, true), multiline_values in (false, true) + ini = parse_ini(text; strict=strict, multiline_values=multiline_values) + @test contents(ini) == (["solver" => "amg"], + ["a" => ["x" => "3", "y" => "5", "z" => "6"], "b" => ["x" => "4"]]) + end + + # appending a line at the end of a file overrides an earlier one + ini = parse_ini(""" + [Options for advanced mode] + solver = cg+amg + mask = none + solver = cholmod + """; strict=true) + @test get(ini, "Options for advanced mode", "solver") == "cholmod" + @test collect(keys(section(ini, "Options for advanced mode"))) == ["solver", "mask"] + + # with lowercase_keys, keys that differ only in case are the same key + ini = parse_ini("[s]\nSolver = a\nSOLVER = b\n"; lowercase_keys=true) + @test collect(section(ini, "s")) == ["solver" => "b"] +end + +@testset "merged" begin + ini = parse_ini(""" + solver = cg+amg + scenario = pairwise + [Options for advanced mode] + solver = cholmod + mask = none + [Output options] + write_cur_maps = True + [Options for advanced mode] + mask = file.asc + [Habitat raster] + scenario = advanced + """) + m = merged(ini) + @test m isa IniFile.OrderedDict{String,String} + # defaults first, then each section in order; later ones win, and each key + # keeps the position where it first appeared + @test collect(m) == ["solver" => "cholmod", "scenario" => "advanced", + "mask" => "file.asc", "write_cur_maps" => "True"] + + # a later section wins over a later line in a repeated, earlier section + ini = parse_ini(""" + [x] + solver = a + [y] + solver = b + [x] + solver = c + """) + @test get(ini, "x", "solver") == "c" + @test merged(ini)["solver"] == "b" + + # a line appended at the end of the file, in the last section, wins + ini = parse_ini(""" + [Options for advanced mode] + solver = cg+amg + [Output options] + write_cur_maps = True + solver = cholmod + """; strict=true) + @test merged(ini)["solver"] == "cholmod" + @test get(ini, "Options for advanced mode", "solver") == "cg+amg" + + # the result is a copy + m = merged(ini) + m["solver"] = "changed" + m["new"] = "1" + @test get(ini, "Output options", "solver") == "cholmod" + @test !haskey(ini, "Output options", "new") + ini = parse_ini("a = 1\n") + @test merged(ini) == defaults(ini) + @test merged(ini) !== defaults(ini) + + @test isempty(merged(Inifile())) + @test collect(merged(parse_ini("Solver = a\n[s]\nSOLVER = b\n"; lowercase_keys=true))) == + ["solver" => "b"] +end + @testset "inline comments" begin text = """ [s] @@ -379,12 +540,12 @@ end line # two ; full-line comment """ - ini = parse_ini(text) + ini = parse_ini(text; multiline_values=true) @test get(ini, "s", "a") == "value ; comment" @test get(ini, "s", "b") == "value # comment" @test get(ini, "s", "e") == "; only a comment" - ini = parse_ini(text; inline_comment_prefixes=(";", "#")) + ini = parse_ini(text; inline_comment_prefixes=(";", "#"), multiline_values=true) @test get(ini, "s", "a") == "value" @test get(ini, "s", "b") == "value" @test get(ini, "s", "c") == "no;comment" @@ -393,7 +554,7 @@ end @test get(ini, "s", "url") == "http://example.com/#anchor" @test get(ini, "s", "f") == "multi\nline" - ini = parse_ini(text; inline_comment_prefixes=[';']) + ini = parse_ini(text; inline_comment_prefixes=[';'], multiline_values=true) @test get(ini, "s", "a") == "value" @test get(ini, "s", "b") == "value # comment" From ad7119fb0540ec1fe9881460f3776bb80b27f933 Mon Sep 17 00:00:00 2001 From: "Viral B. Shah" Date: Sat, 14 Nov 2026 12:24:10 -0500 Subject: [PATCH 2/2] Address review: print never throws, accurate round-trip docs - print, string and interpolation give the file contents without the multi-line check, so logging an Inifile never throws. Only write checks. - write(filename, ini) delegates to write(io, ini) after its check. - Say what a multi-line value loses in a round trip: surrounding whitespace on each line, trailing blank lines, and lines starting with # or ;. Add a test that pins this down. - List write's new ArgumentError in the 0.6 upgrade guide. - Drop the claim that merged matches Python's ConfigParser, which also lowercases keys and strips inline comments. Co-Authored-By: Claude Opus 5.5 --- README.md | 9 +++++++-- src/IniFile.jl | 26 ++++++++++++++------------ test/runtests.jl | 9 ++++++++- 3 files changed, 29 insertions(+), 15 deletions(-) diff --git a/README.md b/README.md index b51e81f..1c09558 100644 --- a/README.md +++ b/README.md @@ -141,7 +141,8 @@ write("file.ini", ini) # or write(io, ini) blank line between sections. Comments in the original file are not kept. A value that contains newlines can only be written with `multiline_values=true`; otherwise `write` throws an `ArgumentError` before writing anything, because the -value could not be read back. +value could not be read back. `print(io, ini)` and `string(ini)` give the same +text without this check, so they never throw. ## File format @@ -184,7 +185,8 @@ split(strip(get(ini, "paths", "search")), '\n') # ["/usr/lib", "/opt/lib"] The lines are joined with `"\n"`. Blank lines inside a value are kept, and comment lines are skipped. `write` puts each extra line on its own line, -indented with a tab, so the value reads back unchanged. +indented with a tab. Whitespace at the start and end of each line is not kept, +and a line of the value that starts with `#` or `;` reads back as a comment. Multi-line values are off by default, so indentation does not change the meaning of a file: every line stands on its own, as in IniFile 0.5. @@ -245,6 +247,9 @@ Version 0.6 has breaking changes: `Inifile(2 sections, 5 keys)`, which is also how an `Inifile` appears inside arrays and other containers. `print`, `string` and `write` still give the file contents. +- `write` throws an `ArgumentError` for a value that contains a newline, unless + the `Inifile` was created with `multiline_values=true`. Such a value used to + be written out as is, and the file could not be read back correctly. - Malformed lines are reported with `@warn` instead of being printed to `stdout`. - `Inifile` is now an immutable struct created with keyword arguments. diff --git a/src/IniFile.jl b/src/IniFile.jl index 9204ff6..0723ad9 100644 --- a/src/IniFile.jl +++ b/src/IniFile.jl @@ -165,10 +165,7 @@ position where it first appeared. Sections are ordered by where their header first appears, and a header that appears again adds to the earlier section (see [`read`](@ref)). So a key in a later section wins even over a line further down the file that is in a repeated, -earlier section. For a file without a `[DEFAULT]` section, this gives the same -values as reading it with Python 2's `ConfigParser` (or Python 3's -`configparser` with `strict=False`) and collecting the items of each section, in -order, into one dictionary. +earlier section. The result is a new dictionary: changing it does not change `ini`. @@ -374,12 +371,16 @@ first, then each section in order, separated by blank lines. Entries are written as `key = value`. If `ini` was created with `multiline_values=true`, a value that contains -newlines is written as continuation lines indented with a tab, so that -[`read`](@ref) restores it. Otherwise such a value could not be read back, so -`write` throws an `ArgumentError` that names its key and section, before -anything is written. +newlines is written as continuation lines indented with a tab, which +[`read`](@ref) joins again. As with any value, whitespace at the start and end +of each line is not kept, and neither are blank lines at the end of the value or +lines that start with `#` or `;`, which are read as comments. Without +`multiline_values=true`, such a value could not be read back at all, so `write` +throws an `ArgumentError` that names its key and section, before anything is +written. -`print(io, ini)` and `string(ini)` also give the file contents. +`print(io, ini)` and `string(ini)` give the same text as `write`, but do not +check values, so they never throw. # Examples ```julia-repl @@ -404,7 +405,7 @@ end # Check before opening the file, so that an error does not leave it empty. function Base.write(filename::AbstractString, ini::Inifile) _check_writable(ini) - return open(io -> write(io, _contents(ini)), filename, "w") + return open(io -> write(io, ini), filename, "w") end # Throw if `ini` has a value that `read` could not restore from the written text. @@ -454,8 +455,9 @@ end _plural(n::Int, word::String) = n == 1 ? "1 $word" : "$n $(word)s" -# `print` and `string` give the file contents, as they did in IniFile 0.5. -Base.print(io::IO, ini::Inifile) = (write(io, ini); nothing) +# `print` and `string` give the file contents, as they did in IniFile 0.5. Unlike +# `write`, they do not check values, so that logging an Inifile never throws. +Base.print(io::IO, ini::Inifile) = (write(io, _contents(ini)); nothing) # Compact form, used when shown inside containers and by `repr`. function Base.show(io::IO, ini::Inifile) diff --git a/test/runtests.jl b/test/runtests.jl index d6588f6..864689b 100644 --- a/test/runtests.jl +++ b/test/runtests.jl @@ -402,7 +402,10 @@ end err = @test_throws ArgumentError ini_string(ini) @test occursin("key \"k\" in section \"s\"", err.value.msg) @test occursin("multiline_values=true", err.value.msg) - @test_throws ArgumentError string(ini) + # print, string and interpolation do not check, so they never throw + @test string(ini) == "[s]\nk = two\n\tlines\n" + @test sprint(print, ini) == string(ini) + @test "config: $ini" == "config: [s]\nk = two\n\tlines\n" # nothing is written, and an existing file is left as it was io = IOBuffer() @@ -429,6 +432,10 @@ end set(ini, "s", "k", "two\nlines") @test ini_string(ini) == "[s]\nk = two\n\tlines\n" @test get(parse_ini(ini_string(ini); multiline_values=true), "s", "k") == "two\nlines" + # as documented, surrounding whitespace on each line, trailing blank lines + # and lines that look like comments do not survive + set(ini, "s", "k", "a\n# b\n c \n\n") + @test get(parse_ini(ini_string(ini); multiline_values=true), "s", "k") == "a\nc" end @testset "repeated keys and sections" begin