% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/awkreader_v2.R
\name{combined.fread}
\alias{combined.fread}
\title{Fast Batch Combining of Flat Files via AWK}
\usage{
combined.fread(
  the.files,
  path.to.awk = NULL,
  header = TRUE,
  the.variables = ".",
  file.pattern = NULL,
  recursive = FALSE,
  include.filename = TRUE,
  skip = 0,
  file.header = "file",
  num.files.per.batch = 1000,
  return.as = "result",
  envir = parent.frame(),
  show.warnings = FALSE,
  return.data.table = TRUE,
  nrows = Inf,
  drop = NULL,
  ...
)
}
\arguments{
\item{the.files}{A character vector of file paths to process. Non-existent files are automatically filtered out.}

\item{path.to.awk}{A character string specifying the path to the AWK binary. If \code{NULL} (default),
the function attempts to invoke a global system call to \code{"awk"}.}

\item{header}{A logical value indicating whether the target files contain a header row. Default is \code{TRUE}.}

\item{the.variables}{A character vector specifying which columns to retain. Use \code{"."} (default)
to retain all columns.}

\item{file.pattern}{Optional character string to filter file names when \code{the.files} contains directory paths. Accepts simple extensions (e.g., \code{"csv"} or \code{".csv"}),
wildcards (e.g., \code{"*.csv"}), or regular expressions (e.g., \code{"\\.csv$"}). Default is \code{NULL} (includes all files).}

\item{recursive}{Logical. Should directory searches recurse into subdirectories when \code{the.files} contains directory paths? Default is \code{FALSE}.}

\item{include.filename}{A logical value indicating whether to include a source file tracking column
in the returned dataset. Default is \code{TRUE}.}

\item{skip}{A numeric offset, a character regex pattern, or a structured list indicating lines to bypass.
If a list is used, it \strong{must follow dot notation}:
\itemize{
\item \code{skip.metadata.rows}: An integer count or a character regex pattern used to identify where
the metadata block ends.
\item \code{skip.data.rows}: An integer specifying the number of data rows to explicitly skip after the header.
}
Default is \code{0}.}

\item{file.header}{A character string defining the column name for the tracked file origin.
Only utilized if \code{include.filename = TRUE}. Default is \code{"file"}.}

\item{num.files.per.batch}{An integer specifying how many files to aggregate per AWK system pipeline call.
Default is \code{1000}.}

\item{return.as}{A character string specifying the desired return object. Options are \code{"result"} (default),
\code{"code"} (returns raw generated AWK scripts), or \code{"all"} (returns both).}

\item{envir}{The environment context in which evaluation variables are evaluated. Default is \code{parent.frame()}.}

\item{show.warnings}{A logical value determining whether underlying \code{data.table::fread()} messages
should be displayed or suppressed. Default is \code{FALSE}.}

\item{return.data.table}{A logical value indicating whether to return a \code{data.table} object
or a standard \code{data.frame}. Default is \code{TRUE}.}

\item{nrows}{An integer specifying the maximum total rows to parse out from the batch pipeline. Default is \code{Inf}.}

\item{drop}{A character or numeric index vector specifying columns that should be explicitly excluded from the final output.}

\item{...}{Extra parameters forwarded to underlying internal setup routines inside \code{filtered.fread()}.}
}
\value{
A \code{data.table} (or \code{data.frame}), or a character vector containing the raw shell commands,
depending on the value passed to \code{return.as}.
}
\description{
A streamlined wrapper around \code{\link{filtered.fread}()} designed to quickly
read, process, and combine multiple flat files into a single dataset without applying row filters.
}
\examples{
\donttest{
# Create sample CSV files with metadata rows
f1 <- tempfile(fileext = ".csv")
f2 <- tempfile(fileext = ".csv")

writeLines(c("# Title: Jan Log", "# Status: Active", "id,val", "1,10", "2,20"), f1)
writeLines(c("# Title: Feb Log", "# Status: Active", "id,val", "3,30", "4,40"), f2)

# Combine multiple log files while skipping the 2 metadata rows
all_logs <- combined.fread(
  the.files = c(f1, f2),
  skip = list(skip.metadata.rows = 2, skip.data.rows = 0)
)
print(all_logs)

# Clean up temporary files
unlink(c(f1, f2))
}
}
