Sigil value files

Use .sgv (Sigil value) for files containing one data value that is read and never run. The convention is: "if it ends in .sgv, it cannot run." Applications uphold that guarantee by using (sigil sgv) and validating the result as data. A filename alone does not enforce it.

(import (sigil sgv) (sigil io) (sigil dict))

(define options
  (call-with-input-file "options.sgv"
    (lambda (port) (read-sgv port max-bytes: 65536))))

(unless (and (dict? options)
             (integer? (dict-ref options text-size: #f))
             (<= 8 (dict-ref options text-size:) 72))
  (error "invalid text-size option"))

A file can contain, for example:

; One dictionary, with nested data.
#{ text-size: 14
   opacity: 0.85
   color: ocean
   enabled: #true
   search-paths: #["docs" "examples"] }

read-sgv-string accepts a string, read-sgv-bytevector accepts UTF-8 bytes, and read-sgv accepts an open text or binary input port. All three require exactly one retained datum followed by EOF, allowing comments and whitespace. Port reads start at the current position and leave the port open. For an already-open file descriptor, pass its input port. A pipe needs an EOF and a caller-controlled I/O deadline.

The grammar includes proper lists ((...) or [...]), vectors (#(...)), arrays (#[...]), dictionaries (#{key value ...}), strings, symbols, keywords (name:), booleans, bounded base-ten integers, and bounded plain decimals. Dictionaries and arrays are returned as actual collections. Dictionary keys must be strings, symbols, keywords, booleans, or integers; duplicate keys are errors. Vertical bars escape symbol spellings.

Decimals require digits on both sides of the point, such as 0.85 and -1.4. They produce inexact binary64 numbers: 0.85 rounds to approximately 0.84999999999999998. Use scaled integers or schema-defined strings when decimal exactness matters. Exponents, radix and exactness prefixes, nonfinite numbers, leading/trailing decimal points, character and bytevector literals, datum labels, dotted pairs, quote and syntax shorthands, directives, and shebangs are refused. Even (delete-file "example") remains a plain list; no procedure is called while reading.

Line comments (;), nested block comments (#| ... |#), and datum comments (#;) are allowed. Discarded datums must also satisfy the strict grammar and share the document's budgets. Missing comment terminators and payloads are errors. Invalid UTF-8 and NUL bytes are refused everywhere, including comments and trailing input. String and symbol escapes also reject NUL and surrogate code points. Rejected documents do not intern symbol or keyword names.

Policy files also reject Unicode format characters (Unicode 17.0 category Cf, including zero-width and bidi controls), even in comments, bar symbols, or string/symbol escapes. A leading UTF-8 BOM has its own BOM refusal. Unquoted symbols cannot contain non-ASCII whitespace such as NBSP; use bars when that whitespace is intentional. Trivia permits spaces, tabs, LF, and CRLF, and rejects a lone CR, vertical tab, or form feed. Strings reject raw C0 controls, including ESC, tabs, and newlines; explicit escapes such as \n and \x1B; remain available. NUL and format characters stay forbidden even when escaped.

All three procedures accept these optional keyword limits:

KeywordDefaultHard maximum
max-bytes:1,048,57616,777,216
max-depth:64128
max-token-bytes:65,5361,048,576
max-elements:65,5361,048,576
max-integer-magnitude:140,737,488,355,327140,737,488,355,327
max-decimal-bytes:3264

Limits are inclusive and positive, except integer magnitude may be zero. The root datum counts as one element and depth one; (0) counts as two elements and depth two. Every nested or discarded datum also counts. Token budgets bound source spelling and decoded UTF-8 content, excluding outer string/symbol quotes and a keyword's final colon. Decimal spelling includes the sign and point. The byte budget includes all whitespace and comments; port acquisition consumes at most that budget plus one byte.

Invalid documents raise catchable errors with a bounded reason and byte, line, and column position. Refusal reasons use stable names such as BOM, FORMAT, WHITESPACE, and CONTROL. Diagnostics do not include input excerpts. Apply a smaller budget when your application's format needs less data. After reading, validate allowed keys, value types, ranges, and any paths or other sensitive settings against your own schema. Never evaluate returned data or interpret arbitrary values as commands.

The reader contract specifies exact grammar, accounting, error codes, and the native API.