/// The root rule for parsing an entire INI file. An INI file consists of multiple sections,
/// each containing key-value pairs or nested sections. The sections are separated by optional
/// newlines and may include comments for readability.
ini_file = { SOI ~ (comment | section | NEWLINE)* ~ EOI }

/// Defines whitespace characters (space or tab) for optional spacing.
WHITESPACE = _{ " " | "\t" }

/// Defines a section in the INI file. A section starts with a name enclosed in square brackets.
section = {
    "[" ~ section_name ~ "]" ~
    NEWLINE* ~
    (comment | key_value | nested_section | NEWLINE)*
}

/// Defines nested sections, which can contain their own key-value pairs.
nested_section = {
    "[[" ~ section_name ~ "]]" ~
    NEWLINE* ~
    (comment | key_value | NEWLINE)*
}

/// Key-value pairs, with optional spaces around the `=` sign and optional quoted or multiline values.
key_value = {
    key ~ WHITESPACE? ~ "=" ~ WHITESPACE? ~ (quoted_value | value)? ~ NEWLINE?
}

/// A valid section name, consisting of alphanumeric characters, underscores, hyphens, and dots.
section_name = { (ASCII_ALPHANUMERIC | "_" | "-" | ".")+ }

/// A key in a key-value pair, consisting of alphanumeric characters, underscores, and hyphens.
key = { (ASCII_ALPHANUMERIC | "_" | "-")+ }

/// A simple value, consisting of ASCII printable characters except for control characters, backslashes, and newlines.
value = { (ASCII_ALPHANUMERIC | PUNCTUATION | " ")+ }

/// A quoted value, allowing spaces and special characters, enclosed in double quotes.
quoted_value = { "\"" ~ (!"\"" ~ (ASCII_ALPHANUMERIC | PUNCTUATION | " "))* ~ "\"" }

/// Represents a comment, starting with `#` or `;` and continuing until the end of the line.
comment = { ("#" | ";") ~ (!NEWLINE ~ (ASCII_ALPHANUMERIC | PUNCTUATION | " "))* ~ NEWLINE? }

/// Matches a newline character (`\n`).
NEWLINE = { "\n" }