中文 • Installation • Usage • Public API
SwiftINI is a small Swift Package for parsing and serializing INI data. Its behavior is modeled after npm's ini package, including bracketed arrays, duplicate-key arrays, dotted nested sections, quoted values, escaped comments, and typed true / false / null values.
- Parse INI text or files.
- Serialize
INIObjectvalues back to INI text. - Supports
;and#comments. - Supports
[section]and[parent.child]nested sections. - Supports
key[] = valuearrays. - Supports duplicate-key arrays.
- Supports escaped
\;and\#so values are not treated as comments. - Supports quoted keys and values.
- Supports typed
true,false, andnullvalues. - Keeps numbers as strings by default, matching npm
ini. - Skips
__proto__keys to avoid prototype-pollution style issues.
Add the package to Package.swift:
dependencies: [
.package(url: "https://github.com/jaywcjlove/SwiftINI.git", from: "1.0.0")
]Then add SwiftINI to your target dependencies:
targets: [
.target(
name: "YourTarget",
dependencies: ["SwiftINI"]
)
]For local development, use a path dependency:
.package(path: "/Users/wong/git/packages/SwiftINI")import SwiftINI
let text = """
; This comment is ignored
scope = global
[database]
user = dbuser
password = dbpassword
database = use_this_database
[paths.default]
datadir = /var/lib/data
array[] = first value
array[] = second value
array[] = third value
"""
let config = INI.parse(text)
print(config["scope"]?.string ?? "")
print(config["database"]?["user"]?.string ?? "")
print(config["paths"]?["default"]?["datadir"]?.string ?? "")
print(config["paths"]?["default"]?["array"]?.array ?? [])let config = try INI.parse(contentsOfFile: "path/to/config.ini")
print(config["Header"]?["Key"]?.string ?? "")You can also read from a URL:
let url = URL(fileURLWithPath: "path/to/config.ini")
let config = try INI.parse(contentsOf: url)let object: INIObject = [
"scope": "global",
"database": [
"user": "dbuser",
"password": "dbpassword",
"database": "use_this_database",
],
"paths": [
"default": [
"datadir": "/var/lib/data",
"array": [
"first value",
"second value",
"third value",
],
],
],
]
let output = INI.stringify(object)
print(output)Output:
scope=global
[database]
user=dbuser
password=dbpassword
database=use_this_database
[paths.default]
datadir=/var/lib/data
array[]=first value
array[]=second value
array[]=third valueINI.parse(_ text: String) -> INIObject
INI.parse(contentsOfFile path: String) throws -> INIObject
INI.parse(contentsOf url: URL) throws -> INIObject
INI.decode(_ text: String) -> INIObject
INI.stringify(_ object: INIObject) -> String
INI.encode(_ object: INIObject) -> StringRecommended semantics:
parse: parse INI text or files.decode: alias ofparse(_:), matching npmini.stringify: serialize anINIObjectto INI text.encode: alias ofstringify(_:), matching npmini.
INIObject subscripting returns INIValue?, and object values can be chained:
let value = config["database"]?["user"]?.stringCommon value accessors:
value.string // String?
value.bool // Bool?
value.array // [INIValue]?
value.object // INIObject?INIValue supports:
case string(String)
case bool(Bool)
case null
case array([INIValue])
case object(INIObject)let config = INI.parse(text, options: .init(bracketedArray: true))INI.DecodeOptions:
| Option | Default | Description |
|---|---|---|
bracketedArray |
true |
When true, key[] = value is parsed as an array. When false, repeated keys are parsed as arrays. |
Example:
array[] = first
array[] = secondDefault result:
["array": ["first", "second"]]Duplicate-key mode:
let config = INI.parse(text, options: .init(bracketedArray: false))array = first
array = secondResult:
["array": ["first", "second"]]let output = INI.stringify(
object,
options: .init(
align: true,
sort: true,
whitespace: true
)
)INI.EncodeOptions:
| Option | Default | Description |
|---|---|---|
section |
nil |
Wraps output in a section prefix. |
align |
false |
Aligns = and implies whitespace. |
newline |
false |
Adds a blank line after section headers. |
sort |
false |
Sorts keys before encoding. |
whitespace |
false |
Uses key = value; otherwise outputs key=value. |
platform |
nil |
Use "win32" for CRLF output. |
bracketedArray |
true |
When true, emits key[]=value; when false, emits repeated key=value lines. |
let output = INI.stringify(
["type": "file"],
options: .init(section: "log")
)Output:
[log]
type=fileArrays are emitted as key[] by default:
let output = INI.stringify([
"items": ["first", "second"]
])items[]=first
items[]=secondWith bracketedArray: false:
let output = INI.stringify(
["items": ["first", "second"]],
options: .init(bracketedArray: false)
)items=first
items=secondLines starting with ; or # are ignored:
; comment
# comment
name = SwiftINIInline comments are cut off at unescaped ; or #:
name = value ; comment
hash = value # commentEscape ; or # when the character is part of the value:
semicolon = this\; is not a comment
hash = this\# is not a commentQuoted values are parsed as JSON strings when possible, preserving leading/trailing spaces and escaped characters:
value = " a "Parsed result:
" a "Only these literal values are converted automatically:
enabled = true
disabled = false
empty = null
count = 10Parsed result:
enabled // .bool(true)
disabled // .bool(false)
empty // .null
count // .string("10")10 remains a string.
swift testThe tests cover parsing, serializing, arrays, duplicate keys, nested sections, CRLF input/output, escaped comments, __proto__ protection, and the main fixture behaviors from npm ini.
Licensed under the MIT License.