((section 2 "Outdated egg!" (p "This is an egg for CHICKEN 4, the unsupported old release.  You're almost certainly looking for " (int-link "/eggref/5/ini-file" "the CHICKEN 5 version of this egg") ", if it exists.") (p "If it does not exist, there may be equivalent functionality provided by another egg; have a look at the " (link "https://wiki.call-cc.org/chicken-projects/egg-index-5.html" "egg index") ". Otherwise, please consider porting this egg to the current version of CHICKEN.") (tags "egg")) (section 2 "ini-file" (toc) (section 3 "Description" (p "Read & write INI configuration files.")) (section 3 "Documentation" (p (tt "ini-file") " is a small library for reading & writing INI files, such as those used in early Windows configuration scripts.") (p "INI syntax as a whole is underspecified and its implementations vary. This egg supports only its most basic features (comments, sections, zero- and one-valued properties).") (p "The source for this egg is available at " (link "https://github.com/kiatoa/ini-file") " (previously available at " (link "https://github.com/evhan/ini-file") ").") (section 4 "API" (def (sig (procedure "(read-property [port])" (id read-property))) (p "Reads a single INI property from " (tt "port") ". If it is a section header, returns a symbol. If it is a property or property/value pair, a pair is returned. Invalid properties will signal an error.") (p "Numeric values and quoted strings are read as Scheme data; everything else is treated as a string. Any such string mapped by the " (tt "property-value-map") " parameter will be replaced by its corresponding value.")) (def (sig (procedure "(read-ini [file-or-port])" (id read-ini))) (p "Reads configuration directives from " (tt "file-or-port") " until " (tt "#!eof") ", returning an alist of alists corresponding hierarchically to the source INI's SECTION -> PROPERTY -> VALUE structure.") (p "Properties appearing before any section heading are associated with the key given by the " (tt "default-section") " parameter.") (p "If " (tt "file-or-port") " is a port, it is not closed.")) (def (sig (procedure "(write-ini alist [file-or-port])" (id write-ini))) (p "Writes " (tt "alist") " as INI directives to " (tt "file-or-port") ".") (p "A symbol at the head of " (tt "alist") " signifies a section of that name. The write order of sections and properties is reverse that of " (tt "alist") ".") (p "The " (tt "property-separator") " parameter specifies the character or string with which to separate property names & values when writing.") (p "The " (tt "property-separator-patt") " parameter specifies the regex speparator pattern for which to separate property names & values when reading.") (p "Any value mapped to by the " (tt "property-value-map") " parameter will be replaced by its first corresponding key.") (p "If " (tt "file-or-port") " is a port, it is not closed."))) (section 4 "Parameters" (def (sig (parameter "(default-section [name])" (id default-section))) (p "Specifies the default alist key (usually a symbol) under which properties without a section label will be placed by " (tt "read-ini") ". Defaults to " (tt "'default") ".")) (def (sig (parameter "(property-separator [char-or-string])" (id property-separator))) (p "Specifies the character or string to be used by " (tt "write-ini") " to separate property names & values. Defaults to " (tt "#\\=") ".")) (def (sig (parameter "(property-separator-patt [string-or-regex])" (id property-separator-patt))) (p "Specifies the string or regex to be used by " (tt "read-ini") " to separate property names & values. Defaults to " (tt "\" * *\"") ".")) (def (sig (parameter "(property-value-map [alist])" (id property-value-map))) (p "Specifies an alist mapping strings to Scheme values, used to translate INI values to & from Scheme data when reading & writing INI files.") (p "The default map is simply:") (pre "   '((\"true\"  . #t)\n     (\"false\" . #f))")) (def (sig (parameter "(allow-empty-values? [boolean])" (id allow-empty-values?))) (p "Specifies whether the empty string should be treated as a valid property value. If " (tt "#f") ", an empty value will signal an error. Defaults to " (tt "#f") ".")) (def (sig (parameter "(allow-bare-properties? [boolean])" (id allow-bare-properties?))) (p "Specifies whether \"bare\" properties (those without a value) should be allowed. If " (tt "#f") ", a line not following \"key separator value\" format will signal an error. Defaults to " (tt "#f") ".")))) (section 3 "Example" (p "Git uses INI syntax for its configuration files. From " (tt "man git-config") ":") (pre "   #\n   # This is the config file, and\n   # a '#' or ';' character indicates\n   # a comment\n   #\n   \n   ; core variables\n   [core]\n           ; Don't trust file modes\n           filemode = false\n   \n   ; Our diff algorithm\n   [diff]\n           external = /usr/local/bin/diff-wrapper\n           renames = true\n   \n   ; Proxy settings\n   [core]\n           gitproxy=\"proxy-command\" for kernel.org\n           gitproxy=default-proxy ; for all the rest") (pre "   (use ini-file)\n   (read-ini \".git/config\")\n   ; => ((core (gitproxy . \"default-proxy\")\n   ;           (gitproxy . \"\\\"proxy-command\\\" for kernel.org\"))\n   ;     (diff (renames  . #t)\n   ;           (external . \"/usr/local/bin/diff-wrapper\"))\n   ;     (core (filemode . #f)))") (p "Note that separate sections of the same name are not merged.")) (section 3 "History" (ul (li "0.3.4 Introduce property-separator-patt") (li "0.3 Introduce property-value-map parameter") (li "0.2 Use regex unit") (li "0.1 Initial release"))) (section 3 "Author" (p (int-link "/users/evan-hanson" "Evan Hanson"))) (section 3 "Maintainer" (p (link "https://github.com/kiatoa" "Matt Welland"))) (section 3 "License" (p "3-Clause BSD"))))