% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/f_io_utilities.R
\name{writeKeyValueFile}
\alias{writeKeyValueFile}
\title{Write a key-value file (KEY=VALUE) from a named list}
\usage{
writeKeyValueFile(
  keyValueList,
  filePath,
  ...,
  writeHeader = TRUE,
  sortKeys = FALSE,
  overwrite = TRUE,
  safeKeyCheck = TRUE
)
}
\arguments{
\item{keyValueList}{A named list of scalar (length-1) atomic values.
Supported value types: character, logical, integer, numeric.
\code{NA} is supported and written as \code{NA}.}

\item{filePath}{Path to the output file (e.g. \code{"inst/tests/META.env"}).}

\item{...}{Currently unused.}

\item{writeHeader}{Logical; if \code{TRUE}, writes a short header comment.}

\item{sortKeys}{Logical; if \code{TRUE}, keys are written in alphabetical order.}

\item{overwrite}{Logical; if \code{FALSE} and the file exists, an error is raised.}

\item{safeKeyCheck}{Logical; if \code{TRUE}, checks that keys only contain
allowed characters. Set to \code{FALSE} to allow arbitrary keys, but be aware that
this may lead to issues when reading the file back, as keys with special characters
may not be parsed correctly.}
}
\value{
Invisibly returns \code{filePath}.
}
\description{
Writes a human-editable text file in a widely used key-value format
(INI/.env-like): one entry per line in the form \code{KEY=VALUE}.
Blank lines and comment lines (starting with \code{#} or \code{;})
are allowed. Values are written as a single line; special characters
are escaped so that the file remains one key per line.
}
\details{
Keys are restricted to \code{[A-Za-z0-9_.-]} to keep the file portable
and easy to edit.

UTF-8 handling: Values are normalized to UTF-8 on write. The file is written
with UTF-8 encoding when supported by the platform. On Windows, UTF-8 is
enforced via \code{fileEncoding = "UTF-8"}. On other platforms, UTF-8 is
typically the native encoding; we still normalize strings to UTF-8.
}
\examples{
\dontrun{
keyValueList <- list(
    STUDY_NAME = "Trial A",
    MAX_PATIENTS = 150L,
    THRESHOLD = 0.075,
    NOTES = "First phase\nSecond phase"
)
filePath <- tempfile(fileext = ".txt")
writeKeyValueFile(
    keyValueList = keyValueList,
    filePath = filePath,
    writeHeader = TRUE,
    sortKeys = TRUE,
    overwrite = TRUE
)
}

}
\keyword{internal}
