% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/awkreader_v2.R
\name{pattern.fread}
\alias{pattern.fread}
\title{Pattern-Based Subsetting and Reading of Multiple Files via AWK}
\usage{
pattern.fread(
  the.files,
  path.to.awk = NULL,
  header = TRUE,
  the.patterns = NULL,
  file.pattern = NULL,
  recursive = FALSE,
  tf = TRUE,
  delim = ",",
  connectors = "or",
  the.variables = ".",
  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.patterns}{A character vector containing the regular expression patterns to match against data rows. Default is \code{NULL}.}

\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{tf}{A logical value determining whether to include rows that match the patterns (\code{TRUE})
or exclude rows that match them (\code{FALSE}). Default is \code{TRUE}.}

\item{delim}{A character string specifying the column separator within the files. Default is \code{","}.}

\item{connectors}{A character string defining how multiple patterns should be combined logically.
Options are \code{"or"} (default) or \code{"and"}.}

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

\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"}, or \code{"all"}.}

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

\item{show.warnings}{A logical value determining whether underlying terminal messages should be shown. Default is \code{FALSE}.}

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

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

\item{drop}{A character or numeric index vector specifying columns to explicitly exclude.}

\item{...}{Extra parameters forwarded to internal setup routines.}
}
\value{
A \code{data.table} (or \code{data.frame}) containing rows satisfying the pattern configurations.
}
\description{
Reads and aggregates multiple flat files concurrently, filtering rows
based on regular expression patterns processed directly via AWK before parsing the data into R.
}
\examples{
\donttest{
# Create sample log files
log1 <- tempfile(fileext = ".log")
log2 <- tempfile(fileext = ".log")
writeLines(c("INFO: System started", "Error: Disk full"), log1)
writeLines(c("INFO: User login", "Critical: Database unreachable"), log2)

# Extract rows matching "Error" or "Critical" across log files
errors <- pattern.fread(
  the.files = c(log1, log2),
  the.patterns = c("Error", "Critical"),
  connectors = "or"
)
print(errors)

# Clean up temporary files
unlink(c(log1, log2))
}
}
