% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/awkreader_v2.R
\name{record.count}
\alias{record.count}
\title{Efficient Record and Row Counting via AWK}
\usage{
record.count(
  the.files,
  path.to.awk = NULL,
  delim = ",",
  the.filter = NULL,
  file.pattern = NULL,
  recursive = FALSE,
  the.variables = ".",
  include.filename = TRUE,
  skip = 0,
  file.header = "file",
  num.files.per.batch = 1000,
  return.as = "result",
  envir = parent.frame(),
  and.symbol = "&",
  or.symbol = "|",
  in.symbol = "\%in\%",
  nin.symbol = "\%nin\%",
  show.warnings = FALSE,
  nrows = Inf,
  drop = NULL,
  ...
)
}
\arguments{
\item{the.files}{A character vector of file paths to scan. 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{delim}{A character string specifying the column separator within the files. Default is \code{","}.}

\item{the.filter}{A character string or unquoted expression outlining the filtering logic to pass to AWK.
Default is \code{NULL} (counts all records matching layout rules).}

\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{the.variables}{A character vector specifying active evaluation columns. Default is \code{"."}.}

\item{include.filename}{A logical value indicating whether to retain tracking metrics grouped by individual files. 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 tracking header index. Default is \code{"file"}.}

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

\item{return.as}{A character string specifying the desired return format. Options are \code{"result"} (default),
\code{"code"}, or \code{"all"}.}

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

\item{and.symbol}{A character replacement flag for logical AND statements. Default is \code{"&"}.}

\item{or.symbol}{A character replacement flag for logical OR statements. Default is \code{"|"}.}

\item{in.symbol}{A character replacement flag for inclusion tests. Default is \code{"\%in\%"}.}

\item{nin.symbol}{A character replacement flag for exclusion tests. Default is \code{"\%nin\%"}.}

\item{show.warnings}{A logical value determining whether terminal messages are displayed. Default is \code{FALSE}.}

\item{nrows}{An integer specifying the maximum total matching record sets to count. Default is \code{Inf}.}

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

\item{...}{Extra parameters forwarded to underlying internal setup routines.}
}
\value{
A \code{data.table} summarizing record counts per file (or overall), or raw shell string arrays.
}
\description{
Computes the total number of records matching specific logical filtering criteria
across multiple large files using AWK. This performs counting at the shell level, eliminating
the overhead of loading whole datasets into memory.
}
\examples{
\donttest{
# Create a sample CSV file with price data
tmp_file <- tempfile(fileext = ".csv")
write.csv(data.frame(id = 1:3, price = c(500, 15000, 20000)), tmp_file, row.names = FALSE)

# Get matching transaction counts without importing full rows
total_expensive_items <- record.count(
  the.files = tmp_file,
  the.filter = "price > 10000"
)
print(total_expensive_items)

# Clean up temporary file
unlink(tmp_file)
}
}
